@iloom/cli 0.10.2 → 0.11.0

package/dist/prompts/issue-prompt.txt

@@ -79,8 +79,9 @@ Use these Recap MCP tools:
 - Complexity classifications
 - Status updates ("implementation complete", "tests pass")
 - Anything about your own workflow process
+- Meta-knowledge about the agent orchestration layer (iloom, MCP servers, worktree mechanics, prompt rendering, etc.) unless the tooling was a direct cause of a problem under investigation
 
-**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.
+**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.
@@ -377,15 +378,26 @@ In swarm mode, phase agents are NOT invoked via @agent syntax (sub-agents cannot
 **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.
 
 **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
-env -u CLAUDECODE ENABLE_TOOL_SEARCH=auto:30 claude -p \
-  --append-system-prompt-file {{EPIC_WORKTREE_PATH}}/.claude/agents/<agent-file>.md \
+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 text \
+  --output-format stream-json \
+  --verbose \
   --max-turns 50 \
-  "<prompt for the phase>"
+  "<prompt for the phase>" > "$PHASE_OUTPUT_FILE" 2>"${PHASE_OUTPUT_FILE}.stderr"
 ```
 
 **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.
@@ -403,8 +415,15 @@ For each agent, use:
 - `--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:**
-The `--output-format text` produces plain text output. The Bash tool output IS the agent's response -- no JSON parsing is needed.
+**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"
+```
+
+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.
@@ -415,6 +434,7 @@ Each `claude -p` process inherits the current working directory. Ensure you are
 - 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
 
 **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
@@ -423,11 +443,16 @@ Each `claude -p` process inherits the current working directory. Ensure you are
 {{#if ARTIFACT_REVIEW_ENABLED}}{{#if ENHANCER_REVIEW_ENABLED}}
 3a. Run artifact review on enhancement output via headless claude -p process (artifact reviewer agent)
 {{/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>"`.
 {{#if ARTIFACT_REVIEW_ENABLED}}{{#if COMPLEXITY_REVIEW_ENABLED}}
 4a. Run artifact review on complexity evaluation output via headless claude -p process (artifact reviewer agent)
 {{/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>"`.
 {{#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)
@@ -444,7 +469,7 @@ Each `claude -p` process inherits the current working directory. Ensure you are
 {{/if}}{{/if}}
 8. Set state to `code_review` (pass `worktreePath: "<your-worktree-path>"`), run code review via headless claude -p process (code reviewer agent)
 9. If critical/high issues found, auto-fix and optionally re-review
-10. Stage and commit all changes: `git add -A && git commit -m "fixes {{ISSUE_PREFIX}}<issue-number>"`
+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
 {{else}}
 You are orchestrating a set of agents through a development process, with human review at each step. This is referred to as the "iloom workflow".
@@ -460,6 +485,10 @@ You are orchestrating a set of agents through a development process, with human
 3. Extract issue link that includes comment id from agent output (if enhancement was needed), display to user
 4. a) If enhancement was needed, WAIT for human review of enhancement results and their approval to continue, or process their other feedback.
    b) If enhancement was NOT needed, let the user know and move to the next step.
+{{#if COMPLEXITY_OVERRIDE}}
+5. Complexity has been overridden to {{COMPLEXITY_OVERRIDE}} via CLI flag. Skip complexity evaluation and proceed directly to routing.
+6. Route to appropriate workflow based on overridden complexity: {{COMPLEXITY_OVERRIDE}}
+{{else}}
 5. Run complexity evaluation for {{ISSUE_NUMBER}} using @agent-iloom-issue-complexity-evaluator
 {{#if ARTIFACT_REVIEW_ENABLED}}{{#if COMPLEXITY_REVIEW_ENABLED}}
 5a. Run artifact review on complexity evaluation output using @agent-iloom-artifact-reviewer
@@ -467,6 +496,7 @@ You are orchestrating a set of agents through a development process, with human
 6. Extract issue link that includes comment id from agent output, display complexity assessment to user
 7. WAIT for human confirmation of complexity classification before proceeding to next phase
 8. Route to appropriate workflow based on confirmed complexity (TRIVIAL, SIMPLE, or COMPLEX)
+{{/if}}
 9. If SIMPLE: Run combined analysis and planning for {{ISSUE_NUMBER}} using @agent-iloom-issue-analyze-and-plan
 {{#if ARTIFACT_REVIEW_ENABLED}}{{#if ANALYZE_AND_PLAN_REVIEW_ENABLED}}
 9a. If SIMPLE: Run artifact review on combined analysis and plan output using @agent-iloom-artifact-reviewer
@@ -524,12 +554,17 @@ For the Enhancement Decision specifically: you check whether an existing comment
    - If skipping, log: "Issue #ISSUE_NUMBER is already thorough ([word count] words with clear structure), skipping enhancement"
 
    **Complexity Evaluation Decision:**
+{{#if COMPLEXITY_OVERRIDE}}
+   - Decision: SKIP_COMPLEXITY_EVAL (complexity overridden to {{COMPLEXITY_OVERRIDE}} via CLI flag)
+   - Log: "Complexity overridden to {{COMPLEXITY_OVERRIDE}} via CLI flag, skipping complexity evaluation"
+{{else}}
    - Search ALL comments for existing complexity evaluation. Consider "already evaluated" if ANY comment has:
      * Header containing "Complexity Assessment" or "Complexity Evaluation"
      * Section with "**Classification**: [TRIVIAL / SIMPLE / COMPLEX]"
      * Metrics section with estimated files, LOC, breaking changes, DB migrations, and risk level
    - Decision: NEEDS_COMPLEXITY_EVAL or SKIP_COMPLEXITY_EVAL
    - If skipping, log: "Issue #ISSUE_NUMBER already has complexity evaluation by @[author] from [date] showing [TRIVIAL/SIMPLE/COMPLEX] classification, skipping evaluation"
+{{/if}}
 
    **Analysis Decision:**
    - Search ALL comments for existing analysis. Consider "already analyzed" if ANY comment has ALL:
@@ -678,6 +713,16 @@ If workflow plan determined SKIP_ENHANCEMENT:
 
 **STEP 1.5 - Complexity Evaluation Phase:**
 
+{{#if COMPLEXITY_OVERRIDE}}
+The complexity has been overridden to **{{COMPLEXITY_OVERRIDE}}** via CLI flag. Skip complexity evaluation entirely.
+1. Set confirmed complexity to {{COMPLEXITY_OVERRIDE}}
+{{#if SWARM_MODE}}
+2. Log: "Complexity overridden to {{COMPLEXITY_OVERRIDE}} via CLI flag, skipping complexity evaluation"
+{{else}}
+2. Display to user: "Complexity overridden to {{COMPLEXITY_OVERRIDE}} via CLI flag, skipping complexity evaluation"
+{{/if}}
+3. Proceed directly to ROUTING DECISION POINT with complexity = {{COMPLEXITY_OVERRIDE}}
+{{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."
@@ -787,6 +832,7 @@ If workflow plan determined SKIP_COMPLEXITY_EVAL:
    If complexity found: "Previous evaluation classified this as [TRIVIAL/SIMPLE/COMPLEX]. Proceeding with [TRIVIAL/SIMPLE/COMPLEX] workflow."
    If not found: "No complexity classification found - defaulting to COMPLEX workflow."
 4. Proceed to ROUTING DECISION POINT with extracted complexity (no confirmation needed)
+{{/if}}
 
 **STEP 2 - Analysis Phase (COMPLEX workflow only):**
 
@@ -1252,7 +1298,7 @@ If workflow plan determined SKIP_IMPLEMENTATION:
 
 ## STEP 5 - Review Phase
 
-This section is about reviewing uncommitted code changes for quality, security, and compliance issues.
+This section is about reviewing code changes for quality, security, and compliance issues.
 
 {{#if SWARM_MODE}}
 **State transition**: Before running review, call `recap.set_loom_state('code_review')` with `worktreePath: "<your-worktree-path>"`.
@@ -1281,7 +1327,7 @@ This section is about reviewing uncommitted code changes for quality, security,
 - Execute: @agent-iloom-code-reviewer with prompt "Run code review."
 - **IMPORTANT**: Must run in foreground (not as background Task) to access MCP tools
 - **DO NOT** pass extra context (file lists, issue details, etc.) - the agent knows what to do
-- The reviewer will analyze uncommitted changes and report findings
+- The reviewer will analyze code changes and report findings
 
 **When issues are found:**
 - Ask the user: "Issues found. Do you want to proceed anyway, or address these first?"
@@ -1377,7 +1423,7 @@ This is NOT optional - if the reviewer requests Claude Local Review, it must be
 ---
 
 {{#if SWARM_MODE}}
-**MANDATORY CHECKPOINT: You MUST complete the code review before committing. After review, stage and commit all changes with `git add -A && git commit -m "fixes {{ISSUE_PREFIX}}<issue-number>"` (using your issue number from invocation arguments). Then set state to `done` and report results.**
+**MANDATORY CHECKPOINT: You MUST complete the code review before committing. After review, stage and commit all changes with `git add -A && git commit -m "feat(issue-<issue-number>): [descriptive summary]"` (using your issue number from invocation arguments). The commit message MUST describe what was implemented — do NOT use generic "fixes #NNN" messages. Then set state to `done` and report results.**
 {{else}}
 {{#if DRAFT_PR_MODE}}
 {{#if AUTO_COMMIT_PUSH}}

package/dist/prompts/pr-prompt.txt

@@ -46,10 +46,13 @@ Use these Recap MCP tools:
 - `recap.add_artifact` - After creating/updating comments, issues, or PRs, log them with type, primaryUrl, and description. Duplicates with the same primaryUrl will be replaced.
 
 **NEVER log:**
+- What phases you skipped
+- Complexity classifications
 - Status updates ("PR reviewed", "tests pass")
 - Anything about your own workflow process
+- Meta-knowledge about the agent orchestration layer (iloom, MCP servers, worktree mechanics, prompt rendering, etc.) unless the tooling was a direct cause of a problem under investigation
 
-**Self-check before adding:** If your entry is about what YOU did rather than what the USER needs to know - don't add it.
+**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.
 
 ---
 
@@ -113,7 +116,62 @@ When working with libraries, frameworks, or APIs that you need documentation for
 - Working with unfamiliar APIs
 - When you need current documentation that may have changed since your training data
 
-After reading both the PR and any referenced issue, wait for the user to provide guidance on what they would like you to work on next.
+---
+
+## Addressing PR Review Feedback
+
+After reading the PR, check for unresolved inline review comments using `mcp__issue_management__get_review_comments`. If there are unresolved review threads:
+
+{{#if ONE_SHOT_MODE}}
+Evaluate unresolved review comments using the same severity framework as the code review agent, then address automatically where appropriate:
+
+1. **Assess each comment** by severity and risk:
+   - **Must fix**: Bugs, security issues, correctness problems, clear code quality issues — address these automatically
+   - **Nice to have**: Style preferences, optional improvements — address if low-effort, skip if subjective
+   - **Complex/ambiguous**: Architectural concerns, large refactors, unclear intent, or requests that could lead to scope creep — do NOT attempt; note them in the summary
+2. **Summarize**: Post a PR comment summarizing all feedback, grouped by what was addressed vs deferred. For deferred items, explain why.
+3. **Address must-fix items and low-effort nice-to-haves**: For each:
+   a. Make the code change
+   b. Reply to the review thread explaining what was changed:
+      ```bash
+      gh api \
+        --method POST \
+        -H "Accept: application/vnd.github+json" \
+        /repos/{owner}/{repo}/pulls/{{PR_NUMBER}}/comments \
+        --input - <<'EOF'
+      {
+        "body": "Fixed — [brief explanation of the change made]",
+        "in_reply_to": REVIEW_COMMENT_ID
+      }
+      EOF
+      ```
+4. **Commit and push** changes after addressing comments
+5. Proceed to code review (see "Code Review" section below)
+{{else}}
+Present a summary of unresolved review feedback to the user:
+
+1. **Summarize feedback**: Group unresolved comments by file/topic. For each, show:
+   - File and line
+   - Reviewer's comment (abbreviated if long)
+   - Your assessment of what needs to change
+2. **Ask the user** how they'd like to proceed:
+   - "Address all comments" — work through them systematically
+   - "Address specific comments" — let the user pick which ones
+   - "Skip for now" — move on to other work
+3. **For each comment being addressed**:
+   a. Make the code change
+   b. Reply to the review thread explaining the fix (using `gh api` as shown above)
+4. After addressing comments, offer to run code review
+{{/if}}
+
+If there are no unresolved review comments:
+{{#if ONE_SHOT_MODE}}
+- Check the PR description and linked issue for remaining work. If there's work to do, proceed with it. Otherwise, run code review.
+{{else}}
+- Let the user know the PR has no unresolved feedback, and wait for guidance on what to work on next.
+{{/if}}
+
+---
 
 Remember to:
 - Follow the project's coding conventions and patterns
@@ -230,7 +288,7 @@ When workflow agents complete their tasks and produce artifacts, check if artifa
 
 ## Code Review
 
-Review uncommitted code changes for quality, security, and compliance issues.
+Review code changes for quality, security, and compliance issues. After reviewing, post findings as a proper GitHub PR review with inline comments.
 
 {{#if REVIEW_ENABLED}}
 **Auto-Run Mode**: After addressing PR feedback or making code changes, review automatically executes. No manual trigger needed.
@@ -244,6 +302,7 @@ Review uncommitted code changes for quality, security, and compliance issues.
    - Ask the user: "Critical issues found. Do you want to proceed anyway, or address these first?"
    - Wait for user response before continuing
 {{/if}}
+4. **Post findings as a GitHub PR review** (see "Posting Review Findings" below)
 {{/if}}
 
 {{#unless ONE_SHOT_MODE}}
@@ -251,7 +310,8 @@ Review uncommitted code changes for quality, security, and compliance issues.
 - Execute: @agent-iloom-code-reviewer with prompt "Run code review."
 - **IMPORTANT**: Must run in foreground (not as background Task) to access MCP tools
 - **DO NOT** pass extra context (file lists, issue details, etc.) - the agent knows what to do
-- The reviewer will analyze uncommitted changes and report findings
+- The reviewer will analyze code changes and report findings
+- After review completes, **post findings as a GitHub PR review** (see below)
 {{/unless}}
 
 **MANDATORY Claude Local Review**: If the reviewer returns "Instructions for Orchestrator: Claude Local Review", you MUST execute those instructions:
@@ -260,11 +320,101 @@ Review uncommitted code changes for quality, security, and compliance issues.
 3. Collect results from all agents
 4. Present unified report as specified
 5. If critical issues found, ask user before proceeding
+6. **Post findings as a GitHub PR review** (see below)
 
 This is NOT optional - if the reviewer requests Claude Local Review, it must be performed before continuing.
 
 ---
 
+## Posting Review Findings to GitHub
+
+After code review completes and produces findings, **you MUST post them as a GitHub PR review with inline comments**. This applies to all review paths (auto-run, manual, and Claude Local Review).
+
+### Step 1: Map Findings to Inline Comments
+
+The code reviewer produces findings in `[FILE:LINE] (Score: XX) Description` format. Map each finding to a review comment object:
+- `path`: The file path from the finding (relative to repo root)
+- `line`: The line number from the finding
+- `body`: The finding description, including severity, score, and recommendation
+
+**Only include findings for lines that are part of the PR diff.** Use `gh pr diff {{PR_NUMBER}}` to check which lines are changed. Skip findings on unchanged lines — GitHub rejects review comments on lines outside the diff.
+
+### Step 2: Submit Batched Review
+
+Submit all findings as a single review using `gh api` with `--input` and a heredoc:
+
+```bash
+gh api \
+  --method POST \
+  -H "Accept: application/vnd.github+json" \
+  /repos/{owner}/{repo}/pulls/{{PR_NUMBER}}/reviews \
+  --input - <<'EOF'
+{
+  "body": "## Code Review Summary\n\n[Summary of findings from unified report]",
+  "event": "EVENT_VALUE",
+  "comments": [
+    {
+      "path": "src/example.ts",
+      "line": 42,
+      "body": "**[Bug]** (Score: 95) Issue description\nRecommendation: ..."
+    },
+    {
+      "path": "src/other.ts",
+      "line": 15,
+      "body": "**[Warning]** (Score: 85) Issue description\nRecommendation: ..."
+    }
+  ]
+}
+EOF
+```
+
+If the review is clean (no inline findings), submit a summary-only review with an empty `comments` array.
+
+**Valid `event` values:** `APPROVE`, `REQUEST_CHANGES`, `COMMENT`
+
+### Step 3: Choose Verdict
+
+{{#if ONE_SHOT_MODE}}
+Choose the verdict automatically based on the code reviewer's severity categories:
+- **`REQUEST_CHANGES`**: If any Critical (95-100) or Warning (80-94) findings exist
+- **`COMMENT`**: If only Suggestions (below 80) exist
+- **`APPROVE`**: If no issues are found (clean review)
+
+Submit the review automatically without asking.
+{{else}}
+Present the review findings summary and the reviewer's recommended verdict to the user. Ask which verdict to submit:
+- **`APPROVE`** -- No issues found
+- **`REQUEST_CHANGES`** -- Critical or Warning-level findings that should be addressed
+- **`COMMENT`** -- Only suggestions, no blocking issues
+
+Wait for user confirmation before submitting the review.
+{{/if}}
+
+---
+
+### One-off Review Comments (Ad-hoc)
+
+For individual findings discovered during conversation (outside the batched review flow), post them as standalone review comments:
+
+```bash
+gh api \
+  --method POST \
+  -H "Accept: application/vnd.github+json" \
+  /repos/{owner}/{repo}/pulls/{{PR_NUMBER}}/comments \
+  --input - <<'EOF'
+{
+  "body": "Issue description and recommendation",
+  "commit_id": "HEAD_COMMIT_SHA",
+  "path": "src/example.ts",
+  "line": 42
+}
+EOF
+```
+
+Get the latest commit SHA with: `gh pr view {{PR_NUMBER}} --json headRefOid -q '.headRefOid'`
+
+---
+
 ## Wrapping Up Instructions
 
 When the user says they're done or ready to wrap up, provide these instructions:

package/dist/prompts/regular-prompt.txt

@@ -50,8 +50,9 @@ Use these Recap MCP tools:
 - Complexity classifications
 - Status updates ("implementation complete", "tests pass")
 - Anything about your own workflow process
+- Meta-knowledge about the agent orchestration layer (iloom, MCP servers, worktree mechanics, prompt rendering, etc.) unless the tooling was a direct cause of a problem under investigation
 
-**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.
+**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.
 
 ---
 
@@ -204,6 +205,10 @@ You are orchestrating a set of agents through a development process, with human
 {{/if}}{{/if}}
 3. Display enhanced specification to user
 4. WAIT for human confirmation of enhanced specification before proceeding
+{{#if COMPLEXITY_OVERRIDE}}
+5. Complexity has been overridden to {{COMPLEXITY_OVERRIDE}} via CLI flag. Skip complexity evaluation and proceed directly to routing.
+6. Route to appropriate workflow based on overridden complexity: {{COMPLEXITY_OVERRIDE}}
+{{else}}
 5. Run complexity evaluation using @agent-iloom-issue-complexity-evaluator (adapted for branch mode)
 {{#if ARTIFACT_REVIEW_ENABLED}}{{#if COMPLEXITY_REVIEW_ENABLED}}
 5a. Run artifact review on complexity evaluation output using @agent-iloom-artifact-reviewer
@@ -211,6 +216,7 @@ You are orchestrating a set of agents through a development process, with human
 6. Display complexity assessment to user
 7. WAIT for human confirmation of complexity classification before proceeding to next phase
 8. Route to appropriate workflow based on confirmed complexity (TRIVIAL, SIMPLE or COMPLEX)
+{{/if}}
 9. If TRIVIAL: Skip to implementation directly (no analysis or planning needed)
 10. If SIMPLE: Run combined analysis and planning using @agent-iloom-issue-analyze-and-plan
 {{#if ARTIFACT_REVIEW_ENABLED}}{{#if ANALYZE_AND_PLAN_REVIEW_ENABLED}}
@@ -329,7 +335,11 @@ You are orchestrating a set of agents through a development process, with human
 4. Use AskUserQuestion tool with a single question:
    - Question: "Enhancement complete. Does this specification accurately capture your requirements?"
    - Options:
+{{#if COMPLEXITY_OVERRIDE}}
+     - "Yes, proceed" (default)
+{{else}}
      - "Yes, proceed to complexity evaluation" (default)
+{{/if}}
      - "No, I have corrections or additions"
      - "Exit workflow"
    - multiSelect: false
@@ -342,6 +352,12 @@ You are orchestrating a set of agents through a development process, with human
 
 **STEP 2 - Complexity Evaluation Phase:**
 
+{{#if COMPLEXITY_OVERRIDE}}
+The complexity has been overridden to **{{COMPLEXITY_OVERRIDE}}** via CLI flag. Skip complexity evaluation entirely.
+1. Set confirmed complexity to {{COMPLEXITY_OVERRIDE}}
+2. Display to user: "Complexity overridden to {{COMPLEXITY_OVERRIDE}} via CLI flag, skipping complexity evaluation"
+3. Proceed directly to ROUTING DECISION POINT with complexity = {{COMPLEXITY_OVERRIDE}}
+{{else}}
 1. Execute: @agent-iloom-issue-complexity-evaluator with the following context:
    - **IMPORTANT**: This is branch mode - there is NO GitHub issue to fetch
    - Provide the enhanced specification directly to the agent: "This is branch mode - analyze complexity based on the following enhanced specification instead of fetching from GitHub: [ENHANCED_SPECIFICATION]"
@@ -424,6 +440,7 @@ You are orchestrating a set of agents through a development process, with human
    - If user chooses "Exit workflow": End workflow gracefully
 6. Mark todos #7 and #8 as completed
 7. Proceed to ROUTING DECISION POINT with confirmed complexity
+{{/if}}
 
 ---
 
@@ -713,7 +730,7 @@ Execute combined analyze-and-plan agent:
 
 ## STEP 5.5 - Review Phase
 
-This section is about reviewing uncommitted code changes for quality, security, and compliance issues.
+This section is about reviewing code changes for quality, security, and compliance issues.
 
 {{#if REVIEW_ENABLED}}
 **Auto-Run Mode**: Review automatically executes after implementation completes. No manual trigger needed.
@@ -734,7 +751,7 @@ This section is about reviewing uncommitted code changes for quality, security,
 - Execute: @agent-iloom-code-reviewer with prompt "Run code review."
 - **IMPORTANT**: Must run in foreground (not as background Task) to access MCP tools
 - **DO NOT** pass extra context (file lists, issue details, etc.) - the agent knows what to do
-- The reviewer will analyze uncommitted changes and report findings
+- The reviewer will analyze code changes and report findings
 
 **When issues are found:**
 - Ask the user: "Issues found. Do you want to proceed anyway, or address these first?"

package/dist/prompts/swarm-orchestrator-prompt.txt

@@ -87,25 +87,44 @@ This is a JSON object representing the dependency DAG. Keys are issue numbers (a
 8. Spawn agents for newly unblocked child issues (repeat as needed)
 9. Handle any failures (mark failed, continue with others)
 10. When all children are done or failed, finalize and clean up
+{{#if POST_SWARM_REVIEW}}
+11. Run post-swarm code review and auto-fix any findings
+12. Create final commit with Fixes trailer for epic issue
+13. Push epic branch to remote (final commit)
+14. Print final summary
+{{else}}
 11. Create final commit with Fixes trailer for epic issue
 12. Push epic branch to remote (final commit)
 13. Print final summary
+{{/if}}
 {{else}}
 6. Clean up completed child worktrees (if not --skip-cleanup)
 7. Spawn agents for newly unblocked child issues (repeat as needed)
 8. Handle any failures (mark failed, continue with others)
 9. When all children are done or failed, finalize and clean up
+{{#if POST_SWARM_REVIEW}}
+10. Run post-swarm code review and auto-fix any findings
+11. Create final commit with Fixes trailer for epic issue
+12. Print final summary
+{{else}}
 10. Create final commit with Fixes trailer for epic issue
 11. Print final summary
 {{/if}}
+{{/if}}
 {{else}}
 6. Clean up completed child worktrees (if not --skip-cleanup)
 7. Spawn agents for newly unblocked child issues (repeat as needed)
 8. Handle any failures (mark failed, continue with others)
 9. When all children are done or failed, finalize and clean up
+{{#if POST_SWARM_REVIEW}}
+10. Run post-swarm code review and auto-fix any findings
+11. Create final commit with Fixes trailer for epic issue
+12. Print final summary
+{{else}}
 10. Create final commit with Fixes trailer for epic issue
 11. Print final summary
 {{/if}}
+{{/if}}
 
 ---
 
@@ -378,26 +397,101 @@ Send `shutdown_request` to all teammates that are still active:
 
 Use `TeamDelete` to clean up the team `swarm-epic-{{EPIC_ISSUE_NUMBER}}`.
 
-### Step 5.3: Final Commit on Epic Branch
+{{#if POST_SWARM_REVIEW}}
+### Step 5.2.5: Post-Swarm Code Review and Auto-Fix
 
-If at least one child succeeded, **delegate the final commit to a subagent.**
+If at least one child succeeded, run a full code review of the integrated epic branch and auto-fix any reported findings.
+
+First, check whether any children succeeded (this is a lightweight read, OK to do directly):
+```bash
+cd {{EPIC_WORKTREE_PATH}}
+git log --oneline -5
+```
+- If no children succeeded (only placeholder or temporary commits exist), skip this step entirely.
+
+#### Step 5.2.5a: Run Code Review
+
+**Delegate this to a subagent.** Spawn a Task subagent to invoke the code reviewer:
 
-Spawn a subagent using the `Task` tool:
 - `subagent_type`: `"general-purpose"`
 - Prompt:
 
 ```
-Create the final commit on the epic branch that closes the epic issue.
+Run a full code review of the integrated epic branch.
+
+## Instructions
+
+You are in the epic worktree at `{{EPIC_WORKTREE_PATH}}`. All child agents' work has been merged into this branch.
+
+1. Execute: @agent-iloom-code-reviewer with prompt "Run code review."
+2. Wait for the review to complete.
+3. Report back with the full review results, including all findings with their confidence scores, file locations, and recommendations.
+   - If no issues found, report "No issues found."
+   - If issues found, include the full structured report (Critical issues 95-100, Warnings 80-94).
+```
+
+**Handle the subagent result:**
+- If the subagent reports **"No issues found"** or the review found no findings scoring 80+: skip to Step 5.3.
+- If the subagent reports findings: proceed to Step 5.2.5b.
+- If the subagent fails (timeout, crash, error): log the failure, skip to Step 5.3. The review is non-blocking -- a failed review must not prevent finalization.
+
+#### Step 5.2.5b: Auto-Fix Reported Issues
+
+If the review found issues (confidence 80+), spawn a fix agent to address them.
+
+**Delegate this to a subagent:**
+
+- `subagent_type`: `"general-purpose"`
+- Prompt:
 
+````
+Fix the following code review findings in the epic worktree at `{{EPIC_WORKTREE_PATH}}`.
+
+## Review Findings
+
+<paste the full review findings from Step 5.2.5a here>
+
+## Instructions
+
+1. Read each finding carefully (file, line, issue, recommendation)
+2. Implement the recommended fix for each finding
+3. After fixing all issues, stage and commit with:
+   ```bash
+   cd {{EPIC_WORKTREE_PATH}}
+   git add -A
+   git commit -m "fix(review): address post-swarm code review findings"
+   ```
+4. Report back with a summary of what was fixed.
+
+IMPORTANT: Only fix the specific issues identified in the review findings. Do NOT refactor, optimize, or make additional changes beyond what the review identified.
+````
+
+**Handle the subagent result:**
+- If the fix agent succeeds: log "Post-swarm review: N findings addressed, fix committed."
+- If the fix agent fails: log the failure and continue. Auto-fix failure is non-blocking.
+
+**Single pass only.** Do NOT re-review after fixing. This prevents infinite review-fix loops.
+
+{{/if}}
+### Step 5.3: Final Commit on Epic Branch
+
+If at least one child succeeded, create the final "Fixes" commit — but only if it doesn't already exist (idempotency).
+
+First, check whether the final commit has already been created (this is a lightweight read, OK to do directly):
 ```bash
 cd {{EPIC_WORKTREE_PATH}}
-git add -A
-git commit --allow-empty -m "Fixes {{ISSUE_PREFIX}}{{EPIC_ISSUE_NUMBER}}"
+git log --oneline --grep="feat(epic-{{EPIC_ISSUE_NUMBER}}):" -1
 ```
+- If a matching commit is found, skip this step — the finalization commit already exists.
 
-NOTE: --allow-empty is used because the child branches have already been merged — there may be no additional staged changes, but we still need the commit message to trigger issue closure.
+If no final commit exists, create it directly (no need to delegate — this is a trivial `--allow-empty` commit with no conflict risk). The commit message MUST have a descriptive first line summarizing what the epic accomplished, with the `Fixes` trailer in the body:
+
+```bash
+cd {{EPIC_WORKTREE_PATH}}
+git add -A
+git commit --allow-empty -m "feat(epic-{{EPIC_ISSUE_NUMBER}}): [summary of what was accomplished across child issues]
 
-Report back with status: "success" or "failed" and the commit hash if successful.
+Fixes {{ISSUE_PREFIX}}{{EPIC_ISSUE_NUMBER}}"
 ```
 
 {{#if DRAFT_PR_MODE}}
@@ -469,10 +563,22 @@ The epic worktree is ready for review at: `{{EPIC_WORKTREE_PATH}}`
 
 {{#if DRAFT_PR_MODE}}
 {{#if AUTO_COMMIT_PUSH}}
+{{#if POST_SWARM_REVIEW}}
+Mark todo #10, #11, #12, #13, and #14 as completed.
+{{else}}
 Mark todo #10, #11, #12, and #13 as completed.
+{{/if}}
+{{else}}
+{{#if POST_SWARM_REVIEW}}
+Mark todo #9, #10, #11, and #12 as completed.
 {{else}}
 Mark todo #9, #10, and #11 as completed.
 {{/if}}
+{{/if}}
+{{else}}
+{{#if POST_SWARM_REVIEW}}
+Mark todo #9, #10, #11, and #12 as completed.
 {{else}}
 Mark todo #9, #10, and #11 as completed.
 {{/if}}
+{{/if}}