[Feature]: Blueprint progressive-distillation workflow (authoritative, collapsing doc for autonomous builds)

[ogil109]

Problem Statement

Projects that adopt Spec Kit often start from a comprehensive "master" design doc and then slice it into per-feature specs. This creates two sources of truth: the master doc and the specs both hold the detail for any slice that's already been specced. Every time a feature spec is refined during review, contributors feel obliged to back-sync the master doc so the two don't drift. That backward sync is cumbersome, error-prone, and never-ending.

The root cause is that the master doc plays two roles, and only one is worth its cost:

Role	Value	Cost
A — holding pen for designed-but-not-yet-specced decisions (the backlog of future specs)	High — where future specs are born	Low — changes only when you design something new
B — detailed mirror of slices that already have a feature spec	Low — the spec already owns this	High — recurring backward sync

Role B is pure overhead. Role A is genuinely valuable, and Spec Kit has no home for it today (where do decisions about a not-yet-specced subsystem live?).

This matters more now that agents run long, autonomous sessions: they need one authoritative artifact that says what to build next, how it fits, and where the truth lives — not detail scattered across a master doc and N specs that drift apart.

Proposed Solution

A blueprint: a decreasing-detail document that is simultaneously (1) the backlog of unspecced subsystems, (2) the cross-cutting architecture map, and (3) the index of feature specs.

• Where no feature spec exists yet: the blueprint keeps full design detail (the holding pen / backlog you draw from when you /speckit.specify that slice later).
• Where a feature spec exists: that section distills to a short architectural summary + a pointer to the spec. The spec is the source of truth; the blueprint just indexes it.
• Over time the blueprint asymptotes to a pure architecture map + index. Detail flows out of the blueprint into specs, once, forward — never back. Role B disappears (nothing to back-sync); Role A is preserved.

I've built this as a bundled extension (same tier as git/bug) and validated it end to end. Working, tested branch:

https://github.com/ogil109/spec-kit/tree/feat/blueprint-progressive-distillation/extensions/blueprint

Three provider-agnostic commands (single command source, render natively for every integration):

• speckit.blueprint.init — scaffold the blueprint, optionally seeding from an existing master/overview doc (the migration path off a legacy master-spec).
• speckit.blueprint.distill — compress a finalized spec's section to summary + pointer. Distillation is lossy, so it prompts and never auto-runs — registered on after_specify as an optional hook, mirroring the git extension's optional-commit pattern.
• speckit.blueprint.status — read-only worklist (spec backlog, distill backlog, drift); designed to be called inside an autonomous loop (status next prints just the single next action).

The blueprint document uses machine-readable section status anchors (<!-- blueprint:subsystem id=… status=detailed|distilled spec=… -->) plus an Architecture Map index, so distill/status can parse it deterministically.

Open question for maintainers: is this a fit for bundled core (where I've built it — it's the cross-cutting coherence layer per-feature specs and the constitution don't provide), or would you prefer it as a community-catalog extension? It works identically either way; I'm happy to repackage as a standalone repo + extension_submission if community is preferred.

Alternatives Considered

• Status quo (manual back-sync) — the friction this removes.
• Presets — presets override existing templates; they don't add a new doc type + command + lifecycle hook, so they don't fit.
• Drop the master doc entirely — loses Role A (the unspecced-design backlog), which is the valuable half.
• Community-catalog extension — viable and lower-friction, but discovery-only rather than shipped-in-core; raised as the open question above.

Component

Agent integrations (command files, workflows) — implemented as a bundled extension with provider-agnostic command definitions, a doc template, an after_specify hook, catalog.json registration, and wheel packaging.

AI Agent (if applicable)

All agents — the commands are defined once and render per provider. Verified rendering for Claude Code (skills SKILL.md, - separator) and Gemini CLI (.toml, . separator); the cross-command references resolve to the correct per-provider separator automatically.

Use Cases

1. Autonomous, waterfall-style builds of self-contained projects — an agent drives a multi-hour session from the blueprint: status says what's next, detailed sections say what to build, distilled pointers say where the truth lives.
2. Migrating off a master/overview doc — init <master-doc> imports it as the holding pen, auto-distilling any sections that already have specs.
3. Keeping a large spec set coherent — status surfaces drift (specced sections still holding detail; pointers to specs that no longer exist; map rows that disagree with sections).

Acceptance Criteria

• New doc type with detailed→distilled section lifecycle and a parseable anchor convention
• init / distill / status commands, provider-agnostic (verified on 2+ agents)
• Distillation is lossy → prompts via an optional after_specify hook (never silent)
• Manifest validates against ExtensionManifest; bundled in catalog.json + wheel
• Tests mirroring the bug/git extension suites (full suite green: 3735 passed, 45 skipped)
• Maintainer decision: bundle into core vs. community catalog
• Docs (README/spec-driven.md) updated to introduce the blueprint concept

Additional Context

• Constitution tie-in: pairs naturally with a "Spec Authority" principle — the feature spec is the source of truth for its slice; the blueprint is a map that defers to specs.
• AI disclosure: this proposal and the linked implementation were developed with AI assistance (Claude Code), per the Contributing guidelines.