mustard-claude 3.0.2 → 3.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustard-claude",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Framework-agnostic CLI for Claude Code project setup",
   "type": "module",
   "bin": {

package/templates/.claude/commands/guards.md

@@ -0,0 +1,76 @@
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+# Guards: Templates
+
+> DO/DON'T rules for the Mustard templates subproject.
+
+## Hook Development
+
+| Rule | Type |
+|------|------|
+| DO read all stdin before processing (`on('end', ...)`) | DO |
+| DO fail-open: `catch → stderr + exit(0)` | DO |
+| DO normalize Windows paths (`\` to `/`) before pattern matching | DO |
+| DO use `process.exit(0)` for approve (silent exit) | DO |
+| DO write JSON to stdout for block/deny/context responses | DO |
+| DON'T use any npm dependencies — only Node.js built-ins | DON'T |
+| DON'T throw unhandled exceptions — always wrap in try/catch | DON'T |
+| DON'T block on parse errors — treat as approve | DON'T |
+| DON'T use `console.log` for debugging — use `process.stderr.write` | DON'T |
+
+## Hook Response Protocol
+
+| Rule | Type |
+|------|------|
+| DO use `permissionDecision: 'block'` or `'deny'` for PreToolUse hooks | DO |
+| DO use `decision: 'approve'` or `'block'` for PostToolUse hooks | DO |
+| DO include `hookEventName` matching the hook's lifecycle event | DO |
+| DON'T mix PreToolUse and PostToolUse response formats | DON'T |
+
+## Settings & Wiring
+
+| Rule | Type |
+|------|------|
+| DO register every new hook in `settings.json` under the correct lifecycle event | DO |
+| DO set a `timeout` for every hook registration (3-15 seconds) | DO |
+| DO use `$CLAUDE_PROJECT_DIR` in hook command paths | DO |
+| DON'T add hooks without a `matcher` — every hook must declare what it matches | DON'T |
+
+## Commands (SKILL.md)
+
+| Rule | Type |
+|------|------|
+| DO end every command SKILL.md with `ULTRATHINK` | DO |
+| DO include `## Trigger` with exact invocation syntax | DO |
+| DO include `## Rules` section with explicit constraints | DO |
+| DON'T create commands that implement code directly — delegate via Task | DON'T |
+
+## Scripts
+
+| Rule | Type |
+|------|------|
+| DO use `execSync` with `stdio: ['pipe','pipe','pipe']` and `windowsHide: true` | DO |
+| DO set timeouts on all `execSync` calls | DO |
+| DO handle missing files/dirs gracefully (try/catch around fs ops) | DO |
+| DON'T import external packages — all scripts must be self-contained | DON'T |
+
+## Skills (SKILL.md)
+
+| Rule | Type |
+|------|------|
+| DO include YAML frontmatter with `name` and `description` | DO |
+| DO write "pushy" descriptions with casual trigger phrases | DO |
+| DO add `<!-- mustard:generated -->` after the closing `---` | DO |
+| DO keep SKILL.md under 500 lines (ideally under 200) | DO |
+| DON'T put `<!-- mustard:generated -->` before the opening `---` | DON'T |
+| DON'T use generic descriptions — be specific about what and when | DON'T |
+
+## Generated Files
+
+| Rule | Type |
+|------|------|
+| DO start every generated file with `<!-- mustard:generated at:{ISO} role:{role} -->` | DO |
+| DO include H1 title + blockquote description | DO |
+| DO keep under 200 lines per file | DO |
+| DO reference real files with `Ref: path/file.ext` | DO |
+| DON'T include generic information — only data traced from real code | DON'T |
+| DON'T overwrite files without `<!-- mustard:generated` header (manual files) | DON'T |

package/templates/.claude/commands/notes.md

@@ -0,0 +1,22 @@
+# Notes: Templates (General)
+
+> Manual notes for the Mustard templates subproject. Never overwritten by /scan.
+
+## Mandatory Patterns
+
+- All hooks read JSON from stdin and write JSON to stdout
+- All hooks fail-open (exit 0 on error) except when explicitly blocking
+- All generated files start with `<!-- mustard:generated -->` header
+- Skills use YAML frontmatter with `name` and `description` fields
+
+## Known Pitfalls
+
+- Hook stdin must be fully consumed before processing (`on('end', ...)`)
+- Windows path separators must be normalized (`\` to `/`) in file-guard and guard-verify
+- CLAUDE_PROJECT_DIR env var may not be set in all contexts — always fallback to cwd
+
+## Observations
+
+- Templates are copied verbatim to target projects by `mustard init`/`mustard update`
+- The `settings.json` defines the full hook wiring — any new hook must be registered there
+- Skills in `skills/` are foundation skills (stack-agnostic); subproject-specific skills go in `{sub}/.claude/skills/`

package/templates/.claude/commands/patterns.md

@@ -0,0 +1,173 @@
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+# Patterns: Templates
+
+> Recurring code patterns across hooks, scripts, and commands.
+
+## P1. Hook Stdin/Stdout Protocol
+
+All hooks read JSON from stdin, process, and either exit silently (approve) or write JSON to stdout (block/deny/context).
+
+```js
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  const data = JSON.parse(input);
+  // ... process
+  process.exit(0); // approve (silent)
+});
+```
+
+Ref: `hooks/bash-safety.js`, `hooks/file-guard.js`, `hooks/enforce-registry.js`
+
+## P2. PreToolUse Block Response
+
+Hooks that block return a specific JSON structure with `permissionDecision`:
+
+```js
+console.log(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'block', // or 'deny'
+    permissionDecisionReason: 'Reason message'
+  }
+}));
+```
+
+Ref: `hooks/enforce-registry.js` (line 100-109), `hooks/bash-safety.js` (line 44-49)
+
+## P3. PostToolUse Approve/Block Response
+
+PostToolUse hooks use `decision` field (not `permissionDecision`):
+
+```js
+process.stdout.write(JSON.stringify({ decision: 'approve' }));
+// or
+process.stdout.write(JSON.stringify({ decision: 'block', reason: '...' }));
+```
+
+Ref: `hooks/guard-verify.js` (line 60-95)
+
+## P4. Fail-Open Error Handling
+
+Every hook wraps the main logic in try/catch and exits 0 on error — never blocking due to hook bugs:
+
+```js
+} catch (err) {
+  process.stderr.write(`[hook-name] Error: ${err.message}\n`);
+  process.exit(0); // fail-open
+}
+```
+
+Ref: `hooks/bash-safety.js` (line 56-59), `hooks/file-guard.js` (line 57-60)
+
+## P5. Regex-Based Dangerous Command Detection
+
+`bash-safety.js` uses an array of `{ re, msg }` objects tested sequentially against the command string:
+
+```js
+const DANGEROUS = [
+  { re: /\brm\s+(-\w*r\w*f|...)\b/i, msg: 'Recursive force delete blocked' },
+  // ...
+];
+for (const { re, msg } of DANGEROUS) {
+  if (re.test(cmd)) { /* deny */ }
+}
+```
+
+Ref: `hooks/bash-safety.js` (line 14-28)
+
+## P6. File Pattern Blocking
+
+`file-guard.js` blocks access to sensitive files using regex patterns tested against both full path and basename:
+
+```js
+const BLOCKED_PATTERNS = [/credentials/i, /\.pem$/i, /\.key$/i, ...];
+for (const pattern of BLOCKED_PATTERNS) {
+  if (pattern.test(normalized) || pattern.test(basename)) { /* deny */ }
+}
+```
+
+Ref: `hooks/file-guard.js` (line 16-25)
+
+## P7. Role Detection via Scoring
+
+`sync-detect.js` assigns numeric weights (HIGH=10, MEDIUM=5, LOW=3) to file/dep signals, accumulating scores per role. Highest score wins:
+
+| Weight | Signal Type | Example |
+|--------|------------|---------|
+| HIGH (10) | Config files | `.csproj` with Sdk.Web, `next.config.*` |
+| MEDIUM (5) | Package deps | `react` in package.json, `express` |
+| LOW (3) | Directories | `Controllers/`, `app/` + `components/` |
+
+Ref: `scripts/sync-detect.js` (line 210-327)
+
+## P8. SHA-256 Source Hashing for Incremental Scan
+
+`sync-detect.js` computes deterministic hashes by sorting files and updating hash with both path and content:
+
+```js
+const hash = crypto.createHash('sha256');
+for (const file of files.sort()) {
+  hash.update(file);    // path (rename-sensitive)
+  hash.update(content); // content
+}
+return hash.digest('hex');
+```
+
+Ref: `scripts/sync-detect.js` (line 643-659)
+
+## P9. FIFO Queue with Type-Match Preference (Subagent Tracker)
+
+Subagent tracker uses a queue to correlate Task tool calls with SubagentStart events. PreToolUse captures description; SubagentStart consumes by type-match first, FIFO fallback:
+
+```js
+const typeIdx = queue.findIndex(q => q.type === agentType);
+if (typeIdx >= 0) { /* consume type-matched entry */ }
+else { /* FIFO: consume first */ }
+```
+
+Ref: `hooks/subagent-tracker.js` (line 80-95)
+
+## P10. ANSI Statusline with Git Cache
+
+`statusline.js` caches git status in a temp file with 5s TTL to avoid repeated `git` calls:
+
+```js
+const GIT_CACHE_FILE = path.join(os.tmpdir(), 'claude-statusline-git.json');
+const GIT_CACHE_TTL = 5000;
+```
+
+Ref: `scripts/statusline.js` (line 17-18, 296-326)
+
+## P11. Command SKILL.md Structure
+
+All slash commands follow the same structure: H1 title, trigger section, description, procedure/action, rules, and `ULTRATHINK` footer:
+
+```markdown
+# /command-name - Title
+## Trigger
+`/command-name <args>`
+## Description / ## Procedure / ## Action
+...
+## Rules
+...
+ULTRATHINK
+```
+
+Ref: `commands/mustard/feature/SKILL.md`, `commands/mustard/bugfix/SKILL.md`
+
+## P12. Foundation Skill YAML Frontmatter
+
+Foundation skills use YAML frontmatter with `name`, `description`, and optional `disable-model-invocation`:
+
+```yaml
+---
+name: skill-name
+description: "What it does. When to use it."
+disable-model-invocation: true
+---
+<!-- mustard:generated -->
+```
+
+Ref: `skills/commit-workflow/SKILL.md`, `skills/pipeline-execution/SKILL.md`

package/templates/.claude/commands/recipes.md

@@ -0,0 +1,91 @@
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+# Recipes: Templates
+
+> Implementation recipes for common tasks in the templates subproject.
+
+## Recipe: New Hook
+
+### Steps
+1. Create `hooks/{hook-name}.js` following stdin/stdout protocol → `patterns.md` P1
+2. Implement logic with fail-open error handling → `patterns.md` P4
+3. Choose response format: PreToolUse (`permissionDecision`) or PostToolUse (`decision`) → `patterns.md` P2, P3
+4. Register in `settings.json` under correct lifecycle event with matcher and timeout
+5. Add test cases in `hooks/__tests__/hooks.test.js`
+6. Run tests: `node --test hooks/__tests__/hooks.test.js`
+
+### Reference module: bash-safety.js (PreToolUse) | guard-verify.js (PostToolUse)
+### Reference files: `hooks/bash-safety.js`, `hooks/guard-verify.js`, `settings.json`, `hooks/__tests__/hooks.test.js`
+
+### Task splits
+- **HookImpl** (steps 1-3): Patterns: `patterns.md` P1-P4 | Depends on: none
+- **HookWiring** (steps 4-6): Patterns: `guards.md` Settings | Depends on: HookImpl
+
+### File hierarchy
+| Level | Component | Depends on |
+|-------|-----------|-----------|
+| 1 | `hooks/{name}.js` | -- |
+| 2 | `settings.json` (registration) | hooks/{name}.js |
+| 3 | `hooks/__tests__/hooks.test.js` | hooks/{name}.js |
+| 4 | test run | all |
+
+## Recipe: New Slash Command
+
+### Steps
+1. Create `commands/mustard/{command-name}/SKILL.md` with trigger, description, procedure, rules → `patterns.md` P11
+2. Include `ULTRATHINK` at the end
+3. Verify command follows delegation pattern (no direct code implementation)
+
+### Reference module: feature/SKILL.md (complex) | status/SKILL.md (simple)
+### Reference files: `commands/mustard/feature/SKILL.md`, `commands/mustard/status/SKILL.md`
+
+### Task splits
+- **CommandDef** (steps 1-3): Patterns: `patterns.md` P11 | Depends on: none
+
+### File hierarchy
+| Level | Component | Depends on |
+|-------|-----------|-----------|
+| 1 | `commands/mustard/{name}/SKILL.md` | -- |
+
+## Recipe: New Foundation Skill
+
+### Steps
+1. Create `skills/{skill-name}/SKILL.md` with YAML frontmatter → `patterns.md` P12
+2. Write pushy description with casual trigger phrases → `guards.md` Skills
+3. Add `<!-- mustard:generated -->` after closing `---`
+4. Create `skills/{skill-name}/references/examples.md` with real code examples
+5. Keep SKILL.md under 500 lines
+
+### Reference module: commit-workflow (simple) | design-craft (with references)
+### Reference files: `skills/commit-workflow/SKILL.md`, `skills/design-craft/SKILL.md`
+
+### Task splits
+- **SkillDef** (steps 1-5): Patterns: `patterns.md` P12, `guards.md` Skills | Depends on: none
+
+### File hierarchy
+| Level | Component | Depends on |
+|-------|-----------|-----------|
+| 1 | `skills/{name}/SKILL.md` | -- |
+| 2 | `skills/{name}/references/examples.md` | SKILL.md |
+
+## Recipe: New Sync Script
+
+### Steps
+1. Create `scripts/{script-name}.js` with shebang and JSDoc header
+2. Use only Node.js built-ins (fs, path, child_process, crypto)
+3. Read ROOT from `path.resolve(__dirname, '..', '..')` → `patterns.md` P8
+4. Handle missing files/dirs gracefully with try/catch
+5. Output JSON to stdout for consumption by other tools
+6. Test manually: `node scripts/{script-name}.js`
+
+### Reference module: sync-detect.js (complex) | sync-registry.js (medium)
+### Reference files: `scripts/sync-detect.js`, `scripts/sync-registry.js`
+
+### Task splits
+- **ScriptImpl** (steps 1-5): Patterns: `patterns.md` P7, P8 | Depends on: none
+- **ScriptTest** (step 6): Depends on: ScriptImpl
+
+### File hierarchy
+| Level | Component | Depends on |
+|-------|-----------|-----------|
+| 1 | `scripts/{name}.js` | -- |
+| 2 | manual test | scripts/{name}.js |

package/templates/.claude/commands/stack.md

@@ -0,0 +1,86 @@
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+# Stack: Templates
+
+> Technology stack and tooling for the Mustard templates subproject.
+
+## Runtime
+
+| Component | Version | Notes |
+|-----------|---------|-------|
+| Node.js | >=18 | All hooks/scripts use CommonJS (`require`) |
+| JavaScript | ES2020+ | Optional chaining, nullish coalescing, `Set`, `Map` |
+
+## Dependencies
+
+None. All template files are dependency-free — they use only Node.js built-in modules:
+
+| Module | Used In |
+|--------|---------|
+| `fs` | All hooks, all scripts |
+| `path` | All hooks, all scripts |
+| `child_process` | `auto-format.js`, `pre-compact.js`, `statusline.js`, `sync-detect.js`, `sync-registry.js` |
+| `crypto` | `sync-detect.js` (SHA-256 hashing) |
+| `os` | `statusline.js`, `session-cleanup.js` |
+
+## File Categories
+
+| Category | Path | Count | Purpose |
+|----------|------|-------|---------|
+| Hooks | `hooks/*.js` | 8 | PreToolUse/PostToolUse/Session lifecycle guards |
+| Scripts | `scripts/*.js` | 3 | Sync-detect, sync-registry, statusline |
+| Commands | `commands/mustard/*/SKILL.md` | 14 | Slash command definitions |
+| Skills | `skills/*/SKILL.md` | 6 | Foundation skills (design-craft, react-best-practices, etc.) |
+| Config | `settings.json` | 1 | Hook wiring, permissions, statusline |
+| Config | `pipeline-config.md` | 1 | Agent dispatch rules, wave system, model selection |
+| Template | `CLAUDE.md` | 1 | Orchestrator rules template |
+
+## Commands
+
+```bash
+# Run hook tests
+node --test hooks/__tests__/hooks.test.js
+
+# Run sync-detect (outputs JSON)
+node scripts/sync-detect.js
+node scripts/sync-detect.js --no-cache
+
+# Run sync-registry
+node scripts/sync-registry.js
+node scripts/sync-registry.js --force
+```
+
+## Structure
+
+```
+templates/
+├── CLAUDE.md                    # Orchestrator rules (copied to .claude/CLAUDE.md)
+├── settings.json                # Hook wiring + permissions
+├── pipeline-config.md           # Agent/wave/model config
+├── commands/mustard/             # 14 slash commands
+│   ├── feature/SKILL.md
+│   ├── bugfix/SKILL.md
+│   ├── scan/SKILL.md
+│   ├── git/SKILL.md
+│   └── ... (approve, complete, resume, status, task, etc.)
+├── hooks/                        # 8 lifecycle hooks
+│   ├── bash-safety.js            # PreToolUse — block dangerous commands
+│   ├── file-guard.js             # PreToolUse — block sensitive files
+│   ├── enforce-registry.js       # PreToolUse — require entity-registry
+│   ├── auto-format.js            # PostToolUse — prettier/dotnet format
+│   ├── guard-verify.js           # PostToolUse — architectural rules
+│   ├── subagent-tracker.js       # Pre/SubagentStart/Stop — agent state
+│   ├── pre-compact.js            # PreCompact — snapshot before compaction
+│   ├── session-cleanup.js        # SessionEnd — prune stale state
+│   └── __tests__/hooks.test.js   # Tests (node:test + node:assert)
+├── scripts/
+│   ├── sync-detect.js            # Subproject discovery + role detection
+│   ├── sync-registry.js          # Entity registry generation
+│   └── statusline.js             # ANSI statusline renderer
+└── skills/                       # Foundation skills
+    ├── commit-workflow/
+    ├── design-craft/
+    ├── pipeline-execution/
+    ├── react-best-practices/
+    ├── senior-architect/
+    └── skill-creator/
+```

package/templates/.claude/skills/templates-command-authoring/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: templates-command-authoring
+description: "Pattern for writing slash command SKILL.md files with trigger, procedure,
+  rules, and ULTRATHINK. Use when creating a new mustard command, adding a pipeline
+  command, writing a /command, or the user says 'new command', 'add slash command',
+  'create /feature-like command', 'write command template'."
+---
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+
+# Command Authoring Pattern
+
+Slash commands are SKILL.md files in `commands/mustard/{command-name}/SKILL.md` that define orchestrator behavior.
+
+## Pattern
+
+### File Convention
+- Location: `commands/mustard/{command-name}/SKILL.md`
+- No YAML frontmatter (commands are not auto-loaded by description)
+- End with `ULTRATHINK` keyword
+
+### Structure
+
+```markdown
+# /{command-name} - Title
+
+> Advisory note (optional)
+
+## Trigger
+`/{command-name} <args>`
+
+## Description
+What the command does and when to use it.
+
+## Procedure / ## Action
+Step-by-step process. Use:
+- Tables for signal → action mappings
+- Numbered steps for sequential flow
+- Code blocks for bash commands
+- `### Phase` headers for multi-phase pipelines
+
+## Rules
+- Explicit constraints (NEVER, ALWAYS, MUST)
+- Budget limits (max reads, max API calls)
+- Delegation requirements
+
+ULTRATHINK
+```
+
+### Key Rules
+- Commands NEVER implement code directly — they orchestrate via Task tool
+- Pipeline commands create spec files and pipeline state JSON
+- Git commands read `mustard.json` for branch flow configuration
+- Zero-confirmation: most commands execute without asking user
+
+### Command Categories
+
+| Category | Examples | Characteristic |
+|----------|----------|---------------|
+| Pipeline | `/feature`, `/bugfix`, `/approve`, `/complete`, `/resume` | Multi-phase, creates spec, state tracking |
+| Task | `/task-analyze`, `/task-review`, `/task-refactor` | Single delegation, no spec |
+| Git | `/git sync`, `/git commit`, `/git push`, `/git merge` | Reads `mustard.json`, submodule-aware |
+| Scan | `/scan`, `/scan-format` | Discovery + analysis + generation |
+| Status | `/status`, `/validate` | Read-only, reporting |
+
+## Example
+
+```markdown
+# /my-command - Do Something
+
+## Trigger
+`/my-command <name>`
+
+## Procedure
+1. Read `pipeline-config.md` for agent config
+2. Dispatch Task agent with context
+3. Collect results and report
+
+## Rules
+- NEVER implement code directly
+- ALWAYS delegate via Task tool
+- Budget: max 5 API calls
+
+ULTRATHINK
+```
+Ref: `commands/mustard/feature/SKILL.md`, `commands/mustard/status/SKILL.md`
+
+## References
+
+For full code examples with variants:
+> Read `references/examples.md`

package/templates/.claude/skills/templates-command-authoring/references/examples.md

@@ -0,0 +1,83 @@
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+# Command Authoring Examples
+
+## Example 1: Simple Status Command
+
+```markdown
+# /status - Consolidated Status
+
+## Trigger
+`/status`
+
+## Description
+Shows consolidated project status.
+
+## Information
+1. **Git Status** — branch, modified files, pending push
+2. **Pipeline** — active pipeline, current phase
+3. **Build** — last validation result
+4. **Entity Registry** — entity count, last update
+
+ULTRATHINK
+```
+Ref: `commands/mustard/status/SKILL.md`
+
+## Example 2: Pipeline Command (Feature)
+
+Key sections from the feature command:
+
+```markdown
+# /feature - Feature Pipeline
+
+## Trigger
+`/feature <feature-name>`
+
+### ANALYZE Phase
+1. Read `pipeline-config.md`
+2. Read `entity-registry.json` via Grep
+3. Determine layers from signals
+
+#### Scope Detection
+| Signal | Scope |
+|--------|-------|
+| 1-2 layers, ≤5 files | Light |
+| 3+ layers, 5+ files | Full |
+
+### PLAN Phase
+Create `.claude/spec/active/{date}-{name}/spec.md`
+
+## Rules
+- NEVER implement code in Full scope
+- ALWAYS create pipeline state at PLAN phase
+- Light scope + user chose "implement now" → EXECUTE inline
+
+ULTRATHINK
+```
+Ref: `commands/mustard/feature/SKILL.md`
+
+## Example 3: Git Command with Action Dispatch
+
+```markdown
+# /git - Git Operations
+
+## Trigger
+`/git <action>`
+
+## Actions
+| Action | Description |
+|--------|-------------|
+| `sync` | Pull parent into current |
+| `commit` | Create commit (no push) |
+| `push` | Sync + commit + push |
+
+## Step 0 — Resolve Parent
+cat mustard.json → match branch against flow patterns
+
+## Behavior
+- ZERO confirmations
+- Minimize Bash calls — chain with &&
+- Submodules BEFORE parent
+
+ULTRATHINK
+```
+Ref: `commands/mustard/git/SKILL.md`

package/templates/.claude/skills/templates-hook-protocol/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: templates-hook-protocol
+description: "Pattern for writing Claude Code JavaScript hooks with stdin/stdout JSON protocol,
+  fail-open error handling, and correct response formats. Use when creating a new hook,
+  adding a guard, writing a PreToolUse or PostToolUse handler, or the user says
+  'add hook', 'new guard', 'block command', 'validate file access'."
+---
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+
+# Hook Protocol Pattern
+
+All Claude Code hooks are Node.js scripts that read JSON from stdin and write JSON to stdout.
+
+## Pattern
+
+### File Convention
+- Location: `hooks/{hook-name}.js`
+- Shebang: `#!/usr/bin/env node`
+- JSDoc: version, purpose, what it blocks/allows
+- Module system: CommonJS (`require`)
+- Dependencies: Node.js built-ins only (`fs`, `path`, `child_process`)
+
+### Stdin/Stdout Contract
+
+1. Read full stdin as UTF-8 string
+2. Parse JSON — contains `tool_name`, `tool_input`, `hook_event_name`, `cwd`
+3. Process: check tool name, extract relevant input, apply rules
+4. Respond:
+   - **Approve**: `process.exit(0)` silently (no stdout)
+   - **PreToolUse block**: `console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'block', permissionDecisionReason: '...' } }))`
+   - **PostToolUse block**: `process.stdout.write(JSON.stringify({ decision: 'block', reason: '...' }))`
+5. **Always fail-open**: wrap in try/catch, exit 0 on error
+
+### Key Rules
+- PreToolUse uses `permissionDecision` (block/deny/allow)
+- PostToolUse uses `decision` (approve/block)
+- NEVER mix the two formats
+- ALWAYS normalize Windows paths before matching (`replace(/\\/g, '/')`)
+
+## Example
+
+```js
+#!/usr/bin/env node
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    if (data.tool_name !== 'Bash') { process.exit(0); }
+    const cmd = data.tool_input?.command || '';
+    if (/dangerous-pattern/.test(cmd)) {
+      console.log(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: '[hook-name] Blocked: reason'
+        }
+      }));
+    }
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`[hook-name] Error: ${err.message}\n`);
+    process.exit(0);
+  }
+});
+```
+Ref: `hooks/bash-safety.js`
+
+## References
+
+For full code examples with variants:
+> Read `references/examples.md`

package/templates/.claude/skills/templates-hook-protocol/references/examples.md

@@ -0,0 +1,74 @@
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+# Hook Protocol Examples
+
+## Example 1: PreToolUse — Regex-Based Blocking (bash-safety.js)
+
+Simple pattern: array of `{ re, msg }` tested against command string.
+
+```js
+const DANGEROUS = [
+  { re: /\brm\s+(-\w*r\w*f|--no-preserve-root)\b/i, msg: 'Recursive delete blocked' },
+  { re: /\bgit\s+push\s+(-\w*f|--force)\b/i, msg: 'Force push blocked' },
+];
+// ... stdin reading ...
+for (const { re, msg } of DANGEROUS) {
+  if (re.test(cmd)) {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: `[bash-safety] ${msg}.`
+      }
+    }));
+    process.exit(0);
+  }
+}
+```
+Ref: `hooks/bash-safety.js`
+
+## Example 2: PreToolUse — File Existence Check (enforce-registry.js)
+
+Validates that a required file exists and has valid content before allowing a skill.
+
+```js
+const registryPath = path.join(process.cwd(), '.claude', 'entity-registry.json');
+if (!fs.existsSync(registryPath)) {
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'block',
+      permissionDecisionReason: 'Entity registry not found. Run /sync-registry first.'
+    }
+  }));
+  return;
+}
+const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+// validate version, entities, patterns...
+```
+Ref: `hooks/enforce-registry.js`
+
+## Example 3: PostToolUse — Content Validation (guard-verify.js)
+
+Checks the content being written against architectural rules.
+
+```js
+const CRITICAL_RULES = [
+  { pattern: /\bDbContext\b/i, scope: /Services?[/\\]/, msg: 'DbContext in Services' },
+];
+// ...
+const violations = [];
+for (const rule of CRITICAL_RULES) {
+  if (!rule.scope.test(relPath)) continue;
+  if (!rule.pattern.test(newContent)) continue;
+  violations.push(rule.msg);
+}
+if (violations.length > 0) {
+  process.stdout.write(JSON.stringify({
+    decision: 'block',
+    reason: violations.map(v => `CRITICAL: ${v}`).join('\n')
+  }));
+} else {
+  process.stdout.write(JSON.stringify({ decision: 'approve' }));
+}
+```
+Ref: `hooks/guard-verify.js`

package/templates/.claude/skills/templates-settings-wiring/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: templates-settings-wiring
+description: "Pattern for wiring hooks, permissions, and statusline in settings.json.
+  Use when adding a new hook to settings, changing permissions, updating lifecycle
+  event matchers, configuring statusline, or the user says 'register hook',
+  'add permission', 'wire up', 'configure settings'."
+---
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+
+# Settings.json Wiring Pattern
+
+The `settings.json` file is the central configuration for Claude Code hook lifecycle, permissions, and statusline.
+
+## Pattern
+
+### Lifecycle Events
+
+| Event | Matcher Examples | Purpose |
+|-------|-----------------|---------|
+| `PreToolUse` | `Bash`, `Read\|Write\|Edit`, `Skill`, `Task` | Guard before tool execution |
+| `PostToolUse` | `Write\|Edit` | Validate/format after tool execution |
+| `SessionStart` | `startup` | Clean stale state |
+| `SessionEnd` | `prompt_input_exit\|clear\|other` | Prune state files |
+| `PreCompact` | `auto\|manual` | Snapshot before compaction |
+| `SubagentStart` | (no matcher) | Register agent |
+| `SubagentStop` | (no matcher) | Deregister agent |
+
+### Hook Registration Structure
+
+```json
+{
+  "matcher": "ToolName|OtherTool",
+  "hooks": [{
+    "type": "command",
+    "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/{hook}.js",
+    "timeout": 5
+  }]
+}
+```
+
+### Key Rules
+- `$CLAUDE_PROJECT_DIR` resolves to the project root at runtime
+- Always quote the path: `\"$CLAUDE_PROJECT_DIR\"`
+- Timeout: 3-5s for simple checks, 10-15s for format/compile
+- Multiple hooks under same matcher run sequentially
+- Matcher uses `|` for OR: `"Write|Edit"`, `"Read|Write|Edit"`
+
+### Permissions
+
+- `allow`: array of tool patterns (`"Bash(git:*)"`, `"Read"`)
+- `deny`: array of blocked patterns (`"Bash(rm -rf:*)"`)
+- Deny overrides allow
+
+## Example
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/my-hook.js",
+        "timeout": 5
+      }]
+    }]
+  }
+}
+```
+Ref: `settings.json`
+
+## References
+
+For full code examples with variants:
+> Read `references/examples.md`

package/templates/.claude/skills/templates-settings-wiring/references/examples.md

@@ -0,0 +1,59 @@
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+# Settings Wiring Examples
+
+## Example 1: PreToolUse with Multiple Matchers
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/bash-safety.js", "timeout": 5 }]
+    },
+    {
+      "matcher": "Read|Write|Edit",
+      "hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/file-guard.js", "timeout": 5 }]
+    },
+    {
+      "matcher": "Skill",
+      "hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/enforce-registry.js", "timeout": 5 }]
+    }
+  ]
+}
+```
+Ref: `settings.json` (lines 74-114)
+
+## Example 2: PostToolUse with Sequential Hooks
+
+Two hooks run sequentially on the same matcher — format first, then verify:
+
+```json
+{
+  "PostToolUse": [{
+    "matcher": "Write|Edit",
+    "hooks": [
+      { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-format.js", "timeout": 15 },
+      { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-verify.js", "timeout": 5 }
+    ]
+  }]
+}
+```
+Ref: `settings.json` (lines 117-133)
+
+## Example 3: Permission Configuration
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read", "Edit", "Write", "Glob", "Grep", "Skill", "Task",
+      "Bash(git:*)", "Bash(node:*)", "Bash(npm:*)", "Bash(dotnet:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)", "Bash(git push --force:*)", "Bash(git reset --hard:*)",
+      "Bash(shutdown:*)", "Bash(reboot:*)"
+    ]
+  }
+}
+```
+Ref: `settings.json` (lines 8-70)

package/templates/.claude/skills/templates-skill-authoring/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: templates-skill-authoring
+description: "Pattern for writing foundation and subproject skills with YAML frontmatter,
+  pushy descriptions, and references. Use when creating a new skill, writing a
+  SKILL.md, adding skill references, or the user says 'new skill', 'create skill',
+  'add pattern skill', 'write foundation skill'."
+---
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+
+# Skill Authoring Pattern
+
+Skills are auto-loaded by Claude based on task description matching the skill's `description` field.
+
+## Pattern
+
+### File Convention
+- Location: `skills/{skill-name}/SKILL.md` (foundation) or `{sub}/.claude/skills/{skill-name}/SKILL.md` (subproject)
+- YAML frontmatter: `name`, `description`, optional `disable-model-invocation`
+- `<!-- mustard:generated -->` goes AFTER closing `---` (never before opening `---`)
+- Max 500 lines (ideally under 200)
+
+### Description Writing (Critical)
+
+Descriptions are the PRIMARY trigger mechanism. They must be "pushy":
+
+**Good:**
+```yaml
+description: "Pattern for .NET Minimal API endpoints with validation and auth.
+  Use when creating new routes, adding HTTP verbs, wiring endpoints, or the user
+  says 'add endpoint', 'new route', 'expose via API'."
+```
+
+**Bad:**
+```yaml
+description: "API patterns"
+```
+
+### SKILL.md Structure
+
+```markdown
+---
+name: {skill-name}
+description: "{What}. {When — be specific and pushy}."
+---
+<!-- mustard:generated at:{ISO} role:{role} -->
+
+# {Skill Title}
+
+{1-2 sentence summary.}
+
+## Pattern
+
+{Concise rules, file conventions, key constraints.}
+
+## Example
+
+{5-10 line code example — happy path only.}
+Ref: `{path/to/real/file}`
+
+## References
+
+For full code examples with variants:
+> Read `references/examples.md`
+```
+
+### references/examples.md
+
+- 2-3 real examples at different complexity levels
+- Always include `Ref: path/to/file.ext`
+- Max 15 lines per example
+- Starts with `<!-- mustard:generated -->` header
+
+## Example
+
+```yaml
+---
+name: commit-workflow
+description: Git commit strategy, submodule-aware, budget <=15 API calls.
+disable-model-invocation: true
+---
+<!-- mustard:generated -->
+
+# Commit Workflow
+
+> Git strategy for mono-repo with submodules.
+
+## Strategy
+1. `git status` — see all changes
+2. Group changes by subproject
+3. Per subproject: `git add` specific files -> `git commit`
+```
+Ref: `skills/commit-workflow/SKILL.md`
+
+## References
+
+For full code examples with variants:
+> Read `references/examples.md`

package/templates/.claude/skills/templates-skill-authoring/references/examples.md

@@ -0,0 +1,69 @@
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+# Skill Authoring Examples
+
+## Example 1: Simple Foundation Skill (commit-workflow)
+
+```yaml
+---
+name: commit-workflow
+description: Git commit strategy, submodule-aware, budget ≤15 API calls.
+disable-model-invocation: true
+---
+<!-- mustard:generated -->
+
+# Commit Workflow
+
+> Git strategy for mono-repo with submodules. Budget ≤15 API calls.
+
+## Strategy
+1. `git status` — see all changes
+2. `git diff --stat` — understand scope
+3. Group changes by subproject
+4. Per subproject: `git add` specific files → `git commit`
+
+## Rules
+- Budget: ≤15 API calls total
+- NEVER use `git add .` — always specific files
+```
+Ref: `skills/commit-workflow/SKILL.md`
+
+## Example 2: Complex Skill with References (pipeline-execution)
+
+```yaml
+---
+name: pipeline-execution
+description: Pipeline phases, dispatch rules, wave system, validate, retry.
+  Load for /feature /resume /approve.
+disable-model-invocation: true
+---
+<!-- mustard:generated -->
+
+# Pipeline Execution Detail
+
+> Phases, role rules, dispatch mechanics, validation, bugfix paths.
+
+## Pipeline Feature
+### ANALYZE Phase
+1. AUTO-SYNC: `node .claude/scripts/sync-registry.js`
+2. Read `entity-registry.json` → entity found? → infer layers
+```
+Ref: `skills/pipeline-execution/SKILL.md`
+
+## Example 3: Skill with Rich References (design-craft)
+
+Structure with multiple reference files:
+
+```
+skills/design-craft/
+├── SKILL.md
+└── references/
+    ├── critique.md
+    ├── example.md
+    ├── palettes-catalog.md
+    ├── principles.md
+    ├── styles-catalog.md
+    ├── typography-catalog.md
+    ├── ux-guidelines.md
+    └── validation.md
+```
+Ref: `skills/design-craft/SKILL.md`

package/templates/.claude/skills/templates-sync-detect/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: templates-sync-detect
+description: "Pattern for subproject discovery, role detection via scoring, and SHA-256
+  incremental hashing in sync-detect.js. Use when modifying detection logic,
+  adding a new role/stack, changing hash computation, adding new scoring signals,
+  or the user says 'add stack detection', 'new role', 'detect framework',
+  'fix detection', 'change scoring'."
+---
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+
+# Sync-Detect Pattern
+
+sync-detect.js discovers subprojects, detects their role via weighted scoring, and computes SHA-256 hashes for incremental scan.
+
+## Pattern
+
+### Discovery Order
+1. `git submodule status` — prefer submodule paths
+2. Fallback: scan root for dirs containing `CLAUDE.md`
+
+### Role Scoring (weighted signals)
+
+| Weight | Constant | Signal Type |
+|--------|----------|-------------|
+| 10 | `HIGH` | Config files: `.csproj` Sdk.Web, `next.config.*`, `drizzle.config.*`, `pubspec.yaml` |
+| 5 | `MEDIUM` | Package deps: `react`, `express`, `drizzle-orm` in package.json |
+| 3 | `LOW` | Directories: `Controllers/`, `app/`+`components/`, `migrations/` |
+
+Roles: `api`, `ui`, `database`, `library`, `mobile`, `general` (fallback).
+Role maps to agent: `api→backend`, `ui→frontend`, `database→database`, `library→backend`, `mobile→mobile`.
+
+### Incremental Hashing
+- Collect source files (`.cs`, `.ts`, `.tsx`, `.js`, `.jsx`, `.dart`)
+- Exclude: `node_modules`, `.next`, `bin`, `obj`, `dist`, `migrations`, `_backup`, dotfiles
+- Sort files → hash(path + content) per file → SHA-256 digest
+- Module-level hashes for fine-grained incremental (backend: `Modules/v{N}/{Module}/`, frontend: `app/(dashboard)/*/`)
+
+### Output
+JSON to stdout: `{ subprojects, agents, detectedAgents, sourceHashes, moduleHashes }`
+Writes `.claude/.detect-cache.json` (unless `--no-cache`).
+
+## Example
+
+```js
+function detectRole(absPath) {
+  const scores = { api: 0, ui: 0, database: 0, library: 0, mobile: 0 };
+  if (isCsprojWeb(absPath)) scores.api += 10;
+  if (fileExists(absPath, 'next.config.*')) scores.ui += 10;
+  // ... more signals ...
+  let maxScore = 0, role = 'general';
+  for (const [r, s] of Object.entries(scores)) {
+    if (s > maxScore) { maxScore = s; role = r; }
+  }
+  return { role, scores };
+}
+```
+Ref: `scripts/sync-detect.js`
+
+## References
+
+For full code examples with variants:
+> Read `references/examples.md`

package/templates/.claude/skills/templates-sync-detect/references/examples.md

@@ -0,0 +1,55 @@
+<!-- mustard:generated at:2026-03-25T00:00:00.000Z role:general -->
+# Sync-Detect Examples
+
+## Example 1: Adding a New Role Signal
+
+To detect a new framework, add scoring in `detectRole()`:
+
+```js
+// In detectRole(absPath):
+// Python FastAPI → api (HIGH)
+if (fileExists(absPath, 'pyproject.toml')) {
+  if (pyprojectHas(absPath, ['fastapi', 'django', 'flask'])) {
+    scores.api += ROLE_WEIGHTS.HIGH;
+  }
+}
+```
+Ref: `scripts/sync-detect.js` (lines 271-276)
+
+## Example 2: Adding Package.json Dep Detection
+
+```js
+const deps = getPackageJsonDeps(absPath);
+if (deps.length > 0) {
+  if (hasAnyDep(deps, ['express', 'fastify', 'hono', 'koa', 'nestjs'])) {
+    scores.api += ROLE_WEIGHTS.MEDIUM;
+  }
+  if (hasAnyDep(deps, ['react', 'next', 'vue', 'nuxt', 'svelte'])) {
+    scores.ui += ROLE_WEIGHTS.MEDIUM;
+  }
+}
+```
+Ref: `scripts/sync-detect.js` (lines 240-254)
+
+## Example 3: Module-Level Hash Computation
+
+```js
+function computeModuleHashes(subprojectPath, role) {
+  const modules = {};
+  if (role === 'api' || role === 'library') {
+    const allModuleDirs = findAllModulesDirs(absPath);
+    // ... collect files per module, compute SHA-256 per module
+    for (const [modName, files] of Object.entries(moduleFiles)) {
+      files.sort();
+      const hash = crypto.createHash('sha256');
+      for (const f of files) {
+        hash.update(f);
+        hash.update(fs.readFileSync(path.join(ROOT, f), 'utf-8'));
+      }
+      modules[modName] = { hash: hash.digest('hex'), files: files.length };
+    }
+  }
+  return modules;
+}
+```
+Ref: `scripts/sync-detect.js` (lines 665-784)

package/templates/CLAUDE.md

@@ -26,5 +26,52 @@ ANALYZE → PLAN → EXECUTE → CLOSE
 Agents auto-load skills from `{subproject}/.claude/skills/` based on task description.
 Guards always loaded via `{subproject}/CLAUDE.md`.
 
+## Stack
+
+Node.js (>=18), CommonJS, no external dependencies. 8 lifecycle hooks, 3 sync scripts, 14 slash commands, 6 foundation skills.
+
+## Commands
+
+```bash
+# Run hook tests
+node --test hooks/__tests__/hooks.test.js
+
+# Subproject discovery (outputs JSON)
+node scripts/sync-detect.js
+node scripts/sync-detect.js --no-cache
+
+# Entity registry generation
+node scripts/sync-registry.js
+node scripts/sync-registry.js --force
+```
+
+## Guards
+
+- All hooks fail-open (exit 0 on error) — never block due to hook bugs
+- All hooks use only Node.js built-ins — no npm dependencies
+- PreToolUse hooks use `permissionDecision` response format
+- PostToolUse hooks use `decision` response format
+- Every new hook must be registered in `settings.json` with a timeout
+- Generated files must start with `<!-- mustard:generated -->` header
+- Skills must have YAML frontmatter BEFORE the `<!-- mustard:generated -->` line
+
+## Scan References
+
+| File | Description |
+|------|-------------|
+| `.claude/commands/stack.md` | Technology stack, structure, tooling |
+| `.claude/commands/patterns.md` | 12 recurring code patterns with refs |
+| `.claude/commands/guards.md` | DO/DON'T rules for hooks, scripts, commands, skills |
+| `.claude/commands/recipes.md` | Implementation recipes for new hooks, commands, skills, scripts |
+| `.claude/commands/notes.md` | Manual notes (never overwritten) |
+
+## Recommended Skills
+
+- `templates-hook-protocol` — Hook stdin/stdout JSON protocol
+- `templates-settings-wiring` — settings.json hook registration
+- `templates-sync-detect` — Subproject discovery and role detection
+- `templates-command-authoring` — Slash command SKILL.md structure
+- `templates-skill-authoring` — Foundation/subproject skill creation
+
 ## Full Reference
 Rules, pipeline, naming: `pipeline-config.md`

package/templates/settings.json

@@ -7,16 +7,16 @@
 
   "permissions": {
     "allow": [
-      "Bash(git:*)",
-      "Bash(cd:*)",
-      "Bash(find:*)",
-      "Bash(ls:*)",
-      "Bash(cat:*)",
-      "Bash(echo:*)",
-      "Bash(node:*)",
-      "Bash(pnpm:*)",
-      "Bash(dotnet build:*)",
-      "Bash(dotnet test:*)"
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "Skill",
+      "Task",
+      "WebFetch",
+      "WebSearch",
+      "Bash"
     ],
     "deny": [
       "Bash(rm -rf:*)",