batch-control
/batch-control
Plan and drive a Factory batch from a local session — turn an epic into ordered stages of parallel tasks, import and validate the plan, start it, watch it to the end and act on whatever needs a person (a PR to review, a question to answer, a task to retry). Use when the user says "run this as a batch", "plan a batch", "split this epic into tasks on Factory", "start the batch", "wait for the batch", "batch report", "retry task X in the batch", or "cancel the batch". Single tasks stay with task-control; "why did it fail" stays with investigate-task.
- Author
- bellows-ai ↗
- Repository
- factory ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Plan and drive a Factory batch from a local session — turn an epic into ordered stages of parallel tasks, import and validate the plan, start it, watch it to the end and act on whatever needs a person (a PR to review, a question to answer, a task to retry). Use when the user says "run this as a batch", "plan a batch", "split this epic into tasks on Factory", "start the batch", "wait for the batch", "batch report", "retry task X in the batch", or "cancel the batch". Single tasks stay with task-control; "why did it fail" stays with investigate-task.
Triggers from the description
Original author description
Plan and drive a Factory batch from a local session — turn an epic into ordered stages of parallel tasks, import and validate the plan, start it, watch it to the end and act on whatever needs a person (a PR to review, a question to answer, a task to retry). Use when the user says "run this as a batch", "plan a batch", "split this epic into tasks on Factory", "start the batch", "wait for the batch", "batch report", "retry task X in the batch", or "cancel the batch". Single tasks stay with task-control; "why did it fail" stays with investigate-task.
How it works
- 1. Write the plan
- 2. Import, validate, revise
- 3. Start
- 4. Watch
- 5. Act on the report
- 6. Cancel
- Reporting back
SKILL.md preview
---
name: batch-control
description: Plan and drive a Factory batch from a local session — turn an epic into ordered stages of parallel tasks, import and validate the plan, start it, watch it to the end and act on whatever needs a person (a PR to review, a question to answer, a task to retry). Use when the user says "run this as a batch", "plan a batch", "split this epic into tasks on Factory", "start the batch", "wait for the batch", "batch report", "retry task X in the batch", or "cancel the batch". Single tasks stay with task-control; "why did it fail" stays with investigate-task.
---
# Drive a batch from a local session
A batch is ordered stages of parallel tasks; each task is an ordinary task thread with its own PR.
The board schedules it — closing this session, or the CLI, cancels nothing. This skill writes the
plan and reacts to what the board reports; it never schedules, merges or answers on its own.
Setup, discovery and the CLI rules are the `task-control` skill's sections 1 and 2: the same
`FACTORY_URL` and `FACTORY_TOKEN`, the same `GET /api/repos` and `GET /api/workspace/executors`
reads before a plan names a repo or an executor — plus `GET /api/org/executors` for the
organization's profiles — the same ONE npm layer
(`npm run dev -w cli -- batch …`). Batch routes take a person's credential only: a `fat_`
personal token, never an `oat_` organization token or the driver's worker token.
## 1. Write the plan
Start from `plan.example.json` beside this file and keep its shape. The contract is
`core/src/batch-plan.ts`; what matters when splitting work:
- **Stage order is the only dependency.** Tasks in one stage run in parallel and must not depend on
each other; a task that needs another's merged change goes in a later stage. There is no
`dependsOn` — any unknown field is refused.
- **Each task is one PR.** `objective` is the command the agent runs; `acceptance` and
`verification` state how a reviewer tells it is done. Up to 4000 characters each.
- Keys (`targets`, `stages`, `tasks`) match `^[a-z0-9][a-z0-9-]*$`, at most 40 characters, unique.
- `completion` is `{ "kind": "pr" }` for code changes. `{ "kind": "accepted", "condition": "…" }`
is only for a task that changes no code, and a person must accept it.
- **`executor` names a profile in a scope.** `executorScope` beside it is `user` (a personal
profile, from `GET /api/workspace/executors`) or `org` (the organization's, from
`GET /api/org/executors`), at the batch and on a task; omitted means the batch's, else `user`.
A name its scope does not hold is refused at validate with `404 UNKNOWN_EXECUTOR`.
- `policy` is `human` (the board opens PRs; people merge them) or `automerge` (the board merges
once GitHub's requirements pass). A stage may override it. Default to `human` unless the user
asks for automerge.
- Bounds: 10 targets, 20 stages, 20 tasks per stage, 100 tasks; `concurrency` 1..20,
`infraRetries` and `repairs` 0..5, `timeLimitMinutes` 1..1440.
- **Size `timeLimitMinutes` from the stages, not the task.** Stages run one after another, and each
lasts as long as its slowest task, a retry or repair included — a one-line change has taken 45
minutes once the repository's full test gate ran twice. An `automerge` stage then waits for the
target's CI on the merged commit, and a `human` stage for a person. Budget every stage that way,
with margin: past the limit nothing new launches.
**What `start` refuses today** — a plan that validates structurally can still be refused at start
with `409 BATCH_UNSUPPORTED`: more than one target (`multi_target`), or `automerge` on a board
without a GitHub installation (`automerge`). A target `branch` the remote does not have is refused
with `409 BATCH_UNKNOWN_BRANCH`. Write one target; omit `branch` to run on the repository's default.
Show the user the stages and tasks, and confirm the repo, the split and the policy before import.
Every task spends real money and opens a real PR.
## 2. Import, validate, revise
```bash
npm run dev -w cli -- batch import --file plan.json --idempotency-key <key> --json # POST /api/batches
npm run dev -w cli -- batch validate <id> --json # POST /api/batches/<id>/validate
npm run dev -w cli -- batch update <id> --version <n> --file plan.json --json # PUT /api/batches/<id>
npm run dev -w cli -- batch inspect <id> --json # GET /api/batches/<id>
```
Import answers the draft's `id` and `version`. `400 BAD_BATCH` lists every problem by its path
(`stages[0].tasks[1].target`); fix them all, then import again. Validate runs the launch checks —
repository visibility, default branch, capability, executors — writes nothing, and shows the plan
as start would freeze it. Update replaces the whole draft at the version you last read;
`409 BATCH_STALE` means someone else wrote it: inspect, merge by hand, update at the new version.
## 3. Start
Confirm with the user first — start freezes the plan and dispatches the first stage.
```bash
npm run dev -w cli -- batch start <id> --version <n> --idempotency-key <key> --json # POST /api/batches/<id>/start
```
Lost answer (exit `7`, or `1` with the "may have been applied" hint): repeat with the same key.
`409 BATCH_STARTED` means it already started.
## 4. Watch
```bash
npm run dev -w cli -- batch wait <id> --timeout 1800 --json
npm run dev -w cli -- batch report <id> --json # GET /api/batches/<id>/report
```
`wait` only watches. Its exit code says what to do next:
| Exit | Meaning | Next |
| --- | --- | --- |
| `0` | every task succeeded and passed its gate, every automerge stage verified | report, done |
| `3` | the wait budget ran out; the batch is still going | wait again |
| `6` | a task, or a stage's verification, needs a person | read the report, act on section 5 |
| `4` | a task failed and needs a decision | read the report, act on section 5 |
| `5` | cancelled, or the time limit expired | report what merged; a new batch for the rest |
| `7` | board unreachable | wait again once it answers |
After a person merges, the board needs up to a minute to observe it: a `wait` that exits `6` again
at once, naming the same merged PR, means wait again — not that the merge was missed.
## 5. Act on the report
The report's `verification` lists each automerge stage's combined check of the target after its
merges. `failed` holds the next stage with no task waiting: its `detail` names what failed on the
target branch (a check on the tip, a merge missing from it). Show it to the user; a flaky check is
re-run on GitHub by a person, a real break is fixed on the target. The board re-reads it on every
pass and advances on its own once it passes — never retry a task for it.
Each report task carries `waitReason`, `attention` and `next` — the one supported next step. Do
what `next.action` says and nothing else:
- `merge` — a `human` stage PR at `next.url`, or an `automerge` one the board can no longer merge
or repair (`waitReason` says why), needs review and merge **by a person**. List the URLs for the
user. The board verifies the merge itself and continues; never merge for them. Passing
checks are not the task's `acceptance`: compare each PR's changed files with it
(`gh pr view <url> --json files`) and name any file outside it — a repair that fixed its
failing gate may have reached past the task.
- `answer` — the agent asked a question (`next.path` names the job and question). Relay it to the
user (`npm run dev -w cli -- job questions <job>` shows its prompts), then send their answer with
`npm run dev -w cli -- job answer <job> <question> --answer <text>`, one `--answer` per prompt
in that order. Never invent an answer.
- `accept` — an `accepted`-completion task finished; show its `condition` and the run's result to
the user and, on their word, `npm run dev -w cli -- batch accept <id> <task>`
(`POST /api/batches/<id>/tasks/<task>/accept`).
- `retry` — failed, budget spent, or its PR closed. Read why first (the `investigate-task` skill on
`job`), confirm with the user, then `npm run dev -w cli -- batch retry <id> <task>`
(`POST /api/batches/<id>/tasks/<task>/retry`). A configuration failure needs the configuration
fixed, not a retry.
- `cancel` — a person force-closed this required task (it reads `cancelled by a person`), so its
stage cannot advance: tell the user, and cancel the batch (section 6) on their word.
- `wait` — the board is still on it, recovery and an `automerge` stage's merge included; go back to
section 4.
- `new_batch` — the batch is fenced; the remaining work needs a new plan.
Sibling tasks keep running while one waits on a person.
## 6. Cancel
Destroys work in progress. **Confirm with the user, quoting the batch id and title.**
```bash
npm run dev -w cli -- batch cancel <id> # POST /api/batches/<id>/cancel
```
Cancel fences first, then stops moving tasks; merges that land afterwards are still recorded.
A batch that ends — completed, cancelled or expired — marks every task thread done.
To drop one task instead, force-close its thread. Confirm with the user, quoting the task key:
```bash
npm run dev -w cli -- job done <job> --force # POST /api/jobs/<job>/done {"force": true}
```
It stops the run and cancels the task for good — no retry, no repair; its PR stays open. A required
task then holds its stage until the batch is cancelled; an optional one lets the stage go on.
## Reporting back
Name the batch id, the board's `state`, merged and open PRs, and each task that needs someone with
its `next` step. Exit `3` is "still running", never a verdict.
Files in this package (2)
- SKILL.md 10 KB
- plan.example.json 2 KB
Versions
The database has no other skills named batch-control.
Database snapshot: 13.11.2026 · package version 8a4ec5e39ad6 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100task-control
Drive a Factory task through its whole lifecycle from a local session — discover repos, executors and workflows, start a task, wait for it to settle, follow up, stop it, mark it done, remove it. Use when the user says "start a task", "run this on the board", "queue it on… - 100run
Run Epic Flow over one feature or many, across any range of stages (brainstorm, technical plan, decompose, gaps, build, verify), or a single stage with the user present: one question session up front, then the rest unattended, each stage checked from the files. Use when the user… - 100advance-task
Advance one task to its end, or every ready task under a map as a batch, and stop only where something blocks it. Use when a person asks to work a task, to run a batch, or to continue what a previous run left in Progress. - 100epic-planner
Create structured epic hierarchies for new features, major refactorings, and large tasks. Generates speckit-style artifacts (spec.md, plan.md, tasks.md, beads-import.md) in specs/ and creates real beads via `bd` CLI with wired dependencies. Use when the user says things like… - 100factory
Use to decide how much of the work runs without a person, or to climb that ladder: \"software factory\", \"dark factory\", \"how autonomous should this be\", \"run this unattended\", \"what's our next step to more automation\", \"agents that ship without me\". NOT building one… - 95arn-code-batch-planning
This skill should be used when the user says "batch planning", "batch plan", "arness batch planning", "arn-code-batch-planning", "plan multiple features", "plan all features", "plan unblocked features", "plan the backlog", "plan from backlog", "batch spec and plan", "plan next…