@iloom/cli 0.6.1 → 0.7.1

package/LICENSE

@@ -20,7 +20,7 @@ it within your organization. What is prohibited is redistributing or offering
 access to this software (in original or modified form) as part of something
 you sell or provide to others.
 
-Change Date: 2029-01-01  
+Change Date: 2030-01-15  
 Change License: Apache License 2.0
 
 For clarity, on or after the Change Date, the Licensed Work will

package/README.md

@@ -16,7 +16,7 @@ iloom
 
 #### Links to key sections
 
-[How It Works](#how-it-works-the-multi-agent-workflow) • [Installation](#quick-start) • [Configuration](#configuration) • [Advanced Features](#advanced-features) • [Limitations](#system-requirements--limitations)
+[How It Works](#how-it-works-the-multi-agent-workflow) • [Installation](#quick-start) • [Configuration](#configuration) • [Advanced Features](#advanced-features) • [Limitations](#system-requirements--limitations) • [Contributing](#contributing-to-iloom)
 
 ## Built For Modern Tools...
 
@@ -90,17 +90,21 @@ When you run il start, iloom orchestrates specialized AI agents. Each has a spec
 
 ### 1. The Agents
 
-Instead of a single generic prompt, iloom uses a pipeline of agents:
+Instead of a single generic prompt, iloom uses a pipeline of specialized agents:
+
+*   **Enhancer:** Expands brief one-liners into detailed requirements with acceptance criteria.
+
+*   **Evaluator:** Assesses complexity and routes to the appropriate workflow:
 
-*   **Enhancer (iloom-issue-enhancer):** Expands brief one-liners into detailed requirements.
-    
-*   **Evaluator (iloom-issue-complexity-evaluator):** Determines the workflow approach:
-    
     *   **Simple:** Combines analysis and planning into one step for efficiency.
-        
-    *   **Complex:** Separates deep root-cause analysis from detailed implementation planning.
-        
-*   **Implementer:** Executes the plan using the context established in the previous steps.
+
+    *   **Complex:** Separates deep analysis from detailed planning for thorough coverage.
+
+*   **Analyzer:** Explores the problem space before any code is written. This agent investigates the codebase to understand existing patterns, examines third-party library APIs and capabilities, and researches technical approaches. The result is a comprehensive analysis that informs the planning phase—leading to significantly better implementation plans than jumping straight to code.
+
+*   **Planner:** Creates an execution plan with parallelization analysis—identifying which steps can run concurrently vs. sequentially. Plans reference specific files and line numbers, making them actionable and precise.
+
+*   **Implementer:** Executes the plan using the context established in the previous steps. For complex tasks, multiple implementers can run in parallel on independent steps.
     
 
 ### 2. Interactive Control
@@ -137,9 +141,10 @@ Command Reference
 | **Command** | **Alias** |  **Description** |
 | ------ | ----- | -----|
 | `il start` | `new` | Create loom, run analysis agents, and launch IDE. |
+| `il commit` | `c` | Commit all files with issue reference (`Refs #N` or `Fixes #N`). |
 | `il finish` | `dn` | Validate tests/lint, commit, handle conflicts, and merge/PR. |
 | `il cleanup` | `remove` | Safely remove a loom and its database branch without merging. |
-| `il list` |  | Show active looms and paths. |
+| `il list` |  | Show active looms for current project. `--finished` for archived, `--all` for active + archived, `--global` for looms across all projects. |
 | `il projects` |  | List configured projects (JSON output). |
 | `il spin` |  | Launch Claude inside the current loom with context auto-detected. |
 | `il open` | `run` | Open loom in browser (web) or run your CLI tool. |
@@ -149,6 +154,7 @@ Command Reference
 | `il test` |  | Run the test script for a workspace. |
 | `il compile` | `typecheck` | Run the compile or typecheck script for a workspace. |
 | `il add-issue` | `a` | Create and AI-enhance a new issue without starting work yet. |
+| `il contribute` |  | Fork, clone, and set up a GitHub repo for contribution (defaults to iloom-cli). |
 | `il init` | `config` | Interactive configuration wizard. |
 | `il feedback` | `f` | Submit bug reports/feedback directly from the CLI. |
 | `il update` |  | Update iloom CLI to the latest version. |
@@ -470,16 +476,23 @@ This is an early-stage product.
 
 See all [known limitations](https://github.com/iloom-ai/iloom-cli/issues?q=is:issue+is:open+label:known-limitation) on GitHub. If you're feeling left out - you're absolutely right! The best way to complain about something is to fix it. So...
 
-Contributing
-------------
+Contributing to iloom
+---------------------
 
-We (Claude and I) welcome contributions! We've made it easy to get started — iloom can even set up its own dev environment.
+We (Claude and I) welcome contributions! iloom can set up its own dev environment:
 
 ```bash
-iloom contribute   # Handles forking, cloning, and setting up the dev environment automatically.
+iloom contribute   # Handles forking, cloning, and dev setup automatically
 ```
 
-You can also use `iloom contribute` to set up any GitHub repository for contribution:
+**PR Requirements:** All PRs should be created with iloom or include detailed context. If you're not using iloom, please provide equivalent detail explaining your approach and reasoning.
+
+New contributors should start with issues labeled [starter-task](https://github.com/iloom-ai/iloom-cli/issues?q=is%3Aissue+is%3Aopen+label%3Astarter-task). For details, see our [Contributing Guide](CONTRIBUTING.md).
+
+Contributing to Open Source
+---------------------------
+
+iloom streamlines the fork → clone → setup → PR workflow for any GitHub repository:
 
 ```bash
 # Full URL format
@@ -492,9 +505,13 @@ iloom contribute "github.com/n8n-io/n8n"
 iloom contribute "n8n-io/n8n"
 ```
 
-**All PRs should be created with iloom or include detailed context.** When you run `iloom contribute`, it configures iloom to create a draft PR as soon as you start work. As you work, iloom posts the AI's analysis, implementation plan, and progress directly to that draft PR—giving reviewers full context before the code is even ready for review. If you're not using iloom, please provide equivalent detail in your PR.
+This command:
+1. Forks the repository (if not already forked)
+2. Clones your fork locally
+3. Configures iloom for the project
+4. Sets merge behavior to `github-draft-pr` (creates a draft PR immediately when you start work)
 
-New contributors should start with issues labeled [starter-task](https://github.com/iloom-ai/iloom-cli/issues?q=is%3Aissue+is%3Aopen+label%3Astarter-task). For details, see our [Contributing Guide](CONTRIBUTING.md).
+The draft PR workflow is ideal for open source: as you work, iloom posts the AI's analysis, implementation plan, and progress directly to that draft PR—giving maintainers full context before the code is even ready for review.
 
 License & Name
 --------------

package/dist/{BranchNamingService-B5PVRR7F.js → BranchNamingService-FLPUUFOB.js}

@@ -3,7 +3,7 @@ import {
   ClaudeBranchNameStrategy,
   DefaultBranchNamingService,
   SimpleBranchNameStrategy
-} from "./chunk-5TXLVEXT.js";
+} from "./chunk-C3AKFAIR.js";
 import "./chunk-6MLEBAYZ.js";
 import "./chunk-VT4PDUYT.js";
 export {
@@ -11,4 +11,4 @@ export {
   DefaultBranchNamingService,
   SimpleBranchNameStrategy
 };
-//# sourceMappingURL=BranchNamingService-B5PVRR7F.js.map
+//# sourceMappingURL=BranchNamingService-FLPUUFOB.js.map

package/dist/ClaudeContextManager-KE5TBZVZ.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import {
+  ClaudeContextManager
+} from "./chunk-6TL3BYH6.js";
+import "./chunk-KVS4XGBQ.js";
+import "./chunk-TIYJEEVO.js";
+import "./chunk-WFQ5CLTR.js";
+import "./chunk-FP7G7DG3.js";
+import "./chunk-6MLEBAYZ.js";
+import "./chunk-VT4PDUYT.js";
+export {
+  ClaudeContextManager
+};
+//# sourceMappingURL=ClaudeContextManager-KE5TBZVZ.js.map

package/dist/ClaudeService-CRSETT3A.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import {
+  ClaudeService
+} from "./chunk-KVS4XGBQ.js";
+import "./chunk-TIYJEEVO.js";
+import "./chunk-WFQ5CLTR.js";
+import "./chunk-FP7G7DG3.js";
+import "./chunk-6MLEBAYZ.js";
+import "./chunk-VT4PDUYT.js";
+export {
+  ClaudeService
+};
+//# sourceMappingURL=ClaudeService-CRSETT3A.js.map

package/dist/{GitHubService-S2OGUTDR.js → GitHubService-O7U4UQ7N.js}

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import {
   GitHubService
-} from "./chunk-3PT7RKL5.js";
-import "./chunk-LT3SGBR7.js";
+} from "./chunk-USJSNHGG.js";
+import "./chunk-GCPAZSGV.js";
 import "./chunk-ZX3GTM7O.js";
 import "./chunk-6MLEBAYZ.js";
 import "./chunk-VT4PDUYT.js";
 export {
   GitHubService
 };
-//# sourceMappingURL=GitHubService-S2OGUTDR.js.map
+//# sourceMappingURL=GitHubService-O7U4UQ7N.js.map

package/dist/{LoomLauncher-5LFM4LXB.js → LoomLauncher-NL65LSKP.js}

@@ -4,18 +4,18 @@ import {
 } from "./chunk-O7VL5N6S.js";
 import {
   ClaudeContextManager
-} from "./chunk-7WANFUIK.js";
-import "./chunk-6U6VI4SZ.js";
-import "./chunk-W6WVRHJ6.js";
+} from "./chunk-6TL3BYH6.js";
+import "./chunk-KVS4XGBQ.js";
+import "./chunk-TIYJEEVO.js";
 import {
   getExecutablePath
 } from "./chunk-GYCR2LOU.js";
-import "./chunk-F6WVM437.js";
+import "./chunk-WFQ5CLTR.js";
 import {
   generateColorFromBranchName,
   hexToRgb
 } from "./chunk-433MOLAU.js";
-import "./chunk-AEIMYF4P.js";
+import "./chunk-FP7G7DG3.js";
 import {
   getLogger
 } from "./chunk-6MLEBAYZ.js";
@@ -252,4 +252,4 @@ var LoomLauncher = class {
 export {
   LoomLauncher
 };
-//# sourceMappingURL=LoomLauncher-5LFM4LXB.js.map
+//# sourceMappingURL=LoomLauncher-NL65LSKP.js.map

package/dist/{MetadataManager-DFI73J3G.js → MetadataManager-XJ2YB762.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   MetadataManager
-} from "./chunk-CFUWQHCJ.js";
+} from "./chunk-VWGKGNJP.js";
 import "./chunk-6MLEBAYZ.js";
 import "./chunk-VT4PDUYT.js";
 export {
   MetadataManager
 };
-//# sourceMappingURL=MetadataManager-DFI73J3G.js.map
+//# sourceMappingURL=MetadataManager-XJ2YB762.js.map

package/dist/PRManager-2ABCWXHW.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import {
+  PRManager
+} from "./chunk-EPPPDVHD.js";
+import "./chunk-YETJNRQM.js";
+import "./chunk-GJMEKEI5.js";
+import "./chunk-HBJITKSZ.js";
+import "./chunk-FXDYIV3K.js";
+import "./chunk-GCPAZSGV.js";
+import "./chunk-FP7G7DG3.js";
+import "./chunk-6MLEBAYZ.js";
+import "./chunk-VT4PDUYT.js";
+export {
+  PRManager
+};
+//# sourceMappingURL=PRManager-2ABCWXHW.js.map

package/dist/{ProjectCapabilityDetector-S5FLNCFI.js → ProjectCapabilityDetector-IA56AUE6.js}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import {
   ProjectCapabilityDetector
-} from "./chunk-ZPSTA5PR.js";
-import "./chunk-BXCPJJYM.js";
+} from "./chunk-7GLZVDPQ.js";
+import "./chunk-XPKN3QWY.js";
 import "./chunk-6MLEBAYZ.js";
 import "./chunk-VT4PDUYT.js";
 export {
   ProjectCapabilityDetector
 };
-//# sourceMappingURL=ProjectCapabilityDetector-S5FLNCFI.js.map
+//# sourceMappingURL=ProjectCapabilityDetector-IA56AUE6.js.map

package/dist/{PromptTemplateManager-C3DK6XZL.js → PromptTemplateManager-7L3HJQQU.js}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import {
   PromptTemplateManager
-} from "./chunk-W6WVRHJ6.js";
+} from "./chunk-TIYJEEVO.js";
 import "./chunk-VT4PDUYT.js";
 export {
   PromptTemplateManager
 };
-//# sourceMappingURL=PromptTemplateManager-C3DK6XZL.js.map
+//# sourceMappingURL=PromptTemplateManager-7L3HJQQU.js.map

package/dist/README.md

@@ -16,7 +16,7 @@ iloom
 
 #### Links to key sections
 
-[How It Works](#how-it-works-the-multi-agent-workflow) • [Installation](#quick-start) • [Configuration](#configuration) • [Advanced Features](#advanced-features) • [Limitations](#system-requirements--limitations)
+[How It Works](#how-it-works-the-multi-agent-workflow) • [Installation](#quick-start) • [Configuration](#configuration) • [Advanced Features](#advanced-features) • [Limitations](#system-requirements--limitations) • [Contributing](#contributing-to-iloom)
 
 ## Built For Modern Tools...
 
@@ -90,17 +90,21 @@ When you run il start, iloom orchestrates specialized AI agents. Each has a spec
 
 ### 1. The Agents
 
-Instead of a single generic prompt, iloom uses a pipeline of agents:
+Instead of a single generic prompt, iloom uses a pipeline of specialized agents:
+
+*   **Enhancer:** Expands brief one-liners into detailed requirements with acceptance criteria.
+
+*   **Evaluator:** Assesses complexity and routes to the appropriate workflow:
 
-*   **Enhancer (iloom-issue-enhancer):** Expands brief one-liners into detailed requirements.
-    
-*   **Evaluator (iloom-issue-complexity-evaluator):** Determines the workflow approach:
-    
     *   **Simple:** Combines analysis and planning into one step for efficiency.
-        
-    *   **Complex:** Separates deep root-cause analysis from detailed implementation planning.
-        
-*   **Implementer:** Executes the plan using the context established in the previous steps.
+
+    *   **Complex:** Separates deep analysis from detailed planning for thorough coverage.
+
+*   **Analyzer:** Explores the problem space before any code is written. This agent investigates the codebase to understand existing patterns, examines third-party library APIs and capabilities, and researches technical approaches. The result is a comprehensive analysis that informs the planning phase—leading to significantly better implementation plans than jumping straight to code.
+
+*   **Planner:** Creates an execution plan with parallelization analysis—identifying which steps can run concurrently vs. sequentially. Plans reference specific files and line numbers, making them actionable and precise.
+
+*   **Implementer:** Executes the plan using the context established in the previous steps. For complex tasks, multiple implementers can run in parallel on independent steps.
     
 
 ### 2. Interactive Control
@@ -137,9 +141,10 @@ Command Reference
 | **Command** | **Alias** |  **Description** |
 | ------ | ----- | -----|
 | `il start` | `new` | Create loom, run analysis agents, and launch IDE. |
+| `il commit` | `c` | Commit all files with issue reference (`Refs #N` or `Fixes #N`). |
 | `il finish` | `dn` | Validate tests/lint, commit, handle conflicts, and merge/PR. |
 | `il cleanup` | `remove` | Safely remove a loom and its database branch without merging. |
-| `il list` |  | Show active looms and paths. |
+| `il list` |  | Show active looms for current project. `--finished` for archived, `--all` for active + archived, `--global` for looms across all projects. |
 | `il projects` |  | List configured projects (JSON output). |
 | `il spin` |  | Launch Claude inside the current loom with context auto-detected. |
 | `il open` | `run` | Open loom in browser (web) or run your CLI tool. |
@@ -149,6 +154,7 @@ Command Reference
 | `il test` |  | Run the test script for a workspace. |
 | `il compile` | `typecheck` | Run the compile or typecheck script for a workspace. |
 | `il add-issue` | `a` | Create and AI-enhance a new issue without starting work yet. |
+| `il contribute` |  | Fork, clone, and set up a GitHub repo for contribution (defaults to iloom-cli). |
 | `il init` | `config` | Interactive configuration wizard. |
 | `il feedback` | `f` | Submit bug reports/feedback directly from the CLI. |
 | `il update` |  | Update iloom CLI to the latest version. |
@@ -470,16 +476,23 @@ This is an early-stage product.
 
 See all [known limitations](https://github.com/iloom-ai/iloom-cli/issues?q=is:issue+is:open+label:known-limitation) on GitHub. If you're feeling left out - you're absolutely right! The best way to complain about something is to fix it. So...
 
-Contributing
-------------
+Contributing to iloom
+---------------------
 
-We (Claude and I) welcome contributions! We've made it easy to get started — iloom can even set up its own dev environment.
+We (Claude and I) welcome contributions! iloom can set up its own dev environment:
 
 ```bash
-iloom contribute   # Handles forking, cloning, and setting up the dev environment automatically.
+iloom contribute   # Handles forking, cloning, and dev setup automatically
 ```
 
-You can also use `iloom contribute` to set up any GitHub repository for contribution:
+**PR Requirements:** All PRs should be created with iloom or include detailed context. If you're not using iloom, please provide equivalent detail explaining your approach and reasoning.
+
+New contributors should start with issues labeled [starter-task](https://github.com/iloom-ai/iloom-cli/issues?q=is%3Aissue+is%3Aopen+label%3Astarter-task). For details, see our [Contributing Guide](CONTRIBUTING.md).
+
+Contributing to Open Source
+---------------------------
+
+iloom streamlines the fork → clone → setup → PR workflow for any GitHub repository:
 
 ```bash
 # Full URL format
@@ -492,9 +505,13 @@ iloom contribute "github.com/n8n-io/n8n"
 iloom contribute "n8n-io/n8n"
 ```
 
-**All PRs should be created with iloom or include detailed context.** When you run `iloom contribute`, it configures iloom to create a draft PR as soon as you start work. As you work, iloom posts the AI's analysis, implementation plan, and progress directly to that draft PR—giving reviewers full context before the code is even ready for review. If you're not using iloom, please provide equivalent detail in your PR.
+This command:
+1. Forks the repository (if not already forked)
+2. Clones your fork locally
+3. Configures iloom for the project
+4. Sets merge behavior to `github-draft-pr` (creates a draft PR immediately when you start work)
 
-New contributors should start with issues labeled [starter-task](https://github.com/iloom-ai/iloom-cli/issues?q=is%3Aissue+is%3Aopen+label%3Astarter-task). For details, see our [Contributing Guide](CONTRIBUTING.md).
+The draft PR workflow is ideal for open source: as you work, iloom posts the AI's analysis, implementation plan, and progress directly to that draft PR—giving maintainers full context before the code is even ready for review.
 
 License & Name
 --------------

package/dist/{SettingsManager-35F5RUJH.js → SettingsManager-YU4VYPTW.js}

@@ -14,7 +14,7 @@ import {
   WorkflowPermissionSchemaNoDefaults,
   WorkflowsSettingsSchema,
   WorkflowsSettingsSchemaNoDefaults
-} from "./chunk-F6WVM437.js";
+} from "./chunk-WFQ5CLTR.js";
 import "./chunk-VT4PDUYT.js";
 export {
   AgentSettingsSchema,
@@ -32,4 +32,4 @@ export {
   WorkflowsSettingsSchema,
   WorkflowsSettingsSchemaNoDefaults
 };
-//# sourceMappingURL=SettingsManager-35F5RUJH.js.map
+//# sourceMappingURL=SettingsManager-YU4VYPTW.js.map

package/dist/agents/iloom-framework-detector.md

@@ -8,12 +8,57 @@ model: sonnet
 
 You are Claude, a framework detection specialist. Your task is to analyze a project's structure and generate appropriate install/build/test/dev scripts for iloom.
 
-**Your Core Mission**: Detect the project's programming language and framework, then create `.iloom/package.iloom.json` with appropriate shell commands for install, build, test, and development workflows.
+**Your Core Mission**: Detect the project's programming language and framework, then create the appropriate iloom package configuration file with shell commands for install, build, test, and development workflows.
 
 **Key Distinction:**
 - `install` - Installs dependencies (runs during loom creation and post-merge)
 - `build` - Compiles/builds the project (for compiled languages or asset compilation)
 
+---
+
+## 🍴 FORK CHECK - DO THIS FIRST (Before Any File Decisions)
+
+**CRITICAL: Before creating ANY configuration file, check if this is a fork.**
+
+### Step 0: Detect Fork Pattern
+
+Run this check FIRST, before any other detection work:
+
+```bash
+git remote -v 2>/dev/null | grep -E '^(origin|upstream)\s' | awk '{print $1}' | sort -u
+```
+
+**If BOTH `origin` AND `upstream` are present → This is a FORK**
+
+### Fork Mode Behavior
+
+When fork is detected:
+
+1. **Default to `.iloom/package.iloom.local.json`** (NOT `package.iloom.json`)
+2. **Inform the user immediately:**
+   ```
+   🍴 Fork Detected (origin + upstream remotes)
+
+   For fork contributors, iloom configuration should be saved to LOCAL files
+   to prevent your personal settings from appearing in PRs to upstream.
+
+   Recommendation: Save to `.iloom/package.iloom.local.json`
+   - This file is globally gitignored
+   - Won't appear in your PRs to upstream
+   - Local scripts merge with package.iloom.json (local takes precedence)
+
+   If the upstream project already has package.iloom.json, your local file
+   will override/extend those scripts for your environment only.
+   ```
+
+3. **Proceed with detection** but write to the local file by default
+
+### Non-Fork Behavior
+
+If only `origin` exists (or no upstream), proceed normally with `package.iloom.json`.
+
+---
+
 ## Core Workflow
 
 ### Step 1: Scan for Language Markers
@@ -299,18 +344,37 @@ Create `.iloom/package.iloom.json` with appropriate scripts and capabilities bas
 
 ### Step 4: Write the File
 
-1. Read `.iloom/package.iloom.json` first to check if it already exists
-2. **If the file exists:**
+**⚠️ CHECKPOINT: Verify fork status from Step 0 before proceeding.**
+
+If fork was detected (both `origin` and `upstream` remotes exist):
+- Default target file: `.iloom/package.iloom.local.json`
+- This prevents personal config from appearing in PRs to upstream
+
+If NOT a fork:
+- Default target file: `.iloom/package.iloom.json`
+
+**Writing Process:**
+
+1. **Determine target file** based on fork status (see above)
+2. Read the target file first to check if it already exists
+3. **If the file exists:**
    - Compare existing configuration with detected configuration
    - Preserve existing scripts (user may have customized them)
    - Only add missing scripts that were detected
    - Preserve existing capabilities, add any missing ones
    - Preserve any other existing fields (like `_metadata`)
-3. **If the file does not exist:**
+4. **If the file does not exist:**
    - Create the full detected configuration
-4. Ensure `.iloom/` directory exists
-5. Write the merged/new JSON to `.iloom/package.iloom.json`
-6. Report what was detected and what changes were made (if any)
+5. Ensure `.iloom/` directory exists
+6. Write the merged/new JSON to the target file
+7. Report what was detected, which file was written, and what changes were made (if any)
+
+**File Selection Summary:**
+| Scenario | Target File | Reason |
+|----------|-------------|--------|
+| Fork detected (origin + upstream) | `package.iloom.local.json` | Keeps PRs clean, gitignored globally |
+| Direct contributor (origin only) | `package.iloom.json` | Shared team configuration |
+| User explicitly requests shared | `package.iloom.json` | User override (even for forks) |
 
 ## Output Format
 
@@ -324,8 +388,9 @@ Detected:
 - Framework: [framework or "None detected"]
 - Package Manager: [package manager]
 - Capabilities: [cli, web, or none]
+- Fork Status: [Yes (origin + upstream) | No]
 
-Created: .iloom/package.iloom.json
+Created: .iloom/[package.iloom.json OR package.iloom.local.json]
 
 Configuration:
 - capabilities: [list of detected capabilities]
@@ -334,7 +399,11 @@ Configuration:
 - test: [command]
 - dev: [command]
 
-You can customize these settings by editing .iloom/package.iloom.json.
+[If fork]: This configuration was saved to the LOCAL file (package.iloom.local.json)
+           because you're working on a fork. This prevents your iloom settings
+           from appearing in PRs to upstream.
+
+You can customize these settings by editing .iloom/[filename].
 ```
 
 ## Error Handling

package/dist/agents/iloom-issue-analyze-and-plan.md

@@ -35,7 +35,7 @@ The recap panel helps users stay oriented without reading all your output. Captu
 
 ### Step 1: Fetch the Issue
 
-Read the issue thoroughly 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.
+Read the issue thoroughly 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.
 
 Extract:
 - The complete issue body for context
@@ -225,9 +225,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
@@ -250,15 +250,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: "# Combined Analysis and Planning\n\n- [ ] Perform lightweight analysis\n- [ ] Create implementation plan",
   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: "# Combined Analysis and Planning\n\n- [ ] Perform lightweight analysis\n- [ ] Create implementation plan",
   type: "issue"
-}){{/IF STANDARD_ISSUE_MODE}}
+}){{/if}}
 
 // Log the comment as an artifact
 await mcp__recap__add_artifact({
@@ -268,15 +268,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: "# Combined Analysis and Planning\n\n- [x] Perform lightweight analysis\n- [ ] Create implementation plan"
-}){{/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: "# Combined Analysis and Planning\n\n- [x] Perform lightweight analysis\n- [ ] Create implementation plan"
-}){{/IF STANDARD_ISSUE_MODE}}
+}){{/if}}
 ```
 </comment_tool_info>
 
@@ -449,9 +449,15 @@ If structure is >5 lines:
 
 ### Detailed Execution Order
 
-#### Phase 1: [Phase Name]
-1. [Action with file:line reference] → Verify: [Expected outcome]
-2. [Next action] → Verify: [Expected outcome]
+**NOTE:** These steps are executed in a SINGLE implementation run. The implementer follows them sequentially - do NOT create separate agent invocations for each step.
+
+1. **[Step Name]**
+   - Files: `/path/to/file1.ts`, `/path/to/file2.ts`
+   - [Action with file:line reference] → Verify: [Expected outcome]
+
+2. **[Step Name]**
+   - Files: `/path/to/file3.ts`
+   - [Action with file:line reference] → Verify: [Expected outcome]
 
 [Continue - keep brief, one line per step...]
 
@@ -692,3 +698,22 @@ Your success is measured by:
 Remember: You are handling a SIMPLE task that has been carefully classified. Perform lightweight analysis followed by detailed planning, combining what would normally be two separate phases into one streamlined workflow. Keep Section 1 brief for human decision-makers, Section 2 complete for implementers.
 
 **HOWEVER**: If you discover cross-cutting complexity during analysis (parameters flowing through 3+ layers), immediately escalate to COMPLEX workflow rather than attempting to complete the planning. Your early detection prevents implementation failures.
+
+## 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 implementation
+```
+
+The orchestrator will use the Comment ID to tell the implementer where to find the plan, and parse the Execution Plan to determine execution (for SIMPLE tasks, this is always a single step).