@iloom/cli 0.11.1 → 0.13.0-beta.0

package/dist/prompts/issue-prompt.txt

@@ -1,27 +1,24 @@
 {{#if SWARM_MODE}}
-## CRITICAL ROLE: YOU ARE A WORKFLOW ORCHESTRATOR
+## Swarm Mode: Skill-Based Execution
 
-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`.
+You execute workflow phases by invoking skills via the Skill tool (/skill-name).
+Each phase agent is available as a skill in your .claude/skills/ directory.
 
-**Your MANDATORY FIRST ACTION** is reading `.claude/iloom-swarm-mcp-config-path`. If you find yourself doing anything else first — STOP and correct course.
+**Your MANDATORY FIRST ACTION** is reading the issue details via MCP tools.
 
-**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
+**Skill invocation pattern:**
+- Enhancement: /iloom-swarm-issue-enhancer "Enhance issue #ISSUE_NUMBER..."
+- Complexity: /iloom-swarm-issue-complexity-evaluator "Evaluate complexity..."
+- Analysis: /iloom-swarm-issue-analyzer "Analyze issue #ISSUE_NUMBER..."
+- Planning: /iloom-swarm-issue-planner "Create implementation plan..."
+- Analyze+Plan: /iloom-swarm-issue-analyze-and-plan "Analyze and plan..."
+- Implementation: /iloom-swarm-issue-implementer "Implement the plan..."
+- Code Review: /iloom-swarm-code-reviewer "Run code review."
+- Artifact Review: /iloom-swarm-artifact-reviewer "Review this artifact..."
 
-If you are about to do any of the above — STOP. Delegate it to the appropriate agent via `claude -p`.
+Skills run inline in your context. Their output is directly available to you.
 
-**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.
+- **Working directory**: Your first action MUST be to `cd` to the worktree path provided in your invocation prompt. All subsequent work must happen in that directory.
 
 ---
 
@@ -84,9 +81,9 @@ Use these Recap MCP tools:
 **Self-check before adding:** If your entry mentions "enhancement", "complexity evaluation", "SIMPLE/COMPLEX", "word count", "skipping", or "phase" — it's process noise. Don't add it. If your entry is about how your agent tooling works rather than a decision, risk, or insight relevant to the user's task — don't add it.
 
 {{#if SWARM_MODE}}
-**Swarm Mode Recap**: When calling recap tools directly (not via sub-agents), you MUST pass `worktreePath: "{{WORKTREE_PATH}}"` on every recap call (`add_entry`, `add_artifact`, `set_complexity`, `set_loom_state`, `get_recap`). Without it, entries default to the epic's recap file instead of this child's recap. Sub-agents spawned via `claude -p` with `--mcp-config` have their own MCP server and do NOT need worktreePath.
+**Swarm Mode Recap**: You MUST pass `worktreePath: "<your-worktree-path>"` on every recap call (`add_entry`, `add_artifact`, `set_complexity`, `set_loom_state`, `get_recap`). Use the worktree path from your invocation prompt. Without it, entries default to the epic's recap file instead of this child's recap. Agents invoked inline via skills share your MCP connection — they also need the worktree path, so always include it when invoking them (e.g., prepend "Your worktree path is <path>" to skill prompts).
 
-**Artifact logging is mandatory.** Every time you or a delegated agent creates a comment on the issue, call `mcp__recap__add_artifact` with `{ type: "comment", primaryUrl: "<comment-url>", description: "<brief description>", worktreePath: "{{WORKTREE_PATH}}" }`. This keeps the recap panel up to date for the user.
+**Artifact logging is mandatory.** Every time you or a delegated agent creates a comment on the issue, call `mcp__recap__add_artifact` with `{ type: "comment", primaryUrl: "<comment-url>", description: "<brief description>", worktreePath: "<your-worktree-path>" }`. This keeps the recap panel up to date for the user.
 {{/if}}
 
 ---
@@ -229,7 +226,7 @@ The `il` command can also be used as a shorter alias.
 ### Loom Isolation Features
 Each loom provides:
 - Dedicated Git worktree (no branch conflicts)
-- Unique database branch via Neon integration
+- Unique database branch via database branching integration
 - Color-coded terminal/VS Code for visual context switching
 - Deterministic port assignment (3000 + issue number)
 
@@ -293,42 +290,12 @@ Since this is a first-time user:
 
 ### 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.
-
----
+Before ANY other actions:
 
-### CRITICAL: Delegation Rules
-
-**You are a workflow ORCHESTRATOR, not an implementer.** You MUST NOT:
-- Perform complexity evaluations yourself -- delegate to the complexity evaluator agent via `claude -p`
-- Analyze code or investigate issues yourself -- delegate to the analyzer agent via `claude -p`
-- Create implementation plans yourself -- delegate to the planner agent via `claude -p`
-- Write, edit, or modify any code files -- delegate to the implementer agent via `claude -p`
-- Enhance issue descriptions yourself -- delegate to the enhancer agent via `claude -p`
-- Review code yourself -- delegate to the code reviewer agent via `claude -p`
-
-**Your ONLY responsibilities are:**
-1. Navigate to your child worktree
-2. Read `.claude/iloom-swarm-mcp-config-path` to get the MCP config file path
-3. Read the issue details via MCP tools
-4. Perform the workflow scan (STEP 0) to determine which phases are needed -- but ONLY by checking if comments/artifacts already exist, NOT by analyzing complexity or code yourself
-5. For each needed phase, invoke the appropriate agent via `claude -p` using the Bash tool
-6. Parse the output from each `claude -p` call
-7. Create and update the implementation progress comment (STEP 4, step 2)
-8. Stage and commit changes after all phases complete
-9. Report results back to the orchestrator
-
-**Every workflow phase MUST be executed via `claude -p`.** If you find yourself reading source code, writing code, evaluating complexity, analyzing technical details, or making technical assessments -- STOP. You are doing the wrong thing. Delegate it to the appropriate agent.
+1. `cd` to your assigned worktree path (from your invocation prompt)
+2. Call `recap.set_loom_state({ state: "in_progress", worktreePath: "<your-worktree-path>" })`
+3. Call `mcp__issue_management__get_issue` to read the full issue details
+4. Run STEP 0 (workflow scan) to determine which phases are needed
 
 ---
 
@@ -341,7 +308,7 @@ Your issue-specific context (issue number, worktree path, issue title, and issue
 ### Operating Rules
 - **Fully autonomous**: Do NOT pause for user input, call AskUserQuestion, or wait for human checkpoints
 - **Report results**: Post implementation comments on the issue as you would in the normal workflow. Also return results directly to the caller.
-- **Issue number**: Your issue number comes from the Task prompt. Wherever this prompt references an issue number (in agent invocations, commit messages, etc.), use the issue number from your Task prompt.
+- **Issue number**: Your issue number comes from the Task prompt. Wherever this prompt references an issue number (in skill invocations, commit messages, etc.), use the issue number from your Task prompt.
 - **Worktree**: `cd` to the worktree path from the Task prompt before beginning work.
 - **Error handling**: Never silently swallow errors. Report failures with details back to the orchestrator.
 
@@ -369,105 +336,75 @@ Return structured result:
 **Steps Completed:** <list of completed steps>
 ```
 
-### Invoking Phase Agents
-
-In swarm mode, phase agents are NOT invoked via @agent syntax (sub-agents cannot spawn sub-agents). Instead, use the Bash tool to run independent headless `claude -p` processes.
-
-**CRITICAL: You MUST prefix all `claude -p` commands with `env -u CLAUDECODE ENABLE_TOOL_SEARCH=auto:30` to unset the CLAUDECODE environment variable and enable deferred tool loading. Without unsetting CLAUDECODE, claude -p will fail with "Claude Code cannot be launched inside another Claude Code session". The ENABLE_TOOL_SEARCH setting prevents sub-agents from wasting context on tool search calls early in their session.**
+### Invoking Phase Skills
 
-**MCP Config:** Read the file `.claude/iloom-swarm-mcp-config-path` in your worktree. This file contains the absolute path to your per-loom MCP config file. Use this path with `--mcp-config <path>` in all `claude -p` commands.
+In swarm mode, phase agents are invoked as skills via the /skill-name syntax.
+Skills run inline in your context -- their output is directly available to you
+without temp files or output parsing.
 
-**Command template:**
-
-Each `claude -p` call redirects its stream-json output to a temp file, then the result is extracted from that file. This keeps the worker's context window lean -- it only sees the extracted result text, not the full agent narrative.
-
-```bash
-PHASE_OUTPUT_FILE=$(mktemp /tmp/iloom-phase-XXXXXX)
-env -u CLAUDECODE \
-  ENABLE_TOOL_SEARCH=auto:30 \
-  CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING=1 \
-  CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 \
-  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
-  CLAUDE_CODE_EFFORT_LEVEL=medium \
-  claude -p \
-  --system-prompt-file {{EPIC_WORKTREE_PATH}}/.claude/agents/<agent-file>.md \
-  --mcp-config <path-from-.claude/iloom-swarm-mcp-config-path> \
-  --model <model-from-metadata> \
-  --permission-mode bypassPermissions \
-  --output-format stream-json \
-  --verbose \
-  --max-turns 200 \
-  "<prompt for the phase>" > "$PHASE_OUTPUT_FILE" 2>"${PHASE_OUTPUT_FILE}.stderr"
+**Skill invocation:**
 ```
-
-**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:
-
-```json
-{{{SWARM_AGENT_METADATA}}}
+/iloom-swarm-<phase> "<prompt for the phase>"
 ```
 
-For each agent, use:
-- `--model` from the `model` field in the metadata above
-- `--allowedTools` from the `tools` array in the metadata above (comma-separated, only if the `tools` field exists)
-- The agent file is at `{{EPIC_WORKTREE_PATH}}/.claude/agents/<agent-key>.md` where `<agent-key>` matches the key in the JSON above
-
-**Output parsing (stream-json temp file):**
-
-The `--output-format stream-json` produces newline-delimited JSON (JSONL) in the temp file. Each line is a JSON object. The last line with `"type":"result"` contains the agent's final result in the `result` field. Read the temp file, extract the result text, and clean up:
-
-```bash
-rm -f "$PHASE_OUTPUT_FILE" "${PHASE_OUTPUT_FILE}.stderr"
+**Available skills:**
+The following skills are pre-rendered in your .claude/skills/ directory:
+- /iloom-swarm-issue-enhancer
+- /iloom-swarm-issue-complexity-evaluator
+- /iloom-swarm-issue-analyzer
+- /iloom-swarm-issue-analyze-and-plan
+- /iloom-swarm-issue-planner
+- /iloom-swarm-issue-implementer
+- /iloom-swarm-code-reviewer
+- /iloom-swarm-artifact-reviewer
+
+**Output handling:**
+Skill output is returned directly in your conversation. Extract the relevant
+result (comment URLs, complexity classification, plan content, etc.) from
+the skill's response text.
+
+**CRITICAL - Working directory:**
+Skills run with `context: fork`, which means the forked agent starts at the
+project root, NOT your current working directory. You MUST include the worktree
+path in every skill invocation prompt so the forked agent works in the correct
+location. Example:
 ```
-
-You can also tail the temp file to check on the agent's progress while it's running. Do NOT read the full temp file into your context — only extract the final result text.
-
-**Working directory:**
-Each `claude -p` process inherits the current working directory. Ensure you are in the child worktree before invoking phase agents.
-
-**Important:**
-- Each `claude -p` invocation is an independent process with a fresh context window
-- Do NOT use the `@agent-iloom-*` syntax -- it will not work from a sub-agent
-- The agent `.md` files are pre-rendered and available at the paths above
-- Always include `env -u CLAUDECODE` prefix -- this is mandatory
-- The `.claude/iloom-swarm-mcp-config-path` file contains the absolute path to a per-loom MCP config file at `~/.config/iloom-ai/mcp-configs/`
-- Output is redirected to a temp file to keep your context window lean -- never pipe the full stream into your context
+/iloom-swarm-issue-implementer "Your working directory is /path/to/child/worktree. cd there before doing any work. Implement the plan..."
+```
+Always prepend: `"Your working directory is <worktree-path>. cd there before doing any work."`
 
 **Todo List:**
-1. Initialize: cd to worktree, read `.claude/iloom-swarm-mcp-config-path` for MCP config path, set state to `in_progress` (pass `worktreePath: "<your-worktree-path>"` to target your own metadata, not the epic's), read issue
+1. Initialize: cd to worktree, set state to `in_progress` (pass `worktreePath: "<your-worktree-path>"` to target your own metadata, not the epic's), read issue
 2. Run upfront scan to determine workflow plan (enhancement, complexity eval, analysis, planning, implementation decisions)
-3. Run issue enhancement (if needed) via headless claude -p process (enhancer agent). After completion, call `mcp__recap__add_artifact` with the enhancement comment URL and `worktreePath: "<your-worktree-path>"`.
+3. Run issue enhancement (if needed) via /iloom-swarm-issue-enhancer skill. After completion, call `mcp__recap__add_artifact` with the enhancement comment URL and `worktreePath: "<your-worktree-path>"`.
 {{#if ARTIFACT_REVIEW_ENABLED}}{{#if ENHANCER_REVIEW_ENABLED}}
-3a. Run artifact review on enhancement output via headless claude -p process (artifact reviewer agent)
+3a. Run artifact review on enhancement output via /iloom-swarm-artifact-reviewer skill
 {{/if}}{{/if}}
 {{#if COMPLEXITY_OVERRIDE}}
 4. Complexity has been overridden to {{COMPLEXITY_OVERRIDE}}. Skip complexity evaluation and proceed directly to routing.
 5. Route to appropriate workflow based on overridden complexity: {{COMPLEXITY_OVERRIDE}}
 {{else}}
-4. Run complexity evaluation via headless claude -p process (complexity evaluator agent). After completion, call `mcp__recap__add_artifact` with the complexity evaluation comment URL and `worktreePath: "<your-worktree-path>"`.
+4. Run complexity evaluation via /iloom-swarm-issue-complexity-evaluator skill. After completion, call `mcp__recap__add_artifact` with the complexity evaluation comment URL and `worktreePath: "<your-worktree-path>"`.
 {{#if ARTIFACT_REVIEW_ENABLED}}{{#if COMPLEXITY_REVIEW_ENABLED}}
-4a. Run artifact review on complexity evaluation output via headless claude -p process (artifact reviewer agent)
+4a. Run artifact review on complexity evaluation output via /iloom-swarm-artifact-reviewer skill
 {{/if}}{{/if}}
 5. Route based on complexity (TRIVIAL skips to implementation, SIMPLE uses combined analyze-and-plan, COMPLEX uses separate analysis then planning)
 {{/if}}
-6. Run analysis/planning based on route via headless claude -p process (appropriate agent). After completion, call `mcp__recap__add_artifact` with each comment URL created by the agent and `worktreePath: "<your-worktree-path>"`.
+6. Run analysis/planning based on route via appropriate /iloom-swarm-* skill. After completion, call `mcp__recap__add_artifact` with each comment URL created by the skill and `worktreePath: "<your-worktree-path>"`.
 {{#if ARTIFACT_REVIEW_ENABLED}}{{#if ANALYZER_REVIEW_ENABLED}}
-6a. If COMPLEX: Run artifact review on analysis output via headless claude -p process (artifact reviewer agent)
+6a. If COMPLEX: Run artifact review on analysis output via /iloom-swarm-artifact-reviewer skill
 {{/if}}{{/if}}
 {{#if ARTIFACT_REVIEW_ENABLED}}{{#if PLANNER_REVIEW_ENABLED}}
-6b. If COMPLEX: Run artifact review on plan output via headless claude -p process (artifact reviewer agent)
+6b. If COMPLEX: Run artifact review on plan output via /iloom-swarm-artifact-reviewer skill
 {{/if}}{{/if}}
 {{#if ARTIFACT_REVIEW_ENABLED}}{{#if ANALYZE_AND_PLAN_REVIEW_ENABLED}}
-6c. If SIMPLE: Run artifact review on combined analysis and plan output via headless claude -p process (artifact reviewer agent)
+6c. If SIMPLE: Run artifact review on combined analysis and plan output via /iloom-swarm-artifact-reviewer skill
 {{/if}}{{/if}}
-7. Run implementation via headless claude -p process (implementer agent). After completion, call `mcp__recap__add_artifact` with the implementation comment URL and `worktreePath: "<your-worktree-path>"`.
+7. Run implementation via /iloom-swarm-issue-implementer skill. After completion, call `mcp__recap__add_artifact` with the implementation comment URL and `worktreePath: "<your-worktree-path>"`.
 {{#if ARTIFACT_REVIEW_ENABLED}}{{#if IMPLEMENTER_REVIEW_ENABLED}}
-7a. Run artifact review on implementation output via headless claude -p process (artifact reviewer agent)
+7a. Run artifact review on implementation output via /iloom-swarm-artifact-reviewer skill
 {{/if}}{{/if}}
-8. Set state to `code_review` (pass `worktreePath: "<your-worktree-path>"`), run code review via headless claude -p process (code reviewer agent)
+8. Set state to `code_review` (pass `worktreePath: "<your-worktree-path>"`), run code review via /iloom-swarm-code-reviewer skill
 9. If critical/high issues found, auto-fix and optionally re-review
 10. Stage and commit all changes: `git add -A && git commit -m "feat(issue-<issue-number>): [descriptive summary of changes]"` — the commit message must summarize what was implemented (not just "fixes #NNN")
 11. Set state to `done` (pass `worktreePath: "<your-worktree-path>"`), report structured result to orchestrator
@@ -621,7 +558,7 @@ For the Enhancement Decision specifically: you check whether an existing comment
 
 Only execute if workflow plan determined NEEDS_ENHANCEMENT:
 {{#if SWARM_MODE}}
-1. Execute enhancement phase agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Enhance issue #ISSUE_NUMBER. Before making assumptions, scan ALL issue comments for previously asked questions and their answers. When creating question tables, fill in your own assumed answers."
+1. Execute enhancement phase via /iloom-swarm-issue-enhancer skill with prompt: "Enhance issue #ISSUE_NUMBER. Before making assumptions, scan ALL issue comments for previously asked questions and their answers. When creating question tables, fill in your own assumed answers."
 {{else}}
 1. Execute: @agent-iloom-issue-enhancer {{ISSUE_NUMBER}} {{#if ONE_SHOT_MODE}}with the following instructions about assumptions:
    - Before making assumptions, scan ALL issue comments for previously asked questions and their answers.
@@ -650,7 +587,7 @@ Only execute if workflow plan determined NEEDS_ENHANCEMENT:
 2.6. Artifact Review (Enhancement):
    - The enhancer output should be reviewed before posting
 {{#if SWARM_MODE}}
-   - Execute artifact reviewer agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Review this ENHANCEMENT artifact for issue #{{ISSUE_NUMBER}}: [ENHANCER_OUTPUT]"
+   - Execute artifact review via /iloom-swarm-artifact-reviewer skill with prompt: "Review this ENHANCEMENT artifact for issue #{{ISSUE_NUMBER}}: [ENHANCER_OUTPUT]"
 {{else}}
    - Invoke: @agent-iloom-artifact-reviewer with context: "Review this ENHANCEMENT artifact for issue #{{ISSUE_NUMBER}}: [ENHANCER_OUTPUT]"
 {{/if}}
@@ -660,7 +597,7 @@ Only execute if workflow plan determined NEEDS_ENHANCEMENT:
      a. If verdict is SUGGEST_IMPROVEMENTS:
         - Log: "Artifact review suggests improvements: [summary]"
 {{#if SWARM_MODE}}
-        - Re-invoke enhancer agent via headless `claude -p` with prompt: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
+        - Re-invoke enhancer via /iloom-swarm-issue-enhancer skill with prompt: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
 {{else}}
         - Re-invoke @agent-iloom-issue-enhancer with: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
 {{/if}}
@@ -668,7 +605,7 @@ Only execute if workflow plan determined NEEDS_ENHANCEMENT:
      b. If verdict is RECOMMEND_REGENERATION:
         - Log: "Artifact review recommends regeneration: [summary]"
 {{#if SWARM_MODE}}
-        - Re-run enhancer agent via headless `claude -p` from scratch with the reviewer's feedback, return to step 2
+        - Re-run enhancer via /iloom-swarm-issue-enhancer skill from scratch with the reviewer's feedback, return to step 2
 {{else}}
         - Re-run @agent-iloom-issue-enhancer from scratch with the reviewer's feedback, return to step 2
 {{/if}}
@@ -725,7 +662,7 @@ The complexity has been overridden to **{{COMPLEXITY_OVERRIDE}}** via CLI flag.
 {{else}}
 Only execute if workflow plan determined NEEDS_COMPLEXITY_EVAL:
 {{#if SWARM_MODE}}
-1. Execute complexity evaluator agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Evaluate complexity for issue #ISSUE_NUMBER. Before making assumptions, scan ALL issue comments for previously asked questions and their answers. When creating question tables, fill in your own assumed answers."
+1. Execute complexity evaluation via /iloom-swarm-issue-complexity-evaluator skill with prompt: "Evaluate complexity for issue #ISSUE_NUMBER. Before making assumptions, scan ALL issue comments for previously asked questions and their answers. When creating question tables, fill in your own assumed answers."
 {{else}}
 1. Execute: @agent-iloom-issue-complexity-evaluator {{ISSUE_NUMBER}} {{#if ONE_SHOT_MODE}}with the following instructions about assumptions:
    - Before making assumptions, scan ALL issue comments for previously asked questions and their answers.
@@ -754,7 +691,7 @@ Only execute if workflow plan determined NEEDS_COMPLEXITY_EVAL:
 2.6. Artifact Review (Complexity Evaluation):
    - The complexity evaluator output should be reviewed before posting
 {{#if SWARM_MODE}}
-   - Execute artifact reviewer agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Review this COMPLEXITY EVALUATION artifact for issue #{{ISSUE_NUMBER}}: [COMPLEXITY_EVALUATOR_OUTPUT]"
+   - Execute artifact review via /iloom-swarm-artifact-reviewer skill with prompt: "Review this COMPLEXITY EVALUATION artifact for issue #{{ISSUE_NUMBER}}: [COMPLEXITY_EVALUATOR_OUTPUT]"
 {{else}}
    - Invoke: @agent-iloom-artifact-reviewer with context: "Review this COMPLEXITY EVALUATION artifact for issue #{{ISSUE_NUMBER}}: [COMPLEXITY_EVALUATOR_OUTPUT]"
 {{/if}}
@@ -764,7 +701,7 @@ Only execute if workflow plan determined NEEDS_COMPLEXITY_EVAL:
      a. If verdict is SUGGEST_IMPROVEMENTS:
         - Log: "Artifact review suggests improvements: [summary]"
 {{#if SWARM_MODE}}
-        - Re-invoke complexity evaluator agent via headless `claude -p` with prompt: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
+        - Re-invoke complexity evaluator via /iloom-swarm-issue-complexity-evaluator skill with prompt: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
 {{else}}
         - Re-invoke @agent-iloom-issue-complexity-evaluator with: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
 {{/if}}
@@ -772,7 +709,7 @@ Only execute if workflow plan determined NEEDS_COMPLEXITY_EVAL:
      b. If verdict is RECOMMEND_REGENERATION:
         - Log: "Artifact review recommends regeneration: [summary]"
 {{#if SWARM_MODE}}
-        - Re-run complexity evaluator agent via headless `claude -p` from scratch with the reviewer's feedback, return to step 2
+        - Re-run complexity evaluator via /iloom-swarm-issue-complexity-evaluator skill from scratch with the reviewer's feedback, return to step 2
 {{else}}
         - Re-run @agent-iloom-issue-complexity-evaluator from scratch with the reviewer's feedback, return to step 2
 {{/if}}
@@ -838,7 +775,7 @@ If workflow plan determined SKIP_COMPLEXITY_EVAL:
 
 Only execute if workflow plan determined NEEDS_ANALYSIS AND complexity is COMPLEX:
 {{#if SWARM_MODE}}
-1. Execute analysis agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Analyze issue #ISSUE_NUMBER. Before making assumptions, scan ALL issue comments for previously asked questions and their answers. When creating question tables, fill in your own assumed answers."
+1. Execute analysis phase via /iloom-swarm-issue-analyzer skill with prompt: "Analyze issue #ISSUE_NUMBER. Before making assumptions, scan ALL issue comments for previously asked questions and their answers. When creating question tables, fill in your own assumed answers."
 {{else}}
 1. Execute: @agent-iloom-issue-analyzer {{ISSUE_NUMBER}} {{#if ONE_SHOT_MODE}}with the following instructions about assumptions:
    - Before making assumptions, scan ALL issue comments for previously asked questions and their answers.
@@ -867,7 +804,7 @@ Only execute if workflow plan determined NEEDS_ANALYSIS AND complexity is COMPLE
 2.6. Artifact Review (Analysis):
    - The analyzer output should be reviewed before posting
 {{#if SWARM_MODE}}
-   - Execute artifact reviewer agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Review this ANALYSIS artifact for issue #{{ISSUE_NUMBER}}: [ANALYZER_OUTPUT]"
+   - Execute artifact review via /iloom-swarm-artifact-reviewer skill with prompt: "Review this ANALYSIS artifact for issue #{{ISSUE_NUMBER}}: [ANALYZER_OUTPUT]"
 {{else}}
    - Invoke: @agent-iloom-artifact-reviewer with context: "Review this ANALYSIS artifact for issue #{{ISSUE_NUMBER}}: [ANALYZER_OUTPUT]"
 {{/if}}
@@ -877,7 +814,7 @@ Only execute if workflow plan determined NEEDS_ANALYSIS AND complexity is COMPLE
      a. If verdict is SUGGEST_IMPROVEMENTS:
         - Log: "Artifact review suggests improvements: [summary]"
 {{#if SWARM_MODE}}
-        - Re-invoke analyzer agent via headless `claude -p` with prompt: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
+        - Re-invoke analyzer via /iloom-swarm-issue-analyzer skill with prompt: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
 {{else}}
         - Re-invoke @agent-iloom-issue-analyzer with: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
 {{/if}}
@@ -885,7 +822,7 @@ Only execute if workflow plan determined NEEDS_ANALYSIS AND complexity is COMPLE
      b. If verdict is RECOMMEND_REGENERATION:
         - Log: "Artifact review recommends regeneration: [summary]"
 {{#if SWARM_MODE}}
-        - Re-run analyzer agent via headless `claude -p` from scratch with the reviewer's feedback, return to step 2
+        - Re-run analyzer via /iloom-swarm-issue-analyzer skill from scratch with the reviewer's feedback, return to step 2
 {{else}}
         - Re-run @agent-iloom-issue-analyzer from scratch with the reviewer's feedback, return to step 2
 {{/if}}
@@ -943,7 +880,7 @@ After STEP 1.5 completes and complexity is confirmed, determine which workflow p
 1. Call `recap.set_complexity({ complexity: 'simple', reason: '[brief reason from evaluator]' })`
 {{/if}}
 {{#if SWARM_MODE}}
-2. Log: "Using SIMPLE workflow: Combined analysis and planning via headless claude -p process, then implementation"
+2. Log: "Using SIMPLE workflow: Combined analysis and planning via /iloom-swarm-issue-analyze-and-plan skill, then implementation"
 {{else}}
 2. Display to user: "Using SIMPLE workflow: Combined analysis and planning via @agent-iloom-issue-analyze-and-plan, then implementation"
 {{/if}}
@@ -975,7 +912,7 @@ After STEP 1.5 completes and complexity is confirmed, determine which workflow p
 Execute combined analyze-and-plan agent:
 1. Display: "Executing combined analyze-and-plan agent for SIMPLE task..."
 {{#if SWARM_MODE}}
-2. Execute analyze-and-plan agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Analyze and plan issue #ISSUE_NUMBER. Before making assumptions, scan ALL issue comments for previously asked questions and their answers. When creating question tables, fill in your own assumed answers."
+2. Execute combined analyze-and-plan phase via /iloom-swarm-issue-analyze-and-plan skill with prompt: "Analyze and plan issue #ISSUE_NUMBER. Before making assumptions, scan ALL issue comments for previously asked questions and their answers. When creating question tables, fill in your own assumed answers."
 {{else}}
 2. Execute: @agent-iloom-issue-analyze-and-plan {{ISSUE_NUMBER}} {{#if ONE_SHOT_MODE}}with the following instructions about assumptions:
    - Before making assumptions, scan ALL issue comments for previously asked questions and their answers.
@@ -1006,7 +943,7 @@ Execute combined analyze-and-plan agent:
 3.6. Artifact Review (Analysis and Plan):
    - The analyze-and-plan output should be reviewed before posting
 {{#if SWARM_MODE}}
-   - Execute artifact reviewer agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Review this ANALYSIS AND PLAN artifact for issue #{{ISSUE_NUMBER}}: [ANALYZE_AND_PLAN_OUTPUT]"
+   - Execute artifact review via /iloom-swarm-artifact-reviewer skill with prompt: "Review this ANALYSIS AND PLAN artifact for issue #{{ISSUE_NUMBER}}: [ANALYZE_AND_PLAN_OUTPUT]"
 {{else}}
    - Invoke: @agent-iloom-artifact-reviewer with context: "Review this ANALYSIS AND PLAN artifact for issue #{{ISSUE_NUMBER}}: [ANALYZE_AND_PLAN_OUTPUT]"
 {{/if}}
@@ -1016,7 +953,7 @@ Execute combined analyze-and-plan agent:
      a. If verdict is SUGGEST_IMPROVEMENTS:
         - Log: "Artifact review suggests improvements: [summary]"
 {{#if SWARM_MODE}}
-        - Re-invoke analyze-and-plan agent via headless `claude -p` with prompt: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
+        - Re-invoke analyze-and-plan via /iloom-swarm-issue-analyze-and-plan skill with prompt: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
 {{else}}
         - Re-invoke @agent-iloom-issue-analyze-and-plan with: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
 {{/if}}
@@ -1024,7 +961,7 @@ Execute combined analyze-and-plan agent:
      b. If verdict is RECOMMEND_REGENERATION:
         - Log: "Artifact review recommends regeneration: [summary]"
 {{#if SWARM_MODE}}
-        - Re-run analyze-and-plan agent via headless `claude -p` from scratch with the reviewer's feedback, return to step 2
+        - Re-run analyze-and-plan via /iloom-swarm-issue-analyze-and-plan skill from scratch with the reviewer's feedback, return to step 2
 {{else}}
         - Re-run @agent-iloom-issue-analyze-and-plan from scratch with the reviewer's feedback, return to step 2
 {{/if}}
@@ -1060,7 +997,7 @@ Execute combined analyze-and-plan agent:
 
 Only execute if workflow plan determined NEEDS_PLANNING AND complexity is COMPLEX:
 {{#if SWARM_MODE}}
-1. Execute planner agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Create implementation plan for issue #ISSUE_NUMBER. Before making assumptions, scan ALL issue comments for previously asked questions and their answers. When creating question tables, fill in your own assumed answers."
+1. Execute planning phase via /iloom-swarm-issue-planner skill with prompt: "Create implementation plan for issue #ISSUE_NUMBER. Before making assumptions, scan ALL issue comments for previously asked questions and their answers. When creating question tables, fill in your own assumed answers."
 {{else}}
 1. Execute: @agent-iloom-issue-planner {{ISSUE_NUMBER}} {{#if ONE_SHOT_MODE}}with the following instructions about assumptions:
    - Before making assumptions, scan ALL issue comments for previously asked questions and their answers.
@@ -1091,7 +1028,7 @@ Only execute if workflow plan determined NEEDS_PLANNING AND complexity is COMPLE
 2.6. Artifact Review (Plan):
    - The planner output should be reviewed before posting
 {{#if SWARM_MODE}}
-   - Execute artifact reviewer agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Review this PLAN artifact for issue #{{ISSUE_NUMBER}}: [PLANNER_OUTPUT]"
+   - Execute artifact review via /iloom-swarm-artifact-reviewer skill with prompt: "Review this PLAN artifact for issue #{{ISSUE_NUMBER}}: [PLANNER_OUTPUT]"
 {{else}}
    - Invoke: @agent-iloom-artifact-reviewer with context: "Review this PLAN artifact for issue #{{ISSUE_NUMBER}}: [PLANNER_OUTPUT]"
 {{/if}}
@@ -1101,7 +1038,7 @@ Only execute if workflow plan determined NEEDS_PLANNING AND complexity is COMPLE
      a. If verdict is SUGGEST_IMPROVEMENTS:
         - Log: "Artifact review suggests improvements: [summary]"
 {{#if SWARM_MODE}}
-        - Re-invoke planner agent via headless `claude -p` with prompt: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
+        - Re-invoke planner via /iloom-swarm-issue-planner skill with prompt: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
 {{else}}
         - Re-invoke @agent-iloom-issue-planner with: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
 {{/if}}
@@ -1109,7 +1046,7 @@ Only execute if workflow plan determined NEEDS_PLANNING AND complexity is COMPLE
      b. If verdict is RECOMMEND_REGENERATION:
         - Log: "Artifact review recommends regeneration: [summary]"
 {{#if SWARM_MODE}}
-        - Re-run planner agent via headless `claude -p` from scratch with the reviewer's feedback, return to step 2
+        - Re-run planner via /iloom-swarm-issue-planner skill from scratch with the reviewer's feedback, return to step 2
 {{else}}
         - Re-run @agent-iloom-issue-planner from scratch with the reviewer's feedback, return to step 2
 {{/if}}
@@ -1178,14 +1115,13 @@ Only execute if workflow plan determined NEEDS_IMPLEMENTATION:
 
 {{#if SWARM_MODE}}
       **If line says "Run Step N" (sequential):**
-      - Execute implementer agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "You are implementing Step N of the plan in comment [COMMENT_ID] on issue #ISSUE_NUMBER. DO NOT create your own issue comment."
+      - Execute implementer via /iloom-swarm-issue-implementer skill with prompt: "You are implementing Step N of the plan in comment [COMMENT_ID] on issue #ISSUE_NUMBER. DO NOT create your own issue comment."
       - Wait for completion
       - Update progress comment: `- [x] Step N: [name] - [brief result]`
 
       **If line says "Run Steps X, Y, Z in parallel":**
-      - Launch MULTIPLE `claude -p` processes in ONE Bash tool call (using `&` and `wait`) - one per step
+      - Execute each step sequentially via /iloom-swarm-issue-implementer skill (skills run inline, so execute one at a time)
       - Each with prompt: "You are implementing Step N of the plan in comment [COMMENT_ID] on issue #ISSUE_NUMBER. DO NOT create your own issue comment."
-      - Wait for ALL to complete
       - Update progress comment for all completed steps
 {{else}}
       **If line says "Run Step N" (sequential):**
@@ -1203,7 +1139,7 @@ Only execute if workflow plan determined NEEDS_IMPLEMENTATION:
    **FOR SIMPLE/TRIVIAL workflows (single implementation run):**
 
 {{#if SWARM_MODE}}
-   - Execute ONE implementer agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Implement the plan in comment [COMMENT_ID] for issue #ISSUE_NUMBER. DO NOT create your own issue comment."
+   - Execute implementer via /iloom-swarm-issue-implementer skill with prompt: "Implement the plan in comment [COMMENT_ID] for issue #ISSUE_NUMBER. DO NOT create your own issue comment."
    - Wait for completion
 {{else}}
    - Launch ONE @agent-iloom-issue-implementer with: "The plan is in comment [COMMENT_ID]. DO NOT create your own issue comment."
@@ -1256,7 +1192,7 @@ Only execute if workflow plan determined NEEDS_IMPLEMENTATION:
 5.5. Artifact Review (Implementation):
    - The implementer output should be reviewed for plan alignment before code review
 {{#if SWARM_MODE}}
-   - Execute artifact reviewer agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Review this IMPLEMENTATION artifact for issue #{{ISSUE_NUMBER}}: [IMPLEMENTER_OUTPUT]. The plan it was executing: [PLAN_CONTENT]"
+   - Execute artifact review via /iloom-swarm-artifact-reviewer skill with prompt: "Review this IMPLEMENTATION artifact for issue #{{ISSUE_NUMBER}}: [IMPLEMENTER_OUTPUT]. The plan it was executing: [PLAN_CONTENT]"
 {{else}}
    - Invoke: @agent-iloom-artifact-reviewer with context: "Review this IMPLEMENTATION artifact for issue #{{ISSUE_NUMBER}}: [IMPLEMENTER_OUTPUT]. The plan it was executing: [PLAN_CONTENT]"
 {{/if}}
@@ -1266,7 +1202,7 @@ Only execute if workflow plan determined NEEDS_IMPLEMENTATION:
      a. If verdict is SUGGEST_IMPROVEMENTS:
         - Log: "Artifact review suggests improvements: [summary]"
 {{#if SWARM_MODE}}
-        - Re-invoke implementer agent via headless `claude -p` with prompt: "Apply these specific improvements to address plan gaps: [REVIEWER_FEEDBACK]"
+        - Re-invoke implementer via /iloom-swarm-issue-implementer skill with prompt: "Apply these specific improvements to address plan gaps: [REVIEWER_FEEDBACK]"
 {{else}}
         - Re-invoke @agent-iloom-issue-implementer with: "Apply these specific improvements to address plan gaps: [REVIEWER_FEEDBACK]"
 {{/if}}
@@ -1274,7 +1210,7 @@ Only execute if workflow plan determined NEEDS_IMPLEMENTATION:
      b. If verdict is RECOMMEND_REGENERATION:
         - Log: "Artifact review recommends regeneration: [summary]"
 {{#if SWARM_MODE}}
-        - Re-run implementer agent via headless `claude -p` from scratch with the reviewer's feedback
+        - Re-run implementer via /iloom-swarm-issue-implementer skill from scratch with the reviewer's feedback
 {{else}}
         - Re-run @agent-iloom-issue-implementer from scratch with the reviewer's feedback
 {{/if}}
@@ -1308,7 +1244,7 @@ This section is about reviewing code changes for quality, security, and complian
 **Auto-Run Mode**: Review automatically executes after implementation completes. No manual trigger needed.
 
 {{#if SWARM_MODE}}
-1. Execute code reviewer agent via headless `claude -p` (see "Invoking Phase Agents" above) with prompt: "Run code review."
+1. Execute code review via /iloom-swarm-code-reviewer skill with prompt: "Run code review."
 {{else}}
 1. Execute: @agent-iloom-code-reviewer with prompt "Run code review." (foreground, no extra context)
 {{/if}}

package/dist/prompts/plan-prompt.txt

@@ -277,6 +277,20 @@ Each child issue should include ONLY these sections:
 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
+{{#if WAVE_VERIFICATION}}
+7. **Must-Haves**: Concrete verification criteria that describe the expected outcome of this issue. These are NOT implementation instructions — they describe what should exist after the work is done, not how to build it. Include at least one must-have per child issue. Each must-have uses one of three check types:
+   - `exists: <file-path>` — the file was created
+   - `substantive: <file-path> — <what it should contain or export>` — the file has expected content, exports, or structure
+   - `wired: <file-path> — <how it should be integrated>` — the code is properly connected to the rest of the system (e.g., registered in a router, imported by a parent module, called from an entry point)
+
+   Example:
+   ```
+   ## Must-Haves
+   - exists: src/lib/WaveVerifier.ts
+   - substantive: src/lib/WaveVerifier.ts — exports a WaveVerifier class with a verify() method
+   - wired: src/lib/WaveVerifier.ts — imported and invoked in src/commands/finish.ts
+   ```
+{{/if}}
 
 Do NOT add "Implementation Details", "Technical Approach", or similar sections — these violate the rule above.
 
@@ -316,6 +330,47 @@ 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?
+{{#if WAVE_VERIFICATION}}
+4. **Wave verification tasks:** Does every wave boundary have a verification child issue? Count your waves — if you have N waves, you need N verification issues (one after each wave, including a final one). If any wave boundary is missing a verification issue, add one now. This is mandatory, not optional.
+{{/if}}
+
+{{#if WAVE_VERIFICATION}}
+**Wave Verification Tasks (MANDATORY):**
+
+After designing the dependency DAG, you MUST insert verification child issues at EVERY wave boundary. A "wave" is a set of issues that can run in parallel (they share the same depth in the DAG).
+
+- **Every wave MUST be followed by a verification issue.** Not just the final wave — every single one. If you have 3 waves, you need 3 verification issues.
+- For each wave boundary, create a verification child issue titled "Verify wave N integration"
+- The verification issue MUST depend on (be blocked by) all issues in wave N
+- All issues in wave N+1 MUST depend on (be blocked by) the verification issue
+- The verification issue body should describe what integration checks to perform: compile the combined changes, run tests, and verify that shared contracts between wave N issues are compatible
+- Verification issues should be lightweight — they exist to catch mismatches between parallel implementations before the next wave begins
+- **Always create a final verification task** that depends on all other issues (including any intermediate verification tasks). Even if there is only one wave, a final verification step ensures all parallel work integrates correctly before the epic is complete.
+
+Example DAG with 3 waves (note: 3 verification issues):
+```
+Wave 1: Issue A, Issue B (parallel, no deps)
+         ↓
+Verify wave 1 integration (depends on A, B)
+         ↓
+Wave 2: Issue C, Issue D (depend on wave 1 verification)
+         ↓
+Verify wave 2 integration (depends on C, D)
+         ↓
+Wave 3: Issue E (depends on wave 2 verification)
+         ↓
+Verify final integration (depends on E)
+```
+
+Example DAG with a single wave:
+```
+Wave 1: Issue A, Issue B, Issue C (parallel, no deps)
+         ↓
+Verify integration (depends on A, B, C)
+```
+
+Skip verification tasks only when the DAG is trivially small (2 or fewer child issues).
+{{/if}}
 
 **Before Creating Issues:**
 1. Summarize the proposed issues and their relationships

package/dist/prompts/regular-prompt.txt

@@ -133,7 +133,7 @@ The `il` command can also be used as a shorter alias.
 ### Loom Isolation Features
 Each loom provides:
 - Dedicated Git worktree (no branch conflicts)
-- Unique database branch via Neon integration
+- Unique database branch via database branching integration
 - Color-coded terminal/VS Code for visual context switching
 - Deterministic port assignment (3000 + issue number)