From 623945ff317dab168fe70667d8cf9c838115fa46 Mon Sep 17 00:00:00 2001 From: Rafael Prado Date: Sat, 1 Aug 2026 20:49:53 -0300 Subject: [PATCH 1/2] docs: realign the worker docs with protocol/9 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four statements drifted from the contract as protocol/8 and /9 landed. None changes behaviour; each is a place where a doc still describes a retired design. - SKILL.md's inline authorization block named only refs/kraken/claims/, omitting the state record protocol/9 made every terminal transition write. That block is the one copy that must stand on its own — SKILL.md hands it verbatim to a subagent precisely because that subagent never reads PROTOCOL.md — so it under-authorized the writes the skill goes on to order. - DELIVERY.md still described the requeue gesture as "comment and remove awaiting-merge". protocol/8 dropped the asymmetry and /9 §3.1 makes removing a held label by hand a no-op on a task that has a record: the comment alone requeues. DELIVERY.md had not been touched since before either revision. - PROTOCOL.md §12 documented four exit codes while the reference implementation also returns 3 (nothing startable) and 13 (unknown project). A driver written to §12 — which is what §12 exists to enable — reads an `idle` envelope as an unknown failure. Name both and fence them off as ergonomics, which §12 already allows above the wire contract. - AGENTS.md summarized PROTOCOL.md without the state record, protocol/9's headline. The file's version marker was updated in #166; this sentence was not. Also drop §3's label-derived reading of `queued`: since /9 the record decides, and `kraken-task` is queue membership rather than a state — the same section goes on to forbid the reading its own table implied. Prose only. No wire-contract change, so no PROTOCOL_VERSION bump and no HISTORY.md entry: these are clarifications, which the versioning rule amends in place. Co-Authored-By: Claude Opus 5 --- AGENTS.md | 5 +++-- PROTOCOL.md | 9 +++++++-- skills/unleash/DELIVERY.md | 4 ++-- skills/unleash/SKILL.md | 6 ++++-- 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2de74de..396ecab 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,8 +13,9 @@ loop around `kraken.py next-action` — **no deltas either**. ## Your operating contract — read these, then follow them 1. [`PROTOCOL.md`](PROTOCOL.md) — the normative wire contract (`kraken-protocol/9`): the - label state machine, the hidden `` markers, the claim algorithm, - delivery, and the authorization boundaries. Agent-agnostic already. + state record and the label state machine it projects, the hidden + `` markers, the claim algorithm, delivery, and the authorization + boundaries. Agent-agnostic already. 2. [`skills/unleash/SKILL.md`](skills/unleash/SKILL.md) — how a worker *executes* that contract. **Read it in full and follow it.** Every transition runs through the bundled [`skills/unleash/kraken.py`](skills/unleash/kraken.py) — the **same** program the diff --git a/PROTOCOL.md b/PROTOCOL.md index d7a9a3f..2c0e38b 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -107,7 +107,7 @@ issue timeline is the log. | Label | State | Suggested color | | --- | --- | --- | -| `kraken-task` | queued (when no other state label is present) | `1D76DB` blue | +| `kraken-task` | queue membership (§1), not a state — a task wearing no other state label *shows* as queued | `1D76DB` blue | | `in-progress` | claimed by a worker and being executed | `FBCA04` yellow | | `needs-decision` | blocked on the operator's decision | `D93F0B` red | | `awaiting-merge` | delivered, waiting for review + merge | `0E8A16` green | @@ -610,7 +610,12 @@ therefore no version handshake between the two sides. The verdict of a transition is an exit status, never text (§5.3). Matching the reference implementation's codes — `0` success, `10` lost CAS or lost lease, `11` not clear, `20` transport failure (state unknown) — is RECOMMENDED, so a driver -written against one conforming worker can drive another. +written against one conforming worker can drive another. Those four cover every +transition this contract defines; a code outside them can only come from an +ergonomic above it (below), and a driver MUST NOT read one as a transition +verdict. The reference implementation's are `3` (nothing startable) and `13` (the +repo has no such `project:` label), both reported by the claim loop and the +envelope rather than by any transition. An implementation MAY offer ergonomics above the wire contract, which are **not** part of it and which a conforming worker may ignore entirely: the reference implementation diff --git a/skills/unleash/DELIVERY.md b/skills/unleash/DELIVERY.md index 2eddec3..66b1c8a 100644 --- a/skills/unleash/DELIVERY.md +++ b/skills/unleash/DELIVERY.md @@ -10,8 +10,8 @@ task's **notes** say otherwise, every task ends as a pushed branch and a draft P ## The branch **First, check whether this task already has one.** A task can come back to the queue -after it was delivered — I bounce a review by commenting the feedback and removing -`awaiting-merge`, and the task requeues with its whole thread. The `brief.body` and the +after it was delivered — I bounce a review by commenting the feedback, and that comment +alone requeues the task with its whole thread. The `brief.body` and the issue thread will show the earlier delivery and its PR. When they do, **continue on that branch and update that PR**: opening a second branch and a second draft PR for one task splits the review and leaves an orphan PR behind. diff --git a/skills/unleash/SKILL.md b/skills/unleash/SKILL.md index 7113dc0..9c48913 100644 --- a/skills/unleash/SKILL.md +++ b/skills/unleash/SKILL.md @@ -204,8 +204,10 @@ instead. - Invoking this skill is my durable authorization to: (a) manage issues **in the coordination repo** — labels and comments, never closing or reopening a task ("done" is *delivered for review*; closing is mine or the merge's) — - and your own claim ref under `refs/kraken/claims/`: create, renew and delete your own - lease, and take over one that has expired; + and the refs under `refs/kraken/`: your own claim ref under `refs/kraken/claims/` + (create, renew and delete your own lease, and take over one that has expired), and the + state record under `refs/kraken/state/` for the task you hold, which every transition + that ends your turn writes; (b) in the task's work repo, **deliver as [`DELIVERY.md`](DELIVERY.md) describes**: create work branches, commit to them with the attribution trailers, push them, and open draft PRs. From 7adf5c922eb4831146c6baeb759584688425d7d3 Mon Sep 17 00:00:00 2001 From: Rafael Prado Date: Sat, 1 Aug 2026 20:51:32 -0300 Subject: [PATCH 2/2] docs(readme): make the comparison table the FAQ answer that asks for it Lift the "Doesn't this already exist" heading and entry above "Why not just use X?", so the section lands inside that entry's disclosure: the question a first-time reader arrives with is what is visible, and expanding it reveals the side-by-side that answers it rather than leaving the two to reference each other across the page. Also fix the "bellow" typo in the entry's prose. Co-Authored-By: Claude Opus 5 --- README.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index a5cd725..8f29d54 100644 --- a/README.md +++ b/README.md @@ -362,6 +362,18 @@ delivered, the result with the acceptance check executed, and the close: A kraken task issue timeline: claim comment, assumptions, draft PR link, result comment, and close + + +## FAQ + +
+Doesn't this already exist — Copilot, Claude cloud agents, CI? + +Partly, and for a single GitHub repo with no local services those are simpler — +say so and use them. Kraken's edge is the prepared environment, GitLab/private +work repos, and a fan-out of named, audited workers. The honest side-by-side can +be found below. + ## Why not just use X? | Alternative | Coordination primitive | Infra required | Agent-agnostic | Prefer it when | @@ -412,16 +424,6 @@ when** your automation is CI-shaped and a disposable runner is the correct environment; prefer Kraken when the environment is the point and you want no lock to a single runner or vendor. -## FAQ - -
-Doesn't this already exist — Copilot, Claude cloud agents, CI? - -Partly, and for a single GitHub repo with no local services those are simpler — -say so and use them. Kraken's edge is the prepared environment, GitLab/private -work repos, and a fan-out of named, audited workers. The honest side-by-side is -[Why not just use X?](#why-not-just-use-x) above. -