claude-blueprint 1.0.0

package/commands/status.md

@@ -0,0 +1,189 @@
+---
+name: blueprint:status
+description: >
+  Architecture governance dashboard with visual knowledge graph. Shows ADR status overview,
+  decision debt score, operation history, relationship graph, and governance health metrics
+  in an IDE-like interface. Use when: "blueprint status", "architecture dashboard", "show
+  governance health", "adr graph", "decision graph", "how are our decisions?", or just
+  "status".
+---
+
+# Architecture Governance Dashboard
+
+Renders a rich, visual governance dashboard with a knowledge graph of ADR relationships.
+Two output modes: terminal (structured text) and browser (interactive HTML).
+
+## Shared Context
+
+Read from parent `blueprint/` skill directory:
+- `config/state.toml` — last operation dates, ADR directory
+- `config/relationships.toml` — ADR dependency graph
+- `config/lifecycle.toml` — status definitions
+- `config/taxonomy.toml` — severity levels, categories
+
+## Process
+
+### Step 1: Gather All Metrics
+
+**ADR inventory:**
+- Read all ADR files, extract status, date, category, severity
+- Count by status: Accepted, Proposed, Rejected, Deferred, Deprecated, Superseded
+- Identify the most recent ADR and oldest unreviewed Proposed ADR
+
+**Decision debt:**
+- Count Deferred ADRs
+- For each, check trigger conditions against codebase (same logic as `/blueprint:debt`)
+- Calculate debt score: Σ(severity × age_months × dependency_count)
+- Flag any with triggered conditions
+
+**Operations recency:**
+- From `config/state.toml`: last audit, evaluation, retro, drift check dates
+- Calculate days since each
+
+**Relationship graph:**
+- From `config/relationships.toml`: nodes (ADRs) and edges (dependencies, conflicts, supersessions)
+- If graph is empty/sparse, suggest running `/blueprint:impact` on key ADRs to populate it
+
+**Fitness function coverage:**
+- Glob for `tests/architecture/` or equivalent
+- Count how many accepted ADRs have corresponding fitness functions
+- Calculate coverage percentage
+
+**Guard status:**
+- Check if pre-commit hook is installed (grep settings.json or .git/hooks/)
+
+### Step 2: Render Terminal Dashboard
+
+Always display this first:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Decisions
+
+  Accepted    ██████████████████████████████  28
+  Proposed    ██                              2   ← needs review
+  Deferred    █                               1   ← 1 trigger met
+  Rejected    ░                               0
+  Superseded  ░                               0
+  Total: 31
+
+## Governance Health
+
+  | Metric              | Value        | Status |
+  |---------------------|-------------|--------|
+  | Decision debt score | 14          | ⚠      |
+  | Last audit          | 12 days ago | ✓      |
+  | Last evaluation     | never       | ✗      |
+  | Last retro          | 3 days ago  | ✓      |
+  | Last drift check    | never       | ✗      |
+  | Fitness coverage    | 8/12 (67%)  | ⚠      |
+  | Guard hook          | not installed| ✗      |
+
+## Relationship Graph (text)
+
+  ADR-0002 (React+FastAPI) ◄── ADR-0003 (two-stage pipeline)
+       │                            │
+       └── ADR-0008 (constrain      └── ADR-0005 (persona)
+            to ICD-10-AM)
+
+  ADR-0006 (defer auth) ···· DEFERRED [trigger: user count >50]
+
+  Clusters: 3 connected components, 2 isolated ADRs
+
+## Suggested Actions
+
+  1. /blueprint:review 29 — Proposed ADR awaiting review
+  2. /blueprint:evaluate — No evaluation on record
+  3. /blueprint:debt — 1 deferred trigger appears met
+```
+
+### Step 3: Generate Interactive HTML Dashboard
+
+After the terminal display, generate an interactive HTML file with a visual knowledge
+graph and offer to open it:
+
+```bash
+# Write to a temp file and open
+/tmp/blueprint-dashboard-{timestamp}.html
+```
+
+**The HTML dashboard includes:**
+
+**Tab 1: Knowledge Graph (main view)**
+
+An interactive graph visualization using inline JavaScript (no external dependencies):
+- **Nodes** = ADRs, colored by status:
+  - Accepted: blue
+  - Proposed: yellow
+  - Deferred: orange
+  - Rejected: gray
+  - Deprecated: faded gray
+  - Superseded: gray with strikethrough
+- **Node size** = severity (High = large, Medium = medium, Low = small)
+- **Edges** = relationships, styled by type:
+  - DEPENDS_ON: solid arrow
+  - CONFLICTS: red dashed line
+  - SUPERSEDES: thick arrow with ×
+  - MODIFIES_SCOPE: dotted arrow
+  - RELATED: thin gray line
+- **Hover** on a node: show ADR title, status, date, category
+- **Click** on a node: show full ADR summary in a side panel
+- **Clusters** visually grouped by category (Technology, Architecture, etc.)
+- **Force-directed layout** using simple physics simulation
+
+Use a self-contained SVG or Canvas renderer — no D3.js or external CDN.
+The file must work offline with zero dependencies.
+
+**Tab 2: Decision Timeline**
+
+Horizontal timeline showing ADRs by date:
+- Color-coded by status
+- Supersession chains shown as connecting arcs
+- Hover for details
+
+**Tab 3: Governance Metrics**
+
+The same metrics as the terminal dashboard but with:
+- Sparkline-style history (from state.toml evaluation/retro history)
+- Color-coded health indicators
+- Clickable actions that copy the relevant `/blueprint:` command
+
+**Tab 4: Decision Debt**
+
+Table of deferred decisions with:
+- Trigger conditions and their status (met/approaching/not yet)
+- Debt score with color coding
+- Age in days
+- Dependency count
+
+### Step 4: Open Dashboard
+
+```bash
+# Write HTML to temp file
+# Open in browser (platform-specific)
+open /tmp/blueprint-dashboard-{timestamp}.html     # macOS
+xdg-open /tmp/blueprint-dashboard-{timestamp}.html # Linux
+start /tmp/blueprint-dashboard-{timestamp}.html    # Windows
+```
+
+Tell the user: "Dashboard opened in your browser. The terminal summary above is always
+available without the browser."
+
+### Step 5: Update State
+
+Set `last_status_check` in `config/state.toml` to today.
+
+## Fallback
+
+If the project has no ADRs yet, show:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+No ADRs found. Run /blueprint:init to bootstrap from existing context.
+```

package/commands/timeline.md

@@ -0,0 +1,113 @@
+---
+name: blueprint:timeline
+description: >
+  Generate a narrative timeline of architectural evolution through ADR history. Shows how
+  decisions built on each other, when things changed, and the arc of the architecture. Use
+  when: "show architecture timeline", "decision history", "how did we get here?", "architecture
+  evolution", "timeline of decisions", or for onboarding and strategic planning.
+---
+
+# Architecture Evolution Timeline
+
+The story of how the architecture evolved, told through its decisions. Not a git log —
+the narrative arc that explains how each decision enabled or constrained the next.
+
+## Shared Context
+
+Read from parent `blueprint/` skill directory:
+- `config/state.toml` — ADR directory
+- `config/relationships.toml` — supersession chains, dependencies
+
+## Process
+
+### Step 1: Read and Sort
+
+Read all ADR files. Extract:
+- ADR number, title, status
+- Date proposed and date decided
+- Supersedes/superseded-by relationships
+- Category from taxonomy
+
+Sort chronologically by date proposed.
+
+### Step 2: Identify Eras
+
+Group decisions into eras — periods where related decisions clustered:
+
+- **Foundation era:** First decisions that established the base (stack, architecture, deployment)
+- **Feature eras:** Groups of decisions related to specific capabilities
+- **Pivot points:** Superseded decisions that mark a change in direction
+- **Current era:** Recent and pending decisions
+
+### Step 3: Build the Narrative
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► ARCHITECTURE TIMELINE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## [Era 1: Foundation] — [date range]
+
+[Narrative paragraph: what was decided and why, how decisions
+connected to each other]
+
+  [date] ── ADR-0001: [title]                    ✓ Accepted
+       └── ADR-0002: [title]                    ✓ Accepted
+       └── ADR-0003: [title]                    ✓ Accepted
+            └── ADR-0008: [title] (depends on)  ✓ Accepted
+
+[1-2 sentences: what this era established and what it enabled]
+
+## [Era 2: ...] — [date range]
+
+  [date] ── ADR-0009: [title]                    ✓ Accepted
+  [date] ── ADR-0010: [title]                    ✗ Rejected
+       └── ADR-0011: [title] (replaced 0010)    ✓ Accepted
+
+[Note rejections and supersessions — these are the most interesting
+parts of the story. Why did the team change direction?]
+
+## Pivot Points
+
+[Decisions that marked a significant change in direction:]
+
+- **[date]: ADR-NNNN superseded ADR-MMMM** — [why the original decision
+  was replaced and what changed in the understanding]
+
+## Current State
+
+Active decisions: [N]
+Pending review: [M]
+Deferred: [K] (with triggers)
+Superseded: [J]
+
+## What's Next
+
+[Based on deferred decisions, pending proposals, and decision debt:]
+- [Decision that's coming up]
+- [Trigger that's approaching]
+```
+
+### Step 4: Visualize Supersession Chains
+
+If any ADRs have been superseded, show the chain:
+
+```
+ADR-0003 (original) ──superseded by──→ ADR-0015 ──superseded by──→ ADR-0022 (current)
+  "Use Redis"           "Use Memcached"              "Use built-in cache"
+```
+
+These chains tell the story of how understanding evolved.
+
+### Step 5: Connect to Relationship Graph
+
+Use `config/relationships.toml` to show dependency clusters — groups of
+ADRs that must be considered together. A dependency cluster is a set
+of decisions where changing one requires reviewing all the others.
+
+## Tone
+
+This is a story, not a report. It should read like a project retrospective
+written by someone who understands why things happened, not just what happened.
+The senior engineer persona applies but with a historian's perspective —
+connecting cause and effect across time.

package/commands/transition.md

@@ -0,0 +1,83 @@
+---
+name: blueprint:transition
+description: >
+  Direct lifecycle transitions for ADRs — accept, reject, defer, or deprecate without spawning
+  agents. Use when: "accept adr N", "reject adr N", "defer adr N", "deprecate adr N". For
+  review with devil's advocate challenge, use /blueprint:review instead. For superseding, use
+  /blueprint:rearchitect instead.
+---
+
+# ADR Lifecycle Transitions
+
+Handle simple status transitions inline — no agent spawning. Read the state machine from
+`config/lifecycle.toml` to validate transitions and requirements.
+
+## Shared Context
+
+Read from parent `adr/` directory:
+- `config/lifecycle.toml` — valid transitions, requirements, error messages
+- `config/state.toml` — ADR directory location
+- `config/relationships.toml` — for updating edges on supersession
+
+## Supported Transitions
+
+### Accept (`/blueprint:transition accept N`)
+
+Proposed → Accepted per `lifecycle.toml`.
+
+1. Read the ADR, verify status is Proposed
+2. Set status to `Accepted`
+3. Set `Date decided` to today
+4. Update README.md index
+5. Commit: `docs(adr): accept ADR-NNNN <title>`
+
+### Reject (`/blueprint:transition reject N`)
+
+Proposed → Rejected per `lifecycle.toml`.
+
+1. Read the ADR, verify status is Proposed
+2. Ask for rejection reason
+3. Append reason to Consequences section
+4. Set status to `Rejected`
+5. Update README.md index
+6. Commit: `docs(adr): reject ADR-NNNN <title>`
+
+### Defer (`/blueprint:transition defer N`)
+
+Proposed → Deferred per `lifecycle.toml`.
+
+1. Read the ADR, verify status is Proposed
+2. Ask for trigger condition (when to revisit)
+3. Add trigger to metadata
+4. Set status to `Deferred`
+5. Update README.md index
+6. Commit: `docs(adr): defer ADR-NNNN <title>`
+
+### Deprecate (`/blueprint:transition deprecate N`)
+
+Accepted → Deprecated per `lifecycle.toml`.
+
+1. Read the ADR, verify status is Accepted
+2. Ask for deprecation reason
+3. Add deprecation note with date
+4. Set status to `Deprecated`
+5. Update README.md index
+6. Commit: `docs(adr): deprecate ADR-NNNN <title>`
+
+## Invalid Transitions
+
+Read `lifecycle.toml.invalid_transitions` for error messages. Present the message and
+suggest the correct action:
+- Rejected → Accepted: "Create a new ADR instead"
+- Proposed → Superseded: "Accept or reject first, then use /blueprint:rearchitect"
+- Proposed → Deprecated: "Use /blueprint:transition reject instead"
+
+## Index Management
+
+Every transition updates the README.md index table. Preserve all other content (lifecycle
+diagram, process docs, etc.). Only modify the row for the affected ADR.
+
+## Shorthand Support
+
+Users may say "accept adr 3" without the full `/blueprint:transition accept 3` path. The root
+`/blueprint` skill should route these to this sub-skill.

package/config/lifecycle.toml

@@ -0,0 +1,71 @@
+# ADR Lifecycle State Machine
+# Agents read this instead of hardcoding lifecycle rules in prose.
+
+[statuses.Proposed]
+description = "Decision is drafted and open for discussion. Not yet binding."
+terminal = false
+requires_review = true
+
+[statuses.Accepted]
+description = "Decision has been reviewed, approved, and is in effect."
+terminal = false
+
+[statuses.Rejected]
+description = "Decision was considered but not adopted. Context preserved."
+terminal = true
+
+[statuses.Deferred]
+description = "Decision acknowledged but postponed. Revisit at trigger point."
+terminal = false
+requires_trigger = true
+
+[statuses.Deprecated]
+description = "Decision was once accepted but is no longer relevant."
+terminal = true
+requires_reason = true
+
+[statuses.Superseded]
+description = "Decision has been replaced by a newer ADR."
+terminal = true
+requires_successor = true
+
+# Valid transitions: "From -> To"
+
+[transitions."Proposed -> Accepted"]
+action = "accept"
+requires = ["review_or_explicit_accept"]
+side_effects = ["set_date_decided", "update_index"]
+
+[transitions."Proposed -> Rejected"]
+action = "reject"
+requires = ["rejection_reason"]
+side_effects = ["append_reason_to_consequences", "update_index"]
+
+[transitions."Proposed -> Deferred"]
+action = "defer"
+requires = ["trigger_condition"]
+side_effects = ["add_trigger_to_metadata", "update_index"]
+
+[transitions."Accepted -> Deprecated"]
+action = "deprecate"
+requires = ["deprecation_reason"]
+side_effects = ["add_deprecation_note", "update_index"]
+
+[transitions."Accepted -> Superseded"]
+action = "supersede"
+requires = ["successor_adr_number"]
+side_effects = ["cross_link_adrs", "update_index_both"]
+
+[transitions."Deferred -> Proposed"]
+action = "revisit"
+requires = ["trigger_met"]
+side_effects = ["update_index"]
+
+# Invalid transitions with error messages
+
+[invalid_transitions]
+"Rejected -> Accepted" = "Cannot accept a rejected ADR. Create a new one instead."
+"Proposed -> Superseded" = "Cannot supersede a proposed ADR. Accept or reject it first."
+"Proposed -> Deprecated" = "Cannot deprecate a proposed ADR. Reject it instead."
+"Deprecated -> Accepted" = "Cannot re-accept a deprecated ADR. Create a new one."
+"Superseded -> Accepted" = "Cannot un-supersede an ADR. The successor is the active decision."

package/config/relationships.toml

@@ -0,0 +1,22 @@
+# ADR Relationship Graph
+# Built incrementally by the impact analyzer and lifecycle transitions.
+# Run /adr:impact to rebuild edges for a specific ADR.
+
+# Edge types:
+#   DEPENDS_ON     = "Target ADR assumes this ADR remains valid"
+#   CONFLICTS      = "Target ADR contradicts this ADR"
+#   MODIFIES_SCOPE = "Target ADR changes or narrows scope of this ADR"
+#   SUPERSEDES     = "Target ADR replaces this ADR"
+#   RELATED        = "ADRs are topically related but independent"
+
+# Nodes are added when ADRs are created:
+# [nodes.ADR-0001]
+# title = "Use ADRs for architectural decisions"
+# status = "Accepted"
+
+# Edges are added by impact analyzer:
+# [[edges]]
+# from = "ADR-0003"
+# to = "ADR-0008"
+# type = "DEPENDS_ON"
+# detail = "Code constraint ADR depends on pipeline architecture ADR"

package/config/state.toml

@@ -0,0 +1,21 @@
+# ADR System State
+# Auto-updated by ADR skill commands. Do not edit manually unless resetting state.
+
+adr_directory = ""
+project_root = ""
+
+[last_operations]
+last_audit = ""
+last_evaluation = ""
+last_retro = ""
+last_adr_created = ""
+
+# Append entries as: [[evaluation_history]]
+# date = "2026-03-30"
+# dimensions = ["consistency", "bugs", "maintainability", "testing", "conways"]
+# health_score = "ADEQUATE"
+
+# Append entries as: [[retro_history]]
+# date = "2026-03-30"
+# verdict = "BAND-AID"
+# adr_created = "0009"

package/config/taxonomy.toml

@@ -0,0 +1,118 @@
+# ADR Domain Taxonomy
+# Extensible classification system used by agents. Add categories as the project evolves.
+
+# --- Root Cause Categories (used by /adr:retro) ---
+
+[root_causes.missing_validation]
+label = "Missing Validation"
+description = "Input wasn't checked at a boundary"
+examples = ["No null check on API response", "Missing schema validation on webhook payload"]
+prevention = "Validation layer at system boundaries"
+
+[root_causes.implicit_contract]
+label = "Implicit Contract"
+description = "Two modules depended on undocumented behavior"
+examples = ["Service A assumed Service B always returns arrays", "Module depends on import side effects"]
+prevention = "Explicit interfaces with typed contracts"
+
+[root_causes.state_management]
+label = "State Management"
+description = "Mutable state got out of sync"
+examples = ["Cache held stale config after update", "Race condition between concurrent writes"]
+prevention = "Immutable state or explicit synchronization"
+
+[root_causes.error_swallowing]
+label = "Error Swallowing"
+description = "Error was caught and silently ignored"
+examples = ["catch (e) {} hiding connection failures", "Promise without .catch()"]
+prevention = "Explicit error handling with logging at every catch"
+
+[root_causes.missing_abstraction]
+label = "Missing Abstraction"
+description = "Same logic duplicated, one copy drifted"
+examples = ["Three files parsing dates differently", "Duplicated auth checks with different rules"]
+prevention = "Single source of truth for shared logic"
+
+[root_causes.wrong_abstraction]
+label = "Wrong Abstraction"
+description = "Abstraction doesn't fit the actual use case"
+examples = ["Generic handler that special-cases 80% of inputs", "Base class with one implementation"]
+prevention = "Refactor when abstraction obscures more than it simplifies"
+
+[root_causes.configuration_drift]
+label = "Configuration Drift"
+description = "Environment-specific behavior not captured in code"
+examples = ["Works locally, breaks in prod", "Hardcoded dev URLs in config"]
+prevention = "Environment parity with infrastructure-as-code"
+
+[root_causes.dependency_coupling]
+label = "Dependency Coupling"
+description = "Change in dependency broke assumptions"
+examples = ["Library update changed default behavior", "Transitive dependency conflict"]
+prevention = "Pin versions, wrap external dependencies, test upgrades"
+
+[root_causes.missing_test]
+label = "Missing Test"
+description = "No test existed for this scenario"
+examples = ["Happy path tested, error path not", "No regression test after previous fix"]
+prevention = "Anti-pattern tests and boundary testing"
+
+[root_causes.architectural_gap]
+label = "Architectural Gap"
+description = "System structure makes this bug class inevitable"
+examples = ["No validation layer between external data and business logic", "No circuit breaker on external calls"]
+prevention = "ADR to address the structural gap"
+
+# --- Evaluation Dimensions (used by /adr:evaluate) ---
+
+[eval_dimensions.consistency]
+label = "Structural Consistency"
+agent = "adr-consistency-auditor"
+aspects = ["naming", "module_structure", "dependency_direction", "error_handling", "api_patterns", "configuration"]
+
+[eval_dimensions.bugs]
+label = "Bug Surface"
+agent = "adr-bug-surface-mapper"
+aspects = ["complexity_hotspots", "coupling", "boundary_integrity", "state_management", "implicit_contracts"]
+
+[eval_dimensions.maintainability]
+label = "Maintainability"
+agent = "adr-maintainability-assessor"
+aspects = ["dependency_health", "abstraction_quality", "change_amplification", "cognitive_complexity", "documentation", "technical_debt"]
+
+[eval_dimensions.testing]
+label = "Testing Strategy"
+agent = "adr-testing-strategy-evaluator"
+aspects = ["pyramid_health", "risk_coverage", "antipattern_tests", "test_quality", "test_architecture"]
+
+[eval_dimensions.conways]
+label = "Conway's Law Alignment"
+agent = "adr-conways-law-analyzer"
+aspects = ["ownership_alignment", "friction_points", "orphaned_modules", "bottlenecks", "scaling_readiness"]
+
+# --- Decision Categories ---
+
+decision_categories = [
+  "Technology Choice",
+  "Architecture Pattern",
+  "Data Model",
+  "API Design",
+  "Deployment Strategy",
+  "Authentication / Authorization",
+  "Integration Strategy",
+  "Performance / Scaling",
+  "Security / Compliance",
+  "Testing Strategy",
+  "Process / Workflow",
+]
+
+# --- Severity Levels ---
+
+[severity.High]
+description = "Core architectural constraint. Affects multiple components, expensive to reverse."
+
+[severity.Medium]
+description = "Significant technical decision. Affects one subsystem, moderately reversible."
+
+[severity.Low]
+description = "Local decision. Affects one module, easily reversed."

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "claude-blueprint",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Architecture Decision Records with teeth — lifecycle management, devil's advocate review, architecture evaluation team, post-fix retrospectives, and compliance auditing for Claude Code.",
+  "bin": {
+    "blueprint": "./bin/cli.js",
+    "claude-blueprint": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    ".claude-plugin/",
+    "commands/",
+    "agents/",
+    "config/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "commander": "^13.0.0",
+    "ora": "^8.0.0"
+  }
+}