architect-refresh
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.
mkdir -p ~/.claude/commands && curl -fsSL https://raw.githubusercontent.com/Hainrixz/the-architect/HEAD/commands/architect-refresh.md -o ~/.claude/commands/architect-refresh.mdarchitect-refresh.md
# `/architect-refresh` — un-rot a blueprint
You are being invoked as `/architect-refresh`. A blueprint written months ago is still
architecturally sound and numerically wrong. This command fixes the numbers and flags the migrations
they imply. It does **not** re-open the design.
The research contract lives in `${CLAUDE_PLUGIN_ROOT}/agents/stack-researcher.md`. Read it first.
## Resolve the target
`$ARGUMENTS` is a path, optionally followed by `--apply`.
| Argument | Do |
|---|---|
| A `.md` file | Refresh that file. |
| A directory | Refresh `blueprint.md`, plus any pins that leaked into `workspace/CLAUDE.md`, `workspace/.claude/**` or `epics/*.md`. |
| Empty | Glob `./blueprints/*/`, then `./blueprints/*-blueprint.md` for single-file mode. One match → use it. Several → ask. None → say so. |
| `--apply` present | Skip the confirmation step in Phase 3 below and edit directly. |
## Phase 1 — extract
Grep the blueprint for every pinned version: the tech stack table, setup commands, lockfile
snippets, Dockerfile base images, CI runner versions, runtime/SDK minimums. Build the inventory:
`Layer | Package or runtime | Pinned in blueprint | Where it appears (section + line)`
Services without versions — Stripe, Supabase, Cloudflare and friends — are not pins. Skip them
unless the blueprint names a specific API version.
## Phase 2 — verify
Dispatch `stack-researcher` **once**, with the whole inventory. One batched subagent, not one per
package. It resolves each package against its live registry and returns current stable, whether the
gap crosses a major, and any rename or removal in between.
Never answer from memory. A pin you recall is a pin you are about to get wrong.
## Phase 3 — the drift report
Print one table:
`Layer | Pinned | Current | Gap | Breaking? | Action | Risk`
- **Gap** — patch, minor, major, or `unverified` if the registry could not be reached. Say
`unverified` out loud; a confident guess is worse than an honest gap.
- **Breaking?** — yes only when the changelog says so. Cite what changed: a rename, a removed flag, a
raised runtime floor.
- **Action** — `bump`, `bump + migrate`, `hold` (with the reason), or `replace` (package is dead).
- **Risk** — what breaks in *this* blueprint if the bump lands, in one clause.
Below the table, list **Migrations required** — for each `bump + migrate`, the concrete edit: the
symbol that was renamed, the config key that moved, the minimum runtime that rose. This is the part
worth reading.
Then ask for a yes before editing, unless `--apply` was passed.
## Phase 4 — apply
On confirmation:
1. Edit each pin in place. Do not restructure sections, do not reword prose, do not touch the build
order unless a migration changes a step's verify command — then edit that command and say so.
2. Update the blueprint header's `Versions last verified:` line to today's date. If the line is
absent (pre-v2 blueprint), insert it directly under `Blueprint version:` and say so in the report.
3. Record the refresh as rows in **§20.3 Decision log** — `Decision: bumped <pkg> <old>→<new>` ·
`Why: registry drift, verified <date>` · `Would reverse if: <the migration proves costly>`. Do not
append a new top-level section: the template's 20 numbered sections are fixed and downstream
tooling indexes them by number.
Update §11 Dependencies in place too, including each bumped row's source URL and checked date —
a pin whose provenance cells still show the old date is a validator finding.
4. Re-run `blueprint-validator` (`${CLAUDE_PLUGIN_ROOT}/agents/blueprint-validator.md`). A refresh
that leaves the bundle failing is not finished.
## Rules
1. **Pins live in exactly one layer of the knowledge base.** The `stack-researcher` report from this
session is the authority; `${CLAUDE_PLUGIN_ROOT}/knowledge/runtime-tracks/` is a cache that drifts
the day after it is written, and never overrides a live registry check. If the drift you found
also affects a track file, say so in one line and stop — refreshing the plugin's own tracks is a
separate, deliberate act, not a side effect of auditing a user's file.
2. **Never bump across a major silently.** A major with no migration note means you did not finish
the research.
3. **Hold is a legitimate action.** Release-candidate lines and packages whose ecosystem has not
caught up get `hold` with a reason, not a bump.
4. **A refresh never redesigns.** If the right answer is "this stack choice is wrong now, not just
old", say that in one line and point at `/architect`. Then stop.
5. Detect and use the user's language.Adversarially 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.
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.
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.
>-