Merge pull request #175 from maystudios/worktree-agent-a7b4e544

fix(workflows): align 4 workflow templates with PROJECT.md spec

Author: maystudios

templates/workflows/execute-plan.md

@@ -184,6 +184,25 @@ Self-check result:
 - All key files exist + all commits found + all sub-issues closed → `## Self-Check: PASSED`
 - Any miss → `## Self-Check: FAILED — {reason}`
 
+## Step 5a — Review Cycle
+
+Before posting the summary, run a focused review cycle:
+
+| Stage | Check | Action on Fail |
+|-------|-------|----------------|
+| Spec Review | Do outputs match all plan requirements and acceptance criteria? | Fix gaps (1 retry) |
+| Code Review | Does code pass linting? All tests pass? No anti-patterns? | Fix issues (1 retry) |
+| Simplify | Can code be cleaner? Any dead code, redundancy, or unnecessary complexity? | Refactor (1 retry) |
+| Final Review | Overall quality approved? Ready to merge? | Accept or flag for orchestrator |
+
+For each stage:
+1. Run the check
+2. If PASS: advance to next stage
+3. If FAIL: attempt a targeted fix (max 1 retry per stage)
+4. If retry fails: record as BLOCKED and proceed (the orchestrator handles escalation)
+
+Record results in the summary comment's `## Review Cycle` section with: stage name, result (PASS/FAIL/BLOCKED/SKIPPED), attempt count, and findings.
+
 ## Step 6 — Post Summary to GitHub
 
 Build summary content and post as a comment on the phase issue.

templates/workflows/execute.md

@@ -452,6 +452,27 @@ git push origin HEAD
 
 **If human_needed:** Present items for human testing. If approved, treat as passed. If issues reported, proceed to Retry Loop.
 
+### 8.2 Error Recovery Protocol
+
+When verification identifies unresolved gaps, recovery proceeds through three tiers:
+
+**Tier 1 — Debug (attempts 1–3):**
+- Spawn a fresh planner to analyze the failure and produce a targeted gap-closure plan
+- Spawn a fresh executor to implement the fix in an isolated worktree
+- Run verification again on the result
+- If successful: phase completes. If fails: advance to next tier.
+
+**Tier 2 — Rollback (after 3 failed attempts):**
+- Revert the failing changes: `git revert HEAD --no-edit`
+- Document which gaps remain unresolved with evidence
+- Surface blockers to the user with exact error output
+
+**Tier 3 — Escalate:**
+- Create a diagnostic GitHub Issue labeled `type:bug` and `maxsim:auto`
+- Include: original spec, all attempt summaries, exact gate failures, root cause analysis
+- Move the phase to "Blocked" on the Project Board
+- Notify the user and await manual intervention
+
 ## 9. Retry Loop (Max 3 Retries — 4 Total Attempts)
 
 ### 9.1 Check attempt budget

templates/workflows/help.md

@@ -66,7 +66,7 @@ Execute all plans in a phase using wave-ordered parallel agents.
 
 - Runs plans in wave order (parallel within waves, sequential across waves)
 - Auto-verifies after execution via GitHub Issue task completion
-- Retries failed verification (max 2 retries, 3 total attempts)
+- Retries failed verification (max 3 retries, 4 total attempts)
 
 ```
 /maxsim:execute 3

templates/workflows/settings.md

@@ -109,6 +109,15 @@ AskUserQuestion([
       { label: "Deep", description: "Maximum competition. Highest quality, highest cost." }
     ]
   },
+  {
+    question: "Auto-advance: Should MaxsimCLI automatically proceed between stages (research → plan → execute) without waiting for confirmation?",
+    header: "Auto-Advance",
+    multiSelect: false,
+    options: [
+      { label: "Yes", description: "Automatically proceed between stages without confirmation. Maps to config key: workflow.auto_advance" },
+      { label: "No (Recommended)", description: "Pause between stages for user confirmation. Maps to config key: workflow.auto_advance" }
+    ]
+  },
   {
     question: "Git branching strategy?",
     header: "Branching",
@@ -157,6 +166,7 @@ node .claude/maxsim/bin/maxsim-tools.cjs config-set worktrees.auto_cleanup [true
 node .claude/maxsim/bin/maxsim-tools.cjs config-set worktrees.branch_prefix "[value]"
 node .claude/maxsim/bin/maxsim-tools.cjs config-set automation.auto_commit_on_success [true/false]
 node .claude/maxsim/bin/maxsim-tools.cjs config-set automation.conventional_commits [true/false]
+node .claude/maxsim/bin/maxsim-tools.cjs config-set workflow.auto_advance [true/false]
 node .claude/maxsim/bin/maxsim-tools.cjs config-set automation.co_author "[value]"
 node .claude/maxsim/bin/maxsim-tools.cjs config-set hooks.enabled [true/false]
 # Per-agent model overrides (only if custom overrides selected)
@@ -210,7 +220,7 @@ Re-run /maxsim:settings anytime to change these.
 
 <success_criteria>
 - [ ] Current config loaded and displayed
-- [ ] User presented with all 8 settings
+- [ ] User presented with all 9 settings
 - [ ] Config updated via maxsim-tools config-set commands
 - [ ] User offered to save as global defaults
 - [ ] Confirmation displayed after save