agentic-sdlc-wizard 1.20.0 → 1.22.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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.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
+- Confidence-driven setup wizard — kills the fixed 18 questions. Scans repo, builds confidence per data point, only asks what it can't infer. Dynamic question count (0-2 for well-configured projects, 10+ for bare repos). 95% aggregate confidence threshold (#52)
+- CI Shepherd opt-in question in setup wizard (#48 partial)
+- Cross-model release review recommendation — releases/publishes as explicit trigger, Release Review Checklist with v1.20.0 evidence (#49)
+- Prove It Gate enforcement in SDLC skill — prevents unvalidated additions with quality test requirements (#50)
+- 6 confidence-driven setup tests, 10 prove-it-gate tests, 6 release review tests
+
+### Removed
+- ci-analyzer skill — violated Prove It philosophy (existence-only tests, no quality validation, overlap with `/claude-automation-recommender`) (#50)
+- ci-self-heal.yml deprecated — local shepherd is the primary CI fix mechanism
+
+### Changed
+- Wizard doc: Q-numbered questions → data point descriptions with detection hints
+- Setup skill: 12 steps (was 11) with new "Build Confidence Map" step
+- CLI distributes 8 template files (was 9, removed ci-analyzer)
+
 ## [1.20.0] - 2026-03-31
 
 ### Added

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -37,7 +37,7 @@ As Claude Code improves, the wizard absorbs those improvements and removes its o
 **But here's the key:** This isn't a one-size-fits-all answer. It's a starting point that helps you find YOUR answer. Every project is different. The self-evaluating loop (plan → build → test → review → improve) needs to be tuned to your codebase, your team, your standards. The wizard gives you the framework — you shape it into something bespoke.
 
 **The living system:**
-- CI self-heal captures friction signals as GitHub issues for pattern analysis
+- The local shepherd captures friction signals during active sessions
 - You approve changes to the process
 - Both sides learn over time
 - The system improves the system (recursive improvement)
@@ -356,6 +356,14 @@ This applies to everything: native Claude Code commands vs custom skills, framew
 
 **For the wizard's CI/CD:** When the weekly-update workflow detects a new Claude Code feature that overlaps with a wizard feature, the CI should automatically run E2E with both versions and recommend KEEP CUSTOM / SWITCH TO NATIVE / TIE.
 
+**This applies to YOUR OWN additions too — not just native vs custom:**
+- Adding a new skill? Prove it fills a gap nothing else covers. Write quality tests.
+- Adding a new hook? Prove it improves scores or catches real issues.
+- Adding a new workflow? Prove the automation ROI exceeds maintenance cost.
+- Existence tests ("file exists", "has frontmatter") are NOT proof. They prove the file was created, not that it works.
+
+**Evidence:** ci-analyzer skill was added in v1.20.0 with 4 existence-only tests, zero quality validation, and overlap with the third-party `/claude-automation-recommender`. Deleted in next release. This gap led to the Prove It Gate enforcement in the SDLC skill.
+
 ---
 
 ## What You're Setting Up
@@ -410,6 +418,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:
@@ -954,7 +964,7 @@ After SDLC setup is complete, run `/claude-automation-recommender` for stack-spe
 | Category | Wizard Ships | Recommender Suggests |
 |----------|-------------|---------------------|
 | SDLC process (TDD, planning, review) | Enforced via hooks + skills | Not covered |
-| CI workflows (self-heal, PR review) | Templates + docs | Not covered |
+| CI workflows (PR review) | Templates + docs | Not covered |
 | MCP servers (context7, Playwright, DB) | Not covered | Per-stack suggestions |
 | Auto-formatting hooks (Prettier, ESLint) | Not covered | Per-stack suggestions |
 | Type-checking hooks (tsc, mypy) | Not covered | Per-stack suggestions |
@@ -1026,39 +1036,44 @@ Feature branches still recommended for solo devs (keeps main clean, easy rollbac
 
 **Back-and-forth:** User questions live in PR comments. Bot's response is always the latest sticky comment. Clean and organized.
 
-**CI monitoring question:**
-> "Should Claude monitor CI checks after pushing and auto-diagnose failures? (y/n)"
+**CI shepherd opt-in (only if CI detected during auto-scan):**
+> "Enable CI shepherd role? Claude will actively watch CI, auto-fix failures, and iterate on review feedback. (y/n)"
 
-- **Yes** → Enable CI feedback loop in SDLC skill, add `gh` CLI to allowedTools
-- **No** → Skip CI monitoring steps (Claude still runs local tests, just doesn't watch CI)
+- **Yes** → Enable full shepherd loop: CI fix loop + review feedback loop. Ask detail questions below
+- **No** → Skip CI shepherd entirely (Claude still runs local tests, just doesn't interact with CI after pushing)
 
-**What this does:**
-1. After pushing, Claude runs `gh pr checks` to watch CI status
-2. If checks fail, Claude reads logs via `gh run view --log-failed`
-3. Claude diagnoses the failure and proposes a fix
-4. Max 2 fix attempts, then asks user
-5. Job isn't done until CI is green
+**What the CI shepherd does:**
+1. **CI fix loop:** After pushing, Claude watches CI via `gh pr checks`, reads failure logs, diagnoses and fixes, pushes again (max 2 attempts)
+2. **Review feedback loop:** After CI passes, Claude reads automated review comments, implements valid suggestions, pushes and re-reviews (max 3 iterations)
 
-**Recommendation:** Yes if you have CI configured. This closes the loop between
-"local tests pass" and "PR is actually ready to merge."
+**Recommendation:** Yes if you have CI configured. The shepherd closes the loop between "local tests pass" and "PR is actually ready to merge."
 
 **Requirements:**
 - `gh` CLI installed and authenticated
 - CI/CD configured (GitHub Actions, etc.)
 - If no CI yet: skip, add later when you set up CI
 
+**Stored in SDLC.md metadata as:**
+```
+<!-- CI Shepherd: enabled -->
+```
+
+**Detail questions (only if CI shepherd is enabled):**
+
+**CI monitoring detail:**
+> "Should Claude monitor CI checks after pushing and auto-diagnose failures? (y/n)"
+
+- **Yes** → Enable CI feedback loop in SDLC skill, add `gh` CLI to allowedTools
+- **No** → Skip CI monitoring steps (Claude still runs local tests, just doesn't watch CI)
+
 **CI review feedback question (only if CI monitoring is enabled):**
 > "What level of automated review response do you want?"
 
-| Level | Name | What autofix handles | Est. API cost |
-|-------|------|---------------------|---------------|
-| **L1** | `ci-only` | CI failures only (broken tests, lint) | ~$0.50/fix |
-| **L2** | `criticals` (default) | + Critical review findings (must-fix) | ~$1/fix |
-| **L3** | `all-findings` | + Every suggestion the reviewer flags | ~$2/fix |
-
-> **Cost note:** Higher levels mean more autofix iterations (each ~$0.50).
-> L3 typically adds 1-2 extra iterations per PR but produces cleaner code.
-> You can change this anytime by editing `AUTOFIX_LEVEL` in your ci-autofix workflow.
+| Level | Name | What the shepherd handles |
+|-------|------|--------------------------|
+| **L1** | `ci-only` | CI failures only (broken tests, lint) |
+| **L2** | `criticals` (default) | + Critical review findings (must-fix) |
+| **L3** | `all-findings` | + Every suggestion the reviewer flags |
 
 **What this does:**
 1. After CI passes, Claude reads the automated code review comments
@@ -1233,9 +1248,11 @@ Recommendation: Your current tests rely heavily on mocks.
 
 ---
 
-## Step 1: Confirm or Customize
+## Step 1: Build Confidence Map and Fill Gaps
+
+Claude assigns a state to each configuration data point based on scan results. **RESOLVED (detected)** items are presented for bulk confirmation. **RESOLVED (inferred)** items are presented with inferred values for the user to verify. **UNRESOLVED** items become questions. **The number of questions is dynamic — it depends on how much the scan resolves.** Stop asking when ALL data points are resolved (detected, inferred+confirmed, or answered by user).
 
-Claude presents what it found. You confirm or override:
+Claude presents what it found, organized by resolution state:
 
 ### Project Structure (Auto-Detected)
 
@@ -1244,13 +1261,13 @@ Claude presents what it found. You confirm or override:
 Override? (leave blank to accept): _______________
 ```
 
-**Q2: Where do your tests live?**
+**Test directory** (detect from tests/, __tests__/, spec/, test file patterns)
 ```
 Examples: tests/, __tests__/, src/**/*.test.ts, spec/
 Your answer: _______________
 ```
 
-**Q3: What's your test framework?**
+**Test framework** (detect from jest.config, vitest.config, pytest.ini, etc.)
 ```
 Options: Jest, Vitest, Playwright, Cypress, pytest, Go testing, other
 Your answer: _______________
@@ -1258,31 +1275,31 @@ Your answer: _______________
 
 ### Commands
 
-**Q4: What runs your linter?**
+**Lint command** (detect from package.json scripts, Makefile, config files)
 ```
 Examples: npm run lint, pnpm lint, eslint ., biome check
 Your answer: _______________
 ```
 
-**Q5: What runs type checking?**
+**Type-check command** (detect from tsconfig.json, mypy.ini, etc.)
 ```
 Examples: npm run typecheck, tsc --noEmit, mypy, none
 Your answer: _______________
 ```
 
-**Q6: What runs all tests?**
+**Run all tests command** (detect from package.json "test" script, Makefile)
 ```
 Examples: npm run test, pnpm test, pytest, go test ./...
 Your answer: _______________
 ```
 
-**Q7: What runs a specific test file?**
+**Run single test file command** (infer from framework: jest → jest path, pytest → pytest path)
 ```
 Examples: npm run test -- path/to/test.ts, pytest path/to/test.py
 Your answer: _______________
 ```
 
-**Q8: What builds for production?**
+**Production build command** (detect from package.json "build" script, Makefile)
 ```
 Examples: npm run build, pnpm build, go build, cargo build
 Your answer: _______________
@@ -1290,7 +1307,7 @@ Your answer: _______________
 
 ### Deployment
 
-**Q8.5: How do you deploy? (auto-detected, confirm or override)**
+**Deployment setup** (auto-detected from Dockerfile, vercel.json, fly.toml, deploy scripts)
 ```
 Detected: [e.g., Vercel, GitHub Actions, Docker, none]
 
@@ -1313,19 +1330,19 @@ Your answer: _______________
 
 ### Infrastructure
 
-**Q9: What database(s) do you use?**
+**Database(s)** (detect from prisma/, .env DB vars, docker-compose services)
 ```
 Examples: PostgreSQL, MySQL, SQLite, MongoDB, none
 Your answer: _______________
 ```
 
-**Q10: Do you use caching (Redis, etc.)?**
+**Caching layer** (detect from .env REDIS vars, docker-compose redis service)
 ```
 Examples: Redis, Memcached, none
 Your answer: _______________
 ```
 
-**Q11: How long do your tests take?**
+**Test duration** (estimate from test file count, CI run times if available)
 ```
 Examples: <1 minute, 1-5 minutes, 5+ minutes
 Your answer: _______________
@@ -1333,7 +1350,7 @@ Your answer: _______________
 
 ### Output Preferences
 
-**Q12: How much detail in Claude's responses?**
+**Response detail level** (cannot detect — always ask if no preference found)
 ```
 Options:
 - Small   - Minimal output, just essentials (experienced users)
@@ -1351,7 +1368,7 @@ Stored in `.claude/settings.json` as `"verbosity": "small|medium|large"`.
 
 ### Testing Philosophy
 
-**Q13: What's your testing approach?**
+**Testing approach** (infer from existing test patterns — test-first files, coverage config)
 ```
 Options:
 - Strict TDD (test first always)
@@ -1362,7 +1379,7 @@ Options:
 Your answer: _______________
 ```
 
-**Q14: What types of tests do you want?**
+**Test types** (detect from existing test file patterns: *.test.*, *.spec.*, e2e/, integration/)
 ```
 (Check all that apply)
 [ ] Unit tests (pure logic, isolated)
@@ -1372,7 +1389,7 @@ Your answer: _______________
 [ ] Other: _______________
 ```
 
-**Q15: Your mocking philosophy?**
+**Mocking philosophy** (detect from jest.mock, unittest.mock usage patterns)
 ```
 Options:
 - Minimal mocking (real DB, mock external APIs only)
@@ -1387,7 +1404,7 @@ Your answer: _______________
 **If test framework detected (Jest, pytest, Go, etc.):**
 
 ```
-Q16: Code Coverage (Optional)
+Code Coverage (Optional)
 
 Detected: [test framework] with coverage configuration
 
@@ -1408,7 +1425,7 @@ Your answer: _______________
 **If no test framework detected (docs/AI-heavy project):**
 
 ```
-Q16: Code Coverage (Optional)
+Code Coverage (Optional)
 
 No test framework detected (documentation/AI-heavy project).
 
@@ -1428,19 +1445,19 @@ Your answer: _______________
 
 ---
 
-### Using Your Answers
+### How Configuration Data Points Map to Files
 
-Your answers map to these files:
+Each resolved data point (whether detected or confirmed by the user) maps to generated files:
 
-| Question | Used In |
-|----------|---------|
-| Q1 (source dir) | `tdd-pretool-check.sh` - pattern match |
-| Q2 (test dir) | `TESTING.md` - documentation |
-| Q3 (test framework) | `TESTING.md` - documentation |
-| Q4-Q8 (commands) | `CLAUDE.md` - Commands section |
-| Q9-Q10 (infra) | `CLAUDE.md` - Architecture section, `TESTING.md` - mock decisions |
-| Q11 (test duration) | `SDLC skill` - wait time note |
-| Q12 (E2E) | `TESTING.md` - testing diamond top |
+| Data Point | Used In |
+|-----------|---------|
+| Source directory | `tdd-pretool-check.sh` - pattern match |
+| Test directory | `TESTING.md` - documentation |
+| Test framework | `TESTING.md` - documentation |
+| Commands (lint, typecheck, test, build) | `CLAUDE.md` - Commands section |
+| Infrastructure (DB, cache) | `CLAUDE.md` - Architecture section, `TESTING.md` - mock decisions |
+| Test duration | `SDLC skill` - wait time note |
+| Test types (E2E) | `TESTING.md` - testing diamond top |
 
 ---
 
@@ -1689,6 +1706,7 @@ TodoWrite([
   { content: "Find and read relevant documentation", status: "in_progress", activeForm: "Reading docs" },
   { content: "Assess doc health - flag issues (ask before cleaning)", status: "pending", activeForm: "Checking doc health" },
   { content: "DRY scan: What patterns exist to reuse?", status: "pending", activeForm: "Scanning for reusable patterns" },
+  { content: "Prove It Gate: adding new component? Research alternatives, prove quality with tests", status: "pending", activeForm: "Checking prove-it gate" },
   { content: "Blast radius: What depends on code I'm changing?", status: "pending", activeForm: "Checking dependencies" },
   { content: "Restate task in own words - verify understanding", status: "pending", activeForm: "Verifying understanding" },
   { content: "Scrutinize test design - right things tested? Follow TESTING.md?", status: "pending", activeForm: "Reviewing test approach" },
@@ -1730,6 +1748,22 @@ TodoWrite([
 - Does test approach follow TESTING.md philosophies?
 - If introducing new test patterns, same scrutiny as code patterns
 
+## Prove It Gate (REQUIRED for New Additions)
+
+**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
+
+**Existence tests are NOT quality tests:**
+- BAD: "ci-analyzer skill file exists" — proves nothing about quality
+- GOOD: "ci-analyzer recommends lint-first when test-before-lint detected" — proves behavior
+
+**If you can't write a quality test for it, you can't prove it works, so don't add it.**
+
 ## Plan Mode Integration
 
 **Use plan mode for:** Multi-file changes, new features, LOW confidence, bugs needing investigation.
@@ -1741,6 +1775,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:
@@ -1779,7 +1826,7 @@ PLANNING → DOCS → TDD RED → TDD GREEN → Tests Pass → Self-Review
 
 ## Cross-Model Review (If Configured)
 
-**When to run:** High-stakes changes (auth, payments, data handling), complex refactors, research-heavy work.
+**When to run:** High-stakes changes (auth, payments, data handling), releases/publishes (version bumps, CHANGELOG, npm publish), complex refactors, research-heavy work.
 **When to skip:** Trivial changes (typo fixes, config tweaks), time-sensitive hotfixes, risk < review cost.
 
 **Prerequisites:** Codex CLI installed (`npm i -g @openai/codex`), OpenAI API key set.
@@ -1884,6 +1931,39 @@ Self-review passes → handoff.json (round 1, PENDING_REVIEW)
 
 **Full protocol:** See the "Cross-Model Review Loop (Optional)" section below for key flags and reasoning effort guidance.
 
+### Release Review Focus
+
+Before any release/publish, add these to `review_instructions`:
+- **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.
+
+### 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:
@@ -1961,9 +2041,27 @@ 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" — the primary CI fix mechanism.** It runs in your active session with full context. The optional CI Auto-Fix bot (`.github/workflows/ci-autofix.yml`) is a fallback for unattended PRs only. When both are active, the bot detects your local pushes via SHA comparison and skips automatically.
+**This is the "local shepherd" — your CI fix mechanism.** It runs in your active session with full context.
 
 **The SDLC doesn't end at local tests.** CI must pass too.
 
@@ -2041,25 +2139,6 @@ CI passes -> Read review suggestions
 - **Ask first**: Present suggestions to user, let them decide which to implement
 - **Skip review feedback**: Ignore CI review suggestions, only fix CI failures
 
-## Shepherd vs. Bot: Two-Tier CI Fix Model
-
-| Aspect | Local Shepherd | CI Auto-Fix Bot |
-|--------|---------------|-----------------|
-| **When** | Active session (you're working) | Unattended (pushed and walked away) |
-| **Context** | Full: codebase, conversation, intent | Minimal: `--bare`, 200-line truncated logs |
-| **Cost** | Session tokens (marginal cost ~$0) | Separate API calls ($0.50-$2.00 per fix) |
-| **Noise** | 0 extra commits | 1+ `[autofix N/M]` commits per attempt |
-| **Quality** | High: full diagnosis, targeted fix | Lower: stateless, may repeat same approach |
-| **Speed** | Immediate: fix locally, push once | Delayed: workflow_run trigger + runner queue |
-| **Deconfliction** | N/A (is the primary) | SHA check: skips if branch advanced since failure |
-
-**The shepherd is the default.** It runs as part of the SDLC checklist above whenever you push from an active session. The bot is optional and only adds value for:
-- Dependabot/Renovate PRs (no human session)
-- PRs where you push and walk away
-- Overnight CI runs
-
-If you set up the bot, the SHA-based suppression ensures they never conflict.
-
 ## DRY Principle
 
 **Before coding:** "What patterns exist I can reuse?"
@@ -2158,7 +2237,7 @@ Create `CLAUDE.md` in your project root. This is your project-specific configura
 
 ## Commands
 
-<!-- CUSTOMIZE: Replace with your actual commands from Q4-Q8 -->
+<!-- CUSTOMIZE: Replace with your actual detected/confirmed commands -->
 
 - Build: `[your build command]`
 - Run dev: `[your dev command]`
@@ -2245,7 +2324,7 @@ These are your full reference docs. Start with stubs and expand over time:
 
 ## Environments
 
-<!-- Claude auto-populates this from Q8.5 deployment detection -->
+<!-- Claude auto-populates this from deployment detection -->
 
 | Environment | URL | Deploy Command | Trigger |
 |-------------|-----|----------------|---------|
@@ -2292,7 +2371,7 @@ If deployment fails or post-deploy verification catches issues:
 
 | Environment | Rollback Command | Notes |
 |-------------|------------------|-------|
-| Preview | [auto-expires or redeploy] | Usually self-heals |
+| Preview | [auto-expires or redeploy] | Ephemeral — redeploy to fix |
 | Staging | `[your rollback command]` | [notes] |
 | Production | `[your rollback command]` | [critical - document clearly] |
 
@@ -2322,7 +2401,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.20.0 -->
+<!-- SDLC Wizard Version: 1.22.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] -->
@@ -2431,6 +2510,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)
@@ -2889,87 +2998,6 @@ Claude: [fetches via gh api, discusses with you interactively]
 
 This is optional - skip if you prefer fresh reviews only.
 
-### CI Auto-Fix Loop (Optional — Bot Fallback)
-
-> **Two-tier model:** The SDLC skill's CI loops (above) are the "local shepherd" — they handle CI fixes during active sessions. This bot is the second tier: an unattended fallback for when no one is watching. The bot includes SHA-based suppression — if you push a fix locally before the bot runs, it skips automatically.
-
-Automatically fix CI failures and PR review findings. Claude reads the error context, fixes the code, commits, and re-triggers CI. Loops until CI passes AND review has no findings at your chosen level, or max retries hit.
-
-**The Loop:**
-```
-Push to PR
-    |
-    v
-CI runs ──► FAIL ──► ci-autofix: Claude reads logs, fixes, commits [autofix 1/3] ──► re-trigger
-    |
-    └── PASS ──► PR Review ──► has findings at your level? ──► ci-autofix: fixes all ──► re-trigger
-                      |
-                      └── APPROVE, no findings ──► DONE
-```
-
-**Safety measures:**
-- Never runs on main branch
-- Max retries (default 3, configurable via `MAX_AUTOFIX_RETRIES`)
-- `AUTOFIX_LEVEL` controls what findings to act on (`ci-only`, `criticals`, `all-findings`)
-- Restricted Claude tools (no git, no npm)
-- Self-modification ban (can't edit its own workflow file)
-- `[autofix N/M]` commit tags for audit trail
-- Sticky PR comments show status
-
-**Setup:**
-1. Create `.github/workflows/ci-autofix.yml`:
-
-```yaml
-name: CI Auto-Fix
-
-on:
-  workflow_run:
-    workflows: ["CI", "PR Code Review"]
-    types: [completed]
-
-permissions:
-  contents: write
-  pull-requests: write
-
-env:
-  MAX_AUTOFIX_RETRIES: 3
-  AUTOFIX_LEVEL: criticals  # ci-only | criticals | all-findings
-
-jobs:
-  autofix:
-    runs-on: ubuntu-latest
-    if: |
-      github.event.workflow_run.head_branch != 'main' &&
-      github.event.workflow_run.event == 'pull_request' &&
-      (
-        (github.event.workflow_run.name == 'CI' && github.event.workflow_run.conclusion == 'failure') ||
-        (github.event.workflow_run.name == 'PR Code Review' && github.event.workflow_run.conclusion == 'success')
-      )
-    steps:
-      # Count previous [autofix] commits to enforce max retries
-      # Download CI failure logs or fetch review comment
-      # Check findings at your AUTOFIX_LEVEL (criticals + suggestions)
-      # Run Claude to fix ALL findings with restricted tools
-      # Commit [autofix N/M], push, re-trigger CI
-      # Post sticky PR comment with status
-```
-
-2. Add `workflow_dispatch:` trigger to your CI workflow (so autofix can re-trigger it)
-3. Optionally configure a GitHub App for token generation (avoids `workflow_run` default-branch constraint)
-
-**Token approaches:**
-
-| Approach | When | Pros |
-|----------|------|------|
-| GITHUB_TOKEN + `gh workflow run` | Default | No extra setup |
-| GitHub App token | `CI_AUTOFIX_APP_ID` secret exists | Push triggers `synchronize` naturally |
-
-**Note:** `workflow_run` only fires for workflows on the default branch. The ci-autofix workflow is dormant until first merged to main.
-
-> **Template vs. this repo:** The template above uses `ci-autofix.yml` with `criticals` as a safe default for new projects. The wizard's own repo has evolved this into `ci-self-heal.yml` with `all-findings` — a more aggressive configuration we dogfood internally. Both naming conventions work; the behavior is identical.
-
----
-
 ### Cross-Model Review Loop (Optional)
 
 Use an independent AI model from a different company as a code reviewer. The author can't grade their own homework — a model with different training data and different biases catches blind spots the authoring model misses.
@@ -3108,6 +3136,7 @@ Claude writes code → self-review passes → handoff.json (round 1)
 
 **When to use this:**
 - High-stakes changes (auth, payments, data handling)
+- **Releases and publishes** (version bumps, CHANGELOG, npm publish) — see Release Review Checklist below
 - Research-heavy work where accuracy matters more than speed
 - Complex refactors touching many files
 - Any time you want higher confidence before merging
@@ -3117,6 +3146,30 @@ Claude writes code → self-review passes → handoff.json (round 1)
 - Time-sensitive hotfixes
 - Changes where the review cost exceeds the risk
 
+#### Release Review Checklist
+
+Before any release or npm publish, add these focus areas to the cross-model `review_instructions`:
+
+**Why:** Self-review and automated tests regularly miss release-specific inconsistencies. Evidence: v1.20.0 cross-model review caught 2 real issues (CHANGELOG section lost during consolidation, stale hardcoded version examples) that passed all tests and self-review.
+
+| Check | What to Look For | Example Failure |
+|-------|-------------------|-----------------|
+| CHANGELOG consistency | All sections present, no lost entries during consolidation | v1.19.0 section dropped when merging into v1.20.0 |
+| Version parity | package.json, SDLC.md, CHANGELOG, wizard metadata all match | SDLC.md says 1.19.0 but package.json says 1.20.0 |
+| Stale examples | Hardcoded version strings in docs/wizard match current release | Wizard examples showing v1.15.0 when publishing v1.20.0 |
+| Docs accuracy | README, ARCHITECTURE.md reflect current feature set | "8 workflows" when there are actually 7 |
+| CLI-distributed file parity | Live skills, hooks, settings match CLI templates | SKILL.md edited but cli/templates/ not updated |
+
+**Example `review_instructions` for releases:**
+```
+Review for release consistency: CHANGELOG completeness (no lost sections),
+version parity across package.json/SDLC.md/CHANGELOG/wizard metadata,
+stale hardcoded versions in examples, docs accuracy vs actual features,
+CLI-distributed file parity (skills, hooks, settings).
+```
+
+**This complements automated tests, not replaces them.** Tests catch exact version mismatches (e.g., `test_package_version_matches_changelog`). Cross-model review catches semantic issues tests cannot — a section silently dropped, examples using outdated but syntactically valid versions, docs describing features that no longer exist.
+
 ---
 
 ## User Understanding and Periodic Feedback
@@ -3249,7 +3302,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.20.0 -->
+<!-- SDLC Wizard Version: 1.22.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

@@ -83,7 +83,7 @@ Layer 1: PHILOSOPHY
 | **SDP normalization** | Separates "the model had a bad day" from "our SDLC broke" by cross-referencing external benchmarks |
 | **CUSUM drift detection** | Catches gradual quality decay over time — borrowed from manufacturing quality control |
 | **Pre-tool TDD hooks** | Before source edits, a hook reminds Claude to write tests first. CI scoring checks whether it actually followed TDD |
-| **Self-evolving loop** | Weekly/monthly external research + CI friction signals from self-heal — you approve, the system gets better |
+| **Self-evolving loop** | Weekly/monthly external research + local CI shepherd loop — you approve, the system gets better |
 
 ## How It Works
 
@@ -186,14 +186,14 @@ 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** | 2 (/sdlc, /setup) | 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 |
-| **Self-healing** | CI auto-fix + re-trigger | No | No |
+| **CI Shepherd** | Local CI fix loop | No | No |
 | **Auto-updates** | Weekly CC + community scan | No | No |
 | **Install** | `npx agentic-sdlc-wizard init` | npm install | npm install |
 | **Philosophy** | Lightweight, prove-it-or-delete | Scale and optimization | Documentation-first |
 
-**Our unique strengths:** Statistical rigor (CUSUM + 95% CI), SDP scoring (model quality vs SDLC compliance), self-healing CI, Prove-It A/B pipeline, comprehensive automated test suite, dogfooding enforcement.
+**Our unique strengths:** Statistical rigor (CUSUM + 95% CI), SDP scoring (model quality vs SDLC compliance), CI shepherd loop, Prove-It A/B pipeline, comprehensive automated test suite, dogfooding enforcement.
 
 **Where others are stronger:** everything-claude-code has broader language/framework coverage. claude-sdlc has webhook-driven automation. Both have npm distribution.
 
@@ -204,7 +204,7 @@ This isn't the only Claude Code SDLC tool. Here's an honest comparison:
 | Document | What It Covers |
 |----------|---------------|
 | [ARCHITECTURE.md](ARCHITECTURE.md) | System design, 5-layer diagram, data flows, file structure |
-| [CI_CD.md](CI_CD.md) | All 5 workflows, E2E scoring, tier system, SDP, integrity checks |
+| [CI_CD.md](CI_CD.md) | All 4 workflows, E2E scoring, tier system, SDP, integrity checks |
 | [SDLC.md](SDLC.md) | Version tracking, enforcement rules, SDLC configuration |
 | [TESTING.md](TESTING.md) | Testing philosophy, test diamond, TDD approach |
 | [CHANGELOG.md](CHANGELOG.md) | Version history, what changed and when |

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/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

@@ -19,6 +19,7 @@ TodoWrite([
   { content: "Find and read relevant documentation", status: "in_progress", activeForm: "Reading docs" },
   { content: "Assess doc health - flag issues (ask before cleaning)", status: "pending", activeForm: "Checking doc health" },
   { content: "DRY scan: What patterns exist to reuse? New pattern = get approval", status: "pending", activeForm: "Scanning for reusable patterns" },
+  { content: "Prove It Gate: adding new component? Research alternatives, prove quality with tests", status: "pending", activeForm: "Checking prove-it gate" },
   { content: "Blast radius: What depends on code I'm changing?", status: "pending", activeForm: "Checking dependencies" },
   { content: "Design system check (if UI change)", status: "pending", activeForm: "Checking design system" },
   { content: "Restate task in own words - verify understanding", status: "pending", activeForm: "Verifying understanding" },
@@ -84,6 +85,22 @@ Critical miss on `tdd_red` or `self_review` = process failure regardless of tota
 - Does test approach follow TESTING.md philosophies?
 - If introducing new test patterns, same scrutiny as code patterns
 
+## Prove It Gate (REQUIRED for New Additions)
+
+**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
+
+**Existence tests are NOT quality tests:**
+- BAD: "ci-analyzer skill file exists" — proves nothing about quality
+- GOOD: "ci-analyzer recommends lint-first when test-before-lint detected" — proves behavior
+
+**If you can't write a quality test for it, you can't prove it works, so don't add it.**
+
 ## Plan Mode Integration
 
 **Use plan mode for:** Multi-file changes, new features, LOW confidence, bugs needing investigation.
@@ -93,6 +110,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:
@@ -131,7 +161,7 @@ PLANNING -> DOCS -> TDD RED -> TDD GREEN -> Tests Pass -> Self-Review
 
 ## Cross-Model Review (If Configured)
 
-**When to run:** High-stakes changes (auth, payments, data handling), complex refactors, research-heavy work.
+**When to run:** High-stakes changes (auth, payments, data handling), releases/publishes (version bumps, CHANGELOG, npm publish), complex refactors, research-heavy work.
 **When to skip:** Trivial changes (typo fixes, config tweaks), time-sensitive hotfixes, risk < review cost.
 
 **Prerequisites:** Codex CLI installed (`npm i -g @openai/codex`), OpenAI API key set.
@@ -236,6 +266,43 @@ Self-review passes → handoff.json (round 1, PENDING_REVIEW)
 
 **Full protocol:** See the wizard's "Cross-Model Review Loop (Optional)" section for key flags and reasoning effort guidance.
 
+### Release Review Focus
+
+Before any release/publish, add these to `review_instructions`:
+- **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, use your judgment: pick the stronger argument, note why you chose it
+4. **Iterate until all approve** — Don't merge until every active reviewer is satisfied or their concerns are explicitly addressed
+5. **Max 3 iterations per reviewer** — If a reviewer keeps finding new things after 3 rounds, escalate to the user
+
+**The value of multiple reviewers:** Different models/humans catch different issues. Claude excels at SDLC/process compliance. Codex catches logic bugs. Humans catch "does this make sense for the product?" None alone is sufficient for high-stakes changes.
+
+### Custom Subagents (`.claude/agents/`)
+
+Claude Code supports custom subagents in `.claude/agents/`. These are specialized agents you can invoke for focused tasks:
+
+- **`sdlc-reviewer`** — An agent focused purely on SDLC compliance review (planning, TDD, self-review checks)
+- **`ci-debug`** — An agent specialized in diagnosing CI failures (reads logs, identifies root cause, suggests fix)
+- **`test-writer`** — An agent focused on writing quality tests following TESTING.md philosophies
+
+**When to use agents vs skills:**
+- **Skills** (`.claude/skills/`) — Prompts that guide Claude's behavior for a task type. Claude reads and follows them
+- **Agents** (`.claude/agents/`) — Independent subprocesses that run autonomously on a focused task and return results
+
+Agents are useful when you want parallel work (e.g., run `sdlc-reviewer` while you continue implementing) or when a task benefits from a fresh context window focused on one thing.
+
 ## Test Review (Harder Than Implementation)
 
 During self-review, critique tests HARDER than app code:
@@ -335,9 +402,38 @@ If tests fail:
 
 Debug it. Find root cause. Fix it properly. Tests ARE code.
 
+## 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. Write the fix
+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 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
+
+**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
+
+**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)
 
-**This is the "local shepherd" — the primary CI fix mechanism.** It runs in your active session with full context. The optional CI Auto-Fix bot (`.github/workflows/ci-autofix.yml`) is a fallback for unattended PRs only. When both are active, the bot detects your local pushes via SHA comparison and skips automatically.
+**This is the "local shepherd" — the CI fix mechanism.** It runs in your active session with full context.
 
 **The SDLC doesn't end at local tests.** CI must pass too.
 

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

@@ -1,17 +1,19 @@
 ---
 name: setup-wizard
-description: Setup wizard — scans codebase, asks 16 config questions, generates SDLC files (CLAUDE.md, SDLC.md, TESTING.md, ARCHITECTURE.md), verifies installation. Use for first-time setup or re-running setup.
+description: Setup wizard — scans codebase, builds confidence per data point, only asks what it can't figure out, generates SDLC files. Use for first-time setup or re-running setup.
 argument-hint: [optional: regenerate | verify-only]
 effort: high
 ---
-# Setup Wizard - Interactive Project Configuration
+# Setup Wizard - Confidence-Driven Project Configuration
 
 ## Task
 $ARGUMENTS
 
 ## Purpose
 
-You are an interactive setup wizard. Your job is to scan the project, ask the user ALL configuration questions, and generate the SDLC files. DO NOT skip questions. DO NOT make assumptions. The user's answers drive the output.
+You are a confidence-driven setup wizard. Your job is to scan the project, infer as much as possible, and only ask the user about what you can't figure out. The number of questions is DYNAMIC — it depends on how much you can detect. Stop asking when all configuration data points are resolved (detected, confirmed, or answered).
+
+**DO NOT ask a fixed list of questions. DO NOT ask what you already know.**
 
 ## MANDATORY FIRST ACTION: Read the Wizard Doc
 
@@ -35,57 +37,72 @@ 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_*)
+- Cache config (redis.conf, .env with REDIS_*)
+
+### Step 2: Build Confidence Map
+
+For each configuration data point, assign a confidence level based on scan results:
+
+**Configuration Data Points:**
 
-Present findings to the user in a clear summary with detected values.
+| Category | Data Point | How to Detect |
+|----------|-----------|---------------|
+| Structure | Source directory | Look for src/, app/, lib/, etc. |
+| Structure | Test directory | Look for tests/, __tests__/, spec/ |
+| Structure | Test framework | Config files (jest.config, vitest.config, pytest.ini) |
+| Commands | Lint command | package.json scripts, Makefile, config files |
+| Commands | Type-check command | tsconfig.json → tsc, mypy.ini → mypy |
+| Commands | Run all tests | package.json "test" script, Makefile |
+| Commands | Run single test file | Infer from framework (jest → jest path, pytest → pytest path) |
+| Commands | Production build | package.json "build" script, Makefile |
+| Commands | Deployment setup | Dockerfile, vercel.json, fly.toml, deploy scripts |
+| Infra | Database(s) | prisma/, .env DB vars, docker-compose services |
+| Infra | Caching layer | .env REDIS vars, docker-compose redis service |
+| Infra | Test duration | Count test files, check CI run times if available |
+| Preferences | Response detail level | Cannot detect — ALWAYS ASK |
+| Preferences | Testing approach | Cannot detect intent from existing code — ALWAYS ASK |
+| Preferences | Mocking philosophy | Cannot detect intent from existing code — ALWAYS ASK |
+| Testing | Test types | What test files exist (*.test.*, *.spec.*, e2e/, integration/) |
+| Coverage | Coverage config | nyc, c8, coverage.py config, CI coverage steps |
+| CI | CI shepherd opt-in | Only if CI detected — ALWAYS ASK |
 
-### Step 2: Ask ALL 17 Questions
+**Each data point has one of three states:**
+- **RESOLVED (detected):** Found concrete evidence — config file, script, directory exists. No question needed, just confirm.
+- **RESOLVED (inferred):** Found indirect evidence — naming patterns, related config. Present inference, let user confirm or correct.
+- **UNRESOLVED:** No evidence found — must ask user directly.
 
-Ask every question. Pre-fill detected values but let the user confirm or override.
+**Preference data points** (response detail, testing approach, mocking philosophy, CI shepherd) are ALWAYS UNRESOLVED regardless of what code patterns exist. Current code patterns show what IS, not what the user WANTS going forward.
 
-**Project Structure:**
-1. Source directory (detected or ask)
-2. Test directory (detected or ask)
-3. Test framework (detected or ask)
+### Step 3: Present Findings and Fill Gaps
 
-**Commands:**
-4. Lint command
-5. Type-check command
-6. Run all tests command
-7. Run single test file command
-8. Production build command
-9. Deployment setup (detected environments, confirm or customize)
+Present ALL detected values organized by state to the user.
 
-**Infrastructure:**
-10. Database(s) used
-11. Caching layer (Redis, etc.)
-12. Test duration (<1 min, 1-5 min, 5+ min)
+**For RESOLVED (detected) items:** Show what was found, let user bulk-confirm with a single "Looks good" or override specific items.
 
-**Output Preferences:**
-13. Response detail level (small/medium/large)
+**For RESOLVED (inferred) items:** Show what was inferred with reasoning, ask user to confirm or correct.
 
-**Testing Philosophy:**
-14. Testing approach (strict TDD, test-after, mixed, minimal, none yet)
-15. Test types wanted (unit, integration, E2E, API)
-16. Mocking philosophy (minimal, heavy, no mocking)
+**For UNRESOLVED items:** Ask the user directly — these are your questions.
 
-**Coverage:**
-17. Code coverage preferences (enforce threshold, report only, AI suggestions, skip)
+**The ready rule:** You are ready to generate files when ALL data points are resolved (detected, inferred+confirmed, or answered by user). The number of questions you ask depends entirely on how many data points remain unresolved after scanning. A well-configured project might need 3-4 questions (just preferences). A bare repo might need 10+. There is no fixed count.
 
-DO NOT proceed to file generation until ALL 17 questions have answers.
+DO NOT proceed to file generation until all data points are resolved.
 
-### Step 3: Generate CLAUDE.md
+### Step 4: Generate CLAUDE.md
 
-Using the user's answers, generate `CLAUDE.md` with:
+Using detected + confirmed values, generate `CLAUDE.md` with:
 - Project overview (from scan results)
-- Commands table (Q4-Q8 answers)
+- Commands table (detected/confirmed commands)
 - Code style section (from detected linters/formatters)
 - Architecture summary (from scan)
-- Special notes (from Q9-Q11)
+- Special notes (infra, deployment)
 
 Reference: See "Step 3" in `CLAUDE_CODE_SDLC_WIZARD.md` for the full template.
 
-### Step 4: Generate SDLC.md
+### Step 5: Generate SDLC.md
 
 Generate `SDLC.md` with the full SDLC checklist customized to the project:
 - Plan mode guidance
@@ -98,35 +115,35 @@ Include metadata comments:
 ```
 <!-- SDLC Wizard Version: [version from CLAUDE_CODE_SDLC_WIZARD.md] -->
 <!-- Setup Date: [today's date] -->
-<!-- Completed Steps: 0.4, 1-10 -->
+<!-- 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 -->
 ```
 
 Reference: See "Step 4" in `CLAUDE_CODE_SDLC_WIZARD.md` for the full template.
 
-### Step 5: Generate TESTING.md
+### Step 6: Generate TESTING.md
 
-Generate `TESTING.md` based on Q13-Q16 answers:
+Generate `TESTING.md` based on detected/confirmed testing data:
 - Testing Diamond visualization
 - Test types and their purposes
-- Mocking rules (from Q15)
-- Test file organization (from Q2, Q3)
-- Coverage config (from Q16)
+- Mocking rules (from detected patterns or user input)
+- Test file organization (from detected structure)
+- Coverage config (from detected config or user input)
 - Framework-specific patterns
 
 Reference: See "Step 5" in `CLAUDE_CODE_SDLC_WIZARD.md` for the full template.
 
-### Step 6: Generate ARCHITECTURE.md
+### Step 7: Generate ARCHITECTURE.md
 
 Generate `ARCHITECTURE.md` with:
 - System overview diagram (from scan)
 - Component descriptions
-- Environments table (from Q8.5)
+- Environments table (from detected deployment config)
 - Deployment checklist
 - Key technical decisions
 
 Reference: See "Step 6" in `CLAUDE_CODE_SDLC_WIZARD.md` for the full template.
 
-### Step 7: Generate DESIGN_SYSTEM.md (If UI Detected)
+### Step 8: Generate DESIGN_SYSTEM.md (If UI Detected)
 
 Only if design system artifacts were found in Step 1:
 - Extract colors, fonts, spacing from config
@@ -135,7 +152,17 @@ Only if design system artifacts were found in Step 1:
 
 Skip this step if no UI/design system detected.
 
-### Step 8: Configure Tool Permissions
+### 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 manager commands (npm, pnpm, yarn, cargo, go, pip, etc.)
@@ -144,11 +171,11 @@ Based on detected stack, suggest `allowedTools` entries for `.claude/settings.js
 
 Present suggestions and let the user confirm.
 
-### Step 9: Customize Hooks
+### Step 10: Customize Hooks
 
-Update `tdd-pretool-check.sh` with the actual source directory from Q1 (replace generic `/src/` pattern).
+Update `tdd-pretool-check.sh` with the actual source directory (replace generic `/src/` pattern).
 
-### Step 10: Verify Setup
+### Step 11: Verify Setup
 
 Run verification checks:
 1. All generated files exist and are non-empty
@@ -159,20 +186,24 @@ Run verification checks:
 
 Report any issues found.
 
-### Step 11: Instruct Restart and Next Steps
+### Step 12: Instruct Restart and Next Steps
 
 Tell the user:
 > Setup complete. Hooks and settings load at session start.
 > **Exit Claude Code and restart it** for the new configuration to take effect.
 > On restart, the SDLC hook will fire and you'll see the checklist in every response.
 >
-> **Optional next step:** Run `/claude-automation-recommender` for stack-specific tooling suggestions (MCP servers, formatting hooks, type-checking hooks, plugins). These are complementary to the SDLC wizard — they add per-stack tooling, not process enforcement.
+> **Optional next step:**
+> - Run `/claude-automation-recommender` for stack-specific tooling suggestions (MCP servers, formatting hooks, type-checking hooks, plugins)
+>
+> The recommender is complementary to the SDLC wizard — it adds tooling recommendations, not process enforcement.
 
 ## Rules
 
-- NEVER skip a question. If the user says "I don't know", record that and move on.
-- NEVER assume answers. If auto-scan can't detect something, ASK.
-- ALWAYS show detected values and let the user confirm or override.
+- NEVER ask what you already know from scanning. If you found it, confirm it — don't ask it.
+- NEVER use a fixed question count. The number of questions is dynamic based on scan results.
+- ALWAYS show detected values organized by resolution state and let the user confirm or override.
 - ALWAYS generate metadata comments in SDLC.md (version, date, steps).
+- If most data points are resolved after scanning, present findings for bulk confirmation — don't force individual questions.
 - If the user passes `regenerate` as an argument, skip Q&A and regenerate files from existing SDLC.md metadata.
-- If the user passes `verify-only` as an argument, skip to Step 10 (verify) only.
+- If the user passes `verify-only` as an argument, skip to Step 11 (verify) only.

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

@@ -45,13 +45,13 @@ 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.15.0
-Latest:    1.20.0
+Installed: 1.20.0
+Latest:    1.22.0
 
 What changed:
+- [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, ...
-- [1.18.0] Added /update-wizard skill, ...
 ```
 
 **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.20.0",
+  "version": "1.22.0",
   "description": "SDLC enforcement for Claude Code — hooks, skills, and wizard setup in one command",
   "bin": {
     "sdlc-wizard": "./cli/bin/sdlc-wizard.js"