execute-plan

What this skill does

## 1. Determine which plan to execute

Read `.agents/plans/state.yml` to check for an active plan.

**If `$ARGUMENTS` contains a plan ID** — use that plan directly.

**If `state.yml` has `currentPlan` set** — resume that plan (retomar from where it left off).

**If no active plan and no argument:**
1. List directories in `.agents/plans/` to find plans with `status: pending`
2. If exactly one pending plan, use it
3. If multiple pending plans, list them and ask the user which one to execute with AskUserQuestion
4. If no pending plans, inform the user and suggest running `/create-plan` first

Read the selected plan's `plan.yml` to load the full plan context.

## 2. QA strategy

Ask the user with AskUserQuestion:
- header: "QA strategy"
- question: "When do you want to review the work?"
- options:
  1. label: "After each task", description: "Pause after each task completes for manual review"
  2. label: "At the end", description: "Review everything once all tasks are done"

Remember the choice — it determines when QA happens in steps 5 and 7.

## 3. Create branch and team

1. Create the plan branch from `plan.yml`'s `branch` field (e.g., `feat/user-notifications`) and switch to it
2. Update `plan.yml` status to `in_progress`
3. Update `state.yml`: set `currentPlan` to the plan ID
4. Call `TeamCreate` to create an agents team

## 4. Create tasks and spawn teammates

You are strictly a coordinator. You NEVER write code, edit files, or execute commands yourself — no matter how small the task. Your only job is to orchestrate.

**File ownership:** you own `plan.yml` and `state.yml` — only you update them. Teammates own their task files — only they update them. This prevents merge conflicts on shared files.

1. **Create tasks** — use `TaskCreate` to create one task per plan task. Use the task title as subject and a brief description.

2. **Identify dispatchable tasks** — find all tasks with `status: pending` whose `dependsOn` are all `completed`.

3. **Spawn one teammate per dispatchable task:**

   First, read `references/teammate-prompt.md`. Everything below the `---` separator is the prompt template. Replace `{{TASK_FILE_PATH}}` with the absolute path to the task file.

   Then use the `Agent` tool:

   ```
   Agent tool call:
     description: "Execute task 01-create-notifications"
     team_name: "<team-name>"
     name: "01-create-notifications"
     isolation: "worktree"
     prompt: <content from teammate-prompt.md with {{TASK_FILE_PATH}} replaced>
   ```

   - Do NOT set `subagent_type` — must be a general-purpose agent
   - `isolation: "worktree"` is MANDATORY — never omit it
   - The prompt is the FULL content from the template — never summarize or shorten it

4. **Assign tasks** — use `TaskUpdate` with `owner` set to the teammate's name.

## 5. Monitor and dispatch

Track progress via `TaskGet`/`TaskList`. Messages from teammates are delivered automatically — do NOT poll.

**When a teammate completes:** update `plan.yml` (set task status to `completed`) and `state.yml` (remove from `activeTasks`). Present an updated status table to the user.

**Per-task QA (if selected in step 2):** after updating tracking files for a completed task, run the QA review flow from step 7 scoped to that task only. After the user finishes reviewing, continue dispatching.

**Merges:** teammates handle merges and conflict resolution autonomously. If two teammates merge around the same time, the second one will rebase and retry automatically.

**Unblocking:** as tasks complete, check if their completion unblocks new tasks (tasks whose `dependsOn` are now all `completed`). For each newly unblocked task, read `references/teammate-prompt.md`, replace `{{TASK_FILE_PATH}}`, and spawn a new teammate (always with `isolation: "worktree"`) using the full template as prompt. Assign via `TaskUpdate`.

**Context limit recovery:** if a teammate hits its context limit and stops responding, read its task file to check progress. Spawn a new teammate for the same task — the teammate prompt handles resumption automatically by reading step progress from the task file.

**Resumability:** if resuming an interrupted plan, read each task file to find:
- Tasks with `status: completed` — skip
- Tasks with `status: in_progress` — spawn a teammate (it handles resumption automatically by reading step progress)
- Tasks with `status: pending` and satisfied dependencies — spawn and dispatch normally

## 6. Completion and cleanup

When all tasks in the plan are `completed`:

1. Update `plan.yml` status to `completed`
2. Update `state.yml`: set `currentPlan` to `null`, update `lastCompletedPlan` to the plan ID, clear `activeTasks`
3. Shut down all teammates via `SendMessage` with `type: "shutdown_request"`. If a teammate does not respond to the shutdown request, skip it — do not block on zombie agents.
4. Clean up the team via `TeamDelete`. If it fails because an agent is still active, inform the user which agent is stuck and ask them to terminate it manually, then retry `TeamDelete`.

## 7. QA review

**If "At the end" was selected in step 2** — run this after cleanup. **If "After each task"** — this flow is called per-task during step 5 (scoped to that task's goals/edge cases).

CRITICAL: complete ALL test cases before launching ANY fix agents. Never investigate, explore, or fix issues mid-QA.

1. Read `plan.yml` to get the user flow, goals, and edge cases (or scope to the completed task)
2. Build a list of test cases from the user flow, goals, and edge cases
3. Present test cases **one at a time** using AskUserQuestion (NEVER as plain text):
   - header: `"Manual review N/M"`
   - question: reproduction steps + expected result in a single paragraph (user's language)
   - options:
     1. label: "Pass", description: "<what success looks like>"
     2. label: "Fail", description: "Algo no funciona como se espera"
     3. label: "Skip", description: "No puedo probar esto ahora"
     4. label: "Chat about this", description: ""
   - If user selects "Chat about this", discuss freely, then re-present the same test case
4. After the user responds, move to the next test case. Repeat until all are reviewed.
5. Present a summary table of all results (pass/fail/skip with details)
6. If any failures, ask the user if they want to fix them
7. If yes, spawn teammates (one per gap or group of related gaps) with `isolation: "worktree"` and the prompt from `references/teammate-prompt.md` describing the gap and the expected behavior.
8. After fixes complete, offer to re-run only the failed test cases (same one-at-a-time flow)

## 8. Deliver

Read `.agents/plan.config.yml` and check for a `completion.mode` field.

**If `completion.mode` exists** — follow it directly without asking.

**If `completion.mode` does not exist** — ask the user with AskUserQuestion:
- question: "How do you want to deliver this plan?"
- header: "Delivery"
- options:
  1. label: "Pull request", description: "Push the plan branch and open a PR for review"
  2. label: "Squash to main", description: "Squash merge the plan branch into the default branch directly"
- After the user answers, persist their choice to `.agents/plan.config.yml` under `completion.mode` (`pr` or `squash`) so it is not asked again.

### mode: pr

Read `references/pr-template.md` and follow it to push the plan branch and create a PR. After the PR is created, inform the user and share the PR URL.

### mode: squash

1. Detect the default branch: `gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'`
2. Switch to the default branch
3. Squash merge the plan branch: `git merge --squash <plan-branch>`
4. Commit using the `commit` field from `plan.yml` as the message. Check if a commit-related skill is available and follow its conventions.
5. Delete the plan branch: `git branch -D <plan-branch>`
6. Inform the user the plan has been squash merged to the default branch

## Acceptance checklist

- [ ] Correct plan identified (by argument, state.yml, or user selection)
- [