claude-blueprint 2.0.1 → 2.0.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "blueprint",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "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"

package/README.md

@@ -173,6 +173,8 @@ This is a lightweight [domain-specific language](https://en.wikipedia.org/wiki/D
 | Command | Agent(s) | Purpose |
 |---------|----------|---------|
 | `/blueprint:init` | cartographer | Bootstrap blueprint onto an existing codebase — scan `.planning/`, `.research/`, CLAUDE.md, package files, git history for existing decisions, create ADR directory with template and lifecycle docs, infer ADRs, generate ARCHITECTURE.md |
+| `/blueprint:quickstart [stack]` | — | Generate 5-8 foundational ADRs from pre-built templates for a stack (react-node, python-fastapi, nextjs, go-api, generic). Auto-detects stack from package manifest. |
+| `/blueprint:onboard` | — | 5-minute architecture walkthrough for new team members — key decisions, domain structure, governance mode, health status, what to read first |
 
 `/blueprint:init` is the "day one" command. It reads every available source of architectural context — GSD planning artifacts, research files, CLAUDE.md conventions, dependency manifests, even early git commit messages — classifies discovered decisions by impact, and produces the full documentation suite in a single atomic commit. Think of it as an archaeological dig that turns implicit decisions into explicit records.
 
@@ -252,21 +254,29 @@ The eli5 commands exist because ADRs are written for the people who make decisio
 | `/blueprint:status` | — | Governance dashboard — terminal summary + interactive HTML with knowledge graph, timeline, metrics, and debt table |
 | `/blueprint:health` | — | Self-diagnostic — 8 consistency checks (index sync, supersession chains, graph integrity, staleness) with auto-repair |
 | `/blueprint:hooks` | — | Configure automatic triggers — pre-commit guard, retro-suggest, architecture-sync, dependency-watch, periodic-health |
-| `/blueprint:hooks install all` | — | Enable all 5 automation hooks in one command |
+| `/blueprint:hooks install all` | — | Enable all automation hooks in one command |
+| `/blueprint:nudge` | — | Check 10 governance staleness thresholds and surface overdue actions |
 
 `/blueprint:status` is the control room. It renders a terminal summary with ADR counts, governance health metrics, fitness coverage, and a text relationship graph — then generates and opens a self-contained HTML dashboard in your browser. The HTML has four tabs: a **force-directed knowledge graph** (nodes = ADRs colored by status, edges = relationships styled by type, click to explore), a **decision timeline**, **governance metrics with history sparklines**, and a **decision debt table**. Zero external dependencies — works offline.
 
 `/blueprint:health` is `fsck` for your ADR system. It validates internal consistency across 8 dimensions: directory structure, index-to-file sync, ADR content completeness, supersession chain integrity (bidirectional links, no cycles), relationship graph consistency (no orphans, no self-references), config freshness, cross-reference validity, and staleness (ADRs older than 12 months without review). Fixable issues get an auto-repair offer.
 
-`/blueprint:hooks` closes the adoption gap. Five configurable hooks embed blueprint into the development workflow so architectural governance happens automatically:
+`/blueprint:hooks` closes the adoption gap. Ten hooks embed blueprint into the development workflow so architectural governance happens automatically:
 
 | Hook | When it fires | What it does | Default |
 |------|--------------|-------------|---------|
-| `guard` | Before any commit | Check staged files against ADR invariants | Off (opt-in) |
-| `retro-suggest` | After fix workflows | Suggest `/blueprint:retro` | On |
+| `guard` | Before Write/Edit | Check staged files against ADR invariants | Off (opt-in) |
+| `retro-suggest` | After git fix commits | Suggest `/blueprint:retro` | On |
+| `bugfix-retro` | After `rapid:bug-fix`, `gsd:debug` | Suggest `/blueprint:retro` for plugin-driven fixes | On |
+| `feynman-evidence` | After `feynman:deepresearch`, `feynman:lit` | Link research to existing ADRs or suggest new ones | On |
+| `gsd-rapid-adr` | After `gsd:plan-phase`, `rapid:execute-set`, etc. | Detect undocumented architectural decisions | On |
+| `agent-adr` | After GSD/RAPID agent completion | Review agent output for architecture choices | On |
 | `architecture-sync` | After ADR transitions | Suggest updating ARCHITECTURE.md + fitness functions | On |
 | `dependency-watch` | Package file changed | Suggest `/blueprint:new` for new dependencies | On |
-| `periodic-health` | Every 20 sessions | Suggest `/blueprint:health` + `/blueprint:debt` | On |
+| `planning-watch` | PLAN.md or .planning/ changed | Detect architectural decisions in planning artifacts | On |
+| `periodic-nudge` | ~Every 20 sessions | Check governance staleness, suggest `/blueprint:nudge` | On |
+| `session-sweep` | Session end | Scan conversation for undocumented architectural decisions | On |
+| `skill-refresh` | Skills or agents modified | Suggest reinstalling to update CLAUDE.md | On |
 
 Hooks suggest rather than block (except `guard`, which is opt-in precisely because it blocks). The goal is to make architectural governance a natural part of the workflow, not a gate that slows development.
 
@@ -357,13 +367,13 @@ npm link
 claude-blueprint install --global
 ```
 
-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.
+The installer deploys 42 skills, 21 agents, 9 config files, and 10 hooks to `~/.claude/commands/blueprint/`, and inserts a managed section into `CLAUDE.md` with the command reference.
 
 ## Architecture of Blueprint Itself
 
 ```
 blueprint/
-├── skills/                39 skill files
+├── skills/                42 skill files
 │   ├── blueprint.md       Thin router
 │   ├── init.md            Bootstrap from existing codebase
 │   ├── help.md            Contextual command reference
@@ -402,8 +412,14 @@ blueprint/
 │   ├── govern.md          Governance tier configuration
 │   ├── status.md          Governance dashboard + knowledge graph
 │   ├── health.md          Self-diagnostic with auto-repair
-│   └── hooks.md           Automatic trigger configuration
-├── agents/                19 agent definitions
+│   ├── hooks.md           Automatic trigger configuration
+│   ├── quickstart.md      Stack-specific ADR bootstrapping
+│   ├── nudge.md           Periodic governance health checks
+│   ├── onboard.md         New developer architecture walkthrough
+│   └── persona/SKILL.md   Shared persona (preloaded via skills field)
+├── hooks/
+│   └── hooks.json         10 pre-built governance hooks
+├── agents/                21 agent definitions
 │   ├── persona.md         Shared senior engineer personality
 │   ├── adr-researcher.md
 │   ├── adr-devils-advocate.md
@@ -433,7 +449,8 @@ blueprint/
 │   ├── contexts.toml      DDD bounded contexts
 │   ├── evidence.toml      Epistemic status tracking
 │   ├── radar.toml         Technology Radar (created on first use)
-│   └── governance.toml    Governance mode (created on first use)
+│   ├── governance.toml    Governance mode (created on first use)
+│   └── quickstart-templates.toml  Pre-built ADR stubs for 5 stacks
 ├── docs/
 │   ├── ARCHITECTURE.md    Bird's-eye codemap (matklad style)
 │   └── adr/               34 self-referential ADRs
@@ -442,7 +459,7 @@ blueprint/
 └── .claude-plugin/        Plugin registration metadata
 ```
 
-Blueprint practices what it preaches: each skill is focused, the router is thin, domain knowledge is in config (not code), and agents have single responsibilities. 39 commands, 21 agents, 8 config files, 41 ADRs.
+Blueprint practices what it preaches: each skill is focused, the router is thin, domain knowledge is in config (not code), and agents have single responsibilities. 42 skills, 21 agents, 9 config files, 10 hooks, 41 ADRs.
 
 ## Intellectual Heritage
 
@@ -493,6 +510,37 @@ Blueprint v2 adds 15 commands derived from a comprehensive survey of 20+ archite
 | ThoughtWorks Technology Radar | `/blueprint:radar` | Technology adoption lifecycle |
 | TOGAF + Advice Process | `/blueprint:govern` | Configurable governance tiers |
 
+## v2.0.2: Developer Experience
+
+v2.0.2 focuses on reducing friction — wider on-ramps without changing the destination.
+
+### New Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `/blueprint:quickstart [stack]` | Generate 5-8 foundational ADRs from pre-built templates. Auto-detects stack from package manifest. Presets: react-node, python-fastapi, nextjs, go-api, generic (27 ADR stubs total). |
+| `/blueprint:onboard` | 5-minute architecture walkthrough for new developers — key decisions, domain structure, governance mode, health status, what to read first. |
+| `/blueprint:nudge` | Check 10 governance staleness thresholds and surface overdue actions. Runs automatically via SessionStart hook (~1-in-20 sessions). |
+
+### Enhancements
+
+| Change | What It Does |
+|--------|-------------|
+| `--format` on `/blueprint:fitness` | Output fitness functions as GitHub Actions (`--format github-actions`), GitLab CI (`--format gitlab-ci`), or justfile (`--format justfile`) — not just shell scripts. |
+| Context-first `/blueprint:list` | ADRs grouped by bounded context by default when contexts are defined. `--flat` for the original numbered list. |
+
+### Cross-Plugin Integration (10 hooks)
+
+Blueprint now runs as a background architecture conscience across the plugin ecosystem:
+
+- **GSD/RAPID phase completion** → detect undocumented architectural decisions
+- **GSD/RAPID agent output** → review for technology choices and pattern selections
+- **`rapid:bug-fix` / `gsd:debug`** → suggest `/blueprint:retro` for root cause analysis
+- **Feynman research completion** → link findings to existing ADRs or suggest new ones
+- **Planning artifact changes** → detect architectural decisions in PLAN.md / .planning/
+- **Session end** → sweep conversation for undocumented decisions
+- **Periodic nudge** → governance staleness check every ~20 sessions
+
 ## License
 
 MIT

package/config/quickstart-templates.toml

@@ -0,0 +1,227 @@
+# Blueprint Quick-Start Templates
+# Pre-built ADR starter sets for common technology stacks.
+# Each stack defines 5-8 foundational ADRs that every project of that type needs.
+
+# --------------------------------------------------------------------------
+# react-node: React + Express/Node.js
+# --------------------------------------------------------------------------
+[stacks.react-node]
+label = "React + Node.js"
+detect = ["react", "express", "react-dom"]
+
+[[stacks.react-node.adrs]]
+title = "Use React for frontend UI"
+context = "The project needs a component-based UI framework for building interactive interfaces. React's ecosystem maturity and hiring pool make it a strong default for teams already committed to JavaScript."
+recommended = "React"
+alternatives = ["Vue", "Svelte", "Angular"]
+category = "Technology Choice"
+
+[[stacks.react-node.adrs]]
+title = "Use Express for API server"
+context = "The backend needs an HTTP framework to handle routing, middleware, and request lifecycle. Express is the most widely adopted Node.js framework with extensive middleware ecosystem."
+recommended = "Express"
+alternatives = ["Fastify", "Koa", "Hono"]
+category = "Technology Choice"
+
+[[stacks.react-node.adrs]]
+title = "Use TypeScript across frontend and backend"
+context = "Shared language across the stack reduces context-switching and enables code sharing. Type safety catches a class of bugs at compile time that would otherwise surface in production."
+recommended = "TypeScript (strict mode)"
+alternatives = ["JavaScript with JSDoc", "JavaScript without types", "TypeScript (lenient)"]
+category = "Developer Experience"
+
+[[stacks.react-node.adrs]]
+title = "Use JWT for API authentication"
+context = "The API needs a stateless authentication mechanism that works across services. JWTs allow the frontend to authenticate without server-side session storage, though token revocation requires additional infrastructure."
+recommended = "JWT with refresh tokens"
+alternatives = ["Session cookies", "OAuth2 with opaque tokens", "API keys"]
+category = "Security"
+
+[[stacks.react-node.adrs]]
+title = "Use PostgreSQL as primary database"
+context = "The application needs a relational store for structured data with ACID guarantees. PostgreSQL offers strong JSON support for semi-structured data alongside traditional relational capabilities."
+recommended = "PostgreSQL"
+alternatives = ["MySQL", "MongoDB", "SQLite"]
+category = "Data Storage"
+
+[[stacks.react-node.adrs]]
+title = "Use Docker for local development and deployment"
+context = "Development environment parity with production reduces works-on-my-machine issues. Container-based deployment simplifies CI/CD pipelines and infrastructure provisioning."
+recommended = "Docker with docker-compose"
+alternatives = ["Native installs", "Nix", "Vagrant"]
+category = "Infrastructure"
+
+# --------------------------------------------------------------------------
+# python-fastapi: Python + FastAPI
+# --------------------------------------------------------------------------
+[stacks.python-fastapi]
+label = "Python + FastAPI"
+detect = ["fastapi", "uvicorn", "pydantic"]
+
+[[stacks.python-fastapi.adrs]]
+title = "Use FastAPI for HTTP API framework"
+context = "The project needs a modern Python web framework with automatic OpenAPI documentation and async support. FastAPI's Pydantic integration provides request validation with minimal boilerplate."
+recommended = "FastAPI"
+alternatives = ["Flask", "Django REST Framework", "Litestar"]
+category = "Technology Choice"
+
+[[stacks.python-fastapi.adrs]]
+title = "Use SQLAlchemy for database access"
+context = "The application needs an ORM that supports both high-level model declarations and low-level SQL when needed. SQLAlchemy's unit-of-work pattern and migration support via Alembic are well-proven."
+recommended = "SQLAlchemy 2.0 with Alembic"
+alternatives = ["Tortoise ORM", "SQLModel", "Raw asyncpg"]
+category = "Data Access"
+
+[[stacks.python-fastapi.adrs]]
+title = "Use Pydantic for data validation and serialization"
+context = "API request/response validation needs to be explicit and produce clear error messages. Pydantic v2's Rust-backed core provides fast validation and integrates natively with FastAPI."
+recommended = "Pydantic v2"
+alternatives = ["attrs + cattrs", "marshmallow", "Manual validation"]
+category = "Data Validation"
+
+[[stacks.python-fastapi.adrs]]
+title = "Use pytest as testing framework"
+context = "The project needs a testing framework that supports fixtures, parametrization, and async test cases. pytest's plugin ecosystem and fixture injection model reduce test boilerplate."
+recommended = "pytest with pytest-asyncio"
+alternatives = ["unittest", "nose2", "ward"]
+category = "Testing"
+
+[[stacks.python-fastapi.adrs]]
+title = "Use PostgreSQL as primary database"
+context = "The application needs a relational store with strong typing and JSON support. PostgreSQL's feature set covers most use cases without needing a separate document store."
+recommended = "PostgreSQL"
+alternatives = ["MySQL", "SQLite", "CockroachDB"]
+category = "Data Storage"
+
+[[stacks.python-fastapi.adrs]]
+title = "Use Poetry for dependency management"
+context = "Python dependency management needs lock files and virtual environment isolation. Poetry provides deterministic builds and a standardized pyproject.toml-based workflow."
+recommended = "Poetry"
+alternatives = ["uv", "pip + pip-tools", "PDM"]
+category = "Developer Experience"
+
+# --------------------------------------------------------------------------
+# nextjs: Next.js fullstack
+# --------------------------------------------------------------------------
+[stacks.nextjs]
+label = "Next.js Fullstack"
+detect = ["next", "react", "@next/font"]
+
+[[stacks.nextjs.adrs]]
+title = "Use Next.js as fullstack framework"
+context = "The project needs server-side rendering, static generation, and API routes in a single framework. Next.js provides file-based routing and multiple rendering strategies without requiring a separate backend."
+recommended = "Next.js (App Router)"
+alternatives = ["Remix", "Nuxt", "SvelteKit"]
+category = "Technology Choice"
+
+[[stacks.nextjs.adrs]]
+title = "Use Server Components as default rendering strategy"
+context = "Most pages benefit from server-side data fetching and reduced client JavaScript. React Server Components allow composing server and client rendering at the component level."
+recommended = "Server Components by default, Client Components opt-in"
+alternatives = ["Client-side rendering throughout", "Full SSR with hydration", "Static generation only"]
+category = "Architecture Pattern"
+
+[[stacks.nextjs.adrs]]
+title = "Use Prisma for database access"
+context = "The application needs type-safe database queries with migration support. Prisma's generated client provides autocomplete and compile-time query validation from a declarative schema."
+recommended = "Prisma"
+alternatives = ["Drizzle ORM", "Kysely", "Raw SQL with pg"]
+category = "Data Access"
+
+[[stacks.nextjs.adrs]]
+title = "Use Tailwind CSS for styling"
+context = "The project needs a styling approach that scales with the component model and avoids CSS specificity conflicts. Utility-first CSS co-locates styles with markup and eliminates dead CSS through purging."
+recommended = "Tailwind CSS"
+alternatives = ["CSS Modules", "styled-components", "vanilla-extract"]
+category = "UI Framework"
+
+[[stacks.nextjs.adrs]]
+title = "Use Vercel for deployment platform"
+context = "Next.js features like ISR, middleware, and edge functions work best on Vercel's infrastructure. Self-hosting is possible but requires additional configuration for feature parity."
+recommended = "Vercel"
+alternatives = ["AWS with SST", "Cloudflare Pages", "Self-hosted with Docker"]
+category = "Infrastructure"
+
+# --------------------------------------------------------------------------
+# go-api: Go API service
+# --------------------------------------------------------------------------
+[stacks.go-api]
+label = "Go API Service"
+detect = ["go.mod"]
+
+[[stacks.go-api.adrs]]
+title = "Use standard library net/http for HTTP routing"
+context = "Go 1.22+ provides pattern-based routing in the standard library, reducing the need for third-party routers. Fewer dependencies means less supply-chain risk and easier upgrades."
+recommended = "net/http with Go 1.22+ routing"
+alternatives = ["Chi", "Gin", "Echo"]
+category = "Technology Choice"
+
+[[stacks.go-api.adrs]]
+title = "Use structured logging with slog"
+context = "The service needs structured, leveled logging for observability. Go's slog package (standard library since 1.21) provides a consistent logging interface without external dependencies."
+recommended = "slog (standard library)"
+alternatives = ["zerolog", "zap", "logrus"]
+category = "Observability"
+
+[[stacks.go-api.adrs]]
+title = "Use sqlc for database query generation"
+context = "The service needs type-safe database access without the overhead of a full ORM. sqlc generates Go code from SQL queries, keeping SQL as the source of truth while providing compile-time type safety."
+recommended = "sqlc"
+alternatives = ["GORM", "sqlx", "Ent"]
+category = "Data Access"
+
+[[stacks.go-api.adrs]]
+title = "Use PostgreSQL as primary database"
+context = "The service needs a relational store with strong concurrency support. PostgreSQL's MVCC model and feature set make it the default choice for Go services."
+recommended = "PostgreSQL"
+alternatives = ["MySQL", "CockroachDB", "SQLite"]
+category = "Data Storage"
+
+[[stacks.go-api.adrs]]
+title = "Use Docker for containerized deployment"
+context = "Go produces static binaries ideal for minimal container images. Multi-stage Docker builds produce images under 20MB, simplifying deployment and reducing attack surface."
+recommended = "Docker with multi-stage builds"
+alternatives = ["Systemd units", "Kubernetes-native buildpacks", "Nix"]
+category = "Infrastructure"
+
+# --------------------------------------------------------------------------
+# generic: Stack-agnostic foundational decisions
+# --------------------------------------------------------------------------
+[stacks.generic]
+label = "Stack-Agnostic Foundations"
+detect = []
+
+[[stacks.generic.adrs]]
+title = "Select primary database engine"
+context = "Every non-trivial application needs persistent storage. The choice between relational and document databases affects schema evolution, query patterns, and operational complexity for years."
+recommended = "PostgreSQL"
+alternatives = ["MySQL", "MongoDB", "SQLite"]
+category = "Data Storage"
+
+[[stacks.generic.adrs]]
+title = "Define authentication and authorization strategy"
+context = "The application needs to verify user identity and enforce access control. Build-vs-buy and protocol choice (OAuth2, SAML, API keys) shape security posture and integration complexity."
+recommended = "OAuth2 with OIDC provider"
+alternatives = ["Session-based auth", "API keys", "Custom JWT implementation"]
+category = "Security"
+
+[[stacks.generic.adrs]]
+title = "Choose deployment and hosting strategy"
+context = "The application needs a deployment target that balances cost, operational complexity, and scaling needs. This decision constrains infrastructure choices for the project lifetime."
+recommended = "Container-based (Docker) on managed platform"
+alternatives = ["Serverless functions", "VM-based deployment", "PaaS (Heroku/Render)"]
+category = "Infrastructure"
+
+[[stacks.generic.adrs]]
+title = "Define testing strategy and coverage expectations"
+context = "The project needs a testing approach that catches regressions without slowing development. The testing pyramid shape and coverage thresholds affect both confidence and velocity."
+recommended = "Testing pyramid with 80% unit, 15% integration, 5% E2E"
+alternatives = ["Testing trophy (more integration)", "E2E-heavy approach", "Contract testing focus"]
+category = "Quality Assurance"
+
+[[stacks.generic.adrs]]
+title = "Choose CI/CD pipeline platform"
+context = "The project needs automated build, test, and deployment pipelines. The CI/CD platform choice affects developer workflow, deployment frequency, and integration with other tooling."
+recommended = "GitHub Actions"
+alternatives = ["GitLab CI", "CircleCI", "Jenkins"]
+category = "Infrastructure"

package/hooks/hooks.json

@@ -1,6 +1,19 @@
 {
   "description": "Blueprint architecture governance hooks. Pre-commit guard is opt-in (disabled by default). All others suggest actions without blocking.",
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Periodic governance health nudge. This fires at session start — to avoid noise, only act roughly every 20 sessions: pick a random number 1-20 and only proceed if it equals 1. If proceeding: read config/state.toml (relative to the blueprint skill directory) and check the [last_operations] timestamps. If any operation has never been run (empty string) or exceeds its staleness threshold (evidence_audit >90d, audit >60d, evaluation >90d, drift >30d, risk_assessment >90d, reflect >60d, strategic_map >180d), output a single concise line: 'Governance checks overdue. Run /blueprint:nudge for details.' If all timestamps are current or you decided to skip this session, stay completely silent — produce no output at all.",
+            "timeout": 5
+          }
+        ],
+        "_comment": "Periodic health nudge — lightweight governance staleness check (roughly every 20 sessions)"
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Write|Edit",
@@ -18,14 +31,60 @@
     "PostToolUse": [
       {
         "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/retro-suggest.js\"",
+            "timeout": 5
+          }
+        ],
+        "_comment": "Retro-suggest after fix commits only (ADR-0034). Uses deterministic script instead of prompt to avoid LLM false positives on non-commit Bash commands."
+      },
+      {
+        "matcher": "Skill",
         "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.",
+            "prompt": "Check if the skill that just completed was a bug-fix workflow: rapid:bug-fix, gsd:debug, gsd:quick (with fix-related arguments). If so, suggest: 'A bug was just fixed. Run /blueprint:retro to classify the root cause and check if this warrants an ADR.' Do not block.",
             "timeout": 5
           }
         ],
-        "_comment": "Retro-suggest after fix workflows (ADR-0034)"
+        "_comment": "Retro-suggest after RAPID/GSD bug-fix workflows"
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Check if the skill that just completed was a Feynman research skill: feynman:deepresearch, feynman:lit, feynman:compare, feynman:audit. If so, check if the research topic relates to any existing accepted ADR (technology choices, architecture patterns, design decisions). If it does, suggest: 'This research is relevant to [ADR-NNNN]. Run /blueprint:evidence set ADR-NNNN L1 to upgrade its evidence level, or update the ADR references section.' If the research covers a topic with no existing ADR, suggest: 'This research could support a new architectural decision. Run /blueprint:new --research \"[topic]\" to formalize.' Stay silent if the research has no architectural relevance.",
+            "timeout": 10
+          }
+        ],
+        "_comment": "Feynman research → ADR evidence pipeline"
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Check if the skill that just completed was a GSD or RAPID planning/execution skill. Specifically look for: gsd:plan-phase, gsd:execute-phase, gsd:discuss-phase, gsd:autonomous, rapid:plan-set, rapid:execute-set, rapid:discuss-set. If one of these just completed successfully, check whether the work involved architectural decisions (new technology choices, pattern selections, API designs, data model changes, deployment strategies, infrastructure choices). If architectural decisions were made during the phase but no ADR was created, suggest: 'Architectural decisions were made during this phase. Run /blueprint:new to document them, or /blueprint:scope to check which bounded context is affected.' Be specific about which decisions you detected. If no architectural decisions were made (e.g., pure UI work, content changes, test additions), stay silent.",
+            "timeout": 10
+          }
+        ],
+        "_comment": "Cross-plugin integration: suggest ADRs after GSD/RAPID phase completion"
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "gsd-executor|gsd-planner|gsd-phase-researcher|rapid-executor|rapid-planner|rapid-research",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "A GSD or RAPID agent just completed. Review its output for architectural decisions that should be documented as ADRs. Look for: new dependencies added, database/cache/queue choices, API pattern selections, module boundary definitions, deployment topology changes, authentication strategy decisions. If you find undocumented architectural decisions, suggest: 'The [agent] made architectural choices that should be recorded. Run /blueprint:new \"[specific decision topic]\" to document.' Only suggest for genuinely architectural decisions — not implementation details.",
+            "timeout": 10
+          }
+        ],
+        "_comment": "Detect architectural decisions made by GSD/RAPID agents"
       }
     ],
     "Stop": [
@@ -41,6 +100,19 @@
         "_comment": "Architecture-sync after ADR transitions (ADR-0034)"
       }
     ],
+    "SessionEnd": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Session is ending. Review the conversation for architectural decisions that were made but never documented as ADRs. Look for: technology choices (databases, frameworks, libraries), pattern selections (REST vs gRPC, monolith vs microservices), data model designs, deployment strategy changes, authentication decisions, API design choices, module boundary definitions. If you find undocumented architectural decisions, output a brief summary: 'Undocumented architectural decisions from this session:\\n- [decision 1] → /blueprint:new \"[topic]\"\\n- [decision 2] → /blueprint:new \"[topic]\"\\nRun these in your next session to formalize.' If no architectural decisions were made, stay silent.",
+            "timeout": 15
+          }
+        ],
+        "_comment": "Session-end sweep for undocumented architectural decisions"
+      }
+    ],
     "FileChanged": [
       {
         "matcher": "package\\.json|requirements\\.txt|pyproject\\.toml|Cargo\\.toml|go\\.mod",
@@ -52,6 +124,28 @@
           }
         ],
         "_comment": "Dependency-watch on package changes (ADR-0034)"
+      },
+      {
+        "matcher": "PLAN\\.md|RESEARCH\\.md|ROADMAP\\.md|\\.planning/",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "A GSD or RAPID planning artifact was modified. If the changes include architectural decisions (technology choices, pattern selections, data model designs, deployment strategies), suggest: 'Planning artifacts contain architectural decisions. Run /blueprint:new to formalize them as ADRs before execution begins.' Only suggest for genuinely architectural content.",
+            "timeout": 5
+          }
+        ],
+        "_comment": "Detect architectural decisions in GSD/RAPID planning artifacts"
+      },
+      {
+        "matcher": "skills/.*\\.md|agents/.*\\.md",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "A Blueprint skill or agent definition was modified. If a new skill was added or a skill was renamed, suggest: 'Run the Blueprint installer to update the CLAUDE.md command reference: npx claude-blueprint install --global' Only suggest if the change adds, removes, or renames a skill — not for content edits to existing skills.",
+            "timeout": 5
+          }
+        ],
+        "_comment": "Auto-refresh CLAUDE.md when skills are added or renamed"
       }
     ]
   }

package/hooks/retro-suggest.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// PostToolUse:Bash hook — suggest /blueprint:retro after fix commits.
+// Deterministic script replaces prompt-based hook to avoid false positives
+// where the LLM would explain its reasoning on non-matching commands.
+
+let input = '';
+const timeout = setTimeout(() => process.exit(0), 5000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(timeout);
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name || '';
+    const toolInput = data.tool_input || {};
+    const toolOutput = data.tool_output || '';
+
+    // Only match git commit commands
+    const cmd = toolInput.command || '';
+    if (!cmd.match(/\bgit\s+commit\b/)) {
+      process.exit(0);
+    }
+
+    // Only match if commit succeeded and message contains fix keywords
+    const output = typeof toolOutput === 'string' ? toolOutput : JSON.stringify(toolOutput);
+    if (/\b(fix|bugfix|hotfix|patch)\b/i.test(output) && !output.includes('nothing to commit')) {
+      const result = {
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext: "A bug fix was just committed. Consider running /blueprint:retro to classify the root cause and check if this warrants an ADR."
+        }
+      };
+      process.stdout.write(JSON.stringify(result));
+    }
+    // Otherwise: zero output = silent pass-through
+  } catch (e) {
+    process.exit(0);
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-blueprint",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "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": {

package/skills/fitness.md

@@ -5,6 +5,15 @@ description: >
   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.
+arguments:
+  --format:
+    type: string
+    default: shell
+    choices: [shell, github-actions, gitlab-ci, justfile]
+    description: >
+      Output format for generated fitness functions. "shell" (default) generates standalone
+      bash scripts and test files. "github-actions" generates a .github/workflows/architecture.yml
+      workflow. "gitlab-ci" generates a .gitlab-ci.yml job. "justfile" generates a just recipe.
 ---
 
 # Architecture Fitness Functions
@@ -103,14 +112,119 @@ Create `tests/architecture/conftest.py` (or equivalent) with shared utilities:
 - `find_files(pattern, directory)` — glob for structural checks
 - `assert_no_violations(violations, adr_id, message)` — standard assertion
 
-### Step 4: Present and Commit
+### Step 4: Generate Output Format
+
+Apply the requested `--format` (default: `shell`). See the **Output Formats** section below
+for the exact templates and rules for each format.
+
+Always generate the test files from Steps 2–3 first, then wrap them in the CI/runner format.
+
+### Step 5: 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
+- Which output format was used and what files were created
+- How to run them: `pytest tests/architecture/` or equivalent (for shell/justfile),
+  or "push to trigger CI" (for github-actions/gitlab-ci)
+
+Commit: `test(architecture): generate fitness functions from [N] ADRs [format: <format>]`
+
+## Output Formats
+
+After generating test files (Steps 1–3), wrap them in the requested output format.
+If `--format` is omitted, default to `shell`.
+
+### `--format shell` (default)
+
+Current behavior. Generate test files and a runner script at `tests/architecture/fitness.sh`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "=== Architecture Fitness Functions ==="
+# Run the test suite for the detected framework
+# e.g., pytest tests/architecture/ or go test ./tests/architecture/...
+<detected_test_command>
+
+echo "All architecture fitness functions passed."
+```
+
+No additional CI wrapper is generated. The user runs or integrates this script manually.
+
+### `--format github-actions`
+
+Generate a GitHub Actions workflow file at `.github/workflows/architecture.yml`:
+
+```yaml
+name: Architecture Fitness
+on: [push, pull_request]
+jobs:
+  fitness:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up runtime
+        # Include language-specific setup (actions/setup-python, actions/setup-node, etc.)
+        # based on the detected test framework from Step 2.
+        <setup_step>
+      - name: Install dependencies
+        run: <install_command>
+      - name: Run architecture fitness functions
+        run: bash tests/architecture/fitness.sh
+```
+
+**Rules:**
+- Always generate `tests/architecture/fitness.sh` alongside the workflow (the workflow calls it).
+- Detect the project language and add the appropriate setup action (`actions/setup-python@v5`,
+  `actions/setup-node@v4`, `actions/setup-go@v5`, etc.).
+- Add dependency installation (`pip install -r requirements.txt`, `npm ci`, `go mod download`).
+- If dependencies cannot be detected, omit the install step and add a YAML comment:
+  `# TODO: add dependency installation for your project`.
+
+### `--format gitlab-ci`
+
+Generate a GitLab CI job. If `.gitlab-ci.yml` already exists, append the job. If not, create it.
+
+```yaml
+architecture-fitness:
+  stage: test
+  script:
+    - bash tests/architecture/fitness.sh
+  rules:
+    - changes:
+        - "src/**/*"
+        - "docs/adr/**/*"
+```
+
+**Rules:**
+- Always generate `tests/architecture/fitness.sh` alongside the job definition.
+- Adjust the `rules.changes` paths to match the project's actual source and ADR directories
+  (read `state.toml` for the ADR path, detect `src/`, `lib/`, `app/`, etc. for source).
+- If appending to an existing `.gitlab-ci.yml`, do not duplicate stages — check whether
+  `test` is already in the `stages:` list.
+- Add language-specific `image:` if detectable (e.g., `image: python:3.12`, `image: node:20`).
+
+### `--format justfile`
+
+Generate a `just` recipe. If a `justfile` already exists, append the recipe. If not, create one.
+
+```just
+# Architecture fitness functions — generated by blueprint:fitness
+# Re-run /blueprint:fitness --format justfile after ADR changes.
+architecture-test:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    echo "=== Architecture Fitness Functions ==="
+    <detected_test_command>
+    echo "All architecture fitness functions passed."
+```
 
-Commit: `test(architecture): generate fitness functions from [N] ADRs`
+**Rules:**
+- If appending to an existing `justfile`, add a blank line separator before the new recipe.
+- Do not duplicate the recipe if `architecture-test` already exists — replace it in-place.
+- The recipe body uses bash via the shebang so it works identically to the shell format.
 
 ## Updating Fitness Functions
 

package/skills/list.md

@@ -4,13 +4,14 @@ description: >
   List all ADRs with status, date, and contextual next-action suggestions. Use when:
   "list adrs", "show decisions", "what adrs do we have", "decision status", "show accepted
   decisions", "any proposed adrs?", "list deferred". Supports filtering by status, context,
-  view, and evidence level.
-  Examples: "/blueprint:list", "/blueprint:list --context=payments", "/blueprint:list --view=physical".
+  view, and evidence level. Defaults to context-grouped display when bounded contexts are defined.
+  Examples: "/blueprint:list", "/blueprint:list --flat", "/blueprint:list --context=payments", "/blueprint:list --view=physical".
 ---
 
 # List ADRs
 
 Display all ADRs in a summary table with contextual suggestions for next actions.
+Defaults to context-grouped display when bounded contexts are defined; use `--flat` for the traditional flat-numbered table.
 
 ## Process
 
@@ -21,7 +22,7 @@ Display all ADRs in a summary table with contextual suggestions for next actions
 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. For each file, extract: number, title (from heading), status, date proposed, date decided
-5. Read `contexts.toml` — extract context assignment per ADR
+5. Read `contexts.toml` — extract context assignment per ADR (Config Resolution Protocol: check `config/` then `{adr_directory}/.state/`)
 6. Read `evidence.toml` — extract evidence level per ADR
 7. Extract Views metadata if present
 
@@ -33,7 +34,65 @@ Supports multiple filter types:
 - **By view:** `--view=physical` — show only ADRs tagged with the physical view (Kruchten 4+1)
 - **By evidence level:** `--evidence=L0` — show only ADRs with unverified evidence
 
-### Step 3: Display Table
+### Step 3: Determine Display Mode
+
+Decide between context-grouped and flat display:
+
+1. If `--flat` flag is passed → use **flat display** (Step 4B)
+2. If `contexts.toml` exists AND defines at least one `[contexts.*]` section → use **context-grouped display** (Step 4A)
+3. Otherwise → use **flat display** (Step 4B)
+
+### Step 4A: Context-Grouped Display (default when contexts exist)
+
+When bounded contexts are defined and `--flat` is not passed, group ADRs by their context assignment.
+
+**Building the groups:**
+1. For each `[contexts.*]` section in `contexts.toml`, collect ADRs listed in its `governed_adrs` array
+2. Collect ADRs listed in `cross_cutting_adrs` into a "cross-cutting" group
+3. Any ADR not appearing in any context's `governed_adrs` or in `cross_cutting_adrs` goes into an "unmapped" group
+4. Sort groups: named contexts alphabetically by context key, then "cross-cutting", then "unmapped" (if non-empty)
+5. Within each group, sort ADRs by number ascending
+
+**Rendering:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ ADR LIST — grouped by bounded context
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## context-key (N ADRs)
+| #    | Title                              | Status   | Evidence |
+|------|------------------------------------|----------|----------|
+| 0001 | Use ADRs for decisions             | Accepted | L2       |
+| 0004 | Lifecycle as state machine         | Accepted | L1       |
+...
+
+## another-context (N ADRs)
+| #    | Title                              | Status   | Evidence |
+|------|------------------------------------|----------|----------|
+...
+
+## cross-cutting (N ADRs)
+| #    | Title                              | Status   | Evidence |
+|------|------------------------------------|----------|----------|
+...
+
+## unmapped (N ADRs)
+| #    | Title                              | Status   | Evidence |
+|------|------------------------------------|----------|----------|
+...
+```
+
+- Use the context key (e.g., `lifecycle`, `analysis`) as the group heading
+- Show ADR count in parentheses after the context key
+- Omit the "unmapped" group entirely if there are no unmapped ADRs
+- If a filter is active (status, evidence, view), apply it within each group and omit empty groups
+- If `--context=X` filter is active, show only that single context group (skip context-grouped layout and show a single table for that context)
+- Show total count at the bottom: "Total: N ADRs across M contexts"
+
+### Step 4B: Flat Display (default when no contexts, or `--flat`)
+
+Show the original flat-numbered table sorted by ADR number:
 
 ```
 | #    | Title                              | Status   | Context    | Evidence | Date       |
@@ -45,7 +104,7 @@ Supports multiple filter types:
 
 If filtering, show the filter: "Showing [N] [status] ADRs (of [total] total)"
 
-### Step 4: Contextual Suggestions
+### Step 5: Contextual Suggestions
 
 Append a `▶ Suggested next actions` section using the same rules as `/blueprint:help` Step 3:
 

package/skills/nudge.md

@@ -0,0 +1,117 @@
+---
+name: blueprint:nudge
+description: >
+  Periodic health nudge — checks project governance timestamps in state.toml and surfaces
+  reminders for overdue operations. Use when: "nudge", "what governance checks are overdue?",
+  "health nudge", "what should I run?", "governance reminders", or triggered automatically
+  via the SessionStart hook roughly every 20 sessions.
+---
+
+# Periodic Health Nudge
+
+Checks governance operation timestamps and surfaces a prioritized reminder list for
+anything overdue. The quiet voice that says "hey, you haven't checked X in a while."
+
+## Shared Context
+
+Read from parent `blueprint/` skill directory:
+- `state.toml` — last operation timestamps (Config Resolution Protocol: check `config/` then `{adr_directory}/.state/`)
+- `config/lifecycle.toml` — valid statuses (for Deferred ADR check)
+- `relationships.toml` — ADR graph
+
+## Process
+
+### Step 1: Resolve Config and Read State
+
+1. Locate `state.toml` via Config Resolution Protocol:
+   - Check `config/state.toml` in the blueprint skill directory
+   - Fall back to `{adr_directory}/.state/state.toml`
+2. Read `[last_operations]` section — extract all timestamps
+3. Parse each timestamp as a date (empty string = never run)
+4. Compute days since each operation relative to today
+
+### Step 2: Locate ADR Directory
+
+Auto-detect adr_directory from `state.toml` or scan for:
+`docs/adr/` → `docs/decisions/` → `adr/` → `decisions/`
+
+### Step 3: Apply Nudge Rules
+
+Evaluate each rule against the timestamps. A rule fires if the operation was never run
+(timestamp is empty) or exceeds its staleness threshold.
+
+| Rule | Operation Key | Threshold | Nudge Message |
+|------|--------------|-----------|---------------|
+| Evidence audit stale | `last_evidence_audit` | >90 days | "Evidence may be stale. Run `/blueprint:evidence`" |
+| Compliance audit stale | `last_audit` | >60 days | "Run `/blueprint:audit` to verify ADRs are followed" |
+| Architecture evaluation stale | `last_evaluation` | >90 days | "Run `/blueprint:evaluate` for a health check" |
+| Drift check stale | `last_drift` | >30 days | "Run `/blueprint:drift` to check erosion trajectory" |
+| Risk assessment stale | `last_risk_assessment` | >90 days | "Run `/blueprint:risk` to update the risk heat map" |
+| Reflexion model stale | `last_reflect` | >60 days | "Run `/blueprint:reflect` for conformance check" |
+| Strategic map stale | `last_strategic_map` | >180 days | "Run `/blueprint:map` to check strategic alignment" |
+| Deferred ADRs aging | (scan ADR files) | >6 months deferred | "Deferred decisions aging. Run `/blueprint:debt`" |
+| No fitness functions | (check for fitness test files) | existence check | "Run `/blueprint:fitness` to generate architecture tests" |
+| ARCHITECTURE.md stale | (check file mtime) | >6 months old | "Run `/blueprint:architect` to refresh the codemap" |
+
+### Step 4: Check for Deferred ADR Aging
+
+1. Read all ADR files in the ADR directory
+2. Find any with status `Deferred`
+3. Check the `Date proposed` or `Date deferred` field
+4. If any Deferred ADR is older than 6 months, fire the deferred nudge rule
+
+### Step 5: Check for Fitness Functions
+
+1. Look for fitness function test files (typically in `tests/fitness/`, `test/fitness/`,
+   or referenced in `state.toml` under `last_trace`)
+2. If no fitness function files exist at all, fire the fitness nudge rule
+
+### Step 6: Check ARCHITECTURE.md Staleness
+
+1. Look for `docs/ARCHITECTURE.md` or `ARCHITECTURE.md` in the project root
+2. If it does not exist, fire the architecture nudge
+3. If it exists, check its last modification date via git log:
+   ```bash
+   git log -1 --format="%ai" -- docs/ARCHITECTURE.md ARCHITECTURE.md 2>/dev/null
+   ```
+4. If older than 6 months, fire the architecture nudge
+
+### Step 7: Display Results
+
+Sort all fired nudges by staleness (most overdue first — "never run" operations sort
+to the top, then by days overdue descending).
+
+Display as a prioritized checklist:
+
+```
+## Governance Nudges
+
+[ ] Evidence audit: never run — "Evidence may be stale. Run /blueprint:evidence"
+[ ] Architecture evaluation: 142 days overdue — "Run /blueprint:evaluate for a health check"
+[ ] Compliance audit: 73 days overdue — "Run /blueprint:audit to verify ADRs are followed"
+[ ] Drift check: 45 days overdue — "Run /blueprint:drift to check erosion trajectory"
+```
+
+If **no rules fire**, output:
+
+```
+All governance checks are current.
+```
+
+### Step 8: Update State
+
+Set `last_nudge` in `state.toml` `[last_operations]` to today's date (`YYYY-MM-DD`).
+
+## Hook Integration
+
+This skill can be triggered:
+- **Manually:** `/blueprint:nudge`
+- **Automatically:** Via the `SessionStart` hook (roughly every 20 sessions)
+- **From other skills:** Any skill can suggest running `/blueprint:nudge` when it detects staleness
+
+## Output Format
+
+- Terminal: markdown checklist as shown above
+- Keep output concise — this is a nudge, not a full report
+- Each nudge line should include: the check name, how overdue it is, and the command to run
+- Never block the user — nudges are suggestions, not gates

package/skills/onboard.md

@@ -0,0 +1,126 @@
+---
+name: blueprint:onboard
+description: >
+  Walk a new team member through the project's architecture in 5 minutes. Summarizes
+  key decisions, active contexts, governance mode, and what to read first. Use when:
+  "onboard me", "I'm new", "explain the architecture", "what should I know?",
+  "new developer walkthrough".
+---
+
+# Onboard — 5-Minute Architecture Walkthrough
+
+Give a new developer everything they need to understand this project's architecture
+in a single, scannable briefing. No digging through files. No asking around. One
+command, full picture.
+
+## Step 1: Read Project State
+
+Read from parent `blueprint/` skill directory and project root:
+
+- `state.toml` — ADR directory location, last operations (audit, evaluation dates)
+- `relationships.toml` — how many ADRs exist, how connected they are
+- `contexts.toml` — bounded contexts and owners
+- `evidence.toml` — overall evidence health (L0/L1/L2 counts)
+- `governance.toml` — current governance mode
+- `docs/ARCHITECTURE.md` (if exists) — extract the codemap summary
+- All accepted ADR files — count, titles, categories, severity
+
+If `state.toml` does not exist or the ADR directory is empty (no ADRs found), skip
+to the **No ADRs** fallback at the bottom.
+
+## Step 2: Generate the Onboarding Briefing
+
+Produce the briefing in this exact format:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► NEW DEVELOPER ONBOARDING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Welcome. Here's what you need to know about this project's architecture.
+
+## The Big Picture
+[2-3 sentence summary from ARCHITECTURE.md codemap, or from the highest-severity ADRs]
+
+## Key Decisions ([N] total ADRs)
+[Top 5 most important ADRs by severity — title + 1-line summary of the decision]
+
+1. ADR-NNNN: [title] — [decision in one sentence]
+2. ...
+
+## Domain Structure
+[From contexts.toml — list bounded contexts with owners]
+- [Context]: [description] (owner: [name], [N] ADRs)
+
+## Governance
+Mode: [lightweight/advised/governed/formal]
+[1-sentence explanation of what this means for the new developer]
+
+## Health Status
+Last audit: [date or NEVER]
+Last evaluation: [date or NEVER]
+Evidence health: [L2/L1/L0 counts]
+Decision debt: [N] deferred decisions
+
+## What to Read First
+1. docs/ARCHITECTURE.md — bird's-eye codemap
+2. docs/adr/[most important ADR] — the foundational decision
+3. docs/adr/[second most important] — the key technology choice
+
+## Quick Commands for New Developers
+- /blueprint:eli5 — plain English explanation of all decisions
+- /blueprint:eli5 N — explain a specific ADR
+- /blueprint:list — see all architectural decisions
+- /blueprint:scope list — see which team/context owns what
+- /blueprint:diagram — generate architecture diagrams
+```
+
+### Field rules
+
+- **The Big Picture**: If `ARCHITECTURE.md` exists, pull the first 2-3 sentences from its
+  codemap or overview section. If it does not exist, synthesize from the highest-severity
+  accepted ADRs.
+- **Key Decisions**: Sort accepted ADRs by severity (critical > high > medium > low). Show
+  the top 5. If fewer than 5 exist, show all. Each entry is the ADR number, title, and
+  the core decision condensed to one sentence.
+- **Domain Structure**: If `contexts.toml` has no entries, show "No bounded contexts defined
+  yet. Run `/blueprint:scope discover` to infer them from the codebase."
+- **Governance**: Read the mode from `governance.toml`. Explain what it means practically:
+  - `lightweight` — "You can propose and accept ADRs without approvals."
+  - `advised` — "You must seek advice before proposing ADRs (Advice Process)."
+  - `governed` — "ADRs require N approvals before acceptance."
+  - `formal` — "ADRs go through phase-based gates with formal review."
+  If `governance.toml` does not exist, default to "lightweight".
+- **Health Status**: Pull last audit/evaluation dates from `state.toml` operations. Count
+  deferred ADRs for decision debt. Pull evidence level counts from `evidence.toml`.
+- **What to Read First**: Pick the two most important ADRs (highest severity, or earliest
+  foundational decisions if severities are equal). Always list `ARCHITECTURE.md` first if
+  it exists; if it does not, note "Not yet generated. Run `/blueprint:architect` to create it."
+
+## Step 3: No ADRs Fallback
+
+If no ADRs exist, show this shorter message instead:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ BLUEPRINT ► NEW DEVELOPER ONBOARDING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+This project hasn't recorded any architectural decisions yet.
+
+That's not necessarily bad — but it means tribal knowledge is the only
+documentation of why things are the way they are.
+
+### Get Started
+Run `/blueprint:init` to bootstrap the ADR system. It will:
+- Scan your codebase for existing architectural patterns
+- Infer decisions that have already been made implicitly
+- Create the ADR directory structure and initial records
+
+### Why Bother?
+- New developers (like you) won't have to ask "why did we do it this way?"
+- Decisions won't get relitigated every quarter
+- The architecture stays intentional instead of accidental
+
+Run `/blueprint:init` and then `/blueprint:onboard` again for the full briefing.
+```

package/skills/quickstart.md

@@ -0,0 +1,154 @@
+---
+name: blueprint:quickstart
+description: >
+  Generate foundational ADR starter sets for common technology stacks. Creates 5-8 Proposed ADRs
+  covering decisions every project of that type needs to make. Auto-detects stack from project
+  manifest files if no argument given.
+  Examples: "/blueprint:quickstart react-node", "/blueprint:quickstart python-fastapi",
+  "/blueprint:quickstart" (auto-detect).
+---
+
+# Quick-Start ADR Generator
+
+Generate a set of foundational Architecture Decision Records for a technology stack, giving the
+project a decision baseline from day one.
+
+## Shared Context
+
+Before starting, read these files from the blueprint skill directory:
+
+- `config/quickstart-templates.toml` — stack definitions and ADR stubs
+- `config/lifecycle.toml` — valid statuses (generated ADRs start as Proposed)
+- `config/taxonomy.toml` — decision categories, severity levels
+- `config/state.toml` — ADR directory location (if previously detected)
+- `config/relationships.toml` — existing ADR relationships (for impact awareness)
+- `agents/persona.md` — your personality
+- `docs/adr/template.md` — the ADR template format (from the ADR directory)
+
+## Directory Detection
+
+If `state.toml` has an `adr_directory`, use it. Otherwise detect:
+1. `docs/adr/` (preferred)
+2. `docs/decisions/`
+3. `adr/`
+4. `decisions/`
+
+If found, update `state.toml` with the detected path.
+
+## Arguments
+
+The skill accepts a single optional argument: a stack identifier.
+
+Valid stack identifiers are the keys under `[stacks.*]` in `config/quickstart-templates.toml`
+(e.g., `react-node`, `python-fastapi`, `nextjs`, `go-api`, `generic`).
+
+If no argument is provided, auto-detect the stack (see below).
+
+## Process
+
+### Step 1: Determine the Stack
+
+If the user provided a stack identifier argument:
+1. Look it up in `config/quickstart-templates.toml` under `stacks.<identifier>`.
+2. If not found, list available stacks and ask the user to pick one.
+
+If no argument was provided, auto-detect:
+1. Check for `package.json` in the project root. If found, read its `dependencies` and
+   `devDependencies` keys. Match dependency names against each stack's `detect` array.
+2. Check for `requirements.txt` or `pyproject.toml` in the project root. If found, scan for
+   package names matching `detect` arrays.
+3. Check for `go.mod` in the project root. If found, match against stacks with `go.mod` in
+   their `detect` array.
+4. If multiple stacks match, pick the most specific one (most `detect` hits). If tied, present
+   the options and ask the user to choose.
+5. If nothing matches, fall back to `generic` and inform the user.
+
+### Step 2: Determine Next ADR Sequence Number
+
+Glob `[0-9][0-9][0-9][0-9]-*.md` in the ADR directory to find existing ADRs. The next sequence
+number is `max(existing) + 1`, or `0001` if no ADRs exist yet. Each generated ADR increments
+the sequence by one.
+
+### Step 3: Present the ADR Plan
+
+Before writing anything, present the full list of ADRs that will be generated. Format as a
+numbered table:
+
+```
+Stack: {stack.label}
+
+The following ADRs will be generated as Proposed:
+
+| #    | ADR ID    | Title                              | Category          | Recommended        |
+|------|-----------|------------------------------------|--------------------|---------------------|
+| 1    | ADR-NNNN  | {title}                            | {category}         | {recommended}       |
+| 2    | ADR-NNNN  | {title}                            | {category}         | {recommended}       |
+| ...  | ...       | ...                                | ...                | ...                 |
+
+Shall I generate these? You can remove items by number, or say "go" to proceed.
+```
+
+Wait for user confirmation. If the user removes items, adjust. Do NOT proceed without explicit
+confirmation.
+
+### Step 4: Generate ADR Files
+
+For each confirmed ADR stub from the template, create a full ADR file following the template at
+`docs/adr/template.md`. Expand each stub into a complete ADR:
+
+**Filename:** `{NNNN}-{kebab-case-title}.md` in the ADR directory.
+
+**Populate the template as follows:**
+
+- **Title line:** `# ADR-{NNNN}: {title}`
+- **Status:** `Proposed`
+- **Date proposed:** today's date (YYYY-MM-DD)
+- **Date decided:** *(leave blank)*
+- **Deciders:** `quickstart generator — requires team review`
+- **Category field in metadata:** use the `category` from the stub
+- **Context section:** expand the 2-sentence context from the stub into a proper paragraph.
+  Add relevant technical details — why this decision matters for the specific stack, what
+  forces are at play. Keep it to 3-5 sentences.
+- **Options Considered:** create an entry for the `recommended` option and each `alternative`.
+  For each option, write 2-3 bullet-point pros and 1-2 bullet-point cons. These should be
+  genuinely useful, not filler.
+- **Decision:** fill in the DCAR template sentence with the recommended option, but note that
+  this is a quickstart default pending team review.
+- **Rationale:** 2-3 sentences on why the recommended option is the default. Be honest about
+  tradeoffs.
+- **Consequences (Positive):** 2-3 items
+- **Consequences (Negative):** 1-2 items (every decision has downsides; don't pretend otherwise)
+- **Consequences (Risks):** 1-2 items
+- **References:** leave as `- (pending research)`
+
+### Step 5: Update State
+
+After writing all ADR files:
+
+1. Update the ADR index if one exists (check for `index.md` or `README.md` in the ADR directory).
+2. Report what was created:
+
+```
+Generated {N} Proposed ADRs for stack "{label}":
+
+  ADR-NNNN: {title}  →  {filepath}
+  ADR-NNNN: {title}  →  {filepath}
+  ...
+
+Next steps:
+  - Review each ADR with your team
+  - Run /blueprint:review {N} to challenge any decision before accepting
+  - Run /blueprint:transition accept {N} once the team agrees
+  - These are quickstart defaults — override the recommended option if your context differs
+```
+
+## Important Rules
+
+- **Never auto-accept.** All generated ADRs must be Proposed status. The team decides.
+- **Never skip confirmation.** Always present the plan and wait for the user to confirm.
+- **Be honest in pros/cons.** Every option has real tradeoffs. Do not write marketing copy.
+- **Respect existing ADRs.** If an existing accepted ADR already covers a topic, skip that
+  stub and note the overlap to the user.
+- **Use the persona.** You are a cranky senior engineer. Be direct, opinionated, and useful.
+  The quickstart defaults are your recommendations, but you respect that the team might
+  disagree.

package/src/claude-md.js

@@ -7,32 +7,65 @@ const SECTION = `${BEGIN}
 ## blueprint
 
 Architecture Decision Records with teeth. Cranky senior engineer persona.
+39 skills, 21 agents, 15 architecture paradigms.
 
-### Commands
+### Core Commands
 
 | Command | What it does |
 |---------|-------------|
 | \`/blueprint:help\` | Full reference + contextual suggestions |
-| \`/blueprint:list\` | ADR table + next actions |
+| \`/blueprint:list\` | ADR table with context, evidence, and filters |
 | \`/blueprint:new "topic"\` | Create ADR (add \`--research\` for evidence) |
-| \`/blueprint:review N\` | Devil's advocate challenge before acceptance |
+| \`/blueprint:advise "topic"\` | Architecture Advice Process before proposing |
+| \`/blueprint:challenge N\` | DCAR forces evaluation — weigh arguments |
+| \`/blueprint:review N\` | Devil's advocate adversarial challenge |
 | \`/blueprint:transition accept N\` | Accept / reject / defer / deprecate |
 | \`/blueprint:search "term"\` | Find decisions by topic |
-| \`/blueprint:impact N\` | Check for cross-ADR conflicts |
+
+### Analysis
+
+| Command | What it does |
+|---------|-------------|
+| \`/blueprint:impact N\` | Cross-ADR conflict detection |
 | \`/blueprint:audit\` | Verify codebase follows accepted decisions |
+| \`/blueprint:reflect\` | Reflexion model — formal conformance check |
+| \`/blueprint:evidence\` | Audit epistemic status + temporal validity |
+| \`/blueprint:tradeoff\` | ATAM utility tree — sensitivity + tradeoff points |
+| \`/blueprint:risk\` | Risk heat map (complexity × churn ÷ governance) |
+| \`/blueprint:trace\` | ADR-to-fitness-function traceability |
 | \`/blueprint:retro\` | Post-fix retrospective (band-aid or systemic?) |
+
+### Strategic & Governance
+
+| Command | What it does |
+|---------|-------------|
+| \`/blueprint:scope\` | DDD bounded context scoping for ADRs |
+| \`/blueprint:map\` | Wardley Map — strategic build-vs-buy analysis |
+| \`/blueprint:radar\` | Technology Radar (Adopt/Trial/Assess/Hold) |
+| \`/blueprint:govern\` | Configure governance mode (lightweight → formal) |
 | \`/blueprint:evaluate\` | 5-agent architecture evaluation team |
-| \`/blueprint:rearchitect "topic"\` | Research + supersede a decision |
 
-### Architecture Evaluation Dimensions
+### Documentation
+
+| Command | What it does |
+|---------|-------------|
+| \`/blueprint:architect\` | Generate/update ARCHITECTURE.md |
+| \`/blueprint:diagram\` | Auto-generate C4 diagrams from ADR graph |
+| \`/blueprint:eli5\` | Plain English explanation of ADRs |
+| \`/blueprint:export arc42\` | Export to arc42 12-section format |
+| \`/blueprint:views\` | Tag ADRs with 4+1 architectural views |
+| \`/blueprint:digest\` | Non-technical stakeholder summary |
+| \`/blueprint:timeline\` | Architecture evolution narrative |
 
-| Dimension | Command |
-|-----------|---------|
-| Structural consistency | \`/blueprint:evaluate consistency\` |
-| Bug surface mapping | \`/blueprint:evaluate bugs\` |
-| Long-term maintainability | \`/blueprint:evaluate maintainability\` |
-| Testing strategy | \`/blueprint:evaluate testing\` |
-| Conway's Law alignment | \`/blueprint:evaluate conways\` |
+### Continuous Governance
+
+| Command | What it does |
+|---------|-------------|
+| \`/blueprint:fitness\` | Generate CI-runnable architecture tests |
+| \`/blueprint:drift\` | Detect gradual architecture erosion |
+| \`/blueprint:debt\` | Track decision debt + evidence expiry |
+| \`/blueprint:guard\` | Pre-commit invariant check |
+| \`/blueprint:federate\` | Cross-repo ADR aggregation |
 ${END}`;
 
 export async function updateClaudeMd(claudeMdPath) {