Core concepts

If a word in the dashboard or the CLI does not mean what you assumed, it is probably here.

Mission

The canonical unit of work: one instruction turned into structured state that flows through plan → implement → verify → review → deliver. A mission owns all of its own state (tasks, approvals, audit events), and the runtime only drives it. That separation is what makes the durable runtime swappable.

Transcript

The immutable record of the original typed or spoken instruction. It is normalized once and never mutated; everything downstream derives from it.

Intent and project resolution

Parsing turns a normalized transcript into a structured intent. Resolution maps that intent to a registered project by confidence, and low confidence becomes a needs_decision rather than a guess. Orgabot asks instead of picking the wrong repo.

Candidates are offered one per repository, never one per registration. A monorepo registered several times (the repo root plus its --workdir sub-projects) collapses to its top-level project before you are asked, so a sub-project is never offered next to its own parent: confirming both would launch two missions against the same repository. The registered repository-root project always owns the repository's issue-source, connector, and other repo-level relationships. Child projects are monorepo-discovered execution targets only; they never become implicit repository owners. The mission itself decides during execution which sub-projects the change applies to, and the widening is recorded in the resolution's rationale. This grouping applies even when the ranking also names an unrelated repo, and even when every candidate is low confidence, because collapsing a repository is deduplication rather than a confidence judgement. Genuinely unrelated repositories still produce a real multi-select, and confirming several of them launches one mission each.

Naming the family is different from naming several registrations. When your instruction mentions the product once ("new social proof for comoji"), only the umbrella registration matches, so there is nothing to collapse. If that umbrella has no `--verify` command and exactly one of its sub-projects does, Orgabot resolves to that sub-project instead: the container is what you named, but the entry whose independent gate has something to run is the one a mission can execute in. The narrowing is recorded in the rationale, naming both ends.

It stays deliberately narrow, because it is a fact rather than a guess. A project that already has a --verify command is never retargeted, so naming a gated project gets you the one you named. A sub-project must sit inside the umbrella's directory and share its registered repo root, so a project registered under an unrelated checkout is never widened into. And if two sub-projects both carry a verify command, which app the work belongs to is a real question: resolution falls through to the ranker and, failing that, to you.

Without this, an umbrella parent with no --verify command of its own left the mission with a weaker gate than a sub-project would have provided, and a workflow that requires a verification gate refused to launch at all ("Setup required by policy - project choice is not confirmed"), asking you to configure a project that exists only to contain the two that are already configured.

Project

A registered repo, optionally with a --workdir sub-path and an optional --verify command, stored in ~/.orgabot/projects.json. The registration at the repository root owns repo-level issue and connector relationships; a child --workdir registration is an execution target inside that root, not an implicit owner. When verify is unset (and no suite is auto-detected), machine verification is skipped and does not block merge; when set, pass/fail is exit-code evidence. The registry defends its root boundary: symlink and .. escapes out of a project root are refused.

Worktree

A real, isolated git worktree where a worker makes its edits. Work is sandboxed from your checkout and from other missions, created and cleaned per task. This is why two missions on the same repo do not fight, and why a killed worker leaves recoverable work rather than a wrecked checkout.

Task DAG

The dependency graph a mission is decomposed into by the planner. Each ready task is implemented, verified, and reviewed in turn.

Gate

A verification checkpoint that passes only with command exit-code evidence. Two rules ride along with it:

• a producer can never waive its own gate;
• a diff touching at least one file (including a binary add, delete, or rename) is never treated as "no changes produced". The no-changes heuristic counts changed files, not inserted lines.

Gates also distinguish a failure the change introduced from one already failing on the base, so a pre-existing red baseline does not block a good change.

Reviewer (independent)

The agent that reviews a change and produces findings. The invariant: the reviewer is never the agent that produced the change.

Draft PR

Pull requests open as drafts by intent. Auto-merge paths promote a draft to ready in the shared merge path before merging. Nothing in Orgabot should stop opening PRs as drafts.

Audit log

An append-only event stream recording everything a mission does, alongside the authority each elevated action ran under. Organization-level grants and changes additionally land in a verifiable ledger (orgabot organization ledger verify).

Autonomy and mode

The policy clamping how far a mission may act without a human. A mission's mode is clamped to the project's configured autonomy. Editing a branch is auto-approved; opening a PR, merging, and deploying require policy or explicit approval.

Approval

A real human (or explicitly delegated) decision gating a sensitive action or grant. Approvals live in ~/.orgabot/approvals/ and route to the inbox of the role that must sign off.

Worker and WorkerAdapter

A worker is the coding agent that edits files. WorkerAdapter is the swappable contract every worker implements, so workers are interchangeable under the orchestrator: the Claude Code adapter, the Codex adapter, an API-key executor, and the deterministic mock worker all plug in at the same seam.

Edit-only vs shell

Orgabot owns workflow-gate and repository-milestone evidence. Worker access is derived from the selected role's toolchest; --edit-only clamps it to editing, and --shell explicitly requests shell access. Shell commands are gated live against the role's tool and connector grants. --operate remains a deprecated alias for --shell.

Hold

A mission that has stopped and is waiting on something specific: a failed gate, a missing grant, an unanswered question, an exhausted quota, an unwritable context source, or an unroutable role. A hold preserves the worktree, branch, session, and recovery evidence. It is a state to resolve, never a silent failure.

Salvage

On worker death or timeout, Orgabot commits work-in-progress to a salvage branch, excluding untracked build-artifact directories (.build/, node_modules/, dist/, target/, DerivedData/) and untracked files over 5 MB. Already-tracked files are still committed. Continue with orgabot mission --base <salvage-branch>.

Objective

A higher-level goal that missions serve, so multi-mission work rolls up to one tracked outcome (orgabot objective).

Duty

A scheduled, recurring objective a role performs on a cron or interval. orgabot duty run-due is the entrypoint a launchd or cron job calls. There is no always-running Orgabot daemon.