fix(workflows): align 4 workflow templates with PROJECT.md spec#175
fix(workflows): align 4 workflow templates with PROJECT.md spec#175maystudios merged 1 commit intomainfrom
Conversation
- 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) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Aligns multiple workflow templates under templates/workflows/ with the current PROJECT.md specification to keep the CLI-guided process, retry semantics, and review/escalation guidance consistent across commands.
Changes:
- Adds an Auto-Advance setting prompt and
workflow.auto_advanceconfig command to the settings workflow. - Updates
/maxsim:helpexecute retry wording to “max 3 retries, 4 total attempts”. - Introduces an “Error Recovery Protocol” section to the execute workflow and adds a “Review Cycle” step to execute-plan.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| templates/workflows/settings.md | Adds Auto-Advance prompt + config-set command; updates success criteria count. |
| templates/workflows/help.md | Corrects execute verification retry description. |
| templates/workflows/execute.md | Adds section 8.2 describing tiered recovery/escalation guidance. |
| templates/workflows/execute-plan.md | Adds Step 5a Review Cycle before posting the summary. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| { 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" } |
There was a problem hiding this comment.
The new Auto-Advance options include "Maps to config key: workflow.auto_advance" in each description, but none of the other AskUserQuestion options in this list include config-key mapping, and the text doesn’t indicate the actual boolean value (true vs false). This makes the question inconsistent with the surrounding settings prompts and potentially unclear to users. Consider removing the mapping text (like the other questions) or explicitly mapping each choice to true/false in a consistent format across 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" } | |
| { label: "Yes", description: "Automatically proceed between stages without confirmation." }, | |
| { label: "No (Recommended)", description: "Pause between stages for user confirmation." } |
| 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):** |
There was a problem hiding this comment.
This section’s attempt numbering conflicts with the workflow’s retry budget in Step 9 ("Max 3 Retries — 4 Total Attempts"). "Tier 1 — Debug (attempts 1–3)" and "Tier 2 — Rollback (after 3 failed attempts)" imply only 3 attempts total and don’t line up with the documented "initial + 3 retries" model. Please align the tier thresholds/labels with the attempt_count semantics used in Step 9 (e.g., clarify whether tiers apply to retries vs total attempts, and update the numbers accordingly).
| 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):** | |
| When verification identifies unresolved gaps, recovery proceeds through three tiers within the attempt budget defined in Step 9 (initial attempt + up to 3 retries; 4 total attempts): | |
| **Tier 1 — Debug (attempts 1–4; initial + up to 3 retries):** | |
| - 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 attempt budget exhausted — 4 failed attempts total):** |
| **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 |
There was a problem hiding this comment.
Tier 3 instructs creating a diagnostic GitHub Issue, but Step 9.1 already defines a diagnostic issue creation flow when the 4-attempt budget is exhausted (with a concrete gh issue create template). As written, this introduces two competing escalation triggers and may cause duplicate issues or unclear operator behavior. Consider either referencing the existing Step 9.1 diagnostic-issue procedure from Tier 3, or explicitly differentiating Tier 3 (when/how to escalate) from the "attempts exhausted" path.
| **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 | |
| **Tier 3 — Escalate (after 4 failed attempts / when §9.1 triggers):** | |
| - Follow the diagnostic GitHub Issue procedure defined in §9.1 ("Verification Failed After 4 Attempts") | |
| - Ensure the diagnostic Issue is labeled `type:bug` and `maxsim:auto` and includes: original spec, all attempt summaries, exact gate failures, and root cause analysis |
| 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. |
There was a problem hiding this comment.
This instructs recording results in the summary comment’s ## Review Cycle section, but the Step 6 summary template below does not include a ## Review Cycle heading/placeholder. That makes the guidance unimplementable as-is. Either add a ## Review Cycle section to the summary template, or update this instruction to point to an existing section (or specify where to insert the review-cycle block).
| Record results in the summary comment's `## Review Cycle` section with: stage name, result (PASS/FAIL/BLOCKED/SKIPPED), attempt count, and findings. | |
| Record results in a `## Review Cycle` section of the summary comment (add this section to the template if it is not already present) with: stage name, result (PASS/FAIL/BLOCKED/SKIPPED), attempt count, and findings. |
|
🎉 This PR is included in version 5.13.1 🎉 The release is available on: Your semantic-release bot 📦🚀 |
Summary
workflow.auto_advanceconfig-set command in Step 3; update success_criteria count from 8 to 9Test plan
🤖 Generated with Claude Code