Phase-driven workflow for building a feature end to end. Four phases run in order: spec gathers intent and constraints, plan turns the spec into commit-sized units, work executes the plan one commit at a time, and safe-change handles scoped edits where a full spec/plan cycle is overkill. Use when starting new work, when an existing plan needs to be executed, or when making a single change that still needs verification.
Phase-driven workflow for building a feature end to end. Four phases run in order: spec gathers intent and constraints, plan turns the spec into commit-sized units, work executes the plan one commit at a time, and safe-change handles scoped edits where a full spec/plan cycle is overkill. Use when starting new work, when an existing plan needs to be executed, or when making a single change that still needs verification.
argument-hint
[spec|plan|work|safe-change]
jk-build
A four-phase build loop. Each phase has a contract: what it takes in, what it produces, when it's done. Pick the phase that matches your starting point and run it to completion before moving to the next.
Phase
Input
Output
Done when
spec
A rough idea
A written spec the human has reviewed
Constraints, scope, and success criteria are all named
plan
A stable spec
A commit list with dependencies
Every commit is self-contained and leaves the build green
work
An approved plan
Code + green tests + commits on the branch
Plan is fully checked off and tests pass
safe-change
A scoped edit request
The edit applied, verified, and documented
Tests green, docs updated, no regressions
Running a phase
The invocation argument, when present, names the phase. When absent, infer it: fresh work starts at spec, an approved PLAN.md in the repo means work, a single scoped edit means safe-change. When in doubt, default to spec.
Before doing anything else, read the file for the active phase and follow it exactly:
Read only the active phase's file; the others load when their turn comes.
Cross-phase principles
Honesty about uncertainty. If you guessed a name, a default, or a structure, say so when reporting. The human can correct cheaply now; expensively later.
Match the work to the phase. Don't draft a spec while in work phase. Don't start coding while in plan phase. The phase boundary is the value.
Working documents stay local. SPEC.md and PLAN.md are working artifacts. Don't commit them unless the repo's convention says to.
Tests are part of the deliverable. A feature without tests is a feature with a deferred bill. The bill comes due.
Stop and re-spec when the ground shifts. If a plan-phase decision turns out wrong during work, that's a signal to update the plan, not to hack around it.
