Spec-Driven Flow

Coderrr writes a spec, shows it to you, and stops. Nothing on disk changes until you approve. This page is what that actually means.

The flow

your request
     │
  PLANNING ──► reads your code, pulls relevant skills
     │         writes requirements.md · design.md · tasks.md
     │
  ┌──┴───────────────────────────────────┐
  │  the plan is shown to you. it stops. │
  └──┬───────────────────────────────────┘
     │ you approve
  EXECUTION ──► per task: read → edit → run in sandbox → verify → mark done

Write tools do not exist during planning

This is the part worth understanding, because it is not a prompt instruction. In planning mode the write tools are absent from the model's tool list entirely. The agent is not asked to refrain from editing — it has no tool that edits.

Mode	Tool classes available
planning	read, system
execution	read, write, system

Approval is the only thing that flips the mode, and there is exactly one place in the codebase where that transition happens. A model that decides mid-plan to start editing cannot: the call fails because the tool is not there.

Why this and not a system prompt

Prompt discipline degrades with model quality — a weaker model instructed "do not edit yet" sometimes edits anyway. Removing the capability holds regardless of which model you point at it, which matters when the default provider is a free local model.

What gets written

Every request produces a numbered spec directory in your project:

.coderrr/
├── specs/                     <- committed; project knowledge
│   └── 003-add-rate-limiting/
│       ├── requirements.md    goal, user stories, acceptance criteria, out of scope
│       ├── design.md          the approach, grounded in your actual code
│       └── tasks.md           an ordered checklist with file targets and status
├── cache/                     <- gitignored
└── session/                   <- gitignored

Coderrr generates a .coderrr/.gitignore that excludes cache/ and session/ while keeping specs/ — they are project documentation and read well in a pull request.

You can edit the spec before approving

The plan is files on disk, not a message in a chat. When Coderrr stops and shows you the plan, the artifacts are already written — open them, change them, and approve. Execution reads what is on disk, so your edits are what gets built.

Useful when:

A task is scoped wrong — rewrite the task, do not re-prompt
The design picked the wrong file — fix the file list
You want three of five tasks — delete the other two
An acceptance criterion is missing — add it, and it gets verified

Declining is also cheap. The spec stays on disk; edit it and re-run to continue from there.

Specs are the agent's memory

A later session reads tasks.md to learn where things stand instead of replaying a chat log. Task status lives in the file — pending, in_progress, done, blocked — so progress survives a closed terminal, a rebooted machine, and a different model.

coderrr spec list
  Spec                    Title                        Tasks
  001-add-auth            Add JWT authentication       4/4
  002-fix-timeout         Fix cold-start timeout       2/2
  003-add-rate-limiting   Add rate limiting            1/3

That is also why a blocked task records why it is blocked. The next run reads the reason rather than rediscovering the wall.

Execution, task by task

For each task, in order:

Step	What happens
mark in_progress	Status written to tasks.md immediately
read	The agent reads the files it is about to touch
edit	write_file or edit_file. A diff is printed before the change lands.
run	run_in_sandbox executes tests or a build and the agent reads the real exit code
verify	A model call checks the change against the task. Configurable via [verify].
mark done	Or blocked, with a reason

A task that fails verification is retried up to [agent].max_iter times (5 by default). The verifier runs at temperature 0.3 rather than zero on purpose — at zero, a weak verifier's false rejection is deterministic and the retry loop can never escape it.

When the agent is unsure

Rather than guessing at an ambiguous request, the agent calls ask_review during planning and asks you. A spec built on a wrong assumption wastes the whole approval cycle, so the question comes first.

If planning ends with no spec at all — smaller models sometimes narrate a plan in prose and stop — Coderrr nudges once and asks for the artifacts. If there is still no spec, or the spec has no tasks, the run stops and nothing is modified. That check runs even under --yes.

Commit your specs

.coderrr/specs/ is meant to be checked in. It is a record of what was asked, what was designed, and what shipped — reviewable alongside the diff it produced.

Coderrr never commits for you. v1's auto-commit ran git add ., which swept unrelated work into its commits; v2 leaves version control entirely to you. See Migrating from v1.