execute-plan

name	execute-plan
description	Trigger only when an already-approved PLAN.md or equivalent structured plan must be executed through wave-ordered tasks, isolated git worktrees, wave-level verification, final integration, and controlled merge handling; never create the plan or execute unapproved work.
requires	[]

execute-plan — Controlled Wave Execution Skill

1. Trigger Boundary

Use this skill only when all conditions hold:

• A user-approved canonical plan file already exists under ~/.yi-workflow/docs/plans/ as plan-YYYYMMDD-HHMMSS-{slug}.md.
• The plan contains waves, tasks, file scopes, dependencies, and verification criteria.
• The user wants the plan executed, not redesigned.

Do not use this skill for:

• Creating or revising a plan; use to-plan instead.
• Implementing ad-hoc natural-language requests without plan approval.
• Reviewing a completed diff only; use review-diff instead.
• Pure verification after implementation; use verification instead.

2. High-Risk Red Lines

• Never execute an unapproved plan. Stop if approval, global plan path, or plan content is missing.
• Never depend on worktree-local ./PLAN.md. Read the approved plan from the exact user-approved planPath under ~/.yi-workflow/docs/plans/ or its resolved absolute home-directory equivalent before creating or entering execution worktrees, reject singular ~/.yi-workflow/docs/plan/ and project-local fallback paths as canonical inputs, then pass plan content or task slices directly to subagents.
• Never skip file-isolation checks before concurrent dispatch.
• Never run concurrent tasks that may edit the same file. Downgrade the wave to sequential execution.
• Never execute approved plan tasks in the main product working tree. Every planned wave must run in a run-owned wave worktree; there is no implicit small-plan, simple-plan, or low-risk direct mode for /skill:execute-plan.
• Never fall back to direct execution when worktree creation fails, is blocked, or is unavailable. Stop with status: blocked, record the reason, and ask the user how to proceed.
• Never treat Agent isolation: "worktree" as recovery for missing run-owned wave worktree state. Agent isolation worktrees do not replace the required shared wave worktree plus .yi-workflow/state/execute-plan/{runId}/worktrees.yaml registry entry.
• Never probe expected guard-blocked worktree creation from the main agent. If shell/git worktree creation belongs to a compliant workflow actor, delegate it first; do not intentionally collide with the guard and recover afterward. Never use the guard as a discovery mechanism for actor boundaries.
• Never merge wave branches before their verification passes. Wave-level verification (State B step 8) must pass before the wave is committed; final verification (State C) must pass before merging into the base branch. Merge is a post-verification action. Main-agent git merge of unverified wave branches is a protocol deviation.
• Never merge if final verification fails. Ask the user whether to fix, re-plan, or cancel.
• Never auto-resolve merge conflicts without user choice. Conflict resolution requires explicit intervention.
• Never delete worktrees or branches that were not created by this execution run.
• Never run destructive git commands without confirming they target only this run’s artifacts.
• Never claim completion until all executed changes are reviewed, verified, merged as intended, and cleaned up or explicitly retained.

3. Progressive Disclosure

Load auxiliary files only when needed:

• Read assets/execution-result-template.yaml before producing the final execution result.
• Read reference/worktree-architecture.md before creating or reasoning about wave worktrees.
• Read reference/dispatch-contracts.md before dispatching executer, reviewer, verifier, or debugger agents.
• Read reference/merge-conflict-flow.md when a merge conflict is detected.
• Read reference/verification-checklist.md before wave-level and final verification.
• Read examples/file-isolation-cases.md when a concurrency decision is ambiguous.

Do not keep long flow diagrams, examples, or templates in active context unless they are required for the immediate state.

4. Execution State Machine

State A — Preflight

1. Load the approved plan from the exact user-provided path under ~/.yi-workflow/docs/plans/ or its resolved absolute home-directory equivalent before creating or entering any worktree.
2. Reject missing, unreadable, malformed, singular-directory ~/.yi-workflow/docs/plan/, product-repo, or project-local plan paths as canonical inputs.
3. Treat the loaded plan content as the canonical execution input; do not assume ./PLAN.md exists inside future worktrees.
4. Accept pure YAML plan artifacts that start with plan:. If an older artifact starts with ---, parse it only if the required plan fields are unambiguous; do not require worktree-local markdown frontmatter.
5. Verify required fields: waves[], wave.type, tasks[], task.files, task.order, task.dependsOn, and verificationCriteria.
6. Record the current branch, base ref, and exact git status --porcelain output.
7. Treat any non-empty git status --porcelain output as a not-clean working tree, including ?? untracked files. Never summarize untracked entries as a clean tree.
8. Classify dirty entries against planned file scopes before continuing:
   • If any dirty entry overlaps a planned file, stop until the user resolves/stashes it or approves a revised plan.
   • If dirty entries are unrelated to planned files, stop and ask whether to continue with isolated wave worktrees, stash/clean first, or cancel.
   • If the user chooses stash/clean, delegate the cleanup to a compliant executer subagent; the main agent must not run rm, rm -rf, git clean, or equivalent destructive filesystem commands directly. A guard-blocked main-agent cleanup attempt is an avoidable protocol deviation; record it in protocolDeviations.
9. Stop with status: blocked if required wave worktree creation is unavailable, blocked, or cannot be proven run-owned; do not execute in the main product working tree.

State B — Execute Waves in Plan Order

For each wave:

1. Ensure the first worktree-creation action is dispatching the compliant workflow actor/subagent (for example agents/executer.md with mode: create-wave-worktree) to create a run-owned wave worktree from the configured main branch/base ref; the main agent must not first issue shell/git worktree commands that are expected to be guard-blocked.
2. Treat any preceding main-agent git worktree add probe as an avoidable protocol deviation, not a normal fallback path, even if later delegation succeeds.
3. Record the wave worktree path, branch, base ref, and run-owned provenance in .yi-workflow/state/execute-plan/{runId}/worktrees.yaml before dispatching any executer.
4. Re-check task file isolation.
5. If wave.type is concurrent and file isolation is proven, dispatch task executers in parallel with the wave worktree path, loaded plan content or wave slice, and each assigned task slice.
6. If wave.type is sequential or isolation is not proven, dispatch task executers one at a time by order with the wave worktree path, loaded plan content or wave slice, and each assigned task slice.
7. Wait for all task executers assigned to the wave to finish.
8. Run wave-level review and verification in the wave worktree by delegating to reviewer/verifier actors; the main agent must not run product verification commands directly.
9. Commit the wave only if review and verification pass.

State C — Final Verification

After all waves finish:

1. Run final integration verification against the full plan.
2. For single-wave plans where the wave-level verification (State B step 8) already covered every verification criterion in the approved plan, a separate State C dispatch is not required; the main agent may satisfy State C by noting that wave-level verification already passed every criterion and recording this in the final report. This is not a state-machine skip — it is a deliberate coverage decision. For multi-wave plans, run a separate final verification that covers cross-wave integration, not just per-wave criteria.
3. If verification fails, stop before merging and ask the user to choose: fix within plan, debug unknown failure, re-plan, or cancel.
4. Continue only after verification passes.

State D — Merge and Conflict Handling

1. Only after final verification (State C) passes, merge completed wave branches in plan order. Never merge unverified wave branches; a main-agent git merge before verification is a protocol deviation and must be recorded in protocolDeviations.
2. If a merge conflict appears, stop and ask the user to choose: debugger-assisted resolution, manual resolution, or cancel.
3. After any conflict resolution, rerun relevant verification before continuing.
4. Stop if verification fails after conflict resolution.

State E — Cleanup and Report

1. Remove only run-owned worktrees and branches after successful merge or explicit user-approved cancellation cleanup.
2. Compare every worktree, branch, and plan artifact targeted for cleanup against .yi-workflow/state/execute-plan/{runId}/worktrees.yaml and the approved plan path before deletion.
3. After successful merge and successful final verification, delete the executed global plan file from ~/.yi-workflow/docs/plans/ and the run-owned state directory from .yi-workflow/state/execute-plan/{runId}/. Delegate these destructive cleanup operations (plan file deletion, state directory removal) to a compliant executer subagent; the main agent must not run rm, rm -rf, or equivalent filesystem commands directly. A guard-blocked main-agent cleanup attempt is an avoidable protocol deviation; record it in protocolDeviations.
4. Preserve the global plan file when execution fails, is blocked, is cancelled before merge, or the user asks to inspect or continue later.
5. If registry provenance is missing or uncertain, retain the artifact and report it in cleanup.retainedArtifacts plus protocolDeviations or userInterventions.
6. Produce the final execution report using the schema below.

5. User Intervention Points

Ask the user before continuing when any condition occurs:

• Approved global plan path is missing, outside ~/.yi-workflow/docs/plans/ or its resolved absolute home-directory equivalent, inside singular ~/.yi-workflow/docs/plan/, product-repo, project-local, unreadable, or malformed.
• Working tree has any uncommitted changes from non-empty git status --porcelain, including untracked ?? files; overlapping planned files must be resolved/stashed or re-planned, and unrelated files require a user choice to continue with isolated wave worktrees, stash/clean first, or cancel.
• Wave-level review or verification fails.
• Final verification fails.
• Merge conflict is detected.
• Cleanup would delete branches, commits, worktrees, or plan files not proven to belong to this execution run.

6. Negative Prompts

• Never infer approval from the existence of a plan file.
• Never require a plan file to exist inside wave worktrees; use the loaded global plan content instead.
• Never treat singular ~/.yi-workflow/docs/plan/, project-local ./PLAN.md, product-repo docs/plans/..., or product-repo absolute paths as canonical approved plans.
• Never let repository-wide verification criteria search global plan artifacts, agent session logs, or execution logs unless the approved plan explicitly asks to inspect those artifacts; scope source/reference cleanup checks to the product repository worktree, and separately classify ignored/cache artifacts such as .pytest_cache historical nodeids.
• Never silently convert failed verification into success.
• Never dispatch parallel executers before checking file intersections.
• Never execute, verify, edit, delete, or clean up approved-plan product changes directly in the main product working tree; dispatch executers/verifiers in run-owned wave worktrees instead.
• Never probe worktree creation with a main-agent bash/git command that the guard or actor boundary is expected to block; delegate worktree creation to the compliant actor first, or stop blocked if no compliant actor is available. The guard is not a discovery mechanism for actor boundaries.
• Never treat non-empty git status --porcelain output as clean, including ?? untracked files.
• Never let an executer modify files outside its assigned task scope without recording and reviewing the deviation.
• Never use bash/shell to read state, plan, or config files under .yi-workflow/ when the Read tool is available for those paths. The main-agent Read tool is permitted for meta/config/plan/state files; shell operations against the same paths are guard-blocked. A guard-blocked bash cat or equivalent against a workflow state file is an avoidable protocol deviation; verify registry, plan, or state files with Read instead.
• Never hide guard-blocked main-agent operations; record them in protocolDeviations even when recovery succeeds by delegating to the compliant actor.
• Never mark a guard-blocked or failed run-owned worktree creation as recovered: true merely because executers were dispatched with Agent isolation: "worktree"; that substitution does not restore the required shared wave worktree or registry state.
• Never report a critical state-machine violation, such as missing wave worktrees with attempted main-tree execution or Agent-isolation fallback after missing run-owned registry state, as status: completed; stop as status: blocked or status: failed.
• Never merge wave branches before their verification completes. Merge is only permitted after the wave passes wave-level verification and final verification (States C–D). Merging unverified or partially verified waves is a protocol deviation; record it in protocolDeviations.
• Never clean up unknown git artifacts or unrelated plan files.
• Never run destructive filesystem commands (rm, rm -rf, git clean -fd) from the main agent during preflight cleanup, plan file deletion, or state-directory removal; delegate every destructive cleanup operation to a compliant executer subagent. A guard-blocked main-agent destructive command is an avoidable protocol deviation.
• Never output historical design notes or obsolete architecture comparisons in the final report.
• Never use unqualified final-summary claims such as zero remaining traces, all traces removed, zero matches across entire repository, or zero matches across the product repository when verification found residual ignored, untracked, binary, cache, generated, or main-working-tree-only artifacts; qualify the claim to the verified scope such as tracked source files.
• Never claim the entire repository or product repository is clean unless verifier evidence explicitly covers tracked files plus ignored/cache/generated artifacts, untracked artifacts, and binary artifacts, or proves those artifact classes do not exist.

7. Final Output Format

Read assets/execution-result-template.yaml before producing the final execution result. Return exactly one raw YAML document at completion or stop point. Apply this output gate before responding:

1. The first visible characters are exactly status:.
2. The response contains exactly one YAML document and ends immediately after the final YAML field.
3. Do not wrap the YAML in markdown fences; any response containing triple backticks is invalid and must be rewritten before sending.
4. Do not include headings, prose, markdown separators, bullet lists outside YAML fields, or any text before or after the YAML.
5. If explanation is needed, place it only inside YAML fields such as summary, userInterventions, or protocolDeviations.

Raw YAML structure:

status: completed | failed | cancelled | blocked planPath: string baseRef: string wavesCompleted: number totalWaves: number waveWorktrees:

• name: string path: string branch: string status: created | executing | committed | merged | retained | removed | failed commitHash: string | null tasksCompleted: number tasksFailed: number finalVerification: passed | failed | skipped mergeConflicts:
• wave: string files: string[] resolved: boolean userInterventions:
• node: string choice: string protocolDeviations:
• node: string expected: string actual: string impact: string recovered: boolean cleanup: worktreesRemoved: string[] branchesDeleted: string[] planFileDeleted: string | null retainedArtifacts: string[] summary: string nextAction: none | fix | debug | replan | manual-resolution | approve-cleanup

protocolDeviations: [] means no known deviations. A guard-blocked main-agent operation during execute-plan must be recorded here even if the workflow recovered by delegating to a compliant subagent. In each entry, expected describes the workflow contract or required state, not the attempted implementation detail; for guard-blocked worktree creation use an expectation such as first worktree-creation action is compliant actor dispatch and registry recording, not main agent runs git worktree add. A preceding main-agent git worktree add probe is an avoidable protocol deviation and not a normal fallback path; recovered: true may describe restored execution state after compliant delegation, but it must not imply the probe itself was compliant. A compliant recovery may report actual: main-agent worktree command was guard-blocked; compliant actor created and recorded the worktree before task dispatch. Agent isolation: "worktree" fallback is not compliant recovery for missing run-owned wave worktree state and must not be reported as recovered: true; without user-approved plan revision, it must produce status: blocked or status: failed. A critical state-machine violation, such as failing to create wave worktrees and attempting main-tree execution, must produce status: blocked or status: failed, not status: completed.