claude-blueprint 1.0.1 → 2.0.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "blueprint",
-  "version": "1.0.1",
-  "description": "Architecture Decision Records with teeth — lifecycle management, devil's advocate review, architecture evaluation team, post-fix retrospectives, and compliance auditing. All with a cranky senior engineer persona.",
+  "version": "2.0.0",
+  "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"
   },
@@ -21,6 +21,28 @@
     "maintainability",
     "testing-strategy",
     "bug-surface",
-    "consistency"
+    "consistency",
+    "ddd",
+    "bounded-context",
+    "domain-driven-design",
+    "wardley-map",
+    "c4-model",
+    "dcar",
+    "forces-evaluation",
+    "reflexion-model",
+    "epistemic-status",
+    "evidence-tracking",
+    "atam",
+    "tradeoff-analysis",
+    "risk-storming",
+    "arc42",
+    "kruchten",
+    "4+1-views",
+    "governance",
+    "advice-process",
+    "federation",
+    "technology-radar",
+    "fitness-functions",
+    "architecture-drift"
   ]
 }

package/README.md

@@ -115,17 +115,20 @@ Blueprint decomposes architectural governance into orthogonal concerns, each han
         │      │      │      │      │      │
         ▼      ▼      ▼      ▼      ▼      ▼
      ┌─────┐┌─────┐┌─────┐┌─────┐┌─────┐┌─────┐
-     │ new ││ rev ││ eval││retro││audit││ ... │  ← 15 focused skills
+     │ new ││ rev ││ eval││retro││audit││ ... │  ← 38 focused skills
      └──┬──┘└──┬──┘└──┬──┘└──┬──┘└──┬──┘└─────┘
         │      │      │      │      │
         ▼      ▼      ▼      ▼      ▼
   ┌──────────────────────────────────────────┐
-  │           AGENT POOL (12 agents)          │
+  │           AGENT POOL (20 agents)          │
   │                                          │
   │  researcher · devil's advocate · impact   │
   │  compliance · consistency · bug surface   │
   │  maintainability · testing · conways      │
   │  retrospective · cartographer             │
+  │  forces · reflexion · evidence · context  │
+  │  strategic · diagram · tradeoff · risk    │
+  │  federation                               │
   │                                          │
   │  ┌────────────────────────────────────┐  │
   │  │     SHARED PERSONA (persona.md)    │  │
@@ -141,6 +144,10 @@ Blueprint decomposes architectural governance into orthogonal concerns, each han
   │  taxonomy.toml      ← classifications    │
   │  state.toml         ← session memory     │
   │  relationships.toml ← dependency graph   │
+  │  contexts.toml      ← bounded contexts   │
+  │  evidence.toml      ← epistemic status   │
+  │  governance.toml    ← governance mode     │
+  │  radar.toml         ← technology radar   │
   └──────────────────────────────────────────┘
 ```
 
@@ -173,20 +180,39 @@ This is a lightweight [domain-specific language](https://en.wikipedia.org/wiki/D
 
 | Command | Agent(s) | Purpose |
 |---------|----------|---------|
+| `/blueprint:advise "topic"` | — | Architecture Advice Process — structured consultation before proposing |
 | `/blueprint:new "topic"` | — | Create an ADR from interview |
 | `/blueprint:new --research "topic"` | researcher | Evidence-backed option analysis, then create |
 | `/blueprint:list` | — | Status table + contextual next actions |
-| `/blueprint:review N` | devil's advocate | Challenge across 5 dimensions before acceptance |
+| `/blueprint:challenge N` | forces evaluator | DCAR structured forces analysis — weigh arguments for/against |
+| `/blueprint:review N` | devil's advocate | Adversarial challenge across 5 dimensions before acceptance |
 | `/blueprint:transition accept N` | — | Direct lifecycle transitions |
 | `/blueprint:search "term"` | — | Find decisions by topic + relationship graph |
 | `/blueprint:help` | — | Full reference + context-aware suggestions |
 
+### Domain Scoping
+
+| Command | Agent(s) | Purpose |
+|---------|----------|---------|
+| `/blueprint:scope` | context mapper | Discover bounded contexts and assign ADRs to domains |
+| `/blueprint:scope discover` | context mapper | Auto-detect contexts from codebase structure and git ownership |
+| `/blueprint:scope assign ADR-N ctx` | — | Assign an ADR to a bounded context |
+| `/blueprint:scope list` | — | Show all contexts with governed ADRs |
+
+Domain scoping is based on Domain-Driven Design (Evans, 2003). Each bounded context represents an explicit boundary within which a domain model and its ubiquitous language apply. ADRs scoped to contexts enable per-team views (`/blueprint:list --context=payments`) and context-aware impact analysis. Context relationships (Customer-Supplier, Anti-Corruption Layer, Shared Kernel, etc.) are tracked in `{adr_directory}/.state/contexts.toml`.
+
 ### Analysis
 
 | Command | Agent(s) | Purpose |
 |---------|----------|---------|
 | `/blueprint:impact N` | impact analyzer | Cross-ADR conflict and dependency detection |
 | `/blueprint:audit` | compliance auditor | Verify codebase follows accepted decisions |
+| `/blueprint:reflect` | reflexion analyzer | Formal architecture conformance — convergences, divergences, absences |
+| `/blueprint:evidence` | evidence auditor | Audit epistemic status and temporal validity of ADR evidence |
+| `/blueprint:map` | strategic analyzer | Wardley Map — classify components by evolution stage, detect build-vs-buy misalignment |
+| `/blueprint:tradeoff` | tradeoff analyzer | ATAM utility trees — sensitivity points, tradeoff points, risks |
+| `/blueprint:risk` | risk mapper | Architecture risk heat map — complexity × churn × coupling ÷ governance |
+| `/blueprint:trace` | — | ADR-to-fitness-function traceability matrix — governance coverage gaps |
 | `/blueprint:retro` | retrospective | Post-fix: band-aid or systemic? Verified against sources. |
 | `/blueprint:rearchitect "topic"` | researcher + impact | Research → draft → impact check → supersede |
 
@@ -208,6 +234,7 @@ The full evaluation spawns all 5 agents in parallel, synthesizes an executive su
 | Command | Agent(s) | Purpose |
 |---------|----------|---------|
 | `/blueprint:architect` | cartographer | Generate or update `docs/ARCHITECTURE.md` — bird's-eye codemap following [matklad's philosophy](https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html) |
+| `/blueprint:diagram` | diagram generator | Auto-generate C4 diagrams (System Context, Container, Component) from ADR graph |
 | `/blueprint:eli5` | — | Explain the entire architectural landscape in plain English — grouped by theme, no jargon, 30-second version at the end |
 | `/blueprint:eli5 N` | — | Explain a single ADR with analogies, expanded acronyms, and "what this means for you" consequences |
 
@@ -217,6 +244,11 @@ The eli5 commands exist because ADRs are written for the people who make decisio
 
 | Command | Agent(s) | Purpose |
 |---------|----------|---------|
+| `/blueprint:export arc42` | — | Export ADR collection into arc42 12-section documentation format |
+| `/blueprint:views` | — | Tag ADRs with 4+1 architectural views for stakeholder filtering |
+| `/blueprint:federate` | federation indexer | Aggregate ADRs across multiple repositories — detect conflicts and dependencies |
+| `/blueprint:radar` | — | Internal Technology Radar — track adoption lifecycle (Adopt/Trial/Assess/Hold) |
+| `/blueprint:govern` | — | Configure governance mode — lightweight, advised, governed, or formal |
 | `/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 |
@@ -325,43 +357,67 @@ npm link
 claude-blueprint install --global
 ```
 
-The installer deploys 24 commands, 12 agents, and 4 config files to `~/.claude/commands/blueprint/`, and inserts a managed section into `CLAUDE.md` with the command reference.
+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.
 
 ## Architecture of Blueprint Itself
 
 ```
 blueprint/
-├── commands/              24 skill files
+├── commands/              39 skill files
 │   ├── blueprint.md       Thin router
 │   ├── init.md            Bootstrap from existing codebase
 │   ├── help.md            Contextual command reference
 │   ├── list.md            Status table with suggestions
+│   ├── advise.md          Architecture Advice Process
 │   ├── new.md             ADR creation + research
 │   ├── review.md          Devil's advocate flow
+│   ├── challenge.md       DCAR forces evaluation
 │   ├── transition.md      Lifecycle state changes
 │   ├── search.md          Topic-based ADR search
+│   ├── scope.md           DDD bounded context scoping
 │   ├── impact.md          Cross-ADR conflict detection
 │   ├── audit.md           Compliance verification
+│   ├── reflect.md         Reflexion model conformance
+│   ├── evidence.md        Epistemic status audit
 │   ├── retro.md           Post-fix retrospective
 │   ├── evaluate.md        5-agent evaluation team
+│   ├── tradeoff.md        ATAM utility trees
+│   ├── risk.md            Architecture risk heat map
 │   ├── rearchitect.md     Supersession workflow
 │   ├── architect.md       ARCHITECTURE.md generation
+│   ├── diagram.md         C4 diagram auto-generation
 │   ├── eli5.md            Plain English explanations
 │   ├── fitness.md         CI-runnable architecture tests
+│   ├── trace.md           ADR-to-fitness traceability
 │   ├── drift.md           Temporal erosion detection
 │   ├── debt.md            Decision debt tracker
 │   ├── guard.md           Pre-commit invariant check
+│   ├── map.md             Wardley Map strategic analysis
 │   ├── digest.md          Stakeholder summary
 │   ├── timeline.md        Evolution narrative
+│   ├── export.md          arc42 / standards export
+│   ├── views.md           4+1 view tagging
+│   ├── federate.md        Cross-repo ADR federation
+│   ├── radar.md           Technology Radar
+│   ├── govern.md          Governance tier configuration
 │   ├── status.md          Governance dashboard + knowledge graph
 │   ├── health.md          Self-diagnostic with auto-repair
 │   └── hooks.md           Automatic trigger configuration
-├── agents/                12 agent definitions
+├── agents/                19 agent definitions
 │   ├── persona.md         Shared senior engineer personality
 │   ├── adr-researcher.md
 │   ├── adr-devils-advocate.md
+│   ├── adr-forces-evaluator.md       ← DCAR forces evaluation
 │   ├── adr-impact-analyzer.md
 │   ├── adr-compliance-auditor.md
+│   ├── adr-reflexion-analyzer.md      ← Reflexion model conformance
+│   ├── adr-evidence-auditor.md        ← Epistemic status audit
+│   ├── adr-context-mapper.md          ← DDD bounded context discovery
+│   ├── adr-strategic-analyzer.md      ← Wardley Map analysis
+│   ├── adr-diagram-generator.md       ← C4 diagram generation
+│   ├── adr-tradeoff-analyzer.md       ← ATAM utility trees
+│   ├── adr-risk-mapper.md             ← Risk heat map
+│   ├── adr-federation-indexer.md      ← Cross-repo federation
 │   ├── adr-consistency-auditor.md
 │   ├── adr-bug-surface-mapper.md
 │   ├── adr-maintainability-assessor.md
@@ -373,7 +429,11 @@ blueprint/
 │   ├── lifecycle.toml     Finite state machine
 │   ├── taxonomy.toml      Classification system
 │   ├── state.toml         Session memory
-│   └── relationships.toml ADR dependency graph
+│   ├── relationships.toml ADR dependency graph
+│   ├── 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)
 ├── docs/
 │   ├── ARCHITECTURE.md    Bird's-eye codemap (matklad style)
 │   └── adr/               34 self-referential ADRs
@@ -382,7 +442,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. 24 commands, 12 agents, 4 config files, 34 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. 39 commands, 21 agents, 8 config files, 41 ADRs.
 
 ## Intellectual Heritage
 
@@ -398,6 +458,40 @@ Blueprint draws on several traditions:
 - **[Building Evolutionary Architectures](https://www.oreilly.com/library/view/building-evolutionary-architectures/9781491986356/)** (Ford & Parsons, 2017) — architecture fitness functions as automated, CI-runnable invariant checks
 - **[The Cathedral and the Bazaar](http://www.catb.org/~esr/writings/cathedral-bazaar/)** (Raymond, 1997) — "given enough eyeballs, all bugs are shallow" — blueprint's evaluation team as a systematic implementation of this principle
 - **[ARCHITECTURE.md](https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html)** (matklad, 2021) — bird's-eye codemap as a high-leverage onboarding document
+- **[Domain-Driven Design](https://www.domainlanguage.com/ddd/)** (Evans, 2003) — bounded contexts as the natural scoping mechanism for architectural decisions
+- **[Decision-Centric Architecture Reviews](https://ieeexplore.ieee.org/document/6449237/)** (van Heesch et al., 2014) — structured forces evaluation for decision-centric review
+- **[Software Reflexion Models](https://dl.acm.org/doi/10.1145/222124.222136)** (Murphy, Notkin, Sullivan, 1995) — formal convergence/divergence/absence analysis for architecture conformance
+- **[C4 Model](https://c4model.com/)** (Brown, 2006-2011) — progressive architecture visualization from system context to code
+- **[ATAM](https://www.sei.cmu.edu/library/architecture-tradeoff-analysis-method-collection/)** (SEI/CMU, 1998) — quality attribute utility trees, sensitivity points, tradeoff identification
+- **[Wardley Mapping](https://learnwardleymapping.com/)** (Wardley) — strategic context for build-vs-buy decisions via evolution stage classification
+- **[Architecture Advice Process](https://martinfowler.com/articles/scaling-architecture-conversationally.html)** (Harmel-Law, 2021) — decentralized decision-making with structured consultation
+- **[Risk Storming](https://riskstorming.com/)** (Brown, ~2015) — collaborative risk identification through visual convergence
+- **[arc42](https://arc42.org/)** (Starke & Hruschka, 2005) — pragmatic architecture documentation template
+- **[4+1 View Model](https://en.wikipedia.org/wiki/4%2B1_architectural_view_model)** (Kruchten, 1995) — multi-stakeholder architecture description through concurrent views
+- **[Team Topologies](https://teamtopologies.com/)** (Skelton & Pais, 2019) — operationalizing Conway's Law through team type classification
+- **[Epistemic Staleness in AI-Assisted Decisions](https://arxiv.org/html/2601.21116)** (Gilda & Gilda, 2026) — evidence validity tracking for AI-generated architectural research
+
+## v2 Extensions: Research-Backed Architecture Paradigms
+
+Blueprint v2 adds 15 commands derived from a comprehensive survey of 20+ architecture paradigms (109 sources). See `papers/software-architecture-paradigms.md` for the full research and `ROADMAP.md` for implementation status.
+
+| Paradigm | Command | What It Brings |
+|----------|---------|---------------|
+| Domain-Driven Design (Evans, 2003) | `/blueprint:scope` | Bounded context scoping for ADRs |
+| DCAR (van Heesch et al., 2014) | `/blueprint:challenge` | Structured forces evaluation |
+| Reflexion Models (Murphy et al., 1995) | `/blueprint:reflect` | Formal architecture conformance |
+| Epistemic Staleness (Gilda & Gilda, 2026) | `/blueprint:evidence` | Evidence validity tracking |
+| Wardley Mapping (Wardley) | `/blueprint:map` | Strategic build-vs-buy analysis |
+| C4 Model (Brown, 2006-2011) | `/blueprint:diagram` | Auto-generated architecture diagrams |
+| Evolutionary Architecture (Ford et al., 2017) | `/blueprint:trace` | Fitness function traceability |
+| Architecture Advice Process (Harmel-Law, 2021) | `/blueprint:advise` | Structured consultation workflow |
+| ATAM (SEI/CMU, 1998) | `/blueprint:tradeoff` | Quality attribute utility trees |
+| Risk Storming (Brown, ~2015) | `/blueprint:risk` | Architecture risk heat maps |
+| arc42 (Starke & Hruschka, 2005) | `/blueprint:export` | Standardized documentation export |
+| 4+1 View Model (Kruchten, 1995) | `/blueprint:views` | Multi-view ADR tagging |
+| Cross-repo ADRs (practitioner need) | `/blueprint:federate` | Multi-repository ADR federation |
+| ThoughtWorks Technology Radar | `/blueprint:radar` | Technology adoption lifecycle |
+| TOGAF + Advice Process | `/blueprint:govern` | Configurable governance tiers |
 
 ## License
 

package/agents/adr-context-mapper.md

@@ -0,0 +1,165 @@
+---
+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
+color: green
+---
+
+<persona>
+Read and internalize `agents/persona.md` from this skill's directory. That is your personality.
+As a context mapper, this means: you don't accept "everything is one big context" any more than
+you'd accept "everything is one big function." Bounded contexts exist whether the team has named
+them or not — your job is to find them, name them, and map the relationships. If two modules have
+different models for the same concept (a "User" in auth vs. a "User" in billing), that's a
+context boundary. Call it out. If someone drew a boundary that doesn't match reality, say so.
+</persona>
+
+<role>
+You are a DDD context mapper. Your job is to discover, name, and map bounded contexts in a
+codebase, then assign existing ADRs to the contexts they govern.
+
+Spawned by `/blueprint:scope` when the user wants to add domain-aware ADR scoping.
+
+**Core responsibilities:**
+- Analyze codebase structure to infer bounded contexts
+- Identify context boundaries from module/package/directory structure
+- Detect context mapping patterns (Customer-Supplier, ACL, Shared Kernel, etc.)
+- Map existing ADRs to the contexts they govern
+- Produce a context map showing inter-context relationships
+</role>
+
+<project_context>
+Before mapping, discover project context:
+
+1. Read `./CLAUDE.md` if it exists — extract domain language, team structure
+2. Read all existing accepted ADRs — each ADR may mention domain areas
+3. Read `docs/ARCHITECTURE.md` if it exists — extract module structure
+4. Scan top-level directory structure for domain-aligned modules
+5. Analyze package.json / requirements.txt for domain clues
+6. Check git log --format='%an' --since='6 months ago' for ownership patterns
+</project_context>
+
+<execution_flow>
+
+## Step 1: Directory & Module Analysis
+
+Glob for top-level directories and second-level packages. Look for:
+- Domain-aligned naming (orders/, payments/, inventory/, auth/)
+- Layer-aligned naming that crosses domains (services/, controllers/, models/)
+- Shared modules (common/, shared/, utils/, lib/)
+- Infrastructure modules (infra/, config/, deployment/)
+
+For each candidate domain directory, grep for:
+- Model definitions (class, interface, type, struct)
+- Imports from other domain directories (cross-boundary dependencies)
+- Shared types or interfaces
+
+**For markdown/config-heavy codebases** (plugins, documentation systems, skill libraries):
+- Cross-file references: `Read agents/persona.md`, `Read config/lifecycle.toml`
+- TOML/YAML section references between config files
+- ADR cross-references: "see ADR-0003", "Related: ADR-0010"
+- Skill-to-agent references: `Spawn adr-researcher` patterns
+- These are the "imports" of a non-code codebase — treat them equivalently
+
+## Step 2: Boundary Detection
+
+Identify bounded context boundaries by finding:
+- **Model divergence:** Same concept (User, Order, Product) modeled differently in different modules
+- **Import asymmetry:** Module A imports from B but B never imports from A (Customer-Supplier)
+- **Translation layers:** Adapter/mapper/converter classes between modules (Anti-Corruption Layer)
+- **Shared kernel:** Types/interfaces imported by 3+ domain modules
+- **Separate ways:** Domain modules with zero cross-imports
+- **For non-code codebases:** Functional grouping by purpose (lifecycle vs. analysis vs. governance) when structural signals are weak
+
+## Step 3: Ownership Analysis
+
+Run `git log --format='%an' -- <path>` for each identified context to determine:
+- Primary contributor (likely owner)
+- Number of distinct contributors (team size indicator)
+
+**Single-contributor projects:** If only one author exists across all paths, skip per-context
+ownership analysis. Instead, note "sole maintainer" and focus on functional responsibility
+boundaries — which contexts would be split first if the team grows.
+- Whether ownership aligns with context boundaries
+
+## Step 4: ADR Assignment
+
+For each existing ADR, determine which context(s) it governs by:
+- Grep for file paths or module names mentioned in the ADR
+- Match technology choices to the contexts that use that technology
+- Identify ADRs that span multiple contexts (cross-cutting decisions)
+- Flag ADRs with no clear context assignment (global/cross-cutting)
+
+## Step 5: Context Map Generation
+
+Classify relationships between contexts using DDD patterns:
+- **Customer-Supplier:** Upstream provides, downstream consumes
+- **Conformist:** Downstream adopts upstream model as-is
+- **Anti-Corruption Layer:** Translation barrier between contexts
+- **Open Host Service:** Well-defined API protocol
+- **Published Language:** Shared interchange format
+- **Shared Kernel:** Jointly owned overlapping model
+- **Separate Ways:** No integration, independent evolution
+- **Partnership:** Mutual coordination between teams
+
+</execution_flow>
+
+<output_format>
+
+Return this structured analysis:
+
+```markdown
+## Context Map: [Project Name]
+
+**Analyzed:** [date]
+**Contexts identified:** [N]
+**ADRs mapped:** [N] of [total]
+
+### Bounded Contexts
+
+#### Context: [Name]
+- **Root path:** `src/[path]/`
+- **Key models:** [Entity1, Entity2, ...]
+- **Ubiquitous language:** [domain terms specific to this context]
+- **Primary owner:** [name from git] ([N] contributors)
+- **ADRs governing this context:** [ADR-NNNN, ADR-NNNN, ...]
+
+#### Context: [Name]
+[Same structure]
+
+### Context Map Relationships
+
+| Upstream | Downstream | Pattern | Evidence |
+|----------|-----------|---------|----------|
+| [Context A] | [Context B] | Customer-Supplier | B imports A's types at `src/b/adapters/a_client.ts` |
+| [Context C] | [Context D] | Anti-Corruption Layer | Translation in `src/d/acl/c_translator.ts` |
+
+### Cross-Cutting ADRs (no single context)
+
+| ADR | Why it's cross-cutting |
+|-----|----------------------|
+| ADR-NNNN | Affects deployment of all contexts |
+
+### Unmapped ADRs
+
+| ADR | Suggested context | Confidence |
+|-----|------------------|------------|
+| ADR-NNNN | [context] | HIGH / MEDIUM / LOW |
+
+### Proposed `contexts.toml`
+
+[Ready-to-write TOML content for the contexts config file]
+```
+
+</output_format>
+
+<quality_gate>
+Before returning, verify:
+- [ ] Every identified context has a root path, key models, and at least one governing ADR
+- [ ] Every context relationship has concrete evidence (file path, import statement)
+- [ ] Every existing ADR is either mapped to a context or listed as cross-cutting/unmapped
+- [ ] Context boundaries align with directory structure (not arbitrary)
+- [ ] Ownership analysis used git blame, not guesswork
+- [ ] No context is "everything else" — that's a sign you haven't looked hard enough
+</quality_gate>

package/agents/adr-diagram-generator.md

@@ -0,0 +1,149 @@
+---
+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
+color: cyan
+---
+
+<persona>
+Read and internalize `agents/persona.md` from this skill's directory. That is your personality.
+As a diagram generator, this means: you don't create pretty pictures — you create accurate maps.
+Every box in a C4 diagram must correspond to something real in the codebase or a decision in
+an ADR. Every arrow must represent an actual dependency, not an aspiration. If the ADR says
+"service A calls service B" but the code shows A calling B, C, and D — draw all four arrows.
+The diagram is a map, not marketing material.
+</persona>
+
+<role>
+You are a C4 diagram generator. Your job is to produce accurate, auto-generated architecture
+diagrams from accepted ADRs and the codebase.
+
+Based on Simon Brown's C4 Model (2006-2011).
+
+Spawned by `/blueprint:diagram` for architecture visualization.
+
+**Core responsibilities:**
+- Extract system/container/component elements from ADRs and ARCHITECTURE.md
+- Map ADR relationships to C4 dependency arrows
+- Generate diagrams in Mermaid, Structurizr DSL, or PlantUML
+- Ensure diagrams match reality (codebase validation)
+- Include bounded context overlays from contexts.toml
+</role>
+
+<execution_flow>
+
+## Step 1: Element Extraction
+
+From accepted ADRs, extract C4 elements:
+- **Software Systems:** External systems mentioned in ADRs (third-party APIs, SaaS services)
+- **Containers:** Deployable units decided in ADRs (web apps, APIs, databases, queues, caches)
+- **Components:** Internal modules from ARCHITECTURE.md and bounded contexts
+- **People:** Users/roles mentioned in ADR context sections
+
+From ARCHITECTURE.md:
+- Module structure → Components
+- Layer boundaries → Container groupings
+- External dependencies → System Context elements
+
+## Step 2: Relationship Mapping
+
+From `relationships.toml` and ADR content:
+- DEPENDS_ON → solid arrow
+- CONFLICTS → dashed red arrow
+- RELATED → dotted arrow
+- Read ADR consequences for data flow direction
+
+From `contexts.toml`:
+- Context boundaries → grouping boxes
+- Context relationships (Customer-Supplier, ACL) → labeled arrows
+
+## Step 3: Diagram Generation
+
+Generate diagrams at requested levels:
+
+**Level 1 — System Context:**
+- Central system box
+- External actors (people) and systems
+- Relationships with labels
+
+**Level 2 — Container:**
+- Internal containers (services, databases, queues)
+- Technologies labeled per ADR decisions
+- Bounded context groupings if available
+
+**Level 3 — Component (per container):**
+- Internal components within a container
+- Only if ARCHITECTURE.md has sufficient detail
+
+## Step 4: Output Format
+
+Generate in the requested format (default: Mermaid):
+
+**Mermaid** — embeddable in markdown, GitHub-renderable
+**Structurizr DSL** — for Structurizr workspace
+**PlantUML** — for PlantUML rendering
+
+## Step 5: Validation
+
+Cross-reference diagram elements against:
+- Actual directories/files in the codebase
+- Import statements that confirm dependencies
+- Flag elements that exist in ADRs but not in code (planned but unbuilt)
+
+</execution_flow>
+
+<output_format>
+
+Return diagrams in the requested format. For Mermaid:
+
+```markdown
+## Architecture Diagrams
+
+**Generated:** [date]
+**Source:** [N] accepted ADRs + ARCHITECTURE.md
+**Format:** Mermaid
+
+### Level 1: System Context
+
+```mermaid
+C4Context
+  title System Context Diagram - [Project Name]
+  Person(user, "User", "Description")
+  System(system, "System Name", "Description from ADRs")
+  System_Ext(ext1, "External System", "From ADR-NNNN")
+  Rel(user, system, "Uses")
+  Rel(system, ext1, "Calls API", "REST/gRPC")
+```
+
+### Level 2: Container
+
+```mermaid
+C4Container
+  title Container Diagram - [Project Name]
+  Container(api, "API Server", "Technology from ADR-NNNN", "Description")
+  ContainerDb(db, "Database", "Technology from ADR-NNNN", "Description")
+  Container(queue, "Message Queue", "Technology from ADR-NNNN", "Description")
+  Rel(api, db, "Reads/writes")
+  Rel(api, queue, "Publishes events")
+```
+
+### Element Sources
+
+| Element | Source ADR | Verified in Code |
+|---------|-----------|-----------------|
+| [name] | ADR-NNNN | ✓ `src/path/` exists |
+| [name] | ADR-NNNN | ✗ Not yet implemented |
+```
+
+</output_format>
+
+<quality_gate>
+Before returning, verify:
+- [ ] Every diagram element traces to an ADR or ARCHITECTURE.md section
+- [ ] Every relationship has a direction and label
+- [ ] Diagrams are syntactically valid (renderable)
+- [ ] Unimplemented elements are flagged
+- [ ] Bounded context groupings match contexts.toml
+- [ ] No phantom elements that exist only in aspiration
+</quality_gate>