Repository integration and codev doctor

Specs and skills are not enough on their own: Claude Code must know that the repository works through codev, CI must catch an invalid spec, and reviewers must see which change a pull request implements. codev init sets these up, codev update keeps them current, and codev doctor tells you what is still missing.

What codev init writes

CLAUDE.md

Claude Code reads CLAUDE.md at the start of every session. codev init creates it, or adds a section to yours, so that Claude does not change behavior without a codev change:

<!-- codev:begin — managed by codev; `codev update` rewrites this block, edit outside it -->
## Spec-driven development with codev

This repository follows spec-driven development with codev.

- `_codev/specs/` describes the current behavior and is authoritative.
- `_codev/decisions/` holds accepted architecture decisions: follow them, do not re-debate them.
- For any change of behavior, start with `/codev-propose`, then implement it with `/codev-apply`. Do not modify behavior without a codev change.
- Trivial fixes (typos, documentation wording) are exempt.
- Run `codev validate` before committing.

Installed skills: `/codev-propose`, `/codev-explore`, `/codev-onboard`, `/codev-apply`, `/codev-sync`, `/codev-archive`, `/codev-update`, `/codev-configure`.
<!-- codev:end -->

The section is in English whatever the language: of the project: it is written for the agent. When /codev-apply is not installed, it asks to implement by following the change’s tasks.md instead.

CI workflow

On a GitHub repository — one with a .github/ folder, or a git remote on github.com — codev init creates .github/workflows/codev.yml:

# codev:managed — generated by `codev init`, refreshed by `codev update`.
# Delete this first line to take the file over: codev will then leave it alone.
name: codev

on:
  push:
  pull_request:

jobs:
  validate:
    name: codev validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Install codev 0.6.1
        run: |
          curl -sSL https://raw.githubusercontent.com/mairistem/codev/main/install.sh | CODEV_VERSION=0.6.1 sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Validate specs and changes
        run: codev validate --strict

The installer is pinned to the version of codev that wrote the file, so CI validates with the same rules as your machine. codev does not write this file when:

• another workflow of .github/workflows/ already runs codev validate — any line naming codev then validate counts, such as cargo run --bin codev -- validate;
• .github/workflows/codev.yml exists and was not written by codev (its first line is not # codev:managed).

codev never edits any other workflow file. On a GitLab repository — a .gitlab-ci.yml file, or a remote on GitLab — it does not touch .gitlab-ci.yml and prints a job to paste instead:

  Repository integration
    + CLAUDE.md                          created
    - .gitlab-ci.yml                     skipped: codev never edits .gitlab-ci.yml — add the job below to run codev validate

        codev:
          image: debian:stable-slim
          before_script:
            - apt-get update -qq && apt-get install -y -qq curl ca-certificates
            - curl -sSL https://raw.githubusercontent.com/mairistem/codev/main/install.sh | CODEV_VERSION=0.6.1 sh
          script:
            - ~/.local/bin/codev validate --strict

    - pull request template              skipped: not a GitHub repository

Elsewhere, the step is skipped with a hint: add codev validate --strict to your pipeline.

Pull request template

On GitHub, codev init adds a section to your pull request template — the first pull_request_template.md found in .github/, the project root or docs/, in any case — or creates .github/PULL_REQUEST_TEMPLATE.md:

<!-- codev:begin — managed by codev; `codev update` rewrites this block, edit outside it -->
## codev

- codev change: <!-- folder under `_codev/changes/`, or "trivial fix, no change" -->
- [ ] `codev validate --strict` passes.
<!-- codev:end -->

Managed sections

codev’s text in CLAUDE.md and the pull request template sits between two HTML comments, invisible once the markdown is rendered:

<!-- codev:begin — managed by codev; `codev update` rewrites this block, edit outside it -->
…
<!-- codev:end -->

• Everything outside the markers is yours and is never modified. A section added to an existing file goes at its end, after a blank line; you may move the whole block anywhere.
• codev update rewrites what lies between the markers, and nothing else: edits you make inside the block are lost on the next update.
• When the markers are unbalanced or repeated, the file is left alone and the managed_section_malformed warning names it.

The workflow file is codev’s as a whole. codev update rewrites it, which moves its pinned version after an upgrade, as long as its first line is # codev:managed. Delete that line to take the file over: codev then leaves it alone.

codev update only refreshes what exists. It never creates CLAUDE.md, the workflow or the template, and never adds a section to a file that has none.

Opting out

The flags apply to one run of codev init. A later codev init without them writes the files; codev update never does.

codev doctor

codev doctor checks the whole setup and gives, for each gap, the command or skill that closes it. It is read-only and works offline; for the changelog check, it asks the local git repository which changes were archived since the latest tag:

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        CHANGELOG.md matches the archived changes

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

✗ marks a missing item, ! a warning — a project may legitimately have no accepted decision. The pr_template check only appears for GitHub repositories. The changelog check, a warning only, compares the [Unreleased] section of CHANGELOG.md with what codev changelog generates; the fix is codev changelog --write — see Release notes and CHANGELOG. The codev_version check is missing when the running codev does not satisfy the project’s codev_version, and a warning when the update cache knows a newer release; the fix is codev self-update, or codev self-update --version <X.Y.Z> when the running codev is newer than the requirement allows. The config.keys check warns about keys of _codev/config.yaml this codev does not know — see Unknown keys. The full list of checks is in the CLI reference.

codev init and codev status end with a one-line hint when something is missing, and /codev-onboard lists the missing items with their fix.

In CI, codev doctor --strict exits with status 1 when a check is missing; warnings never fail. codev doctor --json gives the same report to scripts, with stable check ids and codes — see JSON output.