/kbd-new-phase
Create a fresh top-level KBD phase from scratch — the manual-entry
counterpart to /kbd-next-phase.
OpenSpec lifecycle preflight
Before this stage, follow the orchestrator preflight: use the pinned OpenSpec 2.0.0 CLI through the managed runner — session start runs the read-only verify; phase entry runs refresh, which updates existing KBD/OpenSpec projects — then use that same runner for OpenSpec commands. Retry a pending phase-entry refresh before OpenSpec work; preserve authored specs and task state. Phase scripts run this automatically, including canonical-runtime paths.
What this does
- Parses arguments —
<name>plus zero or more[goals…]. - Validates the name (kebab-case, no path traversal, no slashes).
- Refuses if
.kbd-orchestrator/phases/<name>/already exists. - In runtime-authority mode, reads canonical status. If the lifecycle is
completed,cancelled, orfailed, starts exactly one operator-signed successor run before creating the requested phase. - Creates the phase directory and writes
goals.md+progress.jsonatomically. - Flips
current-waypoint.json:previousPhase ← prior phase,phase ← <name>,status ← assessment_ready, …; preserves unknown fields untouched. - Updates
.kbd-orchestrator/project.jsonactivePhase(warns if absent). - Fires
phase:beforeexactly once for the new phase (best-effort — phase persists even if the hooks subsystem is unavailable). - Emits the canonical Progress Signals and a confirmation banner.
When to use
Run when any of:
- You're starting the very first phase of a project (no prior reflection exists).
- You're pivoting away from the suggestion in the previous phase's
reflection.md(/kbd-next-phaseis the auto-seed path). - You're initialising state by hand and want one canonical entry point
instead of editing
current-waypoint.jsondirectly.
Compare to /kbd-next-phase, which reads reflection.md → "Recommended Next Phase" and auto-seeds the new phase from it.
Progress Signals (MANDATORY)
Starting kbd-new-phase — <name>
Completed kbd-new-phase — <name> ready for /kbd-assess
Prerequisites
- The proposed phase name must not already exist as a directory under
.kbd-orchestrator/phases/. current-waypoint.json, if present, must be valid JSON. (If it is malformed, fix it by hand before retrying; the skill refuses to write on top of a corrupted waypoint to avoid compounding the corruption.)
How to invoke
node scripts/kbd-new-phase.mjs <name> [goal-1] [goal-2] …
Examples
/kbd-new-phase phase-1-foundation
/kbd-new-phase ux-refresh "polish dashboard" "ship dark mode" "audit a11y"
/kbd-new-phase ssed-followup-fixes
Hook integration
/kbd-new-phase is a phase-bracket opening writer. It MUST fire
phase:before exactly once for the new phase, after the waypoint and
project.json flips, and before the Completed kbd-new-phase Progress
Signal — so any hook reading state sees the new phase as authoritative.
The closing phase:after is the responsibility of /kbd-reflect for
the previous phase, which should have run already.