@vpxa/aikit 0.1.1

package/scaffold/general/skills/adr-skill/scripts/set_adr_status.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * Update an ADR's status in-place.
+ *
+ * Supported patterns:
+ * - Bullet status: "- Status: proposed" or "* Status: proposed"
+ * - Nygard-style section: "## Status" followed by a single-line status value
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function die(msg) {
+  process.stderr.write(`${msg}\n`);
+  process.exit(1);
+}
+
+function toPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+function parseArgs(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(
+      [
+        'Usage: node set_adr_status.js <path> --status <value> [--json]',
+        '',
+        'Example:',
+        '  node set_adr_status.js adr/2025-06-15-foo.md --status accepted',
+        '',
+      ].join('\n'),
+    );
+    process.exit(0);
+  }
+
+  if (argv.length < 3) die('Missing <path>');
+  const file = argv[2];
+
+  let status = null;
+  let json = false;
+  for (let i = 3; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--status') {
+      if (i + 1 >= argv.length) die('Missing value for --status');
+      status = argv[++i];
+    } else if (a === '--json') {
+      json = true;
+    } else {
+      die(`Unknown arg: ${a}`);
+    }
+  }
+  if (!status) die('Missing required --status');
+  return { file, status: String(status).trim(), json };
+}
+
+function setYamlFrontMatterStatus(lines, newStatus) {
+  // YAML front matter: starts with '---', ends with next '---'
+  if (lines.length < 2 || lines[0].trim() !== '---') return { lines, changed: false };
+
+  let changed = false;
+  const out = [];
+  let inFrontMatter = true;
+  let passedOpening = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (i === 0 && line.trim() === '---') {
+      passedOpening = true;
+      out.push(line);
+      continue;
+    }
+
+    if (passedOpening && inFrontMatter && line.trim() === '---') {
+      inFrontMatter = false;
+      out.push(line);
+      continue;
+    }
+
+    if (passedOpening && inFrontMatter && /^status\s*:/.test(line)) {
+      out.push(`status: ${newStatus}`);
+      changed = true;
+      continue;
+    }
+
+    out.push(line);
+  }
+
+  return { lines: out, changed };
+}
+
+function setBulletStatus(lines, newStatus) {
+  let changed = false;
+  const out = lines.map((line) => {
+    const m = line.match(/^([*-])\s*Status:\s*(.*)$/);
+    if (!m) return line;
+    changed = true;
+    return `${m[1]} Status: ${newStatus}`;
+  });
+  return { lines: out, changed };
+}
+
+function setSectionStatus(lines, newStatus) {
+  let changed = false;
+  const out = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    out.push(lines[i]);
+
+    if (!/^##\s+Status\s*$/.test(lines[i])) continue;
+
+    // Replace next non-empty, non-heading line. If not found, insert.
+    let j = i + 1;
+    while (j < lines.length && lines[j].trim() === '') {
+      out.push(lines[j]);
+      j++;
+    }
+
+    if (j < lines.length && !/^##\s+/.test(lines[j])) {
+      out.push(newStatus);
+      changed = true;
+      i = j; // skip original status line
+      continue;
+    }
+
+    out.push(newStatus);
+    changed = true;
+    i = j - 1;
+  }
+
+  return { lines: out, changed };
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  const filePath = path.resolve(process.cwd(), args.file);
+  if (!fs.existsSync(filePath)) die(`File not found: ${filePath}`);
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const hadTrailingNewline = content.endsWith('\n');
+  const lines = content.replace(/\r\n/g, '\n').split('\n');
+
+  let r = setYamlFrontMatterStatus(lines, args.status);
+  if (!r.changed) r = setBulletStatus(lines, args.status);
+  if (!r.changed) r = setSectionStatus(lines, args.status);
+  if (!r.changed) {
+    die(
+      "Could not find a status to update. Expected YAML front matter 'status:', '- Status:'/'* Status:', or a '## Status' section.",
+    );
+  }
+
+  const newContent = r.lines.join('\n') + (hadTrailingNewline ? '\n' : '');
+  fs.writeFileSync(filePath, newContent, 'utf8');
+
+  if (args.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        filePath,
+        fileRelPath: toPosix(path.relative(process.cwd(), filePath)),
+        status: args.status,
+        changed: true,
+      })}\n`,
+    );
+  } else {
+    process.stdout.write(`${filePath}\n`);
+  }
+}
+
+main();

package/scaffold/general/skills/aikit/SKILL.md

@@ -0,0 +1,521 @@
+---
+name: aikit
+description: "Use the @vpxa/aikit Knowledge Base MCP server for codebase search, analysis, and persistent memory. Load this skill when using aikit_search, aikit_remember, aikit_analyze_*, or any aikit_* tool. Covers all 67 MCP tools: search (hybrid/semantic/keyword), code analysis (structure, dependencies, symbols, patterns, entry points, diagrams, blast radius), knowledge graph (auto-populated module/symbol/import graph with traversal), context management (worksets, stash, checkpoints, restore, lanes), code manipulation (rename, codemod, eval), knowledge management (remember/read/update/forget), web access (fetch, search, http), FORGE protocol (ground, classify, evidence map, stratum cards, digest), brainstorming (interactive ideation sessions), presentation (rich dashboards via present tool), onboarding (full codebase analysis in one call), and developer utilities (regex, encode, measure, changelog, schema-validate, snippet, env, time)."
+---
+
+# @vpxa/aikit — Knowledge Base Toolkit
+
+Local-first AI developer toolkit — 67 MCP tools for search, analysis, context compression, FORGE quality gates, knowledge management, code manipulation, execution, web access, brainstorming, presentation, and developer utilities.
+
+## When to Use
+
+- You need long-term memory across coding sessions
+- You want to search a codebase semantically (by meaning, not just keywords)
+- You need to compress large contexts to focus on what matters
+- You want structured output from build tools (tsc, vitest, biome, git)
+- You need to plan which files to read for a task
+- You want to safely explore refactors in isolated lanes
+- You need to rename symbols, apply codemods, or run code transformations
+- You want to fetch and read web pages or search the web
+- You need to make HTTP requests, test APIs, or debug endpoints
+- You want to test regex patterns, encode/decode data, or validate JSON schemas
+- You need code complexity metrics or a git changelog
+- You want to save and reuse code snippets across sessions
+
+## Architecture
+
+10-package monorepo published as a single npm package:
+
+```
+core → store → embeddings → chunker → indexer → analyzers → tools → server → cli → tui
+```
+
+- **MCP server**: 67 tools + 2 resources (via `@modelcontextprotocol/sdk`)
+- **CLI**: 45 commands (thin dispatcher + 10 command groups)
+- **Search**: Hybrid vector + keyword + RRF fusion
+- **Embeddings**: ONNX local (mxbai-embed-large-v1, 1024 dimensions)
+- **Vector store**: LanceDB (embedded, zero infrastructure)
+- **Chunking**: Tree-sitter AST (TS/JS/Python/Go/Rust/Java) + regex fallback
+- **TUI**: Ink/React dashboard for human monitoring (search, status, curated, activity log)
+
+## Session Protocol (MANDATORY)
+
+### Start of Session
+```
+status()
+search({ query: "SESSION CHECKPOINT", origin: "curated" })
+list({ category: "conventions" })
+```
+
+### During Session
+```
+search → scope_map → symbol → trace  (orient)
+check → test_run                             (validate changes)
+remember                                         (capture insights)
+```
+
+### End of Session
+```
+remember({ title: "Session checkpoint: <topic>", content: "<what was done, decisions made, next steps>", category: "conventions" })
+```
+
+## Tool Catalog (67 tools)
+
+### Search & Discovery (8)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `search` | `aikit search` | Hybrid/semantic/keyword search with `search_mode` param |
+| `find` | `aikit find` | Federated search: vector + FTS + glob + regex in one call. Use `mode: 'examples'` to find usage examples. |
+| `symbol` | `aikit symbol` | Resolve symbol definition, imports, and references |
+| `lookup` | `aikit lookup` | Full-file retrieval by path or record ID |
+| `scope_map` | `aikit scope-map` | Task-scoped reading plan with token estimates |
+| `trace` | `aikit trace` | Forward/backward flow tracing through call chains |
+| `dead_symbols` | `aikit dead-symbols` | Find exported symbols never imported — separates source (actionable) from docs (informational). Accepts `path` to scope the search. |
+| `file_summary` | `aikit summarize` | Structural overview of a file (exports, imports, functions) |
+
+### Code Analysis (7)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `analyze_structure` | `aikit analyze structure` | Project structure overview |
+| `analyze_dependencies` | `aikit analyze deps` | Dependency graph with confidence |
+| `analyze_symbols` | `aikit analyze symbols` | Symbol extraction and cross-references |
+| `analyze_patterns` | `aikit analyze patterns` | Design pattern detection |
+| `analyze_entry_points` | `aikit analyze entry-points` | Find entry points: handlers, CDK constructs, test suites, package exports (walks workspace packages) |
+| `analyze_diagram` | `aikit analyze diagram` | Generate Mermaid diagrams |
+| `blast_radius` | `aikit analyze blast-radius` | Change impact analysis |
+
+### Context Management (6)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `compact` | `aikit compact` | Compress text to relevant sections using embeddings (no LLM). Accepts `path` for server-side file read. |
+| `workset` | `aikit workset` | Named file set management (save/load/add/remove) |
+| `stash` | `aikit stash` | Named key-value store for session data |
+| `checkpoint` | `aikit checkpoint` | Save/restore session checkpoints |
+| `restore` | `aikit restore` | Restore a previously saved checkpoint |
+| `parse_output` | `aikit parse-output` | Parse tsc/vitest/biome/git output → structured JSON |
+
+### Code Manipulation (4)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `rename` | `aikit rename` | Smart whole-word symbol rename across files (dry-run supported) |
+| `codemod` | `aikit codemod` | Regex-based code transformations with rules (dry-run supported) |
+| `diff_parse` | `aikit diff` | Parse unified diff → structured changes |
+| `data_transform` | `aikit transform` | JQ-like JSON transformations |
+
+### Execution & Validation (5)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `eval` | `aikit eval` | Sandboxed JavaScript/TypeScript execution |
+| `check` | `aikit check` | Incremental typecheck + lint. `detail` param: summary (default, ~300 tokens), errors, full |
+| `test_run` | `aikit test` | Run tests with structured pass/fail results |
+| `batch` | `aikit batch` | Execute multiple operations in parallel |
+| `audit` | `aikit audit` | Unified project audit: structure, deps, patterns, health, dead symbols, check, entry points → synthesized report with score and recommendations. 6 round-trips → 1. |
+
+### Knowledge Management (6)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `remember` | `aikit remember` | Store a curated knowledge entry |
+| `update` | `aikit update` | Update an existing entry |
+| `forget` | `aikit forget` | Delete an entry (requires reason) |
+| `read` | `aikit read` | Read a curated entry by path |
+| `list` | `aikit list` | List curated entries |
+| `produce_knowledge` | — | Auto-generate knowledge from analysis |
+
+### Verified Lanes (1 tool, 6 actions)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `lane` | `aikit lane` | Manage isolated file copies for parallel exploration |
+
+Lane actions: `create` (copy files to lane), `list`, `status` (modified/added/deleted), `diff` (line-level diff), `merge` (apply back to originals), `discard`.
+
+### Git & Environment (4)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `git_context` | `aikit git` | Branch, status, recent commits |
+| `process` | `aikit proc` | Process supervisor (start/stop/logs) |
+| `watch` | `aikit watch` | Filesystem watcher |
+| `delegate` | `aikit delegate` | Delegate subtask to local Ollama model |
+
+### Web & Network (3)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `web_fetch` | — | Fetch web page → markdown/raw/links/outline for LLM consumption |
+| `web_search` | — | Search the web via DuckDuckGo (no API key needed) |
+| `http` | — | Make HTTP requests for API testing/debugging |
+
+### Developer Utilities (8)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `regex_test` | — | Test regex patterns with match/replace/split modes |
+| `encode` | — | Base64, URL, SHA-256, MD5, hex encode/decode, JWT decode |
+| `measure` | — | Code complexity metrics (cyclomatic, cognitive complexity, lines, functions) |
+| `changelog` | — | Generate changelog from git history (conventional commits) |
+| `schema_validate` | — | Validate JSON data against JSON Schema |
+| `snippet` | — | Save/get/search/delete persistent code snippets |
+| `env` | — | System and runtime environment info (sensitive values redacted) |
+| `time` | — | Date parsing, timezone conversion, duration math |
+
+### FORGE Quality Gates (5)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `forge_ground` | — | Full Ground phase: classify tier, scope map, unknowns, constraints |
+| `forge_classify` | — | Quick tier classification (Floor/Standard/Critical) |
+| `evidence_map` | — | CRUD + Gate evaluation for verified/assumed/unknown claims. Safety gate tags (`provenance`/`commitment`/`coverage`) enable mandatory pre-YIELD checks |
+| `stratum_card` | — | Generate T1/T2 compressed context cards from files (10-100x token reduction) |
+| `digest` | — | Compress N text sources into token-budgeted summary |
+
+### System (8)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `status` | `aikit status` | Index statistics |
+| `reindex` | `aikit reindex` | Rebuild index |
+| `health` | `aikit health` | Project health checks (package.json, tsconfig, lockfile, circular deps) |
+| `guide` | `aikit guide` | Tool discovery — given a goal, recommends tools and workflow order |
+| `onboard` | `aikit onboard` | Full codebase onboarding in one call (structure + deps + patterns + knowledge) |
+| `graph` | `aikit graph` | Query the auto-populated knowledge graph (modules, symbols, imports) |
+| `queue` | `aikit queue` | Task queue for sequential agent operations (create/push/next/done/fail) |
+| `replay` | `aikit replay` | View or clear the audit trail of tool invocations (action: list/clear) |
+
+### Presentation (1)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `present` | — | Rich dashboards, charts, tables, timelines. Use `format: "browser"` then `openBrowserPage` to display |
+
+### Brainstorming (1)
+| Tool | CLI | Purpose |
+|------|-----|---------|
+| `brainstorm` | — | Interactive brainstorming and ideation sessions with structured output |
+
+## Search Strategy
+
+## CRITICAL: Use KB Tools Instead of Native IDE Tools
+
+KB tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **Always prefer KB tools.**
+
+### Tool Replacement Table
+
+| Instead of... | Use KB Tool | Why |
+|---------------|-------------|-----|
+| `read_file` (full file) | `file_summary` | Exports, imports, call edges — **10x fewer tokens** |
+| `read_file` (specific section) | `compact({ path, query })` | Server-side read + extract — **5-20x reduction** |
+| `grep_search` / `textSearch` | `search` | Semantic + keyword hybrid across all indexed content |
+| `grep_search` for a symbol | `symbol` | Definition + references **with scope context** |
+| Multiple `read_file` calls | `digest` | Compresses multiple sources into token-budgeted summary |
+| `listDirectory` + `read_file` | `scope_map` | Identifies relevant files for a task automatically |
+| Manual code tracing | `trace` | AST call-graph traversal with scope context |
+| Line counting / `wc` | `measure` | Lines, complexity, **cognitive complexity**, functions |
+| Grep for unused exports | `dead_symbols` | AST-powered export detection with regex fallback |
+| Repeated file reads | `stratum_card` | Reusable compressed context — **10-100x reduction** |
+| `fetch_webpage` | `web_fetch` | Readability extract + token budget — richer output |
+| Web research / browsing | `web_search` | Structured web results without browser — **unique to KB** |
+
+### Decision Tree — How to Read Code
+
+```
+Need to understand a file?
+├─ Just structure? → file_summary (exports, imports, call edges — ~50 tokens)
+├─ Specific section? → compact({ path: "file.ts", query: "topic" }) — 5-20x reduction
+├─ Multiple files? → digest (multi-source compression — token-budgeted)
+├─ Repeated reference? → stratum_card (T1/T2 card — 10-100x reduction)
+└─ Full file needed? → ONLY as last resort, and compact it after reading
+```
+
+### What KB Tools Return (AST-Enhanced)
+
+These tools use Tree-sitter WASM to analyze source code at the AST level, providing structured data that raw file reads cannot:
+
+| Tool | Rich Output |
+|------|-------------|
+| `file_summary` | Imports classified as **external vs internal** (`isExternal` flag). **Call edges** between functions (e.g., `handleRequest() → validateInput() @ line 42`). `exported` flag on interfaces and types. Import count breakdown. |
+| `symbol` | References include **scope** — which function/class/method contains each usage (e.g., `referenced in processOrder() at auth-service.ts:55`). |
+| `trace` | **Call-graph edges** discovered via AST syntax tree, not text matching. Supports forward (who does X call?) and backward (who calls X?) tracing. Scope context on each node. |
+| `measure` | **Cognitive complexity** — weights nesting depth (nested `if` inside `for` inside `try` scores higher). More useful than cyclomatic complexity for understanding code difficulty. |
+| `dead_symbols` | **AST export enumeration** — catches `export default`, barrel re-exports (`export { x } from`), `export =`, and `export type`. Regex fallback for non-AST-supported languages. |
+
+### Example: `file_summary` Output
+
+```
+src/auth-service.ts
+Language: typescript | Lines: 180 | Estimated tokens: ~1400
+
+Imports (6): 3 external, 3 internal
+  - import { hash } from 'bcrypt'          [external]
+  - import { UserRepo } from './user-repo' [internal]
+
+Functions (4):
+  - authenticate @ line 22 [exported]
+  - validateToken @ line 55 [exported]
+  - hashPassword @ line 90
+  - generateJwt @ line 110
+
+Call edges (12 intra-file):
+  - authenticate() → hashPassword() @ line 35
+  - authenticate() → generateJwt() @ line 42
+  - validateToken() → UserRepo.findById() @ line 68
+
+Interfaces (2):
+  - AuthResult @ line 8 [exported]
+  - TokenPayload @ line 14
+```
+
+Compare: `read_file` would cost ~1400 tokens for raw text. `file_summary` gives structured data in ~120 tokens — **12x reduction** with richer information.
+
+## Search Strategy
+
+1. **Start broad**: `search({ query: "topic", search_mode: "hybrid" })`
+2. **Narrow**: Add `content_type`, `origin`, or `category` filters
+3. **Exact match**: Use `search_mode: "keyword"` for identifiers
+4. **Federated**: Use `find` to combine vector + glob + regex
+
+## Workflow Chains
+
+### Codebase Onboarding
+```
+analyze_structure({ path: "src/" })
+→ analyze_dependencies({ path: "src/" })
+→ analyze_entry_points({ path: "src/" })
+→ produce_knowledge({ path: "src/" })
+→ remember({ title: "Codebase onboarding complete", ... })
+```
+
+### Planning a Task
+```
+scope_map({ task: "implement user auth" })
+→ compact({ path: "src/auth.ts", query: "auth flow" })
+→ workset({ action: "save", name: "auth-task", files: [...] })
+```
+
+### Bug Investigation
+```
+parse_output({ output: <error> }) → symbol({ name: "failingFn" })
+→ trace({ symbol: "failingFn", direction: "backward" })
+→ blast_radius({ changed_files: ["suspect.ts"] })
+→ eval({ code: "hypothesis test" }) → check({ files: ["suspect.ts"] })
+```
+
+### Safe Refactor with Lanes
+```
+scope_map({ task: "rename UserService" })
+→ lane({ action: "create", name: "refactor", files: [...] })
+→ [make changes in lane files]
+→ lane({ action: "diff", name: "refactor" })
+→ check({}) → test_run({})
+→ lane({ action: "merge", name: "refactor" })
+```
+
+### After Making Changes
+```
+blast_radius({ changed_files: ["src/auth.ts"] })
+→ check({}) → test_run({ grep: "auth" })
+→ reindex()
+→ remember({ title: "Implemented auth", content: "..." })
+```
+
+### Pre-Commit Validation
+```
+git_context({ diff: true })
+→ diff_parse({ diff: <staged diff> })
+→ blast_radius({ changed_files: [...] })
+→ check({}) → test_run({})
+```
+
+## CLI Quick Reference
+
+```bash
+aikit init              # Scaffold KB in current directory
+aikit init --force      # Overwrite all scaffold/skill files
+aikit init --guide      # JSON report of stale files for LLM-driven updates
+aikit serve             # Start MCP server (stdio or HTTP)
+aikit search <q>    # Hybrid search
+aikit find <q>      # Federated search
+aikit symbol <name> # Resolve symbol
+aikit scope-map <t> # Task reading plan
+aikit compact <q>   # Context compression (--path file or stdin)
+aikit check         # Typecheck + lint (--detail summary|errors|full)
+aikit test          # Run tests
+aikit rename <old> <new> <path>  # Rename symbol
+aikit lane create <name> --files f1,f2  # Create lane
+aikit lane diff <name>  # View lane changes
+aikit lane merge <name> # Merge lane back
+aikit status        # Index stats
+aikit reindex       # Rebuild index
+```
+
+## Configuration
+
+`kb.config.json` in project root:
+```json
+{
+  "sources": [{ "path": ".", "excludePatterns": ["node_modules/**", "**/node_modules/**", "dist/**", "coverage/**", ".aikit-data/**"] }],
+  "indexing": { "chunkSize": 1500, "chunkOverlap": 200, "minChunkSize": 100, "concurrency": 5 },
+  "embedding": { "model": "mixedbread-ai/mxbai-embed-large-v1", "dimensions": 1024 },
+  "store": { "backend": "lancedb", "path": ".aikit-data" },
+  "curated": { "path": "curated" }
+}
+```
+
+## IDE Integration
+
+### VS Code — HTTP mode (recommended for development)
+```json
+// .vscode/mcp.json
+{
+  "servers": {
+    "kb": {
+      "type": "http",
+      "url": "http://localhost:3210/mcp"
+    }
+  }
+}
+```
+Start server: `npx aikit serve --http --port 3210`
+
+### VS Code — stdio mode (no separate server)
+```json
+{
+  "servers": {
+    "kb": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@vpxa/aikit", "serve", "--stdio"]
+    }
+  }
+}
+```
+
+### Claude Code (`.mcp.json`)
+```json
+{
+  "mcpServers": {
+    "kb": {
+      "command": "npx",
+      "args": ["@vpxa/aikit", "serve"]
+    }
+  }
+}
+```
+
+## Development (Self-Dogfooding)
+
+When developing @vpxa/aikit itself, use the tool on its own codebase:
+
+```bash
+# Build → Reindex → Use loop
+pnpm build                          # Build all 10 packages
+node bin/aikit.mjs reindex          # Index own source into LanceDB
+node bin/aikit.mjs search "query"   # Search own code
+node bin/aikit.mjs symbol "FnName"  # Resolve symbols in own code
+node bin/aikit.mjs check            # Typecheck + lint
+pnpm test                           # Run 287+ tests
+
+# Start MCP server for agent use during development
+node bin/aikit.mjs serve --http --port 3210
+```
+
+**Rules:**
+- Always `pnpm build` before using CLI/server (runs from `dist/`)
+- Always `reindex` after structural code changes
+- LanceDB is single-process — don't run CLI and HTTP server simultaneously
+- Curated entries in `curated/` survive reindex and are indexed separately
+
+---
+
+## Flow System
+
+Flows are **pluggable, multi-step development workflows** that orchestrate agents through structured phases. Each flow is a directory containing a manifest (`flow.json`) and step skills (`skills/<step>/SKILL.md`).
+
+### Architecture
+
+```
+Flow Layer      — Pluggable workflows (git repos, local dirs, built-in)
+Foundation Layer — Agents, MCP tools, skills (what you already have)
+Base Layer      — aikit MCP server, CLI, index engine
+```
+
+Flows compose Foundation Layer components (agents + skills + tools) into repeatable processes. They do NOT replace the foundation — they orchestrate it.
+
+### Built-in Flows
+
+| Flow | Steps | Use When |
+|------|-------|----------|
+| `aikit:basic` | assess → implement → verify | Bug fixes, small features, refactoring |
+| `aikit:advanced` | spec → plan → task → execute → verify | New features, API design, architecture changes |
+
+### Flow Manifest (`flow.json`)
+
+```json
+{
+  "name": "aikit:basic",
+  "version": "0.1.0",
+  "description": "Quick development flow",
+  "steps": [
+    {
+      "id": "assess",
+      "name": "Assessment",
+      "skill": "skills/assess/SKILL.md",
+      "produces": ["assessment.md"],
+      "requires": [],
+      "agents": ["Explorer", "Researcher-Alpha"],
+      "description": "Understand scope, analyze codebase"
+    }
+  ],
+  "artifacts_dir": ".spec",
+  "install": []
+}
+```
+
+**Key fields:**
+- `artifacts_dir` — root folder for all flow artifacts (default: `.spec`). Each step writes to a work subfolder: `.spec/<step-slug>/`
+- `install` — external skills needed by this flow. Empty for built-ins. For custom flows: `[{ "name": "my-skill", "repo": "org/repo", "agent": "copilot" }]`
+- `steps[].produces` / `steps[].requires` — declare artifact dependencies between steps. A step can only start when all its `requires` artifacts exist.
+
+### CLI Commands
+
+| Command | Purpose |
+|---------|---------|
+| `aikit flow add <source>` | Install flow from git URL, local path, or built-in name |
+| `aikit flow remove <name>` | Remove an installed flow |
+| `aikit flow list` | List installed flows |
+| `aikit flow use <name>` | Set active flow for current project |
+| `aikit flow status` | Show current step, artifacts, progress |
+| `aikit flow start [step]` | Begin flow (or resume from step) |
+| `aikit flow reset` | Reset flow state to beginning |
+
+### State Machine
+
+Flow progress is tracked in `.spec/flow-state.json`:
+
+```json
+{
+  "flow": "aikit:basic",
+  "current_step": "implement",
+  "steps": {
+    "assess": { "status": "completed", "artifacts": ["assessment.md"] },
+    "implement": { "status": "in_progress", "artifacts": [] },
+    "verify": { "status": "pending", "artifacts": [] }
+  }
+}
+```
+
+Step transitions: `pending` → `in_progress` → `completed` (or `failed` → retry). A step can only start when all its `requires` artifacts exist.
+
+### Flow Sources
+
+Flows can be installed from three sources:
+
+1. **Built-in** — Ship with aikit (`aikit:basic`, `aikit:advanced`)
+2. **Git** — `aikit flow add https://github.com/org/my-flow.git`
+3. **Local** — `aikit flow add ./my-custom-flow`
+
+### Creating Custom Flows
+
+```
+my-flow/
+  flow.json          # Manifest with steps, agents, dependencies
+  skills/
+    step-one/SKILL.md
+    step-two/SKILL.md
+  README.md           # Optional documentation
+```
+
+Each step skill follows standard SKILL.md format with sections: Purpose, Inputs, Process, Outputs, Agents, Completion Criteria. Steps produce artifacts into `.spec/` that downstream steps consume.