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
- 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).
- 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.
- If
mode=unset, ask assets/mode-question.md before any workspace action,
and stop.
- 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, 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.
- Record the approved plan directory by absolute path; read and mirror the
plan only there.
- 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.
- Read the task file, its
Context paths, its evaluator, and the ledger's
rulings, findings, and failed attempts that touch this task. Never work
from memory of the plan.
- Write the attempt row,
State in progress, before any edit: task ID,
attempt ID, current revision, evaluator identity, expected observable.
- 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. A carve-out
in the task's Implementation disciplines stands only where the loaded
skill's own Skip covers the task; otherwise the skill applies.
- Inspect the result yourself: diff against the attempt's starting revision;
compare with
Files, Exclusive ownership/effects, and this task's
rulings. A defect or gap outside the task's contract goes to Findings
outside the task; never fix it inside this task.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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:
- 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.
- 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.
- 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.
- 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.
| Thought |
Reality |
| "All tasks are done, so the plan is done" |
Tasks are done inside the plan. The plan is done after Acceptance, review, and the integration decision — three skills you have not invoked yet. |
| "Tests are green — a PR is the natural next step" |
Green is task-local evidence. Review and integration are separate checks with their own owners. |
| "The plan says approved, so it is" |
A plan cannot authenticate itself. Read the ledger entry or get the answer in this conversation. |
| "Subagents are available, but inline is what I'm already in" |
The row's mode decides, and the Approval rule owner chose it. A delegated row here is a redirect, not a loop to run. |
| "The plan missed a file, so I need reapproval" |
Files is the planner's map, not the spec. If every traced requirement holds, rule and keep going. |
| "A ruling lets me fix this too" |
Only what this Evaluator needs; the rest is a finding. |
Gotchas
- A gap written as a successor halts the run for reapproval: one run wrote
fifteen this way.
- 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, still
in progress, with its raw evidence
and a stable failure-class ID, and start a new attempt that links to it.
- After three attempts in one class without convergence, write
blocked
with the class and the attempts, and skip the task under Step 4.8; the
turn ends only through Step 4.8'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.
- If the index's
Out-of-task findings field says log and report, or is
absent, every finding waits for Step 5.4.
- 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. A task left in progress was
interrupted: keep its uncommitted edits only where a recorded RED covers
them, set the rest aside, and start a new attempt that links to it.
1---2name: executing-plans3description: "Runs an approved plan task by task in this session, through each task's evaluator. Use when the user asks to execute, continue, or resume work governed by an approved plan directory in inline mode, including one remaining task or a reply choosing inline mode. Skip a standalone task with no plan directory, and a plan approved in delegated mode."4metadata:5 source: https://skillmd.com/skills/augments-labs/executing-plans6---78# Executing Plans910Run each task of an approved plan in this session through its evaluator, then11hand the integrated result to review and integration. This skill never decides12what happens to the branch.1314## When to use1516- The user asks to execute, continue, or resume a plan directory, or approves17 it with an inline mode.18- **Skip** a single task with no plan directory: use `test-driven-development`19 and `yagni` directly.20- **Skip** a plan whose approval row records `mode: delegated`:21 `subagent-driven-development` owns it.2223## Available scripts2425- **`scripts/plan-version.sh`** — prints the plan's version, or with `--check-contract` and `--verify` checks task-contract invariants and the decision ledger.26- **`scripts/plan-files.sh`** — checks each task's `Files` paths against a base revision. Read-only.2728## Step 1: Verify approval and mode29301. Run `bash scripts/plan-version.sh --verify` on the plan directory to verify31 the plan's version against the `External decision ledger` (the ledger: add32 to it, never rewrite it) and task-contract invariants. The index cannot33 approve itself; the last decision row (`Section` empty) for the printed34 version must record the `Approval rule` owner's approval and not be closed35 by a later row (`rejected`, `cancelled`, `superseded`, or `changes requested`).362. If `--verify` fails, stop and name the missing version, the row that closed37 it, or the script's error; never substitute a version read from the index.383. If `mode=unset`, ask `assets/mode-question.md` before any workspace action,39 and stop.404. If `mode=delegated`, **REQUIRED SUB-SKILL:** invoke41 `subagent-driven-development`; this skill ends here and runs nothing.4243## Step 2: Set up the workspace4445If every task's `Files` lies outside any git-tracked project, record46`workspace: not applicable` in the ledger, with `plan` in `Section`, and skip472.2. If even one task is inside a repository, Step 2.2 and Step 5.3 apply to48the whole plan.49501. Record the approved plan directory by absolute path; read and mirror the51 plan only there.522. **REQUIRED SUB-SKILL:** invoke `using-git-worktrees`. Fill its record from53 the workspace's own commands.5455## Step 3: Check the plan contract5657Confirm from Step 1's `--verify` output and the task files:5859- `Consumes`, `Depends on`, and `Implementation disciplines` passed `--verify`60 (existing code and external input artifacts belong in `Context`, not an61 invented producer task)62- no task edits its judge unless the approved `Evaluator identity/owner`63 explicitly permits the exact change and requires pre-change RED or64 deliberate falsification; undeclared or weakened criteria block execution65- for a UI task, `Applicable visual references` match the index's `Selected66 visual references` field for field; run each freshness evaluator now6768Record the checked input/output mappings and evaluator ownership in the69execution ledger (the index's `External execution ledger`) before the first70edit. If any check fails, report the field and the task; do not start it.7172- Read `references/phase-queues.md` before the first task when the index73 holds phases or shards, and follow it.74- A high-risk task is blocked until its migration and assurance contracts are75 approved and their entry gates have passed. Report it; do not start it. A76 prerequisite task that only builds an entry gate and touches no target is77 not blocked by that gate.78- Read `Integration cadence`: `plan end` (default) or `per task`.7980## Step 4: The task loop8182Take the next task whose `Depends on` tasks are all `done`. Keep the approved83mode; switching needs the `Approval rule` owner's direct answer.84851. Read the task file, its `Context` paths, its evaluator, and the ledger's86 rulings, findings, and failed attempts that touch this task. Never work87 from memory of the plan.882. Write the attempt row, `State` `in progress`, before any edit: task ID,89 attempt ID, current revision, evaluator identity, expected observable.903. **REQUIRED SUB-SKILLS:** invoke `test-driven-development` and `yagni`91 before the first edit or project command. The plan naming them is not92 invocation; the loading action must appear in this session. A carve-out93 in the task's `Implementation disciplines` stands only where the loaded94 skill's own Skip covers the task; otherwise the skill applies.954. Inspect the result yourself: diff against the attempt's starting revision;96 compare with `Files`, `Exclusive ownership/effects`, and this task's97 rulings. A defect or gap outside the task's contract goes to *Findings98 outside the task*; never fix it inside this task.995. **REQUIRED SUB-SKILL:** invoke `verification-before-completion` on that100 exact state: the `Evaluator`, every `VCONF` row, and101 `visual-ui-verification` for a change visible in a running GUI or TUI.1026. Append the task state to the ledger and mirror the index checkbox:103 - `done`: every check passed on the inspected state104 - `done with concerns`: a check raised something not yet proved105 non-blocking; keep it out of the completion count106 - `blocked` or `needs context`: with the blocker, the owner, and the next107 check108 Mirror only the task row's checkbox and adjacent label. **Do not change the109 index's `Status` header or normalize it out of the plan's identity.**1107. Under `per task` cadence only, **REQUIRED SUB-SKILLS:** invoke111 `requesting-code-review` on this task's revision, then112 `finishing-a-branch`. Return after it records its decision.1138. Go to step 1 with the next ready task. Do not report, ask, or pause at114 `done`. Later `todo` tasks are expected. A blocked task does not block115 independent ready work; retain its blocker and skip it until its entry116 condition changes. Leave the loop only in these cases:117 - If every task is `done`, or `cancelled` or `superseded` with its approved118 ledger decision, go to Step 5.119 - If no authorized ready task can advance, report the unresolved states,120 their blockers, and the next conditions they require.121 - If a task needs a change to the index's `Goal`, a traced requirement,122 `Acceptance`, `Constraints`, or an approved migration or assurance123 contract, or any change *Rulings* says is never a ruling, write the124 proposed successor, ask for reapproval, and end125 the turn. On a high-risk route, **REQUIRED SUB-SKILL:** invoke126 `reviewing-plans` on it first (its Step 1.6).127 - If a high-risk entry gate has not passed and no ready task can advance128 without it, report it and end the turn.129130### Rulings131132A task that cannot be built as written gets a ruling, not a successor,133when every requirement it traces still holds: another signature, a file134outside its `Files`, a changed owner, a corrected way to run its135`Evaluator`. A ruling covers only what this task's `Evaluator` needs. On a136high-risk route, a change `writing-plans`' `scalable-transformation.md`137calls normative is never a ruling.1381391. Before the edit it permits, append a `ruling` row with the task ID in140 `Section`: the change, the requirement it still satisfies, each later141 task it touches (through a changed `Produces` or a file that task owns),142 and its cost if wrong. For a file another task owns, also record the143 ordering. Never edit the plan files.1442. An `Evaluator` ruling changes only how the check runs (command, path,145 fixture, an `Expected` re-printed from the current tree), never drops or146 loosens an assertion a requirement needs; the corrected check goes RED147 on the task's starting state before its GREEN counts. A judge its148 `Evaluator identity/owner` bars this task from editing, or a test the149 spec shipped, changes only by that owner's decision or a successor.1503. After the second ruling caused by a plan claim the code disproves, start151 no task until `writing-plans` Step 3.6 and 3.7 walk every remaining task152 against the current base, once. A gap every traced requirement survives153 gets a ruling; every other gap goes into one successor, its `Bound154 inputs` naming that base revision. A claim that fails Step 3.7 is a155 finding for the owner of the document that made it; invoke nothing from156 here.157158## Step 5: Finish the plan159160In the task workspace recorded in Step 2, in order:1611621. **REQUIRED SUB-SKILL:** invoke `verification-before-completion`: the163 index's `Acceptance` check plus every done task's evaluator, on the HEAD164 that combines every task (`per task`: the base after the last165 integration), or, when `workspace: not applicable`, on the deliverable166 files identified by their content hash. Task ledgers are not evidence for167 this state.1682. **REQUIRED SUB-SKILL:** invoke `requesting-code-review` on that revision, or169 on that hash in working-tree mode. Reading the diff yourself is not this170 step.1713. If `workspace: not applicable` is recorded, hand the result to the user.172 Otherwise, **REQUIRED SUB-SKILL:** invoke `finishing-a-branch` with the173 workspace record from Step 2. It asks the integration question and174 executes the answer. Run no push, PR, merge, or delete here.1754. Close with "Rulings I made": every `ruling` row with its cost if wrong.176 Then "Findings not built": every `finding` row with no `admitted` row,177 with its evidence, one line each. The user decides which become work.178 If the index's `Plan set` names a next slice, name it and ask the179 `Approval rule` owner whether `writing-plans` runs on it now; start180 nothing from here.181182| Thought | Reality |183| --- | --- |184| "All tasks are done, so the plan is done" | Tasks are done inside the plan. The plan is done after Acceptance, review, and the integration decision — three skills you have not invoked yet. |185| "Tests are green — a PR is the natural next step" | Green is task-local evidence. Review and integration are separate checks with their own owners. |186| "The plan says approved, so it is" | A plan cannot authenticate itself. Read the ledger entry or get the answer in this conversation. |187| "Subagents are available, but inline is what I'm already in" | The row's mode decides, and the `Approval rule` owner chose it. A delegated row here is a redirect, not a loop to run. |188| "The plan missed a file, so I need reapproval" | `Files` is the planner's map, not the spec. If every traced requirement holds, rule and keep going. |189| "A ruling lets me fix this too" | Only what this `Evaluator` needs; the rest is a `finding`. |190191## Gotchas192193- A gap written as a successor halts the run for reapproval: one run wrote194 fifteen this way.195- A task file edited after approval leaves the index unchanged; only the196 printed version moves.197- A workspace created from HEAD lacks an uncommitted plan, or holds an older,198 unapproved committed copy.199200## Failures and the circuit breaker201202- If an attempt fails, append it, still `in progress`, with its raw evidence203 and a stable failure-class ID, and start a new attempt that links to it.204- After three attempts in one class without convergence, write `blocked`205 with the class and the attempts, and skip the task under Step 4.8; the206 turn ends only through Step 4.8's exits. Never patch shard failures one207 at a time.208209## Findings outside the task210211A defect or gap outside the current task's contract is never an edit in this212task. One a later listed task's contract covers is left to that task. Any213other, whether you or a review raised it, is a `finding` row in the214execution ledger, with `plan` in `Section` when no task covers it: where,215what, the evidence. It is never a task because someone wrote it down.2162171. If the index's `Out-of-task findings` field says `log and report`, or is218 absent, every finding waits for Step 5.4.2192. Read `references/admitted-findings.md` when the index's `Out-of-task findings` field says `fix when admitted`.220221## Stopping and resuming222223- If the remaining work will not fit this session, finish the current ledger224 row, then invoke `handoff`.225- On resume, rerun `bash scripts/plan-version.sh`, then re-read before226 trusting: the latest decision row (empty `Section`) for the printed227 version, the workspace's base, HEAD, and dirty state through228 `using-git-worktrees`, the execution ledger, and whether each `done` row229 still matches the current revision. A task left `in progress` was230 interrupted: keep its uncommitted edits only where a recorded RED covers231 them, set the rest aside, and start a new attempt that links to it.