Skip to content
CoDev

Onboarding Guide

Start here. This is the short version — what CoDev does, the mental model behind it, and what a day of work actually looks like. This page is the why; for the tactical how — what to actually say to your agent — see Talking to Your Agent. Want to just try it right now instead of reading first? Tutorial 1 walks one small bug fix start to finish. For the exact command sequence once you know the shape, see Manual CLI Walkthrough. For the full technical map (every command, skill, and agent), see docs/product-map.md.

The problem

Section titled “The problem”

AI can now write plausible code faster than a human can review it. That creates a new failure mode: velocity without accountability. A model can invent an API that doesn’t exist, “fix” a test by weakening it, or quietly expand a bug fix into a redesign — and do all of it fluently enough that a tired reviewer skims past it. CoDev exists to make AI-assisted development fast without being unaccountable.

The mental model

Section titled “The mental model”

Think of CoDev as a narrow waist between what you actually want (an outcome, a design decision, a bug report) and the diff that delivers it. Three ideas carry almost all of its behavior:

  • Repository grounding. An AI’s claims about how the code works are worth nothing until checked against the actual files. Every skill starts with inspection, not proposal.
  • One fact, one owner. Outcome and scope live in a brief. Architecture lives in a design document. Assignment and status live in a wave plan. Behavior lives in code and tests. Nothing gets copied between documents — later documents link to earlier ones. If you find yourself updating the same fact in two places, one of those places is wrong.
  • Small, reviewable, evidence-backed changes. A change is done when it’s small enough to review, validated with commands you can rerun, and an independent reviewer — human, and automatically also AI — has looked at the exact diff.

If you remember nothing else: the AI supplies evidence, you supply authority.

A running example

Section titled “A running example”

Say a salt-form compound’s computed molecular weight is wrong: the pipeline’s descriptor calculator is supposed to strip the counter-ion before summing atomic mass, but doesn’t. That one bug threads through every section below, and it’s the exact example Tutorial 1 builds end to end with real commands.

The four steps you’ll actually see

Section titled “The four steps you’ll actually see”

You never have to name a skill. Describe what you want, and CoDev resolves it to one of four steps:

Step Question it answers The descriptor example
Understand (define-product) What are we building, and what has to be decided first? Nothing to decide here — the expected behavior is unambiguous: exclude_salts=True must strip the counter-ion before summing mass. Straight to Build.
Build (build-change) What’s the smallest change that delivers this, with evidence it works? Fix the calculation so salt fragments are stripped before the sum runs, not after. Add a regression test with a salt-form compound.
Review (review-change, plus an automatic pass) Is this exact change correct, safe, and consistent with what we agreed? Confirm the fix doesn’t change the weight of a single-fragment compound — a real, narrow correctness check, not a style nit.
Ship Are we ready to expose this, and how will we know it’s working? A descriptor calculation fix like this usually ships straight through — no staged rollout needed unless it feeds a regulated potency calculation.

A small, local, reversible fix like this one goes Understand → Build → Review → Ship in minutes, with Understand collapsing to “here’s the bug, here’s the expected behavior.” A new product spends real time in Understand instead, because getting the outcome and architecture right is what makes everything after it cheap. The step names don’t change. Only how much work each step requires changes — and that’s decided by risk and coordination need, not by habit.

Two of the twelve installed skills sit outside this table because they don’t fit the four-step shape: pr-review reviews a GitHub Pull Request that already exists (possibly not even yours), and critique-review turns an existing finding into a concrete suggested diff — a bridge from a review to a fix, not a review itself. design-skill-eval, technical-writing-style, and testing-craft are different kinds of tools again: design-skill-eval scaffolds evaluation tasks so you can measure whether a skill actually helps, empirically, rather than just trusting it; technical-writing-style is what the other planning skills read automatically before drafting prose, and what you can invoke directly to revise an existing document’s writing quality; and testing-craft is what specify-project, design-solution, and build-change read automatically before they design or write test content, and what you can invoke directly to design a test strategy, audit an existing suite’s health, or triage a flaky test.

Two steps that only show up sometimes

Section titled “Two steps that only show up sometimes”

Design (design-solution) and Plan (plan-wave) are not extra stages everything passes through — they’re conditional depth inside Understand, triggered by real properties of the change: a shared API or data contract, an authentication or privacy boundary, or more than one developer working the same area concurrently. The salt-stripping fix above skips both — it’s a one-line, single-developer, non-contract change. Tutorial 2 walks a change that does need design-solution, and Tutorial 4 walks one that needs plan-wave.

At the very edges: Specify (specify-project) is for a genuinely new product or a whole-product redesign — one guided interview producing a single canonical specification, used rarely. Launch (launch-product) is for real rollout risk — staged exposure, rollback readiness, the kind of decision a change touching real money or real users at scale needs. Most changes never touch either.

Who does what

Section titled “Who does what”
Human AI
Understand States the problem, makes the product/architecture call Investigates the repository, proposes framing, asks one targeted question at a time
Build Approves the plan, answers stop-condition questions Grounds the plan in real code, implements, tests, self-checks
Review Reads the exact diff, decides whether it may merge Produces an independent, evidence-based review
Ship Authorizes exposure and expansion Assembles readiness evidence, proposes rollout stages

Two artifacts carry the handoff between AI activity and human control, and neither needs to be a separate document for ordinary work like the salt-stripping fix — a few lines in the conversation is enough:

  • The focus card, presented before any editing begins: what’s changing, what success looks like, what’s explicitly out of scope, which files are fair game, how it’ll be validated, and what should stop work and return to you.
  • The evidence receipt, returned when implementation is “done”: what changed, the exact commands run and their output, which acceptance criteria map to which evidence, any deviations from the plan, and current review status.

They become written artifacts (the templates under .agents/skills/*/assets/) once work spans sessions, touches several components, or carries enough risk that a reconstructable record matters.

Review, in practice

Section titled “Review, in practice”

Every change gets an independent human review — whoever wrote it, human or AI, does not approve it. Where the platform supports subagents, this mostly happens without you orchestrating it by hand: a fast correctness check runs after each build, a style and maintainability gate runs automatically right before a pull request opens, and once that PR exists, five specialist reviewers — correctness, security, concurrency, architecture, rollout — examine it in parallel and hand you exactly the findings that need a decision. You triage; CoDev does not decide for you which finding matters (Tutorial 3 walks this end to end). review-change still exists for the case none of that covers: a diff with no task and no open PR yet, reviewed on demand.

Where it breaks down (and how CoDev catches it)

Section titled “Where it breaks down (and how CoDev catches it)”
Failure mode What it looks like The guardrail
Hallucinated implementation AI invents an API or config key that doesn’t exist Mandatory repository inspection before proposing; the reviewer checks claims against the diff
Scope creep A bug fix quietly becomes a refactor The focus card’s allowed scope is a drift boundary; expansion must be surfaced before acting on it
Self-approval The implementing AI declares its own work done The builder cannot invoke another agent or approve; the reviewer is a fresh, independent context
Retry spiral Repeated attempts at the same broken approach Stop after two failed attempts with the same root cause; escalate to the human
Stale plan drift The repository moved under the plan mid-implementation Base-commit and snapshot checks; a changed base is a stop condition, not something to paper over
Rubber-stamp review A review that restates the diff instead of finding problems Reviews must cite evidence and end in one of three explicit states: READY FOR HUMAN APPROVAL, CHANGES REQUIRED, BLOCKED BY MISSING EVIDENCE

Multi-developer, briefly

Section titled “Multi-developer, briefly”

One rule carries most of it: every component or contract has one responsible owner, and the owner and reviewer are never the same person. Two developers can work in parallel once they agree on a shared contract — say, the exact shape of a Descriptor the calculation engine and the screening request surface both depend on — and a fixture to test against it, rather than discovering the mismatch after both branches are done. See Tutorial 4 for a worked example.

Where to go next

Section titled “Where to go next”