Project Documentation
UmnyAut («Умняут») — a connected renovation calculator: enter room dimensions once, get a verified merged shopping list in packs, rolls and bags. This directory holds:
- Source specs (
specs/, Russian) — business, technical and design specifications, mockups, roadmap script. They are the source of truth; reference docs below are English digests of them.
- Reference documentation — human- and AI-readable docs about this codebase, organized by category.
- Skill specifications (
skills/) — tool-agnostic blueprints that any AI agent can turn into a working skill for its own host (Claude Code, Codex, or a generic agent).
- Agent specifications (
agents/) — tool-agnostic blueprints that any developer can turn into a working AI subagent for its own host (a Claude Code subagent in .claude/agents/, a Codex custom agent in .codex/agents/, or a generic framework's agent).
This README is also an instruction set for AI agents. If you are an agent reading this, the sections marked For AI below tell you what you are allowed and expected to do.
Layout
| Path | What lives here |
|---|
specs/ | Source specs (RU), mockups HTML, roadmap script, Wordstat CSV |
details/ | Brand assets: logos, favicons, mascot poses and clips, concept references |
architecture/ | Project structure, module boundaries, routing, state |
design/ | Themes, CSS variables, design tokens, visual system |
ui/ | Component usage, template patterns, layout |
code/ | Calc engine, server API, data |
business/ | Domain logic, product rules, SEO and analytics |
deploy/ | Build, CI/CD, hosting, environments |
integrations/ | Telegram, AI vision |
practices/ | Conventions, testing, git workflow |
plan/ | Phased development plan, accounts registry, dependencies, content & assets plan |
skills/ | Skill specifications (blueprints for AI skills) |
agents/ | Agent specifications (blueprints for AI subagents) |
Reference docs
Skill specifications
Each file in skills/ is a spec: a versioned, host-neutral description of one skill — its purpose, triggers, workflow, and acceptance criteria. A spec is not a finished skill; it is the source of truth from which a real skill is built, adapted to whatever tool reads it.
Current specs
Agent specifications
Each file in agents/ is an agent spec: a versioned, host-neutral description of one AI subagent — its purpose, when to delegate to it, system prompt, tools, model, and guardrails. A spec is not a finished agent; it is the source of truth from which a real agent is built, adapted to whatever host reads it.
Current agents
For AI: materializing a skill from a spec
When asked to build/create/update skills (e.g. "обнови скилы", "set up the skills", or during /init):
- Read each spec in
skills/.
- Choose the adaptation section matching your host: §9.1 Claude Code, §9.2 Codex / AGENTS.md, or §9.3 Universal if your host isn't listed.
- Build the skill in your host's native format:
- Claude Code → create
.claude/skills/<slug>/SKILL.md (project-level by default) with name + a description that encodes the spec's §2 triggers; add scripts/, references/, assets/ from §6.
- Codex → add the capability to
AGENTS.md (or the spec's named instruction file) in Codex's instruction style.
- Other → follow §9.3 Universal.
- Verify the build against the spec's §8 Acceptance criteria.
- Update the spec's Materialization log row (tool, location, built-from spec version, date) and set the spec
status to built.
Always confirm with the user before creating or overwriting skill files.
For AI: materializing an agent from a spec
When asked to build/create/update agents (e.g. "обнови агентов", "set up the agents", "build the frontend agent", or during /init):
- Read each spec in
agents/.
- Choose the adaptation section matching your host: §12.1 Claude Code, §12.2 Codex, or §12.3 Universal if your host isn't listed.
- Build the agent in your host's native format:
- Claude Code → create
.claude/agents/<slug>.md (project-level by default; ~/.claude/agents/ for a personal agent) with YAML frontmatter (name, a description that encodes the spec's §2 delegation triggers, plus tools/model/permissionMode from §5/§6/§9) and a Markdown body = the §4 system prompt + §7 procedure + §8 output contract.
- Codex → create
.codex/agents/<slug>.toml (project-level by default; ~/.codex/agents/ for personal) with name, description, developer_instructions (§4 + §7 + §8), and model/model_reasoning_effort/sandbox_mode/[mcp_servers.*] from §6/§9.
- Other → follow §12.3 Universal.
- Verify the build against the spec's §11 Acceptance criteria.
- Update the spec's Materialization log row (tool, location, built-from spec version, date) and set the spec
status to built.
Always confirm with the user before creating or overwriting agent files.
For AI: /init behavior
If skills/ contains specs but the corresponding skills are not built for this host (no matching entry in a spec's Materialization log, or the host's target file is missing), tell the user these specs exist and offer to materialize them. Do the same for any specs in agents/. Build only after confirmation.
For AI: "update skills" / "update agents" behavior
For each spec in skills/ (on "update skills") or agents/ (on "update agents"), compare its spec_version against the version recorded in the Materialization log for your host:
- Recorded version older than
spec_version → the built skill/agent is stale; rebuild it and update the log.
- No recorded row for your host → not built here; offer to build it.
- Versions match → up to date; skip.
Report what is stale, what is current, and what is missing before changing anything.
