The mechanism, stop by stop.
The Hub's board is the state machine, and your workflow defines its lanes. Everything below is behavior the runtime actually implements; each step links to the document that specifies it.
A configured path, and the catches between states.
Lanes are workflow-defined. These six are the delivery path, and a workflow can define fewer, more, or different ones. Detent's own board configures nine states in total, adding Backlog and Blocked ahead of Todo and Cancelled alongside Done.
The notch marks a gate you defined. Lanes are workflow-defined: this is the delivery path. Detent's own board also configures Backlog, Blocked, and Cancelled.
Claimed by the scheduler when capacity and dependencies allow.
A Codex or Claude Code agent is working on a runner, in an isolated worktree on its own branch.
Held. The workflow asked for a human gate; nothing advances until you release it.
A failed gate or review feedback sent the work back for another pass.
The runner that holds the project lands the change on the base branch with plain git, one at a time.
Landed, or closed as cancelled.
Each lane in detent.yaml has a role: active lanes dispatch an agent, holding lanes wait, and terminal lanes end the work. The board lives on the Hub; GitHub issues can be imported into it, but the Hub's board stays the source of truth. Nothing here is specific to code. Concepts: tracker and board states →
Six steps, in the order they happen.
- 01
Pick a Hub
The Hub holds the board, the issues, the review decisions, and the policy each project runs under. Use Detent Cloud, or run the same Hub yourself.
Detent Cloud has a free plan that needs no card. Self-hosting is free and needs no Detent Cloud account.
Cloud onboarding → - 02
Enroll a runner
A runner is a machine you enroll: a laptop, a build server, a VM, or a Fly Sprite. It keeps your checkout, your agent sign-ins, and your toolchain.
Nothing that touches your code runs on the Hub. Cloud assigns each runner its allowed projects and model selection.
Runners on Fly Sprites → - 03
Commit the contracts
detent.yaml is the machine contract: lanes, gate command, review policy, scheduling, retries, and budgets. WORKFLOW.md is the agent contract: how to work in this repository and what done means.
Trusted workflow definitions from the repository's default branch apply automatically. The README's Start with AI prompt drafts both files for your review.
Concepts → - 04
You put an issue in Todo
A runner that holds the project claims it, creates an isolated worktree, and starts Codex or Claude Code with the issue and WORKFLOW.md. The issue moves to In Progress.
The agent works on its own branch and runs your gate command. When it commits, the runner publishes a Change Request on the Hub with the diff.
Board states → - 05
Gates decide
With review.human: false an accepted change goes straight to Merging. With review.human: true it waits in Human Review until a person approves it or sends it back.
Workflows can add an automated validator and a security audit. Detent's own config sends a failed gate back to Rework with its output.
Native review → - 06
Landing is serialized
In Merging, the runner that holds the project lands the change on the base branch with plain git, one change at a time. Then the issue is Done.
A change that cannot land goes to Blocked with its reason instead of landing broken.
Board states →
One worktree per issue, and where that isolation stops.
Every claimed issue gets its own Git worktree from your source checkout, and its own branch. That is collision isolation, and it is worth being precise about where it stops.
- A worktree per issue, so no two agents share a working tree or fight over the index.
- A branch per issue, so no agent commits onto your main line.
- Your gate command runs on the finished change.
- Promotion is decided by the gates you configured, not by the agent.
- Moving an issue out of an active lane revokes the running worker and stops its process group.
- The runner that holds the project, not the agent, lands every change.
A Git worktree is not an OS sandbox, and WORKFLOW.md is an instruction to the agent rather than a capability boundary. The agent process has whatever host, filesystem, and network access the runner machine and its agent CLI allow.
What the gates and serialized landing guarantee is about promotion: nothing lands on your main branch without clearing them. Treat the agent as a trusted process you have configured, not as a contained one, and choose what each runner machine can reach deliberately.
Designing a project for reliable delivery →A gate is a condition you wrote down.
The workflow decides what a change needs before it advances. These are the shipped options, and they compose.
gate.run is your check command, run on the finished change. Detent's own is make check-landing; yours can render a video or validate a document.
With review.human: true, a Change Request waits in Human Review until a person approves it or sends it back. This is the detent in its most literal form.
A model scores the change against the issue's acceptance criteria and can send unverified work back for another pass.
An independent audit pass on the change before it can land.
With the default review.human: false, an accepted change goes straight to Merging. Detent's own config sends a failed gate back to Rework with its output. Native review →
One change lands at a time.
In Merging, the runner that holds the project lands the accepted change on the base branch with plain git, one change at a time. Parallel agents never race each other onto your main line.
A change that cannot land goes to Blocked with its reason instead of landing broken. Native projects make no GitHub API calls by default; git clone and push work against any host. Board states →
Deciding what is even worth dispatching.
Admission criteria are project-owned text in your workflow: the sections an issue must contain before an agent picks it up. Admission and Todo dispatch use one evaluator, so a vague issue waits instead of producing vague work.
## Issue Contract
- Acceptance criteria
- Must not break
- How we know it workedThese three sections are the default when a project configures none. Required sections must contain text; headings inside code fences do not count. Admission criteria →
Start free on Detent Cloud. Paid plans add concurrent work and hosted artifacts.
The interaction-model argument, the default choices, and the comparison matrix.
Install a runner or your own Hub: platform-tabbed commands, requirements, and the first run.
The operator surface: lanes, agent activity, budgets and capacity, and MCP access.
Reviewed recordings of Detent moving real work through checked-in workflows.
The curated operator reference, mirrored from a pinned Detent release.
FSL-1.1-ALv2, the repository, releases, contributing, and how Detent builds itself.