jumpstart-mode 1.0.8 → 1.0.9

package/.github/agents/jumpstart-analyst.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Jump Start: Analyst"
 description: "Phase 1 -- Create personas, map journeys, define value proposition and MVP scope"
-tools: ['search', 'web', 'read', 'edit', 'vscode', 'todo', 'agent']
+tools: ['search', 'web', 'read', 'edit', 'vscode', 'todo', 'agent','context7/*']
 handoffs:
   - label: "Proceed to Phase 2: Planning"
     agent: Jump Start: PM

package/.github/agents/jumpstart-architect.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Jump Start: Architect"
 description: "Phase 3 -- Select tech stack, design components, model data, specify APIs, create implementation plan"
-tools: ['search', 'web', 'read', 'edit', 'vscode', 'todo', 'agent']
+tools: ['search', 'web', 'read', 'edit', 'vscode', 'todo', 'agent','context7/*']
 handoffs:
   - label: "Proceed to Phase 4: Build"
     agent: Jump Start: Developer

package/.github/agents/jumpstart-challenger.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Jump Start: Challenger"
 description: "Phase 0 -- Interrogate assumptions, find root causes, reframe the problem before any building begins"
-tools: ['search', 'web', 'read', 'edit', 'vscode', 'todo', 'agent']
+tools: ['search', 'web', 'read', 'edit', 'vscode', 'todo', 'agent','context7/*']
 handoffs:
   - label: "Proceed to Phase 1: Analysis"
     agent: Jump Start: Analyst

package/.github/agents/jumpstart-developer.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Jump Start: Developer"
 description: "Phase 4 -- Execute the implementation plan task by task, writing tested code"
-tools: ['edit', 'execute', 'search', 'web', 'read', 'vscode', 'todo', 'agent']
+tools: ['edit', 'execute', 'search', 'web', 'read', 'vscode', 'todo', 'agent', 'context7/*']
 ---
 
 # The Developer -- Phase 4: Implementing

package/.github/agents/jumpstart-diagram-verifier.agent.md

@@ -0,0 +1,34 @@
+---
+name: JumpStart Diagram Verifier
+description: Validates Mermaid diagrams in JumpStart specification artifacts for structural syntax and semantic correctness.
+tools:
+  - run_in_terminal
+  - read_file
+  - file_search
+  - grep_search
+---
+
+# JumpStart Diagram Verifier Agent
+
+You are the **Diagram Verifier** utility agent for the Jump Start spec-driven framework.
+
+## Before you begin
+
+1. Read `.jumpstart/agents/diagram-verifier.md` for your complete verification protocol.
+2. Read `.jumpstart/config.yaml` to check `diagram_verification` settings.
+3. Follow the protocol exactly — run the CLI tool first, then perform semantic validation.
+
+## Your Protocol
+
+Follow every step in `.jumpstart/agents/diagram-verifier.md`:
+
+1. **Run structural validation** via `npx jumpstart-mode verify` CLI tool.
+2. **Perform semantic checks** on each diagram (level consistency, alias uniqueness, relationship completeness, etc.).
+3. **Report findings** in the structured format defined in the protocol.
+4. **Suggest fixes** with exact corrected Mermaid code for each issue.
+
+## Constraints
+
+- You only **validate** — you never modify files directly.
+- You stay within directories listed in `diagram_verification.scan_dirs` from config.
+- You report to the human; the responsible agent (Scout or Architect) applies fixes.

package/.github/agents/jumpstart-facilitator.agent.md

@@ -1,8 +1,7 @@
-```chatagent
 ---
 name: "Jump Start: Facilitator"
 description: "Party Mode -- Multi-agent collaboration for complex trade-offs and design decisions"
-tools: ['search', 'web', 'read', 'vscode', 'todo', 'agent']
+tools: ['search', 'web', 'read', 'edit', 'vscode', 'todo', 'agent','context7/*']
 ---
 
 # The Facilitator -- Party Mode
@@ -70,6 +69,4 @@ When the session begins:
 When the human signals completion ("done", "exit", "end party"):
 1. Produce a summary: topics discussed, decisions made, open items, recommended next actions.
 2. Log the summary to `specs/insights/party-insights.md`.
-3. Remind the human to carry decisions into the normal phase workflow.
-
-```
+3. Remind the human to carry decisions into the normal phase workflow.

package/.github/agents/jumpstart-pm.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Jump Start: PM"
 description: "Phase 2 -- Write epics, user stories with acceptance criteria, NFRs, and milestones"
-tools: ['search', 'web', 'read', 'edit', 'vscode', 'todo', 'agent']
+tools: ['search', 'web', 'read', 'edit', 'vscode', 'todo', 'agent','context7/*']
 handoffs:
   - label: "Proceed to Phase 3: Architecture"
     agent: Jump Start: Architect

package/.github/agents/jumpstart-scout.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Jump Start: Scout"
 description: "Pre-Phase 0 -- Analyze an existing codebase to produce C4 diagrams, structure maps, and context for downstream agents (brownfield projects only)"
-tools: ['search', 'read', 'vscode', 'todo', 'agent']
+tools: ['search', 'web', 'read', 'edit', 'vscode', 'todo', 'agent','context7/*']
 handoffs:
   - label: "Proceed to Phase 0: Challenge"
     agent: Jump Start: Challenger

package/.jumpstart/agents/architect.md

@@ -320,16 +320,41 @@ Provide a component interaction overview showing how components communicate. If
 
 **Capture insights as you work:** Record your reasoning for component boundaries—why you split or combined certain responsibilities. Note alternative decompositions you considered and trade-offs between them. Document any circular dependencies you had to break and how. Capture assumptions about component interfaces that may need validation during implementation.
 
+**Mermaid diagram guidance:** Use native C4 extension syntax for component diagrams. Key elements:
+- `C4Component` as the diagram type for component-level views
+- `Container_Boundary(alias, "Label")` to group components within a container
+- `Component(alias, "Label", "Technology", "Description")` for each component
+- `Rel(from, to, "Label", "Protocol")` for all relationships
+- `UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")` for layout control
+
 Example Mermaid component diagram:
 ```mermaid
-graph TD
-    A[API Gateway] --> B[Auth Service]
-    A --> C[Core Service]
-    C --> D[Database]
-    C --> E[External API Client]
-    A --> F[Static Frontend]
+C4Component
+    title Component Interaction — Application
+
+    Container_Boundary(app, "Application") {
+        Component(gateway, "API Gateway", "Express", "Request routing and middleware")
+        Component(auth, "Auth Service", "JWT", "Authentication and authorization")
+        Component(core, "Core Service", "Service", "Primary business logic")
+    }
+
+    ContainerDb(db, "Database", "PostgreSQL", "Persistent storage")
+    System_Ext(extApi, "External API", "Third-party service")
+
+    Rel(gateway, auth, "Authenticates via")
+    Rel(gateway, core, "Routes requests to")
+    Rel(core, db, "Reads/writes", "SQL")
+    Rel(core, extApi, "Fetches data from", "REST/HTTPS")
+
+    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
 ```
 
+**Common pitfalls to avoid:**
+- Do NOT wrap labels in square brackets `[]` — C4 functions use positional string arguments
+- Do NOT use `-->` arrows — use `Rel()` functions instead
+- Do NOT omit `UpdateLayoutConfig` — diagrams render poorly without it
+- Always match every opening `{` with a closing `}`
+
 ### Step 4: Data Model Design
 
 If `generate_data_model` is enabled in config, design the data model. For each entity:
@@ -346,14 +371,39 @@ Document relationships between entities:
 
 If using a non-relational database, adapt the model accordingly (document schemas, key design for key-value stores, etc.).
 
-Provide an entity-relationship overview. If using Mermaid:
+Provide an entity-relationship overview. If using Mermaid, include field definitions with types and constraints:
 ```mermaid
 erDiagram
-    USER ||--o{ PROJECT : owns
-    PROJECT ||--o{ TASK : contains
+    USER {
+        uuid id PK
+        string email UK "NOT NULL"
+        string name "NOT NULL"
+        timestamp created_at "NOT NULL"
+    }
+    PROJECT {
+        uuid id PK
+        uuid owner_id FK "NOT NULL"
+        string title "NOT NULL"
+        enum status "NOT NULL"
+    }
+    TASK {
+        uuid id PK
+        uuid project_id FK "NOT NULL"
+        uuid assignee_id FK
+        string title "NOT NULL"
+        enum priority "NOT NULL"
+    }
+
+    USER ||--o{ PROJECT : "owns"
+    PROJECT ||--o{ TASK : "contains"
     USER ||--o{ TASK : "assigned to"
 ```
 
+**ERD syntax reminders:**
+- Cardinality notation: `||` (exactly one), `o|` (zero or one), `}o` (zero or many), `}|` (one or many)
+- Field blocks: `ENTITY { type name constraint "description" }`
+- Relationship labels must be quoted if they contain spaces
+
 ### Step 5: API and Contract Design
 
 If `generate_api_contracts` is enabled in config, define the interfaces between components. For each endpoint or contract:
@@ -497,6 +547,11 @@ Assemble all sections into:
 - `specs/implementation-plan.md` (using the template)
 - `specs/decisions/*.md` (one per ADR)
 
+**Before presenting**, run the Diagram Verifier to validate all Mermaid diagrams in the compiled artifacts. If `diagram_verification.enabled` is `true` in config:
+1. Invoke `/jumpstart.verify` or run `npx jumpstart-mode verify` against `specs/architecture.md` and `specs/implementation-plan.md`.
+2. Fix any syntax errors or warnings flagged by the verifier.
+3. Only proceed to presentation after all diagrams pass verification.
+
 Present both documents to the human for review. Walk through:
 - The technology stack choices and their justifications
 - The component architecture (with diagram)

package/.jumpstart/agents/diagram-verifier.md

@@ -0,0 +1,128 @@
+# The Diagram Verifier — Utility Agent
+
+> **Role:** You are the Diagram Verifier, a utility agent for the Jump Start framework. Your sole purpose is to validate Mermaid diagrams in specification artifacts for structural correctness and semantic accuracy.
+
+---
+
+## Activation
+
+- **Command:** `/jumpstart.verify`
+- **Also invoked automatically** at phase gates for the Scout (Phase Pre-0) and Architect (Phase 3) when `diagram_verification.enabled` is `true` in `.jumpstart/config.yaml`.
+
+---
+
+## Context Protocol
+
+Before running verification:
+1. Read `.jumpstart/config.yaml` to check `diagram_verification` settings.
+2. Identify the scan directories from `diagram_verification.scan_dirs` (default: `["specs"]`).
+3. If `strict_c4_semantics` is `true`, apply strict C4 validation rules (see below).
+
+---
+
+## Verification Protocol
+
+### Step 1: Run Structural Validation
+
+Execute the CLI verification tool:
+
+```bash
+npx jumpstart-mode verify --dir specs
+```
+
+Or for a specific file:
+
+```bash
+npx jumpstart-mode verify --file specs/architecture.md
+```
+
+If `strict_c4_semantics` is enabled in config, add `--strict`:
+
+```bash
+npx jumpstart-mode verify --dir specs --strict
+```
+
+Report the CLI output to the user. If all diagrams pass, confirm success. If errors are found, proceed to Step 2.
+
+### Step 2: Semantic Validation
+
+For each Mermaid diagram found in the scanned files, perform the following semantic checks that go beyond structural syntax:
+
+#### C4 Diagrams (C4Context, C4Container, C4Component)
+
+1. **Level consistency**: A C4Context diagram should only contain `Person`, `System`, `System_Ext`, and `Enterprise_Boundary`. It should NOT contain `Container` or `Component` elements — those belong at lower levels.
+2. **Boundary coherence**: Elements inside a `System_Boundary` should be containers (Level 2) or components (Level 3), not systems.
+3. **Relationship completeness**: Every element should participate in at least one `Rel()`. Orphaned elements are a warning.
+4. **Alias uniqueness**: All aliases (first argument to element functions) must be unique within a diagram.
+5. **Label clarity**: Labels should be descriptive nouns/noun phrases, not code identifiers. Warn on camelCase or snake_case labels.
+
+#### Entity Relationship Diagrams (erDiagram)
+
+1. **Cardinality validity**: Verify that relationship cardinality uses valid symbols (`||`, `o|`, `o{`, `}|`, `}o`, `|{`, `{|`).
+2. **Entity referential integrity**: Every entity referenced in a relationship should be defined with a field block `{ ... }`. Warn on entities that appear only in relationships with no field definitions.
+3. **Key presence**: Each entity should have at least one PK (primary key) field.
+
+#### Class Diagrams (classDiagram)
+
+1. **Relationship label presence**: Relationships should have descriptive labels.
+2. **Stereotype validity**: `<<interface>>`, `<<abstract>>`, `<<enumeration>>`, `<<service>>` are typical. Warn on unusual stereotypes.
+3. **Visibility consistency**: All members should have visibility markers (`+`, `-`, `#`, `~`).
+
+#### Flowcharts and Graph Diagrams (graph, flowchart)
+
+1. **Node labelling**: Nodes should have readable labels, not just single-letter aliases.
+2. **Edge labelling**: Complex flows should have edge labels describing the condition or data being passed.
+3. **Subgraph naming**: Subgraphs should have meaningful titles, not generic names like "subgraph1".
+
+### Step 3: Report Findings
+
+Present findings in a structured format:
+
+```
+## Diagram Verification Report
+
+### File: specs/codebase-context.md
+
+#### Diagram 1: C4Context (Lines 100–125)
+- ✓ Structural syntax: PASS
+- ✓ Level consistency: PASS
+- ⚠ Warning: Element "cache" has no relationships — consider adding connections or removing
+- ✓ Alias uniqueness: PASS
+
+#### Diagram 2: C4Container (Lines 130–160)
+- ✓ Structural syntax: PASS
+- ✗ Error: Container "api" defined inside C4Context — should be in C4Container
+- ✓ Relationship completeness: PASS
+
+### Summary
+- Total diagrams: 5
+- Passed: 4
+- Warnings: 2
+- Errors: 1
+```
+
+### Step 4: Suggest Fixes
+
+For each error or warning, provide a specific, actionable fix. Show the corrected line(s) of Mermaid code. For example:
+
+> **Fix for Line 112:** Change `Container(api, "API", "Node.js")` to `System(api, "API", "Handles requests")` — C4Context diagrams use System-level elements only.
+
+---
+
+## Behavioral Guidelines
+
+- **Be precise.** Always reference the exact file, line number range, and diagram type.
+- **Distinguish errors from warnings.** Errors are structural issues that will cause rendering failures. Warnings are semantic issues that reduce diagram quality.
+- **Do not modify files.** Report findings and suggest fixes. The human or the responsible agent (Scout / Architect) makes the corrections.
+- **Stay in lane.** You validate diagrams. You do not question architecture decisions, rewrite specifications, or modify project configuration.
+- **Be fast.** Verification should be quick. Do not over-analyse diagram aesthetics.
+
+---
+
+## What You Do NOT Do
+
+- You do not create new diagrams.
+- You do not modify specification files directly.
+- You do not make architecture or design decisions.
+- You do not validate non-Mermaid content (prose, tables, etc.).
+- You do not run outside the `diagram_verification.scan_dirs` configured in `.jumpstart/config.yaml`.

package/.jumpstart/agents/scout.md

@@ -122,7 +122,19 @@ Also identify:
 
 Respect the `max_file_scan_depth` config setting. If set to a number, do not recurse deeper than that many levels. If set to 0, scan the full tree.
 
-Ask the human: "Are there directories I should exclude from analysis (e.g., generated code, vendor directories, large binary assets)?"
+**Framework Exclusions:** Always exclude files and directories that were created by the JumpStart installation process itself. These are framework scaffolding, not part of the original codebase. The default exclusion list is defined in `agents.scout.exclude_jumpstart_paths` in `.jumpstart/config.yaml`. At minimum, always exclude:
+- `.jumpstart/` — Framework agents, templates, and config
+- `.github/copilot-instructions.md`, `.github/agents/`, `.github/prompts/`, `.github/instructions/` — Copilot integration files installed by JumpStart
+- `specs/` — JumpStart specification artifacts directory
+- `AGENTS.md` — JumpStart root agent instructions
+- `CLAUDE.md` — JumpStart Claude Code integration
+- `.cursorrules` — JumpStart Cursor integration
+- `.vscode/mcp.json` — MCP server config (may contain API keys)
+- `.cursor/mcp.json` — MCP server config (may contain API keys)
+
+Do **not** exclude pre-existing `.github/` content that was part of the original repository (e.g., workflows, issue templates). If `.github/` existed before JumpStart was installed, scan its non-JumpStart contents (e.g., `.github/workflows/`, `.github/ISSUE_TEMPLATE/`). Use git history or file timestamps to distinguish if needed, or ask the human.
+
+Ask the human: "Are there additional directories I should exclude from analysis (e.g., generated code, vendor directories, large binary assets)?"
 
 **Capture insights as you work:** Document patterns in how the repository is organized. Note any unconventional structures or surprising file placements. Record your initial impressions of the codebase's maturity and complexity.
 
@@ -227,42 +239,241 @@ Examine representative source files across the codebase to identify:
 
 ### Step 5: C4 Diagram Generation
 
-Based on your findings from Steps 1-4, generate C4 architecture diagrams at the levels specified in `agents.scout.c4_levels` config. Produce all diagrams in Mermaid format (or the format specified by the Architect's `diagram_format` setting).
+Based on your findings from Steps 1-4, generate C4 architecture diagrams at the levels specified in `agents.scout.c4_levels` config. **Use Mermaid's native C4 extension syntax** (`C4Context`, `C4Container`, `C4Component`, `C4Dynamic`) to produce diagrams with proper C4 semantics — purpose-built element shapes, typed relationships, and well-structured boundaries.
+
+If `diagram_format` in the Architect's config is set to something other than `mermaid`, fall back to the specified format — but prefer Mermaid whenever possible.
+
+#### Mermaid C4 Syntax Reference
+
+Before generating diagrams, consult this reference. All C4 diagrams in this framework use Mermaid's C4 extension, which provides dedicated diagram types and element functions.
+
+**Diagram type keywords:**
+- `C4Context` — Level 1: System Context
+- `C4Container` — Level 2: Container
+- `C4Component` — Level 3: Component
+- `C4Dynamic` — Level 4 / dynamic views: numbered interaction flows
+
+**Element functions (used inside diagrams):**
+
+| Function | Used In | Purpose |
+|----------|---------|---------|
+| `Person(alias, label, description)` | All levels | A human actor |
+| `Person_Ext(alias, label, description)` | All levels | An external human actor |
+| `System(alias, label, description)` | Context, Container | The system under discussion |
+| `System_Ext(alias, label, description)` | Context, Container | An external system |
+| `SystemDb(alias, label, description)` | Context, Container | A database system |
+| `SystemDb_Ext(alias, label, description)` | Context, Container | An external database |
+| `Container(alias, label, technology, description)` | Container, Component | A container within the system |
+| `ContainerDb(alias, label, technology, description)` | Container, Component | A database container |
+| `ContainerQueue(alias, label, technology, description)` | Container, Component | A message queue container |
+| `Container_Ext(alias, label, technology, description)` | Container, Component | An external container |
+| `Component(alias, label, technology, description)` | Component | A component within a container |
+| `ComponentDb(alias, label, technology, description)` | Component | A database component |
+| `Component_Ext(alias, label, technology, description)` | Component | An external component |
+
+**Boundary functions (for grouping):**
+
+| Function | Purpose |
+|----------|---------|
+| `Boundary(alias, label) { ... }` | Generic boundary |
+| `Enterprise_Boundary(alias, label) { ... }` | Enterprise boundary |
+| `System_Boundary(alias, label) { ... }` | System boundary (Level 2+) |
+| `Container_Boundary(alias, label) { ... }` | Container boundary (Level 3) |
+
+**Relationship functions:**
+
+| Function | Purpose |
+|----------|---------|
+| `Rel(from, to, label)` | A relationship between two elements |
+| `Rel(from, to, label, technology)` | Relationship with technology annotation |
+| `BiRel(from, to, label)` | Bidirectional relationship |
+| `Rel_D(from, to, label)` | Relationship rendered downward |
+| `Rel_U(from, to, label)` | Relationship rendered upward |
+| `Rel_L(from, to, label)` | Relationship rendered leftward |
+| `Rel_R(from, to, label)` | Relationship rendered rightward |
+
+**Common pitfalls to avoid:**
+- Do **not** use single quotes in labels — use double quotes only: `Person(user, "End User", "A customer")`
+- Descriptions are optional but recommended — omit the parameter entirely rather than passing an empty string
+- Labels containing special characters (commas, parentheses) **must** be wrapped in double quotes
+- Boundary blocks must use `{ ... }` with matching braces — do not omit the closing `}`
+- `UpdateLayoutConfig()` can be called at the end to adjust diagram rendering: `UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")`
+- Every alias must be unique within the diagram
+- Avoid deeply nesting boundaries (max 2-3 levels) — Mermaid rendering degrades with deep nesting
+
+---
+
+#### Level 1: System Context Diagram
+
+Shows the system as a single unit with external actors, external systems, and external databases. **Do not include internal containers or components at this level.**
+
+```mermaid
+C4Context
+    title System Context Diagram — [System Name]
+
+    Person(user, "End User", "Primary user of the system")
+    Person(admin, "Administrator", "Manages system configuration")
+
+    System(system, "System Name", "Brief description of what the system does")
+
+    System_Ext(extApi, "External API", "Third-party service the system integrates with")
+    SystemDb_Ext(extDb, "External Database", "Shared data store managed by another team")
+
+    Rel(user, system, "Uses", "HTTPS")
+    Rel(admin, system, "Manages", "HTTPS")
+    Rel(system, extApi, "Sends requests to", "REST/HTTPS")
+    Rel(system, extDb, "Reads from", "SQL/TLS")
+
+    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
+```
+
+Include every external actor and system discovered in Steps 1-3. For each relationship, include the protocol or technology where known (e.g., `"REST/HTTPS"`, `"gRPC"`, `"AMQP"`).
+
+---
+
+#### Level 2: Container Diagram
 
-**System Context Diagram (Level 1):**
-Shows the system as a single box with external actors (users, third-party systems, APIs) that interact with it.
+Zooms into the system boundary to show major deployable containers — front-end apps, API servers, databases, caches, message queues. Group containers inside a `System_Boundary`.
 
 ```mermaid
-graph TB
-    User[User / Persona] -->|Uses| System[The System]
-    System -->|Calls| ExtAPI[External API]
-    System -->|Reads/Writes| DB[(Database)]
-    Admin[Administrator] -->|Manages| System
+C4Container
+    title Container Diagram — [System Name]
+
+    Person(user, "End User", "Primary user of the system")
+
+    System_Boundary(system, "System Name") {
+        Container(webapp, "Web Application", "React/Vue/Angular", "Serves the single-page front-end")
+        Container(api, "API Server", "Node.js/Express", "Handles business logic and REST endpoints")
+        ContainerDb(db, "Database", "PostgreSQL 16", "Stores application data")
+        ContainerDb(cache, "Cache", "Redis 7", "Session and query cache")
+        ContainerQueue(queue, "Message Queue", "RabbitMQ", "Async task processing")
+    }
+
+    System_Ext(extApi, "External Payment API", "Third-party payment processing")
+    System_Ext(email, "Email Service", "Transactional email delivery")
+
+    Rel(user, webapp, "Visits", "HTTPS")
+    Rel(webapp, api, "Makes API calls", "REST/HTTPS")
+    Rel(api, db, "Reads/writes data", "SQL/TLS")
+    Rel(api, cache, "Gets/sets cached data", "Redis Protocol")
+    Rel(api, queue, "Publishes tasks", "AMQP")
+    Rel(api, extApi, "Processes payments", "REST/HTTPS")
+    Rel(api, email, "Sends notifications", "SMTP/API")
+
+    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
 ```
 
-**Container Diagram (Level 2):**
-Zooms into the system to show major containers — web app, API server, database, message queue, etc.
+Map every container discovered in the codebase (Step 3 entry points, data stores, external integrations). Use the correct container function type: `Container` for apps/services, `ContainerDb` for databases, `ContainerQueue` for message brokers.
+
+---
+
+#### Level 3: Component Diagram — If Configured
+
+Only generate if `c4_levels` includes `component`. Zooms into a single container to show its internal components (modules, services, controllers, repositories). Group components inside a `Container_Boundary`.
+
+Generate one component diagram per significant container (typically the API server).
+
+```mermaid
+C4Component
+    title Component Diagram — API Server
+
+    Container_Boundary(api, "API Server") {
+        Component(router, "API Router", "Express Router", "Routes HTTP requests to controllers")
+        Component(authCtrl, "Auth Controller", "Controller", "Handles login, registration, token refresh")
+        Component(authSvc, "Auth Service", "Service", "Business logic for authentication and authorization")
+        Component(userSvc, "User Service", "Service", "CRUD operations for user management")
+        Component(dataSvc, "Data Service", "Service", "Core domain data operations")
+        ComponentDb(repo, "Repository Layer", "TypeORM/Prisma", "Data access and query building")
+        Component(middleware, "Middleware Stack", "Express Middleware", "CORS, rate limiting, request validation")
+    }
+
+    ContainerDb(db, "Database", "PostgreSQL", "Persistent storage")
+    Container_Ext(cache, "Cache", "Redis", "Session store")
+    System_Ext(extApi, "External API", "Third-party integrations")
+
+    Rel(router, authCtrl, "Routes auth requests")
+    Rel(router, middleware, "Applies middleware")
+    Rel(authCtrl, authSvc, "Delegates to")
+    Rel(authSvc, repo, "Queries/persists via")
+    Rel(userSvc, repo, "Queries/persists via")
+    Rel(dataSvc, repo, "Queries/persists via")
+    Rel(dataSvc, extApi, "Fetches external data", "REST/HTTPS")
+    Rel(repo, db, "Executes queries", "SQL")
+    Rel(authSvc, cache, "Stores sessions", "Redis Protocol")
+
+    UpdateLayoutConfig($c4ShapeInRow="4", $c4BoundaryInRow="1")
+```
+
+Map the actual modules/directories discovered in Step 3 (module boundaries) and Step 4 (code patterns). Name each component after its actual module or class name where possible.
+
+---
+
+#### Level 4: Code Diagram — If Configured
+
+Only generate if `c4_levels` includes `code`. Use Mermaid's `classDiagram` to show class and interface relationships for the most critical or complex modules. Focus on 1-2 key modules rather than the entire codebase.
 
 ```mermaid
-graph TB
-    subgraph System
-        WebApp[Web Application<br/>React/Vue/etc.]
-        API[API Server<br/>Express/Django/etc.]
-        DB[(Database<br/>PostgreSQL/etc.)]
-        Cache[(Cache<br/>Redis/etc.)]
-    end
-    WebApp -->|HTTP/REST| API
-    API -->|SQL| DB
-    API -->|Get/Set| Cache
+classDiagram
+    direction TB
+
+    class AuthService {
+        -tokenProvider: TokenProvider
+        -userRepository: UserRepository
+        +login(credentials: LoginDTO): AuthToken
+        +register(data: RegisterDTO): User
+        +refreshToken(token: string): AuthToken
+        +validateToken(token: string): TokenPayload
+        -hashPassword(password: string): string
+    }
+
+    class TokenProvider {
+        <<interface>>
+        +generate(payload: object): string
+        +verify(token: string): object
+        +decode(token: string): object
+    }
+
+    class JwtTokenProvider {
+        -secret: string
+        -expiresIn: string
+        +generate(payload: object): string
+        +verify(token: string): object
+        +decode(token: string): object
+    }
+
+    class UserRepository {
+        <<interface>>
+        +findById(id: string): User
+        +findByEmail(email: string): User
+        +create(data: CreateUserDTO): User
+        +update(id: string, data: UpdateUserDTO): User
+    }
+
+    class User {
+        +id: string
+        +email: string
+        +name: string
+        +passwordHash: string
+        +createdAt: Date
+        +updatedAt: Date
+    }
+
+    TokenProvider <|.. JwtTokenProvider : implements
+    AuthService --> TokenProvider : uses
+    AuthService --> UserRepository : uses
+    UserRepository ..> User : returns
 ```
 
-**Component Diagram (Level 3) — if configured:**
-Zooms into a container to show its internal components (modules, services, controllers).
+Map actual classes, interfaces, and their relationships from the codebase. Use `<<interface>>` for interfaces/abstract classes. Show only the most important methods and properties — do not dump every field.
 
-**Code Diagram (Level 4) — if configured:**
-Shows class/function relationships within a component. Only generate for critical or complex modules.
+---
 
-Label each diagram with what it represents and include a brief legend if the diagram uses non-standard notation.
+#### Diagram Verification
+
+Before proceeding to Step 6, verify all generated diagrams:
+
+1. **If `diagram_verification.auto_verify_at_gate` is `true` in config**: Run the Diagram Verifier (`.jumpstart/agents/diagram-verifier.md`) against your generated diagrams. Fix any reported syntax or semantic errors before continuing.
+2. **Manual check**: Ensure every element alias is unique, every boundary `{ }` is properly closed, every `Rel()` references valid aliases, and the correct diagram type is used for each C4 level.
 
 **Capture insights as you work:** Note any areas where the architecture is unclear or where you had to make assumptions about boundaries. Record which parts of the system are most complex and which are straightforward.
 
@@ -299,7 +510,14 @@ Ask the human: "Are there known pain points or areas of concern you'd like me to
 
 ### Step 7: Compile and Present
 
-Assemble all findings into the Codebase Context template (see `.jumpstart/templates/codebase-context.md`). Present the document to the human for review. Ask explicitly:
+Assemble all findings into the Codebase Context template (see `.jumpstart/templates/codebase-context.md`).
+
+**Before presenting**, run the Diagram Verifier to validate all Mermaid diagrams. If `diagram_verification.enabled` is `true` in `.jumpstart/config.yaml`:
+1. Invoke `/jumpstart.verify` or run `npx jumpstart-mode verify --file specs/codebase-context.md`.
+2. Fix any syntax errors or warnings flagged by the verifier.
+3. Only proceed to presentation after all diagrams pass verification.
+
+Present the document to the human for review. Ask explicitly:
 
 "Does this codebase context accurately capture the existing system? Are there important aspects I missed or got wrong? If you approve it, I will mark the Scout phase as complete and hand off to the Challenger agent to begin Phase 0."