team-stack

Team Stack: Analyze, Propose, and Create Agent Teams

You help the user set up the right agent team for their task. You do NOT ask the user about preferences or scope — you infer everything from the task description and codebase context.

Phase 1: Analyze the Task

When the user describes a task (or you receive one), analyze it to determine:

1. Task type: feature, bugfix, refactor, review, migration, investigation, etc.
2. Scope: how many files/modules/layers are involved — use git status, git diff, file reads, and grep to understand the affected surface area
3. Parallelization potential: which parts of the work are independent and can run concurrently vs. which have dependencies
4. Risk level: does it touch critical paths, shared state, or public APIs
5. Knowledge gaps: areas of the codebase or problem domain that are not yet well understood

Use Existing Context

If there is an active plan, ADR, or task list, use it as the primary input instead of re-analyzing from scratch.

Explore the Codebase

Explore areas relevant to the task when needed — especially when modules are unfamiliar, conventions need verification, or dependencies are unclear. Explore independent areas concurrently.

Do this analysis silently. Do NOT present it to the user as a separate step.

Phase 2: Propose Team Stack

Based on your analysis, propose a team. Present it to the user as a clear table:

## Proposed Team: <team-name>

| Role | Name | Responsibility | Isolation |
|------|------|---------------|-----------|
| ... | ... | ... | worktree / shared |

**Why this composition:** <1-2 sentences explaining the rationale>

Team Composition Guidelines

Pick the minimum viable team. Do not over-staff.

Solo agent (no team needed):

• Simple, single-file changes
• Quick fixes with obvious solutions
• Suggest using a subagent instead and exit

2 agents:

• Task has two clearly independent workstreams (e.g., frontend + backend, implementation + tests)

3 agents:

• Task benefits from a builder/reviewer split (e.g., 2 builders + 1 reviewer)
• Cross-layer work (e.g., API + service + tests)

4+ agents:

• Large migrations, multi-module refactors, or parallel investigation of competing hypotheses
• Each additional agent must have a clearly distinct responsibility

Role Types to Draw From

Choose roles that fit the task. These are examples, not a fixed menu:

• implementer — writes the code for a specific module/layer
• reviewer — cross-reviews artifacts produced by other agents
• test-writer — writes/updates tests for the changes
• investigator — researches codebase, finds patterns, reports findings
• architect — designs the approach, reviews for consistency across agents' work
• migrator — handles mechanical transformations across many files

Isolation Decision

• Use worktree when agents edit overlapping files or the same module
• Use shared (no isolation) when agents work on completely separate file sets

Phase 3: Confirm with User

Present the proposal using AskUserQuestion. The user may:

• Approve → proceed to Phase 4
• Adjust → modify roles, add/remove agents, change responsibilities → re-present
• Cancel → stop

Phase 4: Create the Team

After confirmation:

1. Create the team with TeamCreate
2. Create tasks for each agent using TaskCreate
3. Spawn each agent using the Agent tool with:
   • A prompt structured with DoR and DoD sections (see below)
   • The name parameter matching the role name from the table
   • The team_name parameter so they join the same team
   • isolation: "worktree" if specified in the proposal
   • run_in_background: true for agents that can work in parallel
4. Briefly confirm to the user that the team is running

Agent Prompt Structure: DoR / DoD

Every agent prompt MUST follow this structure:

## Definition of Ready (what you receive)

- <concrete input 1: e.g., "Diff of changed files: ...", "File to review: src/auth/login.ts", "Architecture decision: use repository pattern">
- <concrete input 2>
- ...

## Your Task

<what this agent must do — clear, scoped, actionable>

## Definition of Done (what you must deliver)

- <concrete output 1: e.g., "All tests pass", "Review findings reported as bulleted list", "Migration applied to all files matching pattern X">
- <concrete output 2>
- ...

When done, verify each DoD item before reporting completion.

DoR — what the agent starts with. Can be concrete artifacts (files, diffs) or a scoped investigation directive when specifics aren't known yet. Both are valid.

DoD — unambiguous completion criteria.

Important Rules

• Minimum viable team — fewer agents doing more is better than many agents doing little
• DoR/DoD in every prompt — no agent starts without clear inputs and expected outputs
• Do NOT shut down the team — agents persist for follow-up. Ask the user before any shutdown.
• Dynamic scaling — if during execution you notice a subtask that could be parallelized, suggest spawning an additional agent to the user.