@iloom/cli 0.11.0 → 0.12.0

package/dist/README.md

@@ -111,9 +111,9 @@ Each loom is a fully isolated container for your work:
     `ILOOM_COLOR_HEX` is useful for downstream tools that want to visually distinguish looms. For example, a Vite app can read it via `import.meta.env.VITE_ILOOM_COLOR_HEX` to tint the UI. See [Vite Integration Guide](docs/vite-iloom-color.md) for details.
 
 *   **Unique Runtime:**
-    
-    *   **Web Apps:** Runs on a deterministic port (e.g., base port 3000 + issue #25 = 3025).
-        
+
+    *   **Web Apps:** Runs on a deterministic port (e.g., base port 3000 + issue #25 = 3025). Optionally supports [Docker mode](#docker-dev-server) for frameworks that don't respect `PORT`.
+
     *   **CLI Tools:** Creates an isolated binary copy (e.g., my-tool-25). You can run issue #25's version of your CLI alongside issue #99's version without conflicts. (Fun fact: iloom was built with iloom using this feature).
         
 *   **Context Persistence:** All reasoning is stored in issue comments. This makes the "why" behind the code visible to your teammates and your future self.
@@ -344,7 +344,7 @@ Control how `il finish` handles your work. Configure in `.iloom/settings.json`:
 ```json
 {
   "mergeBehavior": {
-    "mode": "local"  // "local", "github-pr", or "github-draft-pr"
+    "mode": "local"  // "local", "pr", or "draft-pr"
   }
 }
 ```
@@ -352,8 +352,8 @@ Control how `il finish` handles your work. Configure in `.iloom/settings.json`:
 | **Mode** | **Description** |
 |----------|-----------------|
 | `local` | (Default) Merge directly into main branch locally. Fast-forward merge, no PR created. |
-| `github-pr` | Push branch and create a GitHub PR on `il finish`. Worktree cleanup is optional. |
-| `github-draft-pr` | Create a draft PR immediately on `il start`. On `il finish`, the PR is marked ready for review. **Recommended for contributions to forked repos.** |
+| `pr` | Push branch and create a PR on `il finish`. Worktree cleanup is optional. |
+| `draft-pr` | Create a draft PR immediately on `il start`. On `il finish`, the PR is marked ready for review. **Recommended for contributions to forked repos.** |
 
 ### Artifact Review
 
@@ -411,8 +411,8 @@ When `il finish` or `il rebase` encounter rebase conflicts, iloom automatically
 
 Note: Potentially destructive commands like `git reset` and `git checkout` are intentionally not auto-approved to prevent accidental data loss.
 
-**When to use `github-draft-pr`:**
-- **Contributing to forks:** When you don't are contributing to a forked repo use this mode to create the PR from your fork immediately, allowing iloom's agents to post workflow comments directly to the PR instead of writing to the upstream repo's issues (which may not be appreciated by the repo owners).
+**When to use `draft-pr`:**
+- **Contributing to forks:** When you are contributing to a forked repo use this mode to create the PR from your fork immediately, allowing iloom's agents to post workflow comments directly to the PR instead of writing to the upstream repo's issues (which may not be appreciated by the repo owners).
 - CI runs on your branch during development (draft PRs trigger CI on most repos)
 - Your team requires PRs for all changes (no direct merges to main)
 - You want reviewers to see progress before the work is complete
@@ -430,6 +430,15 @@ iloom supports multiple issue tracking providers to fit your team's workflow.
 | **Linear**   | `il init` | Requires API token. Supports full read/write on Linear issues. |
 | **Jira**     | Configure in `.iloom/settings.json` | Atlassian Cloud. Requires API token. See [Jira Setup](#jira-setup) below. |
 
+### Version Control Providers
+
+Choose which platform hosts your pull requests and code reviews.
+
+| **Provider** | **Setup** | **Notes** |
+|--------------|-----------|-----------|
+| **GitHub**   | `gh auth login` | Default. Integrated with GitHub Issues. |
+| **BitBucket** | Configure in `.iloom/settings.json` | Atlassian Cloud. Requires API token. See [BitBucket Setup](#bitbucket-setup) below. |
+
 ### Jira Setup
 
 To use Jira as your issue tracker, add this configuration:
@@ -478,14 +487,122 @@ To use Jira as your issue tracker, add this configuration:
 - `doneStatuses`: (Optional) Status names to exclude from `il issues` lists (default: `["Done"]`). Set to match your Jira workflow, e.g., `["Done", "Closed", "Verified"]`
 - `transitionMappings`: (Optional) Map iloom states to your Jira workflow transition names
 
+### BitBucket Setup
+
+To use BitBucket for pull requests, add this configuration:
+
+**.iloom/settings.json (Committed)**
+```json
+{
+  "versionControl": {
+    "provider": "bitbucket",
+    "bitbucket": {
+      "username": "your-bitbucket-username",
+      "workspace": "your-workspace",
+      "repoSlug": "your-repo"
+    }
+  },
+  "mergeBehavior": {
+    "mode": "bitbucket-pr"
+  }
+}
+```
+
+**.iloom/settings.local.json (Gitignored - Never commit this file)**
+```json
+{
+  "versionControl": {
+    "bitbucket": {
+      "apiToken": "your-bitbucket-api-token"
+    }
+  }
+}
+```
+
+**Generate a BitBucket API Token:**
+1. Visit https://bitbucket.org/account/settings/app-passwords/
+2. Click "Create API token" (Note: App passwords were deprecated September 2025)
+3. Grant permissions: `repository:read`, `repository:write`, `pullrequest:read`, `pullrequest:write`
+4. Copy the token to `.iloom/settings.local.json`
+
+**Configuration Options:**
+- `username`: Your BitBucket username
+- `apiToken`: API token (store in settings.local.json only!)
+- `workspace`: (Optional) BitBucket workspace, auto-detected from git remote if not provided
+- `repoSlug`: (Optional) Repository slug, auto-detected from git remote if not provided
+- `reviewers`: (Optional) Array of BitBucket usernames to automatically add as PR reviewers. Usernames are resolved to BitBucket account IDs at PR creation time. Unresolved usernames are logged as warnings but don't block PR creation.
+
+**Example with Reviewers:**
+```json
+{
+  "versionControl": {
+    "provider": "bitbucket",
+    "bitbucket": {
+      "username": "your-bitbucket-username",
+      "reviewers": [
+        "alice.jones",
+        "bob.smith"
+      ]
+    }
+  },
+  "mergeBehavior": {
+    "mode": "bitbucket-pr"
+  }
+}
+```
+
+### Jira + BitBucket Together
+
+Use Jira for issues and BitBucket for pull requests:
+
+**.iloom/settings.json**
+```json
+{
+  "issueManagement": {
+    "provider": "jira",
+    "jira": {
+      "host": "https://yourcompany.atlassian.net",
+      "username": "your.email@company.com",
+      "projectKey": "PROJ"
+    }
+  },
+  "versionControl": {
+    "provider": "bitbucket",
+    "bitbucket": {
+      "username": "your-bitbucket-username"
+    }
+  },
+  "mergeBehavior": {
+    "mode": "bitbucket-pr"
+  }
+}
+```
+
+**.iloom/settings.local.json**
+```json
+{
+  "issueManagement": {
+    "jira": {
+      "apiToken": "your-jira-api-token"
+    }
+  },
+  "versionControl": {
+    "bitbucket": {
+      "apiToken": "your-bitbucket-api-token"
+    }
+  }
+}
+```
+
 
 ### IDE Support
 iloom creates isolated workspace settings for your editor. Color synchronization (visual context) only works best VS Code-based editors.
 
 *   **Supported:** VS Code, Cursor, Windsurf, Antigravity, WebStorm, IntelliJ, Sublime Text.
-    
+
 *   **Config:** Set your preference via `il init` or `il start --set ide.type=cursor`.
 
+
 ### Git Operation Settings
 
 Configure git operation timeouts for projects with long-running pre-commit hooks.
@@ -505,7 +622,6 @@ Configure git operation timeouts for projects with long-running pre-commit hooks
 
 **When to increase:** If you see timeout errors during `il commit` or `il finish`, your pre-commit hooks are taking longer than the default 60 seconds. Set a higher value based on your typical hook duration.
 
-
 Advanced Features
 -----------------
 
@@ -551,6 +667,27 @@ iloom provides first-class support for building CLI tools. When you start a loom
 > my-cli --version     # Unaffected by other looms' CLIs
 ```
 
+### Docker Dev Server
+
+By default, iloom runs your dev server as a native process and sets the `PORT` environment variable so each loom gets its own port. If your framework ignores `PORT` (e.g., Angular CLI hardcodes its listen port), you can opt in to Docker mode instead. You provide a Dockerfile, and iloom uses Docker's `-p` flag to map the container's port to the workspace port on the host — no changes to your app required.
+
+To enable it, create a Dockerfile that builds and runs your dev server, then set `devServer` to `"docker"` in `.iloom/settings.json`:
+
+```json
+{
+  "capabilities": {
+    "web": {
+      "devServer": "docker",
+      "containerPort": 4200
+    }
+  }
+}
+```
+
+Then use `il dev-server`, `il open`, or `il run` as normal.
+
+Docker Compose multi-service stacks are not yet supported — see [#332](https://github.com/iloom-ai/iloom-cli/issues/332) for the roadmap. For full configuration options and known limitations, see the [Complete Command Reference](docs/iloom-commands.md#docker-dev-server-mode).
+
 ### Epic Planning and Decomposition
 
 The `il plan` command launches an interactive Architect session that helps you break down complex features into manageable child issues.
@@ -673,7 +810,9 @@ This is an early-stage product.
 *   ✅ **Runtime:** Node.js 16+, Git 2.5+.
     
 *   ✅ **AI:** Claude CLI installed. A Claude Max subscription is recommended (iloom uses your subscription).
-    
+
+*   ☑️ **Docker** (optional): Only required if using [Docker dev server mode](#docker-dev-server). Docker Desktop or Docker Engine must be installed and running.
+
 
 **Project Support:**
 
@@ -718,7 +857,7 @@ 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)
+4. Sets merge behavior to `draft-pr` (creates a draft PR immediately when you start work)
 
 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.
 
@@ -726,6 +865,7 @@ Acknowledgments
 ----------------
 
 - [@NoahCardoza](https://github.com/NoahCardoza) — Jira Cloud integration (PR [#588](https://github.com/iloom-ai/iloom-cli/pull/588)): JiraApiClient, JiraIssueTracker, ADF/Markdown conversion, MCP provider, sprint/mine filtering, and `il issues` Jira support.
+- [@NoahCardoza](https://github.com/NoahCardoza) — BitBucket integration (PR [#609](https://github.com/iloom-ai/iloom-cli/pull/609)): BitBucketApiClient, BitBucketVCSProvider, PR creation/listing, reviewer resolution, repository auto-detection, and token redaction.
 - [@TickTockBent](https://github.com/TickTockBent) — Linux, WSL, and tmux terminal support (PR [#796](https://github.com/iloom-ai/iloom-cli/pull/796)): strategy-pattern terminal backends, GUI-to-tmux fallback for headless environments, WSL detection, and cross-platform terminal launching.
 - [@rexsilex](https://github.com/rexsilex) — Original Linux/WSL terminal support design (PR [#649](https://github.com/iloom-ai/iloom-cli/pull/649)): pioneered the strategy pattern and backend interface that inspired the final implementation.
 
@@ -740,7 +880,7 @@ License & Name
     
 *   ❌ You cannot resell iloom itself as a product or SaaS.
     
-*   Converts to Apache 2.0 on 2030-03-01.
+*   Converts to Apache 2.0 on 2030-03-10.
     
 
 See [LICENSE](https://raw.githubusercontent.com/iloom-ai/iloom-cli/main/LICENSE) for complete terms.

package/dist/{SettingsManager-WQ5NSGAH.js → SettingsManager-BMQCAXPP.js}

@@ -5,6 +5,8 @@ import {
   CapabilitiesSettingsSchema,
   CapabilitiesSettingsSchemaNoDefaults,
   DatabaseProvidersSettingsSchema,
+  DevServerSettingsSchema,
+  DevServerSettingsSchemaNoDefaults,
   IloomSettingsSchema,
   IloomSettingsSchemaNoDefaults,
   NeonSettingsSchema,
@@ -15,15 +17,19 @@ import {
   WorkflowPermissionSchema,
   WorkflowPermissionSchemaNoDefaults,
   WorkflowsSettingsSchema,
-  WorkflowsSettingsSchemaNoDefaults
-} from "./chunk-ET6A2JR4.js";
-import "./chunk-H2SSF24U.js";
+  WorkflowsSettingsSchemaNoDefaults,
+  mergeModeValues,
+  redactSensitiveFields
+} from "./chunk-653XBU3L.js";
+import "./chunk-VRPPI6GU.js";
 export {
   AgentSettingsSchema,
   BaseAgentSettingsSchema,
   CapabilitiesSettingsSchema,
   CapabilitiesSettingsSchemaNoDefaults,
   DatabaseProvidersSettingsSchema,
+  DevServerSettingsSchema,
+  DevServerSettingsSchemaNoDefaults,
   IloomSettingsSchema,
   IloomSettingsSchemaNoDefaults,
   NeonSettingsSchema,
@@ -34,6 +40,8 @@ export {
   WorkflowPermissionSchema,
   WorkflowPermissionSchemaNoDefaults,
   WorkflowsSettingsSchema,
-  WorkflowsSettingsSchemaNoDefaults
+  WorkflowsSettingsSchemaNoDefaults,
+  mergeModeValues,
+  redactSensitiveFields
 };
-//# sourceMappingURL=SettingsManager-WQ5NSGAH.js.map
+//# sourceMappingURL=SettingsManager-BMQCAXPP.js.map

package/dist/SettingsMigrationManager-ZPARZ5KH.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import {
+  SettingsMigrationManager
+} from "./chunk-AUYSAMXV.js";
+import "./chunk-NPVA65KS.js";
+import "./chunk-VRPPI6GU.js";
+export {
+  SettingsMigrationManager
+};
+//# sourceMappingURL=SettingsMigrationManager-ZPARZ5KH.js.map

package/dist/agents/iloom-code-reviewer.md

@@ -12,10 +12,11 @@ You are an expert code reviewer. Your task is to analyze code changes and provid
 
 **You are running in swarm mode as part of an autonomous workflow.**
 
-- **State transition**: Call `recap.set_loom_state` with state `code_review` at the start of your review. Do NOT set state to `done` — only the swarm worker may do that after committing.
+- **State transition**: Call `recap.set_loom_state` with state `code_review` and `worktreePath` (from your invocation prompt) at the start of your review. Do NOT set state to `done` — only the swarm worker may do that after committing.
 - **No human interaction**: Do NOT ask the user about critical issues. Report all findings directly to the caller.
 - **Concise output**: Return structured review results suitable for the orchestrator to process.
 - **Autonomous handling**: If critical issues are found, report them but do NOT wait for user confirmation.
+- **IMPORTANT recap routing**: You are running inline in a swarm worker's context. You MUST pass `worktreePath` on ALL recap calls (`set_loom_state`, `add_entry`, `get_recap`). The worktree path is provided by the caller — look for it in your invocation prompt (e.g., "Your worktree path is ..."). Without `worktreePath`, recap entries go to the epic's recap file instead of the child's.
 {{/if}}
 
 ## Do NOT Review Temporal Information

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

@@ -1,7 +1,6 @@
 ---
 name: iloom-framework-detector
 description: Use this agent to detect a project's language and framework, then generate appropriate build/test/dev scripts for non-Node.js projects. The agent creates `.iloom/package.iloom.json` with shell commands tailored to the detected stack. Use this for Python, Rust, Ruby, Go, and other non-Node.js projects that don't have a package.json.
-tools: Bash, Glob, Grep, Read, Write
 color: cyan
 model: opus
 ---

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

@@ -1,7 +1,6 @@
 ---
 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__get_issue, mcp__issue_management__get_pr, mcp__issue_management__get_comment, mcp__issue_management__create_comment, mcp__issue_management__update_comment, mcp__issue_management__create_dependency, mcp__issue_management__get_dependencies, mcp__issue_management__remove_dependency, mcp__recap__get_recap, mcp__recap__add_entry, mcp__recap__add_artifact
 color: teal
 model: opus
 ---
@@ -42,6 +41,10 @@ The recap panel helps users stay oriented without reading all your output. Captu
 - `recap.add_entry` - Log with appropriate type
 - `recap.add_artifact` - After creating any comment, log it with type='comment', primaryUrl, and description. Re-calling with the same primaryUrl will update the existing entry.
 
+{{#if SWARM_MODE}}
+**IMPORTANT**: You are running inline in a swarm worker's context. You MUST pass `worktreePath` on ALL recap calls (`add_artifact`, `add_entry`, `set_complexity`, `set_loom_state`, `get_recap`). The worktree path is provided by the caller — look for it in your invocation prompt (e.g., "Your worktree path is ..."). Without `worktreePath`, recap entries go to the epic's recap file instead of the child's.
+{{/if}}
+
 **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"

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

@@ -1,7 +1,6 @@
 ---
 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__get_issue, mcp__issue_management__get_pr, mcp__issue_management__get_comment, mcp__issue_management__create_comment, mcp__issue_management__update_comment, mcp__issue_management__create_dependency, mcp__issue_management__get_dependencies, mcp__issue_management__remove_dependency, mcp__recap__get_recap, mcp__recap__add_entry, mcp__recap__add_artifact
 color: pink
 model: opus
 ---
@@ -45,6 +44,10 @@ The recap panel helps users stay oriented without reading all your output. Captu
 - `recap.add_entry` - Log with type: `insight` or `risk`
 - `recap.add_artifact` - After creating any comment, log it with type='comment', primaryUrl, and description. Re-calling with the same primaryUrl will update the existing entry.
 
+{{#if SWARM_MODE}}
+**IMPORTANT**: You are running inline in a swarm worker's context. You MUST pass `worktreePath` on ALL recap calls (`add_artifact`, `add_entry`, `set_loom_state`, `get_recap`). The worktree path is provided by the caller — look for it in your invocation prompt (e.g., "Your worktree path is ..."). Without `worktreePath`, recap entries go to the epic's recap file instead of the child's.
+{{/if}}
+
 **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"

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

@@ -1,7 +1,6 @@
 ---
 name: iloom-issue-complexity-evaluator
 description: Use this agent when you need to quickly assess the complexity of an issue before deciding on the appropriate workflow. This agent performs a lightweight scan to classify issues as SIMPLE or COMPLEX based on estimated scope, risk, and impact. Runs first before any detailed analysis or 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__get_issue, mcp__issue_management__get_pr, mcp__issue_management__get_comment, mcp__issue_management__create_comment, mcp__issue_management__update_comment, mcp__issue_management__create_dependency, mcp__issue_management__get_dependencies, mcp__issue_management__remove_dependency, mcp__recap__get_recap, mcp__recap__add_entry, mcp__recap__add_artifact, mcp__recap__set_complexity
 color: orange
 model: haiku
 ---
@@ -46,6 +45,10 @@ The recap panel helps users stay oriented without reading all your output. Use t
 - `recap.add_entry` - Log with type: `insight`, `risk`, or `assumption`
 - `recap.add_artifact` - Log comments with type='comment', primaryUrl (full URL with comment ID), and description
 
+{{#if SWARM_MODE}}
+**IMPORTANT**: You are running inline in a swarm worker's context. You MUST pass `worktreePath` on ALL recap calls (`add_artifact`, `add_entry`, `set_complexity`, `set_loom_state`, `get_recap`). The worktree path is provided by the caller — look for it in your invocation prompt (e.g., "Your worktree path is ..."). Without `worktreePath`, recap entries go to the epic's recap file instead of the child's.
+{{/if}}
+
 **IMPORTANT**: Use `set_complexity` (not `add_entry`) for complexity assessments:
 ```
 recap.set_complexity({ complexity: 'simple', reason: 'Few files, low risk' })

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

@@ -1,7 +1,6 @@
 ---
 name: iloom-issue-enhancer
 description: Use this agent when you need to analyze bug or enhancement reports from a Product Manager perspective. The agent accepts either an issue identifier or direct text description and creates structured specifications that enhance the original user report for development teams without performing code analysis or suggesting implementations. Ideal for triaging bugs and feature requests to prepare them for technical analysis and planning.\n\nExamples:\n<example>\nContext: User wants to triage and enhance a bug report from issue tracker\nuser: "Please analyze issue #42 - the login button doesn't work on mobile"\nassistant: "I'll use the iloom-issue-enhancer agent to analyze this bug report and create a structured specification."\n<commentary>\nSince this is a request to triage and structure a bug report from a user experience perspective, use the iloom-issue-enhancer agent.\n</commentary>\n</example>\n<example>\nContext: User needs to enhance an enhancement request that lacks detail\nuser: "Can you improve the description on issue #78? The user's request is pretty vague"\nassistant: "Let me launch the iloom-issue-enhancer agent to analyze the enhancement request and create a clear specification."\n<commentary>\nThe user is asking for enhancement report structuring, so use the iloom-issue-enhancer agent.\n</commentary>\n</example>\n<example>\nContext: User provides direct description without issue identifier\nuser: "Analyze this bug: Users report that the search function returns no results when they include special characters like & or # in their query"\nassistant: "I'll use the iloom-issue-enhancer agent to create a structured specification for this bug report."\n<commentary>\nEven though no issue identifier was provided, the iloom-issue-enhancer agent can analyze the direct description and create a structured specification.\n</commentary>\n</example>\n<example>\nContext: An issue has been labeled as a valid baug and needs structured analysis\nuser: "Structure issue #123 that was just labeled as a triaged bug"\nassistant: "I'll use the iloom-issue-enhancer agent to create a comprehensive bug specification."\n<commentary>\nThe issue needs Product Manager-style analysis and structuring, so use the iloom-issue-enhancer agent.\n</commentary>\n</example>
-tools: Bash, Glob, Grep, Read, WebFetch, WebSearch, BashOutput, KillShell, SlashCommand, ListMcpResourcesTool, ReadMcpResourceTool, mcp__context7__resolve-library-id, mcp__context7__get-library-docs, mcp__issue_management__get_issue, mcp__issue_management__get_pr, mcp__issue_management__get_comment, mcp__issue_management__create_comment, mcp__issue_management__update_comment, mcp__issue_management__create_dependency, mcp__issue_management__get_dependencies, mcp__issue_management__remove_dependency, mcp__recap__get_recap, mcp__recap__add_entry, mcp__recap__add_artifact
 color: purple
 model: opus
 ---
@@ -49,6 +48,10 @@ The recap panel helps users stay oriented without reading all your output. Captu
 - `recap.add_entry` - Log with type: `insight`, `risk`, or `assumption`
 - `recap.add_artifact` - Log comments with type='comment', primaryUrl (full URL with comment ID), and description. Re-calling with the same primaryUrl will update the existing entry.
 
+{{#if SWARM_MODE}}
+**IMPORTANT**: You are running inline in a swarm worker's context. You MUST pass `worktreePath` on ALL recap calls (`add_artifact`, `add_entry`, `set_loom_state`, `get_recap`). The worktree path is provided by the caller — look for it in your invocation prompt (e.g., "Your worktree path is ..."). Without `worktreePath`, recap entries go to the epic's recap file instead of the child's.
+{{/if}}
+
 **Log these:**
 - **insight**: User need discoveries - "Users need to configure multiple environments per project"
 - **risk**: User impact concerns - "Current behavior causes data loss when session expires mid-edit"

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

@@ -1,7 +1,6 @@
 ---
 name: iloom-issue-implementer
 description: Use this agent when you need to implement an issue exactly as specified in its comments and description. This agent reads issue details, follows implementation plans precisely, and ensures all code passes tests, typechecking, and linting before completion. Examples:\n\n<example>\nContext: User wants to implement a specific issue.\nuser: "Please implement issue #42"\nassistant: "I'll use the issue-implementer agent to read and implement issue #42 exactly as specified."\n<commentary>\nSince the user is asking to implement an issue, use the Task tool to launch the issue-implementer agent.\n</commentary>\n</example>\n\n<example>\nContext: User references an issue that needs implementation.\nuser: "Can you work on the authentication issue we discussed in #15?"\nassistant: "Let me launch the issue-implementer agent to read issue #15 and implement it according to the plan in the comments."\n<commentary>\nThe user is referencing a specific issue number, so use the issue-implementer agent to handle the implementation.\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 ,mcp__issue_management__get_issue, mcp__issue_management__get_pr, mcp__issue_management__get_comment, mcp__issue_management__create_comment, mcp__issue_management__update_comment, mcp__issue_management__create_dependency, mcp__issue_management__get_dependencies, mcp__issue_management__remove_dependency, mcp__recap__get_recap, mcp__recap__add_entry, mcp__recap__add_artifact, mcp__recap__set_loom_state, mcp__recap__get_loom_state
 model: opus
 color: green
 ---
@@ -14,7 +13,7 @@ color: green
 - **Issue context**: Read the issue number from `iloom-metadata.json` in the worktree root, or accept it as an invocation argument. Do NOT rely on a baked-in issue number.
 - **Comment routing**: Post comments to the issue. Get the issue number from your invocation prompt. Use `type: "issue"` with `mcp__issue_management__create_comment`.
 - **No human interaction**: Do NOT pause for user input or present options for decision. Make your best judgment and proceed.
-- **State transition**: Call `recap.set_loom_state` with state `in_progress` when you begin implementation. Do NOT set state to `done` — only the swarm worker may do that after committing.
+- **State transition**: Call `recap.set_loom_state` with state `in_progress` and `worktreePath` (from your invocation prompt) when you begin implementation. Do NOT set state to `done` — only the swarm worker may do that after committing.
 - **Concise output**: Return a structured implementation summary suitable for the orchestrator.
 - **Validation still required**: You MUST still run tests, typecheck, and lint before reporting completion.
 {{else}}
@@ -43,6 +42,10 @@ After creating or updating any issue comment, use the Recap MCP tools:
 
 This enables the recap panel to show quick-reference links to artifacts created during the session.
 
+{{#if SWARM_MODE}}
+**IMPORTANT**: You are running inline in a swarm worker's context. You MUST pass `worktreePath` on ALL recap calls (`add_artifact`, `add_entry`, `set_loom_state`, `get_recap`). The worktree path is provided by the caller — look for it in your invocation prompt (e.g., "Your worktree path is ..."). Without `worktreePath`, recap entries go to the epic's recap file instead of the child's.
+{{/if}}
+
 <comment_tool_info>
 IMPORTANT: You have been provided with MCP tools for issue management during this workflow.
 
@@ -174,11 +177,13 @@ NOTE: If no issue number has been provided, use the current branch name to look
 Before implementing, extract and validate the implementation plan:
 1. **Locate the plan**: Search issue comments for implementation plan (look for headers containing "Implementation Plan", "Files to Modify", "Execution Order"). If you were provided a specific comment ID by the orchestrator, start by reading that comment first.
 2. **Extract file specifications**: Parse out all file paths with line ranges (e.g., `/src/lib/Foo.ts:10-25`, `src/utils/bar.ts:42`)
+{{#unless SWARM_MODE}}
 3. **Validate file existence**: For each specified file path, verify the file exists using Read tool
 4. **Log validation results**: Display extracted file list and validation status to user
 5. **Handle extraction/validation failures**: If file extraction fails or plan specifies files that don't exist, immediately update your issue comment to notify the user of the issue but continue with implementation anyway. Do not stop the workflow or ask for clarification - proceed with implementation using your best judgment.
+{{/unless}}
 
-**CRITICAL**: This step prevents wasted time searching for files when the plan already provides exact locations.
+**CRITICAL**: Do not waste turns searching for files — the plan already provides exact locations. Use them directly when implementing.
 
 ### Step 1.6: Apply Step Filter (Multi-Step Execution)
 

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

@@ -1,7 +1,6 @@
 ---
 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__get_issue, mcp__issue_management__get_pr, mcp__issue_management__get_comment, mcp__issue_management__create_comment, mcp__issue_management__update_comment, mcp__issue_management__create_dependency, mcp__issue_management__get_dependencies, mcp__issue_management__remove_dependency, mcp__recap__get_recap, mcp__recap__add_entry, mcp__recap__add_artifact
 color: blue
 model: opus
 ---
@@ -42,6 +41,10 @@ The recap panel helps users stay oriented without reading all your output. Captu
 - `recap.add_entry` - Log with type: `decision` or `assumption`
 - `recap.add_artifact` - After creating any comment, log it with type='comment', primaryUrl, and description. Re-calling with the same primaryUrl will update the existing entry.
 
+{{#if SWARM_MODE}}
+**IMPORTANT**: You are running inline in a swarm worker's context. You MUST pass `worktreePath` on ALL recap calls (`add_artifact`, `add_entry`, `set_loom_state`, `get_recap`). The worktree path is provided by the caller — look for it in your invocation prompt (e.g., "Your worktree path is ..."). Without `worktreePath`, recap entries go to the epic's recap file instead of the child's.
+{{/if}}
+
 **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"