agentic-sdlc-wizard 1.41.0 → 1.42.1

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "sdlc-wizard",
       "source": ".",
       "description": "SDLC enforcement for AI agents — TDD, planning, self-review, CI shepherd",
-      "version": "1.41.0",
+      "version": "1.42.1",
       "author": {
         "name": "Stefan Ayala"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sdlc-wizard",
-  "version": "1.41.0",
+  "version": "1.42.1",
   "description": "SDLC enforcement for AI agents — TDD, planning, self-review, CI shepherd",
   "author": {
     "name": "Stefan Ayala",

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.42.1] - 2026-04-26
+
+### Fixed
+
+- **Skip Claude PR review on wizard self-PRs** (CI hygiene). The `review` job in `pr-review.yml` calls `claude-code-action@v1` which requires `ANTHROPIC_API_KEY` with positive credit balance. The wizard maintainer keeps that key's balance dead as an "API canary" so unexpected API draws fail CI. Result: every wizard self-PR's `review` job was failing with "Credit balance is too low" — seven PRs (v1.39.0–v1.42.0) shipped to main with red CI, normalizing red and masking any real review failure. Fixed: workflow `if:` gate now skips the review job when `github.repository == 'BaseInfinity/claude-sdlc-wizard'`. Consumer projects using `pr-review.yml` are unaffected — the skip only fires on the wizard's own repo. The wizard uses Codex (`codex exec` xhigh) for cross-model review on its own PRs, so the Claude PR review is redundant on self-repo. Documented in `CI_CD.md` → "Self-PR Skip on the Wizard Repo". New `tests/test-self-pr-review-skip.sh` (6 tests) prevents regression.
+
+## [1.42.0] - 2026-04-26
+
+### Added
+
+- **AGENTS.md interop detection in setup** (ROADMAP #205, phase a). Setup wizard now scans for `AGENTS.md` (cross-tool agent-instructions standard adopted by Cursor/Continue.dev/Aider, [CC issue #6235](https://github.com/anthropics/claude-code/issues/6235)) during Step 1 auto-scan. If found, new Step 4.5 surfaces a 3-way decision: dual-maintain (default), merge (manual in phase a), or skip. The choice is recorded as a one-line comment in the project's `SDLC.md` for the user's reference — `/update-wizard` does NOT yet parse this metadata (phase d). No wizard-side merge or symlink behavior in v1.42.0 — option B in the prompt is "record intent, copy by hand"; phase (b) will add the copy helper. Phase (d) drift-consistency test also deferred. New `tests/test-agents-md-interop.sh` (7 tests) asserts setup auto-scan, decision step structure, wizard doc reference + phase-scope honesty.
+
+## [1.41.1] - 2026-04-26
+
+### Added
+
+- **MCP-tool hooks audit documented** (ROADMAP #218). CC 2.1.118 introduced `type: "mcp_tool"` for hooks. Audited all 5 wizard hooks (sdlc-prompt-check, instructions-loaded-check, tdd-pretool-check, model-effort-check, precompact-seam-check) against MCP-tool migration criteria: portability, gating semantics, cross-tool state. Conclusion: all 5 stay bash. Per-hook rationale documented in CLAUDE_CODE_SDLC_WIZARD.md → "Known CC Gotchas → MCP-tool hooks audit". New `tests/test-mcp-hook-audit.sh` (7 tests) ensures the audit doesn't get re-litigated by future maintainers; if a hook DOES migrate later, the test is the natural place to update with new rationale.
+
 ## [1.41.0] - 2026-04-26
 
 ### Added

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -353,6 +353,22 @@ Claude Code now has built-in auto-memory that persists context across sessions.
 
 **No changes needed**: The wizard's hooks and skills work alongside auto-memory. Memory stores preferences and context; the wizard enforces process.
 
+### AGENTS.md interop (cross-tool standard, ROADMAP #205)
+
+`AGENTS.md` is the cross-tool agent-instructions standard adopted by Cursor, Continue.dev, Aider, and other agentic IDEs ([CC issue #6235](https://github.com/anthropics/claude-code/issues/6235), 276 comments). It plays the same role as `CLAUDE.md` does for Claude Code, but reads as agent-agnostic.
+
+**Wizard behavior** (v1.42.0, phase a only):
+
+- **Setup skill detects existing AGENTS.md** during Step 1 auto-scan. If found, Step 4.5 surfaces a 3-way decision: dual-maintain (default, recommended), merge (manual in phase a), or skip. The user's choice is recorded as a one-line comment in their project's `SDLC.md` for their own reference. **`/update-wizard` does NOT parse this comment** — that wiring is phase (d) work, not v1.42.0 scope.
+- **No automatic merge / symlink yet** — phase (a) is detection + decision surfacing only. Option B in the prompt is "record your intent, do the copy by hand"; the wizard does not perform any merge in this phase.
+
+**Deferred phases** (not in v1.42.0 scope):
+
+- **Phase (b)**: when generating `CLAUDE.md` fresh (no AGENTS.md exists), offer to ALSO write AGENTS.md (symlinked or content-duplicated). Requires choosing a sync strategy.
+- **Phase (d)**: cross-document-consistency drift test — fail CI if `CLAUDE.md` and `AGENTS.md` drift apart on key sections (Commands, Architecture, etc.).
+
+**Why phase (a) only**: phase (a) ships detection signal value with zero new merge logic. The dual-maintain decision is reversible per-project; users who pick A get a sensible default and can opt up to phase (b) when it ships. Multi-tool sync is a real engineering problem (which file is source of truth? on edit, propagate which way?) that deserves its own design pass before automating.
+
 ### Built-in Commands (v2.1.59-v2.1.76)
 
 New built-in commands available to use alongside the wizard:
@@ -469,6 +485,32 @@ The same post-mortem documented that a length-limit prompt change (one of severa
 
 See the dedicated subsection under [Tasks System](#tasks-system-v2116) (above, in Claude Code Feature Updates) for the full breakdown. Short version: pin `cleanupPeriodDays: 30` or higher in `.claude/settings.json` if you ever pause SDLC work for more than a week. The wizard ships this default in `cli/templates/settings.json` and the CLI's smart-merge preserves user overrides on `init --force`.
 
+### MCP-tool hooks audit (ROADMAP #218, CC 2.1.118)
+
+CC 2.1.118 introduced `type: "mcp_tool"` for hooks — a hook can now directly invoke an MCP tool instead of running a bash script. **Audit (2026-04-26) of all 5 wizard hooks concluded: none migrate, all stay bash.** This subsection documents the per-hook reasoning so future audits don't redo the work; if a future PR migrates a hook to MCP, update this entry with the new rationale rather than deleting it.
+
+**Decision criteria applied** (any one rules out MCP):
+
+1. **Portability** — bash hooks port to the **shipped** Codex sibling (`~/codex-sdlc-wizard`) and to a **planned** OpenCode sibling (ROADMAP #91, not yet shipped) without rewrite. MCP hooks are CC-specific. Cross-host portability is an XDLC requirement.
+2. **Fail-closed gating** — hooks that block an action (exit 2 from PreCompact) need a fail-closed contract: any error in the hook MUST keep the block in place. CC docs ([code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks)) confirm `mcp_tool` hooks CAN gate via `decision: "block"` JSON output, but **MCP server errors are non-blocking by design** — if the MCP server is down/slow/buggy, the action proceeds. That breaks the fail-closed contract. Bash exit 2 fails closed.
+3. **Local-only state** — hooks that read/write `~/.cache/sdlc-wizard/` or `.reviews/handoff.json` don't surface state across tool boundaries. MCP adds a wire format without consumers.
+
+**Per-hook decision** (each row applies at least one criterion explicitly):
+
+- **`sdlc-prompt-check.sh`** (UserPromptSubmit, ~132 lines) — emits the SDLC BASELINE text on every prompt; writes effort-bump signals to `~/.cache/sdlc-wizard/effort-signals.log` for self-consumption on next invocation. Decision: **Stay bash.** Portability criterion: same script ships to Codex sibling unchanged. Local-state criterion: signal log is local-only.
+- **`instructions-loaded-check.sh`** (~202 lines) — InstructionsLoaded event; validates SDLC files exist, fetches npm `latest` with daily file cache (`~/.cache/sdlc-wizard/npm-latest.json`), emits staleness warnings. Decision: **Stay bash.** Portability criterion: Codex sibling has its own equivalent of session-start validation; bash port is direct. Local-state criterion: cache file is local.
+- **`tdd-pretool-check.sh`** (~29 lines) — PreToolUse on Write/Edit/MultiEdit; emits the TDD reminder text. Decision: **Stay bash.** Portability criterion: trivially portable (one-screen text emit). Gating criterion: not applicable (this hook does not block, it advises). MCP would add a runtime dependency for zero functional gain.
+- **`model-effort-check.sh`** (~69 lines) — SessionStart event; reads `CLAUDE_CODE_EFFORT` env var, emits silent/soft/loud nudge per-tier. Decision: **Stay bash.** Portability criterion: env-var read maps 1:1 to any agent runtime. Local-state criterion: not applicable, hook is stateless.
+- **`precompact-seam-check.sh`** (~125 lines) — PreCompact event (matcher: `manual`); reads `.reviews/handoff.json` via jq, blocks manual `/compact` with exit 2 + stderr message when status is `PENDING_*` and the linked PR (if any) isn't merged. Decision: **Stay bash.** Fail-closed gating criterion: bash exit 2 fails closed by definition; an MCP `mcp_tool` hook returning `decision: "block"` works on the happy path, but if the MCP server crashes/times out the action proceeds — that flips the safety property from fail-closed to fail-open. For a hook whose entire job is to prevent context loss at bad seams, fail-open is the wrong default.
+
+**When to revisit this audit:**
+
+- A future hook genuinely needs cross-tool structured state surfacing (e.g., a "score history reader" that an MCP-aware skill consumes directly).
+- Anthropic deprecates bash hooks in favor of `mcp_tool` (currently both are first-class).
+- Codex / OpenCode siblings gain native MCP-tool hook support (then portability is no longer an MCP-rules-out).
+
+Until then, default answer for new hooks is bash.
+
 ---
 
 ## Prove It's Better
@@ -2874,7 +2916,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.41.0 -->
+<!-- SDLC Wizard Version: 1.42.1 -->
 <!-- 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] -->
@@ -3936,7 +3978,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.41.0 -->
+<!-- SDLC Wizard Version: 1.42.1 -->
 <!-- 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/package.json

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

package/skills/setup/SKILL.md

@@ -38,7 +38,7 @@ Scan the project root for:
 - 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
+- Existing docs: README.md, CLAUDE.md, ARCHITECTURE.md, AGENTS.md (cross-tool agent-instructions standard, ROADMAP #205)
 - 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_*)
@@ -108,6 +108,34 @@ Using detected + confirmed values, generate `CLAUDE.md` with:
 
 Reference: See "Step 8" in `CLAUDE_CODE_SDLC_WIZARD.md` for the full template.
 
+### Step 4.5: AGENTS.md Interop Detection (ROADMAP #205, phase a)
+
+`AGENTS.md` is the cross-tool agent-instructions file converged on by Cursor, Continue.dev, Aider, and other agentic IDEs (CC issue #6235, 276 comments). If the user already has `AGENTS.md` in the repo, the wizard's `CLAUDE.md` overlaps in scope; ignoring it leads to drift between the two files.
+
+**Detection** (already in Step 1's auto-scan): does `./AGENTS.md` exist?
+
+**If YES, surface the dual-maintain decision:**
+
+> Detected `AGENTS.md` (cross-tool agent-instructions standard, used by Cursor/Continue.dev/Aider). The wizard's `CLAUDE.md` covers the same ground for Claude Code. Three options:
+>
+> **A.** **Dual-maintain (recommended)**: keep both files. `CLAUDE.md` for Claude Code (loaded into every session), `AGENTS.md` for other tools. Sync manually when changing one — phase (a) does not auto-merge. Future work (phase d) will add a drift-consistency test.
+>
+> **B.** **Merge** (manual in phase a): record your intent to converge on a single source of truth. The wizard does NOT copy content for you in v1.42.0 — phase (b) will add the copy/symlink helper. For now, pick this if you plan to merge by hand and just want the wizard to know.
+>
+> **C.** **Skip**: leave AGENTS.md alone. The wizard generates only `CLAUDE.md`. AGENTS.md will go stale relative to your CC-specific instructions.
+>
+> Pick A, B, or C: `[A/B/C]`
+
+Default if no response: **A** (dual-maintain). Document the user's choice as a one-line comment in their project's `SDLC.md` (e.g. `<!-- AGENTS.md interop: dual-maintain (per ROADMAP #205 phase a) -->`). v1.42.0 does NOT teach `/update-wizard` to parse this metadata key — that's phase (d) work. The comment is for the user's own reference and for whatever future `/update-wizard` version adds AGENTS-aware behavior.
+
+**If NO `AGENTS.md` exists**: skip this step silently. Phase (b) of #205 (offer to ALSO generate AGENTS.md alongside CLAUDE.md) is deferred — not in v1.42.0 scope.
+
+**Phase scope honest summary**:
+- Phase (a) — DONE in v1.42.0: detection + decision surfacing only.
+- Phase (b) — deferred: write/symlink AGENTS.md when generating CLAUDE.md fresh.
+- Phase (c) — partial: this step IS the setup-skill update.
+- Phase (d) — deferred: cross-document-consistency drift test.
+
 ### Step 5: Generate SDLC.md
 
 Generate `SDLC.md` with the full SDLC checklist customized to the project:

package/skills/update/SKILL.md

@@ -131,9 +131,12 @@ Parse all CHANGELOG entries between the user's installed version and the latest.
 
 ```
 Installed: 1.24.0
-Latest:    1.41.0
+Latest:    1.42.1
 
 What changed:
+- [1.42.1] CI hygiene fix — skip Claude PR review on wizard self-PRs. 7 self-PRs (v1.39.0–v1.42.0) had shipped with red `review` job (API canary firing on dead credit balance). Treated as "expected" but red normalizes red. Workflow `if:` now skips review on `BaseInfinity/claude-sdlc-wizard` repo only; consumer projects unaffected. 7 quality tests, mutation-verified (== inversion fails).
+- [1.42.0] AGENTS.md interop detection — ROADMAP #205 phase (a). Setup wizard auto-scan now lists AGENTS.md (cross-tool agent-instructions standard, CC issue #6235); new Step 4.5 surfaces a 3-way decision (dual-maintain / merge / skip) when AGENTS.md is detected. Phase (b) write-fresh and phase (d) drift-test deferred. 7 quality tests.
+- [1.41.1] MCP-tool hooks audit — ROADMAP #218. Audited all 5 wizard hooks against CC 2.1.118's `type: "mcp_tool"` migration option; conclusion: all stay bash (portability to Codex/OpenCode siblings + exit-code gating semantics rule out MCP). Per-hook rationale documented under "Known CC Gotchas → MCP-tool hooks audit". 7 quality tests.
 - [1.41.0] Post-mortem 2026-04-23 lessons folded into wizard — ROADMAP #221. New "Known CC Gotchas" section documents extended-thinking + caching + idle-session failure mode. Recommended Effort section cites the post-mortem as third-party evidence ("don't rely on CC default — set effort yourself"). Brevity-cap audit clean, regression guard added. 7 quality tests.
 - [1.40.1] cleanupPeriodDays: 30 pinned in template — ROADMAP #225. CC 2.1.117 expanded `cleanupPeriodDays` to also cover `~/.claude/tasks/`. Aggressive defaults could prune in-progress TodoWrite checklists for paused long-running features. Wizard now ships a 30-day floor + documented gotcha. 7 quality tests.
 - [1.40.0] CLI version detection in /update-wizard — ROADMAP #232. New Step 1.5 detects locally installed `agentic-sdlc-wizard` CLI version (npm ls + npx cache inspection, both with semver-aware ordering), compares to `registry.npmjs.org/agentic-sdlc-wizard/latest`, and surfaces a 3-way upgrade choice BEFORE drift detection: A) refresh CLI cache only (default, safest), B) `init --force` re-init with explicit non-settings overwrite warning, C) skip. Closes the gap where in-session file updates landed but the user's stale npx cache kept running an old CLI. Mirrors `claude update` UX. 8 quality tests, mutation-verified.