Add Agent Teams support for collaborative multi-agent development#492
Add Agent Teams support for collaborative multi-agent development#492
Conversation
Co-authored-by: ehartye <1032978+ehartye@users.noreply.github.com>
Co-authored-by: ehartye <1032978+ehartye@users.noreply.github.com>
Co-authored-by: ehartye <1032978+ehartye@users.noreply.github.com>
Co-authored-by: ehartye <1032978+ehartye@users.noreply.github.com>
Add multi-feature detection to brainstorming scoping phase that prompts users to focus on one feature (recommended) or proceed with all (higher risk). When proceeding with multiple features, each feature and shared dependency gets its own worktree, plan, and agent — preserving single- agent-per-feature context isolation. Key additions across 7 skill files: - brainstorming: scope check detects multi-feature requests, presents options - writing-plans: coordination manifest with execution order and dependency graph - using-git-worktrees: multi-worktree creation and dependency distribution - team-driven-development: orchestrator sequences team deployments per manifest - subagent-driven-development: multi-feature context awareness - executing-plans: per-worktree scoping in multi-feature mode - finishing-a-development-branch: orchestrator integration merge order The existing single-feature path is fully preserved and unchanged. https://claude.ai/code/session_01KRPBLUKhMYihnYkiWEtsap
Before creating multiple worktrees, audit the project for issues that break parallel development: hardcoded ports, shared databases, missing .env files, platform-specific needs (Salesforce scratch orgs, Python venvs), git habits like `git add .` and `git stash` that are global across worktrees, and per-ecosystem dependency installation requirements. Key additions: - using-git-worktrees: full "Multi-Worktree Readiness Audit" section covering git habits, port/service conflicts, platform-specific isolation (SFDX, mobile), dependency installation per ecosystem, environment files, and a readiness report template - brainstorming: multi-feature mode now starts with the readiness audit as step 1, with remediation feeding into the shared dependency plan - writing-plans: coordination manifest gains Phase 0 (Environment Readiness) for remediation tasks before any worktree creation https://claude.ai/code/session_01KRPBLUKhMYihnYkiWEtsap
|
Caution Review failedThe pull request is closed. 📝 WalkthroughWalkthroughThis PR introduces comprehensive documentation for a new Agent Teams feature alongside existing subagent-driven development. It includes updated README guidance, new analysis and comparison documentation, a new "team-driven-development" skill with role-specific prompt templates, an end-to-end example, and updates to existing skills to accommodate multi-feature team orchestration contexts. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related issues
Possibly related PRs
Poem
✨ Finishing touches🧪 Generate unit tests (beta)
Tip Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Adds documentation-first support for Claude Code “Agent Teams” as a parallel collaboration workflow to the existing subagent model, plus multi-feature orchestration guidance across existing planning/execution skills.
Changes:
- Introduces new
team-driven-developmentskill with prompt templates and an end-to-end example walkthrough. - Adds docs comparing teams vs subagents and an analysis/implementation summary for the feature.
- Extends several existing skills to support “multi-feature” planning/execution patterns (coordination manifest, multi-worktree readiness audit, per-worktree completion/integration).
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/writing-plans/SKILL.md | Adds multi-feature plan/manifest structure and multi-feature execution handoff guidance. |
| skills/using-git-worktrees/SKILL.md | Adds multi-worktree readiness audit and multi-feature worktree/distribution lifecycle guidance. |
| skills/team-driven-development/SKILL.md | New skill defining when/how to run collaborative agent teams, including multi-feature orchestration and cost guidance. |
| skills/team-driven-development/team-lead-prompt.md | New lead prompt template for orchestration, coordination, and escalation patterns. |
| skills/team-driven-development/team-implementer-prompt.md | New implementer prompt template for task claiming, implementation, and review workflow. |
| skills/team-driven-development/team-reviewer-prompt.md | New reviewer prompt template for structured review feedback and escalation patterns. |
| skills/team-driven-development/example-auth-feature.md | Full example of team-driven auth feature execution with message exchanges and cost comparison. |
| skills/subagent-driven-development/SKILL.md | Adds guidance for operating within a multi-feature orchestration context (single plan/worktree scope). |
| skills/finishing-a-development-branch/SKILL.md | Adds multi-feature completion guidance: per-worktree completion and orchestrator integration merges. |
| skills/executing-plans/SKILL.md | Adds multi-feature context constraints and orchestrator/agent responsibilities. |
| skills/brainstorming/SKILL.md | Adds explicit multi-feature detection step and downstream orchestration guidance. |
| docs/comparison-agent-teams-vs-subagents.md | New decision guide comparing approaches, including cost and hybrid usage scenarios. |
| docs/analysis-agent-teams.md | New gap analysis and roadmap doc for adding teams support. |
| docs/IMPLEMENTATION-SUMMARY.md | New implementation summary document for the PR deliverables and design decisions. |
| README.md | Updates workflow and skill list to reference the new team-driven-development skill. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ````markdown | ||
| # [Initiative Name] Coordination Manifest | ||
|
|
||
| > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans or superpowers:subagent-driven-development per worktree. The orchestrator sequences deployments per this manifest. |
There was a problem hiding this comment.
The coordination manifest template calls out executing-plans/subagent-driven-development as the only per-worktree execution skills, but this PR introduces team-driven-development as an additional execution option. Consider updating this line to include team-driven-development (or explicitly state why teams are excluded in multi-feature manifests) to avoid conflicting guidance.
| > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans or superpowers:subagent-driven-development per worktree. The orchestrator sequences deployments per this manifest. | |
| > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans, superpowers:subagent-driven-development, or superpowers:team-driven-development per worktree. The orchestrator sequences deployments per this manifest. |
| - Let agents claim same task (race condition) | ||
| - Skip the shared task list (how do agents coordinate?) | ||
| - Ignore messages from teammates (breaks collaboration) | ||
| - Mix team and subagent approaches in same workflow |
There was a problem hiding this comment.
This 'Never' rule says not to mix team and subagent approaches, but the comparison guide explicitly recommends a hybrid approach (teams for coordinated phases, subagents for independent phases). Align these docs by clarifying the intended constraint (e.g., "don’t mix within the same task/worktree") or updating/removing the blanket prohibition.
| - Mix team and subagent approaches in same workflow | |
| - Mix team and subagent approaches within the same task/worktree (hybrid across phases is fine; keep each task on one approach) |
| - `teammate-implementer-prompt.md` - Team-aware implementer | ||
| - `teammate-reviewer-prompt.md` - Collaborative reviewer | ||
| - `teammate-researcher-prompt.md` - Exploration and options |
There was a problem hiding this comment.
These prompt filenames don’t exist in the repo (teammate-implementer-prompt.md, teammate-reviewer-prompt.md, teammate-researcher-prompt.md). Update the list to reference the actual templates under skills/team-driven-development/ (team-implementer-prompt.md, team-reviewer-prompt.md, etc.) and clarify that a researcher template is not currently provided if that’s intentional.
| - `teammate-implementer-prompt.md` - Team-aware implementer | |
| - `teammate-reviewer-prompt.md` - Collaborative reviewer | |
| - `teammate-researcher-prompt.md` - Exploration and options | |
| - `team-implementer-prompt.md` - Team-aware implementer | |
| - `team-reviewer-prompt.md` - Collaborative reviewer | |
| - *(Researcher role currently has no dedicated prompt template; use the team lead or implementer prompt as a base, or derive a custom researcher prompt as needed.)* |
| No modifications to existing skills or workflows: | ||
| - New skill added alongside existing ones | ||
| - Existing subagent workflows unchanged |
There was a problem hiding this comment.
This section claims 'No modifications to existing skills or workflows', but this PR updates several existing skills (e.g., writing-plans, using-git-worktrees, executing-plans, etc.). Reword to reflect the actual scope (e.g., 'no breaking changes' / 'additive changes') so the summary isn’t misleading.
| No modifications to existing skills or workflows: | |
| - New skill added alongside existing ones | |
| - Existing subagent workflows unchanged | |
| Additive, backward-compatible updates to existing skills and workflows: | |
| - New skill added alongside existing ones | |
| - Existing subagent workflows preserved |
|
|
||
| ### Single-Feature Handoff | ||
|
|
||
| **"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:** |
There was a problem hiding this comment.
Markdown formatting: this bolded quoted handoff line starts with ** but never closes it, which will cause the rest of the section to render as bold. Close the bold marker (and optionally drop the surrounding quotes) so only the intended sentence is emphasized.
| **"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:** | |
| **Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:** |
|
|
||
| When a coordination manifest exists: | ||
|
|
||
| **"Multi-feature plan complete. Manifest and per-feature plans saved to `docs/plans/`. Execution options:** |
There was a problem hiding this comment.
Markdown formatting: this bolded quoted handoff line starts with ** but never closes it, so subsequent content may render incorrectly. Close the bold marker (and optionally remove the surrounding quotes) to keep formatting scoped to this sentence.
Summary
This PR adds comprehensive support for Claude's new Agent Teams feature (Opus 4.6+), enabling collaborative development with direct inter-agent communication alongside the existing subagent-driven approach. Agent Teams allow multiple agents to work in parallel with shared task lists and peer-to-peer coordination, complementing the sequential hub-and-spoke subagent model.
Key Changes
New Skill: team-driven-development
Documentation
Skill Updates
Implementation Details
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1environment variable; disabled by defaultUse Cases
Agent Teams excel for:
https://claude.ai/code/session_01KRPBLUKhMYihnYkiWEtsap
Summary by CodeRabbit
New Features
Documentation