feat(agents): add finding-triage, a read-only PR-comment checker

.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
     {
       "name": "dev-workflow",
       "source": "./plugins/dev-workflow",
-      "description": "Intake + harden-finding skills, PR-review processor, Codex gate hook, and /workflow-init to scaffold a project."
+      "description": "Intake + harden-finding skills, PR-review processor with fresh-context finding triage, Codex gate hook, and /workflow-init to scaffold a project."
     }
   ]
 }

AGENTS.md

@@ -12,8 +12,9 @@ design at Gate A and the diff at Gate B), a fingerprinted hardening ledger where
 recurring finding escalates one rung harder (prose → lint → type → test), and one
 repo-enforced quality command. Users are developers running Claude Code.
 
-**The product is prompts.** Skills, slash commands, hook reminder messages and every
-template `/workflow-init` scaffolds are the deliverable — plus one POSIX-shell hook.
+**The product is prompts.** Skills, slash commands, agent definitions, hook reminder
+messages and every template `/workflow-init` scaffolds are the deliverable — plus one
+POSIX-shell hook.
 There is no application code, so there is no typechecker to catch a defect; review and
 `docs/prompt-standards.md` are the only gates a prompt passes through.
 
@@ -38,6 +39,7 @@ scripts/check-invariants.test.sh  # its regression suite — reject/accept pairs
 plugins/dev-workflow/
   .claude-plugin/plugin.json      # metadata only — no component keys (invariant 6)
   skills/{intake,harden-finding}/SKILL.md
+  agents/finding-triage.md        # read-only PR-comment checker (convention-loaded)
   commands/{workflow-init,process-pr-review}.md
   hooks/{hooks.json,codex-gate.sh,codex-gate.test.sh}
   examples/                       # read, don't install — one stack's answers
@@ -52,7 +54,7 @@ docs/
 source-files/                     # the extraction seed this repo was built from
 ```
 
-**Boundaries.** `skills/`, `commands/` and `hooks/hooks.json` are loaded by convention
+**Boundaries.** `skills/`, `commands/`, `agents/` and `hooks/hooks.json` are loaded by convention
 from their paths. The executable artifacts are the hook and its test, plus
 `scripts/check-invariants.sh` and its test (the hook ships in the plugin; the checker
 is repo-local CI); everything else is text
@@ -104,7 +106,7 @@ reader can judge whether it still holds.
    prerequisite plugins (superpowers, this kit) are addressed by name and revalidated
    on update, not pinned.
 6. **The manifest never re-declares convention-loaded components.** `skills/`,
-   `commands/` and `hooks/hooks.json` load automatically; a manifest key for them is
+   `commands/`, `agents/` and `hooks/hooks.json` load automatically; a manifest key for them is
    redundant at best and fatal for hooks (duplicate-hooks error → the plugin does not
    load at all; fixed in 0.2.1). Manifest keys only for files outside convention paths.
 7. **`examples/` is read-only reference.** Never installed, never copied by a command,
@@ -125,7 +127,7 @@ reader can judge whether it still holds.
     `docs/hardening-taxonomy.md`, never into the `harden-finding` skill. Otherwise one
     project leaks into every other.
 11. **Prompt changes pass `docs/prompt-standards.md`** — all 11 checklist items, for
-    any skill, command, hook message, or scaffolded template. The prompts are the
+    any skill, command, agent definition, hook message, or scaffolded template. The prompts are the
     product and nothing mechanical checks them.
 
 ## Don'ts

CLAUDE.md

@@ -121,8 +121,8 @@ advisory — validate before applying; dismissed finding → one-line why.
   not because some earlier gate covered them (Gate A runs on specs and plans,
   which a README edit doesn't have). **Prompts are not prose:** `CLAUDE.md` and
   `AGENTS.md` themselves, and anything under a `.claude/`, `plugins/`, `skills/` or
-  `commands/` directory **at any depth** — skills, commands, hook reminder text,
-  inline templates — are the product (@AGENTS.md, "What this project is"), so they
+  `commands/` directory **at any depth** — skills, commands, agent definitions, hook
+  reminder text, inline templates — are the product (@AGENTS.md, "What this project is"), so they
   fire full Gate B even though they are `.md`. So does any mixed commit, and any
   non-`.md` file. The hook classifies paths the same way, matching those directory
   names at any depth on purpose: root-level `skills/` and a monorepo's

README.md

@@ -21,6 +21,7 @@ Why each of these, and how to adapt them: [`docs/coding-workflow.md`](docs/codin
 | `dev-workflow:intake` | skill — a raw idea or voice transcript (German or English) becomes a reviewable story. Captures WHAT and WHY; refuses to invent the parts that aren't there. |
 | `dev-workflow:harden-finding` | skill — one review finding becomes a lint rule, type constraint, test, or documented convention, at the right rung, recorded in the ledger. |
 | `/dev-workflow:process-pr-review` | command — validates PR bot comments against the code and your invariants, replies to each, fixes regressions, tracks pre-existing issues. |
+| `dev-workflow:finding-triage` | agent — read-only, fresh context, judges whether one PR-bot claim is actually true of the code. Used by the PR processor; never counts as a review gate. |
 | `/dev-workflow:workflow-init` | command — scaffolds the per-project files, then interviews you to write `AGENTS.md`. |
 | codex-gate hook | non-blocking reminders that count Gate A and Gate B passes, and verify a Gate-B review against the actual content of the working tree. Always exits 0. |
 

docs/architecture.md

@@ -19,6 +19,7 @@ scripts/check-invariants.sh       # invariants 5 and 6, mechanically (+ .test.sh
 plugins/dev-workflow/
   .claude-plugin/plugin.json
   skills/{intake,harden-finding}/SKILL.md
+  agents/finding-triage.md
   commands/{workflow-init,process-pr-review}.md
   hooks/{hooks.json,codex-gate.sh,codex-gate.test.sh}
   examples/                       # read, don't install — one stack's answers
@@ -27,7 +28,7 @@ docs/{hardening-log,hardening-taxonomy,pr-review-bots}.md
 source-files/                     # the extraction seed this repo was built from
 ```
 
-The plugin manifest declares no components at all: `skills/`, `commands/` and
+The plugin manifest declares no components at all: `skills/`, `commands/`, `agents/` and
 `hooks/hooks.json` are each discovered by convention from their paths, so naming any of
 them again would be two sources of truth for the same fact. For hooks it is worse than
 redundant — a `hooks` manifest key alongside the convention-loaded file is a

docs/coding-workflow.md

@@ -68,7 +68,7 @@ run, a diff, a log line.
 ### The pipeline, stage by stage
 
 Why each stage exists, tool-agnostically. For the *how* — one feature walked through
-the actual skills, commands, and hook messages of this plugin — see
+the actual skills, commands, agent definitions, and hook messages of this plugin — see
 [`getting-started.md`](getting-started.md); it is not repeated here.
 
 **1. Intake — from idea to story.** The front door turns a raw idea into a scoped

docs/getting-started.md

@@ -49,8 +49,12 @@ the WIP via `git commit --amend`.
 
 **8. PR and bots.** Open the PR as usual; once the bots have commented, run
 `/dev-workflow:process-pr-review`. Every comment is validated against code and
-invariants, answered on the thread, and — if accepted — fixed (substantial fixes go
-through Gate B again). Nothing silently ignored, nothing blindly applied.
+invariants — usually by a fresh-context `dev-workflow:finding-triage` subagent per claim,
+so the agent that formed a belief is not the one grading it; on a PR that edits
+instruction files the command checks them itself instead, and says so. Triage judges only
+whether a claim is *true*; the command then decides separately whether fixing it belongs
+in this PR. Each comment is answered on the thread, and, if accepted and actionable, fixed (substantial fixes go through Gate B
+again). Nothing silently ignored, nothing blindly applied.
 
 **9. Close the class, not the instance.** Any finding from steps 3, 7, or 8 that
 could recur: run `harden-finding`. It becomes the strongest durable guard that

docs/prompt-standards.md

@@ -1,7 +1,8 @@
 # Prompt Standards
 
 This repository ships prompts. The skills (`plugins/dev-workflow/skills/`), the slash
-commands (`plugins/dev-workflow/commands/`), the hook's reminder messages
+commands (`plugins/dev-workflow/commands/`), the agent definitions
+(`plugins/dev-workflow/agents/`), the hook's reminder messages
 (`plugins/dev-workflow/hooks/codex-gate.sh`), and every template `/workflow-init`
 writes are all prompt artifacts — they are the product, not documentation of it.
 
@@ -99,8 +100,9 @@ Recurring prompt-quality findings follow the same ladder as code findings: prose
 → checklist item here → template change. Prompts are artifacts; `harden-finding`
 treats them like code (rung `P`).
 
-Note the reflexive case: a prompt-quality defect found in *this repo's* skills or
-commands is a defect in the shipped product, and hardening it means changing the
+Note the reflexive case: a prompt-quality defect found in *this repo's* skills,
+commands, agent definitions, hook messages or scaffolded templates is a defect in the
+shipped product, and hardening it means changing the
 plugin — which every downstream project then inherits on update.
 
 ## Revalidation