Phases

Input: the plan file in $ARGUMENTS. Otherwise use the plan approved in this session, or else the newest file in ~/.claude/plans that matches the current work. Read only its phase list.

PY is python on Windows and python3 elsewhere; use py -3 only if both fail.

Run PY "${CLAUDE_SKILL_DIR}/../../scripts/where.py" --json --no-gh and read its store: it says where the plan is written, so never work that out yourself. store.kind is STATE.md (the default) or beads (a repo that already uses beads; a STATE.md plan wins over a beads epic). If store.note is set, tell the user first. Then follow only the section store.kind names. Never set, export or follow BEADS_DIR.

STATE.md

Edit the file at store.path from the JSON above (in a linked worktree, the main checkout's), or create it if it does not exist. Keep any dated entries, and keep the AIM: line under the # title as it is: never move or rewrite it. If a ## Plan: section already names this plan path, replace it; otherwise add one at the top:

## Plan: <plan name> (<plan path>)
- [x] P1 <title> | branch <branch> | PR #<N>
- [~] P2 <title> | branch <branch> | base <PR base branch>
  - [ ] <sub-task>
- [ ] P3 <title>

## <today, YYYY-MM-DD>
- Next: <the first concrete action of the current phase>
- At: <git rev-parse --short HEAD>

Phases are the outermost checkbox lines in ## Plan:: [x] done, [~] current (exactly one outermost [~]), [ ] open. Fields are optional and separated by |. /yah:where follows the plan with a [~] phase, else the first with an open phase, so a finished plan can stay below.

An indented checkbox line under a phase is a sub-task: not a phase, and not counted in done/total. A [~] line anywhere else (a sub-task, or under ## Follow-ups) is work in progress, not a phase; with no plan, /yah:where shows it as DOING.

An indented plain line under a phase is its handoff log (log in where.py --json): - Done: <what>, - Tried: <what> failed because <why>, - Decided: <what> because <why>. /yah:wrap writes them, keeps the newest 6, and moves them into the PR body when the phase closes. Do not write any here.

A step only the user can do (a review, a merge, a console step) is its own line that ends with (you), as a phase, a sub-task or under ## Follow-ups. It names the command that does it when there is one, ready to paste in a terminal: - [ ] Merge PR #13: gh pr merge 13 --merge (you). /yah:where lists the open ones as waiting on the user.

- At: stamps NEXT so /yah:where can flag it once commits land after it; leave it out if the repo tracks STATE.md. Tell the user STATE.md is not committed unless they want it tracked; offer to add it to .gitignore.

Beads (only if the repo already uses it)

Run every bd below as store.bd, quoted.

1. Look for an existing epic: bd list --type epic --all --json --limit 0. Match spec_id against the plan path. If one exists, update it (add missing phases, fix refs) instead of creating a duplicate.
2. Create the epic: bd create "<plan name>" -t epic -l plan --spec-id "<plan path>" --silent
3. One child per phase, in order: bd create "<phase title>" --parent <epic> -l phase --metadata '{"phase":<n>,"branch":"<branch>","base":"<PR base branch>","next_sha":"<HEAD>"}' --silent
   • <HEAD> is git rev-parse HEAD, run once. It stamps NEXT so /yah:where can flag it once the phase branch has commits NEXT predates.
   • Only the current phase gets --notes "<NEXT: the first concrete action>".
   • Already shipped as a PR: add --external-ref gh-<N>, then bd close <id> --reason "PR #<N> open".
   • A step only the user can do (a review, a merge, a console step) is its own child with -l human and a title that starts with a verb.
4. Claim the current phase: bd update <id> --claim.

Check the result

Run PY "${CLAUDE_SKILL_DIR}/../../scripts/where.py" and show its output. The PLAN, PHASE and NEXT lines must be right, with no ! line about an ignored beads epic. Fix STATE.md or the beads if they are not.

Keep phase text short. The plan file holds the detail (goals, done-when, ground rules); STATE.md or beads hold only state and pointers.

In the plan file, give each phase its own section with a heading that starts with ### P<n> (### P2 <title>), and put choices made at planning time under ## Decisions. Each session reads only those two sections, so a phase without its own section starts with no detail from the plan. If the plan lacks them, tell the user once. A phase section may also carry an After it merges: line and a Files: block (shape in /yah:auto section 3 step 2); /yah:tree draws them, and a plan without them still runs.