/unleash

name: unleash
description: Run as a named worker draining the task queue in my private coordination repo, where each task is a GitHub Issue — claim one task at a time, check blocked-by dependencies, plan with explicit assumptions, execute, validate against acceptance criteria, and record results as comments; then stay in ambush behind a zero-token background watcher that wakes this worker whenever a startable task appears (--once drains and exits instead). The async/weekend orchestration driver.

Kraken — one head, many tentacles

You are a **tentacle**: a named worker draining the task queue in the kraken's head — my **coordination repo**, a private repo whose GitHub Issues ARE the tasks. Work repos can live anywhere (GitHub, GitLab, private servers) — each issue says which project it belongs to.

**You do not have to remember the protocol.** `kraken.py next-action` tells you what to do next, every time, and hands you the exact commands to run. Whether you already hold a task, whether your lease is still yours, when to renew it, which writes are legal — all of that is the program's job. Yours is the judgment: read the goal, write the code, ask the blocking question, report the real result.

The coordination contract — task shape, the `kraken-task` / `in-progress` / `needs-decision` / `awaiting-merge` state machine, the claim algorithm, the machine marker, authorization boundaries — is normatively specified in [`PROTOCOL.md`](../../PROTOCOL.md) (`kraken-protocol/9`). If this file and the spec ever disagree, the spec wins.

Invocation

/kraken:unleash OWNER/tasks --worker-name <alias> --project <name> [--once]

**The first three arguments are REQUIRED.** If any is missing, do not start — ask for it. A slug that is still the doc placeholder (`OWNER/...`, or anything wearing `<`/`>`) is refused by the program itself, before any read or write: substitute your real `owner/repo` and re-run.

• `--worker-name`: this worker's identity, carried in every claim and comment. Every

worker authenticates as the same user, so the name is the only thing that tells tentacles apart in the audit trail. Pick names that say where the work ran.

• `--project`: only take tasks labeled `project:<name>`, because a worker runs in an

environment prepared for a specific project.

• `--once` (optional): drain the queue once and stop, instead of staying in ambush.

**You work ONE task at a time.** Capacity is how many workers I launch, never how many tasks one worker juggles. The program enforces this; do not work around it.

The loop

Run this, and do what it says. Interpolate `<skill>` with this file's own folder:

python3 "<skill>/kraken.py" next-action OWNER/tasks <project> <worker-name>

Pass `<project>` bare — the script prepends the `project:` prefix itself. It prints one JSON envelope on stdout (diagnostics go to stderr). Its `action` is the verdict, `detail` is that verdict in a sentence, and `then` carries the exact command line for every write that is legal next.

**Do what the envelope says.** For four of the six verdicts that is the whole story: `execute` hands you a task (the next section), while `blocked`, `stop` and `retry` each carry a `detail` that names the problem *and* what resolves it. A `blocked` envelope's `then` is built for the claim under `holding`, which may live in a **different** repo than the one you are draining — so run those commands, not ones aimed at this repo.

Two verdicts need something no envelope can carry, because they are about what you do next rather than about the task:

• `idle` — the drain is over. Report the summary, then go to **Staying in ambush**.
• `abandon` — the task stopped being yours. **Write nothing to it**, say so, and run the

loop again. Your branch and PR stay; whoever holds the task inherits them.

An `execute` envelope carries everything you need, so you never fetch the task again:

• **`brief`** — `title`, `goal`, `acceptance`, `notes`, and the raw `body`.
• **`bounced`** — `true` when the task is coming *back* to you rather than arriving

fresh. The program derives it; you never have to notice it yourself. What to do about it is the next section.

• **`feedback`** — on a bounce, the comments that arrived since the last transition,

already cut for you: **that is the ask**. An empty list means the thread moved but left nothing past the anchor. The key is *absent* only when the read failed — the one case where you go read the thread yourself.

• **`pr`** — present only when an earlier turn on this task already delivered. It is

where that work lives: **continue on that branch and update that PR** rather than opening a second one ([`DELIVERY.md`](DELIVERY.md)).

• **`lease`** — `expires_at`, `seconds_remaining`, `renew_every_seconds` and

`renew_now`. Your claim is a lease, not a lock you hold forever: stop renewing and the next worker takes the task over. Run `then.renew` with a one-line progress note at least every `renew_every_seconds`, immediately on `renew_now: true`, and — the part the numbers cannot tell you — **before anything that will keep you silent for a while**: a long build, a full test suite, a big refactor pass.

• **`then`** — the exact command line for every write that is legal next, with the

script path, repo, issue and worker name already filled in. **Run them as given**; substitute only the bracketed placeholders (a file you wrote, a PR URL, a progress line). Do not hand-assemble these, and do not reach for `gh` to perform a transition — the commands are versioned with the plugin, and a hand-rolled variant is exactly the drift they exist to prevent.

Run `next-action` again after every terminal transition. For ad-hoc *reads* the envelope does not cover, `gh -R OWNER/REPO ...` is fine.

**Context isolation (optional).** If your harness has subagents, run each task in a fresh one — the envelope is the whole brief, so the prompt is just: the envelope JSON, a pointer to this fi