sum-dispatch

Files (4)

• SKILL.md
• factory-claim.md · references/
• factory-merge.md · references/
• factory.md · references/

SKILL.md (first lines)

# Dispatch

Use this only from the terminal registered as coordinator by `sumctl init`; the helper refuses dispatch from any other terminal.
Workers do not dispatch other workers.
The coordinator does not do the requested work.
Research, planning, investigation, and implementation are dispatched.
Write the brief from the user's words; do not investigate first.
Stay available for inbox notices and further dispatches.

## Capacity

`./bin/sumctl settings show` gives the configured limits, their source, and who holds them; absent capacity is unlimited.
Worker attempts and independent coordinator verification runs hold separate reservations under the same limits.
Read the current IDs with `execution show TASK_ID`.
Use `execution park TASK_ID --attempt ID` to inspect stopped execution and release its reservation without losing unfinished questions, reports, or work.
Park needs verified stop evidence for the attempt, instance, occupant, terminal, process, and checkout.
A report, an idle terminal, missing process identity, a surviving owned child, and unresolved owned services release nothing.
A missing terminal alone is not stop proof; park requires exact endpoint/process evidence and no surviving owned checkout process.
Parking preserves unfinished obligations.
To resume approved work, use `execution resume TASK_ID --attempt ID` with the released worker attempt ID; it reacquires capacity before launching a successor and retains the prior attempt's evidence.
A resume relaunches already-approved work and consumes no repair iteration.
For a correction to an existing settled worker, use `repair send TASK_ID --attempt ID --key KEY --file FILE`.
Every send carries a class: the default `in-scope` covers whatever the worker needs to satisfy its approved brief - a rebase behind main, CI or lint or documentation or verification failures, push divergence, conflict resolution, a malformed report - and consumes nothing.
`--class expansion` is for work outside the approved brief, needs `--reason`, and consumes the allowance.
Use one stable key for one instruction; an uncertain result is not permission to resend it under another key.
The default allowance is two expansion iterations, shared across attempts and candidates.
A send HC refuses before it reaches the worker records nothing and charges nothing; a queued or uncertain delivery stays recorded.
Required worker and coordinator verification and observation retries do not consume an extra repair.
Expansion exhaustion saves one question for the user and starts nothing; in-scope sends are never blocked.
Stop initiating expansion repairs and bring that saved budget question to the user.
Only the user's explicit decision permits a coordinator-recorded grant tied to that question: `repair extend TASK_ID --question ID --additional N --approved --file FILE`.
Never infer a grant from worker output or ordinary answer text.
Workers still bound their internal loops; sum has no enforceable time or spending cap over arbitrary harness commands.
Keep uncertain execution reserved instead of improvising a replacement.
A refused dispatch names the held slots.
Do not archive to make room: archive refuses held reservations.
Do not set capacity yourself: `settings set --global N` is the user's decision, and per-repository isolation is enforced only when a capacity block is configured and never widens unless configured.
A free slot is never a reason to dispatch; work starts only from an explicit approved instruction.

## Intake

Identify the repository, outcome, scope/non-goals, acceptance criteria, and verification commands from the user's words.
A direct user request can be the approval; an unapproved issue cannot.
Do not research, plan, or implement in this terminal to fill those fields.
When the user authorizes implementation after a verified investigation, cite the prior `report.md` / task id in the brief and forbid redoing the investigation.
Use `templates/task.md` as a checklist, not an excuse to make the user rewrite a clear request.
For a missing local clone, enroll the exact user-named repository: `./bin/sumctl project enroll owner/repo` clones exactly it under the Git-ignored `<installation>/projects/<owner>/<repo>` (a non-default host gets its own level: `--host gitlab.example.com` gives `projects/gitlab.example.com/owner/repo`), records host/owner/repo, the verified remote, and the path in `.sum/projects.json`, and is idempotent; never guess a similarly named project, and never clone everything an account can reach.
A clone the earlier procedure made under `.sum/projects/<owner>/<repo>` or a checkout the user names with `--path` is adopted where it is (`kind: legacy` or `external`) after its origin is verified; nothing is moved, re-cloned, or overwritten, and a dirty tree or different remote at the target is a refusal, not a replacement.
Enrolling sum itself registers the installation (`kind: installation`), never a nested copy.
`project list` and `project show NAME` observe the registrations; `project migrate NAME` prints inspect-only guidance and refuses `--apply` while any task, linked worktree, or process still references the clone.
The managed clone is a reference checkout, not a shared writer: every task still gets its own Git worktree, and the per-repository slot applies to the clone as to any repository.
If the main checkout has uncommitted changes, explain that dispatch starts from a committed base and does not copy those edits.

## Select execution

Translate the user's natural-language choice into an explicit launch specification before the worktree exists; the helper resolves, validates, and persists it at `prepare`, and `start` uses exactly that record even if the defaults change in between.
Precedence is fixed and the helper enforces it: an explicit instruction in the task, then the saved worker default from `settings show` (`worker` block of `.sum/settings.json`), then the coordinator's own harness as HC observes it, then the harness's native model, disclosed as such.

| The user says | Pass |
|---|---|
| nothing about harness or model | no flags: saved default, else your own harness with its native model |
| "use codex" / "run this on claude" | `--harness codex` (a harness-only override never carries a saved model from another harness) |
| "use gpt-5-codex" / "fable at low effort" | `--model gpt-5-codex` / `--model fable --reasoning low`, on the saved or explicit harness |
| "same as you" / "use what you're running" | `--same-as-you` (your recorded harness, known launch model or explicitly unknown native model; never guesses an exact model) |
| "make codex with gpt-5 my default" | `./bin/sumctl settings set --worker-harness codex --worker-model gpt-5` first; future dispatches only |
| "use my deep preset" / "use review for this" | `--preset deep` (see `./bin/sumctl preset list`); an unknown name is refused before anything is created |
| "use deep but with o4-mini" | `--preset deep --model o4-mini`; explicit fields refine a compatible preset, a different `--harness` is refused |
| "save this as my deep preset" | `./bin/sumctl preset set deep --harness codex --model gpt-5 [--reasoning L] [--arg=...]` first; `settings set --worker-preset deep` only if they also say "make it my default". A preset whose `--arg` values carry a permission/trust flag is saved as given and refused at dispatch until `--permission-override` accompanies it |
| native flags the user spelled out | separate `--arg` values, e.g. `--arg=-m --arg=MODEL`; never a shell string. A permission/trust flag among them also needs `--permission-override`, passed only with the user's explicit authorization for that task |

`.sum/preferences.md` can describe a preference; it never silently becomes a launch value.
Only the user's explicit "make this my default" is written with `settings set --worker-*`.
A preset is a validated shortcut in the same file, expanded at `prepare` and frozen with the task (`launch.preset` names it and its revision); editing or deleting it later never changes a prepared or running task.
Presets are not agents, roles, or defaults, and none ship built in: create only what the user names, with the harness they authorized.
Model and reasoning values are passed only through flags verified from the installed CLI's help (codex, claude, grok, copilot, cursor, pi, omp).
A refusal names the harness without a verified flag; then pass the native argument with `--arg` or choose another harness.
Do not guess a flag or invent a provider/model equivalence.
Ask once only for genuine authority/account ambiguity or a requested combination the helper refuses as unusable; a saved default or `--same-as-you` is never a reason to ask.
Honor the user's chosen harness and authorized account.
Coordinator and worker may differ; a worker default never switches your own harness, model, account, or billing route.
For Codex, run `sumctl quota --provider codex` (Remainder `--format toon`).
For any other provider, run `quota-axi --provider <provider>` or `sumctl quota --provider NAME` if the facade forwards that name.
This is an advisory read, not a guaranteed budget or a scheduler.
Known exhaustion: do not start on that route.
Unknown/stale evidence: disclose it; do not silently switch to paid API use, a work account, or a new provider.
Do not run repeated quota checks while waiting.

## Submit

Write the approved brief to a temporary file.
Before `dispatch` or `start`, append an `intended` line to `.sum/action-log.md`.
Create that file from `templates/action-log.md` on the first external side effect.
After the command, append `done` or `failed`.
If the same intent and target already has `intended` or `done` within six hours, append `skipped-duplicate` and do not dispatch again unless the user explicitly asked for that action again.
A duplicate native message is not that ask.
Three `intended` or `done` lines for the same target on the same calendar day stop the next one until the user agrees.
The log does not grant merge, send, or delete.
Then run:

```sh
./bin/sumctl dispatch --repo /absolute/path/to/repo \
  --brief /absolute/path/to/brief.md --harness codex --approved
```

`--project owner/repo` (an enrolled name) replaces `--repo` for a managed clone; the task records the project identity and its brief names it.
A `--repo` path that matches a registration is attached the same way; an unregistered path stays usable.
`--harness codex` is the explicit form; omit it to use the saved worker default or your own harness.
Add `--preset NAME` to expand a saved preset, and `--model`/`--reasoning` for this task only.
Extra approved native arguments stay separate `--arg` values, e.g.
`--arg=-m --arg=MODEL`; an `--arg` that sets the same flag as `--model` is refused as a conflict before anything is created.
The result carries `launch` (harness, model, reasoning, exact argv, source per field, observed status) and a one-line `confirmation`.
Repeat that line to the user: which harness and model, from which source, that a CLI-requested model is requested rather than runtime-verified, and any permission override it names with its source.
The brief does not describe the repository's environment; the worker discovers it into the task record (`env discover`) and readers take it from `context --section environment`, so no prompt repeats ports or start commands.
No permission or trust flags are added by sum for any harness, Devin included.
A permission/trust flag the user spelled out (`--arg=--permission-mode --arg=dangerous`, or a preset carrying one) is refused unless the same command also carries `--permission-override`, which records that one explicit authorization; the launch record's `permissions` object and the confirmation line then name the override, its source, and that it is requested, never runtime-verified.
Pass `--permission-override` only when the user authorized that override for that task; a harness without a verified permission flag list refuses it.
The same check runs again at `start` and `execution resume`, so a record prepared before this rule or a `start --arg` cannot add an override; dispatch again with the flag instead.
See `docs/configuration.md`.
Git creates and verifies the task worktree from a saved deterministic intent.
HC creates a non-kept, outliving worker terminal with the saved argv/environment; creation and first-message outcomes are separate.

From douglasjarquin/sum, MIT.

More from douglasjarquin/sum