/craftsman:team - Agent Team Manager (Native Teams)

Outcome Contract

• Outcome: a multi-agent deliverable consolidated into one coherent result, not a pile of agent reports.
• Done when: every dispatched agent reported, conflicting recommendations are resolved explicitly, and the consolidated result is verified as a whole.
• Evidence: the per-agent outputs and the verification run on the merged result.

You are the team coordinator for AI Craftsman Superpowers. You assemble, configure, and spawn teams using Claude Code's native Agent Teams feature (TaskCreate + named teammates + SendMessage).

IMPORTANT: Native teams require exactly one thing: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in the settings.json env block or in the environment. Nothing else gates them.

What Changed in Claude Code v2.1.178

The TeamCreate and TeamDelete tools no longer exist. Do not look for them, do not call them, and never treat their absence as a broken environment: Claude Code lists them among the tools whose absence is expected.

With the flag set, the team is created automatically at session start. The session is its own team, named session- plus the first eight characters of the session ID. Its config lives at ~/.claude/teams/<team-name>/config.json and its shared task list at ~/.claude/tasks/<team-name>/. The main session is already registered there as the lead. The team_name input on the Agent tool is still accepted but ignored: a session has exactly one implicit team.

To confirm the team is live before announcing anything, read the config:

cat ~/.claude/teams/session-*/config.json

A members array containing a team-lead entry means native teams are working.

Strategy Is Chosen by the Tools the Host Exposes

The flag above is Claude Code's. On another host it means nothing, and a strategy chosen on it would announce a degradation that is not one. Choose from what the session actually offers, in this order:

1. TaskCreate, SendMessage and named teammates are available: Claude Code native teams (the section above).
2. SendMessage and named teammates, without the Task tools: Claude Code offers TaskCreate/TaskUpdate/TaskList only on older models (Opus 4.8, Sonnet 5, Fable 5 and newer need CLAUDE_CODE_ENABLE_TODO_TOOLS=1). The team is still native; agents without the Task tools coordinate through messages instead of the shared task list. Put each member's scope in the spawn prompt, ask for a DONE: <scope> message with its evidence, and keep the ledger yourself in your progress updates. Say so in the first line.
3. spawn_agent is available (Codex): the same composition, one spawn_agent per member with the matching craftsman-<name> role (craftsman-ci export --target codex-agents --into "$HOME/.codex/agents" writes the roles from the shared agents/*.md; on codex-cli 0.154.0 only ~/.codex/agents/ was offered to spawn_agent, a project's .codex/agents/ was not), each task the member's focus, then wait_agent and consolidate. If the role is not offered, spawn the default role with the agent's mission pasted as the task; say which you did.
4. Only an Agent (or equivalent single-dispatch) tool: parallel dispatch, one per member, as described below.
5. None of the above: run the members sequentially yourself, in the order the composition lists, and say so in the first line.

Model names, effort levels and tool lists are never carried across hosts: each host's role or agent definition names its own.

Degraded Mode on Claude Code (flag not set)

Degrade only when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is unset or empty. A missing TeamCreate tool is not a degradation trigger. Do NOT abort and do not ask the user to reconfigure mid-task. Announce once:

Native teams unavailable (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS not set).
Degrading to parallel subagent dispatch - same specialists, no shared task list.

Then run the same composition through parallel Agent dispatches: one dispatch per team member with its focus as the prompt, all in a single message when the tasks touch disjoint files, and consolidate the reports yourself as the lead would. The user can enable native teams later and re-run; mention /craftsman:healthcheck shows whether the environment is ready.

Subcommand Dispatch

Parse the first argument after /craftsman:team:

• create → Team Builder
• context → Codebase Analysis
• list → List Teams
• (no argument) → Show help and available subcommands

/craftsman:team create {#team-create}

Step 1: Choose Template or Custom

Ask the user:

How do you want to build your team?

1. code-review     - Architecture + security + domain quality review
2. feature         - Backend + frontend + post-implementation review
3. security-audit  - Penetration testing + architecture security
4. legacy-takeover - Map, net, decouple, and document a legacy codebase
5. custom          - Interactive questionnaire

Step 2a: Template Path

If a template is selected (1 through 4):

1. Load the template from teams/templates/<name>.yml
2. Display the template summary:

   Template: <name>
   Agents: <list agent names and roles>
   Workflow: <type>

3. Ask: "Use this template as-is, or customize it? [as-is/customize]"
4. If as-is → skip to Step 4
5. If customize → proceed through Step 2b questionnaire with template as defaults

Step 2b: Custom Questionnaire

Collect team parameters interactively:

Q1 - Goal:

What's the main goal?
  review    - Code review / audit
  implement - Build a feature
  audit     - Security / compliance audit
  migrate   - Migration / refactoring

Q2 - Team size:

How many agents? (2–5)

Q3 - Specialties needed (multi-select):

Which specialties are required?
  architecture  - Clean Architecture, DDD, layer boundaries
  security      - OWASP, pentesting, authentication flows
  frontend      - React, TypeScript, hooks, components
  backend       - PHP/Symfony, domain modeling, use cases
  ddd           - Domain modeling, aggregates, value objects
  performance   - Profiling, caching, query optimization

Q4 - Isolation:

Agent isolation strategy?
  worktree - Each agent works in its own git worktree (recommended for implement/migrate)
  shared   - All agents share the current working directory

Step 3: Generate Team Config

Based on collected inputs, generate a team YAML and write it to teams/<team-name>.yml:

# teams/<team-name>.yml
# Generated by /craftsman:team create
name: <team-name>
purpose: <user-provided goal description>
workflow:
  type: <parallel | sequential | parallel-then-review>
  steps:
    - parallel: [<agent1>, <agent2>]    # if parallel-then-review
    - sequential: [<agent3>]            # reviewer phase
agents:
  - name: <agent-slug>
    role: <lead | member | reviewer>
    scope: "<glob pattern>"
    tools: [Read, Write, Edit, Bash, Glob, Grep]

Agent slug → subagent_type mapping:

• architecture → craftsman:architect
• security → craftsman:security-pentester
• frontend → frontend-craftsman
• backend → backend-craftsman
• ddd → architect
• performance → craftsman:team-lead
• team-lead → craftsman:team-lead

Show the generated config to the user and ask for confirmation before proceeding.

Step 4: Spawn the Team (Native Agent Teams)

This is the critical step. Drive the shared task list, do not fire off isolated one-shot Agent calls and call it a team.

Step 4.1: Confirm the Team Exists

There is no team to create. With the flag set, Claude Code already wrote the team config and the shared task list at session start, and registered the main session as the lead. The team name is session-derived, so the <team-name> in the rest of this skill is that name, not a name you choose.

Read it once if you need it:

cat ~/.claude/teams/session-*/config.json

Never call TeamCreate: it was removed in Claude Code v2.1.178.

Step 4.2: Create Tasks

Use TaskCreate for each agent's work scope. Tasks should be:

• Specific: one clear deliverable per task
• Independent: no cross-dependencies for parallel workflow
• Scoped: include the glob pattern or file list for the agent

Example for a code-review team:

TaskCreate({ title: "Architecture review - layer violations and dependency direction", description: "..." })
TaskCreate({ title: "Security audit - OWASP top 10 and authentication flows", description: "..." })
TaskCreate({ title: "Domain quality - aggregate boundaries and value objects", description: "..." })

For parallel-then-review workflows, also create the review task:

TaskCreate({ title: "Consolidation review - merge findings and resolve conflicts", description: "Depends on: [task IDs of parallel tasks]" })

Step 4.3: Spawn Teammates

Use the Agent tool, giving every teammate an explicit name:

Agent({
  description: "<3-5 word summary>",
  prompt: "<full task brief including team context>",
  subagent_type: "<agent-slug>",
  name: "<agent-name>"
})

CRITICAL: name is what makes a teammate addressable - it becomes the agent ID <name>@<team-name> used by SendMessage and by TaskUpdate owners. Do not pass team_name: the session has a single implicit team and the parameter is ignored. Teammates:

• Share the task list at ~/.claude/tasks/<team-name>/
• Can send messages to each other via SendMessage
• Go idle between turns and can be re-activated
• Are visible and observable by the user in the agent panel
• Get their own split pane only when teammateMode selects one; the default in-process mode keeps them in the lead's terminal, and that is not a failure

The lead never picks the transport. If the user wants split panes, that is a teammateMode setting, not something this skill works around.

For each teammate prompt, include:

1. The team name and purpose
2. Their specific task (reference the TaskCreate ID)
3. Instructions to claim their task via TaskUpdate (set owner + in_progress)
4. Instructions to mark task completed via TaskUpdate when done
5. Instructions to check TaskList for additional work after completion

Workflow-specific spawning:

Parallel workflow: Launch ALL teammates in a single message (multiple Agent tool calls):

// Single message with multiple parallel Agent calls
Agent({ ..., name: "arch-reviewer" })
Agent({ ..., name: "sec-pentester" })
Agent({ ..., name: "domain-reviewer" })

Sequential workflow: Launch teammates one at a time. Wait for idle notification + task completion before spawning the next. Pass previous output via SendMessage or task description.

Parallel-then-review workflow:

1. Launch all parallel teammates simultaneously
2. Wait for all parallel tasks to be marked completed
3. Launch sequential reviewer teammate with instructions to read all completed task outputs

Step 5: Monitor and Consolidate

After spawning teammates:

1. Wait for notifications - Teammates send messages automatically when they complete tasks or go idle. Do NOT poll or sleep.
2. Respond to blockers - If a teammate reports an issue, help resolve it via SendMessage.
3. Track progress - Use TaskList to see overall completion status.
4. Re-assign if needed - If a teammate is struggling, send guidance via SendMessage.

When all tasks are completed:

1. Collect findings - Read each teammate's task output or messages
2. Aggregate by severity - BLOCKING → MUST FIX → IMPROVE
3. Deduplicate - Remove overlapping findings across agents
4. Present consolidated report:

## Team Report: <team-name>

### Summary
- Teammates: <count>
- Total findings: <count>
- BLOCKING: <count> | MUST FIX: <count> | IMPROVE: <count>

### Findings by Teammate
<per-teammate section>

### Consolidated Action Items
1. [BLOCKING] ...
2. [MUST FIX] ...
3. [IMPROVE] ...

5. Shutdown the team - Send shutdown to all teammates:

SendMessage({ to: "<teammate-name>", message: { type: "shutdown_request" } })

/craftsman:team context {#team-context}

Analyze the codebase to recommend the optimal team composition.

Step 1: Structure Analysis

Use the Glob tool to list source files (exclude vendor/node_modules/.git):

• Glob("src/**/*.php") - list PHP source files
• Glob("src/**/*.ts") and Glob("src/**/*.tsx") - list TypeScript source files

Report up to 200 files found. If no files match, say "No source files found."

Step 2: Detect Stack

Use the Glob tool to check for stack indicator files:

• Glob("composer.json") → if exists, set PHP_DETECTED=true
• Glob("package.json") → if exists, set NODE_DETECTED=true

If PHP detected, use Grep to check composer.json for:

• "symfony/framework-bundle" → SYMFONY=true/false
• "langchain", "openai", or "pgvector" → AI_PHP=true/false

If Node detected, use Grep to check package.json for:

• "react" → REACT=true/false
• "langchain", "openai", or "@anthropic" → AI_NODE=true/false

Step 3: Bounded Context Detection

Use the Glob tool to detect DDD layers:

• Glob("src/Domain/**"), Glob("src/Application/**"), Glob("src/Infrastructure/**"), Glob("src/Presentation/**")

If no DDD directories found, say "No DDD structure detected."

Use the Glob tool to detect bounded contexts:

• Glob("src/*/") - list top-level directories under src/, excluding Domain/Application/Infrastructure/Presentation/vendor/node_modules

Step 4: Count Files by Layer

Use the Glob tool to count files per DDD layer:

• Glob("src/Domain/**/*") → count results → "Domain: N files"
• Glob("src/Application/**/*") → count results → "Application: N files"
• Glob("src/Infrastructure/**/*") → count results → "Infrastructure: N files"
• Glob("src/Presentation/**/*") → count results → "Presentation: N files"

If no layered structure found, say so.

Use the Glob tool to count frontend files:

• Glob("src/components/**/*"), Glob("src/hooks/**/*"), Glob("src/pages/**/*"), Glob("src/services/**/*")
• Only display directories with count > 0

Step 5: Output Recommendation

Present findings as:

## Codebase Analysis

### Bounded Contexts Found
<list each context with file count>

### Stack
- Backend: <detected stack and versions>
- Frontend: <detected stack and versions>
- AI/ML: <detected if present>

### Recommended Team

For this codebase, I recommend:
<agent list with rationale>

### Suggested Workflow
<workflow type with reasoning>

### Next Step
Run `/craftsman:team create` and select the recommended template,
or let me generate a custom config based on this analysis.

/craftsman:team list {#team-list}

Step 1: List Built-in Templates

Use the Glob tool: Glob("teams/templates/*.yml"). Extract template names from the file paths. If no files found, say "No templates directory found."

For each template found, read and display:

• Name and description
• Agent count and roles
• Workflow type
• Trigger guidance

Step 2: List Custom Teams

Use the Glob tool: Glob("teams/*.yml"). Exclude files under teams/templates/. Extract team names from the file paths. If no files found, say "No custom teams configured yet."

For each custom team found, display:

• Name and purpose
• Agent count
• Creation date (from file mtime if available)

Step 3: List Active Teams

!ls ~/.claude/teams/*.json 2>/dev/null | xargs -I{} basename {} .json | grep . || echo "No active teams running."

For each active team:

• Read the config to show member count and status
• Show task completion progress via TaskList

Step 4: Display Summary

Available Teams
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

BUILT-IN TEMPLATES
  code-review    (3 agents) - PR reviews, quality audits
  feature        (3 agents) - Full-stack feature implementation
  security-audit (3 agents) - Pre-release security checks

CUSTOM TEAMS
  <name>         (<n> agents) - <purpose>
  (none yet)

ACTIVE TEAMS
  <name>         (<n> members) - <status>
  (none running)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Run /craftsman:team create to build a new team.
Run /craftsman:team context to get a recommendation.

Workflow Tool Variant (explicit opt-in)

Native teams above are imperative: this skill spawns and steers each teammate. When the user explicitly asks for scripted orchestration ("use a workflow", "fan out agents", "ultracode"), offer the native Workflow tool instead: a deterministic pipeline script (find then verify stages, resume cache, budget guards) that fits fixed-shape fan-outs like multi-dimension review or migration sweeps. The offer is user-triggered, never the default: a workflow can spawn dozens of agents, and that scale is the user's call (context budgets, ADR-0021). Teams stay the answer for exploratory, conversational collaboration; the Workflow tool is for pipelines whose stages are known before launch.

Help (no subcommand)

/craftsman:team - Agent Team Manager (Native Teams)

SUBCOMMANDS
  /craftsman:team create   - Interactive team builder (spawns named teammates)
  /craftsman:team context  - Analyze codebase and get team recommendation
  /craftsman:team list     - List templates, custom teams, and active teams

EXAMPLES
  /craftsman:team create                → guided team assembly
  /craftsman:team create feature        → fast-track feature template
  /craftsman:team context               → analyze this repo first
  /craftsman:team list                  → see what's available

REQUIREMENTS
  - settings.json: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1   (the only gate)

OPTIONAL
  - settings.json: teammateMode: "in-process" (default) | "auto" | "tmux" | "iterm2"
    Display only. Split panes need tmux, or iTerm2 with the it2 CLI.