# Fulcra Agent Review

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-ashfulcra-fulcra-tools-fulcra-agent-review`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ashfulcra](https://agentstack.voostack.com/s/ashfulcra)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ashfulcra](https://github.com/ashfulcra)
- **Source:** https://github.com/ashfulcra/fulcra-tools/tree/main/skills/fulcra-agent-review
- **Website:** https://fulcradynamics.com

## Install

```sh
agentstack add skill-ashfulcra-fulcra-tools-fulcra-agent-review
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Fulcra Agent Review

Enhances the [`fulcra-agent-teams`](https://github.com/fulcradynamics/agent-skills) 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 ` | 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  --agent ` | 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:  (required: …)` row is an open obligation on you; use the exact verdict path echoed by `review request` (head-keyed PR rounds use `verdicts/--.md`; legacy/non-code reviews use `verdicts/.md`), then verify + ack per [Lifecycle](#lifecycle) step 2 |
| Known artifact's handshake state settled? | `coord-engine review status  ` | prints a line beginning `review  in 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](#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//review//`)
- **`review/.md`** — the review request, written by `review request` (below). OKF `type: Review`.
  `` 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):
  ```yaml
  ---
  type: Review
  schema: review-request/v2
  requested_by: ash
  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: 
  ```
- **`review//verdicts/--.md`** — one append-only
  verdict per requirement and exact PR head. The suffix after `--` 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/.md`. OKF `type: Verdict`:
  ```yaml
  ---
  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`:
   ```bash
   coord-engine review request   \
       --of  [--head ] \
       --reviewer  [--reviewer  …] [--from ]
   ```
   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/.md` and echoes
   each exact verdict path:
   ```
   review  requested (required: reviewer, security)
     reviewer reviewer -> file verdict at team//review//verdicts/--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 `--` (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//verdicts/--reviewer.md`, whoever holds the role.
   - **direct requirement** (`required: alice`) →
     `review//verdicts/--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  ` — 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
   ``: the review-request directive has its own slug `review-request--`, so
   ack that (read it from `coord-engine inbox  --agent  --json` — the `name` of the `REVIEW
   REQUEST: ` row), never `--ack ` (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:
   ```bash
   coord-engine review status   --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 — a transport failure or a nonexistent slug, indistinguishable
   and both UNKNOWN (without the `required` list a lone approval would tally as a clean APPROVED and
   durably hide a pending review). A watcher must read rc 1 as *transport down, retry*, never as a state.

   **Nudge only against a live obligation.** Before nudging a reviewer about a pending review, run
   `review status   --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`](references/review-cli.md) for exact commands.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ashfulcra](https://github.com/ashfulcra)
- **Source:** [ashfulcra/fulcra-tools](https://github.com/ashfulcra/fulcra-tools)
- **License:** MIT
- **Homepage:** https://fulcradynamics.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ashfulcra-fulcra-tools-fulcra-agent-review
- Seller: https://agentstack.voostack.com/s/ashfulcra
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.