gh-codecrew

CodeCrew is a protocol for agent-driven software delivery and a gh extension
that enforces it. Project state lives in GitHub and nowhere else: a milestone
is an issue, a task is an issue with a plan in its body, decisions and
deviations are comments in a fixed shape, and the work of a task is a branch
and a PR. The gates — CI green, an approving review from whoever holds the
reviewer seat, a QA verdict on every requirement not struck by a recorded
decision, a human sign-off wherever one was raised — are checked by the CLI,
which exits non-zero with refused[CODE]: detail when one is unmet. At milestone close the
doc-synthesizer seat compiles the recorded comments into
docs/milestones/<n>-<slug>.md. There is no server, no database and no state
files: the dependencies are gh 2.50.0 or later, a GitHub repo, and CI on its
pull requests.

codecrew.works is the marketing and introduction
site, and carries the blog. This page is the
technical entry point: it is written for whoever wants more detail than the
site gives — someone running a coding harness, or the agent reading on their
behalf — and every reference it links is at source in this repository rather
than on the site. The two references are CLI.md — every verb, its
options, what it reads and writes, and what it refuses — and
SPEC.md, the protocol those verbs enforce.

If you have tried CodeCrew, or tried it and got stuck, tell us how it went
under I tried it
in this repository's Discussions.

The routing table

Four seats — implementer, reviewer, qa, doc-synthesizer — and a coordinator
that dispatches them. Each is a contract file under
.codecrew/roles/, not an account, and each is held by
one of four kinds of principal, named by the identity's type prefix: you
(~), a named human (user:<login>), a GitHub team (team:<org>/<slug>),
or a GitHub App identity (app:<slug>). Who holds which seat is the
roles: table in the hub's .codecrew/config.yml.

Here is a worked example: the roles: section of this repository's own
.codecrew/config.yml, as it stands today. Each row is a seat — the identity
that holds it, and the harness and model it is dispatched under, which can
differ from row to row. There are five rows because the coordinator, the seat
that dispatches the other four, is routed too; ~ means a human holds it,
here the operator who coordinates this hub by hand. Your table will look
different, and every seat pointing at ~ is a complete one.

roles:
  implementer:
    harness: claude-code
    model: claude-opus-5-5
    identity: app:radiusred-cody
  reviewer:
    harness: codex
    model: gpt-5.6-terra
    identity: app:radiusred-checky
  qa:
    harness: codex
    model: gpt-5.6-sol
    identity: app:radiusred-testy
  doc-synthesizer:
    harness: claude-code
    identity: app:radiusred-wordy
  coordinator:
    identity: ~   # the operator: this hub is coordinated by hand (SPEC §7)

Solo is a routing configuration, not a reduced protocol: gh codecrew init
writes the table with every seat routed to ~, and the same gates apply.
gh codecrew identity new <role> mints a dedicated App for a seat through
GitHub's manifest flow and rewrites its row; nothing else changes
(docs/identities.md). The field reference is
SPEC.md §5.

Start now

gh extension install radiusred/gh-codecrew
cd my-project            # any repo on GitHub, brand new or years old
gh codecrew init         # writes and commits .codecrew/, AGENTS.md, CLAUDE.md, ROADMAP.md
                         # (an AGENTS.md or CLAUDE.md you already have is kept,
                         #  with the lines to add to it printed)

Already running CodeCrew? The current release, v2.1.1, implements
protocol 2.1 — the .codecrew/ layout the block above and the rest of this
page describe, unchanged since 2.0, so a 2.0 repo has no migration step:
upgrade the extension and follow the 2.1.0 section of
CHANGELOG.md. A repo still on the 1.x layout
(.codecrew.yml and roles/ at the root) is refused, not read:
gh codecrew migrate moves it forward in one local commit, hubs before
their spokes. What 2.0 broke and the migration
steps are in CHANGELOG.md's 2.0.0 section.

init scaffolds the project with every seat routed to ~. After it, the verbs
are run by the coding agent rather than by the person driving it:
.codecrew/AGENTS.md tells an agent dispatched into the
repo where the hub and the contracts are — the root
AGENTS.md points at it, and CLAUDE.md imports the root — and gh codecrew roles show <role> prints the contract
it works to, local extensions included.

gh codecrew milestone new --title "Walking skeleton" \
  --goal "A deployed hello-world proving the delivery pipeline end to end." \
  --requirement "visiting the app's URL returns a greeting"
gh codecrew task new --milestone 1 --title "Serve the greeting" --requirements M1-R1
gh codecrew task start 3     # refuses NO_PLAN until the task body carries a plan

gh codecrew help lists the rest; gh codecrew status reports the open
milestone, the inferred task states and any raised gate. A human is needed at
three points, whatever harness is driving: a gate raised for a decision
(cc:needs-decision), a PR that needs the reviewer seat's approval, and the QA
verdicts a milestone cannot close without.

Two requirements the CLI checks. gh must be 2.50.0 or later — task finish
reads gh pr checks --json, and an older gh refuses GH_TOO_OLD before any
verb runs. And the repo needs pull-request CI: task finish refuses NO_CHECKS
on a PR that reports no checks at all, with no override. init does not write a
workflow; docs/first-milestone.md
carries a ten-line one.

Read next

Reference documentation, at source in this repository — an agent dispatched
into a CodeCrew repo starts at .codecrew/AGENTS.md and its role contract
under .codecrew/roles/:

• docs/introduction.md — what CodeCrew is, precisely:
  the three parts, what is shipped, and how a refusal reads (the code table
  itself is SPEC §10)
• docs/first-milestone.md — one milestone end to
  end, solo: open it, plan a task, do the work, verdict it, close it
• docs/identities.md — routing seats to humans, teams
  and GitHub App identities, and dispatching a role session
• docs/platform-interop.md — hosting the crew on
  an orchestration platform: the coordinator seat, wake paths, onboarding
• docs/extensions.md — extending a role contract in
  .codecrew/roles/<role>.local.md without forking it
• docs/working-offline.md — which verbs run with no
  network, how the rest refuse, and the recipe for work begun offline
• docs/founding-decisions.md — the trade-offs
  the design was chosen against
• docs/milestones/ — one record per delivered milestone,
  synthesized from the decisions recorded while it was built
• CLI.md — the CLI reference: every verb's synopsis, options,
  reads and writes, refusal codes and exit status
• SPEC.md — the protocol: topology, state model, configuration,
  verbs, roles, gates
• CONTRIBUTING.md and SECURITY.md
• ROADMAP.md — the finished milestones; CHANGELOG.md
  — what each release shipped

Licensed under Apache 2.0.