worclaude 2.2.6 → 2.3.0

package/templates/hooks/pre-compact-save.cjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+'use strict';
+
+// PreCompact hook: saves context snapshot before compaction.
+// Reads JSON from stdin per Claude Code hook contract.
+// Writes snapshot to .claude/sessions/pre-compact-{timestamp}.md.
+// Always exits 0 — never blocks compaction.
+
+const { readFileSync, writeFileSync, mkdirSync } = require('fs');
+const { join } = require('path');
+const { execSync } = require('child_process');
+
+function run(cmd, cwd) {
+  try {
+    return execSync(cmd, {
+      cwd,
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+try {
+  const input = readFileSync(0, 'utf8');
+  const data = JSON.parse(input);
+
+  const trigger = data.trigger || 'unknown';
+  const cwd = data.cwd || process.cwd();
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+
+  const sessionsDir = join(cwd, '.claude', 'sessions');
+  mkdirSync(sessionsDir, { recursive: true });
+
+  const branch = run('git rev-parse --abbrev-ref HEAD', cwd) || 'unknown';
+  const modifiedFiles = run('git status --porcelain', cwd) || '_No uncommitted changes_';
+  const recentCommits = run('git log --oneline -3', cwd) || '_No commits_';
+
+  const snapshot = [
+    '# Pre-Compact Snapshot',
+    `**Trigger:** ${trigger}`,
+    `**Time:** ${new Date().toISOString()}`,
+    `**Branch:** ${branch}`,
+    '',
+    '## Modified Files',
+    modifiedFiles,
+    '',
+    '## Recent Commits',
+    recentCommits,
+    '',
+  ].join('\n');
+
+  writeFileSync(join(sessionsDir, `pre-compact-${timestamp}.md`), snapshot);
+} catch {
+  // Never block compaction
+}
+
+process.exit(0);

package/templates/hooks/skill-hint.cjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+'use strict';
+
+// UserPromptSubmit hook: hints at relevant skills based on user prompt keywords.
+// Reads .claude/skills/ directory, matches skill-name tokens against prompt tokens.
+// Outputs at most one hint to stdout if a match is found; empty output otherwise.
+// Always exits 0.
+
+const { readFileSync, readdirSync, statSync } = require('fs');
+const path = require('path');
+
+const STOPWORDS = new Set([
+  'the', 'and', 'for', 'with', 'that', 'this', 'have', 'from', 'your',
+  'will', 'would', 'could', 'should', 'about', 'when', 'what', 'which',
+  'there', 'here', 'than', 'then', 'them', 'they', 'their', 'been',
+  'being', 'does', 'doing', 'just', 'some', 'like', 'want', 'need',
+  'make', 'made', 'take', 'into', 'also', 'only', 'because',
+]);
+
+function tokenize(text) {
+  return (text || '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((w) => w.length >= 4 && !STOPWORDS.has(w));
+}
+
+try {
+  const data = JSON.parse(readFileSync(0, 'utf8'));
+  const prompt = data.input?.prompt || '';
+  const cwd = data.cwd || process.cwd();
+  const skillsDir = path.join(cwd, '.claude', 'skills');
+
+  if (prompt) {
+    const promptTokens = new Set(tokenize(prompt));
+
+    let skills = [];
+    try {
+      skills = readdirSync(skillsDir)
+        .filter((name) => {
+          try {
+            return statSync(path.join(skillsDir, name)).isDirectory();
+          } catch {
+            return false;
+          }
+        })
+        .sort();
+    } catch {
+      // .claude/skills/ missing — nothing to hint at
+    }
+
+    for (const slug of skills) {
+      const slugTokens = tokenize(slug);
+      const hit = slugTokens.some((t) => promptTokens.has(t));
+      if (hit) {
+        process.stdout.write(
+          `[Skill hint] Consider loading skill: ${slug}/SKILL.md\n`
+        );
+        break;
+      }
+    }
+  }
+} catch {
+  // Never block user input
+}
+
+process.exit(0);

package/templates/memory/decisions.md

@@ -0,0 +1,11 @@
+# Decisions Log
+
+Record significant design and architectural decisions here.
+Format: date, decision, rationale, alternatives considered.
+
+<!-- Example:
+## 2026-04-14: Use PostgreSQL over SQLite
+**Rationale:** Need concurrent write support and dataset will exceed 10GB.
+**Alternatives:** SQLite (too limited for concurrency), MongoDB (team unfamiliar).
+**Status:** Active
+-->

package/templates/memory/preferences.md

@@ -0,0 +1,17 @@
+# Project Preferences
+
+Conventions and preferences learned during development.
+Claude's native memory captures some of these automatically.
+Use this file for team-shared preferences that should be in git.
+
+## Code Style
+
+<!-- Add project-specific preferences here -->
+
+## Tooling
+
+<!-- Add tooling preferences here -->
+
+## Workflow
+
+<!-- Add workflow preferences here -->

package/templates/settings/base.json

@@ -46,13 +46,6 @@
           "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; {formatter_command}"
         }]
       },
-      {
-        "matcher": "Stop",
-        "hooks": [{
-          "type": "command",
-          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; {notification_command}"
-        }]
-      },
       {
         "matcher": "Write|Edit",
         "hooks": [{
@@ -70,12 +63,67 @@
         }]
       }
     ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "test -f .claude/hooks/pre-compact-save.cjs && node .claude/hooks/pre-compact-save.cjs || true",
+          "async": true
+        }]
+      }
+    ],
     "SessionStart": [
       {
         "matcher": "",
         "hooks": [{
           "type": "command",
-          "command": "echo '=== CLAUDE.md ==='; cat CLAUDE.md 2>/dev/null; echo; echo '=== PROGRESS ==='; cat docs/spec/PROGRESS.md 2>/dev/null; echo; echo '=== LAST SESSION ==='; f=$(ls -t .claude/sessions/*.md 2>/dev/null | head -1); if [ -n \"$f\" ]; then cat \"$f\"; else echo 'No previous session found'; fi; echo; echo '=== BRANCH ==='; git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'not a git repo'"
+          "command": "echo '=== CLAUDE.md ==='; cat CLAUDE.md 2>/dev/null; echo; echo '=== PROGRESS ==='; cat docs/spec/PROGRESS.md 2>/dev/null; echo; echo '=== LAST SESSION ==='; f=$(ls -t .claude/sessions/*.md 2>/dev/null | head -1); if [ -n \"$f\" ]; then cat \"$f\"; else echo 'No previous session found'; fi; echo; echo '=== BRANCH ==='; git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'not a git repo'; echo; echo '=== RECENT LEARNINGS ==='; if [ -f .claude/learnings/index.json ]; then node -e \"const idx=JSON.parse(require('fs').readFileSync('.claude/learnings/index.json','utf8'));idx.learnings.sort((a,b)=>b.created.localeCompare(a.created)).slice(0,5).forEach(l=>console.log('- ['+l.category+'] '+l.file));\" 2>/dev/null; else echo 'No learnings captured yet. Use [LEARN] blocks to capture corrections.'; fi"
+        }]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; {notification_command}",
+          "async": true
+        }]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; test -f .claude/hooks/learn-capture.cjs && node .claude/hooks/learn-capture.cjs || true"
+        }]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; test -f .claude/hooks/correction-detect.cjs && node .claude/hooks/correction-detect.cjs || true"
+        }]
+      },
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; test -f .claude/hooks/skill-hint.cjs && node .claude/hooks/skill-hint.cjs || true"
+        }]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "p=${WORCLAUDE_HOOK_PROFILE:-standard}; case \"$p\" in minimal) exit 0;; esac; {notification_command}",
+          "async": true
         }]
       }
     ]

package/templates/skills/templates/backend-conventions.md

@@ -1,6 +1,7 @@
 ---
 description: "Stack-specific backend patterns, API design, database access, error handling conventions"
 when_to_use: "When working on backend logic, data access patterns, configuration management, or filesystem operations"
+version: "1.0.0"
 paths:
   - "src/**"
   - "lib/**"

package/templates/skills/templates/frontend-design-system.md

@@ -1,6 +1,7 @@
 ---
 description: "Design system, component library, styling approach, accessibility and responsive design standards"
 when_to_use: "When building, modifying, or reviewing UI components, styling, layouts, or frontend architecture"
+version: "1.0.0"
 paths:
   - "src/components/**"
   - "src/pages/**"

package/templates/skills/templates/project-patterns.md

@@ -1,6 +1,7 @@
 ---
 description: "Architectural patterns, naming conventions, file organization, and error handling philosophy for this project"
 when_to_use: "When writing new code that should follow established project patterns, or when reviewing code for consistency"
+version: "1.0.0"
 paths:
   - "src/**"
   - "lib/**"

package/templates/skills/universal/coding-principles.md

@@ -0,0 +1,60 @@
+---
+description: "Core behavioral principles: when to ask, when to push back, when to simplify, how to make surgical changes"
+when_to_use: "Always relevant. Load when starting substantive coding tasks, reviewing code, or when output feels overcomplicated or off-target."
+version: "1.0.0"
+---
+
+# Coding Principles
+
+Reference card. Depth and examples live in the linked skills — this file consolidates the rules, not the rationale.
+
+## 1. Think Before Coding
+
+Don't assume. Don't hide confusion. Surface tradeoffs.
+
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+See `prompt-engineering/SKILL.md` for eliciting quality and writing specs.
+
+## 2. Simplicity First
+
+Minimum code that solves the problem. Nothing speculative.
+
+- No features beyond what was asked. No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you wrote 200 lines and it could be 50, rewrite it.
+
+When NOT to simplify: hot paths, stable legacy, framework boilerplate, security-critical code, code you don't fully understand. When in doubt, leave it — a working system is more valuable than a clean one. See the `code-simplifier` agent and `/refactor-clean` command.
+
+## 3. Surgical Changes
+
+Touch only what you must. Every changed line must trace to the request.
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- Remove imports/variables YOUR changes made unused. Leave pre-existing dead code unless asked.
+- Never combine cleanup with feature work.
+
+See `git-conventions/SKILL.md` for style matching and the `/refactor-clean` command for scope.
+
+## 4. Goal-Driven Execution
+
+Define success criteria up front. Loop until verified.
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a failing test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+Close the feedback loop BEFORE committing: change → verify → commit. Not: commit → discover it's broken.
+
+See `verification/SKILL.md`, `testing/SKILL.md`, and `planning-with-files/SKILL.md`.
+
+---
+
+**These principles are working if:** fewer unnecessary diff lines, fewer rewrites from overcomplication, clarifying questions come before implementation rather than after mistakes.

package/templates/skills/universal/context-management.md

@@ -6,6 +6,11 @@ version: "1.0.0"
 
 # Context Management
 
+> **Note:** The bash examples below are reference snippets. If you enable
+> `disableSkillShellExecution` in Claude Code settings (v2.1.101+), any inline
+> shell execution from skills is blocked. These fenced examples are safe to read;
+> copy-paste them into your terminal to run.
+
 ## The 70% Rule
 
 Context windows are finite. When you estimate you've used roughly 70% of available
@@ -141,6 +146,22 @@ Practical takeaways:
 - Skills over 5k tokens get truncated after compaction. Keep skills focused.
 - The 70% rule still applies — these numbers help you estimate when you'll hit it.
 
+## Context Budget Tiers
+
+Monitor your context usage and adjust behavior accordingly:
+
+| Tier | Context Free | Behavior |
+|------|-------------|----------|
+| PEAK | >75% | Normal operation — read files freely, keep full context |
+| GOOD | 50-75% | Be selective about file reads — summarize large files |
+| DEGRADING | 25-50% | Summarize before reading new files, consider /compact |
+| CRITICAL | <25% | Save state immediately, /compact, reload only essentials |
+
+Heuristics (you cannot measure exact tokens):
+- Many large file reads in this session = likely DEGRADING
+- Long conversation with multiple tasks = likely DEGRADING
+- Just started or just compacted = likely PEAK
+
 ## Gotchas
 
 - Compacting doesn't free as much context as you think. If you've read 20 large files,

package/templates/skills/universal/planning-with-files.md

@@ -103,6 +103,17 @@ Just do it:
 - Documentation updates
 - Config changes
 
+## Must-Haves Contract
+
+Every plan should define must-haves that carry through from planning to verification:
+
+- **Truths**: Observable behaviors that must be true when done (e.g., "POST /api/users returns 201 with a user object")
+- **Artifacts**: Files that must exist with real implementation (e.g., "src/routes/users.js with createUser function")
+- **Key Links**: Connections between artifacts (e.g., "users route imported in src/app.js and registered at /api/users")
+
+These must-haves become the verification checklist. If the plan-reviewer doesn't see them,
+it should request them. If the verify-app agent can't confirm them, the feature isn't done.
+
 ## Gotchas
 
 - Plans rot fast. If a plan is more than 2 sessions old and hasn't been started,

package/templates/skills/universal/verification.md

@@ -11,6 +11,11 @@ paths:
 
 # Verification
 
+> **Note:** The bash examples below are reference snippets. If you enable
+> `disableSkillShellExecution` in Claude Code settings (v2.1.101+), any inline
+> shell execution from skills is blocked. These fenced examples are safe to read;
+> copy-paste them into your terminal to run.
+
 ## Beyond Unit Tests
 
 Unit tests verify code logic. Verification confirms the feature actually works in
@@ -114,6 +119,19 @@ If verification fails:
 3. If you introduced it, fix it before committing.
 4. If it's pre-existing, document it and decide whether to fix now or file it.
 
+## Verification Gate Types
+
+Different situations call for different gate behaviors:
+
+- **Pre-flight**: Validate preconditions before starting. Deterministic checks only (file exists, env var set, branch clean). Fail fast if not met.
+- **Revision**: Evaluate output quality, loop back with feedback. Maximum 3 iterations before escalating to user.
+- **Escalation**: Surface unresolvable issues to the user. Pause work, present options clearly, wait for input.
+- **Abort**: Terminate to prevent damage. Preserve current state, report what happened and why, suggest recovery steps.
+
+Use pre-flight for anything that can be checked cheaply up front. Use revision for quality
+gates that may need iteration. Escalate when you've exhausted your ability to resolve.
+Abort only when continuing would make things worse.
+
 ## Gotchas
 
 - "Tests pass" is not the same as "it works." A test suite can have 100% coverage