@defrex/autobuild 0.10.0 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +97 -113
  2. package/SPEC.md +7 -4
  3. package/docs/configuration.md +2 -4
  4. package/package.json +1 -1
  5. package/packages/core/src/cli/init.ts +3 -2
  6. package/packages/core/src/orchestrator/prompt.ts +3 -1
  7. package/skills/guide/SKILL.md +12 -14
  8. package/skills/operate/SKILL.md +146 -19
package/README.md CHANGED
@@ -2,72 +2,29 @@
2
2
 
3
3
  # Autobuild
4
4
 
5
- **Tickets in, PRs out. No babysitting required.**
5
+ **Tickets in, Product out.**
6
6
 
7
7
  </div>
8
8
 
9
- Every build runs headless, so ten tickets in flight cost the same
10
- attention as one. You groom tickets in, you review pull requests out.
11
- Agents do the work, and deterministic code keeps them honest.
9
+ Autobuild runs coding agents through a fixed pipeline that plans, implements,
10
+ reviews, and verifies every ticket before it merges. You groom tickets in and
11
+ review pull requests out; agents do the work, and deterministic code keeps
12
+ them honest.
12
13
 
13
14
  ![The autobuild dispatch dashboard with four builds in flight, each partway
14
15
  through the pipeline](docs/assets/headline-wide.png)
15
16
 
16
- ## Groomed ticket in, reviewed PR out
17
-
18
- Running several coding agents by hand doesn't scale well. Every session wants
19
- prompts, permissions, and attention, and your focus becomes the ceiling.
20
- With Autobuild, each build runs the whole loop headlessly and escalates only
21
- when it is truly blocked. With attention off the critical path, throughput
22
- is only limited by how fast you can write good tickets.
23
-
24
- Headless is safe because the pipeline is deterministic code, not model
25
- judgment. State lives in a typed, append-only event log, phase transitions
26
- are owned by tested code, and every build leaves a queryable paper trail. Your
27
- merge gates are never bypassed: a PR lands when your required checks and your
28
- consent say it lands.
29
-
30
- The loop also feeds itself. While building, agents record observations —
31
- latent bugs, worthwhile refactors, follow-ups they noticed but rightly left
32
- alone. A harvester distills them into proposed tickets and files them for
33
- triage; approve one and it runs the same loop.
34
-
35
- Every seam is an adapter: ticket sources (the hosted service with database or
36
- Linear backend, direct Linear, local files, or a configured plugin), agent runtimes (Claude, Codex, Pi, or a configured plugin), the forge
37
- (GitHub via `gh`, credential-free local Git, or a configured plugin), workspaces,
38
- and the build store all sit behind
39
- narrow interfaces. Trusted Bun plugins declared in `autobuild.toml` can register
40
- third-party ticket, runtime, workspace, and forge adapters against the versioned
41
- `@defrex/autobuild/plugin-sdk` surface. Repositories may also opt into the shipped
42
- `vercel-sandbox` workspace provider: the complete build runs in an isolated
43
- Vercel VM while the local supervisor retains credentialed branch/PR publication.
44
- The default remains a local Git worktree. See the [workspace configuration and
45
- security contract](docs/configuration.md#vercel-sandbox).
46
- Teams that need one durable store across hosts
47
- can deploy the optional [hosted service](packages/hosted-store-service/README.md),
48
- which also serves a GitHub-authenticated browser dashboard, can own ticket
49
- persistence and external tracker credentials, and can run the dispatcher itself on a schedule (see [the hosted dispatcher](docs/hosted-dispatcher.md)). Repository identity across the
50
- Store, dispatcher, query commands, and that dashboard is the repository's
51
- normalized origin URL (e.g. `https://github.com/defrex/autobuild`), never a
52
- checkout path; pre-origin records are not migrated. The web UI uses a server-managed
53
- session; automation clients can use the versioned [operator API](docs/operator-api.md)
54
- for the same controls and projections without exposing service credentials, and
55
- external MCP agents connect through the [hosted MCP server](docs/mcp.md).
56
-
57
17
  ## Quickstart
58
18
 
59
19
  You need [Bun](https://bun.sh), `git`, and the local prerequisites for the
60
- agent runtime you select: Claude Code, Codex CLI, or Pi. Choosing the GitHub
61
- forge also requires an authenticated [`gh` CLI](https://cli.github.com)
62
- (`gh auth login`) or an exported `GITHUB_TOKEN`/`GH_TOKEN`; the local-git forge needs no
63
- account or remote.
64
- Init suggests only runtimes whose executable and/or provider authentication is
65
- usable on your machine.
20
+ agent runtime you select: Claude Code, Codex CLI, or Pi. The GitHub forge also
21
+ needs an authenticated [`gh` CLI](https://cli.github.com) or an exported
22
+ `GITHUB_TOKEN`/`GH_TOKEN`; the local-git forge needs no account or remote.
66
23
 
67
24
  <!-- release-install:start -->
68
25
 
69
26
  ```sh
70
- bun add -g @defrex/autobuild@0.10.0
27
+ bun add -g @defrex/autobuild@0.10.1
71
28
  ```
72
29
 
73
30
  <!-- release-install:end -->
@@ -78,44 +35,36 @@ Then, from the repository you want built:
78
35
  ab init
79
36
  ```
80
37
 
81
- Vendors the editable `ab-*` skills, writes a stack-neutral config, and hands
82
- repository-aware setup to a coding agent. Follow the canonical
83
- [installation and setup procedure](docs/setup.md) to keep local worktrees or
84
- explicitly configure Vercel, then commit the setup and check its real execution
85
- environment without creating build history:
86
-
87
- ```sh
88
- ab init --validate
89
- ```
90
-
91
- See the [configuration reference](docs/configuration.md) for every field. Only
92
- a clean readiness result should be followed by:
38
+ This vendors the editable `ab-*` skills, writes a stack-neutral config, and
39
+ hands repository-aware setup to a coding agent. The
40
+ [configuration reference](docs/configuration.md) covers every field. Then
41
+ start the dispatcher and its live dashboard:
93
42
 
94
43
  ```sh
95
44
  ab dispatch
96
45
  ```
97
46
 
98
- Starts the dispatcher, with the live dashboard on a TTY.
99
-
100
- In your selected coding agent, invoke the ticket-grooming skill:
47
+ Then groom your first ticket in your coding agent:
101
48
 
102
49
  ```text
103
- /ab-spec I want to build a feature!
50
+ /ab-spec add a retry budget
104
51
  ```
105
52
 
106
- The agent asks the questions needed to produce a quality ticket and adds it
107
- directly to your ticketing system. Using the skill to create tickets then
108
- largely becomes your input workflow.
53
+ The agent asks the questions needed to produce a buildable ticket and files it
54
+ in your tracker. From then on, that skill is how work goes in.
109
55
 
110
56
  ## How it works
111
57
 
112
- Every build moves through the same fixed pipeline:
58
+ ### Every ticket runs the pipeline
113
59
 
114
60
  ```text
115
61
  spec → plan ⇄ plan-review → implement ⇄ code-review → verify:* → finalize
116
62
  epilogue: (pr.conflicted → reconcile → verify:*)* → merged or closed
117
63
  ```
118
64
 
65
+ Each ticket moves through deterministic phases inside its own build-runner.
66
+ Every phase is a fresh agent session, with artifacts knitting them together.
67
+
119
68
  1. **spec** — the dispatcher claims a ready ticket, establishes the final
120
69
  spec, and cuts a branch. The spec is the contract for everything after.
121
70
  2. **plan ⇄ plan-review** — a planner writes an implementation plan; an
@@ -125,54 +74,88 @@ spec → plan ⇄ plan-review → implement ⇄ code-review → verify:* → fin
125
74
  you instead of looping forever.
126
75
  4. **verify:\*** — your verification steps, in the order you declare them:
127
76
  shell commands judged by exit code, or agent verifiers that return a
128
- verdict.
129
- 5. **finalize** — the PR opens with an agent-written description and a summary
130
- of explicitly attached evidence, then any post-PR steps you've configured
131
- (changelogs, release notes) run failure-tolerant. A content-producing step
132
- commits selected files locally; the runner extends the open PR branch with
133
- a regular push. A no-op adds no commit, and a publication failure becomes a
134
- follow-up observation rather than failing the green build. Agent verifiers
135
- attach an exact screenshot, trace, or other artifact with
136
- `ab artifact put <kind> <file> --attach`; the PR always gets a pinned
137
- retrieval command, and configured public image hosting can also render
138
- images inline.
77
+ verdict and can attach evidence such as screenshots.
78
+ 5. **finalize** — the PR opens with an agent-written description and the
79
+ attached evidence, then any post-PR steps you've configured (changelogs,
80
+ release notes) run.
139
81
  6. **epilogue** — the dispatcher watches the open PR. Conflicts route back
140
82
  through reconcile and re-verify; the build ends `merged` or `closed`.
141
83
 
142
- Each phase is an agent session, but the pipeline itself is not agentic:
143
- agents never decide what phase comes next, and outcomes are never inferred
144
- from what a model printed. Every phase reports through a typed CLI into an
145
- append-only event log, and tested code decides the transition. That log is
146
- the build — kill the process at any point and the dispatcher resumes from
147
- durable state, and every decision along the way stays queryable after the
148
- fact.
84
+ ### A dispatcher spawns builds
85
+
86
+ The dispatcher claims ready tickets and starts a build-runner for each.
87
+ Runners are isolated, and all state is logged. Agents never decide what phase
88
+ comes next, and outcomes are never inferred from what a model printed: every
89
+ phase reports through a typed CLI into the event log, and tested code decides
90
+ the transition. That log is the build. Kill the process at any point and the
91
+ dispatcher resumes from durable state.
149
92
 
150
93
  The pipeline grammar is fixed on purpose; `verify:*` and `finalize:*` are the
151
- extension points, declared per-repo in `autobuild.toml`. Post-step agents may
152
- commit locally but never push or call the forge; publication stays
153
- kernel-owned. For the seams and the reasoning behind them, see
154
- [`docs/architecture.md`](docs/architecture.md) and [`SPEC.md`](SPEC.md).
155
-
156
- ### Observation harvesting
157
-
158
- Builds notice things they shouldn't fix. An implementer that spots a latent
159
- bug, a worthwhile refactor, or a missing follow-up outside its spec records a
160
- structured observation (`ab observe`) and moves on — the insight is kept, and
161
- scope creep stays out of the PR.
162
-
163
- Observations accumulate per repository, and once enough pile up the
164
- dispatcher runs a separate outer workflow — scan → synthesize ⇄ review →
165
- file — that distills them into proposed tickets, deduplicated against work
166
- already filed. By default, proposals land in triage with the reserved
167
- `autobuild:proposal` label and never dispatch themselves: the label means
168
- observation harvest created the ticket for human triage, not that Autobuild has
169
- groomed or claimed it. Autobuild does not use this label as a readiness gate or
170
- remove it; it is distinct from any configured or historical `autobuild` ready
171
- label. You groom and ready proposals like any ticket you wrote yourself. Agents
172
- propose; humans dispatch.
94
+ extension points, declared per repository in `autobuild.toml`. For the seams
95
+ and the reasoning behind them, see [`docs/architecture.md`](docs/architecture.md)
96
+ and [`SPEC.md`](SPEC.md).
97
+
98
+ ## All local, all remote, or anywhere between
99
+
100
+ Every seam is an adapter you can customize for your project. The build
101
+ pipeline stays the same.
102
+
103
+ | Seam | Decides | Adapters |
104
+ | ---------- | --------------------- | ------------------------------------------ |
105
+ | tickets | where work comes from | local files, Linear, hosted, plugin |
106
+ | dispatcher | what starts builds | local process, scheduled (hosted) |
107
+ | workspace | where a build runs | git worktree, Vercel Sandbox, plugin |
108
+ | runtime | who does the thinking | Claude Code, Codex, Pi, plugin |
109
+ | forge | where code lands | local git, GitHub, plugin |
110
+ | store | where state lives | SQLite, Postgres, any HTTP store |
111
+ | operators | how you watch | terminal, web UI, MCP |
112
+
113
+ Plugins are trusted Bun modules declared in `autobuild.toml` against the
114
+ versioned `@defrex/autobuild/plugin-sdk`. Teams that want one durable store
115
+ across hosts can deploy the optional
116
+ [hosted service](packages/hosted-store-service/README.md), which adds a
117
+ browser dashboard, a [scheduled dispatcher](docs/hosted-dispatcher.md), an
118
+ [operator API](docs/operator-api.md), and an [MCP server](docs/mcp.md).
119
+
120
+
121
+ ## Built for throughput, not latency
122
+
123
+ One build may take longer than a chat with an agent. The trade is far more
124
+ changes landing every day, with much greater reliability.
125
+
126
+ - **File it and walk away.** Nothing in the pipeline waits on you. You don't
127
+ approve tool calls, paste errors back, or watch a terminal. A build
128
+ escalates to you only when it is truly blocked.
129
+ - **As many builds as you can groom.** Builds run side by side, each in its
130
+ own workspace, up to the limit you set. Your attention stops being the
131
+ ceiling; how fast you can write good tickets becomes the limit.
132
+
133
+ Headless is safe because the pipeline is deterministic code, not model
134
+ judgment. State lives in a typed, append-only event log, phase transitions
135
+ are owned by tested code, and every build leaves a queryable paper trail. Your
136
+ merge gates are never bypassed: a PR lands when your required checks and your
137
+ consent say it lands.
138
+
139
+ ## Let the queue fill itself
140
+
141
+ Once tickets are the interface, anything that can write a ticket can put work
142
+ in front of you.
143
+
144
+ Builds feed the queue themselves. An implementer that spots a latent bug, a
145
+ worthwhile refactor, or a missing follow-up outside its spec records an
146
+ observation (`ab observe`) and moves on: the insight is kept, and scope creep
147
+ stays out of the PR. Once enough pile up, the dispatcher distills them into
148
+ proposed tickets, deduplicated against work already filed, and by default
149
+ files them into triage. You groom them like any ticket you wrote yourself.
150
+ Agents propose; humans dispatch.
151
+
152
+ Support threads, meeting notes, and error telemetry can feed it the same way.
153
+ An agent with the `ab` CLI or the MCP server can file tickets and answer
154
+ routine escalations, leaving you only the real product calls.
173
155
 
174
156
  ## Learn more
175
157
 
158
+ - [autobuild.run](https://www.autobuild.run) — the project site.
176
159
  - [`docs/spec-standard.md`](docs/spec-standard.md) — what makes a ticket
177
160
  buildable: the standard every dispatched spec must meet.
178
161
  - [`docs/configuration.md`](docs/configuration.md) — the complete strict
@@ -181,7 +164,8 @@ propose; humans dispatch.
181
164
  configuration, as a worked example of the config surface.
182
165
  - [`docs/architecture.md`](docs/architecture.md) — how the design maps to the
183
166
  codebase: kernel, ports, processes, and stores.
184
- - [`packages/postgres-store/README.md`](packages/postgres-store/README.md) — serverless PostgreSQL persistence with S3-compatible or Vercel Blob storage.
167
+ - [`packages/postgres-store/README.md`](packages/postgres-store/README.md) —
168
+ serverless PostgreSQL persistence with S3-compatible or Vercel Blob storage.
185
169
  - [`docs/remote-store-protocol.md`](docs/remote-store-protocol.md) — the
186
170
  complete HTTP server contract and BuildStore conformance instructions.
187
171
  - [`SPEC.md`](SPEC.md) — the source of truth for the design and its
package/SPEC.md CHANGED
@@ -501,8 +501,11 @@ stream read's ([docs/remote-store-protocol.md](docs/remote-store-protocol.md),
501
501
 
502
502
  #### 7.1.2 The embedded orchestrator (turns)
503
503
 
504
- The orchestrator is the agent that files tickets, watches builds, unblocks
505
- them, and discusses direction — played in the hosted service by a stateless
504
+ The orchestrator is a role, not a deployment: the agent that files tickets,
505
+ watches builds, unblocks them, and discusses direction. Any agent can take it
506
+ on — a coding-agent session at the repository root using the `ab` CLI or
507
+ `ab mcp` needs no initialization — and the canonical `ab-operate` skill is its
508
+ manual in either setting. In the hosted service it is played by a stateless
506
509
  turn runner over the operator tool registry, not by an agent living in a
507
510
  sandbox (parity with MCP; no credential plumbing) and not by an external
508
511
  workflow engine (durability comes from the store; the tick pattern already
@@ -2423,8 +2426,8 @@ installs into a repo:
2423
2426
  non-agent-invocable: they are invoked explicitly by the runner or a human,
2424
2427
  never auto-triggered by a model pattern-matching a description — a model
2425
2428
  must not start a pipeline phase by accident. The model-invocable exceptions
2426
- (`ab-spec`, `ab-tickets`, `ab-guide`) are exactly the three skills that
2427
- **drive no phase**; membership is decided by that criterion, not taste.
2429
+ (`ab-spec`, `ab-tickets`, `ab-guide`, `ab-operate`) are exactly the four
2430
+ skills that **drive no phase**; membership is decided by that criterion, not taste.
2428
2431
 
2429
2432
  When `.agents/skills` and `.claude/skills` resolve to the same filesystem
2430
2433
  entry, that repository-level alias already satisfies harness discovery. Init
package/docs/configuration.md CHANGED
@@ -1572,10 +1572,8 @@ pre-attempt index and reports the original Git failure; merged worktree files
1572
1572
  remain in place and the merge's exit status is unchanged. Upgrade never pushes
1573
1573
  or rewrites history.
1574
1574
 
1575
- Autobuild now installs 12 skills; only `ab-spec`, `ab-tickets`, and `ab-guide`
1576
- are model-invocable. (`ab-operate` — the embedded orchestrator's operating
1577
- manual — also carries `disable-model-invocation: true`; it is read by the
1578
- hosted turn runner, never invoked by a model in a build session.) The setup reference is an ordinary support file in the
1575
+ Autobuild now installs 12 skills; only `ab-spec`, `ab-tickets`, `ab-guide`,
1576
+ and `ab-operate` are model-invocable. The setup reference is an ordinary support file in the
1579
1577
  editable/pristine `ab-guide` tree and participates in the same three-way
1580
1578
  upgrade merge as every other vendored file.
1581
1579
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@defrex/autobuild",
3
- "version": "0.10.0",
3
+ "version": "0.10.1",
4
4
  "description": "Agent-driven software delivery from groomed ticket to merged PR",
5
5
  "repository": {
6
6
  "type": "git",
package/packages/core/src/cli/init.ts CHANGED
@@ -161,11 +161,12 @@ export async function ensureLocalStateIgnored(targetRepo: string): Promise<boole
161
161
  * pattern-matching a description. Membership here is reserved for skills that
162
162
  * drive NO phase — `spec` is the conversation that writes a spec before a build
163
163
  * exists, `tickets` is how "move ticket X to ready" becomes an action, and
164
- * `guide` is read-only reference material about the system. For these, model
164
+ * `guide` is read-only reference material about the system, and `operate` is the
165
+ * orchestrator role's manual (a role any agent takes on, not a pipeline phase). For these, model
165
166
  * invocation is precisely the point. Keep this set small; widening it needs the
166
167
  * §16.3 criterion, not convenience.
167
168
  */
168
- export const MODEL_INVOCABLE_SKILLS = new Set(['spec', 'tickets', 'guide'])
169
+ export const MODEL_INVOCABLE_SKILLS = new Set(['spec', 'tickets', 'guide', 'operate'])
169
170
 
170
171
  /**
171
172
  * Rewrite a canonical skill's YAML frontmatter for installation (§16.3):
package/packages/core/src/orchestrator/prompt.ts CHANGED
@@ -9,7 +9,9 @@
9
9
  * packages/hosted-dispatcher/src/ship-packed-distribution.ts). It is
10
10
  * self-contained per the vendored-skill rule and teaches the tool surface,
11
11
  * the attention set, and when to escalate rather than act; nothing
12
- * repository-specific may be inlined here.
12
+ * repository-specific may be inlined here. The same skill is the manual for
13
+ * the orchestrator role in a local coding-agent session (the `ab` CLI), so
14
+ * hosted-only material stays under its own heading.
13
15
  */
14
16
  import { readFile } from 'node:fs/promises'
15
17
  import { distributionPath } from '../distribution'
package/skills/guide/SKILL.md CHANGED
@@ -899,7 +899,7 @@ repo path, needs no `AB_*` environment, and is safe to re-run. It:
899
899
  base for `ab upgrade`'s three-way merges.
900
900
  - Rewrites frontmatter on install: `name` → `ab-<name>`, and
901
901
  `disable-model-invocation: true` on every skill outside the model-invocable
902
- set (`ab-spec`, `ab-tickets`, `ab-guide`).
902
+ set (`ab-spec`, `ab-tickets`, `ab-guide`, `ab-operate`).
903
903
 
904
904
  The final report states `autobuild.toml: written|skipped`, aggregates all skill
905
905
  counts, names only attention-worthy `kept` and `overwritten` skills, and reports
@@ -1878,16 +1878,14 @@ default, when you need to know what this repo's version says).
1878
1878
  | `ab-code-review` | `code-review` phase | Fresh skeptic: review the implementation diff against spec and plan, same verdict vocabulary. |
1879
1879
  | `ab-reconcile` | `reconcile` phase (epilogue) | Resolve a conflicted PR with one merge commit, base merged *into* the build branch. Never rebases. |
1880
1880
  | `ab-finalize` | `finalize` phase | Write the PR description for a green build; the kernel opens the PR. |
1881
- | `ab-operate` | hosted only | The embedded orchestrator's own operating manual: its role, the registry tool surface with the approval semantics, the attention set, wake-trigger input, budget/approval suspension, and when to escalate to the operator rather than act. Invoked by the embedded orchestrator, never vendored into a build session. |
1882
-
1883
- Autobuild installs 12 skills. Everything except `ab-spec`, `ab-tickets`, and
1884
- `ab-guide` carries `disable-model-invocation: true` — do not invoke a phase
1885
- skill yourself, and do not remove that key to make one convenient to call. A
1886
- model starting a pipeline phase by pattern-matching a description is exactly
1887
- what the flag prevents. Those three exceptions drive no build phase, which is
1888
- the criterion for membership (§16.3): `ab-spec` and `ab-tickets` are
1889
- human/agent-facing pre-build surfaces, and `ab-guide` is read-only reference
1890
- including the setup handoff guidance. The fourth skill outside the
1891
- model-invocable set, `ab-operate`, is not a build-phase skill either: it is the
1892
- embedded orchestrator's own operating manual, read by the hosted turn runner as
1893
- its system prompt and never invoked by a model in a build session.
1881
+ | `ab-operate` | outside the pipeline; model-invocable | The orchestrator role's operating manual, for any agent: file and groom tickets, watch builds with a resumable `ab watch` / `ab wait` loop, answer escalations, pause, resume, abort, control auto-merge, and keep going until every shepherded build is merged, closed, or aborted. Also read by the hosted turn runner as its system prompt (registry tools, approval and budget suspension, wake turns). |
1882
+
1883
+ Autobuild installs 12 skills. Everything except `ab-spec`, `ab-tickets`,
1884
+ `ab-guide`, and `ab-operate` carries `disable-model-invocation: true` — do not
1885
+ invoke a phase skill yourself, and do not remove that key to make one
1886
+ convenient to call. A model starting a pipeline phase by pattern-matching a
1887
+ description is exactly what the flag prevents. Those four exceptions drive no
1888
+ build phase, which is the criterion for membership (§16.3): `ab-spec` and
1889
+ `ab-tickets` are human/agent-facing pre-build surfaces, `ab-guide` is
1890
+ read-only reference including the setup handoff guidance, and `ab-operate` is
1891
+ the manual for the orchestrator role, which any agent may take on.
package/skills/operate/SKILL.md CHANGED
@@ -1,17 +1,140 @@
1
1
  ---
2
2
  name: operate
3
- description: You are the embedded orchestrator for one repository - the agent that answers its operator sessions, watches its builds, unblocks them, and discusses direction. You run inside the hosted service with the operator tool registry bound in process. Use this skill as your operating manual — it defines your role, the complete tool surface, the approval rules, and when to stop and ask the operator instead of acting.
3
+ description: Orchestrate a repository's builds - file and groom tickets, watch builds, answer escalations, pause, resume, or abort builds, control auto-merge, and drive work to merge. Use when asked to watch, shepherd, or orchestrate builds, whether from a coding-agent session at the repository root using the ab CLI or inside the hosted service with the operator tool registry.
4
4
  ---
5
5
 
6
6
  # Operating the repository
7
7
 
8
- You are the orchestrator session for one repository. You file tickets, watch
9
- builds, unblock them, answer operator questions, and discuss direction. You
10
- are not a build phase: you never run pipeline steps, never edit the
11
- repository, and never touch a checkout. Your entire reach is the operator
12
- tool registry bound into your turn.
13
-
14
- ## How you run
8
+ The orchestrator is a role, not a deployment. It is whichever agent is
9
+ pointed at a repository to file tickets, watch builds, unblock them, answer
10
+ operator questions, and drive work to merge. Any agent can take it on: a
11
+ coding-agent session at the repository root using the `ab` CLI (or `ab mcp`),
12
+ or the hosted service's embedded turn runner. There is no initialization
13
+ step — deciding to orchestrate is enough.
14
+
15
+ The orchestrator is not a build phase: it never runs pipeline steps, never
16
+ edits the repository, and never touches a build's checkout. Its reach is the
17
+ operator surface — the `ab` CLI, or the operator tool registry bound into a
18
+ hosted turn.
19
+
20
+ Find your setting and read that section: **Running locally with the `ab`
21
+ CLI** if you are a session with a shell, **Running in the hosted service** if
22
+ your tools are the registry's `builds.*` / `tickets.*` family. The sections
23
+ after them apply to both.
24
+
25
+ ## Running locally with the `ab` CLI
26
+
27
+ Run the commands below from the repository root. Each acts with the operator's
28
+ authority, so say what you are doing before you do anything destructive.
29
+
30
+ ### Watch for attention events
31
+
32
+ `ab watch --json` streams the attention set (escalations, failures, finalize,
33
+ PR conflicted/merged/closed, build completed/aborted) as newline-delimited
34
+ records. Every record carries a `cursor`; a bounded watch ends with a trailing
35
+ `{"cursor": …}` line. Resume with `--since <cursor>` and every event after it
36
+ is delivered exactly once, including events that landed while nothing was
37
+ watching. Name slugs to watch only those builds; with none, every active build
38
+ (including ones created later) is watched. `--event <glob>` replaces the
39
+ default filter, `--timeout <dur>` bounds it (default 30 minutes, `0` is
40
+ unbounded), `--count <n>` ends it after n records.
41
+
42
+ `ab wait [<slug>...] (--for <condition> | --event <glob>) [--since <cursor>] [--json]`
43
+ blocks until a condition holds and prints one record. `--for` state conditions
44
+ are also satisfied immediately by a build already in that state; `--event` is
45
+ satisfied only by new events. Conditions include `attention`,
46
+ `blocked`, `paused`, `running`, `done`, `aborted`, `terminal`, `pr=merged`,
47
+ `pr=closed`, `pr=conflicted`, and `phase=<phase>`. Exit codes: 0 satisfied,
48
+ 1 usage or store error, 2 every named build is terminal without satisfying a
49
+ condition, 3 timeout, 4 interrupted. On 3 and 4 with `--json`, the output is a
50
+ bare `{"cursor": …}` to resume from.
51
+
52
+ Run long watches and waits in whatever background or monitor facility your
53
+ harness provides, so the session stays responsive and you are woken when they
54
+ emit. Never block a foreground command for their whole duration.
55
+
56
+ ### Keep watching until the work is done
57
+
58
+ Checking once is not shepherding. When you take responsibility for builds:
59
+
60
+ 1. Record the set you are shepherding (`ab builds --all --json`, or the slugs
61
+ you were given).
62
+ 2. Arm an event-only watch and keep its cursor:
63
+ `ab watch <slugs…> --json --since <cursor>` (omit `--since` the first
64
+ time). Events are delivered exactly once, so a build that already finished
65
+ is never replayed. Do not loop on `ab wait --for terminal|attention|…`:
66
+ state conditions are satisfied at once by any build already in that state,
67
+ even with `--since`, so a finished build would be returned again and the
68
+ loop would spin on it. If you use `ab wait`, use only `--event <glob>`
69
+ conditions (satisfied by new events only), never `--for`.
70
+ 3. Reconcile current state right after the first watch is armed, and again
71
+ whenever a watch ends without records: a watch baselines each build at its
72
+ current position and does not emit what already happened, so a build that
73
+ merged, or an escalation already open, before registration would otherwise
74
+ never reach you. Run `ab build status <slug> --json` for every slug in the
75
+ set. Reading status after arming leaves no gap — anything earlier shows in
76
+ the status, anything later arrives as an event. Treat a terminal status
77
+ (merged, closed, aborted) as that build's outcome, and an open escalation
78
+ or failed phase as attention to handle now.
79
+ 4. When a watch returns records, react: read the record, inspect the build,
80
+ answer or escalate, then re-arm from the last cursor. Keep your own
81
+ outcome table: mark a build done when you see `pr.merged`, `pr.closed`, or
82
+ `build.aborted`, or when status shows it. A timeout (exit 3, or a watch
83
+ that ends with only a `{"cursor": …}` line) is not completion — reconcile
84
+ as in step 3, then re-arm from that cursor.
85
+ 5. Stop only when every build in the set has an outcome in your table.
86
+ `pr.conflicted` is not terminal — reconcile follows. An open escalation
87
+ (`blocked`) needs a response, not patience. A watch that exits because
88
+ every named build is terminal still needs the step 3 status read to learn
89
+ how each ended.
90
+ 6. Report each outcome to the operator, and file or move tickets when the
91
+ outcome makes that obviously right.
92
+
93
+ ### Inspect
94
+
95
+ - `ab builds [--queued] [--all] [--json]` — builds and their effective status.
96
+ - `ab build status <slug> [--events N]` — one build's detail and recent events.
97
+ - `ab repository status` — the repository's derived status.
98
+ - `ab artifact` — fetch one artifact's bytes.
99
+
100
+ Read events with a cursor or a small `--events` count; logs are long.
101
+
102
+ ### Act
103
+
104
+ - `ab answer <slug> [text]` — answer an open escalation with guidance; omit the
105
+ text for a bare retry. `--dismiss` retires cited review findings,
106
+ `--review-round-ceiling <n>` raises the round limit, `--revise-spec <file>`
107
+ resolves with a revised spec. Run `ab help answer` for the full menu.
108
+ - `ab pause <slug>` / `ab resume <slug>`; `ab pause --all` / `ab resume --all`
109
+ hold and release the whole repository.
110
+ - `ab abort <slug>` — destructive: closes the PR, removes branches, and
111
+ returns the ticket to triage.
112
+ - `ab auto-merge <slug> on|off` — request or cancel native auto-merge.
113
+
114
+ ### Tickets
115
+
116
+ `ab ticket create|update|block|unblock|list|show|move|states` file, edit, and
117
+ move tickets; the `ab-tickets` skill covers the tracker's details. Moving a
118
+ ticket into the ready state sends it to dispatch — do that only when the
119
+ ticket genuinely conforms and the operator's intent is clear.
120
+
121
+ ### What the CLI does not offer
122
+
123
+ The registry has operator notes, harvest control, and `discard`, which have no
124
+ CLI equivalent, and no bulk control beyond `pause --all` / `resume --all`. Say
125
+ so rather than improvising; tell the operator, or record it with `ab observe`
126
+ when you are inside a build. `ab mcp` mounts the same registry over MCP for
127
+ harnesses that support it — if you have those tools, the hosted section's tool
128
+ descriptions apply.
129
+
130
+ ## Running in the hosted service
131
+
132
+ This section applies when your tools are the operator registry bound into
133
+ your turn. If you are a session with a shell and the `ab` CLI, use the
134
+ section above and ignore this one. In the hosted service you never supply a
135
+ repository argument; it is bound for you.
136
+
137
+ ### How you run
15
138
 
16
139
  Each of your turns is one durable agent loop:
17
140
 
@@ -26,7 +149,7 @@ Each of your turns is one durable agent loop:
26
149
  - Your tools target exactly one repository, the session's own. You never
27
150
  supply a repository argument; it is bound for you.
28
151
 
29
- ## Suspension
152
+ ### Suspension
30
153
 
31
154
  Your turn can stop in two ways, and both are normal:
32
155
 
@@ -43,7 +166,7 @@ Your turn can stop in two ways, and both are normal:
43
166
  When suspended, just stop cleanly. Anything important you want to say should
44
167
  already be in your streamed output before the suspension point.
45
168
 
46
- ## The tool surface
169
+ ### The tool surface
47
170
 
48
171
  Your tools are the operator registry. The read-only ones are always safe:
49
172
 
@@ -81,7 +204,7 @@ Every tool returns the operator API's shapes: results, or a typed failure
81
204
  (`kind`, `error`, `code`). A refusal is information, not an exception:
82
205
  report it, adapt, and carry on.
83
206
 
84
- ## The attention set
207
+ ### The attention set
85
208
 
86
209
  When the session has wake settings, the dispatcher wakes you when a build
87
210
  event matching them lands. A wake turn's first message carries the event
@@ -100,7 +223,11 @@ record and the build's reduced state as JSON. Typical wakes and what to do:
100
223
  Do not re-derive history the build's events already tell you; read events
101
224
  with a cursor and keep it short.
102
225
 
103
- ## When to escalate instead of act
226
+ ## Shared rules
227
+
228
+ These apply in both settings. Where the text below says "plain streamed text", a local session means plain text to the human in the session.
229
+
230
+ ### When to escalate instead of act
104
231
 
105
232
  Stop and ask the operator — in plain streamed text — whenever:
106
233
 
@@ -109,18 +236,18 @@ Stop and ask the operator — in plain streamed text — whenever:
109
236
  - Two readings of the operator's intent diverge in cost or risk.
110
237
  - You would be guessing about product direction, priorities, or scope.
111
238
  - A tool refusal repeats and you cannot resolve it with the tools you have.
112
- - The attention event is one you cannot act on with the registry at all.
239
+ - The attention event is one you cannot act on with the tools you have at all.
113
240
 
114
241
  Filing a ticket IS acting — do it when the request is concrete. Asking is
115
242
  not a failure; an unasked destructive action is.
116
243
 
117
- ## Boundaries
244
+ ### Boundaries
118
245
 
119
- - You never claim to have done anything outside the registry. If you cannot
246
+ - You never claim to have done anything outside the tools you have. If you cannot
120
247
  observe it with a tool, say you cannot observe it.
121
248
  - You never invent repository identity, ticket ids, or build slugs; every
122
249
  id you act on came from a tool result or the conversation.
123
- - You do not run concurrent work: one turn at a time, and a message that
124
- arrives mid-turn is answered after the current turn ends.
125
- - The operator's notes artifact is shared ground truth; keep it current
126
- when you learn something durable.
250
+ - In the hosted service you do not run concurrent work: one turn at a time,
251
+ and a message that arrives mid-turn is answered after the current turn ends.
252
+ - Where operator notes exist (hosted), they are shared ground truth; keep
253
+ them current when you learn something durable.