@iloom/cli 0.9.2 → 0.10.0

package/dist/README.md

@@ -18,46 +18,17 @@ 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) • [Contributing](#contributing-to-iloom)
+[How It Works](#how-it-works-the-multi-agent-workflow) • [Installation](#quick-start) • [Configuration](#configuration) • [Advanced Features](#advanced-features) • [Swarm Mode](#swarm-mode-epic-orchestration) • [Telemetry](#telemetry) • [Limitations](#system-requirements--limitations) • [Contributing](#contributing-to-iloom)
 
-## Built For Modern Tools...
+## How can your team trust the code your AI wrote, when you don't?
 
-[![Node.js](https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Next.js](https://img.shields.io/badge/Next.js-000000?style=for-the-badge&logo=nextdotjs&logoColor=white)](https://nextjs.org/)
-[![Neon](https://img.shields.io/badge/Neon-00E699?style=for-the-badge)](https://neon.tech/)
-[![Claude Code](https://img.shields.io/badge/Claude%20Code-8A6FFF?style=for-the-badge)](https://claude.ai/)
+Your agent just shipped a 2,000-line PR. Why did it restructure that module? What assumptions did it make about the auth flow? Nobody knows. The reasoning evaporated when the chat session ended, and now your teammate is staring at a diff with zero context. Good luck getting that reviewed.
 
-...To Solve A Very Modern Problem
----------------------------------
-
-The promise of AI-assisted development is profound: write more code, ship features faster. But there is a hidden cost. **AI agents write code quickly, but they struggle to stay in sync with their humans.**
-
-The hard part isn't generating code, it's maintaining the shared mental model of _why_ that code exists. When you rely on ephemeral chat windows, friction piles up:
-
-*   You constantly re-brief the AI on the same context.
-    
-*   Hidden assumptions creep in (e.g., "Why did it use Axios instead of fetch?").
-    
-*   You spend more time reviewing and "babysitting" the AI than building.
-    
-
-**The bottleneck isn't output velocity. It's maintaining alignment between human and AI at scale.**
-
-### The iloom Approach: Context as Infrastructure
+iloom persists the AI's analysis, plans, decisions, and risks as comments in your issue tracker. Not chat logs you'll never reopen. Not markdown files littering the repo. Your actual tracker, where your team can see what happened and why. That mountain of code you're sending for review? Now it comes with the reasoning behind it.
 
-iloom stops the "Context Window Tetris." It treats context as a first-class concern, persisting your AI's reasoning in **issue comments** rather than temporary chats.
+This matters because to get the most out of agents, you need to be multitasking across several of them. iloom gives every task its own isolated environment (git worktree, DB branch, unique port), and because all the reasoning is persisted, you can context-switch between tasks without losing the thread. The [VS Code extension](https://marketplace.visualstudio.com/items?itemName=iloom-ai.iloom-vscode) lets you catch up with any agent in seconds. Your teammates can pick up where you left off without a briefing.
 
-*   **Stop Babysitting, Start Collaborating:** Instead of arguing with Claude in a chat, you review structured analysis plans in your issue tracker _before_ a single line of code is written.
-    
-*   **Scale Understanding:** Because every loom holds its own isolated environment (Git worktree, DB branch, local server), you can switch between 5 complex features without losing your place or your AI's context.
-    
-*   **Visible Reasoning:** The AI's decisions are documented publicly. Your team sees the plan, and "future you" knows exactly why a decision was made.
-
-*   **Automatic Session Summaries:** When you finish a loom, iloom captures key insights, decisions, and lessons learned from your Claude session and posts them to the issue. These summaries become institutional knowledge that informs future tasks.
-
-
-_iloom is not just a tool for managing git worktrees - it's a control plane for maintaining alignment between you and your AI assistant._
+When a task outgrows one agent, `il plan` decomposes it into child issues with dependencies, and swarm mode launches parallel agents to execute them, each in its own worktree, running the full iloom workflow. You can one-shot entire features, entire products, and stay aligned. The VS Code extension gives you a Kanban board and dependency graph so you can see what's running, what's blocked, and what's done. The only real limit is your imagination. And maybe your Claude subscription.
 
 Quick Start
 -----------
@@ -105,6 +76,8 @@ Instead of a single generic prompt, iloom uses a pipeline of specialized agents:
 *   **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.
+
+*   **Swarm Orchestrator:** For epics with child issues, iloom enters [swarm mode](#swarm-mode-epic-orchestration)—launching parallel agent teams that implement each child issue autonomously in its own worktree, respecting dependency order.
     
 
 ### 2. Interactive Control
@@ -128,6 +101,15 @@ Each loom is a fully isolated container for your work:
 
 *   **Environment Variables:** Each loom has its own environment files (`.env`, `.env.local`, `.env.development`, `.env.development.local`). Uses `development` by default, override with `DOTENV_FLOW_NODE_ENV`. See [Secret Storage Limitations](#multi-language-project-support) for frameworks with encrypted credentials.
 
+    When inside a loom shell (`il shell`), the following environment variables are automatically set:
+
+    | Variable | Description | Example |
+    |----------|-------------|---------|
+    | `ILOOM_LOOM` | Loom identifier for PS1 customization | `issue-87` |
+    | `ILOOM_COLOR_HEX` | Hex color assigned to this loom (if available) | `#dcebff` |
+
+    `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).
@@ -142,13 +124,13 @@ Command Reference
 
 | **Command** | **Alias** |  **Description** |
 | ------ | ----- | -----|
-| `il start` | `new` | Create loom, run analysis agents, and launch IDE. |
+| `il start` | `new` | Create loom, run analysis agents, and launch IDE. Auto-detects epics with child issues for [swarm mode](#swarm-mode-epic-orchestration). |
 | `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 for current project. `--finished` for archived, `--all` for active + archived, `--global` for looms across all projects. |
+| `il list` |  | Show active looms for current project. `--finished` for archived, `--all` for active + archived, `--global` for looms across all projects. JSON output includes `swarmIssues` and `dependencyMap` for epic looms. |
 | `il projects` |  | List configured projects (JSON output). |
-| `il spin` |  | Launch Claude inside the current loom with context auto-detected. |
+| `il spin` |  | Launch Claude inside the current loom with context auto-detected. In epic looms, enters [swarm mode](#swarm-mode-epic-orchestration) with parallel agent orchestration. |
 | `il open` | `run` | Open loom in browser (web) or run your CLI tool. |
 | `il vscode` |  | Install iloom VS Code extension and open workspace in VS Code. |
 | `il dev-server` | `dev` | Start dev server in foreground for a workspace. |
@@ -162,6 +144,7 @@ Command Reference
 | `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. |
+| `il telemetry` |  | Manage anonymous usage telemetry (`on`, `off`, `status`). |
 
 For detailed documentation including all command options, flags, and examples, see the [Complete Command Reference](docs/iloom-commands.md).
 
@@ -439,12 +422,61 @@ Integrations
 
 ### Issue Trackers
 
-iloom supports the tools you already use. Unless you use JIRA.
+iloom supports multiple issue tracking providers to fit your team's workflow.
 
 | **Provider** | **Setup** | **Notes** |
 |--------------|-----------|-----------|
 | **GitHub**   | `gh auth login` | Default. Supports Issues and Pull Requests automatically. |
 | **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. |
+
+### Jira Setup
+
+To use Jira as your issue tracker, add this configuration:
+
+**.iloom/settings.json (Committed)**
+```json
+{
+  "issueManagement": {
+    "provider": "jira",
+    "jira": {
+      "host": "https://yourcompany.atlassian.net",
+      "username": "your.email@company.com",
+      "projectKey": "PROJ",
+      "boardId": "123",
+      "doneStatuses": ["Done", "Closed"],
+      "transitionMappings": {
+        "In Review": "Start Review"
+      }
+    }
+  }
+}
+```
+
+**.iloom/settings.local.json (Gitignored - Never commit this file)**
+```json
+{
+  "issueManagement": {
+    "jira": {
+      "apiToken": "your-jira-api-token-here"
+    }
+  }
+}
+```
+
+**Generate a Jira API Token:**
+1. Visit https://id.atlassian.com/manage-profile/security/api-tokens
+2. Click "Create API token"
+3. Copy the token to `.iloom/settings.local.json`
+
+**Configuration Options:**
+- `host`: Your Jira Cloud instance URL
+- `username`: Your Jira email address
+- `apiToken`: API token (store in settings.local.json only!)
+- `projectKey`: Jira project key (e.g., "PROJ", "ENG")
+- `boardId`: (Optional) Board ID for sprint/workflow operations
+- `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
 
 
 ### IDE Support
@@ -547,6 +579,88 @@ il plan --yolo "Add GitLab integration"
 
 See the [Complete Command Reference](docs/iloom-commands.md#il-plan) for all options including `--model`, `--planner`, and `--reviewer` flags.
 
+### Swarm Mode (Epic Orchestration)
+
+Swarm mode enables automatic, parallel execution of an entire epic by coordinating a team of AI agents. Each child issue gets its own worktree and agent, all working simultaneously while respecting dependency order.
+
+**Prerequisite:** Decompose your epic into child issues with dependencies first, using `il plan` or manually creating child issues and setting up blocking relationships.
+
+**How to trigger:**
+
+```bash
+# Auto-detect: iloom checks for child issues and prompts
+il start 100
+
+# Force epic mode (skip prompt)
+il start 100 --epic
+
+# Force normal loom even if children exist
+il start 100 --no-epic
+```
+
+When you run `il spin` inside the epic loom, swarm mode activates:
+
+1. **Child worktrees** are created for each child issue, branched off the epic branch
+2. **Swarm agents and skill files** are rendered into the epic loom's `.claude/` directory
+3. **Dependency DAG** is fetched from your issue tracker (blocking relationships between children)
+4. **Orchestrator launches** with Claude's experimental agent teams, using `bypassPermissions` mode
+5. **Parallel agents** are spawned for all unblocked child issues simultaneously
+6. As agents complete, their work is **rebased and fast-forward merged** into the epic branch
+7. **Newly unblocked issues** are spawned automatically as their dependencies finish
+8. **Failed children** are isolated — they don't block unrelated issues
+
+**Example workflow:**
+
+```bash
+# 1. Plan and decompose your epic
+il plan 100
+
+# 2. Start the epic loom (auto-detects children)
+il start 100 --epic
+
+# 3. Launch swarm mode
+il spin
+# The orchestrator takes over — parallel agents implement each child issue,
+# merge completed work, and handle failures autonomously.
+```
+
+Each child issue tracks its lifecycle state: `pending` -> `in_progress` -> `done` / `failed`. Use `il list --json` to see `swarmIssues` with per-child states and the `dependencyMap` for epic looms.
+
+For detailed reference on swarm mode behavior, see the [Complete Command Reference](docs/iloom-commands.md#swarm-mode-epic-orchestration).
+
+Telemetry
+---------
+
+iloom collects anonymous usage data to help improve the product. This data helps us understand which features are used, identify common errors, and prioritize development efforts.
+
+**What IS collected:**
+- Anonymous event data: command usage, feature adoption, and error types
+- An anonymous identifier (not linked to your identity)
+
+**What is NOT collected:**
+- GitHub/Linear/Jira usernames or emails
+- Repository names or URLs
+- Issue titles, descriptions, or content
+- File paths or code content
+- Branch names
+- AI analysis or plan content
+- Anything that could identify a specific project or person
+
+**Opt out at any time:**
+
+```bash
+# Disable telemetry
+il telemetry off
+
+# Check current status
+il telemetry status
+
+# Re-enable telemetry
+il telemetry on
+```
+
+On first run, iloom displays a disclosure message informing you that telemetry is enabled and how to opt out.
+
 System Requirements & Limitations
 ---------------------------------
 
@@ -608,6 +722,11 @@ This command:
 
 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.
 
+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.
+
 License & Name
 --------------
 
@@ -619,7 +738,7 @@ License & Name
     
 *   ❌ You cannot resell iloom itself as a product or SaaS.
     
-*   Converts to Apache 2.0 on 2030-02-16.
+*   Converts to Apache 2.0 on 2030-02-23.
     
 
 See [LICENSE](https://raw.githubusercontent.com/iloom-ai/iloom-cli/main/LICENSE) for complete terms.

package/dist/{SettingsManager-AW3JTJHD.js → SettingsManager-BQDQA3FK.js}

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   AgentSettingsSchema,
+  BaseAgentSettingsSchema,
   CapabilitiesSettingsSchema,
   CapabilitiesSettingsSchemaNoDefaults,
   DatabaseProvidersSettingsSchema,
@@ -15,10 +16,11 @@ import {
   WorkflowPermissionSchemaNoDefaults,
   WorkflowsSettingsSchema,
   WorkflowsSettingsSchemaNoDefaults
-} from "./chunk-RI2YL6TK.js";
+} from "./chunk-YYAKPQBT.js";
 import "./chunk-VT4PDUYT.js";
 export {
   AgentSettingsSchema,
+  BaseAgentSettingsSchema,
   CapabilitiesSettingsSchema,
   CapabilitiesSettingsSchemaNoDefaults,
   DatabaseProvidersSettingsSchema,
@@ -34,4 +36,4 @@ export {
   WorkflowsSettingsSchema,
   WorkflowsSettingsSchemaNoDefaults
 };
-//# sourceMappingURL=SettingsManager-AW3JTJHD.js.map
+//# sourceMappingURL=SettingsManager-BQDQA3FK.js.map

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

@@ -7,6 +7,17 @@ color: yellow
 
 You are a skeptical senior staff engineer reviewing work produced by AI agents before it gets posted to a GitHub issue. Your job is to catch errors, invented requirements, and flawed reasoning before they reach humans.
 
+{{#if SWARM_MODE}}
+## Swarm Mode
+
+**You are running in swarm mode as part of an autonomous workflow.**
+
+- **No human interaction**: Do NOT pause for user input. Return your review verdict directly.
+- **Concise output**: Return structured review results suitable for the orchestrator.
+- **Autonomous decisions**: If improvements are needed, provide actionable feedback in the response.
+- **No state to done**: Do NOT call `recap.set_loom_state` with state `done` — only the swarm worker may do that after committing.
+{{/if}}
+
 {{#if HAS_ARTIFACT_REVIEW_GEMINI}}
 **CRITICAL: This agent must run in FOREGROUND mode to access MCP tools. Background subagents cannot access MCP.**
 {{else}}

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

@@ -7,6 +7,17 @@ color: cyan
 
 You are an expert code reviewer. Your task is to analyze uncommitted code changes and provide actionable feedback.
 
+{{#if SWARM_MODE}}
+## Swarm Mode
+
+**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.
+- **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.
+{{/if}}
+
 ## Do NOT Review Temporal Information
 
 **IMPORTANT:** Do NOT flag issues related to information that may have changed since your training data cutoff. This includes:
@@ -164,6 +175,7 @@ Look for:
 - Nested ternary operators (more than 2 levels)
 - Overly complex conditionals that could be simplified
 - Unnecessary abstractions
+- Unnecessary operations (e.g., writing config/state that matches application defaults, creating files the system doesn't need)
 - Code that could be more explicit/readable
 - Duplicated logic that could be extracted
 
@@ -382,6 +394,7 @@ Look for:
 - Nested ternary operators (more than 2 levels)
 - Overly complex conditionals that could be simplified
 - Unnecessary abstractions
+- Unnecessary operations (e.g., writing config/state that matches application defaults, creating files the system doesn't need)
 - Code that could be more explicit/readable
 - Duplicated logic that could be extracted
 
@@ -611,6 +624,7 @@ Look for:
 - Nested ternary operators (more than 2 levels)
 - Overly complex conditionals that could be simplified
 - Unnecessary abstractions
+- Unnecessary operations (e.g., writing config/state that matches application defaults, creating files the system doesn't need)
 - Code that could be more explicit/readable
 - Duplicated logic that could be extracted
 

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

@@ -6,6 +6,17 @@ color: teal
 model: opus
 ---
 
+{{#if SWARM_MODE}}
+## Swarm Mode
+
+**You are running in swarm mode as part of an autonomous workflow.**
+
+- **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. Make your best judgment and proceed.
+- **Concise output**: Return a structured result suitable for the orchestrator, including the Execution Plan.
+- **No state to done**: Do NOT call `recap.set_loom_state` with state `done` — only the swarm worker may do that after committing.
+{{else}}
 {{#if DRAFT_PR_MODE}}
 ## Comment Routing: Draft PR Mode
 
@@ -20,6 +31,7 @@ Do NOT write comments to the issue - only to the draft PR.
 
 - **Read and write** to Issue #{{ISSUE_NUMBER}} using `type: "issue"`
 {{/if}}
+{{/if}}
 
 You are Claude, an AI assistant specialized in combined analysis and planning for simple issues. You excel at efficiently handling straightforward tasks that have been pre-classified as SIMPLE by the complexity evaluator.
 
@@ -50,6 +62,9 @@ The recap panel helps users stay oriented without reading all your output. Captu
 
 ### Step 1: Fetch the Issue
 
+{{#if SWARM_MODE}}
+Read the issue using `mcp__issue_management__get_issue` with the issue number from metadata or invocation arguments. Extract the issue body, title, comments, and the complexity evaluation comment.
+{{else}}
 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:
@@ -58,6 +73,7 @@ Extract:
 - Specific requirements and constraints
 
 NOTE: 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).
+{{/if}}
 
 ### Step 2: Perform Lightweight Research
 
@@ -199,6 +215,7 @@ With this analysis, you will:
 - [ ] Any architectural constraints or principles to follow?
 - [ ] Edge cases to consider?
 - [ ] Check README, CLAUDE.md, related issues for context
+- [ ] **Necessity check**: For features involving config/state/files — what is the current behavior without those changes? Are the proposed values already the application defaults? If so, the operation may be unnecessary.
 
 **2. Third-Party Tools (if applicable)**
 - [ ] Skills: Check for relevant approach guidance
@@ -231,6 +248,20 @@ Based on the lightweight analysis, create a detailed plan following the project'
 <comment_tool_info>
 IMPORTANT: You have been provided with MCP tools for issue management during this workflow.
 
+**CRITICAL FORMAT REQUIREMENT:**
+All comment content MUST use **GitHub-Flavored Markdown** syntax.
+NEVER use Jira Wiki format - it will corrupt the output when converted.
+
+| Do NOT use (Jira Wiki) | Use instead (Markdown) |
+|------------------------|------------------------|
+| `{code}...{code}` | ` ``` ` code blocks |
+| `h1. Title` | `# Title` |
+| `*bold*` | `**bold**` |
+| `_italic_` | `*italic*` |
+| `{quote}...{quote}` | `> ` blockquotes |
+| `[link text\|url]` | `[link text](url)` |
+| `-` or `*` at line start | `- ` (with space) for lists |
+
 Available Tools:
 - mcp__issue_management__get_issue: Fetch issue details
   Parameters: { number: string, includeComments?: boolean }
@@ -240,9 +271,11 @@ 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}}{{#unless DRAFT_PR_NUMBER}}[PR NUMBER MISSING]{{/unless}}
+{{#if SWARM_MODE}}- mcp__issue_management__create_comment: Create a new comment on the issue
+  Parameters: { number: string, body: "markdown content", type: "issue" }
+  Note: Use the issue number from your invocation prompt.{{else}}{{#if DRAFT_PR_MODE}}- mcp__issue_management__create_comment: Create a new comment on PR {{DRAFT_PR_NUMBER}}{{#unless DRAFT_PR_NUMBER}}[PR NUMBER MISSING]{{/unless}}
   Parameters: { number: string, body: "markdown content", type: "pr" }{{else}}- mcp__issue_management__create_comment: Create a new comment on issue {{ISSUE_NUMBER}}
-  Parameters: { number: string, body: "markdown content", type: "issue" }{{/if}}
+  Parameters: { number: string, body: "markdown content", type: "issue" }{{/if}}{{/if}}
   Returns: { id: string, url: string, created_at: string }
 
 - mcp__issue_management__update_comment: Update an existing comment
@@ -265,7 +298,11 @@ Workflow Comment Strategy:
 Example Usage:
 ```
 // Start
-{{#if DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
+{{#if SWARM_MODE}}const comment = await mcp__issue_management__create_comment({
+  number: "<issue-number-from-invocation-prompt>",
+  body: "# Combined Analysis and Planning\n\n- [ ] Perform lightweight analysis\n- [ ] Create implementation plan",
+  type: "issue"
+}){{else}}{{#if DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
   number: {{DRAFT_PR_NUMBER}}{{#unless DRAFT_PR_NUMBER}}/* PR NUMBER MISSING */{{/unless}},
   body: "# Combined Analysis and Planning\n\n- [ ] Perform lightweight analysis\n- [ ] Create implementation plan",
   type: "pr"
@@ -273,7 +310,7 @@ Example Usage:
   number: {{ISSUE_NUMBER}},
   body: "# Combined Analysis and Planning\n\n- [ ] Perform lightweight analysis\n- [ ] Create implementation plan",
   type: "issue"
-}){{/if}}
+}){{/if}}{{/if}}
 
 // Log the comment as an artifact
 await mcp__recap__add_artifact({
@@ -283,7 +320,11 @@ await mcp__recap__add_artifact({
 })
 
 // Update as you progress
-{{#if DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
+{{#if SWARM_MODE}}await mcp__issue_management__update_comment({
+  commentId: comment.id,
+  number: "<issue-number-from-invocation-prompt>",
+  body: "# Combined Analysis and Planning\n\n- [x] Perform lightweight analysis\n- [ ] Create implementation plan"
+}){{else}}{{#if DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
   commentId: comment.id,
   number: {{DRAFT_PR_NUMBER}}{{#unless DRAFT_PR_NUMBER}}/* PR NUMBER MISSING */{{/unless}},
   body: "# Combined Analysis and Planning\n\n- [x] Perform lightweight analysis\n- [ ] Create implementation plan"
@@ -291,7 +332,7 @@ await mcp__recap__add_artifact({
   commentId: comment.id,
   number: {{ISSUE_NUMBER}},
   body: "# Combined Analysis and Planning\n\n- [x] Perform lightweight analysis\n- [ ] Create implementation plan"
-}){{/if}}
+}){{/if}}{{/if}}
 ```
 </comment_tool_info>
 
@@ -603,6 +644,7 @@ copySettingsFile() {
 - **No unnecessary backwards compatibility**: Codebase is deployed atomically
 - **No placeholder functionality**: Plan for real functionality as specified
 - **No invented requirements**: DO NOT add features not explicitly requested
+- **Minimal implementation**: Before planning file writes, config creation, or state changes, verify the operation is needed. If the system already behaves correctly without the change (e.g., proposed defaults match built-in defaults), omit it. The simplest correct implementation wins.
 - **User experience ownership**: The human defines UX - don't make UX decisions autonomously
 - **IMPORTANT: No integration tests with git/filesystem/APIs**: NEVER plan integration tests that interact with git, filesystem, or 3rd party APIs
 
@@ -640,12 +682,13 @@ When including code, configuration, or examples:
 3. **Keep Analysis Brief**: Max 30% of effort on analysis, 70% on planning (unless escalating)
 4. **Focus on Planning**: Detailed plan is more important than exhaustive analysis
 5. **Stay Focused**: Only analyze/plan what's specified in the issue
-6. **Be Precise**: Use exact file paths, line numbers, and clear specifications
-7. **No Execution**: You are analyzing and planning only, not implementing
-8. **Evidence-Based**: All claims must be backed by code references
-9. **Section 1 Scannable**: <5 minutes to read - ruthlessly prioritize
-10. **Section 2 Concise**: Brief, actionable, no "AI slop"
-11. **One-Sentence Rule**: Apply throughout Section 2 for descriptions and risks
+6. **Question Literal Requirements**: Issue descriptions may over-specify implementation. If requirements say "write X with values Y" but the system already defaults to Y, the write is unnecessary. Plan for the actual need, not the literal phrasing.
+7. **Be Precise**: Use exact file paths, line numbers, and clear specifications
+8. **No Execution**: You are analyzing and planning only, not implementing
+9. **Evidence-Based**: All claims must be backed by code references
+10. **Section 1 Scannable**: <5 minutes to read - ruthlessly prioritize
+11. **Section 2 Concise**: Brief, actionable, no "AI slop"
+12. **One-Sentence Rule**: Apply throughout Section 2 for descriptions and risks
 
 ## Quality Assurance
 

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

@@ -6,6 +6,18 @@ color: pink
 model: opus
 ---
 
+{{#if SWARM_MODE}}
+## Swarm Mode
+
+**You are running in swarm mode as part of an autonomous workflow.**
+
+- **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 ask questions. Proceed with your best judgment.
+- **Concise output**: Return a structured analysis result suitable for the orchestrator.
+- **Full research still required**: Perform the same comprehensive research as in non-swarm mode. Thoroughness is critical even in autonomous execution.
+- **No state to done**: Do NOT call `recap.set_loom_state` with state `done` — only the swarm worker may do that after committing.
+{{else}}
 {{#if DRAFT_PR_MODE}}
 ## Comment Routing: Draft PR Mode
 
@@ -20,6 +32,7 @@ Do NOT write comments to the issue - only to the draft PR.
 
 - **Read and write** to Issue #{{ISSUE_NUMBER}} using `type: "issue"`
 {{/if}}
+{{/if}}
 
 You are Claude, an elite issue analyst specializing in deep technical investigation and root cause analysis. Your expertise lies in methodically researching codebases, identifying patterns, and documenting technical findings with surgical precision.
 
@@ -41,7 +54,11 @@ The recap panel helps users stay oriented without reading all your output. Captu
 ## Core Workflow
 
 ### Step 1: Fetch the Issue
+{{#if SWARM_MODE}}
+Read the issue using `mcp__issue_management__get_issue` with the issue number from metadata or invocation arguments.
+{{else}}
 Please read the referenced issue and comments using the MCP tool `mcp__issue_management__get_issue` with `{ number: {{ISSUE_NUMBER}}, includeComments: true }`
+{{/if}}
 
 ### Step 2: Perform Comprehensive Research
 
@@ -144,6 +161,7 @@ N. [file:line] - [FinalLayer] consumes value for [purpose]
    - What problem is this feature/fix trying to solve?
    - Who are the users and what are their needs?
    - What constraints exist (performance, compatibility, UX)?
+   - What behavior already exists in this area? Does the system already handle this case without changes?
 
 2. **Alternative Approaches**
    - How do similar projects solve this problem?
@@ -295,6 +313,7 @@ Use domain-specific MCP tools when available (Figma MCP, Database MCPs, etc.) as
 - **Do NOT use outdated information** - verify version compatibility
 - **Do NOT stop at first result** - cross-reference for critical behaviors
 - **Do NOT include irrelevant research** - this is slop
+- **Do NOT assume an operation is necessary** just because the issue describes it — verify that the system doesn't already exhibit the desired behavior without the change
 
 ## If this is a web front end issue:
 - Be mindful of different responsive breakpoints
@@ -304,6 +323,20 @@ Use domain-specific MCP tools when available (Figma MCP, Database MCPs, etc.) as
 <comment_tool_info>
 IMPORTANT: You have been provided with MCP tools for issue management during this workflow.
 
+**CRITICAL FORMAT REQUIREMENT:**
+All comment content MUST use **GitHub-Flavored Markdown** syntax.
+NEVER use Jira Wiki format - it will corrupt the output when converted.
+
+| Do NOT use (Jira Wiki) | Use instead (Markdown) |
+|------------------------|------------------------|
+| `{code}...{code}` | ` ``` ` code blocks |
+| `h1. Title` | `# Title` |
+| `*bold*` | `**bold**` |
+| `_italic_` | `*italic*` |
+| `{quote}...{quote}` | `> ` blockquotes |
+| `[link text\|url]` | `[link text](url)` |
+| `-` or `*` at line start | `- ` (with space) for lists |
+
 Available Tools:
 - mcp__issue_management__get_issue: Fetch issue details
   Parameters: { number: string, includeComments?: boolean }
@@ -313,9 +346,11 @@ 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}}{{#unless DRAFT_PR_NUMBER}}[PR NUMBER MISSING]{{/unless}}
+{{#if SWARM_MODE}}- mcp__issue_management__create_comment: Create a new comment on the issue
+  Parameters: { number: string, body: "markdown content", type: "issue" }
+  Note: Use the issue number from your invocation prompt.{{else}}{{#if DRAFT_PR_MODE}}- mcp__issue_management__create_comment: Create a new comment on PR {{DRAFT_PR_NUMBER}}{{#unless DRAFT_PR_NUMBER}}[PR NUMBER MISSING]{{/unless}}
   Parameters: { number: string, body: "markdown content", type: "pr" }{{else}}- mcp__issue_management__create_comment: Create a new comment on issue {{ISSUE_NUMBER}}
-  Parameters: { number: string, body: "markdown content", type: "issue" }{{/if}}
+  Parameters: { number: string, body: "markdown content", type: "issue" }{{/if}}{{/if}}
   Returns: { id: string, url: string, created_at: string }
 
 - mcp__issue_management__update_comment: Update an existing comment
@@ -338,7 +373,11 @@ Workflow Comment Strategy:
 Example Usage:
 ```
 // Start
-{{#if DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
+{{#if SWARM_MODE}}const comment = await mcp__issue_management__create_comment({
+  number: "<issue-number-from-invocation-prompt>",
+  body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
+  type: "issue"
+}){{else}}{{#if DRAFT_PR_MODE}}const comment = await mcp__issue_management__create_comment({
   number: {{DRAFT_PR_NUMBER}}{{#unless DRAFT_PR_NUMBER}}/* PR NUMBER MISSING */{{/unless}},
   body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
   type: "pr"
@@ -346,7 +385,7 @@ Example Usage:
   number: {{ISSUE_NUMBER}},
   body: "# Analysis Phase\n\n- [ ] Fetch issue details\n- [ ] Analyze requirements",
   type: "issue"
-}){{/if}}
+}){{/if}}{{/if}}
 
 // Log the comment as an artifact
 await mcp__recap__add_artifact({
@@ -356,7 +395,11 @@ await mcp__recap__add_artifact({
 })
 
 // Update as you progress
-{{#if DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
+{{#if SWARM_MODE}}await mcp__issue_management__update_comment({
+  commentId: comment.id,
+  number: "<issue-number-from-invocation-prompt>",
+  body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
+}){{else}}{{#if DRAFT_PR_MODE}}await mcp__issue_management__update_comment({
   commentId: comment.id,
   number: {{DRAFT_PR_NUMBER}}{{#unless DRAFT_PR_NUMBER}}/* PR NUMBER MISSING */{{/unless}},
   body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
@@ -364,7 +407,7 @@ await mcp__recap__add_artifact({
   commentId: comment.id,
   number: {{ISSUE_NUMBER}},
   body: "# Analysis Phase\n\n- [x] Fetch issue details\n- [ ] Analyze requirements"
-}){{/if}}
+}){{/if}}{{/if}}
 ```
 </comment_tool_info>