The lifecycle lists the stages. This page is the shape of the work: what you agree at each layer, what gets written, and what is still true after the plan is archived.
The /cg-* skills are the procedure an agent follows on a turn. This page is not that procedure.
Prototype before detailed delivery
When the desired experience needs hands-on exploration, start with /cg-prototype. It launches the application, makes small changes, and iterates through your manual feedback while deferring application test automation. Relevant contracts still guide placement and remain truthful.
Explicit prototype acceptance leads to an Active roadmap and preparation of the actual provisional code, without another plan invocation. Prototype acceptance never marks the initiative delivered. See Prototype.
The decomposition stack
For a sufficiently understood outcome, a change is split four times before delivery code moves. Each split answers one question. A later stage may refine how the work is allocated. It should not quietly change the question already answered.
what should be true when we are done
→ ordered phases plan
→ ordered steps in one phase prepare
→ one change produce
→ code + contracts + tests the lasting baselineOn a repository that already has code, warmup runs before this stack. It writes contracts for the structure that exists, and records splits the code does not yet have. Those splits become a plan you validate. After a later package upgrade, the same skill reseeds an already-governed graph additively: missing children, product rules, and route targets. It does not rewrite existing purpose or P IDs, and it does not rewrite the product.
What you agree at each layer
| Stage | You are agreeing | You are not yet deciding |
|---|---|---|
| Prototype | The working experience after manual review, then the remaining delivery roadmap | Acceptance does not prove production readiness |
| Plan | Ordered phase outcomes, dependencies, and what “done” looks like for each phase | Which files move, which branch, which implementation |
| Prepare | The steps for one selected phase: paths, dependencies, and the command that proves each step | A new phase outcome — that is a return to plan |
| Produce | The implementation of the current step, and contracts that describe what is true now | A new split the step did not name |
| Sign-off | Whether the phase gate passed; what to keep as durable record; work that belongs in another phase | Fixing a behaviour or contract defect only in documentation |
Unblock sits beside this stack. Existing accepted decisions settle questions within their scope. When a user decision remains, the agent records the context, viable options, tradeoffs and recommendation, then asks directly. Silence or a preselected recommendation is never approval.
Auto-run is optional. It follows an already-planned roadmap for a few phases, then stops. It does not invent the plan, and it does not settle owner decisions.
How a plan is executed
Plan writes a roadmap under your docs tree (default docs/plans/<programme>/roadmap.md). Each phase has one observable outcome and one acceptance gate. Phases do not own files. Current behaviour stays in contract.yaml.
Prepare turns one selected phase into a queue. Each step names what it may change, what it depends on, what blocks it, and the command that proves it. Real constraints are explicit dependencies, so a blocked step does not freeze an independent later step.
Produce runs the earliest ready step from the last verified state. Code, tests, and any contract change for that step land together. Produce continues through ready work until the queue is drained or nothing is ready.
Sign-off runs when every step in the phase is complete. If the phase gate passes, transient plan files for that phase are archived. Knowledge that must survive goes into contracts, product rules, or durable docs — not into a plan you are about to delete.
What the next session is supposed to trust
A later session should not need the previous chat. It should be able to route through the contract graph, see remaining work on the roadmap and queue, and take accepted resolved decisions as settled until they are promoted or dropped.
| Lasting | Temporary |
|---|---|
contract.yaml nodes, edges, routes, invariants | Roadmaps and step queues |
Architecture bindings (A) and product rules (P) | Auto-run ledgers |
Durable records under docs/decisions/ and docs/guides/ | Warmup findings once adoption has finished; a reseed delta after the owner has read it |
| The decision log file (entries drain; the ledger remains) | A decision id as the source of a contract rule |
If deleting docs/plans/ would lose a rule, the rule was stored in the wrong place. After a green step, the baseline is the pair code that exists and graph that describes it.
Seeing where you are
These commands inspect the same disk state the stages use. They do not require the last chat.
| Command | What it tells you |
|---|---|
cg next | Which stage owns the next move, from the step headers on disk |
cg residue | Plan files nothing still links to |
cg verify | Whether the authored graph is closed — not yet whether every import matches it |
cg graph show | A projection of the contract graph |
cg contract route --task "…" | Which contracts a request should load first |