[KingInYellow18]

Adds /docs:review for multi-persona review of planning documents (PRDs, brainstorms, specs, ADRs). 6 always-applicable personas plus 1 conditional adversarial reviewer. All read-only (tools: Read/Grep/Glob), adapted from upstream compound-engineering v3.3.2 at locked SHA e5b397c9d1883354f03e338dd00f98be3da39f9f.

New agents/review/ directory (auto-discovered): coherence, design-lens, feasibility, product-lens, scope-guardian, security-lens, adversarial-document reviewers. Bash stripped per review-agent read-only contract.

Orchestrator command mirrors yellow-review's Wave 2 pattern: optional learnings pre-pass, parallel persona dispatch, confidence-rubric aggregation (suppress < 75 except safe-auto and P0 escapes), optional safe-auto application, optional compound hand-off.

Closes Wave 3 #2 from the EveryInc merge plan.

Summary

Stack context

Test plan

Notes for reviewers

Greptile Summary

Adds /docs:review, a multi-persona planning-document review command that dispatches 6 always-applicable agents (coherence, design-lens, feasibility, product-lens, scope-guardian, security-lens) plus a conditional adversarial reviewer in parallel, aggregates results through a confidence-rubric gate (< 75 suppressed), and offers optional safe-auto application and compound hand-off. Several P1 issues flagged in the previous review round have been addressed — the \\bauth\\b regex now enumerates authentication and authorization explicitly, the adversarial gate condition uses > 5 (not >= 5), and the learnings pre-pass correctly references yellow-core.

• New command docs:review with path-containment, symlink, and prompt-injection guards throughout.
• 7 new persona agents under agents/review/, all read-only (Read/Grep/Glob), each with distinct scope, confidence calibration, and a yellow-docs compact-return JSON schema.
• CLAUDE.md and README.md updated with accurate agent/command counts and a new "When to Use" entry.

Confidence Score: 5/5

Safe to merge; all previously flagged blocking issues are resolved in this diff.

The orchestrator command and all 7 persona agents are new files with no regressions. The three findings from the prior review round — the auth-regex gap, the requirement-count threshold mismatch, and the plugin-name mismatch in the learnings pre-pass — are all corrected in the current diff. The remaining open item (the unreachable "quick" depth arm for the adversarial agent when requirement count is the sole trigger) was already surfaced in the previous round and represents a minor behavioral edge case rather than a hard failure.

plugins/yellow-docs/commands/docs/review.md — the grep -E risk-signal pattern uses \s+ which is not portable to macOS/BSD; the unreachable "quick" depth assignment for the adversarial reviewer (when REQ_COUNT > 5 is the sole trigger) is still unresolved from the previous review round.

Important Files Changed

Filename	Overview
plugins/yellow-docs/commands/docs/review.md	New orchestrator command; previously-flagged P1s (auth regex, REQ_COUNT threshold, plugin name mismatch) all fixed; one P2 grep portability issue remains (\s+ in ERE pattern); unreachable "quick" depth arm still present (previously flagged)
plugins/yellow-docs/agents/review/adversarial-document-reviewer.md	Conditional adversarial persona with first-match-wins depth calibration; security injection guard present; premise-challenging instruction reads correctly (not inverted as in previous review round); confidence caps documented
plugins/yellow-docs/agents/review/coherence-reviewer.md	Clean coherence persona; safe-auto patterns well-defined; confidence rubric, exclusion list, and output schema all consistent with yellow-docs contract
plugins/yellow-docs/agents/review/security-lens-reviewer.md	Plan-level security persona covering attack surface, auth/authz, data exposure, third-party boundaries, secrets, and a lightweight threat model; prompt-injection guard present
plugins/yellow-docs/agents/review/product-lens-reviewer.md	Product-lens persona with internal/external product context calibration; premise challenge always runs first; confidence caps at 75 for premise critiques documented
plugins/yellow-docs/agents/review/feasibility-reviewer.md	Shadow path tracing (happy/nil/empty/error) and architecture-reality checks; brownfield vs greenfield distinction; clean output schema
plugins/yellow-docs/agents/review/design-lens-reviewer.md	Dimensional 0-10 rating system; AI slop check; only emits findings at 7/10 or below; prompt-injection guard present
plugins/yellow-docs/agents/review/scope-guardian-reviewer.md	Right-sizing and abstraction-justification persona; priority dependency analysis (upward P0→P2 detection); completeness principle for AI-assisted implementation contexts
.changeset/yellow-docs-doc-review.md	Accurate minor-version changeset; agent count, command count, and upstream SHA all consistent with added files
plugins/yellow-docs/CLAUDE.md	CLAUDE.md updated to reflect agents 3→10, commands 5→6, new Review agent table; "When to Use" row added correctly
plugins/yellow-docs/README.md	README updated with new command row and full 3-section agent table; agent count and descriptions match agent files

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["fa:fa-file /docs:review path"] --> B["Step 1: Validate path\n(containment + symlink check)"]
    B --> C["Step 2: Estimate size + risk\n(WORD_COUNT, REQ_COUNT, RISK_HITS)"]
    C --> D{"yellow-core\ninstalled?"}
    D -- yes --> E["Step 3: learnings-researcher\npre-pass (sequential)"]
    D -- no --> F["Step 4: Dispatch 6 personas\nin parallel"]
    E --> F
    F --> G["coherence-reviewer"]
    F --> H["design-lens-reviewer"]
    F --> I["feasibility-reviewer"]
    F --> J["product-lens-reviewer"]
    F --> K["scope-guardian-reviewer"]
    F --> L["security-lens-reviewer"]
    C --> M{"WORD_COUNT>1000\nOR REQ_COUNT>5\nOR RISK_HITS>=1?"}
    M -- yes --> N["adversarial-document-reviewer\n(depth: quick/standard/deep)"]
    M -- no --> O["Skip adversarial"]
    G & H & I & J & K & L & N --> P["Step 5: Wait for all TaskOutput"]
    P --> Q["Step 6: Confidence-rubric gate\n(suppress confidence < 75)"]
    Q --> R["Step 7: Render report"]
    R --> S{"safe_auto\nfindings?"}
    S -- yes --> T["Step 8: AskUserQuestion\nApply / Review / Skip"]
    S -- no --> U["Step 9: Offer compound"]
    T --> U

Loading

Comments Outside Diff (5)

1. plugins/yellow-docs/commands/docs/review.md, line 1133 (link)

   \bauth\b regex won't match authentication or authorization

   The word-boundary regex \bauth\b matches only the bare abbreviation "auth" — not "authentication", "authorize", or "authorization". A document that spells out "authentication" without the shorthand would score RISK_HITS=0 and bypass adversarial review even though it's a high-stakes security domain. The adversarial reviewer's own risk-signal inventory explicitly lists authentication and authorization as triggers, so the grep pattern diverges from the declared spec.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: plugins/yellow-docs/commands/docs/review.md
   Line: 1133
   
   Comment:
   **`\bauth\b` regex won't match `authentication` or `authorization`**
   
   The word-boundary regex `\bauth\b` matches only the bare abbreviation "auth" — not "authentication", "authorize", or "authorization". A document that spells out "authentication" without the shorthand would score `RISK_HITS=0` and bypass adversarial review even though it's a high-stakes security domain. The adversarial reviewer's own risk-signal inventory explicitly lists `authentication` and `authorization` as triggers, so the grep pattern diverges from the declared spec.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

2. plugins/yellow-docs/commands/docs/review.md, line 1139 (link)

   REQ_COUNT threshold is >= 5, but documentation consistently says "more than 5 requirements"

   The adversarial reviewer's description, the changeset, and CLAUDE.md all state the trigger is "more than 5 requirements" (i.e. > 5), but the bash condition uses >= 5. A document with exactly 5 requirements will invoke adversarial review contrary to the documented contract.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: plugins/yellow-docs/commands/docs/review.md
   Line: 1139
   
   Comment:
   **REQ_COUNT threshold is `>= 5`, but documentation consistently says "more than 5 requirements"**
   
   The adversarial reviewer's description, the changeset, and CLAUDE.md all state the trigger is "more than 5 requirements" (i.e. `> 5`), but the bash condition uses `>= 5`. A document with exactly 5 requirements will invoke adversarial review contrary to the documented contract.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   

3. plugins/yellow-docs/commands/docs/review.md, line 1145-1157 (link)

   Plugin name mismatch: condition checks yellow-research but subagent_type references yellow-core

   Step 3 says "If yellow-research is installed, invoke learnings-researcher..." but the subagent_type is yellow-core:research:learnings-researcher. Claude Code agent discovery resolves the three-segment type against the yellow-core plugin, not yellow-research. The pre-pass silently never runs for any user with only yellow-core installed. Either the guard should read "If yellow-core is installed" or the subagent_type should begin with yellow-research.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: plugins/yellow-docs/commands/docs/review.md
   Line: 1145-1157
   
   Comment:
   **Plugin name mismatch: condition checks `yellow-research` but `subagent_type` references `yellow-core`**
   
   Step 3 says "If yellow-research is installed, invoke `learnings-researcher`..." but the `subagent_type` is `yellow-core:research:learnings-researcher`. Claude Code agent discovery resolves the three-segment type against the `yellow-core` plugin, not `yellow-research`. The pre-pass silently never runs for any user with only yellow-core installed. Either the guard should read "If yellow-core is installed" or the subagent_type should begin with `yellow-research`.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

4. plugins/yellow-docs/agents/review/adversarial-document-reviewer.md, line 222-225 (link)

   Standard-depth premise-challenging instruction has inverted logic

   The instruction reads: "Skip premise challenging when the document contains challengeable premise claims (product-lens signal)." This is backwards — the presence of challengeable premise claims is the exact condition under which premise challenging should be applied. As written, the agent suppresses its primary technique for the documents most in need of it. The apparent intent is to avoid duplicating product-lens's work, but the stated condition achieves the opposite.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: plugins/yellow-docs/agents/review/adversarial-document-reviewer.md
   Line: 222-225
   
   Comment:
   **Standard-depth premise-challenging instruction has inverted logic**
   
   The instruction reads: "Skip premise challenging when the document contains challengeable premise claims (product-lens signal)." This is backwards — the presence of challengeable premise claims is the exact condition under which premise challenging should be applied. As written, the agent suppresses its primary technique for the documents most in need of it. The apparent intent is to avoid duplicating product-lens's work, but the stated condition achieves the opposite.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

5. plugins/yellow-docs/commands/docs/review.md, line 1205-1207 (link)

   Depth assignment creates an unreachable "quick" arm for the adversarial agent

   Step 4 assigns depth = "quick" for documents under 1000 words and no risk signals, but the invocation gate only fires when WORD_COUNT > 1000 OR REQ_COUNT >= 5 OR RISK_HITS >= 1. When REQ_COUNT >= 5 is the sole trigger, the orchestrator passes depth: "quick" but the adversarial agent's own Quick calibration defines that tier as "fewer than 5 requirements" — so the agent would internally reassess to Standard, diverging from the orchestrator-passed value.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: plugins/yellow-docs/commands/docs/review.md
   Line: 1205-1207
   
   Comment:
   **Depth assignment creates an unreachable "quick" arm for the adversarial agent**
   
   Step 4 assigns `depth = "quick"` for documents under 1000 words and no risk signals, but the invocation gate only fires when `WORD_COUNT > 1000` OR `REQ_COUNT >= 5` OR `RISK_HITS >= 1`. When `REQ_COUNT >= 5` is the sole trigger, the orchestrator passes `depth: "quick"` but the adversarial agent's own Quick calibration defines that tier as "fewer than 5 requirements" — so the agent would internally reassess to Standard, diverging from the orchestrator-passed value.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
plugins/yellow-docs/commands/docs/review.md:84
`\s+` is a Perl/PCRE extension — POSIX ERE (`grep -E`) does not define `\s`. GNU grep on Linux silently accepts it, but BSD grep on macOS treats `\s` as a literal `s`, so `external\s+api` would match "externalsapi" instead of "external api". On macOS, this term would never trigger a `RISK_HITS` hit, silently reducing adversarial-review coverage for documents that spell out "external api". A portable replacement is `[[:space:]]`.

```suggestion
RISK_HITS=$(grep -ciE -- '\b(auth|authn|authz|authentication|authorization|payment|billing|migration|compliance|cryptography|crypto|pii|external[[:space:]]+api|secret|credential|token|oauth|jwt)\b' "$FULL_PATH" || true)
```

_{Reviews (6): Last reviewed commit: "fix(yellow-docs): make adversarial-docum..." | Re-trigger Greptile}

[codeant-ai]

User kinginyellow18@proton.me does not have a PR Review subscription.

Go to Team management and add this email to the PR Review subscription.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8d842854-8def-4b5f-b4c7-067b8cfc3201

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/feat/yellow-docs-doc-review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[KingInYellow18]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• docs(operations): post-W3 functional smoke test checklist #412
• feat(yellow-docs): /docs:review command + 7 persona reviewer agents (Wave 3 #2) #410 👈 (View in Graphite)
• feat(yellow-debt): confirm v2.0 schema emission across all 5 scanners (Wave 3 #7) #406
• feat: agent-native-reviewers + authoring skills #403
• chore: complete W2 backbone loose threads #402
• main

---

How to use the Graphite Merge Queue

Add the label graphite-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[codacy-production]

Not up to standards ⛔

🔴 Issues 100 minor

Alerts:
⚠ 100 issues (≤ 0 issues of at least minor severity)

Results:
100 new issues

Category	Results
BestPractice	13 minor
CodeStyle	87 minor

View in Codacy

🟢 Metrics 29 complexity · 8 duplication

Metric	Results
Complexity	29
Duplication	8

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[gemini-code-assist]

Code Review

This pull request introduces the /docs:review command and seven specialized persona-based reviewer agents for multi-perspective analysis of planning documents. The review identified a security vulnerability regarding path traversal in the document path resolution and suggested hardening the grep commands against filenames starting with hyphens.

[qodo-code-review]

ⓘ You've reached your Qodo monthly free-tier limit. Reviews pause until next month — upgrade your plan to continue now, or link your paid account if you already have one.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 64d6f919d8

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[Copilot]

Pull request overview

Adds a new /docs:review workflow to the yellow-docs plugin for multi-persona review of planning documents (PRDs/specs/ADRs/etc.), backed by seven specialized reviewer agents adapted from the upstream compound-engineering snapshot.

Changes:

• Introduces /docs:review orchestrator command to dispatch 6 always-on reviewer personas plus a conditional adversarial reviewer.
• Adds 7 new read-only reviewer agents under plugins/yellow-docs/agents/review/.
• Updates yellow-docs docs (README/CLAUDE) and publishes a minor changeset entry.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
plugins/yellow-docs/README.md	Documents the new /docs:review command and adds a Review agents section/table.
plugins/yellow-docs/commands/docs/review.md	New orchestrator command spec for multi-persona document review (path validation, risk gate, parallel dispatch, aggregation).
plugins/yellow-docs/CLAUDE.md	Updates plugin component inventory and “When to Use” table to include /docs:review and reviewer agents.
plugins/yellow-docs/agents/review/coherence-reviewer.md	Adds coherence-focused reviewer agent (read-only tools).
plugins/yellow-docs/agents/review/design-lens-reviewer.md	Adds design/UX-focused reviewer agent (read-only tools).
plugins/yellow-docs/agents/review/feasibility-reviewer.md	Adds feasibility/architecture-focused reviewer agent (read-only tools).
plugins/yellow-docs/agents/review/product-lens-reviewer.md	Adds product/strategy-focused reviewer agent (read-only tools).
plugins/yellow-docs/agents/review/scope-guardian-reviewer.md	Adds scope/complexity-focused reviewer agent (read-only tools).
plugins/yellow-docs/agents/review/security-lens-reviewer.md	Adds plan-level security reviewer agent (read-only tools).
plugins/yellow-docs/agents/review/adversarial-document-reviewer.md	Adds conditional adversarial reviewer agent (read-only tools).
.changeset/yellow-docs-doc-review.md	Declares a minor version bump and summarizes the new command + agents.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9af9ed2355

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 77d8834750

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 77d8834750

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 77d8834750

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[KingInYellow18]

Merge activity

• May 7, 6:04 AM UTC: The merge label 'graphite-queue' was detected. This PR will be added to the Graphite merge queue once it meets the requirements.
• May 7, 6:09 AM UTC: KingInYellow18 added this pull request to the Graphite merge queue.
• May 7, 6:11 AM UTC: CI is running for this pull request on a draft pull request (#432) due to your merge queue CI optimization settings.
• May 7, 6:11 AM UTC: Merged by the Graphite merge queue via draft PR: #432.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 447341c879

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Escape fence delimiters before embedding document text

The Step 4 fencing pattern injects {document_text} verbatim between --- begin/end document-content --- markers, but it never escapes delimiter strings already present in the document. A malicious or accidental line like --- end document-content --- inside the reviewed file will terminate the fence early and let trailing content be interpreted as live instructions, defeating the prompt-injection containment this command depends on for every persona Task.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: df7420f78c

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Allow edits before offering safe-auto application

When a persona emits autofix_class: safe_auto (for example the new coherence reviewer’s header/count and cross-reference fixes) and the user chooses “Apply all” or “Review each” in Step 8, this command is running with only the tools listed here, which exclude Edit and Write. In tool-restricted runs the workflow can ask for approval but then cannot actually apply the approved safe-auto patch, so either add the edit/write tools or make Step 8 report-only.

Useful? React with 👍 / 👎.