Swarming Batch Task Execution

Executes all remaining tasks using agent teams for context isolation. Each task runs in a separate teammate session with its own context window. Teammates are full Claude Code sessions that can spawn subagents (Plan, task-executor, 9 validators), solving the context accumulation problem of inline batch execution.

When to use this vs /groundwork:just-do-it:

• Use this (/groundwork:just-do-it-swarming) for large batches (>5 tasks) where context accumulation is a concern
• Use /groundwork:just-do-it for small batches or when agent teams are not available

Requirement: Agent teams must be enabled (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1" in settings.json env section).

Model: Teammates spawn with model: "opus" for extended context.

Pre-flight: Model Recommendation

Your current effort level is {{effort_level}}.

Skip this step silently if effort is high, xhigh, or max (the scale is low < medium < high < xhigh < max, so xhigh and max are already above high) AND you are Sonnet or Opus. If effort is low or medium (i.e. below high), you MUST show the recommendation prompt — regardless of model. If you are not Sonnet or Opus, you MUST show the recommendation prompt - regardless of effort level.

Otherwise → use AskUserQuestion:

{
  "questions": [{
    "question": "Do you want to switch? Team orchestration with worktree coordination across agents benefits from consistent reasoning.\n\nTo switch: cancel, run `/effort high` (and `/model sonnet` if on Haiku), then re-invoke this skill.",
    "header": "Recommended: Sonnet or Opus at high effort",
    "options": [
      { "label": "Continue" },
      { "label": "Cancel — I'll switch first" }
    ],
    "multiSelect": false
  }]
}

If the user selects "Cancel — I'll switch first": output the switching commands above and stop. Do not proceed with the skill.

Workflow

Step 0: Resolve Project Context

Before loading tasks, ensure project context is resolved:

0. Explicit project argument (highest precedence): If the invocation arguments include --project <name> and <name> is configured in .groundwork.yml, that project is authoritative for this entire run. Resolve its root directly from .groundwork.yml (<repo root>/<configured path>); do not read or consult {{project_name}}.
   • Do NOT invoke select-project, do NOT persist or change the stored selection, and do NOT run the CWD mismatch check below. Other sessions may be running concurrently on different packages and must not be disturbed by a global switch.
   • Substitute the resolved project's paths for the template vars everywhere below: <project root>/specs for {{specs_dir}} and <project root>/.groundwork-plans for {{plans_dir}}.
   • Thread the project explicitly through every downstream invocation instead of relying on the shared selection: call the worktree helper as node ${CLAUDE_PLUGIN_ROOT}/lib/worktree-identity.js TASK-NNN --project <name>, prefix other lib calls with GROUNDWORK_PROJECT=<name>, and record the project in each teammate spawn prompt (ACTIVE PROJECT: line) so teammates resolve the same project.
   • Then skip directly to Step 1.
1. Monorepo check: Does .groundwork.yml exist at the repo root?
   • If yes → Is {{project_name}} non-empty?
     • If empty → Invoke Skill(skill="groundwork:select-project") to select a project, then restart this skill. (select-project is interactive setup for a single session — never run it when an explicit --project was provided; item 0 already resolved the project in that case.)
     • If set → Project is {{project_name}}, specs at {{specs_dir}}/.
   • If no → Continue (single-project repo).
2. CWD mismatch check (monorepo only):
   • Skip if not in monorepo mode or if the project was just selected in item 1 above.
   • If CWD is the repo root → fine, proceed.
   • Check which project's path CWD falls inside (compare against all projects in .groundwork.yml).
   • If CWD is inside the selected project's path → fine, proceed.
   • If CWD is inside a different project's path → warn via AskUserQuestion:

     "You're working from <cwd> (inside [cwd-project]), but the selected Groundwork project is [selected-project] ([selected-project-path]/). What would you like to do?"

     • "Switch to [cwd-project]"
     • "Stay with [selected-project]" If the user switches, invoke Skill(skill="groundwork:select-project").

   • If CWD doesn't match any project → proceed without warning (shared directory).
3. Proceed with the resolved project context. All {{specs_dir}}/ paths will resolve to the correct location.

Step 1: Load and Analyze Tasks

1. Read the tasks file to find all tasks:
   • Single file: {{specs_dir}}/tasks.md
   • Directory: {{specs_dir}}/tasks/ (aggregated in sorted order)
2. Parse all tasks and extract:
   • Task ID (e.g., TASK-001)
   • Title
   • Status (Not Started, In Progress, Complete, Blocked)
   • Dependencies (Blocked by: field)
3. Build dependency graph and calculate execution order:
   • Topological sort respecting dependencies
   • Blocked tasks cannot execute until dependencies complete
4. Sweep and resume gate: Run node ${CLAUDE_PLUGIN_ROOT}/lib/task-resume.js sweep (add --project <name> in monorepos) and auto-clean only the cleanable entries per ${CLAUDE_PLUGIN_ROOT}/references/task-resume-protocol.md. An In Progress task whose node ${CLAUDE_PLUGIN_ROOT}/lib/task-resume.js check <TASK-NNN> reports existing work is in flight from a prior session — assign it to a teammate before any Not Started task (the embedded workflow's resume gate continues it at the right phase).

Detection: Check for file first (takes precedence), then directory.

Step 2: Present Summary and Confirm

Present a summary to the user:

Swarming Batch Execution Summary

Mode: Agent Teams (swarming) Total tasks: X Already complete: Y Remaining: Z

Context Isolation

Each task runs in a separate teammate session with its own context window:

• Teammates are full Claude Code sessions with the complete system prompt
• Each teammate can spawn subagents (Plan, task-executor, 9 validation agents)
• Context is fully isolated between tasks — no accumulation in the lead's conversation
• Changes merged after each task completes

Worktree Isolation

Each task also executes in an isolated git worktree:

• Branch and working directory: resolved per task via the worktree-identity helper (node ${CLAUDE_PLUGIN_ROOT}/lib/worktree-identity.js TASK-NNN) — project-qualified in monorepos (task/<project>/TASK-NNN, <repo>/.worktrees/<project>-TASK-NNN)
• Branch created from current HEAD
• Changes merged automatically after each task completes successfully
• Worktrees cleaned up after successful merge

Execution Order

1. TASK-NNN: [Title]
2. TASK-NNN: [Title] ...

Blocked Tasks (will execute after dependencies complete)

• TASK-NNN: [Title] (blocked by TASK-XXX)

Ask for confirmation before proceeding.

If user declines, stop and suggest alternatives:

• /groundwork:just-do-it for inline execution (no agent teams required)
• /groundwork:work-on N to work on a specific task
• /groundwork:work-on-next-task to work on just the next available task

Step 2.5: Validate Agent Teams Enabled

Before creating the team, verify agent teams are available by checking if the team creation tools are accessible.

If agent teams are not enabled:

"Agent teams are required for swarming mode but are not enabled. To enable them, add this to your settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Alternatively, use /groundwork:just-do-it for inline batch execution (no agent teams required)."

Stop here if not enabled.

Step 2.7: Load Execute-Task Workflow

Before spawning any teammates, load the work-on skill content so it can be embedded in each teammate's prompt:

1. Find the skill file: Use Glob to find **/work-on/SKILL.md within the groundwork plugin directory.
2. Read the file: Use the Read tool to read the entire file.
3. Extract the body: Skip the YAML frontmatter (the --- delimited block at the top of the file) and keep everything after it. This is the work-on workflow content.
4. Store as EXECUTE_TASK_WORKFLOW: Hold this content for use in the teammate spawn prompts below.

CRITICAL: Embed the workflow VERBATIM. Do not summarize, condense, rewrite, or adapt the workflow text. The teammate needs the full, unmodified workflow to follow it step-by-step. Summarization loses gate conditions (e.g. mandatory validation before merge) that prevent broken tasks from being merged.

Step 3: Create Team and Execute

Determine execution mode from the user's argument or request:

• Sequential (default): One task at a time, each in its own teammate session. Clean context per task.
• Parallel (if --parallel argument or user requests it): Independent tasks execute simultaneously in separate teammates.

Sequential Mode (Default)

Create an agent team. Then for each remaining task in dependency order:

1. Read the task section from {{specs_dir}}/tasks.md (or aggregated from {{specs_dir}}/tasks/) to extract the full task definition (goal, action items, acceptance criteria, dependencies).
2. Announce start: "Starting TASK-NNN: [Title] (teammate session)"
3. Update task status to **Status:** In Progress in the tasks file.

4. Spawn a teammate with model: "opus" to execute the task. The teammate's spawn prompt must include:

   You are executing a single task as part of an automated batch run.
   
   GROUNDWORK_BATCH_MODE=true — do NOT use AskUserQuestion. Proceed automatically.
   
   PROJECT ROOT: [absolute path to project root]
   SPECS DIR: {{specs_dir}}
   ACTIVE PROJECT: [project name from Step 0 — teammates must use this project, not change the shared selection]
   
   TASK IDENTIFIER: TASK-NNN
   TASK TITLE: [Title]
   
   TASK DEFINITION:
   [Full task section from tasks file: goal, action items, acceptance criteria, dependencies]
   
   EXECUTE-TASK WORKFLOW:
   [EXECUTE_TASK_WORKFLOW loaded in Step 2.7]
   
   INSTRUCTIONS:
   1. Follow the EXECUTE-TASK WORKFLOW above starting from Step 1 (Parse Task Identifier).
      - Skip Step 0 (context already resolved by the lead) — but still run its
        resume gate item for this task: `node ${CLAUDE_PLUGIN_ROOT}/lib/task-resume.js check TASK-NNN`
        (add `--project <name>` in monorepos) and act on the one-line JSON per
        `${CLAUDE_PLUGIN_ROOT}/references/task-resume-protocol.md` (skip the
        phases it says are done; stand down when live_owner is not none).
      - TASK IDENTIFIER and TASK DEFINITION are provided above — use them directly.
      - GROUNDWORK_BATCH_MODE is true — auto-proceed all confirmations.
   2. When all the steps of the workflow are complete, report:
      - Success: "TASK-NNN: SUCCESS — [one-line summary]"
        Include validation results per agent:
        VALIDATION: code-quality=[N] test-quality=[N] security=[N] spec-alignment=[N] architecture=[N] simplification=[N] housekeeping=[N] performance=[N] design-consistency=[N]
        (where [N] is the number of iterations each agent required to pass)
      - Failure: "TASK-NNN: FAILURE — [one-line reason]"

5. Wait for teammate to complete. Monitor via the shared task list.
6. Collect result from the teammate's completion message.
7. Verify workflow compliance: Parse the teammate's completion message for validation evidence.
   • Look for the VALIDATION: line with per-agent iteration counts (e.g., code-quality=2 test-quality=1 ...).
   • If the validation line is present: proceed to step 8.
   • If the validation line is missing: send the teammate a correction via SendMessage:

     "Your completion report is missing the VALIDATION line with per-agent iteration counts. Run the validation loop (Step 7.5 of the work-on workflow) and report back with: VALIDATION: code-quality=[N] test-quality=[N] security=[N] spec-alignment=[N] architecture=[N] simplification=[N] housekeeping=[N] performance=[N] design-consistency=[N]"

   • Wait for the teammate to respond and re-collect the result.
   • If the teammate's second response still lacks the validation line: mark the task as failed with reason "Teammate did not complete validation".
8. Update task status:
   • Success → **Status:** Complete in the tasks file
   • Failure → STOP immediately (see failure handling below)
9. Shut down the teammate before spawning the next one. This ensures each task gets a completely clean context.
10. Log result: "Completed TASK-NNN: [Title] — [one-line summary]"

On Failure: Report the failed task, reason, tasks completed this session, and tasks remaining. Note that the failed task's worktree is preserved at its reported <worktree_path> for investigation. Clean up the team.

Parallel Mode (--parallel)

1. Build dependency groups: Partition tasks into levels based on the dependency graph. Level 0 = tasks with no dependencies. Level 1 = tasks whose dependencies are all in Level 0. Etc.

2. Process one level at a time:

   For each dependency level:

   a. Determine the independent tasks in this level that are not yet complete.

   b. Cap concurrency: Spawn at most 5 teammates simultaneously (to control token cost). If more tasks than the cap, queue the rest.

   c. Spawn teammates for each task in the level, each with model: "opus" and the same spawn prompt as sequential mode.

   d. Wait for all teammates in this level to complete. As teammates finish, collect results. If any task fails, stop spawning new teammates but let running teammates finish.

   e. Verify workflow compliance for each teammate before shutting it down:

   • Parse the teammate's completion message for the VALIDATION: line with per-agent iteration counts.
   • If present: update task status to Complete.
   • If missing: send the teammate a correction via SendMessage:

     "Your completion report is missing the VALIDATION line with per-agent iteration counts. Run the validation loop (Step 7.5 of the work-on workflow) and report back with: VALIDATION: code-quality=[N] test-quality=[N] security=[N] spec-alignment=[N] architecture=[N] simplification=[N] housekeeping=[N] performance=[N] design-consistency=[N]"

   • Wait for the teammate to respond and re-check.
   • If the teammate's second response still lacks the validation line: mark the task as failed with reason "Teammate did not complete validation".

   f. Shut down all teammates in this level before proceeding to the next.

3. Continue to next dependency level only after all tasks in the current level are complete.

On Failure in Parallel Mode: Report the failed task(s). If multiple tasks in the same level fail, report all of them. Stop processing further levels. Clean up the team.

Step 4: Completion Report

Clean up the agent team, then report:

## Swarming Batch Execution Complete

**Mode:** Agent Teams (swarming)

**Session Summary:**
- Tasks completed: X
- Total tasks complete: Y/Z
- All worktrees merged and cleaned up
- Agent team cleaned up

### Completed Tasks
| Task | Title | Branch | Status |
|------|-------|--------|--------|
| TASK-001 | [Title] | task/TASK-001 | Merged |
| TASK-002 | [Title] | task/TASK-002 | Merged |
...

### Worktree Summary
- Worktrees created: X
- Successfully merged: X
- Cleaned up: X

### Context Isolation Summary
- Teammate sessions spawned: X
- Each task ran in its own context window
- Lead context remained clean throughout execution

### Next Steps
- Run `/source-product-specs-from-code` to update specs with any implementation changes
- Plan next phase if milestone complete
- Review merged changes with `git log --oneline -10`

Edge Cases