spectoflow 0.13.0 → 0.13.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 G. MOMO
+Copyright (c) 2026 Georges 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

package/README.md

@@ -23,8 +23,27 @@ ceremonial command to start.
 ## Install
 
 ```bash
-npm install -g spectoflow        # (once published)
-spectoflow init /path/to/project # or: node bin/spectoflow.js init .
+# npm (recommended)
+npm install -g spectoflow
+spectoflow init /path/to/project
+
+# or use it straight from a clone, no global install
+git clone https://github.com/georgesmomo/spectoflow
+node spectoflow/bin/spectoflow.js init /path/to/project
+```
+
+Every command works both ways — `spectoflow <cmd>` when installed globally, or `node
+/path/to/spectoflow/bin/spectoflow.js <cmd>` from a clone.
+
+### CLI
+
+```
+spectoflow init [dir] [--agent=claude,codex]   scaffold a project (auto-detects installed agents)
+spectoflow update [--dry-run]                  refresh framework files to this kit version
+spectoflow dashboard [--port=NNNN]             run the local control plane (default 4319)
+spectoflow status                              progress + whether the dashboard is running
+spectoflow --version   (-v)                    print the version
+spectoflow --help      (-h)                    show help
 ```
 
 `init` scaffolds:
@@ -90,20 +109,26 @@ agent never clobber each other.
 ## Dashboard (real-time)
 
 ```bash
-node .spectoflow/dashboard/server.js   # → http://localhost:4319
+spectoflow dashboard                     # → http://localhost:4319 (or --port=NNNN)
+# manual (no global install): node .spectoflow/dashboard/server.js
 ```
 
-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
+`spectoflow dashboard` is the simple way — it prints the URL and won't double-start (it detects a
+dashboard already running on the port). `spectoflow status` tells you whether one is up. Running the
+`server.js` directly still works for a manual/embedded setup. Zero dependencies, updates live via SSE +
+file watching. Eight tabs behind a dense icon-tab header (brand logo · subtitle · a slim
+global-progress meter · a sync dot · a **Run** quick-action · a **settings** gear): **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.
+**Requests** (tasks awaiting you — `to_validate`/`to_analyze`), **Attention** (points the agent raised
+via a `::spectoflow attention msg=…` sentinel or that you noted — edit/resolve/delete, or **validate →
+task**), **Backlog** (a flat sortable/filterable, paginated table of every task, defaulting to open
+work), **Workflow** (the pipeline as step cards — click one to enable/disable it, which edits
+`workflow.md`), **Agents & Skills** (enriched cards that open a full-body markdown drawer), **Chat** (a
+full-height group-chat panel), and **Info** (a project-at-a-glance summary). URLs are real routes
+(`/board`, `/backlog/T-012`, …). 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
@@ -125,9 +150,14 @@ INVEST, Playwright E2E, Conventional Commits, and more — not generic one-liner
 
 ## Language
 
-`.spectoflow/config.json` → `language` (default `en`, incl. code comments). Switchable.
+`.spectoflow/config.json` → `language` (default `en`, incl. code comments). Switchable from the CLI
+(`config.json`) or the dashboard's **settings** gear (mode + language).
 
 ## 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.
+spectoflow keeps the good ideas, removes the ceremony, and adds a real-time control plane.
+
+## License & author
+
+MIT © 2026 [Georges MOMO](https://github.com/georgesmomo).

package/bin/spectoflow.js

@@ -16,6 +16,11 @@ const VERSION = require('../package.json').version;
 const argv = process.argv.slice(2);
 const cmd = argv[0] || 'help';
 
+// Tiny ANSI colouriser — no dependency; disabled when not a TTY or NO_COLOR is set.
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const c = { g: paint('32'), cy: paint('36'), b: paint('34'), y: paint('33'), dim: paint('2'), bold: paint('1'), amber: paint('38;5;179') };
+
 // ---- dashboard port + running-state probe ------------------------------------
 // Precedence: --port=NNNN > SPECTOFLOW_PORT env > 4319 (matches templates/dashboard/server.js).
 function resolvePort(args) {
@@ -156,18 +161,27 @@ function update() {
   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)');
+  const changed = r.refreshed.length + r.created.length + r.adopted.length + r.newSidecar.length;
+  const row = (sym, label, list, painter, note) => {
+    if (!list.length) return;
+    const n = c.dim(String(list.length).padStart(2));
+    const detail = note ? c.dim(note) : c.dim(list.slice(0, 6).join(', ') + (list.length > 6 ? ` +${list.length - 6} more` : ''));
+    console.log(`  ${sym}  ${painter(label.padEnd(9))} ${n}   ${detail}`);
+  };
+  console.log('');
+  console.log(`  ${c.bold('spectoflow update')}   ${c.dim(from)} ${c.amber('→')} ${c.bold(r.toVersion)}${dryRun ? c.dim('   (dry-run)') : ''}`);
+  console.log('');
+  row(c.g('✓'), 'refreshed', r.refreshed, c.g);
+  row(c.cy('+'), 'created', r.created, c.cy);
+  row(c.b('~'), 'adopted', r.adopted, c.b);
+  row(c.y('!'), '.new', r.newSidecar, c.y, 'you edited these — new version saved as *.new, merge by hand');
+  if (r.unchanged.length) console.log(`  ${c.dim('·')}  ${c.dim('unchanged'.padEnd(9))} ${c.dim(String(r.unchanged.length).padStart(2))}`);
+  console.log(`  ${c.dim('=')}  ${c.dim('preserved'.padEnd(9))}      ${c.dim('config.json · workflow.md · specs/ · plans/ · your custom agents & skills')}`);
+  console.log('');
+  if (dryRun) console.log(`  ${c.dim('(dry-run — nothing was written)')}`);
+  else console.log(`  ${changed ? c.g('✓ Done') : c.dim('Already up to date')}${changed ? c.dim(` · ${changed} file(s) changed`) : ''}`);
+  if (r.newSidecar.length && !dryRun) console.log(`  ${c.y('→')} ${c.dim(`${r.newSidecar.length} *.new file(s) to review and merge`)}`);
+  console.log('');
 }
 
 // THE launch command — prints the URL clearly and won't crash on EADDRINUSE: it probes first
@@ -204,11 +218,26 @@ async function status() {
   console.log(`dashboard: ${running ? `running → http://localhost:${port}` : 'not running'}`);
 }
 
-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 [--port=NNNN]             run the local control plane (default 4319, or $SPECTOFLOW_PORT)
-  status                              print progress`);
+function version() { console.log(`spectoflow v${VERSION}`); }
+
+const help = () => console.log(`${c.bold('spectoflow')} ${c.amber('v' + VERSION)} — agent-agnostic spec-driven development
+
+${c.dim('Usage:')} spectoflow <command> [options]
+
+${c.bold('Commands:')}
+  ${c.g('init')} [dir] [--agent=claude,codex]   scaffold a project (auto-detects installed agents)
+  ${c.g('update')} [--dry-run]                  refresh framework files to this kit version
+  ${c.g('dashboard')} [--port=NNNN]             run the local control plane (default 4319, or $SPECTOFLOW_PORT)
+  ${c.g('status')}                              print progress + whether the dashboard is running
+
+${c.bold('Options:')}
+  -v, --version                       print the version
+  -h, --help                          show this help
+
+${c.dim('Docs:')} https://github.com/georgesmomo/spectoflow`);
 
-const fns = { init, update, dashboard, status, help };
-fns[cmd] ? fns[cmd]() : help();
+const fns = { init, update, dashboard, status, help, version };
+if (['-v', '-V', '--version', 'version'].includes(cmd)) version();
+else if (['-h', '--help'].includes(cmd)) help();
+else if (fns[cmd]) fns[cmd]();
+else help();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectoflow",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Agent-agnostic spec-driven development framework + real-time local control plane. Markdown artifacts, intent router, workflow-by-scope.",
   "keywords": [
     "spec-driven-development",