github-plan

Create one canonical planning issue with the plan label, keep a structured Current Status section as the recovery point, and link sub-issues and native blocked-by relationships for dependencies. Update the issue graph as reality changes rather than relying on chat history.

Use a parent issue plus sub-issues when work touches three or more modules or repos, has independent sequencing or parallelizable tracks, or mixes research, implementation, and validation. Each child issue gets one scoped finish line and one next action.

No. GitHub Projects and similar surfaces are view layers only; GitHub issues remain canonical for plan prose, relationships, blockers, labels, and completion state. Project fields like Focus (Now, Next, Waiting, Later) provide prioritization context but never override native blockers.

Completed closure requires every native blocked-by target and sub-issue to be closed first; the helper runs a relationship preflight and fails before any mutation. Use --reason not_planned for superseded work, which retains and reports open blockers instead.

plan:blocked means a real current dependency exists, preferably a native blocked-by relationship to an open issue. plan:waiting means work is parked on a non-issue condition like a decision or external event, recorded as Waiting for: in Current Status.