agentleFS
ashfulcraashfulcra/fulcra-tools/skills/fulcra-agent-review/SKILL.md

fulcra-agent-review

Skill10 starsChanged 2 months agoMITView on GitHub

Add a review handshake to a fulcra-agent-teams space: request review of an artifact (PR, doc, plan), reviewers leave verdicts, and the overall APPROVED/CHANGES/PENDING state is computed deterministically — including required-reviewer gating.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before requesting a review or leaving a verdict, probe where the handshake already stands.

    line 20
  2. Distinctive:

    All probes clean → nothing is blocked on your verdict and any artifact you name is at its folded state.

    line 31
  3. Very specific:

    Write it with verdict: approve|changes and notes.

    line 108
  4. Very specific:

    CHANGES: if any reviewer requests changes.

    line 124
  5. Distinctive:

    rc 0 MERGE-READY: only when the register is APPROVED at an exact head (each winning approval is a shard attesting that head), the PR is …

    line 144
  6. Very specific:

    Nudge only against a live obligation: Before nudging a reviewer about a pending review, run review status <team> <slug> --json on the …

    line 155

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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

Fulcra Agent Review

Enhances the fulcra-agent-teams skill with a lightweight review handshake: an author requests review of an artifact, one or more reviewers leave verdicts, and the overall state is folded deterministically. The single-file actions (request, verdict) are prose over fulcra-api file + the teams inbox; the verdict tally is a coord-engine command (folding multiple reviewers is a derived state — code, not eyeballing).

Where to start — the re-entrancy probes

Before requesting a review or leaving a verdict, probe where the handshake already stands. Enter at the first probe that fails (per the repo's skill-quality pattern, docs/skill-quality-pattern.md); requesting is a single-file write and a verdict is an overwrite (re-uploading your verdict file just supersedes it), so re-entry never corrupts the tally:

Probe (run in order)CommandPasses whenIf it fails, enter at
Engine + auth usable?coord-engine doctor <team>exits 0 and the last line is exactly doctor: healthyfix engine/auth first (see fulcra-agent-reconcile) — do NOT tally against a broken engine
Any reviews owed me?coord-engine needs-me <team> --agent <me>NO [REVIEW] pending verdict: row prints for you — no pending_required entry names you (NON-mutating read)Leave a verdict — each printed [REVIEW] pending verdict: <slug> (required: …) row is an open obligation on you; use the exact verdict path echoed by review request (head-keyed PR rounds use verdicts/<head>--<required-token>.md; legacy/non-code reviews use verdicts/<required-token>.md), then verify + ack per Lifecycle step 2
Known artifact's handshake state settled?coord-engine review status <team> <slug>prints a line beginning review <slug> in team/<team>: ending in APPROVED or CHANGES (deterministic fold — never tally by hand)if it prints PENDING, the review is not settled — chase the awaiting required: reviewers per Lifecycle step 3

All probes clean → nothing is blocked on your verdict and any artifact you name is at its folded state; proceed to request a new review or advance an existing one below.

Layout (under team/<team>/review/<slug>/)

  • review/<slug>.md — the review request, written by review request (below). OKF type: Review. <slug> is a stable id for the artifact. For a PR it is always pr-N, reused across pushes; head and round identify the active exact-head round. The required list is what the tally gates on (roles preferred — resolved to fresh lease holders):
    ---
    type: Review
    schema: review-request/v2
    requested_by: user
    of: https://github.com/org/repo/pull/42
    required: [reviewer, security]   # all must approve for APPROVED (string "a, b" also accepted)
    head: 0123456789abcdef0123456789abcdef01234567
    round: 2
    ts: 2026-07-08T12:00:00Z
    ---
    Review requested: <artifact>
  • review/<slug>/verdicts/<head>--<required-token>.md — one append-only verdict per requirement and exact PR head. The suffix after <head>-- is the tally key and must equal a required token (the role, or direct agent name), not the holder's own name. The frontmatter repeats the exact head independently. Legacy/non-code reviews without --head retain verdicts/<required-token>.md. OKF type: Verdict:
    ---
    type: Verdict
    reviewer: alice             # who signed off (informational — the FILENAME drives the tally)
    head: 0123456789abcdef0123456789abcdef01234567
    verdict: approve            # approve | changes
    ---
    Notes / requested changes.

Lifecycle

  1. Request (author) — one command, never a hand-written doc and never a bare tell:

    coord-engine review request <team> <slug-or-title> \
        --of <artifact> [--head <exact-sha>] \
        --reviewer <role> [--reviewer <role> …] [--from <me>]

    For a PR, use one stable slug (pr-N), the PR URL as --of, and its full 40- or 64-hex commit id as --head. Re-requesting the same slug/PR/requester/ required-set with a new head advances the same review doc to the next round; prior verdicts remain append-only and only the active head tallies. An identical head is idempotent recovery. Name roles, not identities, so needs-me resolves fresh lease holders. The command writes review/<slug>.md and echoes each exact verdict path:

    review <slug> requested (required: reviewer, security)
      reviewer reviewer -> file verdict at team/<team>/review/<slug>/verdicts/<head>--reviewer.md

    An identical re-request is idempotent recovery. For a head-keyed PR, a new exact head advances the same slug; a different artifact/requester/required set is refused rather than clobbering the existing review.

    Why the verb, not a tell: the request doc itself IS the obligation. It lands in every required reviewer's needs-me as a pending_required marker and persists there until that reviewer's verdict file exists at the echoed path — the tally folds presence-of-file, so the duty survives sessions, hosts, and compaction with no one having to remember it. A bare tell is the failure mode this replaces: an acked directive leaves no durable marker, so a dropped or forgotten review vanishes silently and the merge gates on nothing. Never request reviews via tell.

  2. Verdict (reviewer): write the verdict file at the exact path review request echoed for you — slug-exact, with the required token encoded after <head>-- (or as the whole legacy filename), not your own name. That path token is what the tally matches, not the frontmatter reviewer: field:

    • role requirement (required: reviewer) → review/<review-slug>/verdicts/<head>--reviewer.md, whoever holds the role.
    • direct requirement (required: alice) → review/<review-slug>/verdicts/<head>--alice.md. Include the same exact head: in the verdict frontmatter. A mismatched or missing head cannot discharge a head-keyed round.

    Write it with verdict: approve|changes and notes. The verdict file is what discharges the obligation (the tally folds presence-of-file). Then verify the fold reflects it (coord-engine review status <team> <review-slug> — that requirement must no longer be in pending_required) and only then ack the accompanying directive as inbox hygiene — using the directive id, NOT the <review-slug>: the review-request directive has its own slug review-request-<review-slug>-<hash>, so ack that (read it from coord-engine inbox <team> --agent <you> --json — the name of the REVIEW REQUEST: <review-slug> row), never --ack <review-slug> (which the directive would never match, leaving it re-notifying). Never satisfy a review by acking without a verdict file, or against a different review's status. To change your mind, re-upload the same file (overwrites; the File Store keeps the history). Fail-closed: a changes verdict keeps blocking until that same file is re-uploaded as approve — pushing a fix does not clear it; the requirement must be re-affirmed.

  3. Check state (anyone) — deterministic fold, do not tally by hand:

    coord-engine review status <team> <slug> --json
    # -> {state: APPROVED|CHANGES|PENDING, approvals, changes, required, pending_required}

    CHANGES if any reviewer requests changes; APPROVED if there's an approval, no outstanding changes, and all required reviewers approved; PENDING otherwise.

    A review round that reaches APPROVED with every required verdict in is settled: the fold caches it at verdicts/.settled so the fan-out folds (briefing/needs-me) skip it. Settled reviews are immutable at that head; a new exact head clears the cache and advances the same PR slug, while a changed artifact/requester/required list needs a new slug. review status never trusts the marker: it recomputes the active-head tally on every call, so a stale or wrong marker self-heals on direct query.

    review status exits 1 with ... unreadable (missing slug or degraded transport) — tally unknown, retry when the review doc can't be read but the review root still lists it (or the listing itself failed): UNKNOWN, because without the required list a lone approval would tally as a clean APPROVED and durably hide a pending review. A watcher must read that rc 1 as transport down, retry, never as a state. A slug the review root does not list at all exits 1 with no such review (ABSENT) and no "retry", and a soft-deleted one exits 1 naming a tombstone; retrying either changes nothing.

  4. Verify before merging (the merger) — the checks a merger repeats by hand, never the merge itself:

    coord-engine review merge-ready <team> <slug> [--json] [--repo OWNER/REPO] [--notify <merger>]

    rc 0 MERGE-READY only when the register is APPROVED at an exact head (each winning approval is a shard attesting that head), the PR is OPEN and not a draft, PR head == register head == verdict head, and every reported CI check passed (no checks at all is NOT READY: nothing was proven). rc 2 NOT READY lists every failed check. rc 1 UNKNOWN: the register, a verdict shard or the forge (gh pr view) could not be read, so nothing is claimed; the prose ends in "retry" iff a retry can help. A host with no GitHub CLI is UNKNOWN without "retry": that includes a gh that is some other client (its gh --version does not begin gh version), such as a built-in client that answers only gh api. With --notify <merger>, a READY result is delivered to that agent's queue as a directive keyed by the head, so a re-run at the same head dedupes and a new head is a new report. Merge with that exact head as the expected head; the verb itself never merges.

    Nudge only against a live obligation. Before nudging a reviewer about a pending review, run review status <team> <slug> --json on the exact slug and nudge only if pending_required still names that assignee — a verdict may have landed since you last looked, and a stale nudge is noise that trains reviewers to ignore the real ones. rc 1 is transport down, retry (not a settled state), so never take an unreadable tally as "no longer pending" and suppress a legitimate nudge on it.

When to use

  • Gating a merge/land on review in a multi-agent team.
  • Any "N reviewers must sign off" flow where you need an unambiguous, non-drifting verdict state.

See references/review-cli.md for exact commands.

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.