V6.6.1 - Context pressure gate, Tailwind v4 reference, plan-level security flag, stub scan, and cleaner docs paths.

### New Features

**Context pressure gate** — The skill-activator hook (and its Codex adapter) now reads the live session JSONL to estimate context window usage, and hard-blocks plan-execution prompts when the last assistant turn exceeded 60% of the 200K window. When triggered, the hook replaces all skill hints with a compact-first instruction telling the model to save state.md via context-management, run /compact, and resume from state.md. This prevents Auto Compact from firing mid-implementation and destroying file paths, variable names, and discovered facts at the worst possible moment. Pressure is computed from `input + cache_creation + cache_read` of the last assistant turn — that is the actual current context size, not a cumulative sum across turns.

**Tailwind v4 reference (`skills/frontend-design/tailwind-v4.md`)** — A dedicated companion file with v4 install commands, `@theme` config syntax, renamed class scales, and new features. Frontend-design's training data is biased toward v3, which leads to broken setups when scaffolding for current Tailwind and it leads to not getting the latest and greatest for your UI designs. The skill now routes to this file before any Tailwind work on greenfield or version-unknown projects.

### Changes

**Writing-plans: security flag per task** — Every task in a plan now carries a `Security flag: none | security` line. Setting it to `security` (for tasks handling auth, credentials, input validation, permissions, crypto, or data-access boundaries) triggers a pre-implementation security review before the implementer is dispatched. Catches the class of bug where security-relevant work ships without anyone explicitly checking it.

**Writing-plans: scope-reduction scan** — Plan self-review now searches the plan for "v1", "basic", "simple", "for now", "placeholder", "initial version", and "minimal", and verifies each hit was explicitly sanctioned by the user. Catches quiet scope downgrades where the model promises less than what was asked for without flagging it.

**Writing-plans: execution auto-selection** — Replaces the open "Which approach?" question with deterministic logic: ≥60% context or ≥5 tasks → subagent-driven; heavy inter-task state sharing → inline; default → subagent. The "Ready to execute" framing and explicit "Stop here" instruction give the user a real redirect window instead of the model chaining straight into execution.

**Verification-before-completion: stub scan** — Implementation tasks now require a grep pass for `TODO`, `FIXME`, `placeholder`, and `NotImplementedError` (excluding test files) before any "done" claim. Any hit in a file the task created or modified blocks completion until the stub is removed or explicitly justified. Catches the common failure mode of declaring success while leaving stub code in production.

**Frontend-design: framework & version awareness** — Before scaffolding any CSS framework, the skill now requires inspecting `package.json` and CSS entry files to detect the existing version (or stating the chosen version explicitly on greenfield). Mixing v3 config syntax with v4 CSS directives produces broken builds; this gate prevents that class of error.

**Dependency-management trigger refinement** — Removed "version bump" from the dependency-management trigger keywords. It was overlapping with the dedicated `version-bump` skill, causing the wrong workflow to load on plain version-bump requests.

**Cleaner docs output paths** — Brainstorming specs and writing-plans plans now save to `docs/specs/` and `docs/plans/` instead of `docs/superpowers-optimized/specs/` and `docs/superpowers-optimized/plans/`. The plugin name no longer surfaces in the folder structure of every project that uses these skills. CLAUDE.md, both skill files, both reviewer prompt templates, the autoimprove fixture, and all integration tests were updated. The `stop-reminders` decision-log detection was unaffected — its regex already matched any `specs/` or `plans/` parent folder rather than the plugin-namespaced one, so existing repos with the old path continue triggering reminders correctly.

**Test coverage** — ~290 lines of new tests in `test-skill-activator.js` cover the context pressure gate: execution-trigger pattern matching, Windows/Unix `cwdToProjectDir` encoding, JSONL pressure parsing, threshold behavior, and the block message format.

Author: REPOZY

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "superpowers-optimized",
       "description": "Agentic development framework for Claude Code — disciplined workflow routing, TDD enforcement, safety hooks, systematic debugging, and code review",
-      "version": "6.6.0",
+      "version": "6.6.1",
       "source": "./",
       "author": {
         "name": "REPOZY"

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-optimized",
   "description": "Agentic development framework for Claude Code — disciplined workflow routing, TDD enforcement, safety hooks, systematic debugging, and code review",
-  "version": "6.6.0",
+  "version": "6.6.1",
   "author": {
     "name": "Jesse Vincent, forked by REPOZY"
   },

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-optimized",
-  "version": "6.6.0",
+  "version": "6.6.1",
   "description": "Structured workflow skills for Codex — systematic debugging, TDD, brainstorming, code review, and 30+ expert workflows. Skills work on all platforms. Lifecycle hooks (routing, safety, reminders) require separate setup on macOS/Linux.",
   "author": {
     "name": "Jesse Vincent, forked by REPOZY"

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "superpowers-optimized",
   "displayName": "Superpowers Optimized",
   "description": "Agentic development framework — disciplined workflow routing, TDD enforcement, safety hooks, systematic debugging, and code review",
-  "version": "6.6.0",
+  "version": "6.6.1",
   "author": {
     "name": "Jesse Vincent, forked by REPOZY"
   },

README.md

@@ -255,8 +255,7 @@ skills/ — 24 skills, each in skills/<name>/SKILL.md
 hooks/ — 10 hooks (JS) + hooks.json registry + skill-rules.json
 
 ## Key Files
-hooks/skill-activator.js — UserPromptSubmit: scores prompts against skill-rules.json,
-  injects skill hints. Micro-task detection (≤8 words + patterns = skip routing).
+hooks/skill-activator.js — UserPromptSubmit: context pressure gate (blocks plan execution at ≥60% context, reads session JSONL); skill hints via skill-rules.json; memory recall from session-log.md + known-issues.md. Micro-task detection skips all enrichment.
 hooks/skill-rules.json — 22 rules: skill name, keywords, intentPatterns, priority.
 
 ## Critical Constraints
@@ -408,7 +407,7 @@ This is the full cross-platform hook inventory for the plugin. Claude Code gets
 
 - **context-engine** (SessionStart) — Runs git commands on every session start and writes `context-snapshot.json`: changed files, blast radius (which other files reference each changed file, filtered to actual import/require references), recent commits, and change stats. Uses per-project watermarks (md5 of cwd) so multiple projects don't interfere, and cross-session diff base so "what changed" reflects changes since your last session, not just the last commit. Zero dependencies. Silent no-op on non-git projects
 - **session-start** (SessionStart) — Injects using-superpowers routing into every session; injects `project-map.md` content directly if it exists (full content ≤200 lines, Critical Constraints + Hot Files only above that); checks for available plugin update
-- **skill-activator** (UserPromptSubmit) — Micro-task detection + confidence-threshold skill matching + weighted memory recall from session-log.md and known-issues.md (70% keyword density + 30% recency scoring)
+- **skill-activator** (UserPromptSubmit) — Context pressure gate: reads session JSONL, blocks plan-execution triggers when context ≥60% of 200K window (fires compact-first instruction instead of skill hints). Also: micro-task detection + confidence-threshold skill matching + weighted memory recall from session-log.md and known-issues.md (70% keyword density + 30% recency scoring)
 - **track-edits** (PostToolUse: Edit/Write) — Logs file changes for TDD reminders; auto-adds AI workspace artifacts (`project-map.md`, `session-log.md`, `state.md`) to `.gitignore` on first write
 - **track-session-stats** (PostToolUse: Skill) — Tracks skill invocations for progress visibility
 - **stop-reminders** (Stop) — Surfaces TDD reminders, commit nudges, and session summary after each response turn

RELEASE-NOTES.md

@@ -1,5 +1,33 @@
 # Superpowers Optimized Release Notes
 
+## v6.6.1 (2026-05-08)
+
+Context pressure gate, Tailwind v4 reference, plan-level security flag, stub scan, and cleaner docs paths.
+
+### New Features
+
+**Context pressure gate** — The skill-activator hook (and its Codex adapter) now reads the live session JSONL to estimate context window usage, and hard-blocks plan-execution prompts when the last assistant turn exceeded 60% of the 200K window. When triggered, the hook replaces all skill hints with a compact-first instruction telling the model to save state.md via context-management, run /compact, and resume from state.md. This prevents Auto Compact from firing mid-implementation and destroying file paths, variable names, and discovered facts at the worst possible moment. Pressure is computed from `input + cache_creation + cache_read` of the last assistant turn — that is the actual current context size, not a cumulative sum across turns.
+
+**Tailwind v4 reference (`skills/frontend-design/tailwind-v4.md`)** — A dedicated companion file with v4 install commands, `@theme` config syntax, renamed class scales, and new features. Frontend-design's training data is biased toward v3, which leads to broken setups when scaffolding for current Tailwind. The skill now routes to this file before any Tailwind work on greenfield or version-unknown projects.
+
+### Changes
+
+**Writing-plans: security flag per task** — Every task in a plan now carries a `Security flag: none | security` line. Setting it to `security` (for tasks handling auth, credentials, input validation, permissions, crypto, or data-access boundaries) triggers a pre-implementation security review before the implementer is dispatched. Catches the class of bug where security-relevant work ships without anyone explicitly checking it.
+
+**Writing-plans: scope-reduction scan** — Plan self-review now searches the plan for "v1", "basic", "simple", "for now", "placeholder", "initial version", and "minimal", and verifies each hit was explicitly sanctioned by the user. Catches quiet scope downgrades where the model promises less than what was asked for without flagging it.
+
+**Writing-plans: execution auto-selection** — Replaces the open "Which approach?" question with deterministic logic: ≥60% context or ≥5 tasks → subagent-driven; heavy inter-task state sharing → inline; default → subagent. The "Ready to execute" framing and explicit "Stop here" instruction give the user a real redirect window instead of the model chaining straight into execution.
+
+**Verification-before-completion: stub scan** — Implementation tasks now require a grep pass for `TODO`, `FIXME`, `placeholder`, and `NotImplementedError` (excluding test files) before any "done" claim. Any hit in a file the task created or modified blocks completion until the stub is removed or explicitly justified. Catches the common failure mode of declaring success while leaving stub code in production.
+
+**Frontend-design: framework & version awareness** — Before scaffolding any CSS framework, the skill now requires inspecting `package.json` and CSS entry files to detect the existing version (or stating the chosen version explicitly on greenfield). Mixing v3 config syntax with v4 CSS directives produces broken builds; this gate prevents that class of error.
+
+**Dependency-management trigger refinement** — Removed "version bump" from the dependency-management trigger keywords. It was overlapping with the dedicated `version-bump` skill, causing the wrong workflow to load on plain version-bump requests.
+
+**Cleaner docs output paths** — Brainstorming specs and writing-plans plans now save to `docs/specs/` and `docs/plans/` instead of `docs/superpowers-optimized/specs/` and `docs/superpowers-optimized/plans/`. The plugin name no longer surfaces in the folder structure of every project that uses these skills. CLAUDE.md, both skill files, both reviewer prompt templates, the autoimprove fixture, and all integration tests were updated. The `stop-reminders` decision-log detection was unaffected — its regex already matched any `specs/` or `plans/` parent folder rather than the plugin-namespaced one, so existing repos with the old path continue triggering reminders correctly.
+
+**Test coverage** — ~290 lines of new tests in `test-skill-activator.js` cover the context pressure gate: execution-trigger pattern matching, Windows/Unix `cwdToProjectDir` encoding, JSONL pressure parsing, threshold behavior, and the block message format.
+
 ## v6.6.0 (2026-04-15)
 
 Full-stack audit: 3 new skills, smarter cross-session memory, scope gates across 6 skills, and expanded hook coverage.

VERSION

@@ -1 +1 @@
-6.6.0
+6.6.1

hooks/codex/user-prompt-submit-adapter.js

@@ -12,6 +12,7 @@ const {
   buildContext, isMicroTask, matchSkills,
   extractKeywords, searchSessionLog, buildMemoryContext,
   searchKnownIssues, buildKnownIssuesContext,
+  isExecutionTrigger, getContextPressure, buildContextPressureBlock,
 } = require('../skill-activator');
 const { readJsonStdin } = require('./utils');
 
@@ -22,6 +23,20 @@ function evaluatePayload(data) {
   if (!prompt || isMicroTask(prompt)) return {};
 
   const cwd = typeof data.cwd === 'string' ? data.cwd : process.cwd();
+  const sessionId = typeof data.session_id === 'string' ? data.session_id : null;
+
+  // Context pressure gate: block plan execution when context ≥60%
+  if (isExecutionTrigger(prompt)) {
+    const pressure = getContextPressure(cwd, sessionId);
+    if (pressure && pressure.overThreshold) {
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: buildContextPressureBlock(pressure),
+        },
+      };
+    }
+  }
 
   const matches = matchSkills(prompt);
   const keywords = extractKeywords(prompt);

hooks/skill-activator.js

@@ -365,6 +365,129 @@ function buildKnownIssuesContext(entries) {
   ].join('\n');
 }
 
+// ── Context pressure gate ─────────────────────────────────────────────────────
+
+/**
+ * Patterns that indicate the user is about to start plan execution
+ * or heavy implementation work.
+ */
+const EXECUTION_TRIGGER_PATTERNS = [
+  /\bexecute\s+(the\s+)?plan\b/i,
+  /\bstart\s+build(ing)?\b/i,
+  /\bstart\s+implement(ing|ation)?\b/i,
+  /\bfollow\s+(the\s+)?plan\b/i,
+  /\bimplement\s+(the\s+)?plan\b/i,
+  /\blet'?s\s+(build|implement|execute)\b/i,
+  /\brun\s+(the\s+)?plan\b/i,
+  /\bbegin\s+implement(ing|ation)?\b/i,
+  /\bbegin\s+(the\s+)?plan\b/i,
+];
+
+const CONTEXT_WINDOW_SIZE = 200000; // Sonnet 4.6 context window tokens
+const CONTEXT_PRESSURE_THRESHOLD = 0.60; // Hard block at 60%
+
+/**
+ * Returns true if the prompt is triggering plan execution or heavy implementation.
+ */
+function isExecutionTrigger(prompt) {
+  if (!prompt || typeof prompt !== 'string') return false;
+  return EXECUTION_TRIGGER_PATTERNS.some(p => p.test(prompt));
+}
+
+/**
+ * Convert a filesystem cwd path to the Claude Code project directory name.
+ * Examples:
+ *   Windows: "C:\Users\Tjerk Pieksma\..." → "c--Users-Tjerk-Pieksma-..."
+ *   Unix:    "/home/user/projects/foo"    → "home-user-projects-foo"
+ */
+function cwdToProjectDir(cwd) {
+  return cwd
+    .replace(/^([A-Za-z]):/, (_, d) => d.toLowerCase() + '-') // C: → c-
+    .replace(/[/\\]/g, '-')  // path separators → -
+    .replace(/\s/g, '-')     // spaces → -
+    .replace(/-+$/, '');     // trim trailing dashes
+}
+
+/**
+ * Read the current session JSONL and return context pressure info.
+ * Uses the last assistant turn's total input tokens as the context size estimate —
+ * this is the most accurate indicator of how much context window is currently occupied.
+ * Returns null if the JSONL can't be read or has no usable data.
+ */
+function getContextPressure(cwd, sessionId) {
+  if (!sessionId) return null;
+
+  const projectDir = cwdToProjectDir(cwd);
+  const homeDir = process.env.USERPROFILE || process.env.HOME || '';
+  const jsonlPath = path.join(homeDir, '.claude', 'projects', projectDir, sessionId + '.jsonl');
+
+  let content;
+  try {
+    content = fs.readFileSync(jsonlPath, 'utf8');
+  } catch {
+    return null; // File absent or unreadable — silent no-op
+  }
+
+  // Use the last assistant turn's input total as context size.
+  // input + cache_creation + cache_read = total tokens in context window for that turn.
+  // Later turns always have more context, so the last value is the current state.
+  let lastInputTotal = 0;
+
+  for (const line of content.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const obj = JSON.parse(line);
+      if (obj.type === 'assistant' && obj.message && obj.message.usage) {
+        const u = obj.message.usage;
+        const turnInput = (u.input_tokens || 0)
+          + (u.cache_creation_input_tokens || 0)
+          + (u.cache_read_input_tokens || 0);
+        if (turnInput > 0) lastInputTotal = turnInput;
+      }
+    } catch {
+      // Skip malformed lines
+    }
+  }
+
+  if (lastInputTotal === 0) return null;
+
+  const ratio = lastInputTotal / CONTEXT_WINDOW_SIZE;
+  return {
+    inputK: Math.round(lastInputTotal / 1000),
+    percent: Math.round(ratio * 100),
+    overThreshold: ratio >= CONTEXT_PRESSURE_THRESHOLD,
+  };
+}
+
+/**
+ * Build the hard block message injected when context pressure ≥60%.
+ * Returned as additionalContext — Claude sees this instead of skill hints.
+ */
+function buildContextPressureBlock(pressure) {
+  return [
+    '<context-pressure-gate>',
+    `STOP — Do not start implementation yet.`,
+    ``,
+    `Context window: ~${pressure.inputK}K tokens consumed (${pressure.percent}% of 200K limit).`,
+    `Starting implementation at ≥60% risks Auto Compact firing mid-task, destroying`,
+    `variable names, file paths, and discovered facts at the worst possible moment.`,
+    ``,
+    `Required actions before proceeding:`,
+    `1. Invoke the context-management skill to write state.md. Include:`,
+    `   - Path to the plan file`,
+    `   - Starting task number (e.g. "Task 1 — fresh start")`,
+    `   - Any research-phase facts (exact file paths, variable names, non-obvious`,
+    `     constraints) that the plan references but does not spell out explicitly.`,
+    `2. Tell the user: "Context is at ${pressure.percent}%. Saving state and compacting`,
+    `   before implementation — this prevents Auto Compact firing mid-task."`,
+    `3. Run /compact.`,
+    `4. After compaction, read state.md and resume with executing-plans.`,
+    ``,
+    `Do NOT begin implementation without completing steps 1–3.`,
+    `</context-pressure-gate>`,
+  ].join('\n');
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -375,13 +498,30 @@ async function main() {
     const data = JSON.parse(input);
     const prompt = data.prompt || '';
     const cwd = data.cwd || process.cwd();
+    const sessionId = data.session_id || null;
 
     // Micro-task fast path: skip all enrichment entirely
     if (isMicroTask(prompt)) {
       process.stdout.write('{}');
       return;
     }
 
+    // Context pressure gate: if the user is about to start implementation and
+    // the context window is ≥60% full, block and require compact-first.
+    // Returns early — pressure block replaces all other hints when it fires.
+    if (isExecutionTrigger(prompt)) {
+      const pressure = getContextPressure(cwd, sessionId);
+      if (pressure && pressure.overThreshold) {
+        process.stdout.write(JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'UserPromptSubmit',
+            additionalContext: buildContextPressureBlock(pressure),
+          },
+        }));
+        return;
+      }
+    }
+
     // Run all pipelines independently
     const matches = matchSkills(prompt);
     const keywords = extractKeywords(prompt);
@@ -425,9 +565,15 @@ if (require.main === module) {
     buildMemoryContext,
     searchKnownIssues,
     buildKnownIssuesContext,
+    isExecutionTrigger,
+    cwdToProjectDir,
+    getContextPressure,
+    buildContextPressureBlock,
     RULES,
     CONFIDENCE_THRESHOLD,
     STOP_WORDS,
     MAX_MEMORY_ENTRIES,
+    CONTEXT_WINDOW_SIZE,
+    CONTEXT_PRESSURE_THRESHOLD,
   };
 }

skills/brainstorming/SKILL.md

@@ -34,7 +34,7 @@ Every project goes through this process. A todo list, a single-function utility,
    - **Critical** (design fails for a significant user scenario): revise the design before proceeding.
    - **Minor** (edge case, acceptable limitation): document as a non-goal in the design.
    Do not skip this step. An approach that survives adversarial questioning is an approach worth approving.
-9. Save approved design to `docs/superpowers-optimized/specs/YYYY-MM-DD-<topic>-design.md`.
+9. Save approved design to `docs/specs/YYYY-MM-DD-<topic>-design.md`.
 10. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see Spec Self-Review below). Fix issues inline; no subagent dispatch needed.
 11. **User reviews written spec** — ask user to review the spec file before proceeding (see User Review Gate below).
 12. Invoke `writing-plans`.
@@ -129,7 +129,7 @@ Apply senior engineering judgment during design:
 
 - User approved the design.
 - Failure-mode check completed — critical failure modes resolved, minor ones documented as non-goals.
-- Design document exists at the required path (`docs/superpowers-optimized/specs/`).
+- Design document exists at the required path (`docs/specs/`).
 - Spec self-review completed — placeholders, contradictions, ambiguity, and scope issues resolved.
 - User reviewed the written spec and approved.
 - `writing-plans` is invoked as the next skill.