Version: Next

Adopting an existing repo

orion init puts Orion's guardrails and ticket routing on a repository you already have, and they then apply to your ordinary Claude Code sessions there as well as to supervised runs.

Working on a sandboxed copy of an existing repository (the old orion new --from <repo>) is unavailable for now: orion new no longer provisions a workspace, orion plan has no equivalent flag yet, and the flag is refused.

`orion init`

cd /path/to/your-repo
orion init

This writes orion.json, creates the artifact directories, and merges Orion's hooks into .claude/settings.json. Running it twice changes nothing the second time.

It keeps your own hooks, permissions and MCP servers in .claude/settings.json: it backs the file up, adds only its own entries, recognises them on a re-run, and refuses to touch a file it cannot parse.

Restart any open Claude Code session afterwards. Hooks are read at session start, so an already-open session stays unguarded.

The hooks it adds

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "orion hook session-start" }] }],
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "orion hook gate" }] },
      { "matcher": "Edit|Write|MultiEdit|NotebookEdit", "hooks": [{ "type": "command", "command": "orion hook shield" }] },
      { "matcher": "*", "hooks": [{ "type": "command", "command": "orion hook breaker" }] }
    ],
    "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "orion hook breaker" }] }]
  }
}

The breaker needs both entries: PostToolUse counts what happened and PreToolUse refuses the next call.

Inside your own sessions only gate and shield are armed. The breaker arms only in supervised runs, where Orion sets ORION_WORKSPACE; at a keyboard it says so and allows the call (Circuit breakers).

The plan gate

gates.require_plan_before_edit refuses implementation edits until a plan exists. Projects orion plan creates have it on; orion init leaves it off, since it would block the first edit in a repository where small changes go in without a plan. Turn it on with:

orion init --plan-gate

or set it in orion.json.

The branch model is enforced

Orion merges work into the integration branch (vcs.work_branch, develop by default). A person promotes it to the release branch (vcs.default_branch, main). Config load, orion init and orion doctor each refuse the two being the same branch, naming both values and the remedy. orion init creates the integration branch when it does not exist, so a repository with only main is offered a develop.

A repository with one branch and no release process opts out explicitly:

"vcs": { "allow_release_branch_merges": true }

Every run that uses it prints a warning that no human promotion step is left.

Routing tickets to agents

orion routes

prints the routing table: each routable agent, the exact keywords it accepts, and the agents left unroutable because something else invokes them. Orion picks a ticket's agent by a fixed lookup on its issue type, components and labels, never from the summary or a model call. Matching is exact and case-insensitive, so a component named docsite-infra does not count as documentation.

Set the marker when you create the ticket. A ticket with no marker goes to the backend implementer. orion queue prints the routing split of the queued work, so you can spot an all-default queue before the run.

Putting tickets in the queue

A ticket is queued when it carries the ORION label (or the label set in tracker.queue_label). Add it by hand or with the CLI:

orion queue add KEY-1 KEY-2      # queue tickets
orion queue                      # what the watch would pick up, in order
orion watch KEY                  # work them

Where the project uses releases, a ticket must also sit on an open version to be claimed (A ticket's statuses and labels).

What differs from a planned project

	Planned with `orion plan`	Adopted with `orion init`
Plan gate	on	off until `--plan-gate`
`collect.batch_integration`	on: finished tickets land together in one CI run	off: one pull request per ticket
Slack	turned on when the project has a channel	add the `slack` block yourself (Credentials)
spec-kit planning steps	delegated by default	not configured

Turn batch integration on with orion config collect batch_integration true. orion repos shows which repository each project key is bound to.

orion init​

The hooks it adds​

The plan gate​

The branch model is enforced​

Routing tickets to agents​

Putting tickets in the queue​

What differs from a planned project​

Next​