jumpstart-mode 1.0.8 → 1.0.9

package/.jumpstart/commands/commands.md

@@ -237,6 +237,46 @@ This file defines the slash commands that drive the Jump Start workflow. Each co
 
 ---
 
+## /jumpstart.verify
+
+**Phase:** Any (utility)
+**Agent:** The Diagram Verifier
+**Agent File:** `.jumpstart/agents/diagram-verifier.md`
+**Output:** Verification report (displayed, not written to file)
+
+**Description:** Validate all Mermaid diagrams in specification artifacts for structural syntax correctness and semantic accuracy. Runs both the automated CLI syntax checker and AI-powered semantic validation. Can be invoked manually at any time or is triggered automatically at phase gates for Scout and Architect when `diagram_verification.auto_verify_at_gate` is `true`.
+
+**Usage:**
+```
+/jumpstart.verify
+/jumpstart.verify specs/architecture.md
+```
+
+**CLI equivalent:**
+```
+npx jumpstart-mode verify
+npx jumpstart-mode verify --file specs/architecture.md --strict
+```
+
+**Pre-conditions:**
+- `diagram_verification.enabled` must be `true` in `.jumpstart/config.yaml` (default: `true`).
+- At least one Markdown file with Mermaid code blocks must exist in the scan directories.
+
+**Behavior:**
+1. Load the Diagram Verifier agent persona from `.jumpstart/agents/diagram-verifier.md`.
+2. Read `diagram_verification` settings from `.jumpstart/config.yaml`.
+3. Run `npx jumpstart-mode verify` against configured `scan_dirs` (or a specific file if provided).
+4. Perform semantic validation on each diagram (level consistency, alias uniqueness, relationship completeness).
+5. Present a structured report of findings — errors, warnings, and passes.
+6. For each error or warning, suggest a specific fix with corrected Mermaid code.
+
+**Guardrails:**
+- The verifier does not modify any files. It reports findings only.
+- The responsible agent (Scout or Architect) or the human applies fixes.
+- When `strict_c4_semantics` is `true`, C4 level consistency violations are treated as errors.
+
+---
+
 ## /jumpstart.party
 
 **Phase:** Any (cross-phase collaboration)

package/.jumpstart/config.yaml

@@ -59,6 +59,18 @@ agents:
     max_file_scan_depth: 6              # How deep to walk the directory tree (0 = unlimited)
     include_dependency_analysis: true   # Parse package managers and map dependency graph
     include_debt_assessment: true       # Flag apparent technical debt, security concerns, outdated deps
+    exclude_jumpstart_paths:            # Paths created by JumpStart install — excluded from brownfield analysis
+      - ".jumpstart/"
+      - "specs/"
+      - "AGENTS.md"
+      - "CLAUDE.md"
+      - ".cursorrules"
+      - ".github/copilot-instructions.md"
+      - ".github/agents/"
+      - ".github/prompts/"
+      - ".github/instructions/"
+      - ".vscode/mcp.json"
+      - ".cursor/mcp.json"
 
   challenger:
     persona_file: "agents/challenger.md"
@@ -146,6 +158,18 @@ hooks:
   # - "gh issue create --title 'Review: {phase_name}' --body 'Artifact: {artifact_path}'"
   # - "curl -X POST $SLACK_WEBHOOK -d '{\"text\": \"Jump Start: {phase_name} complete\"}'"
 
+# ---------------------------------------------------------------------------
+# Diagram Verification
+# ---------------------------------------------------------------------------
+diagram_verification:
+  enabled: true                        # Enable Mermaid diagram verification
+  auto_verify_at_gate: true            # Automatically run verifier before phase gate approval
+  scan_dirs: ["specs"]                 # Directories to scan for Mermaid diagrams
+  strict_c4_semantics: true            # Enforce strict C4 level consistency rules
+  # The verifier can be invoked manually via:
+  #   /jumpstart.verify              (in VS Code Copilot Chat)
+  #   npx jumpstart-mode verify      (in terminal)
+
 # ---------------------------------------------------------------------------
 # Output Paths
 # ---------------------------------------------------------------------------

package/.jumpstart/templates/architecture.md

@@ -82,14 +82,33 @@
 ## Component Interaction Diagram
 
 ```mermaid
-graph TD
-    A[Component A] --> B[Component B]
-    A --> C[Component C]
-    C --> D[Database]
-    C --> E[External Service]
+C4Component
+    title Component Interaction — [System Name]
+
+    %% Replace with actual components from Step 3: System Component Design
+    Container_Boundary(system, "System") {
+        Component(gateway, "API Gateway", "Framework", "Request routing and rate limiting")
+        Component(auth, "Auth Service", "Service", "Authentication and authorization")
+        Component(core, "Core Service", "Service", "Primary business logic")
+        Component(notif, "Notification Service", "Service", "Email and push notifications")
+    }
+
+    ContainerDb(db, "Database", "Engine", "Persistent storage")
+    ContainerDb(cache, "Cache", "Redis", "Session and query cache")
+    System_Ext(extApi, "External API", "Third-party integration")
+
+    Rel(gateway, auth, "Authenticates via")
+    Rel(gateway, core, "Routes requests to")
+    Rel(core, db, "Reads/writes", "SQL")
+    Rel(core, cache, "Caches queries", "Redis Protocol")
+    Rel(core, extApi, "Fetches data from", "REST/HTTPS")
+    Rel(core, notif, "Triggers notifications")
+    Rel(auth, cache, "Stores sessions", "Redis Protocol")
+
+    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
 ```
 
-[Replace with the actual component interaction diagram. If Mermaid is not available, provide an ASCII or text-based representation.]
+[Replace with the actual component interaction diagram from Step 3. Use `C4Component` for Mermaid C4 syntax if `diagram_format` is `mermaid`, or provide an ASCII/text-based representation otherwise.]
 
 ---
 
@@ -119,11 +138,40 @@ graph TD
 
 ```mermaid
 erDiagram
-    ENTITY_A ||--o{ ENTITY_B : "has many"
-    ENTITY_B }o--|| ENTITY_C : "belongs to"
+    USER {
+        uuid id PK
+        string email UK "NOT NULL"
+        string name "NOT NULL"
+        string password_hash "NOT NULL"
+        timestamp created_at "NOT NULL"
+        timestamp updated_at "NOT NULL"
+    }
+    PROJECT {
+        uuid id PK
+        uuid owner_id FK "NOT NULL"
+        string title "NOT NULL"
+        text description
+        enum status "NOT NULL"
+        timestamp created_at "NOT NULL"
+    }
+    TASK {
+        uuid id PK
+        uuid project_id FK "NOT NULL"
+        uuid assignee_id FK
+        string title "NOT NULL"
+        text description
+        enum priority "NOT NULL"
+        enum status "NOT NULL"
+        timestamp due_date
+        timestamp created_at "NOT NULL"
+    }
+
+    USER ||--o{ PROJECT : "owns"
+    USER ||--o{ TASK : "assigned to"
+    PROJECT ||--o{ TASK : "contains"
 ```
 
-[Replace with actual ERD.]
+[Replace with actual ERD. Include field definitions with types, constraints, and keys for each entity. Use Mermaid's `erDiagram` with field blocks for detailed models.]
 
 ### Relationship Details
 

package/.jumpstart/templates/codebase-context.md

@@ -26,6 +26,8 @@
 
 ## Repository Structure
 
+> **Note:** This structure reflects the *original* codebase only. Files and directories created by the JumpStart installation process (`.jumpstart/`, `specs/`, `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and Copilot integration files under `.github/`) are excluded. See `agents.scout.exclude_jumpstart_paths` in config for the full exclusion list.
+
 ```
 [project-root]/
 |-- [annotated directory tree]
@@ -96,11 +98,24 @@
 ### System Context (Level 1)
 
 ```mermaid
-graph TB
-    %% Replace with actual system context diagram
-    User[User] -->|Uses| System[The System]
-    System -->|Calls| ExtService[External Service]
-    System -->|Reads/Writes| DB[(Database)]
+C4Context
+    title System Context Diagram — [System Name]
+
+    %% Replace with actual actors and systems discovered during reconnaissance
+    Person(user, "End User", "Primary user of the system")
+    Person(admin, "Administrator", "Manages system configuration")
+
+    System(system, "System Name", "Brief description of the system")
+
+    System_Ext(extApi, "External API", "Third-party service")
+    SystemDb_Ext(extDb, "External Database", "External data store")
+
+    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")
 ```
 
 [Description of what this diagram shows — the system boundary and external actors.]
@@ -110,14 +125,28 @@ graph TB
 ### Container Diagram (Level 2)
 
 ```mermaid
-graph TB
-    %% Replace with actual container diagram
-    subgraph System Boundary
-        App[Application<br/>Language/Framework]
-        DB[(Database<br/>Engine)]
-    end
-    User[User] --> App
-    App --> DB
+C4Container
+    title Container Diagram — [System Name]
+
+    %% Replace with actual containers discovered in the codebase
+    Person(user, "End User", "Primary user")
+
+    System_Boundary(system, "System Name") {
+        Container(webapp, "Web Application", "Framework", "Front-end application")
+        Container(api, "API Server", "Framework", "Handles business logic")
+        ContainerDb(db, "Database", "Engine", "Persistent data store")
+        ContainerDb(cache, "Cache", "Engine", "Session and query cache")
+    }
+
+    System_Ext(extSvc, "External Service", "Third-party integration")
+
+    Rel(user, webapp, "Visits", "HTTPS")
+    Rel(webapp, api, "Makes API calls", "REST/HTTPS")
+    Rel(api, db, "Reads/writes data", "SQL")
+    Rel(api, cache, "Caches data", "Redis Protocol")
+    Rel(api, extSvc, "Integrates with", "REST/HTTPS")
+
+    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
 ```
 
 [Description of the major deployable containers within the system.]
@@ -127,15 +156,25 @@ graph TB
 ### Component Diagram (Level 3) — If Configured
 
 ```mermaid
-graph TB
-    %% Replace with actual component diagram if c4_levels includes "component"
-    subgraph Container
-        ModA[Module A]
-        ModB[Module B]
-        ModC[Module C]
-    end
-    ModA --> ModB
-    ModB --> ModC
+C4Component
+    title Component Diagram — [Container Name]
+
+    %% Replace with actual components if c4_levels includes "component"
+    Container_Boundary(api, "API Server") {
+        Component(router, "Router", "Framework Router", "Routes requests to handlers")
+        Component(controller, "Controller", "Controller", "Handles HTTP requests")
+        Component(service, "Service", "Service", "Business logic")
+        ComponentDb(repo, "Repository", "ORM", "Data access layer")
+    }
+
+    ContainerDb(db, "Database", "Engine", "Persistent storage")
+
+    Rel(router, controller, "Routes to")
+    Rel(controller, service, "Delegates to")
+    Rel(service, repo, "Queries via")
+    Rel(repo, db, "Executes queries", "SQL")
+
+    UpdateLayoutConfig($c4ShapeInRow="4", $c4BoundaryInRow="1")
 ```
 
 [Description of internal components within the primary container.]
@@ -144,7 +183,43 @@ graph TB
 
 ### Code Diagram (Level 4) — If Configured
 
-[Include only if `c4_levels` includes `code`. Focus on the most critical or complex modules.]
+```mermaid
+classDiagram
+    direction TB
+
+    %% Replace with actual classes/interfaces if c4_levels includes "code"
+    %% Focus on the most critical or complex module only
+
+    class ServiceInterface {
+        <<interface>>
+        +execute(input: InputDTO): OutputDTO
+    }
+
+    class ConcreteService {
+        -repository: Repository
+        -logger: Logger
+        +execute(input: InputDTO): OutputDTO
+        -validate(input: InputDTO): void
+    }
+
+    class Repository {
+        <<interface>>
+        +findById(id: string): Entity
+        +save(entity: Entity): Entity
+    }
+
+    class Entity {
+        +id: string
+        +createdAt: Date
+        +updatedAt: Date
+    }
+
+    ServiceInterface <|.. ConcreteService : implements
+    ConcreteService --> Repository : uses
+    Repository ..> Entity : returns
+```
+
+[Include only if `c4_levels` includes `code`. Focus on the most critical or complex modules. Map actual classes and interfaces from the codebase.]
 
 ---
 

package/bin/cli.js

@@ -74,7 +74,10 @@ function parseArgs() {
 function showHelp() {
   console.log(chalk.bold.blue('\n🚀 Jump Start Framework - Spec-driven agentic coding\n'));
   console.log(chalk.bold('USAGE:'));
-  console.log('  npx jumpstart-mode [directory] [options]\n');
+  console.log('  npx jumpstart-mode [directory] [options]');
+  console.log('  npx jumpstart-mode verify [verify-options]\n');
+  console.log(chalk.bold('COMMANDS:'));
+  console.log('  verify             Validate Mermaid diagrams in spec files\n');
   console.log(chalk.bold('OPTIONS:'));
   console.log('  <directory>        Target directory (default: current directory)');
   console.log('  --name <name>      Set project name in config');
@@ -83,12 +86,19 @@ function showHelp() {
   console.log('  --force            Overwrite existing files without prompting');
   console.log('  --dry-run          Show what would be installed without copying');
   console.log('  --help, -h         Display this help message\n');
+  console.log(chalk.bold('VERIFY OPTIONS:'));
+  console.log('  --dir <path>       Directory to scan (default: specs)');
+  console.log('  --file <path>      Scan a single file');
+  console.log('  --strict           Treat warnings as errors');
+  console.log('  --json             Output as JSON\n');
   console.log(chalk.bold('EXAMPLES:'));
   console.log('  npx jumpstart-mode');
   console.log('  npx jumpstart-mode ./my-project');
   console.log('  npx jumpstart-mode . --name "My Project" --copilot');
   console.log('  npx jumpstart-mode ./existing-app --type brownfield --copilot');
-  console.log('  npx jumpstart-mode --dry-run .\n');
+  console.log('  npx jumpstart-mode --dry-run .');
+  console.log('  npx jumpstart-mode verify');
+  console.log('  npx jumpstart-mode verify --file specs/architecture.md --strict\n');
 }
 
 // Detect whether a target directory is a greenfield or brownfield project
@@ -563,6 +573,15 @@ function appendContext7Config(configPath, dryRun) {
 // Main entry point
 async function main() {
   try {
+    // Check for verify subcommand before parsing normal args
+    if (process.argv[2] === 'verify') {
+      const { run } = require('./verify-diagrams');
+      // Pass remaining args after 'verify' as if they were the full argv
+      const verifyArgv = ['node', 'verify', ...process.argv.slice(3)];
+      run(verifyArgv);
+      return; // verify-diagrams handles process.exit
+    }
+
     let config = parseArgs();
 
     if (config.help) {