dasha-ws/ai-dev-framework/architecture

architecture

Purpose

/architecture is the sole owner of substantive architecture decisions of a target project. It works with the durable architecture context:

.claude/skills/project-context/context/architecture.md

That file is durable architecture, not a Tech Spec and not an implementation plan. /tech-spec later describes how to implement one piece of work inside the agreed architecture.

It works in exactly one of three modes (step 2): documenting the current architecture of an existing project, defining the initial target architecture of a new product, or resolving the architecture impact of a reviewed Feature Spec, and changing the architecture when a substantial change is needed. A PASS of the independent architecture-reviewer belongs to the current reviewed version of architecture.md. What follows is governed by "Next skills".

When to use

• Mode 1. An existing project where the architecture lives in code and configuration, but architecture.md is missing in substance, incomplete or outdated.
• Mode 2. A new product: /product-spec → /review-spec → PASS → /architecture.
• Mode 3. An existing product: /new-feature-spec → /review-spec → PASS → /architecture, when the reviewed Feature Spec either clearly requires a substantial change of architecture, or has an architectural impact that cannot be safely determined before /tech-spec without separate architecture analysis.

Architecture work is for durable structural decisions with cross-feature or system consequences: major component or service boundaries, core storage, major integrations, key data flows, a substantial architectural pattern, or a change that needs one shared structural decision. It is also for an architecture that is insufficient or undefined for a safe technical design, and for recording the actual architecture of an existing project. Ordinary local implementation design stays with /tech-spec.

A feature whose reviewed Feature Spec clearly has no architectural impact (Case A) is not an /architecture case. /architecture is not run for it, and the workflow goes straight to /tech-spec.

When not to use

• The current directory is the ai-dev-framework repository itself. It is the source of the framework, not a target. If the root contains the framework's own skills/ folder, stop and ask which project the user means.
• The framework structure created by /init-project is missing. Stop, say what is missing and suggest /init-project (step 1).
• The work is only a new function, endpoint, table, screen, bot command, a local change inside one module, or an ordinary bugfix, and it clearly does not change the durable architecture. Do not invent architecture work: go straight to /tech-spec. If the impact of a reviewed Feature Spec is unclear, that is mode 3, and step 5 decides.
• The upstream requirements have not passed /review-spec (modes 2 and 3). Stop and suggest /review-spec first (step 3).
• The requirements themselves have to change: /product-spec or /new-feature-spec, then a mandatory /review-spec.
• The user wants a Tech Spec or an implementation plan (/tech-spec), code, tests, infrastructure changes or deployment.

Inputs

• Target project root. Default: the current working directory. Confirm it if there is any doubt.
• The user: the task, answers to clarifying questions and decisions on significant architectural choices.
• The project itself: code, configuration, existing documentation, existing infrastructure.
• The framework structure in the target project, created by /init-project: root CLAUDE.md, .claude/skills/project-context/SKILL.md, and in .claude/skills/project-context/context/ the files architecture.md, product.md, development.md and infrastructure.md, plus .claude/product/product-spec.md and .claude/work/. All are required.
• Reviewed upstream requirements (modes 2 and 3 only): the Product Spec for the initial architecture, the Feature Spec of the work item (.claude/work/<feature-name>/feature-spec.md) for mode 3.
• The installed architecture template. architecture.md was created from it by /init-project. It lives at %USERPROFILE%\.claude\ai-dev-framework\templates\project-context\context\architecture.md. Do not look for it by other means.
• The `architecture-reviewer`, as provided by the current installation.

Files to read

Read before writing anything. All reads are read-only.

Always: the root CLAUDE.md, the project-context router (.claude/skills/project-context/SKILL.md), architecture.md, product.md, development.md, infrastructure.md and the installed architecture template. ux-guide.md only if the router and the task show that UI or interaction architecture is relevant. Then, per mode:

• Mode 2: the reviewed Product Spec, the README and relevant product documentation if needed, and the existing constraints.
• Mode 3: the reviewed Feature Spec, the substantive Product Spec, related current specs if needed, the existing architecture, and the relevant parts of code and configuration, so that the change fits the real project.
• Mode 1: only what is needed: the top-level source layout and entry points, package and build configuration, major modules and components, APIs and interfaces between major parts, data and storage configuration, integrations, infrastructure and configuration where they show system boundaries, and existing documentation and ADRs.

No full code audit. Never read real .env files, credentials or secrets.

Execution steps

1. Confirm the target, the structure and the template

Verify that the working directory is a target project, not the framework repo, and that the required framework structure from "Inputs" exists. If any of it is missing: stop, say what is missing and suggest /init-project. Do not create the structure yourself and do not rebuild it from memory.

Check the installed architecture template. If it is missing, unavailable or empty: stop and say that the framework installation or template needs fixing. Do not invent your own structure. If the existing architecture.md is empty, damaged, or so far from the template that continuing safely is impossible: stop and describe the problem.

2. Determine the mode

Choose exactly one mode, from the user's request, the current workflow and the project state. If it cannot be determined unambiguously: do not guess. Show the possible modes in a few lines, ask the user and do not change architecture.md until they answer.

• Mode 1 observes the real code, configuration and project facts. It records what exists, takes no new architectural decision, invents no intent, does not silently replace an existing decision and does not redesign the system unless the user asks for that.
• Mode 2 creates the minimally sufficient target architecture for the approved product, not speculative enterprise design.
• Mode 3 is the resolution of the architecture impact, not simply a change. It first determines whether a substantive change is required (step 5). If not, that is Case B: no substantial architecture change, with at most a narrow factual sync of architecture.md (step 5). If it is, /architecture designs and writes the change (Case C).

3. Check the reviewed upstream requirements (modes 2 and 3)

Modes 2 and 3 need the current version of the reviewed requirements: .claude/product/product-spec.md for mode 2, .claude/work/<feature-name>/feature-spec.md for mode 3. A /review-spec PASS of the current version counts as reliably established in exactly three cases:

• the current conversation or workflow contains that PASS for this very version, and the spec has had no substantive change since;
• the user explicitly confirms that the current version already passed /review-spec and has not changed in substance since;
• the workflow ledger .claude/work/status.md has a review-spec row for it that powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\.claude\ai-dev-framework\scripts\workflow-state.ps1" check reports FRESH (see templates/work/status.md). The script decides freshness. A STALE or missing row is not established.

In every other case it is not established. Never infer it from the file existing, git history, commits, timestamps, naming or comments. If the conversation or a FRESH ledger row already establishes it, do not ask for a ritual confirmation. If it cannot be established: do not design the architecture, stop and suggest /review-spec for the upstream spec. No other status file, registry or review report files.

Mode 1 needs no requirements PASS, and none is invented for it.

4. Read the project and take the initial baseline

Read what "Files to read" lists for the mode. The sources keep their roles: the Product and Feature Specs hold the approved intent, code and configuration are factual evidence of the current implementation (not proof of a desired architecture), architecture.md holds the agreed durable architecture, project context holds durable facts and constraints (infrastructure.md describes the actual infrastructure: take it into account, do not silently rewrite it and do not design infrastructure implementation here), and a Tech Spec is implementation design, never architecture authority. An architecture decision is not inferred from a planned Tech Spec.

Before the first write, in a git repository, record the initial skill baseline with git status --short -uall, git diff and git diff --cached. It checks the file boundaries of this skill. Do not require a clean working tree. Changes the user already has are part of the baseline: leave them untouched and never overwrite or revert them. If the update cannot be made without overwriting them, stop and report. Never stage, commit, reset, checkout, stash, revert or run any other command that changes git state. If the project is not a git repository, do not invent a filesystem snapshot, hashes or any other baseline mechanism.

Two baselines exist, with different jobs. This one guards the boundaries of /architecture. The reviewer baseline of step 9 is taken separately, right before every reviewer call, and guards only against changes made by the reviewer. Until the reviewer is called, this skill may change only architecture.md.

5. Decide whether architecture work is needed

Do not run architecture work for its own sake.