arn-code-execute-plan-teams

Arness Execute Plan Teams

Execute a structured project plan using Claude Code's experimental Agent Teams feature. Creates a coordinated team of executor, reviewer, and architect teammates that work together on task implementation. Each task goes through an implement->review->gate cycle within the team.

Pipeline position:

arn-code-taskify -> **arn-code-execute-plan-teams** (team: execute -> review -> architect consult -> gate) -> arn-code-review-implementation

This is an alternative to arn-code-execute-plan (subagent-based). Use this when:

• You want tighter executor<->reviewer collaboration (direct messaging between teammates)
• You want an on-call architect for architectural questions during implementation
• You're working on a complex multi-phase project where quality gates matter most
• You accept 3-7x higher token usage for better coordination

Prerequisites

If no ## Arness section exists in the project's CLAUDE.md, inform the user: "Arness is not configured for this project yet. Run /arn-implementing to get started — it will set everything up automatically." Do not proceed without it. Task list must exist (run /arn-code-taskify first).

Workflow

Step 1: Check Agent Teams Availability

Run via Bash: echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

If the variable is not set, is empty, or is set to "0" or "false": Inform the user: "This skill requires Claude Code's experimental Agent Teams feature."

Provide setup instructions:

• Add to ~/.claude/settings.json under "env":

``json "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" ``

• Or set the environment variable before running Claude Code:

``bash CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude ``

Suggest the alternative: "You can use arn-code-execute-plan instead, which uses subagents and doesn't require Agent Teams."

If enabled: proceed to Step 2.

Step 2: Load Configuration and Verify Project

1. Read the project's CLAUDE.md and extract the ## Arness section to find:
2. Plans directory -- base path where project plans are saved
3. Code patterns -- path to the directory containing stored pattern documentation
4. Template path -- path to the report template set (JSON templates)
5. Template version -- plugin version the templates were copied from (if present)
6. Template updates -- user preference: ask, auto, or manual (if present)
7. Specs directory -- path to the directory containing specification files (if present)

Template version check: If Template version and Template updates fields are present, run the template version check procedure documented in arn-code-save-plan Step 1 (Template Version Check) before proceeding. If ## Arness does not contain these fields, treat as legacy and skip.

1. Ask the user for PROJECT_NAME if not provided in the trigger message

1. Verify the project directory exists and contains the required structure:

`` <plans-dir>/<PROJECT_NAME>/ ├── INTRODUCTION.md ├── TASKS.md ├── PROGRESS_TRACKER.json ├── plans/PHASE_*.md └── reports/ ``

1. If the project directory is missing, suggest running /arn-code-save-plan first
2. If PROGRESS_TRACKER.json is missing, warn that progress tracking will not be available. Execution can still proceed.

1. Call TaskList to check for existing tasks
2. If no tasks exist, tell the user to run /arn-code-taskify first
3. If tasks already exist with progress, show state and:

Ask (using AskUserQuestion):

"Tasks already exist with progress. How would you like to proceed?"

Options:

1. Resume -- Continue execution from where it left off, picking up the next pending unblocked task
2. Restart -- Reset task statuses to pending (existing reports will be preserved; confirm before proceeding)

Step 3: Create the Team

Note: Teammates should not claim tasks until Step 4 completes. The lead notifies the team when the task list is structured.

Create ONE team for the entire execution. Determine team size based on the number of unblocked parallel tasks:

• 1-3 unblocked tasks: 1 executor teammate
• 4+ unblocked tasks: 2 executor teammates (more executors add coordination overhead without proportional speedup)

Team composition:

Executor teammate(s) (1-2 instances based on task count):

• Role: Claims pending unblocked IMPL tasks, implements them, writes tests, runs targeted tests
• Spawn prompt includes:
• Project name: <PROJECT_NAME>
• Project folder path: <plans-dir>/<PROJECT_NAME>/
• INTRODUCTION.md path (with instruction to read it first)
• Code patterns directory path (with instruction to read code-patterns.md, testing-patterns.md, architecture.md, and ui-patterns.md if present)
• Phase plan directory path
• Report template path
• Testing instructions: write tests if planned, run ONLY targeted tests (precise test file/function targeting: pytest tests/test_specific.py::TestClass, jest --testPathPattern=specific.test.ts), optionally broader module scope, NEVER full test suite
• Task workflow: claim pending unblocked IMPL tasks from the shared task list via TaskUpdate, implement, test, generate implementation report to <project-folder>/reports/, mark IMPL task as completed via TaskUpdate
• If the project has ### Visual Testing configured in CLAUDE.md, include Layer 1 visual testing config (top-level fields only: capture script path, compare script path, baseline directory, diff threshold) in the spawn prompt. Instruct the executor to capture screenshots after implementing UI tasks, same as the dispatch loop executor.
• Model: Opus

Reviewer teammate (1 instance):

• Role: Claims unblocked REVIEW tasks, validates completed implementations, re-runs tests, classifies findings
• Spawn prompt includes:
• Same project context as executor
• TASK_REVIEW_REPORT_TEMPLATE.json path (from template path directory)
• Review instructions: claim REVIEW tasks when they unblock (after corresponding IMPL completes), read the implementation report, re-run targeted tests, check pattern compliance and acceptance criteria, generate task review report to <project-folder>/reports/
• Verdict logic: pass (mark REVIEW task complete) / pass-with-warnings (append warnings to implementation report, mark complete) / needs-fixes (message the executor directly with specific findings to fix, do NOT mark complete)
• If the executor reported visual capture paths, include them along with Layer 1 visual testing config (top-level fields only: compare script path, baseline directory, diff threshold). Instruct the reviewer to run visual comparison against baselines and classify regressions, same as the dispatch loop reviewer.
• Do NOT modify implementation files -- reviewer uses Bash only for running tests
• Model: Opus

Architect teammate (1 instance, on-call):

• Role: Consulted for architectural disputes, critical design questions, pattern clarification
• Spawn prompt includes:
• architecture.md content (read and include in prompt)
• code-patterns.md content (read and include in prompt)
• ui-patterns.md content (read and include in prompt, if it exists)
• INTRODUCTION.md content (read and include in prompt)
• Instruction: remain idle until messaged by reviewer or executor. When consulted, provide architectural guidance based on documented patterns and decisions. Do not implement code. Do not claim tasks.
• Model: Opus (strategic reasoning)
• Initially idle -- activated only when reviewer or executor messages with an architectural question

Step 4: Structure the Shared Task List

For each existing task in the Claude Code task list, create a corresponding REVIEW task:

For Task N (already in task list):

1. Rename/annotate as IMPL-N: [original description] if needed for clarity
2. Create REVIEW-N: Review implementation of Task N via TaskCreate
3. Block REVIEW-N on IMPL-N via TaskUpdate with addBlockedB