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":

  "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  

• Or set the environment variable before running Claude Code:

  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:

   • Plans directory -- base path where project plans are saved
   • Code patterns -- path to the directory containing stored pattern documentation
   • Template path -- path to the report template set (JSON templates)
   • Template version -- plugin version the templates were copied from (if present)
   • Template updates -- user preference: ask, auto, or manual (if present)
   • 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.

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

3. 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/
   

4. If the project directory is missing, suggest running /arn-code-save-plan first

5. If PROGRESS_TRACKER.json is missing, warn that progress tracking will not be available. Execution can still proceed.

6. Call TaskList to check for existing tasks

   • If no tasks exist, tell the user to run /arn-code-taskify first

   • 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
   • Block REVIEW-N on IMPL-N via TaskUpdate with addBlockedB