ai-architect-mcp-spec

<!-- mcp-name: io.github.cdeust/ai-architect-mcp-spec --> <p align="center"> <img src="assets/banner.svg" alt="AI Architect MCP Spec — verified PRDs for agentic delivery pipelines" width="100%"/> </p> <p align="center"> <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"> <img src="https://img.shields.io/badge/TypeScript-7.0+-3178c6.svg" alt="TypeScript 7.0+"> <img src="https://img.shields.io/badge/Node-20.x_·_22.x-339933.svg" alt="Node 20/22"> <img src="https://img.shields.io/badge/Tests-1506_passing-brightgreen" alt="1506 passing"> <img src="https://img.shields.io/badge/Packages-10-orange" alt="10 packages"> <img src="https://img.shields.io/badge/MCP_Tools-17-8A2BE2" alt="17 MCP tools"> <img src="https://img.shields.io/badge/Validators-Hard_Output_Rules-red" alt="Hard Output Rules"> <img src="https://img.shields.io/badge/Calibration-Closed_Loop-success" alt="Closed-loop reliability calibration"> <a href="https://www.bestpractices.dev/projects/13832"><img src="https://www.bestpractices.dev/projects/13832/badge" alt="OpenSSF Best Practices"></a> </p> <p align="center"> <strong>Catch a hallucinated spec before it becomes code.</strong><br> 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.<br> <strong>Works in Codex, Gemini CLI, Claude Code, and CI. Runs on your machine.</strong> </p> <p align="center"> <a href="#what-an-agent-can-ask-it">What An Agent Asks</a> · <a href="#getting-started">Getting Started</a> · <a href="#the-pipeline">Pipeline</a> · <a href="#the-mcp-tools">Tools</a> · <a href="#multi-judge-verification">Verification</a> · <a href="#calibration--falsification">Calibration</a> · <a href="#architecture">Architecture</a> · <a href="#the-zetetic-standard">Zetetic Standard</a> </p> <p align="center"> _{One of three MCP servers that each run standalone — memory, code graph, spec verification. <a href="#how-it-composes-with-the-rest-of-the-ecosystem">How they compose ↓</a>} </p>

---

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_suspicious rather 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_ATTEMPTS comes from Kaplan-Meier survival math, and map_failure_to_retrieval sends 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-backed ReliabilityRepository; observations flushed on every claim resolution.
• MAX_ATTEMPTS retry calibration — Kaplan-Meier survival math (kmEstimate / kmMedianAttempts / logRankTest with Greenwood + Brookmeyer-Crowley CIs); Schoenfeld sample-size derivation event-rate-corrected to ~519 (was 823) against the measured event_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_provisional ratchet 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, tsc subprocess code oracle, validateSection spec oracle. OracleUnavailableError typed 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 / computeKpiGateComparison produce paired-bootstrap CIs (Efron & Tibshirani 1993 §16.4; deterministic mulberry32 RNG; 12-decimal reproducibility pin). Outcome is a falsifiable recommendation: calibrated_helps, prior_helps, or inconclusive_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. The SEAL_VERIFIED typeof 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 + AgentInvoker interface. The CLI --mode production|canned flag selects whether calibration sees real verdicts or canned ones; the canned arm is preserved for offline reproducibility.

---

What an agent can ask it

start_pipeline(feature_description, codebase_path?)
  → returns the first NextAction; the host executes it and feeds the result
    back via submit_action_result. Eleven steps later: 9 PRD files written.

submit_action_result(run_id, result)
  → drives the reducer one more step. The host sees only SUBSTANTIVE actions
    (ask_user, call_pipeline_tool, call_cortex_tool, spawn_subagents,
     write_file, done, failed). emit_message is coalesced into the
     messages array; the host never has to "advance past" a banner.

validate_prd_section(content, section_type)
  → deterministic Hard Output Rules — zero LLM calls, pure regex/parsing.
  → returns: violations[], hasCriticalViolations, totalScore.

validate_prd_document(sections[])
  → cross-section checks: SP arithmetic, AC numbering, FR-AC coverage,
    test traceability. Catches what per-section validation misses.

coordinate_context_budget(prd_context, completed_sections[])
  → per-section retrieval/generation token budgets so Cortex recall and
    section drafting don't fight over the same context window.

map_failure_to_retrieval(violations[])
  → closes the validation→retrieval feedback loop. When a section fails
    validation, this returns the corrective Cortex query that would
    have prevented the failure.

---

Getting started

_{<strong>A note on naming.</strong> This is published as <code>ai-architect-mcp-spec</code> across its Claude Code, Codex, Gemini, MCPB, PyPI/npm and MCP Registry surfaces. <code>0.7.0</code> moved the Registry entry and primary bundle to that identity; <code>0.8.0</code> completed the migration, so no <code>prd-spec-generator</code> plugin or release alias is retained anywhere. The former <code>io.github.cdeust/prd-spec-generator</code> Registry versions are deprecated with a pointer to the canonical entry rather than left active and frozen.}

Install (marketplace — recommended)

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

Restart your Claude Code session. The 17 MCP tools register on first stdio handshake. Then:

/generate-prd build OAuth login for the admin console

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:

claude plugin uninstall prd-spec-generator@prd-spec-generator-marketplace
claude plugin marketplace remove prd-spec-generator-marketplace
claude plugin marketplace add cdeust/ai-architect-mcp-spec
claude plugin install ai-architect-mcp-spec@ai-architect-mcp-spec-marketplace

Callers that used `prd-spec-generator:generate