chore: extract /pr-review-* agents into .agents/personas/#682
Draft
0xbulma wants to merge 1 commit into
Draft
Conversation
…ase-security Extracts the seven inline review-agent specs from `.agents/lib/pr-review-base.md` into one-file-per-persona under `.agents/personas/`, then collapses Step 5 to a short loop over those files. Pure refactor for the baseline seven: their bodies are copied verbatim (modulo frontmatter), and `pr-review-base.md` shrinks from 271 lines to 196. Adds one new conditional persona, `ci-release-security`, which fires when `<HAS_CI_RELEASE>` is true (diff touches `.github/workflows/**`, `.changeset/**`, `pnpm-lock.yaml`, `.npmrc`, or publish-flow scripts). Covers GitHub Actions workflow injection, action pinning, permissions scopes, secret exposure, publish-flow integrity, lockfile drift. Step 4 grows flag detection for `<HAS_CI_RELEASE>`. The output contract adds `<TOTAL_AGENTS_LAUNCHED>` so the caller's failed-agent report phrases correctly when conditional personas do not fire. Root `AGENTS.md` gets a short pointer to `.agents/personas/` as the canonical inventory of review personas. No new engineering rules. No published package source touched — no changeset needed per CLAUDE.md §7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5 tasks
0xbulma
added a commit
that referenced
this pull request
May 19, 2026
* chore: split /pr-review-* agents into .agents/personas/ + add ci-release-security Extracts the seven inline review-agent specs from `.agents/lib/pr-review-base.md` into one-file-per-persona under `.agents/personas/`, then collapses Step 5 to a short loop over those files. Pure refactor for the baseline seven: their bodies are copied verbatim (modulo frontmatter), and `pr-review-base.md` shrinks from 271 lines to 196. Adds one new conditional persona, `ci-release-security`, which fires when `<HAS_CI_RELEASE>` is true (diff touches `.github/workflows/**`, `.changeset/**`, `pnpm-lock.yaml`, `.npmrc`, or publish-flow scripts). Covers GitHub Actions workflow injection, action pinning, permissions scopes, secret exposure, publish-flow integrity, lockfile drift. Step 4 grows flag detection for `<HAS_CI_RELEASE>`. The output contract adds `<TOTAL_AGENTS_LAUNCHED>` so the caller's failed-agent report phrases correctly when conditional personas do not fire. Root `AGENTS.md` gets a short pointer to `.agents/personas/` as the canonical inventory of review personas. No new engineering rules. No published package source touched — no changeset needed per CLAUDE.md §7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: anchor personas to AGENTS.md sections + expand documentation scope Tightens the spec↔persona relationship four ways: 1. Documentation persona now covers Markdown docs and pointer integrity in addition to JSDoc on exports. Validates: stale prose, out-of-sync inventories, cross-doc consistency, internal Markdown link resolution, path references in prose, frontmatter pointers, rename cascade (old paths surviving in other docs), AGENTS.md ↔ persona backlink consistency. 2. AGENTS.md gains §10 "Review automation & CI/release security": the canonical persona inventory plus the source-of-truth rules that ci-release-security enforces (workflow injection, action pinning, permissions scopes, secret exposure, publish-flow integrity, lockfile drift, dependency hygiene, .npmrc hardening). The persona referenced these rules but they were not codified anywhere — now they live in one place and the persona points at the section. 3. Each AGENTS.md §3–8 ends with a `> Applied by personas: …` callout so a rule-author can navigate from rule to enforcer. Pairs with the personas' new `applies:` frontmatter (next item). 4. Persona frontmatter adds `applies:` (AGENTS.md section anchor) and `out-of-scope:` (boundary against neighbor personas) to all eight personas. Documents the scope contract and reduces overlap drift between code-quality / silent-failure-hunter / module-api-architecture / style-conventions. The temporary "Review personas" callout from #682 is replaced by a one-line pointer to §10. No published package source touched — no changeset per CLAUDE.md §7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: dedupe personas vs AGENTS.md; update test-coverage for colocation Audit-driven cleanup of the documentation architecture surfaced by the last review. Five fixes: 1. test-coverage persona now enforces AGENTS.md §5 colocation (src/Foo.ts ↔ src/Foo.test.ts) instead of describing the obsolete `packages/<pkg>/test/` layout. Captures the dual-layout coexistence rule (colocation wired only in morpho-sdk + evm-simulation today; moving tests in non-wired packages silently skips them) and the *.integration.test.ts naming for fork-bound tests that stay. The incoming TIB-2026-04-27 (PR #596) extends the migration; the rule stays anchored in AGENTS.md §5. 2. module-api-architecture persona: replaced verbatim restatements of AGENTS.md §1/§3/§4/§8 rules (8 bullets) with section pointers and crisp application points. Out-of-scope boundary tightened. 3. style-conventions persona: same fix — replaced verbatim §3/§8 restatements with pointers. Scope sharpened to "mechanical-style enforcement + changeset relevance". 4. code-quality persona: narrowed `applies:` from §1/§3 to §2/§3 so the "Error handling and edge cases" bullet (which overlapped silent-failure-hunter) is replaced by §2's typed-error rule. silent-failure-hunter updated in lock-step: it owns the *depth* of error handling; code-quality owns the *existence* of the typed class. 5. CONTRIBUTING.md: trimmed the duplicated "Code Style" and "Changesets" sections to brief pointers at AGENTS.md §7/§8. The detailed rules live in one place now. Plus housekeeping: - AGENTS.md §10 gains an "Orchestration" sub-table for the three command skills + the shared base, so .agents/lib/pr-review-base.md is discoverable from the inventory. - docs/tibs/TEMPLATE.md footer: removed dangling reference to a non-existent TIB-2026-04-08; added explicit notes that TIBs are proposals feeding into AGENTS.md (not authoritative themselves) and that the repo uses two ID formats (sequential for older TIBs, CalVer for new). No published package source touched — no changeset per CLAUDE.md §7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: clarify @morpho-org/test/mock is incoming via TIB-2026-04-27 The test-coverage persona referenced `@morpho-org/test/mock` as if it already shipped on main, but the sub-export lands with the still-open TIB-2026-04-27 (PR #596). Caught by self-applying the documentation persona's pointer-integrity rule. Softened to "lands with TIB-2026-04-27" / "once TIB-2026-04-27 lands" so the persona is accurate against current main and self-corrects when the TIB merges. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: sharpen web3-security persona + codify release-signing rule Two follow-ups to the architecture refactor. 1. **web3-security persona** rewritten to the new structure (matching what code-quality / silent-failure-hunter / module-api-architecture / style-conventions / test-coverage already use). Was the last persona still in the old "Prompt must include:" bullet-list format. New shape: anchored to AGENTS.md §1 (Action-layer purity) and §2 (chainId validation as a security invariant). Tightened `out-of-scope` boundary against code-quality (which owns generic security primitives per §2) and silent-failure-hunter (which owns generic error swallowing; this persona owns Web3-specific failed-tx surfacing). Structured What-to-flag sections (contract interaction shape, transaction parameter integrity, wallet + chain handling, permit / typed-data, token approvals, race conditions, Action-layer purity) with calibrated severity guidance for this domain. 2. **AGENTS.md §10 + ci-release-security persona** gain a new "Release-commit signing & write-token hardening" rule reflecting the patterns landing in PR #673 (release-bot signing hardening): GitHub- signed identity via `createCommitOnBranch` GraphQL mutation (not local `git commit`); checksum and `$PATH` verification of trusted helpers before minting write-scoped tokens; truncation of `$GITHUB_ENV` / `$GITHUB_PATH` immediately before the privileged step; `.git/hooks/` validated as containing only `*.sample` files; forced trusted `$PATH` and explicit `RELEASE_BRANCH` guard on the write-token step. The rule lives in §10 as source of truth; the persona references it as an anchor. No published package source touched — no changeset per CLAUDE.md §7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: self-applied /pr-review-local --fix findings Ran the persona-powered /pr-review-local on this branch (8 personas, all baseline + ci-release-security since HAS_CI_RELEASE=true). The expanded documentation persona caught 7 cross-doc consistency drifts on its own author's PR — exactly the kind of finding the persona is designed for. Aggregated to 6 after dedup (two web3-security findings on adjacent lines merged — same root cause). Applied: 1. AGENTS.md §1 (Architecture) — added missing `> Applied by personas:` backlink. Three personas had `applies: §1` in frontmatter but the section had no callout linking back. 2. AGENTS.md §2 (Forbidden patterns) — same fix; added missing backlink for code-quality, web3-security, silent-failure-hunter with per-rule attributions. 3. AGENTS.md §10 inventory: `code-quality` row had Anchors `§1, §3`, but the persona's frontmatter and body cite `§2, §3`. Fixed to `§2, §3`. 4. web3-security persona was citing AGENTS.md §2 for the chainId- validation rule, but that invariant is enumerated in §5 (security invariants list). Re-attributed: - frontmatter `applies:` now also names §5 - intro paragraph updated - "Missing chainId validation" body bullet cites §5 AGENTS.md §5 backlink updated to list web3-security alongside test-coverage. AGENTS.md §10 table row also updated to add §5. 5. .agents/lib/pr-review-base.md persona inventory was describing the documentation persona too narrowly ("JSDoc on public exports per docs/jsdoc-style.md") relative to AGENTS.md §10's expanded description. Updated to match. 6. AGENTS.md §10 conditional persona table: <HAS_CI_RELEASE> trigger description was missing the `package.json` `scripts.*publish*` clause. Added, plus a pointer to pr-review-base.md as canonical detector. All 6 are mechanical cross-doc consistency fixes; no rules changed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: address relevant PR review findings (5 of 7 threads) Triaged 7 unresolved threads from Codex + Devin with the 'only if relevant' lens. Applied 5 fixes targeting real drift introduced by this PR; skipped 1 out-of-scope behavior change; 1 was already addressed. Applied: 1. Caller files hardcoded 'of 7 agents' (9 occurrences across pr-review-{ci,gh,local}.md) — broken now that <TOTAL_AGENTS_LAUNCHED> is dynamic (8+ when conditional personas fire). Replaced with '<TOTAL_AGENTS_LAUNCHED>'. 2. module-api-architecture persona's `applies:` was missing §3 even though the body extensively enforces §3 type-discipline rules at the boundary. Added §3 to the frontmatter and to the AGENTS.md §10 inventory row. 3. AGENTS.md §4 backlink listed style-conventions, but that persona covers Biome mechanics + changesets (§7, §8) — not §4 public-API packaging. Dropped it from the §4 callout. 4. test-coverage persona recommended mocked transport-level tests as 'preferred', contradicting AGENTS.md §5 ('No mocked viem clients on RPC paths') because TIB-2026-04-27 has not landed yet. Reworded to defer to §5 forks today, and clearly mark mock support as gated on TIB acceptance. Skipped: - Codex P2 'Trigger CI persona for dependency edits': would broaden <HAS_CI_RELEASE> to fire on any package.json dep edit. Legitimate scenario but a substantive behavior change beyond this PR's doc-architecture scope, and would flood with no-op runs on every dep bump. Better as a follow-up that also reviews the trigger surface holistically. Already addressed: - Devin '§1 and §2 have no Applied by personas callouts': fixed in commit d734a65 (the self-applied /pr-review-local --fix pass). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(pr-fix): point at AGENTS.md §10 + persona-backlink invariant Two targeted additions to /pr-fix's Step 6a project-context reading, catching the gaps that the audit surfaced: 1. CI / release files — when the fix touches .github/workflows/**, .github/actions/**, .changeset/**, lockfiles, .npmrc, or a package.json publish/release script, AGENTS.md §10 is the source-of-truth rule set. The ci-release-security persona enforces these at review time; the same rules govern a fix's correctness. 2. Persona / spec-layering files — when the fix touches AGENTS.md or any file under .agents/personas/, the bidirectional-backlink invariant from the documentation persona applies: every persona's `applies:` frontmatter must match the corresponding `> Applied by personas:` callout in AGENTS.md, and vice versa. A fix to one side must atomically update the other. Both rules were already inherited implicitly via Step 6a's "read root AGENTS.md" line, but making them explicit prevents drift and signals to the fix-applier when a one-side change is incomplete. No published package source touched — no changeset per CLAUDE.md §7. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
.agents/lib/pr-review-base.mdembedded seven review-agent specs inline (~270 lines for Agent 1 through Agent 7). That made the base file hard to scan, prevented other future skills from reusing a persona without copy-paste, and left rootAGENTS.mdwith no visible inventory of how PRs get reviewed.Separately, our CI / release / supply-chain surface (workflows, lockfiles,
.npmrc, publish scripts) had no dedicated review eyes — workflow-injection patterns, floating action tags, and lockfile drift could land unnoticed.Solution
Two changes in one PR:
Pure refactor — extract the seven inline agent sections from
pr-review-base.mdinto one-file-per-persona under.agents/personas/. Bodies are copied verbatim (modulo frontmatter).pr-review-base.mdStep 5 collapses to a short loop over those files. Caller files (/pr-review-{ci,gh,local}) are unchanged.pr-review-base.mddrops from 271 → 196 lines.New conditional persona
ci-release-security.md— fires when<HAS_CI_RELEASE>is true (diff touches.github/workflows/**,.github/actions/**,.changeset/**,pnpm-lock.yaml,pnpm-workspace.yaml,.npmrc, or any file withnpm publish/pnpm publish/changeset publish/gh release create). Reviews: workflow injection (${{ github.event.* }}inrun:blocks), action pinning (SHA vs floating tag), workflowpermissions:scopes, secret exposure, publish-flow integrity (--provenance, registry scope, gating), Changesets config changes, lockfile drift, dependency hygiene (typosquats,postinstallscripts, unpinned ranges),.npmrcsettings.Supporting wiring:
pr-review-base.mdgains a flag-detection bullet for<HAS_CI_RELEASE>and prints the value alongside context files.<TOTAL_AGENTS_LAUNCHED>so the caller's<FAILED_AGENTS> of <TOTAL>report phrases correctly when conditional personas don't fire.AGENTS.mdgets a short pointer paragraph (next to the existing Enforcement note) enumerating baseline vs conditional personas. No new engineering rules.Scope discipline
CLAUDE.md§7.AGENTS.md— pointer only, sits beside the existing Enforcement note./pr-review-{ci,gh,local},/pr-fix, etc.) untouched.Test plan
grep -c '### Agent ' .agents/lib/pr-review-base.mdreturns 0 (was 7).wc -l .agents/lib/pr-review-base.mdshows the file shrunk (~196 lines)./pr-review-localon a small TS-only branch — confirm the 7 baseline personas fire,<HAS_CI_RELEASE>=false,<TOTAL_AGENTS_LAUNCHED>=7, finding shapes unchanged./pr-review-localon a branch touching.github/workflows/*.yml— confirmci-release-securityfires,<HAS_CI_RELEASE>=true,<TOTAL_AGENTS_LAUNCHED>=8.run: echo "${{ github.event.pull_request.title }}") and confirmci-release-securityflags it as critical.uses: actions/checkout@v4) and confirm flagged as high.🤖 Generated with Claude Code