English
What is The Architect?
Imagine you want to build a house. Before anyone picks up a hammer, you need a blueprint — a detailed plan that shows every room, every wall, every pipe, and every wire. Without it, the builders wouldn't know what to do.
The Architect does this for software.
You describe it → "a SaaS for restaurant reservations, team accounts, Stripe"
The Architect designs it → interviews you, picks the stack, writes the blueprint
Claude Code builds it → reads the blueprint, ships the project step by step
It does not write application code. It designs systems and produces blueprints — self-contained markdown files that a different Claude Code instance, with zero prior context, can build from without asking you a single question.
Install
Plugin (recommended)
Two commands, inside any Claude Code session:
/plugin marketplace add Hainrixz/the-architect
/plugin install the-architect@soyenriquerocha
Then type /architect — in any directory. Your blueprints are written to ./blueprints/ in whatever folder you're working in, never inside the plugin.
Clone (still works, exactly as in v1)
git clone https://github.com/Hainrixz/the-architect.git
cd the-architect
claude
Claude Code reads CLAUDE.md and becomes The Architect. Same interview, same gates, same output — blueprints land in ./blueprints/ inside the clone. The slash commands and subagents are plugin-only; clone mode runs the same flow conversationally.
Prerequisites: Claude Code and a Claude subscription. Nothing else.
Pick your path: quick or full
There are two entry points, and the difference is real. Choose before you start.
Questions 3, in one message 12–16, across 6–7 messages
How long, end to end ~10 minutes ~40–60 minutes
Use it when You already know the stack, or the build is small and you mostly want the plan written down You intend to hand the result to an autonomous builder and walk away
What you give up Smart defaults for everything you weren't asked Nothing — but it costs you an hour
What you keep Both gates, EARS acceptance criteria, verify commands, the confirmation gate Same
Quick mode is genuinely faster than v1's default — three questions, one message, defaults stated out loud so you can veto them. Full mode is the one to use when nobody will be around to answer the builder's questions later.
How it works
Four phases. You talk, it designs, it generates.
Phase What happens What you do
1. Discovery 2–3 questions. Classifies your project into one of 14 shapes, and asks first whether this is new code or existing code. Answer
2. Deep dive
Shape-specific questions. Picks the runtime track and the capabilities. The stack-researcher subagent verifies every version against the live registries.
Answer 3–5
3. Architecture One dense message: stack table, how it fits together, what v1 includes and what it explicitly excludes, rough build phases. Both gates run here. Confirm or adjust
4. Generate
Picks bundle or single file from the step count and says which. Then: blueprint-writer composes, blueprint-validator audits until it returns PASS, files are written to ./blueprints/.
Wait
How long Phase 4 takes: 20–30 minutes, silently
This is the part nobody warns you about, so here it is up front. Once you confirm the architecture, generation runs roughly 20–30 minutes for a bundle, 10–15 for a single file, and produces no output until it is finished. That time is real work — a live registry call for every version pin, a full composition pass, and at least one validator round trip — but from your side it looks like nothing happening.
The Architect is required to tell you the estimate before it starts. If it doesn't, that's a bug. Go make coffee; what comes back is a file path and the first command to run.
The two gates (new in v2)
Phase 4 does not run until both pass. Neither is optional.
Gate A — zero [NEEDS CLARIFICATION] markers. Before presenting anything, The Architect scans its own draft and emits a marker for every decision still underspecified — scope boundaries, delete semantics, who can see whose data, who owns the API keys. Each marker is closed one of three ways: you answer it, you confirm a stated default, or it becomes an explicit Non-Goal. Entering generation with an open marker is forbidden.
The failure it prevents: a blueprint that reads as complete because the gaps were quietly filled with plausible guesses, and a builder agent that implements the guess at 2am with nobody to ask.
Gate B — adversarial pre-mortem. Eight angles aimed at killing the plan before it's generated: false assumptions, market, competition, viability, unit economics, execution, the six-months-out obituary, and the blind spot nobody in the conversation is looking at. The 3–7 findings that survive their own rebuttal become Risk Register entries or Non-Goals. If one invalidates the architecture, it goes back to redesign instead of shipping as a "risk". Uses /abogado-del-diablo when installed; runs inline otherwise — the gate is mandatory, only the tooling is optional.
What you get
A blueprint with 20 fixed sections. Section 9, the build order, is what the other 19 exist to support.
Every build step carries four fields: Do, Done when, Verify, Checkpoint. This is the anti-drift fix. In v1, steps had no definition of done — so an autonomous builder had no stopping condition, over-built, and declared victory on work that never ran.
Here's one real step, abridged from the worked example in templates/blueprint-template.md:
#### Step 7 — Stripe checkout and subscription webhook
**Do**
Wire paid signup end to end. Create:
- `src/lib/stripe.ts` — the SDK client, reading `STRIPE_SECRET_KEY`
- `src/app/api/checkout/route.ts` — creates a Checkout Session for the signed-in user
- `src/app/api/webhooks/stripe/route.ts` — signature-verified receiver, raw-body parsing
- `src/lib/billing/sync-subscription.ts` — the single writer to `subscriptions`
- migration `007_subscriptions.sql` — `subscriptions` + `webhook_events` (dedupe ledger)
**Done when**
- [ ] WHEN a POST arrives at `/api/webhooks/stripe` with an invalid `Stripe-Signature` header THE SYSTEM SHALL respond `400` and write zero rows to `subscriptions`.
- [ ] WHEN `checkout.session.completed` is received for a known customer THE SYSTEM SHALL upsert exactly one `subscriptions` row with `status='active'` and a non-null `current_period_end`.
- [ ] WHEN the same Stripe event `id` is delivered twice THE SYSTEM SHALL return `200` both times and leave the `subscriptions` row count unchanged.
- [ ] WHEN `STRIPE_WEBHOOK_SECRET` is unset at boot THE SYSTEM SHALL fail startup with a named error, not serve traffic that silently accepts unsigned payloads.
**Verify**
```bash
pnpm test src/app/api/webhooks/stripe # expect: 6 passed, 0 skipped
pnpm typecheck # expect: exit 0
stripe listen --forward-to localhost:3000/api/webhooks/stripe &
stripe trigger checkout.session.completed
psql "$DATABASE_URL" -c \
"select status, count(*) from subscriptions group by status;"
# expect: active | 1
stripe trigger checkout.session.completed # same fixture, replayed
psql "$DATABASE_URL" -c "select count(*) from subscriptions;"
# expect: 1 (idempotent — not 2)
Checkpoint
git add -A && git commit -m "step 7: stripe checkout + subscription webhook"
git tag step-07-billing
# rollback target if step 8 goes wrong: git reset --hard step-07-billing
Acceptance criteria use EARS form — **WHEN** `<trigger>` **THE SYSTEM SHALL** `<observable response>`. "It looks right", "billing works", "is wired up" are banned; the validator fails a blueprint that contains them. Every criterion must be decidable by a script, today, without leaving the machine. Anything that genuinely needs a human or a store review queue moves to a post-build launch checklist — written down, but not a build gate.
### Output layout
**The Architect picks the mode and tells you which, in one line.** It is derived from the step count — **12 steps or more gets a bundle, 11 or fewer gets a single file** — because packaging is a consequence of the design, not a question worth interrupting you for. Say so at any point and your preference wins instead. Both land under `./blueprints/` in your working directory, and both carry identical acceptanc