The maintenance loop for the graph
The lifecycle is not only a way to produce working code. Its outcome is working code whose current structure remains traversable from the repository contract.
How a programme is split into phases and steps, and what is supposed to remain after a plan is deleted, is the workflow. This page is what each stage is for, and how the graph is decided.
The /cg-* skills are the procedure an agent follows on a turn. This page is not that procedure.
The graph walk
.agents/cg/principles/architecture.yaml graph is what writes and extends the graph. Stay, add-child, and elsewhere remain the only three outcomes.
| Order | Key | Role |
|---|---|---|
| 1 | node | One owned responsibility, one hierarchy kind, one contract.yaml. |
| 2 | recurse | Apply the rest at every candidate. |
| 3 | selfSufficient | Named function, small inbound surface, own change reasons. |
| 4 | surface | Enter only through the declared contract surface. |
| 5 | decide | stay, add-child, or elsewhere. |
| 6 | compose | Parent orchestrates; children decompose owns. |
| 7 | stop | Quit splitting. Not per file; depth is mixed and uncapped. |
| 8 | forbid | A new folder, file, or dependency is not a node. |
| 9 | adapters | Each optional vendor is a child behind a parent-owned port. |
That walk is a protocol the stages apply. It is not an import scanner; cg verify still only proves declared paths exist.
The four delivery stages
cg-plan — shape the programme
Traverse the current graph and turn a broad outcome into an ordered phase roadmap. Planning owns programme shape, dependencies, risk, phase acceptance, and status—not execution allocation.
cg-prepare — make one phase executable
Select one phase and convert it into a prioritized queue of contract-complete Steps. Each Step names its owning boundary, expected graph changes, verification, dependencies, blockers, and state.
cg-produce — deliver the earliest ready Step
Implementation, tests, YAML contract updates, and detectors land as one independently valid structural change. Produce recalculates the queue after each Step and continues serially while ready work remains.
cg-sign-off — close only on a truthful graph
Verify the dependency-safe Step history and the combined behaviour. Sign-off checks that the graph still describes and routes through the implemented system, drives structural defects through corrective Steps, harvests decisions, and leaves a durable record.
Three supporting skills
cg-warmup
Adoption for an existing repository, or additive reseed after a package upgrade. It discovers or extends contracts, verifies structural bindings, and records uncertainty rather than guessing. It does not rewrite existing purpose or product-rule IDs.
cg-unblock
Entered from any stage when a fork needs a recorded decision. It applies contract-backed or reversible defaults, logs blocked work, and keeps independent work visible.
cg-auto-run
Opt-in traversal that follows the measured next route within granted authority. It performs no lifecycle stage itself and never decides through a blocker.
Why plan and prepare are separate
They answer different questions:
- Plan: What sequence of phases delivers the outcome?
- Prepare: How does this selected phase become a safe sequence of executable Steps?
Keeping them separate prevents broad programme intent from being confused with the exact files, contracts, tests, dependencies, and residue that one execution queue owns.
One continuous, sequential queue
A phase uses one branch or worktree, one Step in progress, and explicit dependencies. It does not create a branch per Step or merge between Steps.
| State | Meaning |
|---|---|
Waiting | At least one declared dependency is incomplete. |
Ready | Dependencies are complete, blockers are clear, and verified phase state matches. |
Blocked | An exact decision or external prerequisite prevents execution. |
In progress | The one Step currently executing. |
Complete | The Step gate passed and its handoff is recorded. |
Execution selects the lowest-numbered Ready Step, then recalculates. A blocked Step remains visible and incomplete; later work proceeds only when it has no dependency or path collision with the block.
Steps: 1, 2, 3, 4
2 is blocked
3 depends only on 1
4 depends on 2
Valid history: 1 → 3 → 2 → 4This is continuous serial execution, not parallel execution. It avoids turning coordination ambiguity into integration ambiguity while allowing unrelated ready work to continue.
Contract updates belong to execution
A Step that changes behaviour or structure owns the corresponding implementation, tests, contract nodes, edges, surfaces, routes, invariants, verification, and detectors. Those are one engineering unit—not documentation deferred until completion.
- Resolve the responsible contract and applicable rules.
- Change only the implementation and graph surface allocated to the Step.
- Run the boundary's declared verification.
- Run graph verification for node, edge, reachability, and reference integrity.
- Hand off a branch where the graph describes the code that now exists.
Unattended traversal is bounded
cg-auto-run is opt-in. 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.
It stops on:
- a blocker or a route to
cg-unblock; - a failed gate;
- the third closed phase in the run; or
- a dispatch budget of twelve.
Remaining planned phases are a fresh run. Auto-Run performs no lifecycle stage itself.
Completion is a repair loop
Sign-off is not a detached review that edits contracts after the implementation is complete. Integration composition and emergent tests can be fixed directly, but a behaviour-, boundary-, invariant-, or contract-affecting defect returns to Produce as a corrective Step.
A phase closes only when its acceptance gate is green and the graph tells the truth about the resulting system.