Workflow

Contract Graph Dev Kit carries agreed work through planning, execution, review and verified completion. Its workflows use the repository-native contract graph to locate responsibilities and dependencies, and preserve current context so the next session can continue from the repository.

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 removed.

Guides and manuals

Use your configured documentation root in place of docs. Classify by audience and purpose, not title: a “player guide” belongs in manuals; a “deployment manual” belongs in guides. Both explain current supported behavior. Link shared facts instead of maintaining duplicate instructions. Existing repository layouts can retain their destinations with the same audience distinction.

Installation supplies directory descriptions and preserves existing documentation. It does not automatically relocate old files. When correcting misplaced content, the agent preserves useful material and updates links within the agreed scope.

Decisions you need to make

Reviews are written for functional leaders. You should be able to understand the outcome, cost, risk and choice without learning framework commands. Technical terms appear only when necessary and are explained.

A decision review has a clear question and four fields: Context/background, Options, Recommendation, and Why. Reply in the conversation. The agent keeps approval details separately; you do not need to edit a log or run a verification command. A result summary explains what was checked and what remains uncertain, rather than treating “a command passed” as proof that the product works.

Open choices stay together in the central decision log, with links to the relevant plan or prototype. After you answer, the agent records the agreed outcome and removes the question. The human log is an inbox, not an archive. Routine implementation details, check results and progress updates do not become decisions for your review.

Agent evidence lives separately in .agents/cg/decisions/, using a small JSON file for each material decision. A tiny sequence file prevents reused identifiers; it contains no history. Records remain only while active work, required preservation or a specific retention obligation needs them. Once useful meaning and necessary approval evidence have been preserved in their existing permanent homes, obsolete records are deleted. Merely resolving a question does not justify deleting evidence still needed by unfinished work.

Older mixed logs are migrated as their decisions are touched: preserve the original answer and identity, verify the separate copy, then remove technical details or completed entries from the human log. Unrelated or conflicting evidence is not silently overwritten. No adopting repository is automatically migrated by installing a new CLI.

Agree intent, then deliver a sprint

After init, run warmup for either a new or existing project. Warmup maintains .agents/cg/project-context.md as a concise copy of intent from available vision and specifications, incorporating approved decisions that shape the project, then asks the owner to confirm the interpretation. Code that violates accepted intent is a finding to correct; it does not redefine the intended product. cg intent verify checks whether the reviewed page and its declared binding sources still match attributed approval. It does not prove the implementation conforms or authenticate who approved it.

For new work, /cg-plan agrees a goal, objectives and expected outcomes in one Sprint Plan, or an Epic Plan containing several sprints. A sprint is a bounded, reviewable increment containing whatever features, bugs and tasks serve its goal. Contract impact, dependencies, uncertainty, compatibility risk and review burden guide grouping; there is no fixed contract-count threshold. The plan starts with a short executive summary and retains complete agent detail below it.

/cg-produce implements the selected sprint, preparing small changes internally and collecting related corrections into the agreed review batch. Contracts, binding detectors and required safety checks stay current. Unstable application tests and final documentation may wait until the working result is accepted. /cg-sign-off then finishes those obligations and repairs failures on the same implementation. Acceptance of a preview is not verified completion.

A request to complete a sprint or epic authorizes this continuation without repeated skill invocations. Human acceptance and material product choices still require actual answers. A request merely to agree a plan does not authorize implementation; completion does not itself authorize merging or publication. /cg-unblock records decisions against stable sprint and item IDs.

New roadmaps declare Delivery: sprint. Their existing Phase map rows represent sprints, prepared queues hold finishing work, and delivery records retain review and completion evidence. The separate preparation and auto-run skills remain retired. There is no parallel legacy delivery workflow. Repository-owned workflow policy survives upgrades; reconcile deliberate restrictions rather than silently replacing them.

Organising a Sprint or Epic Plan

A sprint is a bounded, reviewable increment toward an agreed goal. It can contain several features, bugs and supporting tasks; a calendar timebox is optional and its expiry never means completion. An epic contains several dependent sprints in one master plan. Group work by a coherent outcome, dependencies, contract impact, compatibility risk, uncertainty and review burden. The number of contracts is an impact signal, not a fixed threshold, and ticket type is not a useful sprint boundary.

The master plan opens with a short Executive Summary: Problem/Opportunity, Solution Overview and Plan Overview. Complete agent detail follows below, using the same stable sprint and Feature/Bug/Task IDs. Keep useful context instead of making the owner read every technical task to agree the outcome. The summary explains both what each sprint achieves and how it will achieve it.

For example, a reliable export sprint can contain a filtered CSV feature, an empty-state bug fix, regression coverage and documentation. Implement the feature and fix for one review batch, then complete the deferred coverage and docs against accepted behavior. Eight related corrections can stay in one batch. A separate background-export sprint is justified if it has a distinct infrastructure dependency and useful intermediate outcome, not merely because it is another feature.

A full sprint-completion request authorizes implementation, review coordination and finishing within that scope. An epic request can continue successive ready sprints; one-sprint authority stops at its boundary. Neither approves unseen UX nor grants merge or release permission. Routine in-scope corrections update the same plan; a materially changed goal needs the affected decision, not automatic regeneration of every artifact. Record consequential decisions once, scoped to the sprint name/ID and affected item IDs.

During working-result review, unstable application tests and final documentation can be deferred with named obligations. Contract truth, binding detectors, launch/build and risk-critical checks remain immediate. Stable non-UI logic may need early tests. Prepared finishing queues retain their assigned gates, and a failed gate remains unfinished work to investigate and repair. A changed test expectation must follow the accepted promise rather than conceal an implementation defect.

Internal execution queues support finishing and repairs; they are not another owner-facing planning stage.

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; an iteration that edits contract YAML runs cg verify immediately.

Explicit prototype acceptance leads to an Active roadmap describing the actual provisional code and remaining obligations, without another plan invocation. The programme’s top-level Status: is Proposed, Active, or Complete; phase-table statuses are Current, Blocked, Complete, or Future. Both loops end at cg delivery handoff; the same sign-off completes tests/docs and verification, using produce for implementation repairs. Prototype acceptance never marks the initiative delivered. See Prototype for recovery, review evidence, and optional merge protection.

Planning readiness and production review

Planning establishes enough context for a bounded implementation: current behavior and known failures, responsible contracts and consumers, likely approach, prerequisites, risks, immediate checks and deferred obligations. Unknown product decisions block dependent work. Exact implementation actions are refined in production rather than through a second preparation stage.

Before starting production, the agent asks whether to implement all remaining items and review them together, or review after each developed item. It uses selectable options when the host supports them in the current mode, with numbered chat options as a fallback. If scope is also unclear, it collects both choices together. It reuses answers already supplied and remembers the choice for that run; after an answer, it resumes eligible work without another start command. In batch mode it explains that input-dependent steps will wait while independent items proceed. Those skipped steps remain visible and incomplete; their dependents wait too. Per-item mode pauses for each item's review before implementing the next.

Every production run ends with a compact table: Item (Feature/Task/Bug summary, status and plan link), Code, Test, Docs. The work columns use Yes, No, Partial or Blocked. The agent briefly explains exceptions, missing inputs and deferred obligations, then recommends the next action from actual remaining work. When the requested work and its required acceptance and verification are complete, it reports None; it does not invent another sign-off stage. A completed implementation can still await review, tests or documentation.

The agent checkpoints progress in the existing plan and evidence records, recovers pending questions and recorded answers, and resumes eligible work within the original request. Automatic continuation does not require a separate mode or Manager/Engineer hierarchy. A full-completion request carries work through review, finishing and in-scope repairs; required human acceptance and real blockers remain stopping conditions.

How a prepared queue 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. The roadmap is the sequence you agreed. It is not current product behaviour. Current behaviour stays in contract.yaml.

Production’s internal preparation turns the selected finishing or repair work into a queue when needed: <docs>/plans/<programme>/<phase>_detailed_preparation.md. Each step names what it may change, what it depends on, what blocks it, and the command that proves it. Priority is only a tie-break among ready work. 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, or the explicitly measured prototype baseline admitted for its first corrective Step. During finishing, required implementation repairs, tests and contract changes close together. Initial working-result review may defer unstable tests/docs as recorded obligations. When the step's gate and cg verify pass, that handoff is the starting point for the next ready step. 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 removed once their evidence and active consumers are accounted for. Knowledge that must survive goes into contracts, product rules, or durable docs — not into a plan you are about to delete. A defect that is still this phase's behaviour returns to produce. A finding that was never this phase returns to plan.

Technical queues keep one Step In progress in a single integration context. States are Waiting (dependencies incomplete), Ready (dependencies and baseline satisfied), Blocked (a named decision or external prerequisite), In progress, and Complete (gate passed and handoff recorded). Choose the lowest-numbered Ready Step. For Steps 1–4 where 2 is blocked, 3 depends only on 1 and 4 depends on 2, the valid order is 1 → 3 → 2 → 4.

Repository-wide residue belongs at closure, not inside a Step prerequisite. cg next detects direct global residue commands in fenced shell Done when blocks and routes to production repair; it cannot interpret arbitrary wrappers or prose. A scoped residue check does not waive a repository-required global gate. Another programme’s files must be handled by their owner, not removed to make a check green.

Reviewing responsibility ownership

Planning and implementation compare the proposed behavior with existing owners and relevant sibling implementations. Sign-off checks the final result, including compatibility paths, repeated resolution or lifecycle logic, mixed coordinators and changed test fixtures. A single entry point or one ownership sentence does not establish that a large implementation is cohesive. Similar code can also serve different promises; extraction needs evidence of a shared responsibility.

The existing acceptance evidence records what was compared, the owner, the decision and each finding's disposition. Introduced or worsened ownership defects return to production before completion. Pre-existing issues outside the agreed outcome retain an owner and explicit follow-up; they do not silently disappear when a plan is deleted. Separate implementations can be retained with an evidenced reason. A small change needs only a proportionate comparison, not a repository-wide audit.

This is an agent review obligation. Graph checks validate declarations, source inspection gathers syntax facts, and delivery closure runs the supplied gate and retains evidence. Those tools do not automatically prove semantic uniqueness or the quality of the architectural judgment.

Verification without duplicate work

Preparation assigns checks for the changed promises, applicable detectors, and affected consumers. Produce executes that assignment. Sign-off uses one final evidence inventory for Step obligations, composition, and the full repository gate. Checks run again when relevant inputs change or their applicability is uncertain; a stage transition alone does not invalidate a recorded result.

Coverage follows changed behavior and invariants, rather than requiring a new test file for every class. Existing sufficient coverage can be retained. Internal edits with unchanged contract facts need an impact assessment but no artificial YAML change. Repository-required gates remain binding; Contract Graph does not yet calculate safe implementation impact automatically.

Keeping documentation small

Each fact has one home: contracts for structural truth, the roadmap for programme outcomes, the phase queue for Step state and inline handoffs, and one phase acceptance record for final evidence. Later stages link those records. They do not require another report that repeats them. Shared phase context appears once above the Step sections; current notes are updated rather than appended forever.

A guide or decision is created only for an unmet reader need. Closing a phase can require no durable documentation change. Existing evidence remains available, but its preservation does not require copying the same narrative into every handoff.

Successful completion includes cleanup of the finished scope’s temporary files. Update existing product/operator documentation, approved intent, contracts and applicable rules before deleting their planning sources. Preserve actual owner approval when intent changes. Keep shared plans and evidence still needed by active work, and honor explicit repository retention policy; do not create an archive by default. The delivery JSON retains acceptance and final verification, including the sign-off text. Remove its temporary sign-off input after successful close, then verify links and graph truth. A closed receipt does not waive unfinished cleanup.

Decision consolidation at sign-off

Every sign-off accounts for the completed scope’s resolved decisions and relevant design records, even when the plan has no explicit harvest phase. Approved project direction belongs in .agents/cg/project-context.md; structural promises belong in the owning contract.yaml; qualifying policy belongs in the appropriate architecture, engineering or product YAML catalog. Routine implementation choices need no permanent framework entry.

The existing completion evidence records each decision’s disposition and preserves its actual authority before consumed agent records are deleted. Scope-owned files under docs/decisions/ can be retired before the final delivery gate once their useful meaning is consolidated and their evidence and incoming links are handled. The sign-off input retains the authority evidence until the delivery receipt stores it. Retain a record when detailed rationale, active dependencies or explicit retention policy still needs it, with that reason stated. Pending questions and other programmes’ decisions are not cleared. Declared harvest cohorts retain their existing classification and routing gates.

This keeps framework context current without turning it into another chronological log. Decision selection and semantic consolidation are agent responsibilities; the CLI checks intent freshness and declared harvest data, not whether every important product decision has been understood.

What the next session is supposed to trust

A permanent contract that cites a plan path or ticket id as the source of a rule cannot survive plan removal. State the current promise in full in its owning contract and keep scheduling evidence in the plan.

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.

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. The next step, and the next person or agent, starts from that pair.

Delivery records and routing

cg next and cg status derive their answers; they create no second progress ledger. Roadmap Status is Proposed, Active or Complete; Phase map rows use Current, Blocked, Complete or Future. Proposed sprints route to planning. Active sprint iteration reports delivery-review and routes to produce; a non-closed sprint receipt denies prototype dispatch. Malformed roadmap headers block delivery while allowing planning repair. Explicit programme selection isolates unrelated plans.

Both loops meet at cg delivery handoff, which validates the shared roadmap, review freshness and accepted scope and records source/review snapshots. A Handed off receipt routes to the common delivery-completion procedure. Without a queue, sign-off finishes from the roadmap; it does not demand a preparation document. Before handoff, sign-off can assess with handoffReady: false but cannot treat development as accepted. See upgrade for earlier receipt locations and command aliases.

Skill admission is not execution readiness. A blocked queue, or a complete queue with an active completion request, can admit produce with executionAllowed: false to prepare an in-scope repair. Implementation waits for an eligible Step. Completion requests retain the owner’s actual words and scope; the CLI does not authenticate identity or interpret free text as unlimited authority.

These mechanisms check records, freshness and routing, not product satisfaction, safe concurrent writes or model judgment. Review cadence, report formatting and specialist behavior remain agent instructions; no live lower-capability-model trial is claimed. Runtime coverage lives in delivery tests and intent tests; the procedure lives in the shipped skills.

Seeing where you are

These commands inspect the same disk state the stages use. They do not require the last chat.

cg init --docs can place plans somewhere other than docs/. cg residue prints the plans directory that is actually in use.

Related

• Vision — why the graph exists.
• Contracts — node shape and what verification proves today.
• Lifecycle — the stages and the structural walk they share.
• Upgrade — Update through cg init, preserving repository choices.

Coordinating specialist work

Produce and prototype support optional coordinator-led execution or a single agent. See experts and coordination for ownership, recovery, parallel-work limits and extending the supplied expertise.

Bounded corrections and programme selection

A concrete authorised correction with clear ownership, expected behaviour and checks can proceed through cg-produce without creating a roadmap, queue or receipt solely for process. The agent routes, inspects, implements, verifies and reports. Combined result review is the default for this path; explicit per-item preferences and required human UX acceptance remain binding. Existing governed programmes retain their gates and records. Consequential uncertainty pauses only dependent work.

cg status --select <slug> saves a selection in this Git worktree's metadata; cg status --clear-selection clears it. Selection persists until cleared or changed, including across branch switches, and is never inferred from a branch. Commands diagnose stale/terminal pointers rather than silently resuming another programme. Explicit --programme takes precedence over CG_PROGRAMME, then the worktree pointer, then existing single-programme/recovery selection. Concurrent sessions should use their own CG_PROGRAMME; two worktrees have separate pointers. Non-Git repositories support explicit/environment selection only. Selection grants no acceptance or execution authority. cg status --summary shows all discovered programme obligations without changing selection; ordinary status output and its ambiguity exit behavior remain available.

Checkpoint evidence may include evidenceInputs: ["package.json", "config"] independently of writes. Review freshness retains these inputs and all historical writes even after a writer releases or narrows its declaration. Changing, adding or removing a relevant input invalidates scoped review; unrelated files remain outside that established review scope. Legacy unscoped approval and final closure retain whole-repository semantics. Inputs cover Git-visible source only; ignored/generated/external dependencies still need appropriate explicit checks. Declaring an evidence input does not grant write permission or establish that every dependency was discovered.

Successful closure losslessly compacts legacy receipts as part of the atomic final write. cg delivery compact --programme <slug> remains available for Closed receipts. --format delta opts a closed receipt into v3 snapshot-array splice compression when it is smaller than v2; --format v2 converts it back losslessly. V3 retains every logical event and unknown field, bounds delta chains at 32, and checks reconstructed digests. Older executables cannot read v3: coordinate readers before opting in. New receipts remain v2 by default, active v1 receipts remain v1 until closure, and later writes to a migrated v3 receipt compare v3 with v2 and may fall back to v2 when smaller. No history is pruned and no fixed size or merge-conflict guarantee follows.

Explicit standalone admission

For an authorised bounded correction while unrelated programmes are open, write a temporary JSON request with task and writes (repository-relative files/directories, no globs), then use cg next --for cg-produce --standalone <file> --json. It does not change the worktree pointer, plans or receipts. Do not combine it with --programme or CG_PROGRAMME. Installation and intent gates still apply.

Unknown programme scopes return source paths and a fingerprint. Read those sources and dependency contracts, then provide scopeReviews entries containing programme, that fingerprint, complete affected paths and a nonempty reason for independence. Re-run admission. Known receipt write/evidence overlap cannot be overridden by a narrower assessment; changed programme evidence invalidates a review. Shared configuration and verification inputs belong in the assessment. Unknown scope remains a review prerequisite, not permission to implement. This does not enforce write confinement or prove semantic independence. For hook dispatch, set CG_STANDALONE to the request path in the hook process environment and clear it when returning to programme work. Existing completion-chain scope remains binding.

Closed records recommend no action when their programme plan directory is empty. Retained files recommend cg-sign-off for cleanup assessment only, with entry: cleanup-review and handoffReady: false; neither production nor another closure is authorised. Suspended and Abandoned work still needs an actual resume request.

cg status --summary --compact --json shares installation, intent and recovery metadata once. Programme rows retain state/action, receipt identity, queue/cleanup counts and a detailed retrieval command. hasProblems preserves failure status even if failing rows are omitted. The compact JSON budget is 64 KiB; counts and retrieval expose omissions. Expanded summary remains the default compatibility format.

Compaction gain depends on the record population. Repeated identical evidence may already be efficiently interned in v2; changing snapshots can benefit from v3 splice deltas, while unique historical evidence still occupies space. Compare per-record identity, state, format, byte size and reconstructed logical equality before drawing aggregate conclusions. A zero-gain subset and a mixed population with savings can both be correct. Compaction is not pruning, and a smaller query response does not imply a smaller retained receipt.