agentic-sdlc-wizard 1.81.0 → 1.82.0

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.81.0",
+      "version": "1.82.0",
       "author": {
         "name": "Stefan Ayala"
       },

package/.claude-plugin/plugin.json

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

package/AI_SETUP_LANES.md

@@ -15,6 +15,8 @@ This is **guidance, not a hard rule**. Maintainer override is always allowed.
 
 Quality-first lane. Fable 5 advises automatically at key decision points (architecture, complexity, blast-radius) via native `advisorModel` (v2.1.170+), Opus 4.6 max implements (stable, Max-bundled), GPT-5.5 xhigh reviews (cross-family, free on ChatGPT sub, catches blind spots Fable can't see in its own work). Escalate to Fable review for the ~5% of PRs where stakes justify it.
 
+**Effort levels:** Opus driver at `max` (standing default). Fable advisor runs at its own effort level server-side. If switching driver to Fable temporarily (fallback), use `/effort high` — Fable `high` already exceeds prior models at `max`. Unset `CLAUDE_CODE_EFFORT_LEVEL` env var if it forces `max`.
+
 ## Setup B — Claude Saver (OpusPlan)
 
 | Role | Model |
@@ -105,6 +107,25 @@ The `!` prefix runs shell commands inside your CC session — no need to exit an
 
 Fable 5 as advisor also requires Fable 5 access for your organization/plan (free on Max through June 22, 2026).
 
+## When the Advisor Is Unavailable
+
+If the advisor returns "Advisor unavailable," the server-side harness failed to initialize. No in-session action (`/model`, `/clear`) can recover it.
+
+**Step 1 — restart the session.** Exit and run `claude` (not `--resume`). A fresh process re-initializes the server handshake. This resolves most advisor failures.
+
+**Step 2 — if the API incident persists:**
+
+- `/model fable` + `/effort high` for the planning phase, then `/model claude-opus-4-6` for implementation. Interactive — stays on your Max subscription.
+- Or proceed with Opus only and let the Codex xhigh PR gate catch issues.
+
+**Last resort (scripted/CI only):**
+
+- `claude --model fable --effort high -p "$(cat <file>)"` — headless mode bills API credits, not your Max subscription.
+
+Check [status.claude.com](https://status.claude.com) if the advisor fails across multiple fresh sessions.
+
+Whichever path you use, the cross-model PR review gate still applies.
+
 ## Credit-Spend Warning
 
 Setups A and B use Opus 4.6 max for at least the planner — that's the expensive half. On Max-plan subscriptions, **Premium can burn the 5-hour cap faster than Saver** because Opus 4.6 max drives implementation too. If you're hitting the cap mid-session:
@@ -117,6 +138,10 @@ Setups A and B use Opus 4.6 max for at least the planner — that's the expensiv
 
 The reviewer (GPT-5.5 xhigh) is billed against your OpenAI account, separately. Watch both bills.
 
+## Autocompact Thresholds
+
+For recommended `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` values per context window and task shape, see [CLAUDE_CODE_SDLC_WIZARD.md → Autocompact Tuning](CLAUDE_CODE_SDLC_WIZARD.md#autocompact-tuning).
+
 ## How Billing Works — 1M Context, Max Plan, and the June 15 Split
 
 A common question: **"does the `[1m]` model alias get billed differently? Does it pull from my Max plan or from API credits?"**

package/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.82.0] - 2026-06-11
+
+### Added
+
+- **"Reading Usage Signals" subsection** in Token Efficiency section. Maps community-observed session signals (subagent-heavy, >150K context, 8+ hour sessions) to SDLC actions per setup lane. Marked as community-observed, not official CC docs.
+
+- **Advisor fallback procedure** in AI_SETUP_LANES.md. Escalation ladder: restart session → Fable driver fallback → `-p` last resort (with billing caveat). Documented after advisor was unavailable for a full session during API incident (2026-06-11).
+
+- **Fable effort guidance** in Setup A description. Opus stays at `max`; Fable at `high` (exceeds prior models at `max`). Unset `CLAUDE_CODE_EFFORT_LEVEL` env var if switching driver to Fable temporarily.
+
+- **Autocompact Thresholds cross-reference** in AI_SETUP_LANES.md. Numbers-free pointer to wizard doc to prevent dual-source drift.
+
+### Fixed
+
+- **Stale `/usage` row** in Monitor Costs table. Was "Session total: USD, API time, code changes" — now accurately describes plan usage limits and per-category breakdown (skill, subagent, plugin, MCP server). Added `/status` row (settings panel) to prevent future confusion.
+
+- **`/usage` mention in SKILL.md** Context Management section. Folded into existing auto-compact bullet within 20K char budget.
+
+### Why
+
+- Token-burn spike (1.36M costly tokens vs ~86K median) in session 98d6c7b0 surfaced that the wizard's usage guidance was stale and didn't help diagnose the cause. The Monitor Costs table described `/usage` incorrectly, and no wizard prose mapped usage signals to SDLC actions. The advisor fallback procedure is a direct lesson from the same session where the Fable advisor was unavailable for the entire duration.
+
 ## [1.81.0] - 2026-06-10
 
 ### Changed

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -3041,7 +3041,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.81.0 -->
+<!-- SDLC Wizard Version: 1.82.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] -->
@@ -3691,10 +3691,21 @@ Practical techniques to reduce token consumption without sacrificing quality.
 
 | Tool | What It Shows | When to Use |
 |------|---------------|-------------|
-| `/usage` | Session total: USD, API time, code changes (aliases: `/cost`, `/stats`) | After a session to review spend |
+| `/usage` | Session cost, plan usage limits, and per-category breakdown (skill, subagent, plugin, MCP server). Aliases: `/cost`, `/stats` | After heavy subagent work, before/after workflow runs, when approaching rate limits |
+| `/status` | Settings panel — version, model, account, connectivity | Confirm setup before starting work |
 | `/context` | What's consuming context window space | When hitting context limits |
 | Status line | Real-time `cost.total_cost_usd` + token counts | Continuous monitoring |
 
+### Reading Usage Signals
+
+These signals are community-observed behavior on paid plans (Max/Team) — not in official CC docs. They are independent dimensions, not a single breakdown. A single session can contribute to all three. Run `/usage` to see the per-category breakdown.
+
+| Signal | What It Means | SDLC Action |
+|--------|---------------|-------------|
+| **Subagent-heavy** | Each subagent runs its own context. The advisor is a separate server-side consultation (full transcript forwarded, different token profile). Explore agents, full Agent delegates, and workflow agents each spawn separate contexts. | Expected in Setup A (Fable advisor fires per-decision). If unexpectedly high: use `subagent_type: "Explore"` for search (lighter), reserve full agents for implementation. |
+| **>150K context** | Sessions staying large between compactions. | **Context-window dependent.** On 1M (Setup A): >150K is expected at 30% compact threshold — the real question is whether the task needed 1M headroom. On 200K (Setup B/C): lower `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` toward 75%. `/compact` between planning and implementation. |
+| **8+ hour sessions** | Long-running sessions accumulate stale context. | `/clear` between unrelated tasks. Split multi-feature work into separate sessions. After committing a PR, start fresh. Background `/loop` sessions count toward this — audit which are still needed. |
+
 ### Reduce Consumption
 
 | Technique | Savings | How |

package/package.json

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

package/skills/sdlc/SKILL.md

@@ -267,7 +267,7 @@ Don't fix only the symptom. Add a gate so it can't happen again. Example: PR #14
 
 - `/compact` between planning and implementation (plan preserved in summary)
 - `/clear` between unrelated tasks; after 2+ failed corrections (context polluted)
-- Auto-compact fires at ~95% capacity
+- Auto-compact fires at ~95%; `/usage` shows what's driving token spend
 - After committing a PR, `/clear` before next feature
 - `--bare` mode (v2.1.81+) skips ALL hooks/skills/LSP/plugins. Scripted headless only — never normal development.
 - Custom subagents (`.claude/agents/`) run autonomously and return results. Skills guide behavior; agents do work. Use for parallel tasks or fresh context. Examples: `sdlc-reviewer`, `ci-debug`, `test-writer`.

package/skills/update/SKILL.md

@@ -93,9 +93,10 @@ Parse CHANGELOG entries between the user's installed version and latest. Present
 
 ```
 Installed: 1.42.0
-Latest:    1.81.0
+Latest:    1.82.0
 
 What changed:
+- [1.82.0] Usage diagnostics: fix /usage row, Reading Usage Signals guide, advisor fallback procedure, Fable effort guidance, autocompact cross-reference.
 - [1.81.0] Native `advisorModel` support: Setup A gets Fable advisor, Setup B gets Opus advisor. Replaces manual subagent spawning. Requires CC v2.1.170+.
 - [1.80.0] Flip default: Opus 4.6 max becomes recommended flagship; Opus 4.8 demoted to opt-in `[l] Latest` tier.
 - [1.79.0] Opus 4.6 Stability tier added as flagship alternative (now graduated to default in 1.80.0).