Fulcra Agent Forge

Fulcra Agent Forge

Enhances [fulcra-agent-review](../fulcra-agent-review/SKILL.md). When a review's artifact: is a GitHub PR URL, the forge is the ground truth — this skill mirrors it onto the team store so coord-engine review status reflects reality:

• Evidence: one idempotent shard per PR state transition

(_coord/evidence//state-.md).

• Auto-verdict: when the PR merges, a verdicts/forge.md approval is written (reviewer forge) —

the review tally then folds it like any reviewer.

Where to start — the re-entrancy probes

The forge is stateless — forge mirror is a full idempotent pass, so there is no mid-journey resume; the probes are a preflight confirming you can mirror. Enter at the first probe that fails (per docs/skill-quality-pattern.md); both probes are non-mutating (the mirror pass itself is the only write, and it's idempotent):

| 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 mirror against a broken engine | | GitHub reachable? | gh auth status | exits 0 (an authenticated gh is installed) | authenticate the GitHub CLI: gh auth login — without it forge mirror is a clean no-op (exit 0) and no evidence is written, so review status stays stale | | Watching my authored PRs? | coord-engine needs-me --agent | a PR you authored or requested review on surfaces as a [FORGE] item (feedback is reaching you) | it isn't a swept target — register it: forge watch --agent , then sweep (see [PR feedback lives on three surfaces](#pr-feedback-lives-on-three-surfaces)) | | Feedback swept? | coord-engine forge feedback | exits 0 — a sweep pass over all three surfaces completed (new shards, if any, written) | authenticate gh first (the row above); an unauthenticated sweep is a clean no-op |

All probes clean → run one mirror pass to fold current PR state into review evidence and sweep feedback (see [Usage](#usage)); re-run on your heartbeat alongside reconcile.

Usage

coord-engine forge mirror    # one pass over all PR-backed reviews

Run it ad hoc, or on the heartbeat alongside reconcile. Requires the GitHub CLI (gh) authenticated; without it the command is a clear no-op (exit 0) — the skill degrades, nothing breaks.

PR feedback lives on three surfaces

A PR's feedback is scattered across three GitHub API surfaces, and a poll that reads only one misses the rest:

• Formal reviews — gh pr view --json reviews (APPROVE / CHANGES / COMMENTED verdicts).
• Inline review comments — gh api repos///pulls//comments (diff-anchored threads; a distinct REST shape).
• Conversation comments — gh pr view --json comments (the PR timeline).

The motivating failure mode: a watch prompt that polled conversation comments alone saw an empty timeline and reported "no feedback" while a formal CHANGES review and inline comments sat unread — a real review went unseen this way. forge feedback (sweep-only) and forge mirror (which now sweeps too) hit all three surfaces every pass, mirroring each item to an idempotent shard keyed by its GitHub node id, so a re-run converges rather than duplicating. Items authored by the PR author are skipped as self-comments — and when the PR author can't be resolved (the reviews call failed), self-skip can't apply, so the sweep notes it on stderr.

Watch PRs the review flow doesn't already cover. A PR that backs a review artifact is swept automatically; an authored or upstream PR with no review doc is not, until you register it:

coord-engine forge watch     [--agent ]  # register; default responsible = caller
coord-engine forge unwatch                            # deregister
coord-engine forge feedback                                   # sweep all three surfaces now

Discovery reads the review doc's of: first, falling back to artifact:; a watched PR joins that same target set.

The needs-me guarantee. Swept feedback on a PR you're responsible for surfaces as a [FORGE] item in needs-me and briefing for that agent, and persists until you ack it — it does not age out. Acking is two steps (non-obvious, so spell it out):

1. coord-engine needs-me --agent --json — each forge-feedback row carries an

items array; those stems are the ack ids.

1. coord-engine inbox --ack --agent — ack each stem. A later sweep that finds a

new node id writes a new shard, which re-surfaces — you silence only what you've already seen.

Notes

• Only github.com///pull/ artifacts are mirrored; other artifacts are skipped silently.
• A failing gh call leaves the review untouched (never fabricates state).
• The forge approval doesn't override human verdicts — a human changes still blocks (CHANGES dominates).

Source & license

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

• Author: ashfulcra
• Source: ashfulcra/fulcra-tools
• License: MIT
• Homepage: https://fulcradynamics.com

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