Hainrixz/the-architect: a Claude Code plugin that writes the blueprint before the builder starts

The problem: an autonomous builder with nobody to ask

Most specification tools assume a human reads the spec. The Architect assumes the opposite. Its README frames the output as a self-contained markdown file that a different Claude Code instance, with zero prior context, can build from without asking a single question. That single constraint explains nearly every design decision in the plugin.

If the builder cannot ask, then every underspecified decision becomes a guess the builder fills in on its own. The README names the failure mode directly: 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. The plugin's answer is not better prose. It is a hard rule that generation cannot start while any decision is still open.

The audience is narrow on purpose. Solo developers and small teams using Claude Code who want to describe a product, walk away, and come back to a repository built from a plan. It is not for people who want the agent to write application code. The README is explicit that The Architect does not write application code; it designs systems and produces blueprints.

Four phases, from a sentence to a blueprint file

The flow is four phases. Discovery asks 2 to 3 questions, classifies the project into one of 14 shapes, and asks first whether this is new code or existing code, which is where the greenfield and brownfield split enters. Deep dive asks shape-specific questions, picks the runtime track and capabilities, and dispatches a `stack-researcher` subagent that verifies every version against the live registries. Architecture produces one dense message: a stack table, how the pieces fit together, what v1 includes and what it explicitly excludes, and rough build phases. Both gates run in this phase. Generate then picks bundle or single file based on the step count and says which, after which `blueprint-writer` composes and `blueprint-validator` audits until it returns PASS.

The output has 20 fixed sections. Section 9, the build order, is the one the other 19 exist to support. Every build step carries four fields: `Do`, `Done when`, `Verify`, `Checkpoint`. The README describes this as the anti-drift fix and contrasts it with v1, where steps had no definition of done, so an autonomous builder had no stopping condition and over-built. The `Verify` field is the one to look at closely: it means each step is supposed to carry a runnable command, not a description of a command.

The version history is short and recent. v2.3.0 is titled the literal-builder test, v2.4.0 reports 14 of 14 shapes under a strict protocol, and v2.5.0 claims zero deviations. Those are the maintainer's own claims about their own test protocol, not independent measurements, and the repository does not publish the protocol. Treat them as evidence that the author is testing something, not as a benchmark.

Installing the plugin and generating a first blueprint

The README recommends the plugin route. Both commands run inside a Claude Code session, and the marketplace name is `soyenriquerocha`, not the repository name, which is easy to mistype.

/plugin marketplace add Hainrixz/the-architect
/plugin install the-architect@soyenriquerocha

After that, `/architect` works in any directory. The README states that blueprints are written to `./blueprints/` in whatever folder you are working in, never inside the plugin. That matters if you keep several projects side by side, because the output lands next to the project you are actually building.

There is a second entry point, and the difference is large enough that the README tells you to choose before you start. `/architect-quick` asks 3 questions in a single message and the README estimates about 10 minutes end to end. `/architect` asks 12 to 16 questions across 6 to 7 messages and is estimated at 40 to 60 minutes. Quick mode gives up the smart defaults you were never asked about, stated out loud so you can veto them, but keeps both gates, the EARS acceptance criteria and the verify commands.

/architect-quick

If you prefer not to install a plugin, the clone path still works exactly as in v1. Claude Code reads `CLAUDE.md` and becomes The Architect, with the same interview, gates and output. The README notes that slash commands and subagents are plugin-only, so clone mode runs the same flow conversationally.

git clone https://github.com/Hainrixz/the-architect.git
cd the-architect
claude

The only prerequisites the README lists are Claude Code and a Claude subscription. Nothing else. There is no separate runtime, no API key to configure, and no build step.

The two gates, and why they are the actual product

Gate A is a zero-marker rule. Before presenting anything, The Architect scans its own draft and emits a `[NEEDS CLARIFICATION]` marker for every decision still underspecified: scope boundaries, delete semantics, who can see whose data, who owns the API keys. Each marker closes 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.

This is stricter than it sounds, and it is the right kind of strict. The alternative most spec tools take is to let the model resolve ambiguity silently and produce a document that looks finished. Gate A makes the ambiguity visible and forces a decision, even if the decision is to declare the thing out of scope. The cost is real: you cannot get a blueprint out of full mode without engaging with every open question, and the README puts that at 40 to 60 minutes.

Gate B is an adversarial pre-mortem with eight angles: false assumptions, market, competition, viability, unit economics, execution, a six-months-out obituary, and the blind spot nobody in the conversation is looking at. The 3 to 7 findings that survive their own rebuttal become Risk Register entries or Non-Goals. If a finding invalidates the architecture, the README says it goes back to redesign rather than shipping as a risk. That last rule is the one worth testing. A pre-mortem that only ever produces a risk register is theater; a pre-mortem that can send you back to Phase 3 is a gate.

The README notes that Gate B uses `/abogado-del-diablo` when installed and runs inline otherwise, and that the gate is mandatory while the tooling is optional. So the name of the command is not something you need to know before installing.

The 20 to 30 minutes of silence in Phase 4

Once you confirm the architecture, generation produces no output until it finishes. The README gives the estimate directly: roughly 20 to 30 minutes for a bundle, 10 to 15 for a single file. It attributes that time to a live registry call for every version pin, a full composition pass, and at least one validator round trip.

This is the most under-documented part of the workflow in most tools of this kind, and The Architect at least states it. The README also says the plugin is required to tell you the estimate before it starts, and that failing to do so is a bug. That is an unusual thing to write into a README: it turns a UX expectation into a defect report. Whether the behavior holds in practice is something you can only check by running it.

The practical consequence is that full mode is not an interactive session. You answer 12 to 16 questions, confirm an architecture, then wait half an hour with no progress indicator described in the README. If you are the kind of user who wants to watch the plan assemble, this is the wrong tool, and `/architect-quick` at 10 minutes end to end is the escape hatch.

Where it is the wrong tool

The Architect does not write application code. If your goal is a working prototype by the end of the session, this plugin adds a phase before the phase you wanted. The blueprint is the deliverable, and you still need a builder to act on it.

The 20 fixed sections cut both ways. A fixed structure is what makes the output predictable for a context-free builder, and predictability is the whole point. But a small CLI tool and a multi-tenant SaaS with Stripe billing get the same 20 sections, and nothing in the README describes a mechanism for collapsing sections that do not apply. The likely outcome for small projects is either padding or a run of Non-Goals. Neither is fatal, but it is a cost that scales inversely with project size.

Version pinning is another boundary. The `stack-researcher` subagent verifies every version against live registries, which means generation depends on network access to those registries at generation time. The README does not describe an offline mode or a fallback when a registry call fails. If you are building in an air-gapped environment, that dependency is unaddressed.

Finally, the trust model. The v2.3.0 through v2.5.0 release notes describe a literal-builder test and a strict protocol, with v2.5.0 claiming zero deviations. The repository does not publish the protocol, the test corpus, or the failure criteria. The claims are the author's, and a reader has no way to reproduce them from what the repository publishes. That does not make them false. It means you should verify the output quality on your own project rather than on the release notes.

Compared with writing a spec by hand in Claude Code

The obvious alternative is not another plugin. It is the workflow most Claude Code users already have: open a session, describe the project, iterate on a plan in conversation, then ask the same session to build it. The difference in approach is the context boundary.

In the conversational approach, the builder and the designer are the same session. Everything the designer learned during the interview is still in context when the build starts, so gaps get filled from memory rather than from the document. That works well when you stay in the session. It breaks the moment you start a fresh session, hand the plan to a different instance, or come back a week later, because the plan was never forced to stand alone.

The Architect inverts this by making the document the only channel. The interview happens in one context, the build happens in another, and the blueprint has to carry everything. The two gates and the four fields per build step are consequences of that inversion, not features bolted on top. If you never intend to hand the build to a context-free instance, you are paying the full-mode cost for a guarantee you do not need, and a conversational plan in a single session is the cheaper path.

Licence, maintenance and upgrade cost

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the standard permissive arrangement, and nothing in the README adds terms on top. This is not legal advice; if you are redistributing the plugin inside a product, read the LICENSE file in the repository rather than this summary.

The last push to the default branch was on 2026-07-28, and the three releases in the repository (v2.3.0, v2.4.0, v2.5.0) all landed on 2026-07-28 as well. That is a single day of concentrated release activity rather than a long cadence, and the repository is not archived. The README describes v2 as a substantial change from v1: the two gates, the four fields per build step, and the anti-drift fix in the build order all arrive in v2. The README also states that clone mode still works exactly as in v1, so a v1 user who clones does not get the new behavior automatically.

Upgrade cost is mostly re-reading the blueprint format. If you built from a v1 blueprint, the steps lack the `Done when` and `Verify` fields, and a v2 builder reading that file has no stopping condition. Regenerating the blueprint is the path the README implies, since the format change is in the output rather than in the plugin's interface. The repository also carries `VERSIONING.md` and `CHANGELOG.md` at the top level, which is where the release notes come from.

Editorial conclusion

Adopt it if you intend to hand a build to an autonomous Claude Code instance and nobody will be around to answer that instance's questions; the confirmation gate, the zero-marker rule and the per-step Verify field exist precisely for that handoff. Do not adopt it if you already know the stack and the build is small, because the full interview costs 40 to 60 minutes plus 20 to 30 minutes of silent generation, and /architect-quick exists for exactly that case. Before committing, verify three things against the repository: whether Section 9's four fields (Do, Done when, Verify, Checkpoint) appear on every step in a sample blueprint, whether the two gates actually run in the mode you picked, and whether the 20 fixed sections fit a project your size or will be padded to fill the template.

Frequently asked questions

Official sources

1. Hainrixz/the-architect on GitHub
2. License: MIT
3. Project website
4. README
5. Releases