spectoflow 0.27.1 → 0.28.0

package/README.md

@@ -117,12 +117,21 @@ 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/SPECTOFLOW.md` —
+`spectoflow update` adds it too to a project installed before that; existing `plans/*.md` tasks are given
+stable ids.
+
+**Entry files vs. the brain.** `CLAUDE.md`, `AGENTS.md` and `GEMINI.md` at your project root are thin
+pointers, in the place each agent reads natively. The real brain (intent router, workflow, rules) is
+`.spectoflow/SPECTOFLOW.md`, owned by the framework and refreshed by `spectoflow update`. (Before 0.28 it
+was named `.spectoflow/AGENTS.md`, easy to confuse with the root one — `update` renames it, keeping any
+edits you made, and rewrites the old path in your entry files.)
 
 ## Update
 
 `init` is idempotent (it never overwrites), so it can't refresh an installed project. `spectoflow
-update` refreshes **framework-owned** files (engine, `AGENTS.md`, `capabilities.md`, `policy.md`,
+update` refreshes **framework-owned** files (engine, `SPECTOFLOW.md`, `capabilities.md`, `policy.md`,
 default agents & skills) to the CLI's version — retiring the project's own vendored dashboard folder
 along the way for anyone updating from before v0.24 — while **preserving your work** —
 `config.json`, `workflow.md`, `specs/`, `plans/`, and any agent/skill you created or edited are never
@@ -186,9 +195,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
@@ -290,7 +355,7 @@ INVEST, Playwright E2E, Conventional Commits, and more — not generic one-liner
 ### Clarify before acting
 
 spectoflow is an **expert analyst, not an order-taker**. When a request is vague ("login displays
-badly, users can't sign in"), an always-on **Clarify reflex** — in the agent's memory (`AGENTS.md`)
+badly, users can't sign in"), an always-on **Clarify reflex** — in the agent's memory (`SPECTOFLOW.md`)
 and backed by the `clarify` skill — reflects it back and asks **one targeted question at a time**,
 each with a recommendation anchored in the project's goals and best practices, until the need is
 crisp; then it runs the normal workflow. It's additive: it feeds the router, never replaces it, and

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.appended.length + r.pointers.repointed.length + r.migration.repointedUserFiles.length + (r.migration.renamedBrain ? 1 : 0);
   const row = (sym, label, list, painter, note) => {
     if (!list.length) return;
     const n = c.dim(String(list.length).padStart(2));
@@ -150,6 +150,9 @@ 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');
+  if (r.migration.renamedBrain) console.log(`  ${c.cy('→')}  ${c.cy('renamed'.padEnd(9))} ${c.dim(' 1')}   ${c.dim('.spectoflow/AGENTS.md → .spectoflow/SPECTOFLOW.md (the brain; your edits, if any, came along)')}`);
+  row(c.cy('→'), 'repointed', [...r.pointers.repointed, ...r.migration.repointedUserFiles.map((f) => '.spectoflow/' + f)], c.cy, null);
+  row(c.cy('+'), 'linked', r.pointers.appended, c.cy, `${r.pointers.appended.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,10 +614,11 @@ 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…)
+  Refresh framework-owned files (engine, default agents & skills, SPECTOFLOW.md, policy…)
   to this CLI's version, ${c.bold('preserving your work')}: config.json, workflow.md, specs/, plans/
   and any agent/skill you edited are never overwritten (an edited file's new version lands as
   ${c.dim('*.new')} for you to merge). ${c.g('--dry-run')} previews without writing.

package/lib/adapters.js

@@ -1,6 +1,6 @@
 'use strict';
 /*
- * Per-agent adapters. The canonical brain is .spectoflow/AGENTS.md. Each agent needs a thin entry
+ * Per-agent adapters. The canonical brain is .spectoflow/SPECTOFLOW.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/…)
@@ -14,7 +14,7 @@ const path = require('path');
 
 const CLAUDE_MD = `# CLAUDE.md — spectoflow
 
-This project uses **spectoflow**. **Read \`.spectoflow/AGENTS.md\` and follow it** as your operating
+This project uses **spectoflow**. **Read \`.spectoflow/SPECTOFLOW.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
@@ -23,7 +23,7 @@ instructions (intent router, workflow, standing rules).
 
 **Be an expert analyst, not an order-taker.** When a request is ambiguous, **clarify before acting**:
 reflect it back and ask **one targeted question at a time** (each with a recommendation) until the need
-is clear — then execute. See the Clarify reflex in \`.spectoflow/AGENTS.md\`.
+is clear — then execute. See the Clarify reflex in \`.spectoflow/SPECTOFLOW.md\`.
 
 - Command: \`/spectoflow\` (\`init\` / \`status\` / or just a request).
 - Dashboard: \`spectoflow dashboard\` → http://localhost:4319
@@ -32,30 +32,30 @@ is clear — then execute. See the Clarify reflex in \`.spectoflow/AGENTS.md\`.
 
 const ROOT_AGENTS_MD = `# AGENTS.md — spectoflow
 
-This project uses **spectoflow**. **Read \`.spectoflow/AGENTS.md\` and follow it** as your operating
+This project uses **spectoflow**. **Read \`.spectoflow/SPECTOFLOW.md\` and follow it** as your operating
 instructions. Artifacts are markdown in \`specs/\` and \`plans/\`; the workflow is \`.spectoflow/workflow.md\`.
 
 **Be an expert analyst, not an order-taker.** When a request is ambiguous, **clarify before acting**:
 reflect it back and ask **one targeted question at a time** (each with a recommendation) until the need
-is clear — then execute. See the Clarify reflex in \`.spectoflow/AGENTS.md\`.
+is clear — then execute. See the Clarify reflex in \`.spectoflow/SPECTOFLOW.md\`.
 `;
 
 const GEMINI_MD = `# GEMINI.md — spectoflow
 
-This project uses **spectoflow**. **Read \`.spectoflow/AGENTS.md\` and follow it** as your operating
+This project uses **spectoflow**. **Read \`.spectoflow/SPECTOFLOW.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\`.
 
 **Be an expert analyst, not an order-taker.** When a request is ambiguous, **clarify before acting**:
 reflect it back and ask **one targeted question at a time** (each with a recommendation) until the need
-is clear — then execute. See the Clarify reflex in \`.spectoflow/AGENTS.md\`.
+is clear — then execute. See the Clarify reflex in \`.spectoflow/SPECTOFLOW.md\`.
 `;
 
 const SLASH_CMD = `---
 description: spectoflow — spec-driven control (init / status / or just a request)
 ---
 
-Read \`.spectoflow/AGENTS.md\` and \`.spectoflow/config.json\` first.
+Read \`.spectoflow/SPECTOFLOW.md\` and \`.spectoflow/config.json\` first.
 
 Argument: \`$ARGUMENTS\`
 
@@ -63,7 +63,7 @@ Argument: \`$ARGUMENTS\`
   \`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\`.
+- otherwise: treat \`$ARGUMENTS\` as a request and run the Router in \`.spectoflow/SPECTOFLOW.md\`.
 `;
 
 // Priority order = which agent becomes the default when several are detected.
@@ -224,24 +224,68 @@ 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);
-  return true;
+// 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`;
+
+// The brain was `.spectoflow/AGENTS.md` before 0.28 — renamed so it can't be mistaken for the
+// project-root AGENTS.md. Pointers written back then are rewritten in place, never duplicated.
+const BRAIN = '.spectoflow/SPECTOFLOW.md';
+const LEGACY_BRAIN = '.spectoflow/AGENTS.md';
+const ENTRY_FILES = [...MEMORY_FILES, '.claude/commands/spectoflow.md'];
+
+// Bring one existing entry file up to date: rewrite a legacy pointer, then (memory files only)
+// append the pointer section if it still has none. Returns what it did (or would do, on dryRun).
+function linkEntry(fp, rel, dryRun) {
+  const before = fs.readFileSync(fp, 'utf8');
+  let text = before.split(LEGACY_BRAIN).join(BRAIN);
+  const repointed = text !== before;
+  const appended = MEMORY_FILES.includes(rel) && !text.includes(BRAIN);
+  if (appended) text = text.replace(/\s*$/, '') + '\n\n' + POINTER_BLOCK;
+  if ((repointed || appended) && !dryRun) fs.writeFileSync(fp, text);
+  return { repointed, appended };
 }
 
 // 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. An entry file that already exists is linked instead (linkEntry).
 function generate(projectRoot, agents) {
   const list = (agents && agents.length ? agents : ['claude', 'codex']).map(byId).filter(Boolean);
-  const written = [];
+  const written = [], appended = [], repointed = [], seen = new Set();
   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 (seen.has(e.path)) continue;
+      seen.add(e.path);
+      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);
+        continue;
+      }
+      const r = linkEntry(fp, e.path, false);
+      if (r.appended) appended.push(e.path);
+      if (r.repointed) repointed.push(e.path);
     }
   }
-  return written;
+  return { written, appended, repointed };
+}
+
+// For `update`: link every entry file that exists — never creates one for an agent the project may
+// not use.
+function ensurePointers(projectRoot, dryRun = false) {
+  const out = { appended: [], repointed: [] };
+  for (const rel of ENTRY_FILES) {
+    const fp = path.join(projectRoot, rel);
+    if (!fs.existsSync(fp)) continue;
+    const r = linkEntry(fp, rel, dryRun);
+    if (r.appended) out.appended.push(rel);
+    if (r.repointed) out.repointed.push(rel);
+  }
+  return out;
 }
 
 // { id: runner } defaults for the given agents — used to seed config.runners at init.
@@ -260,4 +304,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, BRAIN, LEGACY_BRAIN };

package/lib/dashboard/public/app.js

@@ -1354,7 +1354,7 @@ function renderCustomDashboards(){
 
 // ---- Settings → Customize: add dashboards/skills/agents by description, or "Auto" -------------
 // Generation itself is real agent work (research, clarify, write a file) — this UI never does it
-// client-side. It just constructs a plain-language prompt (recognized by AGENTS.md's Router, which
+// client-side. It just constructs a plain-language prompt (recognized by SPECTOFLOW.md's Router, which
 // hands it to framework-curator) and sends it through the SAME /api/run + group-chat pipeline every
 // other "Run" already uses, then jumps to Chat so the requester watches it happen and can answer any
 // clarifying question there — no separate conversational UI to build or keep in sync.

package/lib/dashboard/public/i18n.js

@@ -1,7 +1,7 @@
 'use strict';
 /*
  * Dashboard UI translations. `config.json`'s `language` governs BOTH the agent's own output (specs,
- * plans, code comments — per AGENTS.md) AND, from here, this dashboard's chrome — so picking a
+ * plans, code comments — per SPECTOFLOW.md) AND, from here, this dashboard's chrome — so picking a
  * language actually changes what you see, not just what the agent writes.
  *
  * t(key, vars?) looks up I18N[currentLang][key], falls back to I18N.en[key], then to the key itself
@@ -93,7 +93,7 @@ en: {
   'meeting.sub':'One dated note per day for this project — write it yourself, or have the active agent draft it from recent tasks and chat activity.','meeting.history':'History','meeting.today':'today','meeting.generate':'Generate','meeting.generateTitle':'Generate today\'s note from recent activity','meeting.overwriteWarn':'This will overwrite today\'s note.','meeting.generateAnyway':'Generate anyway',
   'chat.widgetTitle':'Run an agent','chat.widgetSub':'Quick access · full view in the Chat tab',
   'chat.tabSub':'Full conversation with the runner — the same run as the widget, more room to read it.',
-  'chat.idle':'Type a request — the agent runs headless in this project with full memory (<code>CLAUDE.md → AGENTS.md</code>) and updates the board live.',
+  'chat.idle':'Type a request — the agent runs headless in this project with full memory (<code>CLAUDE.md / AGENTS.md → .spectoflow/SPECTOFLOW.md</code>) and updates the board live.',
   'chat.inputPlaceholder':'e.g. Add a login feature with email + password',
   'chat.orchestrateTitle':'Walk the enabled workflow','chat.summarizeTitle':'Condense the recent activity into a summary','chat.clearTitle':'Clear the chat log',
   'chat.warn':'⚠ Launches a real agent (<code>config.json → runners</code>) that can modify files &amp; run commands.','chat.running':'Agent running…',
@@ -212,7 +212,7 @@ fr: {
   'meeting.sub':'Une note datée par jour pour ce projet — rédigez-la vous-même, ou laissez l’agent actif la rédiger à partir des tâches récentes et du chat.','meeting.history':'Historique','meeting.today':'aujourd’hui','meeting.generate':'Générer','meeting.generateTitle':'Générer la note du jour à partir de l’activité récente','meeting.overwriteWarn':'Cela va écraser la note d’aujourd’hui.','meeting.generateAnyway':'Générer quand même',
   'chat.widgetTitle':'Lancer un agent','chat.widgetSub':'Accès rapide · vue complète dans l’onglet Chat',
   'chat.tabSub':'Conversation complète avec l’exécuteur — la même exécution que le widget, avec plus de place pour la lire.',
-  'chat.idle':'Tapez une demande — l’agent s’exécute sans supervision dans ce projet avec toute sa mémoire (<code>CLAUDE.md → AGENTS.md</code>) et met le tableau à jour en direct.',
+  'chat.idle':'Tapez une demande — l’agent s’exécute sans supervision dans ce projet avec toute sa mémoire (<code>CLAUDE.md / AGENTS.md → .spectoflow/SPECTOFLOW.md</code>) et met le tableau à jour en direct.',
   'chat.inputPlaceholder':'ex. Ajouter une fonctionnalité de connexion par email + mot de passe',
   'chat.orchestrateTitle':'Parcourir le workflow activé','chat.summarizeTitle':'Condenser l’activité récente en un résumé','chat.clearTitle':'Effacer le journal de discussion',
   'chat.warn':'⚠ Lance un agent réel (<code>config.json → runners</code>) qui peut modifier des fichiers et exécuter des commandes.','chat.running':'Agent en cours d’exécution…',
@@ -331,7 +331,7 @@ es: {
   'meeting.sub':'Una nota fechada por día para este proyecto — escríbela tú mismo, o deja que el agente activo la redacte a partir de las tareas y el chat recientes.','meeting.history':'Historial','meeting.today':'hoy','meeting.generate':'Generar','meeting.generateTitle':'Generar la nota de hoy a partir de la actividad reciente','meeting.overwriteWarn':'Esto sobrescribirá la nota de hoy.','meeting.generateAnyway':'Generar de todos modos',
   'chat.widgetTitle':'Ejecutar un agente','chat.widgetSub':'Acceso rápido · vista completa en la pestaña Chat',
   'chat.tabSub':'Conversación completa con el ejecutor — la misma ejecución que el widget, con más espacio para leerla.',
-  'chat.idle':'Escribe una solicitud — el agente se ejecuta sin supervisión en este proyecto con toda su memoria (<code>CLAUDE.md → AGENTS.md</code>) y actualiza el tablero en vivo.',
+  'chat.idle':'Escribe una solicitud — el agente se ejecuta sin supervisión en este proyecto con toda su memoria (<code>CLAUDE.md / AGENTS.md → .spectoflow/SPECTOFLOW.md</code>) y actualiza el tablero en vivo.',
   'chat.inputPlaceholder':'p. ej. Añadir un inicio de sesión con email + contraseña',
   'chat.orchestrateTitle':'Recorrer el workflow activado','chat.summarizeTitle':'Condensar la actividad reciente en un resumen','chat.clearTitle':'Borrar el registro del chat',
   'chat.warn':'⚠ Lanza un agente real (<code>config.json → runners</code>) que puede modificar archivos y ejecutar comandos.','chat.running':'Agente en ejecución…',
@@ -450,7 +450,7 @@ de: {
   'meeting.sub':'Eine datierte Notiz pro Tag für dieses Projekt — schreibe sie selbst, oder lass sie vom aktiven Agenten aus den letzten Aufgaben und dem Chat entwerfen.','meeting.history':'Verlauf','meeting.today':'heute','meeting.generate':'Generieren','meeting.generateTitle':'Die heutige Notiz aus der letzten Aktivität generieren','meeting.overwriteWarn':'Dies überschreibt die heutige Notiz.','meeting.generateAnyway':'Trotzdem generieren',
   'chat.widgetTitle':'Agenten ausführen','chat.widgetSub':'Schnellzugriff · vollständige Ansicht im Chat-Tab',
   'chat.tabSub':'Vollständiges Gespräch mit dem Runner — derselbe Lauf wie im Widget, mit mehr Platz zum Lesen.',
-  'chat.idle':'Geben Sie eine Anfrage ein — der Agent läuft eigenständig in diesem Projekt mit vollem Gedächtnis (<code>CLAUDE.md → AGENTS.md</code>) und aktualisiert das Board live.',
+  'chat.idle':'Geben Sie eine Anfrage ein — der Agent läuft eigenständig in diesem Projekt mit vollem Gedächtnis (<code>CLAUDE.md / AGENTS.md → .spectoflow/SPECTOFLOW.md</code>) und aktualisiert das Board live.',
   'chat.inputPlaceholder':'z. B. Login mit E-Mail + Passwort hinzufügen',
   'chat.orchestrateTitle':'Den aktivierten Workflow durchlaufen','chat.summarizeTitle':'Die letzten Aktivitäten zu einer Zusammenfassung verdichten','chat.clearTitle':'Chat-Verlauf löschen',
   'chat.warn':'⚠ Startet einen echten Agenten (<code>config.json → runners</code>), der Dateien ändern und Befehle ausführen kann.','chat.running':'Agent läuft…',
@@ -569,7 +569,7 @@ pt: {
   'meeting.sub':'Uma nota datada por dia para este projeto — escreva-a você mesmo, ou deixe o agente ativo redigi-la a partir das tarefas e do chat recentes.','meeting.history':'Histórico','meeting.today':'hoje','meeting.generate':'Gerar','meeting.generateTitle':'Gerar a nota de hoje a partir da atividade recente','meeting.overwriteWarn':'Isto vai substituir a nota de hoje.','meeting.generateAnyway':'Gerar mesmo assim',
   'chat.widgetTitle':'Executar um agente','chat.widgetSub':'Acesso rápido · vista completa no separador Chat',
   'chat.tabSub':'Conversa completa com o executor — a mesma execução do widget, com mais espaço para ler.',
-  'chat.idle':'Escreva um pedido — o agente corre sem supervisão neste projeto com toda a sua memória (<code>CLAUDE.md → AGENTS.md</code>) e atualiza o painel em direto.',
+  'chat.idle':'Escreva um pedido — o agente corre sem supervisão neste projeto com toda a sua memória (<code>CLAUDE.md / AGENTS.md → .spectoflow/SPECTOFLOW.md</code>) e atualiza o painel em direto.',
   'chat.inputPlaceholder':'ex. Adicionar login com email + palavra-passe',
   'chat.orchestrateTitle':'Percorrer o workflow ativado','chat.summarizeTitle':'Condensar a atividade recente num resumo','chat.clearTitle':'Limpar o registo do chat',
   'chat.warn':'⚠ Inicia um agente real (<code>config.json → runners</code>) que pode alterar ficheiros e executar comandos.','chat.running':'Agente em execução…',
@@ -688,7 +688,7 @@ it: {
   'meeting.sub':'Una nota datata al giorno per questo progetto — scrivila tu stesso, oppure lascia che l’agente attivo la scriva a partire dalle attività e dalla chat recenti.','meeting.history':'Cronologia','meeting.today':'oggi','meeting.generate':'Genera','meeting.generateTitle':'Genera la nota di oggi dall’attività recente','meeting.overwriteWarn':'Questo sovrascriverà la nota di oggi.','meeting.generateAnyway':'Genera comunque',
   'chat.widgetTitle':'Avvia un agente','chat.widgetSub':'Accesso rapido · vista completa nella scheda Chat',
   'chat.tabSub':'Conversazione completa con l’esecutore — la stessa esecuzione del widget, con più spazio per leggerla.',
-  'chat.idle':'Digita una richiesta — l’agente viene eseguito senza supervisione in questo progetto con tutta la sua memoria (<code>CLAUDE.md → AGENTS.md</code>) e aggiorna la bacheca in diretta.',
+  'chat.idle':'Digita una richiesta — l’agente viene eseguito senza supervisione in questo progetto con tutta la sua memoria (<code>CLAUDE.md / AGENTS.md → .spectoflow/SPECTOFLOW.md</code>) e aggiorna la bacheca in diretta.',
   'chat.inputPlaceholder':'es. Aggiungi un login con email + password',
   'chat.orchestrateTitle':'Percorri il workflow attivato','chat.summarizeTitle':'Condensa l’attività recente in un riassunto','chat.clearTitle':'Cancella il registro della chat',
   'chat.warn':'⚠ Avvia un agente reale (<code>config.json → runners</code>) che può modificare file ed eseguire comandi.','chat.running':'Agente in esecuzione…',

package/lib/dashboard/public/index.html

@@ -318,7 +318,7 @@
         </div>
         <div class="chat-tab-log" id="chatTabLog">
           <div class="chat-idle" data-i18n-html="chat.idle">Type a request — the agent runs headless in this project with full memory
-            (<code>CLAUDE.md → AGENTS.md</code>) and updates the board live.</div>
+            (<code>CLAUDE.md / AGENTS.md → .spectoflow/SPECTOFLOW.md</code>) and updates the board live.</div>
         </div>
         <!-- Toolbar right above the input, not up in the header — this is where you're looking
              when you reach for Summarize/Clear or switch which agent the next message runs on. -->
@@ -455,7 +455,7 @@
     </div>
     <div class="chat-log" id="chatLog">
       <div class="chat-idle" data-i18n-html="chat.idle">Type a request — the agent runs headless in this project with full memory
-        (<code>CLAUDE.md → AGENTS.md</code>) and updates the board live.</div>
+        (<code>CLAUDE.md / AGENTS.md → .spectoflow/SPECTOFLOW.md</code>) and updates the board live.</div>
     </div>
     <div class="chat-toolbar">
       <button id="widgetSummarizeBtn" class="mini-btn" data-i18n-title="chat.summarizeTitle" data-i18n="action.summarize" title="Condense the recent activity into a summary">Summarize</button>

package/lib/init.js

@@ -99,7 +99,9 @@ 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, repointed } = adapters.generate(target, agents);
+  appended.forEach((f) => notes.push(`Existing ${f} kept — a spectoflow section was appended to it so your agent finds ${adapters.BRAIN}.`));
+  repointed.forEach((f) => notes.push(`${f} pointed to ${adapters.LEGACY_BRAIN} — now ${adapters.BRAIN}.`));
 
   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));
@@ -29,7 +30,7 @@ const LEGACY_LEFTOVERS = ['dashboard', 'lib/store.js', 'lib/agents-registry.js',
 // Data migration (0.23 → 0.24): custom views out of the old dashboard folder, the per-project lock
 // and its .gitignore line gone. Runs before any removal, is idempotent, and never overwrites.
 function migrateProjectData(projectRoot, sf, dryRun) {
-  const r = { movedViews: [], conflicts: [], removedLock: false, gitignoreCleaned: false };
+  const r = { movedViews: [], conflicts: [], removedLock: false, gitignoreCleaned: false, renamedBrain: false, repointedUserFiles: [] };
   const oldDir = path.join(sf, 'dashboard', 'custom'), newDir = path.join(sf, 'dashboards');
   if (fs.existsSync(oldDir)) {
     for (const f of fs.readdirSync(oldDir).filter((x) => x.endsWith('.json')).sort()) {
@@ -53,6 +54,42 @@ function migrateProjectData(projectRoot, sf, dryRun) {
   return r;
 }
 
+// 0.28: the brain `AGENTS.md` became `SPECTOFLOW.md`. Treated as a move, not "retire + create": the
+// file (edits included) and its manifest baseline follow the new name, so the normal matrix below
+// then refreshes it if untouched or offers a .new if edited. In dry-run nothing moves; `readFrom`
+// tells the matrix to read the brain from its old place instead.
+const BRAIN = 'SPECTOFLOW.md', LEGACY_BRAIN = 'AGENTS.md';
+function moveBrain(sf, templatesDir, baseline, dryRun) {
+  const kitHasBrain = fs.existsSync(toDisk(templatesDir, BRAIN)) && !fs.existsSync(toDisk(templatesDir, LEGACY_BRAIN));
+  const from = toDisk(sf, LEGACY_BRAIN), to = toDisk(sf, BRAIN);
+  if (!kitHasBrain || !fs.existsSync(from) || fs.existsSync(to)) return null;
+  if (baseline[LEGACY_BRAIN] !== undefined) { baseline[BRAIN] = baseline[LEGACY_BRAIN]; delete baseline[LEGACY_BRAIN]; }
+  if (!dryRun) fs.renameSync(from, to);
+  return { readFrom: dryRun ? from : to };
+}
+
+// Agent-read markdown the user owns (generated agents/skills) may name the old brain path. Kit files
+// are skipped: the matrix owns them, and rewriting one would make it look user-edited.
+function repointUserFiles(sf, templatesDir, dryRun) {
+  const kit = new Set(ownership.listFrameworkFiles(templatesDir));
+  const changed = [];
+  const walk = (rel) => {
+    const abs = toDisk(sf, rel);
+    if (!fs.existsSync(abs)) return;
+    for (const e of fs.readdirSync(abs, { withFileTypes: true })) {
+      const child = rel + '/' + e.name;
+      if (e.isDirectory()) { walk(child); continue; }
+      if (!e.name.endsWith('.md') || kit.has(child)) continue;
+      const fp = toDisk(sf, child), text = fs.readFileSync(fp, 'utf8');
+      if (!text.includes('.spectoflow/' + LEGACY_BRAIN)) continue;
+      changed.push(child);
+      if (!dryRun) fs.writeFileSync(fp, text.split('.spectoflow/' + LEGACY_BRAIN).join('.spectoflow/' + BRAIN));
+    }
+  };
+  walk('agents'); walk('skills');
+  return changed;
+}
+
 // Remove `fp`, then every now-empty parent up to (not including) `stop`.
 function removeAndPrune(fp, stop) {
   fs.unlinkSync(fp);
@@ -81,10 +118,13 @@ function runUpdate({ projectRoot, templatesDir, version, dryRun = false, force =
     kept: [],
     migration: null,
     legacyLeftovers: [],
+    pointers: [],
   };
-  const baseline = (prev && prev.files) || {};
+  const baseline = { ...((prev && prev.files) || {}) };
   const nextFiles = {}; // manifest to write after this run
   report.migration = migrateProjectData(projectRoot, sf, dryRun);
+  const brainMove = moveBrain(sf, templatesDir, baseline, dryRun);
+  report.migration.renamedBrain = !!brainMove;
 
   const write = (fp, buf) => {
     if (dryRun) return;
@@ -95,7 +135,7 @@ function runUpdate({ projectRoot, templatesDir, version, dryRun = false, force =
   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 diskPath = rel === BRAIN && brainMove ? brainMove.readFrom : toDisk(sf, rel);
     const base = baseline[rel]; // undefined for legacy / brand-new files
 
     if (!fs.existsSync(diskPath)) {
@@ -145,6 +185,9 @@ 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);
+  report.migration.repointedUserFiles = repointUserFiles(sf, templatesDir, 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.28.0",
   "description": "Agent-agnostic spec-driven development framework + real-time local control plane. Markdown artifacts, intent router, workflow-by-scope.",
   "keywords": [
     "spec-driven-development",

package/templates/README.md

@@ -7,17 +7,17 @@ workflow, and tracks everything as **markdown artifacts** you can diff and own.
 
 Everything the framework needs lives here in `.spectoflow/`, so your project root stays clean and the
 framework is swappable/updatable. Your per-agent entry files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`)
-sit at the project root and just point back here.
+sit at the project root and just point back to `SPECTOFLOW.md`, here.
 
 ## How you use it
 
 - **Just say what you want** to your agent ("add a login feature", "fix T-042"). The router in
-  `AGENTS.md` classifies it (quick / standard / major), gates it by your **mode** and **policy**, and
+  `SPECTOFLOW.md` classifies it (quick / standard / major), gates it by your **mode** and **policy**, and
   runs the matching workflow — no ceremonial command.
 - **When your ask is vague, it clarifies first.** spectoflow behaves like an expert analyst, not an
   order-taker: on an ambiguous request ("login displays badly") it reflects it back and asks **one
   targeted question at a time** (each with a recommendation) until the need is crisp, then executes
-  (skill `clarify`, wired into the agent's memory in `AGENTS.md`).
+  (skill `clarify`, wired into the agent's memory in `SPECTOFLOW.md`).
 - **Watch it live** in the dashboard (it starts in the background and hands the prompt back):
   ```
   spectoflow dashboard          # → http://localhost:4319
@@ -58,7 +58,7 @@ Your **artifacts are markdown, and they live at the project root, not in here**:
 
 | Path | What it is |
 |------|------------|
-| `AGENTS.md` | **The brain** — the intent router, the modes, and the standing rules your agent follows. |
+| `SPECTOFLOW.md` | **The brain** — the intent router, the modes, and the standing rules your agent follows. |
 | `workflow.md` | The **single** workflow definition (the pipeline steps and their capability/skill). |
 | `capabilities.md` | The capability palette (intake, analysis, planning, implementation, testing, quality, security, governance…) and how it adapts to the project type. |
 | `policy.md` | **Non-negotiable gates** — actions that need explicit human approval regardless of mode (prod deploy, destructive migration, security change, spend, source-of-truth drift at done/Major). |

package/templates/{AGENTS.md → SPECTOFLOW.md}

@@ -1,7 +1,7 @@
 # spectoflow — project brain (read fully at session start)
 
-> Agent-agnostic. Any agent reading this — Claude Code (`CLAUDE.md` points here), Codex/Cursor
-> (`AGENTS.md`), etc. — knows how to behave. Keep it lean; details live in the files it points to.
+> Agent-agnostic. Any agent reading this — Claude Code (`CLAUDE.md` points here), Codex/Cursor and most
+> others (the project-root `AGENTS.md` points here), etc. — knows how to behave. Keep it lean; details live in the files it points to.
 
 ## What spectoflow is
 

package/templates/capabilities.md

@@ -12,7 +12,7 @@ surfaces drift to the Attention tab; it gates only at `done`/Major (see `policy.
 `clarify` is a **reflex under `intake`, not a workflow step** either: on *any* ambiguous request the
 agent reflects it back and asks **one targeted question at a time** (each with a recommendation) until
 the need is crisp, then proceeds — it feeds the workflow, never replaces it. See `skills/clarify` and
-the Clarify step in `AGENTS.md`.
+the Clarify step in `SPECTOFLOW.md`.
 
 `customization` is also **not a workflow step** — it is triggered explicitly, either from the
 dashboard's Settings → Customize page or by a direct request ("add a dashboard for…", "create a skill

package/templates/skills/clarify/SKILL.md

@@ -10,7 +10,7 @@ standard: requirements elicitation
 
 Turn a vague request into a crisp, agreed need **before** classifying or acting — the way a good
 analyst does: reflect, ask the sharpest question, listen, repeat. This is a **reflex**, always in the
-agent's memory (see the Clarify step in `AGENTS.md`), not a workflow stage — it fires on *any*
+agent's memory (see the Clarify step in `SPECTOFLOW.md`), not a workflow stage — it fires on *any*
 request, including bug reports and change requests on an existing project ("the login page doesn't
 display well, users can't sign in").
 

package/templates/skills/generate-agent/SKILL.md

@@ -96,7 +96,7 @@ list.
 
 ### 6. Resolve capability collisions explicitly
 
-`.spectoflow/AGENTS.md`'s routing assumes one agent per capability unless a `priority` is set (see the
+`.spectoflow/SPECTOFLOW.md`'s routing assumes one agent per capability unless a `priority` is set (see the
 front-matter rules in `docs/agents-skills-standard.md`). If the chosen capability already has an
 agent, either pick a different, more precise capability for this role, or set `priority` deliberately
 and tell the user which agent now wins ties — never leave two agents silently competing for the same