---
name: execute-phase-bg
description: Background-dispatch variant of execute-phase. Spawns one `claude --bg --agent maxv-executor` session per plan (with auto-worktree) instead of running waves of in-process Agent calls. Frees the main session immediately. Use when the phase has multiple independent plans, the work is long-running, and you want to monitor via `claude agents` instead of staying attached.
when_to_use: |
  Trigger phrases: "/maxvision-orchestration:execute-phase-bg",
  "execute phase in background", "run phase plans async",
  "dispatch phase to claude agents", "execute-phase --bg",
  "long-running phase, free my main session".
disable-model-invocation: true
argument-hint: <phase number> [--limit=N] [--dry-run]
arguments: phase_arg
allowed-tools: Read Grep Glob Bash(test *) Bash(find *) Bash(jq *) Bash(${CLAUDE_PLUGIN_ROOT}/bin/maxv-dispatch *) Skill(execute-phase)
---

# Execute phase in background

Argument: `$phase_arg` — phase number (e.g. `3`) plus optional flags:
- `--limit=N` — cap the number of background sessions dispatched (default: all incomplete plans, max 10)
- `--dry-run` — print the dispatch plan without invoking claude

This skill is the **async cousin** of `execute-phase`. It does NOT replace
the wave-of-N synchronous executor; it adds an opt-in path for users who
prefer Agent View workflow over inline subagent dispatch.

## When to use which

| Property | `execute-phase` | `execute-phase-bg` |
| --- | --- | --- |
| Dispatch model | Synchronous wave-of-N Agent() calls | One `claude --bg` per plan |
| Main thread | Blocked until all plans return | Free immediately |
| Monitoring | Inline progress | `claude agents` UI |
| Worktree | Per maxv-executor (via `isolation: worktree`) | Auto-isolated by CC for each --bg session |
| Token cost | Within parent session quota | Independent session quotas (multiplies) |
| Best for | Wave coordination, quick plans (<5 min each) | Long-running plans you'll review later |
| Failure recovery | Surfaces in conversation | Surfaces in `claude agents` row |

## Hard rules

1. **Manual confirmation required.** Dispatch plan must be approved with `sim`.
2. **Cap at 10 parallel sessions** by default. Each session has independent token quota — fanning out to 30 plans will burn through subscription limits quickly. Override with `--limit=N` and an explicit `--accept-cost` flag.
3. **Refuse on dirty working tree.** Each background session creates its own worktree from `origin/HEAD`; uncommitted changes in the main checkout are NOT carried in.
4. **Refuse if `bin/maxv-dispatch` is missing.** This skill is a thin wrapper; without the CLI, fall back to recommending `execute-phase` (sync).
5. **Refuse if CC < 2.1.139.** Agent View prerequisite.

## Render-time preflight

- claude binary: !`which claude >/dev/null 2>&1 && echo "OK" || echo "MISSING"`
- claude version: !`claude --version 2>/dev/null | head -1 || echo "unknown"`
- maxv-dispatch:  !`test -f "${CLAUDE_PLUGIN_ROOT:-/missing}/bin/maxv-dispatch" && echo "OK" || echo "MISSING"`
- working tree:   !`test -z "$(git status --porcelain 2>/dev/null)" && echo "CLEAN" || echo "DIRTY"`
- phase dir hint: !`find .maxvision -maxdepth 2 -type d -name 'phase-*' 2>/dev/null | head -3 || echo "(no .maxvision/phase-*)"`

## Workflow

### 1. Honor preflight

Abort if any check fails:

```json
{"status":"aborted","reason":"<missing|too_old|dirty|no_phase>","next_step":"<remediation>"}
```

### 2. Parse arguments

Extract `PHASE_NUMBER`, `LIMIT` (default 10), `DRY_RUN` (default 0),
`ACCEPT_COST` (default 0). Reject unknown flags with rc=2.

If `LIMIT > 10` and `--accept-cost` is NOT set, abort with a structured
warning explaining the cost multiplier.

### 3. Resolve plans

For phase N, plans live in `.maxvision/phase-${PHASE_NUMBER}/plans/*.md`.
Read each plan file's frontmatter to filter:

- Skip plans with `status: completed` (already done).
- Skip plans with `status: blocked` (require prior unblocking).
- Include plans with `status: pending` or no frontmatter status field.

Cap the resulting list at `LIMIT`.

### 4. Show dispatch plan

```
About to dispatch <K> background sessions for phase <N>:

  Phase:        <N>
  Plans:        <K> of <total-incomplete>
  Cap:          <LIMIT>
  Each session: claude --bg --agent maxv-executor --worktree --name="phase<N>-plan<i>"
  Worktrees:    .claude/worktrees/phase<N>-plan<i>/ (auto-created per session)
  Token cost:   approximately <K> × <per-plan-estimate>

Plans to dispatch:
  - .maxvision/phase-<N>/plans/plan-001-...md
  - .maxvision/phase-<N>/plans/plan-002-...md
  ...

Proceed? [sim/skip]
```

Wait for explicit `sim`. On `skip`, exit 0 with `{"status":"skipped"}`.

### 5. Dispatch in sequence

For each plan, invoke `bin/maxv-dispatch run`. Issue dispatches
sequentially (one shell call per message) to avoid `.git/config.lock`
contention during the worktree-creation phase. Once all worktrees are
created, the actual maxv-executor work runs in parallel.

```bash
set -euo pipefail
${CLAUDE_PLUGIN_ROOT}/bin/maxv-dispatch run maxv-executor \
  "Execute plan: ${plan_path}. Read the plan, apply each task atomically, commit per task, produce SUMMARY.md." \
  --worktree="phase${PHASE}-plan${i}" \
  --name="phase${PHASE}-plan${i}"
```

Capture each session ID. Build a manifest at
`.maxvision/phase-${PHASE_NUMBER}/bg-dispatch.json`:

```json
{
  "phase": <N>,
  "dispatched_at": "<ISO8601>",
  "sessions": [
    {"plan": "plan-001-...md", "session_id": "abc12345", "name": "phase3-plan1"},
    ...
  ]
}
```

### 6. Report

```
✓ Dispatched <K> background sessions for phase <N>.

  Watch all:   maxv-dispatch status   (or `claude agents`)
  Attach one:  maxv-dispatch attach <id>
  Logs:        maxv-dispatch logs <id>
  Stop one:    maxv-dispatch stop <id>
  Stop all:    (manual: stop each id, no batch op)

Manifest written to .maxvision/phase-<N>/bg-dispatch.json

Recommended verification once all sessions report ✓ in `claude agents`:
  /maxvision-orchestration:verify-work
```

## Output JSON

```json
{
  "status": "dispatched",
  "phase": <N>,
  "session_count": <K>,
  "manifest_path": ".maxvision/phase-<N>/bg-dispatch.json",
  "next_step": "Monitor via `maxv-dispatch status` or `claude agents`"
}
```

## Sibling skills

- [`execute-phase`](../execute-phase/SKILL.md) — synchronous wave-of-N
- [`dispatch-background`](../dispatch-background/SKILL.md) — single-agent
  background dispatch for ad-hoc tasks
- [`verify-work`](../verify-work/SKILL.md) — goal-backward verification
  after background sessions report `Ready for review`