create-claude-cabinet 0.6.0

package/templates/hooks/skill-telemetry.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# UserPromptSubmit hook for skill telemetry
+# Detects /skill-name invocations and logs to JSONL
+#
+# Configuration (environment variables with defaults):
+#   TELEMETRY_FILE — where to write JSONL records
+#   DEBUG_LOG      — where to write debug output
+#   SKILL_DIR      — where to discover skills (scans */SKILL.md)
+
+TELEMETRY_DIR="${TELEMETRY_DIR:-${HOME}/.claude/telemetry}"
+TELEMETRY_FILE="${TELEMETRY_FILE:-${TELEMETRY_DIR}/telemetry.jsonl}"
+DEBUG_LOG="${DEBUG_LOG:-${TELEMETRY_DIR}/hook-debug.log}"
+SKILL_DIR="${SKILL_DIR:-${HOME}/.claude/skills}"
+
+# Ensure telemetry directory exists
+mkdir -p "$(dirname "$TELEMETRY_FILE")"
+mkdir -p "$(dirname "$DEBUG_LOG")"
+
+# Auto-discover skill names from skills/*/SKILL.md
+SKILLS=""
+for skill_path in "$SKILL_DIR"/*/SKILL.md; do
+    [ -f "$skill_path" ] || continue
+    skill=$(basename "$(dirname "$skill_path")")
+    [ "$skill" = "perspectives" ] && continue
+    [ "$skill" = "_template" ] && continue
+    SKILLS="$SKILLS $skill"
+done
+
+# Read hook input from stdin, extract prompt and session_id
+INPUT=$(cat)
+eval "$(echo "$INPUT" | python3 -c "
+import sys, json, shlex
+try:
+    data = json.load(sys.stdin)
+    print(f'PROMPT={shlex.quote(data.get(\"prompt\", \"\"))}')
+    print(f'SESSION_ID={shlex.quote(data.get(\"session_id\", \"unknown\"))}')
+except:
+    print('PROMPT=\"\"')
+    print('SESSION_ID=\"unknown\"')
+" 2>/dev/null)"
+
+# Check if prompt starts with a slash command
+if [[ "$PROMPT" =~ ^/([a-z-]+) ]]; then
+    COMMAND="${BASH_REMATCH[1]}"
+
+    # Check if it's a known skill
+    for skill in $SKILLS; do
+        if [[ "$COMMAND" == "$skill" ]]; then
+            TIMESTAMP=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
+            python3 -c "
+import json
+record = {
+    'ts': '$TIMESTAMP',
+    'event': 'skill-invoke',
+    'skill': '$COMMAND',
+    'session_id': '$SESSION_ID'
+}
+print(json.dumps(record))
+" >> "$TELEMETRY_FILE"
+            echo "--- skill-telemetry $TIMESTAMP skill=$COMMAND ---" >> "$DEBUG_LOG"
+            break
+        fi
+    done
+fi
+
+exit 0

package/templates/hooks/skill-tool-telemetry.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# PostToolUse hook for Skill tool telemetry
+# Captures programmatic Skill invocations (not user-typed /slash-commands)
+# Complements skill-telemetry.sh (UserPromptSubmit) for full coverage
+#
+# Configuration (environment variables with defaults):
+#   TELEMETRY_FILE — where to write JSONL records
+#   DEBUG_LOG      — where to write debug output
+
+TELEMETRY_DIR="${TELEMETRY_DIR:-${HOME}/.claude/telemetry}"
+TELEMETRY_FILE="${TELEMETRY_FILE:-${TELEMETRY_DIR}/telemetry.jsonl}"
+DEBUG_LOG="${DEBUG_LOG:-${TELEMETRY_DIR}/hook-debug.log}"
+
+# Ensure telemetry directory exists
+mkdir -p "$(dirname "$TELEMETRY_FILE")"
+mkdir -p "$(dirname "$DEBUG_LOG")"
+
+# Read hook input from stdin
+INPUT=$(cat)
+
+# Extract skill name and session_id from the tool input
+eval "$(echo "$INPUT" | python3 -c "
+import sys, json, shlex
+try:
+    data = json.load(sys.stdin)
+    tool_input = data.get('tool_input', {})
+    if isinstance(tool_input, str):
+        tool_input = json.loads(tool_input)
+    skill = tool_input.get('skill', '')
+    session_id = data.get('session_id', 'unknown')
+    print(f'SKILL={shlex.quote(skill)}')
+    print(f'SESSION_ID={shlex.quote(session_id)}')
+except:
+    print('SKILL=\"\"')
+    print('SESSION_ID=\"unknown\"')
+" 2>/dev/null)"
+
+if [[ -n "$SKILL" ]]; then
+    TIMESTAMP=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
+    python3 -c "
+import json
+record = {
+    'ts': '$TIMESTAMP',
+    'event': 'skill-invoke',
+    'skill': '$SKILL',
+    'source': 'tool',
+    'session_id': '$SESSION_ID'
+}
+print(json.dumps(record))
+" >> "$TELEMETRY_FILE"
+    echo "--- skill-tool-telemetry $TIMESTAMP skill=$SKILL ---" >> "$DEBUG_LOG"
+fi
+
+exit 0

package/templates/hooks/stop-hook.md

@@ -0,0 +1,56 @@
+# Stop Hook Template
+
+The Stop hook fires when a session is ending. It checks whether
+substantive work was done without running the session-closing skill
+(e.g., `/debrief`). If yes, it prompts to run it.
+
+## How to Install
+
+Add this to your `.claude/settings.json` under the `hooks` key:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Check if substantive work was done without running the session-closing skill. If yes, prompt to run it.",
+            "statusMessage": "Checking session close compliance..."
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## How It Works
+
+- **Event:** `Stop` — fires when the user ends the session
+- **Type:** `prompt` — an LLM-evaluated check, not a deterministic script
+- **Compliance:** ~80% — prompt-type hooks are advisory, not blocking
+
+## Customization
+
+Replace the prompt text with your project's specific closing skill name:
+
+```
+"Check if substantive work was done without /debrief. If yes, prompt to run it."
+```
+
+This is the single most important anti-entropy hook in the methodology.
+Without it, sessions end without capturing what happened, and the next
+session starts blind. The session loop (orient → work → debrief) is the
+system's learning mechanism. This hook guards the debrief step.
+
+## Limitations
+
+This is a prompt-type hook, not a command hook. It asks the LLM to check
+and prompt — it doesn't deterministically block the session from ending.
+Compliance is imperfect. This is an honest example of the anti-entropy
+principle in action: debrief compliance has been a recurring friction
+point in the reference implementation, promoted to a hook. It's better
+than without. It's not 100%.

package/templates/memory/patterns/_pattern-template.md

@@ -0,0 +1,119 @@
+# Pattern File Format Template
+
+This documents the frontmatter schema for feedback patterns — the
+reusable structure for any project's feedback-to-enforcement pipeline.
+
+## How Patterns Work
+
+Patterns consolidate recurring observations (friction, mistakes, things
+that worked) into named rules with enforcement classification. They are
+the intermediate step between raw feedback captures and enforced rules.
+
+## The Schema
+
+```yaml
+---
+name: pattern-descriptive-name
+description: >
+  One-line description of what this pattern captures. Should be specific
+  enough to decide relevance without reading the full content.
+type: pattern
+sources:
+  - feedback-observation-that-led-to-this.md
+  - another-observation.md
+  - a-third-observation.md
+enforcement: guide | detect | prevent | document
+promotion_candidates:
+  - rule-or-hook-name-if-ready-for-promotion
+---
+```
+
+## Fields
+
+### `name`
+Descriptive slug. Convention: `pattern-{domain}-{topic}` or just
+`pattern-{topic}`.
+
+### `description`
+One-line summary. Used by orient/debrief to decide whether to load
+the full pattern. Be specific — "deployment issues" is too vague;
+"silent deployment failures and stale build log output" is useful.
+
+### `type`
+Always `pattern` for consolidated feedback patterns.
+
+### `sources`
+List of raw observation files that were consolidated into this pattern.
+Preserves provenance — you can trace any rule back to the specific
+incidents that motivated it.
+
+### `enforcement`
+How this pattern should be enforced. Determines promotion target:
+
+| Value | Meaning | Compliance | Promotion Target |
+|-------|---------|------------|-----------------|
+| **guide** | Prompt context (CLAUDE.md or memory) | ~60-80% | Rules file or CLAUDE.md section |
+| **detect** | Validation script or PostToolUse hook | ~80-90% | Validation script |
+| **prevent** | PreToolUse hook or pre-commit hook | ~100% | Deterministic hook |
+| **document** | Reference material, not a rule | N/A | Documentation |
+
+### `promotion_candidates`
+Specific rules within this pattern that are ready to move up the
+compliance stack. Empty list `[]` if nothing is ready for promotion.
+
+## Body Structure
+
+After the frontmatter, the body follows this structure:
+
+```markdown
+## Principle
+
+One paragraph: the core lesson this pattern encodes.
+
+## Rules
+
+- Concrete, actionable rules derived from the principle.
+- Each rule should be testable — you can tell whether it was followed.
+
+## When This Applies
+
+When to apply these rules (triggers, file types, situations).
+```
+
+## Example
+
+```yaml
+---
+name: pattern-deployment-verification
+description: >
+  Silent deployment failures and stale CLI output — always verify
+  deployments through authoritative sources, not just CLI success messages.
+type: pattern
+sources:
+  - feedback-railway-stale-logs.md
+  - feedback-deploy-without-verify.md
+  - feedback-silent-build-failure.md
+enforcement: detect
+promotion_candidates:
+  - post-deploy-verification-hook
+---
+
+## Principle
+
+Deployment tools report success based on submission, not outcome. The
+CLI saying "deployed" means "I sent the request," not "it's running."
+Always verify through the deployment platform's authoritative source.
+
+## Rules
+
+- After every deploy, verify the change is live (hit the endpoint,
+  check the dashboard, read the build log from the platform itself).
+- If the CLI build log is stale, use the web dashboard as fallback.
+- Never assume a deploy worked because the command exited 0.
+
+## When This Applies
+
+Any deployment to a remote platform (Railway, Vercel, AWS, etc.).
+Also applies to LaunchAgent restarts and any operation where the
+success indicator is decoupled from the actual outcome.
+```

package/templates/memory/patterns/pattern-intelligence-first.md

@@ -0,0 +1,41 @@
+---
+name: pattern-intelligence-first
+description: Intelligence over regex — use structured JSON between tools, don't let regex gatekeep LLM access, research thoroughly before coding
+type: pattern
+sources:
+  - feedback-intelligence-vs-regex.md
+  - feedback-intelligence-not-regex.md
+  - feedback-research-before-iterating.md
+  - feedback-use-framework-docs-mcp.md
+enforcement: guide
+promotion_candidates: []
+---
+
+## Principle
+
+When the task is semantic (understanding structure, classifying items,
+extracting meaning), regex is the wrong tool. It creates brittle parsers
+that break on edge cases the author didn't anticipate. Similarly, when
+building detection or integration features, blind iteration wastes hours
+that 30 minutes of research would have saved. **Use intelligence for
+semantic work and research for unfamiliar territory.**
+
+## Rules
+
+- **Use structured output (JSON) not brittle delimiter parsing** for
+  tool-to-tool data pipelines. When an LLM produces output that another
+  tool consumes, use JSON — never regex over free text.
+- **Never let regex gatekeep LLM access to content.** If content needs
+  semantic understanding, try focused LLM extraction first, fall back to
+  full content only if needed.
+- **Research thoroughly before coding** detection/integration features.
+  Don't iterate blind — 30 minutes of research saves hours of wrong
+  approaches.
+- **Check framework-docs MCP before web-searching.** If a library/service
+  has an `llms.txt`, add it to `.mcp.json`. The docs are faster and more
+  accurate than web search.
+
+## When This Applies
+
+When building parsers, data pipelines between tools, content extraction
+systems, or any feature that integrates with unfamiliar APIs or platforms.

package/templates/rules/enforcement-pipeline.md

@@ -0,0 +1,151 @@
+# Enforcement Pipeline
+
+Rules don't arrive fully formed. They start as friction — something went
+wrong, someone noticed, it got written down. This pipeline turns friction
+into structure over time.
+
+## The Compliance Stack
+
+Not all rules need the same enforcement. The stack gives each rule a
+natural home based on two questions: *Can it be checked mechanically?*
+and *What's the cost of violation?*
+
+| Layer          | Mechanism                   | Compliance | Best For                           |
+| -------------- | --------------------------- | ---------- | ---------------------------------- |
+| CLAUDE.md      | Prompt context              | ~60-80%    | Intent, heuristics, judgment calls |
+| .claude/rules/ | Scoped prompt               | ~80%       | Path-specific constraints          |
+| Hooks          | Deterministic shell scripts | ~100%      | Hard guardrails                    |
+
+A principle like "ask rather than assume when something affects
+correctness" belongs in CLAUDE.md. It requires judgment. A rule like
+"never commit without a fid tag" belongs in a hook. It's deterministic,
+and the consequence of violating it is severe.
+
+**The best enforcement isn't enforcement at all — it's structural
+encoding that makes the wrong thing impossible.** A pre-commit hook
+doesn't remind you to do something. It blocks the commit until the
+condition is met. The wrong state can't enter the system. When you can
+encode a rule structurally (API rejects invalid input, schema enforces
+constraints), prefer that over any compliance layer.
+
+## Pipeline Stages
+
+### 1. Capture (every session, during debrief)
+
+Record what went wrong or what worked unexpectedly. Raw observations,
+not polished rules.
+
+- Save to memory or a feedback directory (raw observation files)
+- Check if it fits an existing pattern:
+  - **MERGE** — same ground as an existing pattern → update that pattern
+  - **KEEP_SEPARATE** — distinct observation → stays as individual file
+  - **REPLACE** — supersedes an existing observation → remove old
+  - **UPDATE** — enriches an existing pattern → add to pattern's evidence
+- If 3+ related observations accumulate without a pattern, create one
+
+### 2. Classify (at capture time)
+
+Every observation or pattern gets an enforcement type:
+
+- **prevent** — candidate for a hook (~100% compliance needed)
+- **detect** — candidate for a validation script or post-action check
+- **guide** — stays as prompt context (CLAUDE.md or rules file)
+- **document** — reference material, not a rule
+
+Classification drives what promotion means for that pattern.
+
+### 3. Promote (periodic review)
+
+When observations about the same class of problem accumulate, they
+consolidate into a pattern and may move up the compliance stack.
+
+**Promotion criteria are intelligence, not thresholds.** There is no
+magic number of observations that triggers promotion. One catastrophic
+incident can justify immediate promotion to a hook. A dozen minor
+annoyances might stay as guidance forever. The human decides what to
+promote and when, informed by severity and pattern, not by count.
+
+Promotion moves a rule up the stack:
+- CLAUDE.md guidance → `.claude/rules/` file (scoped, more reliable)
+- Rules file → hook (deterministic, ~100% compliance)
+- Any layer → structural encoding (makes the wrong thing impossible)
+
+### 4. Encode (after promotion approval)
+
+Implement the promoted rule at its target layer:
+- **CLAUDE.md promotion:** Add to root CLAUDE.md or create/update a
+  `.claude/rules/` file
+- **Hook promotion:** Add to `.claude/settings.json` hooks section.
+  Command hooks for deterministic checks, prompt hooks for semantic
+  evaluation.
+- **Structural encoding:** Modify API, schema, or validation to reject
+  invalid states directly
+
+### 5. Monitor (ongoing)
+
+Are the rules working?
+- Are hooks firing correctly?
+- Is the same friction appearing despite encoding? (If yes, the
+  encoding is wrong — either the rule is at the wrong layer or the
+  implementation doesn't catch the actual failure mode.)
+- Are there dead rules? (Rules that reference files or patterns that
+  no longer exist.)
+- Is unabsorbed feedback accumulating without being consolidated?
+
+## Pattern File Format
+
+Use the pattern template in `memory/patterns/_pattern-template.md` for
+capturing consolidated patterns. Each pattern file has frontmatter with
+the enforcement type, sources (raw observations that fed into it), and
+promotion candidates (specific rules ready for promotion).
+
+## Where Each Step Lives
+
+| Step | Owner | When |
+|------|-------|------|
+| Capture + Classify | /debrief | Every session |
+| Pattern analysis | Periodic review | As feedback accumulates |
+| Promotion checkpoint | Review cadence | When patterns mature |
+| Enforcement health | /orient or /pulse | Regular check |
+
+## Audit Findings as Promotion Input
+
+The audit system feeds the enforcement pipeline. When the same type of
+finding keeps getting approved across multiple audit runs, it signals a
+recurring problem that detection alone isn't solving. That's a promotion
+candidate.
+
+**The virtuous cycle:** Audit detects a pattern → triage approves it →
+the fix is applied → the same finding appears again next audit → this
+time, instead of just fixing it again, the pattern gets promoted to a
+rule or hook that *prevents* it from recurring. The audit catches
+problems; the enforcement pipeline prevents them.
+
+**Signals that a finding should become a rule:**
+- Same finding (or same class of finding) approved in 3+ audit runs
+- Finding addresses something mechanically checkable (could be a hook)
+- Finding addresses something that requires judgment but has a clear
+  principle (could be a CLAUDE.md rule or `.claude/rules/` file)
+- The cost of violation is high enough to justify enforcement
+
+**Signals that a finding should stay a finding:**
+- One-time issue that was fixed and won't recur
+- Context-dependent — the right answer changes each time
+- Low severity — enforcement overhead exceeds violation cost
+
+The audit skill's triage history tracks which findings recur. The
+enforcement pipeline's pattern files track which recurring findings are
+ready for promotion. Together, they create a feedback loop from
+observation to prevention.
+
+## Current State
+
+<!--
+Track your project's enforcement pipeline state here:
+
+- **N pattern files** in memory/patterns/
+- **N raw observations** in memory/archive/ (or wherever you store them)
+- **N rules files** in .claude/rules/
+- **N hooks** in .claude/settings.json
+- **N promotion candidates** identified
+-->

package/templates/scripts/cor-drift-check.cjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// CoR Drift Check — detect modified upstream-managed files
+//
+// Compares current file hashes against .corrc.json manifest hashes.
+// Reports files that have been modified since install (drift).
+//
+// Usage:
+//   node scripts/cor-drift-check.js          # exit 0 if clean, 1 if drift
+//   node scripts/cor-drift-check.js --json   # output JSON for programmatic use
+//   node scripts/cor-drift-check.js --fix    # show what /cor-upgrade would fix
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const projectRoot = findProjectRoot();
+if (!projectRoot) {
+  console.error('No .corrc.json found — not a CoR project.');
+  process.exit(2);
+}
+
+const metadataPath = path.join(projectRoot, '.corrc.json');
+const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+const manifest = metadata.manifest || {};
+
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.corrc.json'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function hashContent(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+const drifted = [];
+const missing = [];
+const clean = [];
+
+for (const [relPath, expectedHash] of Object.entries(manifest)) {
+  const fullPath = path.join(projectRoot, relPath);
+
+  if (!fs.existsSync(fullPath)) {
+    missing.push(relPath);
+    continue;
+  }
+
+  const content = fs.readFileSync(fullPath, 'utf8');
+  const currentHash = hashContent(content);
+
+  if (currentHash !== expectedHash) {
+    drifted.push(relPath);
+  } else {
+    clean.push(relPath);
+  }
+}
+
+const args = process.argv.slice(2);
+
+if (args.includes('--json')) {
+  console.log(JSON.stringify({ drifted, missing, clean: clean.length }, null, 2));
+} else {
+  if (drifted.length === 0 && missing.length === 0) {
+    console.log(`All ${clean.length} CoR-managed files match upstream hashes.`);
+  } else {
+    if (drifted.length > 0) {
+      console.log(`Drifted (${drifted.length} files modified from upstream):`);
+      for (const f of drifted) console.log(`  ${f}`);
+    }
+    if (missing.length > 0) {
+      console.log(`Missing (${missing.length} files deleted):`);
+      for (const f of missing) console.log(`  ${f}`);
+    }
+    console.log(`\nClean: ${clean.length} files match.`);
+    if (args.includes('--fix')) {
+      console.log('\nRun /cor-upgrade to restore drifted files to upstream versions.');
+    }
+  }
+}
+
+process.exit(drifted.length > 0 || missing.length > 0 ? 1 : 0);

package/templates/scripts/finding-schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["findings", "meta"],
+  "properties": {
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "perspective", "severity", "title", "description", "autoFixable"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique finding ID: {cabinet-member}-{NNNN}",
+            "pattern": "^[a-z-]+-\\d{4}$"
+          },
+          "perspective": {
+            "type": "string",
+            "description": "Cabinet member name matching the directory name in skills/cabinet-*/",
+            "pattern": "^[a-z][a-z0-9-]+$"
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "warn", "info", "idea"],
+            "description": "critical = data loss/breakage, warn = degradation/drift, info = improvement opportunity, idea = suggestion"
+          },
+          "title": {
+            "type": "string",
+            "maxLength": 120,
+            "description": "Short description of the finding"
+          },
+          "description": {
+            "type": "string",
+            "description": "Full explanation of the finding"
+          },
+          "assumption": {
+            "type": "string",
+            "description": "What the auditor assumes the intent was"
+          },
+          "evidence": {
+            "type": "string",
+            "description": "What was observed that led to this finding"
+          },
+          "question": {
+            "type": "string",
+            "description": "What the auditor is uncertain about — invites human judgment"
+          },
+          "file": {
+            "type": "string",
+            "description": "Primary file path relative to repo root, if applicable"
+          },
+          "line": {
+            "type": "integer",
+            "description": "Line number in the file, if applicable"
+          },
+          "suggestedFix": {
+            "type": "string",
+            "description": "Proposed fix or approach"
+          },
+          "type": {
+            "type": "string",
+            "enum": ["finding", "positive"],
+            "default": "finding",
+            "description": "finding = issue to triage, positive = health confirmation (not triageable)"
+          },
+          "autoFixable": {
+            "type": "boolean",
+            "description": "Whether a fix agent could resolve this without human judgment"
+          },
+          "reference": {
+            "type": "string",
+            "description": "URL or source reference"
+          },
+          "tags": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Categorization tags for filtering"
+          }
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "required": ["perspective", "timestamp"],
+      "properties": {
+        "perspective": { "type": "string" },
+        "timestamp": { "type": "string", "format": "date-time" },
+        "commitHash": { "type": "string" },
+        "durationSeconds": { "type": "number" },
+        "model": { "type": "string" }
+      }
+    }
+  }
+}