Quickstart

This chapter takes you from an empty repository to your first archived change in about five minutes. It assumes codev is installed and that you use Claude Code.

Each step shows the Claude Code way first (recommended), then the plain CLI equivalent, so you can see what the skills do underneath. The command output below is real, with the project path shortened to /home/you/acme-app.

1. Initialize the project

At the root of your repository:

codev init

On a terminal, codev init asks at most two questions — which workflows to install and a free-text context for the skills — then writes the files. Pass --yes to accept every default without prompting, as in this run:

codev init --yes --language en

codev initialized in /home/you/acme-app

  Structure   _codev/ — specs, decisions, changes, schemas
  Skills      codev-propose, codev-explore, codev-onboard, codev-apply, codev-sync, codev-archive, codev-update, codev-configure → .claude/skills/

  Repository integration
    + CLAUDE.md                          created
    + .github/workflows/codev.yml        created
    + .github/PULL_REQUEST_TEMPLATE.md   created

  17 file(s) created, 0 updated

→ Recommended next step: in Claude Code, run /codev-configure.
  Claude will analyze the project and enrich _codev/config.yaml
  (context, per-artifact rules) — ~30 seconds.

Or skip this step and run /codev-propose <an-idea> directly.

Run `codev doctor` to see the 2 setup check(s) still to fix.

This repository has a GitHub remote, so codev also wrote a CI workflow and a pull request template; see step 5 below.

Restart Claude Code (or start a new session) so it discovers the new skills.

What `codev init` does

Probes the environment, silently: project manifests (Cargo.toml, package.json, pyproject.toml, go.mod, pom.xml), the license file, the presence of .github/workflows/, your locale, and the MCP servers declared in .mcp.json, .claude/settings.json and ~/.claude.json. --no-detect skips the probe.
Asks at most two questions when run on a terminal: which workflows to install (full, minimal, or custom) and a free-text context for the skills. An empty answer to the context question opens $EDITOR on a skeleton. A detected Jira MCP server is confirmed rather than asked for. With --yes, or when stdin is not a terminal (CI, pipes), no question is asked.

Creates the _codev/ tree — specs/, decisions/, changes/, changes/archive/, schemas/ — and a _codev/config.yaml in which every detected value carries a comment saying where it came from:

# codev configuration — generated by `codev init`.
# Hand-editable: each non-trivial field carries its source as a comment.

schema: spec-driven

# Language of the prose skills write in artifacts (proposal, design,
# tasks, specs). Structural keywords such as `## Why` or
# `### Requirement:` always stay in English.
# set with `codev init --language`
language: en

workflows:
  - propose
  - explore
  - onboard
  - apply
  - sync
  - archive
  - update
  - configure

Installs the skills into .claude/skills/codev-<workflow>/SKILL.md.
Integrates codev into the repository, unless you opt out:
- a codev section in CLAUDE.md, created if missing, telling Claude Code that the specs are authoritative and that behavior changes go through /codev-propose then /codev-apply;
- on GitHub, .github/workflows/codev.yml, which runs codev validate --strict on every push and pull request;
- on GitHub, a codev section in the pull request template.
codev’s text sits between  and  markers and never replaces yours. --no-claude-md, --no-ci, --no-pr-template and --no-integration skip these files. See Repository integration and codev doctor.
Declares inherited sources given with --inherit, and pins the git ones right away. See Inherited sources.

If _codev/config.yaml already exists, codev init leaves it untouched: it only installs or refreshes the skills and the repository integration.

codev doctor then lists what the setup still lacks — here, rules and a first spec — with the command or skill that fixes each item:

codev doctor

codev doctor — /home/you/acme-app

Configuration
  ✗ config.rules     no rules: in _codev/config.yaml
      fix: /codev-configure
  ✓ config.language  language: is set
  ✓ config.keys      no unknown key in _codev/config.yaml
  ✓ config.roles     active roles: analyst, investigator, product, qa, architect, lead, tracer, skeptic, developer, newcomer; on domain: security (security), privacy (personal-data), accessibility (user-interface), performance (performance), ops (operations), migration (migration); disabled: none
  ✓ skills           8 skill(s) installed and current
  ✓ sources          no inherited git source
  ✓ codev_version    no newer codev release known

Planning
  ✗ specs            no main spec in _codev/specs/
      fix: /codev-propose <a change> — documenting existing behavior is planned work too
  ! decisions        no accepted decision (not every project needs one)
      fix: codev decision new "<title>"
  ✓ validate         codev validate reports no issue

Repository
  ✓ claude_md        CLAUDE.md has the codev section
  ✓ ci               .github/workflows/codev.yml runs codev validate
  ✓ pr_template      the pull request template has the codev section
  ! changelog        no CHANGELOG.md
      fix: codev changelog --write

14 check(s), 2 to fix, 2 warning(s)

Note The recommended next step, /codev-configure, lets Claude read your README, contributing guide and a sample of your code, then propose a richer context: and per-artifact rules: for the configuration. It shows a diff and writes nothing without your confirmation.

2. Propose a change

In Claude Code, describe what you want:

/codev-propose add a dark mode that follows the system preference

The skill picks a kebab-case name (here add-dark-mode), creates the change, then writes its four planning artifacts in dependency order: proposal.md, the spec deltas under specs/, design.md and tasks.md. It modifies no code, and stops once the plan is ready for your review.

Underneath, it starts with:

codev new change add-dark-mode --goal "Let users switch the UI to a dark theme"

Change `add-dark-mode` created
  Location  /home/you/acme-app/_codev/changes/add-dark-mode
  Schema    spec-driven

Next step: `codev instructions --change add-dark-mode` shows the artifact to write.

codev status shows which artifacts exist and which are waiting on others:

Change: add-dark-mode
Schema: spec-driven

  [ ] proposal
  [-] specs (waiting on: proposal)
  [-] design (waiting on: proposal)
  [-] tasks (waiting on: specs, design)

Planning: 0/4 artifacts
Next:     proposal

For each artifact, the skill asks codev for everything it needs to write it — the schema’s instruction, the template, the project context and rules, the language, and the files it depends on:

codev instructions proposal --change add-dark-mode

Artifact: proposal (change `add-dark-mode`, schema spec-driven)
Write to: /home/you/acme-app/_codev/changes/add-dark-mode/proposal.md
Language: en — prose only; template keywords stay in English

Instruction:

Write the document that establishes WHY this change is needed.
…

Skills call the same command with --json and receive a stable document instead.

3. Review the plan

Once the skill is done, read the artifacts in _codev/changes/add-dark-mode/. The spec delta is the heart of the plan — it states the behavior the change adds, as testable requirements:

## Purpose

Let users choose the color theme of the interface.

## ADDED Requirements

### Requirement: Theme follows the system preference by default

The application SHALL render with the operating system's color scheme until the user picks a theme.

#### Scenario: No theme chosen yet

- **GIVEN** a user who has never changed the theme setting
- **WHEN** their operating system is set to dark mode
- **THEN** the application renders with the dark theme

Ask Claude for adjustments with /codev-update, or edit the files yourself. Then check that planning is complete and the change is valid:

codev status

Change: add-dark-mode
Schema: spec-driven

  [x] proposal
  [x] specs
  [x] design
  [x] tasks

Planning: 4/4 artifacts
Planning is complete.

codev validate add-dark-mode

change add-dark-mode — _codev/changes/add-dark-mode
  ✓ no issues

1 item(s) validated, no issues.

Note A change with no spec delta fails validation with zero_delta_without_marker. That is deliberate: it keeps specs from being forgotten. A change that really has no behavioral impact — a refactor, tooling, documentation — declares skip_specs: true in its change.yaml.

4. Implement

/codev-apply add-dark-mode

The skill reads tasks.md, works through each unchecked task in order, runs the verification each task names, and checks the box. It stops at the first blocker or ambiguity and asks you. It is the only codev skill that modifies code outside _codev/.

5. Archive

When the tasks are done:

/codev-archive add-dark-mode

Or with the CLI:

codev archive --change add-dark-mode

Archived change `add-dark-mode`

Created:
  /home/you/acme-app/_codev/specs/ui/theme/spec.md

Moved to: /home/you/acme-app/_codev/changes/archive/2026-09-30-add-dark-mode

Archiving validates the change, merges its deltas into the main specs — here it creates _codev/specs/ui/theme/spec.md, since ui/theme is a new capability — and moves the change folder to the dated archive. Commit the result: the main specs now describe the behavior you just shipped.

What’s next

Every later change follows the same cycle, from a one-line fix to a capability rewrite. The workflow describes each step in detail.
Concepts explains deltas, capabilities and decisions.
/codev-onboard gives a read-only tour of codev and of your project’s current state, with a recommended next action.

Keyboard shortcuts

codev