docs(readme): add skills, hooks, and spec system usage guidelines

Update README with Skills System (/spec, /linear-run), Hooks
(automatic task tracking, skill-eval, PROMPT_PLAN auto-progress),
and Prompt Forge sections. Add hook templates for on-task-complete,
skill-eval, and skill-rules.json to auto-install during npm install.
Update package.json keywords and description for npm discoverability.

Author: StackMemory Bot (CLI)

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.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.",
+  "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",

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));

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"
+}