@stackmemoryai/stackmemory 0.5.66 → 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
 
 ---
 
@@ -103,7 +105,7 @@ Use these JSON snippets with Claude Code’s MCP “tools/call”. Responses are
 
 - Plan only (no code):
   ```json
-  {"method":"tools/call","params":{"name":"plan_only","arguments":{"task":"Refactor config loader","plannerModel":"claude-3-5-sonnet-latest"}}}
+  {"method":"tools/call","params":{"name":"plan_only","arguments":{"task":"Refactor config loader","plannerModel":"claude-sonnet-4-20250514"}}}
   ```
 
 - Approval‑gated plan (phase 1):
@@ -124,20 +126,134 @@ Use these JSON snippets with Claude Code’s MCP “tools/call”. Responses are
   ```
 
 Env defaults (optional):
-- `STACKMEMORY_MM_PLANNER_MODEL` (e.g., `claude-3-5-sonnet-latest` or `claude-3-opus-latest`)
+- `STACKMEMORY_MM_PLANNER_MODEL` (e.g., `claude-sonnet-4-20250514`)
 - `STACKMEMORY_MM_REVIEWER_MODEL` (defaults to planner if unset)
 - `STACKMEMORY_MM_IMPLEMENTER` (`codex` or `claude`)
 - `STACKMEMORY_MM_MAX_ITERS` (e.g., `2`)
 
 ---
 
-## 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
 
-See above for install and minimal usage. For advanced options, see Setup.
+Options: `--priority <level>`, `--tag <tag>`, `--dry-run`, `--maxConcurrent <n>`
 
 ---
 
-## 2. Detailed Setup
+## 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
+
+# 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.
+
+---
+
+## 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)
+# 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
 ```
 
-### 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
-```
-
-**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
 
@@ -414,7 +508,7 @@ See https://github.com/stackmemoryai/stackmemory/blob/main/docs/roadmap.md for o
 - [Agent Instructions](./AGENTS.md) - Specific guidance for AI agents working with ML systems
 
 ### Documentation
-
+- [Vision](./vision.md) - Product vision, principles, roadmap, metrics
 - [Product Requirements](./PRD.md) - Detailed product specifications
 - [Technical Architecture](./TECHNICAL_ARCHITECTURE.md) - System design and database schemas
 - [Beads Integration](./BEADS_INTEGRATION.md) - Git-native memory patterns from Beads ecosystem

package/bin/codex-sm

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Codex-SM CLI Launcher (ESM)
+ * Delegates to built CLI in dist without requiring tsx.
+ */
+import('../dist/src/cli/codex-sm.js');

package/bin/opencode-sm

@@ -3,4 +3,4 @@
  * OpenCode-SM CLI Launcher (ESM)
  * Delegates to built CLI in dist without requiring tsx.
  */
-import('../dist/cli/opencode-sm.js');
+import('../dist/src/cli/opencode-sm.js');

package/dist/src/cli/claude-sm.js

@@ -27,6 +27,22 @@ import {
 } from "../core/models/model-router.js";
 import { launchWrapper } from "../features/sweep/pty-wrapper.js";
 import { FallbackMonitor } from "../core/models/fallback-monitor.js";
+import {
+  ensureWorkerStateDir,
+  saveRegistry,
+  loadRegistry,
+  clearRegistry
+} from "../features/workers/worker-registry.js";
+import {
+  isTmuxAvailable,
+  createTmuxSession,
+  sendToPane,
+  killTmuxSession,
+  attachToSession,
+  listPanes,
+  sendCtrlC,
+  sessionExists
+} from "../features/workers/tmux-manager.js";
 const DEFAULT_SM_CONFIG = {
   defaultWorktree: false,
   defaultSandbox: false,
@@ -156,11 +172,15 @@ class ClaudeSM {
     }
     return null;
   }
-  gepaProcess = null;
+  gepaProcesses = [];
   startGEPAWatcher() {
-    const claudeMdPath = fs.existsSync(path.join(process.cwd(), "CLAUDE.md")) ? path.join(process.cwd(), "CLAUDE.md") : null;
-    if (!claudeMdPath) {
-      console.log(chalk.gray("   Prompt Forge: disabled (no CLAUDE.md found)"));
+    const watchFiles = ["CLAUDE.md", "AGENT.md", "AGENTS.md"].map((f) => path.join(process.cwd(), f)).filter((p) => fs.existsSync(p));
+    if (watchFiles.length === 0) {
+      console.log(
+        chalk.gray(
+          "   Prompt Forge: disabled (no CLAUDE.md, AGENT.md, or AGENTS.md found)"
+        )
+      );
       return;
     }
     const gepaPaths = [
@@ -193,29 +213,31 @@ class ClaudeSM {
       console.log(chalk.gray("   Prompt Forge: disabled (scripts not found)"));
       return;
     }
-    this.gepaProcess = spawn("node", [gepaScript, "watch", claudeMdPath], {
-      detached: true,
-      stdio: ["ignore", "pipe", "pipe"],
-      env: { ...process.env, GEPA_SILENT: "1" }
-    });
-    this.gepaProcess.unref();
-    this.gepaProcess.stdout?.on("data", (data) => {
-      const output = data.toString().trim();
-      if (output && !output.includes("Watching")) {
-        console.log(chalk.magenta(`[GEPA] ${output}`));
-      }
-    });
+    for (const filePath of watchFiles) {
+      const gepaProcess = spawn("node", [gepaScript, "watch", filePath], {
+        detached: true,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, GEPA_SILENT: "1" }
+      });
+      gepaProcess.unref();
+      this.gepaProcesses.push(gepaProcess);
+      gepaProcess.stdout?.on("data", (data) => {
+        const output = data.toString().trim();
+        if (output && !output.includes("Watching")) {
+          console.log(chalk.magenta(`[GEPA] ${output}`));
+        }
+      });
+    }
+    const fileNames = watchFiles.map((f) => path.basename(f)).join(", ");
     console.log(
-      chalk.cyan(
-        `   Prompt Forge: watching ${path.basename(claudeMdPath)} for optimization`
-      )
+      chalk.cyan(`   Prompt Forge: watching ${fileNames} for optimization`)
     );
   }
   stopGEPAWatcher() {
-    if (this.gepaProcess) {
-      this.gepaProcess.kill("SIGTERM");
-      this.gepaProcess = null;
+    for (const proc of this.gepaProcesses) {
+      proc.kill("SIGTERM");
     }
+    this.gepaProcesses = [];
   }
   ensureGreptileMcp() {
     const apiKey = process.env["GREPTILE_API_KEY"];
@@ -822,11 +844,17 @@ class ClaudeSM {
           claudeBin: claudeBin2,
           claudeArgs
         });
+        return;
       } catch (error) {
-        console.error(chalk.red(error.message));
-        process.exit(1);
+        const msg = error.message || "Unknown PTY error";
+        console.error(chalk.yellow(`[Sweep disabled] ${msg}`));
+        console.log(
+          chalk.gray(
+            "Falling back to direct Claude launch (no prediction bar)..."
+          )
+        );
+        this.config.useSweep = false;
       }
-      return;
     }
     console.log(chalk.gray("Starting Claude..."));
     console.log(chalk.gray("\u2500".repeat(42)));
@@ -1224,6 +1252,115 @@ GREPTILE_API_KEY=${key.trim()}
   console.log(chalk.gray(`
 Saved to ${getConfigPath()}`));
 });
+program.command("spawn <count>").description("Spawn N parallel Claude workers in tmux panes").option("-t, --task <desc>", "Task description for each worker").option("--worktree", "Create isolated git worktrees per worker").option("--no-sweep", "Disable Sweep predictions").option("--no-attach", "Do not attach to tmux session after creation").action(async (countStr, opts) => {
+  const count = parseInt(countStr, 10);
+  if (isNaN(count) || count < 1 || count > 8) {
+    console.error(chalk.red("Worker count must be between 1 and 8"));
+    process.exit(1);
+  }
+  if (!isTmuxAvailable()) {
+    console.error(chalk.red("tmux is required for parallel workers."));
+    console.log(chalk.gray("Install with: brew install tmux"));
+    process.exit(1);
+  }
+  const sessionId = uuidv4().substring(0, 8);
+  const sessionName = `claude-sm-${sessionId}`;
+  console.log(
+    chalk.blue(`Spawning ${count} workers in tmux session: ${sessionName}`)
+  );
+  createTmuxSession(sessionName, count);
+  const workers = [];
+  const panes = listPanes(sessionName);
+  for (let i = 0; i < count; i++) {
+    const workerId = `w${i}-${uuidv4().substring(0, 6)}`;
+    const stateDir = ensureWorkerStateDir(workerId);
+    const pane = panes[i] || String(i);
+    const parts = ["claude-sm"];
+    if (opts["sweep"] === false) parts.push("--no-sweep");
+    if (opts["worktree"]) parts.push("--worktree");
+    if (opts["task"]) parts.push("--task", `"${opts["task"]}"`);
+    const cmd = parts.join(" ");
+    sendToPane(
+      sessionName,
+      pane,
+      `export SWEEP_INSTANCE_ID=${workerId} SWEEP_STATE_DIR=${stateDir} && ${cmd}`
+    );
+    workers.push({
+      id: workerId,
+      pane,
+      cwd: process.cwd(),
+      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      stateDir,
+      task: opts["task"]
+    });
+    console.log(
+      chalk.gray(
+        `  Worker ${i}: ${workerId} (pane ${pane}, state: ${stateDir})`
+      )
+    );
+  }
+  const session = {
+    sessionName,
+    workers,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  saveRegistry(session);
+  console.log(chalk.green(`
+Registry saved (${workers.length} workers)`));
+  if (opts["attach"] !== false) {
+    console.log(chalk.gray("Attaching to tmux session..."));
+    attachToSession(sessionName);
+  } else {
+    console.log(
+      chalk.gray(`Attach later with: tmux attach -t ${sessionName}`)
+    );
+  }
+});
+const workersCmd = program.command("workers").description("List active workers (default) or manage them");
+workersCmd.command("list", { isDefault: true }).description("List active workers").action(() => {
+  const session = loadRegistry();
+  if (!session) {
+    console.log(chalk.gray("No active worker session."));
+    return;
+  }
+  const alive = sessionExists(session.sessionName);
+  const status = alive ? chalk.green("ACTIVE") : chalk.red("DEAD");
+  console.log(chalk.blue(`Session: ${session.sessionName} [${status}]`));
+  console.log(chalk.gray(`Created: ${session.createdAt}`));
+  console.log();
+  for (const w of session.workers) {
+    const taskLabel = w.task ? ` task="${w.task}"` : "";
+    console.log(`  ${chalk.cyan(w.id)} pane=${w.pane}${taskLabel}`);
+    console.log(chalk.gray(`    state: ${w.stateDir}`));
+  }
+});
+workersCmd.command("kill [id]").description("Kill entire session or send Ctrl-C to a specific worker").action((id) => {
+  const session = loadRegistry();
+  if (!session) {
+    console.log(chalk.gray("No active worker session."));
+    return;
+  }
+  if (id) {
+    const worker = session.workers.find((w) => w.id === id);
+    if (!worker) {
+      console.error(chalk.red(`Worker ${id} not found.`));
+      process.exit(1);
+    }
+    sendCtrlC(session.sessionName, worker.pane);
+    console.log(
+      chalk.yellow(`Sent Ctrl-C to worker ${id} (pane ${worker.pane})`)
+    );
+  } else {
+    if (sessionExists(session.sessionName)) {
+      killTmuxSession(session.sessionName);
+      console.log(
+        chalk.yellow(`Killed tmux session: ${session.sessionName}`)
+      );
+    }
+    clearRegistry();
+    console.log(chalk.gray("Registry cleared."));
+  }
+});
 program.option("-w, --worktree", "Create isolated worktree for this instance").option("-W, --no-worktree", "Disable worktree (override default)").option("-r, --remote", "Enable remote mode (WhatsApp for all questions)").option("--no-remote", "Disable remote mode (override default)").option("-n, --notify-done", "Send WhatsApp notification when session ends").option("--no-notify-done", "Disable notification when session ends").option(
   "--whatsapp",
   "Enable WhatsApp mode (auto-start webhook + ngrok + notifications)"