fix(workflows): align 4 workflow templates with PROJECT.md spec by maystudios · Pull Request #175 · maystudios/maxsimcli

maystudios · 2026-03-25T12:45:37Z

Summary

settings.md: Add auto-advance question to Step 2 AskUserQuestion block and workflow.auto_advance config-set command in Step 3; update success_criteria count from 8 to 9
help.md: Correct execute retry description from "max 2 retries, 3 total attempts" to "max 3 retries, 4 total attempts"
execute.md: Add section 8.2 Error Recovery Protocol with 3-tier recovery (Debug, Rollback, Escalate) between sections 8 and 9
execute-plan.md: Add Step 5a Review Cycle (Spec Review, Code Review, Simplify, Final Review) between Step 5 Self-Check and Step 6 Post Summary

Test plan

Verify settings.md auto-advance question is formatted consistently with existing questions
Verify help.md retry count matches execute.md spec (max 3 retries, 4 total attempts)
Verify execute.md section 8.2 is positioned between 8.1 and 9, uses correct markdown heading level
Verify execute-plan.md Step 5a is positioned between Step 5 and Step 6, table renders correctly

🤖 Generated with Claude Code

- 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>

Copilot

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_advance config command to the settings workflow.
Updates /maxsim:help execute 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.

Copilot · 2026-03-25T12:48:04Z

templates/workflows/settings.md

+      { 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" }


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.

Suggested change

{ 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." }

Copilot · 2026-03-25T12:48:05Z

templates/workflows/execute.md

+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):**


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).

Suggested change

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):**

Copilot · 2026-03-25T12:48:05Z

templates/workflows/execute.md

+**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 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.

Suggested change

**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

Copilot · 2026-03-25T12:48:05Z

templates/workflows/execute-plan.md

+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.


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).

Suggested change

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.

github-actions · 2026-03-25T12:53:33Z

🎉 This PR is included in version 5.13.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

Copilot AI review requested due to automatic review settings March 25, 2026 12:45

Copilot started reviewing on behalf of maystudios March 25, 2026 12:46 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

maystudios merged commit 03350db into main Mar 25, 2026
5 checks passed

github-actions bot added the released label Mar 25, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

fix(workflows): align 4 workflow templates with PROJECT.md spec#175
maystudios merged 1 commit intomainfrom
worktree-agent-a7b4e544

maystudios commented Mar 25, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Copilot AI Mar 25, 2026

Uh oh!

Uh oh!

github-actions bot commented Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		{ 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" }

	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.

Conversation

maystudios commented Mar 25, 2026

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Mar 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants