Tutorial 1: your first fix

A start-to-finish walkthrough of one small, real bug fix through CoDev: install, describe the bug, build, review, and (where a GitHub remote exists) open the pull request. By the end you’ll have run every CLI command in the normal inner loop yourself and know what real output looks like at each step — not a hypothetical reconstruction. The CLI commands and output below were run against the real codev CLI while writing this tutorial, including the one mistake in “A mistake you will probably also make” further down.

Who actually types these commands

Every codev ... command below is shown so you can see exactly what happens under the hood. In a real session, your agent runs almost all of them for you — you only supply the plain-language parts, in Step 2 and wherever the tutorial shows you approving something. See Talking to Your Agent for the shape of that conversation.

For the concepts behind these steps, see the Onboarding Guide; this tutorial is the narrated “do this” companion to it.

Who this is for

You have codev installed (pipx install open-codev-workflow or uv tool install open-codev-workflow) and a Git repository you want to try it in — your own, or a scratch one. You don’t need to know anything about CoDev’s internals to follow this.

The bug

A compound-screening pipeline’s molecular-weight calculator is wrong for salt forms: it’s supposed to strip the counter-ion fragment before summing atomic mass when exclude_salts=True, but sums every fragment regardless — so a salt-form compound’s computed weight comes out too high. The fix is genuinely small — this tutorial is deliberately about the smallest realistic case, because that’s the case most people hit first, and the full lifecycle still applies to it.

Step 1: install CoDev into the repository

codev init --target . --agent-platform opencode

ADD       .agents/skills/build-change/SKILL.md
ADD       .agents/skills/build-change/agents/openai.yaml
...
ADD       .opencode/agents/builder.md
...
ADD       docs/codev/README.md
...
INTEGRATE AGENTS.md — append managed policy block
INTEGRATE .gitignore — append escalation-log ignore rule
INTEGRATE .opencode/opencode.json — integrated OpenCode agents: code-audit,
code-audit-gate, builder, reviewer, lightweight-reviewer, ...
Installed CoDev 0.6.0 into /path/to/your/repo

(Real run had ~70 ADD lines — every skill and agent file gets listed. Trimmed here; your terminal will show the full list.) Commit this as one infrastructure change:

git add -A && git commit -m "Install CoDev"

Check it installed cleanly:

codev status --target .

CoDev 0.5.0 - /path/to/your/repo
Bundle: healthy (76 managed files, no drift)
Adapters: opencode
Tasks in progress: 0

Step 2: describe the bug to your AI assistant

Start a session in the repository and state the outcome in plain language – there is no agent to switch to first:

Fix compute_molecular_weight so exclude_salts=True actually strips the counter-ion
fragment before summing mass. Add a regression test with a salt-form compound.

You don’t need to name a skill. The assistant begins with Understand: it inspects the actual descriptor code, and for a change this small and unambiguous, presents a short focus card instead of a full brief — something like:

Change:      exclude_salts=True should drop counter-ion fragments before summing mass.
Success:     A salt-form compound's computed weight matches its free-base weight; a
             single-fragment compound's weight is unchanged.
Non-goals:   No change to fragment-splitting itself.
Scope:       screening/descriptors.py, tests/test_descriptors.py
Validation:  python -m unittest discover -s tests
Stop if:     split_into_fragments doesn't reliably separate the salt from the parent
             (that would be a different, bigger bug upstream).

Nothing here needs a design document or a wave plan — no shared contract changes, no new API, one file. Approve it and move to Build.

Step 3: start and branch the tracked task

Capture the current commit as the base, then start the task and create its branch:

git rev-parse HEAD

4f3aaf0537be7fd58ef431d146c750df6a2a2461

codev task start --id descriptor-salt-stripping-fix \
  --base 4f3aaf0537be7fd58ef431d146c750df6a2a2461 \
  --summary "Strip counter-ion salts before summing molecular weight" --no-github-issue

Started task descriptor-salt-stripping-fix at /path/to/your/repo/.codev/task/descriptor-salt-stripping-fix/round-state.json

(--no-github-issue is only correct for a scratch repo with no GitHub remote, like the one this was run against. In a real GitHub-backed repository, use --github-issue <number> or let your agent create one for you — see Starting Prompts for why that’s worth naming up front.)

codev git branch --id descriptor-salt-stripping-fix \
  --base 4f3aaf0537be7fd58ef431d146c750df6a2a2461

Created branch codev/descriptor-salt-stripping-fix for descriptor-salt-stripping-fix

Your agent normally performs this recording and branching itself as part of the same conversation, in one call to codev slice begin – these two commands are shown separately here so you see exactly what state they create.

Step 4: build, with evidence

Ask the assistant to implement the approved focus card. It inspects the actual code before editing:

# screening/descriptors.py, before
def compute_molecular_weight(mol, exclude_salts=True):
    fragments = split_into_fragments(mol)
    total = sum(
        fragment_mass(f) for f in fragments
    )  # <- salts included unconditionally
    return total

# screening/descriptors.py, after
def compute_molecular_weight(mol, exclude_salts=True):
    fragments = split_into_fragments(mol)
    if exclude_salts:
        fragments = [largest_fragment(fragments)]
    return sum(fragment_mass(f) for f in fragments)

…and adds the regression test alongside the existing one, runs the suite, and reports back:

Delivered:    Salt-form compounds no longer include counter-ion mass in the computed
              weight; single-fragment compounds are unchanged.
Changed:      screening/descriptors.py, tests/test_descriptors.py
Validation:   python -m unittest discover -s tests -v -- both tests pass
Known limitations: none
Review state: AWAITING INDEPENDENT REVIEW

The builder does not commit or call codev task record itself — whoever dispatched it commits the diff and records the evidence against that exact resulting head, in one call to codev round close:

codev git commit --id descriptor-salt-stripping-fix \
  --message "Strip counter-ion salts before summing molecular weight"

Committed cc62907e9ef4942d401826e2d0021f7ed6ab62d4 on descriptor-salt-stripping-fix's branch

codev task record --id descriptor-salt-stripping-fix --round 1 --role builder \
  --head cc62907e9ef4942d401826e2d0021f7ed6ab62d4 --evidence evidence.json

Recorded round 1 (builder) for descriptor-salt-stripping-fix

A mistake you will probably also make

Calling codev task check right after codev git commit, before recording the builder round, looks like this:

codev task check --id descriptor-salt-stripping-fix --head cc62907e9ef4942d401826e2d0021f7ed6ab62d4

stop_drift: round 1: expected head 4f3aaf053...; got cc62907e9...; code changed
outside the tracked builder/reviewer flow

That’s not a bug — it’s the drift guard working exactly as designed (ADR-0001): the tool has no evidence yet that the new head came from a recorded round, so it refuses to assume it did. Record the round first, then check.

Step 5: independent review

A fresh reviewer context — human, and where the platform supports subagents, automatically also AI — looks at the exact diff, not the builder’s private reasoning. It records its verdict:

codev task record --id descriptor-salt-stripping-fix --round 1 --role reviewer \
  --head cc62907e9ef4942d401826e2d0021f7ed6ab62d4 \
  --findings findings.json --coverage coverage.json \
  --decision READY_FOR_OUTER_LOOP

Recorded round 1 (reviewer) for descriptor-salt-stripping-fix

Now check whether the loop may proceed:

codev task check --id descriptor-salt-stripping-fix --head cc62907e9ef4942d401826e2d0021f7ed6ab62d4

ok_ready_for_pr: round 1: inner loop satisfied, ready to open a pull request

--decision READY_FOR_OUTER_LOOP is what routes here — it’s the normal inner-loop handoff, distinct from READY_FOR_HUMAN_APPROVAL (used by review-change’s standalone, no-task, no-PR review path). Using the wrong one is an easy mix-up; if task check reports ok_approve instead of ok_ready_for_pr, that’s why.

Step 6: open the pull request (needs a real GitHub remote)

Once task check reports ok_ready_for_pr, push and open the PR using the guarded Git commands — they act on this task’s branch, never the default branch:

codev git push --id descriptor-salt-stripping-fix
codev git open-pr --id descriptor-salt-stripping-fix \
  --title "Strip counter-ion salts before summing molecular weight"

These need an actual GitHub remote to do anything (this tutorial’s demo repo didn’t have one, so there’s no output to show here — in a real repository you’ll see the PR URL). The PR opens as a draft. For a change this small, the outer loop’s five specialists are optional but still available — see Tutorial 3 if you want to see that in action on a slightly larger change. When ready:

codev git mark-ready --id descriptor-salt-stripping-fix

Step 7: the human decision, and closing the task

You inspect the actual pull request and CI, and decide whether to merge. After that human decision:

codev task close --id descriptor-salt-stripping-fix --outcome approved

Closed task descriptor-salt-stripping-fix as approved

codev status --target .

CoDev 0.5.0 - /path/to/your/repo
Bundle: healthy (76 managed files, no drift)
Adapters: opencode
Tasks in progress: 0

That’s the whole loop. Everything after this point is the same shape, just with more happening inside “Understand” (Tutorials 2 and 4) or “Review” (Tutorial 3) as risk and coordination need actually call for it — never because a bigger change means more ceremony by default.

Where to go next

• A change that touches a shared contract: Tutorial 2
• Reviewing an already-open pull request: Tutorial 3
• Two developers, one shared contract: Tutorial 4
• The command checklist for when you already know the shape: Manual CLI Walkthrough