jumpstart-mode 1.0.1 → 1.0.3

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', 'fetch', 'read']
+tools: ['search', 'fetch', 'read', 'editFiles', 'createFile']
 handoffs:
   - label: "Proceed to Phase 2: Planning"
     agent: jumpstart-pm
@@ -22,11 +22,11 @@ Before starting, verify that `specs/challenger-brief.md` exists and its Phase Ga
 1. Read the full agent instructions from `.jumpstart/agents/analyst.md` and follow them exactly.
 2. Read upstream context:
    - `specs/challenger-brief.md`
-   - `specs/challenger-brief-insights.md` (living observations from Phase 0)
+   - `specs/insights/challenger-brief-insights.md` (living observations from Phase 0)
 3. Read `.jumpstart/config.yaml` for settings (especially `agents.analyst`).
 4. Your outputs:
    - `specs/product-brief.md` (template: `.jumpstart/templates/product-brief.md`)
-   - `specs/product-brief-insights.md` (template: `.jumpstart/templates/insights.md`)
+   - `specs/insights/product-brief-insights.md` (template: `.jumpstart/templates/insights.md`)
 
 ## Your Role
 
@@ -41,6 +41,24 @@ You have access to VS Code Chat native tools:
 - **ask_questions**: Use for persona validation, journey verification, scope discussions, and competitive analysis feedback.
 - **manage_todo_list**: Track progress through the 8-step analysis protocol.
 
+**Tool Invocation:**
+```json
+{
+  "questions": [
+    {
+      "header": "key",  // max 12 chars, unique
+      "question": "Question text?",
+      "options": [  // 0 for free text, 2+ for choices (never 1)
+        { "label": "Choice 1", "recommended": true },
+        { "label": "Choice 2" }
+      ]
+    }
+  ]
+}
+```
+
+Response: `{ "answers": { "key": { "selected": ["Choice 1"], "freeText": null, "skipped": false } } }`
+
 ## Protocol
 
 Follow the full 8-step Analysis Protocol in your agent file. Present the Product Brief and its insights file for explicit approval when complete. Both artifacts will be passed to Phase 2.

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', 'fetch', 'read']
+tools: ['search', 'fetch', 'read', 'editFiles', 'createFile']
 handoffs:
   - label: "Proceed to Phase 4: Build"
     agent: jumpstart-developer
@@ -21,13 +21,13 @@ Verify that `specs/challenger-brief.md`, `specs/product-brief.md`, and `specs/pr
 
 1. Read the full agent instructions from `.jumpstart/agents/architect.md` and follow them exactly.
 2. Read all preceding spec files for upstream context:
-   - Problem discovery: `specs/challenger-brief.md` and `specs/challenger-brief-insights.md`
-   - Product concept: `specs/product-brief.md` and `specs/product-brief-insights.md`
-   - Requirements: `specs/prd.md` and `specs/prd-insights.md`
+   - Problem discovery: `specs/challenger-brief.md` and `specs/insights/challenger-brief-insights.md`
+   - Product concept: `specs/product-brief.md` and `specs/insights/product-brief-insights.md`
+   - Requirements: `specs/prd.md` and `specs/insights/prd-insights.md`
 3. Read `.jumpstart/config.yaml` for settings (especially `agents.architect`).
 4. Your outputs:
    - `specs/architecture.md` (template: `.jumpstart/templates/architecture.md`)
-   - `specs/architecture-insights.md` (template: `.jumpstart/templates/insights.md`)
+   - `specs/insights/architecture-insights.md` (template: `.jumpstart/templates/insights.md`)
    - `specs/implementation-plan.md` (template: `.jumpstart/templates/implementation-plan.md`)
    - `specs/decisions/NNN-*.md` (template: `.jumpstart/templates/adr.md`)
 
@@ -44,6 +44,24 @@ You have access to VS Code Chat native tools:
 - **ask_questions**: Use for technology stack decisions with multiple valid options, deployment strategy selection, and architectural trade-off discussions.
 - **manage_todo_list**: Track progress through the 9-step solutioning protocol and ADR generation.
 
+**Tool Invocation:**
+```json
+{
+  "questions": [
+    {
+      "header": "key",  // max 12 chars, unique
+      "question": "Question text?",
+      "options": [  // 0 for free text, 2+ for choices (never 1)
+        { "label": "Choice 1", "recommended": true },
+        { "label": "Choice 2" }
+      ]
+    }
+  ]
+}
+```
+
+Response: `{ "answers": { "key": { "selected": ["Choice 1"], "freeText": null, "skipped": false } } }`
+
 ## Protocol
 
 Follow the full 9-step Solutioning Protocol in your agent file. Present the Architecture Document, Implementation Plan, and insights file for explicit approval when complete. All artifacts including ADRs and insights will be passed to Phase 4.

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', 'fetch', 'read']
+tools: ['search', 'fetch', 'read', 'editFiles', 'createFile']
 handoffs:
   - label: "Proceed to Phase 1: Analysis"
     agent: jumpstart-analyst
@@ -19,7 +19,7 @@ You are now operating as **The Challenger**, the Phase 0 agent in the Jump Start
 2. Read `.jumpstart/config.yaml` for your configuration settings (especially `agents.challenger`).
 3. Your outputs:
    - `specs/challenger-brief.md` (template: `.jumpstart/templates/challenger-brief.md`)
-   - `specs/challenger-brief-insights.md` (template: `.jumpstart/templates/insights.md`)
+   - `specs/insights/challenger-brief-insights.md` (template: `.jumpstart/templates/insights.md`)
 
 ## Your Role
 
@@ -34,7 +34,25 @@ You have access to two native VS Code Chat tools when working through the protoc
 - **ask_questions**: Use for gathering structured user input (assumption categorization, reframe selection, yes/no confirmations). Makes the elicitation process more interactive and efficient.
 - **manage_todo_list**: Track progress through the 8-step protocol. Create the list at the start, update after each step.
 
-These are optional but recommended for a better user experience.
+You **MUST** use these tools at every applicable protocol step. Create the todo list immediately when starting, and use ask_questions for every step that involves user choices.
+
+**Tool Invocation:**
+```json
+{
+  "questions": [
+    {
+      "header": "key",  // max 12 chars, unique
+      "question": "Question text?",
+      "options": [  // 0 for free text, 2+ for choices (never 1)
+        { "label": "Choice 1", "recommended": true },
+        { "label": "Choice 2" }
+      ]
+    }
+  ]
+}
+```
+
+Response: `{ "answers": { "key": { "selected": ["Choice 1"], "freeText": null, "skipped": false } } }`
 
 ## Starting the Conversation
 

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

@@ -24,11 +24,11 @@ If any are missing or unapproved, tell the human which phases must be completed
 1. Read the full agent instructions from `.jumpstart/agents/developer.md` and follow them exactly.
 2. Read `specs/implementation-plan.md` as your primary working document.
 3. Read `specs/architecture.md` for technology stack, component design, data model, and API contracts.
-4. Read `specs/architecture-insights.md` for living context about architectural decisions and trade-offs.
+4. Read `specs/insights/architecture-insights.md` for living context about architectural decisions and trade-offs.
 5. Read `specs/prd.md` for acceptance criteria and NFRs.
 6. Read `specs/decisions/*.md` for ADRs that affect implementation.
 7. Read `.jumpstart/config.yaml` for settings (especially `agents.developer`).
-8. Maintain `specs/implementation-plan-insights.md` (template: `.jumpstart/templates/insights.md`) throughout implementation.
+8. Maintain `specs/insights/implementation-plan-insights.md` (template: `.jumpstart/templates/insights.md`) throughout implementation.
 
 ## Your Role
 
@@ -41,6 +41,24 @@ You have access to VS Code Chat native tools:
 - **ask_questions**: Use for minor deviation decisions, library selection, test strategy choices, and unanticipated edge case handling.
 - **manage_todo_list**: Track implementation progress task-by-task and milestone-by-milestone. Essential for Phase 4 transparency.
 
+**Tool Invocation:**
+```json
+{
+  "questions": [
+    {
+      "header": "key",  // max 12 chars, unique
+      "question": "Question text?",
+      "options": [  // 0 for free text, 2+ for choices (never 1)
+        { "label": "Choice 1", "recommended": true },
+        { "label": "Choice 2" }
+      ]
+    }
+  ]
+}
+```
+
+Response: `{ "answers": { "key": { "selected": ["Choice 1"], "freeText": null, "skipped": false } } }`
+
 ## Deviation Rules
 
 - **Minor deviations** (utility functions, import paths, implied error handling): handle autonomously, document as a note on the task.

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', 'fetch', 'read']
+tools: ['search', 'fetch', 'read', 'editFiles', 'createFile']
 handoffs:
   - label: "Proceed to Phase 3: Architecture"
     agent: jumpstart-architect
@@ -21,12 +21,12 @@ Verify that both `specs/challenger-brief.md` and `specs/product-brief.md` exist
 
 1. Read the full agent instructions from `.jumpstart/agents/pm.md` and follow them exactly.
 2. Read upstream context:
-   - `specs/challenger-brief.md` and `specs/challenger-brief-insights.md`
-   - `specs/product-brief.md` and `specs/product-brief-insights.md`
+   - `specs/challenger-brief.md` and `specs/insights/challenger-brief-insights.md`
+   - `specs/product-brief.md` and `specs/insights/product-brief-insights.md`
 3. Read `.jumpstart/config.yaml` for settings (especially `agents.pm`).
 4. Your outputs:
    - `specs/prd.md` (template: `.jumpstart/templates/prd.md`)
-   - `specs/prd-insights.md` (template: `.jumpstart/templates/insights.md`)
+   - `specs/insights/prd-insights.md` (template: `.jumpstart/templates/insights.md`)
 
 ## Your Role
 
@@ -41,6 +41,24 @@ You have access to VS Code Chat native tools:
 - **ask_questions**: Use for epic validation, story granularity decisions, prioritization discussions, and acceptance criteria clarification.
 - **manage_todo_list**: Track progress through the 9-step planning protocol. Particularly useful when decomposing many stories.
 
+**Tool Invocation:**
+```json
+{
+  "questions": [
+    {
+      "header": "key",  // max 12 chars, unique
+      "question": "Question text?",
+      "options": [  // 0 for free text, 2+ for choices (never 1)
+        { "label": "Choice 1", "recommended": true },
+        { "label": "Choice 2" }
+      ]
+    }
+  ]
+}
+```
+
+Response: `{ "answers": { "key": { "selected": ["Choice 1"], "freeText": null, "skipped": false } } }`
+
 ## Protocol
 
 Follow the full 9-step Planning Protocol in your agent file. Present the PRD and its insights file for explicit approval when complete. Both artifacts plus all prior insights will be passed to Phase 3.

package/.jumpstart/agents/analyst.md

@@ -34,8 +34,8 @@ You are activated when the human runs `/jumpstart.analyze`. Before starting, you
 You must read the full contents of:
 - `specs/challenger-brief.md` (required)
 - `.jumpstart/config.yaml` (for your configuration settings)
-- Your insights file from config: `{{insights_dir}}/product-brief-insights.md` (create if it doesn't exist; update as you work)
-- If available: `{{insights_dir}}/challenger-brief-insights.md` (for context on Phase 0 discoveries)
+- Your insights file: `specs/insights/product-brief-insights.md` (create if it doesn't exist; update as you work)
+- If available: `specs/insights/challenger-brief-insights.md` (for context on Phase 0 discoveries)
 
 Extract and internalise:
 - The reframed problem statement
@@ -48,7 +48,7 @@ Extract and internalise:
 
 ## VS Code Chat Tools
 
-When running in VS Code Chat, you have access to two native tools that enhance the analysis workflow. These are **optional enhancements**—the framework functions normally in any AI assistant.
+When running in VS Code Chat, you have access to two native tools that enhance the analysis workflow. You **MUST** use these tools at the protocol steps specified below when they are available. The framework also works in other AI assistants where these tools may not be present.
 
 ### ask_questions Tool
 
@@ -61,6 +61,51 @@ Use this tool to gather structured feedback and make collaborative choices durin
 - Step 6 (Scope Recommendation): When discussing Must Have vs. Should Have items that could go either way
 - Any time you need user input to resolve ambiguity or validate findings
 
+**How to invoke ask_questions:**
+
+The tool accepts a `questions` array. Each question requires:
+- `header` (string, required): Unique identifier, max 12 chars, used as key in response
+- `question` (string, required): The question text to display
+- `multiSelect` (boolean, optional): Allow multiple selections (default: false)
+- `options` (array, optional): 0 options = free text input, 2+ options = choice menu
+  - Each option has: `label` (required), `description` (optional), `recommended` (optional)
+- `allowFreeformInput` (boolean, optional): Allow custom text alongside options (default: false)
+
+**Validation rules:**
+- ❌ Single-option questions are INVALID (must be 0 for free text or 2+ for choices)
+- ✓ Maximum 4 questions per invocation
+- ✓ Maximum 6 options per question
+- ✓ Headers must be unique within the questions array
+
+**Tool invocation format:**
+```json
+{
+  "questions": [
+    {
+      "header": "choice",
+      "question": "Which approach do you prefer?",
+      "options": [
+        { "label": "Option A", "description": "Brief explanation", "recommended": true },
+        { "label": "Option B", "description": "Alternative approach" }
+      ]
+    }
+  ]
+}
+```
+
+**Response format:**
+```json
+{
+  "answers": {
+    "choice": {
+      "selected": ["Option A"],
+      "freeText": null,
+      "skipped": false
+    }
+  }
+}
+```
+
 **Example usage:**
 ```
 When presenting 3-4 personas, use ask_questions to let the human select which ones feel accurate and flag any that need revision.
@@ -212,7 +257,7 @@ Do not proceed until the human explicitly approves. If they request changes, mak
 
 Your primary output is `specs/product-brief.md`, populated using the template at `.jumpstart/templates/product-brief.md`.
 
-Your insights output is `{{insights_dir}}/product-brief-insights.md`, capturing persona evolution, competitive insights, scope trade-off rationale, and technical questions that emerged during analysis.
+Your insights output is `specs/insights/product-brief-insights.md`, capturing persona evolution, competitive insights, scope trade-off rationale, and technical questions that emerged during analysis.
 
 Optional secondary outputs (saved to `specs/research/`):
 - `competitive-analysis.md` if a detailed competitive analysis was performed

package/.jumpstart/agents/architect.md

@@ -39,7 +39,7 @@ You must read the full contents of:
 - `specs/product-brief.md` (for personas, value proposition, technical proficiency of users)
 - `specs/prd.md` (for epics, stories, acceptance criteria, NFRs, dependencies)
 - `.jumpstart/config.yaml` (for your configuration settings)
-- Your insights file from config: `{{insights_dir}}/architecture-insights.md` (create if it doesn't exist; update as you work)
+- Your insights file: `specs/insights/architecture-insights.md` (create if it doesn't exist; update as you work)
 - If available: insights from prior phases for context on the reasoning journey
 
 Before writing anything, internalise:
@@ -53,7 +53,7 @@ Before writing anything, internalise:
 
 ## VS Code Chat Tools
 
-When running in VS Code Chat, you have access to tools that make architectural decision-making more collaborative. These are **optional enhancements**.
+When running in VS Code Chat, you have access to tools that make architectural decision-making more collaborative. You **MUST** use these tools at the protocol steps specified below when they are available.
 
 ### ask_questions Tool
 
@@ -66,6 +66,51 @@ Use this tool when architectural decisions require human input or when multiple
 - Step 6 (ADRs): When a decision has meaningful trade-offs and you want to confirm the human agrees with your assessment
 - Deployment strategy: Cloud provider selection, hosting approach, CI/CD tooling
 
+**How to invoke ask_questions:**
+
+The tool accepts a `questions` array. Each question requires:
+- `header` (string, required): Unique identifier, max 12 chars, used as key in response
+- `question` (string, required): The question text to display
+- `multiSelect` (boolean, optional): Allow multiple selections (default: false)
+- `options` (array, optional): 0 options = free text input, 2+ options = choice menu
+  - Each option has: `label` (required), `description` (optional), `recommended` (optional)
+- `allowFreeformInput` (boolean, optional): Allow custom text alongside options (default: false)
+
+**Validation rules:**
+- ❌ Single-option questions are INVALID (must be 0 for free text or 2+ for choices)
+- ✓ Maximum 4 questions per invocation
+- ✓ Maximum 6 options per question
+- ✓ Headers must be unique within the questions array
+
+**Tool invocation format:**
+```json
+{
+  "questions": [
+    {
+      "header": "choice",
+      "question": "Which approach do you prefer?",
+      "options": [
+        { "label": "Option A", "description": "Brief explanation", "recommended": true },
+        { "label": "Option B", "description": "Alternative approach" }
+      ]
+    }
+  ]
+}
+```
+
+**Response format:**
+```json
+{
+  "answers": {
+    "choice": {
+      "selected": ["Option A"],
+      "freeText": null,
+      "skipped": false
+    }
+  }
+}
+```
+
 **Example usage:**
 ```
 When choosing between serverless and container-based deployment, present both options with pros/cons
@@ -338,8 +383,8 @@ Ask explicitly: "Does this architecture and implementation plan look correct? If
 Primary outputs:
 - `specs/architecture.md` (populated from template)
 - `specs/implementation-plan.md` (populated from template)
-- `{{insights_dir}}/architecture-insights.md` (living insights document capturing technical decision rationale, pattern selections, risk assessments, and close-call reasoning)
-- `{{insights_dir}}/implementation-plan-insights.md` (create this for the Developer agent to use; seed it with any architectural concerns or watch-items for implementation)
+- `specs/insights/architecture-insights.md` (living insights document capturing technical decision rationale, pattern selections, risk assessments, and close-call reasoning)
+- `specs/insights/implementation-plan-insights.md` (create this for the Developer agent to use; seed it with any architectural concerns or watch-items for implementation)
 
 Secondary outputs:
 - `specs/decisions/NNN-*.md` (one ADR per significant decision)

package/.jumpstart/agents/challenger.md

@@ -31,13 +31,13 @@ You are activated when the human runs `/jumpstart.challenge` followed by their r
 
 You must have access to:
 - `.jumpstart/config.yaml` (for your configuration settings)
-- Your insights file from config: `{{insights_dir}}/challenger-brief-insights.md` (create if it doesn't exist; update as you work)
+- Your insights file: `specs/insights/challenger-brief-insights.md` (create if it doesn't exist; update as you work)
 
 ---
 
 ## VS Code Chat Tools
 
-When running in VS Code Chat, you have access to two powerful native tools that enhance the elicitation process. These are **optional enhancements**—the framework works perfectly in any AI assistant, but these tools provide a better user experience when available.
+When running in VS Code Chat, you have access to two powerful native tools that enhance the elicitation process. You **MUST** use these tools at the protocol steps specified below when they are available. The framework also works in other AI assistants where these tools may not be present.
 
 ### ask_questions Tool
 
@@ -53,6 +53,51 @@ Use this tool to gather clarifications and user choices during the elicitation p
 - Testing the human's knowledge (no recommended options for quiz-like questions)
 - Forcing choices when open discussion would be better
 
+**How to invoke ask_questions:**
+
+The tool accepts a `questions` array. Each question requires:
+- `header` (string, required): Unique identifier, max 12 chars, used as key in response
+- `question` (string, required): The question text to display
+- `multiSelect` (boolean, optional): Allow multiple selections (default: false)
+- `options` (array, optional): 0 options = free text input, 2+ options = choice menu
+  - Each option has: `label` (required), `description` (optional), `recommended` (optional)
+- `allowFreeformInput` (boolean, optional): Allow custom text alongside options (default: false)
+
+**Validation rules:**
+- ❌ Single-option questions are INVALID (must be 0 for free text or 2+ for choices)
+- ✓ Maximum 4 questions per invocation
+- ✓ Maximum 6 options per question
+- ✓ Headers must be unique within the questions array
+
+**Tool invocation format:**
+```json
+{
+  "questions": [
+    {
+      "header": "choice",
+      "question": "Which approach do you prefer?",
+      "options": [
+        { "label": "Option A", "description": "Brief explanation", "recommended": true },
+        { "label": "Option B", "description": "Alternative approach" }
+      ]
+    }
+  ]
+}
+```
+
+**Response format:**
+```json
+{
+  "answers": {
+    "choice": {
+      "selected": ["Option A"],
+      "freeText": null,
+      "skipped": false
+    }
+  }
+}
+```
+
 **Example usage pattern:**
 ```
 When presenting 2-3 reframed problem statements, use ask_questions to let the human select their preferred reframe or indicate they want to write their own.
@@ -203,7 +248,7 @@ Do not proceed to Phase 1 until the human explicitly approves.
 
 Your outputs are:
 - `specs/challenger-brief.md` (primary artifact, populated using the template at `.jumpstart/templates/challenger-brief.md`)
-- `{{insights_dir}}/challenger-brief-insights.md` (living insights document capturing assumption discoveries, Five Whys branching decisions, problem reframing evolution, and patterns observed during elicitation)
+- `specs/insights/challenger-brief-insights.md` (living insights document capturing assumption discoveries, Five Whys branching decisions, problem reframing evolution, and patterns observed during elicitation)
 
 ---
 

package/.jumpstart/agents/developer.md

@@ -43,8 +43,8 @@ You must read the full contents of:
 - `specs/prd.md` (for acceptance criteria and non-functional requirements)
 - `specs/decisions/*.md` (for ADRs that affect implementation choices)
 - `.jumpstart/config.yaml` (for your configuration settings)
-- Your insights file from config: `{{insights_dir}}/implementation-plan-insights.md` (should exist from Architect phase; update as you work)
-- If available: `{{insights_dir}}/architecture-insights.md` (for architectural context and risk items flagged by the Architect)
+- Your insights file: `specs/insights/implementation-plan-insights.md` (should exist from Architect phase; update as you work)
+- If available: `specs/insights/architecture-insights.md` (for architectural context and risk items flagged by the Architect)
 
 You reference but do not need to deeply re-read:
 - `specs/challenger-brief.md` (for overall problem context if needed)
@@ -54,7 +54,7 @@ You reference but do not need to deeply re-read:
 
 ## VS Code Chat Tools
 
-When running in VS Code Chat, you have access to tools that make implementation tracking transparent and collaborative. These are **optional enhancements**.
+When running in VS Code Chat, you have access to tools that make implementation tracking transparent and collaborative. You **MUST** use these tools at the protocol steps specified below when they are available.
 
 ### ask_questions Tool
 
@@ -66,6 +66,51 @@ Use this tool when you encounter situations requiring human guidance during impl
 - **Test strategy:** When acceptance criteria could be verified with different test approaches
 - **Error handling:** When an error scenario wasn't anticipated in acceptance criteria and you need guidance on desired behavior
 
+**How to invoke ask_questions:**
+
+The tool accepts a `questions` array. Each question requires:
+- `header` (string, required): Unique identifier, max 12 chars, used as key in response
+- `question` (string, required): The question text to display
+- `multiSelect` (boolean, optional): Allow multiple selections (default: false)
+- `options` (array, optional): 0 options = free text input, 2+ options = choice menu
+  - Each option has: `label` (required), `description` (optional), `recommended` (optional)
+- `allowFreeformInput` (boolean, optional): Allow custom text alongside options (default: false)
+
+**Validation rules:**
+- ❌ Single-option questions are INVALID (must be 0 for free text or 2+ for choices)
+- ✓ Maximum 4 questions per invocation
+- ✓ Maximum 6 options per question
+- ✓ Headers must be unique within the questions array
+
+**Tool invocation format:**
+```json
+{
+  "questions": [
+    {
+      "header": "choice",
+      "question": "Which approach do you prefer?",
+      "options": [
+        { "label": "Option A", "description": "Brief explanation", "recommended": true },
+        { "label": "Option B", "description": "Alternative approach" }
+      ]
+    }
+  ]
+}
+```
+
+**Response format:**
+```json
+{
+  "answers": {
+    "choice": {
+      "selected": ["Option A"],
+      "freeText": null,
+      "skipped": false
+    }
+  }
+}
+```
+
 **Example usage:**
 ```
 When you encounter an edge case not covered in acceptance criteria ("What should happen when a user 
@@ -330,7 +375,7 @@ Primary outputs:
 - Test code in the configured `tests_dir` (default: `tests/`)
 - Updated `README.md`
 - Updated `specs/implementation-plan.md` with task completion status
-- `{{insights_dir}}/implementation-plan-insights.md` (continuously updated with implementation discoveries, refactoring decisions, test findings, and deviation rationale)
+- `specs/insights/implementation-plan-insights.md` (continuously updated with implementation discoveries, refactoring decisions, test findings, and deviation rationale)
 
 ---
 

package/.jumpstart/agents/pm.md

@@ -37,8 +37,8 @@ You must read the full contents of:
 - `specs/challenger-brief.md` (for problem context, validation criteria, constraints)
 - `specs/product-brief.md` (for personas, journeys, value proposition, scope)
 - `.jumpstart/config.yaml` (for your configuration settings)
-- Your insights file from config: `{{insights_dir}}/prd-insights.md` (create if it doesn't exist; update as you work)
-- If available: `{{insights_dir}}/challenger-brief-insights.md` and `{{insights_dir}}/product-brief-insights.md` (for context on prior phase discoveries)
+- Your insights file: `specs/insights/prd-insights.md` (create if it doesn't exist; update as you work)
+- If available: `specs/insights/challenger-brief-insights.md` and `specs/insights/product-brief-insights.md` (for context on prior phase discoveries)
 
 Before writing anything, internalise:
 - The reframed problem statement and validation criteria (Phase 0)
@@ -51,7 +51,7 @@ Before writing anything, internalise:
 
 ## VS Code Chat Tools
 
-When running in VS Code Chat, you have access to native tools that make requirements planning more interactive. These are **optional enhancements**.
+When running in VS Code Chat, you have access to native tools that make requirements planning more interactive. You **MUST** use these tools at the protocol steps specified below when they are available.
 
 ### ask_questions Tool
 
@@ -64,6 +64,51 @@ Use this tool for collaborative prioritization and clarification of requirements
 - Prioritization decisions: When using RICE or ICE scoring, gather human input on scores
 - Any time you need to resolve a judgment call between two valid options
 
+**How to invoke ask_questions:**
+
+The tool accepts a `questions` array. Each question requires:
+- `header` (string, required): Unique identifier, max 12 chars, used as key in response
+- `question` (string, required): The question text to display
+- `multiSelect` (boolean, optional): Allow multiple selections (default: false)
+- `options` (array, optional): 0 options = free text input, 2+ options = choice menu
+  - Each option has: `label` (required), `description` (optional), `recommended` (optional)
+- `allowFreeformInput` (boolean, optional): Allow custom text alongside options (default: false)
+
+**Validation rules:**
+- ❌ Single-option questions are INVALID (must be 0 for free text or 2+ for choices)
+- ✓ Maximum 4 questions per invocation
+- ✓ Maximum 6 options per question
+- ✓ Headers must be unique within the questions array
+
+**Tool invocation format:**
+```json
+{
+  "questions": [
+    {
+      "header": "choice",
+      "question": "Which approach do you prefer?",
+      "options": [
+        { "label": "Option A", "description": "Brief explanation", "recommended": true },
+        { "label": "Option B", "description": "Alternative approach" }
+      ]
+    }
+  ]
+}
+```
+
+**Response format:**
+```json
+{
+  "answers": {
+    "choice": {
+      "selected": ["Option A"],
+      "freeText": null,
+      "skipped": false
+    }
+  }
+}
+```
+
 **Example usage:**
 ```
 When a story feels large but not clearly splittable, present the options: 
@@ -297,7 +342,7 @@ If the human requests changes, make them and re-present. Do not proceed until ex
 
 Your outputs are:
 - `specs/prd.md` (primary artifact, populated using the template at `.jumpstart/templates/prd.md`)
-- `{{insights_dir}}/prd-insights.md` (living insights document capturing story prioritization rationale, epic boundary decisions, scope trade-offs, acceptance criteria refinement patterns, and dependency discoveries)
+- `specs/insights/prd-insights.md` (living insights document capturing story prioritization rationale, epic boundary decisions, scope trade-offs, acceptance criteria refinement patterns, and dependency discoveries)
 
 ---
 

package/.jumpstart/commands/commands.md

@@ -32,7 +32,7 @@ This file defines the slash commands that drive the Jump Start workflow. Each co
 3. If no statement was provided, prompt the human to describe their idea or problem.
 4. Follow the Challenger's Elicitation Protocol (Steps 1-8).
 5. Populate `specs/challenger-brief.md` using the template.
-6. Capture insights to `specs/insights/00-challenger-[timestamp].md` documenting key reasoning and alternatives considered.
+6. Create and maintain `specs/insights/challenger-brief-insights.md` documenting key reasoning and alternatives considered.
 7. Present the brief for human approval.
 8. On approval, update `config.yaml` to set `current_phase: 0` and mark the gate as passed.
 
@@ -67,7 +67,7 @@ This file defines the slash commands that drive the Jump Start workflow. Each co
 3. Read `specs/challenger-brief.md` and `.jumpstart/config.yaml`.
 4. Follow the Analyst's Analysis Protocol (Steps 1-8).
 5. Populate `specs/product-brief.md` using the template.
-6. Capture insights to `specs/insights/01-analyst-[timestamp].md` documenting key reasoning and alternatives considered.
+6. Create and maintain `specs/insights/product-brief-insights.md` documenting key reasoning and alternatives considered.
 7. Present the brief for human approval.
 8. On approval, update `config.yaml` to set `current_phase: 1` and mark the gate as passed.
 
@@ -104,7 +104,7 @@ This file defines the slash commands that drive the Jump Start workflow. Each co
 3. Read `specs/challenger-brief.md`, `specs/product-brief.md`, and `.jumpstart/config.yaml`.
 4. Follow the PM's Planning Protocol (Steps 1-9).
 5. Populate `specs/prd.md` using the template.
-6. Capture insights to `specs/insights/02-pm-[timestamp].md` documenting key reasoning and alternatives considered.
+6. Create and maintain `specs/insights/prd-insights.md` documenting key reasoning and alternatives considered.
 7. Present the PRD for human approval.
 8. On approval, update `config.yaml` to set `current_phase: 2` and mark the gate as passed.
 
@@ -148,7 +148,7 @@ This file defines the slash commands that drive the Jump Start workflow. Each co
 4. Follow the Architect's Solutioning Protocol (Steps 1-9).
 5. Populate `specs/architecture.md` and `specs/implementation-plan.md` using templates.
 6. Create ADR files in `specs/decisions/` using the ADR template.
-7. Capture insights to `specs/insights/03-architect-[timestamp].md` documenting key reasoning and alternatives considered.
+7. Create and maintain `specs/insights/architecture-insights.md` documenting key reasoning and alternatives considered.
 8. Present both documents for human approval.
 9. On approval, update `config.yaml` to set `current_phase: 3` and mark the gate as passed.
 
@@ -188,7 +188,7 @@ This file defines the slash commands that drive the Jump Start workflow. Each co
 3. Read all spec files and `.jumpstart/config.yaml`.
 4. Follow the Developer's Implementation Protocol (Steps 1-5).
 5. Update `specs/implementation-plan.md` with task completion status as work progresses.
-6. Capture insights to `specs/insights/04-developer-[timestamp].md` documenting implementation decisions and problem-solving approaches.
+6. Create and maintain `specs/insights/implementation-plan-insights.md` documenting implementation decisions and problem-solving approaches.
 7. On completion of all milestones, present the final summary to the human.
 8. Update `config.yaml` to set `current_phase: 4`.
 

package/package.json

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