[Extension]: Add Blueprint Index — Living Architecture Map #3628

Extension ID: blueprint-index

Extension Name: Blueprint Index — Living Architecture Map

Version: 0.2.0

Description:
A living architecture map for spec-driven projects, kept honest by a deterministic, low-friction, machine-first CI gate (JSON output, self-healable) that blocks only when the map contradicts the specs or code — and warns, without blocking, on the rest. Brownfield or greenfield.

Author: ogil109

Repository URL: https://github.com/ogil109/spec-kit-blueprint

Download URL: https://github.com/ogil109/spec-kit-blueprint/releases/download/v0.2.0/blueprint.zip

License: MIT

Homepage (optional): https://github.com/ogil109/spec-kit-blueprint/tree/main

Documentation URL (optional): https://github.com/ogil109/spec-kit-blueprint/blob/main/README.md

Changelog URL (optional): https://github.com/ogil109/spec-kit-blueprint/blob/main/CHANGELOG.md

Required Spec Kit Version: >=0.10.0

Required Tools (optional):

• bash (>=4) — required to run the deterministic oracle / coherence gate on Unix/macOS
• git — required for the code-staleness check / remap baselines
• PowerShell (>=7) — alternative oracle for Windows (parity port; pending execution-verification)

Number of Commands: 4

Number of Hooks: 0

Tags: blueprint, architecture, coherence, drift, brownfield, ci

Key Features:

• One collapsing architecture map. A section holds full design only while design work is pending; once an owner (a feature spec, or existing code) holds the truth it distills to a digest + pointer. Detail flows out into specs once, forward, never back-synced — killing the master-doc↔spec duplication.
• A tiered, machine-first coherence gate for CI (blueprint-state.sh check, no LLM). It classifies issues by severity: HARD (the map contradicts reality — a built spec it doesn't index, or a section pointing at deleted code) blocks the merge; SOFT (code changed under a mapped area, new unmapped code, an unprocessed section, a missing baseline) is advisory — because blocking every code change is the false-positive friction teams reject. --strict promotes soft → blocking. Output is machine-first (JSON when piped, human on a TTY — check and next are the machine surfaces; status is a human dashboard); check --json emits a versioned contract with a self-describing remedy.run + remedy.kind per issue, so a CI LLM backend can self-heal. remap re-derives a section and refreshes its git baseline.
• Dual on-ramp. Seed the map from a design doc (greenfield) or init --from-code to reverse-map an existing codebase into a code-owned architecture map (brownfield).
• It doesn't change how you build — you keep your normal spec-kit flow; the blueprint is the map around it and check is the gate that keeps it honest.
• Autonomous waterfall harness (no extra command). Because the map is externalized state and the oracle computes the next action deterministically, an agent can loop on it to run the spec-kit waterfall across a multi-spec backlog without drifting over a long session. The loop contract + a recommended constitution principle live in docs/autonomous-harness.md; tests/harness_loop_test.sh proves the loop sequences multiple specs with parking and stop bounds.
• Provider-agnostic command definitions (one source renders natively per AI integration).

Testing Checklist: (all required boxes)

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements:

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details:

• Installation verified against the published v0.2.0 release asset (downloaded from the Download URL above, not a local build) through spec-kit's ExtensionManager.install_from_zip: the manifest validates, all 4 commands register, and every file lands under .specify/extensions/blueprint-index/. The installed oracle was then executed in that project (check, status) and behaved correctly.
• 33 deterministic tests, all passing in CI (.github/workflows/tests.yml), requiring nothing beyond bash + git:
  • tests/oracle_test.sh (13) — phase frontier, provenance markers, context sections, distill drift, and the greenfield / organic-doc / brownfield-settled state logic.
  • tests/check_remap_test.sh (15) — the tiered gate against a real git repo: HARD issues (drift, dangling) block (exit 1); SOFT issues (stale, unmapped, unstamped) are advisory (exit 0) and block only under --strict; check --json emits the versioned contract with the right severity/type/remedy.kind; restamp refreshes baselines.
  • tests/harness_loop_test.sh (5) — looping on the real oracle over a multi-slice project sequences specs cleanly (specify → … → distill, per slice, in order), honoring stop bounds, slug scoping, and parking.
• Dogfooded end-to-end on a real ~2,100-line brownfield project (two slices carried through to distilled, map kept in sync by the gate).
• The Bash and PowerShell oracles are diffed against each other over shared fixtures as a cross-check. That diff caught a real bug in the Bash side before this submission (an issue with an empty target had its fields shifted), fixed in 0.1.3 with regression tests.
• Honest scope. This is 0.1.3 and deliberately labelled experimental:
  • The oracle and gate are deterministic and tested; map content (init mapping a repo, distill writing a digest) is agent-authored and reviewed.
  • The gate does detection, not conformance — it flags that mapped code moved, not that it correctly implements its spec, and it does not verify that a distilled digest still faithfully reflects its spec.
  • The central design bet — that making stale advisory rather than blocking is the right friction balance for real CI — is validated on one codebase. Feedback on false positives/negatives is the main thing I hope to get from listing this.
  • The PowerShell oracle is execution-verified at output parity with the Bash oracle on pwsh 7.4 (Linux) — identical JSON, identical exit codes (default and --strict), identical recorded baselines, across every issue state. Windows itself is unverified (path separators, git-for-Windows); that is the open gap.
  • Two narrow edges are documented: a [NEEDS CLARIFICATION] marker wrapped across lines is not detected, and the unmapped scan skips a top-level directory whose name contains a space.
  • status prints a human dashboard only; check and next are the machine-readable surfaces.
• Note for other extension authors: verified against specify 0.13.3.dev0 (built from main): installing from a zip leaves shipped .sh scripts non-executable (zipfile.extractall drops the mode bit), while a --dev directory install preserves it. ensure_executable_scripts() already covers .specify/extensions but isn't called from extension_add, so this self-heals after a later specify init and persists otherwise. All documented invocations here therefore use bash <path>, which works regardless.

Example Usage:

# Install
specify extension add blueprint-index \
  --from https://github.com/ogil109/spec-kit-blueprint/releases/download/v0.2.0/blueprint.zip

# Greenfield: seed the map from a design doc, then build with normal spec-kit
/speckit.blueprint-index.init docs/master-spec.md
/speckit.blueprint-index.distill 001-some-slice     # collapse a finished slice; stamps its baseline

# Brownfield: reverse-map an existing repo
/speckit.blueprint-index.init --from-code
/speckit.blueprint-index.status

# Keep the map honest in CI (exit 1 on distill drift or code staleness)
bash .specify/extensions/blueprint-index/scripts/bash/blueprint-state.sh check
/speckit.blueprint-index.remap src/payments          # after a refactor flagged it STALE

Proposed Catalog Entry:

{
  "blueprint-index": {
    "name": "Blueprint Index — Living Architecture Map",
    "id": "blueprint-index",
    "description": "A living architecture map for spec-driven projects, kept honest by a deterministic, low-friction, machine-first CI gate (JSON, self-healable) that blocks only when the map contradicts the specs or code. Brownfield or greenfield.",
    "author": "ogil109",
    "version": "0.2.0",
    "download_url": "https://github.com/ogil109/spec-kit-blueprint/releases/download/v0.2.0/blueprint.zip",
    "repository": "https://github.com/ogil109/spec-kit-blueprint",
    "homepage": "https://github.com/ogil109/spec-kit-blueprint/tree/main",
    "documentation": "https://github.com/ogil109/spec-kit-blueprint/blob/main/README.md",
    "changelog": "https://github.com/ogil109/spec-kit-blueprint/blob/main/CHANGELOG.md",
    "license": "MIT",
    "category": "process",
    "effect": "read-write",
    "requires": {
      "speckit_version": ">=0.10.0"
    },
    "provides": {
      "commands": 4,
      "hooks": 0
    },
    "tags": ["blueprint", "architecture", "coherence", "drift", "brownfield", "autonomous", "ci"],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "2026-07-21T00:00:00Z",
    "updated_at": "2026-07-21T00:00:00Z"
  }
}

Additional Context:
This extension was proposed in #2989; a maintainer asked for it to be delivered as a community extension. Developed with AI assistance (Claude Code), per the Contributing guidelines.