@wrongstack/core 0.277.2 → 0.280.0

package/dist/{worktree-manager-C4YIf1Fa.d.ts → worktree-manager-BjOFF6bt.d.ts}

@@ -1,4 +1,4 @@
-import { E as EventBus } from './brain-CCfuEOdp.js';
+import { E as EventBus } from './events-Bs2fmldo.js';
 
 /**
  * Lifecycle of a single worktree handle.

package/dist/{wstack-paths-_NrRovdr.d.ts → wstack-paths-CMl_cYgq.d.ts}

@@ -9,6 +9,10 @@
 interface WstackPaths {
     /** ~/.wrongstack — global root. */
     globalRoot: string;
+    /** Absolute project root. */
+    projectRoot: string;
+    /** Home directory (~) — base for foreign tool state (~/.codex, ~/.agents, …). */
+    homeDir: string;
     /**
      * ~/.wrongstack — directory for user-global stateful config files
      * (mode.json, theme.json, …). Currently an alias for `globalRoot`;
@@ -24,6 +28,8 @@ interface WstackPaths {
     globalMemory: string;
     /** ~/.wrongstack/skills — user-global skills. */
     globalSkills: string;
+    /** ~/.claude/skills — user-global skills from foreign coding agents (Claude Code, Codex, …). Read-only. */
+    globalClaudeSkills: string;
     /** ~/.wrongstack/design-kits — user-global Design Studio kits. */
     globalDesignKits: string;
     /** ~/.wrongstack/prompts — user-global prompt library. */
@@ -67,6 +73,8 @@ interface WstackPaths {
     inProjectAgentsFile: string;
     /** <project>/.wrongstack/skills — committed project skills. */
     inProjectSkills: string;
+    /** <project>/.claude/skills — project skills authored for foreign coding agents (Claude Code, …). Read-only. */
+    inProjectClaudeSkills: string;
     /** <project>/.wrongstack/prompts — committed project prompt library. */
     inProjectPrompts: string;
     /** <project>/.wrongstack/instructions — committed project instruction overrides. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/core",
-  "version": "0.277.2",
+  "version": "0.280.0",
   "license": "MIT",
   "description": "WrongStack core: kernel, types, defaults, and shared utilities for the WrongStack CLI agent.",
   "repository": {

package/skills/mailbox-bridge/SKILL.md

@@ -126,6 +126,7 @@ require `Authorization: Bearer <token>`. All responses are JSON.
 |--------|------|-------|
 | POST | `/mailbox/send` | `GlobalMailbox.send` |
 | POST | `/mailbox/query` | `GlobalMailbox.query` |
+| POST | `/mailbox/check` | convenience inbox check: direct/base/broadcast query plus optional read/completion batch ack |
 | POST | `/mailbox/ack` | `GlobalMailbox.ack` |
 | POST | `/mailbox/ack-many` | `GlobalMailbox.ackMany` (batch under one lock + rewrite) |
 | POST | `/mailbox/unread-count` | `GlobalMailbox.unreadCount` |

package/skills/plugin-author/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: plugin-author
+description: |
+  Use this skill when creating, reviewing, or refactoring a WrongStack plugin
+  in `packages/plugins/`. Covers the Plugin interface, tool registration, config
+  schema, the H1 audit pattern (teardown + health), PluginAPI extension for host
+  data, and the entry-point registration steps (tsup, package.json, index.ts).
+  Triggers: user says "new plugin", "add a plugin", "plugin teardown", "plugin
+  health", "register a tool", "PluginAPI extension".
+version: 1.0.0
+---
+
+# Plugin Author — WrongStack
+
+## Overview
+
+Guides the creation and maintenance of first-party plugins in
+`packages/plugins/`. A plugin is a TypeScript module that implements
+the `Plugin` interface from `@wrongstack/core`, registering tools,
+hooks, slash commands, or pipelines into the agent's runtime.
+
+There are currently **21 official plugins** in the suite:
+
+| Plugin | Tools | Hooks | Stateful |
+|--------|-------|-------|----------|
+| `auto-doc` | `auto_doc` | — | ✅ teardown+health |
+| `git-autocommit` | `git_autocommit` | — | ✅ teardown+health |
+| `shell-check` | `shellcheck` | — | ✅ teardown+health |
+| `cost-tracker` | `cost_summary`, `cost_reset`, `cost_export` | — | ✅ teardown+health |
+| `file-watcher` | `watch_start`, `watch_stop`, `watch_list` | — | ✅ teardown+health |
+| `cron` | `cron_schedule`, `cron_list`, `cron_cancel` | — | ✅ teardown+health |
+| `template-engine` | `template_expand`, `template_render`, `template_create`, `template_list` | — | ✅ teardown+health |
+| `semver-bump` | `semver_bump`, `semver_current`, `semver_changelog` | — | ✅ teardown+health |
+| `secret-scanner` | `secret_scanner_status`, `secret_scanner_test` | `PreToolUse` + `PostToolUse` | ✅ teardown+health |
+| `todo-tracker` | `todo_tracker_list/add/complete/drop/remove/pull/status` | — | ✅ teardown+health |
+| `token-budget` | `token_budget_status` | `Stop` + `PostToolUse` | ✅ teardown+health |
+| `lint-gate` | `lint_gate_status` | `PreToolUse` (`write\|edit`) | ✅ teardown+health |
+| `branch-guard` | `branch_guard_status` | `PreToolUse` (`bash\|git_autocommit`) | ✅ teardown+health |
+| `diff-summary` | `diff_summary_status` | `PostToolUse` (`write\|edit`) | ✅ teardown+health |
+| `commit-validator` | `commit_validator_status` | `PreToolUse` (`bash\|git_autocommit`) | ✅ teardown+health |
+| `format-on-save` | `format_on_save_status` | `PostToolUse` (`write\|edit`) | ✅ teardown+health |
+| `test-runner-gate` | `test_gate_status` | `PostToolUse` (`write\|edit`) | ✅ teardown+health |
+| `import-organizer` | `import_organizer_status` | `PostToolUse` (`write\|edit`) | ✅ teardown+health |
+| `todo-listener` | `todo_listener_status` | `PostToolUse` (`todo`) | ✅ teardown+health |
+| `session-recap` | `session_recap_status` | `Stop` | ✅ teardown+health |
+| `spec-linker` | `spec_linker_status` | `PostToolUse` (`write\|edit`) | ✅ teardown+health |
+
+## Rules
+
+1. **Every plugin must implement `teardown()` and `health()`.** Even
+   stateless plugins (shell-check, semver-bump) add both — the teardown
+   logs a completion line with per-session counters, and `health()`
+   reports `ok: true` + counters for `/diag plugins`. This is the **H1
+   audit pattern** (see below).
+2. **State at module scope, not in the setup() closure.** The Plugin
+   interface does not thread state from `setup()` → `teardown()`. If
+   teardown needs to clean up a resource (timer, watcher, counter),
+   the reference must live at module scope. State in the setup
+   closure is unreachable from teardown and **leaks on reload**.
+3. **`setup()` is idempotent.** It must zero/clear state before
+   re-initializing. Calling `setup()` twice (e.g. across a hot-reload)
+   leaves a clean slate, not accumulated state.
+4. **`teardown()` never deletes on-disk state.** File-based plugins
+   (todo-tracker) leave the file in place — the user may return. Only
+   in-memory counters and resource handles (timers, watchers) are
+   cleaned up.
+5. **Tool names use `snake_case`.** Plugin-level tools registered via
+   `api.tools.register()` must be unique across the suite. The built-in
+   tools (`bash`, `write`, `read`, `edit`, `fetch`, `search`, `json`,
+   `todo`, `git`, etc.) are always present; don't collide.
+6. **`apiVersion` must satisfy `^0.1` (current kernel API = `0.1.10`).**
+   Bump only when the PluginAPI surface breaks. Additive changes (new
+   optional fields on PluginAPI) do NOT require a bump.
+7. **Config goes under `config.extensions['<plugin-name>']`**, not
+   `config.plugins`. The loader's `buildPluginOptions` merges both
+   surfaces; plugins read from `api.config.extensions`.
+
+## The Plugin interface
+
+```typescript
+import type { Plugin } from '@wrongstack/core';
+
+const plugin: Plugin = {
+  name: 'my-plugin',
+  version: '0.1.0',
+  description: 'One-line summary for wstack plugins list',
+  apiVersion: '^0.1.10',
+  capabilities: { tools: true }, // hints for /diag
+
+  // Optional: JSON Schema for config validation
+  defaultConfig: { enabled: true },
+  configSchema: {
+    type: 'object',
+    properties: {
+      enabled: { type: 'boolean', default: true },
+    },
+  },
+
+  // Called by the host to activate the plugin.
+  setup(api) { /* register tools, hooks, events */ },
+
+  // Called by the host during unload. Same api instance as setup.
+  teardown(api) { /* clear state, release resources, log */ },
+
+  // Called by /diag plugins. Return ok + message + counters.
+  async health() {
+    return { ok: true, message: 'healthy', invocationCount: 0 };
+  },
+};
+
+export default plugin;
+```
+
+## H1 audit pattern
+
+After the 2026-06-03 audit found that several plugins leaked resources
+on reload (timers, chokidar watchers, in-memory caches unreachable from
+teardown), the following lifecycle pattern was formalized. **All 10
+plugins follow it.**
+
+### 1. State at module scope
+
+```typescript
+// ✅ Module scope — teardown can reach this
+const state = {
+  invocationCount: 0,
+  timers: new Map<string, NodeJS.Timeout>(),
+  lastRun: null as null | { when: string; result: string },
+};
+
+// ❌ NEVER — setup closure, unreachable from teardown
+setup(api) {
+  const timers = new Map();  // LEAKS on reload
+}
+```
+
+### 2. Idempotent setup
+
+```typescript
+setup(api) {
+  // Clear everything first, then re-init from config.
+  state.invocationCount = 0;
+  for (const t of state.timers.values()) clearTimeout(t);
+  state.timers.clear();
+  state.lastRun = null;
+
+  // Now register tools, apply config, subscribe to events.
+  api.tools.register({ /* ... */ });
+}
+```
+
+### 3. Teardown releases resources
+
+```typescript
+teardown(api) {
+  const count = state.invocationCount;
+  state.invocationCount = 0;
+  state.lastRun = null;
+  // Release every resource that was acquired in setup().
+  for (const t of state.timers.values()) clearTimeout(t);
+  state.timers.clear();
+  api.log.info('my-plugin: teardown complete', { invocations: count });
+}
+```
+
+### 4. Health reports per-session visibility
+
+```typescript
+async health() {
+  return {
+    ok: true,
+    message: state.lastRun === null
+      ? 'my-plugin: no calls yet'
+      : `my-plugin: last call at ${state.lastRun.when}`,
+    invocationCount: state.invocationCount,
+    lastRun: state.lastRun,
+  };
+}
+```
+
+## Tool registration
+
+```typescript
+api.tools.register({
+  name: 'my_tool',
+  description: 'What this tool does. Include when to use and what it returns.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'File path' },
+    },
+    required: ['path'],
+  },
+  permission: 'auto',     // 'auto' | 'confirm'
+  mutating: false,         // does it change external state?
+  category: 'Project',
+  async execute(input: Record<string, unknown>) {
+    const path = input['path'] as string;
+    // ... do the work ...
+    return { ok: true, path, result: '...' };
+  },
+});
+```
+
+### Permission levels
+
+| Permission | When |
+|------------|------|
+| `auto` | Safe operations (read, list, query). No user confirmation. |
+| `confirm` | Destructive or side-effecting operations (write, commit, delete). User must approve. |
+
+## Config surface
+
+Two surfaces exist. The loader merges them:
+
+1. **`config.plugins`** — loading control: `[{ name: 'my-plugin', enabled: false }]`
+2. **`config.extensions['my-plugin']`** — options: `{ option1: value1 }`
+
+Plugins read from `api.config.extensions`:
+
+```typescript
+setup(api) {
+  const ext = api.config.extensions?.['my-plugin'] as Record<string, unknown> | undefined;
+  const myOption = (ext?.['myOption'] as string) ?? 'default';
+}
+```
+
+If the plugin declares `configSchema`, the loader validates the
+options section before calling `setup` and rejects the plugin with a
+clear error on failure.
+
+## Hook registration (PreToolUse, PostToolUse, etc.)
+
+```typescript
+// secret-scanner pattern: block tools whose args contain secrets
+api.registerHook('PreToolUse', 'bash|write|edit', (input) => {
+  const text = JSON.stringify(input.toolInput ?? {});
+  if (detectSecret(text)) {
+    return {
+      decision: 'block',
+      reason: 'Plaintext credential detected in tool arguments',
+    };
+  }
+  // Omitted decision = allow (no-op)
+});
+```
+
+Available events: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`,
+`SessionStart`, `Stop`.
+
+`HookOutcome` fields:
+- `decision: 'block' | 'allow'` — block stops the action
+- `reason: string` — surfaced to the model when blocking
+- `modifiedInput: Record<string, unknown>` — PreToolUse replacement args
+- `additionalContext: string` — extra context folded back to the model
+
+## PluginAPI extension (cross-package host data)
+
+When a plugin needs host data not yet on `PluginAPI` (e.g.
+`modelsRegistry`, `projectDir`), extend the surface in three steps:
+
+1. **`packages/core/src/types/plugin.ts`** — add the optional field to `PluginAPI`
+2. **`packages/core/src/plugin/api.ts`** — add to `PluginAPIInit` + `DefaultPluginAPI`
+3. **`packages/cli/src/wiring/plugins.ts`** — destructure + forward in `setupPlugins`
+
+Precedent: commit `9bed619f` added `modelsRegistry?: ModelsRegistry` for
+cost-tracker's pricing hydration.
+
+## Entry-point registration (3 files)
+
+After writing `src/<name>/index.ts`, wire it into three files:
+
+### 1. `src/index.ts` — named re-export
+
+```typescript
+export { default as myPluginPlugin } from './my-plugin/index.js';
+```
+
+### 2. `tsup.config.ts` — build entry
+
+```typescript
+entry: {
+  // ...
+  'my-plugin': 'src/my-plugin/index.ts',
+},
+```
+
+### 3. `package.json` — subpath export
+
+```json
+"./my-plugin": {
+  "types": "./dist/my-plugin.d.ts",
+  "import": "./dist/my-plugin.js"
+}
+```
+
+### 4. `packages/cli/src/wiring/plugins.ts` — built-in factory
+
+```typescript
+async () => (await import('@wrongstack/plugins/my-plugin')).default,
+```
+
+## Tests
+
+Every plugin gets two test files:
+
+- **`tests/<name>.test.ts`** — unit tests (mock API, tool registration,
+  config validation, teardown log line, health() shape)
+- **`tests/<name>-exec.test.ts`** — integration tests (real filesystem,
+  real CLI tools if applicable)
+
+For the H1 pattern, extend `tests/plugin-teardown.test.ts` with a
+`describe('<name>')` block covering:
+- `teardown` logs a completion line and does not throw
+- `health()` reports ok + non-empty message
+- `teardown` zeros counters
+
+## Anti-patterns
+
+- **State in setup closure** — leaks on reload. Always module scope.
+- **Missing teardown** — `/diag plugins` shows a gap; reload leaks.
+- **Missing health()** — operator can't confirm the plugin is alive.
+- **Tool name collision** — `read`, `write`, `bash`, etc. are built-in.
+- **Deleting on-disk state in teardown** — the user may return.
+- **Blocking setup with async hydration** — use `void (async () => { ... })()`
+  for fire-and-forget; let the first call fall through to fallback if
+  the async hasn't completed yet.
+- **Not lowercasing model/config keys** — case-insensitive lookup is
+  the convention; `model.toLowerCase()` everywhere.
+
+## Workflow
+
+1. **Create the plugin directory**: `src/<name>/index.ts`
+2. **Write the Plugin object**: name, version, apiVersion, setup, teardown, health
+3. **Register tools/hooks** in `setup()`
+4. **Add state + teardown + health** following the H1 pattern
+5. **Wire into 3 files**: `index.ts`, `tsup.config.ts`, `package.json`
+6. **Add to `BUILTIN_PLUGIN_FACTORIES`** in CLI wiring
+7. **Write tests**: `<name>.test.ts` (unit) + extend `plugin-teardown.test.ts`
+8. **Run verification**: `npx vitest run packages/plugins` + `npx tsc --noEmit` + `npx tsup`
+9. **Update `src/index.ts` doc comment** — bump the plugin count
+
+## Skills in scope
+
+- `skill-creator` — for the SKILL.md format and frontmatter rules
+- `prompt-engineering` — for crafting tool descriptions and usageHint
+- `typescript-strict` — for strict TypeScript patterns in plugin code
+- `node-modern` — for ESM imports, AbortSignal, and async patterns
+- `testing` — for vitest patterns and mock API construction
+- `output-standards` — for standardized `<next_steps>` formatting

package/skills/sdd/SKILL.md

@@ -1,135 +1,135 @@
----
-name: sdd
-description: |
-  Use this skill when starting a non-trivial implementation, bug fix, or refactor
-  in WrongStack. Triggers: user says "/sdd", "spec", "specification", "task graph",
-  "SDD", "acceptance criteria", or starts a new feature.
-version: 2.1.0
----
-
-# Spec-Driven Development — WrongStack
-
-## Overview
-
-Every non-trivial change starts with a spec. The spec is the source of truth — it defines what to build, how to verify it, and what counts as done. SDD uses `/sdd` slash commands to create specs, generate task graphs, and track execution.
-
-## Rules
-
-1. Every non-trivial task needs a spec before writing code — you'll rewrite it anyway.
-2. Spec must have acceptance criteria — without them, you can't know when it's done.
-3. Tasks must have dependencies — everything is a dependency of something.
-4. Spec must be specific: "Users authenticate via OAuth2 with PKCE" not "improve auth".
-5. Skipping `/sdd` for urgent tasks backfires — the spec is what makes "urgent" possible.
-6. When the spec reveals a multi-file refactor, delegate to `refactor-planner` first.
-
-## When to use
-
-- New feature implementation
-- Bug fix with complexity
-- Refactoring with scope
-- Any task requiring more than 1 hour
-
-## The SDD workflow
-
-```
-1. /sdd new [title]          → Build spec from questions
-2. /sdd tasks <id>           → Generate task graph from spec
-3. /sdd graph <id>           → Visualize dependencies
-4. /sdd critical <id>        → Find bottlenecks
-5. /sdd execute <id>         → Run tasks (or execute manually)
-```
-
-## Task lifecycle commands
-
-| Command | What it does |
-|---------|--------------|
-| `/sdd tasks` | Show task list with progress bar (sorted: in_progress → pending → review → blocked → failed → completed) |
-| `/sdd next` | Show next executable task + blockers |
-| `/sdd done <N>` | Complete a task (by number or fuzzy title match) |
-| `/sdd skip <N>` | Skip a task back to pending |
-| `/sdd fail <N>` | Mark a task as failed |
-| `/sdd review <N>` | Send a task to review |
-| `/sdd edit <N> <text>` | Edit task title (short text) or description (long text) |
-| `/sdd undo` | Undo last task completion |
-| `/sdd graph` | ASCII task dependency visualization |
-| `/sdd critical` | Critical path analysis + bottlenecks |
-
-## Spec templates
-
-| Template | Best for |
-|---|---|
-| `feature` | New feature development |
-| `bugfix` | Bug fix with root cause analysis |
-| `refactor` | Code refactoring with goals |
-| `infra` | Infrastructure/tooling changes |
-| `integration` | External service integration |
-| `cli-command` | New CLI commands/slash commands |
-
-## Spec structure
-
-A complete spec has:
-1. **Overview** — What problem does this solve?
-2. **Requirements** — `[priority] description` format
-3. **Architecture** — High-level design (if needed)
-4. **API Design** — Endpoints, inputs, outputs (if applicable)
-5. **Acceptance Criteria** — How do we know it's done?
-
-### Requirement format
-
-```
-[critical] Users can authenticate with OAuth2
-[high] Rate limiting: 100 req/min per user  
-[medium] Response time < 200ms p95
-[low] Support dark mode
-```
-
-## Task graph generation
-
-Each requirement generates one or more tasks. Tasks have states:
-```
-pending → in_progress → review → completed
-              ↓
-           blocked (waiting on dependencies)
-              ↓
-           failed
-```
-
-## Critical path
-
-The critical path finds:
-- **Bottleneck tasks** blocking the most downstream work
-- **Parallel groups** that can run concurrently
-- **Ready tasks** that can start immediately
-- **Execution order** respecting all dependencies
-
-## Goal & Eternal Mode
-
-`/sdd` pairs with `/goal` for autonomous execution:
-
-| Command | What it does |
-|---------|--------------|
-| `/goal set <text>` | Set an autonomous mission |
-| `/goal pause` | Pause at end of current iteration |
-| `/goal resume` | Resume a paused goal |
-| `/goal journal [N]` | Show recent journal entries |
-| `/goal clear` | Clear goal and stop eternal mode |
-| `/autonomy eternal` | Run goal loop indefinitely |
-| `/autonomy stop` | Stop eternal mode |
-
-**Eternal stage flow:** `decide → execute → reflect → sleep | paused | stopped`
-Stage shown in real-time. Pause stops after current iteration completes.
-
-## Anti-patterns
-
-- **Writing code before the spec** — you'll rewrite it anyway
-- **Spec that's too vague** — "improve auth" is not a spec, "Users authenticate via OAuth2 with PKCE" is
-- **Tasks with no dependencies** — everything is a dependency of something
-- **Spec without acceptance criteria** — how do you know when it's done?
-- **Skipping /sdd for urgent tasks** — the spec is what makes "urgent" possible
-
-## Skills in scope
-
-- `refactor-planner` — when the spec reveals a multi-file refactor
-- `bug-hunter` — when a bugfix spec needs a root cause analysis section
-- `multi-agent` — for executing parallel task groups
+---
+name: sdd
+description: |
+  Use this skill when starting a non-trivial implementation, bug fix, or refactor
+  in WrongStack. Triggers: user says "/sdd", "spec", "specification", "task graph",
+  "SDD", "acceptance criteria", or starts a new feature.
+version: 2.1.0
+---
+
+# Spec-Driven Development — WrongStack
+
+## Overview
+
+Every non-trivial change starts with a spec. The spec is the source of truth — it defines what to build, how to verify it, and what counts as done. SDD uses `/sdd` slash commands to create specs, generate task graphs, and track execution.
+
+## Rules
+
+1. Every non-trivial task needs a spec before writing code — you'll rewrite it anyway.
+2. Spec must have acceptance criteria — without them, you can't know when it's done.
+3. Tasks must have dependencies — everything is a dependency of something.
+4. Spec must be specific: "Users authenticate via OAuth2 with PKCE" not "improve auth".
+5. Skipping `/sdd` for urgent tasks backfires — the spec is what makes "urgent" possible.
+6. When the spec reveals a multi-file refactor, delegate to `refactor-planner` first.
+
+## When to use
+
+- New feature implementation
+- Bug fix with complexity
+- Refactoring with scope
+- Any task requiring more than 1 hour
+
+## The SDD workflow
+
+```
+1. /sdd new [title]          → Build spec from questions
+2. /sdd tasks <id>           → Generate task graph from spec
+3. /sdd graph <id>           → Visualize dependencies
+4. /sdd critical <id>        → Find bottlenecks
+5. /sdd execute <id>         → Run tasks (or execute manually)
+```
+
+## Task lifecycle commands
+
+| Command | What it does |
+|---------|--------------|
+| `/sdd tasks` | Show task list with progress bar (sorted: in_progress → pending → review → blocked → failed → completed) |
+| `/sdd next` | Show next executable task + blockers |
+| `/sdd done <N>` | Complete a task (by number or fuzzy title match) |
+| `/sdd skip <N>` | Skip a task back to pending |
+| `/sdd fail <N>` | Mark a task as failed |
+| `/sdd review <N>` | Send a task to review |
+| `/sdd edit <N> <text>` | Edit task title (short text) or description (long text) |
+| `/sdd undo` | Undo last task completion |
+| `/sdd graph` | ASCII task dependency visualization |
+| `/sdd critical` | Critical path analysis + bottlenecks |
+
+## Spec templates
+
+| Template | Best for |
+|---|---|
+| `feature` | New feature development |
+| `bugfix` | Bug fix with root cause analysis |
+| `refactor` | Code refactoring with goals |
+| `infra` | Infrastructure/tooling changes |
+| `integration` | External service integration |
+| `cli-command` | New CLI commands/slash commands |
+
+## Spec structure
+
+A complete spec has:
+1. **Overview** — What problem does this solve?
+2. **Requirements** — `[priority] description` format
+3. **Architecture** — High-level design (if needed)
+4. **API Design** — Endpoints, inputs, outputs (if applicable)
+5. **Acceptance Criteria** — How do we know it's done?
+
+### Requirement format
+
+```
+[critical] Users can authenticate with OAuth2
+[high] Rate limiting: 100 req/min per user  
+[medium] Response time < 200ms p95
+[low] Support dark mode
+```
+
+## Task graph generation
+
+Each requirement generates one or more tasks. Tasks have states:
+```
+pending → in_progress → review → completed
+              ↓
+           blocked (waiting on dependencies)
+              ↓
+           failed
+```
+
+## Critical path
+
+The critical path finds:
+- **Bottleneck tasks** blocking the most downstream work
+- **Parallel groups** that can run concurrently
+- **Ready tasks** that can start immediately
+- **Execution order** respecting all dependencies
+
+## Goal & Eternal Mode
+
+`/sdd` pairs with `/goal` for autonomous execution:
+
+| Command | What it does |
+|---------|--------------|
+| `/goal set <text>` | Set an autonomous mission |
+| `/goal pause` | Pause at end of current iteration |
+| `/goal resume` | Resume a paused goal |
+| `/goal journal [N]` | Show recent journal entries |
+| `/goal clear` | Clear goal and stop eternal mode |
+| `/autonomy eternal` | Run goal loop indefinitely |
+| `/autonomy stop` | Stop eternal mode |
+
+**Eternal stage flow:** `decide → execute → reflect → sleep | paused | stopped`
+Stage shown in real-time. Pause stops after current iteration completes.
+
+## Anti-patterns
+
+- **Writing code before the spec** — you'll rewrite it anyway
+- **Spec that's too vague** — "improve auth" is not a spec, "Users authenticate via OAuth2 with PKCE" is
+- **Tasks with no dependencies** — everything is a dependency of something
+- **Spec without acceptance criteria** — how do you know when it's done?
+- **Skipping /sdd for urgent tasks** — the spec is what makes "urgent" possible
+
+## Skills in scope
+
+- `refactor-planner` — when the spec reveals a multi-file refactor
+- `bug-hunter` — when a bugfix spec needs a root cause analysis section
+- `multi-agent` — for executing parallel task groups
 - `output-standards` — for standardized `<next_steps>` formatting