Start here

Your first mission

The happy path from a registered project to a delivered draft pull request, plus what to do when the mission holds instead of shipping.

This walks the shortest route to a real, reviewed, delivered pull request. Every command runs from framework/.

1. Register the project

npm run orgabot -- project add <repo-path> --verify "npm test"
npm run orgabot -- project list

The /orgabot-register Claude Code skill does the same thing and auto-detects independently buildable sub-apps with the right --workdir and --verify.

2. Launch the mission

npm run orgabot -- mission <project> "<instruction>"

Useful flags on that first run:

Flag	Effect
`--background`	Run detached with logs and notifications; advance through the selected workflow milestone when its gates pass
`--edit-only` / `--shell`	Clamp the worker to editing or explicitly allow shell; otherwise access is derived from the role toolchest (`--operate` is a deprecated `--shell` alias)
`--mock`	Use the deterministic mock worker (no `claude` login needed)
`--repository-milestone <kind>`	Require `patch`, `branch`, `pull_request`, `merge`, or `post_merge` evidence (`pull_request` is the compatibility default)
`--no-pr`	Compatibility alias for the `branch` milestone
`--durable`	Require Restate durability (default already prefers Restate when the runtime is up; without it, unavailable Restate is a silent in-process fallback)
`--base <branch>`	Branch off a specific base: how you continue salvaged work

Orgabot owns the selected workflow gates and their evidence regardless of worker access. A role's toolchest normally determines shell access; --edit-only clamps it, while --shell requests it. Worker prose is never verification evidence.

3. Watch it

npm run orgabot -- status
npm run orgabot -- logs <mission-id>
npm run orgabot -- wait <mission-id>      # blocks; --json for machine output

Or watch it live in the mission terminal in the dashboard.

4. Ship, review, merge

npm run orgabot -- ship [project]           # opens the draft PR and runs review → fix → re-review → merge
npm run orgabot -- review <project> <pr#>   # a single independent review; --post to comment
npm run orgabot -- review-loop <project> <pr#>
npm run orgabot -- merge <project> <pr#>    # --method squash|merge|rebase

PRs open as drafts by intent; auto-merge paths promote a draft to ready before merging. The merge still respects the project's autonomy and approval policy. See Shipping and review.

5. Approvals

If the mission needs authority it does not hold, it raises an approval instead of proceeding:

npm run orgabot -- approvals
npm run orgabot -- approve <id>
npm run orgabot -- deny <id>

When it holds instead of shipping

A hold is Orgabot refusing to guess. It is a normal outcome, not a crash. The common ones:

Verification failed. The project's own test command exited non-zero. Read the log, then continue with orgabot follow-up.
No role could be auto-selected. An org maps the project but routing resolved nothing, so the mission waits for you to name the owning role. Answering the prompt with a role name relaunches that same mission under it; a name Orgabot does not recognize (or a role with no accountable actor) is refused and the prompt stays put. It must never silently fall back to a generic worker.
Fail-closed delivery. The role has no GitHub grant, so its committed work waits rather than delivering through your ambient gh.
`memorialization_unwritable`. There is no writable context source to record the mission's intent to. Inspect with orgabot context holds and resume with orgabot context resume.
Quota exhausted. The executor chain is spent; the mission waits for the window to reset, then escalates.
Blocked on a question. Surface it with orgabot inputs and answer with orgabot answer.

Troubleshooting covers each of these with the exact commands.

Continuing a mission

orgabot follow-up continues a finished or held mission on its own branch, resuming the recorded worker session; the round re-verifies and re-reviews. A steering message sent to a mission that is still running is never refused: it is either injected into the live session or durably queued for the next round.

Solo path

If you want none of the org machinery, orgabot mission <project> "<instruction>" --no-org runs on your own credentials and delivers through your ambient gh. Everything above still applies, minus roles and scoped tokens.

A hold is Orgabot refusing to guess, and several are expected in first beta rather than faults. Known limitations lists which ones, and why each is a deliberate refusal.

← Install and setup Core concepts →