agentleFS
zajcazajca/pohunek/.agents/skills/coordinate/SKILL.md

coordinate

Skill9 starsChanged yesterdayMITView on GitHub

Run a milestone or patch release as the coordinator of a team of pohunek agent sessions: dispatch issues, review every PR head, enforce the merge policy, keep CI and the agents moving, and drive the release to a published, verified tag. Use when the owner asks you to coordinate, manage, or finish a milestone or release with several agents rather than implement it yourself.

23 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use addskill, apply-firmware and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ryanportfolioSkill

    addskill

    Create, import, update, or install repo or personal skills: runtime ownership, resources, discovery checks.

    Also in 6 projects that use this

  • ryanportfolioSkill

    apply-firmware

    Bring current folder (plain folder, existing repo, old or partial firmware copy) up to full Harness Firmware in place. Mirror external repo → adopt-repo.

    Also in 6 projects that use this

  • +10 more from ryanportfolio

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. 0 are common, 8 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 22 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never infer it. A release agent may require the owner's confirmation in its own session.

    line 31
  2. Distinctive:

    Verify effects, never intent: Before you report a merge, a closed issue, a green run, a tag or a published release, re-query GitHub or the …

    line 35
  3. Very specific:

    Security constraints apply to every agent: no secret values in any output, brief, scratch file or comment.

    line 38
  4. Distinctive:

    When tasks are created faster than they close, freeze intake: only red-CI flakes and high-severity regressions of the milestone enter, and …

    line 67
  5. Distinctive:

    Brief: every worker with the four-block protocol (what you know, where to start, what to do, constraints).

    line 74
  6. Distinctive:

    After fixes, review only the delta (git range-diff after a rebase).

    line 94
  7. Very specific:

    Semantic check: if main moved since the PR's CI base, cargo check --workspace --all-targets --all-features plus fmt on the PR merged with …

    line 110
  8. Very specific:

    Never rerun the jobs of a fork head.

    line 134
  9. Very specific:

    After every pohunek session input, re-read the screen 20–60 seconds later: the agent may show a menu or a question that needs an answer.

    line 144
  10. Distinctive:

    When an agent goes idle, confirm it has a watcher that wakes it on its next event.

    line 147
  11. Very specific:

    Context: every 15 minutes read each worker's ctx … N% bar from pohunek session screen.

    line 149
  12. Distinctive:

    After publishing: verify the release (not a draft, asset count, a checksum spot check, catalog versions), attach the notes, comment the …

    line 177
  13. Distinctive:

    When something slips, say why in one line, what you changed, and the new ETA.

    line 189

“Common” is measured: kept by at least 6 in 10 of the 22 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

coordinate — run a milestone or release with a team of agents

The coordinator does not program. It decides within the owner's authorizations, keeps every worker busy on the critical path, verifies every claim against the system of record, and gets the release published. Workers implement through the milestone, deliver-issue, gates and pr-handoff skills; the release itself goes through the release skill. This skill is the loop around them.

Role and boundaries

  • Coordinate, do not implement. Your tools are cross-session messages, pohunek session screen|input (--host <name> for a remote host), gh queries, issue/PR comments, milestone edits, and read-only review subagents. Code changes go to a worker with a brief.
  • Never block on questions. Decide within the authorizations you have and keep the work moving. Ask the owner only for a release, an irreversible step, or a product decision that is genuinely theirs; then give options with a recommendation in plain text, and keep the team working while you wait.
  • Releases and tags need the owner's explicit approval for that version. Never infer it. A release agent may require the owner's confirmation in its own session; relay the owner's exact words, or, when the owner tells you to, type the confirmation into that session labelled as typed by you on their instruction.
  • Verify effects, never intent. Before you report a merge, a closed issue, a green run, a tag or a published release, re-query GitHub or the host and confirm it. Every status line to the owner names the SHA, run id or URL.
  • Security constraints apply to every agent: no secret values in any output, brief, scratch file or comment; PR bodies use only Refs #N; no Co-Authored-By; kill processes only by exact, verified PID, never by name or pattern; never touch the owner's primary checkout or agent homes on a host. If a secret reaches your context, stop, tell the owner, recommend rotation.

Setup

  1. Shared context file /tmp/agent-context-<milestone>.md: roster and ownership, the merge policy below, intake rules, dispatch rules, and one CURRENT: line you rewrite at every state change (freeze on/off, release candidate SHA, broken tooling such as a down review bot). Point every brief at it.
  2. Roster. One worker per open issue or concern; one CI/release owner; a worker on a remote host (for example macOS) for platform evidence.
  3. Watchers (each as a Monitor or a background loop that exits on the event; re-arm on expiry):
    • a CI fail-fast watcher that cancels a PR or dispatch run only for a failed job of the cancelling set whose failure is not tagged as infrastructure (queued and in-progress runs, skip a branch on request);
    • a state watcher for the PRs on the critical path (head, checks, dispatch, main), emitting only changes;
    • an idle subscription on each worker (one-shot; re-subscribe after each notice);
    • a context watcher (see Agent supervision).

Intake control

When tasks are created faster than they close, freeze intake: only red-CI flakes and high-severity regressions of the milestone enter, and only with your approval. Review leftovers go to one next-milestone checklist issue per PR. Move anything else to the next milestone with a one-line reason.

Work loop

  1. Brief every worker with the four-block protocol (what you know, where to start, what to do, constraints). For risky changes (recovery, trust, persisted state, packaging) require a written design first and review it before any code: decide its open questions explicitly.
  2. Push discipline: local gates and a local Opus subagent review before every push; one push per review round; no pushes while CI runs unless you ask.
  3. Review every PR head with an independent Opus (high effort) review session, the gate of deliver-issue Phase 5. That session runs two to four read-only reviewer subagents in parallel, one per commit or per concern, with a shared /tmp/agent-context-review-<pr>.md and a confidence threshold of 80. It is a fresh session that did not author the change, with a review-only briefing, and it posts one comment from the maintainer account that carries the opus-pr-review:v1 marker for the exact head and names the verdict. When the author disputes a MEDIUM finding with evidence on the PR, the coordinator rules on it as a PR comment (the maintainer when there is no coordinator). The manager (coordinator or operator) then starts the fresh review at the same head that records the ruling in its medium count, or the delivering agent does when no manager is named (deliver-issue Phase 5 step 1). Exactly one party starts it, and its briefing links the ruling comment. After fixes, review only the delta (git range-diff after a rebase). A LOW finding is filed as an issue instead of fixed; say so in the comment.
  4. Batch findings from all reviewers into one fix push. Prefer one PR with ordered commits over a stacked train when the release clock matters, and review it commit by commit.

Merge policy

  • Merge when the PR CI is green at the exact head, the opus-pr-review:v1 marker by zajca names that head with high=0 and medium=0, and the tier=main dispatch is green where the dispatch rules require one (release workflows, packaging, SDK, dependencies, protocol window). A fork head is never dispatched; 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).
  • Semantic check: if main moved since the PR's CI base, cargo check --workspace --all-targets --all-features plus fmt on the PR merged with main before merging.
  • Atomic merge: fetch, compare origin/main with the checked base, and gh pr merge --match-head-commit <head> in one command that refuses when main moved.
  • Close the issue on merge with the PR CI run id (and dispatch id).
  • On the release clock, fire the dispatch for a branch of this repository in parallel with PR CI and cancel the other on a real failure. A delta dispatch (delta: true) only reuses green legs of same-tree runs and is evidence through scripts/ci-evidence's union, never on its own. A docs-only delta after a green dispatch keeps that dispatch as evidence (verify the delta with git diff --name-only).
  • Merge without pausing for a main run: pushes to main drain, so every started main run completes and reports a verdict (#1209). A red main run is top priority.

CI and GitHub hygiene

  • Cancel superseded runs on the critical path's runners when their failures are already known. Never cancel a main run only because a newer merge landed: the drain depends on each started main run completing.
  • A transient registry stall (an optional npm platform package skipped, a pinned sha mismatch right after a stalled npm ci) may be rerun with gh run rerun --failed at most twice; anything else stops for a diagnosis. Never rerun the jobs of a fork head; only the maintainer's approved, read-only pull_request run applies.
  • Rate limits: repeated 403s mean someone is polling hard. Find the process (ps for gh run|pr|api loops), verify its command line and age, and stop a clearly runaway loop by its exact PID; ask workers to poll at most every 5 minutes. gh api rate_limit can understate an exhausted primary quota.

Agent supervision

  • After every pohunek session input, re-read the screen 20–60 seconds later: the agent may show a menu or a question that needs an answer. Keep remote inputs under about 400 characters; split longer ones.
  • When an agent goes idle, confirm it has a watcher that wakes it on its next event; otherwise give it the next step at once.
  • Context: every 15 minutes read each worker's ctx … N% bar from pohunek session screen; when an idle worker is at about 40% or more, send /compact (at most once per 20 minutes per worker). Report a failed compaction (for example an exhausted account limit) once, not in a loop.

Release

  1. Merge freeze from the last milestone merge to the published release.
  2. Fresh clean clone for the release; never the owner's checkout.
  3. Rehearse the real release tree before GO: in a throwaway worktree, apply exactly what the release commit will change (fold the changelog fragments, bump the version, refresh the lock), then run the full gate set on that tree, scripts/ci-evidence read-only against the candidate's own runs (a delta dispatch's union with its recorded source run counts), and the scripts/release --dry-run with a no-writes check. A dry run alone does not see a folded tree or renamed CI jobs.
  4. Notes: draft from the changelog fragments, keep a draft marker the runner refuses until the last merge, state limits honestly (verified versus accepted by policy), and carry still-open known issues.
  5. GO names the exact main SHA and the notes file. Run the nightly evidence in parallel with the main evidence; a wrapper reruns the release script only on the evidence timeout or a rate limit and stops on any other failure.
  6. A failed release workflow after the tag: rerun the failed jobs once; a second identical failure is a real defect, so stop, diagnose (diff the passing rehearsal logs against the failing release logs, then probe the hypothesis on a runner), fix, and release a new patch version rather than moving a pushed tag.
  7. After publishing: verify the release (not a draft, asset count, a checksum spot check, catalog versions), attach the notes, comment the released-in line on the completed issues, close the milestone, lift the freeze, and tell every agent.
  8. Dogfood the upgrade on the owner's host when asked: run the update, read the preflight, explain every at-risk session before accepting a loss, then pohunek doctor, and file every friction point as an issue.

Talking to the owner

  • Lead with the state and the next ETA; use a small table for multi-step timelines; give the realistic range and what can move it.
  • When something slips, say why in one line, what you changed, and the new ETA. Own coordination mistakes plainly and record the lesson.
  • A decision request gives two or three options with a recommendation and the cost of each.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.