execute-plan

name	execute-plan
description	Executes a plan generated by /create-plan. Orchestrates team members in parallel, each working in isolated worktrees. Use when ready to execute a plan from .agents/plans/, resume an interrupted execution, or run a specific plan by ID.
disable-model-invocation	true
argument-hint	[plan-id]

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: ""
     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)
• QA strategy chosen by user (per-task or end)
• Plan branch created and checked out
• Team created via TeamCreate
• Tasks created via TaskCreate
• Every teammate spawned with isolation: "worktree" and full prompt from references/teammate-prompt.md
• No teammate spawned with subagent_type — all general-purpose
• Tasks assigned to teammates via TaskUpdate
• Status tables shown to user after each state change
• Merges handled autonomously by teammates
• Newly unblocked tasks spawn new teammates as dependencies complete
• Context limit recoveries handled by spawning replacement teammates
• All task files updated with completed status, progress, and learnings
• plan.yml and state.yml updated by coordinator only
• Team shut down and cleaned up (zombie agents handled gracefully)
• QA review completed (per-task or end) — gaps identified and fixed
• Delivery mode determined (from plan.config.yml or user choice, persisted for future)
• PR created or squash merge completed
• User informed with PR URL or squash merge confirmation