Teams

Teams are persistent groups of agents that work together across tasks. Once you create a team, the agents stay — you assign work to them through the planner, and the same agents handle every task.

Creating a Team

The fastest way to create a team is through the planner:

1. Spawn a planner agent
2. Describe your team's purpose: "This team manages the dashboard — frontend, backend, and QC"
3. The planner analyzes the codebase and recommends a team structure
4. Click Launch Team to spawn all agents

Agents spawn with proper roles, scopes, and a QC agent queued for phase 2.

From the CLI:

groove team create my-team
groove spawn --role frontend --team my-team --scope "src/components/**"
groove spawn --role backend --team my-team --scope "src/api/**"

Assigning Work

Once the team exists, you have two paths:

Through the Planner

Tell the planner what to do. It decides which existing agent handles the work and auto-delegates — no Launch modal, just a toast confirming which agent got the task.

You → planner: "fix the token counter bug in the dashboard"
Planner → auto-delegates to frontend-3
Toast: "Planner delegated work → frontend-3"

For cross-scope work, the planner routes to multiple agents in parallel.

Directly to an Agent

For quick fixes, message the agent directly from its chat panel. No planner overhead.

You → backend-2: "add a /api/health/detailed endpoint"

Agent Reuse

Teams never spawn duplicate agents. When the planner delegates work to a role that already exists in the team, the existing agent resumes with the new task and full context — project map, design system, user feedback from previous tasks.

This means your agents accumulate session history and context across tasks. The fifth task is faster than the first because the agent already knows the codebase.

QC Agent

Every team includes a fullstack QC agent. It:

• Spawns idle when the team is created with no tasks
• Auto-triggers when a teammate completes work (receives file list and summary)
• Audits changes, runs tests, verifies the build
• Stays idle again after finishing — ready for the next round

The QC never starts long-running dev servers. It verifies the build compiles and tests pass, then stops.

Cross-Scope Handoffs

When an agent needs changes outside its scope, it writes a handoff file:

.groove/handoffs/backend.md
→ "Need a new API endpoint at /api/tokens/detailed that returns per-agent breakdown"

Groove detects the file, wakes the backend agent with the request, and the frontend continues its own work.

Team Management

groove team list              # List all teams
groove team rename <id> name  # Rename a team
groove team delete <id>       # Delete team + all agents + logs

Deleting a team kills all running agents, removes them from the registry, and immediately cleans up all associated logs and generated files.

Switching Teams in the GUI

The GUI header shows team tabs. Click a tab to view that team's agents in the tree. Each team has its own node layout — positions persist independently.