import { Aside } from '@astrojs/starlight/components';
import Exchange from '../../components/Exchange.astro';

## The core idea

In normal use, you never type a `codev` command. You describe what you want, in plain
language, to the agent you're already talking to — there is no separate identity to
select first. It inspects the actual repository, proposes a plan, and — once you approve
it — runs `codev` on your behalf: opening the task, committing, recording review rounds,
opening the pull request. The CLI is the agent's hands. It doesn't have to be yours.

Everything else on this site that shows a `codev ...` command is showing you the
*mechanism*, not a script to type. [CLI Reference](/CoDev/cli-reference/) and the
[Manual CLI Walkthrough](/CoDev/workflow-checklist/) exist for the moments that genuinely
call for it — CI, scripting, recovering a task by hand — not for everyday work.

## Nothing to select

There is one entry point, and it isn't an agent you dispatch -- it's the conversation you
already have on Claude Code or OpenCode, guided by instructions every session already
reads. Earlier versions of CoDev asked you to start a `planner` session for design work,
an `orchestrator` session (later renamed `lead`) for building, and an `outer-loop-runner`
session for review — and to know which one you needed. Later, `lead` became a single
agent you dispatched instead of three, which was progress but was still a name to know
and a thing to select. A session boundary you have to notice is a command by another
name, and CoDev's whole position is that you don't run commands
([ADR-0044](https://github.com/urban233/CoDev/blob/main/docs/adr/0044-lead-is-not-an-agent.md)).

The separation still exists, but underneath: coordination never edits product code
itself outside an explicitly recorded `pair` slice, and the agents it dispatches can't
review their own work. That's a permission boundary now, not a thing you operate. See
[Roles](/CoDev/roles/) for who does what.

Every turn opens with where the work stands, what it recommends next, and why — without
you asking. When something blocks it, it says so and offers you the choices rather than
stopping at a wall.

## What you actually say

Four moments where your own words are what actually moves things forward. Each is
deliberately short — a longer prompt doesn't make the agent safer, it mostly just repeats
what it already does by default.

### Starting a task

<Exchange>
  <Fragment slot="you">
    "A salt-form compound's computed molecular weight is too high — <code>exclude_salts</code>{' '}
    isn't stripping the counter-ion before summing mass. Fix it and add a regression test."
  </Fragment>
  <Fragment slot="agent">
    Inspects the actual code, opens the task, drafts a focus card, and — once you approve
    it — runs <code>codev task start</code> and <code>codev git branch</code> before
    touching any code.
  </Fragment>
</Exchange>

### Approving a plan or focus card

<Exchange>
  <Fragment slot="you">
    "Looks right, go ahead." — or a correction: "No, don't touch the fragment-splitting
    logic itself, only how the result gets summed."
  </Fragment>
  <Fragment slot="agent">
    Proceeds to Build against exactly what was approved; a correction narrows or redirects
    the plan before any file changes, not after.
  </Fragment>
</Exchange>

### Choosing outer-loop specialists

<Exchange>
  <Fragment slot="you">
    Reply with the numbers you want ("1, 3, 4") or "all" when the outer-loop-review
    skill presents the five-specialist menu.
  </Fragment>
  <Fragment slot="agent">
    Dispatches exactly the specialists you selected, and records which ones actually ran —
    distinct from what was merely offered — in <code>codev task log</code>.
  </Fragment>
</Exchange>

### Triaging findings and deciding to merge

<Exchange>
  <Fragment slot="you">
    "Fix the concurrency one, defer the naming nit with a reason, waive rollout — this is
    internal descriptor logic with no staged exposure."
  </Fragment>
  <Fragment slot="agent">
    Records your triage decisions with <code>codev task triage</code>/<code>codev task
    waive</code>, sends anything that needs a fix back through Build, and stops for your
    actual merge decision once every dimension passes or is waived.
  </Fragment>
</Exchange>

### Being told where things stand, without asking

Your agent opens every phase boundary with this on its own. You do not prompt
for it.

<Exchange>
  <Fragment slot="you">
    "Where are we?"
  </Fragment>
  <Fragment slot="agent">
    "Task <code>auth-rotation</code> is in the outer phase, round 1, with two blocking
    findings waiting on you. Nothing can proceed until they are addressed or deferred
    with a reason. Which should we fix now?" — computed from the task's own state, not
    remembered.
  </Fragment>
</Exchange>

### Asking for a part to be built with you

<Exchange>
  <Fragment slot="you">
    "The token-rotation slice I want to write with you — don't delegate that one."
  </Fragment>
  <Fragment slot="agent">
    Marks that slice as pair work. When the loop reaches it, it does not dispatch the
    builder; it works alongside you. The same rounds are recorded and the same reviewer
    runs, so the work still carries its evidence.
  </Fragment>
</Exchange>

### Interrupting, and coming back

<Exchange>
  <Fragment slot="you">
    "Stop — I want to take this by hand for a bit." <em>(later)</em> "Okay, pick it back
    up."
  </Fragment>
  <Fragment slot="agent">
    Records the interruption with the partial commit attached, then resumes on that
    commit in pair style, absorbing what you wrote rather than reporting it as drift.
    The round cap is raised to match, so pausing costs you nothing.
  </Fragment>
</Exchange>

<Aside type="tip">
  Every one of these has a full copy-paste version on [Starting
  Prompts](/CoDev/starting-prompts/) — this page shows the shape of the conversation, that
  page gives you the exact wording.
</Aside>

## What you'll never have to type

The [CLI Reference](/CoDev/cli-reference/) documents every `codev` command CoDev ships, and
the [Manual CLI Walkthrough](/CoDev/workflow-checklist/) walks the exact sequence a task
goes through end to end. Both are genuinely useful — for understanding what your agent is
actually doing under the hood, for wiring CoDev into CI, or for recovering a task by hand
when no agent session is available — but neither is required reading before you start
using CoDev. Just talk to your agent first; read those pages when you're
curious or when you actually need to run something yourself.

## Where to go next

- The exact copy-paste prompts: [Starting Prompts](/CoDev/starting-prompts/)
- See this play out start to finish: [Tutorial 1: your first fix](/CoDev/tutorials/your-first-fix/)
- The mental model behind all of this: [Onboarding Guide](/CoDev/onboarding-guide/)
- The workflow steps and commands behind each one: [Concepts](/CoDev/concepts/)