architect-brownfield
Design a change against an existing codebase — maps the repo's stack, conventions, structure and tests, then emits a blueprint for a feature, refactor, or migration instead of a from-scratch build. / Diseña un cambio sobre un repo existente — mapea stack y convenciones y emite un blueprint de cambio, no de proyecto nuevo.
mkdir -p ~/.claude/commands && curl -fsSL https://raw.githubusercontent.com/Hainrixz/the-architect/HEAD/commands/architect-brownfield.md -o ~/.claude/commands/architect-brownfield.mdarchitect-brownfield.md
# `/architect-brownfield` — design a change to code that already exists
You are being invoked as `/architect-brownfield`. Most coding-agent work is not greenfield —
roughly a quarter of sessions write new code, and the rest modify what is already there. This is the
entry point for the rest.
Read the skill first — the phases, the shapes, and the acceptance-criteria contract are unchanged:
- Plugin install: `${CLAUDE_PLUGIN_ROOT}/skills/architect/SKILL.md`
- Clone install: `./CLAUDE.md` at the repo root — the clone-mode mirror of the skill. Same rules,
same state machine, repo-relative paths, and the subagent work done inline.
## Mode
| Setting | Value |
|---|---|
| Entry | Existing repo in the cwd |
| Deliverable | A **change blueprint** — feature, refactor, integration, or migration |
| Shapes | Same files. They are stack-agnostic, so they describe a system that already exists just as well as one that does not. |
| Output | Bundle or single file — **ask at phase-4 Step 2**, recommend bundle. Both land under `./blueprints/` in the repo. |
| Gate | `blueprint-validator` must return **PASS** |
## Phase 0 — map the repo (this is the phase that does not exist in the greenfield flow)
Before any question, read the codebase. Do not ask the user what you can read.
| What | Where to look |
|---|---|
| Runtime track | Package manifest + lockfile, language version files, container base image |
| Framework and topology | Entry points, routing directory, server vs client split, workspace layout |
| Conventions | Naming, module boundaries, error handling, the linter/formatter config that is actually enforced |
| Data layer | Migrations directory, schema files, ORM usage sites |
| Test setup | Runner, where tests live, how they are named, what the coverage floor is if any |
| CI and deploy | Workflow files, deploy config, environment variable surface |
| Existing agent instructions | `CLAUDE.md` / `AGENTS.md` — these outrank the plugin's defaults |
Then print a **Repo Map**: track, framework, data layer, test command, lint command, build command,
deploy target, and the 3-5 conventions the change must respect. Ask the user to correct anything you
read wrong. Their correction is cheaper than your assumption.
## Phase 1-3 — compressed interview
Skip discovery of *what the product is* — the repo already answered that. Ask about the **delta**,
max 3 questions per message, using `${CLAUDE_PLUGIN_ROOT}/questions/phase-2-branches.md` and
`${CLAUDE_PLUGIN_ROOT}/questions/phase-3-confirmation.md` as the source:
1. What should be true after this change that is not true now?
2. What must keep working exactly as it does today?
3. What is off-limits — files, services, data, downtime windows?
Then present the change architecture for sign-off: the delta, the blast radius, the rollback.
## Phase 4 — the change blueprint
Compose from `${CLAUDE_PLUGIN_ROOT}/templates/blueprint-template.md`. **Brownfield gets no sections
of its own.** The template's 20 numbered sections are fixed and downstream tooling indexes them by
number, so brownfield content goes into existing sections as named subsections:
| Brownfield content | Goes in |
|---|---|
| **Current state** — the Repo Map plus the specific modules the change touches | §1 Project Overview, as a `### Current state` subsection |
| **Target state** — what the code looks like after, in the repo's own conventions | §1 Project Overview, as a `### Target state` subsection |
| **Delta** — files added, modified, deleted; named, not gestured at | §3 Directory Structure, §4 Data Model, §5 API Design — a `### Delta` subsection in each, covering only what that section owns |
| **Interfaces held constant** — public API surface, DB columns, events, env vars that must not move | §5 API Design, as an `### Interfaces held constant` subsection. Mirror each frozen interface as a row in §1 Non-Goals. |
| **Build order** | §9, unchanged. Same numbered one-sitting steps, each with an observable "Done when" and a verify command that runs against **this** repo's test setup. |
| **Parity and cutover** | **§9.1** — required when the change is a migration (see below) |
| **Rollback** | §12 Release and rollback, plus the per-step `Checkpoint` field in each §9 step |
**All 20 sections still appear.** A section with no brownfield content carries
`NOT APPLICABLE — <reason>` under its heading. Never delete a heading and never add a 21st.
Emit the canonical bundle (`${CLAUDE_PLUGIN_ROOT}/questions/phase-4-generate.md` Step 3 is the
authority on the tree):
```
./blueprints/<change-slug>/
├── blueprint.md # the 20-section narrative
├── tasks.json # ${CLAUDE_PLUGIN_ROOT}/templates/tasks-schema.md
├── epics/NN-<name>.md # ${CLAUDE_PLUGIN_ROOT}/templates/epic-template.md
└── workspace/ # the builder copies this directory INTO the repo root
├── CLAUDE.md
├── AGENTS.md
└── .claude/{settings.json, skills/<name>/SKILL.md, rules/<name>.md}
```
In a brownfield repo `workspace/CLAUDE.md` and `workspace/AGENTS.md` **merge into** the repo's
existing files rather than overwriting them — say so in the handoff. **Never emit
`.claude/commands/`**: a slash command only fires when a human types it, and an autonomous builder
types nothing. Repeatable project workflows go in `.claude/skills/<name>/SKILL.md`.
Single-file mode emits `./blueprints/<change-slug>-blueprint.md` with everything inline, no
`tasks.json` and no `epics/`. `/architect-next` needs the bundle; single file means resume is manual.
With a bundle, `/architect-next` works on it identically to a greenfield one.
## §9.1 Parity and cutover — required when the change is a migration
Rewrites die at cutover, not at design. Any migration — framework, database, provider, language —
gets **Section 9.1** or the validator fails it. Its six parts:
1. **Parity checklist** — every behavior the old path has, as a checkable row. Including the ones
nobody documented; go read them out of the code.
2. **ParAdversarially audits a finished blueprint bundle and returns PASS or FAIL with line-referenced findings. Use before handing any blueprint to the user or to a build agent, and again after fixes. Read-only, Grep-driven, no shell. Fails on verify commands that reference files no build step creates, unobservable or machine-undecidable acceptance criteria, a migration with no Section 9.1 parity and cutover plan, missing sections, an empty Non-Goals scope fence, steps with no checkpoint tag, oversized steps, undocumented env vars, verify commands missing from the settings.json allowlist, dangling references, bad skill references, surviving placeholders, invented filenames for tool-generated artifacts, workspace files that are malformed or unignorable under the blueprint's own linter config (formatter *execution* is handed to the main thread's smoke test, not guessed at here), pins that imply verification that never happened, pins that no step ever installs, a step that retroactively breaks an earlier step's verify gate, an emitted runner config that cannot resolve a package the blueprint mandates, a standalone tool reading env vars nothing loads, an asserted count that disagrees with the blueprint's own content, checkpoint tags with no repository initialisation, an ignore file excluding a file the blueprint calls committed, two emitted artifacts that state the same path, entry point, name or port differently, an entry point that is built but never invoked, an emitted config that does not exclude the bundle's own path, a guard that exits non-zero on the path it guards against, a step Verify that asserts repository state only that same step's Checkpoint could produce, a byte-exact golden file or expected-output example that contradicts the blueprint's own data model or quotes a message only the pinned runtime could have produced, a gate whose pass condition is any non-zero exit so a usage error satisfies it vacuously, an ignore file or governing config delivered after the command it governs, and a tasks.json that does not match its epics. Triages pattern hits before filing them — an approval gate or a notarization command whose criterion resolves on this machine is correct work, not a finding.
Composes the finished blueprint from the interview findings, the chosen shape, the runtime track, and the selected capabilities — and in bundle mode writes the whole bundle: blueprint.md, tasks.json, epics/, and workspace/ (CLAUDE.md, AGENTS.md, .claude/, and the §19.6 verify-critical config files the gates need to run). Use after the architecture has been confirmed with the user, so the long generation runs in isolated context instead of flooding the interview thread. Its prompt must state the output mode. Returns the written paths, section coverage, an assumptions log, and any gap it refused to invent an answer for.
Resolves package versions and package identifiers against authoritative sources — the published artifact first, then the registry — before either is written into a blueprint. Use PROACTIVELY whenever a version is about to be pinned, a runtime track is refreshed, an export or option name is in doubt, or the user asks "what version should we use". Its report is authoritative over any cached runtime-track file. Returns package → current stable version → source URL → date checked, and flags prereleases, versions the rest of the stack cannot accept yet, unmaintained packages, and anything it could not verify.
Run the blueprint-validator against an existing blueprint and report PASS/FAIL with specifics. Blueprints written before v2 will FAIL — they have no acceptance criteria. That is expected, not a bug. / Audita un blueprint existente con el validador; los blueprints v1 fallan porque no tienen criterios de aceptación.
Resume a build — reads tasks.json from a bundle, finds the first pending task whose dependencies are all done, and prints it with its epic, acceptance criteria, and every verify command. This is what lets a long build survive across sessions. / Reanuda una construcción desde tasks.json y muestra la siguiente tarea desbloqueada.
Fast-track blueprint — three questions, smart defaults for everything else, still validator-gated. For when you just want it built. / Blueprint express — tres preguntas, defaults inteligentes, con el mismo validador.
Re-verify every pinned version in an existing blueprint against the live registries and report what moved, what breaks, and what to change — un-rots a months-old blueprint without a redesign. / Reverifica cada versión fijada en un blueprint contra los registros y reporta qué cambió y qué romper.
>-