The mechanism, stop by stop.
Configured GitHub status is the state machine. Everything below is behavior the runtime actually implements — the state table and connector model live in the repository's Concepts document, and each step here links to it.
A configured path, and the catches between states.
Lanes are workflow-defined. These six are the delivery path — 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 agent is working in an isolated worktree on its own branch.
Held. The workflow asked for a human gate; nothing advances until you release it.
Unresolved review feedback sent the work back for another pass.
In the serialized merge train: rebase, CI-watch, merge — one at a time.
Merged green, or closed as cancelled.
The source of truth can be a GitHub ProjectV2 board, or Detent can run boardless from an issue Status field or from repository status labels while supplying its own Kanban view. Concepts: connectors and board states →
Six steps, in the order they happen.
- 01
You write the contracts
Each project has a checked-in detent.yaml machine contract — tracker bindings, states, lifecycle policy, scheduling, retries, leases, gates — plus a checked-in, portable WORKFLOW.md agent instruction contract.
The prompt declares the project's required CI stage categories and the commands and check names that satisfy each one. Optional gitignored detent.local.yaml and WORKFLOW.local.md apply machine-specific overrides without touching the shared contracts.
Configuration reference → - 02
You mark an issue Todo
Detent claims it, creates an isolated Git worktree from your source checkout, and dispatches a Codex agent with the contract — moving the issue to In Progress.
The source of truth can be a GitHub ProjectV2 board, or Detent can run boardless from an issue Status field or repository status labels while supplying its own Kanban view.
Connectors and board states → - 03
The agent works
In its own branch. It runs your validation gate and opens or updates a pull request.
Review-gate workflows move the issue to Human Review. Autopilot workflows leave it active with status: complete in the Workpad.
Execution seams → - 04
Gates decide
The workflow decides whether promotion to Merging waits in Human Review, waits in the active lane, requires a current-head automated PR review, or only needs linked PR + green CI + quiet time.
Unresolved feedback sends the issue to Rework for another pass. Code defaults to make check plus CI plus automated review; a human approval-label gate is available when the workflow explicitly asks for one.
Review gates → - 05
The merge train is serialized
One rebase, CI-watch, and merge at a time, so concurrent candidates never invalidate each other's CI. Then the issue is Done.
Train width is configuration, not a fixed rule — Detent's own board runs it at one candidate at a time.
Merge train → - 06
One host, many repos
A global.yaml runs multiple projects with weights, priority, pause, and fair scheduling.
The web dashboard and terminal UI show live counts, running agents, token / budget / rate-limit state, and board flow.
Multi-project operation →
One worktree per issue — and what that does not mean.
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 validation gate runs before anything is pushed.
- Promotion is decided by the gates you configured, not by the agent.
- The Rework lane catches unresolved review feedback.
- Leases and retries release a stalled claim instead of holding it forever.
- The merge train, not the agent, performs every merge.
A Git worktree is not an OS sandbox, and WORKFLOW.md is an instruction to the agent rather than a capability boundary. Detent's own production config runs thread_sandbox: danger-full-access, so the agent process has whatever host, filesystem, network, and GitHub access its runtime policy allows.
What the gates and the train 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 set approval_policy and the sandbox mode deliberately.
Sandbox and approval configuration →A gate is a condition you wrote, not a vibe.
The workflow decides what promotion to Merging requires. These are the shipped options.
The issue moves to the Human Review lane and stops. Nothing advances until a person releases it. This is the detent in its most literal form.
The issue stays active with status: complete in the Workpad. Autopilot workflows use this when no human stop is wanted.
Promotion requires a current-head automated review. A review of a stale head does not count.
The lightest gate: a linked pull request, passing CI, and a quiet window with no new activity.
Validation gates are pluggable. Code defaults to make check plus CI plus automated review; a human approval-label gate is available when the workflow explicitly asks for one. Unresolved review feedback routes the issue back into the Rework lane.
What lands is always green.
Serialized: one rebase, one CI watch, one merge at a time. Ten agents working in parallel never invalidate each other's CI, because only one candidate is ever being tested against the head that will receive it.
Train width is configuration, not doctrine — Detent runs its own board at one candidate at a time. The guarantee that follows is narrow and worth stating plainly: a merge only happens after CI passed on the exact commit that is about to land. Merge train configuration →
Deciding what is even worth dispatching.
A scheduled read-only pass scores Backlog issues against the admission criteria in your WORKFLOW.md and proposes the ones worth working.
backlog_admission:
enabled: true
schedule: '*/15 * * * *'
auto_admit: true
auto_admit_min_confidence: 0.85
sources:
states:
- BacklogThat confidence bar started at 0.9 and was lowered to 0.85 after every sub-0.9 proposal to date had been accepted by hand anyway — the original bar was stricter than the operator's own judgment and was producing silent waits. The comment explaining that decision is in the config, next to the value. Admission criteria →
The interaction-model argument, the default choices, and the comparison matrix.
The operator surface: lanes, agent activity, budget and rate-limit state, and the TUI.
Platform-tabbed install commands, requirements, and the first run.
Reviewed recordings of Detent moving real work through checked-in workflows.
The curated operator reference, mirrored from a pinned Detent release.
MIT, the repository, releases, contributing, and the self-hosting proof.