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

  "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 addBlockedBy
   • Preserve original dependency chain for IMPL tasks

This creates pairs:

IMPL-1 (unblocked) -> REVIEW-1 (blocked by IMPL-1)
IMPL-2 (blocked by IMPL-1) -> REVIEW-2 (blocked by IMPL-2)
...

Executor teammates claim IMPL tasks via TaskUpdate (set status to in_progress). Reviewer teammate claims REVIEW tasks as they unblock.

Step 5: Monitor and Coordinate

The lead (main session) monitors:

• Task list progress -- call TaskList periodically (every 30-60 seconds) to check for stalled tasks
• Progress tracker -- after each task is marked completed by the reviewer, the lead reads <project-folder>/PROGRESS_TRACKER.json, updates the matching phase entry status to "completed" with a completedAt timestamp and the review verdict/cycles, and writes it back to disk. This keeps the tracker current during team execution.
• Teammate health -- if a teammate goes idle unexpectedly, investigate
• Review outcomes -- if reviewer reports needs-fixes:
  • The reviewer messages the executor directly with findings
  • Executor fixes, reviewer re-reviews
  • If fix cycle exceeds 2 iterations, lead intervenes and escalates to user
• Architect activation -- if architect remains idle but should be consulted, the lead can message the reviewer to consult the architect on a specific issue

Intervention triggers:

• Teammate idle for extended period with pending tasks available
• Circular messaging (executor and reviewer stuck in a loop)
• All REVIEW tasks returning needs-fixes repeatedly
• Any teammate crash or error

Step 6: Completion

When all IMPL and REVIEW tasks are completed:

• Finalize PROGRESS_TRACKER.json:
  • Read <project-folder>/PROGRESS_TRACKER.json
  • Verify all phase statuses are up to date (set any remaining phases with completed IMPL/REVIEW tasks to "completed")
  • Set overallStatus to "completed" and update lastUpdated
  • Write PROGRESS_TRACKER.json to disk
• If the project has ### Visual Testing configured in CLAUDE.md, include a visual testing summary: screenshots captured, baselines updated, visual diffs detected. Note any Layer 1 visual regressions that were flagged during execution.

Pattern refresh (auto): After finalizing progress tracking, refresh stored pattern documentation.

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-execute-plan/references/pattern-refresh.md and follow the pattern refresh procedure.

This is automatic and non-blocking. If the refresh fails, note it in the summary but do not block completion.

• Present summary: total tasks, pass rate on first review, fix cycles needed, reports generated
• Show: "Progress tracker finalized in <project-folder>/PROGRESS_TRACKER.json"
• List all reports in <project-folder>/reports/
• Note token usage if available
• Offer: "Would you like to run /arn-code-review-implementation for a full project review?"

Error Handling

• Agent Teams not enabled -- provide setup instructions, suggest /arn-code-execute-plan as alternative
• ## Arness config missing in CLAUDE.md -- suggest running /arn-implementing to get started
• Project directory missing -- suggest running /arn-code-save-plan to create the project structure
• No tasks in TaskList -- suggest running /arn-code-taskify to convert TASKS.md into tasks
• Teammate crashes -- lead reports issue, suggests retrying the failed task or falling back to subagent mode (/arn-code-execute-plan)
• Teammates deadlocked -- lead intervenes with clarifying message, breaks the cycle
• Executor and reviewer stuck in fix loop (>2 cycles) -- lead escalates to user with findings
• Architect unresponsive -- lead messages architect directly, or provides architectural guidance itself based on pattern docs
• Token budget exceeded -- warn user, suggest completing remaining tasks with /arn-code-execute-plan (lower cost)
• Task list inconsistency -- if IMPL/REVIEW pairs get out of sync, lead reconciles by checking task statuses and re-aligning

Cost Considerations

Agent Teams use significantly more tokens than the subagent-based arn-code-execute-plan. Expect:

• ~3-4x tokens for a 3-teammate team working 30 minutes
• ~5-7x tokens when teammates use plan mode extensively
• Each teammate is a full Claude Code session with its own context window

To keep costs manageable:

• All teammates use Opus. The architect's cost is justified by its strategic role — it stays idle until consulted.
• Shut down the team promptly when all tasks complete
• For simpler projects (fewer than 5 tasks, no complex dependencies), prefer /arn-code-execute-plan instead