create-claude-cabinet 0.31.0 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"

package/templates/cabinet/checkpoint-protocol.md

@@ -72,6 +72,27 @@ Either way, each spawned agent receives:
   relevant git diff (`this file group`, `pre-commit`, aggregate)
 - An instruction to return the verdict object below
 
+**Plan-first review discipline (critical for `pre-impl` scope):** at
+`pre-impl` scope, the agent receives the plan's full notes. The plan IS
+the primary input — it may already address common risks (auth, validation,
+XSS, race conditions). The agent MUST:
+
+1. **Read the plan text first.** Understand what the plan says it will do
+   and what mitigations it already includes.
+2. **Only raise concerns the plan does NOT address.** If the plan says
+   "preview action lives in Admin::TargetsController with three-layered
+   auth," do not raise "needs admin auth" as a concern — the plan already
+   covers it. Explicitly acknowledge addressed concerns rather than
+   re-raising them.
+3. **Distinguish "the codebase has this risk" from "the plan doesn't
+   mitigate this risk."** A checkpoint is not a codebase audit. The
+   question is whether THIS PLAN is safe to start — not whether the
+   codebase has pre-existing issues outside the plan's scope.
+
+Without this discipline, cabinet members pattern-match against codebase
+state and raise false positives that the plan already handles, wasting
+tokens on re-runs that produce the same concerns.
+
 ## Step 3 — Collect verdicts
 
 Each agent returns exactly this shape:

package/templates/workflows/execute-group.js

@@ -110,7 +110,18 @@ function reviewScope({ members, scopeLabel, scopeInstruction, phaseTitle }) {
         `Checkpoint scope: ${scopeLabel}.`,
         scopeInstruction,
         ``,
-        `You have Bash/Read/Grep/Glob — inspect the actual code and diffs yourself.`,
+        `IMPORTANT — plan-first review discipline:`,
+        `1. Read the plan text FIRST. The plan may already address common risks`,
+        `   (auth, validation, XSS, race conditions, etc.).`,
+        `2. Only raise concerns the plan does NOT address. If the plan explicitly`,
+        `   says how it handles a risk, do NOT re-raise it — acknowledge it and`,
+        `   move on. "The plan already covers X" is the right response.`,
+        `3. Distinguish "the codebase has this risk" from "the plan doesn't`,
+        `   mitigate this risk." A checkpoint reviews the PLAN, not the codebase.`,
+        `   Pre-existing codebase issues outside the plan's scope are not findings.`,
+        ``,
+        `You have Bash/Read/Grep/Glob — use them to verify claims in the plan`,
+        `against the actual code, but start from the plan, not from a codebase scan.`,
         `Return a verdict object: { verdict: continue|pause|stop, concerns: [...] }.`,
       ].filter(Boolean).join('\n'),
       { agentType: m.agentType || undefined, label: `${phaseTitle}:${m.key}`, phase: phaseTitle, schema: VERDICT_SCHEMA }
@@ -145,11 +156,11 @@ const cp1 = { group: null, perPlan: [] }
 if (members.length > 0) {
   // Group-level CP1 only meaningful for 2+ plans (combination concerns).
   if (isGroup) {
-    const aggregateSurface = plans.map(p => `- ${p.fid} ${p.text}\n${p.surfaceArea || '(surface area in notes)'}`).join('\n')
+    const planSummaries = plans.map(p => `=== Plan ${p.fid}: ${p.text} ===\n${p.notes || p.surfaceArea || '(no notes)'}\n`).join('\n')
     const groupVerdicts = await reviewScope({
       members,
       scopeLabel: `group aggregate — these ${plans.length} plans will run in parallel`,
-      scopeInstruction: `Review the COMBINATION. Any concern about these plans running together (shared assumptions, ordering, cross-plan interactions)?\n\nPlans:\n${aggregateSurface}`,
+      scopeInstruction: `Review the COMBINATION of these plans running in parallel. Read each plan's full notes — they describe what will be built and how risks are mitigated. Only raise concerns about the COMBINATION that the individual plans don't address (shared assumptions, ordering dependencies, cross-plan interactions, conflicting approaches).\n\n${planSummaries}`,
       phaseTitle: 'CP1',
     })
     const e = escalate(groupVerdicts)
@@ -164,7 +175,7 @@ if (members.length > 0) {
     reviewScope({
       members,
       scopeLabel: `pre-impl review of plan ${p.fid}`,
-      scopeInstruction: `Is this plan safe to start? Review its approach and surface area.\n\nPlan ${p.fid}: ${p.text}\n\n${p.notes || p.surfaceArea || ''}`,
+      scopeInstruction: `Is this plan safe to start? Read the plan's full notes below — the plan may already address common risks. Only raise concerns it does NOT cover.\n\nPlan ${p.fid}: ${p.text}\n\n${p.notes || p.surfaceArea || ''}`,
       phaseTitle: 'CP1',
     }).then(verdicts => ({ fid: p.fid, escalation: escalate(verdicts), verdicts }))
   ))