Using One Connect

Issues, dispatch and review

Create or import issues, dispatch them to agents with pre-flight checks, follow each run, and take the work through independent review, merge and acceptance.

The issue list#

Choose List in the top bar. Issues sit in columns by lifecycle stage:

Filter by text, agent or label. Card badges show tracker sync: syncing, not in tracker (the tracker is in dry run) or sync failed. Below the columns are the Now/Next queues of every agent.

Create an issue#

New issue asks for a title, a description, acceptance criteria (one per line; they decide when the issue is Done), labels such as bug, schema, and a priority. The issue is created in the project's tracker. Agents can also file issues for problems they find outside their scope, with report_finding.

Import from GitHub or Linear#

Import issues previews open issues from a GitHub repository or a Linear team, lets you search their titles, keys and labels, and imports the ones you select.

• Imported issues get local tracker keys and keep their original keys and links (provenance). Importing the same issue twice is detected.
• Status changes stay local. Import requires tracker.type: local; using GitHub or Linear as the owning tracker is a separate setup.
• A live preview uses your own signed-in gh CLI, or Linear's public API with a separately stored key. It searches the latest 200 open GitHub issues or 100 Linear issues.
• Sources are declared in configuration and stay disabled until you enable them:

tracker: { type: local, key_prefix: ACC }
import_sources:
  - { id: github, name: GitHub, type: github, repo: owner/repository, enabled: false }
  - { id: linear, name: Linear, type: linear, team: ENG, enabled: false }

Dispatch#

Open an issue and use Dispatch:

1. Pick an agent. Relay and coordinator-only agents are labelled.
2. Review the assignment. It is generated from the template with the goal, acceptance criteria, scope, required checks, worktree and branch, and the frozen skills and design contract. You can edit it.
3. Read pre-flight. Every check must pass; a failure says exactly what to fix. See Pre-flight.
4. Dispatch Now if the agent is free, or queue it as Next.

From the queues, drag to reorder, or drop a card on another agent to reassign it.

While it runs#

The agent works in its own worktree and branch. Its console shows the live transcript, pending approvals, the diff against its base, tests, usage and the handoff when it arrives. You can message the agent, pause, resume, nudge or stop it. Questions it asks with ask_human come to your inbox and the run waits for your answer.

When the run ends, One Connect collects its commits, finds and verifies the handoff, re-runs the required checks itself at the exact SHA, moves the issue to Handoff received and posts the verified handoff to the tracker. See Runs.

Review and merge#

The Review & merge panel on an issue takes it from handoff to the integration branch.

1. Request review. Choose a reviewer: a different agent from the author. One Connect creates a read-only review assignment at the exact commit. The reviewer records its verdict with submit_review; findings that are not nits become linked follow-up issues, and a review with blocker findings cannot approve.

2. Check the merge gates. Every gate must pass:

   Gate	Passes when
   Source commit	The branch head is the reviewed, recorded commit
   Target branch	The target is the integration branch, not a protected branch
   Lifecycle	The issue is Approved
   Independent approval	An independent reviewer approved this exact SHA
   Required checks	The required checks passed at this SHA, in the current check runtime
   Workflow gates	Every prerequisite task of its workflow is done

3. Request merge decision. This creates a Decision bound to the exact SHAs. When you approve it, One Connect merges locally into the integration branch, then runs the required checks again at the merge SHA.

4. Record acceptance. Acceptance evidence marks the issue Done, together with the verified merge. Issues that require it also need production or real-device evidence.

App-owned Git operations suppress repository and global hooks, filters, external diff drivers, credential helpers and signing programs. A merge approval authorizes the local merge of the recorded SHAs; it does not approve repository hook code. If the repository configures a custom merge driver, conflict previews and merges stay unavailable.

Trackers#

• Dry run first. GitHub and Linear do nothing until you set live: true. Writes wait in the outbox and the UI says dry run. Turning live on is recorded as your standing approval for issue, status and comment writes to that tracker.
• Statuses use neutral categories (backlog, todo, in progress, in review, done, canceled). Linear's state_names maps them to your workflow's names; GitHub uses acc:<status> labels plus open and closed (the prefix is label_prefix).
• Sync. Each status change and its tracker write commit together. Two failed deliveries raise a critical out of sync alert. Polling (every poll_seconds, default 60) picks up edits made in the tracker and flags drift: closed there without evidence, or in progress there without a live run.
• Acceptance criteria travel in the issue body as a ## Acceptance criteria checklist.

To connect another tracker, see Adding a tracker adapter.