claude-blueprint 2.0.0 → 2.0.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "blueprint",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Architecture Decision Records with teeth — 39 commands, 21 agents, 15 architecture paradigms. DDD bounded contexts, DCAR forces evaluation, reflexion model conformance, epistemic status tracking, Wardley strategic analysis, C4 diagrams, ATAM tradeoff analysis, risk heat maps, cross-repo federation, and configurable governance tiers. All with a cranky senior engineer persona.",
   "author": {
     "name": "pragnition"
@@ -8,6 +8,7 @@
   "homepage": "https://github.com/pragnition/blueprint",
   "repository": "https://github.com/pragnition/blueprint",
   "license": "MIT",
+  "hooks": "./hooks/hooks.json",
   "keywords": [
     "adr",
     "architecture",

package/README.md

@@ -357,13 +357,13 @@ npm link
 claude-blueprint install --global
 ```
 
-The installer deploys 39 commands, 21 agents, and 8 config files to `~/.claude/commands/blueprint/`, and inserts a managed section into `CLAUDE.md` with the command reference.
+The installer deploys 39 skills, 21 agents, and 8 config files to `~/.claude/commands/blueprint/`, and inserts a managed section into `CLAUDE.md` with the command reference.
 
 ## Architecture of Blueprint Itself
 
 ```
 blueprint/
-├── commands/              39 skill files
+├── skills/                39 skill files
 │   ├── blueprint.md       Thin router
 │   ├── init.md            Bootstrap from existing codebase
 │   ├── help.md            Contextual command reference

package/agents/adr-architect-cartographer.md

@@ -3,6 +3,7 @@ name: adr-architect-cartographer
 description: Generates and maintains ARCHITECTURE.md — a bird's-eye map of the codebase following matklad's philosophy. Produces codemap, invariants, cross-cutting concerns, and layer boundaries. References ADRs as the canonical source for why things are the way they are.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: white
 ---
 

package/agents/adr-bug-surface-mapper.md

@@ -3,6 +3,7 @@ name: adr-bug-surface-mapper
 description: Maps the architectural bug surface — identifies where bugs are structurally likely to emerge based on complexity, coupling, missing boundaries, and state management. Does NOT hunt for specific bugs.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: orange
 ---
 

package/agents/adr-compliance-auditor.md

@@ -3,6 +3,7 @@ name: adr-compliance-auditor
 description: Audits the codebase against accepted ADRs to verify decisions are being followed. Detects violations, drift, and non-compliance with evidence.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: blue
 ---
 

package/agents/adr-consistency-auditor.md

@@ -3,6 +3,7 @@ name: adr-consistency-auditor
 description: Evaluates structural consistency across a codebase — pattern adherence, layering discipline, naming conventions, dependency direction, and error handling uniformity.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: green
 ---
 

package/agents/adr-context-mapper.md

@@ -3,6 +3,7 @@ name: adr-context-mapper
 description: Analyzes codebase to infer bounded contexts from module structure, package boundaries, naming patterns, and git ownership. Maps ADRs to contexts and generates context maps showing inter-context relationships.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: green
 ---
 

package/agents/adr-conways-law-analyzer.md

@@ -3,6 +3,7 @@ name: adr-conways-law-analyzer
 description: Analyzes alignment between system architecture and team/organizational structure (Conway's Law). Identifies where module boundaries, ownership, and communication overhead create friction or enable velocity.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: teal
 ---
 

package/agents/adr-devils-advocate.md

@@ -3,6 +3,7 @@ name: adr-devils-advocate
 description: Critically challenges a proposed ADR before acceptance. Identifies unconsidered alternatives, hidden risks, faulty assumptions, and missing consequences. Produces a challenge report.
 tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
 model: inherit
+skills: ["persona"]
 color: red
 ---
 

package/agents/adr-diagram-generator.md

@@ -3,6 +3,7 @@ name: adr-diagram-generator
 description: Generates C4 Model diagrams (System Context, Container, Component) from accepted ADRs and the relationship graph. Outputs Mermaid, Structurizr DSL, or PlantUML.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: cyan
 ---
 

package/agents/adr-evidence-auditor.md

@@ -3,6 +3,7 @@ name: adr-evidence-auditor
 description: Audits the epistemic status and temporal validity of evidence supporting accepted ADRs. Detects stale evidence, unverified AI-generated research, and decisions whose supporting context has changed.
 tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
 model: inherit
+skills: ["persona"]
 color: magenta
 ---
 

package/agents/adr-federation-indexer.md

@@ -3,6 +3,7 @@ name: adr-federation-indexer
 description: Aggregates ADRs across multiple repositories into a unified index. Detects cross-repo conflicts, duplicates, and missing cross-references. Addresses the top practitioner criticism of repo-scoped ADRs.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: green
 ---
 

package/agents/adr-forces-evaluator.md

@@ -3,6 +3,7 @@ name: adr-forces-evaluator
 description: Evaluates an ADR using DCAR's structured forces template — systematically weighs arguments for and against a decision, generates force-balance reports, and scores decisions as confirmed or needs-re-evaluation.
 tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
 model: inherit
+skills: ["persona"]
 color: yellow
 ---
 

package/agents/adr-impact-analyzer.md

@@ -3,6 +3,7 @@ name: adr-impact-analyzer
 description: Analyzes a new or existing ADR against all other accepted ADRs and the codebase. Detects conflicts, duplicates, dependencies, and affected components.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: yellow
 ---
 

package/agents/adr-maintainability-assessor.md

@@ -3,6 +3,7 @@ name: adr-maintainability-assessor
 description: Evaluates long-term maintainability — dependency health, abstraction quality, change amplification, cognitive complexity, and technical debt indicators.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: purple
 ---
 

package/agents/adr-reflexion-analyzer.md

@@ -3,6 +3,7 @@ name: adr-reflexion-analyzer
 description: Computes reflexion models by comparing the intended architecture (from accepted ADRs + ARCHITECTURE.md) against actual source code structure. Reports convergences, divergences, and absences for rigorous drift detection.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: red
 ---
 

package/agents/adr-researcher.md

@@ -3,6 +3,7 @@ name: adr-researcher
 description: Researches technology options, alternatives, and trade-offs for a proposed architectural decision. Produces a structured research brief consumed by the ADR drafting flow.
 tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
 model: inherit
+skills: ["persona"]
 color: cyan
 ---
 

package/agents/adr-retrospective.md

@@ -3,6 +3,7 @@ name: adr-retrospective
 description: Post-fix retrospective agent that evaluates recent changes for band-aid vs systemic fixes, identifies root cause classes, and proposes ADRs for architectural improvements worth formalizing.
 tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
 model: inherit
+skills: ["persona"]
 color: amber
 ---
 

package/agents/adr-risk-mapper.md

@@ -3,6 +3,7 @@ name: adr-risk-mapper
 description: Generates automated risk heat maps by analyzing ADR coverage gaps, component complexity, git churn, coupling density, and missing governance. Identifies architectural risk concentrations.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: red
 ---
 

package/agents/adr-strategic-analyzer.md

@@ -3,6 +3,7 @@ name: adr-strategic-analyzer
 description: Analyzes ADRs against Wardley Map evolution stages to detect strategic misalignment — building custom solutions for commodity problems, or using commodity tools for genesis-stage differentiators.
 tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
 model: inherit
+skills: ["persona"]
 color: blue
 ---
 

package/agents/adr-testing-strategy-evaluator.md

@@ -3,6 +3,7 @@ name: adr-testing-strategy-evaluator
 description: Evaluates testing strategy completeness — coverage architecture, anti-pattern tests, testing pyramid health, test quality, and alignment between test structure and system risk areas.
 tools: Read, Grep, Glob, Bash
 model: inherit
+skills: ["persona"]
 color: magenta
 ---
 

package/agents/adr-tradeoff-analyzer.md

@@ -3,6 +3,7 @@ name: adr-tradeoff-analyzer
 description: Generates ATAM-style quality attribute utility trees from accepted ADRs. Identifies sensitivity points, tradeoff points, risks, and non-risks across the decision landscape.
 tools: Read, Grep, Glob, Bash, WebSearch
 model: inherit
+skills: ["persona"]
 color: yellow
 ---
 

package/config/taxonomy.toml

@@ -165,6 +165,15 @@ L0 = "Unverified — AI-generated, unsourced, or unconfirmed"
 L1 = "Logically Consistent — sourced, sound reasoning, not project-tested"
 L2 = "Empirically Validated — tested and confirmed in this project"
 
+# --- Decision Debt Scoring ---
+# Single source of truth for debt calculation. Used by /blueprint:debt and /blueprint:status.
+
+[debt_scoring]
+formula = "severity_weight × age_months × dependency_count"
+severity_weights = { High = 3, Medium = 2, Low = 1 }
+thresholds = { nominal = 10, elevated = 25, critical = 50 }
+evidence_debt_multiplier = 1.5   # Expired evidence scores 1.5x vs deferred decisions
+
 # --- Decision Categories ---
 
 decision_categories = [

package/hooks/hooks.json

@@ -0,0 +1,58 @@
+{
+  "description": "Blueprint architecture governance hooks. Pre-commit guard is opt-in (disabled by default). All others suggest actions without blocking.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Check if this file change violates any accepted ADR invariant. If it does, warn the user with the specific ADR reference. If no ADRs exist or no violation is detected, approve silently.",
+            "timeout": 10
+          }
+        ],
+        "disabled": true,
+        "_comment": "Pre-commit architecture guard (ADR-0026). Enable with /blueprint:hooks install guard"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "If the command output indicates a bug fix was just applied (commit message contains 'fix', 'bugfix', 'hotfix', or 'patch'), suggest: 'Run /blueprint:retro to check if this fix warrants an ADR.' Do not block — just suggest.",
+            "timeout": 5
+          }
+        ],
+        "_comment": "Retro-suggest after fix workflows (ADR-0034)"
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "If an ADR was just accepted, rejected, or transitioned during this session, suggest: 'Run /blueprint:architect to update ARCHITECTURE.md and /blueprint:fitness to regenerate fitness functions.' Do not block.",
+            "timeout": 5
+          }
+        ],
+        "_comment": "Architecture-sync after ADR transitions (ADR-0034)"
+      }
+    ],
+    "FileChanged": [
+      {
+        "matcher": "package\\.json|requirements\\.txt|pyproject\\.toml|Cargo\\.toml|go\\.mod",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "A dependency manifest was modified. If a new dependency was added, suggest: 'Consider /blueprint:new to document this technology choice as an ADR.' Do not block.",
+            "timeout": 5
+          }
+        ],
+        "_comment": "Dependency-watch on package changes (ADR-0034)"
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-blueprint",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "type": "module",
   "description": "Architecture Decision Records with teeth — lifecycle management, 15 architecture paradigms, DDD context scoping, DCAR forces evaluation, reflexion models, Wardley mapping, C4 diagrams, ATAM tradeoff analysis, and 19 specialized agents for Claude Code.",
   "bin": {
@@ -11,7 +11,8 @@
     "bin/",
     "src/",
     ".claude-plugin/",
-    "commands/",
+    "skills/",
+    "hooks/",
     "agents/",
     "config/"
   ],

package/{commands → skills}/debt.md

@@ -58,9 +58,10 @@ For each deferred decision, check if the trigger condition has been met:
 
 ### Step 3: Calculate Decision Debt Score
 
-```
-Decision Debt = Σ (severity × age_months × dependency_count)
-```
+Read the formula and weights from `config/taxonomy.toml` `[debt_scoring]` section.
+Default formula: `severity_weight × age_months × dependency_count`
+Severity weights: High=3, Medium=2, Low=1
+Thresholds: nominal < 10, elevated < 25, critical ≥ 50
 
 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

package/skills/persona/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: persona
+description: Senior Engineer Persona — shared personality for all Blueprint agents
+user-invocable: false
+disable-model-invocation: true
+---
+
+# Senior Engineer Persona
+
+You are a senior engineer with 20 years of production experience and zero patience for
+sloppiness. You've been paged at 3 AM because someone thought "it's fine, we'll fix it
+later." You've watched "temporary" workarounds survive three team turnovers. You've debugged
+race conditions caused by developers who thought shared mutable state was "simpler."
+
+You are not mean. You are direct. There is a difference.
+
+**Your principles:**
+
+- Say what you mean. "Consider using const" is weak. "This should be const — it's never
+  reassigned, and let signals mutation intent you don't have" is clear.
+- Small things matter because they compound. One inconsistent naming convention is a style
+  choice. Fifty is a codebase that nobody can navigate.
+- "It works" is not a quality bar. Code that works but violates conventions, has no error
+  handling, or is untested is a landmine with a longer fuse.
+- Be specific with criticism. "This is messy" is unhelpful. "This function is 80 lines with
+  6 levels of nesting — extract the validation logic" is actionable.
+- Credit good work when you see it. Not everything is broken. When the architecture is solid,
+  say so — briefly, then move on to what isn't.
+
+**Your tone:**
+
+- Blunt but not cruel. You respect the developer, not the code.
+- Opinionated with receipts. Strong opinions backed by evidence, not vibes.
+- Zero hedging. Not "you might want to consider..." but "do this, here's why."
+- Petty about the right things. Naming matters. Consistency matters. Error handling matters.
+  Whitespace doesn't.
+- Dry humor is fine. Sarcasm directed at patterns, never at people.
+
+**Apply this persona to your functional role.** You are still doing your specific job
+(researching, reviewing, auditing, analyzing) — the persona shapes HOW you communicate
+findings, not WHAT you look for. Your structured output format stays the same. Your verdicts
+and recommendations stay evidence-based. But your prose should read like it was written by
+someone who has strong opinions because they've earned them the hard way.

package/{commands → skills}/status.md

@@ -69,8 +69,8 @@ Read from parent `blueprint/` skill directory:
 
 **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)
+- For each, check trigger conditions against codebase (delegate to `/blueprint:debt` logic)
+- Read debt score formula from `config/taxonomy.toml` `[debt_scoring]` section
 - Flag any with triggered conditions
 
 **Operations recency:**

package/src/install.js

@@ -45,20 +45,20 @@ export async function install(opts) {
   // Copy root command (router)
   spinner.start('Installing router...');
   await copyFile(
-    join(PLUGIN_ROOT, 'commands', 'blueprint.md'),
+    join(PLUGIN_ROOT, 'skills', 'blueprint.md'),
     join(paths.commands, 'SKILL.md'),
   );
   spinner.succeed('Router installed');
 
-  // Copy sub-commands as SKILL.md in their directories
-  spinner.start('Installing commands...');
+  // Copy sub-skills as SKILL.md in their directories
+  spinner.start('Installing skills...');
   for (const cmd of SUB_COMMANDS) {
     await copyFile(
-      join(PLUGIN_ROOT, 'commands', `${cmd}.md`),
+      join(PLUGIN_ROOT, 'skills', `${cmd}.md`),
       join(paths.commands, cmd, 'SKILL.md'),
     );
   }
-  spinner.succeed(`${SUB_COMMANDS.length} commands installed`);
+  spinner.succeed(`${SUB_COMMANDS.length} skills installed`);
 
   // Copy agents
   spinner.start('Installing agents...');

package/src/verify.js

@@ -2,9 +2,9 @@ import { access } from 'fs/promises';
 import { join } from 'path';
 import { getTargetPaths } from './paths.js';
 
-const EXPECTED_COMMANDS = [
+const EXPECTED_SKILLS = [
   'SKILL.md',
-  // v1 commands
+  // v1 skills
   'help/SKILL.md',
   'list/SKILL.md',
   'new/SKILL.md',
@@ -28,7 +28,7 @@ const EXPECTED_COMMANDS = [
   'status/SKILL.md',
   'health/SKILL.md',
   'hooks/SKILL.md',
-  // v2 commands
+  // v2 skills
   'scope/SKILL.md',
   'challenge/SKILL.md',
   'reflect/SKILL.md',
@@ -111,8 +111,8 @@ export async function verify(opts) {
 
     let missing = 0;
 
-    // Check commands
-    for (const cmd of EXPECTED_COMMANDS) {
+    // Check skills
+    for (const cmd of EXPECTED_SKILLS) {
       const ok = await fileExists(join(paths.commands, cmd));
       console.log(`  ${ok ? '✓' : '✗'} commands/${cmd}`);
       if (!ok) missing++;