@shipfast-ai/shipfast 0.6.1 → 1.0.2

package/commands/sf/plan.md

@@ -0,0 +1,106 @@
+---
+name: sf:plan
+description: "Research and plan a phase. Scout gathers findings, Architect creates task list. Stores tasks in brain.db."
+argument-hint: "<describe what to build>"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<objective>
+Dedicated planning command. Produces a precise task list stored in brain.db.
+Does NOT execute — that's /sf-do's job.
+
+Separation matters: planning uses different context than execution.
+Fresh context for each phase = no degradation.
+</objective>
+
+<process>
+
+## Step 1: Analyze
+
+Classify intent and complexity (same as /sf-do Step 1):
+- fix/feature/refactor/test/ship/perf/security/style/data/remove
+- trivial/medium/complex
+
+If trivial: skip planning. Tell user to run `/sf-do` directly.
+
+## Step 2: Scout (fresh agent)
+
+Launch sf-scout agent to research the task:
+- Provide: task description + brain.db context (decisions, learnings, hot files)
+- Scout returns: files, functions, consumers, conventions, risks, recommendation
+- Scout tags findings with confidence: [VERIFIED], [CITED], [ASSUMED]
+
+**Scout runs in its own agent = fresh context, no pollution.**
+
+Wait for Scout to complete before proceeding.
+
+## Step 3: Discuss (if complex or ambiguous)
+
+Check for ambiguity (rule-based, zero tokens):
+- WHERE: no file paths mentioned
+- WHAT: no behavior described
+- HOW: multiple approaches possible
+- RISK: touches auth/payment/data
+- SCOPE: >30 words with conjunctions
+
+If ambiguous: ask 2-5 targeted questions. Store answers as locked decisions in brain.db:
+```bash
+sqlite3 .shipfast/brain.db "INSERT INTO decisions (question, decision, reasoning, phase) VALUES ('[Q]', '[A]', '[why]', '[phase]');"
+```
+
+## Step 4: Architect (fresh agent)
+
+Launch sf-architect agent to create task list:
+- Provide: task description + Scout findings + locked decisions from brain.db
+- Architect returns: must-haves (truths/artifacts/links) + ordered task list
+
+**Architect runs in its own agent = fresh context, no pollution.**
+
+Architect's output must include for EACH task:
+- Exact file paths
+- Consumer list (who uses what's being changed)
+- Specific action instructions
+- Verify command
+- Measurable done criteria
+
+## Step 5: Store tasks in brain.db
+
+For each task from Architect, store in brain.db:
+```bash
+sqlite3 .shipfast/brain.db "INSERT INTO tasks (id, phase, description, plan_text, status) VALUES ('[id]', '[phase]', '[description]', '[full task details]', 'pending');"
+```
+
+Also store must-haves:
+```bash
+sqlite3 .shipfast/brain.db "INSERT OR REPLACE INTO context (id, scope, key, value, version, updated_at) VALUES ('phase:[name]:must_haves', 'phase', 'must_haves:[name]', '[JSON must-haves]', 1, strftime('%s', 'now'));"
+```
+
+## Step 6: Report
+
+```
+Plan ready: [N] tasks stored in brain.db
+
+Must-haves:
+  Truths: [list]
+  Artifacts: [list]
+  Key links: [list]
+
+Tasks:
+  1. [description] — [files] — [size]
+  2. [description] — [files] — [size]
+  ...
+
+Run /sf-do to execute. Tasks will run with fresh context per task.
+```
+
+</process>
+
+<context>
+$ARGUMENTS
+</context>

package/commands/sf/project.md

@@ -30,6 +30,22 @@ Read the user's project description. If brain.db exists, load:
 
 If the project description is ambiguous, run the ambiguity detection from /sf-discuss first.
 
+## Step 1.5: Parallel Domain Research (for new/complex projects)
+
+If the project involves unfamiliar technology or external integrations, launch **up to 4 Scout agents in parallel** to research:
+
+1. **Stack Scout** — What's the standard stack for this domain? Libraries, versions, frameworks.
+2. **Architecture Scout** — How are similar systems typically structured? Patterns, tiers, boundaries.
+3. **Pitfalls Scout** — What do projects like this commonly get wrong? Gotchas, anti-patterns.
+4. **Integration Scout** — What external services/APIs are needed? Auth, webhooks, SDKs.
+
+Each Scout runs in its own context. Findings are stored in brain.db:
+```bash
+sqlite3 .shipfast/brain.db "INSERT OR REPLACE INTO context (id, scope, key, value, version, updated_at) VALUES ('project:research:[topic]', 'project', 'research:[topic]', '[findings JSON]', 1, strftime('%s', 'now'));"
+```
+
+Skip this step for simple projects or projects where brain.db already has relevant decisions.
+
 ### Multi-Repo Detection
 Check if the workspace contains multiple git repositories (submodules, monorepo packages):
 ```bash

package/commands/sf/verify.md

@@ -0,0 +1,140 @@
+---
+name: sf:verify
+description: "Verify completed work against must-haves. Checks artifacts, data flow, stubs, build, consumers."
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Dedicated verification command. Runs AFTER /sf-do completes.
+Checks the codebase delivers what was planned — not just "tests pass".
+
+Separation matters: verification needs fresh context to see the code objectively,
+without the biases accumulated during execution.
+</objective>
+
+<process>
+
+## Step 1: Load must-haves from brain.db
+
+```bash
+sqlite3 -json .shipfast/brain.db "SELECT value FROM context WHERE key LIKE 'must_haves:%' ORDER BY updated_at DESC LIMIT 1;" 2>/dev/null
+```
+
+If no must-haves stored, extract from the task descriptions:
+```bash
+sqlite3 -json .shipfast/brain.db "SELECT description FROM tasks WHERE status = 'passed' ORDER BY created_at;" 2>/dev/null
+```
+
+## Step 2: Check observable truths
+
+For each truth in must-haves, verify:
+- Does the code actually implement this?
+- Grep for the function/component/route that delivers it
+- Is it wired (imported and used), not just existing?
+
+Score: VERIFIED / FAILED / NEEDS_HUMAN
+
+## Step 3: 3-Level artifact validation
+
+For each artifact in must-haves:
+
+**Level 1 — Exists**: `[ -f path ] && echo OK || echo MISSING`
+**Level 2 — Substantive**: File has >3 non-comment lines (not empty/stub)
+**Level 3 — Wired**: `grep -r "basename" --include="*.ts" .` shows imports from other files
+
+Score per artifact: L1/L2/L3 or MISSING
+
+## Step 4: Data flow check
+
+For new components/APIs, check they receive real data:
+- Not hardcoded empty arrays: `grep "data: \[\]" [file]`
+- Not returning null: `grep "return null" [file]`
+- Not empty handlers: `grep "() => {}" [file]`
+- Fetch calls have response handling
+
+## Step 5: Stub detection (deep)
+
+Scan all files changed in this session:
+```bash
+git diff --name-only HEAD~[N commits]
+```
+
+Check each for:
+- TODO, FIXME, HACK, "not implemented", "placeholder"
+- Empty click/submit handlers
+- console.log debug statements
+- debugger statements
+- Commented-out code blocks
+
+## Step 6: Build verification
+
+```bash
+npm run build 2>&1 | tail -5
+# or: tsc --noEmit
+# or: cargo check
+```
+
+## Step 7: Consumer integrity
+
+For every function/type/export that was modified or removed:
+```bash
+grep -r "removed_function_name" --include="*.ts" --include="*.tsx" .
+```
+Any remaining consumers = CRITICAL failure.
+
+## Step 8: Score and report
+
+```
+Verification Results
+====================
+
+Truths: [N]/[M] verified
+Artifacts: [N]/[M] at Level 3 (wired)
+Data flow: [PASS/ISSUES]
+Stubs: [N] found
+Build: [PASS/FAIL]
+Consumers: [CLEAN/BROKEN]
+
+Verdict: PASS | PASS_WITH_WARNINGS | FAIL
+
+[If FAIL:]
+Failed items:
+  - [truth/artifact]: [what's wrong]
+  - [truth/artifact]: [what's wrong]
+
+Fix with: /sf-do [fix description]
+```
+
+## Step 9: Store results
+
+```bash
+sqlite3 .shipfast/brain.db "INSERT OR REPLACE INTO context (id, scope, key, value, version, updated_at) VALUES ('verify:latest', 'session', 'verification', '[JSON results]', 1, strftime('%s', 'now'));"
+```
+
+## Step 10: Interactive UAT (if complex)
+
+For complex features, offer manual testing:
+```
+Manual checks (answer pass/issue/skip):
+
+Test 1: [what to test]
+  Expected: [behavior]
+  Result?
+
+Test 2: [what to test]
+  Expected: [behavior]
+  Result?
+```
+
+For each issue reported, generate a fix task and store in brain.db.
+
+</process>
+
+<context>
+$ARGUMENTS
+</context>

package/commands/sf/workstream.md

@@ -0,0 +1,51 @@
+---
+name: sf:workstream
+description: "Manage parallel workstreams — create, list, switch, complete."
+argument-hint: "list | create <name> | switch <name> | complete <name>"
+allowed-tools:
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Workstreams let you work on multiple features in parallel, each with its own branch and task tracking.
+Each workstream gets a namespaced set of tasks in brain.db.
+</objective>
+
+<process>
+
+## Parse subcommand from $ARGUMENTS
+
+### list
+```bash
+sqlite3 -json .shipfast/brain.db "SELECT key, value FROM context WHERE scope = 'workstream' ORDER BY updated_at DESC;" 2>/dev/null
+git branch --list "sf/*" 2>/dev/null
+```
+Show all workstreams with status (active/complete) and branch name.
+
+### create <name>
+1. Create git branch: `git checkout -b sf/[name]`
+2. Store in brain.db:
+```bash
+sqlite3 .shipfast/brain.db "INSERT OR REPLACE INTO context (id, scope, key, value, version, updated_at) VALUES ('workstream:[name]', 'workstream', '[name]', '{\"status\":\"active\",\"branch\":\"sf/[name]\",\"created\":\"[timestamp]\"}', 1, strftime('%s', 'now'));"
+```
+3. Report: `Workstream [name] created on branch sf/[name]`
+
+### switch <name>
+1. `git checkout sf/[name]`
+2. Report: `Switched to workstream [name]`
+
+### complete <name>
+1. Ask: "Merge sf/[name] into current branch? [y/n]"
+2. If yes: `git merge sf/[name]` then `git branch -d sf/[name]`
+3. Update brain.db:
+```bash
+sqlite3 .shipfast/brain.db "UPDATE context SET value = replace(value, 'active', 'complete') WHERE id = 'workstream:[name]';"
+```
+4. Report: `Workstream [name] completed and merged.`
+
+</process>
+
+<context>
+$ARGUMENTS
+</context>

package/core/architecture.cjs

@@ -0,0 +1,272 @@
+/**
+ * ShipFast Architecture Layer Computation
+ *
+ * Derives architecture layers purely from the import graph + directory structure.
+ * ZERO hardcoded patterns — works with any project, any language, any structure.
+ *
+ * How it works:
+ *   1. Build import graph from brain.db edges
+ *   2. Compute layer from graph depth (L0 = nothing imports it, LN = imports nothing)
+ *   3. Index directory tree as folders with aggregated stats
+ *   4. Detect folder roles from content (most exports = util, most imports = entry)
+ */
+
+'use strict';
+
+const { execFileSync: safeRun } = require('child_process');
+const path = require('path');
+const brain = require('../brain/index.cjs');
+
+// ============================================================
+// Ensure architecture table exists
+// ============================================================
+
+function ensureTable(cwd) {
+  const dbPath = brain.getBrainPath(cwd);
+  safeRun('sqlite3', [dbPath], {
+    input: [
+      "DROP TABLE IF EXISTS architecture;",
+      "DROP TABLE IF EXISTS folders;",
+      "CREATE TABLE IF NOT EXISTS architecture (file_path TEXT PRIMARY KEY, layer INTEGER NOT NULL, folder TEXT, imports_count INTEGER DEFAULT 0, imported_by_count INTEGER DEFAULT 0, updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')));",
+      "CREATE TABLE IF NOT EXISTS folders (folder_path TEXT PRIMARY KEY, file_count INTEGER DEFAULT 0, total_imports INTEGER DEFAULT 0, total_imported_by INTEGER DEFAULT 0, avg_layer REAL, role TEXT, updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')));",
+      "CREATE INDEX IF NOT EXISTS idx_arch_layer ON architecture(layer);",
+      "CREATE INDEX IF NOT EXISTS idx_arch_folder ON architecture(folder);",
+      "CREATE INDEX IF NOT EXISTS idx_folders_role ON folders(role);",
+    ].join('\n'),
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+}
+
+// ============================================================
+// Compute layers from import graph (zero hardcoding)
+// ============================================================
+
+function computeArchitecture(cwd) {
+  if (!brain.brainExists(cwd)) return { computed: 0 };
+
+  ensureTable(cwd);
+
+  // Get all file nodes
+  const files = brain.query(cwd, "SELECT file_path FROM nodes WHERE kind = 'file'");
+  if (!files.length) return { computed: 0 };
+
+  // Get all import edges
+  const edges = brain.query(cwd, "SELECT source, target FROM edges WHERE kind = 'imports'");
+
+  // Build adjacency maps
+  const outbound = {}; // file → what it imports
+  const inbound = {};  // file → who imports it
+  const allFiles = new Set();
+
+  for (const { file_path } of files) {
+    allFiles.add(file_path);
+    outbound[file_path] = [];
+    inbound[file_path] = [];
+  }
+
+  // Build basename→filepath lookup for fuzzy matching unresolved imports
+  const basenameMap = {};
+  for (const f of allFiles) {
+    const base = f.split('/').pop().replace(/\.(ts|tsx|js|jsx|mjs|cjs|rs|py)$/, '');
+    if (!basenameMap[base]) basenameMap[base] = [];
+    basenameMap[base].push(f);
+  }
+
+  function resolveTarget(src, tgt) {
+    // Direct match
+    if (allFiles.has(tgt)) return tgt;
+    // Try with common extensions
+    for (const ext of ['.ts', '.tsx', '.js', '.jsx', '/index.ts', '/index.tsx', '/index.js']) {
+      if (allFiles.has(tgt + ext)) return tgt + ext;
+    }
+    // Fuzzy: match basename in same project
+    const base = tgt.split('/').pop().replace(/\.(ts|tsx|js|jsx)$/, '');
+    const srcProject = src.split('/')[0]; // e.g., 'desktop-app'
+    const candidates = (basenameMap[base] || []).filter(f => f.startsWith(srcProject));
+    if (candidates.length === 1) return candidates[0];
+    return null;
+  }
+
+  for (const edge of edges) {
+    const src = edge.source.replace('file:', '');
+    const tgt = edge.target.replace('file:', '');
+    const resolved = resolveTarget(src, tgt);
+    if (allFiles.has(src) && resolved) {
+      outbound[src].push(resolved);
+      inbound[resolved].push(src);
+    }
+  }
+
+  // Compute layer: BFS from entry points (files with zero importers)
+  const layers = {};
+  const entryPoints = [...allFiles].filter(f => inbound[f].length === 0);
+
+  // BFS to assign depth from entry points
+  const queue = entryPoints.map(f => ({ file: f, depth: 0 }));
+  const visited = new Set();
+
+  while (queue.length > 0) {
+    const { file, depth } = queue.shift();
+    if (visited.has(file)) continue;
+    visited.add(file);
+    layers[file] = depth;
+
+    for (const dep of (outbound[file] || [])) {
+      if (!visited.has(dep)) {
+        queue.push({ file: dep, depth: depth + 1 });
+      }
+    }
+  }
+
+  // Files not reachable from entry points get layer based on their own import count
+  for (const f of allFiles) {
+    if (!(f in layers)) {
+      // Isolated file — assign layer based on outbound/inbound ratio
+      const out = (outbound[f] || []).length;
+      const inc = (inbound[f] || []).length;
+      if (inc === 0 && out === 0) layers[f] = 0; // standalone
+      else if (inc === 0) layers[f] = 0; // entry-like
+      else if (out === 0) layers[f] = 99; // leaf (type/constant)
+      else layers[f] = Math.round(out / (inc + 1)); // ratio-based
+    }
+  }
+
+  // Normalize layers to 0-based consecutive
+  const uniqueLayers = [...new Set(Object.values(layers))].sort((a, b) => a - b);
+  const layerMap = {};
+  uniqueLayers.forEach((l, i) => layerMap[l] = i);
+  for (const f of allFiles) {
+    layers[f] = layerMap[layers[f]] || 0;
+  }
+
+  // Extract folder from file path
+  function getFolder(filePath) {
+    const parts = filePath.split('/');
+    return parts.length > 1 ? parts.slice(0, -1).join('/') : '.';
+  }
+
+  // Aggregate folder stats
+  const folderStats = {};
+  for (const f of allFiles) {
+    const folder = getFolder(f);
+    if (!folderStats[folder]) {
+      folderStats[folder] = { count: 0, totalImports: 0, totalImportedBy: 0, layerSum: 0 };
+    }
+    folderStats[folder].count++;
+    folderStats[folder].totalImports += (outbound[f] || []).length;
+    folderStats[folder].totalImportedBy += (inbound[f] || []).length;
+    folderStats[folder].layerSum += layers[f];
+  }
+
+  // Detect folder role from stats (auto-derived, not hardcoded)
+  function detectRole(stats) {
+    const avgLayer = stats.layerSum / stats.count;
+    const importRatio = stats.totalImports / Math.max(stats.totalImportedBy, 1);
+
+    if (stats.totalImportedBy === 0 && stats.totalImports > 0) return 'entry';
+    if (stats.totalImports === 0 && stats.totalImportedBy > 0) return 'leaf';
+    if (importRatio < 0.3) return 'shared'; // heavily imported by others = shared/util
+    if (importRatio > 3) return 'consumer'; // imports many, few import it = consumer/page
+    if (avgLayer < 1) return 'top';
+    if (avgLayer > 4) return 'foundation';
+    return 'middle';
+  }
+
+  // Build SQL statements
+  const dbPath = brain.getBrainPath(cwd);
+  const statements = ['BEGIN TRANSACTION;', 'DELETE FROM architecture;', 'DELETE FROM folders;'];
+
+  for (const f of allFiles) {
+    const folder = getFolder(f);
+    const layer = layers[f];
+    const importsCount = (outbound[f] || []).length;
+    const importedByCount = (inbound[f] || []).length;
+    const esc = s => s.replace(/'/g, "''");
+
+    statements.push(
+      `INSERT OR REPLACE INTO architecture (file_path, layer, folder, imports_count, imported_by_count, updated_at) ` +
+      `VALUES ('${esc(f)}', ${layer}, '${esc(folder)}', ${importsCount}, ${importedByCount}, strftime('%s', 'now'));`
+    );
+  }
+
+  for (const [folder, stats] of Object.entries(folderStats)) {
+    const role = detectRole(stats);
+    const avgLayer = (stats.layerSum / stats.count).toFixed(1);
+    const esc = s => s.replace(/'/g, "''");
+
+    statements.push(
+      `INSERT OR REPLACE INTO folders (folder_path, file_count, total_imports, total_imported_by, avg_layer, role, updated_at) ` +
+      `VALUES ('${esc(folder)}', ${stats.count}, ${stats.totalImports}, ${stats.totalImportedBy}, ${avgLayer}, '${role}', strftime('%s', 'now'));`
+    );
+  }
+
+  statements.push('COMMIT;');
+  safeRun('sqlite3', [dbPath], { input: statements.join('\n'), stdio: ['pipe', 'pipe', 'pipe'] });
+
+  return { computed: files.length, folders: Object.keys(folderStats).length };
+}
+
+// ============================================================
+// Query helpers
+// ============================================================
+
+function getLayerSummary(cwd) {
+  return brain.query(cwd,
+    "SELECT layer, COUNT(*) as files, SUM(imports_count) as total_imports, SUM(imported_by_count) as total_consumers " +
+    "FROM architecture GROUP BY layer ORDER BY layer"
+  );
+}
+
+function getFolderRoles(cwd) {
+  return brain.query(cwd,
+    "SELECT folder_path, file_count, total_imports, total_imported_by, avg_layer, role " +
+    "FROM folders ORDER BY avg_layer, folder_path LIMIT 40"
+  );
+}
+
+function getFileLayer(cwd, filePath) {
+  return brain.query(cwd,
+    `SELECT a.*, f.role as folder_role FROM architecture a LEFT JOIN folders f ON a.folder = f.folder_path ` +
+    `WHERE a.file_path LIKE '%${brain.esc(filePath)}%' LIMIT 5`
+  );
+}
+
+function getDataFlow(cwd, filePath) {
+  const file = brain.query(cwd,
+    `SELECT * FROM architecture WHERE file_path LIKE '%${brain.esc(filePath)}%' LIMIT 1`
+  );
+  if (!file.length) return { error: 'File not found' };
+
+  const upstream = brain.query(cwd,
+    `SELECT a.file_path, a.layer, a.folder FROM architecture a ` +
+    `JOIN edges e ON ('file:' || a.file_path) = e.source ` +
+    `WHERE e.target LIKE '%${brain.esc(filePath)}%' AND e.kind = 'imports' ` +
+    `ORDER BY a.layer ASC LIMIT 10`
+  );
+
+  const downstream = brain.query(cwd,
+    `SELECT a.file_path, a.layer, a.folder FROM architecture a ` +
+    `JOIN edges e ON ('file:' || a.file_path) = e.target ` +
+    `WHERE e.source LIKE '%${brain.esc(filePath)}%' AND e.kind = 'imports' ` +
+    `ORDER BY a.layer DESC LIMIT 10`
+  );
+
+  return { file: file[0], upstream, downstream };
+}
+
+function getMostConnected(cwd, limit) {
+  return brain.query(cwd,
+    `SELECT file_path, layer, folder, imports_count, imported_by_count, ` +
+    `(imports_count + imported_by_count) as total FROM architecture ` +
+    `ORDER BY total DESC LIMIT ${parseInt(limit) || 15}`
+  );
+}
+
+module.exports = {
+  computeArchitecture,
+  getLayerSummary,
+  getFolderRoles,
+  getFileLayer,
+  getDataFlow,
+  getMostConnected
+};