AI Architect MCP Spec README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the AI Architect MCP Spec listing page.
Catch a hallucinated spec before it becomes code.
It checks that every symbol exists, every acceptance criterion traces to a requirement, and no performance claim passes without a measurement — deterministically, with no model in the checking loop.
Works in Codex, Gemini CLI, Claude Code, and CI. Runs on your machine.
What An Agent Asks · Getting Started · Pipeline · Tools · Verification · Calibration · Architecture · Zetetic Standard
One of three MCP servers that each run standalone — memory, code graph, spec verification. How they compose ↓
Every AI agent that drafts a PRD eventually invents a function that doesn't exist, claims latency it can't measure, or writes acceptance criteria that don't tie back to the requirements they're supposed to test. The output sounds confident. It is not actionable. The next stage in the pipeline — code generation, ticket import, sprint planning — silently inherits the hallucination, ships it, and pays for it later.
AI Architect MCP Spec is a TypeScript MCP server that fixes this at the structural level. Its portable verifier gives Codex, Gemini CLI, Claude Code, CI, and other stdio MCP hosts the same deterministic Hard Output Rules and cross-section traceability checks. The full pipeline is a stateless reducer (step(state, result?) → next_state, action) driven by a host that can execute its orchestration actions; Claude Code is the only packaged full-pipeline host today. Sections are produced one at a time, validated before the host ever sees them, and every load-bearing claim is judged by a panel of genius reasoning agents drawn from zetetic-team-subagents against the codebase graph from ai-architect-mcp-codebase. The loop is closed: per-judge reliability is calibrated from history, retry budgets are derived from survival statistics, KPI gates are tuned against frozen baselines, and held-out partitions are mechanically sealed so no calibration result can be peeked at before evaluation.
What you get
- A spec that survives contact with code. Symbols are cross-checked against the real codebase graph, so a PRD cannot reference a function that was renamed last week.
- Traceability that is actually checked. Every acceptance criterion must tie back to a requirement; numbering gaps are caught, not assumed away.
- No PASS without a measurement. The verdict taxonomy refuses to pass a latency, throughput, fps or storage claim — it returns SPEC-COMPLETE or NEEDS-RUNTIME instead of a confident guess.
- A guard against agreeable judges. A panel that agrees 100% of the time over 5+ claims raises
distribution_suspiciousrather than being read as consensus. - It works where you work. The deterministic verifier travels to Codex, Gemini CLI, Claude Code and CI; the full generation pipeline runs on hosts that can execute its orchestration actions.
Sovereign verification, eco-responsible by intent
Sovereign is what it is today. The server is a stateless reducer — step(state, result?) → next_state, action. It emits actions; your host executes them. It runs on your machine, and it never phones home for a verdict.
Eco-responsible is what we're aiming at. This one's lever is different from its siblings': it is avoided rework. A hallucinated PRD is inherited by code generation, ticket import and sprint planning before anyone notices — and every stage that consumed it has to be redone. The spec stage is the cheapest place in the pipeline to catch that, and three design choices keep the catching itself cheap:
- The checks run no model. Hard Output Rules and cross-section traceability are deterministic; finding a broken FR-AC link costs zero inference.
- Sections fail before they are finished. Each is validated before the host ever sees it, instead of being generated in full and then discarded.
- Retry budgets are derived, not guessed.
MAX_ATTEMPTScomes from Kaplan-Meier survival math, andmap_failure_to_retrievalsends a corrective query before a retry — a retry that reuses the context that just failed is waste with a receipt.
As in the sibling repos, we publish no energy or CO₂ figure: this repository measures no joules, and avoided rework is a design argument rather than a measurement.
10 packages. 17 MCP tools. 20 pipeline steps (11 PRD generation + 9 opt-in implementation). Multi-judge verification with consensus. Closed-loop calibration with externally-grounded falsifiers. 1506 tests. Every numeric constant traces to a citation, a benchmark, or a // source: provisional heuristic admission.
Closed-loop reliability calibration
Verification is not a one-shot pass/fail report. Every claim resolution can flush an observation back to a calibration repository, every consensus run can pull calibrated posteriors from history, and every closed loop runs an external control arm so the calibration's effect is measured, not assumed.
- Per-judge Bayesian reliability calibration — Beta(7,3) prior with sensitivity / specificity split per
claim_type. Posteriors stored in a SQLite-backedReliabilityRepository; observations flushed on every claim resolution. - MAX_ATTEMPTS retry calibration — Kaplan-Meier survival math (
kmEstimate/kmMedianAttempts/logRankTestwith Greenwood + Brookmeyer-Crowley CIs); Schoenfeld sample-size derivation event-rate-corrected to ~519 (was 823) against the measuredevent_rate=0.4762, CP CI[0.4456, 0.5069]. - KPI gate tuning — Clopper-Pearson exact CIs; per-machine-class wall_time normalization with 5-bucket
detectMachineClass; frozen-baseline content-hash assertion;loadCalibratedGates+hold_provisionalratchet protection. - Plan-mismatch fire-rate — measured via XmR control charts (Wheeler 1995, Western Electric 1956) with a synthetic injection round-trip pre-flight that catches drift between the diagnostic prefix and the regex matcher.
- Externally-grounded held-out subsets — Ajv schema oracle, mathjs oracle,
tscsubprocess code oracle,validateSectionspec oracle.OracleUnavailableErrortyped throw replaces stub-mode fabrication. This is the layer that breaks annotator-circularity — judges and oracles share no inference path. - CC-3 forced-exploration control arms — every closed loop carves out a 20% partition that reverts to the prior. Without it, calibration-on-calibration looks like progress whether or not it actually is.
- Cross-arm comparison metrics —
computeAblationComparison/computeReliabilityComparison/computeKpiGateComparisonproduce paired-bootstrap CIs (Efron & Tibshirani 1993 §16.4; deterministic mulberry32 RNG; 12-decimal reproducibility pin). Outcome is a falsifiable recommendation:calibrated_helps,prior_helps, orinconclusive_underpowered. - Mechanically-enforced held-out partition seals — three sealed lock files (
maxattempts-heldout.lock.json,kpigates-heldout.lock.json,heldout-partition.lock.json) commit a sha256 of the partition before evaluation. TheSEAL_VERIFIEDtypeof sentinel is the only way to compute cross-arm metrics on a sealed partition; passing anything else is a type error at the boundary. - Production-mode dispatcher —
makeProductionDispatcher+AgentInvokerinterface. The CLI--mode production|cannedflag selects whether calibration sees real verdicts or canned ones; the canned arm is preserved for offline reproducibility.
What an agent can ask it
Getting started
A note on naming. This is published as ai-architect-mcp-spec across its Claude Code, Codex, Gemini, MCPB, PyPI/npm and MCP Registry surfaces. 0.7.0 moved the Registry entry and primary bundle to that identity; 0.8.0 completed the migration, so no prd-spec-generator plugin or release alias is retained anywhere. The former io.github.cdeust/prd-spec-generator Registry versions are deprecated with a pointer to the canonical entry rather than left active and frozen.
Install (marketplace — recommended)
Restart your Claude Code session. The 17 MCP tools register on first stdio handshake. Then:
The plugin's bundled MCP server at mcp-server/index.js is self-contained
(only better-sqlite3 is an optional native dependency for the evidence
repository — gracefully degrades to in-memory mode when absent).
Migrating from prd-spec-generator
The old plugin and marketplace are deprecated publications, not aliases. Remove them before installing the canonical package:
Callers that used prd-spec-generator:generate-prd must use
ai-architect-mcp-spec:generate-prd. The prd-gen MCP server name,
@prd-gen/* private workspace packages, PRD_GEN_* environment variables,
and .prd-gen local data directory remain stable internal interfaces; they do
not keep the deprecated publication installed.
Plugin-scoped MCP tool names include both the publication name and the stable server key, so prompts, automation, and allowlists must migrate the complete prefix:
- old:
mcp__plugin_prd-spec-generator_prd-gen__<tool> - new:
mcp__plugin_ai-architect-mcp-spec_prd-gen__<tool>
Gemini CLI also keys installed extensions by the manifest name. Replace an installed extension under the former identity instead of updating it in place:
Companion ecosystem
For full effect, install the three companion plugins so the pipeline can consume codebase intelligence, persistent memory, and the genius-agent panel:
Each plugin is independently useful; together they are the ai-architect ecosystem. See Companion ecosystem above.
Building from source
For development or to run the audit cycle locally:
pnpm verify runs all of the above (install + build + bundle + test) —
same as CI.
Prerequisites for source builds: Node.js 20.x or 22.x, pnpm v10+
(corepack enable && corepack prepare pnpm@10).
Smoke-test offline
Both run in <2s on an M-series Mac. No LLM calls, no MCP traffic — the reducer is fully driven by canned ActionResults so you can audit behaviour offline.
Use with other MCP hosts
Honest scoping first. The full pipeline is host-dependent: the reducer
returns actions (ask_user, spawn_subagents, write_file) that assume a
host which executes them and feeds results back. Claude Code (via the plugin +
/generate-prd skill) remains the only packaged host for that workflow.
Codex and Gemini instead receive the portable Spec Verifier: a no-LLM
surface with exactly two deterministic tools and the same audit-prd and
validate-spec skills:
validate_prd_section— Hard Output Rules against a single sectionvalidate_prd_document— cross-section checks (SP/AC/FR/test traceability)
Install it in Codex from the repository marketplace:
Install the same package as a Gemini CLI extension:
Both manifests launch mcp-server/index.js with --profile verifier. The
existing Claude manifest passes no profile and therefore retains the default
17-tool full surface.
A zero-violation result means that the document satisfies the implemented structural rules. It does not prove factual accuracy, product value, implementation feasibility, security, or semantic correctness.
For an un-packaged MCP host, clone the repository and select the same narrow
profile explicitly. Replace /abs/path with the clone location.
OpenAI Codex CLI (~/.codex/config.toml, shared with the ChatGPT
desktop app and Codex IDE extension):
Cursor (.cursor/mcp.json) and Windsurf
(~/.codeium/windsurf/mcp_config.json):
VS Code (.vscode/mcp.json):
The pipeline
The reducer produces twenty sequential steps: eleven PRD-generation steps, then nine opt-in post-specs implementation steps entered only through a human gate. Each step emits at most one substantive action; the host executes it and feeds the result back. A typical trial-tier feature run (11 sections) takes ~62 host-visible iterations.
| # | Step | What it produces |
|---|---|---|
| 1 | banner | Welcome banner with run ID + feature description + capability summary |
| 2 | preflight | Probes the required ecosystem MCPs (Cortex, ai-architect) before the pipeline depends on them; skippable via skip_preflight |
| 3 | context_detection | Detects PRD type from trigger words; asks user when ambiguous |
| 4 | input_analysis | Calls index_codebase (ai-architect-mcp-codebase) when a path is provided; sets codebase_graph_path |
| 5 | feasibility_gate | Detects epic-scope inputs (≥2 EPIC_SIGNALS); asks user to focus |
| 6 | clarification | Compose-then-answer rounds (4–10 depending on tier); short-circuits on "proceed" |
| 7 | budget | Per-section retrieval/generation token allocation via Cortex paper's 60/30/10 split |
| 8 | section_generation | One section at a time: Cortex recall → engineer draft → validate → (retry up to 3) |
| 9 | jira_generation | Synthesises JIRA tickets from requirements + user_stories + acceptance_criteria |
| 10 | file_export | Writes 9 files (6 core + 3 companion) per SKILL.md |
| 11 | self_check | Two-phase multi-judge verification (see below); typed verification field on done |
Steps 12–20 are the opt-in post-specs implementation loop: implementation_gate (human gate — "Implement" vs "PRD only"; also writes 10-verification-report.md) → pre_impl_grounding → implementation (engineer subagent in an isolated worktree) → post_impl_verification (index → detect changes → semantic diff → security gates) → testing → review (a FAIL verdict retries implementation on the same worktree, bounded by REVIEW_RETRY_CAP) → pr_gate (mandatory human gate before any push) → pr_creation → finalize. Answering "PRD only" at implementation_gate skips straight to finalize; complete is the terminal marker, not a step.
Every step is independently testable (stepOnce(state, result?) returns the same shape as the runner). The runner coalesces emit_message actions internally so the host never sees a no-op.
The MCP tools
Three surfaces. The reducer drives the full pipeline; the validation + verification
- budget tools can be consumed directly by other systems without entering the pipeline; the diagnostics surface exposes config + health + history.
Each tool takes structured Zod-validated arguments and returns a typed response. No tool calls an LLM — section drafts and judge verdicts come back via the host's spawn_subagents action so the same pipeline runs against any agent runtime.
Multi-judge verification
The self_check step is a two-phase contract. Phase A plans the verification batch and persists a snapshot of (claim_ids, judges) to state. Phase B receives the verdicts, parses them against the snapshot, and aggregates via the consensus engine.
The verdict taxonomy is deliberately five-level — not binary. NFR claims (latency, fps, throughput, storage) MUST NOT receive PASS: they are SPEC-COMPLETE if a measurement method is specified, NEEDS-RUNTIME otherwise. Judges that default to PASS for everything are caught by the distribution_suspicious detector and flagged in the typed done.verification field.
Calibration & falsification
The verification subsystem is itself a hypothesis: that consensus weighted by historically-calibrated reliability outperforms consensus weighted by a uniform prior. The closed loop below is what tests it.
- Observe. Each verification run can flush per-judge observations (claim_id, claim_type, judge_id, verdict, oracle_truth?) to a SQLite reliability repository. Observations carry an
external_groundingfield that propagates fromClaimthrough the orchestrator to the oracle resolution path; when an external oracle (Ajv schema, mathjs,tsc,validateSection) can resolve the claim, its truth replaces LLM-only consensus. - Calibrate. On subsequent runs, calibrated posteriors weight consensus per judge, per
claim_type. A 20% control-arm partition is forced-explored using the prior (getReliabilityForRun/getRetryArmForRundecide which arm a given run lands in deterministically fromrun_id). Without the control arm, calibration-on-calibration looks like progress whether or not it actually is. - Compare. Cross-arm metrics (
computeAblationComparison,computeReliabilityComparison,computeKpiGateComparison) run paired-bootstrap CIs (Efron & Tibshirani 1993 §16.4; deterministic mulberry32 RNG; 12-decimal reproducibility pin) and emit one of three falsifiable recommendations:calibrated_helps,prior_helps, orinconclusive_underpowered. - Seal. Held-out partitions are committed to lock files (
maxattempts-heldout.lock.jsonfor §4.2,kpigates-heldout.lock.jsonfor §4.5,heldout-partition.lock.jsonfor the §4.1 50-claim externally-grounded corpus) with a sha256 hash of the partition. The cross-arm metric functions accept aSEAL_VERIFIEDtypeof sentinel as a parameter; the only way to obtain that sentinel is to verify the seal first. Peeking at a held-out partition before evaluation is a type error. - Ground. Where an external oracle can resolve a claim deterministically, it does. Where it cannot,
OracleUnavailableErroris thrown rather than fabricating a stub-mode truth. This is the line that breaks annotator-circularity: judges trained against (or biased toward) LLM-style reasoning cannot poison calibration that uses non-LLM truth.
The lock files, the seal-verification dance, and the control-arm partition together mean: when a cross-arm comparison says "calibrated_helps with 95% CI excluding zero," the claim is measured, not vibes-checked. When it says "inconclusive_underpowered," that is also a falsifiable claim — you need more data, not more confidence.
Architecture
Ten workspace packages, each independently buildable, with strict Clean Architecture layering enforced by package boundaries.
Dependency rule (absolute)
Every package's package.json is checked: core depends only on zod; verification depends only on core; orchestration depends on core/validation/verification/meta-prompting (NOT on ecosystem-adapters); ecosystem-adapters depends on core + verification; mcp-server is the only place where everything composes.
A cross-audit found and fixed two layer violations:
orchestrationwas importingextractJsonObjectandbuildJudgePromptfromecosystem-adapters— pure utilities lived in the wrong package; moved tocoreandverificationrespectively.- Pure domain types (
Claim,JudgeVerdict,JudgeRequest,AgentIdentity) lived inecosystem-adapters/contracts/subagent.ts; moved tocore/domain/agent.ts. The infrastructure package now re-exports them as a backward-compat shim.
What this fixes that previous PRD generators don't
| Failure mode | What we do |
|---|---|
| Section drift between turns | Single immutable PipelineState snapshot per step; reducer is pure; host can replay any step |
| Hallucinated symbols | validate_prd_section runs Hard Output Rules; symbols cross-checked against ai-architect-mcp-codebase graph if codebase_path is set |
| NFRs claiming PASS without measurement | Verdict taxonomy refuses PASS for latency/throughput/fps/storage; consensus engine forwards SPEC-COMPLETE / NEEDS-RUNTIME |
| Confirmatory bias (every judge says PASS) | distribution_suspicious flag fires at 100% PASS over ≥5 claims; surfaced in typed done.verification.distribution_suspicious |
| Acceptance criteria not traceable to requirements | Cross-document validator checks FR-AC coverage and AC numbering gaps |
| Tests claiming "comprehensive" without listing what they cover | Test-traceability rule: every section's claimed test must reference an FR or AC ID |
| Retries that use the same context as the failure | map_failure_to_retrieval closes the validator→Cortex feedback loop; corrective queries before retry |
| Magic-number budgets ("we'll use 4K tokens for retrieval") | coordinate_context_budget produces per-section allocations from the canonical SECTIONS_BY_CONTEXT plan |
How it composes with the rest of the ecosystem
Each project owns one concern. ai-architect-mcp-codebase knows what's true about the code. Cortex knows what we already decided. zetetic-team-subagents knows how to reason about a specific shape of claim. AI Architect MCP Spec is the deterministic glue that turns those three signals into a PRD an agent can act on.
The Zetetic Standard
Every load-bearing constant in this codebase carries a // source: annotation. Three forms are accepted:
The cross-audit found and tagged every previously bare constant. Examples:
The four pillars (consistent / true / useful / necessary) and the seven rules of zetetic inquiry are inherited from the zetetic-team-subagents standard. Provisional values are not silently propagated as truth.
What this system does not do
The same standard applied to itself.
- The PRD pipeline does not write code — and the server itself never does. Steps 1–11 produce a PRD; symbols in the PRD are validated against the graph but never edited by us. The opt-in implementation loop (steps 12–20) runs only when a human answers "Implement" at
implementation_gate; there, the host's engineer/test-engineer/code-reviewer subagents write, test, and review the implementation in an isolated worktree, and nothing is pushed or turned into a PR without the mandatorypr_gateapproval. This server only emitsspawn_subagentsactions — it never edits source files or pushes branches itself. - It does not validate prose quality. Hard Output Rules check structural invariants (FR numbering, AC traceability, NFR shape, cross-references). They do not check whether a sentence is well-written or persuasive. That is what the multi-judge phase is for, and even there the judges return verdicts on claims — atomic assertions — not on style.
- The judge phase is end-to-end testable but the judges are not deterministic. In tests we use a canned dispatcher that returns 100% PASS by construction; the
distribution_suspiciousdetector exists precisely because real judge panels can also degenerate into confirmatory consensus, and we do not pretend otherwise. - The KPI gates are calibrated, not hand-picked.
iteration_count_max,wall_time_ms_max, andmean_section_attempts_maxare calibrated against the K=100 frozen baseline with Clopper-Pearson exact CIs, per-machine-class wall_time normalization, andloadCalibratedGates+hold_provisionalratchet protection. The lock file commits a content-hash of the baseline; mutating it post hoc fails the seal verification. Where data is still thin, gates remainhold_provisionalrather than locked. See docs/PHASE_4_PLAN.md for the full pre-registration. - Citation presence ≠ citation validity. A
// source: Knuth 1998comment satisfies the convention whether or not Knuth 1998 exists or supports the value. We enforce that the citation IS THERE; the cross-audit cycle (genius + team review every phase) is what keeps it honest.
Reproducing the audit cycle
The repo ships a multi-agent cross-audit workflow. After every non-trivial phase:
Each agent reads the current state of the code (not from memory) and produces a ranked finding list, severity-ranked. Findings are closed in the cycle that raised them; anything that cannot be closed without new measurement is carried with the evidence required to close it written down, so a deferral is a stated obligation rather than a silence.
Project layout
License
MIT — see LICENSE.
Project documents: ROADMAP (what the project intends to do, and what it will not do, for the next year) · CONTRIBUTING (how to propose a change, and the testing policy) · GOVERNANCE (who decides, and what happens to the project if the maintainer stops) · SECURITY (how to report a vulnerability, and the supply-chain guarantees) · Assurance case (the security argument and where it stops) · CODE OF CONDUCT · CHANGELOG.
This software is the independent work of Clément Deust. It was developed outside any employment relationship and is not affiliated with, endorsed by, or owned by any past or present employer. It is part of the ai-architect ecosystem (Cortex, ai-architect-mcp-codebase, zetetic-team-subagents).
Citations and primary sources for algorithms and constants are documented
inline in the code via // source: annotations per the project's
source-discipline rules. Removing those annotations does not change the
license terms but does forfeit attribution to the original research the
code is built on.
Don't ship a PRD that hallucinates a function it can't measure.
Ship one whose every claim was judged by Pearl, Curie, Liskov, and a panel of seven others, validated against the call graph, and grounded in what Cortex remembers from yesterday.