v6.3.0

v6.3.0 (2026-04-03)

Session memory quality pass: the stop-reminders hook now tracks undocumented work phases across long sessions, enforced token budgets prevent session-log bloat from inflating injection costs, and parallel dispatch defaults are corrected in two skills.

New Features

Phase-aware decision-log reminders — The stop-reminders hook previously asked "were significant files edited in the last 30 minutes?" — a window that fails in long sessions with multiple work phases (same edits stay in the window after a [saved] entry, while later phases can slip out entirely). It now asks "were significant files edited since the last [saved] entry?" The track-edits hook detects when a [saved] entry is written to session-log.md and records a timestamp marker; stop-reminders reads that marker at Stop time. Each logical work batch gets exactly one reminder at the right time, with no false positives between phases.

Session-log token budget guard — stop-reminders now measures the last 2 [saved] entries at every session Stop and warns when any entry exceeds the 250-token budget (~1,000 characters). These entries are injected into every future session; a bloated entry costs tokens forever. The warning identifies the specific over-budget entry and instructs what to trim.

Strict [saved] entry template in context-management — The context-management skill's [saved] entry template now has an explicit structure (Goal / Decisions / Rejected / Open only), a "Never include" list (test results, task checklists → state.md, how-it-works walkthroughs, speculative analysis → design docs, one-time confirmations), and a hard token budget. Without this enforcement, the AI defaulted to "more is safer" and wrote entries that were 5–10× over the optimal size.

dispatching-parallel-agents skill hint added — skill-rules.json now includes a rule for dispatching-parallel-agents — it was the only skill with no hint coverage, meaning prompts like "dispatch these tasks simultaneously" received no routing suggestion.

Changes

Parallel Waves is now the default in subagent-driven-development — "Parallel Waves" was previously labeled "Optional Speed Mode". It is now the stated default for independent tasks; sequential execution is the explicit fallback for tasks with shared-file or state dependencies. The single-message dispatch requirement is now explicit in both subagent-driven-development and dispatching-parallel-agents, with a rationale: all subagents share the same cached system prompt prefix, and dispatching them in one message ensures every agent gets a cache hit on the heavy shared prefix.

Anti-sycophancy rules added to global CLAUDE.md — Four rules now govern position stability: don't revise a stated position under pushback without new evidence; proactively state the strongest objection to any non-trivial proposal; agreement must cite a specific reason, not just affirm; state confidence level explicitly when uncertain.

v6.2.0

Cross-session memory overhaul: the full memory stack is now injected automatically at session start, stop-reminders actually writes to session-log.md, and agents can no longer waste tokens as content relays.

New Features

Full memory stack injected at session start — session-log.md (last 2 [saved] decisions), state.md (active task snapshot), known-issues.md (error map), and context-snapshot.json (changed files + recent commits) are now all injected into session context by the session-start hook — unconditionally, without requiring the AI to remember to read them. Previously only project-map.md was injected; the rest depended entirely on AI compliance with the entry sequence.

Decision-log reminder in stop-reminders — When the session modified SKILL.md files, hooks, or plugin config, the Stop hook now surfaces an explicit prompt to invoke context-management before ending the session. These are the sessions where the "why" matters most and is most likely to be lost.

Changes

Agent & External Content Rules added to token-efficiency — Five new rules cover the behavioral characteristics of the Agent tool and WebFetch that the AI previously had to discover by failure: agent results are always compressed on return (never use agents as content relays), WebFetch returns AI summaries not raw text (use curl -sf for verbatim URL content), and local files should always be Read directly. These rules are always-on from session start.

"When the User Names a Specific Skill" section added to using-superpowers — Clarifies that phrases like "use brainstorming" or "use context management" are Skill tool invocations, not conceptual goals to achieve ad-hoc. This was the root cause of entry sequence bypass in analyzed session transcripts: the AI improvised with agents instead of calling the Skill tool.

Mandatory first actions surfaced at injection point — The session-start hook now prepends three concrete steps before the full using-superpowers body: activate token-efficiency, classify complexity, and invoke named skills via the Skill tool. Previously these were buried in the skill text where they competed with everything else for attention.

Content-relay anti-pattern added to dispatching-parallel-agents — "The task is content relay" is now an explicit entry in the "Do not use when" list, with a one-line explanation: agent results are compressed, raw content will be lost.

using-superpowers step 4 extended — Now requires a [saved] entry at the end of any session where significant decisions were made, not just sessions with ongoing incomplete work.

known-issues.md added to auto-gitignore list — track-edits.js now includes known-issues.md in the AI_ARTIFACTS list so it is automatically added to .gitignore on first write.

Fixes

stop-reminders.js never wrote to session-log.md — The hook was documented as "auto-writes session-log.md [auto] entry" but only wrote to a private temp file at ~/.claude/hooks-logs/edit-log.txt. The [auto] entries visible in prior session logs were written manually by the AI. Fixed: the hook now writes a proper [auto] entry to session-log.md in the project root on session stop, gated by the existing 2-minute guard to prevent duplicates.

MANDATORY FIRST ACTIONS had invalid JSON — The preamble added in the previous session contained literal unescaped double-quotes ("use brainstorming") inside the bash string that produced the hook's JSON output. This caused JSON.parse failures on every session start for any platform that validated the JSON. Fixed by removing the quotes from the example text.

v6.1.0

v6.1.0 (2026-03-28)

Skill quality pass: two new automated review gates, richer subagent prompts, sharper stop conditions, and a fix to the project-map staleness loop.

New Features

Spec reviewer gate in brainstorming — After a design is approved and saved, brainstorming now dispatches a spec-reviewer subagent using a calibrated prompt template (spec-document-reviewer-prompt.md) before handing off to writing-plans. The reviewer checks for placeholders, internal contradictions, ambiguous requirements, and scope creep. Critical issues block the handoff; minor issues become advisory recommendations. This catches design gaps before they propagate into the plan.

Plan reviewer gate in writing-plans — writing-plans now dispatches a plan-reviewer subagent using plan-document-reviewer-prompt.md after the plan is saved. The reviewer cross-checks the plan against the original spec — not just the plan in isolation — catching scope drift, vague steps, missing file paths, and incorrect TDD ordering. Both reviewer prompts include skill leakage prevention to keep subagents focused.

Changes

dispatching-parallel-agents strengthened — Added a "Do not use when" block covering exploratory debugging, related failures, and shared-state scenarios. Added an assembled example prompt showing all required fields (scope, goal, constraints, output format, leakage prevention) wired together. Added a ❌/✅ common mistakes section. Updated the description to "2+" (more precise than "multiple") and added "sequential dependencies" as an explicit disqualifier alongside file and state conflicts.

executing-plans stop conditions expanded — The single "stop on repeated verification failures" bullet is replaced with a named list: missing dependency, plan gap preventing start, unclear/contradictory instruction, repeated verification failure. Added "never guess — ask for clarification" as an explicit directive. Added the main/master branch prohibition with a reference to the worktree step.

claude-md-creator self-assesses redundancy — The skill no longer asks the user "anything you'd cut?" It now applies the redundancy filter itself before presenting the draft: every line must pass "would the agent produce incorrect output without this?" Lines that don't survive the filter are cut before the user sees them.

PR description required in finishing-a-development-branch — Option 2 (push + open PR) now requires a structured description: what changed, why, how to verify, and notable decisions. Previously the skill just said "Create PR" with no guidance on content.

Worktree path persistence clarified — using-git-worktrees now explicitly states that the cd in the creation step does not persist across separate shell calls, and that all subsequent commands must use the full worktree path or cd && inline.

find-polluter.sh surfaced for test pollution — systematic-debugging Phase 1 now references the find-polluter.sh script for tests that fail only in certain orderings. Previously the script existed in the skill folder but was never mentioned in the skill itself.

Fixes

project-map.md staleness loop fixed — The staleness check in using-superpowers entry sequence step 6 detected stale map entries and re-read changed files — but never wrote the updates back. Every session with a stale map would re-read the same files and leave the map unchanged for next time, repeating the cycle forever. The check now explicitly updates the changed Key Files entries and refreshes the git hash in the header after re-reading, breaking the loop.

project-map.md version sync constraint was incomplete — The constraint listed three manifest files that must stay version-synced, but omitted .codex-plugin/plugin.json and VERSION (both required per CLAUDE.md). A version bump following the map's constraint would silently miss two files. Updated to list all five.

context-snapshot.json creation expectation clarified — When git init runs mid-session via the fresh-project gate, context-snapshot.json is not created in that session (the context-engine hook already fired at session start before git existed). The confirm path in using-superpowers now states this explicitly and notes that the file will appear on the next session start from the project root.

v6.0.0

Comprehensive codebase audit and hardening. Twelve bugs, routing gaps, and safety issues found and fixed across hooks, skill routing, and the subagent guard.

Fixes

Gitignore corruption when section already exists — When track-edits.js appended an AI artifact to an existing # AI assistant artifacts section in .gitignore, it omitted the newline prefix, causing the new entry to be concatenated onto the last line of the file if it lacked a trailing newline. The entry would be silently malformed and git would not recognize it. Fixed by applying the prefix variable in both branches.

Dead export appendAutoSessionEntry in stop-reminders — stop-reminders.js exported appendAutoSessionEntry in its module.exports, but the function was never defined anywhere in the file. Any consumer calling it would get a TypeError. Removed from exports.

Cross-platform cache age check in session-start — The update check used date -r FILE +%s to read a file's modification time, which behaves inconsistently on some Linux distributions. On failure the cache age defaulted to 0, causing a GitHub fetch on every session start. Replaced with stat -c %Y (GNU/Linux) falling back to stat -f %m (BSD/macOS) falling back to 0.

Awk stderr leaked into session context — The session-start hook used 2>&1 when capturing the using-superpowers skill body via awk. Any awk error (permission denied, missing file) would be injected into the AI's session context as part of the skill text. Changed to 2>/dev/null.

premise-check was unreachable via skill-activator hook — Despite being the most important safety-net skill (validates whether work should exist before building it), premise-check had no entry in skill-rules.json. The skill-activator hook could never suggest it based on user input — it only fired if the model proactively read the Routing Guide text. Added a high-priority rule covering "design a system", "should we build this", "validate the premise", and related phrases.

receiving-code-review was unreachable via skill-activator hook — Same gap: no skill-rules.json entry. Phrases like "address review feedback" and "respond to review" never triggered it. Added a medium-priority rule.

error-recovery missing from Routing Guide — The skill existed and was in skill-rules.json, but was absent from the Routing Guide in using-superpowers. A model doing full-complexity routing would never find it as a destination. Added to the guide.

deliberation missing from subagent-guard — The subagent guard's violation patterns covered 20 skills but omitted deliberation. A subagent invoking deliberation by plain name (without the superpowers-optimized: prefix) would slip through. Added to the patterns. The guard was also refactored to use a verb-prefix pattern (invoking/using/running + skill name) that eliminates false positives from prose mentions of skill names.

ReDoS vulnerability in block-dangerous-commands — Six regex patterns used (-.+\s+)* which is a nested quantifier enabling catastrophic backtracking on adversarial input. Replaced with (-\S+\s+)* which eliminates the backtracking risk while preserving the same match semantics.

Changes

Routing Guide clarifies parallel execution paths — The distinction between dispatching-parallel-agents (ad-hoc parallel work outside plan execution) and subagent-driven-development (plan execution with optional parallel waves) is now explicit in the Routing Guide. Previously the two entries looked equivalent, causing model confusion on which to pick.

Internal skills documented in Routing Guide — self-consistency-reasoner (invoked internally by systematic-debugging and verification-before-completion) and token-efficiency (always-on, invoked at Entry Sequence step 1) are now noted as intentional non-entries in the Routing Guide. Previously their absence was undocumented, which could be misread as orphaned skills.

CMD arg limit documented in run-hook.cmd — A comment now notes the 8-argument limit of the %2-%9 forwarding pattern in the Windows batch wrapper, flagging it for future callers who need more.

v5.6.0

v5.6.0 (2026-03-21)

Session memory enhanced, auto-gitignore for AI artifacts, and routing guide completeness. project-map.md is now injected directly into every session start by the hook — no instruction-following required. AI workspace files are automatically added to .gitignore the moment they're created. The routing guide now covers every user-invocable skill in the plugin.

New Features

project-map.md auto-injected at session start — The session-start hook now reads project-map.md from the working directory and injects its content directly into context, unconditionally, before the first turn. Previously, reading the project map relied on Claude following the entry sequence — if the task was classified as micro, or if the first message was conversational, the file might never be read. Now it's always in context. For maps ≤200 lines the full content is injected; for larger maps only the ## Critical Constraints and ## Hot Files sections are injected, with a note pointing to the full file.

Auto-gitignore for AI workspace artifacts — When Claude creates project-map.md, session-log.md, or state.md in a project, they are now automatically added to .gitignore under a # AI assistant artifacts section header. These are tooling artifacts — generated by the AI, not part of the project — and should never appear in git status as untracked files. The gitignore check runs in the PostToolUse hook for files Claude writes directly, and in the stop hook for session-log.md entries written by the hook itself. Idempotent: if the entry already exists, nothing is changed.

Changes

Routing guide now covers all user-invocable skills — premise-check and using-git-worktrees were missing from the routing guide in using-superpowers and had no coverage anywhere in the entry sequence. Both are now listed: premise-check at the top of the guide (run before brainstorming or planning when it's unclear whether work should exist at all), and using-git-worktrees before the implementation entries (run before implementation when the work needs branch isolation).

claude-md-creator added to routing guide with explicit bypass protection — CLAUDE.md creation was being classified as lightweight and implemented directly, bypassing the claude-md-creator skill that exists specifically for this task. The routing guide now includes an explicit entry for CLAUDE.md / AGENTS.md creation pointing to claude-md-creator, with a note that it applies at any complexity level. The lightweight action text now includes an exception: if a dedicated implementation skill exists for the task, invoke it — lightweight only skips workflow overhead, not implementation skills.

v5.5.0

v5.5.0 (2026-03-20)

Reasoning gap prevention and fresh project memory setup. The AI now catches its own design and implementation gaps earlier, classifies tasks more accurately, and proactively offers to set up the memory stack before building anything in a new directory.

New Features

Fresh project gate — When you type "build", "create", "implement", or any creation-intent prompt in a directory with no project-map.md, the AI now pauses before starting and explains exactly what it will lose without the memory stack (re-exploring structure, re-reading known files, re-proposing rejected approaches, losing the "why" behind decisions). It offers to run git init and generate project-map.md in ~30 seconds before proceeding, or start immediately if you prefer. Previously this offer only appeared if git was absent — now it fires whenever no project-map.md exists, regardless of git status, so users who already have git initialized are no longer silently skipped.

Failure-mode check in brainstorming — Before any design can be approved, the AI must now state the top 2–3 ways the chosen approach could fail or not cover all cases. This is adversarial reasoning — actively trying to break the design — not a list of known assumptions. Critical failure modes (the design fails for a significant user scenario) must be fixed before proceeding; minor ones are documented as non-goals. This catches unknown assumptions at the design stage, where fixing them costs nothing, rather than discovering them after implementation.

Assumption externalization in writing-plans — The plan header now requires an Assumptions field listing what the plan rests on and what each assumption excludes ("Assumes X — will NOT work if Y"). Every task involving conditional logic now requires a Does NOT cover field stating which scenarios the condition excludes. If an excluded scenario should be covered, the task is revised before implementation begins. This catches known assumptions at the planning stage, complementing the adversarial failure-mode check in brainstorming.

Condition coverage check in verification — verification-before-completion now requires, as step 5 of its gate, that any change involving a condition or gate explicitly state what it does NOT cover before the task is marked done. If the answer reveals a gap that should be covered, it must be fixed before proceeding. This is the final catch in a three-stage adversarial pipeline: design → planning → completion.

Changes

Classification hard overrides — The complexity classification in using-superpowers now has a hard override section that is evaluated before the lightweight criteria. If any of four conditions are true (adds/modifies/removes a condition or trigger, affects user experience, modifies a shared dependency, introduces a new outcome), the task is immediately classified as full regardless of file count. This prevents lightweight anchoring on file count for tasks that have significant behavioral impact.

Lightweight articulation requirement — Before classifying any task as lightweight, the AI must now explicitly state in one sentence why each of the four lightweight criteria is satisfied. If any criterion cannot be clearly articulated, the task is classified as full. Combined with the hard overrides, this closes the gap where tasks with new conditional logic were being mis-classified as lightweight, skipping brainstorming and the design-stage failure-mode check.

v5.3.0

v5.3.0 (2026-03-17)

Frontend design intelligence and documentation improvements. The frontend skill was completely rewritten from a 62-line checklist into a comprehensive design reasoning system, and several docs were updated to reflect the current state of the plugin.

New Features

frontend-design skill (complete rewrite) — The former frontend-craftsmanship skill has been renamed to frontend-design and rewritten from scratch. It now includes a 4-step design system generation framework that forces deliberate style, color, typography, and effects decisions before writing code. Adds a 25-style reference catalog (Minimalism through Cyberpunk), a 30-category industry design reference table mapping product types to recommended design directions, 8 common page structure patterns (dashboard, landing page, admin panel, etc.), 5-state UI state management (loading, error, empty, success, partial), frontend-backend integration patterns (API loading, optimistic updates, error boundaries, auth flows), dark mode implementation guidance, micro-copy and UX writing standards, and 10 priority quality standard categories covering accessibility, touch targets, performance, animation, forms, navigation, and charts. 353 lines, single file, zero dependencies.

Red team pipeline documentation — New docs/red-team-pipeline.md explains the end-to-end flow from code review through red team dispatch to auto-fix pipeline, including when each component fires, what the red team produces, how auto-fix processes findings, and merge blocking rules.

Frontend design documentation — New docs/frontend-design.md explains the skill's 7 capabilities with examples, what users can expect when prompting for frontend work, and how activation integrates with other Superpowers skills.

Changes

Testing documentation updated — docs/testing.md (now docs/testing-structure.md) was rewritten to reflect the actual 5-directory test structure: claude-code, skill-triggering, explicit-skill-requests, subagent-driven-dev, and opencode. Added the subagent hook scope test, fixed stale plugin name references, and added a quick reference section with copy-paste commands for every test suite.

AGENTS.minimal.md updated — Added missing premise-check skill reference.

frontend-craftsmanship → frontend-design rename — All references across 9 files updated: SKILL.md frontmatter, skill-rules.json, subagent-guard.js, README.md, AGENTS.minimal.md, using-superpowers routing, executing-plans, subagent-driven-development, and RELEASE-NOTES.md.