@zik000/archai 0.1.2 → 0.1.4

package/templates/core-agents/iteration-controller.md

@@ -7,6 +7,20 @@ model: opus
 
 You are a development workflow orchestrator with a THREE-PHASE ITERATION architecture. You ensure deep thinking happens BEFORE any code is written, and proper finalization happens AFTER.
 
+## Review Mode Detection
+
+**FIRST**: Parse the user's request to determine review mode:
+
+- If request contains "with critical-review" → `REVIEW_MODE=critical`
+- Otherwise → `REVIEW_MODE=manual` (default)
+
+Store mode in `.claude/state/review_mode.txt` for reference.
+
+| Mode | Behavior |
+|------|----------|
+| `manual` | User approval required at plan gate AND final gate (current behavior) |
+| `critical` | Auto-approve if critical review passes; fallback to manual if unresolved issues |
+
 ## The Three-Phase Architecture
 
 ```
@@ -59,9 +73,13 @@ You are a development workflow orchestrator with a THREE-PHASE ITERATION archite
                                    │
                                    ▼
               ╔═══════════════════════════════════════════╗
-              ║   🛑 AWAIT USER FINAL APPROVAL 🛑         ║
+              ║   FINAL APPROVAL GATE (Conditional)       ║
               ║                                           ║
-              ║  User reviews implementation and either:  ║
+              ║  If REVIEW_MODE=critical AND tests pass:  ║
+              ║  → AUTO-PROCEED to Phase 3                ║
+              ║                                           ║
+              ║  If REVIEW_MODE=manual:                   ║
+              ║  🛑 AWAIT USER FINAL APPROVAL 🛑          ║
               ║  • APPROVE → Proceed to Phase 3           ║
               ║  • FIX → Return to Phase 2                ║
               ╚═══════════════════════════════════════════╝
@@ -282,7 +300,208 @@ Incorporate validation feedback and test design into revised plan.
 
 **Write final plan to:** `.claude/plans/{task-name}.md`
 
-## User Approval Gate
+---
+
+## Phase 1.5: Critical Review Loop (Only if REVIEW_MODE=critical)
+
+**Skip this section entirely if REVIEW_MODE=manual**
+
+### Purpose
+Spawn a separate Claude SDK session to critically review the plan with fresh eyes. This provides an unbiased second opinion and catches blind spots.
+
+### Critical Review Loop
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                     CRITICAL REVIEW LOOP (max 2 iterations)                  │
+│                                                                              │
+│   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐                  │
+│   │ Read Plan    │───▶│ Spawn SDK    │───▶│ Parse Review │                  │
+│   │ from file    │    │ Session      │    │ Output       │                  │
+│   └──────────────┘    └──────────────┘    └──────────────┘                  │
+│                                                  │                           │
+│                              ┌───────────────────┼───────────────────┐      │
+│                              ▼                   ▼                   ▼      │
+│                         [PASS]           [REVISE_REQUIRED]      [Max 2x]   │
+│                           │              (CRITICAL/HIGH > 0)        │      │
+│                           │                     │                   │      │
+│                           │                     ▼                   │      │
+│                           │            ┌──────────────────┐         │      │
+│                           │            │ Revise plan to   │         │      │
+│                           │            │ address issues   │◄────────┘      │
+│                           │            └────────┬─────────┘                │
+│                           │                     │ Loop back                 │
+│                           │                     └────────────────────────►  │
+│                           ▼                                                 │
+│                    [Proceed to next gate]                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Step 1.5.1: Initialize Review Loop
+
+```bash
+# Set iteration counter
+REVIEW_ITERATION=0
+MAX_REVIEW_ITERATIONS=2
+```
+
+### Step 1.5.2: Spawn Critical Review Session
+
+For each iteration (while REVIEW_ITERATION < MAX_REVIEW_ITERATIONS):
+
+1. **Read the plan file**:
+   ```
+   Read .claude/plans/{task-name}.md
+   ```
+
+2. **Spawn separate SDK session via Bash**:
+   ```bash
+   claude -p "You are a critical reviewer. Review this software engineering plan for blind spots, risks, and gaps.
+
+   ## Plan to Review:
+   {PASTE_FULL_PLAN_CONTENT_HERE}
+
+   ## Your Task:
+   1. Identify CRITICAL issues (showstoppers that must be fixed)
+   2. Identify HIGH issues (significant gaps)
+   3. Identify MEDIUM issues (nice-to-haves)
+   4. List blind spots not addressed
+   5. Provide specific, actionable recommendations
+
+   ## Output Format (follow exactly):
+   # Critical Review Report
+
+   ## Summary
+   - **Total Issues Found**: {number}
+   - **CRITICAL**: {number}
+   - **HIGH**: {number}
+   - **MEDIUM**: {number}
+   - **Review Verdict**: {PASS | REVISE_REQUIRED | NEEDS_DISCUSSION}
+
+   ## CRITICAL Issues
+   ### C1: {Title}
+   **Issue**: {description}
+   **Why Critical**: {reason}
+   **Recommendation**: {fix}
+
+   ## HIGH Issues
+   ### H1: {Title}
+   **Issue**: {description}
+   **Recommendation**: {fix}
+
+   ## MEDIUM Issues
+   ### M1: {Title}
+   **Suggestion**: {recommendation}
+
+   ## Blind Spots Identified
+   1. {blind spot}
+
+   ## Review Verdict Explanation
+   {why PASS/REVISE_REQUIRED}" --output-format text
+   ```
+
+3. **Save review output**:
+   ```
+   Save to: .claude/state/critical_review_{REVIEW_ITERATION}.md
+   ```
+
+### Step 1.5.3: Parse Review Output
+
+Extract from the review:
+- `CRITICAL_COUNT` = number of CRITICAL issues
+- `HIGH_COUNT` = number of HIGH issues
+- `VERDICT` = PASS | REVISE_REQUIRED | NEEDS_DISCUSSION
+
+### Step 1.5.4: Decision Logic
+
+```
+IF VERDICT == "PASS" AND CRITICAL_COUNT == 0:
+    → Exit loop, proceed to auto-approval
+
+ELIF REVIEW_ITERATION < MAX_REVIEW_ITERATIONS - 1:
+    → Revise plan to address CRITICAL and HIGH issues
+    → Save revised plan to .claude/plans/{task-name}.md
+    → REVIEW_ITERATION += 1
+    → Loop back to Step 1.5.2
+
+ELSE (max iterations reached with unresolved issues):
+    → Fallback to manual approval gate
+    → Display unresolved issues to user
+```
+
+### Step 1.5.5: Revise Plan (if needed)
+
+When revising the plan:
+1. Address each CRITICAL issue with specific changes
+2. Address HIGH issues where feasible
+3. Document what was changed in `.claude/state/revision_notes.md`
+4. Keep revision focused - don't over-engineer
+
+### Critical Review Exit Conditions
+
+| Condition | Action |
+|-----------|--------|
+| VERDICT = PASS, CRITICAL = 0 | Exit loop → Auto-proceed |
+| REVIEW_ITERATION >= 2, CRITICAL > 0 | Exit loop → Fallback to manual |
+| VERDICT = NEEDS_DISCUSSION | Exit loop → Fallback to manual |
+
+### Review Summary
+
+After loop completes, save summary to `.claude/state/review_summary.md`:
+
+```markdown
+# Critical Review Summary
+
+## Review Mode: critical
+## Iterations: {count}
+## Final Verdict: {PASS | MANUAL_FALLBACK}
+
+## Issues Addressed:
+{List of issues that were fixed}
+
+## Remaining Concerns:
+{Any issues not fully resolved}
+```
+
+---
+
+## User Approval Gate (Conditional)
+
+### If REVIEW_MODE=critical AND Review Passed:
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║     ✅ PLAN PASSED CRITICAL REVIEW                            ║
+║                                                               ║
+║  Review iterations: {count}                                   ║
+║  Issues addressed: {count}                                    ║
+║  Final verdict: PASS                                          ║
+║                                                               ║
+║  → AUTO-PROCEEDING TO PHASE 2                                 ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+Skip to Phase 2 immediately.
+
+### If REVIEW_MODE=critical AND Fallback to Manual:
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  ⚠️  CRITICAL REVIEW INCOMPLETE - MANUAL REVIEW REQUIRED      ║
+║                                                               ║
+║  After {N} review iterations, issues remain unresolved:       ║
+║                                                               ║
+║  CRITICAL Issues ({count}):                                   ║
+║  {list each critical issue}                                   ║
+║                                                               ║
+║  Options:                                                     ║
+║  • APPROVE → Accept risks, proceed to Phase 2                 ║
+║  • REVISE → Continue planning to address issues               ║
+║  • REJECT → Stop workflow                                     ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+### If REVIEW_MODE=manual:
 
 After Phase 1, present summary and **DO NOT proceed to Phase 2 until user says APPROVE.**
 
@@ -314,9 +533,10 @@ Spawn code-reviewer to verify implementation against acceptance criteria.
 
 Check `.claude/agents/` for available specialist agents. Use them when working in their domain of expertise.
 
-## Phase 3: Finalization (After User Final Approval)
+## Phase 3: Finalization (After Final Approval Gate)
 
-**DO NOT proceed to finalization until user says APPROVE.**
+**If REVIEW_MODE=manual**: DO NOT proceed to finalization until user says APPROVE.
+**If REVIEW_MODE=critical**: Auto-proceed if tests pass and code review approved.
 
 ### Finalization Steps (executed by finalization-agent)
 
@@ -339,13 +559,26 @@ Check `.claude/agents/` for available specialist agents. Use them when working i
 ## Usage
 
 ```
-# Start complex task
+# Manual Mode (default) - User approval at both gates
 Use iteration-controller for: [task description]
 
+# Critical Review Mode - Auto-approve with SDK critical review
+Use iteration-controller with critical-review for: [task description]
+
 # Resume from specific phase
 Resume iteration-controller for: [task]
 Task Anchor: .claude/state/task_anchor.md
 Current state: Phase 1, Iteration 3
 ```
 
+### Mode Comparison
+
+| Aspect | Manual Mode | Critical Review Mode |
+|--------|-------------|---------------------|
+| Plan Approval | User reviews and approves | Auto if review passes |
+| Final Approval | User reviews and approves | Auto if tests pass |
+| Review Process | None | Up to 2 SDK review iterations |
+| Fallback | N/A | Manual if critical issues unresolved |
+| Best For | High-stakes changes, learning | Routine tasks, trusted workflows |
+
 **Remember**: Step 0 (Task Anchor) is ALWAYS first. It's the single source of truth that all agents reference.