Executing Plans

Run each task of an approved plan in this session through its evaluator, then hand the integrated result to review and integration. This skill never decides what happens to the branch.

When to use

• The user asks to execute, continue, or resume a plan directory, or approves it with an inline mode.
• Skip a single task with no plan directory: use test-driven-development and yagni directly.
• Skip a plan whose approval row records mode: delegated: subagent-driven-development owns it.

Available scripts

• scripts/plan-version.sh — prints the plan's version, or with --check-contract and --verify checks task-contract invariants and the decision ledger.
• scripts/plan-files.sh — checks each task's Files paths against a base revision. Read-only.

Step 1: Verify approval and mode

1. Run bash scripts/plan-version.sh --verify on the plan directory to verify the plan's version against the External decision ledger (the ledger: add to it, never rewrite it) and task-contract invariants. The index cannot approve itself; the last decision row (Section empty) for the printed version must record the Approval rule owner's approval and not be closed by a later row (rejected, cancelled, superseded, or changes requested).
2. If --verify fails, stop and name the missing version, the row that closed it, or the script's error; never substitute a version read from the index.
3. If mode=unset, ask assets/mode-question.md before any workspace action, and stop.
4. If mode=delegated, REQUIRED SUB-SKILL: invoke subagent-driven-development; this skill ends here and runs nothing.

Step 2: Set up the workspace

If every task's Files lies outside any git-tracked project, or the index says the deliverable is not a repository change, record workspace: not applicable in the ledger, with plan in Section, and skip 2.2. If even one task is inside a repository, Step 2.2 and Step 5.3 apply to the whole plan.

1. Record the approved plan directory by absolute path; read and mirror the plan only there.
2. REQUIRED SUB-SKILL: invoke using-git-worktrees. Fill its record from the workspace's own commands.

Step 3: Check the plan contract

Confirm from Step 1's --verify output and the task files:

• Consumes, Depends on, and Implementation disciplines passed --verify (existing code and external input artifacts belong in Context, not an invented producer task)
• no task edits its judge unless the approved Evaluator identity/owner explicitly permits the exact change and requires pre-change RED or deliberate falsification; undeclared or weakened criteria block execution
• for a UI task, Applicable visual references match the index's Selected visual references field for field; run each freshness evaluator now

Record the checked input/output mappings and evaluator ownership in the execution ledger (the index's External execution ledger) before the first edit. If any check fails, report the field and the task; do not start it.

• Read references/phase-queues.md before the first task when the index holds phases or shards, and follow it.
• A high-risk task is blocked until its migration and assurance contracts are approved and their entry gates have passed. Report it; do not start it. A prerequisite task that only builds an entry gate and touches no target is not blocked by that gate.
• Read Integration cadence: plan end (default) or per task.

Step 4: The task loop

Take the next task whose Depends on tasks are all done. Keep the approved mode; switching needs the Approval rule owner's direct answer.

1. Read the task file, its Context paths, its evaluator, the ledger's learnings, and the rulings that touch this task. Never work from memory of the plan.
2. Write the attempt row before any edit: task ID, attempt ID, current revision, evaluator identity, expected observable.
3. REQUIRED SUB-SKILLS: invoke test-driven-development and yagni before the first edit or project command. The plan naming them is not invocation; the loading action must appear in this session.
4. Inspect the result yourself: diff against the attempt's starting revision; compare with Files, Exclusive ownership/effects, and this task's rulings. For a dispatched task, read its raw diff, result revision, and evaluator output, never its summary. A defect or gap outside the task's contract goes to Findings outside the task; never fix it inside this task.
5. REQUIRED SUB-SKILL: invoke verification-before-completion on that exact state: the Evaluator, every VCONF row, and visual-ui-verification for a change visible in a running GUI or TUI.
6. Append the task state to the ledger and mirror the index checkbox:
   • done: every check passed on the inspected state
   • done with concerns: a check raised something not yet proved non-blocking; keep it out of the completion count
   • blocked or needs context: with the blocker, the owner, and the next check Mirror only the task row's checkbox and adjacent label. Do not change the index's Status header or normalize it out of the plan's identity.
7. After parallel work, rerun the combined check on the merged state before any of its tasks is done.
8. Under per task cadence only, REQUIRED SUB-SKILLS: invoke requesting-code-review on this task's revision, then finishing-a-branch. Return after it records its decision.
9. Go to step 1 with the next ready task. Do not report, ask, or pause at done. Later todo tasks are expected. A blocked task does not block independent ready work; retain its blocker and skip it until its entry condition changes. Leave the loop only in these cases:
   • If every task is done, or cancelled or superseded with its approved ledger decision, go to Step 5.
   • If no authorized ready task can advance, report the unresolved states, their blockers, and the next conditions they require.
   • If a task needs a change to the index's Goal, a traced requirement, Acceptance, Constraints, or an approved migration or assurance contract, or any change Rulings says is never a ruling, write the proposed successor, ask for reapproval, and end the turn. On a high-risk route, REQUIRED SUB-SKILL: invoke reviewing-plans on it first (its Step 1.6).
   • If a high-risk entry gate has not passed and no ready task can advance without it, report it and end the turn.

Rulings

A task that cannot be built as written gets a ruling, not a successor, when every requirement it traces still holds: another signature, a file outside its Files, a changed owner, a corrected way to run its Evaluator. A ruling covers only what this task's Evaluator needs. On a high-risk route, a change writing-plans' scalable-transformation.md calls normative is never a ruling.

1. Before the edit it permits, append a ruling row with the task ID in Section: the change, the requirement it still satisfies, each later task it touches (through a changed Produces or a file that task owns), and its cost if wrong. For a file another task owns, also record the ordering. Never edit the plan files.
2. An Evaluator ruling changes only how the check runs (command, path, fixture, an Expected re-printed from the current tree), never drops or loosens an assertion a requirement needs; the corrected check goes RED on the task's starting state before its GREEN counts. A judge its Evaluator identity/owner bars this task from editing, or a test the spec shipped, changes only by that owner's decision or a successor.
3. After the second ruling caused by a plan claim the code disproves, start no task until writing-plans Step 3.6 and 3.7 walk every remaining task against the current base, once. A gap every traced requirement survives gets a ruling; every other gap goes into one successor, its Bound inputs naming that base revision. A claim that fails Step 3.7 is a finding for the owner of the document that made it; invoke nothing from here.

Step 5: Finish the plan

In the task workspace recorded in Step 2, in order:

1. REQUIRED SUB-SKILL: invoke verification-before-completion: the index's Acceptance check plus every done task's evaluator, on the HEAD that combines every task (per task: the base after the last integration), or, when workspace: not applicable, on the deliverable files identified by their content hash. Task ledgers are not evidence for this state.
2. REQUIRED SUB-SKILL: invoke requesting-code-review on that revision, or on that hash in working-tree mode. Reading the diff yourself is not this step.
3. If workspace: not applicable is recorded, hand the result to the user. Otherwise, REQUIRED SUB-SKILL: invoke finishing-a-branch with the workspace record from Step 2. It asks the integration question and executes the answer. Run no push, PR, merge, or delete here.
4. Close with "Rulings I made": every ruling row with its cost if wrong. Then "Findings not built": every finding row with no admitted row, with its evidence, one line each. The user decides which become work. If the index's Plan set names a next slice, name it and ask the Approval rule owner whether writing-plans runs on it now; start nothing from here.

Gotchas

• A gap written as a successor halts the run for reapproval: one run wrote fifteen this way.
• An instruction to fix whatever turns up reads as licence to queue every advisory as a task, and each fix's review then raises more — reproduced by a plan run that carried that instruction with no budget: its 14-row list grew to 91. Admit by observed failure, inside the budget.
• A task file edited after approval leaves the index unchanged; only the printed version moves.
• A workspace created from HEAD lacks an uncommitted plan, or holds an older, unapproved committed copy.

Failures and the circuit breaker

• If an attempt fails, append it with its raw evidence and a stable failure-class ID, and start a new attempt that links to it.
• If a worker is past its deadline, write cancellation requested, wait until it and everything it started have stopped, set its output aside unused, and reject its late results.
• After three attempts in one class without convergence, write blocked with the class and the attempts, and skip the task under Step 4.9; the turn ends only through Step 4.9's exits. Never patch shard failures one at a time.

Findings outside the task

A defect or gap outside the current task's contract is never an edit in this task. One a later listed task's contract covers is left to that task. Any other, whether you or a review raised it, is a finding row in the execution ledger, with plan in Section when no task covers it: where, what, the evidence. It is never a task because someone wrote it down.

1. If the index's Out-of-task findings field says log and report, or is absent, every finding waits for Step 5.4.
2. Read references/admitted-findings.md when the index's Out-of-task findings field says fix when admitted.

Stopping and resuming

• If the remaining work will not fit this session, finish the current ledger row, then invoke handoff.
• On resume, rerun bash scripts/plan-version.sh, then re-read before trusting: the latest decision row (empty Section) for the printed version, the workspace's base, HEAD, and dirty state through using-git-worktrees, the execution ledger, and whether each done row still matches the current revision.