<p align="center"> <h1 align="center">The Architect</h1> <p align="center"> <strong>A Claude Code meta-agent that designs complete software blueprints.</strong> </p> <p align="center"> Describe what you want to build. Get a complete blueprint. Let Claude Code build it for you. </p> <p align="center"> <a href="https://tododeia.com">tododeia.com</a> &middot; <a href="#english">English</a> &middot; <a href="#español">Español</a> </p> </p> <p align="center"> <a href="https://github.com/Hainrixz/the-architect/releases/latest"><img src="https://img.shields.io/github/v/release/Hainrixz/the-architect?sort=semver&style=for-the-badge&label=release&color=blueviolet" alt="Latest release" /></a> <img src="https://img.shields.io/badge/Claude_Code-Plugin-blueviolet?style=for-the-badge" alt="Claude Code Plugin" /> <img src="https://img.shields.io/badge/Blueprints-Markdown-blue?style=for-the-badge" alt="Markdown Blueprints" /> <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="MIT License" /> <img src="https://img.shields.io/badge/by-tododeia.com-black?style=for-the-badge" alt="by tododeia.com" /> </p>

---

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.

| | /architect-quick | /architect | |---|---|---| | 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**
```bash
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 acceptance criteria and verify commands.

Bundle — for parallel builders, multi-week builds, or resumable state:

./blueprints/<project-slug>/
├── blueprint.md          # the 20-section narrative artifact
├── tasks.json            # the machine-readable task DAG
├── epics/
│   ├── 01-<name>.md
│   └── 02-<name>.md
└── workspace/            # copied INTO the target project root by the builder
    ├── CLAUDE.md
    ├── AGENTS.md
    └── .claude/
        ├── settings.json
        ├── skills/<name>/SKILL.md
        └── rules/<name>.md

workspace/ exists so the builder copies one directory into the project root — cp -R workspace/. <project-root>/ and the agent configuration is in place.

Single file — one builder, a build measured in days, nothing to resume:

./blueprints/<project-slug>-blueprint.md

Everything inline. One file to send, paste, or commit anywhere.

---

The 14 shapes

v1 had 6 archetypes. v2 has 14 shapes, and they're stack-agnostic — a shape describes what a thing is, never what it's written in.

| Shape | What it covers | Default track | | |---|---|---|---| | SaaS Web Application | Sign up, log in, manage something that's yours. The default web shape. | TypeScript / Node | | | Marketing / Content Site | Landing pages, portfolios, docs. Content-first, near-zero client JS. | TypeScript / Node | | | Mobile App | App Store / Play Store, release trains, platform review. | Mobile native | | | API / Backend Service | Headless, consumed over the network by other software or agents. | TypeScript / Node | | | Internal Tool / Admin Dashboard | CRUD and charts for a known authenticated team. Never public. | TypeScript / Node | | | Content & Community Platform | Content plus identity plus a social graph. Publicati