relay
/relay
Przetwarza partię poprawek użytkownika jako ścisłą pętlę pracy: segregacja, jedna pozycja naraz, sprawdzone kryteria; nowe uwagi nie przerywają pracy.
- Autor
- luzanovdm ↗
- Repozytorium
- relay ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 11.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 11.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Przetwarza partię poprawek użytkownika jako ścisłą pętlę pracy: segregacja, jedna pozycja naraz, sprawdzone kryteria; nowe uwagi nie przerywają pracy.
Oryginalny opis (EN)
Run a batch of user revisions as a strict work loop with the rq tool: triage, one item at a time, proven acceptance criteria, new feedback never interrupts. Use when the user asks for a revision queue or a batch of fixes.
Jak działa
- Talking to the user
- rq: the only way to touch the queue
- Intake
- Triage (parallel, never blocks current work)
- The loop
- Checks
- Commit gate
- Sessions
- Measure and clean
- Hooks (Claude Code)
Podgląd SKILL.md
---
name: relay
description: Run a batch of user revisions as a strict work loop with the rq tool: triage, one item at a time, proven acceptance criteria, new feedback never interrupts. Use when the user asks for a revision queue or a batch of fixes.
---
# Relay: revision work loop
Shared by Claude and Codex. The queue is a work loop driven by the `rq` tool, not
a notebook: the turn does not end while an open item exists. One writer owns a
checkout; this skill creates no other task, team, branch or publication gate.
An item is a **triaged request**, not the user's wording: original message, root
cause, root-level solution, acceptance criteria and priority, worked out before
implementation and without slowing the current work.
## Talking to the user
- **Never by id.** The user does not remember item ids. In every message to the user an item is
named by what it does ("logo on the sign-in screen centred"), in the user's language. Ids appear
only inside commands and file paths. A status or progress question is answered from `rq report`
(titles, no ids): `<done> of <total>`, what is done, what is in progress and what it waits for,
what waits for the user. The Stop hook rejects a message with three or more ids.
- **Titles are written for the user.** `rq add "<title>"` states the outcome the user will see, in the
user's language, not the ticket id, a file name or an implementation detail.
- **No false choices.** When the request names several things, do all of them. Never offer "this or
that" for work that both belong to the request, and never end a turn with a menu of next steps.
- **Done means done.** An item is either proven complete or still open. "Partially done", "the rest
needs a decision" and a completion report that lists remaining defects are not allowed: the
unfinished part keeps the item open (`in_progress`, or `blocked` with the exact missing thing).
Criteria are never narrowed to what was convenient; the Coverage section of the detail file maps
every point of the user's message to a criterion.
## rq: the only way to touch the queue
`rq` is `bin/rq` next to this file (Python 3 standard library, macOS/Linux/WSL). It owns the file
format, IDs, statuses and guards. If `rq` is not on PATH, call it by that path. Never edit
`revision-queue.md` by hand. Files live in `$(git rev-parse --git-path agent)` (outside Git `./.agent/`;
`RQ_DIR` overrides): `revision-queue.md`, `revision-queue/<ID>.md` (detail), `revision-history/`,
`revision-assets/<ID>/`, plus the state files `RESUME.md` (handoff) and `PLAN.md` (checklist plan).
Private, never committed.
| Command | Use |
|---|---|
| `rq init <batch>` | start a batch |
| `rq add "<title>" --original - [--image P --desc "visible details"] [--prio P1] [--family Q-3]` | intake; new item is `triage`, detail file created, original stored verbatim from stdin |
| `rq next [--start]` | **the loop driver**: prints `ACTION:` and the item, its criteria and next step; `--start` takes it |
| `rq set <ID> <status\|-> [key=value ...]` | change status/fields in place, guarded; `rq set <ID> - next="..."` records where to resume |
| `rq check <ID>` | run the item's `fast:` commands (per-edit, cheap) |
| `rq verify [ID ...]` | run `run:` commands, record evidence, auto-complete proven items |
| `rq evidence <ID> A<n> "<text or path>"` | manual evidence |
| `rq review <ID> <file>` | store an independent root-cause review; demanded by `REVIEW` (see The loop) |
| `rq show/list/lint/related <path>/stats/status --json` | read, validate, reuse, measure |
| `rq add "<title>" --inbox N` / `--skip 3,4` on `next`, `set`, `add` / `rq inbox` | the user's messages stored verbatim by a hook; convert or skip each; `rq inbox` only lists |
| `rq refs <words> [--pin ID]` | newest source-of-truth files by mtime; `--pin` writes the winner into Refs |
| `rq consumers <path> [--write ID]` | consumers of a file from `git grep` (selector, class, file name) with their specs |
| `rq gate [--worktree]` | commit gate (run by a git-commit hook): staged (or all changed) files vs files touched per item |
| `rq report [--json]` | human progress without ids: the only source for answering "what is the status" |
| `rq run [--name N] [--timeout S] [--idle S] -- CMD` | run a long command with a hard timeout and an idle kill, registered so nothing is left behind (use it with `run_in_background`) |
| `rq procs [--kill]` | list or kill the registered processes |
| `rq waiting "<reason>"` / `--clear` | declare that the only open work is a background job or subagent: the Stop hook then lets the turn end and the completion notification wakes the session |
| `rq close [--carry IDS]` | archive the batch (kills registered processes first) |
| `rq gc [--days N] [--apply]` | dry-run list of stale private files; `--apply` deletes |
Guards `rq` enforces: an item cannot be `pending`/`in_progress`/`implemented`
until its detail file is triaged (cause level, solution, every criterion with a
`check:`); one `in_progress` at a time; `implemented` only from `in_progress`;
`completed` only from `implemented` with evidence on every criterion (a failing
`rq verify` reopens the item to `pending`; entering `in_progress` clears old
evidence); `needs_approval` needs `decision=` and `kind=irreversible|contradicts_user|missing_info`
and is left only with `answer=`; `rq verify` refuses while any other item is untriaged, pending or in
progress (`--early` only on the user's word); triage needs a Coverage section mapping every point of
the Original to a criterion;
`blocked` and `superseded` need `reason=`; an item that is the third attempt at one problem
(or was reopened twice) cannot enter `in_progress` until `rq review` stored an independent
root-cause review (`RQ_STRIKES`, default 2). Statuses: triage, pending, in_progress,
blocked, implemented, needs_approval, completed, superseded. `[ ]` keeps the loop
alive, `[?]` (needs_approval) waits for the user, `[x]` is archived at once.
## Intake
A hook stores every user message verbatim in the inbox while a queue is active and
tells you its number; the text is already in your context, so do not list the inbox
(`rq inbox` is for messages you cannot see, e.g. after context loss). `rq next` shows
`INTAKE` when no item is in progress, and the Stop hook counts unconverted messages as
open work, so a message cannot be lost.
Each actionable request becomes its own item via `rq add "<title>" --inbox N`
(several requests = several items; images still go with `--image/--desc`); a
message that is not a request is skipped on the rq call you make anyway, never in a call of its
own: `rq next --start --skip N`, `rq add ... --skip N`, `rq set --skip N <ID> <status>` (`--skip` goes before the id). Intake is bookkeeping: it never starts work
on the new item and never changes, pauses or widens the current one; return to the
current item exactly where it was. An answer to an approval is resolved with
`rq set <ID> pending answer="..."`, not added as a new item.
Screenshots: inspect each image once and pass the visible details with `--desc`
(stored in the detail file); afterwards work from the text and reload the image
only when a detail is missing. Never invent a copied file or an observation.
## Triage (parallel, never blocks current work)
Fill the detail file (`rq show <ID>` shows the template): **Original** (verbatim),
**Cause** (`level: local|shared|kit|contract|architecture`: one file, a component several files
use, a shared kit/library/design system, an API or data contract, the system structure; `file:line`
evidence, all consumers of the affected unit), **Solution** (fix at the owning level: owner
-> state/contract -> consumer -> recovery; consumers that change; what is NOT done,
no local patches hiding a shared defect), **Acceptance criteria**, **Coverage** (every separate point
of the Original -> the criterion that proves it, one line each: `- <point> -> A2`; a point without a
criterion keeps the item untriaged), **Refs**,
**Priority** (P0 blocks user/data loss, P1 broken core flow, P2 visible defect, P3
polish; size S/M/L; deps — the user's explicit priority wins), **Confidence**.
- **Depth by size.** Quick look first. `rq consumers <path> --write <ID>` builds the
consumer list from `git grep` (not from memory) and stores it with HEAD and date;
`rq related <path>` shows earlier items that touched the same file. One local file,
one consumer, obvious cause: do it inline. Shared component, kit, contract,
several consumers or unknown cause: a read-only subagent writes the content,
the main session stores it. `consumers` and `related` work on any language (top-level
definitions plus component selectors; test files by the usual `.spec`/`.test`/`_test`/`test_`/`Tests` names).
- **Family.** Items with one suspected cause go to one triage (`family:`), so the
cause is found once. At most 3 triages in flight. `rq add` prints `similar earlier` items
(same family, similar title, two shared files in Cause or touched) that were completed before
this item was added, within the last 14 days: read them before triage, they are earlier
attempts at this problem.
- **Performance items** (slow, lag, jank, latency, ...) get a `## Baseline` section: measure
first and record the number (command, value, data size or device); the item stays untriaged
without it. Criteria state the target number, so "faster" is never accepted without a measurement.
- Result: `rq set <ID> pending prio=P1`. The user is asked (`rq set <ID> needs_approval
decision="..." kind=...`) only when `kind` is one of: `irreversible` (data loss, a destructive
or outward-facing action), `contradicts_user` (the request conflicts with the user's own earlier
words) or `missing_info` (a fact only the user has: a credential, a preference never stated).
Everything else is the agent's decision: more than one reasonable solution, a change to the kit,
an architecture or contract choice, behaviour the request implies, edge cases. For a design
or architecture fork an `architect` subagent decides and its decision is written into Solution;
the owner's earlier messages and the existing product are the tie-breakers. An implied
consequence of the request is part of the item, not a question.
### Acceptance criteria (written during triage, before implementation)
`- A1: <observable outcome> | check: <how proven> | fast: <cmd> | run: <cmd> | evidence:`
Cover: the original failure no longer reproduces (steps), each affected consumer
still works, edge/empty/error states. Prefer executable proof: `run:` is a command
or test/Playwright scenario (stored as `agent/revision-queue/<ID>.spec.*`);
`fast:` is a cheap per-edit check (typecheck of the unit, one spec). Manual
evidence only where nothing can be automated. The implementer never weakens a
criterion; narrowing needs a new triage and approval.
### Approval
For a `[?]` item tell the user **immediately**, in the message: what the item is (by title),
the decision in one or two sentences with the alternative and the recommendation. Do not stop
or wait: other items keep moving. Unanswered items are repeated in every report with the exact
question, each described in full words, never by id.
### Sources of truth (mockups, specs, tasks)
Every item that mentions a design, mockup, page or doc gets exact `Refs`, resolved
before triage ends, never from memory: `rq refs <words> --pin <ID>` lists matches
under the repo and the private agent dir (extra roots: `--root` or `RQ_ROOTS`) newest
first, prints `CHECK` when the newest and the runner-up live in different folders
(confirm the newest is the intended one), and pins path plus date. Directory names are not refs. A newer file that contradicts
an older one wins; note it. A missing source keeps the item `blocked`.
## The loop
Repeat `rq next --start`, act on `ACTION`, until it says `CLOSE`/`ASK`/`BLOCKED`:
- **WORK** — one item only. Re-read its detail file and compare the solution with
the current code (re-triage if the premise broke). Implement exactly the triaged
solution; touch only what it needs; never edit for several items in one pass.
The main session orchestrates: it hands each item (or one family) to a `worker` subagent
with the detail file as the brief and takes back a short text result. Screenshots, the
simulator and the browser are used only inside subagents, which return what they saw as text;
an image in the main context is paid for on every later turn and forces compaction.
Items of one family may follow each other inside one worker context (files read once),
each with its own criteria and evidence. After each edit run `rq check <ID>`.
Do not reset/stash/clean or include another item's changes. When done:
`rq set <ID> implemented`. Delegated implementation stays `in_progress` until
integrated and rechecked. Only an explicit urgent instruction in the user's own words
("urgent", "first", "stop, do ... now") preempts: `rq set <current> pending next="<exact
resume point>"`, `rq add ... --prio P0`, triage it, `rq next --start`; the paused
item resumes before fresh ones of its priority.
- **REVIEW** — this problem was attempted before (`note:` lists the attempts): stop patching.
An independent read-only reviewer (an `architect` subagent or a fresh session that did not
work on it) gets `rq show <ID>`, `rq related <path>` and the earlier items, and answers what is
wrong in the whole system, deeper and wider than the stated problem, not why the last fix
failed. It writes a file with `## Root cause`, `## Earlier attempts` (what each assumed and
why it did not hold), `## Shared cause` (every item and consumer with the same cause, by id),
`## Plan` (root-level fix, with a measured baseline for performance). Then
`rq review <ID> <file>`, rewrite Cause, Solution and criteria of the item and of every covered
item from the Plan, and continue with `rq next --start`. The review resets the count for the
covered items and their relatives, so the rest of the family proceeds normally.
- **INTAKE** — convert or skip the inbox messages, then return to the loop.
- **TRIAGE_NEEDED** — triage the item now (inline, or a read-only subagent); the
`note:` of WORK lists untriaged ids to start in parallel. Never wait idle.
- **VERIFY** — runs only after every item is implemented: builds, full test runs and visual
review come last, never between items (`rq verify` refuses otherwise). Start long runs with
`rq run ... ` under `run_in_background`. `rq verify` (failures reopen the item as `pending`); for `MANUAL`
criteria collect evidence and run `rq evidence`. Manual criteria of P0/P1 and
kit/architecture items are checked by a subagent that did not implement them.
- **CLOSE** — `rq close`, then report the per-item results by title (from `rq report`).
- **ASK** — report the `[?]` decisions with exact questions.
- **BLOCKED** — report the missing thing for each blocked item.
Never between iterations: a summary, "what next", offering queued items, a
report; no status line the user did not ask for. When the user asks for progress or status,
answer at once from `rq report` (see Talking to the user), then return to the loop exactly
where it was. Decisions already settled by a plan, triage or refs are not asked again.
A real blocker that only the user can resolve ends the message with one concrete question
as its last block, starting with the ask marker (`WAITING FOR ANSWER:`; `RELAY_ASK_MARKER`
changes it). The Stop hook releases the turn only for that marker, for `ASK`/`BLOCKED`, or
when nothing is open.
**Waiting.** Never wait in the foreground (`sleep`, polling loops, `tail -f`, `--watch`,
`gh run watch`): a waiting command holds the turn, so the user's messages are not seen until it
ends. Start the command as `rq run --name <what> -- <cmd>` under `run_in_background`: its exit
wakes the session, it dies on a hard timeout or when its output stops for 10 minutes, and `rq procs`
shows everything still running (`rq procs --kill` clears it). Continue with the next item. When the
only open work is that job or a subagent, run `rq waiting "<what>"` and end the turn silently (no
"waiting for notification" message): the Stop hook lets it end, and the completion wakes the
session. Never poll a job, a subagent or another agent's progress in a loop; one check per wake-up.
Before `rq close` and before a handoff, `rq procs` must be empty: stop dev servers, simulators and
watchers you started.
Failures: adding an item and stopping; reporting while items are open; abandoning
the current item because new feedback arrived; several items at once; implementing
an untriaged item; completing without per-criterion evidence; closing an item as
"partly done"; asking the user a decision the agent can take; naming items by id
in a message; a local patch over a shared cause; a mockup resolved from memory or a directory name;
fixing the same problem a third time without a review; waiting in the foreground; a background
job started without `rq run` or left running; images in the main context.
## Checks
`rq` records the duration of every `check`/`verify`; keep `fast:` to seconds and the
full run in `VERIFY`. "Tests only at the end" moves checks into `VERIFY`; it never
lets an item complete without evidence. UI criteria
use `run: pw:<spec path>`: `rq verify` runs all of them in one Playwright invocation
(`RQ_PW` overrides the command) and records evidence per criterion.
## Commit gate
`rq set <ID> in_progress` snapshots the dirty files; `implemented` records the files
the item touched. A git-commit hook runs `rq gate` and denies a commit that stages a
file of an unfinished item or one touched by several open items; commit them apart or
finish the item first. Files edited by someone else while an item is in progress are
attributed to it: keep one writer per checkout.
## Sessions
The SessionStart hook prints `RESUME.md` (a handoff you write on request: goal, done, open, branch/HEAD,
exact next step, verify commands) and `PLAN.md`, and the queue carries the state. A `PLAN.md`
checklist with open `- [ ]` steps keeps the turn alive
the same way a queue does (ignored when untouched for 12 hours). A queue belongs to
the session that last ran `rq` (hook-written `session` file). In any other session
the hooks neither capture messages nor block stopping and say "stale queue"; ignore
it unless the user asks to continue: then `rq next` adopts it.
## Measure and clean
`rq stats` shows work time, reopens, failed checks and check time per item. A reopen
after VERIFY means triage missed something: say what. `rq gc` is a dry run; apply
it only on the user's yes.
## Hooks (Claude Code)
`hooks/relay-hooks.py` (one script, installed by the plugin or the README's settings snippet)
does these things: store each user message in the inbox (and, for a progress question, point at
`rq report`), record which session owns the queue, deny `git commit` when `rq gate` fails and
foreground waits, keep the turn alive while work is open (but let it end while `rq waiting` is
fresh or `rq run` jobs are alive), reject a message that names three or more items by id, and print
the handoff at session start. Without it everything above still works, but the guarantees that
nothing is lost, stopped early or committed half-done become your job (see Codex).
## Codex
No hooks, so do by hand what they do in Claude: pipe every user message to
`rq inbox --add` (or `rq add "<title>" --original -`) before anything else, run
`rq status --json` before the final message (stop only on `CLOSE`/`ASK`/`BLOCKED`
with nothing open) and `rq gate --worktree` before every commit, and never wait in the foreground.
Answer progress questions from `rq report` and never name items by id.
## Commits and delivery
One commit per item only when the user requests that policy. Otherwise save
coherent authorized batches with explicit paths and normal hooks. No push, PR,
merge or deploy permission follows from the queue.
## After context loss
`rq next` shows the current item, its `next:` and detail path. Re-run lost
triages, reconcile the actual branch/source and the result, resume the loop. Do
not read archives or equate an existing commit with acceptance.
Pliki w paczce (2)
- SKILL.md 20 KB
- bin/rq 62 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · luzanovdm/relay | 90 | MIT |
| digital-stoic-org/agent-skills | 100 | MIT |
| epilande/ccmux | 100 | MIT |
| oleg-koval/agent-skills | 100 | MIT |
| oleg-koval/agent-skills | 100 | MIT |
| xhluca/agent-talk | 100 | MIT |
| gavishap/omnia-vault | 90 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki f713e94d9fe9 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 90relay-run
Uruchamia automatycznie oczekujące zadania w pliku statusu, jedno po drugim, przez agenta-workera, a potem przegląda partię z ograniczoną liczbą poprawek. - 90relay-plan
Planuje projekt lub partię dla workera: czyta SPEC.md, przygotowuje szkielet i testy, a potem tworzy małe zadania i plan statusu na nowej gałęzi. - 86relay-board
Pokazuje kolejkę poprawek jako tablicę: w toku, następne, czekające, zablokowane i gotowe. - 100pr-review-grill
Omawia uwagi z przeglądu pull requestu jedna po jednej: pyta, kwestionuje i decyduje, a zmiany stosuje zbiorczo.