Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
maystudios merged 1 commit into from
Mar 25, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions templates/workflows/execute-plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.

## Step 6 — Post Summary to GitHub

Build summary content and post as a comment on the phase issue.
Expand Down
21 changes: 21 additions & 0 deletions templates/workflows/execute.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):**
Comment on lines +457 to +465
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
- 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
Comment on lines +470 to +472
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
- 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
Expand Down
2 changes: 1 addition & 1 deletion templates/workflows/help.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 11 additions & 1 deletion templates/workflows/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" }
Comment on lines +117 to +118
Copy link

Copilot AI Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
]
},
{
question: "Git branching strategy?",
header: "Branching",
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down
Loading