keel-plan

/keel-plan — build and maintain the phase map

When: at bootstrap right after the tailoring (rules.md §0), whenever the user asks for a plan or a re-plan, or when scope changes enough that the DAG no longer matches reality. PLAN.md is the strategic view; TASKS.md stays the tactical board — never duplicate checkboxes across them.

1. Propose. From the user's goal derive phases + sub-phases, each with: id (p1, p1_2 — lowercase [a-z0-9_]), a gate (verifiable done-when, same spirit as TASKS.md), after dependencies (siblings with no mutual after may run in parallel), and — on a multi-user project — an owner (the person's git config user.name; blank = anyone). Ask who owns what when parallel branches are assigned to different people; only the owner advances an owned phase (/keel-autopilot stops at a foreign one). Single-user projects leave owner blank. Multi-user governance: when the project declares itself multi-user, ASK who the PROJECT owner (founder) is — never assume it's whoever is bootstrapping — and write their git config user.name as the single line of .claude/project-owner. That file arms the owner-guard hook (governance files — PLAN/rules/CLAUDE/architecture/ADR/.claude — become owner-only; non-owner git push to main blocked) and the session role line. Assignments (@name tags in TASKS, the owner column here) are then the OWNER's call; sprint deadlines ride the TASKS item as due: YYYY-MM-DD (the re-ground hook nags past-due) (docs/steering.md "Multi-user"). Single-user: no file, nothing changes. Map product phases only — what the project builds and ships. One-time meta/tooling work (a mid-project tool adoption, a dependency/CVE sweep, a pure refactor) is not a phase node: record it in an ADR and/or the Fix log. A meta stub given an after becomes a permanent dead-end fork in the graph — exactly the noise the map should avoid. Show the table draft — apply only after approval (§10.36).

2. Write PLAN.md. Patch the phase table (SOURCE OF TRUTH) and Current focus; regenerate the whole diagram block from the table between the KEEL_PLAN_DIAGRAM markers — never hand-edit inside, never rewrite the rest of the file (patch, don't clobber). One syntax slip breaks the whole GitHub render.

   Canonical diagram spec — this skill OWNS it. (PLAN.md is PROTECTED by /keel-update, so palette fixes reach existing projects only through this skill's regeneration, not by editing their PLAN header.)

   • Node id = the phase id (p1, a2), NOT "Phase 1"; label reads id short-name so table, TASKS, Fix-log and diagram key on ONE token. Order is the ARROWS, never the number — a big id on a parallel branch may finish before a small one (that is normal in a DAG, not a mistake to hide).
   • Status → semantic class (a plan at rest must not look alarming — reserve red for real trouble):

     classDef done    fill:#2e7d32,color:#ffffff,stroke:#1b5e20
     classDef wip     fill:#f9a825,color:#000000,stroke:#e65100,stroke-width:3px
     classDef todo    fill:#eceff1,color:#37474f,stroke:#b0bec5,stroke-dasharray:4 3
     classDef blocked fill:#c62828,color:#ffffff,stroke:#8e0000
     

     done green · wip amber+thick border (the "you are here") · todo neutral grey+dashed (not-started ≠ broken) · blocked red (reserved). Emit a one-line legend just above the fence: > yeşil done · **amber** wip · gri-kesik todo · kırmızı blocked — sıra OKLARDA, numarada değil.
   • Mermaid safety (GitHub ~v10): ids [a-z0-9_]; every node on its own line, edges below; labels "double-quoted", ASCII only — no emoji, no unquoted (), no lowercase end; solid --> = depends-on, dotted -.-> = contains; every classDef pairs fill with color; no %%{init}%%.

3. Seed the board. Refill TASKS.md ## Now (3–5 items max) from the wip leaf's gate; reference the phase id in each item so the Fix log and HANDOVER one-liners can point back.

4. Status lifecycle. todo → wip → done, flipped at rituals: /keel-handover updates statuses + Current focus each session; /keel-phase-review is the only gate to done. done never flips back — a bug found later is a Fix log row (date | fix | phase-id), which keeps the map honest after the project completes.

5. Re-planning (experiments change the plan). PLAN.md always shows ONLY the latest plan: phases dropped in a re-plan are removed entirely from the table and diagram — no tombstone rows or statuses. The failed approach is already recorded in LESSONS.md [fail] / HANDOVER block (b), and git history keeps every earlier shape of the plan. done phases stay; existing ids are never renumbered (Fix log / HANDOVER references must keep resolving).

6. Drift. The SessionStart hook warns when the table and diagram disagree or when a wip phase has an empty TASKS.md ## Now — fix by regenerating from the table (this skill), not by editing the diagram.