specweave 2.0.0 → 2.1.0

package/plugins/specweave/hooks/run-worker.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * SpecWeave hook launcher (zero-dependency, cross-platform).
+ *
+ * Invoked by Claude Code in exec form (no shell):
+ *   node ${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs <event>
+ *
+ * Contract:
+ *   - reads the hook JSON from stdin (5 s cap), normalizes backslashes in
+ *     tool_input.file_path, locates the installed `specweave` CLI, imports its
+ *     built hook router and prints exactly ONE JSON object;
+ *   - always exits 0; on ANY failure prints `{}` (pass) — except SessionStart,
+ *     which prints an additionalContext line telling the user the CLI is missing.
+ *
+ * CLI root resolution order:
+ *   1. $SPECWEAVE_HOME
+ *   2. <plugin root>/../..  (plugin shipped inside the npm package / repo checkout)
+ *   3. require.resolve('specweave/package.json') from $CLAUDE_PROJECT_DIR / cwd
+ *   4. `npm root -g` (result cached in a per-user private file under ~/.specweave)
+ *
+ * Fast path: PreToolUse for a file outside `.specweave/increments/` prints `{}`
+ * without loading the CLI at all (the guards only concern increment files).
+ */
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const EVENTS = new Set(['session-start', 'pre-tool-use', 'stop', 'pre-compact']);
+const STDIN_CAP_MS = 5000;
+const ROUTER_REL = path.join('dist', 'src', 'core', 'hooks', 'handlers', 'hook-router.js');
+/**
+ * Per-user cache path. NEVER the shared OS temp dir: run.mjs `import()`s the
+ * path it reads back, so a world-writable cache is arbitrary code execution on
+ * every SessionStart/Stop/PreCompact of every session on the machine.
+ */
+const CACHE_DIR = safeHomeDir() ? path.join(safeHomeDir(), '.specweave') : null;
+const CACHE_FILE = CACHE_DIR ? path.join(CACHE_DIR, 'hook-cli-root') : null;
+
+function safeHomeDir() {
+  try {
+    const home = homedir();
+    return home && path.isAbsolute(home) ? home : null;
+  } catch {
+    return null;
+  }
+}
+
+/** True only for a regular file (not a symlink) owned by the current user. */
+function isPrivateOwnedFile(file) {
+  try {
+    const st = lstatSync(file);
+    if (!st.isFile()) return false;
+    const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+    return uid === null || st.uid === uid;
+  } catch {
+    return false;
+  }
+}
+
+const event = process.argv[2] ?? '';
+
+function inactiveOutput() {
+  if (event === 'session-start') {
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext:
+          'SpecWeave hooks inactive: specweave CLI not found (npm i -g specweave)',
+      },
+    };
+  }
+  return {};
+}
+
+let printed = false;
+function emit(obj) {
+  if (printed) return;
+  printed = true;
+  let text = '{}';
+  try {
+    text = JSON.stringify(obj && typeof obj === 'object' ? obj : {});
+  } catch {
+    text = '{}';
+  }
+  process.stdout.write(text + '\n', () => process.exit(0));
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      resolve(Buffer.concat(chunks).toString('utf8'));
+    };
+    const timer = setTimeout(finish, STDIN_CAP_MS);
+    if (timer.unref) timer.unref();
+    try {
+      process.stdin.on('data', (c) => chunks.push(c));
+      process.stdin.on('end', finish);
+      process.stdin.on('error', finish);
+      process.stdin.on('close', finish);
+      if (process.stdin.readableEnded) finish();
+    } catch {
+      finish();
+    }
+  });
+}
+
+/** Returns { raw, skip } — `skip` when the event cannot possibly need the CLI. */
+function normalizeInput(raw) {
+  try {
+    const input = JSON.parse(raw);
+    if (input && typeof input === 'object') {
+      const ti = input.tool_input;
+      let filePath = '';
+      if (ti && typeof ti === 'object' && typeof ti.file_path === 'string') {
+        ti.file_path = ti.file_path.replace(/\\/g, '/');
+        filePath = ti.file_path;
+      }
+      if (typeof input.cwd === 'string') input.cwd = input.cwd.replace(/\\/g, '/');
+      const skip = event === 'pre-tool-use' && !filePath.includes('.specweave/increments/');
+      return { raw: JSON.stringify(input), skip };
+    }
+  } catch {
+    // fall through — the router tolerates a non-JSON payload
+  }
+  return { raw, skip: false };
+}
+
+function isCliRoot(dir) {
+  if (!dir) return false;
+  try {
+    const pkg = path.join(dir, 'package.json');
+    if (!existsSync(pkg) || !existsSync(path.join(dir, ROUTER_REL))) return false;
+    return JSON.parse(readFileSync(pkg, 'utf8')).name === 'specweave';
+  } catch {
+    return false;
+  }
+}
+
+function pluginRoot() {
+  if (process.env.CLAUDE_PLUGIN_ROOT) return path.resolve(process.env.CLAUDE_PLUGIN_ROOT);
+  return path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+}
+
+function fromCache() {
+  if (!CACHE_FILE || !isPrivateOwnedFile(CACHE_FILE)) return null;
+  try {
+    const cached = readFileSync(CACHE_FILE, 'utf8').trim();
+    return isCliRoot(cached) ? cached : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(dir) {
+  if (!CACHE_DIR || !CACHE_FILE) return;
+  try {
+    mkdirSync(CACHE_DIR, { recursive: true, mode: 0o700 });
+    // Drop whatever is there (possibly a planted symlink) before writing.
+    rmSync(CACHE_FILE, { force: true });
+    writeFileSync(CACHE_FILE, dir, { flag: 'wx', mode: 0o600 });
+  } catch {
+    // cache is best-effort
+  }
+}
+
+function fromNpmGlobal() {
+  try {
+    const res = spawnSync('npm root -g', { shell: true, encoding: 'utf8', timeout: 4000 });
+    const root = (res.stdout || '').trim().split(/\r?\n/).pop();
+    if (!root) return null;
+    const dir = path.join(root, 'specweave');
+    if (!isCliRoot(dir)) return null;
+    writeCache(dir);
+    return dir;
+  } catch {
+    return null;
+  }
+}
+
+function resolveCliRoot() {
+  const candidates = [
+    () => process.env.SPECWEAVE_HOME,
+    () => path.resolve(pluginRoot(), '..', '..'),
+    ...[process.env.CLAUDE_PROJECT_DIR, process.cwd()].filter(Boolean).flatMap((dir) => [
+      () => path.dirname(createRequire(path.join(dir, 'package.json')).resolve('specweave/package.json')),
+      () => path.join(dir, 'node_modules', 'specweave'),
+    ]),
+    fromCache,
+    fromNpmGlobal,
+  ];
+  for (const candidate of candidates) {
+    try {
+      const dir = candidate();
+      if (isCliRoot(dir)) return dir;
+    } catch {
+      // try the next strategy
+    }
+  }
+  return null;
+}
+
+async function main() {
+  if (!EVENTS.has(event)) {
+    await readStdin();
+    return emit({});
+  }
+  const { raw, skip } = normalizeInput(await readStdin());
+  if (skip) return emit({});
+  const cliRoot = resolveCliRoot();
+  if (!cliRoot) return emit(inactiveOutput());
+  try {
+    const mod = await import(pathToFileURL(path.join(cliRoot, ROUTER_REL)).href);
+    const result = await mod.hookRouter(event, raw);
+    return emit(result);
+  } catch {
+    return emit(inactiveOutput());
+  }
+}
+
+process.on('uncaughtException', () => emit(inactiveOutput()));
+process.on('unhandledRejection', () => emit(inactiveOutput()));
+main().catch(() => emit(inactiveOutput()));

package/plugins/specweave/hooks/run.mjs

@@ -1,229 +1,95 @@
 #!/usr/bin/env node
-/**
- * SpecWeave hook launcher (zero-dependency, cross-platform).
- *
- * Invoked by Claude Code in exec form (no shell):
- *   node ${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs <event>
- *
- * Contract:
- *   - reads the hook JSON from stdin (5 s cap), normalizes backslashes in
- *     tool_input.file_path, locates the installed `specweave` CLI, imports its
- *     built hook router and prints exactly ONE JSON object;
- *   - always exits 0; on ANY failure prints `{}` (pass) — except SessionStart,
- *     which prints an additionalContext line telling the user the CLI is missing.
- *
- * CLI root resolution order:
- *   1. $SPECWEAVE_HOME
- *   2. <plugin root>/../..  (plugin shipped inside the npm package / repo checkout)
- *   3. require.resolve('specweave/package.json') from $CLAUDE_PROJECT_DIR / cwd
- *   4. `npm root -g` (result cached in a per-user private file under ~/.specweave)
- *
- * Fast path: PreToolUse for a file outside `.specweave/increments/` prints `{}`
- * without loading the CLI at all (the guards only concern increment files).
- */
-import { createRequire } from 'node:module';
-import { spawnSync } from 'node:child_process';
-import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+// SpecWeave hook supervisor: parent deadline remains live while the worker blocks in Git.
+import { spawn, spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const EVENTS = new Set(['session-start', 'pre-tool-use', 'stop', 'pre-compact']);
-const STDIN_CAP_MS = 5000;
-const ROUTER_REL = path.join('dist', 'src', 'core', 'hooks', 'handlers', 'hook-router.js');
-/**
- * Per-user cache path. NEVER the shared OS temp dir: run.mjs `import()`s the
- * path it reads back, so a world-writable cache is arbitrary code execution on
- * every SessionStart/Stop/PreCompact of every session on the machine.
- */
-const CACHE_DIR = safeHomeDir() ? path.join(safeHomeDir(), '.specweave') : null;
-const CACHE_FILE = CACHE_DIR ? path.join(CACHE_DIR, 'hook-cli-root') : null;
-
-function safeHomeDir() {
-  try {
-    const home = homedir();
-    return home && path.isAbsolute(home) ? home : null;
-  } catch {
-    return null;
-  }
-}
-
-/** True only for a regular file (not a symlink) owned by the current user. */
-function isPrivateOwnedFile(file) {
-  try {
-    const st = lstatSync(file);
-    if (!st.isFile()) return false;
-    const uid = typeof process.getuid === 'function' ? process.getuid() : null;
-    return uid === null || st.uid === uid;
-  } catch {
-    return false;
-  }
-}
-
-const event = process.argv[2] ?? '';
-
-function inactiveOutput() {
-  if (event === 'session-start') {
-    return {
-      hookSpecificOutput: {
-        hookEventName: 'SessionStart',
-        additionalContext:
-          'SpecWeave hooks inactive: specweave CLI not found (npm i -g specweave)',
-      },
-    };
-  }
-  return {};
-}
-
-let printed = false;
-function emit(obj) {
-  if (printed) return;
-  printed = true;
-  let text = '{}';
-  try {
-    text = JSON.stringify(obj && typeof obj === 'object' ? obj : {});
-  } catch {
-    text = '{}';
-  }
-  process.stdout.write(text + '\n', () => process.exit(0));
-}
-
-function readStdin() {
-  return new Promise((resolve) => {
-    const chunks = [];
-    let done = false;
-    const finish = () => {
-      if (done) return;
-      done = true;
-      resolve(Buffer.concat(chunks).toString('utf8'));
-    };
-    const timer = setTimeout(finish, STDIN_CAP_MS);
-    if (timer.unref) timer.unref();
-    try {
-      process.stdin.on('data', (c) => chunks.push(c));
-      process.stdin.on('end', finish);
-      process.stdin.on('error', finish);
-      process.stdin.on('close', finish);
-      if (process.stdin.readableEnded) finish();
-    } catch {
-      finish();
-    }
-  });
-}
-
-/** Returns { raw, skip } — `skip` when the event cannot possibly need the CLI. */
-function normalizeInput(raw) {
-  try {
-    const input = JSON.parse(raw);
-    if (input && typeof input === 'object') {
-      const ti = input.tool_input;
-      let filePath = '';
-      if (ti && typeof ti === 'object' && typeof ti.file_path === 'string') {
-        ti.file_path = ti.file_path.replace(/\\/g, '/');
-        filePath = ti.file_path;
-      }
-      if (typeof input.cwd === 'string') input.cwd = input.cwd.replace(/\\/g, '/');
-      const skip = event === 'pre-tool-use' && !filePath.includes('.specweave/increments/');
-      return { raw: JSON.stringify(input), skip };
+import { fileURLToPath } from 'node:url';
+const event = process.argv[2];
+const worker = path.join(path.dirname(fileURLToPath(import.meta.url)), 'run-worker.mjs');
+const budget = event === 'stop' ? 25000 : 7500;
+let child, finished = false, input = '', output = '', size = 0;
+const started = Date.now();
+// Ordinary turns should not resolve npm, import the CLI, or start a second Node
+// process. Auto mode is explicit and its small local marker is authoritative.
+function hasActiveAutoSession(data) {
+  let current = path.resolve(typeof data.cwd === 'string' ? data.cwd : process.cwd());
+  for (let depth = 0; depth < 100; depth++) {
+    const state = path.join(current, '.specweave', 'state');
+    if (existsSync(path.join(current, '.specweave', 'config.json'))) {
+      const sessionId = process.env.CLAUDE_SESSION_ID;
+      // Match session-state-manager's path-safe IDs, including dots and spaces.
+      const scoped = sessionId && !/[/\\]|\.\.|\0/.test(sessionId)
+        ? path.join(state, 'sessions', sessionId, 'auto-mode.json') : null;
+      const marker = scoped && existsSync(scoped) ? scoped : path.join(state, 'auto-mode.json');
+      try { return JSON.parse(readFileSync(marker, 'utf8')).active === true; }
+      catch { return false; }
     }
-  } catch {
-    // fall through — the router tolerates a non-JSON payload
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
   }
-  return { raw, skip: false };
+  return false;
 }
-
-function isCliRoot(dir) {
-  if (!dir) return false;
+function record(reason) {
   try {
-    const pkg = path.join(dir, 'package.json');
-    if (!existsSync(pkg) || !existsSync(path.join(dir, ROUTER_REL))) return false;
-    return JSON.parse(readFileSync(pkg, 'utf8')).name === 'specweave';
-  } catch {
-    return false;
-  }
+    const dir = path.join(homedir(), '.specweave', 'logs');
+    mkdirSync(dir, {recursive:true, mode:0o700});
+    appendFileSync(path.join(dir, 'hook-health.jsonl'), JSON.stringify({at:new Date().toISOString(),event,reason,elapsedMs:Date.now()-started})+'\n', {mode:0o600});
+  } catch {}
 }
-
-function pluginRoot() {
-  if (process.env.CLAUDE_PLUGIN_ROOT) return path.resolve(process.env.CLAUDE_PLUGIN_ROOT);
-  return path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-}
-
-function fromCache() {
-  if (!CACHE_FILE || !isPrivateOwnedFile(CACHE_FILE)) return null;
-  try {
-    const cached = readFileSync(CACHE_FILE, 'utf8').trim();
-    return isCliRoot(cached) ? cached : null;
-  } catch {
-    return null;
-  }
-}
-
-function writeCache(dir) {
-  if (!CACHE_DIR || !CACHE_FILE) return;
-  try {
-    mkdirSync(CACHE_DIR, { recursive: true, mode: 0o700 });
-    // Drop whatever is there (possibly a planted symlink) before writing.
-    rmSync(CACHE_FILE, { force: true });
-    writeFileSync(CACHE_FILE, dir, { flag: 'wx', mode: 0o600 });
-  } catch {
-    // cache is best-effort
+function killWorker() {
+  if (!child?.pid) return;
+  if (process.platform === 'win32') {
+    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], {timeout:1000, windowsHide:true, stdio:'ignore'});
+  } else {
+    try { process.kill(-child.pid, 'SIGKILL'); } catch { try {child.kill('SIGKILL');} catch {} }
   }
 }
-
-function fromNpmGlobal() {
-  try {
-    const res = spawnSync('npm root -g', { shell: true, encoding: 'utf8', timeout: 4000 });
-    const root = (res.stdout || '').trim().split(/\r?\n/).pop();
-    if (!root) return null;
-    const dir = path.join(root, 'specweave');
-    if (!isCliRoot(dir)) return null;
-    writeCache(dir);
-    return dir;
-  } catch {
-    return null;
-  }
+function finish(result = {}, reason) {
+  if (finished) return;
+  finished = true;
+  clearTimeout(deadline);
+  killWorker();
+  if (reason) record(reason);
+  process.stdout.write(JSON.stringify(result)+'\n',()=>process.exit(0));
 }
-
-function resolveCliRoot() {
-  const candidates = [
-    () => process.env.SPECWEAVE_HOME,
-    () => path.resolve(pluginRoot(), '..', '..'),
-    ...[process.env.CLAUDE_PROJECT_DIR, process.cwd()].filter(Boolean).flatMap((dir) => [
-      () => path.dirname(createRequire(path.join(dir, 'package.json')).resolve('specweave/package.json')),
-      () => path.join(dir, 'node_modules', 'specweave'),
-    ]),
-    fromCache,
-    fromNpmGlobal,
-  ];
-  for (const candidate of candidates) {
+const deadline = setTimeout(()=>finish({},'deadline_exceeded'),budget);
+process.on('SIGTERM',()=>finish({},'terminated'));
+process.on('SIGINT',()=>finish({},'interrupted'));
+process.on('uncaughtException',()=>finish({},'adapter_error'));
+process.stdin.setEncoding('utf8');
+process.stdin.on('data',chunk=>{
+  size += Buffer.byteLength(chunk, 'utf8');
+  if(size>1024*1024) return finish({},'input_limit');
+  input+=chunk;
+});
+process.stdin.on('error',()=>finish({},'stdin_error'));
+process.stdin.on('end',()=>{
+  let data;
+  try {data=JSON.parse(input);if(!data || typeof data!=='object'||Array.isArray(data))throw Error();}
+  catch {return finish({},'invalid_input');}
+  if(!['session-start','pre-tool-use','pre-compact','stop'].includes(event))return finish({});
+  if(process.env.SPECWEAVE_DISABLE_HOOKS === '1')return finish({});
+  if(event === 'stop' && !hasActiveAutoSession(data))return finish({});
+  const env={...process.env};
+  child=spawn(process.execPath,[worker,event],{env,detached:process.platform !== 'win32',stdio:['pipe','pipe','pipe']});
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data',chunk=>{
+    output+=chunk;
+    if(output.length>1024*1024)finish({},'output_limit');
+  });
+  child.stderr.resume();
+  child.stdin.on('error',()=>{});
+  child.on('error',()=>finish({},'worker_spawn_failed'));
+  child.on('close',code=>{
+    if(finished)return;
+    if(code!==0)return finish({},'worker_failed');
     try {
-      const dir = candidate();
-      if (isCliRoot(dir)) return dir;
-    } catch {
-      // try the next strategy
-    }
-  }
-  return null;
-}
-
-async function main() {
-  if (!EVENTS.has(event)) {
-    await readStdin();
-    return emit({});
-  }
-  const { raw, skip } = normalizeInput(await readStdin());
-  if (skip) return emit({});
-  const cliRoot = resolveCliRoot();
-  if (!cliRoot) return emit(inactiveOutput());
-  try {
-    const mod = await import(pathToFileURL(path.join(cliRoot, ROUTER_REL)).href);
-    const result = await mod.hookRouter(event, raw);
-    return emit(result);
-  } catch {
-    return emit(inactiveOutput());
-  }
-}
-
-process.on('uncaughtException', () => emit(inactiveOutput()));
-process.on('unhandledRejection', () => emit(inactiveOutput()));
-main().catch(() => emit(inactiveOutput()));
+      const result=JSON.parse(output);
+      if(!result||typeof result!=='object'||Array.isArray(result))throw Error();
+      finish(result);
+    } catch {finish({},'invalid_worker_output');}
+  });
+  child.stdin.end(input);
+});

package/plugins/specweave/skills/increment/SKILL.md

@@ -11,11 +11,13 @@ An increment is one folder — `.specweave/increments/NNNN-slug/` — holding
 `ledger.jsonl` (state, written by the CLI) and `metadata.json`. It is the unit of
 work and the tracker; every commit for it carries its id in the subject.
 
-## Plan mode first (blocking)
+## Scope before implementation
 
-Planning produces a document the user approves before any code is written. If your
-tool has a plan mode, enter it now (Claude Code: `EnterPlanMode`) and wait for
-confirmation. Do not create files, do not implement, until the plan is approved.
+Write a concise plan for work that needs shared acceptance criteria. Ask only about
+material ambiguity or actions beyond the user's authorization. When the user has
+asked for autonomous execution, make routine decisions and continue through
+implementation and verification. A small self-contained fix can remain a
+lightweight intent without this workflow.
 
 ## Steps
 
@@ -79,7 +81,7 @@ confirmation. Do not create files, do not implement, until the plan is approved.
    least one task; every task needs a `Test:` that a machine can run (or an explicit
    "manual: <what to check>"). Shared contracts (types, schema, migrations) go in an early
    task everything else depends on.
-6. **Present the plan** (problem, ACs, task list, risks) and get approval. Then leave plan mode.
+6. **Share the plan** (problem, ACs, tasks, material risks). Resolve any remaining decision that needs the user; otherwise continue within existing authorization.
 7. **Hand off to execution**: `sw:do <id>` for one agent; `sw:team <id>` when the work has
    3+ disjoint lanes or 15+ tasks.
 

package/src/templates/AGENTS.md.template

@@ -1,7 +1,7 @@
 <!-- SECTION:header required -->
 # {PROJECT_NAME}
 
-SpecWeave project. Work happens in increments under `.specweave/increments/NNNN-slug/`. `spec.md` (Problem, ACs, Approach) is the source of truth; the ledger records who did what. This file is for Codex, OpenCode, Cursor, Gemini, Aider and humans; Claude Code reads CLAUDE.md (same content). Keep it under one page; project-specific notes go in **Project notes** at the bottom.
+SpecWeave project. Small requests live in the intent board; scoped work lives in increments under `.specweave/increments/NNNN-slug/`. `spec.md` (Problem, ACs, Approach) is the source of truth; the ledger records who did what. This file is for Codex, OpenCode, Cursor, Gemini, Aider and humans; Claude Code reads CLAUDE.md (same content). Keep it under one page; project-specific notes go in **Project notes** at the bottom.
 <!-- /SECTION -->
 
 <!-- SECTION:structure -->
@@ -9,6 +9,7 @@ SpecWeave project. Work happens in increments under `.specweave/increments/NNNN-
 
 ```
 .specweave/
+  intents/board.jsonl       append-only intent history (latest revision per id; planning state, not verification)
   increments/NNNN-slug/   spec.md (Problem · ACs · Approach) · tasks.md (tasks + rendered board) · ledger.jsonl (claims/done, CLI-written) · handoff.md · reports/ (evidence; binaries in reports/artifacts/, gitignored)
   docs/                    ADRs and hand-written docs (read before changing architecture)
   config.json
@@ -23,7 +24,7 @@ Only those files (plus optional `plan.md` when Approach outgrows a page, and `sc
 
 | Step | Command (each step is also a standalone skill you can install into any tool with `npx vskill install anton-abyzov/specweave/sw-do` — same for `sw-increment`, `sw-review`, `sw-handoff`, `sw-task`) |
 |---|---|
-| Plan a feature: write `spec.md` (Problem, Scope, `AC-01…` checkboxes, Approach: files that change, order of work, risks, decisions), get approval before any code | `specweave create-increment "title"` |
+| Plan a feature: write `spec.md` (Problem, Scope, `AC-01…` checkboxes, Approach: files that change, order of work, risks, decisions), resolve material scope questions before implementation | `specweave create-increment "title"` |
 | Work the tasks | `specweave task next` → `specweave task claim T-NN` → implement → commit (`NNNN: …`) → `specweave task done T-NN --run "<test cmd>"` (the command runs through your OS shell: cmd.exe on Windows, sh elsewhere) |
 | Verify the whole increment | `specweave verify` |
 | Review before closing (recommended for anything that ships) | in a fresh session: read spec.md, list findings by severity citing path:line, re-verify each before writing `reports/review.md`; the authoring session never approves its own work |
@@ -31,7 +32,7 @@ Only those files (plus optional `plan.md` when Approach outgrows a page, and `sc
 | Stop for any reason | `specweave handoff` |
 
 Without the `specweave` CLI: create the folder by hand (id = highest existing 4-digit prefix + 1, zero-padded); append one JSON line per event to `ledger.jsonl` as UTF-8 without BOM, LF-terminated, e.g. `{"t":"T-01","e":"claim","by":"<tool>@<host>","at":"<ISO>"}` (bash: `>>`; PowerShell: `[IO.File]::AppendAllText('ledger.jsonl', $line + "`n")`, never `>>`, it writes UTF-16); mark done with the same line using `"e":"done","evidence":"<commit sha>"` after the Test command exits 0; write `reports/verify.md` with the real test output and say the increment is ready to close (closing itself needs the CLI).
-Start every feature with an increment, even a small one, unless the user says "no increment". Fix a bug by writing the failing test first, then fixing the code without touching the test.
+Use an increment for work that needs shared scope, acceptance criteria, or a handoff. Small self-contained fixes can remain a lightweight intent. For bugs, reproduce the failure and add a regression test when it protects behavior. User authorization carries through routine implementation and verification.
 <!-- /SECTION -->
 
 <!-- SECTION:verify required -->
@@ -48,8 +49,7 @@ Run the project's build/test/lint (see **Commands**) before reporting any task c
 3. Never edit ledger lines or another task's status; append only. On a git conflict in `ledger.jsonl` keep every line from both sides.
 4. `done` needs the task's **Test** command exit 0 and a commit sha. A task that turns out unnecessary is closed with `specweave task skip T-NN --reason "..."` (no CLI: append a `skip` ledger line with a reason), never ticked.
 5. When you stop: `specweave task release --all-mine` then `specweave handoff`.
-
-Resuming: find the active increment with `specweave status` (or the `NNNN-*` folder whose `metadata.json` has `"status": "active"`), read `spec.md`, then the latest `handoff.md`, then `specweave task next`.
+Resuming: check `.specweave/intents/board.jsonl` (latest revision per id) or `specweave dashboard` for unfinished intents, including work without an increment. Then find the active increment with `specweave status` (or the `NNNN-*` folder whose `metadata.json` has `"status": "active"`), read `spec.md`, then the latest `handoff.md`, then `specweave task next`.
 <!-- /SECTION -->
 
 <!-- SECTION:conventions required -->

package/src/templates/CLAUDE.md.template

@@ -1,7 +1,7 @@
 <!-- SECTION:header required -->
 # {PROJECT_NAME}
 
-SpecWeave project. Work happens in increments under `.specweave/increments/NNNN-slug/`. `spec.md` (Problem, ACs, Approach) is the source of truth; the ledger records who did what. Keep this file under one page; project-specific notes go in **Project notes** at the bottom.
+SpecWeave project. Small requests live in the intent board; scoped work lives in increments under `.specweave/increments/NNNN-slug/`. `spec.md` (Problem, ACs, Approach) is the source of truth; the ledger records who did what. Keep this file under one page; project-specific notes go in **Project notes** at the bottom.
 <!-- /SECTION -->
 
 <!-- SECTION:structure -->
@@ -9,6 +9,7 @@ SpecWeave project. Work happens in increments under `.specweave/increments/NNNN-
 
 ```
 .specweave/
+  intents/board.jsonl       append-only intent history (latest revision per id; planning state, not verification)
   increments/NNNN-slug/   spec.md (Problem · ACs · Approach) · tasks.md (tasks + rendered board) · ledger.jsonl (claims/done, CLI-written) · handoff.md · reports/ (evidence; binaries in reports/artifacts/, gitignored)
   docs/                    ADRs and hand-written docs (read before changing architecture)
   config.json
@@ -23,14 +24,14 @@ Only those files (plus optional `plan.md` when Approach outgrows a page, and `sc
 
 | Step | Command |
 |---|---|
-| Plan a feature (spec.md with ACs + Approach, in plan mode; approved before any code) | `/sw:increment "title"` |
+| Plan a feature (spec.md with ACs + Approach; resolve material scope questions) | `/sw:increment "title"` |
 | Work the tasks (claim → implement → commit → done with evidence) | `/sw:do` (loops `specweave task next` / `claim` / `done --run`) |
 | Verify the whole increment | `specweave verify` |
 | Review before closing (recommended for anything that ships: fresh context, findings cite path:line and are re-verified) | `/sw:review` |
 | Close (needs a green verify or `--reason`) | `/sw:done` |
 | Stop for any reason (context, tokens, switching tools) | `/sw:handoff` |
 
-Start every feature with the increment, even a small one, unless the user says "no increment". Fix a bug by writing the failing test first, then fixing the code without touching the test.
+Use an increment for work that needs shared scope, acceptance criteria, or a handoff. Small self-contained fixes can remain a lightweight intent. For bugs, reproduce the failure and add a regression test when it protects behavior. User authorization carries through routine implementation and verification.
 <!-- /SECTION -->
 
 <!-- SECTION:verify required -->
@@ -47,8 +48,7 @@ Run the project's build/test/lint (see **Commands**) before reporting any task c
 3. Never edit ledger lines or another task's status; append only. On a git conflict in `ledger.jsonl` keep every line from both sides.
 4. `done` needs the task's **Test** command exit 0 and a commit sha. A task that turns out unnecessary is closed with `specweave task skip T-NN --reason "..."`, never ticked.
 5. When you stop: `specweave task release --all-mine` then `/sw:handoff`.
-
-Resuming: find the active increment with `specweave status` (or the `NNNN-*` folder whose `metadata.json` has `"status": "active"`), read `spec.md`, then the latest `handoff.md`, then `/sw:do`.
+Resuming: check `.specweave/intents/board.jsonl` (latest revision per id) or `specweave dashboard` for unfinished intents, including work without an increment. Then find the active increment with `specweave status` (or the `NNNN-*` folder whose `metadata.json` has `"status": "active"`), read `spec.md`, then the latest `handoff.md`, then `/sw:do`.
 <!-- /SECTION -->
 
 <!-- SECTION:conventions required -->