@rkarim08/sia 1.0.0

package/package.json

@@ -0,0 +1,110 @@
+{
+	"name": "@rkarim08/sia",
+	"version": "1.0.0",
+	"description": "Persistent graph memory for AI coding agents",
+	"type": "module",
+	"license": "Apache-2.0",
+	"author": {
+		"name": "Ramez Karim"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/rkarim08/sia.git"
+	},
+	"homepage": "https://github.com/rkarim08/sia#readme",
+	"bugs": {
+		"url": "https://github.com/rkarim08/sia/issues"
+	},
+	"keywords": [
+		"claude-code",
+		"plugin",
+		"memory",
+		"knowledge-graph",
+		"mcp",
+		"ai-coding",
+		"persistent-memory",
+		"bi-temporal",
+		"tree-sitter"
+	],
+	"bin": {
+		"sia": "./src/cli/index.ts"
+	},
+	"scripts": {
+		"test": "vitest run --config vitest.config.ts",
+		"test:unit": "vitest run --config vitest.config.ts",
+		"test:integration": "vitest run --config vitest.integration.config.ts",
+		"test:watch": "vitest --config vitest.config.ts",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write .",
+		"format": "biome format --write .",
+		"typecheck": "tsc --noEmit",
+		"test:tree-sitter-bun": "bun test tests/bun/tree-sitter-smoke.test.ts",
+		"prepublishOnly": "bun run typecheck && bun run test"
+	},
+	"dependencies": {
+		"@ai-sdk/anthropic": "^3.0.58",
+		"@ai-sdk/openai": "^3.0.41",
+		"@anthropic-ai/sdk": "^0.79.0",
+		"@libsql/client": "^0.10.0",
+		"@modelcontextprotocol/sdk": "^1.27.1",
+		"@napi-rs/keyring": "^1.1.8",
+		"ai": "^6.0.116",
+		"chokidar": "^3.6.0",
+		"onnxruntime-node": "^1.24.3",
+		"tree-sitter": "^0.25.0",
+		"tree-sitter-bash": "^0.25.1",
+		"tree-sitter-c": "^0.24.1",
+		"tree-sitter-c-sharp": "^0.23.1",
+		"tree-sitter-cpp": "^0.23.4",
+		"tree-sitter-dart": "^1.0.0",
+		"tree-sitter-elixir": "^0.3.5",
+		"tree-sitter-go": "^0.25.0",
+		"tree-sitter-haskell": "^0.23.1",
+		"tree-sitter-java": "^0.23.5",
+		"tree-sitter-javascript": "^0.25.0",
+		"tree-sitter-kotlin": "^0.3.8",
+		"tree-sitter-lua": "^2.1.3",
+		"tree-sitter-ocaml": "^0.24.2",
+		"tree-sitter-php": "^0.24.2",
+		"tree-sitter-python": "^0.25.0",
+		"tree-sitter-r": "^0.0.1-security",
+		"tree-sitter-ruby": "^0.23.1",
+		"tree-sitter-rust": "^0.24.0",
+		"tree-sitter-scala": "^0.24.0",
+		"tree-sitter-sql": "^0.1.0",
+		"tree-sitter-swift": "^0.7.1",
+		"tree-sitter-toml": "^0.5.1",
+		"tree-sitter-typescript": "^0.23.2",
+		"tree-sitter-zig": "^0.2.0",
+		"turndown": "^7.2.2",
+		"uuid": "^13.0.0",
+		"web-tree-sitter": "^0.26.7",
+		"yaml": "^2.8.3",
+		"zod": "^4.3.6"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.7",
+		"@types/better-sqlite3": "^7.6.13",
+		"@types/bun": "^1.3.10",
+		"@types/turndown": "^5.0.6",
+		"@types/uuid": "^11.0.0",
+		"better-sqlite3": "^12.8.0",
+		"typescript": "^5.9.3",
+		"vitest": "^4.1.0"
+	},
+	"engines": {
+		"bun": ">=1.0.0"
+	},
+	"files": [
+		"src/",
+		"scripts/",
+		"skills/",
+		"agents/",
+		"hooks/",
+		"migrations/",
+		".claude-plugin/",
+		".mcp.json",
+		"CLAUDE.md",
+		"PLUGIN_README.md"
+	]
+}

package/scripts/branch-switch.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Branch switch detection hook
+# stderr is redirected to a log file so diagnostics from the TypeScript
+# handler are preserved for debugging (not discarded via /dev/null).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(dirname "$SCRIPT_DIR")"
+
+SIA_LOG_DIR="${CLAUDE_PLUGIN_DATA:-${HOME}/.sia}/logs"
+mkdir -p "$SIA_LOG_DIR"
+
+exec bun run "$PLUGIN_ROOT/src/hooks/plugin-branch-switch.ts" 2>>"${SIA_LOG_DIR}/hooks.log"

package/scripts/build-wasm-grammars.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# build-wasm-grammars.sh
+# Builds tree-sitter WASM grammars from npm packages.
+# Requires: tree-sitter CLI, emscripten (emcc on PATH)
+#
+# Usage:
+#   ./scripts/build-wasm-grammars.sh [grammar-name ...]
+#   If no arguments given, builds all grammars from grammars/versions.json.
+#
+# Output: grammars/wasm/*.wasm
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+VERSIONS_FILE="${REPO_ROOT}/grammars/versions.json"
+OUT_DIR="${REPO_ROOT}/grammars/wasm"
+NODE_MODULES="${REPO_ROOT}/node_modules"
+
+mkdir -p "${OUT_DIR}"
+
+# Check dependencies
+if ! command -v tree-sitter &>/dev/null; then
+  echo "ERROR: tree-sitter CLI not found. Install with: npm install -g tree-sitter-cli" >&2
+  exit 1
+fi
+
+if ! command -v emcc &>/dev/null; then
+  echo "ERROR: emcc (Emscripten) not found. See https://emscripten.org/docs/getting_started/downloads.html" >&2
+  exit 1
+fi
+
+# Parse versions.json to get grammar list
+# Requires: jq
+if ! command -v jq &>/dev/null; then
+  echo "ERROR: jq not found. Install with: brew install jq / apt install jq" >&2
+  exit 1
+fi
+
+# Build a specific grammar given its language key
+build_grammar() {
+  local lang="$1"
+  local pkg wasm_file src_dir
+
+  pkg=$(jq -r ".grammars[\"${lang}\"].package" "${VERSIONS_FILE}")
+  wasm_file=$(jq -r ".grammars[\"${lang}\"].wasmFile" "${VERSIONS_FILE}")
+
+  if [[ "${pkg}" == "null" ]]; then
+    echo "WARNING: Unknown grammar '${lang}', skipping." >&2
+    return 0
+  fi
+
+  src_dir="${NODE_MODULES}/${pkg}"
+
+  if [[ ! -d "${src_dir}" ]]; then
+    echo "WARNING: Package directory not found: ${src_dir}. Run 'bun install' first." >&2
+    return 0
+  fi
+
+  echo "Building ${lang} -> ${wasm_file} ..."
+  (
+    cd "${src_dir}"
+    tree-sitter build --wasm --output "${OUT_DIR}/${wasm_file}"
+  )
+  echo "  Done: ${OUT_DIR}/${wasm_file}"
+}
+
+# Determine which grammars to build
+if [[ $# -gt 0 ]]; then
+  TARGETS=("$@")
+else
+  mapfile -t TARGETS < <(jq -r '.grammars | keys[]' "${VERSIONS_FILE}")
+fi
+
+echo "Building ${#TARGETS[@]} WASM grammar(s) into ${OUT_DIR}/"
+for lang in "${TARGETS[@]}"; do
+  build_grammar "${lang}"
+done
+
+echo ""
+echo "All done. WASM files written to: ${OUT_DIR}/"

package/scripts/post-compact.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# PostCompact hook — logs compaction coverage info for observability
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(dirname "$SCRIPT_DIR")"
+
+exec bun run "$PLUGIN_ROOT/src/hooks/plugin-post-compact.ts" 2>/dev/null

package/scripts/post-tool-use.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# PostToolUse hook — captures knowledge from Write/Edit events
+# Receives hook event data on stdin as JSON
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Pass stdin through to the handler
+exec bun run "$PLUGIN_ROOT/src/hooks/plugin-post-tool-use.ts" 2>/dev/null

package/scripts/pre-compact.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# PreCompact hook — scans transcript tail for unextracted knowledge before context compaction
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(dirname "$SCRIPT_DIR")"
+
+exec bun run "$PLUGIN_ROOT/src/hooks/plugin-pre-compact.ts" 2>/dev/null

package/scripts/session-end.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# SessionEnd hook — records session statistics and entity counts
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(dirname "$SCRIPT_DIR")"
+
+exec bun run "$PLUGIN_ROOT/src/hooks/plugin-session-end.ts" 2>/dev/null

package/scripts/session-start.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# SessionStart hook — injects recent decisions/conventions/bugs as context
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(dirname "$SCRIPT_DIR")"
+
+exec bun run "$PLUGIN_ROOT/src/hooks/plugin-session-start.ts" 2>/dev/null

package/scripts/start-mcp.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env bun
+import { randomUUID } from "node:crypto";
+import { resolveRepoHash } from "../src/capture/hook";
+import { openBridgeDb } from "../src/graph/bridge-db";
+import { openMetaDb } from "../src/graph/meta-db";
+import { openGraphDb } from "../src/graph/semantic-db";
+import { startServer } from "../src/mcp/server";
+import { getConfig, resolveSiaHome } from "../src/shared/config";
+
+const cwd = process.cwd();
+const repoHash = resolveRepoHash(cwd);
+const siaHome = resolveSiaHome();
+const config = getConfig(siaHome);
+
+const graphDb = openGraphDb(repoHash, siaHome);
+const metaDb = openMetaDb(siaHome);
+const bridgeDb = openBridgeDb(siaHome);
+const sessionId = randomUUID();
+
+await startServer({ graphDb, bridgeDb, metaDb, embedder: null, config, sessionId });
+
+// Start maintenance scheduler (background — non-blocking)
+try {
+	const { openEpisodicDb } = await import("../src/graph/semantic-db");
+	const { createMaintenanceScheduler } = await import("../src/decay/maintenance-scheduler");
+
+	const episodicDb = openEpisodicDb(repoHash, siaHome);
+
+	const scheduler = createMaintenanceScheduler({
+		graphDb,
+		episodicDb,
+		bridgeDb,
+		config,
+		repoHash,
+		siaHome,
+	});
+
+	scheduler.onStartup(repoHash).catch((err) => {
+		process.stderr.write(`sia: maintenance startup failed (non-fatal): ${err}\n`);
+	});
+
+	process.stderr.write("sia: maintenance scheduler started\n");
+} catch (err) {
+	process.stderr.write(`sia: maintenance scheduler init failed: ${err}\n`);
+}

package/scripts/stop-hook.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Stop hook — detects uncaptured knowledge patterns before session ends
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(dirname "$SCRIPT_DIR")"
+
+exec bun run "$PLUGIN_ROOT/src/hooks/plugin-stop.ts" 2>/dev/null

package/scripts/user-prompt-submit.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — captures user prompts and detects correction/preference patterns
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(dirname "$SCRIPT_DIR")"
+
+exec bun run "$PLUGIN_ROOT/src/hooks/plugin-user-prompt-submit.ts" 2>/dev/null

package/scripts/viz-server.ts

@@ -0,0 +1,152 @@
+#!/usr/bin/env bun
+
+// SIA Graph Visualizer — Live browser companion server
+//
+// Watches a directory for HTML files and serves the newest one.
+// Based on superpowers' visual companion pattern.
+//
+// Usage: bun run scripts/viz-server.ts --screen-dir <dir> [--port <port>]
+
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { createServer } from "node:http";
+import { extname, join } from "node:path";
+
+// Frame template with SIA branding
+export const FRAME_TEMPLATE = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>SIA Knowledge Graph</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: #1a1a2e; color: #e0e0e0; }
+  .header { padding: 12px 24px; background: #16213e; border-bottom: 1px solid #0f3460; display: flex; align-items: center; gap: 12px; }
+  .header h1 { font-size: 16px; font-weight: 600; color: #e94560; }
+  .header .subtitle { font-size: 13px; color: #888; }
+  .content { padding: 24px; }
+  h2 { color: #e94560; margin-bottom: 16px; }
+  h3 { color: #ccc; margin-bottom: 8px; }
+  .subtitle { color: #888; font-size: 14px; }
+  .options { display: flex; flex-wrap: wrap; gap: 16px; margin: 16px 0; }
+  .option { background: #16213e; border: 2px solid #0f3460; border-radius: 8px; padding: 16px; cursor: pointer; flex: 1; min-width: 200px; transition: all 0.2s; }
+  .option:hover { border-color: #e94560; }
+  .option.selected { border-color: #e94560; background: #1a1a3e; }
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>SIA</h1>
+  <span class="subtitle">Knowledge Graph Visualizer</span>
+</div>
+<div class="content">
+{{CONTENT}}
+</div>
+<script>
+function toggleSelect(el) {
+  document.querySelectorAll('.option, .card').forEach(o => o.classList.remove('selected'));
+  el.classList.add('selected');
+  const choice = el.dataset.choice;
+  const text = el.textContent.trim().slice(0, 100);
+  fetch('/event', { method: 'POST', body: JSON.stringify({ type: 'click', choice, text, timestamp: Date.now() }) });
+}
+</script>
+</body>
+</html>`;
+
+/** Replace the {{CONTENT}} placeholder in the frame template. */
+export function buildFrameHtml(content: string): string {
+	return FRAME_TEMPLATE.replace("{{CONTENT}}", content);
+}
+
+/** Find the newest .html file in the given directory. Returns filename or null. */
+export function getNewestHtml(dir: string): string | null {
+	if (!existsSync(dir)) return null;
+	const files = readdirSync(dir)
+		.filter((f) => extname(f) === ".html")
+		.map((f) => ({ name: f, mtime: statSync(join(dir, f)).mtimeMs }))
+		.sort((a, b) => b.mtime - a.mtime);
+	return files.length > 0 ? files[0].name : null;
+}
+
+/** Start the viz server. Only runs when executed directly (not imported for tests). */
+export function startServer(screenDir: string, port: number): void {
+	mkdirSync(screenDir, { recursive: true });
+
+	const server = createServer((req, res) => {
+		if (req.method === "POST" && req.url === "/event") {
+			const chunks: Buffer[] = [];
+			req.on("data", (c) => chunks.push(c));
+			req.on("end", () => {
+				appendFileSync(join(screenDir, ".events"), `${Buffer.concat(chunks).toString()}\n`);
+				res.writeHead(200);
+				res.end("ok");
+			});
+			return;
+		}
+
+		if (req.url === "/health") {
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ status: "ok" }));
+			return;
+		}
+
+		const newest = getNewestHtml(screenDir);
+		if (!newest) {
+			res.writeHead(200, { "Content-Type": "text/html" });
+			res.end(buildFrameHtml("<p class='subtitle'>Waiting for visualization...</p>"));
+			return;
+		}
+
+		const content = readFileSync(join(screenDir, newest), "utf-8");
+		res.writeHead(200, { "Content-Type": "text/html" });
+
+		if (content.startsWith("<!DOCTYPE") || content.startsWith("<html")) {
+			res.end(content);
+		} else {
+			res.end(buildFrameHtml(content));
+		}
+	});
+
+	server.listen(port, () => {
+		const info = {
+			type: "server-started",
+			port,
+			url: `http://localhost:${port}`,
+			screen_dir: screenDir,
+		};
+		writeFileSync(join(screenDir, ".server-info"), JSON.stringify(info));
+		console.log(JSON.stringify(info));
+	});
+}
+
+// --- CLI entry point ---
+// Only start server when run directly, not when imported for testing
+const isDirectRun =
+	process.argv[1]?.endsWith("viz-server.ts") || process.argv[1]?.endsWith("viz-server.js");
+
+if (isDirectRun) {
+	const args = process.argv.slice(2);
+	let screenDir = "";
+	let port = 52742;
+
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === "--screen-dir" && args[i + 1]) screenDir = args[++i];
+		if (args[i] === "--port" && args[i + 1]) port = parseInt(args[++i], 10);
+	}
+
+	if (!screenDir) {
+		console.error("Usage: bun run viz-server.ts --screen-dir <dir>");
+		process.exit(1);
+	}
+
+	startServer(screenDir, port);
+}

package/skills/sia-brainstorm/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: sia-brainstorm
+description: Brainstorms features using SIA's knowledge graph — surfaces past decisions, rejected alternatives, and architectural constraints before proposing approaches. Use when starting any creative work, designing features, or modifying behavior.
+---
+
+# SIA-Enhanced Brainstorming
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue, powered by SIA's knowledge graph. This improves upon standard brainstorming by starting with accumulated project knowledge instead of from scratch.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## What SIA Adds
+
+Standard brainstorming explores the codebase by reading files and recent commits. SIA-enhanced brainstorming also queries:
+- **Past decisions** in the same area — what was chosen and why
+- **Rejected alternatives** — what was tried and abandoned (bi-temporal `t_valid_until` data)
+- **Architectural constraints** — conventions and patterns that must be respected
+- **Community structure** — module boundaries and relationships
+- **Prior sessions** — what was discussed before about similar topics
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **SIA Context Retrieval** — query the knowledge graph for prior decisions, conventions, and rejected approaches
+2. **Explore project context** — check files, docs, recent commits
+3. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
+4. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+5. **Propose 2-3 approaches** — with trade-offs and your recommendation (informed by SIA graph context)
+6. **Present design** — in sections scaled to their complexity, get user approval after each section
+7. **Write design doc + capture knowledge** — save to `docs/specs/YYYY-MM-DD-<topic>-design.md`, capture decisions to SIA, commit
+8. **Spec review loop** — dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md); fix issues and re-dispatch until approved (max 3 iterations, then surface to human)
+9. **User reviews written spec** — ask user to review the spec file before proceeding
+10. **Transition to implementation** — invoke sia-plan to create implementation plan
+
+## Enhanced Workflow
+
+### Step 0 — SIA Context Retrieval (before any exploration)
+
+Before exploring files or asking questions, query the knowledge graph:
+
+```
+sia_search({ query: "<feature area description>", task_type: "feature", limit: 15 })
+sia_search({ query: "decisions conventions <feature area>", node_types: ["Decision", "Convention"], limit: 10 })
+sia_community({ query: "<feature area>", level: 1 })
+```
+
+Review the results. Key things to note:
+- **Active decisions** that constrain the design space
+- **Conventions** that must be followed
+- **Past proposals** in this area (check for invalidated entities — `t_valid_until` set — these are rejected approaches)
+- **Community structure** showing module boundaries
+
+Present a brief "Graph Context" summary to the user before asking questions:
+
+> **SIA Context:**
+> - 3 prior decisions in this area: [list]
+> - 2 conventions that apply: [list]
+> - 1 previously rejected approach: [description + why rejected]
+
+### Step 1 — Explore Project Context
+
+Check out the current project state (files, docs, recent commits). Before asking detailed questions, assess scope: if the request describes multiple independent subsystems, flag this immediately.
+
+If the project is too large for a single spec, help the user decompose into sub-projects. Each sub-project gets its own spec → plan → implementation cycle.
+
+### Step 2 — Offer Visual Companion
+
+When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer the visual companion once for consent:
+
+> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"
+
+**This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
+
+**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
+
+- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
+- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
+
+If they agree to the companion, read the detailed guide before proceeding:
+`skills/sia-brainstorm/visual-companion.md`
+
+### Step 3 — Ask Clarifying Questions
+
+- One question at a time — don't overwhelm with multiple questions
+- Prefer multiple choice when possible, but open-ended is fine too
+- Focus on understanding: purpose, constraints, success criteria
+
+### Step 4 — Propose 2-3 Approaches (ENHANCED)
+
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**SIA Enhancement:** When proposing approaches, explicitly note which prior decisions each approach aligns with or contradicts. If an approach was tried before and rejected, say so and explain what's different now.
+
+### Step 5 — Present Design
+
+- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+
+**Design for isolation and clarity:**
+- Break the system into smaller units with one clear purpose each
+- For each unit: what does it do, how do you use it, what does it depend on?
+
+### Step 6 — Write Design Doc + Capture Knowledge (ENHANCED)
+
+Write the validated design (spec) to `docs/specs/YYYY-MM-DD-<topic>-design.md` and commit.
+
+**SIA Enhancement — capture decisions to the graph:**
+
+```
+sia_note({ kind: "Decision", name: "<main design decision>", content: "<rationale, alternatives considered, what was rejected>", tags: ["design", "<feature-area>"] })
+```
+
+For each rejected alternative:
+
+```
+sia_note({ kind: "Decision", name: "Rejected: <alternative>", content: "<why rejected>", supersedes: "<old_decision_id if replacing>" })
+```
+
+### Step 7 — Spec Review Loop
+
+After writing the spec document:
+
+1. Dispatch spec-document-reviewer subagent (see `skills/sia-brainstorm/spec-document-reviewer-prompt.md`)
+2. If Issues Found: fix, re-dispatch, repeat until Approved
+3. If loop exceeds 3 iterations, surface to human for guidance
+
+### Step 8 — User Review Gate
+
+After the spec review loop passes, ask the user to review the written spec before proceeding:
+
+> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+
+Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.
+
+### Step 9 — Transition to Implementation
+
+Invoke sia-plan to create a detailed implementation plan. Do NOT invoke any other skill.
+
+## Key Principles
+
+- **Never brainstorm from zero** — always check what SIA knows first
+- **One question at a time** — don't overwhelm with multiple questions
+- **Multiple choice preferred** — easier to answer than open-ended when possible
+- **YAGNI ruthlessly** — remove unnecessary features from all designs
+- **Surface rejected approaches explicitly** — prevent repeating failed ideas
+- **Capture the design** — future brainstorming sessions will benefit from this one's output
+- **Cite graph entities** — when a prior decision constrains the design, name it