feat: add Tier selection logic to debug.md and plan-research.md (§7.2 audit fix)

[maystudios]

Summary

• Adds a Tier Selection step to templates/workflows/debug.md (new Step 3) that evaluates CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS and config.execution.parallelism.competition_strategy before spawning debugging agents
• Adds a Tier Selection step to templates/workflows/plan-research.md (new Step 6) with the same evaluation logic before spawning researcher agents
• Both files now include the Tier 2 Agent Teams path (collaborative debugging / cross-checking researchers) and the Tier 1 graceful degradation path, consistent with the reference implementation in execute.md §6.3

Fixes the §7.2 parallelism audit gap: both workflows were previously hardwired to Tier 1 subagents only, with no awareness of the Agent Teams capability.

Test plan

• Verify templates/workflows/debug.md Step 3 references CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS and config.execution.parallelism.competition_strategy
• Verify templates/workflows/plan-research.md Step 6 references the same env var and config key
• Verify both files include the graceful degradation message and PROJECT.md §7.2 guarantee
• Verify step numbering in both files is consistent (no orphaned cross-references)
• Verify wording is consistent with the reference implementation in execute.md §6.3

🤖 Generated with Claude Code

[github-actions]

🎉 This PR is included in version 5.15.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[Copilot]

Pull request overview

Adds Tier Selection guidance to the workflow templates so debug.md and plan-research.md can account for Agent Teams (Tier 2) vs subagents (Tier 1), addressing the §7.2 parallelism audit gap.

Changes:

• Add a new Tier Selection step to templates/workflows/debug.md and renumber subsequent steps.
• Add a new Tier Selection step to templates/workflows/plan-research.md, renumber subsequent steps, and update success criteria accordingly.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
templates/workflows/plan-research.md	Adds Tier Selection step before spawning researchers; renumbers steps and updates success criteria checklist.
templates/workflows/debug.md	Adds Tier Selection step before spawning debugging agents; renumbers steps and updates success criteria checklist.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The Tier 2 availability check here only looks at the env var + config, but the subsequent condition text also references “feature not yet stable”. In execute.md’s reference tier selection, this is handled by doing a lightweight TeamCreate probe before deciding Tier 2 is available. Consider adding the same probe step here (or rewording the condition) so the workflow doesn’t attempt Agent Teams when the feature is enabled but non-functional.

[Copilot]

This workflow introduces a Tier 2 (Agent Teams) path for “Research gathering”, but PROJECT.md §7.2’s tier selection table currently specifies “Research gathering → Tier 1 (Subagents)”. Either update this step to match the current spec (Tier 1 only) or adjust the text to explicitly frame Tier 2 research cross-checking as an experimental extension and align the spec/reference docs accordingly.

Suggested change

	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.
	Before spawning researcher agents, confirm the execution tier for this workflow:
	1. **Lock research gathering to Tier 1 (Subagents):**
	- Per PROJECT.md §7.2, the "Research gathering" phase MUST use Tier 1 subagents only.
	- Do **not** use Agent Teams (Tier 2) for this workflow, even if `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set or `competition_strategy` is `deep`.
	2. **User-facing confirmation:**
	- Inform the user explicitly that research is running in Tier 1 mode:
	> "Research gathering: using Tier 1 subagents as required by PROJECT.md §7.2. Each researcher works independently; the coordinator collates and synthesizes findings."
	- Then proceed with Tier 1 batch agents as described below (this is the required and fully supported path).
	> **Graceful degradation guarantee (project-wide):** 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. This specific research sub-workflow is **always** Tier 1 by design, so it does not depend on Agent Teams availability.

[Copilot]

The Tier 2 availability check here only covers the env var + config, but the later condition text also includes “feature not yet stable”. execute.md’s tier selection covers this by doing a lightweight TeamCreate probe before opting into Tier 2. Consider adding the same probe step here (or rewording the condition) to avoid attempting Agent Teams when enabled but non-functional.

[Copilot]

PROJECT.md §7.2’s tier selection table lists “Collaborative debugging → Tier 2 (Agent Teams)”, but this workflow only opts into Tier 2 when competition_strategy is deep. If competition_strategy is meant to gate Tier 2 usage outside competitive implementation, the spec/reference docs should be updated to reflect that; otherwise consider removing this gating for debugging.