@iloom/cli 0.6.1 → 0.7.1

package/dist/agents/iloom-issue-analyzer.md

@@ -26,7 +26,7 @@ The recap panel helps users stay oriented without reading all your output. Captu
 ## Core Workflow
 
 ### Step 1: Fetch the Issue
-Please read the referenced issue and comments using the MCP tool `mcp__issue_management__get_issue` with `{ number: ISSUE_NUMBER, includeComments: true }`
+Please read the referenced issue and comments using the MCP tool `mcp__issue_management__get_issue` with `{ number: {{ISSUE_NUMBER}}, includeComments: true }`
 
 ### Step 2: Perform Comprehensive Research
 
@@ -298,9 +298,9 @@ Available Tools:
   Parameters: { commentId: string, number: string }
   Returns: { id, body, author, created_at, ... }
 
-{{#IF DRAFT_PR_MODE}}- mcp__issue_management__create_comment: Create a new comment on PR DRAFT_PR_NUMBER
-  Parameters: { number: string, body: "markdown content", type: "pr" }{{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}- mcp__issue_management__create_comment: Create a new comment on issue ISSUE_NUMBER
-  Parameters: { number: string, body: "markdown content", type: "issue" }{{/IF STANDARD_ISSUE_MODE}}
+{{#if DRAFT_PR_MODE}}- mcp__issue_management__create_comment: Create a new comment on PR {{DRAFT_PR_NUMBER}}
+  Parameters: { number: string, body: "markdown content", type: "pr" }{{/if}}{{#if STANDARD_ISSUE_MODE}}- mcp__issue_management__create_comment: Create a new comment on issue {{ISSUE_NUMBER}}
+  Parameters: { number: string, body: "markdown content", type: "issue" }{{/if}}
   Returns: { id: string, url: string, created_at: string }
 
 - mcp__issue_management__update_comment: Update an existing comment
@@ -323,15 +323,15 @@ Workflow Comment Strategy:
 Example Usage:
 ```
 // Start
-{{#IF DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
-  number: DRAFT_PR_NUMBER,
+{{#if DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
+  number: {{DRAFT_PR_NUMBER}},
   body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
   type: "pr"
-}){{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}const comment = await mcp__issue_management__create_comment({
-  number: ISSUE_NUMBER,
+}){{/if}}{{#if STANDARD_ISSUE_MODE}}const comment = await mcp__issue_management__create_comment({
+  number: {{ISSUE_NUMBER}},
   body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
   type: "issue"
-}){{/IF STANDARD_ISSUE_MODE}}
+}){{/if}}
 
 // Log the comment as an artifact
 await mcp__recap__add_artifact({
@@ -341,15 +341,15 @@ await mcp__recap__add_artifact({
 })
 
 // Update as you progress
-{{#IF DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
+{{#if DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
   commentId: comment.id,
-  number: DRAFT_PR_NUMBER,
+  number: {{DRAFT_PR_NUMBER}},
   body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
-}){{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}await mcp__issue_management__update_comment({
+}){{/if}}{{#if STANDARD_ISSUE_MODE}}await mcp__issue_management__update_comment({
   commentId: comment.id,
-  number: ISSUE_NUMBER,
+  number: {{ISSUE_NUMBER}},
   body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
-}){{/IF STANDARD_ISSUE_MODE}}
+}){{/if}}
 ```
 </comment_tool_info>
 

package/dist/agents/iloom-issue-complexity-evaluator.md

@@ -34,7 +34,7 @@ recap.set_complexity({ complexity: 'simple', reason: 'Few files, low risk' })
 
 ### Step 1: Fetch the Issue
 
-Read the issue using the MCP issue management tool: `mcp__issue_management__get_issue` with `{ number: ISSUE_NUMBER, includeComments: true }`
+Read the issue using the MCP issue management tool: `mcp__issue_management__get_issue` with `{ number: {{ISSUE_NUMBER}}, includeComments: true }`
 
 ### Step 2: Perform Quick Complexity Assessment
 
@@ -135,6 +135,25 @@ Estimate the following metrics:
    - HIGH risks: Core functionality changes, security implications, performance impacts
    - CRITICAL risks: Data loss potential, system-wide failures, irreversible operations
 
+8. **Architectural Complexity Signals** (Any YES = COMPLEX):
+   - **CRITICAL**: These signals detect "hidden complexity" that surface metrics miss
+
+   | Signal | Question |
+   |--------|----------|
+   | External constraints | Does this depend on third-party system behavior not documented in our codebase? |
+   | Uncertain approach | Are there multiple valid implementation approaches with different tradeoffs? |
+   | New patterns | Does this require designing new patterns rather than extending existing ones? |
+   | Integration points | Does this coordinate between multiple systems (hooks, extensions, APIs)? |
+   | "How" clarity | Does the implementation approach NOT follow obviously from requirements? |
+
+   **Key Heuristic**: If the planner/analyzer would need to make architectural decisions (not just identify files to change), classify as COMPLEX.
+
+   **Detection Process**:
+   1. Check if issue mentions external tools/APIs with undocumented behavior
+   2. Look for phrases indicating uncertainty: "could", "might", "options", "approach", "design"
+   3. Check if solution requires new coordination mechanisms not in codebase
+   4. Assess whether "how to implement" is obvious from "what to implement"
+
 **Classification Logic:**
 
 - **TRIVIAL**: ALL conditions must be met:
@@ -143,6 +162,7 @@ Estimate the following metrics:
   - No breaking changes
   - No database migrations
   - No cross-cutting changes
+  - No architectural complexity signals triggered
   - Risk level = LOW only
   - All modified files <500 LOC UNLESS changes are isolated to specific functions/handlers in larger files
   - NOT security/authentication/login related
@@ -157,6 +177,7 @@ Estimate the following metrics:
   - No breaking changes
   - No database migrations
   - No cross-cutting changes
+  - No architectural complexity signals triggered
   - Risk level ≤ MEDIUM
   - **All modified files <500 LOC OR well-architected**
 
@@ -164,8 +185,9 @@ Estimate the following metrics:
   - Any modified file >1000 LOC
   - Any modified file 500-1000 LOC with poor architecture quality
   - Multiple modified files >500 LOC (cumulative cognitive load)
+  - **Any Architectural Complexity Signal answered YES**
 
-**IMPORTANT**: Cross-cutting changes and large/poorly-architected files automatically trigger COMPLEX classification regardless of other metrics. These changes appear deceptively simple but require complex coordination or significant cognitive load.
+**IMPORTANT**: Cross-cutting changes, architectural complexity signals, and large/poorly-architected files automatically trigger COMPLEX classification regardless of other metrics. These changes appear deceptively simple but require complex coordination, architectural decisions, or significant cognitive load.
 
 <comment_tool_info>
 IMPORTANT: You have been provided with MCP tools for issue management during this workflow.
@@ -179,9 +201,9 @@ Available Tools:
   Parameters: { commentId: string, number: string }
   Returns: { id, body, author, created_at, ... }
 
-{{#IF DRAFT_PR_MODE}}- mcp__issue_management__create_comment: Create a new comment on PR DRAFT_PR_NUMBER
-  Parameters: { number: string, body: "markdown content", type: "pr" }{{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}- mcp__issue_management__create_comment: Create a new comment on issue ISSUE_NUMBER
-  Parameters: { number: string, body: "markdown content", type: "issue" }{{/IF STANDARD_ISSUE_MODE}}
+{{#if DRAFT_PR_MODE}}- mcp__issue_management__create_comment: Create a new comment on PR {{DRAFT_PR_NUMBER}}
+  Parameters: { number: string, body: "markdown content", type: "pr" }{{/if}}{{#if STANDARD_ISSUE_MODE}}- mcp__issue_management__create_comment: Create a new comment on issue {{ISSUE_NUMBER}}
+  Parameters: { number: string, body: "markdown content", type: "issue" }{{/if}}
   Returns: { id: string, url: string, created_at: string }
 
 - mcp__issue_management__update_comment: Update an existing comment
@@ -205,15 +227,15 @@ Workflow Comment Strategy:
 Example Usage:
 ```
 // Start
-{{#IF DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
-  number: DRAFT_PR_NUMBER,
+{{#if DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
+  number: {{DRAFT_PR_NUMBER}},
   body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
   type: "pr"
-}){{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}const comment = await mcp__issue_management__create_comment({
-  number: ISSUE_NUMBER,
+}){{/if}}{{#if STANDARD_ISSUE_MODE}}const comment = await mcp__issue_management__create_comment({
+  number: {{ISSUE_NUMBER}},
   body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
   type: "issue"
-}){{/IF STANDARD_ISSUE_MODE}}
+}){{/if}}
 
 // Log the comment as an artifact
 await mcp__recap__add_artifact({
@@ -223,15 +245,15 @@ await mcp__recap__add_artifact({
 })
 
 // Update as you progress
-{{#IF DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
+{{#if DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
   commentId: comment.id,
-  number: DRAFT_PR_NUMBER,
+  number: {{DRAFT_PR_NUMBER}},
   body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
-}){{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}await mcp__issue_management__update_comment({
+}){{/if}}{{#if STANDARD_ISSUE_MODE}}await mcp__issue_management__update_comment({
   commentId: comment.id,
-  number: ISSUE_NUMBER,
+  number: {{ISSUE_NUMBER}},
   body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
-}){{/IF STANDARD_ISSUE_MODE}}
+}){{/if}}
 ```
 </comment_tool_info>
 
@@ -251,6 +273,7 @@ await mcp__recap__add_artifact({
 - Database migrations: [Yes/No]
 - Cross-cutting changes: [Yes/No]
 - File architecture quality: [Good/Poor - include largest file size if >500 LOC]
+- Architectural signals triggered: [None / List of triggered signals]
 - Overall risk level: [Low/Medium/High]
 
 **Reasoning**: [1-2 sentence explanation of why this classification was chosen]

package/dist/agents/iloom-issue-enhancer.md

@@ -34,7 +34,7 @@ First, determine which mode to operate in by checking if the user input contains
 - **Direct Prompt Mode**: Input is a text description without an issue identifier
 
 ### Step 2: Fetch the Input
-- **Issue Mode**: Read the issue using the MCP tool `mcp__issue_management__get_issue` with `{ number: ISSUE_NUMBER, includeComments: true }`. This returns the issue body, title, comments, labels, assignees, and other metadata.
+- **Issue Mode**: Read the issue using the MCP tool `mcp__issue_management__get_issue` with `{ number: {{ISSUE_NUMBER}}, includeComments: true }`. This returns the issue body, title, comments, labels, assignees, and other metadata.
   - If this command fails due to permissions, authentication, or access issues, return immediately: `Permission denied: [specific error description]`
 - **Direct Prompt Mode**: Read and thoroughly understand the provided text description
 
@@ -103,9 +103,9 @@ Available Tools:
   Parameters: { commentId: string, number: string }
   Returns: { id, body, author, created_at, ... }
 
-{{#IF DRAFT_PR_MODE}}- mcp__issue_management__create_comment: Create a new comment on PR DRAFT_PR_NUMBER
-  Parameters: { number: string, body: "markdown content", type: "pr" }{{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}- mcp__issue_management__create_comment: Create a new comment on issue ISSUE_NUMBER
-  Parameters: { number: string, body: "markdown content", type: "issue" }{{/IF STANDARD_ISSUE_MODE}}
+{{#if DRAFT_PR_MODE}}- mcp__issue_management__create_comment: Create a new comment on PR {{DRAFT_PR_NUMBER}}
+  Parameters: { number: string, body: "markdown content", type: "pr" }{{/if}}{{#if STANDARD_ISSUE_MODE}}- mcp__issue_management__create_comment: Create a new comment on issue {{ISSUE_NUMBER}}
+  Parameters: { number: string, body: "markdown content", type: "issue" }{{/if}}
   Returns: { id: string, url: string, created_at: string }
 
 - mcp__issue_management__update_comment: Update an existing comment
@@ -129,15 +129,15 @@ Workflow Comment Strategy:
 Example Usage:
 ```
 // Start
-{{#IF DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
-  number: DRAFT_PR_NUMBER,
+{{#if DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
+  number: {{DRAFT_PR_NUMBER}},
   body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
   type: "pr"
-}){{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}const comment = await mcp__issue_management__create_comment({
-  number: ISSUE_NUMBER,
+}){{/if}}{{#if STANDARD_ISSUE_MODE}}const comment = await mcp__issue_management__create_comment({
+  number: {{ISSUE_NUMBER}},
   body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
   type: "issue"
-}){{/IF STANDARD_ISSUE_MODE}}
+}){{/if}}
 
 // Log the comment as an artifact
 await mcp__recap__add_artifact({
@@ -147,15 +147,15 @@ await mcp__recap__add_artifact({
 })
 
 // Update as you progress
-{{#IF DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
+{{#if DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
   commentId: comment.id,
-  number: DRAFT_PR_NUMBER,
+  number: {{DRAFT_PR_NUMBER}},
   body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
-}){{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}await mcp__issue_management__update_comment({
+}){{/if}}{{#if STANDARD_ISSUE_MODE}}await mcp__issue_management__update_comment({
   commentId: comment.id,
-  number: ISSUE_NUMBER,
+  number: {{ISSUE_NUMBER}},
   body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
-}){{/IF STANDARD_ISSUE_MODE}}
+}){{/if}}
 ```
 </comment_tool_info>
 
@@ -163,7 +163,7 @@ await mcp__recap__add_artifact({
 
 When analyzing input (regardless of mode):
 1. **Read the input**:
-   - Issue Mode: Use the MCP tool `mcp__issue_management__get_issue` with `{ number: ISSUE_NUMBER, includeComments: true }`
+   - Issue Mode: Use the MCP tool `mcp__issue_management__get_issue` with `{ number: {{ISSUE_NUMBER}}, includeComments: true }`
    - Direct Prompt Mode: Carefully read the provided text description
 2. **Assess quality first** (Step 3 from Core Workflow):
    - Check word count (>250 words?)

package/dist/agents/iloom-issue-implementer.md

@@ -27,9 +27,9 @@ Available Tools:
   Parameters: { commentId: string, number: string }
   Returns: { id, body, author, created_at, ... }
 
-{{#IF DRAFT_PR_MODE}}- mcp__issue_management__create_comment: Create a new comment on PR DRAFT_PR_NUMBER
-  Parameters: { number: string, body: "markdown content", type: "pr" }{{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}- mcp__issue_management__create_comment: Create a new comment on issue ISSUE_NUMBER
-  Parameters: { number: string, body: "markdown content", type: "issue" }{{/IF STANDARD_ISSUE_MODE}}
+{{#if DRAFT_PR_MODE}}- mcp__issue_management__create_comment: Create a new comment on PR {{DRAFT_PR_NUMBER}}
+  Parameters: { number: string, body: "markdown content", type: "pr" }{{/if}}{{#if STANDARD_ISSUE_MODE}}- mcp__issue_management__create_comment: Create a new comment on issue {{ISSUE_NUMBER}}
+  Parameters: { number: string, body: "markdown content", type: "issue" }{{/if}}
   Returns: { id: string, url: string, created_at: string }
 
 - mcp__issue_management__update_comment: Update an existing comment
@@ -37,6 +37,15 @@ Available Tools:
   Returns: { id: string, url: string, updated_at: string }
 
 Workflow Comment Strategy:
+
+**MULTI-STEP MODE CHECK:** If the orchestrator told you "DO NOT create your own issue comment" or assigned you a specific step (e.g., "You are implementing Step 2"), you are in MULTI-STEP MODE:
+- Do NOT create any issue comments
+- Do NOT call mcp__issue_management__create_comment or update_comment
+- Just implement your assigned step and return results to the orchestrator
+- The orchestrator manages the progress comment
+- Skip the comment strategy below and go directly to implementation
+
+**SINGLE-STEP MODE (default):** If no step was assigned, follow this comment strategy:
 1. When beginning implementation, create a NEW issue comment informing the user you are working on Implementing the issue.
 2. Store the returned comment ID and URL. After creating the comment, call `mcp__recap__add_artifact` to log it with type='comment', primaryUrl=[comment URL], and a brief description (e.g., "Implementation progress comment").
 3. Once you have formulated your tasks in a todo format, update the issue comment using mcp__issue_management__update_comment with your tasks formatted as checklists using markdown:
@@ -59,15 +68,15 @@ Workflow Comment Strategy:
 Example Usage:
 ```
 // Start
-{{#IF DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
-  number: DRAFT_PR_NUMBER,
+{{#if DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
+  number: {{DRAFT_PR_NUMBER}},
   body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
   type: "pr"
-}){{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}const comment = await mcp__issue_management__create_comment({
-  number: ISSUE_NUMBER,
+}){{/if}}{{#if STANDARD_ISSUE_MODE}}const comment = await mcp__issue_management__create_comment({
+  number: {{ISSUE_NUMBER}},
   body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
   type: "issue"
-}){{/IF STANDARD_ISSUE_MODE}}
+}){{/if}}
 
 // Log the comment as an artifact
 await mcp__recap__add_artifact({
@@ -77,15 +86,15 @@ await mcp__recap__add_artifact({
 })
 
 // Update as you progress
-{{#IF DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
+{{#if DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
   commentId: comment.id,
-  number: DRAFT_PR_NUMBER,
+  number: {{DRAFT_PR_NUMBER}},
   body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
-}){{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}await mcp__issue_management__update_comment({
+}){{/if}}{{#if STANDARD_ISSUE_MODE}}await mcp__issue_management__update_comment({
   commentId: comment.id,
-  number: ISSUE_NUMBER,
+  number: {{ISSUE_NUMBER}},
   body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
-}){{/IF STANDARD_ISSUE_MODE}}
+}){{/if}}
 ```
 </comment_tool_info>
 
@@ -94,7 +103,7 @@ await mcp__recap__add_artifact({
 ## Core Workflow
 
 ### Step 1: Fetch the Issue
-You will thoroughly read issues using the MCP tool `mcp__issue_management__get_issue` with `{ number: ISSUE_NUMBER, includeComments: true }` to extract:
+You will thoroughly read issues using the MCP tool `mcp__issue_management__get_issue` with `{ number: {{ISSUE_NUMBER}}, includeComments: true }` to extract:
 - The complete issue body for context
 - All comments containing implementation plans
 - Specific requirements and constraints
@@ -115,6 +124,24 @@ Before implementing, extract and validate the implementation plan:
 
 **CRITICAL**: This step prevents wasted time searching for files when the plan already provides exact locations.
 
+### Step 1.6: Apply Step Filter (Multi-Step Execution)
+
+If the orchestrator assigned you a specific step (e.g., "You are implementing Step 2"):
+
+1. **Parse step assignment**: Extract step index N from the orchestrator's instructions
+2. **Locate step definition**: In the implementation plan, find "Implementation Steps" or "Detailed Execution Order" section and locate Step N
+3. **Extract file scope**: Parse the "**Files:**" list for Step N
+4. **Filter implementation**: During Step 2 implementation, ONLY modify files listed in this step's scope
+5. **Skip other files**: If the plan references files outside this step's scope, skip them with note: "Skipping [file] - not in Step N scope"
+
+**CRITICAL**: When step filtering is active:
+- Only implement changes to files in the step's "**Files:**" list
+- Run validation only for the scope of changes made in this step
+- Do NOT create validation failures for work deferred to other steps
+- Final summary should note: "Implemented Step N of M"
+
+If no step was assigned, implement the entire plan as before.
+
 ### Step 2: Implement the Solution
 
 2. **Strict Implementation Guidelines**:
@@ -160,7 +187,9 @@ When implementation is complete, use this TWO-SECTION structure for your final c
 **Target audience:** Human reviewers who need to understand what was done
 
 ```markdown
-# Implementation Complete - Issue #[NUMBER] ✅
+# Implementation Complete - Issue #[NUMBER] [Step N/M] ✅
+
+**Note:** Include "[Step N/M]" only when executing a specific step from a multi-step plan. Omit for single-step implementations.
 
 ## Summary
 [2-3 sentences describing what was implemented]

package/dist/agents/iloom-issue-planner.md

@@ -43,9 +43,9 @@ Available Tools:
   Parameters: { commentId: string, number: string }
   Returns: { id, body, author, created_at, ... }
 
-{{#IF DRAFT_PR_MODE}}- mcp__issue_management__create_comment: Create a new comment on PR DRAFT_PR_NUMBER
-  Parameters: { number: string, body: "markdown content", type: "pr" }{{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}- mcp__issue_management__create_comment: Create a new comment on issue ISSUE_NUMBER
-  Parameters: { number: string, body: "markdown content", type: "issue" }{{/IF STANDARD_ISSUE_MODE}}
+{{#if DRAFT_PR_MODE}}- mcp__issue_management__create_comment: Create a new comment on PR {{DRAFT_PR_NUMBER}}
+  Parameters: { number: string, body: "markdown content", type: "pr" }{{/if}}{{#if STANDARD_ISSUE_MODE}}- mcp__issue_management__create_comment: Create a new comment on issue {{ISSUE_NUMBER}}
+  Parameters: { number: string, body: "markdown content", type: "issue" }{{/if}}
   Returns: { id: string, url: string, created_at: string }
 
 - mcp__issue_management__update_comment: Update an existing comment
@@ -68,15 +68,15 @@ Workflow Comment Strategy:
 Example Usage:
 ```
 // Start
-{{#IF DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
-  number: DRAFT_PR_NUMBER,
+{{#if DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
+  number: {{DRAFT_PR_NUMBER}},
   body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
   type: "pr"
-}){{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}const comment = await mcp__issue_management__create_comment({
-  number: ISSUE_NUMBER,
+}){{/if}}{{#if STANDARD_ISSUE_MODE}}const comment = await mcp__issue_management__create_comment({
+  number: {{ISSUE_NUMBER}},
   body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
   type: "issue"
-}){{/IF STANDARD_ISSUE_MODE}}
+}){{/if}}
 
 // Log the comment as an artifact
 await mcp__recap__add_artifact({
@@ -86,15 +86,15 @@ await mcp__recap__add_artifact({
 })
 
 // Update as you progress
-{{#IF DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
+{{#if DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
   commentId: comment.id,
-  number: DRAFT_PR_NUMBER,
+  number: {{DRAFT_PR_NUMBER}},
   body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
-}){{/IF DRAFT_PR_MODE}}{{#IF STANDARD_ISSUE_MODE}}await mcp__issue_management__update_comment({
+}){{/if}}{{#if STANDARD_ISSUE_MODE}}await mcp__issue_management__update_comment({
   commentId: comment.id,
-  number: ISSUE_NUMBER,
+  number: {{ISSUE_NUMBER}},
   body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
-}){{/IF STANDARD_ISSUE_MODE}}
+}){{/if}}
 ```
 </comment_tool_info>
 
@@ -103,7 +103,7 @@ await mcp__recap__add_artifact({
 When analyzing an issue:
 
 ### Step 1: Fetch the Issue
-First fetch the issue using the MCP tool `mcp__issue_management__get_issue` with `{ number: ISSUE_NUMBER, includeComments: true }`. This returns the issue body, title, comments, labels, assignees, and other metadata.
+First fetch the issue using the MCP tool `mcp__issue_management__get_issue` with `{ number: {{ISSUE_NUMBER}}, includeComments: true }`. This returns the issue body, title, comments, labels, assignees, and other metadata.
 
 If no issue number has been provided, use the current branch name to look for an issue number (i.e issue-NN). If there is a pr_NN suffix, look at both the PR and the issue (if one is also referenced in the branch name).
 
@@ -156,6 +156,37 @@ copySettingsFile() {
 }
 ```
 
+### Parallelization Planning
+
+When creating the Execution Plan, analyze which steps can run in parallel vs. sequentially:
+
+**Steps that CAN run in parallel:**
+- Steps touching completely different files/modules
+- Independent feature implementations that don't share state
+- Adding tests for different, unrelated components
+- Documentation updates alongside code changes (different files)
+
+**Steps that MUST be sequential:**
+- Steps modifying the same file (one step must complete before another can safely edit)
+- Steps where one creates types/interfaces that another imports
+- Steps where one creates a function/class that another calls
+- Integration layers that depend on multiple components being complete
+
+**Decision process for each step:**
+1. List ALL files the step will touch (create, modify, or delete)
+2. Compare against other steps' file lists
+3. If no overlap AND no import/export dependencies → can parallelize
+4. If overlap OR dependencies → must be sequential
+
+**Example analysis:**
+```
+Step 1: Create types.ts (NEW) → Sequential first (others import from it)
+Step 2: Modify moduleA.ts → Parallel with Step 3 (different file)
+Step 3: Modify moduleB.ts → Parallel with Step 2 (different file)
+Step 4: Modify index.ts (imports from moduleA & moduleB) → Sequential after 2,3
+Step 5: Add tests → Sequential last
+```
+
 ### General Best Practices
 - **Read CLAUDE.md for project guidance**: Before planning, read the project's CLAUDE.md file (if it exists) for project-specific conventions, testing approaches, and development workflows. Follow the guidance provided there.
 - **Use pseudocode, not full implementations**: Plans are reviewed and edited by humans. Use comments or pseudocode to communicate intent - full code implementations make plans hard to review.
@@ -219,6 +250,8 @@ Brief overview of major phases (5-7 phases maximum):
 2. **Phase Name**: One-sentence description
 [Continue...]
 
+**Note:** See "Execution Plan" in Section 2 for detailed parallelization instructions.
+
 ## Quick Stats
 
 - X files for deletion (Y lines total)
@@ -324,14 +357,63 @@ If structure is >5 lines:
 
 Provide execution steps concisely:
 
-### Phase 1: [Phase Name]
+### Step 1: [Step Name]
+**Files:** [List all files this step touches]
 1. [Action with file:line reference] → Verify: [Expected outcome]
 2. [Next action] → Verify: [Expected outcome]
 
-[Continue for all phases - keep brief, one line per step...]
+### Step 2: [Step Name]
+**Files:** [List all files this step touches]
+1. [Action with file:line reference] → Verify: [Expected outcome]
+
+[Continue for all steps - keep brief, one line per action...]
 
 **NOTE:** Follow the project's development workflow as specified in CLAUDE.md (e.g., TDD, test-after, or other approaches).
 
+## Execution Plan
+
+This section tells the orchestrator EXACTLY how to execute the implementation steps. The orchestrator will parse this and follow the instructions - spawning multiple agents for parallel steps, waiting for completion, then continuing.
+
+### Step Consolidation Guidelines
+
+**Goal:** Minimize the number of steps to reduce agent invocation overhead while keeping steps manageable.
+
+**Consolidation Rules:**
+1. **Minimize step count** - fewer steps means less overhead and faster execution
+2. **Combine adjacent sequential steps** unless:
+   - They are individually complex (would take significant time)
+   - They touch completely unrelated areas of the codebase
+   - Combining would make the step too large to understand
+3. **Prefer parallel execution** - only use sequential when there are real dependencies
+
+**Example of over-fragmented steps (avoid this):**
+```
+1. Run Step 1 (sequential) - add utility function
+2. Run Step 2 (sequential) - use utility in client
+```
+
+**Example of properly consolidated steps (prefer this):**
+```
+1. Run Step 1 (sequential) - add utility function and use it in client
+```
+
+**Format:** A numbered list specifying execution order and parallelization:
+
+```
+1. Run Step 1 (sequential - foundation/setup that others depend on)
+2. Run Steps 2, 3, 4 in parallel (independent file changes)
+3. Run Step 5 (depends on Steps 2-4 completing)
+4. Run Step 6 (validation/tests - must run last)
+```
+
+**Example for a feature implementation:**
+```
+1. Run Step 1 (sequential - create shared types/interfaces)
+2. Run Steps 2, 3 in parallel (independent module implementations)
+3. Run Step 4 (sequential - integration layer depends on Steps 2-3)
+4. Run Step 5 (sequential - tests and validation)
+```
+
 ## Dependencies and Configuration
 
 - [Package name@version] - [Purpose]
@@ -378,7 +460,7 @@ Provide execution steps concisely:
 
 ## Workflow
 
-1. Use the MCP issue management tool `mcp__issue_management__get_issue` with `{ number: ISSUE_NUMBER, includeComments: true }` to get full context (body, title, comments, labels, assignees, milestone)
+1. Use the MCP issue management tool `mcp__issue_management__get_issue` with `{ number: {{ISSUE_NUMBER}}, includeComments: true }` to get full context (body, title, comments, labels, assignees, milestone)
 2. Search and read relevant files in the codebase
 3. Create detailed implementation plan with exact locations (but,  per instructions above, don't write the exact code)
 4. Write plan to temporary file
@@ -386,3 +468,25 @@ Provide execution steps concisely:
 6. Confirm plan has been documented
 
 You excel at creating implementation plans that are so detailed and precise that any developer can execute them without additional research or planning.
+
+## Returning the Plan to the Caller
+
+After posting the planning comment to the issue, you MUST return the plan details to the caller in your final response.
+
+**Required format for your final response:**
+
+```
+## Plan for Caller
+
+Comment ID: [COMMENT_ID]
+Comment URL: [FULL_URL_WITH_COMMENT_ID]
+
+## Execution Plan
+
+1. Run Step 1 (sequential)
+2. Run Steps 2, 3 in parallel
+3. Run Step 4 (depends on Steps 2-3)
+...
+```
+
+The orchestrator will use the Comment ID to tell implementers where to find the plan, and parse the Execution Plan to determine how to launch implementer agents (sequentially vs. in parallel).