From 61301596af31efbf6e48e4cd36f5e48a910f1856 Mon Sep 17 00:00:00 2001 From: Sven Date: Wed, 25 Mar 2026 13:45:07 +0100 Subject: [PATCH] fix(workflows): align workflow templates with PROJECT.md spec - settings.md: add auto-advance question to AskUserQuestion block and corresponding config-set command; update success_criteria count to 9 - help.md: correct execute retry count to "max 3 retries, 4 total attempts" - execute.md: add section 8.2 Error Recovery Protocol (3-tier recovery) - execute-plan.md: add Step 5a Review Cycle (spec/code/simplify/final) Co-Authored-By: Claude Opus 4.6 (1M context) --- templates/workflows/execute-plan.md | 19 +++++++++++++++++++ templates/workflows/execute.md | 21 +++++++++++++++++++++ templates/workflows/help.md | 2 +- templates/workflows/settings.md | 12 +++++++++++- 4 files changed, 52 insertions(+), 2 deletions(-) diff --git a/templates/workflows/execute-plan.md b/templates/workflows/execute-plan.md index 85bc6a03..0554a91d 100644 --- a/templates/workflows/execute-plan.md +++ b/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. diff --git a/templates/workflows/execute.md b/templates/workflows/execute.md index 8e8479c9..8184392d 100644 --- a/templates/workflows/execute.md +++ b/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 diff --git a/templates/workflows/help.md b/templates/workflows/help.md index 78ca7a7c..e635117d 100644 --- a/templates/workflows/help.md +++ b/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 diff --git a/templates/workflows/settings.md b/templates/workflows/settings.md index 4eaf38f4..9fe5af29 100644 --- a/templates/workflows/settings.md +++ b/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. - [ ] 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