worclaude 2.2.6 → 2.3.0

package/templates/commands/compact-safe.md

@@ -10,3 +10,8 @@ After compaction, briefly confirm:
 - Current task
 - Current branch
 - What was just being worked on
+
+## Trigger Phrases
+- "compact context"
+- "free up context"
+- "running low on context"

package/templates/commands/conflict-resolver.md

@@ -43,3 +43,8 @@ If anything fails, fix it.
   Use exactly this message format — no trailers or Co-Authored-By lines.
 
 Do NOT push. Do NOT create a PR. The user will run /sync next.
+
+## Trigger Phrases
+- "resolve conflicts"
+- "fix merge conflicts"
+- "merge conflict"

package/templates/commands/end.md

@@ -4,6 +4,10 @@ description: "Mid-task stop — writes handoff file and session summary for next
 
 Use this ONLY when stopping work mid-task without committing.
 
+When invoked with arguments, use them as the description of current work. Example: `/end implementing user registration`
+
+Arguments: $ARGUMENTS
+
 Do NOT update PROGRESS.md — /sync handles that on develop after merging.
 
 ## Pre-flight: Worktree Safety
@@ -35,3 +39,9 @@ If you are working in a git worktree (not the main checkout):
 5. git commit -m "wip: handoff for [task description]"
    Use exactly this message format — no trailers or Co-Authored-By lines.
 6. git push
+
+## Trigger Phrases
+- "stop working"
+- "end session"
+- "save and stop"
+- "I need to go"

package/templates/commands/learn.md

@@ -0,0 +1,33 @@
+---
+description: "Capture a correction or convention as a persistent learning"
+---
+
+The user wants to capture a learning from this session.
+
+When invoked with arguments, use them as the learning to capture.
+Example: `/learn Always use conventional commits for this project`
+
+If no arguments provided, ask the user what they want to remember.
+
+Format it as a [LEARN] block:
+
+[LEARN] Category: One-line rule description
+Mistake: What went wrong (optional)
+Correction: What should happen instead (optional)
+
+Write this to `.claude/learnings/{category-slug}.md` with YAML frontmatter:
+- created: today's date (YYYY-MM-DD)
+- category: from the [LEARN] block
+- project: current project name (from package.json name field, or directory name)
+- times_applied: 0
+
+Update `.claude/learnings/index.json` to include the new entry.
+If index.json doesn't exist, create it with `{ "learnings": [] }`.
+
+Confirm to the user what was saved and where.
+
+## Trigger Phrases
+- "remember this"
+- "learn this"
+- "save this rule"
+- "capture this correction"

package/templates/commands/refactor-clean.md

@@ -7,6 +7,10 @@ runs INLINE in your current session — it reads uncommitted changes,
 improves them in place, and leaves everything uncommitted for
 /commit-push-pr.
 
+When invoked with arguments, use them to scope the cleanup. Example: `/refactor-clean src/core/merger.js`
+
+Arguments: $ARGUMENTS
+
 Do NOT spawn a subagent or worktree for this. Work directly on
 the files in the current working directory.
 
@@ -54,3 +58,9 @@ the files in the current working directory.
 - After implementing a feature, before /verify and /commit-push-pr
 - Weekly maintenance pass
 - When /review-changes flagged issues you want to fix
+
+## Trigger Phrases
+- "clean up the code"
+- "refactor this"
+- "simplify"
+- "tidy up"

package/templates/commands/review-changes.md

@@ -22,3 +22,8 @@ Only analyze and report.
 
 The user will decide which findings to act on and apply fixes themselves.
 Do NOT apply any fixes. Do NOT touch any files. REPORT ONLY.
+
+## Trigger Phrases
+- "review my changes"
+- "what did I change"
+- "code review"

package/templates/commands/review-plan.md

@@ -12,3 +12,8 @@ review the plan for:
 - SPEC.md alignment
 
 Wait for the review and address all feedback before proceeding.
+
+## Trigger Phrases
+- "review this plan"
+- "check my implementation plan"
+- "plan review"

package/templates/commands/setup.md

@@ -114,3 +114,8 @@ these files with real, project-specific content:
    features from the interview, marking completed items.
 
 Show the user what files were updated and offer to review each one.
+
+## Trigger Phrases
+- "set up the project"
+- "configure this project"
+- "project interview"

package/templates/commands/start.md

@@ -5,6 +5,10 @@ description: "Load session context, check for handoff files, detect drift since
 The SessionStart hook has already loaded CLAUDE.md, PROGRESS.md,
 and the most recent session summary into context.
 
+When invoked with arguments, use them as the task focus. Example: `/start implement auth module`
+
+Arguments: $ARGUMENTS
+
 Your job is to supplement that with drift detection and additional context.
 
 ## 1. Drift Detection
@@ -73,3 +77,9 @@ Summarize:
 - What was last completed (from session summary loaded by hook)
 - What's next (from PROGRESS.md loaded by hook)
 - Any blockers or notes
+
+## Trigger Phrases
+- "start a new session"
+- "begin working"
+- "load context"
+- "what changed since last time"

package/templates/commands/status.md

@@ -8,3 +8,8 @@ Report current session state:
 - Test status (last run results)
 - Context usage estimate
 - Any blockers or pending decisions
+
+## Trigger Phrases
+- "what's the status"
+- "where am I"
+- "what am I working on"

package/templates/commands/sync.md

@@ -52,3 +52,8 @@ and tell the user to run /conflict-resolver first.
    Use exactly this message format — no trailers or Co-Authored-By lines.
 10. git push origin develop
 11. gh pr create --base main with description of what was merged
+
+## Trigger Phrases
+- "sync progress"
+- "update shared files"
+- "post-merge sync"

package/templates/commands/techdebt.md

@@ -11,3 +11,8 @@ Scan the codebase for technical debt:
 - Inconsistent patterns
 
 Report findings organized by severity. Fix quick wins directly.
+
+## Trigger Phrases
+- "find tech debt"
+- "scan for issues"
+- "code quality scan"

package/templates/commands/test-coverage.md

@@ -55,3 +55,8 @@ Delegates to the test-writer agent for test creation.
 - After implementing a large feature
 - When coverage drops below project threshold (check CLAUDE.md)
 - During periodic maintenance
+
+## Trigger Phrases
+- "check test coverage"
+- "what needs tests"
+- "coverage gaps"

package/templates/commands/update-claude-md.md

@@ -11,3 +11,8 @@ Review what happened:
 
 Write the proposed additions to the Gotchas section or
 Critical Rules section. Show the diff before applying.
+
+## Trigger Phrases
+- "update CLAUDE.md"
+- "add to rules"
+- "update project rules"

package/templates/commands/verify.md

@@ -3,6 +3,11 @@ description: "Run full project verification — tests, build, lint, type checkin
 ---
 
 Run full project verification:
+
+When invoked with arguments, use them to scope what to verify. Example: `/verify just the auth module`
+
+Arguments: $ARGUMENTS
+
 1. Run the test suite
 2. Run the build
 3. Run the linter
@@ -10,3 +15,9 @@ Run full project verification:
 5. Run any domain-specific verification
 
 Report results clearly. Do not proceed if any check fails.
+
+## Trigger Phrases
+- "verify everything"
+- "run all checks"
+- "is this working"
+- "test and lint"

package/templates/core/agents-md.md

@@ -0,0 +1,25 @@
+# AGENTS.md
+
+{project_name} — {description}
+
+## Tech Stack
+{tech_stack_filled_during_init}
+
+## Build & Test Commands
+{commands_filled_during_init}
+
+## Code Conventions
+- Follow existing patterns in the codebase
+- Test before committing
+- Read source files before modifying them
+- Ask if ambiguous, do not guess
+
+## Project Structure
+- `src/` — Source code
+- `tests/` — Test files
+- `docs/` — Documentation
+
+## Key Principles
+- Source of truth: docs/spec/SPEC.md
+- One task at a time, verify each before moving on
+- Never invent features not in the specification

package/templates/core/claude-md.md

@@ -16,6 +16,7 @@
 See `.claude/skills/` — load only what's relevant:
 - context-management/SKILL.md — Session lifecycle
 - claude-md-maintenance/SKILL.md — CLAUDE.md self-healing
+- coding-principles/SKILL.md — Behavioral principles: assumptions, simplicity, surgical changes, verification
 - git-conventions/SKILL.md — Commits, branches, versioning
 - planning-with-files/SKILL.md — Implementation planning
 - prompt-engineering/SKILL.md — Prompting patterns and quality
@@ -45,6 +46,22 @@ See `.claude/skills/` — load only what's relevant:
 7. Mediocre fix → scrap it, implement elegantly.
 8. Feature branches NEVER modify shared-state files. Those are updated only on develop via /sync after merging PRs. See git-conventions.md Shared-State Files for the canonical list.
 9. Never add Co-Authored-By trailers, AI attribution footers, or "Generated with" signatures to commits or PRs.
+10. Surgical changes only — every changed line must trace to the request. Don't "improve" adjacent code, comments, or formatting.
+11. Push back when simpler approaches exist. Present alternatives, don't pick silently.
+12. Transform tasks to success criteria. "Fix the bug" → "Write a failing test, then make it pass."
+
+## Memory Architecture
+
+- This file: static project rules. Keep under 200 lines.
+- Native memory (`/memory`): auto-captured project knowledge.
+- Persistent corrections: `.claude/learnings/` via [LEARN] blocks or `/learn`.
+- Path-scoped rules: `.claude/rules/` with YAML frontmatter.
+- Session state: `.claude/sessions/` (gitignored).{memory_architecture_extras}
+- Do NOT write session learnings or auto-captured patterns here.
+
+## Learnings
+
+Corrections captured via [LEARN] blocks live in `.claude/learnings/`. SessionStart loads recent ones automatically.
 
 ## Gotchas
 [Grows during development]

package/templates/hooks/README.md

@@ -0,0 +1,106 @@
+# Worclaude Hooks
+
+This directory holds Node.js hook scripts that `worclaude init` copies
+into `.claude/hooks/` of the scaffolded project. Each script corresponds
+to a `hooks[<event>]` entry in `templates/settings/base.json`.
+
+`scaffoldHooks()` only copies `*.cjs` and `*.js` files — this `README.md`
+and everything under `examples/` stays in the Worclaude repo and is NOT
+shipped into user projects.
+
+## Scaffolded hooks
+
+| File | Event | Purpose |
+|---|---|---|
+| `pre-compact-save.cjs` | `PreCompact` | Writes a git context snapshot to `.claude/sessions/` before auto-compaction so nothing is lost if compaction truncates state. |
+| `correction-detect.cjs` | `UserPromptSubmit` | Regex-matches user prompts against correction patterns and learn signals. On match, writes a hint to `.claude/.correction-hint`. |
+| `learn-capture.cjs` | `Stop` | Scans the session transcript for `[LEARN] …` blocks and persists them to `.claude/learnings/` with an `index.json`. Uses a file-based re-entry flag to tolerate hypothetical re-entrant Stop events. |
+| `skill-hint.cjs` | `UserPromptSubmit` | Token-overlap match between the user's prompt and installed skill directory names. Emits a `[Skill hint]` line when a match is found. |
+
+All scripts:
+- use the `.cjs` extension so `require()` works regardless of the host project's `package.json` `"type": "module"` setting
+- read JSON from stdin, handle malformed input gracefully, and always exit 0
+- suppress stderr noise from git or filesystem helpers
+
+## Hook profiles
+
+Every hook except `SessionStart`, `PostCompact`, and `PreCompact` is
+gated by the `WORCLAUDE_HOOK_PROFILE` environment variable:
+
+| Profile | Runs |
+|---|---|
+| `minimal` | Only context-loading hooks (`SessionStart`, `PostCompact`, `PreCompact`). All other hooks exit immediately. |
+| `standard` (default) | All hooks including formatter on `PostToolUse`, learnings capture on `Stop`, notifications on `SessionEnd`/`Notification`. |
+| `strict` | Standard + TypeScript type-checking after every `Write`/`Edit`. |
+
+Users override the profile via shell env: `export WORCLAUDE_HOOK_PROFILE=minimal`.
+
+## Handler types
+
+Claude Code supports three hook handler types. Worclaude scaffolds
+`type: "command"` hooks; the others are available for custom use.
+
+### `command` (what we scaffold)
+
+Runs a shell command. Stdin receives JSON context; stdout/stderr are
+surfaced in the session.
+
+```json
+{
+  "type": "command",
+  "command": "node .claude/hooks/my-hook.cjs",
+  "async": true
+}
+```
+
+### `prompt` (cheap LLM-powered validation)
+
+Runs a small prompt through a Claude model (defaults to Haiku).
+`$ARGUMENTS` is replaced with the hook's input JSON. The model must
+reply with `{"ok": true}` or `{"ok": false, "reason": "..."}`. An `ok:
+false` response blocks the tool with the reason displayed.
+
+```json
+{
+  "type": "prompt",
+  "prompt": "Check this: $ARGUMENTS. Reply {\"ok\": true} or {\"ok\": false, \"reason\": \"...\"}.",
+  "model": "haiku",
+  "timeout": 30
+}
+```
+
+`model` is a sibling of `type`; the `model` field accepts aliases
+(`haiku`, `sonnet`, `opus`) or full model IDs. Default timeout is 30s.
+
+### `agent` (full subagent invocation)
+
+Runs a subagent. Heaviest option — use sparingly.
+
+## Prompt-hook example
+
+`examples/prompt-hook-commit-validator.json` is a complete, valid
+`PreToolUse` prompt hook that validates git commit messages against
+Conventional Commits. To enable it in a scaffolded project:
+
+1. Open the project's `.claude/settings.json`.
+2. Merge the `PreToolUse` entry from the example into the `hooks`
+   object (or append if `PreToolUse` already exists).
+3. Test by running `git commit -m 'bad message'` inside a Claude Code
+   session — the hook should reject with a reason.
+
+Prompt hooks consume Haiku tokens. Expect a few cents per 1000 commits.
+
+## Adding custom hooks
+
+- Drop a new `.cjs` or `.js` into `.claude/hooks/`.
+- Reference it from `.claude/settings.json` under the appropriate event.
+- Gate it on `WORCLAUDE_HOOK_PROFILE` if it is expensive or optional.
+- `disableSkillShellExecution` in Claude Code settings does NOT affect
+  hook scripts — hooks are executed by the Claude Code hook runtime,
+  not by skill inline-shell evaluation. Hook scripts run even when
+  `disableSkillShellExecution` is enabled.
+
+## Further reading
+
+- Claude Code hooks reference: `/docs/reference/hooks.md` in this repo.
+- Worclaude hook profiles: `CLAUDE.md` of this repo, "Hook Profiles" section.

package/templates/hooks/correction-detect.cjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+'use strict';
+
+// UserPromptSubmit hook: detects correction and learn patterns in user prompts.
+// Outputs a hint to stdout if a pattern matches; empty output otherwise.
+// No file I/O, no network. Always exits 0.
+
+const { readFileSync } = require('fs');
+
+const correctionPatterns = [
+  /no,?\s*(that's|thats)?\s*(wrong|incorrect|not right)/i,
+  /you\s*(should|shouldn't|need to|forgot)/i,
+  /that's not what I (meant|asked|wanted)/i,
+  /wrong file/i,
+  /undo that/i,
+  /don't do that/i,
+  /actually,?\s/i,
+  /I said /i,
+];
+
+const learnPatterns = [
+  /remember (this|that)/i,
+  /add (this|that) to (your )?rules/i,
+  /don't (do|make) that (again|mistake)/i,
+  /learn from this/i,
+  /\[LEARN\]/i,
+];
+
+try {
+  const data = JSON.parse(readFileSync(0, 'utf8'));
+  const prompt = data.input?.prompt || '';
+
+  if (prompt) {
+    if (learnPatterns.some((p) => p.test(prompt))) {
+      process.stdout.write(
+        '[Learn trigger detected] Capture this as a [LEARN] block with category, rule, and optional mistake/correction.\n'
+      );
+    } else if (correctionPatterns.some((p) => p.test(prompt))) {
+      process.stdout.write(
+        '[Correction detected] Consider proposing a [LEARN] block if this is a generalizable rule.\n'
+      );
+    }
+  }
+} catch {
+  // Never block user input
+}
+
+process.exit(0);

package/templates/hooks/examples/prompt-hook-commit-validator.json

@@ -0,0 +1,16 @@
+{
+  "PreToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Check if this git commit message follows Conventional Commits (feat/fix/refactor/docs/test/chore/ci/build/perf/style/revert). Message: $ARGUMENTS. Reply with JSON only: {\"ok\": true} or {\"ok\": false, \"reason\": \"...\"}.",
+          "model": "haiku",
+          "timeout": 30,
+          "statusMessage": "Validating commit message format"
+        }
+      ]
+    }
+  ]
+}

package/templates/hooks/learn-capture.cjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+'use strict';
+
+// Stop hook: scans the transcript for [LEARN] blocks and persists them
+// to .claude/learnings/ as markdown files with YAML frontmatter.
+// Always exits 0 — never blocks session stop.
+
+const { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, unlinkSync } = require('fs');
+const { join, basename } = require('path');
+
+const LEARN_REGEX =
+  /\[LEARN\]\s*([\w][\w\s-]*?)\s*:\s*(.+?)(?:\r?\nMistake:\s*(.+?))?(?:\r?\nCorrection:\s*(.+?))?(?=\r?\n\[LEARN\]|\r?\n\r?\n|$)/gim;
+
+const STALE_THRESHOLD_MS = 30000; // 30 seconds
+
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-z0-9-]/g, '');
+}
+
+function checkStopHookActive(cwd) {
+  const flagPath = join(cwd, '.claude', '.stop-hook-active');
+  if (existsSync(flagPath)) {
+    try {
+      const stat = statSync(flagPath);
+      if (Date.now() - stat.mtimeMs < STALE_THRESHOLD_MS) {
+        return true; // Another stop hook is active
+      }
+    } catch {
+      // Flag file unreadable — proceed
+    }
+  }
+  return false;
+}
+
+function setStopHookActive(cwd) {
+  const flagPath = join(cwd, '.claude', '.stop-hook-active');
+  try {
+    writeFileSync(flagPath, String(Date.now()));
+  } catch {
+    // Non-critical
+  }
+}
+
+function clearStopHookActive(cwd) {
+  const flagPath = join(cwd, '.claude', '.stop-hook-active');
+  try {
+    unlinkSync(flagPath);
+  } catch {
+    // Non-critical
+  }
+}
+
+function readIndex(learningsDir) {
+  const indexPath = join(learningsDir, 'index.json');
+  if (existsSync(indexPath)) {
+    try {
+      return JSON.parse(readFileSync(indexPath, 'utf8'));
+    } catch {
+      return { learnings: [] };
+    }
+  }
+  return { learnings: [] };
+}
+
+function writeIndex(learningsDir, index) {
+  writeFileSync(join(learningsDir, 'index.json'), JSON.stringify(index, null, 2) + '\n');
+}
+
+function extractLearnings(transcriptPath) {
+  if (!existsSync(transcriptPath)) return [];
+
+  const lines = readFileSync(transcriptPath, 'utf8').split(/\r?\n/).filter(Boolean);
+  const learnings = [];
+
+  // Scan last 20 lines for assistant messages containing [LEARN] blocks
+  const recent = lines.slice(-20);
+  for (const line of recent) {
+    try {
+      const entry = JSON.parse(line);
+      if (entry.type !== 'assistant') continue;
+
+      const content = entry.message?.content;
+      if (!Array.isArray(content)) continue;
+
+      for (const block of content) {
+        if (block.type !== 'text' || !block.text) continue;
+
+        let match;
+        LEARN_REGEX.lastIndex = 0;
+        while ((match = LEARN_REGEX.exec(block.text)) !== null) {
+          learnings.push({
+            category: match[1].trim(),
+            rule: match[2].trim(),
+            mistake: match[3] ? match[3].trim() : null,
+            correction: match[4] ? match[4].trim() : null,
+          });
+        }
+      }
+    } catch {
+      // Skip malformed JSONL lines
+    }
+  }
+
+  return learnings;
+}
+
+try {
+  const input = readFileSync(0, 'utf8');
+  const data = JSON.parse(input);
+  const cwd = data.cwd || process.cwd();
+  const transcriptPath = data.transcript_path;
+
+  if (checkStopHookActive(cwd)) process.exit(0);
+  setStopHookActive(cwd);
+
+  try {
+    if (!transcriptPath) process.exit(0);
+
+    const learnings = extractLearnings(transcriptPath);
+    if (learnings.length === 0) process.exit(0);
+
+    const learningsDir = join(cwd, '.claude', 'learnings');
+    mkdirSync(learningsDir, { recursive: true });
+
+    const index = readIndex(learningsDir);
+    const today = new Date().toISOString().split('T')[0];
+    const projectName = basename(cwd);
+
+    for (const learning of learnings) {
+      const slug = slugify(learning.category);
+      const filename = `${slug}.md`;
+      const filePath = join(learningsDir, filename);
+
+      const entry = [
+        '---',
+        `created: ${today}`,
+        `category: ${learning.category}`,
+        `project: ${projectName}`,
+        'times_applied: 0',
+        '---',
+        '',
+        `**Rule:** ${learning.rule}`,
+      ];
+      if (learning.mistake) entry.push(`**Mistake:** ${learning.mistake}`);
+      if (learning.correction) entry.push(`**Correction:** ${learning.correction}`);
+      entry.push('');
+
+      if (existsSync(filePath)) {
+        const existing = readFileSync(filePath, 'utf8');
+        writeFileSync(filePath, existing + '\n' + entry.join('\n'));
+      } else {
+        writeFileSync(filePath, entry.join('\n'));
+      }
+
+      const existingEntry = index.learnings.find((l) => l.file === filename);
+      if (existingEntry) {
+        existingEntry.created = today;
+      } else {
+        index.learnings.push({
+          file: filename,
+          category: learning.category,
+          created: today,
+          times_applied: 0,
+        });
+      }
+    }
+
+    writeIndex(learningsDir, index);
+  } finally {
+    clearStopHookActive(cwd);
+  }
+} catch {
+  // Never block session stop
+}
+
+process.exit(0);