jumpstart-mode 1.0.6 → 1.0.8

package/.jumpstart/config.yaml

@@ -1,7 +1,7 @@
 # ============================================================================
 # Jump Start Framework Configuration
 # ============================================================================
-# This file controls the behaviour of the Jump Start agentic coding workflow.
+# This file controls the behavior of the Jump Start agentic coding workflow.
 # Edit values below to customise the framework for your project.
 # ============================================================================
 
@@ -9,6 +9,28 @@ project:
   name: ""                              # Your project name (populated by `jumpstart init`)
   description: ""                       # One-line project description
   created_at: ""                        # ISO date, auto-populated
+  approver: ""                          # Name of the human approver (captured during first phase gate)
+  type: null                            # greenfield | brownfield (null = not yet determined)
+                                        #   greenfield: New project built from scratch
+                                        #   brownfield: Existing codebase being extended or refactored
+                                        #   Detected by CLI at install time, confirmed by Challenger at Phase 0
+  domain: null                          # auto | healthcare | fintech | govtech | edtech | aerospace
+                                        #   automotive | scientific | legaltech | insuretech | energy
+                                        #   process_control | building_automation | gaming | general
+                                        #   null/auto: detected from Challenger Brief domain signals
+                                        #   When set, enables domain-adaptive planning rigor
+
+# ---------------------------------------------------------------------------
+# Roadmap
+# ---------------------------------------------------------------------------
+# The roadmap defines non-negotiable principles governing all agent behavior.
+# See .jumpstart/roadmap.md for the full document.
+roadmap:
+  enabled: true                         # Enforce roadmap checks at agent activation
+  test_drive_mandate: false             # true = strict TDD gate per Article III
+                                        #   When true: Developer must write failing tests first,
+                                        #   get human approval, then implement (Red-Green-Refactor)
+                                        #   When false: Tests recommended but not gated
 
 # ---------------------------------------------------------------------------
 # Workflow Settings
@@ -17,6 +39,8 @@ workflow:
   require_gate_approval: true           # Require explicit human approval between phases
   auto_commit_artifacts: false          # Auto-commit spec files to git after generation
   allow_phase_skip: false               # If true, allows jumping to a later phase
+  auto_handoff: true                    # Automatically proceed to next phase after approval
+  archive_on_restart: true               # Archive existing artifacts before regenerating (rename with date suffix)
   current_phase: null                   # Tracks active phase (0-4), managed by framework
 
 # ---------------------------------------------------------------------------
@@ -24,6 +48,18 @@ workflow:
 # ---------------------------------------------------------------------------
 agents:
 
+  scout:
+    persona_file: "agents/scout.md"
+    capture_insights: true              # Capture observations and patterns discovered during codebase analysis
+    c4_levels:                          # Which C4 diagram levels to generate (list)
+      - context                         #   context:   System context -- external actors and systems
+      - container                       #   container: Container-level -- apps, datastores, services
+      # - component                     #   component: Component-level -- internal modules and their interactions
+      # - code                          #   code:      Code-level -- class/function relationships (very detailed)
+    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
+
   challenger:
     persona_file: "agents/challenger.md"
     capture_insights: true              # Capture decision rationale and alternatives considered
@@ -69,6 +105,7 @@ agents:
     diagram_format: "mermaid"           # mermaid | text | ascii
     generate_api_contracts: true        # Generate API contract specifications
     generate_data_model: true           # Generate entity/relationship definitions
+    generate_agents_md: true            # Generate per-directory AGENTS.md files (greenfield only)
     implementation_plan_style: "task"   # task | story | ticket
     #   task:   Granular developer tasks with file paths
     #   story:  Story-level chunks mapped to PRD stories
@@ -83,6 +120,11 @@ agents:
     commit_message_prefix: "jumpstart"  # Prefix for commit messages
     update_readme: true                 # Update README.md after implementation
     lint_on_save: true                  # Run linter after writing files
+    agents_md_depth: "module"           # Depth for per-directory AGENTS.md generation (greenfield only)
+                                        #   all:       Every directory with source code gets an AGENTS.md
+                                        #   module:    Major module directories only (e.g., src/api/, src/services/)
+                                        #   top-level: Only top-level directories under src/
+                                        #   2, 3, etc: Numeric depth limit from source root
 
 # ---------------------------------------------------------------------------
 # Integration Settings
@@ -112,6 +154,9 @@ paths:
   decisions_dir: "specs/decisions"
   research_dir: "specs/research"
   insights_dir: "specs/insights"      # Stores insight files capturing decision rationale
+  codebase_context: "specs/codebase-context.md"  # Scout agent output (brownfield projects)
+  roadmap: ".jumpstart/roadmap.md"       # Project roadmap (non-negotiable principles)
+  domain_complexity: ".jumpstart/domain-complexity.csv"  # Domain-adaptive planning rigor data
   source_dir: "src"
   tests_dir: "tests"
 

package/.jumpstart/domain-complexity.csv

@@ -0,0 +1,15 @@
+domain,signals,complexity,key_concerns,required_knowledge,special_sections
+healthcare,"medical,diagnostic,clinical,FDA,patient,treatment,HIPAA,therapy,pharma,drug",high,"FDA approval;Clinical validation;HIPAA compliance;Patient safety;Medical device classification;Liability","Regulatory pathways;Clinical trial design;Medical standards;Data privacy;Integration requirements","clinical_requirements;regulatory_pathway;validation_methodology;safety_measures"
+fintech,"payment,banking,trading,investment,crypto,wallet,transaction,KYC,AML,funds,fintech",high,"Regional compliance;Security standards;Audit requirements;Fraud prevention;Data protection","KYC/AML requirements;PCI DSS;Open banking;Regional laws (US/EU/APAC);Crypto regulations","compliance_matrix;security_architecture;audit_requirements;fraud_prevention"
+govtech,"government,federal,civic,public sector,citizen,municipal,voting",high,"Procurement rules;Security clearance;Accessibility (508);FedRAMP;Privacy;Transparency","Government procurement;Security frameworks;Accessibility standards;Privacy laws;Open data requirements","procurement_compliance;security_clearance;accessibility_standards;transparency_requirements"
+edtech,"education,learning,student,teacher,curriculum,assessment,K-12,university,LMS",medium,"Student privacy (COPPA/FERPA);Accessibility;Content moderation;Age verification;Curriculum standards","Educational privacy laws;Learning standards;Accessibility requirements;Content guidelines;Assessment validity","privacy_compliance;content_guidelines;accessibility_features;curriculum_alignment"
+aerospace,"aircraft,spacecraft,aviation,drone,satellite,propulsion,flight,radar,navigation",high,"Safety certification;DO-178C compliance;Performance validation;Simulation accuracy;Export controls","Aviation standards;Safety analysis;Simulation validation;ITAR/export controls;Performance requirements","safety_certification;simulation_validation;performance_requirements;export_compliance"
+automotive,"vehicle,car,autonomous,ADAS,automotive,driving,EV,charging",high,"Safety standards;ISO 26262;V2X communication;Real-time requirements;Certification","Automotive standards;Functional safety;V2X protocols;Real-time systems;Testing requirements","safety_standards;functional_safety;communication_protocols;certification_requirements"
+scientific,"research,algorithm,simulation,modeling,computational,analysis,data science,ML,AI",medium,"Reproducibility;Validation methodology;Peer review;Performance;Accuracy;Computational resources","Scientific method;Statistical validity;Computational requirements;Domain expertise;Publication standards","validation_methodology;accuracy_metrics;reproducibility_plan;computational_requirements"
+legaltech,"legal,law,contract,compliance,litigation,patent,attorney,court",high,"Legal ethics;Bar regulations;Data retention;Attorney-client privilege;Court system integration","Legal practice rules;Ethics requirements;Court filing systems;Document standards;Confidentiality","ethics_compliance;data_retention;confidentiality_measures;court_integration"
+insuretech,"insurance,claims,underwriting,actuarial,policy,risk,premium",high,"Insurance regulations;Actuarial standards;Data privacy;Fraud detection;State compliance","Insurance regulations by state;Actuarial methods;Risk modeling;Claims processing;Regulatory reporting","regulatory_requirements;risk_modeling;fraud_detection;reporting_compliance"
+energy,"energy,utility,grid,solar,wind,power,electricity,oil,gas",high,"Grid compliance;NERC standards;Environmental regulations;Safety requirements;Real-time operations","Energy regulations;Grid standards;Environmental compliance;Safety protocols;SCADA systems","grid_compliance;safety_protocols;environmental_compliance;operational_requirements"
+process_control,"industrial automation,process control,PLC,SCADA,DCS,HMI,operational technology,OT,control system",high,"Functional safety;OT cybersecurity;Real-time control requirements;Legacy system integration;Process safety","Functional safety standards;OT security frameworks;Industrial protocols;Process control architecture;Plant reliability","functional_safety;ot_security;process_requirements;engineering_authority"
+building_automation,"building automation,BAS,BMS,HVAC,smart building,lighting control,fire alarm,life safety",high,"Life safety codes;Building energy standards;Multi-trade coordination;Commissioning;Indoor environmental quality","Building automation protocols;HVAC controls;Fire protection design;Commissioning;Building codes","life_safety;energy_compliance;commissioning_requirements;engineering_authority"
+gaming,"game,player,gameplay,level,character,multiplayer,quest",medium,"Performance optimization;Player engagement;Monetization ethics;Platform requirements;Accessibility","Game design patterns;Real-time networking;Graphics optimization;Platform SDKs;Analytics","performance_targets;engagement_metrics;platform_requirements;accessibility_features"
+general,"",low,"Standard requirements;Basic security;User experience;Performance","General software practices","standard_requirements"

package/.jumpstart/roadmap.md

@@ -0,0 +1,85 @@
+# Project Roadmap
+
+> This document defines the non-negotiable principles that govern all AI agent behavior in this project. Roadmap principles supersede agent-specific protocols — no agent may violate a Core Principle, regardless of phase or task context.
+
+---
+
+## Core Principles
+
+### I. Sequential Phase Integrity
+
+Phases are strictly sequential. No phase may begin until the previous phase's artifact is explicitly approved by the human operator. Agents must never skip, combine, or reorder phases. The workflow order is inviolable:
+
+```
+[Scout] → Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4
+```
+
+An artifact is only "approved" when its Phase Gate Approval section has all checkboxes checked and "Approved by" is not "Pending".
+
+### II. Template Compliance
+
+All output artifacts must be generated using the markdown templates in `.jumpstart/templates/`. Agents must not invent new document formats, omit required template sections, or leave bracket placeholders (e.g., `[DATE]`, `[description]`) in final artifacts. Template structure ensures cross-phase consistency and machine-readability.
+
+### III. Test-First Development
+
+**Enforcement level:** Governed by `roadmap.test_drive_mandate` in `.jumpstart/config.yaml`.
+
+When **enabled** (`test_drive_mandate: true`):
+- The Developer agent MUST write the test suite for each task **before** writing any implementation code.
+- Tests MUST be run to confirm they fail (Red phase).
+- The failing test list MUST be presented to the human for approval.
+- Only after human approval of the failing tests may the Developer write implementation code (Green phase).
+- After tests pass, the Developer SHOULD refactor if needed (Refactor phase).
+- **Violation of this principle is a hard stop.** The Developer must not write source code for a task until its tests exist and the human has confirmed them.
+
+When **disabled** (`test_drive_mandate: false`):
+- The Developer SHOULD write tests before or alongside implementation code, but is not required to obtain human approval of failing tests before proceeding.
+- All other testing requirements (coverage, acceptance criteria mapping) remain in effect.
+
+### IV. Upstream Traceability
+
+Every downstream artifact must demonstrably trace to its upstream source:
+- PRD user stories → Product Brief capabilities → Challenger Brief validation criteria
+- Architecture decisions → PRD requirements → Product Brief scope
+- Implementation tasks → Architecture components → PRD stories
+
+No orphan requirements are permitted. If a requirement cannot be traced upstream, it must be flagged and justified or removed. Agents must not hallucinate requirements that contradict upstream documents.
+
+### V. Human Gate Authority
+
+No agent may mark a phase as complete or approve its own output. All phase transitions require explicit human approval via the Phase Gate Approval section. The human operator is the sole authority on artifact acceptance.
+
+Agents must always ask: *"Does this meet your expectations?"* before considering their work complete. Self-approval is a roadmapal violation.
+
+---
+
+## Additional Constraints
+
+- **Stay in Lane:** Each agent operates strictly within its defined phase. The Challenger never suggests solutions. The Analyst never writes code. The Developer never changes architecture. Violations must be flagged, not silently accommodated.
+- **Living Insights:** Every agent must maintain its phase's insights file. Reasoning, trade-offs, and discarded alternatives must be captured as they occur, not reconstructed after the fact.
+- **Ambiguity Handling:** When an agent encounters ambiguous, vague, or underspecified input, it must seek clarification from the human rather than making assumptions. Vague adjectives ("fast", "secure", "robust") without measurable criteria must be flagged with `[NEEDS CLARIFICATION]` markers.
+
+---
+
+## Development Workflow
+
+- **Artifact Location:** All specification documents go in `specs/`. Architecture decisions go in `specs/decisions/`. Source code goes in `src/`. Tests go in `tests/`.
+- **Configuration Authority:** `.jumpstart/config.yaml` is the single source of truth for framework settings. Agents must read it at the start of every phase.
+- **Template Authority:** `.jumpstart/templates/` contains the canonical structure for all artifacts. Agents must use these templates without modification to their structure.
+
+---
+
+## Governance
+
+This Roadmap supersedes all other agent protocols and practices. In the event of a conflict between a Roadmap principle and an agent-specific instruction, the Roadmap prevails.
+
+**Amendments require:**
+1. A written proposal with rationale for the change
+2. Explicit human approval
+3. A migration plan for any affected artifacts or in-progress work
+
+Roadmap violations must always be reported to the human, never silently ignored or worked around. An agent that detects a potential violation in its own planned actions must halt and report before proceeding.
+
+---
+
+**Version**: 1.0.0 | **Ratified**: 2026-02-08 | **Last Amended**: 2026-02-08

package/.jumpstart/templates/agents-md.md

@@ -0,0 +1,93 @@
+# AGENTS.md Template
+
+> **Purpose:** Template for per-directory `AGENTS.md` files generated during greenfield projects.
+> **Created by:** The Architect (Phase 3) and The Developer (Phase 4)
+> **Updated by:** The Developer after each milestone
+
+---
+
+## Template
+
+The following template should be adapted for each directory. Not all sections apply to every directory — omit sections that are not relevant (e.g., a `utils/` directory may not have a "Public API" section).
+
+```markdown
+# [Directory Name]
+
+## Module Purpose
+
+[1-3 sentences describing what this directory/module does and its role in the overall system. Reference the Architecture Document component it belongs to.]
+
+## Public API / Exports
+
+[List the key interfaces, functions, classes, or types that this module exposes to other parts of the system. For internal-only modules, describe what is consumed by sibling or parent modules.]
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `[name]` | [function / class / interface / type / constant] | [What it does and when to use it] |
+
+## Dependencies
+
+### Internal
+- `[module-path]` — [What is imported and why]
+
+### External
+- `[package-name]` — [What it provides to this module]
+
+## Patterns and Conventions
+
+- **File naming:** [Convention used in this directory, e.g., kebab-case, PascalCase]
+- **Error handling:** [How errors are handled in this module]
+- **Testing:** [Test file location and naming convention for this module]
+- **[Other relevant pattern]:** [Description]
+
+## AI Agent Guidelines
+
+> Rules for AI coding agents working in this directory.
+
+- [DO: Follow the established patterns visible in existing files]
+- [DO: Write tests for new functionality following the test conventions above]
+- [DO: Use the module's error handling pattern consistently]
+- [DON'T: Import from peer modules except through their public API]
+- [DON'T: Add new external dependencies without checking the Architecture Document]
+- [DON'T: Modify the public API without updating this file and consumers]
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `[filename]` | [Brief description of what this file does] |
+```
+
+---
+
+## Usage Guidelines
+
+### When to Create
+
+- **Architect (Phase 3):** Define which directories will receive `AGENTS.md` files in the architecture document's Project Structure section. Include initial `AGENTS.md` creation tasks in the implementation plan.
+- **Developer (Phase 4):** Create `AGENTS.md` files during project scaffolding (Step 2) and update them after each milestone as module APIs and patterns solidify.
+
+### Depth Configuration
+
+The `agents.developer.agents_md_depth` config setting controls which directories get `AGENTS.md` files:
+
+- **`all`**: Every directory containing source code gets an `AGENTS.md`
+- **`module`**: Major module directories (e.g., `src/api/`, `src/services/`, `src/models/`) — directories that represent a distinct functional area
+- **`top-level`**: Only top-level directories directly under the source root (e.g., `src/`)
+- **`2`, `3`, etc.**: Numeric depth limit measured from the source root directory
+
+### When to Update
+
+Update an `AGENTS.md` file when:
+- A new public export is added to or removed from the module
+- The module's error handling or testing patterns change
+- New AI-relevant guidelines are discovered during implementation
+- Dependencies (internal or external) change significantly
+- After each milestone verification (Developer Step 4)
+
+### Quality Standards
+
+- Keep `AGENTS.md` files concise and actionable — they are working documents, not documentation novels
+- Focus on information that an AI coding agent would need to work effectively in this directory
+- Ensure the "AI Agent Guidelines" section contains specific, actionable rules (not generic advice)
+- Update the "Key Files" section to reflect the current state of the directory

package/.jumpstart/templates/architecture.md

@@ -2,13 +2,14 @@
 
 > **Phase:** 3 -- Solutioning
 > **Agent:** The Architect
-> **Status:** Draft | Approved
+> **Status:** Draft
 > **Created:** [DATE]
-> **Approved:** [DATE or pending]
+> **Approval date:** [DATE or "Pending"]
+> **Approved by:** [Human's name or "Pending"]
 > **Upstream References:**
-> - [specs/challenger-brief.md](../challenger-brief.md)
-> - [specs/product-brief.md](../product-brief.md)
-> - [specs/prd.md](../prd.md)
+> - [specs/challenger-brief.md](challenger-brief.md)
+> - [specs/product-brief.md](product-brief.md)
+> - [specs/prd.md](prd.md)
 
 ---
 
@@ -18,6 +19,29 @@
 
 ---
 
+## Existing System Context (Brownfield Only)
+
+> **Instruction:** Include this section only if `project.type` is `brownfield`. Remove it entirely for greenfield projects.
+
+**Source:** [specs/codebase-context.md](codebase-context.md)
+
+### Current Architecture Summary
+
+[2-3 sentence summary of the existing system's architecture as documented by the Scout agent. Reference the C4 diagrams in the codebase context.]
+
+### Constraints from Existing System
+
+| Constraint | Rationale | Impact on New Design |
+|------------|-----------|---------------------|
+| [e.g., Must maintain PostgreSQL 14] | [Why this can't change] | [How this shapes the new architecture] |
+| [e.g., Existing REST API contracts] | [External consumers depend on them] | [Must maintain backward compatibility] |
+
+### Migration Strategy
+
+[Brief description of how the new architecture will coexist with or transition from the existing system. Reference any relevant ADRs.]
+
+---
+
 ## Technology Stack
 
 | Layer | Choice | Version | Justification | Alternatives Considered |
@@ -245,8 +269,8 @@ Push to branch
 
 | ADR | Title | Status | File |
 |-----|-------|--------|------|
-| ADR-001 | [Decision title] | Accepted | [specs/decisions/001-short-title.md](../decisions/001-short-title.md) |
-| ADR-002 | [Decision title] | Accepted | [specs/decisions/002-short-title.md](../decisions/002-short-title.md) |
+| ADR-001 | [Decision title] | Accepted | [specs/decisions/001-short-title.md](decisions/001-short-title.md) |
+| ADR-002 | [Decision title] | Accepted | [specs/decisions/002-short-title.md](decisions/002-short-title.md) |
 
 [List all ADRs. Full content lives in individual files in specs/decisions/.]
 
@@ -272,7 +296,7 @@ Push to branch
 
 ## Insights Reference
 
-**Companion Document:** [specs/insights/architecture-insights.md](../insights/architecture-insights.md)
+**Companion Document:** [specs/insights/architecture-insights.md](insights/architecture-insights.md)
 
 This artifact was informed by ongoing insights captured during Solutioning. Key insights that shaped this document:
 
@@ -284,6 +308,21 @@ See the insights document for complete decision rationale, alternatives consider
 
 ---
 
+## Directory AGENTS.md Plan (Greenfield Only)
+
+> **Instruction:** Include this section only if `project.type` is `greenfield`. Remove it entirely for brownfield projects. The Developer agent will create these files during scaffolding and maintain them during task execution. Use the template from `.jumpstart/templates/agents-md.md`.
+
+| Directory | Purpose | Key Exports | Notes |
+|-----------|---------|-------------|-------|
+| `src/` | Application root | — | Top-level module documentation |
+| [e.g., `src/api/`] | [API endpoint handlers] | [Routes, middleware] | |
+| [e.g., `src/models/`] | [Data models and schemas] | [Entity types, validators] | |
+| [e.g., `src/services/`] | [Business logic layer] | [Service functions] | |
+
+[Add rows for each directory that should receive an AGENTS.md file. The depth is governed by `agents.developer.agents_md_depth` in config.yaml: `top-level` (src/ only), `module` (src/[module]/), or `deep` (all significant directories).]
+
+---
+
 ## Phase Gate Approval
 
 - [ ] Human has reviewed this Architecture Document
@@ -298,3 +337,4 @@ See the insights document for complete decision rationale, alternatives consider
 
 **Approved by:** [Human's name or "Pending"]
 **Approval date:** [Date or "Pending"]
+**Status:** Draft

package/.jumpstart/templates/challenger-brief.md

@@ -2,9 +2,10 @@
 
 > **Phase:** 0 -- Problem / Challenge Discovery
 > **Agent:** The Challenger
-> **Status:** Draft | Approved
+> **Status:** Draft
 > **Created:** [DATE]
-> **Approved:** [DATE or pending]
+> **Approval date:** [DATE or "Pending"]
+> **Approved by:** [Human's name or "Pending"]
 
 ---
 
@@ -92,7 +93,7 @@ How will we know the problem has been solved?
 
 | # | Criterion | Type | Measurable? |
 |---|-----------|------|------------|
-| 1 | [Outcome-based success criterion, solution-agnostic] | Behavioural / Metric / Qualitative | Yes / Needs refinement |
+| 1 | [Outcome-based success criterion, solution-agnostic] | Behavioral / Metric / Qualitative | Yes / Needs refinement |
 | 2 | | | |
 | 3 | | | |
 
@@ -118,7 +119,7 @@ How will we know the problem has been solved?
 
 ## Insights Reference
 
-**Companion Document:** [specs/insights/challenger-brief-insights.md](../insights/challenger-brief-insights.md)
+**Companion Document:** [specs/insights/challenger-brief-insights.md](insights/challenger-brief-insights.md)
 
 This artifact was informed by ongoing insights captured during Problem Discovery. Key insights that shaped this document:
 
@@ -140,3 +141,4 @@ See the insights document for complete decision rationale, alternatives consider
 
 **Approved by:** [Human's name or "Pending"]
 **Approval date:** [Date or "Pending"]
+**Status:** Draft