Skip to content

docs(execute): add tier selection and isolation parameter info #190

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

docs(execute): add tier selection and isolation parameter info #190

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
6 changes: 5 additions & 1 deletion packages/cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,10 @@ Removes MAXSIM files from `.claude/`. Your own skills, agents, and Claude Code c
| `/maxsim:quick <description>` | Quick task — create a GitHub Issue and execute in simplified flow |
| `/maxsim:progress` | Show project status from GitHub Project Board with next-action recommendation |
| `/maxsim:debug` | Systematic debugging with reproduce-hypothesize-isolate-verify-fix cycle |
| `/maxsim:debug-loop [symptom]` | Autonomous bug hunting with hypothesis testing |
| `/maxsim:fix-loop [error-command]` | Autonomous error repair until zero errors remain |
| `/maxsim:improve [metric-command]` | Autonomous optimization loop against any metric |
| `/maxsim:security [scope]` | Security audit — STRIDE + OWASP + red-team (read-only) |
| `/maxsim:settings` | View and modify MaxsimCLI configuration |
| `/maxsim:help` | Show available MaxsimCLI commands and usage |

Expand Down Expand Up @@ -210,7 +214,7 @@ Phase numbers are flexible. Integer (`01`, `02`), letter suffixes for parallel t
| Agent | Role | What it does |
|-------|------|-------------|
| Executor | Builds things | Reads plans, makes code changes, commits atomically, handles deviations |
| Planner | Creates plans | Turns research into structured PLAN.md files with tasks, waves, and dependencies |
| Planner | Creates plans | Turns research into structured plan comments on GitHub Issues with tasks, waves, and dependencies |
| Researcher | Investigates | Explores the codebase, gathers technical context, can use Brave Search |
| Verifier | Checks results | Validates plan structure, artifacts, requirement evidence, commit integrity |

Expand Down
2 changes: 1 addition & 1 deletion packages/cli/src/core/version.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/** MaxsimCLI version — auto-injected from package.json at build time. */
export const VERSION = '5.12.0';
export const VERSION = '5.13.1';

/**
* Parse a semantic version string into components.
Expand Down
3 changes: 3 additions & 0 deletions templates/commands/maxsim/execute.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@ Follow @.claude/maxsim/workflows/execute.md end-to-end.
3. Group task Issues by wave — re-evaluate wave composition before each spawn against current GitHub state. Present the execution plan to the user for review.
4. Exit Plan Mode via `ExitPlanMode` — user reviews and approves the execution plan
5. Execute parallel Agents within each wave, sequential across waves
- Tier 1 (default): each Agent uses `isolation: "worktree"` and `run_in_background: true`
- Tier 2 (opt-in, `competition_strategy: deep`): Agent Teams with `SendMessage` debate — requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
- Graceful degradation: if Tier 2 is unavailable, falls back to Tier 1 automatically
Comment on lines +30 to +32
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 Tier 2 bullets here read like they apply to the general “execute parallel agents within each wave” flow, but in templates/workflows/execute.md Tier selection is described only under the Competitive Implementation (Optional) section (gated by config.execution.competitive_enabled and a critical label). Consider clarifying that Tier 2 (competition_strategy: deep + Agent Teams) is used for competitive/debate mode only, while standard wave execution remains Tier 1 worktree-isolated Agent subagents.

Suggested change
- Tier 1 (default): each Agent uses `isolation: "worktree"` and `run_in_background: true`
- Tier 2 (opt-in, `competition_strategy: deep`): Agent Teams with `SendMessage` debate — requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
- Graceful degradation: if Tier 2 is unavailable, falls back to Tier 1 automatically
- Tier 1 (standard/default): each wave is executed by `Agent` subagents using `isolation: "worktree"` and `run_in_background: true`
- Tier 2 (competitive/debate mode only; opt-in via `competition_strategy: deep`): Agent Teams with `SendMessage` debate — used only when competitive execution is enabled and a `critical` task is being run, as described in @.claude/maxsim/workflows/execute.md; requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
- Graceful degradation (competitive path only): if Tier 2 competitive execution is requested but unavailable, fall back to Tier 1 automatically for that work

Copilot uses AI. Check for mistakes.
6. Each Agent updates its GitHub Issue label on start and completion
7. After all tasks complete, spawn a verifier Agent to check acceptance criteria
8. On verification failure, auto-retry with gap-closure context (max 3 retries, 4 total attempts)
Expand Down
2 changes: 1 addition & 1 deletion templates/templates/config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"version": "0.0.0-dev",
"version": "5.13.1",
"execution": {
"model_profile": "balanced",
"parallelism": {
Expand Down
Loading