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.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- coordinator-disciplineSkill
- fulcra-agent-atcSkill
- fulcra-agent-automationSkill
- fulcra-agent-cloud-coordinatorSkill
- fulcra-agent-continuitySkill
- fulcra-agent-directivesSkill
- fulcra-agent-durable-stateSkill
- fulcra-agent-forgeSkill
- fulcra-agent-healthSkill
- fulcra-agent-operatorSkill
- fulcra-agent-presenceSkill
- fulcra-agent-reconcileSkill
- fulcra-agent-rolesSkill
- fulcra-agent-tasksSkill
- fulcra-content-reviewSkill
- fulcra-fdeSkill
- fulcra-lab-resultsSkill
- map-our-teamSkill
- sealed-secretsSkill
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
- Distinctive: line 20
Before requesting a review or leaving a verdict, probe where the handshake already stands.
- Distinctive: line 31
All probes clean → nothing is blocked on your verdict and any artifact you name is at its folded state.
- Very specific: line 108
Write it with verdict: approve|changes and notes.
- Very specific: line 124
CHANGES: if any reviewer requests changes.
- Distinctive: line 144
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 …
- Very specific: line 155
Nudge only against a live obligation: Before nudging a reviewer about a pending review, run review status <team> <slug> --json on the …
≈ “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.
Files
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) | Command | Passes when | If it fails, enter at |
| Engine + auth usable? | coord-engine doctor <team> | exits 0 and the last line is exactly doctor: healthy | fix 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 byreview request(below). OKFtype: Review.<slug>is a stable id for the artifact. For a PR it is alwayspr-N, reused across pushes;headandroundidentify the active exact-head round. Therequiredlist 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 arequiredtoken (the role, or direct agent name), not the holder's own name. The frontmatter repeats the exact head independently. Legacy/non-code reviews without--headretainverdicts/<required-token>.md. OKFtype: Verdict:--- type: Verdict reviewer: alice # who signed off (informational — the FILENAME drives the tally) head: 0123456789abcdef0123456789abcdef01234567 verdict: approve # approve | changes --- Notes / requested changes.
Lifecycle
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, soneeds-meresolves fresh lease holders. The command writesreview/<slug>.mdand echoes each exact verdict path:review <slug> requested (required: reviewer, security) reviewer reviewer -> file verdict at team/<team>/review/<slug>/verdicts/<head>--reviewer.mdAn 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'sneeds-meas apending_requiredmarker 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 baretellis 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 viatell.Verdict (reviewer): write the verdict file at the exact path
review requestechoed 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 frontmatterreviewer: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 exacthead:in the verdict frontmatter. A mismatched or missing head cannot discharge a head-keyed round.
Write it with
verdict: approve|changesand 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 inpending_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 slugreview-request-<review-slug>-<hash>, so ack that (read it fromcoord-engine inbox <team> --agent <you> --json— thenameof theREVIEW 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: achangesverdict keeps blocking until that same file is re-uploaded asapprove— pushing a fix does not clear it; the requirement must be re-affirmed.- role requirement (
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
requiredreviewers approved; PENDING otherwise.A review round that reaches APPROVED with every
requiredverdict in is settled: the fold caches it atverdicts/.settledso 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 statusnever trusts the marker: it recomputes the active-head tally on every call, so a stale or wrong marker self-heals on direct query.review statusexits 1 with... unreadable (missing slug or degraded transport) — tally unknown, retrywhen the review doc can't be read but the review root still lists it (or the listing itself failed): UNKNOWN, because without therequiredlist 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 withno such review (ABSENT)and no "retry", and a soft-deleted one exits 1 naming a tombstone; retrying either changes nothing.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 aghthat is some other client (itsgh --versiondoes not begingh version), such as a built-in client that answers onlygh 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> --jsonon the exact slug and nudge only ifpending_requiredstill 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.
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.

