@stackmemoryai/stackmemory 0.5.67 → 0.6.0

package/README.md

@@ -14,7 +14,9 @@ StackMemory is a **production-ready memory runtime** for AI coding tools that pr
 - **Full Linear integration** with bidirectional sync
 - **Context persistence** that survives /clear operations
 - **Hierarchical frame organization** (nested call stack model)
-- **490 tests passing** with comprehensive coverage
+- **Skills system** with `/spec` and `/linear-run` for Claude Code
+- **Automatic hooks** for task tracking, Linear sync, and spec progress
+- **498 tests passing** with comprehensive coverage
 
 Instead of a linear chat log, StackMemory organizes memory as a **call stack** of scoped work (frames), with intelligent LLM-driven retrieval and team collaboration features.
 
@@ -34,13 +36,13 @@ Tools forget decisions and constraints between sessions. StackMemory makes conte
 
 ## Features (at a glance)
 
-- MCP tools for Claude Code: 26+ tools; context on every request
-- Safe branches: worktree isolation with `--worktree` or `-w`
-- Persistent context: frames, anchors, decisions, retrieval
-- Optional boosts: model routing, prompt optimization (GEPA)
-- Integrations: Linear, Greptile, DiffMem, Browser MCP
-
-See the docs directory for deeper feature guides.
+- **MCP tools** for Claude Code: 26+ tools; context on every request
+- **Skills**: `/spec` (iterative spec generation), `/linear-run` (task execution via RLM)
+- **Hooks**: automatic context save, task tracking, Linear sync, PROMPT_PLAN updates
+- **Prompt Forge**: watches AGENTS.md and CLAUDE.md for prompt optimization (GEPA)
+- **Safe branches**: worktree isolation with `--worktree` or `-w`
+- **Persistent context**: frames, anchors, decisions, retrieval
+- **Integrations**: Linear, Greptile, DiffMem, Browser MCP
 
 ---
 
@@ -131,13 +133,127 @@ Env defaults (optional):
 
 ---
 
-## Quick Start
+## Skills System
+
+StackMemory ships Claude Code skills that integrate directly into your workflow. Skills are invoked via `/skill-name` in Claude Code or `stackmemory skills <name>` from the CLI.
+
+### Spec Generator (`/spec`)
+
+Generates iterative spec documents following a 4-doc progressive chain. Each document reads previous ones from disk for context.
+
+```
+ONE_PAGER.md  →  DEV_SPEC.md  →  PROMPT_PLAN.md  →  AGENTS.md
+(standalone)     (reads 1)       (reads 1+2)        (reads 1+2+3)
+```
+
+```bash
+# Generate specs in order
+/spec one-pager "My App"          # Problem, audience, core flow, MVP
+/spec dev-spec                    # Architecture, tech stack, APIs
+/spec prompt-plan                 # TDD stages A-G with checkboxes
+/spec agents                      # Agent guardrails and responsibilities
+
+# Manage progress
+/spec list                        # Show existing specs
+/spec update prompt-plan "auth"   # Check off matching items
+/spec validate prompt-plan        # Check completion status
+
+# CLI equivalent
+stackmemory skills spec one-pager "My App"
+```
+
+Output goes to `docs/specs/`. Use `--force` to regenerate an existing spec.
+
+### Linear Task Runner (`/linear-run`)
+
+Pulls tasks from Linear, executes them via the RLM orchestrator (8 subagent types), and syncs results back.
+
+```bash
+/linear-run next                  # Execute next todo task
+/linear-run next --priority high  # Filter by priority
+/linear-run all                   # Execute all pending tasks
+/linear-run all --dry-run         # Preview without executing
+/linear-run task STA-123          # Run a specific task
+/linear-run preview               # Show execution plan
+
+# CLI equivalent
+stackmemory ralph linear next
+```
+
+On task completion:
+1. Marks the Linear task as `done`
+2. Auto-checks matching PROMPT_PLAN items
+3. Syncs metrics (tokens, cost, tests) back to Linear
+
+Options: `--priority <level>`, `--tag <tag>`, `--dry-run`, `--maxConcurrent <n>`
+
+---
+
+## Hooks (Automatic)
+
+StackMemory installs Claude Code hooks that run automatically during your session. Hooks are non-blocking and fail silently to never interrupt your workflow.
+
+### Installed Hooks
+
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `on-task-complete` | Task marked done | Saves context, syncs Linear (STA-* tasks), auto-checks PROMPT_PLAN items |
+| `on-startup` | Session start | Loads StackMemory context, initializes frame |
+| `on-clear` | `/clear` command | Persists context before clearing |
+| `skill-eval` | User prompt | Scores prompt against 28 skill patterns, recommends relevant skills |
+| `tool-use-trace` | Tool invocation | Logs tool usage for context tracking |
+
+### Skill Evaluation
+
+When you type a prompt, the `skill-eval` hook scores it against `skill-rules.json` (28 mapped skills with keyword, pattern, intent, and directory matching). Skills scoring above the threshold (default: 3) are recommended.
+
+```json
+// Example: user types "generate a spec for the auth system"
+// skill-eval recommends:
+{
+  "recommendedSkills": [
+    { "skillName": "spec-generator", "score": 8 },
+    { "skillName": "frame-management", "score": 5 }
+  ]
+}
+```
+
+### Hook Installation
+
+Hooks install automatically during `npm install` (with user consent). To install or reinstall manually:
+
+```bash
+# Automatic (prompted during npm install)
+npm install -g @stackmemoryai/stackmemory
+
+# Manual install
+stackmemory hooks install
 
-See above for install and minimal usage. For advanced options, see Setup.
+# Skip hooks (CI/non-interactive)
+STACKMEMORY_AUTO_HOOKS=true npm install -g @stackmemoryai/stackmemory
+```
+
+Hooks are stored in `~/.claude/hooks/` and configured via `~/.claude/hooks.json`.
+
+### PROMPT_PLAN Auto-Progress
+
+When a task completes (via hook or `/linear-run`), StackMemory fuzzy-matches the task title against unchecked `- [ ]` items in `docs/specs/PROMPT_PLAN.md` and checks them off automatically. One item per task completion, best-effort.
 
 ---
 
-## 2. Detailed Setup
+## Prompt Forge (GEPA)
+
+When launching via `claude-sm`, StackMemory watches `CLAUDE.md`, `AGENT.md`, and `AGENTS.md` for changes. On file modification, the GEPA optimizer analyzes content and suggests improvements for prompt clarity and structure. Runs as a detached background process.
+
+```bash
+# Launch with Prompt Forge active
+claude-sm
+
+# Status shown in terminal:
+# Prompt Forge: watching CLAUDE.md, AGENTS.md for optimization
+```
+
+---
 
 ### Install
 
@@ -180,15 +296,11 @@ stackmemory doctor
 
 Checks project initialization, database integrity, MCP config, and suggests fixes.
 
----
-
-## 3. Advanced Setup
-
-See https://github.com/stackmemoryai/stackmemory/blob/main/docs/setup.md for advanced options (hosted mode, ChromaDB, manual MCP config, and available tools).
+See [docs/setup.md](https://github.com/stackmemoryai/stackmemory/blob/main/docs/setup.md) for advanced options (hosted mode, ChromaDB, manual MCP config).
 
 ---
 
-## 2. Open-Source Local Mode
+## Open-Source Local Mode
 
 ### Step 1: Clone & Build
 
@@ -285,35 +397,17 @@ StackMemory implements an intelligent two-tier storage architecture:
 
 ## Claude Code Integration
 
-StackMemory can automatically save context when using Claude Code, so your AI assistant has access to previous context and decisions.
-
-### Quick Setup
+StackMemory integrates with Claude Code via MCP tools, skills, and hooks. See the [Hooks](#hooks-automatic) and [Skills](#skills-system) sections above.
 
 ```bash
-# Add alias
-echo 'alias claude="~/Dev/stackmemory/scripts/claude-code-wrapper.sh"' >> ~/.zshrc
-source ~/.zshrc
-
-# Use: claude (saves context on exit)
-```
-
-### Integration Methods
-
-```bash
-# 1. Shell wrapper (recommended)
-claude [--auto-sync] [--sync-interval=10]
-
-# 2. Linear auto-sync daemon
-./scripts/linear-auto-sync.sh start [interval]
-
-# 3. Background daemon
-./scripts/stackmemory-daemon.sh [interval] &
-
-# 4. Git hooks
-./scripts/setup-git-hooks.sh
+# Full setup (one-time)
+npm install -g @stackmemoryai/stackmemory   # installs hooks automatically
+cd your-project && stackmemory init          # init project
+stackmemory setup-mcp                        # configure MCP
+stackmemory doctor                           # verify everything works
 ```
 
-**Features:** Auto-save on exit, Linear sync, runs only in StackMemory projects, configurable sync intervals.
+Additional integration methods: shell wrapper (`claude-sm`), Linear auto-sync daemon, background daemon, git hooks. See [docs/setup.md](https://github.com/stackmemoryai/stackmemory/blob/main/docs/setup.md).
 
 ## RLM (Recursive Language Model) Orchestration
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stackmemoryai/stackmemory",
-  "version": "0.5.67",
-  "description": "Project-scoped memory for AI coding tools. Durable context across sessions with MCP integration, frames, and smart retrieval.",
+  "version": "0.6.0",
+  "description": "Project-scoped memory for AI coding tools. Durable context across sessions with MCP integration, frames, smart retrieval, Claude Code skills, and automatic hooks.",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=10.0.0"
@@ -42,12 +42,17 @@
     "llm",
     "mcp",
     "claude",
+    "claude-code",
     "coding",
     "persistence",
-    "code-review",
-    "predictive-edit",
+    "skills",
+    "hooks",
+    "spec-generator",
+    "linear",
+    "task-runner",
     "prompt-optimization",
-    "model-routing"
+    "model-routing",
+    "agent-orchestration"
   ],
   "scripts": {
     "start": "node dist/src/integrations/mcp/server.js",

package/scripts/install-claude-hooks-auto.js

@@ -58,6 +58,8 @@ async function askForConsent() {
   console.log('  - Track tool usage for better context');
   console.log('  - Enable session persistence across restarts');
   console.log('  - Sync context with Linear (optional)');
+  console.log('  - Auto-update PROMPT_PLAN on task completion');
+  console.log('  - Recommend relevant skills based on your prompts');
   console.log('\nThis will modify files in ~/.claude/\n');
 
   return new Promise((resolve) => {
@@ -89,11 +91,19 @@ async function installClaudeHooks() {
       console.log('Created ~/.claude/hooks directory');
     }
 
-    // Copy hook files
-    const hookFiles = ['tool-use-trace.js', 'on-startup.js', 'on-clear.js'];
+    // Copy hook files (scripts + data files)
+    const hookFiles = [
+      'tool-use-trace.js',
+      'on-startup.js',
+      'on-clear.js',
+      'on-task-complete.js',
+      'skill-eval.sh',
+      'skill-eval.cjs',
+    ];
+    const dataFiles = ['skill-rules.json'];
     let installed = 0;
 
-    for (const hookFile of hookFiles) {
+    for (const hookFile of [...hookFiles, ...dataFiles]) {
       const srcPath = join(templatesDir, hookFile);
       const destPath = join(claudeHooksDir, hookFile);
 
@@ -107,12 +117,14 @@ async function installClaudeHooks() {
 
         copyFileSync(srcPath, destPath);
 
-        // Make executable
-        try {
-          const { execSync } = await import('child_process');
-          execSync(`chmod +x "${destPath}"`, { stdio: 'ignore' });
-        } catch {
-          // Silent fail on chmod
+        // Make executable (scripts only, not data files)
+        if (!dataFiles.includes(hookFile)) {
+          try {
+            const { execSync } = await import('child_process');
+            execSync(`chmod +x "${destPath}"`, { stdio: 'ignore' });
+          } catch {
+            // Silent fail on chmod
+          }
         }
 
         installed++;
@@ -136,6 +148,8 @@ async function installClaudeHooks() {
       'tool-use-approval': join(claudeHooksDir, 'tool-use-trace.js'),
       'on-startup': join(claudeHooksDir, 'on-startup.js'),
       'on-clear': join(claudeHooksDir, 'on-clear.js'),
+      'on-task-complete': join(claudeHooksDir, 'on-task-complete.js'),
+      'user-prompt-submit': join(claudeHooksDir, 'skill-eval.sh'),
     };
 
     writeFileSync(claudeConfigFile, JSON.stringify(newHooksConfig, null, 2));

package/templates/claude-hooks/hooks.json

@@ -1,5 +1,7 @@
 {
   "tool-use-approval": "~/.claude/hooks/tool-use-trace.js",
   "on-startup": "~/.claude/hooks/on-startup.js",
-  "on-clear": "~/.claude/hooks/on-clear.js"
-}
+  "on-clear": "~/.claude/hooks/on-clear.js",
+  "on-task-complete": "~/.claude/hooks/on-task-complete.js",
+  "user-prompt-submit": "~/.claude/hooks/skill-eval.sh"
+}

package/templates/claude-hooks/on-task-complete.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+/**
+ * On-task-complete hook for StackMemory
+ * Triggers when a task is marked as done in Claude Code.
+ *
+ * Actions:
+ * 1. Auto-updates PROMPT_PLAN.md checkboxes (fuzzy match on task keywords)
+ * 2. Syncs Linear tasks (if STA-* identifier present)
+ * 3. Logs to ~/.stackmemory/logs/hook-errors.log on failure (non-blocking)
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+async function onTaskComplete() {
+  try {
+    const input = JSON.parse(fs.readFileSync(0, 'utf-8'));
+
+    // Sync Linear if STA task
+    if (input.task && input.task.includes('STA-')) {
+      try {
+        const smBin = path.join(process.env.HOME || '', '.stackmemory', 'bin');
+        const syncScript = path.join(
+          process.cwd(),
+          'scripts',
+          'sync-linear-graphql.js'
+        );
+        if (fs.existsSync(syncScript)) {
+          const { execSync } = await import('child_process');
+          execSync(`node "${syncScript}"`, {
+            stdio: 'ignore',
+            timeout: 10000,
+          });
+        }
+      } catch (_e) {
+        // Non-blocking
+      }
+    }
+
+    // Auto-update PROMPT_PLAN checkboxes if spec exists
+    const promptPlanPath = path.join(
+      process.cwd(),
+      'docs',
+      'specs',
+      'PROMPT_PLAN.md'
+    );
+    if (fs.existsSync(promptPlanPath) && input.task) {
+      try {
+        const content = fs.readFileSync(promptPlanPath, 'utf-8');
+        const taskWords = input.task.split(/\s+/).filter((w) => w.length > 3);
+        const lines = content.split('\n');
+        let updated = false;
+        for (let i = 0; i < lines.length; i++) {
+          if (
+            lines[i].includes('- [ ]') &&
+            taskWords.some((w) =>
+              lines[i].toLowerCase().includes(w.toLowerCase())
+            )
+          ) {
+            lines[i] = lines[i].replace('- [ ]', '- [x]');
+            updated = true;
+            break;
+          }
+        }
+        if (updated) {
+          fs.writeFileSync(promptPlanPath, lines.join('\n'));
+        }
+      } catch (_e) {
+        // Silently fail
+      }
+    }
+  } catch (error) {
+    const logDir = path.join(
+      process.env.HOME || '/tmp',
+      '.stackmemory',
+      'logs'
+    );
+    try {
+      fs.mkdirSync(logDir, { recursive: true });
+      fs.appendFileSync(
+        path.join(logDir, 'hook-errors.log'),
+        `[${new Date().toISOString()}] on-task-complete: ${error.message}\n`
+      );
+    } catch (_e) {
+      // Last resort: silent
+    }
+  }
+}
+
+onTaskComplete();

package/templates/claude-hooks/skill-eval.cjs

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+/**
+ * Skill Evaluation Engine v2.0
+ *
+ * Intelligent skill activation based on:
+ * - Keywords and patterns in prompts
+ * - File paths mentioned or being edited
+ * - Directory mappings
+ * - Intent detection
+ * - Content pattern matching
+ *
+ * Outputs a structured reminder with matched skills and reasons.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Configuration
+const RULES_PATH = path.join(__dirname, 'skill-rules.json');
+
+/**
+ * @typedef {Object} SkillMatch
+ * @property {string} name - Skill name
+ * @property {number} score - Confidence score
+ * @property {string[]} reasons - Why this skill was matched
+ * @property {number} priority - Skill priority
+ */
+
+/**
+ * Load skill rules from JSON file
+ * @returns {Object} Parsed skill rules
+ */
+function loadRules() {
+  try {
+    const content = fs.readFileSync(RULES_PATH, 'utf-8');
+    return JSON.parse(content);
+  } catch (error) {
+    console.error(`Failed to load skill rules: ${error.message}`);
+    process.exit(0); // Exit gracefully to not block the prompt
+  }
+}
+
+/**
+ * Extract file paths mentioned in the prompt
+ * @param {string} prompt - User's prompt text
+ * @returns {string[]} Array of detected file paths
+ */
+function extractFilePaths(prompt) {
+  const paths = new Set();
+
+  // Match explicit paths with extensions (.tsx, .ts, .jsx, .js, .json, .gql, .yaml, .yml, .md, .sh)
+  const extensionPattern =
+    /(?:^|\s|["'`])([\w\-./]+\.(?:[tj]sx?|json|gql|ya?ml|md|sh))\b/gi;
+  let match;
+  while ((match = extensionPattern.exec(prompt)) !== null) {
+    paths.add(match[1]);
+  }
+
+  // Match paths starting with common directories
+  const dirPattern =
+    /(?:^|\s|["'`])((?:src|app|components|screens|hooks|utils|services|navigation|graphql|localization|\.claude|\.github|\.maestro)\/[\w\-./]+)/gi;
+  while ((match = dirPattern.exec(prompt)) !== null) {
+    paths.add(match[1]);
+  }
+
+  // Match quoted paths
+  const quotedPattern = /["'`]([\w\-./]+\/[\w\-./]+)["'`]/g;
+  while ((match = quotedPattern.exec(prompt)) !== null) {
+    paths.add(match[1]);
+  }
+
+  return Array.from(paths);
+}
+
+/**
+ * Check if a pattern matches the text
+ * @param {string} text - Text to search in
+ * @param {string} pattern - Regex pattern
+ * @param {string} flags - Regex flags
+ * @returns {boolean}
+ */
+function matchesPattern(text, pattern, flags = 'i') {
+  try {
+    const regex = new RegExp(pattern, flags);
+    return regex.test(text);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a glob pattern matches a file path
+ * @param {string} filePath - File path to check
+ * @param {string} globPattern - Glob pattern (simplified)
+ * @returns {boolean}
+ */
+function matchesGlob(filePath, globPattern) {
+  // Convert glob to regex (simplified)
+  const regexPattern = globPattern
+    .replace(/\./g, '\\.')
+    .replace(/\*\*\//g, '<<<DOUBLESTARSLASH>>>')
+    .replace(/\*\*/g, '<<<DOUBLESTAR>>>')
+    .replace(/\*/g, '[^/]*')
+    .replace(/<<<DOUBLESTARSLASH>>>/g, '(.*\\/)?')
+    .replace(/<<<DOUBLESTAR>>>/g, '.*')
+    .replace(/\?/g, '.');
+
+  try {
+    const regex = new RegExp(`^${regexPattern}$`, 'i');
+    return regex.test(filePath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if file path matches any directory mapping
+ * @param {string} filePath - File path to check
+ * @param {Object} mappings - Directory to skill mappings
+ * @returns {string|null} Matched skill name or null
+ */
+function matchDirectoryMapping(filePath, mappings) {
+  for (const [dir, skillName] of Object.entries(mappings)) {
+    if (filePath === dir || filePath.startsWith(dir + '/')) {
+      return skillName;
+    }
+  }
+  return null;
+}
+
+/**
+ * Evaluate a single skill against the prompt and context
+ * @param {string} skillName - Name of the skill
+ * @param {Object} skill - Skill configuration
+ * @param {string} prompt - User's prompt
+ * @param {string} promptLower - Lowercase prompt
+ * @param {string[]} filePaths - Extracted file paths
+ * @param {Object} rules - Full rules object
+ * @returns {SkillMatch|null}
+ */
+function evaluateSkill(
+  skillName,
+  skill,
+  prompt,
+  promptLower,
+  filePaths,
+  rules
+) {
+  const { triggers = {}, excludePatterns = [], priority = 5 } = skill;
+  const scoring = rules.scoring;
+
+  let score = 0;
+  const reasons = [];
+
+  // Check exclude patterns first
+  for (const excludePattern of excludePatterns) {
+    if (matchesPattern(promptLower, excludePattern)) {
+      return null;
+    }
+  }
+
+  // 1. Check keywords
+  if (triggers.keywords) {
+    for (const keyword of triggers.keywords) {
+      if (promptLower.includes(keyword.toLowerCase())) {
+        score += scoring.keyword;
+        reasons.push(`keyword "${keyword}"`);
+      }
+    }
+  }
+
+  // 2. Check keyword patterns (regex)
+  if (triggers.keywordPatterns) {
+    for (const pattern of triggers.keywordPatterns) {
+      if (matchesPattern(promptLower, pattern)) {
+        score += scoring.keywordPattern;
+        reasons.push(`pattern /${pattern}/`);
+      }
+    }
+  }
+
+  // 3. Check intent patterns
+  if (triggers.intentPatterns) {
+    for (const pattern of triggers.intentPatterns) {
+      if (matchesPattern(promptLower, pattern)) {
+        score += scoring.intentPattern;
+        reasons.push(`intent detected`);
+        break;
+      }
+    }
+  }
+
+  // 4. Check context patterns
+  if (triggers.contextPatterns) {
+    for (const pattern of triggers.contextPatterns) {
+      if (promptLower.includes(pattern.toLowerCase())) {
+        score += scoring.contextPattern;
+        reasons.push(`context "${pattern}"`);
+      }
+    }
+  }
+
+  // 5. Check file paths against path patterns
+  if (triggers.pathPatterns && filePaths.length > 0) {
+    for (const filePath of filePaths) {
+      for (const pattern of triggers.pathPatterns) {
+        if (matchesGlob(filePath, pattern)) {
+          score += scoring.pathPattern;
+          reasons.push(`path "${filePath}"`);
+          break;
+        }
+      }
+    }
+  }
+
+  // 6. Check directory mappings
+  if (rules.directoryMappings && filePaths.length > 0) {
+    for (const filePath of filePaths) {
+      const mappedSkill = matchDirectoryMapping(
+        filePath,
+        rules.directoryMappings
+      );
+      if (mappedSkill === skillName) {
+        score += scoring.directoryMatch;
+        reasons.push(`directory mapping`);
+        break;
+      }
+    }
+  }
+
+  // 7. Check content patterns in prompt (for code snippets)
+  if (triggers.contentPatterns) {
+    for (const pattern of triggers.contentPatterns) {
+      if (matchesPattern(prompt, pattern)) {
+        score += scoring.contentPattern;
+        reasons.push(`code pattern detected`);
+        break;
+      }
+    }
+  }
+
+  if (score > 0) {
+    return {
+      name: skillName,
+      score,
+      reasons: [...new Set(reasons)],
+      priority,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Get related skills that should also be suggested
+ * @param {SkillMatch[]} matches - Current matches
+ * @param {Object} skills - All skill definitions
+ * @returns {string[]} Additional skill names to suggest
+ */
+function getRelatedSkills(matches, skills) {
+  const matchedNames = new Set(matches.map((m) => m.name));
+  const related = new Set();
+
+  for (const match of matches) {
+    const skill = skills[match.name];
+    if (skill?.relatedSkills) {
+      for (const relatedName of skill.relatedSkills) {
+        if (!matchedNames.has(relatedName)) {
+          related.add(relatedName);
+        }
+      }
+    }
+  }
+
+  return Array.from(related);
+}
+
+/**
+ * Format confidence level based on score
+ * @param {number} score - Confidence score
+ * @param {number} minScore - Minimum threshold
+ * @returns {string} Confidence label
+ */
+function formatConfidence(score, minScore) {
+  if (score >= minScore * 3) return 'HIGH';
+  if (score >= minScore * 2) return 'MEDIUM';
+  return 'LOW';
+}
+
+/**
+ * Main evaluation function
+ * @param {string} prompt - User's prompt
+ * @returns {string} Formatted output
+ */
+function evaluate(prompt) {
+  const rules = loadRules();
+  const { config, skills } = rules;
+
+  const promptLower = prompt.toLowerCase();
+  const filePaths = extractFilePaths(prompt);
+
+  // Evaluate all skills
+  const matches = [];
+  for (const [name, skill] of Object.entries(skills)) {
+    const match = evaluateSkill(
+      name,
+      skill,
+      prompt,
+      promptLower,
+      filePaths,
+      rules
+    );
+    if (match && match.score >= config.minConfidenceScore) {
+      matches.push(match);
+    }
+  }
+
+  if (matches.length === 0) {
+    return '';
+  }
+
+  // Sort by score (descending), then by priority (descending)
+  matches.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return b.priority - a.priority;
+  });
+
+  // Limit to max skills
+  const topMatches = matches.slice(0, config.maxSkillsToShow);
+
+  // Check for related skills
+  const relatedSkills = getRelatedSkills(topMatches, skills);
+
+  // Format output
+  let output = '<user-prompt-submit-hook>\n';
+  output += 'SKILL ACTIVATION REQUIRED\n\n';
+
+  if (filePaths.length > 0) {
+    output += `Detected file paths: ${filePaths.join(', ')}\n\n`;
+  }
+
+  output += 'Matched skills (ranked by relevance):\n';
+
+  for (let i = 0; i < topMatches.length; i++) {
+    const match = topMatches[i];
+    const confidence = formatConfidence(match.score, config.minConfidenceScore);
+
+    output += `${i + 1}. ${match.name} (${confidence} confidence)\n`;
+
+    if (config.showMatchReasons && match.reasons.length > 0) {
+      output += `   Matched: ${match.reasons.slice(0, 3).join(', ')}\n`;
+    }
+  }
+
+  if (relatedSkills.length > 0) {
+    output += `\nRelated skills to consider: ${relatedSkills.join(', ')}\n`;
+  }
+
+  output += '\nBefore implementing, you MUST:\n';
+  output += '1. EVALUATE: State YES/NO for each skill with brief reasoning\n';
+  output += '2. ACTIVATE: Invoke the Skill tool for each YES skill\n';
+  output += '3. IMPLEMENT: Only proceed after skill activation\n';
+  output += '\nExample evaluation:\n';
+  output += `- ${topMatches[0].name}: YES - [your reasoning]\n`;
+  if (topMatches.length > 1) {
+    output += `- ${topMatches[1].name}: NO - [your reasoning]\n`;
+  }
+  output += '\nDO NOT skip this step. Invoke relevant skills NOW.\n';
+  output += '</user-prompt-submit-hook>';
+
+  return output;
+}
+
+// Main execution
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+
+  process.stdin.on('data', (chunk) => {
+    input += chunk;
+  });
+
+  process.stdin.on('end', () => {
+    let prompt = '';
+
+    try {
+      const data = JSON.parse(input);
+      prompt = data.prompt || '';
+    } catch {
+      prompt = input;
+    }
+
+    if (!prompt.trim()) {
+      process.exit(0);
+    }
+
+    try {
+      const output = evaluate(prompt);
+      if (output) {
+        console.log(output);
+      }
+    } catch (error) {
+      console.error(`Skill evaluation failed: ${error.message}`);
+    }
+
+    process.exit(0);
+  });
+}
+
+main();

package/templates/claude-hooks/skill-eval.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Skill Evaluation Hook v2.0
+# Wrapper script that delegates to the Node.js evaluation engine
+#
+# This hook runs on UserPromptSubmit and analyzes the prompt for:
+# - Keywords and patterns indicating skill relevance
+# - File paths mentioned in the prompt
+# - Intent patterns (what the user wants to do)
+# - Directory mappings (what directories map to which skills)
+#
+# Configuration is in skill-rules.json
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+NODE_SCRIPT="$SCRIPT_DIR/skill-eval.cjs"
+
+# Check if Node.js is available
+if ! command -v node &>/dev/null; then
+  # Fallback: exit silently if Node.js not found
+  exit 0
+fi
+
+# Check if the Node script exists
+if [[ ! -f "$NODE_SCRIPT" ]]; then
+  exit 0
+fi
+
+# Pipe stdin to the Node.js script (suppress stderr noise from nvm/shell init)
+cat | node "$NODE_SCRIPT" 2>/dev/null
+
+# Always exit 0 to allow the prompt through
+exit 0

package/templates/claude-hooks/skill-rules.json

@@ -0,0 +1,274 @@
+{
+  "$schema": "./skill-rules.schema.json",
+  "version": "2.0",
+  "config": {
+    "minConfidenceScore": 3,
+    "showMatchReasons": true,
+    "maxSkillsToShow": 5
+  },
+  "scoring": {
+    "keyword": 2,
+    "keywordPattern": 3,
+    "pathPattern": 4,
+    "directoryMatch": 5,
+    "intentPattern": 4,
+    "contentPattern": 3,
+    "contextPattern": 2
+  },
+  "directoryMappings": {
+    "src/core": "frame-management",
+    "src/cli": "cli-commands",
+    "src/integrations/linear": "linear-integration",
+    "src/integrations/mcp": "mcp-server",
+    "src/features/tui": "terminal-ui",
+    "src/core/context": "context-bridge",
+    "src/core/storage": "storage-tiers",
+    "src/core/tasks": "task-management",
+    ".claude": "claude-integration",
+    ".github/workflows": "github-actions",
+    "scripts": "build-scripts",
+    "docs": "documentation"
+  },
+  "skills": {
+    "frame-management": {
+      "description": "Frame stack and context management patterns",
+      "priority": 9,
+      "triggers": {
+        "keywords": ["frame", "stack", "context", "framemanager", "push", "pop"],
+        "keywordPatterns": ["\\bframe\\b", "\\bstack\\b", "context(?:Bridge)?"],
+        "pathPatterns": ["**/frame-*.ts", "**/context/*.ts", "**/stack-*.ts"],
+        "intentPatterns": [
+          "(?:manage|handle).*(?:frame|context)",
+          "(?:push|pop).*(?:frame|stack)"
+        ],
+        "contentPatterns": ["FrameManager", "pushFrame", "popFrame", "getContext"]
+      },
+      "relatedSkills": ["context-bridge", "storage-tiers"]
+    },
+    "linear-integration": {
+      "description": "Linear API integration and task sync",
+      "priority": 8,
+      "triggers": {
+        "keywords": ["linear", "issue", "sync", "task sync", "oauth"],
+        "keywordPatterns": ["\\blinear\\b", "\\bissue\\b", "sync.*task"],
+        "pathPatterns": ["**/linear/**", "**/linear-*.ts"],
+        "intentPatterns": [
+          "(?:sync|update).*(?:linear|issue)",
+          "(?:linear).*(?:task|issue|sync)"
+        ],
+        "contentPatterns": ["LinearClient", "syncIssue", "createIssue"]
+      }
+    },
+    "mcp-server": {
+      "description": "Model Context Protocol server implementation",
+      "priority": 8,
+      "triggers": {
+        "keywords": ["mcp", "tool", "server", "protocol", "claude code"],
+        "keywordPatterns": ["\\bmcp\\b", "model.context", "claude.code"],
+        "pathPatterns": ["**/mcp/**", "**/mcp-*.ts", "**/tools/**"],
+        "intentPatterns": [
+          "(?:implement|create).*(?:mcp|tool)",
+          "(?:mcp).*(?:server|tool|protocol)"
+        ],
+        "contentPatterns": ["MCPServer", "registerTool", "@tool", "toolCall"]
+      },
+      "relatedSkills": ["claude-integration"]
+    },
+    "testing-patterns": {
+      "description": "Jest testing and test infrastructure",
+      "priority": 7,
+      "triggers": {
+        "keywords": ["test", "jest", "spec", "mock", "fixture"],
+        "keywordPatterns": ["\\btest\\b", "\\bspec\\b", "\\bjest\\b"],
+        "pathPatterns": ["**/*.test.ts", "**/*.spec.ts", "**/__tests__/**"],
+        "intentPatterns": [
+          "(?:write|add|fix).*(?:test|spec)",
+          "(?:test).*(?:coverage|suite)"
+        ],
+        "contentPatterns": ["describe\\(", "it\\(", "expect\\(", "jest\\.mock"]
+      }
+    },
+    "cli-commands": {
+      "description": "CLI command implementation and structure",
+      "priority": 7,
+      "triggers": {
+        "keywords": ["cli", "command", "yargs", "terminal", "console"],
+        "keywordPatterns": ["\\bcli\\b", "\\bcommand\\b", "\\byargs\\b"],
+        "pathPatterns": ["**/cli/**", "**/commands/**", "**/cli-*.ts"],
+        "intentPatterns": [
+          "(?:add|create).*(?:command|cli)",
+          "(?:cli).*(?:command|option|argument)"
+        ],
+        "contentPatterns": ["yargs", "command\\(", "option\\(", "argv"]
+      }
+    },
+    "storage-tiers": {
+      "description": "3-tier storage system (Redis/Railway/GCS)",
+      "priority": 7,
+      "triggers": {
+        "keywords": ["storage", "redis", "railway", "bucket", "tier", "cache"],
+        "keywordPatterns": ["\\bstorage\\b", "\\btier\\b", "\\bredis\\b"],
+        "pathPatterns": ["**/storage/**", "**/railway-*.ts", "**/redis-*.ts"],
+        "intentPatterns": [
+          "(?:implement|configure).*(?:storage|tier)",
+          "(?:migrate).*(?:data|storage)"
+        ],
+        "contentPatterns": ["RailwayOptimizedStorage", "StorageTier", "Redis"]
+      }
+    },
+    "context-bridge": {
+      "description": "Cross-session context synchronization",
+      "priority": 8,
+      "triggers": {
+        "keywords": ["bridge", "sync", "session", "shared context", "handoff"],
+        "keywordPatterns": ["context.*bridge", "shared.*context", "handoff"],
+        "pathPatterns": ["**/context-bridge*.ts", "**/shared-context/**"],
+        "intentPatterns": [
+          "(?:sync|share).*(?:context|session)",
+          "(?:handoff).*(?:session|context)"
+        ],
+        "contentPatterns": ["ContextBridge", "SharedContext", "syncContext"]
+      },
+      "relatedSkills": ["frame-management"]
+    },
+    "task-management": {
+      "description": "Task creation, tracking, and persistence",
+      "priority": 7,
+      "triggers": {
+        "keywords": ["task", "todo", "progress", "tracking", "pebbles"],
+        "keywordPatterns": ["\\btask\\b", "\\btodo\\b", "pebbles"],
+        "pathPatterns": ["**/tasks/**", "**/task-*.ts", "**/pebbles-*.ts"],
+        "intentPatterns": [
+          "(?:create|manage).*(?:task|todo)",
+          "(?:track).*(?:progress|task)"
+        ],
+        "contentPatterns": ["TaskManager", "createTask", "updateTask", "PebblesTaskStore"]
+      }
+    },
+    "terminal-ui": {
+      "description": "Terminal UI with Ink and React",
+      "priority": 6,
+      "triggers": {
+        "keywords": ["tui", "terminal", "ink", "dashboard", "monitor"],
+        "keywordPatterns": ["\\btui\\b", "\\bink\\b", "terminal.*ui"],
+        "pathPatterns": ["**/tui/**", "**/terminal-*.tsx", "**/dashboard/**"],
+        "intentPatterns": [
+          "(?:create|build).*(?:tui|terminal)",
+          "(?:dashboard|monitor).*(?:ui|interface)"
+        ],
+        "contentPatterns": ["ink", "Text", "Box", "useInput"]
+      }
+    },
+    "claude-integration": {
+      "description": "Claude Code integration and hooks",
+      "priority": 8,
+      "triggers": {
+        "keywords": ["claude", "hook", "skill", "auto-trigger", "clear survival"],
+        "keywordPatterns": ["claude.*(?:code|hook)", "skill.*eval"],
+        "pathPatterns": [".claude/**", "**/claude-*.ts", "**/hooks/**"],
+        "intentPatterns": [
+          "(?:integrate|setup).*(?:claude)",
+          "(?:hook|trigger).*(?:claude|skill)"
+        ],
+        "contentPatterns": ["UserPromptSubmit", "PreToolUse", "PostToolUse", "skill-eval"]
+      },
+      "relatedSkills": ["mcp-server"]
+    },
+    "build-scripts": {
+      "description": "Build, deployment, and utility scripts",
+      "priority": 5,
+      "triggers": {
+        "keywords": ["script", "build", "deploy", "npm", "package"],
+        "keywordPatterns": ["\\bscript\\b", "\\bbuild\\b", "npm.*run"],
+        "pathPatterns": ["scripts/**", "**/*.sh", "**/build/**"],
+        "intentPatterns": [
+          "(?:create|write).*(?:script)",
+          "(?:build|deploy).*(?:project)"
+        ],
+        "contentPatterns": ["#!/bin/bash", "npm run", "NODE_ENV"]
+      }
+    },
+    "documentation": {
+      "description": "Documentation and API reference",
+      "priority": 4,
+      "triggers": {
+        "keywords": ["docs", "documentation", "readme", "api", "reference"],
+        "keywordPatterns": ["\\bdoc(?:s)?\\b", "readme", "api.*reference"],
+        "pathPatterns": ["docs/**", "**/*.md", "**/README*"],
+        "intentPatterns": [
+          "(?:write|update).*(?:doc|documentation)",
+          "(?:document).*(?:api|feature)"
+        ]
+      }
+    },
+    "github-actions": {
+      "description": "CI/CD workflows and GitHub Actions",
+      "priority": 6,
+      "triggers": {
+        "keywords": ["workflow", "action", "ci", "cd", "pipeline"],
+        "keywordPatterns": ["github.*action", "ci.*cd", "\\bworkflow\\b"],
+        "pathPatterns": [".github/workflows/**", ".github/**/*.yml"],
+        "intentPatterns": [
+          "(?:create|setup).*(?:workflow|pipeline)",
+          "(?:ci|cd).*(?:setup|configure)"
+        ],
+        "contentPatterns": ["runs-on:", "uses:", "steps:"]
+      }
+    },
+    "code-quality": {
+      "description": "Code review and quality checks",
+      "priority": 8,
+      "triggers": {
+        "keywords": ["review", "lint", "quality", "eslint", "prettier"],
+        "keywordPatterns": ["code.*review", "\\blint\\b", "quality.*check"],
+        "intentPatterns": [
+          "(?:review|check).*(?:code|quality)",
+          "(?:fix).*(?:lint|formatting)"
+        ]
+      }
+    },
+    "performance-optimization": {
+      "description": "Performance analysis and optimization",
+      "priority": 7,
+      "triggers": {
+        "keywords": ["performance", "optimize", "slow", "bottleneck", "profile"],
+        "keywordPatterns": ["\\bperf\\b", "optimiz", "bottleneck"],
+        "intentPatterns": [
+          "(?:optimize|improve).*(?:performance|speed)",
+          "(?:debug|fix).*(?:slow|performance)"
+        ],
+        "contentPatterns": ["performance\\.now", "console\\.time", "profiler"]
+      }
+    },
+    "spec-generator": {
+      "description": "Iterative spec document generation (one-pager, dev-spec, prompt-plan, agents)",
+      "priority": 8,
+      "triggers": {
+        "keywords": ["spec", "one-pager", "dev-spec", "prompt-plan", "agents.md", "scaffold"],
+        "keywordPatterns": ["\\bspec\\b", "one.pager", "dev.spec", "prompt.plan"],
+        "pathPatterns": ["docs/specs/**", "**/AGENTS.md", "**/ONE_PAGER.md", "**/PROMPT_PLAN.md"],
+        "intentPatterns": [
+          "(?:generate|create).*(?:spec|one-pager|dev-spec)",
+          "(?:spec).*(?:generate|validate|update|list)"
+        ],
+        "contentPatterns": ["SpecGeneratorSkill", "ONE_PAGER", "DEV_SPEC", "PROMPT_PLAN"]
+      },
+      "relatedSkills": ["linear-task-runner"]
+    },
+    "linear-task-runner": {
+      "description": "Execute Linear tasks via RLM orchestrator",
+      "priority": 8,
+      "triggers": {
+        "keywords": ["linear-run", "run task", "execute task", "task runner", "ralph linear"],
+        "keywordPatterns": ["linear.run", "run.*task", "task.*runner"],
+        "pathPatterns": ["**/linear-task-runner.ts"],
+        "intentPatterns": [
+          "(?:run|execute).*(?:linear|task)",
+          "(?:linear).*(?:run|execute|next|all)"
+        ],
+        "contentPatterns": ["LinearTaskRunner", "runNext", "runAll", "runTask"]
+      },
+      "relatedSkills": ["spec-generator", "linear-integration"]
+    }
+  }
+}