wipnote:execute

What this skill does

# wipnote Parallel Execute

Use this skill to execute development tasks in parallel using dependency-driven dispatch and worktree isolation.

**Trigger keywords:** execute plan, run plan, run tasks, parallelize work, work in parallel, start execution, dispatch agents

---

## Environment

When running in a worktree, `WIPNOTE_PROJECT_DIR` is set automatically. All `wipnote` CLI commands resolve to the main project's `.wipnote/` — no need to `cd` to main. Just run commands directly: `wipnote track show <id>`.

**NEVER use bare `cd` in Bash** — the hook will block it. Use subshells if you must change directories: `(cd dir && command)`.

---

## Efficiency Rules (read before dispatching)

Every tool call spends a turn. The goal is to dispatch the first subagent within **≤5 tool calls**. To hit that budget:

1. **One call, not ten.** Use `wipnote execute-preview <trk-id> --format json` to get the track, linked features/bugs/plans, and current git state in a single invocation. Do not call `wipnote track show`, `wipnote feature show`, `wipnote plan show`, and `git status` separately before the first dispatch.
2. **Batch git-state probes.** If execute-preview doesn't cover a probe you need, chain with `&&` in one Bash call — never one tool call per git subcommand.
3. **Don't feature-show more than twice in a row.** If you find yourself calling `wipnote feature show` for every linked feature, stop and re-read the preview JSON — the status you need is already there.
4. **Don't retry flag variants.** If a flag fails, check the skill for the real flag name before trying a second guess. This skill is validated by a build-time smoke test — prescribed flags are real.

---

## Work Item Attribution (MANDATORY)

Before dispatching any agents, verify attribution is set:

1. **Confirm active feature/track:** `wipnote status` — check "In progress" section
2. **If no active feature:** `wipnote feature start <id>` before proceeding
3. **Each agent prompt MUST include:**
   - `wipnote feature start {feature_id}` as the FIRST command the agent runs
   - `wipnote feature complete {feature_id}` after passing quality gates
4. **Need help?** Run `wipnote help` for available commands

Without attribution, work is invisible to the project graph.

---

## Core Principle: Dependency-Driven Dispatch Loop

Do NOT execute in manual waves. Instead, run a dispatch loop:

```
LOOP:
  1. Query: which tasks are unblocked? (pending + no blockedBy)
  1.5. Check file overlap among unblocked tasks → partition into non-conflicting waves
  2. Dispatch non-overlapping unblocked tasks in a single message (parallel agents)
  3. Wait for agents to complete
  4. Merge completed branches to main
  5. Run quality gates on merged result
  6. Check: are there newly unblocked tasks? → LOOP
  7. No more tasks? → DONE
```

This maximizes parallelism automatically. If 10 of 13 tasks are independent, all 10 run in the first dispatch — no artificial wave boundaries.

Slices promoted via `wipnote plan promote-slice` from a still-active plan are dispatched through the same dependency-readiness loop — they appear as features linked to the track via `part_of` edges and are ready to dispatch as soon as their `blocked_by` deps are complete.

### Incremental slice promotion

When a track is executing a v2 plan, slices may be promoted one at a time rather than all at once. Each call to `wipnote plan promote-slice <plan-id> <num>` creates a `feat-XXX` linked to the track and marks the slice `execution_status=promoted`. That feature immediately appears in `wipnote execute-preview <trk-id>` and enters the dispatch loop. Dep-blocked slices stay in the `blocked` bucket until their dependencies complete, exactly like manually created features. No special handling is required — promoted slices are regular features from the executor's perspective.

---

## Step 1: Query Unblocked Tasks

Use `TaskList()` to find all tasks ready for dispatch:

```
TaskList()

# Filter for: status=pending AND blockedBy is empty
# These are ready to dispatch immediately
```

If no tasks exist yet, create them from the plan (see `/wipnote:plan`).

---

## Step 1.5: Check File Overlap Among Unblocked Tasks

Before dispatching, verify that unblocked tasks do not edit the same files in parallel. File-level overlap defeats parallelism — two agents editing the same file produce merge conflicts that require manual resolution.

**Overlap detection:**

For each unblocked feature candidate, run `wipnote trace <feat-id>` to get its attributed file set. Then compute pairwise file-set intersection:

- **No overlap detected** → Proceed to dispatch all unblocked features in a single message (the existing happy path).
- **Partial overlap detected** → Partition into waves: dispatch the largest non-overlapping subset first; defer the conflicting features to the next dispatch cycle (after the first wave merges to main).
- **All candidates conflict** → Warn the orchestrator with explicit confirmation; either dispatch a single feature only this wave, or document the override choice to accept merge conflicts. This is rare but possible if all remaining features touch the same critical files (e.g., `go.mod`, `plugin.json`, main registration files).

**Implementation note:** The dependency graph alone is insufficient. Features can be dependency-independent but file-overlapping. This check is orthogonal to `blockedBy` — a feature may be unblocked but file-overlapping with another unblocked feature.

---

## Step 1.6: Precondition Check — SendMessage Availability (Diagnostic)

Before dispatching ANY agents in parallel, check whether the `SendMessage` tool is available. This diagnostic informs your recovery strategy if a sub-agent pauses on tool budget.

**Run this check BEFORE step 2:**

```
ToolSearch(query="select:SendMessage", max_results=1)
```

**If the result is empty or "No matching deferred tools found":**

SendMessage is not available (gated behind `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). First, check the strict gating env var:

```
Bash(command="[ \"$WIPNOTE_EXECUTE_REQUIRE_SENDMESSAGE\" = \"1\" ] && echo strict || echo lax")
```

If the output is `strict`, print this abort message and STOP — do NOT proceed to dispatch:

```
/wipnote:execute: WIPNOTE_EXECUTE_REQUIRE_SENDMESSAGE=1 is set and SendMessage
is not loaded. Strict gating mode is active — aborting parallel dispatch.

To proceed, either:
  (a) unset WIPNOTE_EXECUTE_REQUIRE_SENDMESSAGE
  (b) enable agent-teams mode (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)
```

Otherwise (output is `lax`), print this WARNING and continue to step 1.7:

```
WARNING: SendMessage is not available in this session.

Implications:
- Parallel dispatch will proceed (first-pass execution works normally).
- If any sub-agent pauses on tool budget mid-execution, it cannot be resumed
  automatically. You must either:
    (a) Accept the paused task as failed-needs-rerun and continue with other tasks.
    (b) Fall back to sequential dispatch: `wipnote yolo --feature <id>` per feature.
    (c) Enable agent-teams mode (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) to load
        SendMessage (note: even with SendMessage, worktree subagents cannot be
        resumed per Claude Code issue #42596 — SendMessage only helps agent-teams
        mode).

Proceeding with parallel dispatch. Review your recovery options above before starting.
```

**If the result lists SendMessage:** proceed to the dispatch loop. (Note: paused
worktree subagents cannot be resumed via SendMessage per Claude Code issue #42596;
SendMessage only benefits agent-teams mode.)

> Note: SendMessage availability affects recovery of paused sub-agents during
> parallel execution. Absence does not prevent first-pass execution; it affects
> what happens if a sub-agent exhausts tool budget mid-task. Worktree subagents
> still cannot be resumed via SendMessage per Claude Code issue #42596; this is
> a limitation of the underlying implementation, not this check.

---

## Step 1.7: Popu