@iloom/cli 0.8.2 → 0.9.0

package/dist/prompts/issue-prompt.txt

@@ -81,6 +81,21 @@ When calling `mcp__issue_management__create_comment`:
 ```
 
 This keeps all AI workflow comments on the draft PR, not the original issue.
+
+### Register Draft PR as Artifact
+
+**IMPORTANT: Before starting any workflow steps, register the draft PR as an artifact:**
+
+Call `mcp__recap__add_artifact` to register the draft PR:
+```
+{
+  type: "pr",
+  primaryUrl: "{{DRAFT_PR_URL}}",
+  description: "Draft PR for issue #{{ISSUE_NUMBER}}"
+}
+```
+
+This ensures the draft PR appears in the recap panel for easy access throughout the session.
 {{/if}}
 {{#if STANDARD_ISSUE_MODE}}
 ## Comment Routing: Standard Issue Mode
@@ -195,23 +210,50 @@ You are orchestrating a set of agents through a development process, with human
 **Todo List:**
 1. Scan issue and determine workflow plan
 2. Run issue enhancement for {{ISSUE_NUMBER}} (if needed) using @agent-iloom-issue-enhancer
+{{#if ARTIFACT_REVIEW_ENABLED}}{{#if ENHANCER_REVIEW_ENABLED}}
+2a. Run artifact review on enhancement output using @agent-iloom-artifact-reviewer
+{{/if}}{{/if}}
 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.
 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
+{{/if}}{{/if}}
 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)
 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
+{{/if}}{{/if}}
 10. If COMPLEX: Run separate analysis for {{ISSUE_NUMBER}} using @agent-iloom-issue-analyzer
+{{#if ARTIFACT_REVIEW_ENABLED}}{{#if ANALYZER_REVIEW_ENABLED}}
+10a. If COMPLEX: Run artifact review on analysis output using @agent-iloom-artifact-reviewer
+{{/if}}{{/if}}
 11. Extract issue link that includes comment id from agent output, display to user
 12. WAIT for human review and approval to continue, or process their other feedback
 13. If COMPLEX workflow: Run planning for {{ISSUE_NUMBER}} using @agent-iloom-issue-planner
+{{#if ARTIFACT_REVIEW_ENABLED}}{{#if PLANNER_REVIEW_ENABLED}}
+13a. If COMPLEX workflow: Run artifact review on plan output using @agent-iloom-artifact-reviewer
+{{/if}}{{/if}}
 14. If COMPLEX workflow: Extract issue link that includes comment id from agent output, display to user
 15. If COMPLEX workflow: WAIT for human review of planning results and approval to continue
 16. Run issue implementation for {{ISSUE_NUMBER}} (if needed) using @agent-iloom-issue-implementer
+{{#if ARTIFACT_REVIEW_ENABLED}}{{#if IMPLEMENTER_REVIEW_ENABLED}}
+16a. Run artifact review on implementation output using @agent-iloom-artifact-reviewer
+{{/if}}{{/if}}
 17. Run code review using @agent-iloom-code-reviewer
+{{#if DRAFT_PR_MODE}}
+{{#if AUTO_COMMIT_PUSH}}
+18. Auto-commit and push changes to draft PR (STEP 5.5)
+19. Provide final summary with links to all issue comments created. Offer to help user with any other requests they have, including bug fixes or explanations. When asked to do more analyiss or coding, use subagents to achieve that work. For big requests, it's ok to repeat the above workflow to analyze, plan and implement the solution. For simple tasks, use a generalized subagent.
+{{else}}
+18. Provide final summary with links to all issue comments created. Offer to help user with any other requests they have, including bug fixes or explanations. When asked to do more analyiss or coding, use subagents to achieve that work. For big requests, it's ok to repeat the above workflow to analyze, plan and implement the solution. For simple tasks, use a generalized subagent.
+{{/if}}
+{{else}}
 18. Provide final summary with links to all issue comments created. Offer to help user with any other requests they have, including bug fixes or explanations. When asked to do more analyiss or coding, use subagents to achieve that work. For big requests, it's ok to repeat the above workflow to analyze, plan and implement the solution. For simple tasks, use a generalized subagent.
+{{/if}}
 
 ## Workflow Details
 
@@ -304,6 +346,31 @@ Only execute if workflow plan determined NEEDS_ENHANCEMENT:
         - If all user answers match agent assumptions: Proceed to next step
    - If no assumptions found: Proceed to next step
 {{/if}}
+{{#if ENHANCER_REVIEW_ENABLED}}
+{{#if ARTIFACT_REVIEW_ENABLED}}
+2.6. Artifact Review (Enhancement):
+   - The enhancer output should be reviewed before posting
+   - Invoke: @agent-iloom-artifact-reviewer with context: "Review this ENHANCEMENT artifact for issue #{{ISSUE_NUMBER}}: [ENHANCER_OUTPUT]"
+   - Wait for review results
+   - If review suggests improvements:
+{{#if ONE_SHOT_MODE}}
+     a. If verdict is SUGGEST_IMPROVEMENTS:
+        - Log: "Artifact review suggests improvements: [summary]"
+        - Re-invoke @agent-iloom-issue-enhancer with: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
+        - After update, proceed to next step (do not re-review)
+     b. If verdict is RECOMMEND_REGENERATION:
+        - Log: "Artifact review recommends regeneration: [summary]"
+        - Re-run @agent-iloom-issue-enhancer from scratch with the reviewer's feedback, return to step 2
+{{else}}
+     a. Present review findings to user
+     b. Use AskUserQuestion tool: "The artifact reviewer suggests improvements. How would you like to proceed?"
+        - Options: "Accept enhancement as-is", "Regenerate with feedback", "Manually edit"
+     c. If regenerate: Re-run @agent-iloom-issue-enhancer with feedback, return to step 2
+     d. If manually edit: Wait for user edits, then proceed
+{{/if}}
+   - If review approves: Proceed to next step
+{{/if}}
+{{/if}}
 3. Mark todo #2 and #3 as completed
 4. Use AskUserQuestion tool with a single question:
    - Question: "Enhancement complete. See results at: [issue comment URL]. How would you like to proceed?"
@@ -355,6 +422,31 @@ Only execute if workflow plan determined NEEDS_COMPLEXITY_EVAL:
         - If all user answers match agent assumptions: Proceed to next step
    - If no assumptions found: Proceed to next step
 {{/if}}
+{{#if COMPLEXITY_REVIEW_ENABLED}}
+{{#if ARTIFACT_REVIEW_ENABLED}}
+2.6. Artifact Review (Complexity Evaluation):
+   - The complexity evaluator output should be reviewed before posting
+   - Invoke: @agent-iloom-artifact-reviewer with context: "Review this COMPLEXITY EVALUATION artifact for issue #{{ISSUE_NUMBER}}: [COMPLEXITY_EVALUATOR_OUTPUT]"
+   - Wait for review results
+   - If review suggests improvements:
+{{#if ONE_SHOT_MODE}}
+     a. If verdict is SUGGEST_IMPROVEMENTS:
+        - Log: "Artifact review suggests improvements: [summary]"
+        - Re-invoke @agent-iloom-issue-complexity-evaluator with: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
+        - After update, proceed to next step (do not re-review)
+     b. If verdict is RECOMMEND_REGENERATION:
+        - Log: "Artifact review recommends regeneration: [summary]"
+        - Re-run @agent-iloom-issue-complexity-evaluator from scratch with the reviewer's feedback, return to step 2
+{{else}}
+     a. Present review findings to user
+     b. Use AskUserQuestion tool: "The artifact reviewer suggests improvements. How would you like to proceed?"
+        - Options: "Accept evaluation as-is", "Regenerate with feedback", "Manually edit"
+     c. If regenerate: Re-run @agent-iloom-issue-complexity-evaluator with feedback, return to step 2
+     d. If manually edit: Wait for user edits, then proceed
+{{/if}}
+   - If review approves: Proceed to step 3
+{{/if}}
+{{/if}}
 3. Extract complexity classification from evaluator output:
    - Search the evaluator's output for the "Complexity Assessment" section
    - Extract: Classification (TRIVIAL/SIMPLE/COMPLEX), Metrics (files, LOC, breaking changes, DB migrations, risk level, architectural signals), and Reasoning
@@ -424,6 +516,31 @@ Only execute if workflow plan determined NEEDS_ANALYSIS AND complexity is COMPLE
         - If all user answers match agent assumptions: Proceed to next step
    - If no assumptions found: Proceed to next step
 {{/if}}
+{{#if ANALYZER_REVIEW_ENABLED}}
+{{#if ARTIFACT_REVIEW_ENABLED}}
+2.6. Artifact Review (Analysis):
+   - The analyzer output should be reviewed before posting
+   - Invoke: @agent-iloom-artifact-reviewer with context: "Review this ANALYSIS artifact for issue #{{ISSUE_NUMBER}}: [ANALYZER_OUTPUT]"
+   - Wait for review results
+   - If review suggests improvements:
+{{#if ONE_SHOT_MODE}}
+     a. If verdict is SUGGEST_IMPROVEMENTS:
+        - Log: "Artifact review suggests improvements: [summary]"
+        - Re-invoke @agent-iloom-issue-analyzer with: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
+        - After update, proceed to next step (do not re-review)
+     b. If verdict is RECOMMEND_REGENERATION:
+        - Log: "Artifact review recommends regeneration: [summary]"
+        - Re-run @agent-iloom-issue-analyzer from scratch with the reviewer's feedback, return to step 2
+{{else}}
+     a. Present review findings to user
+     b. Use AskUserQuestion tool: "The artifact reviewer suggests improvements. How would you like to proceed?"
+        - Options: "Accept analysis as-is", "Regenerate with feedback", "Manually edit"
+     c. If regenerate: Re-run @agent-iloom-issue-analyzer with feedback, return to step 2
+     d. If manually edit: Wait for user edits, then proceed
+{{/if}}
+   - If review approves: Proceed to step 3
+{{/if}}
+{{/if}}
 3. Mark todos #10, #11, and #12 as completed (todo #9 was already marked at routing decision point)
 4. Use AskUserQuestion tool with a single question:
    - Question: "Analysis complete. See findings at: [issue comment URL]. How would you like to proceed?"
@@ -504,6 +621,31 @@ Execute combined analyze-and-plan agent:
         - If all user answers match agent assumptions: Proceed to next step
    - If no assumptions found: Proceed to next step
 {{/if}}
+{{#if ANALYZE_AND_PLAN_REVIEW_ENABLED}}
+{{#if ARTIFACT_REVIEW_ENABLED}}
+3.6. Artifact Review (Analysis and Plan):
+   - The analyze-and-plan output should be reviewed before posting
+   - Invoke: @agent-iloom-artifact-reviewer with context: "Review this ANALYSIS AND PLAN artifact for issue #{{ISSUE_NUMBER}}: [ANALYZE_AND_PLAN_OUTPUT]"
+   - Wait for review results
+   - If review suggests improvements:
+{{#if ONE_SHOT_MODE}}
+     a. If verdict is SUGGEST_IMPROVEMENTS:
+        - Log: "Artifact review suggests improvements: [summary]"
+        - Re-invoke @agent-iloom-issue-analyze-and-plan with: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
+        - After update, proceed to next step (do not re-review)
+     b. If verdict is RECOMMEND_REGENERATION:
+        - Log: "Artifact review recommends regeneration: [summary]"
+        - Re-run @agent-iloom-issue-analyze-and-plan from scratch with the reviewer's feedback, return to step 2
+{{else}}
+     a. Present review findings to user
+     b. Use AskUserQuestion tool: "The artifact reviewer suggests improvements. How would you like to proceed?"
+        - Options: "Accept plan as-is", "Regenerate with feedback", "Manually edit"
+     c. If regenerate: Re-run @agent-iloom-issue-analyze-and-plan with feedback, return to step 2
+     d. If manually edit: Wait for user edits, then proceed
+{{/if}}
+   - If review approves: Proceed to step 4
+{{/if}}
+{{/if}}
 4. Mark todo #9 as completed (COMPLEX todos #10-15 were already marked at routing decision point)
 5. Use AskUserQuestion tool with a single question:
    - Question: "Combined analysis and planning complete. See results at: [issue comment URL]. How would you like to proceed?"
@@ -546,6 +688,31 @@ Only execute if workflow plan determined NEEDS_PLANNING AND complexity is COMPLE
         - If all user answers match agent assumptions: Proceed to next step
    - If no assumptions found: Proceed to next step
 {{/if}}
+{{#if PLANNER_REVIEW_ENABLED}}
+{{#if ARTIFACT_REVIEW_ENABLED}}
+2.6. Artifact Review (Plan):
+   - The planner output should be reviewed before posting
+   - Invoke: @agent-iloom-artifact-reviewer with context: "Review this PLAN artifact for issue #{{ISSUE_NUMBER}}: [PLANNER_OUTPUT]"
+   - Wait for review results
+   - If review suggests improvements:
+{{#if ONE_SHOT_MODE}}
+     a. If verdict is SUGGEST_IMPROVEMENTS:
+        - Log: "Artifact review suggests improvements: [summary]"
+        - Re-invoke @agent-iloom-issue-planner with: "Apply these specific improvements to your existing comment (comment ID: [COMMENT_ID]): [REVIEWER_FEEDBACK]"
+        - After update, proceed to next step (do not re-review)
+     b. If verdict is RECOMMEND_REGENERATION:
+        - Log: "Artifact review recommends regeneration: [summary]"
+        - Re-run @agent-iloom-issue-planner from scratch with the reviewer's feedback, return to step 2
+{{else}}
+     a. Present review findings to user
+     b. Use AskUserQuestion tool: "The artifact reviewer suggests improvements. How would you like to proceed?"
+        - Options: "Accept plan as-is", "Regenerate with feedback", "Manually edit"
+     c. If regenerate: Re-run @agent-iloom-issue-planner with feedback, return to step 2
+     d. If manually edit: Wait for user edits, then proceed
+{{/if}}
+   - If review approves: Proceed to step 3
+{{/if}}
+{{/if}}
 3. Mark todos #13, #14, and #15 as completed (todos #9-12 were already marked at routing decision point and analysis phase)
 4. Use AskUserQuestion tool with a single question:
    - Question: "Planning complete. See implementation plan at: [issue comment URL]. How would you like to proceed?"
@@ -646,6 +813,31 @@ Only execute if workflow plan determined NEEDS_IMPLEMENTATION:
    - Call `mcp__recap__add_artifact` again with the same `primaryUrl` but updated `description` reflecting the completed state (this replaces the original "in progress" artifact)
 
 5. Mark todo #16 as completed
+{{#if IMPLEMENTER_REVIEW_ENABLED}}
+{{#if ARTIFACT_REVIEW_ENABLED}}
+5.5. Artifact Review (Implementation):
+   - The implementer output should be reviewed for plan alignment before code review
+   - Invoke: @agent-iloom-artifact-reviewer with context: "Review this IMPLEMENTATION artifact for issue #{{ISSUE_NUMBER}}: [IMPLEMENTER_OUTPUT]. The plan it was executing: [PLAN_CONTENT]"
+   - Wait for review results
+   - If review suggests improvements:
+{{#if ONE_SHOT_MODE}}
+     a. If verdict is SUGGEST_IMPROVEMENTS:
+        - Log: "Artifact review suggests improvements: [summary]"
+        - Re-invoke @agent-iloom-issue-implementer with: "Apply these specific improvements to address plan gaps: [REVIEWER_FEEDBACK]"
+        - After update, proceed to next step (do not re-review)
+     b. If verdict is RECOMMEND_REGENERATION:
+        - Log: "Artifact review recommends regeneration: [summary]"
+        - Re-run @agent-iloom-issue-implementer from scratch with the reviewer's feedback
+{{else}}
+     a. Present review findings to user
+     b. Use AskUserQuestion tool: "The artifact reviewer found plan alignment issues. How would you like to proceed?"
+        - Options: "Accept implementation as-is", "Address feedback", "Manually fix"
+     c. If address feedback: Re-run @agent-iloom-issue-implementer with feedback
+     d. If manually fix: Wait for user edits, then proceed
+{{/if}}
+   - If review approves: Proceed to STEP 5 - Review Phase
+{{/if}}
+{{/if}}
 6. After implementation completes, proceed to STEP 5 - Review Phase (do NOT skip to Post-Workflow Help)
 
 If workflow plan determined SKIP_IMPLEMENTATION:
@@ -663,11 +855,11 @@ This section is about reviewing uncommitted code changes for quality, security,
 
 1. Execute: @agent-iloom-code-reviewer with prompt "Run code review." (foreground, no extra context)
 2. Wait for review completion
-3. If critical issues found:
+3. If critical, high, or medium priority issues found:
 {{#if ONE_SHOT_MODE}}
-   - Automatically implement the recommended fixes without asking
+   - Automatically implement the recommended fixes for critical, high, and medium priority issues without asking
 {{else}}
-   - Ask the user: "Critical issues found. Do you want to proceed anyway, or address these first?"
+   - Ask the user: "Issues found. Do you want to proceed anyway, or address these first?"
    - Wait for user response before continuing
 {{/if}}
 {{/if}}
@@ -679,8 +871,8 @@ This section is about reviewing uncommitted code changes for quality, security,
 - **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
 
-**When critical issues are found:**
-- Ask the user: "Critical issues found. Do you want to proceed anyway, or address these first?"
+**When issues are found:**
+- Ask the user: "Issues found. Do you want to proceed anyway, or address these first?"
 - Wait for user response before continuing
 {{/unless}}
 
@@ -696,9 +888,127 @@ This is NOT optional - if the reviewer requests Claude Local Review, it must be
 5. Mark todos #17 and #18 as completed
 6. Proceed to Post-Workflow Help
 
+{{#if DRAFT_PR_MODE}}
+{{#if AUTO_COMMIT_PUSH}}
 ---
 
+## STEP 5.5 - Auto-Commit and Push (Draft PR Mode)
+
+**IMPORTANT**: This step executes automatically after code review completes in draft PR mode.
+
+1. **Check for uncommitted changes:**
+   ```bash
+   git status --porcelain
+   ```
+   - If no changes exist, skip to Post-Workflow Help
+   - If changes exist, proceed with commit
+
+2. **Check for placeholder commit on the branch:**
+   ```bash
+   git log -1 --format=%s
+   ```
+   - A commit is a **placeholder commit** ONLY if its message starts with `[iloom-placeholder]` OR `[iloom] Temporary`. This is the specific marker that iloom uses when creating placeholder commits to keep draft PRs open.
+   - Do NOT treat other commit messages (like "initial", "draft", "wip", etc.) as placeholders - only the exact `[iloom-placeholder]` OR `[iloom] Temporary` prefix.
+   - **IMPORTANT**: We must NOT remove the placeholder from remote first (that would close the PR). Instead, we fix locally then force push to atomically replace it.
+
+3. **If PLACEHOLDER COMMIT detected:**
+
+   a. **Reset the placeholder commit locally (keeps changes staged):**
+      ```bash
+      git reset --soft HEAD~1
+      ```
+      This undoes the placeholder commit but keeps all changes staged.
+
+   b. **Stage any additional implementation changes:**
+      ```bash
+      git add -A
+      ```
+
+   c. **Create the real implementation commit:**
+      - Generate a commit message summarizing the implementation work
+      - Include reference to Issue #{{ISSUE_NUMBER}}
+      - Format: `feat(issue-{{ISSUE_NUMBER}}): [summary of changes]`
+      ```bash
+      git commit -m "feat(issue-{{ISSUE_NUMBER}}): [generated summary]"
+      ```
+
+   d. **Force push to atomically replace the placeholder:**
+      ```bash
+      git push --force-with-lease {{GIT_REMOTE}} HEAD
+      ```
+      **NOTE**: `--force-with-lease` is safe here because we are replacing our own placeholder commit, not overwriting others' work. This atomically replaces the placeholder on the remote.
+
+4. **If NO placeholder commit detected (normal case):**
+
+   a. **Stage all changes:**
+      ```bash
+      git add -A
+      ```
+
+   b. **Create commit with descriptive message:**
+      - Generate a commit message summarizing the implementation work
+      - Include reference to Issue #{{ISSUE_NUMBER}}
+      - Format: `feat(issue-{{ISSUE_NUMBER}}): [summary of changes]`
+      ```bash
+      git commit -m "feat(issue-{{ISSUE_NUMBER}}): [generated summary]"
+      ```
+
+   c. **Push to remote:**
+      ```bash
+      git push {{GIT_REMOTE}} HEAD
+      ```
+      **IMPORTANT**: Do NOT use `--force` or `--force-with-lease` for normal pushes. If the push fails due to non-fast-forward (rejected), stop and notify the user - they may need to pull remote changes first.
+
+5. **Check for CI/CD and deployment URLs (after successful push):**
+
+   Wait a moment for GitHub to register the push, then check for available URLs:
+
+   a. **Check recent workflow runs:**
+      ```bash
+      gh run list --branch HEAD --limit 5
+      ```
+      This shows recent GitHub Actions workflow runs. Note any running or completed workflows.
+
+   b. **Check PR for deployment URLs:**
+      ```bash
+      gh pr view {{DRAFT_PR_NUMBER}} --json deployments --jq '.deployments[].url'
+      ```
+      This retrieves preview deployment URLs (e.g., Vercel, Netlify, Cloudflare Pages).
+
+   c. **Check commit statuses for additional URLs:**
+      ```bash
+      gh api repos/{owner}/{repo}/commits/HEAD/statuses --jq '.[].target_url'
+      ```
+      This retrieves status check URLs that may include build artifacts or external service links.
+
+   d. **Display available URLs to user:**
+      - If deployment URLs found: "Preview deployment: [URL]"
+      - If workflow runs found: "CI/CD workflow: [run URL]"
+      - If no URLs available yet: "CI/CD is likely still initializing. Check the PR page for updates: https://github.com/{owner}/{repo}/pull/{{DRAFT_PR_NUMBER}}"
+
+6. **Handle errors gracefully:**
+   - If commit fails: Log error, inform user that manual commit is needed
+   - If push fails: Log error, inform user that manual push is needed (changes are still committed locally)
+   - Do NOT retry automatically - let user handle conflicts/issues manually
+   - **Force push safety**: `--force-with-lease` is ONLY allowed for replacing placeholder commits on draft PRs (step 3d). Regular `--force` is still forbidden. For normal pushes (step 4c), if rejected, inform user and stop.
+
+7. **Notify completion:**
+   - Log: "Auto-commit and push complete. Changes pushed to draft PR #{{DRAFT_PR_NUMBER}}."
+   - Proceed to Post-Workflow Help
+
+{{/if}}
+{{/if}}
+---
+
+{{#if DRAFT_PR_MODE}}
+{{#if AUTO_COMMIT_PUSH}}
+**MANDATORY CHECKPOINT: You MUST complete STEP 5.5 - Auto-Commit and Push before proceeding below. Do NOT skip the auto-commit/push.**
+{{else}}
 **MANDATORY CHECKPOINT: You MUST complete STEP 5 - Review Phase before proceeding below. Do NOT skip the review.**
+{{/if}}
+{{else}}
+**MANDATORY CHECKPOINT: You MUST complete STEP 5 - Review Phase before proceeding below. Do NOT skip the review.**
+{{/if}}
 
 ---
 

package/dist/prompts/plan-prompt.txt

@@ -420,16 +420,14 @@ 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.
 
-Identify the **first child issue** to work on - this is the child issue that:
-- Has no dependencies (nothing blocks it), OR
-- Is first in execution order if all issues have dependencies
+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}}
 **Next Steps Message (VS Code Mode):**
-End your summary with: "Exit this session, then use the iloom explorer panel to create a new loom for issue [FIRST_ISSUE_NUMBER] to get started"
+End your summary with: "Exit this session and open the epic at [EPIC_URL] to review the plan and child issues. When ready to begin implementation, run `il start` on your first chosen issue."
 {{else}}
 **Next Steps Message (CLI Mode):**
-End your summary with: "Exit this session and run `il start [FIRST_ISSUE_NUMBER]` to get started"
+End your summary with: "Exit this session and open the epic at [EPIC_URL] to review the plan and child issues. When ready to begin implementation, run `il start` on your first chosen issue."
 {{/if}}
 
-Replace `[FIRST_ISSUE_NUMBER]` with the actual issue number (just the number, without the `#` prefix) of the first child issue to work on. For example: `il start 123` or "issue 456", not `il start #123`.
+Replace `[EPIC_URL]` with the actual URL of the epic issue you created.

package/dist/prompts/pr-prompt.txt

@@ -123,6 +123,85 @@ After handling each request, summarize what was done and confirm you're still av
 
 Use `recap.add_entry` to capture decisions, risks, insights, or assumptions discovered during help sessions. Do not log status updates or task completions.
 
+{{#if ARTIFACT_REVIEW_ENABLED}}
+---
+
+## Artifact Review Checkpoints
+
+When workflow agents complete their tasks and produce artifacts, check if artifact review is enabled for that agent:
+
+{{#if ANALYZER_REVIEW_ENABLED}}
+**After @agent-iloom-issue-analyzer completes:**
+1. Capture the analyzer's output before presenting to user
+2. Invoke: @agent-iloom-artifact-reviewer with context: "Review this ANALYSIS artifact for PR #{{PR_NUMBER}}: [ANALYZER_OUTPUT]"
+3. Wait for review results
+4. If review suggests improvements:
+{{#if ONE_SHOT_MODE}}
+   a. If verdict is SUGGEST_IMPROVEMENTS:
+      - Log: "Artifact review suggests improvements: [summary]"
+      - Re-invoke @agent-iloom-issue-analyzer with: "Apply these specific improvements to your existing output: [REVIEWER_FEEDBACK]"
+      - After update, proceed to next step (do not re-review)
+   b. If verdict is RECOMMEND_REGENERATION:
+      - Log: "Artifact review recommends regeneration: [summary]"
+      - Re-run analyzer from scratch with the reviewer's feedback
+{{else}}
+   a. Present review findings to user
+   b. Ask: "The artifact reviewer suggests improvements to the analysis. How would you like to proceed?"
+      - Options: "Accept analysis as-is", "Regenerate with feedback", "Manually edit"
+   c. If regenerate: Re-run analyzer with feedback
+   d. If manually edit: Wait for user edits, then proceed
+{{/if}}
+5. If review approves: Present results to user
+{{/if}}
+
+{{#if ANALYZE_AND_PLAN_REVIEW_ENABLED}}
+**After @agent-iloom-issue-analyze-and-plan completes:**
+1. Capture the agent's output before presenting to user
+2. Invoke: @agent-iloom-artifact-reviewer with context: "Review this PLAN artifact for PR #{{PR_NUMBER}}: [ANALYZE_AND_PLAN_OUTPUT]"
+3. Wait for review results
+4. If review suggests improvements:
+{{#if ONE_SHOT_MODE}}
+   a. If verdict is SUGGEST_IMPROVEMENTS:
+      - Log: "Artifact review suggests improvements: [summary]"
+      - Re-invoke @agent-iloom-issue-analyze-and-plan with: "Apply these specific improvements to your existing output: [REVIEWER_FEEDBACK]"
+      - After update, proceed to next step (do not re-review)
+   b. If verdict is RECOMMEND_REGENERATION:
+      - Log: "Artifact review recommends regeneration: [summary]"
+      - Re-run analyze-and-plan from scratch with the reviewer's feedback
+{{else}}
+   a. Present review findings to user
+   b. Ask: "The artifact reviewer suggests improvements to the plan. How would you like to proceed?"
+      - Options: "Accept plan as-is", "Regenerate with feedback", "Manually edit"
+   c. If regenerate: Re-run analyze-and-plan with feedback
+   d. If manually edit: Wait for user edits, then proceed
+{{/if}}
+5. If review approves: Proceed to implementation
+{{/if}}
+
+{{#if IMPLEMENTER_REVIEW_ENABLED}}
+**After @agent-iloom-issue-implementer completes:**
+1. Capture the implementer's summary output
+2. Invoke: @agent-iloom-artifact-reviewer with context: "Review this IMPLEMENTATION artifact for PR #{{PR_NUMBER}}: [IMPLEMENTER_OUTPUT]"
+3. Wait for review results
+4. If review suggests improvements:
+{{#if ONE_SHOT_MODE}}
+   a. If verdict is SUGGEST_IMPROVEMENTS:
+      - Log: "Artifact review suggests improvements: [summary]"
+      - Re-invoke @agent-iloom-issue-implementer with: "Apply these specific improvements: [REVIEWER_FEEDBACK]"
+      - After update, proceed to next step (do not re-review)
+   b. If verdict is RECOMMEND_REGENERATION:
+      - Log: "Artifact review recommends regeneration: [summary]"
+      - Re-run implementer from scratch with the reviewer's feedback
+{{else}}
+   a. Present review findings to user
+   b. Ask: "The artifact reviewer suggests improvements. How would you like to proceed?"
+      - Options: "Accept implementation as-is", "Address feedback", "Manually edit"
+   c. If address feedback: Re-run implementer with feedback
+{{/if}}
+5. If review approves: Proceed to code review
+{{/if}}
+{{/if}}
+
 ---
 
 ## Code Review