jumpstart-mode 1.0.6 → 1.0.8

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

@@ -0,0 +1,265 @@
+# Codebase Context
+
+> **Phase:** Pre-0 -- Reconnaissance
+> **Agent:** The Scout
+> **Status:** Draft
+> **Created:** [DATE]
+> **Approval date:** [DATE or "Pending"]
+> **Approved by:** [Human's name or "Pending"]
+
+---
+
+## Project Overview
+
+| Attribute | Detail |
+|-----------|--------|
+| **Project Name** | [Name from config or repository] |
+| **Primary Language(s)** | [e.g., TypeScript, Python, Go] |
+| **Framework(s)** | [e.g., Express, Django, React] |
+| **Build System** | [e.g., npm scripts, Makefile, Gradle] |
+| **Package Manager(s)** | [e.g., npm, pip, cargo] |
+| **Runtime** | [e.g., Node.js 20, Python 3.12, Go 1.22] |
+| **Repository Age** | [Approximate, from git history if available] |
+| **Approximate Size** | [Number of source files, lines of code if measurable] |
+
+---
+
+## Repository Structure
+
+```
+[project-root]/
+|-- [annotated directory tree]
+|-- [each directory with a brief purpose description]
+```
+
+### Directory Purposes
+
+| Directory | Purpose | Language(s) | Notable Files |
+|-----------|---------|-------------|---------------|
+| `[dir]` | [What this directory contains and its role] | [Language] | [Key files] |
+| | | | |
+
+---
+
+## Technology Stack
+
+| Category | Technology | Version | Role | Notes |
+|----------|-----------|---------|------|-------|
+| **Language** | [e.g., TypeScript] | [e.g., 5.x] | Primary application language | |
+| **Runtime** | [e.g., Node.js] | [e.g., 20 LTS] | Server runtime | |
+| **Framework** | [e.g., Express] | [e.g., 4.18] | HTTP server framework | |
+| **Database** | [e.g., PostgreSQL] | [e.g., 16] | Primary data store | |
+| **ORM** | [e.g., Prisma] | [e.g., 5.x] | Database access layer | |
+| **Testing** | [e.g., Jest] | [e.g., 29.x] | Test framework | |
+| **Linting** | [e.g., ESLint] | | Code quality | |
+| **CI/CD** | [e.g., GitHub Actions] | | Continuous integration | |
+
+[Add or remove rows as appropriate.]
+
+---
+
+## Dependencies
+
+### Production Dependencies
+
+| Package | Version | Category | Role |
+|---------|---------|----------|------|
+| [package-name] | [version] | Core / Database / Auth / UI / Utility | [What it does in this project] |
+| | | | |
+
+### Development Dependencies
+
+| Package | Version | Category | Role |
+|---------|---------|----------|------|
+| [package-name] | [version] | Testing / Build / Linting / Tooling | [What it does] |
+| | | | |
+
+### Dependency Observations
+
+[Notes about dependency health, outdated packages, version pinning strategies, or notable gaps.]
+
+---
+
+## External Integrations
+
+| System / Service | Type | Protocol | Purpose | Configuration |
+|-----------------|------|----------|---------|---------------|
+| [e.g., Stripe API] | Third-party API | REST/HTTPS | Payment processing | `STRIPE_API_KEY` env var |
+| [e.g., PostgreSQL] | Database | TCP/SQL | Primary data store | `DATABASE_URL` env var |
+| [e.g., Redis] | Cache | TCP | Session/cache store | `REDIS_URL` env var |
+| | | | | |
+
+---
+
+## C4 Architecture Diagrams
+
+### 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)]
+```
+
+[Description of what this diagram shows — the system boundary and external actors.]
+
+---
+
+### 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
+```
+
+[Description of the major deployable containers within the system.]
+
+---
+
+### 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
+```
+
+[Description of internal components within the primary container.]
+
+---
+
+### Code Diagram (Level 4) — If Configured
+
+[Include only if `c4_levels` includes `code`. Focus on the most critical or complex modules.]
+
+---
+
+## Code Patterns and Conventions
+
+### File Organization
+
+| Pattern | Convention | Example |
+|---------|-----------|---------|
+| **File naming** | [kebab-case / camelCase / PascalCase / snake_case] | [e.g., `user-service.ts`] |
+| **Directory structure** | [Feature-based / Layer-based / Hybrid] | [e.g., `src/features/auth/`] |
+| **Test location** | [Co-located / Separate tree / Both] | [e.g., `__tests__/` next to source] |
+| **Config files** | [Root / Dedicated config dir] | [e.g., `.env`, `config/`] |
+
+### Coding Patterns
+
+| Pattern | Approach | Notes |
+|---------|----------|-------|
+| **Error handling** | [Exceptions / Result types / Error codes / Error-first callbacks] | |
+| **Async model** | [async/await / Promises / Callbacks / Goroutines] | |
+| **Dependency injection** | [Constructor / Framework DI / Module imports / None] | |
+| **Logging** | [Library name and approach, e.g., "Winston, structured JSON"] | |
+| **Input validation** | [Library or approach, e.g., "Joi schemas at controller layer"] | |
+| **State management** | [Approach if frontend, e.g., "Redux Toolkit"] | |
+
+### Testing Patterns
+
+| Aspect | Convention |
+|--------|-----------|
+| **Test framework** | [e.g., Jest, pytest, Go testing] |
+| **Test naming** | [e.g., `describe/it`, `test_function_name`, `TestFunctionName`] |
+| **Mocking approach** | [e.g., jest.mock, unittest.mock, testify/mock] |
+| **Test data** | [Fixtures / Factories / Inline / Seed files] |
+| **Coverage** | [Approximate coverage level if measurable] |
+
+---
+
+## Existing Documentation
+
+| Document | Location | Status | Notes |
+|----------|----------|--------|-------|
+| README | [path] | [Current / Outdated / Minimal] | [Brief assessment] |
+| API docs | [path or URL] | [Current / Outdated / Missing] | |
+| Architecture docs | [path] | [Current / Outdated / Missing] | |
+| Contributing guide | [path] | [Exists / Missing] | |
+| AGENTS.md / AI instructions | [path] | [Exists / Missing] | |
+
+---
+
+## Technical Debt and Observations
+
+> **Note:** These are observations, not recommendations. The Scout documents what it sees without prescribing changes.
+
+### Structural Observations
+
+- [Observation about code organization, module boundaries, or file structure]
+- [e.g., "The `utils/` directory contains 47 files with varied purposes, suggesting it may benefit from sub-categorization"]
+
+### Code Quality Observations
+
+- [Observation about patterns, consistency, or notable code characteristics]
+- [e.g., "Error handling is inconsistent: controllers use try/catch, services use error callbacks"]
+
+### Test Coverage Observations
+
+- [Observation about which areas are well-tested vs. under-tested]
+- [e.g., "Unit tests exist for all service modules; no integration or e2e tests found"]
+
+### Security Observations
+
+- [Observation about security-relevant patterns]
+- [e.g., "Authentication middleware is applied per-route rather than globally"]
+
+### TODO/FIXME/HACK Comments
+
+| File | Line | Comment | Category |
+|------|------|---------|----------|
+| [path] | [line] | [The comment text] | TODO / FIXME / HACK |
+| | | | |
+
+[Include only notable or high-impact comments, not an exhaustive list.]
+
+---
+
+## Key Files Reference
+
+| File | Purpose | Importance |
+|------|---------|------------|
+| [path] | [What this file does — entry point, config, core logic, etc.] | Critical / High / Medium |
+| | | |
+
+---
+
+## Insights Reference
+
+**Companion Document:** [specs/insights/codebase-context-insights.md](insights/codebase-context-insights.md)
+
+This artifact was informed by ongoing insights captured during reconnaissance. Key insights:
+
+1. **[Brief insight title]** - [One sentence summary]
+2. **[Brief insight title]** - [One sentence summary]
+3. **[Brief insight title]** - [One sentence summary]
+
+See the insights document for complete observation rationale, ambiguities encountered, and patterns discovered.
+
+---
+
+## Phase Gate Approval
+
+- [ ] Repository structure has been mapped and annotated
+- [ ] Dependencies have been cataloged with categories and versions
+- [ ] C4 diagrams have been generated at configured levels
+- [ ] Code patterns and conventions have been documented
+- [ ] The human has reviewed and approved this document
+
+**Approved by:** [Human's name or "Pending"]
+**Approval date:** [Date or "Pending"]
+**Status:** Draft

package/.jumpstart/templates/implementation-plan.md

@@ -2,12 +2,13 @@
 
 > **Phase:** 3 -- Solutioning (output) / Phase 4 -- Implementing (working document)
 > **Agent:** Generated by The Architect, executed by The Developer
-> **Status:** Draft | Approved | In Progress | Complete
+> **Status:** Draft
 > **Created:** [DATE]
-> **Approved:** [DATE or pending]
+> **Approval date:** [DATE or "Pending"]
+> **Approved by:** [Human's name or "Pending"]
 > **Upstream References:**
-> - [specs/prd.md](../prd.md)
-> - [specs/architecture.md](../architecture.md)
+> - [specs/prd.md](prd.md)
+> - [specs/architecture.md](architecture.md)
 
 ---
 
@@ -28,6 +29,9 @@
 |--------|---------|
 | `[S]` | Sequential -- must complete before the next task can begin |
 | `[P]` | Parallelizable -- can run alongside other `[P]` tasks in the same group |
+| `[R]` | Refactoring -- modifies existing code without changing behavior (brownfield) |
+| `[M]` | Migration -- data or schema migration task (brownfield) |
+| `[D]` | Documentation -- creates or updates AGENTS.md or other documentation files (greenfield) |
 | `[PENDING]` | Not yet started |
 | `[IN PROGRESS]` | Currently being implemented |
 | `[COMPLETE]` | Finished and verified |
@@ -200,7 +204,7 @@ Document any deviations from the original plan during implementation.
 
 ## Insights Reference
 
-**Companion Document:** [specs/insights/implementation-plan-insights.md](../insights/implementation-plan-insights.md)
+**Companion Document:** [specs/insights/implementation-plan-insights.md](insights/implementation-plan-insights.md)
 
 This artifact was informed by ongoing insights captured during Solutioning and Implementation. Key insights that shaped this document:
 

package/.jumpstart/templates/insights.md

@@ -2,7 +2,7 @@
 
 > **Phase:** [0-4] -- [Phase Name]
 > **Agent:** [Agent Name]
-> **Parent Artifact:** [`specs/[artifact-name].md`](specs/[artifact-name].md)
+> **Parent Artifact:** [`specs/[artifact-name].md`](../[artifact-name].md)
 > **Created:** [DATE]
 > **Last Updated:** [DATE]
 
@@ -49,9 +49,9 @@ You can record different kinds of insights. Here are some common types, but don'
 When an insight relates to a specific section of the parent artifact, link to it:
 
 ```markdown
-→ See [Problem Statement](specs/challenger-brief.md#reframed-problem-statement)
-→ Related to [User Persona 2](specs/product-brief.md#user-personas)
-→ Influences [Architecture Decision 003](specs/decisions/003-api-design.md)
+→ See [Problem Statement](../challenger-brief.md#reframed-problem-statement)
+→ Related to [User Persona 2](../product-brief.md#user-personas)
+→ Influences [Architecture Decision 003](../decisions/003-api-design.md)
 ```
 
 ### Timestamps
@@ -122,8 +122,8 @@ During assumption surfacing, the human initially framed the problem as "develope
 This realization shifted the problem from "ongoing inefficiency" to "high-friction project initialization." The scope and solution implications are very different.
 
 **Cross-references:**
-- [Assumption #3](specs/challenger-brief.md#assumptions-identified) captured this shift
-- [Reframed Problem Statement](specs/challenger-brief.md#reframed-problem-statement) now focuses on "project setup friction"
+- [Assumption #3](../challenger-brief.md#assumptions-identified) captured this shift
+- [Reframed Problem Statement](../challenger-brief.md#reframed-problem-statement) now focuses on "project setup friction"
 
 ---
 
@@ -140,7 +140,7 @@ The human chose to follow the organizational path, which revealed that the root
 I noted the tooling branch as "Alternative thread" in the brief—it might resurface during architecture phase.
 
 **Cross-references:**
-- [Root Cause Analysis](specs/challenger-brief.md#root-cause-analysis-five-whys)
+- [Root Cause Analysis](../challenger-brief.md#root-cause-analysis-five-whys)
 
 ---
 
@@ -157,8 +157,8 @@ While synthesizing interview notes (simulated), I noticed a third distinct behav
 This persona has inverse priorities: they *want* more friction at setup to ensure compliance. Including them changes the requirements—solution needs configuration/policy layer, not just speed.
 
 **Cross-references:**
-- Added as [Persona 3: Platform Engineer](specs/product-brief.md#user-personas)
-- Impacts [Feature Priority](specs/product-brief.md#feature-prioritization)—audit/compliance features elevated
+- Added as [Persona 3: Platform Engineer](../product-brief.md#user-personas)
+- Impacts [Feature Priority](../product-brief.md#feature-prioritization)—audit/compliance features elevated
 
 ---
 
@@ -175,7 +175,7 @@ This could be a meaningful differentiation point—not just templates, but *opin
 Noted as open question for PM phase to address with proposed value prop testing.
 
 **Cross-references:**
-- [Competitive Analysis](specs/product-brief.md#competitive-landscape)
+- [Competitive Analysis](../product-brief.md#competitive-landscape)
 
 ---
 
@@ -197,8 +197,8 @@ Decision: defer all advanced customization to v2. MVP will be opinionated by def
 Trade-off acknowledged: loses Platform Engineer as primary MVP audience. They become secondary (can still use, but won't get custom policy enforcement).
 
 **Cross-references:**
-- [MVP Scope](specs/prd.md#mvp-scope)
-- [Persona 3 deprioritized rationale](specs/prd.md#out-of-scope)
+- [MVP Scope](../prd.md#mvp-scope)
+- [Persona 3 deprioritized rationale](../prd.md#out-of-scope)
 
 ---
 
@@ -215,7 +215,7 @@ Problem: "active" is vague. Active in what sense? Commits? Deploys? Team still e
 Alternative: "Users report 50% reduction in setup time" (survey-based, direct). Suggested we use both: time saved (short-term) and project longevity (long-term quality signal).
 
 **Cross-references:**
-- [Success Metrics](specs/prd.md#success-metrics)—now includes both
+- [Success Metrics](../prd.md#success-metrics)—now includes both
 
 ---
 
@@ -243,8 +243,8 @@ Reasoning:
 Trade-off: Hard to add community-contributed templates without code changes. Acceptable for MVP.
 
 **Cross-references:**
-- [Architecture Decision Record 004](specs/decisions/004-template-storage.md)
-- [Component: Template Engine](specs/architecture.md#component-template-engine)
+- [Architecture Decision Record 004](../decisions/004-template-storage.md)
+- [Component: Template Engine](../architecture.md#component-template-engine)
 
 ---
 
@@ -266,8 +266,8 @@ Options:
 Chose #1 + note to revisit in developer phase. Flagged as performance testing requirement in implementation plan.
 
 **Cross-references:**
-- [Performance Requirements](specs/architecture.md#non-functional-requirements)
-- [Implementation Task: Optimize File I/O](specs/implementation-plan.md#phase-1-tasks)
+- [Performance Requirements](../architecture.md#non-functional-requirements)
+- [Implementation Task: Optimize File I/O](../implementation-plan.md#phase-1-tasks)
 
 ---
 
@@ -310,7 +310,7 @@ Trade-off: if we expand CLI to 10+ commands later, we might regret this. For MVP
 
 **Cross-references:**
 - [Implementation: CLI module](src/cli.js)
-- [Dependency Justification](specs/architecture.md#external-dependencies)—updated to remove yargs
+- [Dependency Justification](../architecture.md#external-dependencies)—updated to remove yargs
 
 ---
 

package/.jumpstart/templates/prd.md

@@ -2,12 +2,13 @@
 
 > **Phase:** 2 -- Planning
 > **Agent:** The Product Manager
-> **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/challenger-brief.md](challenger-brief.md)
+> - [specs/product-brief.md](product-brief.md)
 
 ---
 
@@ -346,7 +347,7 @@ Polish (Phase N)
 ---
 ## Insights Reference
 
-**Companion Document:** [specs/insights/prd-insights.md](../insights/prd-insights.md)
+**Companion Document:** [specs/insights/prd-insights.md](insights/prd-insights.md)
 
 This artifact was informed by ongoing insights captured during Planning. Key insights that shaped this document:
 
@@ -373,3 +374,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/product-brief.md

@@ -2,10 +2,11 @@
 
 > **Phase:** 1 -- Analysis
 > **Agent:** The Analyst
-> **Status:** Draft | Approved
+> **Status:** Draft
 > **Created:** [DATE]
-> **Approved:** [DATE or pending]
-> **Upstream Reference:** [specs/challenger-brief.md](../challenger-brief.md)
+> **Approval date:** [DATE or "Pending"]
+> **Approved by:** [Human's name or "Pending"]
+> **Upstream Reference:** [specs/challenger-brief.md](challenger-brief.md)
 
 ---
 
@@ -176,7 +177,7 @@ Capabilities explicitly excluded from this effort. Documenting these is as impor
 
 ## Insights Reference
 
-**Companion Document:** [specs/insights/product-brief-insights.md](../insights/product-brief-insights.md)
+**Companion Document:** [specs/insights/product-brief-insights.md](insights/product-brief-insights.md)
 
 This artifact was informed by ongoing insights captured during Analysis. Key insights that shaped this document:
 
@@ -200,3 +201,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/roadmap.md

@@ -0,0 +1,79 @@
+# [PROJECT_NAME] 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. [PRINCIPLE_1_NAME]
+<!-- Example: Sequential Phase Integrity -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: 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. -->
+
+### II. [PRINCIPLE_2_NAME]
+<!-- Example: Template Compliance -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: All output artifacts must be generated using the markdown templates
+in `.jumpstart/templates/`. Agents must not invent new document formats or omit
+required template sections. -->
+
+### III. [PRINCIPLE_3_NAME]
+<!-- Example: Test-First Development (when enabled) -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: When `roadmap.test_drive_mandate` is `true` in config, the Developer
+agent must write failing tests first, present them for human approval, and only then
+write implementation code. No source code may be written for a task until its tests
+exist and the human has confirmed them. -->
+
+### IV. [PRINCIPLE_4_NAME]
+<!-- Example: Upstream Traceability -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Every requirement, story, and task must trace back to an upstream artifact.
+PRD stories reference Product Brief capabilities. Product Brief capabilities reference
+Challenger Brief validation criteria. No orphan requirements are permitted. -->
+
+### V. [PRINCIPLE_5_NAME]
+<!-- Example: Human Gate Authority -->
+[PRINCIPLE_5_DESCRIPTION]
+<!-- Example: No agent may mark a phase as complete or approve its own output. All phase
+transitions require explicit human approval. The human operator is the sole authority
+on artifact acceptance. -->
+
+---
+
+## [SECTION_2_NAME]
+<!-- Example: Additional Constraints, Security Requirements, Compliance Standards, etc. -->
+
+[SECTION_2_CONTENT]
+<!-- Example: Technology stack restrictions, data privacy requirements, deployment
+policies, regulatory compliance standards, etc. -->
+
+---
+
+## [SECTION_3_NAME]
+<!-- Example: Development Workflow, Quality Gates, Review Process, etc. -->
+
+[SECTION_3_CONTENT]
+<!-- Example: Code review requirements, testing gates, deployment approval process,
+documentation standards, etc. -->
+
+---
+
+## Governance
+
+<!-- The Roadmap supersedes all other agent protocols and practices.
+Amendments to a Core Principle require:
+1. A written proposal with rationale
+2. Explicit human approval
+3. A migration plan for any affected artifacts or processes
+Roadmap violations must always be reported to the human, never silently ignored. -->
+
+[GOVERNANCE_RULES]
+
+---
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- Example: Version: 1.0.0 | Ratified: 2026-02-08 | Last Amended: 2026-02-08 -->

package/AGENTS.md

@@ -4,29 +4,46 @@
 
 ## Workflow Overview
 
-The development lifecycle follows five strict, sequential phases. No phase may begin until the previous phase's artifact is **explicitly approved** by the human operator.
+The development lifecycle follows strict, sequential phases. No phase may begin until the previous phase's artifact is **explicitly approved** by the human operator. For **brownfield** projects, a pre-phase Scout agent analyzes the existing codebase before Phase 0 begins.
 
 ```mermaid
 flowchart TB
+    CONST["Roadmap\n(.jumpstart/roadmap.md)"] -.->|governs all agents| P0
+    CONST -.->|governs all agents| P1
+    CONST -.->|governs all agents| P2
+    CONST -.->|governs all agents| P3
+    CONST -.->|governs all agents| P4
+    S[Pre-Phase: Scout] -.->|brownfield only| P0
     P0[Phase 0: Challenge] -->|Brief| P1[Phase 1: Analyze]
     P1 -->|Product Brief| P2[Phase 2: Plan]
     P2 -->|PRD| P3[Phase 3: Architect]
     P3 -->|Specs| P4[Phase 4: Build]
+    PM_PARTY["Party Mode\n(advisory)"] -.->|available anytime| P0
+    PM_PARTY -.->|available anytime| P1
+    PM_PARTY -.->|available anytime| P2
+    PM_PARTY -.->|available anytime| P3
+    PM_PARTY -.->|available anytime| P4
     
+    SC(Scout) -.-> S
     C(Challenger) -.-> P0
     A(Analyst) -.-> P1
     PM(Product Manager) -.-> P2
     Arch(Architect) -.-> P3
     Dev(Developer) -.-> P4
+    F(Facilitator) -.-> PM_PARTY
 
+    style S fill:#ff9800,stroke:#333,stroke-width:2px,color:#fff
     style P0 fill:#1976d2,stroke:#333,stroke-width:2px,color:#fff
     style P4 fill:#43a047,stroke:#333,stroke-width:2px,color:#fff
+    style CONST fill:#e53935,stroke:#333,stroke-width:2px,color:#fff
+    style PM_PARTY fill:#7b1fa2,stroke:#333,stroke-width:2px,color:#fff
 ```
 
 ## Agent Directory
 
 | Phase | Agent Persona | Activation Command | Primary Responsibility | Output Artifact |
 | --- | --- | --- | --- | --- |
+| **Pre-0** | **The Scout** | `/jumpstart.scout` | Analyzes existing codebase for brownfield projects. Creates C4 diagrams and context. | `specs/codebase-context.md` |
 | **0** | **The Challenger** | `/jumpstart.challenge` | Interrogates the problem, finds root causes, reframes assumptions. | `specs/challenger-brief.md` |
 | **1** | **The Analyst** | `/jumpstart.analyze` | Defines personas, user journeys, and MVP scope. | `specs/product-brief.md` |
 | **2** | **The PM** | `/jumpstart.plan` | Writes user stories, acceptance criteria, and NFRs. | `specs/prd.md` |
@@ -34,6 +51,7 @@ flowchart TB
 
 <br>`specs/implementation-plan.md` |
 | **4** | **The Developer** | `/jumpstart.build` | Writes code and tests according to the plan. | `src/`, `tests/`, `README.md` |
+| **Any** | **The Facilitator** | `/jumpstart.party` | Orchestrates multi-agent roundtable discussions. Advisory only. | None (insights only) |
 
 ---
 
@@ -47,6 +65,7 @@ All agents must follow these directives without exception.
 * **Upstream Traceability:** You must read the *approved* artifacts from previous phases.
 * *Analyst* reads *Challenger Brief*.
 * *Architect* reads *PRD*, *Product Brief*, and *Challenger Brief*.
+* **Brownfield Context:** If `project.type` is `brownfield`, all agents (Phase 0–4) must also read `specs/codebase-context.md` to understand the existing codebase.
 * Do not hallucinate requirements that contradict upstream documents.
 
 
@@ -54,10 +73,13 @@ All agents must follow these directives without exception.
 ### 2. The Execution Protocol
 
 * **Stay in Lane:**
+* The **Scout** only analyzes — it never proposes changes, new features, or solutions.
 * The **Challenger** never suggests solutions or technologies.
 * The **Analyst** never writes code or defines database schemas.
 * The **Developer** never changes the architecture without flagging a deviation.
 
+* **Greenfield AGENTS.md Files:** For greenfield projects, the **Architect** plans per-directory `AGENTS.md` files in the implementation plan, and the **Developer** creates and maintains them during scaffolding and task execution. These files provide AI-friendly context for each module.
+
 
 * **Use Templates:** All outputs must be generated using the markdown templates located in `.jumpstart/templates/`. Do not invent new document formats.
 * **Living Insights:** Simultaneously maintain your phase's `insights.md` file to log your reasoning, trade-offs, and discarded alternatives.
@@ -79,6 +101,14 @@ All agents must follow these directives without exception.
 * **Source Code:** Application code goes into `src/`.
 * **Tests:** Test code goes into `tests/`.
 
+### 5. The Roadmap Protocol
+
+* **Read on Activation:** Every agent must read `.jumpstart/roadmap.md` before generating any content.
+* **Non-Negotiable:** Roadmap principles supersede agent-specific instructions. If a protocol step conflicts with the Roadmap, the Roadmap wins.
+* **Article III (Test-First):** When `roadmap.test_drive_mandate` is `true` in `.jumpstart/config.yaml`, the Developer agent must follow strict Red-Green-Refactor TDD for every task.
+* **Amendments:** Only the human can amend the Roadmap. Agents may propose amendments in their insights files, but may not modify the Roadmap directly.
+* **Domain Awareness:** If `project.domain` is set in config, agents must consult `.jumpstart/domain-complexity.csv` for domain-specific concerns and adapt their outputs accordingly.
+
 ---
 
 ## Tool Usage (VS Code Copilot)

package/CLAUDE.md

@@ -6,11 +6,13 @@ This repository uses the Jump Start spec-driven agentic coding framework.
 
 | Command | Action |
 |---------|--------|
+| `/jumpstart.scout` | Check `project.type` is `brownfield`. Load `.jumpstart/agents/scout.md`. Follow Reconnaissance Protocol. Output to `specs/codebase-context.md`. |
 | `/jumpstart.challenge [idea]` | Load `.jumpstart/agents/challenger.md`. Follow the Elicitation Protocol. Output to `specs/challenger-brief.md`. |
 | `/jumpstart.analyze` | Verify Phase 0 approved. Load `.jumpstart/agents/analyst.md`. Output to `specs/product-brief.md`. |
 | `/jumpstart.plan` | Verify Phases 0-1 approved. Load `.jumpstart/agents/pm.md`. Output to `specs/prd.md`. |
 | `/jumpstart.architect` | Verify Phases 0-2 approved. Load `.jumpstart/agents/architect.md`. Output to `specs/architecture.md`, `specs/implementation-plan.md`, `specs/decisions/*.md`. |
 | `/jumpstart.build` | Verify Phases 0-3 approved. Load `.jumpstart/agents/developer.md`. Output code to `src/`, tests to `tests/`. |
+| `/jumpstart.party` | Load `.jumpstart/agents/facilitator.md`. Launch multi-agent roundtable discussion. Advisory only — no artifact writes. |
 | `/jumpstart.status` | Read config and all spec files. Report phase completion status. |
 | `/jumpstart.review` | Validate current artifacts against templates. Report gaps. |
 
@@ -21,3 +23,4 @@ This repository uses the Jump Start spec-driven agentic coding framework.
 3. Always ask for explicit human approval before phase transitions.
 4. Use templates from `.jumpstart/templates/`.
 5. Read `.jumpstart/config.yaml` at the start of every command.
+6. Read `.jumpstart/roadmap.md` at activation. Roadmap principles are non-negotiable and supersede agent-specific instructions.