The workflow

Every change in a codev project goes through the same four steps. Each step has a Claude Code skill, and — except for implementation — a CLI command that does the underlying work.

┌───────────┐    ┌───────────┐    ┌───────────┐    ┌───────────┐
│  propose  │───▶│   apply   │───▶│   sync    │───▶│  archive  │
│ plan it   │    │ build it  │    │ merge the │    │ file it   │
│           │    │           │    │ deltas    │    │ away      │
└───────────┘    └───────────┘    └───────────┘    └───────────┘

Two more skills support the cycle: /codev-explore to think an idea through before proposing anything, and /codev-update to revise a plan that is already written. See Claude Code skills.

At each step, the agent works in a defined role — product owner, QA analyst, architect, tech lead, skeptical reviewer, developer — with criteria it checks before moving on, and stops where you decide. See Roles.

Propose

Proposing creates a change folder and writes its planning artifacts. With the default spec-driven schema, a change has four artifacts:

The dependencies form a graph: specs and design can be written once the proposal exists, and tasks once both are done. codev status reports each artifact as done ([x]), ready to write ([ ]), blocked on a dependency ([-]) or skipped ([~]). State comes only from which files exist — codev keeps no state file.

In Claude Code, /codev-propose does everything in one pass:

1. If your request mentions a ticket identifier such as PROJ-123 and a Jira MCP server is configured, it fetches the ticket first. See Jira and other MCP servers.
2. It creates the change with codev new change <name>.
3. For each artifact that is ready, it runs codev instructions <artifact> --change <name> --json, studies the relevant code, and writes the file following the template.
4. It checks traceability between proposal, specs and tasks, then challenges the plan as a skeptical reviewer, writing each finding to the change’s review record, fixing what is unambiguous and listing up to five points to challenge. See Propose.
5. It stops when planning is complete and presents the plan. It never starts implementing in the same turn.

When writing design.md, the skill receives the architecture decisions currently in effect, so the design follows them — or proposes explicitly to supersede one. See Decisions.

A change that has no behavioral impact — a refactor, a dependency bump, documentation — declares skip_specs: true in its change.yaml. The specs artifact is then skipped, and validation accepts the absence of deltas.

Apply

/codev-apply <name> implements the plan. It reads tasks.md, works through each unchecked - [ ] task in file order, runs the verification the task names (a test, a command, an observable behavior), and checks the box only once it passes. Tests follow your existing test suite first, then your language’s conventions and your rules. Once every task is checked, it re-reads the code the change touched as a newcomer to the project would, joined by the experts the proposal’s domains activate, simplifies what is unambiguous without widening the scope, and lists up to five review notes in its summary. Every finding is kept in the change’s review record, with the author’s answer and the reviewer’s check; what only you can decide is listed at the end. Then it runs the full test suite once.

It stops at the first blocker or ambiguity and asks you rather than guessing. It modifies only the named change, never archives and never syncs: those remain explicit steps for you to request.

apply is the only skill allowed to run arbitrary shell commands, because it has to run your tests. There is no CLI equivalent: implementation is the agent’s job.

Sync

codev sync --change <name>

Syncing merges the change’s deltas into the main specs under _codev/specs/ without moving the change. Use it when another change in progress needs to see a new capability in the main specs, or to review the merge before archiving.

Syncing is idempotent: running it again reports the specs as unchanged. In the usual case you skip this step — archiving syncs for you.

Like archiving, syncing validates the change first and refuses if validation reports an error: nothing is written, and codev validate <name> shows the findings.

Archive

codev archive --change <name>

Archiving closes a change:

1. It validates the change and refuses if validation reports an error, pointing you to codev validate <name> for the details.
2. It checks the review record and refuses (review_blocked) if it is missing for a step where review roles were active, or if a high-severity finding is still open or disputed; codev review --change <name> shows what is left.
3. It merges the deltas into the main specs, exactly as sync does.
4. It moves the change folder, review record included, to _codev/changes/archive/<YYYY-MM-DD>-<name>/.

The whole merge is computed and checked before the first file is written, so an invalid change or a delta that does not apply — for example a MODIFIED requirement missing from the main spec — is reported before anything on disk changes.

After archiving, the main specs describe the behavior you shipped, and the archived folder records why and how it changed. Commit both — and, if the change has a release note, run codev changelog --write to add it to CHANGELOG.md (see Release notes and CHANGELOG).

Choosing the change

codev status, codev instructions, codev sync and codev archive accept --change <name>. When the project has exactly one active change, you can omit it. With several, codev asks you to choose:

error: several active changes: add-audit-log, rework — specify which one
help: `--change add-audit-log`

Change names are kebab-case: lowercase letters, digits and hyphens, such as add-user-auth.

Validating

codev validate

Without arguments, codev validate checks every active change, every main spec and the decision seals. Pass a change or capability name to check one item, or --changes / --specs to check one family. Errors make the command exit with status 1; with --strict, warnings do too — use it in CI:

codev validate --strict

The checks cover the structure of specs and deltas (every requirement uses SHALL or MUST — or DOIT or DOIVENT — and has at least one #### Scenario:), consistency inside a delta (no requirement both added and modified, no rename colliding with an addition), the zero-delta rule, and the integrity of sealed decisions. See File formats for the rules each file must follow.