[Feature]: Blueprint — a waterfall harness for autonomous, agent-driven builds (collapsing blueprint + deterministic oracle + driver)

[ogil109]

Problem Statement

Projects that adopt Spec Kit often start from a comprehensive "master" design doc and slice it into per-feature specs. This creates two sources of truth: the master doc and the specs both hold the detail for any already-specced slice, so every spec refinement drags a cumbersome back-sync behind it. The master doc plays two roles — (A) a holding pen for designed-but-unspecced decisions (high value, low churn) and (B) a detailed mirror of slices that already have a spec (pure overhead). Role B is recurring waste; Role A has no home in Spec Kit today.

This matters more now that agents run long, autonomous sessions. To drive a multi-hour build unattended, an agent needs one authoritative artifact that says what to build next, how it fits, and where the truth lives — and a way to stay grounded that doesn't depend on the model remembering its own progress.

Proposed Solution

A blueprint waterfall harness — three layers:

1. Blueprint (state) — a decreasing-detail doc that is simultaneously the backlog of unspecced subsystems, the architecture map, and the spec index. Unspecced sections hold full design (the holding pen); once a feature spec owns a slice, that section distills to an at-a-glance digest + a pointer. Detail flows out into specs, once, forward — never back-synced. Prose-first: it works on organically-grown overview docs, not just generated ones.

2. Deterministic oracle (scripts/bash/blueprint-state.sh) — reads specs/ (ground truth) + the blueprint and computes the single next waterfall action (specify | clarify | plan | tasks | implement | distill | done). No LLM judgment in the part that must be reliable; the filesystem is the source of truth, so a long run can't drift.

3. Autonomous driver (/speckit.blueprint.drive + a blueprint-waterfall workflow) — loops the backlog through specify → clarify → plan → tasks → implement, distilling each slice as it goes, re-running the oracle every step. Bounded by max_steps / stop_before / slug / dry_run, and it parks any slice it can't finish autonomously and keeps going.

Working, tested branch (bundled extension, same tier as git/bug):
https://github.com/ogil109/spec-kit/tree/feat/2989-blueprint-progressive-distillation/extensions/blueprint

Commands (provider-agnostic, one source rendering natively per integration): init, next, status, distill, drive, plus the blueprint-waterfall workflow with persisted, resumable run-state.

Open question for maintainers

Fit for bundled core (where I've built it — the cross-cutting coherence + autonomy layer that per-feature specs and the constitution don't provide), or would you prefer a community-catalog extension? Works identically either way.

Honest status

• Deterministic Bash oracle with unit and behavioral tests (full suite green)
• Provider-agnostic commands; manifest validates against ExtensionManifest; bundled in catalog.json + wheel
• Prose-first blueprint convention; oracle works on hand-written overview docs
• PowerShell oracle port is written for parity but needs execution-verification on Windows/pwsh before merge
• Maintainer decision: bundle into core vs. community catalog
• Docs (README/spec-driven.md) introducing the blueprint concept

Additional Context

• Pairs naturally with a "Spec Authority" constitution 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.