claude-blueprint 1.0.0

package/commands/debt.md

@@ -0,0 +1,102 @@
+---
+name: blueprint:debt
+description: >
+  Track decision debt — deferred ADRs with trigger conditions that may have been met.
+  Surfaces decisions that are due for revisiting. Use when: "check decision debt",
+  "any deferred decisions due?", "decision debt", "what decisions are overdue?",
+  "deferred adrs", or periodically to prevent forgotten deferrals.
+---
+
+# Decision Debt Tracker
+
+Deferred ADRs are invisible liabilities. Each has a trigger condition — "revisit when X" —
+but nobody monitors whether X has happened. This skill does.
+
+> Decision debt compounds faster than technical debt. A deferred technology choice
+> becomes a deferred architecture choice becomes a deferred rewrite.
+
+## Shared Context
+
+Read from parent `blueprint/` skill directory:
+- `config/state.toml` — ADR directory
+- `config/taxonomy.toml` — severity levels
+
+## Process
+
+### Step 1: Find All Deferred Decisions
+
+Read all ADR files. Filter to status `Deferred`. For each, extract:
+- The trigger condition (from metadata or Consequences section)
+- When it was deferred (date)
+- The severity of the decision (from taxonomy)
+- What depends on this decision (from relationships.toml)
+
+Also scan for quasi-deferred decisions in Accepted ADRs:
+- Consequences that say "revisit when...", "defer until...", "reconsider if..."
+- TODO items in the decision or consequences sections
+- v2/future references that imply deferred scope
+
+### Step 2: Evaluate Trigger Conditions
+
+For each deferred decision, check if the trigger condition has been met:
+
+**Codebase triggers:**
+- "Revisit when we have >N files" → count source files
+- "Defer until auth is implemented" → grep for auth code
+- "Revisit when we add a second database" → grep for new DB imports
+- "Defer until performance matters" → check for performance-related code/config
+
+**Time triggers:**
+- "Revisit in 6 months" → compare defer date to today
+- "Reconsider at v2" → check version in package.json
+
+**External triggers:**
+- "Defer until data is available" → flag as "check manually"
+- "Revisit when team grows" → flag as "check manually"
+
+### Step 3: Calculate Decision Debt Score
+
+```
+Decision Debt = Σ (severity × age_months × dependency_count)
+```
+
+Higher score = more urgent. A high-severity decision deferred 8 months ago with
+3 other decisions depending on it is more urgent than a low-severity decision
+deferred last week.
+
+### Step 4: Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► DECISION DEBT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Total deferred: [N] explicit + [M] implicit
+Triggers met: [K] — action needed
+Decision debt score: [score]
+
+## Overdue Decisions (triggers met)
+
+| ADR | Decision | Trigger | Deferred | Age |
+|-----|----------|---------|----------|-----|
+| ... | ... | [trigger — MET] | [date] | [N] months |
+
+## Upcoming Decisions (triggers approaching)
+
+| ADR | Decision | Trigger | Status |
+|-----|----------|---------|--------|
+| ... | ... | [trigger — approaching] | [evidence] |
+
+## Implicit Deferrals (in accepted ADRs)
+
+| ADR | Deferred Item | Trigger |
+|-----|--------------|---------|
+| ... | "revisit when..." from consequences | [condition] |
+
+## Recommendations
+1. [Most urgent — trigger met, high severity, many dependents]
+2. [Next priority]
+```
+
+For triggered decisions, suggest `/blueprint:new --research` to make the deferred
+decision with fresh evidence.

package/commands/digest.md

@@ -0,0 +1,106 @@
+---
+name: blueprint:digest
+description: >
+  Generate a non-technical stakeholder digest of architectural decisions. For PMs, executives,
+  and non-technical stakeholders who need the what/why/cost/risk without the code. Use when:
+  "stakeholder summary", "executive digest", "architecture digest", "non-technical summary",
+  "explain decisions to management", "board summary", or before architecture review meetings.
+---
+
+# Stakeholder Architecture Digest
+
+One-page summary for people who allocate budget and set priorities. No code, no jargon,
+no implementation details. What was decided, why, what it costs, and what risks it carries.
+
+> Different audience than eli5. ELI5 is for developers who need to understand the system.
+> Digest is for people who need to understand the *decisions* — and their business implications.
+
+## Shared Context
+
+Read from parent `blueprint/` skill directory:
+- `config/state.toml` — ADR directory
+- `config/relationships.toml` — decision dependencies
+- `config/taxonomy.toml` — severity levels
+
+## Process
+
+### Step 1: Read All Decisions
+
+Read all ADR files. Categorize by:
+- Status (Accepted, Proposed, Deferred, Rejected, Deprecated, Superseded)
+- Category from taxonomy (Technology, Architecture, Data, Deployment, Security, etc.)
+- Severity (High, Medium, Low)
+- Date
+
+### Step 2: Generate Digest
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ ARCHITECTURE DIGEST — [Project Name]
+ Generated: [date]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Summary
+
+[2-3 sentences: what the system is, how many architectural decisions
+have been made, overall health/maturity assessment]
+
+Decisions: [N] accepted | [M] proposed | [K] deferred
+
+## Key Decisions
+
+[Top 5-7 highest-severity accepted decisions. For each:]
+
+### [Decision title — no technical terms]
+
+**What:** [One sentence — what was decided, in business language]
+**Why:** [One sentence — what problem this solves or risk it mitigates]
+**Trade-off:** [One sentence — what was given up]
+**Status:** Accepted [date]
+
+[Group by theme if possible: "Data & Storage", "Security", "Performance"]
+
+## Pending Decisions ([N])
+
+[Proposed ADRs awaiting review — these need attention:]
+
+- **[Title]** — [Why it matters to the business. What's blocked until decided.]
+
+## Deferred Decisions ([N])
+
+[Decisions explicitly postponed — these are conscious risks:]
+
+- **[Title]** — Deferred because [reason]. Trigger: [when to revisit].
+  **Risk if ignored:** [business impact of never deciding]
+
+## Risk Register
+
+| Risk | Severity | Source | Mitigation |
+|------|----------|--------|------------|
+| [business-language risk] | High/Med/Low | ADR-NNNN | [what's being done] |
+
+[Derive from ADR consequences sections — translate technical risks
+to business risks: "Data loss" not "Missing ACID guarantees"]
+
+## Decision Timeline
+
+[Chronological narrative — 3-5 sentences:]
+"In [month], the team decided to [first major decision]. This was followed
+by [second decision] in [month], which [enabled/constrained] [what].
+Currently, [N] decisions are pending review."
+
+## What Needs Attention
+
+[Actionable items for stakeholders — at most 3:]
+1. [Most urgent — what decision needs to be made and by when]
+2. [Second priority]
+3. [Upcoming trigger that will require a decision]
+```
+
+### Step 3: Tone
+
+- No technical terms. "Database" is ok. "ORM" is not.
+- Focus on business impact. "This saves $X/month" not "this reduces query latency"
+- Risks in terms stakeholders understand: "data loss", "security breach", "launch delay"
+- Short. If it's longer than one printed page, it's too long.
+- No code snippets, file paths, or architecture diagrams. This is prose.

package/commands/drift.md

@@ -0,0 +1,104 @@
+---
+name: blueprint:drift
+description: >
+  Detect gradual architectural drift by comparing codebase evolution against ADR expectations
+  over time. Not a point-in-time audit but a trajectory analysis. Use when: "check for drift",
+  "is the architecture eroding?", "drift analysis", "architecture trajectory", "are we
+  drifting from our decisions?", or periodically as a health check.
+---
+
+# Architecture Drift Detection
+
+Detects gradual architectural erosion — the kind where every individual commit is fine
+but the aggregate trajectory moves away from the architecture. The building inspector
+who compares photographs six months apart.
+
+## Shared Context
+
+Read from parent `blueprint/` skill directory:
+- `config/state.toml` — ADR directory, last operations
+- `config/relationships.toml` — ADR dependency graph
+- `agents/persona.md` — personality
+
+## Process
+
+### Step 1: Establish the Baseline
+
+Read all accepted ADRs and extract what the architecture *should* look like:
+- Module boundaries and their responsibilities
+- Dependency direction rules
+- Technology constraints
+- Pattern expectations
+
+Read `docs/ARCHITECTURE.md` if it exists for the canonical map.
+
+### Step 2: Analyze Git History for Trajectory
+
+Examine recent git history (configurable, default: last 3 months):
+
+```bash
+# File churn — which areas change most?
+git log --since="3 months ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -30
+
+# Cross-boundary commits — changes that touch multiple modules simultaneously
+git log --since="3 months ago" --name-only --pretty=format:"---COMMIT---" | ...
+
+# New files — where is the codebase growing?
+git log --since="3 months ago" --diff-filter=A --name-only --pretty=format: | sort | uniq -c | sort -rn
+
+# Deleted files — where is it shrinking?
+git log --since="3 months ago" --diff-filter=D --name-only --pretty=format:
+```
+
+### Step 3: Detect Drift Patterns
+
+For each accepted ADR, check if recent changes are moving toward or away from it:
+
+**Boundary erosion:** Module A was self-contained 3 months ago. Now it imports from
+3 new modules. The boundary is dissolving.
+
+**Responsibility creep:** A module that ADR-NNNN defines as "handles X" now also
+does Y and Z. Functions and files are accumulating outside the original scope.
+
+**Technology sprawl:** ADR says "use PostgreSQL." New code includes SQLite imports,
+a Redis client, and a JSON file database. The single-technology decision is fragmenting.
+
+**Pattern divergence:** ADR says "two-stage pipeline." Recent commits add a shortcut
+path that bypasses stage 1. The pattern is being undermined.
+
+**Dependency inversion:** ADR says "services depend on repositories, not vice versa."
+Recent imports show repositories importing from services.
+
+### Step 4: Quantify Drift
+
+For each detected drift:
+
+- **Direction:** Drifting TOWARD or AWAY from the ADR's intent
+- **Velocity:** How fast — number of drift-contributing commits per month
+- **Severity:** LOW (cosmetic), MEDIUM (architectural tension), HIGH (invariant violated)
+- **Reversibility:** Easy (rename/move), Moderate (refactor), Hard (rewrite)
+
+### Step 5: Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► DRIFT ANALYSIS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Period: [start] — [end]
+Overall trajectory: STABLE / DRIFTING / ERODING
+
+| ADR | Decision | Drift | Velocity | Severity |
+|-----|----------|-------|----------|----------|
+| ... | ... | TOWARD/AWAY/STABLE | N commits/mo | H/M/L |
+
+## Drift Details
+[Per-ADR analysis with evidence]
+
+## Recommendations
+- [Highest-impact corrective actions]
+- [ADRs that may need revision to match reality]
+```
+
+Suggest `/blueprint:rearchitect` for ADRs where reality has legitimately diverged
+from the decision — sometimes the drift is correct and the ADR is wrong.

package/commands/eli5.md

@@ -0,0 +1,149 @@
+---
+name: blueprint:eli5
+description: >
+  Explain an ADR or the entire architectural landscape in plain English. No jargon, no
+  acronyms left unexpanded, concrete analogies. Use when: "explain adr N", "eli5 adr N",
+  "what does adr 3 mean?", "explain architecture", "eli5 the whole thing", "summarise
+  our decisions", "what have we decided so far?", "give me the big picture", or when
+  onboarding someone who hasn't read the ADRs.
+---
+
+# ELI5 — Explain Like I'm 5 (but an intelligent 5)
+
+Two modes depending on whether a number is provided:
+
+- **`/blueprint:eli5 N`** — Explain a single ADR in plain English
+- **`/blueprint:eli5`** (no number) — Explain the entire architectural landscape
+
+No jargon survives this skill. Every technical term gets an analogy. Every decision gets
+a "so what?" The goal is that someone who has never read an ADR can understand what was
+decided and why it matters after reading the output.
+
+## Shared Context
+
+Read from parent `blueprint/` skill directory:
+- `config/state.toml` — ADR directory location
+- `config/relationships.toml` — how ADRs relate to each other
+
+## Mode 1: Single ADR (`/blueprint:eli5 N`)
+
+Read the specified ADR file. Produce a plain-English explanation with this structure:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► ELI5: ADR-NNNN
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## The Problem
+
+[1-2 sentences: what situation made this decision necessary.
+Use a real-world analogy. Not "we needed a database" but "we needed
+somewhere to store patient records that wouldn't lose data if the
+power went out."]
+
+## What We Decided
+
+[1-2 sentences: the decision in plain English. No acronyms.
+"We chose PostgreSQL" becomes "We chose a traditional relational
+database (PostgreSQL) — think of it as a very organized filing
+cabinet where every drawer has a label and everything is
+cross-referenced."]
+
+## What We Considered
+
+[For each option that was evaluated, one sentence:]
+- **[Option]**: [Plain English description + why we didn't pick it]
+
+## Why This One
+
+[2-3 sentences: the actual rationale in non-technical terms.
+What made this option better than the others for our situation?]
+
+## What This Means for You
+
+[1-3 bullets: practical consequences a developer would care about.
+"So what?" answers:]
+- If you need to X, do it this way because of this decision
+- Don't do Y — this decision rules it out
+- This connects to ADR-NNNN which decided [related thing]
+
+## The Trade-Off
+
+[1 sentence: what we gave up by making this choice.
+Every decision has a cost. Name it plainly.]
+```
+
+**Rules:**
+- Every acronym gets expanded AND explained on first use
+- Technical terms get a concrete analogy (not "asynchronous processing" but "like a restaurant where you order at the counter and they call your number when it's ready")
+- No hedging — state things directly
+- Keep total length under 30 lines
+- If the ADR references other ADRs, briefly note the connection
+
+## Mode 2: Full Landscape (`/blueprint:eli5`, no number)
+
+Read ALL ADR files and `docs/ARCHITECTURE.md` if it exists. Produce a narrative summary
+of the entire architectural landscape:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► ELI5: THE BIG PICTURE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## What We're Building
+
+[2-3 sentences from ARCHITECTURE.md or inferred from ADRs.
+Plain English, no jargon.]
+
+## The Key Decisions (in order of importance)
+
+[Group related ADRs into themes. For each theme:]
+
+### [Theme: e.g., "How We Store Data"]
+
+We decided to [plain English summary]. This means [practical
+consequence]. (ADR-NNNN, ADR-MMMM)
+
+### [Theme: e.g., "How the AI Works"]
+
+...
+
+[Continue for each theme. 3-6 themes typical.]
+
+## The Rules
+
+[From ARCHITECTURE.md invariants or inferred from ADRs.
+Plain English list of things you must not do:]
+
+1. Never [rule] — because [one-sentence reason]
+2. Always [rule] — because [one-sentence reason]
+
+## What We Deliberately Don't Do
+
+[From out-of-scope decisions and rejected ADRs.
+These are just as important as what we do:]
+
+- We don't [thing] — because [reason]
+
+## The 30-Second Version
+
+[One paragraph. If someone reads nothing else, they read this.
+What is it, what are the 3 most important decisions, what are
+the 2 most important rules.]
+```
+
+**Rules for full landscape:**
+- Group by theme, not by ADR number — humans think in topics, not sequence numbers
+- Read `config/relationships.toml` to identify clusters of related ADRs
+- Lead with the most impactful decisions, not the first ones chronologically
+- The 30-second version at the end is the most important part — write it last
+- Keep total length under 80 lines
+- If there are more than 15 ADRs, focus on the top 10 by impact and mention the rest as "also decided: [list]"
+
+## Tone
+
+This is the ONE skill where the cranky senior engineer persona softens slightly. The
+persona still applies — direct, no hedging, no fluff — but the goal is comprehension,
+not challenge. Think of it as the senior engineer explaining the system to a smart new
+hire on their first day. Patient about the concepts, impatient about unnecessary
+complexity in the explanation itself.

package/commands/evaluate.md

@@ -0,0 +1,61 @@
+---
+name: blueprint:evaluate
+description: >
+  Run the architecture evaluation team — 5 specialized agents analyzing consistency, bug surface,
+  maintainability, testing strategy, and Conway's Law alignment. Use when: "evaluate architecture",
+  "arch eval", "architecture review", "system evaluation", "evaluate codebase". Run individual
+  dimensions with: "/blueprint:evaluate consistency", "/blueprint:evaluate testing", etc. Produces a
+  comprehensive report with proposed ADRs for critical findings.
+---
+
+# Architecture Evaluation Team
+
+Spawns a team of 5 specialized agents in parallel to produce a comprehensive architecture
+evaluation. Each agent focuses on one dimension. Results are synthesized into a unified
+report with proposed ADRs for the most critical findings.
+
+## Shared Context
+
+Read from parent `adr/` skill directory:
+- `config/taxonomy.toml` — evaluation dimensions with agent mappings
+- `config/state.toml` — last evaluation date, ADR directory
+- `agents/persona.md` — shared personality
+
+## Dimensions
+
+Read `config/taxonomy.toml` `evaluation_dimensions` for the canonical list. Currently:
+
+| Dimension | Agent | Aspect Focus |
+|-----------|-------|-------------|
+| consistency | adr-consistency-auditor | naming, layering, dependency direction, error handling |
+| bugs | adr-bug-surface-mapper | complexity, coupling, boundaries, state, implicit contracts |
+| maintainability | adr-maintainability-assessor | dependencies, abstractions, change amplification, debt |
+| testing | adr-testing-strategy-evaluator | pyramid, risk coverage, anti-pattern tests, quality |
+| conways | adr-conways-law-analyzer | ownership, friction points, bottlenecks, scaling |
+
+## Process
+
+### Full Evaluation (`/blueprint:evaluate`)
+
+1. Read all 5 agent files + `agents/persona.md` from parent skill directory
+2. Spawn all 5 agents in parallel (single message, 5 Agent tool calls) with:
+   - Full agent instructions + persona
+   - Project root path, ADR directory path
+   - List of existing ADR filenames
+3. As agents complete, collect their reports
+4. **Synthesize unified report:**
+   - Overall health score: STRONG / ADEQUATE / CONCERNING / CRITICAL
+   - Top 3 risks across all dimensions
+   - Top 3 strengths across all dimensions
+5. **Collect proposed ADRs** from all agent reports, deduplicate, prioritize
+6. Ask user which to create:
+   - "Create all proposed ADRs"
+   - "Let me pick" — present list for selection
+   - "Report only" — skip ADR creation
+7. Draft selected ADRs via the `/blueprint:new` flow
+8. Update `config/state.toml` — set `last_evaluation` to today, append to evaluation_history
+
+### Individual Evaluation (`/blueprint:evaluate [dimension]`)
+
+Spawn only the specified dimension's agent. Same process but single agent, no synthesis step.
+Valid dimensions: `consistency`, `bugs`, `maintainability`, `testing`, `conways`.

package/commands/fitness.md

@@ -0,0 +1,119 @@
+---
+name: blueprint:fitness
+description: >
+  Generate executable architecture fitness functions from accepted ADRs. Produces test files
+  that enforce architectural invariants as CI-runnable checks. Use when: "generate fitness
+  functions", "architecture tests", "enforce invariants", "create architecture guards",
+  "fitness functions from adrs", or after accepting ADRs with structural constraints.
+---
+
+# Architecture Fitness Functions
+
+Translates accepted ADR invariants into executable test files. Fitness functions are
+unit tests for architecture — they run in CI and fail when architectural constraints
+are violated.
+
+> "An architecture that isn't tested will drift. An architecture with fitness functions
+> drifts and gets caught."
+
+## Shared Context
+
+Read from parent `blueprint/` skill directory:
+- `config/state.toml` — ADR directory location
+- `config/taxonomy.toml` — severity levels
+- `agents/persona.md` — personality
+
+## Process
+
+### Step 1: Extract Testable Invariants
+
+Read all accepted ADRs. For each, determine if the decision produces a testable
+invariant:
+
+**Testable invariants (generate fitness functions):**
+- Dependency direction rules: "Module A must not import from module B"
+- Technology constraints: "All database access must go through the ORM"
+- Pattern enforcement: "All API endpoints must have input validation"
+- Boundary rules: "No direct database queries outside the repository layer"
+- Constraint rules: "All code suggestions must come from the validated database"
+- File structure rules: "Every service must have a corresponding test file"
+
+**Non-testable (skip):**
+- Process decisions: "Use ADRs for decisions"
+- Deployment decisions: "Deploy as standalone web app"
+- Deferred decisions: "Defer auth to v2"
+
+### Step 2: Generate Test Files
+
+For each testable invariant, generate an executable test:
+
+**Detect the project's test framework:**
+- Python: pytest (check for pytest.ini, conftest.py, pyproject.toml [tool.pytest])
+- JavaScript/TypeScript: vitest or jest (check package.json)
+- Go: go test (check go.mod)
+- If unclear, ask the user
+
+**Test file naming:** `tests/architecture/test_adr_NNNN.py` (or equivalent)
+
+**Each test includes:**
+```python
+"""
+Architecture Fitness Function: ADR-NNNN — [Title]
+
+This test enforces the architectural invariant from ADR-NNNN.
+If this test fails, either fix the code to comply with the ADR,
+or create a new ADR to formally change the decision.
+
+DO NOT skip or delete this test without updating the ADR.
+"""
+```
+
+**Test patterns by invariant type:**
+
+Dependency direction:
+```python
+def test_adr_NNNN_no_service_imports_from_api():
+    """Services must not import from the API layer (ADR-NNNN)."""
+    violations = find_imports(source_dir="src/services", forbidden_pattern="from src.api")
+    assert not violations, f"Dependency violation: {violations}"
+```
+
+Technology constraint:
+```python
+def test_adr_NNNN_no_raw_sql():
+    """All database access must use the ORM (ADR-NNNN)."""
+    violations = grep_source(pattern=r"cursor\.execute|\.raw\(", exclude_dirs=["migrations"])
+    assert not violations, f"Raw SQL found: {violations}"
+```
+
+Pattern enforcement:
+```python
+def test_adr_NNNN_all_endpoints_validated():
+    """Every API endpoint must have Pydantic input validation (ADR-NNNN)."""
+    endpoints = find_route_handlers("src/api")
+    unvalidated = [e for e in endpoints if not has_pydantic_param(e)]
+    assert not unvalidated, f"Unvalidated endpoints: {unvalidated}"
+```
+
+### Step 3: Generate Helper Module
+
+Create `tests/architecture/conftest.py` (or equivalent) with shared utilities:
+- `find_imports(source_dir, forbidden_pattern)` — grep for import violations
+- `grep_source(pattern, include_dirs, exclude_dirs)` — regex search across source
+- `find_files(pattern, directory)` — glob for structural checks
+- `assert_no_violations(violations, adr_id, message)` — standard assertion
+
+### Step 4: Present and Commit
+
+Show the user:
+- How many ADRs produced fitness functions
+- List of generated test files
+- How to run them: `pytest tests/architecture/` or equivalent
+
+Commit: `test(architecture): generate fitness functions from [N] ADRs`
+
+## Updating Fitness Functions
+
+When an ADR is superseded or deprecated, the corresponding fitness function should
+be updated or removed. Suggest running `/blueprint:fitness` after any ADR lifecycle
+transition that changes invariants.