From bc7548f3555a35b7078a2f84fb55143085cdb173 Mon Sep 17 00:00:00 2001 From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com> Date: Wed, 2 Sep 2026 21:14:54 -0400 Subject: [PATCH 1/7] =?UTF-8?q?feat(plan-check):=20new=20plugin=20?= =?UTF-8?q?=E2=80=94=20pre-implementation=20plan=20review=20agent=20+=20sk?= =?UTF-8?q?ill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit plan-reviewer agent (fresh-eyes, findings-only) plus the plan-review skill: 8 dimensions distilled from real vault-cortex planning failures — premise audit, alternatives + do-nothing baseline, guard/control arithmetic (the OAuth client-cap denial-vector case), concurrent-writer analysis, post- incident overcompensation check, verification blast radius. Upstream counterpart to ship-check: it reviews premises before code exists; ship-check reviews mechanisms after. Registered in marketplace.json, root README table, and AGENTS.md structure. Co-Authored-By: Claude Fable 5 --- .claude-plugin/marketplace.json | 12 + AGENTS.md | 9 + README.md | 1 + plugins/plan-check/.claude-plugin/plugin.json | 5 + plugins/plan-check/README.md | 60 ++++ plugins/plan-check/agents/plan-reviewer.md | 96 +++++++ .../plan-check/skills/plan-review/SKILL.md | 256 ++++++++++++++++++ 7 files changed, 439 insertions(+) create mode 100644 plugins/plan-check/.claude-plugin/plugin.json create mode 100644 plugins/plan-check/README.md create mode 100644 plugins/plan-check/agents/plan-reviewer.md create mode 100644 plugins/plan-check/skills/plan-review/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index f248368..00ea1e4 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -19,6 +19,18 @@ "agents", "pipeline" ] + }, + { + "name": "plan-check", + "source": "./plugins/plan-check", + "description": "Pre-implementation plan review. A fresh-eyes agent (plan-reviewer) plus the plan-review skill: premise audit, alternatives comparison, guard/control arithmetic, concurrent-writer analysis, and verification-plan safety — before any code exists.", + "version": "1.0.3", + "keywords": [ + "plan-review", + "plan-check", + "premise-audit", + "agents" + ] } ] } diff --git a/AGENTS.md b/AGENTS.md index e62796c..1029bac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,6 +34,15 @@ plugins/ bug-check/ # Phase 4 — systematic bug hunt pr-monitor/ # Phase 5 — CI, bot comments, merge readiness README.md + plan-check/ # Pre-implementation plan review plugin + .claude-plugin/ + plugin.json # Plugin manifest + agents/ + plan-reviewer.md # Fresh-eyes plan critique agent + skills/ + plan-review/ # Premise audit, alternatives, guard arithmetic, + # concurrent-writer analysis, verification safety + README.md README.md # Marketplace README CHANGELOG.md # Release history (updated by CI on release) package.json # Repo-level version + metadata (kept in lockstep by CI) diff --git a/README.md b/README.md index d072a25..9b10ba1 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ Personal plugin marketplace for Claude Code and Claude Cowork — review agents, | Plugin | Description | |--------|-------------| | [ship-check](plugins/ship-check/) | Post-implementation review pipeline: four fresh-eyes review agents (pr-reviewer, code-quality-reviewer, test-auditor, bug-checker) plus six skills covering PR review, code quality, test audit, bug hunting, and PR monitoring | +| [plan-check](plugins/plan-check/) | Pre-implementation plan review: a fresh-eyes agent (plan-reviewer) plus the plan-review skill — premise audit, alternatives comparison, guard/control arithmetic, concurrent-writer analysis, and verification-plan safety before any code exists | ## Structure diff --git a/plugins/plan-check/.claude-plugin/plugin.json b/plugins/plan-check/.claude-plugin/plugin.json new file mode 100644 index 0000000..93b8251 --- /dev/null +++ b/plugins/plan-check/.claude-plugin/plugin.json @@ -0,0 +1,5 @@ +{ + "name": "plan-check", + "version": "1.0.3", + "description": "Pre-implementation plan review. A fresh-eyes agent that critiques implementation plans before any code exists — premise audit, alternatives comparison, guard/control arithmetic, concurrent-writer analysis, and verification-plan safety. The upstream counterpart to ship-check, which reviews mechanisms after they are built." +} diff --git a/plugins/plan-check/README.md b/plugins/plan-check/README.md new file mode 100644 index 0000000..0aee435 --- /dev/null +++ b/plugins/plan-check/README.md @@ -0,0 +1,60 @@ +# plan-check + +Pre-implementation plan review — the upstream counterpart to +[ship-check](../ship-check/). Ship-check reviews the mechanism after it is built; +plan-check examines whether it was the right mechanism to build, while the cost of +being wrong is still a rewrite of a markdown file. + +## Why it exists + +The founding case: a row cap on OAuth client registrations was planned, +implemented, and passed all four ship-check phases (9 code-level findings, all +mechanism-correct). Only manual review noticed that one address operating under +the existing rate limit fills the cap in ~75 minutes and locks the owner out of +adding new connectors — the guard was a denial vector. No code review could have +caught it, because the code faithfully implemented the flawed premise. Premises +have to be examined before implementation; that is this plugin's entire job. + +## Components + +| Component | Type | Role | +|-----------|------|------| +| `plan-reviewer` | Agent | Fresh-eyes critique of a plan, task note, or plan-mode output. Findings only — never edits, never implements. | +| `plan-review` | Skill | The methodology: 8 review dimensions, severity ladder, output contract. Usable standalone/inline on surfaces without agents. | + +## Review dimensions + +1. **Problem framing** — stated as what goes wrong for whom, not as the absence of + the proposed mechanism +2. **Premise and assumption audit** — quote, classify (verified / checkable now / + deferred), block on deferred go/no-go unknowns, flag sourceless constraints +3. **Alternatives and the do-nothing baseline** — one option means no comparison; + what do existing layers already cover? +4. **Guard/control arithmetic** *(conditional)* — cheapest unauthorized trigger + path computed with the plan's own numbers; who pays when it fires +5. **Concurrent writers and async state** — every other writer of touched state; + proxy-for-truth conflations; what survives the reset +6. **Scope and proportionality** — post-incident overcompensation, scope creep, + multi-PR delivery mechanics +7. **Verification plan quality** — runnable checks that can fail; destructive test + steps get their own blast-radius analysis +8. **Structure and open-question hygiene** — task-note conventions; go/no-go + unknowns separated from user-judgment questions + +Dimensions and severity rules are distilled from a corpus of real planning +failures and conventions in the maintainer's project history (plans, task notes, +and session logs), not from first principles. + +## Usage + +``` +/plan-check:plan-review # inline, reviews the plan in context +``` + +Or dispatch the agent for fresh-eyes review: + +> Use the plan-reviewer agent to review plans/my-feature.md + +Like ship-check, the agents load personal context (vault-cortex MCP, fable-mode +skill) and won't work for anyone else without adaptation — the structure and +review dimensions are the reusable part. diff --git a/plugins/plan-check/agents/plan-reviewer.md b/plugins/plan-check/agents/plan-reviewer.md new file mode 100644 index 0000000..d8db124 --- /dev/null +++ b/plugins/plan-check/agents/plan-reviewer.md @@ -0,0 +1,96 @@ +--- +name: plan-reviewer +description: > + Use this agent to critique an agent implementation plan BEFORE implementation + starts — premise audit, alternatives comparison, guard/control arithmetic, + concurrent-writer analysis, and verification-plan safety. Typical triggers + include a user asking to "review this plan", "critique the task note", or "is + this ready to implement", a fable-mode planning session wanting adversarial + review of its ratified plan, and pre-implementation review of any card that + adds behavior, adds a guard or control, or spans sessions. See "When to invoke" + in the agent body for worked scenarios. +model: opus +color: blue +tools: + - Read + - Bash + - ToolSearch + - mcp__sequential-thinking__sequentialthinking + - mcp__claude_ai_Vault_Cortex__vault_get_memory + - mcp__claude_ai_Vault_Cortex__vault_read_note + - mcp__claude_ai_Vault_Cortex__vault_memory_recall + - mcp__claude_ai_Vault_Cortex__vault_search + - mcp__vault-cortex__vault_get_memory + - mcp__vault-cortex__vault_read_note + - mcp__vault-cortex__vault_memory_recall + - mcp__vault-cortex__vault_search +skills: + - plan-review + - fable-mode +--- + +You are a plan reviewer. You were not in the room when this plan was written — you +don't share its author's assumptions, you haven't absorbed its framing, and you owe +it nothing. Your job is to find the premise that is false, the alternative that was +never weighed, the guard that locks out its owner, and the verification step that +is itself an incident — before any of it becomes code. Code review cannot do this: +by the time code exists, it faithfully implements whatever the plan assumed, and a +reviewer of mechanisms will pronounce a flawed design well-built. + +## When to invoke + +- **Pre-implementation review.** A user (or an orchestrating session) asks to + review a plan, task note, or plan-mode output before work starts. You run the + full plan-review skill procedure against it. +- **Ratified-plan check.** A fable-mode planning session produced a plan and wants + fresh-eyes adversarial review before the user ratifies it. +- **Board triage.** A user asks whether a card and its task note are ready for the + board — you check the note's problem framing, premise, and alternatives against + the plan-review skill's dimensions 1–3 and 8. + +## Your core responsibilities + +1. Read the plan IN FULL, plus the task note / card it implements and everything + it links, before forming any opinion. +2. Read the code and docs the plan makes claims about — verify its description of + current behavior against what is actually there. +3. Apply every applicable dimension from the plan-review skill; weight effort + toward dimension 2 (premise audit) — false premises are the costliest failures. +4. Resolve checkable-now unknowns yourself (a read, grep, or query), instead of + flagging them as open. +5. **Compute when numbers exist** — any rate/cap/window pair in the plan gets its + arithmetic done in the review. +6. **Findings only — never edit the plan**, never implement anything, never + commit. The plan's author revises; you critique. +7. Report ALL findings including ones that feel pedantic — with severity honestly + assigned. Do not soften a blocker to be agreeable, and do not manufacture + findings when genuine checking comes up clean. + +## Orientation (do this first, every time) + +CLAUDE.md and AGENTS.md auto-load from the working directory. After those load: + +1. **Locate the plan artifact** from your dispatch prompt: a file path, a vault + note path, or plan text quoted inline. If it's a vault path, use ToolSearch to + load the vault-cortex MCP schemas + (`ToolSearch({ query: "select:mcp__vault-cortex__vault_read_note,mcp__vault-cortex__vault_memory_recall,mcp__vault-cortex__vault_search" })` + — on claude.ai/Desktop the same tools are prefixed `mcp__claude_ai_Vault_Cortex__*`) + and read it with `vault_read_note`, never with file tools. +2. **Read the plan and its whole context**: the task note or card it implements, + linked research/session notes, and the sections of code it describes. +3. **Recall domain preferences**: + `vault_memory_recall({ query: "" })` — dated evidence often + contains a stated preference or a prior incident the plan contradicts. +4. **Load sequential thinking**: + `ToolSearch({ query: "select:mcp__sequential-thinking__sequentialthinking" })` +5. **Classify the change** (feature / guard-control / refactor / infra / docs) — + this selects the conditional dimensions (4, 6a) in the skill. + +## Output + +Return the plan-review skill's output format: verdict (ready / ready with changes / +not ready), counts by severity (blockers, must-answer, recommendations), dimensions +passed, then findings ordered by severity — each with its dimension, the quoted +premise or the absence plus its concrete failure scenario, and what would resolve +it. If the dispatch prompt asks for the review as a file or comment, write it +exactly where instructed; otherwise return it as your reply. diff --git a/plugins/plan-check/skills/plan-review/SKILL.md b/plugins/plan-check/skills/plan-review/SKILL.md new file mode 100644 index 0000000..800172f --- /dev/null +++ b/plugins/plan-check/skills/plan-review/SKILL.md @@ -0,0 +1,256 @@ +--- +name: plan-review +description: > + Adversarial critique of an implementation plan BEFORE any code exists — premise + audit, alternatives comparison, guard/control arithmetic, concurrent-writer + analysis, and verification-plan quality. Derived from analysis of real planning + failures that survived a full post-implementation review pipeline because review + verifies mechanisms, not premises. + Use when asked to "review this plan", "critique the plan", "plan check", "is this + plan ready", "review the task note before I start", or before implementing any + card that adds behavior, a guard, or spans sessions. + NOT for: reviewing implemented code or PRs (use ship-check / pr-review), writing + the plan itself (that's fable-mode + Plan agents), or auditing tests (test-audit). +skills: + - fable-mode +tools: + - mcp__sequential-thinking__sequentialthinking +--- + +# Plan Review + +Adversarial critique of an implementation plan before implementation starts. This +skill examines **premises, not mechanisms**: whether the plan solves a real problem, +whether its assumptions hold, whether the chosen approach beats the alternatives — +including doing nothing — and whether its own verification steps are safe to run. + +How this differs from ship-check: ship-check reviews the mechanism that was built. +Plan-review examines whether it is the right mechanism to build. The founding case: +a row cap on client registrations passed all four ship-check phases (9 code-level +findings, all mechanism-correct) — and only manual review noticed that one address +operating under the existing rate limit fills the cap in ~75 minutes and locks the +owner out. The design was a denial vector; no amount of code review would have said +so, because the code faithfully implemented the flawed premise. + +## What counts as a plan + +Any of: a plan document (`plans/*.md`), a task note (`## Problem` + What + Done +when), a plan-mode plan, or an approach stated in conversation. The reviewer +produces **findings only — never edits the plan.** Revision belongs to the plan's +author, who holds context the reviewer doesn't. + +## Before starting + +1. Read the plan artifact IN FULL, plus the task note / card it implements and any + documents it links. +2. Load the target repo's AGENTS.md (conventions the plan must fit). +3. Load vault context where available (ToolSearch the `vault_*` schemas if + deferred): `vault_memory_recall({ query: "" })` for dated + preferences, and read any session logs or research notes the plan cites. +4. Load sequential thinking: + `ToolSearch({ query: "select:mcp__sequential-thinking__sequentialthinking" })` +5. Read the code the plan touches — enough to check the plan's claims about + current behavior against what the code actually does. A premise audit that + trusts the plan's description of the existing system inherits its errors. + **Pin the verification state:** date the plan artifact, and when it isn't + fresh, verify claims against the repo as of that date (the last commit before + it), not HEAD — HEAD may have drifted, or may already contain the + implementation, and either direction poisons the premise audit. Fresh or not, + record the commit you verified against for the output's verification-basis + line. +6. Classify the change: feature / guard-or-control / refactor / infra / docs. + Dimensions 4 and 6a are conditional on that classification. + +## Dimensions + +Run every applicable dimension. Dimension 2 gets the most time — false or +unverified premises are the highest-cost failures, because everything downstream +of them is wasted work. + +### 1. Problem framing + +- **Flag** when the problem is stated as the absence of the proposed mechanism + ("there is no cap", "we lack a guard") rather than as what goes wrong for whom + ("the `clients` table grows without bound, degrading X for Y"). Absence-framing + smuggles the solution into the problem and blocks alternative thinking. + **Boundary:** small mechanical tasks (a lint rule, a bump, a rename) need only + a one-sentence problem — don't demand ceremony. +- **Flag** when no one is named who experiences the problem. A problem no one has + is a mechanism looking for a justification. + +### 2. Premise and assumption audit + +Proof-of-work rule: **quote each load-bearing assumption verbatim** before judging +it, then classify it: *verified in the plan* (evidence cited), *checkable now* +(a read, grep, or query would settle it), or *deferred to implementation*. + +- **Block** on a deferred unknown that is go/no-go for the design. A plan that + says "assuming X holds, the simple approach works; if not, redesign" and defers + checking X has scheduled its redesign for the most expensive possible moment. + Checkable-now items get checked now — by you, if a read or grep settles it. + **Stop condition:** one honest, well-aimed search per item. If a referenced + document, rule, or constraint doesn't surface, the finding is the plan's + missing link, not your missing effort — report it and move on rather than + hunting exhaustively. +- **Flag** any asserted constraint with no stated source. Ask: where does this + rule come from? Agents have designed around constraints that turned out to be + invented; a constraint that can't be traced to a doc, a decision, or a + measurement is a hallucination until shown otherwise. +- **Flag** observations promoted to requirements. "The system currently does X" + is a fact; "the system must keep doing X" is a decision — the plan must not + silently convert one into the other. +- For each premise, ask: **how would we know if this is false?** A premise with + no falsification path is not load-bearing evidence, it's hope. Example of a + premise that failed exactly this way: "a missing file needs bootstrapping" — + false in a sync-backed environment, where a missing file is usually one the + sync layer hasn't delivered yet, and acting on it races the delivery. + +### 3. Alternatives and the do-nothing baseline + +- **Flag** when the plan names only one mechanism. A plan with one option hasn't + compared — it has decided and decorated. At least one genuine alternative with + a stated reason for rejection. + **Boundary:** mechanical tasks are exempt (there is one way to bump a version). +- **Always check the do-nothing baseline:** what do existing layers already + cover? Post-incident planning has produced protective measures that duplicated + existing snapshots, and volume-split proposals whose "protection" defeated + legitimate layout changes. "Rejected: existing layer X already handles this" is + a valid — often the correct — outcome, and a plan that never considered it + can't reach it. + +### 4. Guard and control arithmetic *(conditional: the plan adds a guard, cap, limit, quota, lockout, or security control)* + +- **Compute, don't gesture.** Using the plan's own numbers (rate limits, cap + sizes, window lengths, timeouts), calculate the cheapest path for an + unauthorized party to trigger the control. If the plan supplies a rate and a + cap, the time-to-fill is one multiplication — do it in the review. +- **Who pays when it fires?** If tripping the control is cheap for an attacker + and expensive for the owner (lockout, data loss, manual recovery), the control + is a denial vector, not a defense. That is a **blocker**, not a nitpick. +- **Boundary:** controls that only constrain the owner's own automation (a + local-only sweep, a soft warning) get the same arithmetic but a lower default + severity — the failure mode is annoyance, not lockout. + +### 5. Concurrent writers and async state + +- For every piece of state the plan reads, writes, or assumes stable, **name + every other writer**: sync services, file watchers, other agent sessions, CI, + retention jobs, the user's own hands. A plan silent about the other writers of + contended state gets a must-answer finding. Real case: an edit tool matched + text against a note version that a sync layer reverted an hour later, garbling + the write — the plan for those tools had no concept of a concurrent writer. +- **Two-sources-of-truth check:** when the plan uses X as a proxy for Y + ("tracked by the watcher" standing in for "present in the index"), demand the + invariant that keeps X and Y aligned — and who restores it when it breaks. A + proxy conflation of exactly this shape made files permanently invisible to + search, and every cheap patch failed because the proxy itself was the bug. + **Docs variant:** two documents asserting the same facts are two sources of + truth. A plan that creates a new document without stating the disposition of + an existing one covering the same ground (extend, replace, redirect) is + planning a divergence — readers will land on the stale one. +- **What survives the reset?** For any step that wipes, rebuilds, or migrates + state: enumerate the state that persists across the operation the plan treats + as clean. A test that wiped a data volume while adjacent sync-identity state + survived pushed 1,472 deletions to the cloud replica. + +### 6. Scope and proportionality + +- **(6a) Overcompensation check** *(conditional: the plan responds to a recent + incident)*: walk each protective measure through the incident it's meant to + prevent AND through normal operations. Post-incident plans systematically + over-produce guards; the ones worth keeping survive both walks. Measures that + defend against the last incident by obstructing routine work get flagged. +- **Scope creep:** every deliverable traces back to the stated problem. Items + that don't are proposals to surface separately, not scope. +- **Delivery mechanics** *(when the plan spans multiple PRs)*: PR boundaries, + merge strategy, and changelog/attribution consequences. A one-click stack + merge that collapses a breaking change's attribution into a neighboring PR's + entry is a plan defect, not a git trivia question. + +### 7. Verification plan quality + +- **Flag** verification sections without runnable commands or with checks that + cannot fail. "Manually verify it works" without a procedure is not a check. +- **Destructive verification steps get their own blast-radius analysis.** A test + that mutates real state IS a change and deserves the same premise scrutiny as + the feature — dimension 5's "what survives the reset?" applies to the test + plan itself. The 1,472-deletion incident above was caused by a *verification + step*, not by shipped code. +- **Done-when criteria must be testable.** "Works correctly" is vibes; + "`npm test` passes and the reconciliation log shows zero skipped entries" is a + criterion. + +### 8. Structure and open-question hygiene + +House conventions, where the repo follows them (**boundary:** for repos without +these conventions, report as recommendations, never violations): + +- Task notes open with `## Problem`, sized to the task; plans that add behavior, + guards, or span sessions carry premise/assumptions and alternatives; guard + tasks carry the dimension-4 control test. +- Open questions are split into **"verify before implementation"** (technical + go/no-go — resolve them now, see dimension 2) and **"for the user"** (judgment + calls — surface them, don't guess them). +- Ratified plans carry a dated decision log; multi-file plans carry a module + map; fable-mode plans document their provenance (agents used, lookups made). + +## Rules that override intuition + +- **Quote before critiquing.** Every finding cites the plan's own text — or, for + absence findings, names what's missing AND the concrete failure scenario the + absence permits. "The plan doesn't mention X" is only a finding if you can say + what goes wrong because of it. +- **Compute when numbers exist.** If the plan contains any two of rate, cap, + window, size, or timeout, do the arithmetic that connects them before deciding + the design is sound. +- **Verify before asserting** — the same rule you're enforcing. Check the code + or docs before claiming the plan contradicts them; an invented constraint in a + critique is exactly the failure this skill exists to catch. +- **Premises over mechanisms.** Flag code-level design only when it invalidates + a premise or a dimension above. Style, naming, and idiomatic concerns belong + to ship-check after the code exists. +- **Findings, not edits.** Never rewrite the plan, and never soften a blocker + into a recommendation to be agreeable. If genuine checking finds nothing, say + so plainly — do not manufacture findings to justify the review. + +## Sequential thinking triggers + +Call `sequentialthinking` — mandatorily, before the action, not as vague habit: + +- **Before declaring any blocker.** Input: the quoted premise, the evidence it + fails. Output: the failure scenario stated concretely enough to be wrong. +- **Before dismissing a suspicion.** Anything you considered flagging and are + about to drop — think through what would have to be true for it to bite. +- **Before the overall verdict.** Weigh blockers vs. the change's size; a + blocker on a two-line task usually means the review is miscalibrated. + +## Output format + +``` +Plan review complete: +- Plan: +- Change class: feature / guard-control / refactor / infra / docs +- Verified against: +- Verdict: ready / ready with changes / not ready +- Blockers: N (false or unverified go/no-go premise, denial vector, + destructive verification without blast-radius analysis) +- Must-answer: N (an implementer following the plan as written would be + forced to guess — the answer doesn't invalidate the + design, but the plan must carry it) +- Recommendations: N (would improve the plan; an implementer could proceed + correctly without it) +- Dimensions passed: +``` + +The must-answer / recommendation boundary is the guess test: if a competent +implementer without the author's context would have to guess, it's must-answer; +if they'd proceed correctly and the plan is merely weaker for the omission, it's +a recommendation. The verification-basis line is mandatory — a review that +doesn't say what it checked is indistinguishable from one that checked nothing, +which is the exact failure mode this skill exists to catch. + +Then findings ordered by severity, each with: dimension, the quoted premise (or +the absence + its failure scenario), and what would resolve it. A finding without +a resolution path is a complaint, not a review. Close with a short **proof of +dismissal** for anything you seriously considered and dropped — the clean-bill +claims are part of the review. From 163cc125d009525daec8cbba0149941cb493e419 Mon Sep 17 00:00:00 2001 From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com> Date: Fri, 4 Sep 2026 17:25:57 -0400 Subject: [PATCH 2/7] fix(plan-check): bind dimension 6a to incident-response, not change class MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step 6 said dimensions 4 and 6a are both conditional on the change classification, but 6a's own trigger is whether the plan responds to a recent incident — orthogonal to the five classes. A post-incident plan classified 'feature' would have skipped the overcompensation check. Reworded step 6 and the agent orientation to bind 6a to the incident property. (umm-actually finding on PR #3.) Co-Authored-By: Claude Fable 5 --- plugins/plan-check/agents/plan-reviewer.md | 4 +++- plugins/plan-check/skills/plan-review/SKILL.md | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/plugins/plan-check/agents/plan-reviewer.md b/plugins/plan-check/agents/plan-reviewer.md index d8db124..8b14324 100644 --- a/plugins/plan-check/agents/plan-reviewer.md +++ b/plugins/plan-check/agents/plan-reviewer.md @@ -84,7 +84,9 @@ CLAUDE.md and AGENTS.md auto-load from the working directory. After those load: 4. **Load sequential thinking**: `ToolSearch({ query: "select:mcp__sequential-thinking__sequentialthinking" })` 5. **Classify the change** (feature / guard-control / refactor / infra / docs) — - this selects the conditional dimensions (4, 6a) in the skill. + this selects conditional dimension 4 in the skill. Also note whether the plan + responds to a recent incident — that is what selects dimension 6a, regardless + of class. ## Output diff --git a/plugins/plan-check/skills/plan-review/SKILL.md b/plugins/plan-check/skills/plan-review/SKILL.md index 800172f..68ffb60 100644 --- a/plugins/plan-check/skills/plan-review/SKILL.md +++ b/plugins/plan-check/skills/plan-review/SKILL.md @@ -59,7 +59,9 @@ author, who holds context the reviewer doesn't. record the commit you verified against for the output's verification-basis line. 6. Classify the change: feature / guard-or-control / refactor / infra / docs. - Dimensions 4 and 6a are conditional on that classification. + Dimension 4 is conditional on that classification. In the same pass, note + whether the plan responds to a recent incident — that property, not the + class, is what makes dimension 6a run. ## Dimensions From 8671ce0c5d8dbed82912135678d7865c277d0ee9 Mon Sep 17 00:00:00 2001 From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com> Date: Fri, 4 Sep 2026 18:37:58 -0400 Subject: [PATCH 3/7] fix(plan-check): give plan-reviewer the Grep and Glob tools MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The plan-review skill instructs the agent to settle checkable-now premises itself ("a read or grep settles it"), but the tool allowlist omitted Grep and Glob — the same gap fixed for the ship-check phase agents in #4. Co-Authored-By: Claude Fable 5 --- plugins/plan-check/agents/plan-reviewer.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/plugins/plan-check/agents/plan-reviewer.md b/plugins/plan-check/agents/plan-reviewer.md index 8b14324..e9acce0 100644 --- a/plugins/plan-check/agents/plan-reviewer.md +++ b/plugins/plan-check/agents/plan-reviewer.md @@ -14,6 +14,8 @@ color: blue tools: - Read - Bash + - Grep + - Glob - ToolSearch - mcp__sequential-thinking__sequentialthinking - mcp__claude_ai_Vault_Cortex__vault_get_memory From 4538c6775b4950ee9140a722ef6cc66500845fe0 Mon Sep 17 00:00:00 2001 From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com> Date: Fri, 4 Sep 2026 18:39:52 -0400 Subject: [PATCH 4/7] fix(skills): rename unrecognized tools: frontmatter key to allowed-tools MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SKILL.md frontmatter does not recognize a tools: key (that field belongs to agent definitions), so the declaration was inert. allowed-tools is the recognized skill field — it pre-approves the listed tool for inline invocation without restricting anything. Applied across plan-review and the five ship-check skills carrying the same key. Co-Authored-By: Claude Fable 5 --- plugins/plan-check/skills/plan-review/SKILL.md | 2 +- plugins/ship-check/skills/bug-check/SKILL.md | 2 +- plugins/ship-check/skills/code-quality/SKILL.md | 2 +- plugins/ship-check/skills/pr-monitor/SKILL.md | 2 +- plugins/ship-check/skills/pr-review/SKILL.md | 2 +- plugins/ship-check/skills/test-audit/SKILL.md | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/plugins/plan-check/skills/plan-review/SKILL.md b/plugins/plan-check/skills/plan-review/SKILL.md index 68ffb60..c685b94 100644 --- a/plugins/plan-check/skills/plan-review/SKILL.md +++ b/plugins/plan-check/skills/plan-review/SKILL.md @@ -13,7 +13,7 @@ description: > the plan itself (that's fable-mode + Plan agents), or auditing tests (test-audit). skills: - fable-mode -tools: +allowed-tools: - mcp__sequential-thinking__sequentialthinking --- diff --git a/plugins/ship-check/skills/bug-check/SKILL.md b/plugins/ship-check/skills/bug-check/SKILL.md index c38e64a..d55bdb9 100644 --- a/plugins/ship-check/skills/bug-check/SKILL.md +++ b/plugins/ship-check/skills/bug-check/SKILL.md @@ -12,7 +12,7 @@ description: > review (use security-review), or high-level correctness review (use pr-review). skills: - fable-mode -tools: +allowed-tools: - mcp__sequential-thinking__sequentialthinking --- diff --git a/plugins/ship-check/skills/code-quality/SKILL.md b/plugins/ship-check/skills/code-quality/SKILL.md index 51a1a86..b05bdc4 100644 --- a/plugins/ship-check/skills/code-quality/SKILL.md +++ b/plugins/ship-check/skills/code-quality/SKILL.md @@ -11,7 +11,7 @@ description: > generic simplification without convention grounding (use /simplify). skills: - fable-mode -tools: +allowed-tools: - mcp__sequential-thinking__sequentialthinking --- diff --git a/plugins/ship-check/skills/pr-monitor/SKILL.md b/plugins/ship-check/skills/pr-monitor/SKILL.md index 5d2d217..8c8f3e9 100644 --- a/plugins/ship-check/skills/pr-monitor/SKILL.md +++ b/plugins/ship-check/skills/pr-monitor/SKILL.md @@ -11,7 +11,7 @@ description: > reviewing the diff itself. skills: - fable-mode -tools: +allowed-tools: - mcp__sequential-thinking__sequentialthinking --- diff --git a/plugins/ship-check/skills/pr-review/SKILL.md b/plugins/ship-check/skills/pr-review/SKILL.md index 1f10df3..d738be6 100644 --- a/plugins/ship-check/skills/pr-review/SKILL.md +++ b/plugins/ship-check/skills/pr-review/SKILL.md @@ -12,7 +12,7 @@ description: > or code simplification without a PR context (use code-quality). skills: - fable-mode -tools: +allowed-tools: - mcp__sequential-thinking__sequentialthinking --- diff --git a/plugins/ship-check/skills/test-audit/SKILL.md b/plugins/ship-check/skills/test-audit/SKILL.md index 1558169..c9d1c7b 100644 --- a/plugins/ship-check/skills/test-audit/SKILL.md +++ b/plugins/ship-check/skills/test-audit/SKILL.md @@ -11,7 +11,7 @@ description: > NOT for: production code quality (use code-quality) or full PR review (use pr-review). skills: - fable-mode -tools: +allowed-tools: - mcp__sequential-thinking__sequentialthinking --- From d0836410f8c7d980cf2665133affded28af96d6b Mon Sep 17 00:00:00 2001 From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com> Date: Fri, 4 Sep 2026 18:40:33 -0400 Subject: [PATCH 5/7] fix(plan-check): add missing boundaries to three plan-review triggers AGENTS.md trigger structure requires action + condition + boundary (or an explicit always-applies). Three flags had neither: D1 no-one-named (now shares the mechanical-task carve-out), D2 sourceless constraint (trace it yourself when one search settles it), and D2 observation-promoted-to- requirement (explicit reasoned preservation is fine; the flag is for silent conversion). Co-Authored-By: Claude Fable 5 --- plugins/plan-check/skills/plan-review/SKILL.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/plugins/plan-check/skills/plan-review/SKILL.md b/plugins/plan-check/skills/plan-review/SKILL.md index c685b94..77d45fb 100644 --- a/plugins/plan-check/skills/plan-review/SKILL.md +++ b/plugins/plan-check/skills/plan-review/SKILL.md @@ -79,6 +79,9 @@ of them is wasted work. a one-sentence problem — don't demand ceremony. - **Flag** when no one is named who experiences the problem. A problem no one has is a mechanism looking for a justification. + **Boundary:** shares the mechanical-task carve-out above — a one-sentence + problem for small mechanical work names its sufferer implicitly (the failing + lint, the stale dependency); don't demand a cast list. ### 2. Premise and assumption audit @@ -98,9 +101,14 @@ it, then classify it: *verified in the plan* (evidence cited), *checkable now* rule come from? Agents have designed around constraints that turned out to be invented; a constraint that can't be traced to a doc, a decision, or a measurement is a hallucination until shown otherwise. + **Boundary:** if one read or search can trace the constraint, do that instead + of flagging (the checkable-now rule) — flag only what fails the search or + can't be checked from here. - **Flag** observations promoted to requirements. "The system currently does X" is a fact; "the system must keep doing X" is a decision — the plan must not silently convert one into the other. + **Boundary:** an explicit decision to preserve current behavior, with a stated + reason, is legitimate — the flag is for the silent conversion only. - For each premise, ask: **how would we know if this is false?** A premise with no falsification path is not load-bearing evidence, it's hope. Example of a premise that failed exactly this way: "a missing file needs bootstrapping" — From 9629efd0fa7ce9391f3c2c67ca5e8028e0c62d1f Mon Sep 17 00:00:00 2001 From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com> Date: Fri, 4 Sep 2026 18:40:55 -0400 Subject: [PATCH 6/7] fix(plan-check): make dimension verb-to-severity mapping explicit Dimensions use Flag/Block verbs while the output contract counts blockers / must-answer / recommendations, with only two dimensions mapping between them explicitly. Added the mapping rule at the top of the Dimensions section: Block is always a blocker; Flag resolves via the guess test unless the dimension assigns severity itself. Co-Authored-By: Claude Fable 5 --- plugins/plan-check/skills/plan-review/SKILL.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/plugins/plan-check/skills/plan-review/SKILL.md b/plugins/plan-check/skills/plan-review/SKILL.md index 77d45fb..d8c2c55 100644 --- a/plugins/plan-check/skills/plan-review/SKILL.md +++ b/plugins/plan-check/skills/plan-review/SKILL.md @@ -69,6 +69,11 @@ Run every applicable dimension. Dimension 2 gets the most time — false or unverified premises are the highest-cost failures, because everything downstream of them is wasted work. +Verb-to-severity mapping: **Block** always produces a blocker. A **Flag** lands +as must-answer or recommendation via the guess test defined under Output format +— unless the dimension assigns the severity itself (dimension 4's who-pays rule +and dimension 5's silent-writers rule do). + ### 1. Problem framing - **Flag** when the problem is stated as the absence of the proposed mechanism From 74adc63d6895f97e9c7822f70146e26a08754373 Mon Sep 17 00:00:00 2001 From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com> Date: Fri, 4 Sep 2026 18:57:14 -0400 Subject: [PATCH 7/7] feat(plan-check): allow plan-reviewer the full read-only vault-cortex set MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The premise audit reads task notes, boards, backlinks, and linked research — the four-tool subset forced Bash workarounds for graph, listing, and task queries. Adds the 20 read-only vault-cortex tools under both server prefixes; write tools stay excluded (findings only). Co-Authored-By: Claude Fable 5 --- plugins/plan-check/agents/plan-reviewer.md | 32 ++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/plugins/plan-check/agents/plan-reviewer.md b/plugins/plan-check/agents/plan-reviewer.md index e9acce0..ee5d1c6 100644 --- a/plugins/plan-check/agents/plan-reviewer.md +++ b/plugins/plan-check/agents/plan-reviewer.md @@ -20,12 +20,44 @@ tools: - mcp__sequential-thinking__sequentialthinking - mcp__claude_ai_Vault_Cortex__vault_get_memory - mcp__claude_ai_Vault_Cortex__vault_read_note + - mcp__claude_ai_Vault_Cortex__vault_read_file - mcp__claude_ai_Vault_Cortex__vault_memory_recall + - mcp__claude_ai_Vault_Cortex__vault_list_memory_files - mcp__claude_ai_Vault_Cortex__vault_search + - mcp__claude_ai_Vault_Cortex__vault_search_by_folder + - mcp__claude_ai_Vault_Cortex__vault_search_by_property + - mcp__claude_ai_Vault_Cortex__vault_search_by_tag + - mcp__claude_ai_Vault_Cortex__vault_list_notes + - mcp__claude_ai_Vault_Cortex__vault_list_files + - mcp__claude_ai_Vault_Cortex__vault_list_tags + - mcp__claude_ai_Vault_Cortex__vault_list_property_keys + - mcp__claude_ai_Vault_Cortex__vault_list_property_values + - mcp__claude_ai_Vault_Cortex__vault_list_tasks + - mcp__claude_ai_Vault_Cortex__vault_get_backlinks + - mcp__claude_ai_Vault_Cortex__vault_get_outgoing_links + - mcp__claude_ai_Vault_Cortex__vault_get_daily_note + - mcp__claude_ai_Vault_Cortex__vault_recent_notes + - mcp__claude_ai_Vault_Cortex__vault_find_orphans - mcp__vault-cortex__vault_get_memory - mcp__vault-cortex__vault_read_note + - mcp__vault-cortex__vault_read_file - mcp__vault-cortex__vault_memory_recall + - mcp__vault-cortex__vault_list_memory_files - mcp__vault-cortex__vault_search + - mcp__vault-cortex__vault_search_by_folder + - mcp__vault-cortex__vault_search_by_property + - mcp__vault-cortex__vault_search_by_tag + - mcp__vault-cortex__vault_list_notes + - mcp__vault-cortex__vault_list_files + - mcp__vault-cortex__vault_list_tags + - mcp__vault-cortex__vault_list_property_keys + - mcp__vault-cortex__vault_list_property_values + - mcp__vault-cortex__vault_list_tasks + - mcp__vault-cortex__vault_get_backlinks + - mcp__vault-cortex__vault_get_outgoing_links + - mcp__vault-cortex__vault_get_daily_note + - mcp__vault-cortex__vault_recent_notes + - mcp__vault-cortex__vault_find_orphans skills: - plan-review - fable-mode