skill-team-implement

# Team Implement Skill Multi-agent implementation with wave-based phase parallelization. Analyzes phase dependencies to identify parallelization opportunities, spawns teammates for independent phases, and coordinates sequential execution of dependent phases. **IMPORTANT**: This skill requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` environment variable. If team creation fails, gracefully degrades to single-agent implementation via skill-implementer. ## Context References Reference (load as needed during coordination): - 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: - `/implement N --team` is invoked - Task exists and has implementation plan - Team mode is requested via --team flag ## Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `task_number` | integer | Yes | Task to implement | | `plan_path` | string | Yes | Path to implementation plan | | `resume_phase` | integer | No | Phase to resume from | | `team_size` | integer | No | Max concurrent teammates (2-4, default 2) | | `session_id` | string | Yes | Session ID for tracking | | `model_flag` | string | No | Model override (haiku, sonnet, opus, fable). If set, use instead of default | | `effort_flag` | string | No | Effort level (fast, hard). Passed as prompt context | **Model Selection**: Determine teammate model early: ```bash # Use model_flag if provided, otherwise default to sonnet (cost-effective for team mode) teammate_model="${model_flag:-sonnet}" model_preference_line="Model preference: Use Claude ${teammate_model^} for this task." ``` --- ## Execution Flow ### Stage 1: Input Validation Validate required inputs: - `task_number` - Must exist in state.json - `plan_path` - Must exist and contain phases - `team_size` - Clamp to range [2, 4], default 2 ```bash # Lookup task task_data=$(jq -r --argjson num "$task_number" \ '.active_projects[] | select(.project_number == $num)' \ specs/state.json) if [ -z "$task_data" ]; then return error "Task $task_number not found" fi # Extract fields task_type=$(echo "$task_data" | jq -r '.task_type // "general"') status=$(echo "$task_data" | jq -r '.status') project_name=$(echo "$task_data" | jq -r '.project_name') # Validate plan exists if [ ! -f "$plan_path" ]; then return error "Plan not found: $plan_path" fi # Validate team_size team_size=${team_size:-2} [ "$team_size" -lt 2 ] && team_size=2 [ "$team_size" -gt 4 ] && team_size=4 ``` --- ### Stage 2 + Stage 3: Preflight Status Update and Postflight Marker Source `skill-base.sh` once, then follow `@.claude/context/patterns/skill-preflight-flow.md` in full for Stage 2 (preflight status update) and Stage 3 (marker creation): ```bash source .claude/scripts/skill-base.sh padded_num=$(printf "%03d" "$task_number") skill_name="skill-team-implement" operation="implement" ``` **Routing fix**: this call replaces a hand-rolled `state-write.sh` status write with `update-task-status.sh preflight` (via `skill_preflight_update`), which regenerates TODO.md internally — TODO.md's Task Order block is therefore no longer stale for the whole duration of a team run, since it is now refreshed at preflight, not only at postflight. `operation="implement"` (not `"team-implement"`) is required here: `update-task-status.sh`'s `target_status` vocabulary has no `team-implement` value, so this skill maps onto the plain `implement` operation, same as `skill-implementer`. **Marker unification note**: this skill's marker previously carried "Shape D" — a `team_size` field and no `created`/`stop_hook_active`. `skill_create_postflight_marker`'s fixture test asserts an EXACT Shape A key set, so `team_size` is dropped here rather than carried as an extra field; the marker's `operation` field now reads `"implement"` (matching `$operation` above) rather than `"team-implement"`. --- ### Stage 4: Check Team Mode Availability Verify Agent Teams feature is available: ```bash # Check environment variable if [ "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" != "1" ]; then echo "Warning: Team mode unavailable, falling back to single agent" # Fall back to skill-implementer (see Stage 4a) fi ``` --- ### Stage 4a: Fallback to Single Agent If team mode is unavailable: 1. Log warning about degradation. 2. Invoke the underlying single-agent subagent **directly** via the Agent tool (`subagent_type: "general-implementation-agent"`, the same subagent `skill-implementer`'s own Stage 5 invokes) — passing the same task_context/delegation_context/format-specification this skill would otherwise have assembled per-phase-teammate. **Do NOT invoke the whole `skill-implementer` skill**: that would re-run its own full preflight/postflight/continuation lifecycle on top of this skill's, double-writing status and markers, and is the defect this stage previously carried. 3. Add `degraded_to_single: true` to the metadata: record it via `specs/${padded_num}_${project_name}/.degraded-fallback-note.json` (`{"degraded_to_single": true, "reason": "team mode unavailable"}`) before invoking the subagent, and merge that flag into Stage 13's metadata-write content when composing the final team execution summary. 4. Follow `@.claude/context/patterns/skill-self-execution-fallback.md`'s write obligation as Stage 4c below describes: the directly-invoked subagent already writes `.return-meta.json` (satisfying the obligation), so Stage 4c is a no-op in the direct-subagent case. 5. Continue with postflight — the resulting `.return-meta.json` is read exactly like the normal team-implementation path. --- ### Stage 4c: Self-Execution Fallback Follow `@.claude/context/patterns/skill-self-execution-fallback.md` in full. This skill's success status value for that block's write obligation is `"implemented"`. As Stage 4a Step 4 notes, this stage is reached in its "real write" capacity only when this skill performed work inline without invoking any subagent at all. --- ### Stage 4b: Calculate Artifact Number Read `next_artifact_number` from state.json and use (current-1) since summary stays in the same round as research/plan: ```bash # Read next_artifact_number from state.json next_num=$(jq -r --argjson num "$task_number" \ '.active_projects[] | select(.project_number == $num) | .next_artifact_number // 1' \ specs/state.json) # Implement uses (current - 1) to stay in the same round as research/plan # If next_artifact_number is 1 (no research yet), use 1 if [ "$next_num" -le 1 ]; then artifact_number=1 else artifact_number=$((next_num - 1)) fi # Fallback for legacy tasks: count existing summary artifacts if [ "$next_num" = "null" ] || [ -z "$next_num" ]; then padded_num=$(printf "%03d" "$task_number") count=$(ls "specs/${padded_num}_${project_name}/summaries/"*[0-9][0-9]*.md 2>/dev/null | wc -l) artifact_number=$((count + 1)) fi run_padded=$(printf "%02d" "$artifact_number") ``` **Note**: Team implement does NOT increment `next_artifact_number`. Only research advances the sequence. --- ### Stage 5: Analyze Phase Dependencies Parse implementation plan to identify parallelization opportunities. Prefer explicit dependency data from the plan; fall back to heuristic inference for older plans. **Primary: Explicit dependencies** (plans with `**Depends on**:` fields per phase): ```bash # Parse explicit "**Depends on**:" fields from each phase dependency_graph = {} has_explicit_deps = false for phase in phases: depends_on_field = parse_field(phase, "Depends on") if depends_on_field is not None: has_explicit_deps = true if depends_on_field == "none": deps = [] else: deps = [int(x.strip()) for x in depends_on_field.split(",")] dependency_graph[phase.number] = { "status": phase.status, "depends_on": deps } ``` **Fallback: Heuristic inference** (plans without explicit dependency fields): ```bash if not has_explicit_deps: # Build dependency graph from file overlap analysis dependency_graph = {} for phase in phases: dependency_graph[phase.number] = { "status": phase.status, "depends_on": infer_from_file_overlap(phase, phases), "files": phase.files_modified } ``` **Heuristic signals** (fallback only): - Implicit dependencies from file modifications (phases modifying same files are dependent) - Cross-phase imports or references **`infer_from_file_overlap(phase, phases)` definition**: This function applies the shared directory-prefix overlap algorithm defined once in `.claude/context/patterns/file-footprint-overlap.md` (referenced by path — the rule is not restated here). For the given `phase`, compare its declared/inferred file touch-set (parsed from the plan's "Files to modify" list for that phase) pairwise against every other phase in `phases` using the same overlap rule (exact match, or bidirectional directory-prefix containment). Return the list of phase numbers whose file touch-set overlaps with this phase's — those phases must be treated as dependencies (serialized), since concurrent dispatch would risk two phase-implementer sub-agents editing the same file at once. This is the phase-level counterpart to the task-level Component 4a check in `.claude/docs/reference/standards/multi-task-creation-standard.md`; both consume the same canonical algorithm. > **CRITICAL: Plan-Text-Only Analysis** -- Stage 5 analyzes dependencies using file paths and phase descriptions extracted from the plan text. The lead agent MUST NOT read, grep, or glob source files to infer dependencies. All signals come from parsing the plan document itself. Actual source file reading is the exclusive responsibility of phase implementer sub-agents. --- ### Stage 6: Calculate Implementation Waves **Primary: Read wave table from plan** (plans with `**Dependency Analysis**` table): ``` # Parse the Dependency Analysis table from the plan # Format: | Wave | Phases | Blocked by | waves = parse_dependency_analysis_table(plan) if waves is not empty: # Use pre-computed wave groupings directly # Example parsed result: # Wave 1: [1] (blocked by: --) # Wave 2: [2, 3] (blocked by: 1) # Wave 3: [4] (blocked by: 2, 3) ``` **Fallback: Compute from dependency graph** (plans without wave table): ``` if waves is empty: # Topological grouping from dependency_graph (Stage 5 output) Wave 1: Phases with no unfinished dependencies Wave 2: Phases depending on Wave 1 Wave 3: Phases depending on Wave 2 ... Example: Phase 1, 2, 3: No dependencies -> Wave 1 (parallel) Phase 4: Depends on 1, 2 -> Wave 2 Phase 5: Depends on 3 -> Wave 2 Phase 6: Depends on 4, 5 -> Wave 3 ``` --- ### Stage 7: Spawn Phase Implementers For each wave, spawn teammates for parallelizable phases (up to team_size): > **CRITICAL: Template Population from Plan Text Only** -- All template variables (`{phase_details}`, `{files_list}`, `{steps_from_plan}`, `{verification_criteria}`) MUST be populated by extracting text from the plan file. The lead agent MUST NOT read source files, run grep/glob, or use MCP tools to populate these fields. The sub-agent will read source files after it is spawned. **Phase Implementer Prompt Template**: ``` Implement phase {P} of task {task_number}: {phase_name} {model_preference_line} ## Plan Context {phase_details from plan} ## Files to Modify {files_list} ## Steps {steps_from_plan} ## Verification {verification_criteria} ## Instructions 1. Read existing files before modifying 2. Execute steps in order 3. Verify completion with criteria 4. Update phase status in plan file to [COMPLETED] 5. Write results to: specs/{NNN}_{SLUG}/phases/{RR}_phase-{P}-results.md ## On Error If build/test fails: 1. Write error details to results file 2. Mark phase [PARTIAL] instead of [COMPLETED] 3. Return with error context for debugger ``` --- ### Stage 8: Wave Execution Loop Execute waves sequentially, phases within wave in parallel. Detect Y-shaped dependency patterns: when a single-phase "trunk" wave precedes a multi-phase "branching" wave, execute the trunk with a single agent before spawning parallel teammates for the branching waves. ``` # Y-shaped detection: classify each wave as trunk or branching # A trunk wave has 1 phase and is followed by a wave with 2+ phases for i, wave in enumerate(waves): next_wave = waves[i+1] if i+1 < len(waves) else None wave.is_trunk = (len(wave.phases) == 1 and next_wave is not None and len(next_wave.phases) > 1) for wave in waves: if wave.is_trunk: # Trunk wave: execute single phase directly (no team spawning) phase = wave.phases[0] execute_phase_directly(phase) # single agent, no teammate overhead mark_phase_complete(phase) else: # Branching or standard wave: spawn parallel teammates active_teammates = [] for phase in wave.phases[:team_size]: teammate = spawn_phase_implementer(phase) active_teammates.append(teammate) # Wait for wave completion while not all_complete(active_teammates): for teammate in active_teammates: if teammate.complete(): result = teammate.result if result.error: # Spawn debugger for this phase spawn_debugger(phase, result.error) else: mark_phase_complete(phase) # Spawn additional teammates if slots available remaining_phases = wave.phases[len(active_teammates):] for phase in remaining_phases[:team_size - len(active)]: