From 6ddc31e572b1093fc494b8c29259cb0cf41d44f3 Mon Sep 17 00:00:00 2001 From: Khaliq Date: Sun, 17 May 2026 22:23:13 +0200 Subject: [PATCH] Tighten review signoff scope matrix guidance --- README.md | 4 +-- prpm.json | 4 +-- skills/review-fix-signoff-loop/SKILL.md | 34 +++++++++++++++++++++++++ 3 files changed, 38 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6da037a..1201a7b 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Skills, slash commands, and a Claude Code plugin for building multi-agent systems with Agent Relay. -Package metadata lives in [prpm.json](prpm.json). The repo currently publishes `agent-workforce-skills` version `1.0.9`. +Package metadata lives in [prpm.json](prpm.json). The repo currently publishes `agent-workforce-skills` version `1.0.10`. ## Published Skills @@ -14,7 +14,7 @@ Package metadata lives in [prpm.json](prpm.json). The repo currently publishes ` | [using-agent-relay](skills/using-agent-relay/SKILL.md) | 1.2.0 | Coordinate agents in real time with Relaycast messaging, channels, threads, reactions, search, and webhooks. | | [running-headless-orchestrator](skills/running-headless-orchestrator/SKILL.md) | 1.0.5 | Self-bootstrap Agent Relay infrastructure and manage worker agents without human intervention. | | [relay-80-100-workflow](skills/relay-80-100-workflow/SKILL.md) | 1.0.7 | Author workflows that close the 80-to-100 validation gap with repair-aware test, verify, mandatory Claude-then-Codex review/fix with test hardening, and commit gates. | -| [review-fix-signoff-loop](skills/review-fix-signoff-loop/SKILL.md) | 1.0.1 | Loop review, repair, validation, and fresh-context dual-agent signoff until independent reviewers both satisfy the verdict contract. | +| [review-fix-signoff-loop](skills/review-fix-signoff-loop/SKILL.md) | 1.0.2 | Loop review, repair, validation, and fresh-context dual-agent signoff until independent reviewers both satisfy the verdict contract. | ## Slash Commands diff --git a/prpm.json b/prpm.json index a649f0a..2b75e84 100644 --- a/prpm.json +++ b/prpm.json @@ -1,6 +1,6 @@ { "name": "agent-workforce-skills", - "version": "1.0.9", + "version": "1.0.10", "description": "Skills for multi-agent coordination - swarm patterns, workflow building, relay usage, and headless orchestration", "author": "khaliqgant", "organization": "agent-relay", @@ -126,7 +126,7 @@ }, { "name": "review-fix-signoff-loop", - "version": "1.0.1", + "version": "1.0.2", "description": "Use when writing Agent Relay or Ricky workflows that must loop review, fix, and validation with fresh agent context until independent signoff agents both agree the work is comprehensively complete", "format": "claude", "subtype": "skill", diff --git a/skills/review-fix-signoff-loop/SKILL.md b/skills/review-fix-signoff-loop/SKILL.md index a83b689..a13a001 100644 --- a/skills/review-fix-signoff-loop/SKILL.md +++ b/skills/review-fix-signoff-loop/SKILL.md @@ -15,6 +15,7 @@ Pair this with `writing-agent-relay-workflows` for SDK syntax and `relay-80-100- 1. Run deterministic preflight before agents start. - Confirm repository root, required specs, declared write scope, credentials needed for PR comments, and whether commit/push/PR creation is in scope. + - For cross-repo or package-release work, write a scope matrix before implementation: repositories, branches, PRs, packages, providers/features touched, published versions, consuming package manifests, lockfiles, and expected downstream bumps. - Probe the CLIs used by later agent steps. For Codex, `codex login status` is not enough; run a tiny `codex exec --ephemeral --json --sandbox read-only -m ` prompt and fail early with a clear re-login instruction if it cannot return the expected token. - Write preflight evidence to `.workflow-artifacts//iteration-N/preflight.md`. @@ -25,10 +26,14 @@ Pair this with `writing-agent-relay-workflows` for SDK syntax and `relay-80-100- 3. Reconcile before validation. - Add a deterministic `implementation-reconcile` gate that checks required files, expected API/UI/runtime surfaces, migrations, generated artifacts, and untracked files with `git status --short -- `. + - For multi-provider changes, reconcile against the scope matrix: every touched provider/package must be classified as `implemented`, `dependency-only`, `intentionally-deferred`, or `not-applicable`, with proof. Do not let "we only bumped the package I remembered" pass this gate. + - For package-release flows, reconcile producer and consumer state: `npm view version`, package manifests, lockfile resolved tarballs/integrities, and `npm ls ` from every consuming workspace. + - For CI failures, map each failing job to its exact local command or documented non-local equivalent. Distinguish similarly named gates (for example handler coverage vs acceptance route coverage) and replay the one that actually failed. - Use `failOnError: false`, then route the captured output to a repair owner. 4. Run repairable validation. - Use capture -> fix -> rerun for typecheck, targeted tests, integration or E2E tests, and regression checks. + - Include exact failing CI commands when available before broader "nearby" checks. A nearby green gate is supporting evidence, not proof that the reported CI failure is fixed. - Red validation output is input for a repair agent, not an immediate workflow failure. - Write `BLOCKED_NO_COMMIT.md` only for true external blockers. @@ -44,6 +49,7 @@ Pair this with `writing-agent-relay-workflows` for SDK syntax and `relay-80-100- 7. Report final signoff. - Write a final `SIGNOFF.md` that includes iteration count, validation evidence, Claude rationale, Codex rationale, remaining risks, and artifact paths. + - Include the final scope matrix with every repository/package/provider row signed off, deferred with owner/date, or marked not applicable. For release flows, include published and consumed versions. - Post the same report to the PR. Resolve the PR from an explicit env var first, then from `gh pr view`. ## Verdict Contract @@ -55,6 +61,7 @@ VERDICT: COMPREHENSIVELY_SATISFIED | FINDINGS | BLOCKED why_passed: required when VERDICT is COMPREHENSIVELY_SATISFIED end_to_end_wiring_verified: required when VERDICT is COMPREHENSIVELY_SATISFIED deterministic_evidence: required when VERDICT is COMPREHENSIVELY_SATISFIED +scope_matrix_verified: required when VERDICT is COMPREHENSIVELY_SATISFIED for cross-repo/provider/package work remaining_risks: required when VERDICT is COMPREHENSIVELY_SATISFIED finding_id: stable-id when VERDICT is FINDINGS severity: blocker | high | medium | low @@ -70,8 +77,35 @@ A deterministic dual-signoff gate should require: - both review files contain `VERDICT: COMPREHENSIVELY_SATISFIED` - neither review file contains `VERDICT: FINDINGS`, `VERDICT: BLOCKED`, or an open `finding_id` - both review files include the required pass-rationale fields +- for cross-repo/provider/package work, both review files include `scope_matrix_verified:` and cite the matrix artifact - the latest final acceptance artifact is green +## Scope Matrix + +Create a machine-readable and human-readable matrix before the first fix pass for work that spans repositories, packages, providers, or CI gates. Keep it updated every iteration. + +Recommended columns: + +```text +repo | branch | PR | package/provider/surface | expected change | producer version | consumer version | files expected | gates required | status | evidence | owner +``` + +Use the matrix to prevent "last-mile" omissions: + +- A package published from one repo must have a matching consumer row in every repo that should install it. +- A provider touched in adapter code must have Cloud ingest/write/digest/writeback/dependency rows, or an explicit not-applicable rationale. +- A route or API surface with both runtime tests and coverage metadata must list both gates separately. +- Untracked generated artifacts must be classified as expected workflow artifacts, ignored local output, or unexpected drift before commit. + +Example package-consumption evidence: + +```bash +npm view @scope/pkg version +rg -n '"@scope/pkg"' package.json package-lock.json packages -g package.json -g package-lock.json +npm ls @scope/pkg --workspace +node -e 'const lock=require("./package-lock.json"); console.log(lock.packages["node_modules/@scope/pkg"].version)' +``` + ## Fresh Context Implementation Prefer an outer loop that starts a new Agent Relay workflow run per iteration: