spec-kit-synthesis

spec-kit-synthesis

Synthesize a project's scattered spec-kit specs into one readable, beautiful, interactive whole-system architecture document. Where /speckit.clarify checks one spec for correctness and /speckit.analyze checks consistency, this reads all of them — overlapping, evolving, sometimes contradictory — and reasons them into a single current-state architecture storybook, organized by structure, not by spec history.

• What it is: a Claude Code plugin with two skills — speckit-storybook (one repo → one storybook) and speckit-atlas (a workspace of repos → a documentation portal). The in-session agent is the reasoning engine — no API key, no subprocess.
• Output: one self-contained, interactive HTML document — or a whole static portal of them
• Toolchain: uv · Python ≥ 3.11
• Status: Phases 1–3 shipped, each judged faithful (0/0/0) by independent cross-model review
• License: MIT

A newcomer reads one generated document and understands how the whole system is built — accurately, in plain English, with every claim traceable to a source. Not a dashboard. Not a per-spec renderer. The book, not the filing cabinet.

---

Why synthesis

A spec-driven project accretes dozens of small specs over time. No single document ever says "here is the whole system." New engineers and technical evaluators can't read 30 fragmented spec folders and reconstruct the architecture — and the specs contradict each other, because feature 003 supersedes a decision feature 001 made. Existing tooling can't help here:

Need	/speckit.clarify	/speckit.analyze	Synthesis
Is one spec internally correct?	✅	partial	—
Are the specs mutually consistent?	❌	✅	—
What does the whole system look like, now?	❌	❌	✅
Which superseded decisions are no longer true?	❌	❌	✅
Where do the specs leave a gap?	partial	partial	✅
Is the spec actually built (intent vs code)?	❌	❌	✅

Synthesis is a reasoning task — reconciling many sources into one current-state narrative — which is why an LLM does it and a template cannot.

How it works

flowchart LR
    S1["specs/"]:::src --> AD
    S2["code"]:::src --> AD
    S3["design docs / ADRs"]:::src --> AD
    AD["source-typed<br/>adapters"]:::code --> FC["fragment<br/>corpus"]:::ir
    FC --> EX["extract"]:::agent --> RC["reconcile<br/>· the product ·"]:::agent --> CO["compose"]:::agent --> VG{"verify<br/>fail-closed"}:::code
    VG -->|pass| RN["render"]:::code --> HTML["interactive<br/>storybook"]:::out
    VG -.->|"fail: fix &amp; re-reason"| EX
    classDef src fill:#f3efe4,stroke:#b3471d,color:#17150f
    classDef code fill:#e2ece7,stroke:#1f5048,color:#17150f
    classDef agent fill:#f6e6da,stroke:#b3471d,color:#17150f
    classDef ir fill:#ffffff,stroke:#87827a,color:#17150f
    classDef out fill:#efe4f0,stroke:#6a3a6f,color:#17150f

1. Adapt (code). A source adapter turns each input into a source-typed fragment corpus — spec fragments from spec folders, code fragments from a source tree, design_doc fragments from ADRs/design docs. The core never learns what a "spec" is; it reasons over uniform fragments. This is the seam that lets new sources drop in without a rewrite.
2. Extract → reconcile → compose (the in-session agent). The agent reads the corpus and reasons the three phases: pull each source's claims/decisions/open-questions; reconcile them into one current-state model — merging overlaps, demoting superseded behaviour to evolution notes, surfacing contradictions as open questions; then compose altitude-tagged prose, callouts, and declarative diagrams. Reconcile is the product; everything else serves it.
3. Verify (code, fail-closed). A deterministic gate rejects any claim whose provenance doesn't resolve, any ungrounded block, any empty callout, or a missing scope note. Faithfulness is code-enforced, not model-promised — if the gate exits non-zero, the run isn't done.
4. Render (code). A deterministic renderer turns the document model into one self-contained, interactive SVG storybook (theme-aware, no external assets).

What it produces

A single HTML file you can read at three depths via one control — so an executive and a developer read the same document:

flowchart TD
    R(["Read as …"]):::ctl --> L0 & L1 & L2
    L0["Overview · Layer 0<br/>plain-English — an exec stops here"]:::l0
    L1["Technical · Layer 1<br/>entity tables, data model, infra"]:::l1
    L2["Sources · Layer 2<br/>named, source-typed citations"]:::l2
    classDef ctl fill:#b3471d,stroke:#b3471d,color:#ffffff
    classDef l0 fill:#f3efe4,stroke:#87827a,color:#17150f
    classDef l1 fill:#f6e6da,stroke:#b3471d,color:#17150f
    classDef l2 fill:#e2ece7,stroke:#1f5048,color:#17150f