claude-blueprint 1.0.0

package/commands/guard.md

@@ -0,0 +1,102 @@
+---
+name: blueprint:guard
+description: >
+  Pre-commit architecture guard — checks if staged changes violate any accepted ADR invariant
+  before committing. Fast, targeted check on just the files being changed. Use when: "guard
+  this commit", "check before commit", "architecture guard", "pre-commit check", or configure
+  as an automatic pre-commit hook.
+---
+
+# Pre-Commit Architecture Guard
+
+Fast, targeted invariant check on staged files. Not a full audit — just "do these specific
+changes violate any accepted ADR?"
+
+Catches violations at the point of creation, not after the fact.
+
+## Shared Context
+
+Read from parent `blueprint/` skill directory:
+- `config/state.toml` — ADR directory
+- `config/lifecycle.toml` — to identify accepted statuses
+
+## Process
+
+### Step 1: Identify Staged Changes
+
+```bash
+git diff --cached --name-only
+git diff --cached --stat
+```
+
+If nothing is staged, check unstaged changes instead and note the difference.
+
+### Step 2: Map Changes to ADRs
+
+For each changed file, determine which ADRs govern it:
+
+- Read all accepted ADRs
+- Match changed file paths against ADR scopes:
+  - ADR about database → governs files in `models/`, `repositories/`, `migrations/`
+  - ADR about API design → governs files in `api/`, `routes/`, `handlers/`
+  - ADR about testing → governs files in `tests/`
+  - ADR about architecture patterns → governs files matching the pattern's scope
+
+If no ADRs govern the changed files, report "No architectural constraints apply to
+these changes" and exit.
+
+### Step 3: Fast Invariant Check
+
+For each relevant ADR, check the diff (not the whole codebase) for violations:
+
+- **Dependency direction:** Does the diff add an import that violates the rule?
+- **Technology constraint:** Does the diff introduce a forbidden technology?
+- **Pattern enforcement:** Does the diff bypass a required pattern?
+- **Naming convention:** Does the diff introduce inconsistent naming?
+
+Read only the diff, not the entire file. This must be fast — under 10 seconds
+for a typical commit.
+
+### Step 4: Report
+
+**No violations:**
+```
+✓ Guard passed — [N] ADRs checked against [M] changed files
+```
+
+**Violations found:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► GUARD: VIOLATIONS FOUND
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| File | ADR | Violation |
+|------|-----|-----------|
+| [file] | ADR-NNNN | [what the diff does wrong] |
+
+Fix these before committing, or run /blueprint:new to formally
+change the decision if the violation is intentional.
+```
+
+## Hook Integration
+
+To run automatically before every commit, suggest the user add a hook:
+
+```bash
+# .git/hooks/pre-commit or via settings.json hook
+claude -p "Run /blueprint:guard on the currently staged changes"
+```
+
+Or via Claude Code settings.json:
+```json
+{
+  "hooks": {
+    "PreCommit": [{
+      "type": "command",
+      "command": "claude -p 'blueprint:guard'"
+    }]
+  }
+}
+```
+
+Note: This is a suggestion, not automatic. The user decides whether to enable it.

package/commands/health.md

@@ -0,0 +1,139 @@
+---
+name: blueprint:health
+description: >
+  Self-diagnostic for the blueprint ADR system. Checks internal consistency: broken
+  supersession chains, index sync, orphaned references, missing relationship edges,
+  stale config, template drift. Use when: "blueprint health", "check adr health",
+  "validate adrs", "is the adr system consistent?", "health check", or when things
+  seem off.
+---
+
+# Blueprint Health Check
+
+Validates the ADR system's internal consistency and offers to repair issues found.
+Think of it as fsck for your architecture decisions.
+
+## Shared Context
+
+Read from parent `blueprint/` skill directory:
+- `config/state.toml` — cached paths
+- `config/lifecycle.toml` — valid statuses
+- `config/relationships.toml` — graph to validate
+
+## Process
+
+### Step 1: Run All Checks
+
+Execute these checks in order, collecting findings:
+
+**1. ADR Directory Structure**
+- [ ] ADR directory exists at detected path
+- [ ] `template.md` exists
+- [ ] `README.md` exists with index table
+- [ ] File naming follows `NNNN-kebab-case.md` pattern
+- [ ] Sequence numbers are contiguous (no gaps, no duplicates)
+
+**2. Index Sync**
+- [ ] Every ADR file has a corresponding row in README.md index
+- [ ] Every index row points to an existing file
+- [ ] Status in index matches status in the ADR file
+- [ ] Dates in index match dates in the ADR file
+- [ ] Index is sorted by ADR number
+
+**3. ADR Content Validity**
+- [ ] Every ADR has the required Metadata table (Status, Date proposed)
+- [ ] Status is a valid value from `lifecycle.toml`
+- [ ] Every ADR has Context, Options Considered, Decision, Consequences sections
+- [ ] At least 2 options were considered (not just the chosen one)
+- [ ] Consequences has both Positive and Negative subsections
+
+**4. Supersession Chain Integrity**
+- [ ] Every "Superseded by ADR-NNNN" points to a real ADR
+- [ ] The target ADR has "Supersedes ADR-MMMM" pointing back (bidirectional)
+- [ ] No circular supersession chains
+- [ ] Superseded ADRs have status "Superseded"
+- [ ] Superseding ADRs have status "Accepted" or "Proposed"
+
+**5. Relationship Graph Consistency**
+- [ ] Every node in `relationships.toml` corresponds to a real ADR file
+- [ ] Every edge references existing nodes
+- [ ] No duplicate edges
+- [ ] Edge types are valid (from the edge_types definition)
+- [ ] No self-referencing edges
+
+**6. Config Freshness**
+- [ ] `state.toml` adr_directory matches actual location
+- [ ] `state.toml` timestamps are plausible (not in the future)
+- [ ] `relationships.toml` has nodes for all existing ADRs
+- [ ] `lifecycle.toml` statuses cover all statuses used in ADRs
+- [ ] `taxonomy.toml` categories cover all categories used in ADRs
+
+**7. Cross-Reference Integrity**
+- [ ] ADRs that reference other ADRs (e.g., "see ADR-0003") point to real ADRs
+- [ ] Referenced ADRs are not Rejected (referencing rejected decisions is suspicious)
+- [ ] `docs/ARCHITECTURE.md` ADR references (if file exists) point to real ADRs
+
+**8. Staleness Detection**
+- [ ] No accepted ADR is older than 12 months without a review (flag as "consider revisiting")
+- [ ] `docs/ARCHITECTURE.md` last updated within 6 months (if it exists)
+- [ ] Deferred ADRs older than 6 months flagged as "may be forgotten"
+
+### Step 2: Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► HEALTH CHECK
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Results
+
+  | Check                    | Status | Issues |
+  |--------------------------|--------|--------|
+  | Directory structure      | ✓      | 0      |
+  | Index sync               | ⚠      | 2      |
+  | ADR content validity     | ✓      | 0      |
+  | Supersession chains      | ✓      | 0      |
+  | Relationship graph       | ⚠      | 3      |
+  | Config freshness         | ✓      | 0      |
+  | Cross-references         | ✓      | 0      |
+  | Staleness                | ⚠      | 1      |
+
+  Overall: 5 issues found (0 critical, 3 warnings, 2 info)
+
+## Issues
+
+  ⚠ INDEX-001: ADR-0029 status in index (Accepted) doesn't match
+    file (Proposed). Fix: update index row.
+
+  ⚠ INDEX-002: ADR-0031 missing from README.md index.
+    Fix: add index row.
+
+  ⚠ GRAPH-001: 12 ADRs have no nodes in relationships.toml.
+    Fix: run /blueprint:impact on each to populate.
+
+  ⚠ GRAPH-002: Edge ADR-0003 → ADR-0008 exists but reverse not declared.
+    Fix: add bidirectional edge.
+
+  ⚠ GRAPH-003: Node ADR-0099 in graph but no file exists.
+    Fix: remove orphaned node.
+
+  ℹ STALE-001: ADR-0001 accepted 8 months ago, never reviewed.
+    Suggestion: revisit or confirm still valid.
+```
+
+### Step 3: Offer Repair
+
+For each fixable issue, offer to repair automatically:
+
+- Index sync issues → update README.md index
+- Missing graph nodes → add nodes for all existing ADRs
+- Orphaned graph nodes → remove nodes with no file
+- Status mismatches → update index to match file (file is authoritative)
+- Missing bidirectional edges → add the missing direction
+
+Ask: "Fix [N] repairable issues?" (Yes / No / Let me pick)
+
+### Step 4: Commit Repairs
+
+If repairs were made:
+`docs: repair ADR system health — [N] issues fixed`

package/commands/help.md

@@ -0,0 +1,119 @@
+---
+name: blueprint:help
+description: >
+  Show the full ADR command reference with contextual suggestions based on current ADR state
+  and conversation history. Use when: "adr help", "what adr commands are there?", "what can I
+  do with adrs?", "help with adrs".
+---
+
+# ADR Help
+
+Display the full command reference with context-aware next-action suggestions.
+
+## Process
+
+### Step 1: Detect Current State
+
+1. Read `config/state.toml` from the parent `adr/` directory for ADR directory location
+2. If no directory cached, detect: `docs/adr/` → `docs/decisions/` → `adr/` → `decisions/`
+3. Glob for all ADR files (`[0-9][0-9][0-9][0-9]-*.md`)
+4. Extract status from each ADR (count Proposed, Accepted, Rejected, Deferred, Deprecated, Superseded)
+5. Read `config/state.toml` for last audit/evaluation/retro dates
+6. Scan recent conversation history for architectural topics being discussed
+7. Check if application code exists (glob for source files beyond wireframes/docs)
+
+### Step 2: Display Command Reference
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ ADR ► COMMAND REFERENCE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Lifecycle
+
+  /blueprint:new "topic"              Create a new ADR from interview
+  /blueprint:new --research "topic"   Research options first, then create ADR
+  /blueprint:list                     List all ADRs with status + suggestions
+  /blueprint:review N                 Challenge + review a Proposed ADR
+  /blueprint:transition accept N      Accept an ADR (no challenge)
+  /blueprint:transition reject N      Reject a Proposed ADR
+  /blueprint:transition defer N       Defer a Proposed ADR
+  /blueprint:transition deprecate N   Deprecate an Accepted ADR
+  /blueprint:search "term"            Find ADRs about a topic
+
+## Analysis
+
+  /blueprint:impact N                 Check ADR for conflicts with other decisions
+  /blueprint:audit                    Verify codebase follows accepted ADRs
+  /blueprint:retro                    Post-fix retrospective — band-aid or systemic?
+  /blueprint:rearchitect "topic"      Research + replace an existing decision
+
+## Architecture Evaluation Team
+
+  /blueprint:evaluate                 Run all 5 evaluators in parallel
+  /blueprint:evaluate consistency     Pattern adherence, naming, layering, deps
+  /blueprint:evaluate bugs            Complexity hotspots, coupling, boundaries
+  /blueprint:evaluate maintainability Dependency health, abstractions, tech debt
+  /blueprint:evaluate testing         Test pyramid, anti-pattern tests, coverage
+  /blueprint:evaluate conways         Team-architecture alignment, ownership
+
+## Setup
+
+  /blueprint:init                    Bootstrap blueprint onto existing codebase
+
+## Documentation
+
+  /blueprint:architect                Generate/update ARCHITECTURE.md (matklad style)
+  /blueprint:eli5                     Explain an ADR or the whole landscape in plain English
+  /blueprint:eli5 N                   Explain a single ADR — no jargon, all analogies
+
+## Continuous Governance
+
+  /blueprint:fitness                   Generate CI-runnable architecture tests from ADRs
+  /blueprint:drift                     Detect gradual architecture erosion over time
+  /blueprint:debt                      Track deferred decisions and overdue triggers
+  /blueprint:guard                     Pre-commit check against ADR invariants
+
+## Reporting
+
+  /blueprint:digest                    Non-technical stakeholder summary (1-page)
+  /blueprint:timeline                  Narrative evolution of architectural decisions
+
+## System
+
+  /blueprint:status                    Governance dashboard + knowledge graph (browser)
+  /blueprint:health                    Self-diagnostic — check ADR system consistency
+  /blueprint:hooks                     Configure automatic blueprint triggers
+  /blueprint:hooks install all         Enable all automation hooks
+
+## Meta
+
+  /blueprint:help                     This reference + contextual suggestions
+```
+
+### Step 3: Display Contextual Suggestions
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ ▶ SUGGESTED NEXT ACTIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Apply these rules in order (show up to 3 suggestions):
+
+1. **Proposed ADRs exist:** "You have [N] Proposed ADR(s) awaiting review: [titles]. Run `/blueprint:review [N]` to challenge and decide."
+2. **Conversation discussed an architectural topic without an ADR:** "This conversation discussed [topic] — consider `/blueprint:new \"[topic]\"` to document the decision."
+3. **Application code exists, no recent audit:** "You have [N] accepted ADRs and application code. Run `/blueprint:audit` to check compliance."
+4. **Application code exists, no recent evaluation:** "Run `/blueprint:evaluate` for a full architecture health check."
+5. **Recent fix committed:** "Recent changes detected. Run `/blueprint:retro` to check if they warrant an ADR."
+6. **No ADRs exist:** "No ADRs found. Run `/blueprint:new \"[topic]\"` to create your first decision record."
+7. **All ADRs Accepted, no action needed:** "All [N] ADRs are Accepted. No pending actions."
+
+### Step 4: Show ADR Summary Stats
+
+```
+ADRs: [total] total | [N] Accepted | [N] Proposed | [N] other
+Last audit: [date or "never"]
+Last evaluation: [date or "never"]
+Last retro: [date or "never"]
+```

package/commands/hooks.md

@@ -0,0 +1,131 @@
+---
+name: blueprint:hooks
+description: >
+  Configure automatic blueprint triggers via Claude Code hooks. Install, list, or remove
+  hooks that fire blueprint commands automatically at the right moments. Use when: "set up
+  blueprint hooks", "install hooks", "auto-retro after fixes", "auto-guard on commits",
+  "blueprint hooks", "configure automation", "what hooks are available?".
+---
+
+# Blueprint Hooks
+
+Configure automatic triggers that embed blueprint into the development workflow.
+Without hooks, blueprint is a tool you remember to use. With hooks, it speaks up on its own.
+
+## Available Hooks
+
+| Hook | Trigger | What it does | Default |
+|------|---------|-------------|---------|
+| **guard** | Pre-commit | Run `/blueprint:guard` on staged files | Off |
+| **retro-suggest** | After fix workflows | Suggest `/blueprint:retro` | On |
+| **architecture-sync** | After ADR transition | Suggest updating ARCHITECTURE.md + fitness functions | On |
+| **dependency-watch** | package.json/requirements.txt change | Suggest `/blueprint:new` for tech choice | On |
+| **periodic-health** | Every 20 sessions | Suggest `/blueprint:health` + `/blueprint:debt` | On |
+
+## Process
+
+### `/blueprint:hooks` (no args) — List Current Hooks
+
+Read Claude Code settings.json and check for blueprint hook entries:
+
+```bash
+cat ~/.claude/settings.json 2>/dev/null | grep -A5 "blueprint"
+```
+
+Display current hook status:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► HOOKS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  | Hook              | Status    | Trigger |
+  |-------------------|-----------|---------|
+  | guard             | ✗ Off     | Pre-commit |
+  | retro-suggest     | ✓ On      | After fix workflows |
+  | architecture-sync | ✓ On      | After ADR transition |
+  | dependency-watch  | ✓ On      | Dependency file change |
+  | periodic-health   | ✓ On      | Every 20 sessions |
+
+  /blueprint:hooks install guard     — enable pre-commit guard
+  /blueprint:hooks remove guard      — disable pre-commit guard
+  /blueprint:hooks install all       — enable all hooks
+```
+
+### `/blueprint:hooks install <hook>` — Install a Hook
+
+Use the `update-config` skill to add the hook to Claude Code settings.json.
+
+**guard hook** — adds a PreToolUse hook that runs before Bash git commit:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "if echo \"$INPUT\" | grep -q 'git commit'; then echo 'Run /blueprint:guard first'; fi"
+      }]
+    }]
+  }
+}
+```
+
+**retro-suggest hook** — adds a PostToolUse notification after fix-related tool calls:
+
+The retro-suggest hook doesn't block — it adds a note after fix workflows suggesting
+`/blueprint:retro`. This is implemented as a behavioral instruction in the project's
+CLAUDE.md rather than a settings.json hook:
+
+```markdown
+<!-- BEGIN blueprint-hooks -->
+## Blueprint Automation
+
+After completing any fix workflow (gsd:quick, rapid:quick, rapid:bug-fix, or manual
+bug fix commits), suggest: "Fix is in. Run `/blueprint:retro` to check if it warrants
+an ADR?"
+
+After any ADR lifecycle transition (accept, reject, deprecate, supersede), suggest:
+"ADR updated. Consider `/blueprint:architect` to refresh ARCHITECTURE.md and
+`/blueprint:fitness` to update architecture tests."
+
+When package.json, requirements.txt, pyproject.toml, go.mod, or Cargo.toml is modified,
+check if the change introduces a new major dependency. If so, suggest:
+"New dependency detected. Consider `/blueprint:new` to document this technology choice."
+<!-- END blueprint-hooks -->
+```
+
+**architecture-sync hook** — same CLAUDE.md section as above.
+
+**dependency-watch hook** — same CLAUDE.md section as above.
+
+**periodic-health hook** — adds a session counter note to state.toml:
+
+```toml
+[hooks]
+sessions_since_health = 0
+health_interval = 20
+```
+
+The help and status commands check this counter and suggest `/blueprint:health` when
+it exceeds the interval.
+
+### `/blueprint:hooks remove <hook>` — Remove a Hook
+
+Reverse the installation: remove the relevant section from settings.json or CLAUDE.md.
+
+### `/blueprint:hooks install all` — Install All Hooks
+
+Install all 5 hooks in one go. Present the configuration and ask for confirmation
+before writing.
+
+## Implementation Notes
+
+Blueprint hooks are intentionally lightweight — they suggest, they don't block (except
+guard, which is opt-in). The goal is to make architectural governance a natural part of
+the workflow, not a gate that slows development.
+
+Hooks that go into CLAUDE.md use the same fenced-section pattern as the main blueprint
+installer (<!-- BEGIN --> / <!-- END -->). They're updated by re-running the hooks
+command, never manually edited.

package/commands/impact.md

@@ -0,0 +1,38 @@
+---
+name: blueprint:impact
+description: >
+  Analyze an ADR's impact on other decisions and the codebase. Detects conflicts, dependencies,
+  and affected components. Use when: "impact of adr N", "check adr N for conflicts", "does this
+  conflict with anything?", "adr impact N".
+---
+
+# ADR Impact Analysis
+
+Cross-references a target ADR against all accepted ADRs and the codebase to detect conflicts,
+dependencies, and affected areas.
+
+## Shared Context
+
+Read from parent `adr/` directory:
+- `config/state.toml` — ADR directory location
+- `config/relationships.toml` — existing relationship graph
+- `agents/persona.md` — personality
+- `agents/adr-impact-analyzer.md` — agent instructions
+
+## Process
+
+1. Read the target ADR (user specifies by number)
+2. Read `agents/adr-impact-analyzer.md` and `agents/persona.md`
+3. Spawn `general-purpose` agent with:
+   - Full text of the target ADR
+   - ADR file path and directory path
+   - List of all ADR filenames
+   - Current relationship graph from `config/relationships.toml`
+   - Full agent instructions + persona
+4. Present the impact report
+5. **Update `config/relationships.toml`** with discovered edges (DEPENDS_ON, CONFLICTS, etc.)
+6. If conflicts found, suggest:
+   - Resolve conflicts first
+   - Revise the target ADR
+   - Accept the tension with documentation
+   - Run `/blueprint:rearchitect` to supersede a conflicting decision