ak:team

---
name: ak:team
description: "Orchestrate subagent teams for parallel multi-session collaboration. Platform-adaptive: detects Claude Code / Cursor / Copilot / Codex / AntiGravity at runtime and routes to the appropriate subagent strategy. Tier 3 (Claude Code Agent Teams) / Tier 2 (Copilot /fleet) / Tier 1 (Cursor Task, Codex Subagent, AntiGravity Manager)."
category: dev-tools
keywords: [agents, parallel, multi-session, collaboration, platform-adaptive, multi-agent, orchestration]
argument-hint: "<template> <context> [--devs|--researchers|--reviewers N] [--delegate]"
metadata:
  author: auroraphtgrp01
  version: "4.0.0"
  platform-detection: file-existence
  capability-matrix-version: "2026-05-13"
  capability-tiers:
    - tier: 3
      name: "Full Team"
      platforms: [claude-code]
      features: [TeamCreate, SendMessage, TaskCreate, worktree-isolation]
    - tier: 2
      name: "Orchestrator"
      platforms: [copilot-cli]
      features: [fleet, custom-agents, hooks]
    - tier: 1
      name: "Parallel Spawn"
      platforms: [cursor, codex, antigravity]
      features: [native-spawn, manual-coordination]
---

# Agent Teams — Platform-Adaptive Orchestration

Coordinate multiple agents for parallel multi-session collaboration. Detects the runtime platform and routes to the appropriate subagent strategy.

## Platform Detection

Detect via file-existence checks (in order of precedence):

| Priority | Platform | Detection | Capability Tier |
|---|---|---|---|
| 1 | Claude Code | `.claude/` directory exists | **Tier 3** (if Agent Teams enabled) / **Tier 1** (otherwise) |
| 2 | Cursor IDE | `.cursor/CURSOR.md` exists | **Tier 1** |
| 3 | GitHub Copilot CLI | `.github/copilot-instructions.md` exists | **Tier 2** |
| 4 | Codex CLI | `.codex/CODEX.md` exists | **Tier 1** |
| 5 | AntiGravity | `.agents/` directory exists | **Tier 1** |
| 6 | Unknown | none of the above | **Tier 1** fallback |

```text
detect_platform():
  if exists(".claude/")                          → "claude-code"  (Tier 3 or 1)
  if exists(".cursor/CURSOR.md")                 → "cursor"        (Tier 1)
  if exists(".github/copilot-instructions.md")   → "copilot"       (Tier 2)
  if exists(".codex/CODEX.md")                  → "codex"         (Tier 1)
  if exists(".agents/")                          → "antigravity"   (Tier 1)
  return "unknown"                               → fallback to Tier 1
```

## Capability Report

At the start of every invocation, report to the user:

```text
Platform: {platform}
Tier: {tier}
Inter-agent messaging: {YES / NO}
Shared task list: {YES / NO}
File conflict prevention: {YES / manual / NO}

Orchestration mode: {team / fleet / parallel-spawn}
```

If the detected tier differs from the user's expectation, warn explicitly.

## Usage

```
ak:team <template> <context> [flags]
```

**Templates:** `research`, `cook`, `review`, `debug`

**Flags:**
- `--devs N` | `--researchers N` | `--reviewers N` | `--debuggers N` -- team size
- `--plan-approval` / `--no-plan-approval` -- plan gate (default: on for cook)
- `--delegate` -- lead only coordinates, never touches code
- `--worktree` -- use git worktrees for implementation isolation (default: on for cook)

## Capability Tier Reference

### Tier 3 — Full Team (Claude Code only)

Requires: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in settings.json.
Requires: CLI terminal — `TeamCreate`/`TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList` are **disabled in VSCode extension** (isTTY check). Agent Teams CANNOT run in VSCode-based IDEs.

Available tools: `TeamCreate`, `TeamDelete`, `Agent(team_name)`, `SendMessage`, `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`, `SendMessage(type: "shutdown_request")`

### Tier 2 — Orchestrator (Copilot CLI only)

Requires: `/fleet` command. Custom agents via Markdown YAML frontmatter files.
Available tools: `/fleet`, custom agents, hooks (`preToolUse`, `postToolUse`, `subagentStop`)

### Tier 1 — Parallel Spawn (Cursor / Codex / AntiGravity / Claude Code fallback)

Requires: Native subagent spawning per platform. Manual coordination, no inter-agent messaging.

- **Cursor:** `Task` tool (background mode) + `/multitask` (Cursor 3.2+)
- **Codex:** Explicit spawn prompt + `/agent` thread management + TOML sandbox config
- **AntiGravity:** Agent Manager GUI/API + 16 specialized agents (AgentKit 2.0) + file locking

## Pre-flight Check

1. Execute platform detection.
2. Assign capability tier.
3. Report capability status to user.
4. Proceed with tier-appropriate workflow.

**Tier 3 (Claude Code):** Call `TeamCreate`. If it errors → report Agent Teams unavailable. Do NOT silently fall back unless user approves.
**Tier 2 (Copilot):** Use `/fleet` as orchestrator.
**Tier 1 (Cursor/Codex/AntiGravity/unknown):** Use native subagent spawning.

## Tool Reference by Tier

### Tier 3 — Claude Code Agent Tools

| Tool | Purpose | Params |
|------|---------|--------|
| `TeamCreate` | Create team + task list | `team_name`, `description` |
| `TeamDelete` | Remove team resources | *none* |
| `Agent(team_name, ...)` | Spawn teammate | `subagent_type`, `model: "opus"`, `run_in_background: true`, `isolation: "worktree"` |
| `SendMessage` | Inter-agent messaging | `type`, `to`/`recipient`, `message` |
| `TaskCreate` | Create work item | `subject`, `description`, `priority`, `addBlockedBy`, `addBlocks` |
| `TaskUpdate` | Claim/complete task | `taskId`, `status`, `owner` |
| `TaskGet` | Full task details | `taskId` |
| `TaskList` | All tasks | *none* |

### Tier 1 — Cursor Task Tool

| Tool | Purpose | Params |
|------|---------|--------|
| `Task` | Spawn subagent | `subagent_type`, `prompt`, `description`, `run_in_background: true/false` |
| `/multitask` | Auto-decompose + parallel dispatch | prompt (Cursor 3.2+) |

Built-in subagent types: `Explore`, `Bash`, `Browser`

### Tier 1 — Codex Subagent

| Tool | Purpose | Params |
|------|---------|--------|
| Subagent spawn | Explicit prompt-based | "Spawn one agent per X" |
| `/agent` | Thread management | switch, steer, stop, close |
| TOML sandbox | Isolation config | `sandbox_mode: read-only | workspace-write | danger-full-access` |

Built-in agents: `default`, `worker`, `explorer`
Config: `max_threads` (default 6), `max_depth` (default 1)

### Tier 1 — AntiGravity Agent Manager

| Tool | Purpose | Params |
|------|---------|--------|
| Agent Manager | Spawn agents | role, context, async |
| Manager Surface | Real-time monitoring | token consumption, errors |
| File locking | Conflict prevention | automatic |
| Per-agent model | Model selection | per agent |

16 specialized agents (AgentKit 2.0):
- Frontend: UI Builder, Styler, A11y Auditor, Perf Optimizer
- Backend: API Designer, DB Manager, Auth Handler, Cache Architect
- Testing: Unit Tester, Integration Tester, E2E Tester, Security Scanner
- DevOps: CI/CD Builder, Docker Specialist, K8s Manager, Monitor

### Tier 2 — Copilot CLI /fleet

| Tool | Purpose | Params |
|------|---------|--------|
| `/fleet` | Orchestrator | task decomposition, parallel dispatch |
| Custom agents | Markdown YAML | `name`, `description`, `tools`, `infer`, `mcpServers` |
| Hooks | Lifecycle events | `preToolUse`, `postToolUse`, `subagentStop` |

Built-in agents: `explore`, `task`, `research`, `code-review`, `rubber-duck`, `general-purpose`

## CK Context Block

Every subagent spawn prompt MUST include this context at the end:

```
CK Context:
- Work dir: {CWD}
- Reports: {REPORTS_PATH or "plans/reports/"}
- Plans: {PLANS_PATH or "plans/"}
- Branch: {GIT_BRANCH or current branch}
- Naming: {NAMING_PATTERN or "YYMMDD-HHMM"}
- Active plan: {ACTIVE_PLAN or "none"}
- Commits: conventional (feat:, fix:, docs:, refactor:, test:, chore:)
- Platform: {DETECTED_PLATFORM}
- Tier: {CAPABILITY_TIER}
```

---

## ON `ak:team research <topic>` [--researchers N]

*Investigate a topic from multiple angles in parallel.*

### Tier 3 (Claude Code)

1. Derive N angles from `<topic>` (default N=3)
2. Call `TeamCreate(team_name: "<topic-slug>")`
3. Call `TaskCreate` x N — one per angle
4. Spawn teammates x N via `Agent(team_name, model: "opus", run_in_background: true)`
5. Monitor via TaskCompleted events + TaskList fallback
6. Read all researcher reports from `{REPORTS_PATH}/`
7. Synthesize into: `{REPORTS_PATH}/research-summary-{name}-{topic-slug}.md`
8. `SendMessage(type: "shutdown_request")` to each teammate
9. `TeamDelete`
10. Report: `Research complete. Summary: {path}. N reports generated.`

### Tier 2 (Copilot CLI)

1. Use `/fleet` with researcher agents
2. Built-in: `research` agent for investigation
3. Copilot's /fleet handles decomposition, dispatch, polling, synthesis
4. Report: `Research complete via /fleet.`

### Tier 1 (Cursor / Codex / AntiGravity)

1. Derive N angles from `<topic>` (default N=3)
2. Spawn N background subagents:
   - **Cursor:** `Task(subagent_type: "Explore", prompt: task + CK Context, run_in_background: true)`
   - **Codex:** Explicit prompt: "Spawn researcher-{N} to investigate angle: {angle}. Save to {REPORTS_PATH}/researcher-{N}-{name}.md"
   - **AntiGravity:** Agent Manager spawn N parallel agents with `research` role
3. Monitor results (Cursor: poll; Codex: `/agent`; AntiGravity: Manager Surface)
4. Read all reports from `{REPORTS_PATH}/`
5. Synthesize into: `{REPORTS_PATH}/research-summary-{name}-{topic-slug}.md`
6. Report: `Research complete. Summary: {path}. N reports generated. Platform: {platform}.`

---

## ON `ak:team cook <plan-path-or-description>` [--devs N]

*Implement a feature or plan with parallel developers.*

### Tier 3 (Claude Code)

1. Read plan or spawn planner teammate
2. Call `TeamCreate(team_name: "<feature-slug>")`
3. Call `TaskCreate` x (N + 1) — N dev tasks + 1 tester task (tester blocked by all devs)
4. Spawn developers x N via `Agent(subagent_type: "fullstack-developer", model: "opus", isolation: "worktree", run_in_background: true)`
5. Monitor dev completion via TaskCompleted events
6. When all dev tasks complete, spawn tester: `Agent(subagent_type: "tester", model: "opus")`
7. Merge worktree branches: `git merge <dev-branch> --no-ff`, resolve conflicts, cleanup worktrees
8. Docs sync eval
9. `SendMessage(type: "shutdown_request")` to all teammates
10. `TeamDelete`
11. Report test results, docs impact

### Tier 2 (Copilot CLI)

1. Use `/fleet` with task agents
2. Built-in: `task` agent for implementation
3. `/fleet` handles decomposition, parallel dispatch, polling, synthesis
4. If `--plan-approval`: include instruction for plan approval gate
5. Report: `Cook complete via /fleet.`

### Tier 1 (Cursor / Codex / AntiGravity)

1. Read plan and decompose into N non-overlapping file ownership groups
2. Spawn N background developer subagents:
   - **Cursor:** `Task(subagent_type: "general-purpose", prompt: task + plan + CK Context, run_in_background: true)`
   - **Codex:** "Spawn worker-{N} to implement files matching {glob}. Plan approval: {--plan-approval}. Save diffs to {REPORTS_PATH}/dev-{N}-{name}.md"
   - **AntiGravity:** Agent Manager spawn N `API Designer` / `UI Builder` agents (select by plan scope)
3. If `--plan-approval`: wait for plan review before spawning
4. Monitor completion:
   - Cursor: poll each Task result
   - Codex: `/agent` thread management
   - AntiGravity: Manager Surface
5. Manually assign file ownership to prevent conflicts
6. Merge results (manual — no team merge tools)
7. Docs sync eval
8. Report: `Cook complete. N developers. Platform: {platform}.`

---

## ON `ak:team review <scope>` [--reviewers N]

*Review code from multiple perspectives in parallel.*

### All Tiers

1. Derive N review focuses from `<scope>` (default N=3)
   - Focus 1: Security — vulnerabilities, auth, input validation, OWASP
   - Focus 2: Performance — bottlenecks, memory, complexity, scaling
   - Focus 3: Test coverage — gaps, edge cases, error paths

### Tier 3 (Claude Code)

2. Call `TeamCreate(team_name: "review-<scope-slug>")`
3. Call `TaskCreate` x N — one per focus
4. Spawn reviewers x N via `Agent(subagent_type: "code-reviewer", model: "opus", run_in_background: true)`
5. Monitor via TaskCompleted events
6. Synthesize findings: `{REPORTS_PATH}/review-{scope-slug}.md`
7. `SendMessage(type: "shutdown_request")` + `TeamDelete`
8. Report: `Review complete. {X} findings ({Y} critical). Report: {path}.`

### Tier 2 (Copilot CLI)

2. Use `/fleet` with `code-review` agents
3. Built-in: `code-review` agent
4. Report: `Review complete via /fleet. {X} findings.`

### Tier 1 (Cursor / Codex / AntiGravity)

2. Spawn N background reviewer subagents:
   - **Cursor:** `Task(subagent_type: "Explore", prompt: review task + CK Context, run_in_background: true)`
   - **Codex:** "Spawn reviewer to review {scope} for {focus}. Output severity-rated findings. Save to {REPORTS_PATH}/reviewer-{N}-{name}-{scope}.md"
   - **AntiGravity:** Agent Manager spawn N parallel agents with `Security Scanner` / `Unit Tester` roles
3. Monitor completion
4. Synthesize findings: `{REPORTS_PATH}/review-{scope-slug}.md`
5. Report: `Review complete. {X} findings. Platform: {platform}.`

---

## ON `ak:team debug <issue>` [--debuggers N]

*Root-cause debugging with competing hypotheses.*

### All Tiers

1. Generate N competing hypotheses from `<issue>` (default N=3)
   - Each must be independently testable
   - Each predicts different observable symptoms
   - Frame as: "If <cause>, then we should see <evidence>"

### Tier 3 (Claude Code)

2. Call `TeamCreate(team_name: "debug-<issue-slug>")`
3. Call `TaskCreate` x N — one per hypothesis
4. Spawn debuggers x N via `Agent(subagent_type: "debugger", model: "opus", run_in_background: true)`
5. Debuggers message each other — let them converge
6. Read all debugger reports
7. Identify surviving theory as root cause
8. Write root cause report: `{REPORTS_PATH}/debug-{issue-slug}.md`
9. `SendMessage(type: "shutdown_request")` + `TeamDelete`
10. Report: `Debug complete. Root cause: {summary}. Report: {path}.`

### Tier 2 (Copilot CLI)

2. Use `/fleet` with task agents + adversarial hypotheses
3. Built-in: `task` agent for investigation
4. Report: `Debug complete via /fleet. Root cause: {summary}.`

### Tier 1 (Cursor / Codex / AntiGravity)

2. Spawn N background debugger subagents:
   - **Cursor:** `Task(prompt: hypothesis task, run_in_background: true)`
   - **Codex:** "Spawn debugger-{N} to test hypothesis: {hypothesis}. For issue: {issue}. ADVERSARIAL: try to disprove. Save findings to {REPORTS_PATH}/debugger-{N}-{name}-{issue}.md"
   - **AntiGravity:** Agent Manager spawn N parallel agents with `Security Scanner` / custom debug role
3. Monitor completion
4. Read all reports, identify surviving theory
5. Write root cause report: `{REPORTS_PATH}/debug-{issue-slug}.md`
6. Report: `Debug complete. Root cause: {summary}. Platform: {platform}.`

---

## Template-Per-Platform Summary

| Template | Claude Code (Tier 3) | Copilot (Tier 2) | Cursor (Tier 1) | Codex (Tier 1) | AntiGravity (Tier 1) |
|---|---|---|---|---|---|
| **research** | Team + SendMessage | `/fleet` researchers | Task xN | Subagent xN + /agent | Parallel agents |
| **cook** | Team + worktree | `/fleet` + plan approval | Task xN | Subagent xN + TOML | Specialist + Generalist |
| **review** | Team + reviewers | `/fleet` reviewers | Task xN | Subagent xN + TOML | Parallel agents |
| **debug** | Team + adversarial | `/fleet` debuggers | Task xN hypotheses | Subagent xN | Parallel agents |

## When to Use Team vs Subagent

| Scenario | Subagent only | Team appropriate |
|----------|--------------|----------------|
| Focused task (test, lint, single review) | **Yes** | Overkill |
| Sequential chain (plan -> code -> test) | **Yes** | No |
| 3+ independent parallel workstreams | Maybe | **Yes** |
| Competing debug hypotheses | No | **Yes** |
| Cross-layer work (FE + BE + tests) | Maybe | **Yes** |
| Workers need to discuss/challenge findings | No | **Yes** (Tier 3 only) |
| Token budget is tight | **Yes** | No |
| Platform lacks Agent Teams | **Yes** | No |

## Error Recovery

### Tier 3 (Claude Code)

1. Check status: `Shift+Up/Down` (in-process) or click pane (split)
2. Redirect: `SendMessage` direct with corrective instructions
3. Replace: shut down failed teammate, spawn replacement
4. Reassign: `TaskUpdate` stuck task to unblock dependents
5. Abort: `SendMessage(type: "shutdown_request")` all, then `TeamDelete`

### Tier 2 (Copilot CLI)

1. Check subagent output
2. Redirect: re-invoke with corrective prompt
3. Replace: close subagent, respawn

### Tier 1 (Cursor / Codex / AntiGravity)

1. Check subagent result
2. Redirect: spawn replacement with corrective instructions
3. No team-level cleanup needed — subagents are self-contained

## Communication Rules

1. **User chat:** always respond in Vietnamese.
2. **Code and documentation:** use English unless explicitly requested otherwise.

> v4.0.0: Platform-adaptive refactoring. Tier 3 (Claude Code Agent Teams), Tier 2 (Copilot /fleet), Tier 1 (Cursor/Codex/AntiGravity). Capability report shown at invocation.