agentic-sdlc-wizard 1.21.0 → 1.23.0

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to the SDLC Wizard.
 
 > **Note:** This changelog is for humans to read. Don't manually apply these changes - just run the wizard ("Check for SDLC wizard updates") and it handles everything automatically.
 
+## [1.23.0] - 2026-04-01
+
+### Added
+- Update notification hook — `instructions-loaded-check.sh` checks npm for newer wizard version each session. Non-blocking, graceful on network failure. One-liner: "SDLC Wizard update available: X → Y (run /update-wizard)" (#64)
+- Cross-model review standardization — mission-first handoff (mission/success/failure fields), preflight self-review doc, verification checklist, adversarial framing, domain template guidance, convergence reduced to 2-3 rounds. Audited 4 repos + 14 external repos + 7 papers (#72, #56)
+- Release Planning Gate — section in SDLC skill. Before implementing release items: list all, plan each at 95% confidence, identify blocks, present plans as batch. Prove It Gate strengthened with absorption check (#73)
+- 6 quality tests for update notification (fake npm in PATH, version comparison, failure modes)
+- 12 quality tests for cross-model review, context position, release planning
+- Testing Diamond boundary table — explicit E2E (UI/browser ~5%) vs Integration (API/no UI ~90%) vs Unit (pure logic ~5%) in SKILL.md and wizard doc (#65)
+- Skill frontmatter docs — expanded to full table covering `paths:`, `context: fork`, `effort:`, `disable-model-invocation:`, `argument-hint:` (#69)
+- `--bare` mode documentation in SKILL.md — complete wizard bypass warning for scripted headless calls (#70)
+- 6 quality tests for #65/#69/#70
+- "NEVER AUTO-MERGE" enforcement gate in CI Shepherd section — same weight as "ALL TESTS MUST PASS." Full shepherd sequence documented as mandatory (post-mortem from PR #145 incident)
+- Post-Mortem pattern — when process fails, feed it back: Incident → Root Cause → New Rule → Test → Ship. "Every mistake becomes a rule"
+- 4 quality tests for enforcement gate + post-mortem
+
+### Fixed
+- Dead-code pipe in `test_prove_it_absorption()` — `grep -qi | grep -qi` was a no-op (P1 from PR #145 CI review)
+
+### Changed
+- Moved "ALL TESTS MUST PASS" from 61% depth to 11% depth in SDLC skill (Lost in the Middle fix) (#57)
+- Prove It Gate now requires absorption check — "can this be a section in an existing skill?" — before proposing new skills/components
+- Wizard "E2E vs Manual Testing" section replaced with "E2E vs Integration — The Critical Boundary" (#65)
+- Wizard "Skill Effort Frontmatter" section expanded to "Skill Frontmatter Fields" with full field reference (#69)
+
+## [1.22.0] - 2026-04-01
+
+### Added
+- Plan Auto-Approval Gate — skip plan approval when confidence >= 95% AND task is single-file/trivial. Still announces approach, just doesn't wait. "When in doubt, wait for approval" (#53)
+- Debugging Workflow section — systematic Reproduce → Isolate → Root Cause → Fix → Regression Test methodology. `git bisect` for regressions, environment-specific debugging guidance (#55)
+- `/feedback` skill — privacy-first community contribution loop. Bug reports, feature requests, pattern sharing, SDLC improvements. Never scans without explicit consent. Creates GH issues on wizard repo (#37)
+- BRANDING.md detection in setup wizard — scans for brand/, logos/, style-guide.md, brand-voice.md. Conditional generation only when branding assets found (#44)
+- N-Reviewer CI Pipeline guidance — address each reviewer independently, resolve conflicts, max 3 iterations per reviewer (#32)
+- Custom Subagents documentation — `.claude/agents/` pattern for sdlc-reviewer, ci-debug, test-writer agents. Skills vs agents comparison (#45)
+- CLI distributes `/feedback` skill (9 template files, was 8)
+- Improved CLI install restart messaging — `--continue` promoted as primary option for preserving conversation history
+- 20 new tests across all 6 roadmap items
+
+### Changed
+- SDLC skill: added Auto-Approval, Debugging Workflow, Multiple Reviewers, Custom Subagents sections
+- Setup skill: added branding asset detection (Step 1) and BRANDING.md generation (Step 8.5)
+- Wizard doc: added Plan Auto-Approval, Debugging Workflow, N-Reviewer Pipeline, Custom Subagents, BRANDING.md template
+
 ## [1.21.0] - 2026-03-31
 
 ### Added

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -307,9 +307,24 @@ New built-in commands available to use alongside the wizard:
 
 **Tip**: `/simplify` pairs well with the self-review phase. Run it after implementation as an additional quality check.
 
-### Skill Effort Frontmatter (v2.1.80+)
+### Skill Frontmatter Fields (v2.1.80+)
 
-Skills can now set an `effort` level in frontmatter. The wizard's `/sdlc` skill uses `effort: high` to ensure Claude gives full attention to SDLC tasks.
+Skills support these frontmatter fields:
+
+| Field | Purpose | Example |
+|-------|---------|---------|
+| `name` | Skill name (matches `/command`) | `name: sdlc` |
+| `description` | Trigger description for auto-invocation | `description: Full SDLC workflow...` |
+| `effort` | Set reasoning effort level | `effort: high` |
+| `paths` | Restrict skill to specific file patterns | `paths: ["src/**/*.ts", "tests/**"]` |
+| `context` | Context mode (`fork` = isolated subagent) | `context: fork` |
+| `argument-hint` | Hint for `$ARGUMENTS` placeholder | `argument-hint: [task description]` |
+| `disable-model-invocation` | Prevent skill from being auto-invoked by model | `disable-model-invocation: true` |
+
+**Key fields explained:**
+- **`effort: high`** — The wizard's `/sdlc` skill uses this to ensure Claude gives full attention. `max` is available but costs significantly more tokens.
+- **`paths:`** — Limits when a skill activates based on files being worked on. Useful for language-specific or directory-specific skills.
+- **`context: fork`** — Runs the skill in an isolated subagent context. The subagent gets its own context window, so it won't pollute the main conversation. Useful for review skills or analysis that should run independently.
 
 ### InstructionsLoaded Hook (v2.1.69+)
 
@@ -418,6 +433,8 @@ After planning, you get a free `/compact` - Claude's plan is preserved in the su
 4. You run `/compact` → frees context, plan preserved in summary
 5. Claude implements with clean context
 
+**Plan Auto-Approval:** For HIGH confidence (95%+) tasks that are single-file or trivial (config tweak, small bug fix, string change) with no new patterns — skip plan approval and go straight to TDD. Claude still announces the approach but doesn't wait for approval. When in doubt, wait.
+
 ### 2. Confidence Levels Prevent Disasters
 
 Claude MUST state confidence before implementing:
@@ -473,10 +490,11 @@ Here's the "Testing Diamond" approach (recommended for AI agents):
 - **Confidence**: If integration tests pass, production usually works
 - **AI-friendly**: Give Claude concrete pass/fail feedback on real behavior
 
-**E2E vs Manual Testing:**
-- **E2E (automated)**: Playwright, Cypress - runs without human
-- **Manual testing**: Human sign-off at the very end
-- **Goal**: Zero manual testing. Only for final verification when 100% confident.
+**E2E vs Integration — The Critical Boundary:**
+- **E2E**: Tests that go through the user's actual UI/browser (Playwright, Cypress). ~5% of suite.
+- **Integration**: Tests that hit real systems via API without UI — real DB, real cache, real services. ~90% of suite.
+- **Unit**: Pure logic only — no DB, no API, no filesystem. ~5% of suite.
+- **The rule**: If your test doesn't open a browser or render a UI, it's not E2E — it's integration. Mislabeling leads to overinvestment in slow browser tests.
 
 **But your team decides:**
 
@@ -1773,6 +1791,19 @@ TodoWrite([
 
 **Before TDD, MUST ask:** "Docs updated. Run `/compact` before implementation?"
 
+### Auto-Approval: Skip Plan Approval Step
+
+If ALL of these are true, skip plan approval and go straight to TDD:
+- Confidence is **HIGH (95%+)** — you know exactly what to do
+- Task is **single-file or trivial** (config tweak, small bug fix, string change)
+- No new patterns introduced
+- No architectural decisions
+
+When auto-approving, still announce your approach — just don't wait for approval:
+> "Confidence HIGH (95%). Single-file change. Proceeding directly to TDD."
+
+**When in doubt, wait for approval.** Auto-approval is for clear-cut cases only.
+
 ## Confidence Check (REQUIRED)
 
 Before presenting approach, STATE your confidence:
@@ -1927,6 +1958,28 @@ Before any release/publish, add these to `review_instructions`:
 
 Evidence: v1.20.0 cross-model review caught CHANGELOG section loss and stale wizard version examples that passed all tests and self-review.
 
+### Multiple Reviewers (N-Reviewer Pipeline)
+
+When multiple reviewers comment on a PR (Claude, Codex, human reviewers), address each reviewer independently:
+
+1. **Read all reviews** — collect feedback from every active reviewer
+2. **Respond per-reviewer** — each reviewer has different blind spots. Address each one's findings separately
+3. **Resolve conflicts** — if reviewers disagree, pick the stronger argument, note why
+4. **Iterate until all approve** — don't merge until every active reviewer is satisfied
+5. **Max 3 iterations per reviewer** — escalate to user if a reviewer keeps finding new things
+
+The value of multiple reviewers: different models/humans catch different issues. No single reviewer is sufficient for high-stakes changes.
+
+### Custom Subagents (`.claude/agents/`)
+
+Claude Code supports custom subagents in `.claude/agents/`. These run as independent subprocesses focused on a single task:
+
+- **`sdlc-reviewer`** — SDLC compliance review (planning, TDD, self-review checks)
+- **`ci-debug`** — CI failure diagnosis (reads logs, identifies root cause)
+- **`test-writer`** — Quality test writing following TESTING.md philosophies
+
+**Skills vs agents:** Skills guide Claude's behavior for a task type. Agents are independent subprocesses that run autonomously and return results. Use agents when you want parallel work or a fresh context window.
+
 ## Test Review (Harder Than Implementation)
 
 During self-review, critique tests HARDER than app code:
@@ -2004,6 +2057,24 @@ Sometimes the flakiness is genuinely in CI infrastructure (runner environment, G
 - **Keep quality gates strict** — the actual pass/fail decision must NOT have `continue-on-error`
 - **Separate "fail the build" from "nice to have"** — a missing PR comment is not a regression
 
+## Debugging Workflow (Systematic Investigation)
+
+When something breaks and the cause isn't obvious, follow this systematic debugging workflow:
+
+```
+Reproduce → Isolate → Root Cause → Fix → Regression Test
+```
+
+1. **Reproduce** — Can you make it fail consistently? If intermittent, stress-test (run N times). If you can't reproduce it, you can't fix it
+2. **Isolate** — Narrow the scope. Which file? Which function? Which input? Use binary search: comment out half the code, does it still fail?
+3. **Root cause** — Don't fix symptoms. Ask "why?" until you hit the actual cause. "It crashes on line 42" is a symptom. "Null pointer because the API returns undefined when rate-limited" is a root cause
+4. **Fix** — Fix the root cause, not the symptom
+5. **Regression test** — Write a test that fails without your fix and passes with it (TDD GREEN)
+
+**For regressions** (it worked before, now it doesn't): Use `git bisect` to find the exact breaking commit. `git bisect start`, `git bisect bad` (current), `git bisect good <known-good-commit>`. Narrows to the breaking commit in O(log n) steps.
+
+**Environment-specific bugs** (works locally, fails in CI/staging/prod): Check environment differences (env vars, OS version, dependency versions, file permissions). Reproduce the environment locally if possible. Add logging at the failure point — don't guess, observe.
+
 ## CI Feedback Loop — Local Shepherd (After Commit)
 
 **This is the "local shepherd" — your CI fix mechanism.** It runs in your active session with full context.
@@ -2346,7 +2417,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.21.0 -->
+<!-- SDLC Wizard Version: 1.23.0 -->
 <!-- Setup Date: [DATE] -->
 <!-- Completed Steps: step-0.1, step-0.2, step-0.4, step-1, step-2, step-3, step-4, step-5, step-6, step-7, step-8, step-9 -->
 <!-- Git Workflow: [PRs or Solo] -->
@@ -2455,6 +2526,36 @@ Reference: `components/ui/` or Storybook
 
 **If you have external design system:** Point to Storybook/Figma URL instead of duplicating.
 
+### BRANDING.md (If Branding Assets Detected)
+
+**Only generated if branding-related files are found:** BRANDING.md, brand/, logos/, style-guide.md, brand-voice.md, tone-of-voice.*, or UI/content-heavy project patterns.
+
+```markdown
+# Brand Guidelines
+
+## Brand Voice & Tone
+- [Detected from brand-voice.md or style guide, or ask user]
+- Formal/casual/technical/friendly
+- Target audience description
+
+## Naming Conventions
+- Product name: [official name, capitalization]
+- Feature names: [naming pattern]
+- Technical terminology: [glossary of project-specific terms]
+
+## Visual Identity
+- Logo usage: [reference to logo files or guidelines]
+- Color palette: [reference to DESIGN_SYSTEM.md if exists]
+- Typography: [font choices and usage]
+
+## Content Style
+- [Any content writing guidelines]
+- [Error message tone]
+- [User-facing copy standards]
+```
+
+**Why BRANDING.md?** Claude writing user-facing copy, error messages, or documentation needs to know the brand voice. Without this, output tone is inconsistent. Skip for backend-only or internal-tool projects.
+
 ---
 
 ## Step 10: Verify Setup (Claude Does This Automatically)
@@ -2712,6 +2813,7 @@ Docs drift when code changes but docs don't. The SDLC skill's planning phase det
 - During planning, Claude reads feature docs for the area being changed
 - If the code change contradicts what the doc says, Claude updates the doc
 - The "After Session" step routes learnings to the right doc
+- Plan files get closed out — if the session's work came from a plan, it gets deleted or marked complete so future sessions aren't misled
 - Stale docs cause low confidence — if Claude struggles, the doc may need updating
 
 **CLAUDE.md health:** Run `/claude-md-improver` periodically (quarterly or after major changes). It audits CLAUDE.md specifically — structure, clarity, completeness (6 criteria, 100-point rubric). It does NOT cover feature docs, TESTING.md, or ADRs — the SDLC workflow handles those.
@@ -2929,7 +3031,7 @@ Use an independent AI model from a different company as a code reviewer. The aut
 **The Protocol:**
 
 1. Create a `.reviews/` directory in your project
-2. After Claude completes its SDLC loop (self-review passes), write a handoff file:
+2. After Claude completes its SDLC loop (self-review passes), write a preflight doc (what you already checked) then a mission-first handoff file:
 
 ```jsonc
 // .reviews/handoff.json
@@ -2937,12 +3039,22 @@ Use an independent AI model from a different company as a code reviewer. The aut
   "review_id": "feature-xyz-001",
   "status": "PENDING_REVIEW",
   "round": 1,
+  "mission": "What changed and why — context for the reviewer",
+  "success": "What 'correctly reviewed' looks like",
+  "failure": "What gets missed if the reviewer is superficial",
   "files_changed": ["src/auth.ts", "tests/auth.test.ts"],
-  "review_instructions": "Review for security, edge cases, and correctness",
+  "verification_checklist": [
+    "(a) Verify input validation at auth.ts:45",
+    "(b) Verify test covers null-token edge case"
+  ],
+  "review_instructions": "Focus on security and edge cases. Assume bugs may be present until proven otherwise.",
+  "preflight_path": ".reviews/preflight-feature-xyz-001.md",
   "artifact_path": ".reviews/feature-xyz-001/"
 }
 ```
 
+The `mission/success/failure` fields give the reviewer context. Without them, you get generic "looks good" feedback. With them, reviewers dig into source files and verify specific claims. The `verification_checklist` tells the reviewer exactly what to verify — not "review this" but specific items with file:line references.
+
 3. Run the independent reviewer (Round 1 — full review). These commands use your Codex default model — configure it to the latest, most capable model available:
 
 ```bash
@@ -3217,7 +3329,7 @@ Walk through updates? (y/n)
 Store wizard state in `SDLC.md` as metadata comments (invisible to readers, parseable by Claude):
 
 ```markdown
-<!-- SDLC Wizard Version: 1.21.0 -->
+<!-- SDLC Wizard Version: 1.23.0 -->
 <!-- Setup Date: 2026-01-24 -->
 <!-- Completed Steps: step-0.1, step-0.2, step-1, step-2, step-3, step-4, step-5, step-6, step-7, step-8, step-9 -->
 <!-- Git Workflow: PRs -->

package/README.md

@@ -186,7 +186,7 @@ This isn't the only Claude Code SDLC tool. Here's an honest comparison:
 |--------|------------|----------------------|-------------|
 | **Focus** | SDLC enforcement + measurement | Agent performance optimization | Plugin marketplace |
 | **Hooks** | 3 (SDLC, TDD, instructions) | 12+ (dev blocker, prettier, etc.) | Webhook watcher |
-| **Skills** | 3 (/sdlc, /setup, /update) | 80+ domain-specific | 13 slash commands |
+| **Skills** | 4 (/sdlc, /setup, /update, /feedback) | 80+ domain-specific | 13 slash commands |
 | **Evaluation** | 95% CI, CUSUM, SDP, Tier 1/2 | Configuration testing | skilltest framework |
 | **CI Shepherd** | Local CI fix loop | No | No |
 | **Auto-updates** | Weekly CC + community scan | No | No |

package/cli/init.js

@@ -22,6 +22,7 @@ const FILES = [
   { src: 'skills/sdlc/SKILL.md', dest: '.claude/skills/sdlc/SKILL.md' },
   { src: 'skills/setup/SKILL.md', dest: '.claude/skills/setup/SKILL.md' },
   { src: 'skills/update/SKILL.md', dest: '.claude/skills/update/SKILL.md' },
+  { src: 'skills/feedback/SKILL.md', dest: '.claude/skills/feedback/SKILL.md' },
 ];
 
 const WIZARD_HOOK_MARKERS = FILES
@@ -224,12 +225,12 @@ function init(targetDir, { force = false, dryRun = false } = {}) {
   console.log(`
 ${GREEN}SDLC Wizard installed successfully!${RESET}
 
-${YELLOW}Important:${RESET} Hooks and settings load at session start.
-  If Claude Code is already running, type ${CYAN}/exit${RESET} then ${CYAN}claude${RESET} to restart.
-  (Or ${CYAN}claude --continue${RESET} to keep your conversation history.)
+${YELLOW}Restart Claude Code${RESET} to load new hooks and skills:
+  ${CYAN}/exit${RESET} then ${CYAN}claude --continue${RESET}  (keeps conversation history)
+  ${CYAN}/exit${RESET} then ${CYAN}claude${RESET}              (fresh start)
 
 Next steps:
-  1. Start Claude Code in this directory (or restart if already running)
+  1. Restart Claude Code (see above)
   2. Tell Claude anything — setup auto-invokes when SDLC files are missing
   3. Claude reads the wizard doc and creates CLAUDE.md, SDLC.md, TESTING.md, ARCHITECTURE.md
 

package/cli/templates/hooks/instructions-loaded-check.sh

@@ -20,4 +20,16 @@ if [ -n "$MISSING" ]; then
     echo "Invoke Skill tool, skill=\"setup-wizard\" to generate them."
 fi
 
+# Version update check (non-blocking, best-effort)
+SDLC_MD="$PROJECT_DIR/SDLC.md"
+if [ -f "$SDLC_MD" ]; then
+    INSTALLED_VERSION=$(grep -o 'SDLC Wizard Version: [0-9.]*' "$SDLC_MD" | head -1 | sed 's/SDLC Wizard Version: //')
+    if [ -n "$INSTALLED_VERSION" ] && command -v npm > /dev/null 2>&1; then
+        LATEST_VERSION=$(npm view agentic-sdlc-wizard version 2>/dev/null) || true
+        if [ -n "$LATEST_VERSION" ] && [ "$LATEST_VERSION" != "$INSTALLED_VERSION" ]; then
+            echo "SDLC Wizard update available: ${INSTALLED_VERSION} → ${LATEST_VERSION} (run /update-wizard)"
+        fi
+    fi
+fi
+
 exit 0

package/cli/templates/skills/feedback/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: feedback
+description: Submit feedback, bug reports, feature requests, or share SDLC patterns you've discovered. Privacy-first — always asks before scanning.
+argument-hint: [optional: bug | feature | pattern | improvement]
+effort: medium
+---
+# Feedback — Community Contribution Loop
+
+## Task
+$ARGUMENTS
+
+## Purpose
+
+Help users contribute back to the SDLC wizard: bug reports, feature requests, pattern sharing, and SDLC improvements. Privacy-first — never scan without explicit permission.
+
+## Privacy & Permission (MANDATORY)
+
+**NEVER scan the user's repo without explicit consent.** Always ask first:
+
+> "I can scan your SDLC setup to identify what you've customized vs wizard defaults. This helps me create a more specific report. May I scan? (Only file names and SDLC config are read — no source code, secrets, or business logic.)"
+
+**What IS scanned (with permission):**
+- SDLC.md, TESTING.md, CLAUDE.md structure (not content details)
+- Hook file names and which hooks are active
+- Skill names and which skills exist
+- .claude/settings.json hook configuration (not allowedTools or secrets)
+
+**What is NEVER scanned:**
+- Source code files
+- .env files, secrets, credentials
+- Business logic or proprietary code
+- Git history or commit messages
+
+## Feedback Types
+
+### Bug Report
+1. Ask user to describe the issue
+2. With permission, check which wizard version is installed (`SDLC.md` metadata)
+3. Check if hooks are properly configured
+4. Create a GitHub issue with reproduction steps
+
+### Feature Request
+1. Ask user what they want
+2. With permission, check if a similar capability already exists in their setup
+3. Create a GitHub issue with the request and context
+
+### Pattern Sharing
+1. Ask user what pattern they've discovered (custom hook, modified philosophy, test approach)
+2. With permission, diff their SDLC setup against wizard defaults to identify customizations
+3. Ask: "Which of these customizations worked well for you?"
+4. Create a GitHub issue describing the pattern and evidence it works
+
+### SDLC Improvement
+1. Ask what could be better about the SDLC workflow
+2. With permission, check which SDLC steps they use most/least
+3. Create a GitHub issue with the improvement suggestion
+
+## Creating the Issue
+
+Use `gh issue create` on the wizard repo:
+
+```bash
+gh issue create \
+  --repo BaseInfinity/agentic-ai-sdlc-wizard \
+  --title "[feedback-type]: Brief description" \
+  --body "$(cat <<'EOF'
+## Feedback Type
+bug / feature / pattern / improvement
+
+## Description
+[User's description]
+
+## Context
+- Wizard version: [from SDLC.md metadata]
+- Setup type: [detected stack if permission granted]
+
+## Evidence (if pattern sharing)
+[What the user customized and why it worked]
+
+---
+Submitted via `/feedback` skill
+EOF
+)"
+```
+
+## Rules
+
+- **Privacy first** — always ask before scanning anything
+- **Opt-in only** — if user declines scan, still create the issue with whatever they tell you manually
+- **No source code** — never include source code snippets in issues
+- **Be specific** — vague issues waste maintainer time. Ask clarifying questions
+- **Check for duplicates** — `gh issue list --repo BaseInfinity/agentic-ai-sdlc-wizard --search "keywords"` before creating

package/cli/templates/skills/sdlc/SKILL.md

@@ -48,7 +48,8 @@ TodoWrite([
   { content: "Post-deploy verification (if deploy task — see Deployment Tasks)", status: "pending", activeForm: "Verifying deployment" },
   // FINAL
   { content: "Present summary: changes, tests, CI status", status: "pending", activeForm: "Presenting final summary" },
-  { content: "Capture learnings (if any — update TESTING.md, CLAUDE.md, or feature docs)", status: "pending", activeForm: "Capturing session learnings" }
+  { content: "Capture learnings (if any — update TESTING.md, CLAUDE.md, or feature docs)", status: "pending", activeForm: "Capturing session learnings" },
+  { content: "Close out plan files: if task came from a plan, mark complete or delete", status: "pending", activeForm: "Closing plan artifacts" }
 ])
 ```
 
@@ -72,6 +73,42 @@ Your work is scored on these criteria. **Critical** criteria are must-pass.
 
 Critical miss on `tdd_red` or `self_review` = process failure regardless of total score.
 
+## Test Failure Recovery (SDET Philosophy)
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  ALL TESTS MUST PASS. NO EXCEPTIONS.                                │
+│                                                                     │
+│  This is not negotiable. This is not flexible. This is absolute.   │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+**Not acceptable:**
+- "Those were already failing" → Fix them first
+- "Not related to my changes" → Doesn't matter, fix it
+- "It's flaky" → Flaky = bug, investigate
+
+**Treat test code like app code.** Test failures are bugs. Investigate them the way a 15-year SDET would - with thought and care, not by brushing them aside.
+
+If tests fail:
+1. Identify which test(s) failed
+2. Diagnose WHY - this is the important part:
+   - Your code broke it? Fix your code (regression)
+   - Test is for deleted code? Delete the test
+   - Test has wrong assertions? Fix the test
+   - Test is "flaky"? Investigate - flakiness is just another word for bug
+3. Fix appropriately (fix code, fix test, or delete dead test)
+4. Run specific test individually first
+5. Then run ALL tests
+6. Still failing? ASK USER - don't spin your wheels
+
+**Flaky tests are bugs, not mysteries:**
+- Sometimes the bug is in app code (race condition, timing issue)
+- Sometimes the bug is in test code (shared state, not parallel-safe)
+- Sometimes the bug is in test environment (cleanup not proper)
+
+Debug it. Find root cause. Fix it properly. Tests ARE code.
+
 ## New Pattern & Test Design Scrutiny (PLANNING)
 
 **New design patterns require human approval:**
@@ -89,11 +126,12 @@ Critical miss on `tdd_red` or `self_review` = process failure regardless of tota
 
 **Adding a new skill, hook, workflow, or component? PROVE IT FIRST:**
 
-1. **Research:** Does something equivalent already exist (native CC, third-party plugin, existing skill)?
-2. **If YES:** Why is yours better? Show evidence (A/B test, quality comparison, gap analysis)
-3. **If NO:** What gap does this fill? Is the gap real or theoretical?
-4. **Quality tests:** New additions MUST have tests that prove OUTPUT QUALITY, not just existence
-5. **Less is more:** Every addition is maintenance burden. Default answer is NO unless proven YES
+1. **Absorption check:** Can this be added as a section in an existing skill instead of a new component? Default is YES — new skills/hooks need strong justification. Releasing is SDLC, not a separate skill. Debugging is SDLC, not a separate skill. Keep it lean
+2. **Research:** Does something equivalent already exist (native CC, third-party plugin, existing skill)?
+3. **If YES:** Why is yours better? Show evidence (A/B test, quality comparison, gap analysis)
+4. **If NO:** What gap does this fill? Is the gap real or theoretical?
+5. **Quality tests:** New additions MUST have tests that prove OUTPUT QUALITY, not just existence
+6. **Less is more:** Every addition is maintenance burden. Default answer is NO unless proven YES
 
 **Existence tests are NOT quality tests:**
 - BAD: "ci-analyzer skill file exists" — proves nothing about quality
@@ -110,6 +148,19 @@ Critical miss on `tdd_red` or `self_review` = process failure regardless of tota
 2. **Transition** (after approval): Update feature docs
 3. **Implementation**: TDD RED -> GREEN -> PASS
 
+### Auto-Approval: Skip Plan Approval Step
+
+If ALL of these are true, skip plan approval and go straight to TDD:
+- Confidence is **HIGH (95%+)** — you know exactly what to do
+- Task is **single-file or trivial** (config tweak, small bug fix, string change)
+- No new patterns introduced
+- No architectural decisions
+
+When auto-approving, still announce your approach — just don't wait for approval:
+> "Confidence HIGH (95%). Single-file change. Proceeding directly to TDD."
+
+**When in doubt, wait for approval.** Auto-approval is for clear-cut cases only.
+
 ## Confidence Check (REQUIRED)
 
 Before presenting approach, STATE your confidence:
@@ -118,9 +169,9 @@ Before presenting approach, STATE your confidence:
 |-------|---------|--------|--------|
 | HIGH (90%+) | Know exactly what to do | Present approach, proceed after approval | `high` (default) |
 | MEDIUM (60-89%) | Solid approach, some uncertainty | Present approach, highlight uncertainties | `high` (default) |
-| LOW (<60%) | Not sure | ASK USER before proceeding | Consider `/effort max` |
-| FAILED 2x | Something's wrong | STOP. ASK USER immediately | Try `/effort max` |
-| CONFUSED | Can't diagnose why something is failing | STOP. Describe what you tried, ask for help | Try `/effort max` |
+| LOW (<60%) | Not sure | Do more research or try cross-model research (Codex) to get to 95%. If still LOW after research, ASK USER | Consider `/effort max` |
+| FAILED 2x | Something's wrong | Try cross-model research (Codex) for a fresh perspective. If still stuck, STOP and ASK USER | Try `/effort max` |
+| CONFUSED | Can't diagnose why something is failing | Try cross-model research (Codex). If still confused, STOP. Describe what you tried, ask for help | Try `/effort max` |
 
 ## Self-Review Loop (CRITICAL)
 
@@ -153,36 +204,76 @@ PLANNING -> DOCS -> TDD RED -> TDD GREEN -> Tests Pass -> Self-Review
 
 **Prerequisites:** Codex CLI installed (`npm i -g @openai/codex`), OpenAI API key set.
 
-### Round 1: Initial Review
+**The core insight:** The review PROTOCOL is universal across domains. Only the review INSTRUCTIONS change. Code review is the default template below. For non-code domains (research, persuasion, medical content), adapt the `review_instructions` and `verification_checklist` fields while keeping the same handoff/dialogue/convergence loop.
 
-1. After self-review passes, write `.reviews/handoff.json`:
-   ```jsonc
-   {
-     "review_id": "feature-xyz-001",
-     "status": "PENDING_REVIEW",
-     "round": 1,
-     "files_changed": ["src/auth.ts", "tests/auth.test.ts"],
-     "review_instructions": "Review for security, edge cases, and correctness",
-     "artifact_path": ".reviews/feature-xyz-001/"
-   }
-   ```
-2. Run the independent reviewer:
-   ```bash
-   codex exec \
-     -c 'model_reasoning_effort="xhigh"' \
-     -s danger-full-access \
-     -o .reviews/latest-review.md \
-     "You are an independent code reviewer. Read .reviews/handoff.json, \
-      review the listed files. Output each finding with: an ID (1, 2, ...), \
-      severity (P0/P1/P2), description, and a 'certify condition' stating \
-      what specific change would resolve it. \
-      End with CERTIFIED or NOT CERTIFIED."
-   ```
-3. If CERTIFIED → proceed to CI. If NOT CERTIFIED → go to Round 2.
+### Step 0: Write Preflight Self-Review Doc
+
+Before submitting to an external reviewer, document what YOU already checked. This is proven to reduce reviewer findings to 0-1 per round (evidence: anticheat repo preflight discipline).
+
+Write `.reviews/preflight-{review_id}.md`:
+```markdown
+## Preflight Self-Review: {feature}
+- [ ] Self-review via /code-review passed
+- [ ] All tests passing
+- [ ] Checked for: [specific concerns for this change]
+- [ ] Verified: [what you manually confirmed]
+- [ ] Known limitations: [what you couldn't verify]
+```
+
+### Step 1: Write Mission-First Handoff
+
+After self-review and preflight pass, write `.reviews/handoff.json`:
+```jsonc
+{
+  "review_id": "feature-xyz-001",
+  "status": "PENDING_REVIEW",
+  "round": 1,
+  "mission": "What changed and why — 2-3 sentences of context",
+  "success": "What 'correctly reviewed' looks like — the reviewer's goal",
+  "failure": "What gets missed if the reviewer is superficial",
+  "files_changed": ["src/auth.ts", "tests/auth.test.ts"],
+  "fixes_applied": [],
+  "previous_score": null,
+  "verification_checklist": [
+    "(a) Verify input validation at auth.ts:45 handles empty strings",
+    "(b) Verify test covers the null-token edge case",
+    "(c) Check no hardcoded secrets in diff"
+  ],
+  "review_instructions": "Focus on security and edge cases. Be strict — assume bugs may be present until proven otherwise.",
+  "preflight_path": ".reviews/preflight-feature-xyz-001.md",
+  "artifact_path": ".reviews/feature-xyz-001/"
+}
+```
 
-### Round 2+: Dialogue Loop
+**Key fields explained:**
+- `mission/success/failure` — Gives the reviewer context. Without this, you get generic "looks good" feedback. With it, reviewers read raw source files and verify specific claims (proven across 4 repos)
+- `verification_checklist` — Specific things to verify with file:line references. NOT "review for correctness" — that's too vague. Each item is independently verifiable
+- `preflight_path` — Shows the reviewer what you already checked, so they focus on what you might have missed
+
+### Step 2: Run the Independent Reviewer
+
+```bash
+codex exec \
+  -c 'model_reasoning_effort="xhigh"' \
+  -s danger-full-access \
+  -o .reviews/latest-review.md \
+  "You are an independent code reviewer performing a certification audit. \
+   Read .reviews/handoff.json for full context — mission, success/failure \
+   conditions, and verification checklist. \
+   Verify each checklist item with evidence (file:line, grep results, test output). \
+   Output each finding with: ID (1, 2, ...), severity (P0/P1/P2), evidence, \
+   and a 'certify condition' (what specific change resolves it). \
+   Re-verify any prior-round passes still hold. \
+   End with: score (1-10), CERTIFIED or NOT CERTIFIED."
+```
+
+**Always use `xhigh` reasoning effort.** Lower settings miss subtle errors (wrong-generation references, stale pricing, cross-file inconsistencies).
+
+If CERTIFIED → proceed to CI. If NOT CERTIFIED → go to dialogue loop.
+
+### Step 3: Dialogue Loop
 
-When the reviewer finds issues, respond per-finding instead of silently fixing everything:
+Respond per-finding — don't silently fix everything:
 
 1. Write `.reviews/response.json`:
    ```jsonc
@@ -192,16 +283,16 @@ When the reviewer finds issues, respond per-finding instead of silently fixing e
      "responding_to": ".reviews/latest-review.md",
      "responses": [
        { "finding": "1", "action": "FIXED", "summary": "Added missing validation" },
-       { "finding": "2", "action": "DISPUTED", "justification": "This is intentional — see CODE_REVIEW_EXCEPTIONS.md" },
+       { "finding": "2", "action": "DISPUTED", "justification": "Intentional — see CODE_REVIEW_EXCEPTIONS.md" },
        { "finding": "3", "action": "ACCEPTED", "summary": "Will add test coverage" }
      ]
    }
    ```
-   - **FIXED**: "I fixed this. Here is what changed." Reviewer verifies.
-   - **DISPUTED**: "This is intentional/incorrect. Here is why." Reviewer accepts or rejects.
-   - **ACCEPTED**: "You are right. Fixing now." (Same as FIXED, batched.)
+   - **FIXED**: "I fixed this. Here's what changed." Reviewer verifies against certify condition.
+   - **DISPUTED**: "This is intentional/incorrect. Here's why." Reviewer accepts or rejects with reasoning.
+   - **ACCEPTED**: "You're right. Fixing now." (Same as FIXED, batched.)
 
-2. Update `handoff.json` with `"status": "PENDING_RECHECK"`, increment `round`, add `"response_path"` and `"previous_review"` fields.
+2. Update `handoff.json`: increment `round`, set `"status": "PENDING_RECHECK"`, add `fixes_applied` list with numbered items and file:line references, update `previous_score`.
 
 3. Run targeted recheck (NOT a full re-review):
    ```bash
@@ -209,60 +300,88 @@ When the reviewer finds issues, respond per-finding instead of silently fixing e
      -c 'model_reasoning_effort="xhigh"' \
      -s danger-full-access \
      -o .reviews/latest-review.md \
-     "You are doing a TARGETED RECHECK. First read .reviews/handoff.json \
-      to find the previous_review path — read that file for the original \
-      findings and certify conditions. Then read .reviews/response.json \
-      for the author's responses. For each: \
-      FIXED → verify the fix against the original certify condition. \
-      DISPUTED → evaluate the justification (ACCEPT if sound, REJECT if not). \
+     "TARGETED RECHECK — not a full re-review. Read .reviews/handoff.json \
+      for previous_review path and response.json for the author's responses. \
+      For each finding: FIXED → verify against original certify condition. \
+      DISPUTED → evaluate justification (ACCEPT if sound, REJECT with reasoning). \
       ACCEPTED → verify it was applied. \
       Do NOT raise new findings unless P0 (critical/security). \
       New observations go in 'Notes for next review' (non-blocking). \
-      End with CERTIFIED or NOT CERTIFIED."
+      Re-verify all prior passes still hold. \
+      End with: score (1-10), CERTIFIED or NOT CERTIFIED."
    ```
 
-4. If CERTIFIED → done. If NOT CERTIFIED (rejected disputes or failed fixes) → fix rejected items and repeat.
-
 ### Convergence
 
-Max 3 recheck rounds (4 total including initial review). If still NOT CERTIFIED after round 4, escalate to the user with a summary of open findings. Don't spin indefinitely.
+**2 rounds is the sweet spot. 3 max.** Research across 14 repos and 7 papers confirms additional rounds beyond 3 produce <5% position shift.
+
+Max 2 recheck rounds (3 total including initial review). If still NOT CERTIFIED after round 3, escalate to the user with a summary of open findings.
 
 ```
-Self-review passes → handoff.json (round 1, PENDING_REVIEW)
-                            |
-                   Reviewer: FULL REVIEW (structured findings)
-                            |
-                   CERTIFIED? → YES → CI feedback loop
-                            |
-                            NO (findings with IDs + certify conditions)
-                            |
-                   Claude writes response.json:
-                     FIXED / DISPUTED / ACCEPTED per finding
-                            |
-                   handoff.json (round 2+, PENDING_RECHECK)
-                            |
-                   Reviewer: TARGETED RECHECK (previous findings only)
-                            |
-                   All resolved? → YES → CERTIFIED
-                            |
-                            NO → fix rejected items, repeat
-                            (max 3 rechecks, then escalate to user)
+Preflight → handoff.json (round 1) → FULL REVIEW
+                                          |
+                               CERTIFIED? → YES → CI
+                                          |
+                                          NO (scored findings)
+                                          |
+                               response.json (FIXED/DISPUTED/ACCEPTED)
+                                          |
+                               handoff.json (round 2+) → TARGETED RECHECK
+                                          |
+                               CERTIFIED? → YES → CI
+                                          |
+                                          NO → one more round, then escalate
 ```
 
 **Tool-agnostic:** The value is adversarial diversity (different model, different blind spots), not the specific tool. Any competing AI reviewer works.
 
-**Full protocol:** See the wizard's "Cross-Model Review Loop (Optional)" section for key flags and reasoning effort guidance.
+### Anti-Patterns to Avoid
+
+- **"Find at least N problems"** — Incentivizes false positives. Use adversarial framing ("assume bugs may be present") instead
+- **"Review this"** — Too vague, gets generic feedback. Use mission + verification checklist
+- **Numeric 1-10 scales without criteria** — Unreliable. Decompose into specific checklist items
+- **Letting reviewer see author's reasoning** — Causes anchoring bias. Let them form independent opinion from code
 
 ### Release Review Focus
 
-Before any release/publish, add these to `review_instructions`:
+Before any release/publish, add these to `verification_checklist`:
 - **CHANGELOG consistency** — all sections present, no lost entries during consolidation
 - **Version parity** — package.json, SDLC.md, CHANGELOG, wizard metadata all match
 - **Stale examples** — hardcoded version strings in docs match current release
 - **Docs accuracy** — README, ARCHITECTURE.md reflect current feature set
 - **CLI-distributed file parity** — live skills, hooks, settings match CLI templates
 
-Evidence: v1.20.0 cross-model review caught CHANGELOG section loss and stale wizard version examples that passed all tests and self-review. Tests catch version mismatches; cross-model review catches semantic issues tests cannot.
+### Multiple Reviewers (N-Reviewer Pipeline)
+
+When multiple reviewers comment on a PR (Claude PR review, Codex, human reviewers), address each reviewer independently:
+
+1. **Read all reviews** — `gh api repos/OWNER/REPO/pulls/PR/comments` to get every reviewer's feedback
+2. **Respond per-reviewer** — Each reviewer has different blind spots and priorities. Address each one's findings separately
+3. **Resolve conflicts** — If reviewers disagree, pick the stronger argument, note why
+4. **Iterate until all approve** — Don't merge until every active reviewer is satisfied
+5. **Max 3 iterations per reviewer** — If a reviewer keeps finding new things, escalate to the user
+
+### Adapting for Non-Code Domains
+
+The handoff format and dialogue loop work for ANY domain. Only `review_instructions` and `verification_checklist` change:
+
+| Domain | Instructions Focus | Checklist Example |
+|--------|-------------------|-------------------|
+| **Code (default)** | Security, logic bugs, test coverage | "Verify input validation at file:line" |
+| **Research/Docs** | Factual accuracy, source verification, overclaims | "Verify $736-$804 appears in both docs, no stale $695-$723 remains" |
+| **Persuasion** | Audience psychology, tone, trust | "If you were [audience], what's the moment you'd stop reading?" |
+
+For non-code: add `"audience"` and `"stakes"` fields to handoff.json. For code, these are implied (audience = other developers, stakes = production impact).
+
+### Custom Subagents (`.claude/agents/`)
+
+Claude Code supports custom subagents in `.claude/agents/`:
+
+- **`sdlc-reviewer`** — SDLC compliance review (planning, TDD, self-review checks)
+- **`ci-debug`** — CI failure diagnosis (reads logs, identifies root cause, suggests fix)
+- **`test-writer`** — Quality tests following TESTING.md philosophies
+
+**Skills** guide Claude's behavior. **Agents** run autonomously and return results. Use agents for parallel work or fresh context windows.
 
 ## Test Review (Harder Than Implementation)
 
@@ -276,6 +395,16 @@ During self-review, critique tests HARDER than app code:
 
 **Tests are the foundation.** Bad tests = false confidence = production bugs.
 
+### Testing Diamond — Know Your Layers
+
+| Layer | What It Tests | % of Suite | Key Trait |
+|-------|--------------|------------|-----------|
+| **E2E** | Full user flow through UI/browser (Playwright, Cypress) | ~5% | Slow, brittle, but proves the real thing works |
+| **Integration** | Real systems via API without UI — real DB, real cache, real services | ~90% | **Best bang for buck.** Fast, stable, high confidence |
+| **Unit** | Pure logic only — no DB, no API, no filesystem | ~5% | Fast but limited scope |
+
+**The critical boundary:** E2E tests go through the user's actual UI/browser. Integration tests hit real systems via API but without UI. If your test doesn't open a browser or render a UI, it's not E2E — it's integration. This distinction matters because mislabeling integration tests as E2E leads to overinvestment in slow browser tests when fast API-level tests would suffice.
+
 ### Minimal Mocking Philosophy
 
 | What | Mock? | Why |
@@ -327,41 +456,34 @@ If you notice something else that should be fixed:
 
 **Why this matters:** AI agents can drift into "helpful" changes that weren't requested. This creates unexpected diffs, breaks unrelated things, and makes code review harder.
 
-## Test Failure Recovery (SDET Philosophy)
+## Debugging Workflow (Systematic Investigation)
+
+When something breaks and the cause isn't obvious, follow this systematic debugging workflow:
 
 ```
-┌─────────────────────────────────────────────────────────────────────┐
-│  ALL TESTS MUST PASS. NO EXCEPTIONS.                                │
-│                                                                     │
-│  This is not negotiable. This is not flexible. This is absolute.   │
-└─────────────────────────────────────────────────────────────────────┘
+Reproduce → Isolate → Root Cause → Fix → Regression Test
 ```
 
-**Not acceptable:**
-- "Those were already failing" → Fix them first
-- "Not related to my changes" → Doesn't matter, fix it
-- "It's flaky" → Flaky = bug, investigate
-
-**Treat test code like app code.** Test failures are bugs. Investigate them the way a 15-year SDET would - with thought and care, not by brushing them aside.
+1. **Reproduce** — Can you make it fail consistently? If intermittent, stress-test (run N times). If you can't reproduce it, you can't fix it
+2. **Isolate** — Narrow the scope. Which file? Which function? Which input? Use binary search: comment out half the code, does it still fail?
+3. **Root cause** — Don't fix symptoms. Ask "why?" until you hit the actual cause. "It crashes on line 42" is a symptom. "Null pointer because the API returns undefined when rate-limited" is a root cause
+4. **Fix** — Fix the root cause, not the symptom. Write the fix
+5. **Regression test** — Write a test that fails without your fix and passes with it (TDD GREEN)
 
-If tests fail:
-1. Identify which test(s) failed
-2. Diagnose WHY - this is the important part:
-   - Your code broke it? Fix your code (regression)
-   - Test is for deleted code? Delete the test
-   - Test has wrong assertions? Fix the test
-   - Test is "flaky"? Investigate - flakiness is just another word for bug
-3. Fix appropriately (fix code, fix test, or delete dead test)
-4. Run specific test individually first
-5. Then run ALL tests
-6. Still failing? ASK USER - don't spin your wheels
+**For regressions** (it worked before, now it doesn't):
+- Use `git bisect` to find the exact commit that broke it
+- `git bisect start`, `git bisect bad` (current), `git bisect good <known-good-commit>`
+- Bisect narrows to the breaking commit in O(log n) steps
 
-**Flaky tests are bugs, not mysteries:**
-- Sometimes the bug is in app code (race condition, timing issue)
-- Sometimes the bug is in test code (shared state, not parallel-safe)
-- Sometimes the bug is in test environment (cleanup not proper)
+**Environment-specific bugs** (works locally, fails in CI/staging/prod):
+- Check environment differences: env vars, OS version, dependency versions, file permissions
+- Reproduce the environment locally if possible (Docker, env vars)
+- Add logging at the failure point — don't guess, observe
 
-Debug it. Find root cause. Fix it properly. Tests ARE code.
+**When to stop and ask:**
+- After 2 failed fix attempts → STOP and ASK USER
+- If the bug is in code you don't understand → read first, then fix
+- If reproducing requires access you don't have → ASK USER
 
 ## CI Feedback Loop — Local Shepherd (After Commit)
 
@@ -383,25 +505,25 @@ Local tests pass -> Commit -> Push -> Watch CI
                                                    STOP and ASK USER
 ```
 
-**How to watch CI:**
-1. Push changes to remote
-2. Check CI status:
-   ```bash
-   # Watch checks in real-time (blocks until complete)
-   gh pr checks --watch
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  NEVER AUTO-MERGE. NO EXCEPTIONS.                                   │
+│                                                                     │
+│  Do NOT run `gh pr merge --auto`. Ever.                            │
+│  Auto-merge fires before you can read review feedback.             │
+│  The shepherd loop IS the process. Skipping it = shipping bugs.    │
+└─────────────────────────────────────────────────────────────────────┘
+```
 
-   # Or check status without blocking
-   gh pr checks
+**The full shepherd sequence — every step is mandatory:**
+1. Push changes to remote
+2. Watch CI: `gh pr checks --watch`
+3. If CI fails → read logs (`gh run view <RUN_ID> --log-failed`), fix, push again (max 2 attempts)
+4. If CI passes → read ALL review comments: `gh api repos/OWNER/REPO/pulls/PR/comments`
+5. Fix valid suggestions, push, iterate until clean
+6. Only then: explicit merge with `gh pr merge --squash`
 
-   # View specific failed run logs
-   gh run view <RUN_ID> --log-failed
-   ```
-3. If CI fails:
-   - Read failure logs: `gh run view <RUN_ID> --log-failed`
-   - Diagnose root cause (same philosophy as local test failures)
-   - Fix and push again
-4. Max 2 fix attempts - if still failing, ASK USER
-5. If CI passes - proceed to present final summary
+**Why this is non-negotiable:** PR #145 auto-merged a release before review feedback was read. CI reviewer found a P1 dead-code bug that shipped to main. The fix required a follow-up commit. Auto-merge cost more time than the shepherd loop would have taken.
 
 **Context GC (compact during idle):** While waiting for CI (typically 3-5 min), suggest `/compact` if the conversation is long. Think of it like a time-based garbage collector — idle time + high memory pressure = good time to collect. Don't suggest on short conversations.
 
@@ -451,6 +573,8 @@ CI passes -> Read review suggestions
 - Auto-compact fires at ~95% capacity — no manual management needed
 - After committing a PR, `/clear` before starting the next feature
 
+**`--bare` mode (v2.1.81+):** `claude -p "prompt" --bare` skips ALL hooks, skills, LSP, and plugins. This is a complete wizard bypass — no SDLC enforcement, no TDD checks, no planning hooks. Use only for scripted headless calls (CI pipelines, automation) where you explicitly don't want wizard enforcement. Never use `--bare` for normal development work.
+
 ## DRY Principle
 
 **Before coding:** "What patterns exist I can reuse?"
@@ -475,6 +599,21 @@ CI passes -> Read review suggestions
 
 **If no DESIGN_SYSTEM.md exists:** Skip these checks (project has no documented design system).
 
+## Release Planning (If Task Involves a Release)
+
+**When to check:** Task mentions "release", "publish", "version bump", "npm publish", or multiple items being shipped together.
+**When to skip:** Single feature implementation, bug fix, or anything that isn't a release.
+
+Before implementing any release items:
+
+1. **List all items** — Read ROADMAP.md (or equivalent), identify every item planned for this release
+2. **Plan each at 95% confidence** — For each item: what files change, what tests prove it works, what's the blast radius. If confidence < 95% on any item, flag it
+3. **Identify blocks** — Which items depend on others? What must go first?
+4. **Present all plans together** — User reviews the complete batch, not one at a time. This catches conflicts, sequencing issues, and scope creep before any code is written
+5. **User approves, then implement** — Full SDLC per item (TDD RED → GREEN → self-review), in the prioritized order
+
+**Why batch planning works:** Ad-hoc one-at-a-time implementation leads to unvalidated additions and scope creep. Batch planning catches problems early — if you can't plan it at 95%, you're not ready to ship it.
+
 ## Deployment Tasks (If Task Involves Deploy)
 
 **When to check:** Task mentions "deploy", "release", "push to prod", "staging", etc.
@@ -540,6 +679,26 @@ If this session revealed insights, update the right place:
 - **Feature-specific quirks** → Feature docs (`*_PLAN.md`, `*_DOCS.md`)
 - **Architecture decisions** → `docs/decisions/` (ADR format) or `ARCHITECTURE.md`
 - **General project context** → `CLAUDE.md` (or `/revise-claude-md`)
+- **Plan files** → If this session's work came from a plan file, delete it or mark it complete. Stale plans mislead future sessions into thinking work is still pending
+
+## Post-Mortem: When Process Fails, Feed It Back
+
+**Every process failure becomes an enforcement rule.** When you skip a step and it causes a problem, don't just fix the symptom — add a gate so it can't happen again.
+
+```
+Incident → Root Cause → New Rule → Test That Proves the Rule → Ship
+```
+
+**How to post-mortem a process failure:**
+1. **What happened?** — Describe the incident (what went wrong, what was the impact)
+2. **Root cause** — Not "I forgot" — what structurally allowed the skip? Was it guidance (easy to ignore) instead of a gate (impossible to skip)?
+3. **New rule** — Turn the failure into an enforcement rule in the SDLC skill
+4. **Test** — Write a test that proves the rule exists (TDD — the rule is code too)
+5. **Evidence** — Reference the incident so future readers understand WHY the rule exists
+
+**Example (real incident):** PR #145 auto-merged before CI review was read. Root cause: auto-merge was enabled by default, no enforcement gate existed. New rule: "NEVER AUTO-MERGE" block added to CI Shepherd section with the same weight as "ALL TESTS MUST PASS." Test: `test_never_auto_merge_gate` verifies the block exists.
+
+**Industry pattern:** "Every mistake becomes a rule" — the best SDLC systems are built from accumulated incident learnings, not theoretical best practices.
 
 ---
 

package/cli/templates/skills/setup/SKILL.md

@@ -37,6 +37,7 @@ Scan the project root for:
 - Feature docs: *_PLAN.md, *_DOCS.md, *_SPEC.md, docs/
 - Deployment: Dockerfile, vercel.json, fly.toml, netlify.toml, Procfile, k8s/
 - Design system: tailwind.config.*, .storybook/, theme files, CSS custom properties
+- Branding assets: BRANDING.md, brand/, logos/, style-guide.md, brand-voice.md, tone-of-voice.*
 - Existing docs: README.md, CLAUDE.md, ARCHITECTURE.md
 - Scripts in package.json (lint, test, build, typecheck, etc.)
 - Database config files (prisma/, drizzle.config.*, knexfile.*, .env with DB_*)
@@ -151,6 +152,16 @@ Only if design system artifacts were found in Step 1:
 
 Skip this step if no UI/design system detected.
 
+### Step 8.5: Generate BRANDING.md (If Branding Detected)
+
+Only if branding-related assets were found in Step 1 (brand/, logos/, style-guide.md, brand-voice.md, existing BRANDING.md, or UI/content-heavy project detected):
+- Brand voice and tone guidelines
+- Naming conventions (product names, feature names, terminology)
+- Visual identity summary (logo usage, color palette references)
+- Content style guide (if the project has user-facing copy)
+
+Skip this step if no branding assets or UI/content patterns detected.
+
 ### Step 9: Configure Tool Permissions
 
 Based on detected stack, suggest `allowedTools` entries for `.claude/settings.json`:

package/cli/templates/skills/update/SKILL.md

@@ -45,13 +45,14 @@ Extract the latest version from the first `## [X.X.X]` line.
 Parse all CHANGELOG entries between the user's installed version and the latest. Present a clear summary:
 
 ```
-Installed: 1.19.0
-Latest:    1.21.0
+Installed: 1.21.0
+Latest:    1.23.0
 
 What changed:
+- [1.23.0] Update notification hook, ...
+- [1.22.0] Plan auto-approval, debugging workflow, /feedback skill, BRANDING.md detection, ...
 - [1.21.0] Confidence-driven setup, prove-it gate, cross-model release review, ...
 - [1.20.0] Version-pinned CC update gate, Tier 1 flakiness fix, flaky test guidance, ...
-- [1.19.0] CI shepherd model, token efficiency, feature doc enforcement, ...
 ```
 
 **If versions match:** Say "You're up to date! (version X.X.X)" and stop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-wizard",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "SDLC enforcement for Claude Code — hooks, skills, and wizard setup in one command",
   "bin": {
     "sdlc-wizard": "./cli/bin/sdlc-wizard.js"