roadrunner

Files (1)

• SKILL.md

SKILL.md (first lines)

# Roadrunner

Pathfinder finds the trail; you walk it. Carry out a plan folder exactly as written, with `path.json` as the live
record of progress.

## Open the plan

Read `context.md`, then the **whole** `path.json`, before touching step 1. The rationale tells you what each `action`
is for, and the full arc keeps an early step from painting a later one into a corner. Given only a plan name, look in
`.agents/plans/<name>/`, then `.claude/plans/<name>/`.

A plan may already be part-run. Steps marked `done` or `skipped` are finished; start at the first step that isn't. If
it's `in_progress` or `blocked`, a previous run stopped there and may have left it half-done, so check what it already
changed before redoing it.

A part folder (`<feature>/01-<part-name>/`, beside a `design.md`) runs like any other plan: its `path.json` already
carries what the design pinned, so the design doc isn't yours to read or reconcile.

## The loop

From there, for each step in `id` order:

1. Set its `status` to `in_progress` and save.
2. Do exactly what `action` says, heeding `notes` — no more, and no reinterpretation. A plan you "improved" mid-run is
   no longer the one the user approved.
3. When the action is genuinely complete, set `status` to `done` and save.

Save each change at once, so an interrupted run resumes from the file rather than your memory. Edit only the `status`
field, and only along `pending → in_progress → done | blocked | skipped` — the values pathfinder's validator accepts.
A `blocked` step returns to `in_progress` when the user's direction, or a later run, resumes it.

`action` is the source of truth; `context.md` explains the why and never overrides it. If the two disagree in a way
that changes what you'd do, that's a hole in the plan: a blocker.

## Verification steps

A `verification` step checks something and changes nothing. `done` means the check ran and held, never "I edited until
it passed"; a failed check is a blocker.

Cheap checks just run. When one will cost real time or money, or hit a live or external system — `notes` may flag it,
but judge for yourself — ask the user whether to run or skip it. `skipped` records their choice, and only a
verification can be skipped: skipping an implementation step leaves the change half-built.

## Stop, don't improvise

When a step can't be done as written — a command fails, a precondition is false, the `action` is wrong or impossible —
set it to `blocked`, tell the user briefly where you stopped and why, quoting the decisive error or finding, and stop
for direction. The user expects the plan done as agreed or halted honestly: a workaround buries a decision that was
theirs, and limping past a broken step builds confident-looking garbage on a cracked foundation.

## Confirm irreversible effects

Before a step writes to a live external system, deletes or overwrites real data, or sends something outward, confirm
with the user or route it to a sandbox, even when the plan just says "do it". Plans are written optimistically ("add
the items" when the store points at production); you're the last check before a real side effect.

## Report

When the plan is `done` or stopped at a `blocked` step: what got done, what's blocked and why, what actually changed.
The detail lives in `path.json` and the diff, so leave the plan unrestated.

From ghamadi/skills, MIT.

More from ghamadi/skills