deliver-issue
Skill9 starsChanged 2 days agoMITView on GitHub
Deliver one larger GitHub issue end to end without asking the operator anything: plan the stack, implement through parallel subagents, pass the gates, publish stacked PRs, then loop on CI and the Opus review marker of every pushed head — fixing or rebutting each finding — until the head is green with a passing marker, merge bottom-up, verify the landing, close the issue, and file every verified follow-up. Use when the operator hands over an issue to be finished autonomously ("dotáhni issue #N", "deliver #N", "work on #N until it's merged").
3 other projects use a version of this.
Adopted by
Most recently taken up by
- grove/promise-to-prooftheir own version, first seen Oct 12, 2026
- phmatray/ai-migration-kittheir own version, first seen Sep 14, 2026
- phmatray/tagouttheir own version, first seen Sep 14, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- grove/promise-to-proof★ 4same name
- phmatray/ai-migration-kit★ 4same name
- phmatray/tagout★ 4same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository13 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- ms-rustSkill
- contributeSkill
- coordinateSkill
- gatesSkill
- github-workflowSkill
- merge-advanceSkill
- milestone-reviewSkill
- milestoneSkill
- plan-phaseSkill
- pr-handoffSkill
- releaseSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
28 rules. 0 are common, 11 are distinctive, and 17 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
11
Distinctive
This author's own choices. Worth a look.
17
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 29
Never ask the operator. Resolve every ambiguity yourself: take the most conservative interpretation consistent with docs/architecture.md, …
- Distinctive: line 36
Never end a turn waiting for the operator.
- Distinctive: line 51
Create a local task list (any progress-tracking mechanism the runtime provides) mirroring the phases and DoD items.
- Very specific: line 57
Read AGENTS.md, docs/architecture.md, and every doc the issue names.
- Very specific: line 58
Before any .rs work, read .agents/rust-guidelines/ per .agents/instructions/coding.md or the guidelines' own SKILL.md index.
- Very specific: line 70
Create the worktree per milestone step 2 with scripts/worktree-new <slug>: it lands in pohunek-worktrees/<slug> beside the primary checkout …
- Distinctive: line 77
Write a shared context file (in the session scratchpad) holding: the worktree path and HEAD, "no commits, no pushes, no branches", the …
- Very specific: line 96
run the checks its change affects: its crate's tests, clippy -D warnings (host, and scripts/darwin-check for platform/daemon code), cargo …
- Distinctive: line 101
Follow-ups in a worker's area go to the same worker — resume or re-message the worker that owns that area (it keeps its context).
- Distinctive: line 106
Every "open point" a worker reports is resolved before the phase ends: fixed in this issue when it is in scope, otherwise filed as a …
- Very specific: line 115
Run the full applicable gate set per the gates skill once on the final revision of each slice, on the whole worktree, not per crate.
- Very specific: line 119
Commit per pr-handoff: explicit staging, --no-gpg-sign, concise imperative English message with the *why*, no trailers or footers.
- Very specific: line 121
Run a local Opus subagent review of git diff origin/main...HEAD for the slice and fix every finding at MEDIUM and above before the push.
- Very specific: line 133
Every push creates a new head.
- Distinctive: line 156
Only the independent review session posts a marker.
- Distinctive: line 167
Watch: Start one background watcher per push (a monitor tool where the runtime has one.
- Very specific: line 177
Read high, medium, and low from the marker and the findings from the same comment.
- Very specific: line 214
Verify it against the code.
- Distinctive: line 220
Prefer the principled fix the finding points at over a narrow patch, and scan the touched lifecycle for the same pattern (e.g.
- Distinctive: line 256
If the operator asked for merge on green CI in the invocation, merge as soon as the checks are green, keep watching for the head's marker, …
- Very specific: line 265
Verify the landing: git fetch and confirm the merge commit is on origin/main.
- Very specific: line 291
Tests: follow the testing policy (.agents/instructions/verification.md#testing-policy): integration scenarios driving cooperating …
- Very specific: line 301
Run tests through bash, with every POHUNEK_* variable unset — zsh does not word-split $VAR, so a zsh env $U … silently removes nothing: …
- Very specific: line 304
Never print variable values.
- Distinctive: line 323
No PoC, stubs, mocks of real implementations, or placeholders.
- Very specific: line 324
Never sign commits; no Co-Authored-By or generated-by footer.
- Distinctive: line 325
Never weaken a test or a safety check to get green.
- Very specific: line 326
Every GitHub write follows github-workflow safe persistence.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
deliver-issue — autonomous issue-to-merge delivery
The operator hands over one issue and expects it back merged, verified, and
closed — not a question, not a partial state. This skill chains the
existing loop skills (github-workflow → milestone → gates →
pr-handoff → merge-advance) and adds what they leave to the operator:
the review loop, CI triage, and the merge decision. Where a step below says
"per <skill>", follow that skill; this file only states what differs.
Authorization and autonomy
- Invoking this skill is the owner's explicit request to commit, push,
open the issue's PRs, and merge them once the merge criteria (below) hold
(accepted harness trade-offs (
.agents/instructions/workflow.md)). It does not authorize releases, tags, force-pushes tomain, or work outside the issue's scope. - Never ask the operator. Resolve every ambiguity yourself: take the most
conservative interpretation consistent with
docs/architecture.md, the RFCs, and the issue's decisions, and record it on the issue asDecision (autonomous): … because …. The only stop conditions are: the issue does not exist or has no actionable scope, competing issues make the target unclear, or a required credential/permission is missing. Record a stop as a blocker comment on the issue, then report it. - Never end a turn waiting for the operator. Waiting for CI or a review is done through whatever watch/monitor capability the runtime offers (a monitor tool, a background command, or a scheduled wakeup), so the next callback or notification resumes the work.
- File every verified out-of-scope finding as its own issue automatically
(dedup, add to the project, link as a sub-issue of the delivered issue) per
github-workflow. Never "offer" a follow-up.
Phase 1 — intake
- Resolve the issue per
github-workflow(explicit number wins). Read the body and all comments; pin the DoD item IDs and the issue'supdatedAt. Before each later phase re-read it and reconcile substantive spec drift explicitly (new/changed DoD, decisions) on the issue. - Set the project status to
In Progress. - Create a local task list (any progress-tracking mechanism the runtime provides) mirroring the phases and DoD items; keep it current — it is the local progress view, the issue is the record.
Phase 2 — plan
- Read AGENTS.md,
docs/architecture.md, and every doc the issue names. Before any.rswork, read.agents/rust-guidelines/per.agents/instructions/coding.mdor the guidelines' ownSKILL.mdindex. - Split the work into a PR stack per
milestonestep 4 andpullRequestsin.github/agent-workflow.json: one concern per slice, dependency order, each slice mapped to its DoD items. Record the slice plan in the issue body. - For each slice, build a file-ownership matrix: which worker owns which files. Two workers never own the same file; work on one file is sequenced, not parallel.
Phase 3 — implement through subagents
Create the worktree per milestone step 2 with scripts/worktree-new
<slug>: it lands in pohunek-worktrees/<slug> beside the primary checkout
(the parent of git rev-parse --path-format=absolute --git-common-dir)
whichever checkout it runs from, and prints that absolute path (never under
/tmp, a small RAM tmpfs) with a reflink-seeded target/. Then, per
slice:
- Write a shared context file (in the session scratchpad) holding: the
worktree path and HEAD, "no commits, no pushes, no branches", the mandatory
repo rules (Rust guidelines, comment rules below, no hardcoded tuning
values, the testing policy (
.agents/instructions/verification.md#testing-policy), knowledge-bundle updates), the local test environment rules (below), and the report format. Brief every worker with "read the context file first" plus its own 4-step briefing (known facts,path:linestarts, testable success criteria, owned files). - Spawn the workers in parallel (several subagent/worker delegations in one
step, using your runtime's parallel-worker mechanism). Each
worker must:
- verify the task/finding against the code first and report a false
premise with
path:lineevidence instead of changing code; - for a bug, lifecycle, durability, concurrency, or security fix, add a
regression scenario — an integration scenario driving cooperating
production components through a supported boundary, or an E2E scenario
driving the real product processes — extending the existing scenario
when one fits, and show it fails without the change and passes with it;
add no test for a trivial helper change or a refactor existing scenarios
already cover, and never write a new unit test (testing policy (
.agents/instructions/verification.md#testing-policy)); - run the checks its change affects: its crate's tests, clippy
-D warnings(host, andscripts/darwin-checkfor platform/daemon code),cargo fmt, andcargo xtask docs checkwhen docs changed; - report root cause, changes with
path:line, test evidence, and open points.
- verify the task/finding against the code first and report a false
premise with
- Follow-ups in a worker's area go to the same worker — resume or re-message the worker that owns that area (it keeps its context); where the runtime offers no way to resume a worker, spawn a fresh worker briefed with the previous one's report and owned files. Spawn fresh workers only for new areas.
- Every "open point" a worker reports is resolved before the phase ends: fixed in this issue when it is in scope, otherwise filed as a follow-up issue. Nothing is left only in chat.
- Review each worker's diff yourself before accepting it: scope, ownership,
and comment rules (
git diff -U0 | grepfor history words such as "previously", "no longer", "now also", "used to", "as before").
Phase 4 — gates, commit, publish
- Run the full applicable gate set per the
gatesskill once on the final revision of each slice, on the whole worktree, not per crate. A gate that cannot run locally (see environment rules) is named as CI-only in the evidence, never silently skipped. - Commit per
pr-handoff: explicit staging,--no-gpg-sign, concise imperative English message with the why, no trailers or footers. - Run a local Opus subagent review of
git diff origin/main...HEADfor the slice and fix every finding at MEDIUM and above before the push; repeat it after every fix round. It is a pre-push quality check, not the review gate of Phase 5. - Push and open the PR stack sequentially per
pr-handoff(evidence-built descriptions,Refs #N/ finalCloses #N). Keep higher slices rebased and gate-checked locally, and push only the lowest slice currently awaiting CI or review. Publish the next one after the prior head finishes; record unpublished slices as pending on the issue.
Phase 5 — the CI + review loop
Every push creates a new head. The review gate is an opus-pr-review:v1
marker for that exact head, next to green CI. Both must be checked for
every head; checking only CI loses review rounds.
The marker is a comment on the PR conversation, authored by zajca, posted by
the independent review session for the pushed head: a fresh Opus (high
effort) session that did not author the change, started by the maintainer's
manager (the coordinator or operator) or, when no manager is named, by the
delivering agent per step 1. It carries
<!-- opus-pr-review:v1:<repo>#<N>@<40-char head sha>:high=<h>:medium=<m>:low=<l> -->followed by the findings. The rules:
- The comment author is
zajca. A marker from any other login is not a review. No label starts or enables the review. - The sha is the PR's current head. A marker for an earlier head does not carry over to a new head; when several markers name the head, the latest counts.
- GO is
high=0andmedium=0. A review with only LOW findings passes; each LOW finding is verified and filed as a follow-up issue pergithub-workflow. - Only the independent review session posts a marker. The authoring agent never posts, edits, or imitates one.
- Request the review. The authoring session never reviews its own change. Report every pushed head (PR number, sha, CI state) to the manager through the channel the invocation names. When the invocation names no manager or channel, start the independent review session yourself: a fresh session with a review-only briefing (the PR, the head sha, the issue's DoD, the marker format) that did not take part in the implementation. When a review is late, say so again and record the wait on the issue; never push or amend a head only to provoke a review.
Watch. Start one background watcher per push (a monitor tool where the runtime has one; otherwise a polling loop or repeated scheduled checks) that polls until (a) every check of the PR is non-pending and (b) a marker for the pushed head exists:
gh api "repos/<repo>/issues/<n>/comments" --paginate \ --jq '.[] | select(.user.login == "zajca") | select(.body | contains("opus-pr-review:v1:<repo>#<n>@<sha>:")) | .html_url'Read
high,medium, andlowfrom the marker and the findings from the same comment; emit failed checks and the marker link as events. Also read human reviews, inline review comments, and PR conversation comments since the last round. Re-arm on expiry. Never merge without the marker of the final head.Disputed MEDIUM. The gate stays
high=0andmedium=0at the exact head. When a MEDIUM finding is a false positive, answer it with evidence (path:line, spec reference, reproduction) as a comment on the PR. The coordinator rules on the dispute, or the maintainer when there is no coordinator, as a comment on the PR. The manager (coordinator or operator) then starts the re-review after the ruling; with no manager the delivering agent waits for the maintainer's ruling and starts it per step 1. Exactly one party starts it, and its briefing links the ruling comment so the fresh session reads the ruling from the PR. The fresh review only records the ruling; it does not replace the finding's evidence. A fresh independent review at the same head reflects the ruling in themediumcount of its marker, and the latest marker for the head decides.- CI failure triage — before changing anything:
- Fetch logs only after the whole run completed (
gh run view <run> --job <job> --log-failed; earlier it returns nothing). - Classify with evidence: regression from this diff; product race or
ordering bug exposed by CI load; non-hermetic test (depends on the
host's processes, paths, timing); pre-existing flake (check the test's
history on this branch and
mainwithgh run list). Reproduce locally under CI-like conditions when it is timing-related (build first withcargo nextest run ... --no-run, then wrap only the run inscripts/stress-run --deadline <D> -- cargo nextest run ... --stress-count N, never a detached load or one that uses every host CPU; slow fsync viastrace -f -e inject=fsync,fdatasync:delay_enter=<µs>, a helper spawning non-dumpable processes, a symlinked/longTMPDIR). - Fix the root cause. A test is aligned only to the product's real
contract (e.g. the product hook's timeout), never weakened below it.
A pre-existing flake outside the diff gets its own issue (with root
cause); rerun the failed job only after that. An agent never reruns the jobs
of a fork head (see Fork heads in
.agents/instructions/verification.md).
- Fetch logs only after the whole run completed (
- Review findings — for each finding of the round:
- Verify it against the code. A false positive is answered, not coded
around: record the evidence (
path:line, spec/manual reference, a reproduction) in the round's issue comment. A disputed MEDIUM is answered on the PR per the dispute path of Phase 5 step 2. - Group real findings by file ownership and dispatch them to workers (Phase 3 rules; resume the worker that owns the area).
- Prefer the principled fix the finding points at over a narrow patch, and scan the touched lifecycle for the same pattern (e.g. every durable write after releasing a lock) — fix all occurrences in the round.
- A finding whose proper fix is a separate design decision outside the issue's DoD becomes a follow-up issue with the evidence; one inside the DoD is fixed here, never deferred.
- Verify it against the code. A false positive is answered, not coded
around: record the evidence (
- Close the round. Re-run the checks whose inputs the round's fixes
changed (
cargo ta --printnames the affected crates; workspace-wide inputs such asCargo.toml,Cargo.lock,.config/nextest.toml, or the CI workflow mean the full applicable gate set); checks with unchanged inputs keep their evidence. Before replacing a head whose PR run is still active, identify and cancel that PR's obsolete run perpr-handoff, then verify its final status. Commit and push to the owning slice branch; restack upper slices locally withgit rebase --update-refs, and publish them bottom-up after the lower head's CI and review. Post one issue comment per round: marker link, each finding → fixed (path:line, test) / rejected (evidence) / follow-up (#issue), CI triage results, gate results, new head SHA. Go back to step 1 (report the new head).
Merge criteria for a PR (all must hold on its current head):
every required check green; the opus-pr-review:v1 marker authored by zajca
names this exact head with high=0 and medium=0, and every LOW finding is
filed as a follow-up issue; no unresolved human
review request; every DoD item the slice owns is met with evidence. A diff
that touches release workflows or xtask release code, runtime packages or
packaging, the TypeScript SDK, Cargo dependencies, or the protocol version
window also needs one green tier=main dispatch at the final head, started
after PR CI and the marker are green (gh workflow run ci.yml --ref <branch>
-f tier=main; pass -f delta=true after a green pull request run of the same
tree to reuse its green jobs instead of running them again). A fork head is never dispatched in this repository: the
maintainer re-creates the change on its own branch and dispatches that, or
relies on a later run on main (the post-merge run for the main tier; the
scheduled nightly run or a tier=nightly dispatch for the release rehearsal
and the other nightly-only jobs; Fork heads in
.agents/instructions/verification.md).
If the operator asked for merge on green CI in the invocation, merge as
soon as the checks are green, keep watching for the head's marker, and
address its findings in a new fix PR off the updated main (same loop).
Phase 6 — merge, verify, close
- Merge bottom-up per
merge-advance/pr-handoffconstraints (gh pr merge <n> --merge; retarget the next slice withgh pr edit --base main, rebase it when needed). Never merge an upper slice first. - Verify the landing:
git fetchand confirm the merge commit is onorigin/main; watch themainCI run for that commit to finish green (a redmainis fixed immediately in a new PR through the same loop). - Close the issue per
github-workflow(DoD verdict table withpath:lineevidence, merged PR links, gate results) and setDoneonly after the verified landing. Verify every write from the API response. - Clean up per
merge-advancestep 3 (worktree, local branches). - Final report to the operator: merged PRs, DoD verdicts, review rounds handled (count, rejected findings), follow-up issues filed, and anything CI-only that was not verified locally.
Rules the workers inherit
- Comments state current behavior or reason, never history ("previously", "no longer", "as before", "this replaces …"); the before/after story goes in the commit message and PR description.
- No hardcoded tuning values: reuse existing config/settings, or add a
config knob in the same pattern; document magic values
(
M-DOCUMENTED-MAGIC). - Durability and concurrency: a destructive step runs only after the durable write it depends on applied (check the result, never log-and-go); a conditional write is compared against the record as persisted; never write a stale snapshot after releasing a lock; background paths (retries, watchers, reconciliation) must not act on work a live task still owns.
- Fail closed: uncertain evidence never deletes, kills, or retires anything; it keeps a visible, retryable state.
- Tests follow the testing policy (
.agents/instructions/verification.md#testing-policy): integration scenarios driving cooperating production components through a supported boundary, or E2E scenarios driving the real product processes, with independent expected results; no new unit tests, no coverage targets, no duplicates of covered behavior. - Tests are deterministic (hooks, barriers, paused time — no sleeps) and hermetic (no dependence on the host's process table, paths, or timing).
Local environment rules
- Run tests through
bash, with everyPOHUNEK_*variable unset — zsh does not word-split$VAR, so a zshenv $U …silently removes nothing:bash -c 'for v in $(compgen -e | grep "^POHUNEK_"); do unset "$v"; done; cargo nextest run …'. Never print variable values. Never callenvorprintenvin any form (includingenv | grep -cto verify): a runtime permission or ask rule may fire on any occurrence and block the autonomous run on a confirmation; verify withcompgen -e | grep -c '^POHUNEK_'. cargo clippy --target aarch64-apple-darwincannot buildringorpsmon a Linux host without an Apple SDK; runscripts/darwin-checkinstead (it needszigon PATH). It only lints, so macOS behavior is CI-only evidence./tmpis a small tmpfs: no worktrees or target dirs there. macOS puts temporary directories below the/varsymlink — canonicalize test roots that trusted-directory checks inspect.dashandshellcheckmay be missing locally; shell scripts must stay POSIX (CI runs Ubuntudashand macOS/bin/sh).- Git in a worktree-isolated session: run plain
git/ghcommands from the worktree; nevergit stashwithout a unique tag.
Constraints
- One issue per invocation; its DoD is the contract — no scope creep, no unmet DoD item moved to a follow-up to claim completion.
- No PoC, stubs, mocks of real implementations, or placeholders.
- Never sign commits; no
Co-Authored-Byor generated-by footer. - Never weaken a test or a safety check to get green; never merge red.
- Every GitHub write follows
github-workflowsafe persistence; a blocked write is reported as blocked, never as done.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

