agentic-sdlc-wizard 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -418,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:
@@ -1773,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:
@@ -1927,6 +1942,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 +2041,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 +2401,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.21.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] -->
@@ -2455,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)
@@ -3217,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.21.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

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

@@ -110,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:
@@ -264,6 +277,32 @@ 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. 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:
@@ -363,6 +402,35 @@ 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 CI fix mechanism.** It runs in your active session with full context.

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,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.19.0
-Latest:    1.21.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, ...
 ```
 
 **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.22.0",
   "description": "SDLC enforcement for Claude Code — hooks, skills, and wizard setup in one command",
   "bin": {
     "sdlc-wizard": "./cli/bin/sdlc-wizard.js"