Chalk Protocol

Ship agent-written code through gates, not vibes — a locked spec decides success, not the model.

Chalk turns an unattended coding agent into a disciplined contributor: every change lands through a gated loop it cannot talk its way around.

Get started View the repo

The loop — four gates every change must clear

A specced task enters the loop; nothing merges until all four gates say so.

  1. Locked test A real test is authored for the acceptance criteria, then locked read-only. The agent cannot weaken or delete it to pass.
  2. Verify The real toolchain plus a test-integrity check must print GREEN. The gate decides success — never the agent.
  3. Adversarial review A second agent tries to refute the change. Every blocking finding must be fixed before it passes.
  4. Merge gate `chalk done` only succeeds when verify is green, locked tests are untouched, and review passed.

Quickstart — the per-task loop

  1. chalk next find the one task to work on
  2. chalk context <id> read the acceptance criteria and at-risk tests before coding
  3. chalk start <id> begin — it refuses tasks with no acceptance criteria
  4. write code satisfy the criteria, keep the diff small
  5. chalk verify loop until the gate prints GREEN
  6. chalk review <id> survive the adversarial reviewer
  7. chalk done <id> the merge gate closes the task

Docs

Protocol documentation lives in the parent repo — the source of truth this site cannot drift from.