Team Plan Skill

Multi-agent planning with wave-based parallelization. Spawns 2-3 teammates to generate alternative plans, then synthesizes into a final plan with trade-off analysis.

IMPORTANT: This skill requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable. If team creation fails, gracefully degrades to single-agent planning via skill-planner.

Context References

Reference (load as needed during synthesis):

• Path: .claude/context/patterns/team-orchestration.md - Wave coordination patterns
• Path: .claude/context/formats/team-metadata-extension.md - Team result schema
• Path: .claude/context/formats/return-metadata-file.md - Base metadata schema
• Path: .claude/context/reference/team-wave-helpers.md - Reusable wave patterns

Trigger Conditions

This skill activates when:

• /plan N --team is invoked
• Task exists and status allows planning
• Team mode is requested via --team flag

Input Parameters

Model Selection: Determine teammate model early:

bash
1# Use model_flag if provided, otherwise default to sonnet (cost-effective for team mode)
2teammate_model="${model_flag:-sonnet}"
3model_preference_line="Model preference: Use Claude ${teammate_model^} 4.6 for this task."

Execution Flow

Stage 1: Input Validation

Validate required inputs:

• task_number - Must exist in state.json
• team_size - Clamp to range [2, 3], default 2

bash
1# Lookup task
2task_data=$(jq -r --argjson num "$task_number" \
3  '.active_projects[] | select(.project_number == $num)' \
4  specs/state.json)
5
6if [ -z "$task_data" ]; then
7  return error "Task $task_number not found"
8fi
9
10# Extract fields
11task_type=$(echo "$task_data" | jq -r '.task_type // "general"')
12status=$(echo "$task_data" | jq -r '.status')
13project_name=$(echo "$task_data" | jq -r '.project_name')
14description=$(echo "$task_data" | jq -r '.description // ""')
15
16# Validate team_size (2-3 for planning)
17team_size=${team_size:-2}
18[ "$team_size" -lt 2 ] && team_size=2
19[ "$team_size" -gt 3 ] && team_size=3

Stage 2: Preflight Status Update

Update task status to "planning" BEFORE spawning teammates.

Update state.json:

bash
1jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
2   --arg status "planning" \
3   --arg sid "$session_id" \
4  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
5    status: $status,
6    last_updated: $ts,
7    session_id: $sid
8  }' specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json

Update TODO.md: Change status marker to [PLANNING].

Stage 3: Create Postflight Marker

Create marker file to prevent premature termination:

bash
1padded_num=$(printf "%03d" "$task_number")
2mkdir -p "specs/${padded_num}_${project_name}"
3
4cat > "specs/${padded_num}_${project_name}/.postflight-pending" << EOF
5{
6  "session_id": "${session_id}",
7  "skill": "skill-team-plan",
8  "task_number": ${task_number},
9  "operation": "team-plan",
10  "team_size": ${team_size},
11  "reason": "Team planning in progress: synthesis, status update, git commit pending"
12}
13EOF

Stage 4: Check Team Mode Availability

Verify Agent Teams feature is available:

bash
1# Check environment variable
2if [ "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" != "1" ]; then
3  echo "Warning: Team mode unavailable, falling back to single agent"
4  # Fall back to skill-planner (see Stage 4a)
5fi

Stage 4a: Fallback to Single Agent

If team mode is unavailable:

1. Log warning about degradation
2. Invoke skill-planner via Skill tool
3. Pass original parameters
4. Add degraded_to_single: true to metadata
5. Continue with postflight

Stage 5a: Calculate Artifact Number

Read next_artifact_number from state.json and use (current-1) since plan stays in the same round as research:

bash
1# Read next_artifact_number from state.json
2next_num=$(jq -r --argjson num "$task_number" \
3  '.active_projects[] | select(.project_number == $num) | .next_artifact_number // 1' \
4  specs/state.json)
5
6# Plan uses (current - 1) to stay in the same round as research
7# If next_artifact_number is 1 (no research yet), use 1
8if [ "$next_num" -le 1 ]; then
9  artifact_number=1
10else
11  artifact_number=$((next_num - 1))
12fi
13
14# Fallback for legacy tasks: count existing plan artifacts
15if [ "$next_num" = "null" ] || [ -z "$next_num" ]; then
16  padded_num=$(printf "%03d" "$task_number")
17  count=$(ls "specs/${padded_num}_${project_name}/plans/"*[0-9][0-9]*.md 2>/dev/null | wc -l)
18  artifact_number=$((count + 1))
19fi
20
21run_padded=$(printf "%02d" "$artifact_number")
22# run_padded is now the artifact number for this team planning run (e.g., "01")

Note: Team plan does NOT increment next_artifact_number. Only research advances the sequence.

Stage 5b: Load Research Context

Load research report if available:

bash
1padded_num=$(printf "%03d" "$task_number")
2research_content=""
3if [ -n "$research_path" ] && [ -f "$research_path" ]; then
4  research_content=$(cat "$research_path")
5fi

Stage 5: Spawn Planning Wave

Create teammate prompts and spawn wave. Pass artifact_number and teammate_letter to each teammate.

Delegation context for teammates:

json
1{
2  "artifact_number": "{run_padded}",
3  "teammate_letter": "a",
4  "artifact_pattern": "{NN}_candidate-{letter}.md"
5}

Teammate A - Plan Version A (Incremental Delivery):

Create an implementation plan for task {task_number}: {description}

{model_preference_line}

Artifact number: {run_padded}
Teammate letter: a

Focus on incremental delivery with verification at each phase.
Each phase should deliver working, tested functionality.
Consider dependencies between phases.

Research findings:
{research_content}

Output your plan to:
specs/{NNN}_{SLUG}/plans/{run_padded}_candidate-a.md

Format: Standard implementation plan format with:
- Overview
- Phases with status markers [NOT STARTED]
- Tasks with file modifications
- Verification steps per phase
- Estimated effort

Teammate B - Plan Version B (Alternative Boundaries):

Create an alternative implementation plan for task {task_number}: {description}

{model_preference_line}

Artifact number: {run_padded}
Teammate letter: b

Consider different phase boundaries or ordering.
Look for opportunities to parallelize phases.
Focus on risk mitigation through early verification.

Research findings:
{research_content}

Do NOT duplicate Teammate A's exact phase structure.
Provide a meaningfully different approach.

Output your plan to:
specs/{NNN}_{SLUG}/plans/{run_padded}_candidate-b.md

Format: Same as Teammate A

Teammate C - Risk/Dependency Analysis (if team_size >= 3):

Analyze dependencies and risks for implementing task {task_number}: {description}

{model_preference_line}

Artifact number: {run_padded}
Teammate letter: c

Identify:
- Which phases can be parallelized vs must be sequential
- Critical path through the implementation
- High-risk phases requiring extra verification
- External dependencies that could block progress

Research findings:
{research_content}

Output your analysis to:
specs/{NNN}_{SLUG}/plans/{run_padded}_risk-analysis.md

Format: Risk analysis with dependency graph and critical path

Spawn teammates using TeammateTool.

IMPORTANT: Pass the model parameter to enforce model selection:

• Use model: "sonnet" for all tasks

Synthesis uses base number without letter: After all teammates complete, the synthesis plan uses {run_padded}_{slug}.md (e.g., 01_implementation-plan.md).

Stage 6: Wait for Wave Completion

Wait for all teammates to complete or timeout:

Timeout: 30 minutes for Wave 1

While not all complete and not timed out:
  - Check teammate completion status
  - Collect completed results
  - Wait 30 seconds between checks

On timeout:
  - Mark remaining as "timeout"
  - Continue with available results

Stage 7: Collect Teammate Results

Read each teammate's output file:

bash
1teammate_results=[]
2padded_num=$(printf "%03d" "$task_number")
3
4for candidate in a b; do
5  file="specs/${padded_num}_${project_name}/plans/${run_padded}_candidate-${candidate}.md"
6  if [ -f "$file" ]; then
7    teammate_results+=("...")
8  fi
9done
10
11# Also check for risk analysis if team_size >= 3
12if [ "$team_size" -ge 3 ]; then
13  file="specs/${padded_num}_${project_name}/plans/${run_padded}_risk-analysis.md"
14  if [ -f "$file" ]; then
15    teammate_results+=("...")
16  fi
17fi

Stage 8: Synthesize Plans

Lead synthesizes plan candidates:

1. Compare phase structures from candidates A and B
2. Evaluate trade-offs between approaches
3. Incorporate risk analysis (if available)
4. Select best elements from each candidate
5. Identify parallelization opportunities

Trade-off Comparison:

• Phase count and estimated effort
• Risk profile
• Dependency complexity
• Parallelization potential

Stage 9: Create Final Plan

Write synthesized plan:

markdown
1# Implementation Plan: Task #{N}
2
3**Task**: {title}
4**Version**: {run_padded}
5**Created**: {ISO_DATE}
6**Task Type**: {task_type}
7**Mode**: Team Planning ({team_size} teammates)
8
9## Overview
10
11{Synthesized approach based on candidate evaluation}
12
13## Trade-off Analysis
14
15### Candidate A (Incremental Delivery)
16- Phases: {N}
17- Estimated effort: {hours}
18- Strengths: {list}
19- Weaknesses: {list}
20
21### Candidate B (Alternative)
22- Phases: {N}
23- Estimated effort: {hours}
24- Strengths: {list}
25- Weaknesses: {list}
26
27### Selected Approach
28{Explanation of why chosen elements were selected}
29
30## Phases
31
32### Phase 1: {Name} [NOT STARTED]
33
34**Estimated effort**: {hours}
35
36**Objectives**:
371. {Objective}
38
39**Files to modify**:
40- `path/to/file` - {changes}
41
42**Steps**:
431. {Step}
44
45**Verification**:
46- {How to verify}
47
48---
49
50{Additional phases...}
51
52## Dependencies
53
54- {Dependency}
55
56## Risks and Mitigations
57
58| Risk | Impact | Mitigation |
59|------|--------|------------|
60
61## Success Criteria
62
63- [ ] {Criterion}
64
65## Team Planning Metadata
66
67| Teammate | Role | Status |
68|----------|------|--------|
69| A | Incremental plan | completed |
70| B | Alternative plan | completed |

Output to: specs/{NNN}_{SLUG}/plans/{RR}_implementation-plan.md

Stage 10: Update Status (Postflight)

Update task status to "planned":

Update state.json:

bash
1jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
2   --arg status "planned" \
3  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
4    status: $status,
5    last_updated: $ts,
6    planned: $ts
7  }' specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json

Update TODO.md: Change status marker to [PLANNED].

Link artifact:

bash
1padded_num=$(printf "%03d" "$task_number")
2jq --arg path "specs/${padded_num}_${project_name}/plans/${run_padded}_implementation-plan.md" \
3   --arg type "plan" \
4   --arg summary "Team planning with ${team_size} teammates and trade-off analysis" \
5  '(.active_projects[] | select(.project_number == '$task_number')).artifacts += [{"path": $path, "type": $type, "summary": $summary}]' \
6  specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json

Update TODO.md: Link artifact using the automated script:

bash
1bash .claude/scripts/link-artifact-todo.sh $task_number '**Plan**' '**Description**' "$artifact_path"

If the script exits non-zero, log a warning but continue (linking errors are non-blocking).

Stage 11: Write Metadata File

Write team execution metadata:

json
1{
2  "status": "planned",
3  "summary": "Team planning completed with {N} teammates",
4  "artifacts": [
5    {
6      "type": "plan",
7      "path": "specs/{NNN}_{SLUG}/plans/{RR}_implementation-plan.md",
8      "summary": "Implementation plan with trade-off analysis"
9    }
10  ],
11  "team_execution": {
12    "enabled": true,
13    "wave_count": 1,
14    "teammates_spawned": {team_size},
15    "teammates_completed": {completed_count},
16    "teammates_failed": {failed_count},
17    "token_usage_multiplier": 5.0,
18    "degraded_to_single": false
19  },
20  "metadata": {
21    "session_id": "{session_id}",
22    "agent_type": "skill-team-plan",
23    "phase_count": {N},
24    "estimated_hours": "{X-Y}"
25  }
26}

Stage 12: Git Commit

Commit using targeted staging:

bash
1padded_num=$(printf "%03d" "$task_number")
2git add \
3  "specs/${padded_num}_${project_name}/plans/" \
4  "specs/${padded_num}_${project_name}/.return-meta.json" \
5  "specs/TODO.md" \
6  "specs/state.json"
7git commit -m "task ${task_number}: complete team planning (${team_size} teammates)
8
9Session: ${session_id}

Stage 13: Cleanup

Remove marker and temporary files:

bash
1padded_num=$(printf "%03d" "$task_number")
2rm -f "specs/${padded_num}_${project_name}/.postflight-pending"
3rm -f "specs/${padded_num}_${project_name}/.return-meta.json"
4# Keep candidate plans for reference

Stage 14: Return Summary

Return brief text summary:

Team planning completed for task {N}:
- Spawned {team_size} teammates for parallel plan generation
- Teammate A: Incremental delivery plan ({N} phases)
- Teammate B: Alternative approach ({N} phases)
- Trade-off analysis completed
- Final plan at specs/{NNN}_{SLUG}/plans/{RR}_implementation-plan.md
- Status updated to [PLANNED]

Error Handling

Team Creation Failure

• Fall back to skill-planner
• Mark degraded_to_single: true
• Continue with single-agent planning

Teammate Timeout

• Continue with available results
• Note timeout in synthesis
• Mark result as partial if critical candidate missing

Git Commit Failure

• Non-blocking: log and continue
• Return success with warning

Return Format

Brief text summary (NOT JSON):

Team planning completed for task 412:
- Spawned 2 teammates for parallel plan generation
- Teammate A: Incremental plan (4 phases, 8-12 hours)
- Teammate B: Alternative plan (3 phases, 6-10 hours)
- Selected: Hybrid approach favoring Candidate A structure with B's parallelization
- Final plan at specs/412_task_name/plans/01_implementation-plan.md
- Status updated to [PLANNED]
- Changes committed with session sess_...

MUST NOT (Postflight Boundary)

After teammates complete and plans are synthesized, this skill MUST NOT:

1. Edit source files - All planning work is done by teammates
2. Run build/test commands - Verification is done by teammates
3. Analyze task requirements - Analysis is teammate work
4. Write plan files - Artifact creation is done during synthesis, not postflight
5. Use research tools - Research is for teammate use only

The postflight phase is LIMITED TO:

• Reading teammate metadata files
• Updating state.json via jq
• Updating TODO.md status marker via Edit
• Linking artifacts in state.json
• Git commit
• Cleanup of temp/marker files

Reference: @.claude/context/standards/postflight-tool-restrictions.md