spectoflow 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 G. MOMO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/georgesmomo/spectoflow/main/logo-spectoflow-white.png">
+    <img src="https://raw.githubusercontent.com/georgesmomo/spectoflow/main/logo-spectoflow.png" alt="spectoflow" width="112">
+  </picture>
+</p>
+
+<h1 align="center">spectoflow</h1>
+
+<p align="center"><em>Agent-agnostic spec-driven development with a real-time local control plane.</em></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/spectoflow"><img src="https://img.shields.io/npm/v/spectoflow.svg?color=e6a54b" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-5fb2cc" alt="node >= 18">
+  <img src="https://img.shields.io/badge/dependencies-0-4caf72" alt="zero dependencies">
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+</p>
+
+An **agent-agnostic** spec-driven development framework with a **real-time local control plane**.
+You speak in plain language; the framework classifies your intent and runs the right workflow. No
+ceremonial command to start.
+
+## Install
+
+```bash
+npm install -g spectoflow        # (once published)
+spectoflow init /path/to/project # or: node bin/spectoflow.js init .
+```
+
+`init` scaffolds:
+- `.spectoflow/` — the framework (brain, `workflow.md`, `agents/`, `skills/`, `policy.md`, `config.json`, dashboard, engine).
+- `specs/` and `plans/` — **markdown artifacts**, your versioned source of truth.
+- per-agent shims: `CLAUDE.md` (Claude Code), `AGENTS.md` (Codex/Cursor), `GEMINI.md` (Gemini),
+  `.claude/commands/spectoflow.md`.
+- `.spectoflow/runtime.json` is gitignored (volatile execution state).
+
+`init` **auto-detects your installed agent(s)** (probes PATH for `claude`, `codex`, `cursor-agent`,
+`gemini`, and existing `.claude`/`.codex`/… dirs): it writes shims for each, sets the active agent in
+`config.json`, and seeds the runner commands. Override with `--agent=claude,codex`; if nothing is
+detected it falls back to claude + codex.
+
+**Empty project** → your agent asks what to build and runs Intake (brainstorm → analysis → spec → plan).
+**Existing project** → an existing `CLAUDE.md` is preserved as `CLAUDE.md.tomerge` (merged on first run);
+existing `plans/*.md` tasks are given stable ids.
+
+## Update
+
+`init` is idempotent (it never overwrites), so it can't refresh an installed project. `spectoflow
+update` refreshes **framework-owned** files (engine, dashboard, `AGENTS.md`, `capabilities.md`,
+`policy.md`, default agents & skills) to the CLI's version, while **preserving your work** —
+`config.json`, `workflow.md`, `specs/`, `plans/`, and any agent/skill you created or edited are never
+touched. A file you edited is preserved and its new version is written next to it as `<file>.new`
+for you to merge by hand. Add `--dry-run` to preview.
+
+First refresh the kit, then run update from your project — the flow is the same whichever way you
+installed:
+
+```bash
+# npm global
+npm update -g spectoflow  &&  spectoflow update
+
+# manual (cloned repo)
+git -C /path/to/spectoflow pull  &&  node /path/to/spectoflow/bin/spectoflow.js update
+
+# npx (no install)
+npx spectoflow@latest update
+```
+
+`update` resolves the framework version from the CLI you run and the project from the current
+directory, so it behaves identically across all three. `init` records a hashed baseline in
+`.spectoflow/.manifest.json` (committed) that lets update tell an untouched framework file from one
+you've edited; installs made before this file existed degrade safely (a matching file is adopted, a
+divergent one gets a `.new`).
+
+## Storage is markdown
+
+Plans are plain markdown with checkbox tasks — human-readable, git-diffable, standard:
+
+```
+## Phase 1 — Login
+- [ ] T-001 Add login form @dev ~standard %in_progress
+  - note: waiting on design tokens
+- [x] T-002 Set up auth routes @dev
+```
+
+`[x]` done · `~level` quick|standard|major · `%status` in_progress|to_validate|to_analyze|blocked ·
+`@owner`. The dashboard parses these and writes back **one line at a time** (granular), so it and your
+agent never clobber each other.
+
+## Dashboard (real-time)
+
+```bash
+node .spectoflow/dashboard/server.js   # → http://localhost:4319
+```
+
+Zero dependencies, updates live via SSE + file watching. Seven tabs behind a dense icon-tab header
+(brand · subtitle · a slim global-progress meter · a sync dot · a **Run** quick-action): **Board**
+(the control-room Overview — KPI cards, a status donut, a **scope-vs-delivered area curve**, a
+workflow-at-a-glance strip, per-phase progress bars, filter chips + search — plus the phase board),
+**Requests** (tasks awaiting you — `to_validate`/`to_analyze`), **Backlog** (a flat sortable/filterable
+table of every task across every plan), **Workflow** (the pipeline as a diagram — click a step to
+enable/disable it, which edits `workflow.md`), **Agents & Skills** (enriched cards — capability,
+standards, uses/inputs/outputs — that open a full-body markdown drawer), **Chat** (a full-height
+group-chat panel), and **Info** (a project-at-a-glance summary). Charts are zero-dep, hand-rolled SVG
+in `dashboard/public/charts.js` (donut/area/bars/ring, animated, `prefers-reduced-motion`-aware), and
+every aggregate is computed client-side.
+
+A floating **💬 chat widget** (bottom-right, redesigned) and the **Chat** tab render the same
+`runtime.messages` log via a shared `renderChatLog()`, so they never drift. A running agent identifies
+itself by printing `::spectoflow role=… kind=… msg=…` sentinels, which become labelled messages
+(analyst / developer / qa …); other output streams raw. The board refreshes live as it edits plans.
+Either surface can also **Orchestrate** the enabled workflow: each step runs its agent, gated by mode
++ policy. The Agents & Skills drawer is served by the one read-only endpoint, `GET
+/api/agentfile?path=` (scoped to `.spectoflow/agents/**` + `.spectoflow/skills/**`,
+path-traversal-safe) — the framework's only other server surface is unchanged.
+
+## Agents vs skills
+
+Agents (`.spectoflow/agents/`) are **stable team personas** (Product Manager, Developer, QA Engineer…).
+Skills (`.spectoflow/skills/`) are **evolving procedures**. A workflow step → a capability → its agent →
+runs a skill. Improve a skill without touching the agent.
+
+Agents and skills follow real domain standards, cited in-file — TDD, OWASP ASVS/Top 10, C4/ADR,
+INVEST, Playwright E2E, Conventional Commits, and more — not generic one-liners.
+
+## Language
+
+`.spectoflow/config.json` → `language` (default `en`, incl. code comments). Switchable.
+
+## Studied, not copied
+
+Structure informed by spec-kit, OpenSpec (markdown + per-agent adapters), and BMAD (agent-personas).
+spectoflow keeps the good ideas, removes the ceremony, and adds a real-time control plane. MIT.

package/bin/spectoflow.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const store = require('../templates/lib/store');
+const adapters = require('../lib/adapters');
+const detect = require('../lib/detect');
+const ownership = require('../lib/ownership');
+const manifest = require('../lib/manifest');
+
+const KIT = path.resolve(__dirname, '..');
+const TPL = path.join(KIT, 'templates');
+const VERSION = require('../package.json').version;
+const argv = process.argv.slice(2);
+const cmd = argv[0] || 'help';
+
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, e.name), d = path.join(dst, e.name);
+    if (e.isDirectory()) copyDir(s, d);
+    else if (!fs.existsSync(d)) fs.copyFileSync(s, d);
+  }
+}
+
+// Existing project: give id-less checkbox tasks a stable id, in place.
+const ID_RE = /^[A-Za-z]{1,5}-?\d+[A-Za-z]?$/;
+function normalizePlans(root) {
+  const dir = path.join(root, 'plans');
+  if (!fs.existsSync(dir)) return 0;
+  let added = 0, seq = 1;
+  for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.md'))) {
+    const fp = path.join(dir, f);
+    const lines = fs.readFileSync(fp, 'utf8').split('\n');
+    let touched = false;
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(/^(\s*- \[[ xX]\]\s+)(\S+)(\s.*)?$/);
+      if (m && !ID_RE.test(m[2])) {
+        const id = 'T-' + String(seq++).padStart(3, '0');
+        lines[i] = `${m[1]}${id} ${m[2]}${m[3] || ''}`;
+        touched = true; added++;
+      } else if (m) { seq++; }
+    }
+    if (touched) fs.writeFileSync(fp, lines.join('\n'));
+  }
+  return added;
+}
+
+function init() {
+  const target = path.resolve(argv[1] && !argv[1].startsWith('--') ? argv[1] : '.');
+  const agentsArg = (argv.find((a) => a.startsWith('--agent=')) || '').split('=')[1];
+  fs.mkdirSync(target, { recursive: true });
+  const notes = [];
+
+  // explicit --agent wins; otherwise detect installed agents; otherwise fall back to claude + codex
+  let agents, detected = [];
+  if (agentsArg) {
+    agents = agentsArg.split(',');
+  } else {
+    detected = detect.detectAgents(target);
+    agents = detected.length ? detected : ['claude', 'codex'];
+    notes.push(detected.length
+      ? `Detected agent(s): ${detected.join(', ')} — active: ${agents[0]}.`
+      : 'No agent CLI detected — defaulted to claude + codex.');
+  }
+
+  // preserve an existing CLAUDE.md
+  const claude = path.join(target, 'CLAUDE.md');
+  if (fs.existsSync(claude) && !fs.existsSync(claude + '.tomerge')) {
+    fs.renameSync(claude, claude + '.tomerge');
+    notes.push('Existing CLAUDE.md preserved as CLAUDE.md.tomerge — your agent merges it on first run.');
+  }
+
+  // canonical framework → .spectoflow/
+  const spectoflowDir = path.join(target, '.spectoflow');
+  copyDir(TPL, spectoflowDir);
+
+  // record the install baseline so `update` can tell untouched framework files from user edits
+  const frameworkFiles = ownership.listFrameworkFiles(TPL);
+  manifest.writeManifest(spectoflowDir, {
+    version: VERSION,
+    files: manifest.hashFileMap(spectoflowDir, frameworkFiles),
+  });
+
+  // set the active agent and seed runner commands from the selected/detected agents
+  const cfgPath = path.join(spectoflowDir, 'config.json');
+  const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+  cfg.agent = agents[0];
+  cfg.runners = { ...cfg.runners, ...adapters.defaultRunners(agents) };
+  fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+
+  // artifact folders
+  fs.mkdirSync(path.join(target, 'specs'), { recursive: true });
+  fs.mkdirSync(path.join(target, 'plans'), { recursive: true });
+
+  // existing project: id-normalize any plans already there
+  const added = normalizePlans(target);
+  if (added) notes.push(`Normalized ${added} existing task(s) with stable ids.`);
+
+  // per-agent shims
+  const written = adapters.generate(target, agents);
+
+  // gitignore the volatile runtime
+  const gi = path.join(target, '.gitignore');
+  const line = '.spectoflow/runtime.json';
+  if (!fs.existsSync(gi) || !fs.readFileSync(gi, 'utf8').includes(line)) {
+    fs.appendFileSync(gi, (fs.existsSync(gi) ? '\n' : '') + line + '\n');
+  }
+
+  console.log('spectoflow installed in', target);
+  console.log('  .spectoflow/   framework (brain, workflow, agents, skills, policy, dashboard, config)');
+  console.log('  specs/ plans/  markdown artifacts (your source of truth)');
+  written.forEach((w) => console.log('  + ' + w));
+  notes.forEach((n) => console.log('  ! ' + n));
+  console.log('\nNext:');
+  console.log('  1) Open your agent here (Claude Code loads CLAUDE.md; Codex loads AGENTS.md).');
+  console.log('  2) Run /spectoflow init — or just say what you want to build.');
+  console.log('  3) Watch: node .spectoflow/dashboard/server.js → http://localhost:4319');
+}
+
+function update() {
+  const root = process.cwd();
+  if (!fs.existsSync(path.join(root, '.spectoflow'))) {
+    return console.log('No spectoflow project here. Run: spectoflow init');
+  }
+  const dryRun = argv.includes('--dry-run');
+  const r = require('../lib/update').runUpdate({ projectRoot: root, templatesDir: TPL, version: VERSION, dryRun });
+
+  const from = r.fromVersion || 'unknown';
+  console.log(`spectoflow update — ${from} → ${r.toVersion}${dryRun ? '   (dry-run)' : ''}`);
+  const line = (label, list) => list.length && console.log(`  ${label.padEnd(10)} ${String(list.length).padStart(2)}   ${list.join(', ')}`);
+  line('refreshed', r.refreshed);
+  line('created', r.created);
+  line('adopted', r.adopted);
+  line('.new', r.newSidecar);
+  if (r.unchanged.length) console.log(`  ${'unchanged'.padEnd(10)} ${String(r.unchanged.length).padStart(2)}`);
+  console.log(`  ${'preserved'.padEnd(10)}      config.json, workflow.md, specs/, plans/, your custom agents & skills`);
+  if (r.newSidecar.length) {
+    console.log(`\n${r.newSidecar.length} file(s) you edited have a new version alongside as *.new — compare and merge by hand.`);
+  }
+  if (dryRun) console.log('\n(dry-run — nothing was written)');
+}
+
+function dashboard() {
+  const local = path.resolve('.spectoflow', 'dashboard', 'server.js');
+  const bundled = path.join(TPL, 'dashboard', 'server.js');
+  spawn('node', [fs.existsSync(local) ? local : bundled], { stdio: 'inherit' });
+}
+
+function status() {
+  const root = process.cwd();
+  if (!fs.existsSync(path.join(root, 'plans')) && !fs.existsSync(path.join(root, '.spectoflow'))) {
+    return console.log('No spectoflow project here. Run: spectoflow init');
+  }
+  const p = store.readProject(root);
+  const tasks = p.plans.flatMap((pl) => pl.phases.flatMap((ph) => ph.tasks));
+  const done = tasks.filter((t) => t.status === 'done').length;
+  console.log(`${(p.config && p.config.projectType) || 'project'} — mode ${p.config.mode} · lang ${p.config.language}`);
+  console.log(`${done}/${tasks.length} tasks done · ${p.specs.length} spec(s) · ${p.agents.length} agents · ${p.skills.length} skills`);
+  tasks.filter((t) => t.status === 'in_progress').forEach((t) => console.log(`  > in progress: ${t.id} ${t.title}`));
+}
+
+const help = () => console.log(`spectoflow — commands:
+  init [dir] [--agent=claude,codex]   install into a project
+  update [--dry-run]                  refresh framework files to this kit version
+  dashboard                           run the local control plane
+  status                              print progress`);
+
+({ init, update, dashboard, status, help })[cmd] ? ({ init, update, dashboard, status, help })[cmd]() : help();

package/lib/adapters.js

@@ -0,0 +1,120 @@
+'use strict';
+/*
+ * Per-agent adapters. The canonical brain is .spectoflow/AGENTS.md. Each agent needs a thin entry
+ * file in the place IT reads, pointing back to the canonical brain — so the framework stays in
+ * .spectoflow/ (swappable, no pollution) while every agent still finds its native entry point.
+ * (Same pattern OpenSpec uses to support claude/codex/cursor/gemini/…)
+ *
+ * The REGISTRY is the single source: for each agent, the native entry file(s) to write (shims), the
+ * default headless runner command (fills config.runners; user-adjustable), and how to detect it
+ * (a PATH binary and/or existing agent dir). Order = default-agent priority when several are found.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const CLAUDE_MD = `# CLAUDE.md — spectoflow
+
+This project uses **spectoflow**. **Read \`.spectoflow/AGENTS.md\` and follow it** as your operating
+instructions (intent router, workflow, standing rules).
+
+> If \`CLAUDE.md.tomerge\` exists next to this file, it is your previous CLAUDE.md, preserved on
+> install. Merge its project-specific content into this file, then delete \`CLAUDE.md.tomerge\`,
+> before anything else.
+
+- Command: \`/spectoflow\` (\`init\` / \`status\` / or just a request).
+- Dashboard: \`node .spectoflow/dashboard/server.js\` → http://localhost:4319
+- Artifacts are markdown in \`specs/\` and \`plans/\`; volatile state in \`.spectoflow/runtime.json\`.
+`;
+
+const ROOT_AGENTS_MD = `# AGENTS.md — spectoflow
+
+This project uses **spectoflow**. **Read \`.spectoflow/AGENTS.md\` and follow it** as your operating
+instructions. Artifacts are markdown in \`specs/\` and \`plans/\`; the workflow is \`.spectoflow/workflow.md\`.
+`;
+
+const GEMINI_MD = `# GEMINI.md — spectoflow
+
+This project uses **spectoflow**. **Read \`.spectoflow/AGENTS.md\` and follow it** as your operating
+instructions (intent router, workflow, standing rules). Artifacts are markdown in \`specs/\` and
+\`plans/\`; the workflow is \`.spectoflow/workflow.md\`.
+`;
+
+const SLASH_CMD = `---
+description: spectoflow — spec-driven control (init / status / or just a request)
+---
+
+Read \`.spectoflow/AGENTS.md\` and \`.spectoflow/config.json\` first.
+
+Argument: \`$ARGUMENTS\`
+
+- \`init\`: verify setup. If \`CLAUDE.md.tomerge\` exists, merge it into \`CLAUDE.md\` and delete it. If
+  \`specs/\` and \`plans/\` are empty, greet me, state the mode, and start Intake (brainstorm → analysis
+  → spec → plan) by asking what I want to build.
+- \`status\`: summarize progress from \`plans/*.md\` and \`.spectoflow/runtime.json\`.
+- otherwise: treat \`$ARGUMENTS\` as a request and run the Router in \`.spectoflow/AGENTS.md\`.
+`;
+
+// Priority order = which agent becomes the default when several are detected.
+const REGISTRY = [
+  {
+    id: 'claude',
+    entries: [
+      { path: 'CLAUDE.md', content: CLAUDE_MD },
+      { path: '.claude/commands/spectoflow.md', content: SLASH_CMD },
+    ],
+    runner: 'claude -p --permission-mode acceptEdits',
+    detect: { bin: 'claude', dirs: ['.claude'] },
+  },
+  {
+    id: 'codex',
+    entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
+    runner: 'codex exec',
+    detect: { bin: 'codex', dirs: ['.codex'] },
+  },
+  {
+    id: 'cursor',
+    entries: [{ path: 'AGENTS.md', content: ROOT_AGENTS_MD }],
+    runner: 'cursor-agent -p',
+    detect: { bin: 'cursor-agent', dirs: ['.cursor'] },
+  },
+  {
+    id: 'gemini',
+    entries: [{ path: 'GEMINI.md', content: GEMINI_MD }],
+    runner: 'gemini -p',
+    detect: { bin: 'gemini', dirs: ['.gemini'] },
+  },
+];
+
+const byId = (id) => REGISTRY.find((a) => a.id === id);
+
+function writeIfAbsent(fp, content) {
+  if (fs.existsSync(fp)) return false;
+  fs.mkdirSync(path.dirname(fp), { recursive: true });
+  fs.writeFileSync(fp, content);
+  return true;
+}
+
+// Write the native entry-file shims for each selected agent. Shared files (AGENTS.md across
+// codex/cursor) are written once — writeIfAbsent dedupes. Returns the relative paths written.
+function generate(projectRoot, agents) {
+  const list = (agents && agents.length ? agents : ['claude', 'codex']).map(byId).filter(Boolean);
+  const written = [];
+  for (const a of list) {
+    for (const e of a.entries) {
+      if (writeIfAbsent(path.join(projectRoot, e.path), e.content)) written.push(e.path);
+    }
+  }
+  return written;
+}
+
+// { id: runner } defaults for the given agents — used to seed config.runners at init.
+function defaultRunners(agents) {
+  const out = {};
+  for (const id of agents) {
+    const a = byId(id);
+    if (a) out[id] = a.runner;
+  }
+  return out;
+}
+
+module.exports = { generate, defaultRunners, REGISTRY };

package/lib/detect.js

@@ -0,0 +1,34 @@
+'use strict';
+/*
+ * Agent auto-detection. A detected agent means: its CLI is on PATH (so its runner will actually
+ * work) OR the project already has that agent's config dir. `init` uses this to pick sensible
+ * defaults (which shims to write, which agent is active) instead of asking the user to specify.
+ */
+const fs = require('fs');
+const path = require('path');
+const { REGISTRY } = require('./adapters');
+
+// Is `bin` an executable resolvable on PATH? On win32, an extension from PATHEXT is required, so we
+// try each; we also try the bare name (covers test fixtures and extensionless shims).
+function binOnPath(bin, { env = process.env, platform = process.platform } = {}) {
+  const raw = env.PATH || env.Path || '';
+  const dirs = raw.split(path.delimiter).filter(Boolean);
+  const exts =
+    platform === 'win32' ? ['', ...(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)] : [''];
+  for (const d of dirs) {
+    for (const e of exts) {
+      if (fs.existsSync(path.join(d, bin + e))) return true;
+    }
+  }
+  return false;
+}
+
+// Agent ids detected for `projectRoot`, in REGISTRY (priority) order.
+function detectAgents(projectRoot, opts = {}) {
+  return REGISTRY.filter((a) => {
+    if (a.detect.bin && binOnPath(a.detect.bin, opts)) return true;
+    return (a.detect.dirs || []).some((d) => fs.existsSync(path.join(projectRoot, d)));
+  }).map((a) => a.id);
+}
+
+module.exports = { binOnPath, detectAgents };

package/lib/manifest.js

@@ -0,0 +1,36 @@
+'use strict';
+/*
+ * The install manifest — `.spectoflow/.manifest.json`. Records the kit version and a sha256 of every
+ * framework-owned file as it was installed. `update` compares the on-disk hash against this baseline
+ * to tell "untouched framework file" (safe to refresh) from "user-edited" (preserve, drop a .new).
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const MANIFEST_NAME = '.manifest.json';
+
+function sha256(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+// { relPath: sha256 } for each file, read relative to baseDir.
+function hashFileMap(baseDir, relFiles) {
+  const map = {};
+  for (const rel of relFiles) {
+    map[rel] = sha256(fs.readFileSync(path.join(baseDir, rel.split('/').join(path.sep))));
+  }
+  return map;
+}
+
+function writeManifest(spectoflowDir, data) {
+  fs.writeFileSync(path.join(spectoflowDir, MANIFEST_NAME), JSON.stringify(data, null, 2) + '\n');
+}
+
+function readManifest(spectoflowDir) {
+  const fp = path.join(spectoflowDir, MANIFEST_NAME);
+  if (!fs.existsSync(fp)) return null;
+  return JSON.parse(fs.readFileSync(fp, 'utf8'));
+}
+
+module.exports = { sha256, hashFileMap, writeManifest, readManifest, MANIFEST_NAME };

package/lib/ownership.js

@@ -0,0 +1,34 @@
+'use strict';
+/*
+ * Ownership model for `spectoflow update`.
+ *
+ * Framework-owned files (refreshed on update) are DERIVED from the kit's templates/ — every file the
+ * kit ships EXCEPT the ones that belong to the user. Deriving the set (rather than hard-coding it)
+ * keeps it correct when new default agents/skills are added to the kit.
+ *
+ * User-owned (never touched): config.json (settings) and workflow.md (edited from the dashboard).
+ * specs/, plans/, runtime.json and .manifest.json are not in templates/, so they never appear here.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// Files the kit ships but the user owns — never refreshed by update.
+const USER_OWNED = new Set(['config.json', 'workflow.md']);
+
+function walk(dir, base, out) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, e.name);
+    const rel = path.relative(base, abs).split(path.sep).join('/');
+    if (e.isDirectory()) walk(abs, base, out);
+    else out.push(rel);
+  }
+}
+
+// Relative POSIX paths of every framework-owned file shipped in `templatesDir`, sorted, deduped.
+function listFrameworkFiles(templatesDir) {
+  const out = [];
+  walk(templatesDir, templatesDir, out);
+  return [...new Set(out.filter((f) => !USER_OWNED.has(f)))].sort();
+}
+
+module.exports = { listFrameworkFiles, USER_OWNED };

package/lib/update.js

@@ -0,0 +1,78 @@
+'use strict';
+/*
+ * `spectoflow update` — refresh framework-owned files in an installed project to the current kit,
+ * without ever touching the user's work. Ownership is decided per file against the install manifest:
+ *
+ *   file absent on disk .......................... create (new file shipped by this version)
+ *   disk == new template ......................... already current (unchanged, or adopted if legacy)
+ *   disk == manifest baseline (untouched) ........ refresh to the new template
+ *   otherwise (user-edited, or legacy-divergent) . preserve; write <file>.new for manual merge
+ *
+ * User-owned files (config.json, workflow.md) are not in the framework set, so they are never read
+ * for writing. No 3-way auto-merge and no deletions in v1 — refresh the safe, offer the rest as .new.
+ */
+const fs = require('fs');
+const path = require('path');
+const ownership = require('./ownership');
+const manifest = require('./manifest');
+
+function toDisk(sf, rel) {
+  return path.join(sf, rel.split('/').join(path.sep));
+}
+
+function runUpdate({ projectRoot, templatesDir, version, dryRun = false }) {
+  const sf = path.join(projectRoot, '.spectoflow');
+  const prev = manifest.readManifest(sf);
+  const report = {
+    fromVersion: prev ? prev.version : null,
+    toVersion: version,
+    dryRun,
+    created: [],
+    refreshed: [],
+    newSidecar: [],
+    adopted: [],
+    unchanged: [],
+  };
+  const baseline = (prev && prev.files) || {};
+  const nextFiles = {}; // manifest to write after this run
+
+  const write = (fp, buf) => {
+    if (dryRun) return;
+    fs.mkdirSync(path.dirname(fp), { recursive: true });
+    fs.writeFileSync(fp, buf);
+  };
+
+  for (const rel of ownership.listFrameworkFiles(templatesDir)) {
+    const newBuf = fs.readFileSync(toDisk(templatesDir, rel));
+    const newHash = manifest.sha256(newBuf);
+    const diskPath = toDisk(sf, rel);
+    const base = baseline[rel]; // undefined for legacy / brand-new files
+
+    if (!fs.existsSync(diskPath)) {
+      write(diskPath, newBuf);
+      report.created.push(rel);
+      nextFiles[rel] = newHash;
+      continue;
+    }
+
+    const diskHash = manifest.sha256(fs.readFileSync(diskPath));
+
+    if (diskHash === newHash) {
+      (base === undefined ? report.adopted : report.unchanged).push(rel);
+      nextFiles[rel] = newHash; // bring legacy files under tracking; keep tracked ones current
+    } else if (base !== undefined && diskHash === base) {
+      write(diskPath, newBuf); // untouched framework file → safe to refresh
+      report.refreshed.push(rel);
+      nextFiles[rel] = newHash;
+    } else {
+      write(diskPath + '.new', newBuf); // user-edited or legacy-divergent → offer, never overwrite
+      report.newSidecar.push(rel);
+      if (base !== undefined) nextFiles[rel] = base; // keep flagged as diverged next time
+    }
+  }
+
+  if (!dryRun) manifest.writeManifest(sf, { version, files: nextFiles });
+  return report;
+}
+
+module.exports = { runUpdate };

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "spectoflow",
+  "version": "0.12.0",
+  "description": "Agent-agnostic spec-driven development framework + real-time local control plane. Markdown artifacts, intent router, workflow-by-scope.",
+  "keywords": [
+    "spec-driven-development",
+    "sdd",
+    "ai-agents",
+    "coding-agents",
+    "agent-agnostic",
+    "workflow",
+    "orchestration",
+    "dashboard",
+    "control-plane",
+    "markdown",
+    "claude",
+    "codex",
+    "cursor",
+    "gemini"
+  ],
+  "homepage": "https://github.com/georgesmomo/spectoflow#readme",
+  "bugs": { "url": "https://github.com/georgesmomo/spectoflow/issues" },
+  "repository": { "type": "git", "url": "git+https://github.com/georgesmomo/spectoflow.git" },
+  "author": "Georges MOMO <georges.momo@gmail.com>",
+  "license": "MIT",
+  "bin": { "spectoflow": "bin/spectoflow.js" },
+  "files": ["bin", "lib", "templates", "README.md", "LICENSE"],
+  "scripts": { "status": "node bin/spectoflow.js status", "test": "node --test" },
+  "engines": { "node": ">=18" }
+}