gatecrew

Your coding agent gets a crew and gates. Nothing ships unchecked.

gatecrew is a workflow for coding agents. It gives a project a fixed set of commands that route work from a first idea through a decision, a spec, a build, a review, and a ship — fresh-context roles that do the heavy reading and writing so the agent driving the work doesn't have to carry every file it reads — standards those roles are held to — and deterministic gates that check the rules mechanically instead of hoping someone remembers them. It installs into a project as a Node command-line tool, and works with Claude Code today; adapters for Codex CLI and Gemini CLI are planned, not built yet.

Install

npx gatecrew init
npx gatecrew install
npx gatecrew doctor

• init looks at the project — its git history, its manifest files, its branch names — and writes .gatecrew/workflow.yaml, then prints a summary of what it detected, what it had to ask you, and how many of the 16 gates are turned on. Read that summary before moving on — it's the one chance to catch a wrong guess before anything is installed. Pass --dry-run to see the same summary without writing anything.
• install copies gatecrew to a stable location on your machine, then wires it into the harness you're using: it registers the gates, renders the roles, renders one file per pipeline command into ~/.claude/commands/ so each shows up as its own /<name> command, and links the skills.
• doctor checks that the install is actually working — every gate is present and executable, the harness's own configuration is in sync with gatecrew's, the project's config file is valid — and reports "in sync" or exactly what's wrong.

See the full worked example — one feature end to end, with the gate that fires at each stage — in docs/WALKTHROUGH.md.

How work moves through the pipeline

/decide  → research + 2-3 options + blast radius + NFR impact → developer decides
           (the ADR is committed to the project's ADR directory (`docs.adr_dir`); the heavy
           lifting runs on build-tier roles: context-scout, solution-researcher,
           option-designer, design-author)
/spec    → decision → precise spec a fresh session can build from (the ticket body or a
           committed doc, per `spec.home`)
           (industry: functional spec; drafted by spec-author, reviewed by the orchestrator;
           a component change or a non-trivial build gets its HLD/LLD/NFR design doc written
           NOW, at spec time, per the design standard)
/build   → TDD Red → Green → Refactor — ALWAYS dispatched to the engineer role
           (the orchestrator never writes production/test code inline; it briefs the role
           with the spec + ADR + design doc + module docs, then reviews)
           (when an LLD exists it IS the code-level design — the engineer types it out, one
           test-plan-skeleton case at a time; no LLD → the build plan is it)
/update-docs → docs move with code, same commit
/ship-check  → /verify-e2e (drive the app as a real user)
             → /precommit  (the gate command, then fresh-context reviewers:
                correctness + readability always; security when a trust boundary is
                touched; api-compat when the public contract is touched)
push + PR    → manual, developer's call
deferred-work interview → the tracker or the project's known-issues doc (`docs.known_issues`)
                          (never a scratch file)

How much of this fires scales with what the change actually touches — not every task earns the full pipeline:

| Tier | Trigger | Pipeline that fires | |------|---------|---------------------| | Trivial | docs, comments, rename, config value, roughly 20 changed lines or fewer, zero design decisions | inline edit → the gate command → one combined reviewer | | Small | a bounded bugfix or tweak, 1–2 files, approach obvious, no new behavior contract | the engineer role or an inline edit → one combined correctness+readability reviewer | | Standard | new behavior or a feature, none of the project's critical surfaces touched | spec → build → ship-check (one reviewer per axis the diff actually triggers; decide only if the approach is genuinely undecided) | | Critical | one of the project's critical surfaces — money, tenancy, authz, destructive migrations by default | the full pipeline: decide → spec (plus a design doc) → build → ship-check with precommit's escalated votes |

A lower tier never skips a gate — it only skips ceremony. Every tier still exits through the gate command and the review step, and a user-facing change still gets driven end to end before it counts as done.

Gates

Sixteen gates ship today. Registering a gate is a one-time, machine-wide step; whether it's switched on for a given project depends on that project's configuration.

| Gate | What it stops or reminds | When it's on | |---|---|---| | the destructive-git gate | Stops a git command that would silently discard uncommitted work — a hard reset, a force push, a checkout that overwrites, clean -f, deleting a branch | always | | the known-issue confirmation gate | Asks before editing a file that's already listed as a known issue, so a known problem isn't silently patched over without a decision | the project has a known-issues doc configured | | the ADR rewrite-in-place gate | Denies editing an accepted decision record as if it were still open — an "Amendment" heading, a bracketed superseded marker — instead of writing a new one | the project has an ADR directory configured | | the banned-vocabulary gate | Denies writing one of the project's forbidden words into a doc — stale terminology, a retired name | the project has listed banned terms | | the read-source-once gate | Stops a role from re-reading a source document it already condensed into a decisions file, so a large uploaded document isn't re-read wholesale on every turn | always | | the handoff-note gate | Puts the previous session's handoff note into context at the start of a session, or on a bare "continue", so a fresh session doesn't have to re-derive where the work stands | always | | the lesson-capture reminder | Notices a correction ("that's wrong", "revert that", "try again") and reminds the agent to run the lesson command | always | | the brief-sentinel gate | Denies dispatching a role whose brief is missing a required line — a "VERIFY WITH" line on every build or review dispatch, and a "NAMES LOCKED" line whenever the brief renames something or touches schema | the project has dispatch rules configured | | the model-tier gate | Denies dispatching a role that isn't tagged with a cost/capability tier, so that choice stays deliberate rather than left to whatever the harness defaults to | the project lists untiered agents | | the contract-tool-used marker | Records that a role actually called the project's API-contract tool during its turn, so the two gates below have something to check | the project has a contract tool configured | | the contract-shape nudge | Reminds a role that just read a request or response shape out of source code to check the real contract tool instead of trusting what it inferred | the project has a contract tool configured | | the contract-tools-on-dispatch gate | Denies dispatching a role to describe an API request or response shape unless that role can reach the contract tool | the project has a contract tool configured | | the cross-repo contract-read gate | Denies reading a request/response shape file that lives in a different repository than the one being worked on | the project has marked a separate contract repository | | the integration-into-feature gate | Denies merging the integration branch back into a feature branch — the wrong direction | the project uses a feature → integration → trunk branch model | | the integration-before-trunk gate | Denies merging a feature branch straight into the trunk branch, skipping the integration branch | the project uses a feature → integration → trunk branch model |

Configuring

Everything lives in one file, .gatecrew/workflow.yaml, committed to the project so every teammate's install reads the same gates and the same operating model.

| Key | Meaning | |---|---| | config_version | The config file's own format version | | harness | Which coding-agent tool gatecrew is wired into | | project | The project's name, languages, and frameworks — decides which language layers load | | paths | Where gatecrew's own files live inside the repository | | tracker | Which issue tracker this project uses, and how to recognise its ticket keys | | spec | Where the functional spec lives — a tracker ticket, or a committed document | | docs | Where the ADR directory, design docs, known-issues doc, generated docs, and the end-to-end runbook live | | commands | The actual shell commands for testing, formatting, static analysis, the full gate, installing dependencies, and regenerating docs | | branches | The branch model, the trunk and integration branch names, and ticket-branch prefixes | | build | The build stage's TDD requirement — required (default) or off as a committed project decision | | agents | Which rendered role plays each job — builder, verifier, reviewers, mechanical | | models | The cost/capability tier for each kind of work, without naming a specific vendor's model | | tools | The names of the integration tools this project has wired up — left blank where nothing is configured, so a role says a fact was inferred rather than inventing a tool call | | contract | How to recognise the project's own API-contract calls and files | | risk | Which surfaces — money, authz, tenancy, migrations, secrets by default — get the escalated review tier | | vocabulary | Words a docs or PR review should flag as stale or forbidden | | handoff | Where the optional handoff note lives, and which bare prompts mean "resume" | | lessons | The pattern that recognises a developer correction, so the lesson-capture reminder fires | | markers | The inline instruction-comment prefix (default AI:) and what it means | | dispatch | The sentinel rules that deny an incomplete dispatch brief, and which agents need a model tier | | sources | File extensions treated as uploaded source documents | | environments | The project's named deployment environments | | known_flakes | Tests known to fail intermittently, so a red run isn't mistaken for a new regression | | hooks | Per-gate overrides of the default "when it's on" rule |

Four places can hold a value, read in this order — the last one that sets a key wins: the built-in defaults, then ~/.gatecrew/config.yaml (personal, applies to every project), then the project's committed .gatecrew/workflow.yaml, then .gatecrew/local.yaml (personal to you, never committed). Running init again never overwrites a value you've hand-edited — only a value still marked as auto-detected gets refreshed, and only when you ask for that explicitly.

Harness support

gatecrew's core prose never names a tool call directly — it names one of nine things a working method needs to be able to do, and each harness adapter maps those to its own real calls.

| Capability | Claude Code | Codex CLI | Gemini CLI | |---|---|---|---| | ask the developer | AskUserQuestion | planned | planned | | dispatch a role | the Agent tool with subagent_type | planned | planned | | message a running role | SendMessage | planned | planned | | watch a signal | Monitor | planned | planned | | load a tool | ToolSearch | planned | planned | | preload a standard | skills: frontmatter on the role definition | planned | planned | | gate | a PreToolUse / PostToolUse / UserPromptSubmit / SessionStart hook in settings.json | planned | planned | | plan first | plan mode | planned | planned | | the orchestrator | the main thread | planned | planned |

Language layers

Each layer is a thin file sitting on top of one of the core review standards, adding only what's specific to that language.

| Language | Shipped | Missing | |---|---|---| | PHP | readability, correctness, security, build | — | | TypeScript | readability, correctness, build | security | | Python | readability, correctness, security | build |

Every other language runs on the core standards alone, with no language-specific layer yet.

Philosophy

• Decide before you build. No production code before the decision artifact exists — the ADR and the spec come first.
• A gate beats a reminder. A rule worth enforcing gets checked mechanically, not left as a line in a document someone has to remember to read.
• Fresh eyes review. The role that reviews a change is not the role that wrote it, and it starts from the diff and the standard, not the reasoning that produced the change.
• Ask the tools, don't infer. A fact you can look up — a database column, an API contract, a package's real behavior — is never a fact you guess from reading nearby code.
• A lesson becomes a gate. A correction gets triaged down to the strongest mechanical check that can catch it again, not just written down and hoped for.

Licence

MIT.