Open source · MIT In development · pre-1.0

From feature to verified PRD.
11 steps. One reducer.

A feature description goes in. A verified PRD of up to 9 files comes out — grounded on your actual code graph, not a hallucinated one. ai-architect-mcp-spec runs an 11-step stateless PRD reducer; ai-architect-mcp-codebase supplies the codebase intelligence it grounds on. Ask it to keep going and 9 opt-in steps implement, test, review and open the pull request, behind a human gate.

> /plugin marketplace add cdeust/ai-architect-mcp-spec
> /plugin install ai-architect-mcp-spec@ai-architect-mcp-spec-marketplace

Node.js 20.x or 22.x. /generate-prd also needs Cortex and zetetic-team-subagents installed. Pairs with ai-architect-mcp-codebase (Rust; the plugin installs a release binary) for codebase-grounded input analysis — optional, not required.

AI Architect Codebase in 90 seconds. Silent. Generated from cdeust/ai-architect-mcp-codebase at v0.15.0 (); every figure it prints is read from site-facts.json.
What the film says, scene by scene
  1. To answer, an agent re-reads the code file by file. The baseline: substring search and full-file reads.
  2. On your machine, the code becomes a graph. No language model reads the code; nothing is uploaded. Repository: 11 languages. tree-sitter: parses the structure. Graph: Imports, Calls, Implements, Extends, Uses, with confidence scores. Communities: Louvain with C2 repair. Re-run analyze_codebase after edits.
  3. One question, one call: search_codebase. Lexical: BM25 over symbols and documentation text. Sparse: TF-IDF over tokenized symbol names, no embedding. Fusion: reciprocal rank fusion, k = 60. Model: no tool calls a language model.
  4. get_context: one symbol and its neighbourhood. Its callers, callees, imports, implementations, community and processes, in one call.
  5. get_impact: what does a change touch? The answer carries an epistemic label, exact or lower bound, with its reasons.
  6. Measured, with its limits stated. Modeled tool calls per question: Substring search, file reads 5.20; Code graph 1.00. Payload token proxy per question: Substring search, file reads 550.36; Code graph 43.14. Offline retrieval evaluation, n = 20, protocol committed before the first run. Costs are modeled from payload sizes; the repository does not claim a token saving for real sessions.
  7. AI Architect Codebase. 27 MCP tools, 8 in the core profile, 11 languages. Indexing and queries run locally. $ claude plugin marketplace add cdeust/ai-architect-mcp-codebase $ claude plugin install ai-architect-mcp-codebase@ai-architect-mcp-codebase-marketplace

Sources: Sources: README, docs/evaluation.md and src/search of cdeust/ai-architect-mcp-codebase at the v0.15.0 tag (e2f1099). Figures: ai-architect.tools/site-facts.json.

ai-architect-mcp-codebase — the codebase intelligence layer

The 11-step reducer above needs the truth about your code before it writes a PRD. ai-architect-mcp-codebase is the Rust MCP server that supplies it — the read-only half between “here is a feature description” and “here is what is actually true about the code.”

What it does

  • Indexes Rust / Python / TypeScript / Java / Kotlin / Swift / Objective-C / C / C++ / Go codebases, plus Ruby on a shallow path, into a property graph (LadybugDB)
  • Resolves imports and calls across files by static parsing — no language model reads the code; calls made through reflection, dynamic dispatch, generated code or unexpanded macros have no edge unless the optional language-server pass or runtime traces supply one
  • Detects functional communities (Louvain with C2 repair)
  • Traces processes from entry points
  • Hybrid BM25 + sparse TF-IDF + RRF search
  • Validates PRDs against the actual graph (flags symbols a PRD names that do not exist)
  • Security gates: auth-community touch, public API change, unresolved imports, test-coverage gap — the unsafe-symbol check decides no language yet
  • Semantic diff: before/after graph, regression score, new cycles

By the numbers

  • 27 MCP tools at v0.15.0 — a core profile of 8 read-only tools, full for all 27 (a 28th is merged, not yet released)
  • v0.15.0 — released 12 November 2026
  • 11 languages (10 with deep extraction, Ruby on a shallow path)
  • 3,500+ tests at v0.15.0
  • 168,366 lines of Rust (measured at commit 47536d3, 15 November 2026)
  • Read-only — never writes code, opens PRs, or runs CI
  • Pairs with Cortex and ai-architect-mcp-spec (call-graph context)
# In Claude Code:
> /plugin marketplace add cdeust/ai-architect-mcp-codebase
> /plugin install ai-architect-mcp-codebase@ai-architect-mcp-codebase-marketplace

The plugin downloads the release binary and verifies its Sigstore provenance before running it; this needs GitHub CLI 2.68 or newer. A source build takes about five minutes the first time (LadybugDB's C++ core) and requires Rust 1.95.0 (pinned by rust-toolchain.toml) and CMake.

What a /generate-prd run looks like

$ /generate-prd "add rate limiting to the export endpoint"

[01/11] banner ........................ OK
[02/11] preflight ...................... OK   Cortex + ai-architect-mcp-codebase reachable; zetetic-team-subagents started a subagent
[03/11] context_detection .............. OK   context: feature
[04/11] input_analysis ................. OK   graph-grounded via ai-architect-mcp-codebase
[05/11] feasibility_gate ............... OK   single feature, pass-through
[06/11] clarification .................. OK   1 round, proceed-signal set
[07/11] budget ....................... OK
[08/11] section_generation ............. OK   per-section recall + validate + retry
[09/11] jira_generation ................ OK
[10/11] file_export .................... OK   8 files written
[11/11] self_check ..................... OK   multi-judge + deterministic verdicts

PRD complete. 8 files written under prd-output/; the verification report follows at implementation_gate.
Ask to continue: implementation -> testing -> review -> pr_gate -> pull request.

What this pipeline does

It takes a feature description and produces a verified PRD — and, if you ask it to keep going, a pull request.

Give ai-architect-mcp-spec a feature description. It runs an 11-step stateless PRD reducer: check that Cortex, zetetic-team-subagents and (when a codebase path is given) ai-architect-mcp-codebase are reachable, detect the PRD context, ground the feature on your real code graph via ai-architect-mcp-codebase, gate on scope, clarify with the user, check that clarification ended cleanly, generate every PRD section against per-section Cortex recall, generate JIRA tickets, export the PRD files, and self-check with a two-phase multi-judge verification pass.

self_check is not the end of the road. When you ask it to continue, the same state machine advances through an implementation loop — an engineer subagent implements on a feature branch, a test-engineer subagent runs the suite, a code-reviewer subagent verifies the diff (retrying implementation on a FAIL, bounded by a retry cap), and a mandatory human gate (pr_gate) asks before pushing. “No” is a valid terminal outcome, not a failure.

It works with any language your project uses — the pipeline reads your build system and test framework, not the other way around. The 11 named steps cover the PRD-generation phase; the 9 post-PRD implementation steps are optional and separately gated.

Get started

Install the plugin, then run /generate-prd. The command also needs Cortex and zetetic-team-subagents installed; without them it stops at its preflight step.

1

Install the plugin

# In Claude Code:
> /plugin marketplace add cdeust/ai-architect-mcp-spec
> /plugin install ai-architect-mcp-spec@ai-architect-mcp-spec-marketplace
2

Run the pipeline

# In Claude Code:
> /generate-prd "describe the feature here"

The reducer detects context, grounds the feature on your code graph (if ai-architect-mcp-codebase is installed), clarifies, generates, and exports a verified 9-file PRD.

11 steps, each with a defined state transition

A stateless reducer: every step reads the current state, emits one action, and advances. When a generated section fails validation, it retries with the violations injected — then advances regardless, so one bad section never blocks the PRD.

Setup
01 Banner
02 Preflight
03 Context Detection
Grounding
04 Input Analysis
05 Feasibility Gate
06 Clarification
07 Budget
Generation
08 Section Generation
09 JIRA Generation
Delivery
10 File Export
11 Self-Check

01 Step 1 — Banner

Emits a welcome banner with the run ID, the feature description and a capability summary.

02 Step 2 — Preflight

Probes Cortex, ai-architect-mcp-codebase when a codebase path is set, then zetetic-team-subagents by starting one subagent, before the pipeline depends on them; skippable via skip_preflight.

03 Step 3 — Context Detection

Classifies the feature description into one of eight PRD contexts — feature, bug, incident, proposal, PoC, MVP, release, or CI/CD — by trigger-word matching. The detected context selects which sections get generated and which validation rules apply.

04 Step 4 — Input Analysis

Calls ai-architect-mcp-codebase's analyze_codebase (index + resolve + cluster in one call), then prepare_prd_input to ground the feature on the real code graph — matched symbols, impacted communities, impacted processes. Without a codebase path, this step degrades gracefully and the PRD is generated from the description alone.

05 Step 5 — Feasibility Gate

Detects epic-scope signals in the feature description — at least two of “and,” “&,” “plus,” “also,” or a comma-separated list — and asks the user to pick one to focus on. Otherwise passes through.

06 Step 6 — Clarification

A two-phase loop: an engineer subagent composes a targeted question with options and rationale, the user answers, and the loop repeats until a clean proceed-signal is set. Bounded rounds — it does not ask forever.

07 Step 7 — Budget

Checks that clarification ended cleanly, then moves to section generation. v0.9.0 still ships a coordinate_context_budget tool, but the run reads nothing of what it computes; the tool is removed on the main branch, not yet released.

08 Step 8 — Section Generation

The core authoring loop, per section: recall Cortex context for that section, spawn an engineer subagent to draft it, validate deterministically, retry with the violations injected as context on failure, and advance to the next section on pass — or after retries are exhausted, so one bad section never blocks the PRD.

09 Step 9 — JIRA Generation

Spawns an engineer subagent to turn the acceptance criteria, user stories, and requirements sections into JIRA tickets, stored as a synthetic section so file export can pick it up.

10 Step 10 — File Export

Writes the PRD files of the run's context profile: the core PRD, the companion and JIRA files whose sections passed, and a run-notes file naming each skipped file or withheld failed section. No placeholder files — a companion file whose source section produced no content is never written.

11 Step 11 — Self-Check

Two phases: a multi-judge verification batch over every generated section, with a panel chosen per claim type; then combining deterministic validation violations with the multi-judge report into the final verification summary. Not the end — from here the same runner can advance into an optional implementation → testing → review → pull-request loop, gated by a mandatory human decision at pr_gate.

Why this architecture matters

Steps, retries, and verification that isn't one model grading another.

Reducer, not monolith

Most AI PRD tools run a single prompt-to-document pass. This pipeline is a stateless reducer with 11 named PRD steps, each reading current state and emitting one action. Every step's output is inspectable on its own — you get an artifact at every transition, not just at the end.

Retry the section, not the run

When a generated section fails deterministic validation, the pipeline retries that section with the violations injected as context — not the whole PRD. When the retry budget runs out, it advances anyway rather than blocking the entire document on one section.

Verification isn't one model grading itself

Self-check sends each claim to a judge panel chosen by its type — architecture, performance, correctness, security, data model — from a fixed table in the source, so the same claim always meets the same panel. Deterministic Hard Output Rules validators, which make zero LLM calls, run alongside. A distribution_suspicious flag catches confirmatory bias when every judge agrees suspiciously often.

PropertyTypical AI PRD toolai-architect-mcp-spec
StructureSingle prompt → document11-step stateless reducer, one action per step
GroundingDescription onlyOptional real code-graph grounding via ai-architect-mcp-codebase
VerificationNone, or one LLM re-reading its own outputSpecialized multi-judge panels per claim type + deterministic validators
Failure handlingRegenerate the whole documentRetry the failing section only, bounded, then advance
OutputOne documentUp to 9 files, depending on the PRD context
Beyond the PRDManual handoff to a coding agentOptional implementation → testing → review → PR loop, same runner

This is not CI/CD

CI/CD runs after code is written. This pipeline can write the code.

CI/CD triggers when a developer pushes code: build, test, deploy. It assumes a human wrote the code. This pipeline operates upstream — it takes a feature description and produces the PRD, and on request the code, tests, and pull request that your CI/CD system then validates. It does not replace your build system. It feeds it.

AspectTraditional CI/CDThis pipeline
TriggerCode push by developerFeature description
InputSource codeUnstructured requirements
OutputBuild artifact, deployVerified PRD (9 files); optionally a pull request with code, tests, and docs
Code authorshipHuman developerAutonomous engineer subagent, human-gated at pr_gate
VerificationTest suite onlyTest suite + multi-judge PRD verification + deterministic Hard Output Rules
Retry strategyRe-run same buildRetry the failing section or the failing implementation with the failure context injected
ScopeBuild → DeployFeature description → PRD → (optional) Pull Request

It can generate the commits. Your CI/CD still validates and deploys them.

ai-architect-mcp-codebase works with your stack

Deep extraction across 10 languages — the grounding layer, not a code-generation restriction. ai-architect-mcp-spec itself is language-agnostic.

Rust
Python
TypeScript
Java
Kotlin
Swift
Objective-C
C
C++
Go

ai-architect-mcp-codebase reads your project's real structure — imports, call chains, communities, execution processes — across these 10 languages with deep extraction. Every other file type (docs, config, binaries) is still indexed as a File node. The PRD reducer itself has no language restriction: it reads your build system, test framework, and directory structure, and runs your test suite natively during the optional implementation loop.

Part of the engagement journey · Exhibit 03

Where this pipeline fits in an engagement

ai-architect-mcp-codebase and ai-architect-mcp-spec do the grounding and verification work inside the paid pilot — working automations built against your own code and a measured before/after, not a one-time demo.

Stage Exhibit 03 · Paid pilot