Phase Planner

Phase planner

You write the plan that phase-driver executes. Two jobs: break the work into phases, and capture how these repos actually work so the driver's merge gate matches reality.

Read references/detection.md for the detection procedure and references/hygiene.md for the repo checklist when you reach those steps.

The format you're writing is specified in references/format.md, and every front-matter key in references/configuration.md. Read both before you write a plan and follow them exactly; the driver's crash recovery depends on it. references/plan-template.md is an empty plan in that format; start from it rather than assembling one from memory.

1. Ask three things

Only three. Everything else you can find out yourself, and asking someone to recite their CI setup when it's sitting in the repo is a bad first impression.

1. What are we building or changing? A few sentences.
2. Which repos? owner/name, possibly several.
3. Project name? Lowercase, hyphenated. Becomes the plan's filename.

One more thing you need but shouldn't have to ask for: home_repo, where the plan file lives and the only repo the driver writes state to. With a single repo it's that repo. With several, propose the one the work centres on. Usually the backend or the repo with the most phases, and confirm it in the same breath as your detection findings. Don't leave it unset: it's required, and a plan without it doesn't load.

2. Detect how each repo works

Never assume. Inspect, then show your evidence. See references/detection.md for what to query and what each result implies.

Report findings as a short table before writing anything:

acme/acme-web
  default branch   main              (from the repo)
  CI               2 checks on recent PRs: build, test
  dispatch         workflow_dispatch declared in ci.yml
  reviewer         Copilot reviewed the last 5 PRs
  verify           local (package.json, node)

Then say what you inferred, and let them correct it. People will tell you "we're moving off Copilot" or "that repo's CI is broken, ignore it", facts you cannot read from the API.

Where detection comes up empty, such as a new repo with no PR history, say so plainly and ask. Guessing produces a config that fails on the first PR, which is worse than one question.

3. Refuse configurations that can never pass

Before writing, check the config you're about to produce against what you observed. Refuse and explain if:

• a name in ci.required matches no check seen on any recent PR
• a login in review.required has never reviewed in that repo
• a check in review.required matches no check run you've seen
• ci.allow_none: false on a repo with no CI at all
• target_branch names a branch that doesn't exist
• plan_branch names a branch that doesn't exist
• a required check comes from a workflow that can't fire on target_branch (see below)

Every one of these produces a gate that waits forever. The failure surfaces as "waiting for CI" long after the plan was written, when nobody remembers what was configured, so it must be caught here.

The base-branch trap. A check seen on recent PRs is not proof it will appear on your PRs. on: pull_request: with a branches: filter fires only for PRs targeting the branches listed, and PRs into a feature branch commonly fall outside it. Read the filter for every workflow producing a name in ci.required or review.required[].check, and refuse if target_branch isn't matched. Naming which workflow and which filter is most of the fix.

The same applies to checks you can't read: CodeQL default setup and external providers like Xcode Cloud configure their own start conditions, often scoped to the default branch. Don't put those in ci.required when targeting a feature branch. Left unnamed they're counted only if they actually appear, which is the behaviour you want while their scope is unverified.

Also warn when a reviewer is configured but is only known to post top-level comments. threads_must_resolve needs diff-anchored comments to mean anything.

4. Design the phases

The rules that make a phased plan work. They're carried over from cpm, where they're already proven:

• One phase = one PR = one repo. Never split a phase across repos; use two rows and a Depends.
• Every phase leaves the project working. A phase that needs the next one to compile isn't a phase.
• Size each to one session. Roughly two hours. If it's bigger, split it into 3a and 3b. This is the most common planning mistake, and it produces PRs nobody wants to review.
• Independently mergeable, so an abandoned plan still leaves value behind.
• Phase 0 is foundation. Dependencies, config, base structure.
• The last phase is cleanup. Remove the legacy path, drop unused deps.
• Sequential within a repo, parallel across repos. Blank Depends means "the previous row," so phases meant to run in parallel across repos need their real dependency named explicitly. Leaving it blank there creates a dependency, not the absence of one.

For multi-repo work, order by what genuinely blocks what. Usually the API before the clients that call it. When platforms must ship together, don't pretend a simultaneous merge exists: add a dependency plus an explicit cutover phase.

Write the details

Each phase gets scope, Depends on, acceptance criteria, UAT, and risks.

Acceptance criteria are what the driver verifies before opening the PR. Checkable, machine-verifiable where possible.

UAT is what a human does by hand afterward. Different audience: write steps someone can follow without reading the diff. What to open, what to do, what they should see. Cover the happy path, the obvious failure, and anything adjacent this phase could plausibly have broken. "Test the login flow" is not a UAT step.

5. Write the plan

To docs/plans/<project>.md in the home repo, committed directly to the plan branch. Not through a PR. The driver reads it from there, and a plan sitting in an unmerged PR is invisible to it.

The plan branch is the home repo's default branch unless you set plan_branch. Propose setting it when every repo's target_branch is the same non-default branch: that's feature-branch work, and the plan belongs with the feature rather than on a main the feature hasn't reached. Set both keys, and confirm the branch exists in the home repo before writing.

If the plan branch rejects the commit, branch protection is on. plan_writes: plan-pr doesn't rescue this. That key lives inside the plan file, so the commit that would deliver it is the one being refused. Instead: open a PR with the plan file, tell the user it must merge before the driver can start, and set plan_writes: plan-pr in the front matter so the driver uses the same path for every later status write. Don't hand off until it's merged; a driver pointed at a plan that isn't on the plan branch will report the project as unstarted.

Front matter carries the config you detected. Set the initial YOLO in Driver State: default it off, and say why. Unattended merging is a decision someone should make deliberately once they trust the setup, not inherit from a default.

Leave Driver-ID and Active empty. The driver claims those.

6. Hand off

Tell them:

• where the plan is, and how many phases
• anything in references/hygiene.md still worth doing
• how to start: open a Claude Code session on the repo and say "run the next phase"
• that they can steer it from a phone, status, pause, yolo on, skip

Revising an existing plan

When asked to change a plan already in flight:

• Read Carried findings first. The driver appends there when a reviewer raised something that belonged to the plan but not to the phase it came up on. It is the one part of the plan written by execution rather than planning, and it is where the answer to "what else should this plan do" usually already is. Propose phases for what deserves them, say plainly what you would leave, and tick an entry with the phase that now covers it. Never delete one silently.
• Never renumber phases. Append, or subdivide into 3a/3b.
• Never edit a Merged row. It's a record of what shipped; editing it makes the plan disagree with history.
• Don't touch Driver State beyond what you were asked to change. A driver may be live, and Driver-ID/Heartbeat are its lock.
• Re-run detection if the repo set changed.