Skip to content
Skills Library
Management & product · Planning

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.

Repository
factory ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

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

run this as a batchplan a batchsplit this epic into tasks on Factorystart the batchwait for the batchbatch reportretry task X in the batchcancel the batch
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. 1. Write the plan
  2. 2. Import, validate, revise
  3. 3. Start
  4. 4. Watch
  5. 5. Act on the report
  6. 6. Cancel
  7. Reporting back
Original SKILL.md headings · 158 lines, 1,530 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.