jumpstart-mode 1.0.5 → 1.0.7

package/AGENTS.md

@@ -1,28 +1,96 @@
 # Jump Start Framework -- Agent Instructions
 
-This repository uses the Jump Start spec-driven agentic coding framework. When performing tasks in this repository, follow these rules.
+> **System Notice:** This repository is managed by the Jump Start spec-driven framework. All AI agents operating in this context must adhere strictly to the protocols defined below.
 
-## Workflow
+## Workflow Overview
 
-Five sequential phases, each with a dedicated agent persona in `.jumpstart/agents/`:
+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.
 
-| Phase | Agent | Command | Output |
-|-------|-------|---------|--------|
-| 0 | Challenger | Select "Jump Start: Challenger" agent | `specs/challenger-brief.md` |
-| 1 | Analyst | Select "Jump Start: Analyst" agent | `specs/product-brief.md` |
-| 2 | PM | Select "Jump Start: PM" agent | `specs/prd.md` |
-| 3 | Architect | Select "Jump Start: Architect" agent | `specs/architecture.md`, `specs/implementation-plan.md`, `specs/decisions/*.md` |
-| 4 | Developer | Select "Jump Start: Developer" agent | `src/`, `tests/`, `README.md` |
+```mermaid
+flowchart TB
+    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]
+    
+    C(Challenger) -.-> P0
+    A(Analyst) -.-> P1
+    PM(Product Manager) -.-> P2
+    Arch(Architect) -.-> P3
+    Dev(Developer) -.-> P4
 
-## Rules
+    style P0 fill:#1976d2,stroke:#333,stroke-width:2px,color:#fff
+    style P4 fill:#43a047,stroke:#333,stroke-width:2px,color:#fff
+```
 
-1. **Sequential enforcement.** Do not start a phase unless all preceding artifacts exist and are approved.
-2. **Agent fidelity.** When operating as a specific agent, load and follow `.jumpstart/agents/<agent>.md` exactly.
-3. **Human gates.** Never auto-approve phase transitions. Always present the artifact and ask for explicit approval.
-4. **Templates.** Use `.jumpstart/templates/` for all artifact structures.
-5. **Config.** Read `.jumpstart/config.yaml` at the start of every phase.
-6. **Artifact locations.** Specs go in `specs/`. ADRs in `specs/decisions/`. Code in `src/`. Tests in `tests/`.
+## Agent Directory
 
-## Checking Approval
+| Phase | Agent Persona | Activation Command | Primary Responsibility | Output Artifact |
+| --- | --- | --- | --- | --- |
+| **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` |
+| **3** | **The Architect** | `/jumpstart.architect` | Selects tech stack, models data, designs APIs, plans tasks. | `specs/architecture.md`<br>
 
-An artifact is approved when its Phase Gate Approval section has all checkboxes checked and "Approved by" is not "Pending".
+<br>`specs/implementation-plan.md` |
+| **4** | **The Developer** | `/jumpstart.build` | Writes code and tests according to the plan. | `src/`, `tests/`, `README.md` |
+
+---
+
+## Operational Protocols
+
+All agents must follow these directives without exception.
+
+### 1. The Context Protocol
+
+* **Read Before Write:** Before generating any content, you must read `.jumpstart/config.yaml` and the specific agent instruction file in `.jumpstart/agents/`.
+* **Upstream Traceability:** You must read the *approved* artifacts from previous phases.
+* *Analyst* reads *Challenger Brief*.
+* *Architect* reads *PRD*, *Product Brief*, and *Challenger Brief*.
+* Do not hallucinate requirements that contradict upstream documents.
+
+
+
+### 2. The Execution Protocol
+
+* **Stay in Lane:**
+* 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.
+
+
+* **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.
+
+### 3. The Gate Protocol
+
+* **No Auto-Approval:** You cannot mark a phase as complete. You must present the final artifact to the human and ask: *"Does this meet your expectations?"*
+* **Checkboxes Matter:** An artifact is only considered "Approved" when:
+1. The `Phase Gate Approval` section at the bottom of the file is filled.
+2. All checkboxes in that section are marked `[x]`.
+3. The "Approved by" field is not "Pending".
+
+
+
+### 4. The Artifact Protocol
+
+* **Specs Location:** All documentation goes into `specs/`.
+* **Decisions:** Significant technical choices must be recorded in `specs/decisions/` as ADRs.
+* **Source Code:** Application code goes into `src/`.
+* **Tests:** Test code goes into `tests/`.
+
+---
+
+## Tool Usage (VS Code Copilot)
+
+If running within VS Code Copilot, agents have access to native UI tools:
+
+* **`ask_questions`:** Use this to present multiple-choice decisions to the user (e.g., selecting a tech stack or prioritizing a feature).
+* **`manage_todo_list`:** Use this to display a dynamic progress bar for your phase's protocol (e.g., "Step 3 of 8: User Journey Mapping").
+
+---
+
+## Troubleshooting
+
+* **Missing Context:** If an upstream artifact is missing (e.g., running `/jumpstart.plan` before Phase 1 is done), **stop** and instruct the user to complete the missing phase first.
+* **Ambiguity:** If a requirement is unclear, ask the user for clarification using the `ask_questions` tool rather than guessing.

package/README.md

@@ -1,22 +1,48 @@
-# Jump Start
+# ⚡ Jump Start
 
-A spec-driven agentic coding framework that transforms a raw idea into production-ready code through five sequential phases. Each phase is owned by a specialized AI agent. Every artifact lives in your repository, version-controlled and accessible.
+![Version](https://img.shields.io/npm/v/jumpstart-mode?style=flat-square)
+![License](https://img.shields.io/npm/l/jumpstart-mode?style=flat-square)
+![Node](https://img.shields.io/node/v/jumpstart-mode?style=flat-square)
+
+**A spec-driven agentic coding framework that transforms a raw idea into production-ready code through five sequential, AI-governed phases.**
+
+Every artifact lives in your repository, version-controlled, diffable, and transparent.
 
 ---
 
-## How It Works
+## Table of Contents
+- [How It Works](#how-it-works)
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [Example Workflow](#example-workflow)
+- [Commands](#commands)
+- [Configuration](#configuration)
+- [Project Structure](#project-structure)
+- [Living Insights](#living-insights)
+- [VS Code Chat Features](#vs-code-chat-features)
+- [Troubleshooting](#troubleshooting)
 
-Jump Start runs five phases in a strict sequence. Each phase produces Markdown artifacts that become the input for the next phase. A human gate sits between every phase transition.
+---
 
-```
-Phase 0         Phase 1        Phase 2       Phase 3          Phase 4
-Challenge  -->  Analyze   -->  Plan     -->  Architect   -->  Build
-(Challenger)    (Analyst)      (PM)          (Architect)      (Developer)
-     |               |             |              |                |
-     v               v             v              v                v
-challenger-     product-       prd.md       architecture.md   src/
-brief.md        brief.md                    impl-plan.md      tests/
-                                            decisions/*.md    README.md
+## How It Works
+
+Jump Start runs five phases in a strict sequence. Each phase is owned by a specialized AI agent and produces Markdown artifacts that serve as the input for the next phase. A human gate sits between every transition to ensure quality.
+
+```mermaid
+flowchart TB
+    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]
+    
+    C(Challenger) -.-> P0
+    A(Analyst) -.-> P1
+    PM(Product Manager) -.-> P2
+    Arch(Architect) -.-> P3
+    Dev(Developer) -.-> P4
+
+    style P0 fill:#1976d2,stroke:#333,stroke-width:2px,color:#fff
+    style P4 fill:#43a047,stroke:#333,stroke-width:2px,color:#fff
 ```
 
 **Phase 0 -- Problem Discovery.** The Challenger agent interrogates your idea, surfaces hidden assumptions, drills to root causes, and produces a validated problem statement.
@@ -93,7 +119,7 @@ This creates the full directory structure, all agent definitions, templates, and
 
 ### 2. Configure
 
-Edit `.jumpstart/config.yaml` to customise agent behaviour, story format, prioritisation method, and other settings. The file is self-documenting with inline comments.
+Edit `.jumpstart/config.yaml` to customise agent behavior, story format, prioritization method, and other settings. The file is self-documenting with inline comments.
 
 ### 3. Run
 
@@ -225,7 +251,7 @@ Insights live in `specs/insights/` with a 1:1 relationship to primary artifacts:
 specs/insights/
 ├── challenger-brief-insights.md      # Phase 0: Problem discovery reasoning
 ├── product-brief-insights.md         # Phase 1: Analysis explorations and trade-offs
-├── prd-insights-md                  # Phase 2: Planning decisions and story prioritisation
+├── prd-insights.md                  # Phase 2: Planning decisions and story prioritization
 ├── architecture-insights.md          # Phase 3: Technical choices and design trade-offs
 └── implementation-plan-insights.md   # Phase 4: Implementation learnings and gotchas
 ```
@@ -320,14 +346,14 @@ This creates a **two-way knowledge graph** between formal specs and informal rea
 
 ## Configuration
 
-The `.jumpstart/config.yaml` file controls framework behaviour. Key settings:
+The `.jumpstart/config.yaml` file controls framework behavior. Key settings:
 
 **Workflow:**
 - `require_gate_approval`: Enforce human approval between phases (default: true)
 - `allow_phase_skip`: Allow jumping to later phases (default: false)
 
 **Agents:**
-- Each agent has configurable settings (elicitation depth, story format, prioritisation method, diagram format, test framework, etc.)
+- Each agent has configurable settings (elicitation depth, story format, prioritization method, diagram format, test framework, etc.)
 
 **Integrations:**
 - `ai_assistant`: Which AI tool you're using (copilot, claude-code, cursor, gemini, windsurf)
@@ -466,7 +492,7 @@ vscode_tools:
 ### Adding Custom Agents
 
 Create a new agent file in `.jumpstart/agents/` following the pattern of the existing agents:
-- Define the agent's identity, mandate, and behavioural guidelines
+- Define the agent's identity, mandate, and behavioral guidelines
 - Specify its input context (which artifacts it reads)
 - Define its protocol (step-by-step instructions)
 - Specify its output (which artifacts it produces)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jumpstart-mode",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Spec-driven agentic coding framework that transforms ideas into production code through AI-powered sequential phases",
   "keywords": [
     "jumpstart",