spectoflow 0.27.1 → 0.27.2

package/README.md

@@ -117,7 +117,14 @@ 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.
+an existing `AGENTS.md` or `GEMINI.md` is kept as-is and gets a short, delimited spectoflow section
+appended (`<!-- spectoflow:start -->` … `<!-- spectoflow:end -->`) pointing to `.spectoflow/AGENTS.md` —
+`spectoflow update` adds it too to a project installed before that; existing `plans/*.md` tasks are given
+stable ids.
+
+**Two `AGENTS.md`, on purpose.** The one at your project root is a thin pointer, in the place each agent
+reads natively. The real brain (intent router, workflow, rules) is `.spectoflow/AGENTS.md`, owned by the
+framework and refreshed by `spectoflow update`.
 
 ## Update
 
@@ -186,9 +193,65 @@ spectoflow dashboard                     # → http://localhost:4319 (or --port=
 dashboard already running on the port). `spectoflow status` tells you whether one is up. Zero
 dependencies, updates live via SSE + file watching.
 
-Want your own hosted, online dashboard instead of (or alongside) the local one? `server/` is a
-separate, self-hostable relay with a ready-made Docker deployment path — see
-[`server/docs/deploy-vps.md`](server/docs/deploy-vps.md).
+### One hub, every project
+
+There is only ever **one dashboard process on your machine**, no matter how many projects you have.
+`spectoflow dashboard`, run from *any* initialized project, does two things: it registers that
+project, and it makes sure the hub is running — starting it if it's the first one to ask, or simply
+joining an already-running hub otherwise. So the very first `spectoflow dashboard` you ever run
+starts the hub; every one after that (from other projects) just adds a card to the same page.
+
+```
+  $ spectoflow dashboard              (in todo-list-v2/)
+      no hub found → starts one → http://localhost:4319
+                                          │
+                                          └── card: "todo-list-v2"
+
+  $ spectoflow dashboard              (in my-other-app/, later, or another day)
+      hub already running → just joins it
+                                          │
+                                          └── card: "my-other-app"
+
+  → open http://localhost:4319 in your browser: both projects, one page
+```
+
+That's the whole local setup — no login, no token, nothing to configure. **The rest of this section
+is entirely optional.**
+
+### Going online (optional): local hub vs. relay server
+
+`spectoflow dashboard login/publish` are for one specific, separate need: opening a project's
+dashboard from **another device**, or sharing it with someone else. They talk to `server/` — a
+different application in this repo, not part of the local hub — that you (or someone) hosts
+somewhere reachable (see [`server/docs/deploy-vps.md`](server/docs/deploy-vps.md), or run it
+locally to try it, per [`server/README.md`](server/README.md)). Nothing about your local hub changes;
+it grows one extra, optional connection outward:
+
+```
+  YOUR MACHINE                                    THE RELAY SERVER (server/)
+  local hub · localhost:4319                      hosted by you or someone else
+
+  [todo-list-v2]   ── published ──────────────►    only "published" projects
+  [my-other-app]   ── NOT published, stays local    ever show up here
+
+           ▲
+           │  one-time, per machine:
+           │  $ spectoflow dashboard login --url=<relay-url> --token=<spf_…>
+           │
+     the token is minted ON THE RELAY, not by you:
+     $ node server/cli.js token create   (run by whoever administers it)
+
+  once logged in and published → any browser, anywhere, can open it
+```
+
+| Command | Runs where | What it does |
+| --- | --- | --- |
+| `spectoflow dashboard` | your machine | start/join the local hub, register the current project |
+| `node server/cli.js token create` | on the relay server | mint a login token for a machine |
+| `spectoflow dashboard login --url=… --token=…` | your machine | link this machine to that relay (once) |
+| `spectoflow dashboard publish` | your machine | make the *current* project visible through the relay |
+| `spectoflow dashboard unpublish` | your machine | take it back offline |
+| `spectoflow dashboard logout` | your machine | unlink the machine entirely |
 
 The header bar always shows the brand, the **active agent**, autonomy mode, language, a global-progress
 meter, a sync dot, and a **Run** quick-action. Thirteen tabs — and **which ones you see, and in what

package/bin/spectoflow.js

@@ -133,7 +133,7 @@ async function update() {
   const r = require('../lib/update').runUpdate({ projectRoot: root, templatesDir: TPL, version: VERSION, dryRun, force });
 
   const from = r.fromVersion || 'unknown';
-  const changed = r.refreshed.length + r.created.length + r.adopted.length + r.newSidecar.length + r.forced.length + r.removed.length + r.migration.movedViews.length;
+  const changed = r.refreshed.length + r.created.length + r.adopted.length + r.newSidecar.length + r.forced.length + r.removed.length + r.migration.movedViews.length + r.pointers.length;
   const row = (sym, label, list, painter, note) => {
     if (!list.length) return;
     const n = c.dim(String(list.length).padStart(2));
@@ -150,6 +150,7 @@ async function update() {
   row(c.y('!'), '.new', r.newSidecar, c.y, 'you edited these — new version saved as *.new, merge by hand (or re-run with --force)');
   row(c.dim('−'), 'removed', r.removed, c.dim, 'no longer part of the kit (the dashboard lives in the spectoflow package now)');
   row(c.y('!'), 'kept', r.kept, c.y, 'you modified these and they are no longer part of the kit — delete them yourself when ready');
+  row(c.cy('+'), 'linked', r.pointers, c.cy, `${r.pointers.join(', ')} existed without a pointer — a spectoflow section was appended`);
   if (r.migration.movedViews.length) console.log(`  ${c.cy('→')}  ${c.cy('views'.padEnd(9))} ${c.dim(String(r.migration.movedViews.length).padStart(2))}   ${c.dim('custom views moved to .spectoflow/dashboards/')}`);
   r.migration.conflicts.forEach((f) => console.log(`  ${c.y('!')}  ${c.y('conflict'.padEnd(9))}      ${c.dim(`dashboards/${f} already exists — the old copy stays in dashboard/custom/ for you to merge`)}`));
   if (r.legacyLeftovers.length) console.log(`  ${c.y('!')}  ${c.dim('this project has no install manifest, so nothing was deleted. Safe to remove by hand: ' + r.legacyLeftovers.map((p) => '.spectoflow/' + p).join(', '))}`);
@@ -611,7 +612,8 @@ const HELP = {
   ${c.dim('copilot, amazon-q, droid, auggie, goose, kimi')}) and writes their entry shims; override
   with ${c.g('--agent=claude,codex')}. Also wires ${c.bold('Playwright MCP')} into the project's
   ${c.dim('.mcp.json')} (idempotent — never touches an existing entry).
-  ${c.dim('An existing CLAUDE.md is preserved as CLAUDE.md.tomerge for you to merge on first run.')}
+  ${c.dim('An existing CLAUDE.md is preserved as CLAUDE.md.tomerge for you to merge on first run;')}
+  ${c.dim('an existing AGENTS.md/GEMINI.md is kept and gets a spectoflow pointer section appended.')}
   ${c.dim('Full list with docs links: the dashboard\'s Documentation tab, or the README.')}`,
   update: `${c.bold('spectoflow update')} ${c.dim('[--dry-run] [--force|-f]')}\n
   Refresh framework-owned files (engine, default agents & skills, AGENTS.md, policy…)

package/lib/adapters.js

@@ -224,24 +224,51 @@ const REGISTRY = [
 
 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);
+// Root memory files an agent loads natively. A project often already has one (AGENTS.md is shared
+// by most tools and usually team-maintained), so we never replace it: we append a delimited pointer
+// section instead, otherwise the agent reading it would never be told spectoflow exists.
+const MEMORY_FILES = ['AGENTS.md', 'GEMINI.md', 'CLAUDE.md'];
+const POINTER_START = '<!-- spectoflow:start -->';
+const POINTER_END = '<!-- spectoflow:end -->';
+const POINTER_BLOCK = `${POINTER_START}\n${ROOT_AGENTS_MD.replace(/^# .*\n/, '## spectoflow\n').trimEnd()}\n${POINTER_END}\n`;
+
+const hasPointer = (text) => text.includes('.spectoflow/AGENTS.md');
+
+function appendPointer(fp, dryRun) {
+  const text = fs.readFileSync(fp, 'utf8');
+  if (hasPointer(text)) return false;
+  if (!dryRun) fs.writeFileSync(fp, text.replace(/\s*$/, '') + '\n\n' + POINTER_BLOCK);
   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.
+// codex/cursor) are handled once. A memory file that already exists gets the pointer appended.
 function generate(projectRoot, agents) {
   const list = (agents && agents.length ? agents : ['claude', 'codex']).map(byId).filter(Boolean);
-  const written = [];
+  const written = [], appended = [];
   for (const a of list) {
     for (const e of a.entries) {
-      if (writeIfAbsent(path.join(projectRoot, e.path), e.content)) written.push(e.path);
+      if (written.includes(e.path) || appended.includes(e.path)) continue;
+      const fp = path.join(projectRoot, e.path);
+      if (!fs.existsSync(fp)) {
+        fs.mkdirSync(path.dirname(fp), { recursive: true });
+        fs.writeFileSync(fp, e.content);
+        written.push(e.path);
+      } else if (MEMORY_FILES.includes(e.path) && appendPointer(fp)) {
+        appended.push(e.path);
+      }
     }
   }
-  return written;
+  return { written, appended };
+}
+
+// For `update`: an already-installed project whose existing memory files never got the pointer.
+// Only repairs files that exist — never creates one for an agent the project may not use.
+function ensurePointers(projectRoot, dryRun = false) {
+  return MEMORY_FILES.filter((rel) => {
+    const fp = path.join(projectRoot, rel);
+    return fs.existsSync(fp) && appendPointer(fp, dryRun);
+  });
 }
 
 // { id: runner } defaults for the given agents — used to seed config.runners at init.
@@ -260,4 +287,4 @@ function knownAgents() {
   return REGISTRY.map((a) => ({ id: a.id, label: a.label, bin: a.detect.bin, dirs: a.detect.dirs || [], runner: a.runner, headless: a.headless, docsUrl: a.docsUrl }));
 }
 
-module.exports = { generate, defaultRunners, REGISTRY, knownAgents };
+module.exports = { generate, ensurePointers, defaultRunners, REGISTRY, knownAgents };

package/lib/init.js

@@ -99,7 +99,8 @@ function runInit({ target, templatesDir, version, agentsArg, defaults }) {
   const added = normalizePlans(target, cfg);
   if (added) notes.push(`Normalized ${added} existing task(s) with stable ids.`);
 
-  const written = adapters.generate(target, agents);
+  const { written, appended } = adapters.generate(target, agents);
+  appended.forEach((f) => notes.push(`Existing ${f} kept — a spectoflow section was appended to it so your agent finds .spectoflow/AGENTS.md.`));
 
   const mcpTargets = [path.join(target, '.mcp.json')];
   if (agents.includes('cursor')) mcpTargets.push(path.join(target, '.cursor', 'mcp.json'));

package/lib/update.js

@@ -17,6 +17,7 @@ const fs = require('fs');
 const path = require('path');
 const ownership = require('./ownership');
 const manifest = require('./manifest');
+const adapters = require('./adapters');
 
 function toDisk(sf, rel) {
   return path.join(sf, rel.split('/').join(path.sep));
@@ -81,6 +82,7 @@ function runUpdate({ projectRoot, templatesDir, version, dryRun = false, force =
     kept: [],
     migration: null,
     legacyLeftovers: [],
+    pointers: [],
   };
   const baseline = (prev && prev.files) || {};
   const nextFiles = {}; // manifest to write after this run
@@ -145,6 +147,8 @@ function runUpdate({ projectRoot, templatesDir, version, dryRun = false, force =
     for (const rel of LEGACY_LEFTOVERS) if (fs.existsSync(toDisk(sf, rel))) report.legacyLeftovers.push(rel);
   }
 
+  report.pointers = adapters.ensurePointers(projectRoot, dryRun);
+
   if (!dryRun) manifest.writeManifest(sf, { version, files: nextFiles });
   return report;
 }

package/package.json

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