Concepts

Core concepts

The vocabulary One Connect uses everywhere, from issues and assignments to runs, handoffs, evidence, approvals and decisions.

Sources of truth#

Three systems own the facts. Everything else, including the dashboard, is a view of them.

Project#

A project is one git repository with its own engine, event database, tracker binding, policies, agent worktrees, Docker namespace, context index and dashboard. Projects are isolated from each other: another project's agents, messages, keys and phone sessions are never visible. See Projects.

Agent#

An agent is one configured way of running a coding tool: for example "Codex on my ChatGPT Plus plan, as an engineer". Each agent has:

• a harness (adapter): the program it runs through, such as claude-headless or codex-cli;
• a model source (provider): your subscription by default, or an API key or local model you opt into;
• a role: lead, engineer, reviewer, qa or researcher;
• a mode: normal, or coordinator-only for agents that plan and coordinate but may never take code-writing work;
• a model rule: a fixed model, or newest within a model family;
• a concurrency of 1 to 8 simultaneous runs.

Agents never drive each other's apps. They talk to One Connect through its tools, and to each other through team messages.

Issue#

An issue (a work item in the engine) lives in the tracker and carries a key such as ACC-12, a title, a description, labels, a priority and a ## Acceptance criteria checklist. Labels map to quality-floor categories, so a security issue can require a stronger model than a docs fix.

Assignment#

An assignment binds one issue to one agent. Its prompt is generated from a template and stays editable until dispatch. It states:

• the goal and acceptance criteria;
• the scope: the paths the agent may change;
• the required checks;
• the worktree and branch;
• the frozen versions of the skills and design contract the agent must follow.

Agents call get_assignment for the current text, so nobody works from a stale copy.

Now and Next#

Each agent has one Now slot (the work it is doing) and an ordered Next queue. When Now finishes, the first Next item starts automatically, and "idle with work queued" raises an alert. Drag cards to reorder a queue, or onto another agent to reassign.

Pre-flight#

Before a dispatch, pre-flight checks the exact assignment against current state. Any failure blocks the dispatch and says why.

Run#

A run is one execution of an agent's tool for an assignment. It is a detached process with its own process group, so it survives a daemon restart and is reattached afterwards. Each line of output is redacted before it is written to disk, parsed into typed events (messages, commands, edits, tests, questions) and streamed to the agent's console. See How it works.

Worktree and branches#

• Every assignment gets its own worktree, on a branch named <agent>/<KEY>-<slug>, created from the integration branch.
• Agent branches merge into the integration branch, never straight into a protected branch such as main.
• A per-worktree pre-commit hook rejects files outside the assignment's scope. A pre-push hook rejects pushes to protected branches. The daemon itself never pushes.

Handoff#

Agents end their work with a structured handoff block, through the post_handoff tool and at the end of their final message:

### Handoff
Done: <one line: what is finished>
Evidence:
- `<exact command>` → <actual result, e.g. 42 passed, 0 failed>
Commit: <full or short SHA> on <branch>
Blocked: none | <what> (on <whom: human / issue KEY / agent id>)
Next: <the next step you recommend>

If the agent forgets, One Connect looks for a handoff in the final message, then in a commit body, and otherwise raises an alert with a generated handoff skeleton that you can review and accept.

Evidence#

Evidence is what One Connect can prove, kept separate from what an agent claims.

• Checks. After every run, the daemon re-runs the required checks itself, from committed source at the exact SHA, in your configured local Docker runtime. It never falls back to the host.
• Claims. A handoff's evidence lines are cross-checked against the commands One Connect actually saw the agent run. Each is shown as verified or claimed.
• Merge and acceptance. Done requires verified merge evidence and verified acceptance evidence, plus production or real-device evidence when the issue requires it.

Review and merge#

A different agent (author ≠ reviewer) reviews the work at its exact SHA and records a verdict. Findings that are not nits become linked follow-up issues. An approved item is merged locally into the integration branch after your merge Decision, and the required checks run again at the merge SHA. See Issues, dispatch and review.

Approvals and Decisions#

• An approval is a tool permission request from a running agent: for example, Claude Code asking to run a command that is outside its pre-approved set. Clearly in-scope requests are allowed automatically; risky ones (push, deploy, migrate, publish, messaging) wait for you.
• A Decision is a question or an exact action that needs the owner: an agent's ask_human question, a merge, a Docker action, a settings change, a cost approval, a tunnel launch or an outbound message. Action Decisions are bound to the exact action, expire, are single-use, and ask for a second confirmation when irreversible.

Every answer is recorded with who answered, when, and through which channel (desk or phone). See Inbox, approvals and decisions.

Alerts and rules#

Rules watch the event log and act or alert:

Idle agents with queued work, tracker sync failures, scope violations and served-model mismatches also raise alerts. Each rule can be turned off under policies.rules.

Event log#

Every state change is a typed event appended to SQLite in the same transaction as its side effects (tracker outbox rows, log offsets). Updates and deletes are blocked by database triggers. The daemon and the browser apply the same reducer to the same events, every event names its actor (human, agent or system), and the log doubles as the audit trail. acc rebuild replays the whole log.

Kill switch#

Stop all stops every run in the project immediately (SIGTERM, then SIGKILL, to each run's process group) and blocks new dispatch until you release it. acc kill-all works even when the daemon is down, by verifying runner process IDs from their run folders. A paired phone can engage the kill switch but cannot release it.

Lifecycle#

An issue moves through these states. When there is no direct edge, a transition walks the shortest valid path, so every intermediate state is recorded.

Backlog → Selected → Assigned (Next) → Assigned (Now) → Running → Handoff received → In review → Changes requested ↺ → Approved → Merged to integration → Release candidate → Deployed → Verified (Done)

Side states: Blocked (on a human, an issue or an agent), Stalled, Failed and Canceled. Each tracker adapter maps these onto its own statuses through neutral categories: backlog, todo, in progress, in review, done and canceled.