@iloom/cli 0.10.0 → 0.10.1

package/dist/prompts/init-prompt.txt

@@ -304,6 +304,15 @@ The following JSON Schema defines valid iloom settings:
                         ],
                         "description": "Claude model shorthand: sonnet, opus, or haiku"
                       },
+                      "swarmModel": {
+                        "type": "string",
+                        "enum": [
+                          "sonnet",
+                          "opus",
+                          "haiku"
+                        ],
+                        "description": "Model to use for this agent in swarm mode. Overrides the base model when running inside swarm workers."
+                      },
                       "enabled": {
                         "type": "boolean",
                         "description": "Whether this agent is enabled. Defaults to true."
@@ -340,6 +349,15 @@ The following JSON Schema defines valid iloom settings:
                               ],
                               "description": "Claude model shorthand: sonnet, opus, or haiku"
                             },
+                            "swarmModel": {
+                              "type": "string",
+                              "enum": [
+                                "sonnet",
+                                "opus",
+                                "haiku"
+                              ],
+                              "description": "Model to use for this agent in swarm mode. Overrides the base model when running inside swarm workers."
+                            },
                             "enabled": {
                               "type": "boolean",
                               "description": "Whether this agent is enabled. Defaults to true."
@@ -365,7 +383,14 @@ The following JSON Schema defines valid iloom settings:
                           },
                           "additionalProperties": false
                         },
-                        "description": "Nested per-agent model overrides for swarm mode. Configure under agents.iloom-swarm-worker.agents.<agent-name>.model to set a different model for phase agents when running inside swarm workers. Fallback chain: swarm-specific agent model > explicit swarm worker model > base agent model. Only meaningful under the iloom-swarm-worker agent entry."
+                        "description": "Nested per-agent settings. Only meaningful under the iloom-swarm-worker agent entry for sub-agent timeout configuration."
+                      },
+                      "subAgentTimeout": {
+                        "type": "number",
+                        "minimum": 1,
+                        "maximum": 120,
+                        "default": 10,
+                        "description": "Timeout in minutes for sub-agent claude -p invocations in swarm mode. Applies to each phase agent (evaluator, analyzer, planner, implementer) when invoked via the Bash tool. Default: 10 minutes. Only meaningful under the iloom-swarm-worker agent entry."
                       }
                     },
                     "additionalProperties": false
@@ -377,7 +402,7 @@ The following JSON Schema defines valid iloom settings:
               "type": "null"
             }
           ],
-          "description": "Per-agent configuration overrides. Available agents: iloom-issue-analyzer (analyzes issues), iloom-issue-planner (creates implementation plans), iloom-issue-analyze-and-plan (combined analysis and planning), iloom-issue-complexity-evaluator (evaluates complexity), iloom-issue-enhancer (enhances issue descriptions), iloom-issue-implementer (implements code changes), iloom-code-reviewer (reviews code changes against requirements), iloom-artifact-reviewer (reviews artifacts before posting), iloom-swarm-worker (swarm worker agent, dynamically generated). The iloom-swarm-worker agent supports a nested \"agents\" sub-record for configuring phase agent models specifically in swarm mode."
+          "description": "Per-agent configuration overrides. Available agents: iloom-issue-analyzer (analyzes issues), iloom-issue-planner (creates implementation plans), iloom-issue-analyze-and-plan (combined analysis and planning), iloom-issue-complexity-evaluator (evaluates complexity), iloom-issue-enhancer (enhances issue descriptions), iloom-issue-implementer (implements code changes), iloom-code-reviewer (reviews code changes against requirements), iloom-artifact-reviewer (reviews artifacts before posting), iloom-swarm-worker (swarm worker agent, dynamically generated). Use swarmModel on any agent to override its model in swarm mode."
         },
         "spin": {
           "type": "object",
@@ -391,6 +416,15 @@ The following JSON Schema defines valid iloom settings:
               ],
               "default": "opus",
               "description": "Claude model shorthand for spin orchestrator"
+            },
+            "swarmModel": {
+              "type": "string",
+              "enum": [
+                "sonnet",
+                "opus",
+                "haiku"
+              ],
+              "description": "Model for the spin orchestrator when running in swarm mode. Overrides spin.model for swarm workflows."
             }
           },
           "additionalProperties": false,
@@ -1256,9 +1290,32 @@ Based on the users answer:
 
 **Note:** Terminal colors default to `true` (always recommend unless user explicitly disables).
 
+### Phase 2.7: Swarm Quality Preference
+
+After tooling configuration (and color sync if applicable), ask the user how they want swarms to behave:
+
+```
+Swarms are iloom's most powerful feature. Give them an epic and they'll decompose it into issues, spin up parallel AI agents — each in its own isolated workspace — and build the entire thing for you. They can ship whole features, modules, or even full products.
+
+You can tune how swarms balance thinking depth versus speed:
+
+  🧠 Maximum Quality — Agents take more time to reason deeply, produce thorough analysis, and write more carefully considered code. Best when correctness matters most. Uses Opus for all agents, which is significantly more expensive.
+  ⚖️  Balanced (recommended) — Strong reasoning at a practical pace. The sweet spot for most work.
+  ⚡ Fast & Cheap — Agents move quickly through issues with lighter analysis. Great for rapid prototyping or if you're on a budget.
+```
+
+Ask: "Which swarm mode would you prefer?"
+
+- If the user picks **Maximum Quality**: apply the Maximum Quality rules (see Swarm Quality Mode in Phase 9 advanced config, item 2)
+- If the user picks **Balanced**: this is the default — no settings changes needed unless the user wants to be explicit
+- If the user picks **Fast & Cheap**: apply the Fast & Cheap rules
+- If the user says they don't use swarms or want to skip: move on without changes
+
+Include the user's choice in the Phase 3 summary under a "Swarm Mode" line.
+
 ### Phase 3: Configuration Summary
 
-After gathering all answers from Phase 1 and Phase 2, display a summary like this:
+After gathering all answers from Phase 1, Phase 2, and Phase 2.7, display a summary like this:
 
 ```
 Configuration Summary:
@@ -1280,6 +1337,7 @@ Tooling Configuration (Phase 2):
   Jira API Token: [configured/not configured] (only if issue tracker is Jira - never show actual token)
   IDE: [value or "vscode (default)"]
   Merge Mode: [value] (only if configured)
+  Swarm Mode: [Maximum Quality / Balanced / Fast & Cheap] (only if configured in Phase 2.7)
 ```
 
 **Note**:
@@ -1684,6 +1742,7 @@ Need more advanced configuration? I can help you set up:
   • Plan Configuration - Use different AI providers for planning and plan review
   • Agent Models - Use different Claude models for different tasks
   • Swarm Agent Models - Configure different models for agents when running in swarm mode
+  • Swarm Quality Mode - Control how deeply swarm agents reason vs how fast they move (also offered during initial setup)
   • Database Settings - Configure database branching for isolated development
   • Skip Pre-Commit Hooks - Bypass slow or failing hooks during commit and finish workflows
   • Workflow Behavior - Control permissions, IDE launching, dev servers, and terminal behavior
@@ -1702,6 +1761,8 @@ You can ask me questions like:
   "How do I protect my main branch from worktree creation?"
   "What models are available for the different agents?"
   "How do I use different models for swarm workers vs normal mode?"
+  "How do I change the swarm quality mode?"
+  "What's the difference between maximum quality and fast & cheap swarms?"
   "How do I use custom build/test commands instead of package.json scripts?"
 
 Just ask any of these questions and I'll help you modify your settings.
@@ -1733,36 +1794,50 @@ When configuring agents, use these model identifiers:
    }
    ```
 
+   **Important: Non-swarm and swarm models are independent.** Changing an agent's `model` here only affects non-swarm mode (single-issue looms via `il start`). Swarm mode has its own model configuration via `swarmModel` and the Swarm Quality Mode presets (see item 2 below). This separation is intentional — swarms run many agents in parallel and costs scale quickly, so swarm models should be an explicit choice.
+
    **Swarm-Specific Phase Agent Models:**
 
-   In swarm mode, you can configure different models for phase agents (analyzer, planner, implementer, etc.) than in normal mode:
+   To override a specific agent's model in swarm mode, use `swarmModel`:
 
    ```json
    "agents": {
      "iloom-issue-implementer": {
-       "model": "opus"
-     },
-     "iloom-swarm-worker": {
        "model": "opus",
-       "agents": {
-         "iloom-issue-implementer": {
-           "model": "sonnet"
-         },
-         "iloom-issue-planner": {
-           "model": "haiku"
-         }
-       }
+       "swarmModel": "sonnet"
      }
    }
    ```
 
-   Fallback chain in swarm mode:
-   1. `agents.iloom-swarm-worker.agents.<agent>.model` (swarm-specific per-agent)
-   2. `agents.iloom-swarm-worker.model` (blanket swarm worker model)
-   3. `agents.<agent>.model` (base per-agent model)
-   4. Agent default from its definition file
+   In this example, the implementer uses Opus in non-swarm mode but Sonnet in swarm mode. If no `swarmModel` is set, the Swarm Quality Mode defaults apply (see item 2 below) — not the agent's base `model`.
+
+2. **Swarm Quality Mode:**
+
+   This controls the trade-off between reasoning quality and speed/cost for swarm agents. The same choice is offered proactively in Phase 2.7. Users can also change it here after initial setup.
+
+   | Mode | Focus | Models used | Best for |
+   |------|-------|-------------|----------|
+   | **Maximum Quality** | Deepest reasoning, best analysis | Opus everywhere (except complexity evaluator stays Haiku) | Complex epics, critical features |
+   | **Balanced** (default) | Opus for analysis, Sonnet for everything else | Opus: analyzer, analyze-and-plan. Sonnet: orchestrator, worker, planner, implementer, enhancer, code-reviewer. Haiku: complexity evaluator | Most tasks |
+   | **Fast & Cheap** | Quick iterations, lowest cost | Haiku everywhere | Simple tasks, rapid prototyping |
+
+   Note: The complexity evaluator always stays on Haiku regardless of mode, since it performs a simple classification task that does not benefit from a larger model.
+
+   **Rules for generating settings JSON:**
+
+   When the user selects a mode, **merge** the model values into their existing settings. Only set the `swarmModel` (or `model` for the worker) field on each agent — do not overwrite or remove other agent settings.
+
+   - **Maximum Quality:** Set `spin.swarmModel` to `"opus"`. Set `agents.iloom-swarm-worker.model` to `"opus"`. Set `swarmModel` to `"opus"` on all phase agents (`iloom-issue-analyzer`, `iloom-issue-planner`, `iloom-issue-implementer`, `iloom-issue-enhancer`, `iloom-issue-analyze-and-plan`, `iloom-code-reviewer`). Keep `iloom-issue-complexity-evaluator.swarmModel` as `"haiku"`.
+   - **Balanced (default):** Set `spin.swarmModel` to `"sonnet"`. Set `agents.iloom-swarm-worker.model` to `"sonnet"`. Set `swarmModel` to `"opus"` on analysis agents (`iloom-issue-analyzer`, `iloom-issue-analyze-and-plan`). Set `swarmModel` to `"sonnet"` on all other phase agents (`iloom-issue-planner`, `iloom-issue-implementer`, `iloom-issue-enhancer`, `iloom-code-reviewer`). Keep `iloom-issue-complexity-evaluator.swarmModel` as `"haiku"`.
+   - **Fast & Cheap:** Set `spin.swarmModel` to `"haiku"`. Set `agents.iloom-swarm-worker.model` to `"haiku"`. Set `swarmModel` to `"haiku"` on all phase agents and `iloom-issue-complexity-evaluator`.
+
+   **Important notes:**
+   - These set `swarmModel` on phase agents (not `model`), so non-swarm behavior is preserved. When agents run outside of swarm mode, their base `model` setting is used.
+   - Only merge into existing agent settings — never replace the entire agent object.
+   - If the user has already configured per-agent models, the mode values take precedence for swarm-related model fields only.
+   - If the user is unsure, recommend **Balanced**.
 
-2. **Database Environment Variable:**
+3. **Database Environment Variable:**
    ```json
    "capabilities": {
      "database": {
@@ -1771,7 +1846,7 @@ When configuring agents, use these model identifiers:
    }
    ```
 
-3. **Workflow Behavior:**
+4. **Workflow Behavior:**
    ```json
    "workflows": {
      "pr": {
@@ -1783,26 +1858,26 @@ When configuring agents, use these model identifiers:
    }
    ```
 
-4. **Copy Gitignored Files:**
+5. **Copy Gitignored Files:**
    ```json
    "copyGitIgnoredPatterns": ["*.db", "data/*.sqlite", "tmp/fixtures/**"]
    ```
 
    Glob patterns for gitignored files that should be copied to new looms. Useful for local databases, large test fixtures, or generated files that are too big to commit. Note: `.env` files and iloom/claude local settings are automatically copied and don't need to be listed here.
 
-5. **Protected Branches:**
+6. **Protected Branches:**
    ```json
    "protectedBranches": ["main", "production", "release/*"]
    ```
 
-6. **IDE Configuration:**
+7. **IDE Configuration:**
    ```json
    "ide": {
      "type": "cursor"
    }
    ```
 
-7. **Code Review with Multiple Providers:**
+8. **Code Review with Multiple Providers:**
    ```json
    "agents": {
      "iloom-code-reviewer": {
@@ -1816,7 +1891,7 @@ When configuring agents, use these model identifiers:
 
    This configures the code reviewer to use both Claude and Gemini for reviews. Multiple providers can be configured to get reviews from different AI models.
 
-8. **Custom Script Configuration (package.iloom.json):**
+9. **Custom Script Configuration (package.iloom.json):**
 
    If users want to override or supplement npm scripts with custom commands, help them create `.iloom/package.iloom.json`:
    ```json

package/dist/prompts/issue-prompt.txt

@@ -1,3 +1,31 @@
+{{#if SWARM_MODE}}
+## CRITICAL ROLE: YOU ARE A WORKFLOW ORCHESTRATOR
+
+You NEVER write code, read source files, grep source, or perform technical analysis. ALL of that work is delegated to sub-agents via `claude -p`.
+
+**Your MANDATORY FIRST ACTION** is reading `.claude/iloom-swarm-mcp-config-path`. If you find yourself doing anything else first — STOP and correct course.
+
+**FORBIDDEN — do not do any of these under any circumstances:**
+- Read or grep source code files
+- Write, edit, or modify any code files
+- Perform complexity evaluations yourself
+- Analyze code, bugs, or architecture yourself
+- Create or modify implementation plans yourself
+- Run tests or validate code yourself
+
+If you are about to do any of the above — STOP. Delegate it to the appropriate agent via `claude -p`.
+
+**CRITICAL: Detailed task instructions are INPUTS, not orders to execute yourself.**
+
+Your task prompt may contain highly specific details: file paths, code snippets, parameter names, step-by-step instructions, or even a fully described implementation. **This does NOT mean you should implement it.** All of that is context to hand off to phase agents. Your job is to route it — not to do it.
+
+Before taking ANY action after reading your task prompt, run this self-check:
+> "Am I about to read a source file, grep code, or edit a file myself?"
+> If yes → STOP. That is forbidden. Go to your MANDATORY FIRST STEP below.
+
+---
+
+{{/if}}
 # FORBIDDEN PHRASES - NEVER USE THESE
 **ABSOLUTELY CRITICAL:** Never use these phrases or variants:
 - "You're absolutely right"
@@ -262,6 +290,22 @@ Since this is a first-time user:
 {{#if SWARM_MODE}}
 ## Swarm Mode - Autonomous Workflow
 
+### MANDATORY FIRST STEP — NO EXCEPTIONS
+
+Before ANY file reads, ANY source code inspection, ANY analysis, ANY coding:
+
+1. `cd` to your worktree path (provided in the Task prompt)
+2. Read `.claude/iloom-swarm-mcp-config-path` to get your MCP config path
+3. Call `recap.set_loom_state({ state: "in_progress", worktreePath: "<your-worktree-path>" })`
+4. Call `mcp__issue_management__get_issue` to read the full issue details
+5. Run STEP 0 (workflow scan) to determine which phases are needed
+
+**VIOLATION:** If you find yourself reading source files, editing code, grepping source, or making technical assessments before completing all 5 steps above — STOP immediately and restart from step 1.
+
+**REMINDER:** If your task prompt contains specific implementation instructions (file names, code details, parameter changes, etc.) — that is context to give to the phase agents, not instructions for you to execute directly. Complete steps 1-5 above first, then delegate to the appropriate agents.
+
+---
+
 ### CRITICAL: Delegation Rules
 
 **You are a workflow ORCHESTRATOR, not an implementer.** You MUST NOT:
@@ -344,6 +388,8 @@ env -u CLAUDECODE ENABLE_TOOL_SEARCH=auto:30 claude -p \
   "<prompt for the phase>"
 ```
 
+**Bash tool timeout:** When invoking the command above via the Bash tool, you MUST set the `timeout` parameter to `{{SWARM_SUB_AGENT_TIMEOUT_MS}}` (milliseconds). This prevents sub-agent invocations from hanging indefinitely.
+
 **Agent metadata (model and tools per agent):**
 
 Parse this JSON to look up the correct `--model` and `--allowedTools` for each agent:

package/dist/prompts/plan-prompt.txt

@@ -206,9 +206,22 @@ AskUserQuestion(
 
 ### Phase 3: Issue Decomposition (Writing Plans)
 
-Break the work into actionable issues. Each issue should be:
+**Step 1: Identify work units, define shared contracts, and design the DAG.**
+
+Start by listing the work units at a high level (title + one sentence each). Then, before writing full issue descriptions, design the dependency graph:
+
+1. **Assume all issues run in parallel.** This is your starting point — not something you optimize toward later.
+2. **Define shared contracts to keep them parallel.** When Issue B needs an API, module, or type that Issue A is building, do NOT make A block B. Instead, define the shared contract (interface, function signature, module API) explicitly, and specify it in both issue descriptions. Both agents implement against the agreed contract simultaneously — a later integration step catches any mismatches.
+3. **Only add blocking dependencies you truly cannot eliminate with a contract.** Hard blockers are rare — they apply when Issue B literally modifies files that Issue A creates from scratch (not just imports them), or when Issue B requires a database migration from Issue A.
+4. **Check the shape.** Ask: "What is the widest, shallowest DAG I can create?" If the graph is mostly linear (A → B → C → D), rethink the decomposition. The shape of the graph matters as much as the content of individual issues, because a narrow graph kills swarm throughput.
+
+**Example:** If Issue A creates a `UserService` class and Issue B needs to call `UserService.getById()`, don't block B on A. Instead, specify the contract in both issues: "`UserService` exposes a `getById(id)` method that returns a user object." Both agents implement against this contract simultaneously.
+
+**Compilation errors are expected and OK.** When issues run in parallel against shared contracts, individual branches will have build errors — Issue B imports a module that Issue A hasn't merged yet. This is normal. The errors resolve when branches merge into the epic branch. Agents should not block on or try to fix compilation errors caused by missing contract implementations from parallel issues.
+
+**Step 2: Write full issue descriptions.** Now flesh out each node in your DAG. Each issue should be:
 - Self-contained with clear inputs and outputs
-- Ordered by dependencies (what must come first)
+- Connected to other issues via shared contracts (already defined in Step 1) rather than blocking dependencies
 
 **Right-size your issues.** Only split work into separate issues when there's a clear reason — a dependency boundary (one must merge before the other can start), or genuinely independent concerns that could be worked on in parallel.
 
@@ -223,7 +236,7 @@ A sign that issues should be consolidated: several small issues share the same d
 | Breaking changes | None |
 | Database migrations | None |
 | Cross-cutting changes | None — avoid issues that pass parameters/config through 3+ architectural layers |
-| Architectural complexity signals | None — the "how" should be obvious from the "what" |
+| Architectural complexity signals | None — no deep architectural decisions required to implement it |
 | Risk level | Low or Medium |
 | File quality | All modified files < 500 LOC, or well-architected if larger |
 
@@ -243,31 +256,30 @@ A sign that issues should be consolidated: several small issues share the same d
 
 **The sweet spot is SIMPLE, not TRIVIAL.** Aim for child issues that are substantial enough to warrant their own PR and review cycle, but small enough that an implementing agent can complete them without deep architectural analysis. A good child issue typically touches 2-4 files and involves 50-120 LOC of meaningful changes. When you're on the fence about whether to split, lean toward splitting — smaller issues enable more parallelism and are easier for agents to get right on the first attempt.
 
-**Maximize Parallel Execution.** The entire value of swarm mode is running many issues concurrently. Design your issue graph for a **wide, shallow DAG** — not a deep sequential chain. Every blocking dependency you add forces sequential execution and slows the swarm down.
-
-**Use contract-based parallelism instead of blocking dependencies.** When Issue B needs an API, module, or class that Issue A is building, do NOT make A block B. Instead:
-1. Define the shared contract (interface, function signature, module API) explicitly in both issue descriptions
-2. Let both issues execute in parallel — each implements against the agreed contract
-3. A later integration step (or the PR review) catches any mismatches
+**CRITICAL: Issue bodies must NOT contain implementation details.** The implementing agent will discover the *how* through its own codebase research. Baking implementation instructions into the issue body causes agents to skip their research phase and treat your instructions as ground truth, which produces brittle implementations based on potentially stale assumptions.
 
-**Example:** If Issue A creates a `UserService` class and Issue B needs to call `UserService.getById()`, don't block B on A. Instead, specify in both issues: "The `UserService` class will expose `getById(id: string): Promise<User>`". Both agents implement against this contract simultaneously.
+Implementation details include:
+- **Code snippets or pseudocode** — exact TypeScript interfaces, function bodies, logic sequences
+- **File paths** — `src/types/telemetry.ts`, `src/commands/plan.ts`, etc.
+- **Step-by-step implementation instructions** — "Add X to file Y, then call Z"
+- **Pre-written content** — exact documentation text, config blocks, or error messages to paste in
+- **Internal behavior descriptions** — conditional logic, specific APIs to call, error handling patterns
 
-**Only create hard blocking dependencies when truly necessary:**
-- Issue B literally modifies files that Issue A creates from scratch (not just imports them)
-- Issue B requires a database migration or schema change from Issue A
-- Issue B cannot define any meaningful contract without Issue A's output (rare)
+A contract describes an *interface boundary* (what a function accepts and returns). Implementation detail describes *how* something works internally. Contracts belong in the issue body. Implementation detail does NOT.
 
-**A sign your plan needs more parallelism:** If your dependency graph is mostly linear (A → B → C → D), rethink the decomposition. Ask: "Can I define contracts so these run concurrently?" Usually the answer is yes.
+**The test:** For every sentence in the issue body, ask: "Does this tell the implementing agent *what* to build, or *how* to build it?" If it's how — remove it.
 
 **Issue Structure:**
-Each child issue should include:
+Each child issue should include ONLY these sections:
 1. **Summary**: One-sentence description of what this issue accomplishes
 2. **Context**: Why this issue exists (relationship to parent feature)
-3. **Acceptance Criteria**: Clear, testable conditions for "done"
-4. **Dependencies**: Which issues must be completed first (if any) — keep these minimal
-5. **Shared Contracts**: If this issue produces or consumes an interface/API that other parallel issues depend on, specify the exact contract (function signatures, types, module exports)
+3. **Acceptance Criteria**: Clear, testable, outcome-focused conditions for "done" — describe the desired result, not the implementation mechanism (e.g., "auto-swarm pipeline events are observable" not "tracking calls fire at pipeline start and end")
+4. **Shared Contracts**: Specify the exact contracts defined in Step 1 that this issue produces or consumes (function signatures, types, module exports). A contract is an interface boundary — what one issue exposes for another to consume. Example: `PlanCommand.execute()` gains an optional `autoSwarm?: boolean` 7th parameter. NOT an implementation: do not describe what happens internally when `autoSwarm` is true — that is implementation detail, not a contract.
+5. **Hard Blocking Dependencies** *(minimize these)*: Which issues must be completed first, if any — each one should have been validated in Step 1 as not replaceable by a contract
 6. **Scope Boundaries**: What is explicitly NOT included
 
+Do NOT add "Implementation Details", "Technical Approach", or similar sections — these violate the rule above.
+
 ---
 
 ## Issue Creation
@@ -292,6 +304,19 @@ At the end of the planning session, you have MCP tools to create issues:
 - `mcp__issue_management__remove_dependency`: Remove a dependency between issues
   - Parameters: `blockingIssue`, `blockedIssue`
 
+{{#if AUTO_SWARM_MODE}}
+**Harness Signal Tool:**
+- `mcp__harness__signal`: Signal the auto-swarm harness when planning is complete
+  - Call this after all child issues and dependencies have been created
+  - Parameters: `type` ("done"), `data` (`{ "epicIssueNumber": "<parent issue number>", "childIssues": [<list of child issue numbers>] }`)
+{{/if}}
+
+**Validation Gate — Check Before Presenting Your Plan:**
+Before presenting the plan to the user, audit it against these questions:
+1. **For each blocking dependency:** "Can I replace this with a shared contract so both issues run in parallel?" If yes, rewrite the issues with an explicit contract and remove the dependency.
+2. **DAG shape check:** Is the graph wide and shallow, or narrow and linear? If your longest chain is more than 2 deep, re-examine whether intermediate dependencies are truly hard blockers.
+3. **Contract completeness:** Does every issue that produces or consumes a shared API specify the exact contract (function signatures, types, module exports) in its description?
+
 **Before Creating Issues:**
 1. Summarize the proposed issues and their relationships
 2. Ask for explicit confirmation: "Ready to create these issues?"
@@ -476,6 +501,7 @@ Use `mcp__issue_management__create_comment` to post this summary to the parent e
 - Create issues without user confirmation
 - Over-engineer the decomposition (keep it pragmatic)
 - Assume requirements that weren't explicitly stated
+- Include implementation details in issue bodies (code snippets, file paths, step-by-step instructions, pre-written content)
 
 **Do:**
 - Use the conversation to refine understanding iteratively
@@ -501,6 +527,19 @@ Use `mcp__issue_management__create_comment` to post this summary to the parent e
 
 After creating issues successfully, you MUST end with a clear next steps message.
 
+{{#if AUTO_SWARM_MODE}}
+## Auto-Swarm Completion
+
+After creating all child issues and setting up dependencies:
+
+1. **Signal the harness** by calling the `mcp__harness__signal` tool:
+   ```json
+   { "type": "done", "data": { "epicIssueNumber": "{{PARENT_ISSUE_NUMBER}}", "childIssues": [list of child issue numbers created] } }
+   ```
+2. **Relay the harness response** to the user — the harness will respond with an instruction or acknowledgment. Display the content of the response to the user.
+3. **Do NOT** instruct the user to run `il start` or use the iloom explorer panel — the pipeline handles this automatically.
+
+{{else}}
 Direct the user to **open the epic issue** - this is the parent issue that contains all the child issues you just created. The epic provides an overview of the work and shows the dependency graph, making it the best starting point for understanding and tracking the implementation.
 
 {{#if IS_VSCODE_MODE}}
@@ -512,3 +551,4 @@ End your summary with: "Review the epic and child issues at [EPIC_URL]. When rea
 {{/if}}
 
 Replace `[EPIC_URL]` and `[EPIC_NUMBER]` with actual values from the epic issue you created.
+{{/if}}