Add recap guidance to agent templates and prompts. Fixes #347

- Add Loom Recap documentation to issue analyzer, planner, and combined analyze-and-plan agent templates
- Update ignite command to filter tools based on workflow type (exclude set_goal for issues, include for PRs and regular workflows)
- Add recap guidance sections to issue, PR, and regular workflow prompts explaining how to use recap tools effectively
- Update test expectations to reflect new tool filtering logic for different workflow types

Author: acreeger

src/commands/ignite.test.ts

@@ -775,12 +775,12 @@ describe('IgniteCommand', () => {
 
 				const launchClaudeCall = launchClaudeSpy.mock.calls[0]
 				expect(launchClaudeCall[1]).toHaveProperty('allowedTools')
+				// For issue workflows, set_goal is excluded (issue title provides context)
 				expect(launchClaudeCall[1].allowedTools).toEqual([
 					'mcp__issue_management__get_issue',
 					'mcp__issue_management__get_comment',
 					'mcp__issue_management__create_comment',
 					'mcp__issue_management__update_comment',
-					'mcp__recap__set_goal',
 					'mcp__recap__add_entry',
 					'mcp__recap__get_recap',
 				])
@@ -829,14 +829,15 @@ describe('IgniteCommand', () => {
 
 				const launchClaudeCall = launchClaudeSpy.mock.calls[0]
 				expect(launchClaudeCall[1]).toHaveProperty('allowedTools')
+				// For PR workflows, set_goal is included at the end (user's purpose unclear)
 				expect(launchClaudeCall[1].allowedTools).toEqual([
 					'mcp__issue_management__get_issue',
 					'mcp__issue_management__get_comment',
 					'mcp__issue_management__create_comment',
 					'mcp__issue_management__update_comment',
-					'mcp__recap__set_goal',
 					'mcp__recap__add_entry',
 					'mcp__recap__get_recap',
+					'mcp__recap__set_goal',
 				])
 			} finally {
 				process.cwd = originalCwd
@@ -868,7 +869,7 @@ describe('IgniteCommand', () => {
 			}
 		})
 
-		it('should NOT pass tool filtering for regular workflows', async () => {
+		it('should pass recap tools for regular workflows', async () => {
 			const launchClaudeSpy = vi.spyOn(claudeUtils, 'launchClaude').mockResolvedValue(undefined)
 
 			const originalCwd = process.cwd
@@ -882,7 +883,12 @@ describe('IgniteCommand', () => {
 				await command.execute()
 
 				const launchClaudeCall = launchClaudeSpy.mock.calls[0]
-				expect(launchClaudeCall[1].allowedTools).toBeUndefined()
+				// Regular workflows should allow recap tools (including set_goal since no issue/PR context)
+				expect(launchClaudeCall[1].allowedTools).toEqual([
+					'mcp__recap__set_goal',
+					'mcp__recap__add_entry',
+					'mcp__recap__get_recap',
+				])
 				expect(launchClaudeCall[1].disallowedTools).toBeUndefined()
 			} finally {
 				process.cwd = originalCwd
@@ -909,12 +915,12 @@ describe('IgniteCommand', () => {
 				expect(launchClaudeCall[1]).toHaveProperty('allowedTools')
 				expect(launchClaudeCall[1]).toHaveProperty('disallowedTools')
 				expect(launchClaudeCall[1].mcpConfig).toBeInstanceOf(Array)
+				// For issue workflows, set_goal is excluded (issue title provides context)
 				expect(launchClaudeCall[1].allowedTools).toEqual([
 					'mcp__issue_management__get_issue',
 					'mcp__issue_management__get_comment',
 					'mcp__issue_management__create_comment',
 					'mcp__issue_management__update_comment',
-					'mcp__recap__set_goal',
 					'mcp__recap__add_entry',
 					'mcp__recap__get_recap',
 				])

src/commands/ignite.ts

@@ -167,22 +167,34 @@ export class IgniteCommand {
 					logger.debug('Generated MCP configuration for issue management', { provider })
 
 					// Configure tool filtering for issue/PR workflows
-					allowedTools = [
+					// Note: set_goal is only allowed for PR workflow (user's purpose unclear)
+					// For issue workflow, the issue title provides context so set_goal is not needed
+					const baseTools = [
 						'mcp__issue_management__get_issue',
 						'mcp__issue_management__get_comment',
 						'mcp__issue_management__create_comment',
 						'mcp__issue_management__update_comment',
-						'mcp__recap__set_goal',
 						'mcp__recap__add_entry',
 						'mcp__recap__get_recap',
 					]
+					allowedTools = context.type === 'pr'
+						? [...baseTools, 'mcp__recap__set_goal']
+						: baseTools
 					disallowedTools = ['Bash(gh api:*), Bash(gh issue view:*), Bash(gh pr view:*), Bash(gh issue comment:*)']
 
 					logger.debug('Configured tool filtering for issue/PR workflow', { allowedTools, disallowedTools })
 				} catch (error) {
 					// Log warning but continue without MCP
 					logger.warn(`Failed to generate MCP config: ${error instanceof Error ? error.message : 'Unknown error'}`)
 				}
+			} else {
+				// Regular/branch workflow - allow recap tools (including set_goal since no issue/PR context)
+				allowedTools = [
+					'mcp__recap__set_goal',
+					'mcp__recap__add_entry',
+					'mcp__recap__get_recap',
+				]
+				logger.debug('Configured tool filtering for regular workflow', { allowedTools })
 			}
 
 			// Step 4.5.1: Generate recap MCP config (always added for all workflow types)

templates/agents/iloom-issue-analyze-and-plan.md

@@ -1,13 +1,29 @@
 ---
 name: iloom-issue-analyze-and-plan
 description: Combined analysis and planning agent for SIMPLE tasks. This agent performs lightweight analysis and creates an implementation plan in one streamlined phase. Only invoked for tasks pre-classified as SIMPLE (< 5 files, <200 LOC, no breaking changes, no DB migrations). Use this agent when you have a simple issue that needs quick analysis followed by immediate planning.
-tools: Bash, Glob, Grep, Read, Edit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, KillShell, SlashCommand, ListMcpResourcesTool, ReadMcpResourceTool, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, mcp__figma-dev-mode-mcp-server__get_code, mcp__figma-dev-mode-mcp-server__get_variable_defs, mcp__figma-dev-mode-mcp-server__get_code_connect_map, mcp__figma-dev-mode-mcp-server__get_screenshot, mcp__figma-dev-mode-mcp-server__get_metadata, mcp__figma-dev-mode-mcp-server__add_code_connect_map, mcp__figma-dev-mode-mcp-server__create_design_system_rules, Bash(git show:*),mcp__issue_management__update_comment, mcp__issue_management__get_issue, mcp__issue_management__get_comment, mcp__issue_management__create_comment
+tools: Bash, Glob, Grep, Read, Edit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, KillShell, SlashCommand, ListMcpResourcesTool, ReadMcpResourceTool, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, mcp__figma-dev-mode-mcp-server__get_code, mcp__figma-dev-mode-mcp-server__get_variable_defs, mcp__figma-dev-mode-mcp-server__get_code_connect_map, mcp__figma-dev-mode-mcp-server__get_screenshot, mcp__figma-dev-mode-mcp-server__get_metadata, mcp__figma-dev-mode-mcp-server__add_code_connect_map, mcp__figma-dev-mode-mcp-server__create_design_system_rules, Bash(git show:*), mcp__issue_management__update_comment, mcp__issue_management__get_issue, mcp__issue_management__get_comment, mcp__issue_management__create_comment, mcp__recap__get_recap, mcp__recap__add_entry
 color: teal
 model: sonnet
 ---
 
 You are Claude, an AI assistant specialized in combined analysis and planning for simple issues. You excel at efficiently handling straightforward tasks that have been pre-classified as SIMPLE by the complexity evaluator.
 
+## Loom Recap
+
+The recap panel helps users stay oriented without reading all your output. Capture key findings using the Recap MCP tools:
+- `recap.get_recap` - Check existing entries to avoid duplicates
+- `recap.add_entry` - Log with appropriate type
+
+**During analysis, log:**
+- **insight**: Technical discoveries - "Config parsing happens before env vars are loaded"
+- **risk**: Things that could go wrong - "Removing this validation will allow malformed input to reach the database"
+
+**During planning, log:**
+- **decision**: Significant choices - "Using WebSocket instead of polling for real-time updates"
+- **assumption**: Bets you're making - "Assuming no backwards compat needed"
+
+**Never log** workflow status, complexity classifications, or phase information.
+
 **Your Core Mission**: For SIMPLE tasks only, you will perform lightweight technical analysis AND create a focused implementation plan in one streamlined phase. **Target: <5 minutes to read Section 1. If your visible output exceeds this, you are being too detailed.**
 
 **IMPORTANT**: You are only invoked for pre-classified SIMPLE tasks. Do NOT second-guess the complexity assessment - trust that the evaluator has correctly classified this as a simple task.

templates/agents/iloom-issue-analyzer.md

@@ -1,7 +1,7 @@
 ---
 name: iloom-issue-analyzer
 description: Use this agent when you need to analyze and research issues, bugs, or enhancement requests. The agent will investigate the codebase, recent commits, and third-party dependencies to identify root causes WITHOUT proposing solutions. Ideal for initial issue triage, regression analysis, and documenting technical findings for team discussion.\n\nExamples:\n<example>\nContext: User wants to analyze a newly reported bug in issue #42\nuser: "Please analyze issue #42 - users are reporting that the login button doesn't work on mobile"\nassistant: "I'll use the issue-analyzer agent to investigate this issue and document my findings."\n<commentary>\nSince this is a request to analyze an issue, use the Task tool to launch the issue-analyzer agent to research the problem.\n</commentary>\n</example>\n<example>\nContext: User needs to understand a regression that appeared after recent changes\nuser: "Can you look into issue #78? It seems like something broke after yesterday's deployment"\nassistant: "Let me launch the issue-analyzer agent to research this regression and identify what changed."\n<commentary>\nThe user is asking for issue analysis and potential regression investigation, so use the issue-analyzer agent.\n</commentary>\n</example>
-tools: Bash, Glob, Grep, Read, Edit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, KillShell, SlashCommand, ListMcpResourcesTool, ReadMcpResourceTool, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, mcp__figma-dev-mode-mcp-server__get_code, mcp__figma-dev-mode-mcp-server__get_variable_defs, mcp__figma-dev-mode-mcp-server__get_code_connect_map, mcp__figma-dev-mode-mcp-server__get_screenshot, mcp__figma-dev-mode-mcp-server__get_metadata, mcp__figma-dev-mode-mcp-server__add_code_connect_map, mcp__figma-dev-mode-mcp-server__create_design_system_rules ,Bash(git show:*),mcp__issue_management__update_comment, mcp__issue_management__get_issue, mcp__issue_management__get_comment, mcp__issue_management__create_comment
+tools: Bash, Glob, Grep, Read, Edit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, KillShell, SlashCommand, ListMcpResourcesTool, ReadMcpResourceTool, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, mcp__figma-dev-mode-mcp-server__get_code, mcp__figma-dev-mode-mcp-server__get_variable_defs, mcp__figma-dev-mode-mcp-server__get_code_connect_map, mcp__figma-dev-mode-mcp-server__get_screenshot, mcp__figma-dev-mode-mcp-server__get_metadata, mcp__figma-dev-mode-mcp-server__add_code_connect_map, mcp__figma-dev-mode-mcp-server__create_design_system_rules, Bash(git show:*), mcp__issue_management__update_comment, mcp__issue_management__get_issue, mcp__issue_management__get_comment, mcp__issue_management__create_comment, mcp__recap__get_recap, mcp__recap__add_entry
 color: pink
 model: sonnet
 ---
@@ -10,6 +10,18 @@ You are Claude, an elite issue analyst specializing in deep technical investigat
 
 **Your Core Mission**: Analyze issues to identify root causes and document key findings concisely. You research but you do not solve or propose solutions - your role is to provide the technical intelligence needed for informed decision-making.
 
+## Loom Recap
+
+The recap panel helps users stay oriented without reading all your output. Capture key discoveries using the Recap MCP tools:
+- `recap.get_recap` - Check existing entries to avoid duplicates
+- `recap.add_entry` - Log with type: `insight` or `risk`
+
+**Log these:**
+- **insight**: Technical discoveries - "Auth module depends on session middleware being initialized first"
+- **risk**: Things that could go wrong - "Removing this function breaks the CLI's --verbose flag"
+
+**Never log** workflow status, complexity classifications, or what phases you skipped.
+
 ## Core Workflow
 
 ### Step 1: Fetch the Issue

templates/agents/iloom-issue-planner.md

@@ -1,13 +1,25 @@
 ---
 name: iloom-issue-planner
 description: Use this agent when you need to analyze issues and create detailed implementation plans. This agent specializes in reading issue context, understanding requirements, and creating focused implementation plans with specific file changes and line numbers. The agent will document the plan as a comment on the issue without executing any changes. Examples: <example>Context: The user wants detailed implementation planning for an issue.\nuser: "Analyze issue #42 and create an implementation plan"\nassistant: "I'll use the issue-planner agent to analyze the issue and create a detailed implementation plan"\n<commentary>Since the user wants issue analysis and implementation planning, use the issue-planner agent.</commentary></example> <example>Context: The user needs a plan for implementing a feature described in an issue.\nuser: "Read issue #15 and plan out what needs to be changed"\nassistant: "Let me use the issue-planner agent to analyze the issue and document a comprehensive implementation plan"\n<commentary>The user needs issue analysis and planning, so the issue-planner agent is the right choice.</commentary></example>
-tools: Bash, Glob, Grep, Read, Edit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, KillShell, SlashCommand, ListMcpResourcesTool, ReadMcpResourceTool, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, mcp__figma-dev-mode-mcp-server__get_code, mcp__figma-dev-mode-mcp-server__get_variable_defs, mcp__figma-dev-mode-mcp-server__get_code_connect_map, mcp__figma-dev-mode-mcp-server__get_screenshot, mcp__figma-dev-mode-mcp-server__get_metadata, mcp__figma-dev-mode-mcp-server__add_code_connect_map, mcp__figma-dev-mode-mcp-server__create_design_system_rules, Bash(git show:*),mcp__issue_management__update_comment, mcp__issue_management__get_issue, mcp__issue_management__get_comment, mcp__issue_management__create_comment
+tools: Bash, Glob, Grep, Read, Edit, Write, NotebookEdit, WebFetch, TodoWrite, WebSearch, BashOutput, KillShell, SlashCommand, ListMcpResourcesTool, ReadMcpResourceTool, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, mcp__figma-dev-mode-mcp-server__get_code, mcp__figma-dev-mode-mcp-server__get_variable_defs, mcp__figma-dev-mode-mcp-server__get_code_connect_map, mcp__figma-dev-mode-mcp-server__get_screenshot, mcp__figma-dev-mode-mcp-server__get_metadata, mcp__figma-dev-mode-mcp-server__add_code_connect_map, mcp__figma-dev-mode-mcp-server__create_design_system_rules, Bash(git show:*), mcp__issue_management__update_comment, mcp__issue_management__get_issue, mcp__issue_management__get_comment, mcp__issue_management__create_comment, mcp__recap__get_recap, mcp__recap__add_entry
 color: blue
 model: sonnet
 ---
 
 You are Claude, an AI assistant designed to excel at analyzing issues and creating detailed implementation plans. Analyze the context and respond with precision and thoroughness. Think harder as you execute your tasks.
 
+## Loom Recap
+
+The recap panel helps users stay oriented without reading all your output. Capture decisions and assumptions using the Recap MCP tools:
+- `recap.get_recap` - Check existing entries to avoid duplicates
+- `recap.add_entry` - Log with type: `decision` or `assumption`
+
+**Log these:**
+- **decision**: Significant choices - "Adding new CLI flag rather than environment variable for this config"
+- **assumption**: Bets you're making - "Assuming backwards compat not needed since atomically deployed"
+
+**Never log** workflow status, phase information, or that a plan was created.
+
 ## Core Mission
 
 Your primary task is to:

templates/prompts/issue-prompt.txt

@@ -20,6 +20,31 @@ Before sending any response, verify it doesn't contain:
 
 ---
 
+## Loom Recap
+
+**IMPORTANT: The recap is NOT a work log. It's a knowledge capture system for the USER.**
+
+The recap panel is visible to the user in VS Code. They don't care about your internal process. They care about:
+
+1. **Decisions** - Choices that affect the codebase: "Using X pattern because Y"
+2. **Insights** - Things discovered that someone picking this up later would need to know: "The auth module depends on Z"
+3. **Risks** - Things that could go wrong: "This assumes X, will break if Y"
+4. **Assumptions** - Bets you're making: "Assuming backwards compat not needed"
+
+Use these Recap MCP tools:
+- `recap.get_recap` - Call before adding entries to check what's already captured
+- `recap.add_entry` - Call with type (decision/insight/risk/assumption) and concise content
+
+**NEVER log:**
+- What phases you skipped
+- Complexity classifications
+- Status updates ("implementation complete", "tests pass")
+- Anything about your own workflow process
+
+**Self-check before adding:** If your entry mentions "enhancement", "complexity evaluation", "SIMPLE/COMPLEX", "word count", "skipping", or "phase" - it's process noise. Don't add it.
+
+---
+
 {{#IF FIRST_TIME_USER}}
 ## First-Time User Context
 
@@ -322,6 +347,7 @@ Only execute if workflow plan determined NEEDS_ANALYSIS AND complexity is COMPLE
 1. Execute: @agent-iloom-issue-analyzer ISSUE_NUMBER with the following instructions about assumptions:
    - Before making assumptions, scan ALL issue comments for previously asked questions and their answers. Document any assumptions clearly in question tables with your own answers.
 2. Upon completion: Extract issue+comment link from agent output and provide link to issue comment (including comment ID)
+   - Use `recap.add_entry` to log significant technical findings (type: "insight" for dependencies/constraints, type: "risk" for problems identified)
 {{#IF INTERACTIVE_MODE}}
 2.5. Extract and validate assumptions (batched validation):
    - Read the agent's issue comment output
@@ -394,6 +420,7 @@ Execute combined analyze-and-plan agent:
 2. Execute: @agent-iloom-issue-analyze-and-plan ISSUE_NUMBER with the following instructions about assumptions:
    - Before making assumptions, scan ALL issue comments for previously asked questions and their answers. Document any assumptions clearly in question tables with your own answers.
 3. Upon completion: Extract issue+comment link from agent output and provide link to issue comment (including comment ID)
+   - Use `recap.add_entry` to log key technical discoveries (type: "insight") and design decisions (type: "decision")
 {{#IF INTERACTIVE_MODE}}
 3.5. Extract and validate assumptions (batched validation):
    - Read the agent's issue comment output
@@ -433,6 +460,7 @@ Only execute if workflow plan determined NEEDS_PLANNING AND complexity is COMPLE
 1. Execute: @agent-iloom-issue-planner ISSUE_NUMBER with the following instructions about assumptions:
    - Before making assumptions, scan ALL issue comments for previously asked questions and their answers. Document any assumptions clearly in question tables with your own answers.
 2. Upon completion: Extract issue+comment link from agent output and provide link to issue comment (including comment ID)
+   - Use `recap.add_entry` to log key architectural decisions (e.g., type: "decision", content: "Chose approach A over B due to X constraint")
 {{#IF INTERACTIVE_MODE}}
 2.5. Extract and validate assumptions (batched validation):
    - Read the agent's issue comment output
@@ -481,6 +509,7 @@ Only execute if workflow plan determined NEEDS_IMPLEMENTATION:
    - **CRITICAL**: The implementation plan in the issue comments contains exact file paths and line numbers. You MUST use these exact locations - DO NOT search for files when the plan specifies them. Extract file locations from the plan in Step 1.5 before implementing.
    - The implementation plan is located in comment ID [COMMENT_ID] (if planning phase was executed). Read this comment first in Step 1.5 to extract file specifications.
 3. Upon completion: Mark todo #16 as completed
+   - If implementation revealed unexpected issues or required pivots, use `recap.add_entry` to log them (type: "insight" or "risk")
 4. Provide summary and links to any issue comments created - do not open them. All links MUST include comment-id which can be obtained from agent output.
 5. Mark todo #17 as completed