From ef9590e8ee9aa976607e875c5601e5c80a48ef2f Mon Sep 17 00:00:00 2001 From: Sven Date: Wed, 25 Mar 2026 22:58:30 +0100 Subject: [PATCH] feat: add Tier selection logic to debug.md and plan-research.md workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes §7.2 audit gap: both workflows were hardwired to Tier 1 only. Each now evaluates CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS and config.execution.parallelism.competition_strategy before spawning agents, using Tier 2 Agent Teams when available and strategy is 'deep', with graceful degradation to Tier 1 otherwise (per PROJECT.md §7.2 guarantee). Co-Authored-By: Claude Sonnet 4.6 --- templates/workflows/debug.md | 40 +++++++++++++++++++++++----- templates/workflows/plan-research.md | 38 ++++++++++++++++++++++---- 2 files changed, 67 insertions(+), 11 deletions(-) diff --git a/templates/workflows/debug.md b/templates/workflows/debug.md index 13c52c43..c0558e57 100644 --- a/templates/workflows/debug.md +++ b/templates/workflows/debug.md @@ -94,7 +94,32 @@ Wait for user confirmation to proceed (unless symptoms are fully specified in `$ --- -## Step 3: Reproduce — Confirm the Problem +## Step 3: Tier Selection + +Before spawning debugging agents, evaluate the execution tier: + +1. **Check Tier 2 availability:** + - Verify `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var is set (MaxsimCLI installer enables this by default) + - Read `config.execution.parallelism.competition_strategy` from `.claude/maxsim/config.json` + +2. **If Tier 2 is available AND `competition_strategy` is `deep`:** + - Use Agent Teams collaborative debugging pattern: + - `TeamCreate` to create a debug team + - Spawn 2-3 hypothesis investigator teammates, each exploring a different root-cause theory + - Teammates use `SendMessage` to challenge each other's hypotheses — a hypothesis only survives if it holds up to adversarial cross-examination + - Coordinator collects surviving theories and selects the most evidence-backed root cause + - This fights LLM anchoring bias (first plausible hypothesis wins by default) + +3. **If Tier 2 is NOT available (env var unset, feature not yet stable, or `competition_strategy` is `none`/`quick`/`standard`):** + - **Graceful degradation to Tier 1** — inform the user: + > "Collaborative debugging: using Tier 1 subagents (Agent Teams not available or not required). Each agent investigates independently; coordinator synthesizes findings." + - Proceed with Tier 1 subagents as described below (current default path, fully functional) + +> **Graceful degradation guarantee:** Per PROJECT.md §7.2, if Agent Teams are unavailable (env var not set, unsupported plan, or feature not yet stable), MaxsimCLI falls back to Tier 1 subagents for all workflows. The user is informed but not blocked. + +--- + +## Step 4: Reproduce — Confirm the Problem Spawn a verifier agent to drive steps 1–4 of the `systematic-debugging` skill (Reproduce, Hypothesize, Isolate, Verify): @@ -171,7 +196,7 @@ Options: 3. Manual — I'll fix it myself (close debug issue as resolved) ``` -Proceed to step 4 (ExitPlanMode + Fix). +Proceed to step 5 (ExitPlanMode + Fix). **CHECKPOINT reached:** @@ -196,7 +221,7 @@ If the user provides more context, update `$DESCRIPTION` / `$ERROR` / `$REPRO_ST --- -## Step 4: ExitPlanMode — Confirm the Fix +## Step 5: ExitPlanMode — Confirm the Fix Call `ExitPlanMode`. @@ -219,7 +244,7 @@ Wait for user confirmation before spawning the executor. --- -## Step 5: Fix — Implement the Fix +## Step 6: Fix — Implement the Fix Spawn an executor agent to implement the fix (step 5 of the `systematic-debugging` skill): @@ -256,7 +281,7 @@ Extract `$COMMIT_HASH` and `$FIX_SUMMARY` from executor output. --- -## Step 6: Confirm — Verify the Fix +## Step 7: Confirm — Verify the Fix Spawn a verifier agent to confirm the fix (step 6 of the `systematic-debugging` skill): @@ -294,7 +319,7 @@ If FAIL: display issues, ask user whether to retry the fix or accept as-is. --- -## Step 7: Report — Post Results and Close Issue +## Step 8: Report — Post Results and Close Issue Post a resolution comment to the GitHub Issue: @@ -347,6 +372,9 @@ Verification: $VERIFY_STATUS - [ ] Open debug Issues checked on GitHub before starting a new session - [ ] GitHub Issue created with label "type:bug" and moved to "In Progress" - [ ] EnterPlanMode called before presenting the debugging plan +- [ ] Tier selection evaluated: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var and config.execution.parallelism.competition_strategy checked +- [ ] Tier 2 path (Agent Teams collaborative debugging) used when env var set and strategy is `deep` +- [ ] Graceful degradation to Tier 1 with user notification when Tier 2 is not available - [ ] Verifier agent spawned with subagent_type="verifier" and isolation="worktree" - [ ] Verifier drives systematic-debugging steps 1–4 (Reproduce, Hypothesize, Isolate, Verify) - [ ] Checkpoint, INCONCLUSIVE, and ROOT_CAUSE return paths handled diff --git a/templates/workflows/plan-research.md b/templates/workflows/plan-research.md index 171490ba..8c84b403 100644 --- a/templates/workflows/plan-research.md +++ b/templates/workflows/plan-research.md @@ -112,7 +112,32 @@ Each domain should be independently investigatable by a separate agent. Select 5-10 domains most relevant to this phase. Define a focused research question for each. -## Step 6: Spawn Parallel Research Agents +## Step 6: Tier Selection + +Before spawning researcher agents, evaluate the execution tier: + +1. **Check Tier 2 availability:** + - Verify `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var is set (MaxsimCLI installer enables this by default) + - Read `config.execution.parallelism.competition_strategy` from `.claude/maxsim/config.json` + +2. **If Tier 2 is available AND `competition_strategy` is `deep`:** + - Use Agent Teams cross-checking pattern: + - `TeamCreate` to create a research team + - Spawn 5-10 researcher teammates, each investigating a different domain independently + - Researchers use `SendMessage` to share findings and challenge each other's sources, conclusions, and recommended approaches + - Coordinator collects validated findings, flagging areas where agents agree or disagree, and synthesizes a higher-confidence research document + - This improves research quality by exposing weak sources and conflicting evidence before the planner acts on findings + +3. **If Tier 2 is NOT available (env var unset, feature not yet stable, or `competition_strategy` is `none`/`quick`/`standard`):** + - **Graceful degradation to Tier 1** — inform the user: + > "Research gathering: using Tier 1 subagents (Agent Teams not available or not required). Each researcher works independently; coordinator collates findings." + - Proceed with Tier 1 batch agents as described below (current default path, fully functional) + +> **Graceful degradation guarantee:** Per PROJECT.md §7.2, if Agent Teams are unavailable (env var not set, unsupported plan, or feature not yet stable), MaxsimCLI falls back to Tier 1 subagents for all workflows. The user is informed but not blocked. + +--- + +## Step 7: Spawn Parallel Research Agents Display: ``` @@ -174,7 +199,7 @@ Return findings as structured markdown: Spawn all research agents in parallel using `run_in_background=true`. Do not await any individual agent before spawning the next. -## Step 7: Collect and Aggregate Findings +## Step 8: Collect and Aggregate Findings After all background agents complete, collect their results. @@ -221,7 +246,7 @@ For each agent result: *Agents: {N} researchers across {N} domains* ``` -## Step 8: Post Research to GitHub +## Step 9: Post Research to GitHub Post the consolidated research as a comment on the phase GitHub Issue: @@ -242,7 +267,7 @@ Display confirmation: Research complete. Findings from {N} agents posted to GitHub Issue #{phase_issue_number}. ``` -## Step 9: Handle Agent Failures +## Step 10: Handle Agent Failures If any research agent fails or returns no findings: @@ -262,7 +287,7 @@ Research partially failed. Only {N}/{total} agents returned findings. Wait for user choice. -## Step 10: Return to Orchestrator +## Step 11: Return to Orchestrator After research is posted to GitHub (or research is skipped), return control to the plan.md orchestrator. Do NOT show gate confirmation or next steps -- the orchestrator handles the gate @@ -275,6 +300,9 @@ between Research and Planning. - [ ] Existing research detected from GitHub Issue comment ( marker) and reused unless --force-research - [ ] Phase context read from GitHub Issue (context comment + issue body) - [ ] 5-10 research domains defined based on phase characteristics +- [ ] Tier selection evaluated: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var and config.execution.parallelism.competition_strategy checked +- [ ] Tier 2 path (Agent Teams cross-checking) used when env var set and strategy is `deep` +- [ ] Graceful degradation to Tier 1 with user notification when Tier 2 is not available - [ ] All research agents spawned in parallel using run_in_background=true - [ ] Agent tool used (not Task) for all agent spawning - [ ] Each agent investigates a distinct, focused domain