spectoflow 0.17.5 → 0.19.0

package/templates/dashboard/public/i18n.js

@@ -107,6 +107,11 @@ en: {
   'task.failingPassing':'{f} failing, {p} passing','task.comments':'Comments','task.noComments':'No comments.',
   'task.addCommentPlaceholder':'Add a comment, a remark, feedback…',
   'task.toAnalyzeHint':'"To analyze" moves the task back so the agent picks it up next round.',
+  'customize.title':'Customize','customize.sub':'Add project-specific dashboards, skills and agents — describe what you want, or let Auto propose candidates from this project.',
+  'customize.dashboards':'Dashboards','customize.skills':'Skills','customize.agents':'Agents',
+  'customize.add.dashboard':'Add dashboard','customize.add.skill':'Add skill','customize.add.agent':'Add agent',
+  'customize.empty.dashboard':'No custom dashboards yet.','customize.empty.skill':'No custom skills yet.','customize.empty.agent':'No custom agents yet.',
+  'customize.describePh':'Describe what you want…','customize.auto':'Auto','customize.generate':'Generate','customize.blocksSub':'block(s)',
 },
 fr: {
   'nav.board':'Tableau','nav.requests':'Demandes','nav.attention':'Attention','nav.backlog':'Backlog',
@@ -197,6 +202,11 @@ fr: {
   'task.failingPassing':'{f} en échec, {p} réussi(s)','task.comments':'Commentaires','task.noComments':'Aucun commentaire.',
   'task.addCommentPlaceholder':'Ajouter un commentaire, une remarque, un retour…',
   'task.toAnalyzeHint':'« À analyser » renvoie la tâche pour que l’agent la reprenne au tour suivant.',
+  'customize.title':'Personnaliser','customize.sub':'Ajoutez des dashboards, compétences et agents propres au projet — décrivez ce que vous voulez, ou laissez Auto proposer des pistes à partir de ce projet.',
+  'customize.dashboards':'Dashboards','customize.skills':'Compétences','customize.agents':'Agents',
+  'customize.add.dashboard':'Ajouter un dashboard','customize.add.skill':'Ajouter une compétence','customize.add.agent':'Ajouter un agent',
+  'customize.empty.dashboard':'Aucun dashboard personnalisé pour l’instant.','customize.empty.skill':'Aucune compétence personnalisée pour l’instant.','customize.empty.agent':'Aucun agent personnalisé pour l’instant.',
+  'customize.describePh':'Décrivez ce que vous voulez…','customize.auto':'Auto','customize.generate':'Générer','customize.blocksSub':'bloc(s)',
 },
 es: {
   'nav.board':'Tablero','nav.requests':'Solicitudes','nav.attention':'Atención','nav.backlog':'Backlog',
@@ -287,6 +297,11 @@ es: {
   'task.failingPassing':'{f} fallando, {p} superadas','task.comments':'Comentarios','task.noComments':'Sin comentarios.',
   'task.addCommentPlaceholder':'Añade un comentario, una observación, feedback…',
   'task.toAnalyzeHint':'«Por analizar» devuelve la tarea para que el agente la retome en la siguiente ronda.',
+  'customize.title':'Personalizar','customize.sub':'Añade dashboards, habilidades y agentes propios del proyecto — describe lo que quieres, o deja que Auto proponga candidatos a partir de este proyecto.',
+  'customize.dashboards':'Dashboards','customize.skills':'Habilidades','customize.agents':'Agentes',
+  'customize.add.dashboard':'Añadir dashboard','customize.add.skill':'Añadir habilidad','customize.add.agent':'Añadir agente',
+  'customize.empty.dashboard':'Aún no hay dashboards personalizados.','customize.empty.skill':'Aún no hay habilidades personalizadas.','customize.empty.agent':'Aún no hay agentes personalizados.',
+  'customize.describePh':'Describe lo que quieres…','customize.auto':'Auto','customize.generate':'Generar','customize.blocksSub':'bloque(s)',
 },
 de: {
   'nav.board':'Board','nav.requests':'Anfragen','nav.attention':'Hinweise','nav.backlog':'Backlog',
@@ -377,6 +392,11 @@ de: {
   'task.failingPassing':'{f} fehlgeschlagen, {p} bestanden','task.comments':'Kommentare','task.noComments':'Keine Kommentare.',
   'task.addCommentPlaceholder':'Kommentar, Anmerkung oder Feedback hinzufügen…',
   'task.toAnalyzeHint':'„Zu analysieren“ gibt die Aufgabe zurück, damit der Agent sie in der nächsten Runde aufgreift.',
+  'customize.title':'Anpassen','customize.sub':'Fügen Sie projektspezifische Dashboards, Skills und Agenten hinzu — beschreiben Sie, was Sie wollen, oder lassen Sie Auto Kandidaten aus diesem Projekt vorschlagen.',
+  'customize.dashboards':'Dashboards','customize.skills':'Skills','customize.agents':'Agenten',
+  'customize.add.dashboard':'Dashboard hinzufügen','customize.add.skill':'Skill hinzufügen','customize.add.agent':'Agent hinzufügen',
+  'customize.empty.dashboard':'Noch keine eigenen Dashboards.','customize.empty.skill':'Noch keine eigenen Skills.','customize.empty.agent':'Noch keine eigenen Agenten.',
+  'customize.describePh':'Beschreiben Sie, was Sie wollen…','customize.auto':'Auto','customize.generate':'Generieren','customize.blocksSub':'Block/Blöcke',
 },
 pt: {
   'nav.board':'Painel','nav.requests':'Pedidos','nav.attention':'Atenção','nav.backlog':'Backlog',
@@ -467,6 +487,11 @@ pt: {
   'task.failingPassing':'{f} a falhar, {p} bem-sucedido(s)','task.comments':'Comentários','task.noComments':'Sem comentários.',
   'task.addCommentPlaceholder':'Adicione um comentário, uma observação, feedback…',
   'task.toAnalyzeHint':'«Por analisar» devolve a tarefa para o agente a retomar na ronda seguinte.',
+  'customize.title':'Personalizar','customize.sub':'Adicione dashboards, habilidades e agentes específicos do projeto — descreva o que quer, ou deixe o Auto propor candidatos a partir deste projeto.',
+  'customize.dashboards':'Dashboards','customize.skills':'Habilidades','customize.agents':'Agentes',
+  'customize.add.dashboard':'Adicionar dashboard','customize.add.skill':'Adicionar habilidade','customize.add.agent':'Adicionar agente',
+  'customize.empty.dashboard':'Ainda sem dashboards personalizados.','customize.empty.skill':'Ainda sem habilidades personalizadas.','customize.empty.agent':'Ainda sem agentes personalizados.',
+  'customize.describePh':'Descreva o que quer…','customize.auto':'Auto','customize.generate':'Gerar','customize.blocksSub':'bloco(s)',
 },
 it: {
   'nav.board':'Bacheca','nav.requests':'Richieste','nav.attention':'Attenzione','nav.backlog':'Backlog',
@@ -557,6 +582,11 @@ it: {
   'task.failingPassing':'{f} falliti, {p} superati','task.comments':'Commenti','task.noComments':'Nessun commento.',
   'task.addCommentPlaceholder':'Aggiungi un commento, un’osservazione, un feedback…',
   'task.toAnalyzeHint':'«Da analizzare» rimanda l’attività così l’agente la riprende al giro successivo.',
+  'customize.title':'Personalizza','customize.sub':'Aggiungi dashboard, skill e agenti specifici del progetto — descrivi cosa vuoi, oppure lascia che Auto proponga candidati a partire da questo progetto.',
+  'customize.dashboards':'Dashboard','customize.skills':'Skill','customize.agents':'Agenti',
+  'customize.add.dashboard':'Aggiungi dashboard','customize.add.skill':'Aggiungi skill','customize.add.agent':'Aggiungi agente',
+  'customize.empty.dashboard':'Ancora nessuna dashboard personalizzata.','customize.empty.skill':'Ancora nessuna skill personalizzata.','customize.empty.agent':'Ancora nessun agente personalizzato.',
+  'customize.describePh':'Descrivi cosa vuoi…','customize.auto':'Auto','customize.generate':'Genera','customize.blocksSub':'blocco/i',
 },
 };
 

package/templates/dashboard/public/index.html

@@ -4,19 +4,19 @@
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>spectoflow · control</title>
-  <link rel="icon" type="image/png" href="logo-dark.png" />
-  <link rel="icon" type="image/png" media="(prefers-color-scheme: dark)" href="logo-white.png" />
-  <link rel="stylesheet" href="styles.css" />
-  <link rel="stylesheet" href="designs/console.css" />
-  <link rel="stylesheet" href="designs/orbit.css" />
+  <link rel="icon" type="image/png" href="/logo-dark.png" />
+  <link rel="icon" type="image/png" media="(prefers-color-scheme: dark)" href="/logo-white.png" />
+  <link rel="stylesheet" href="/styles.css" />
+  <link rel="stylesheet" href="/designs/console.css" />
+  <link rel="stylesheet" href="/designs/orbit.css" />
 </head>
 <body>
   <header class="topbar">
     <div class="brand">
       <button class="nav-toggle" id="navToggle" data-i18n-aria="topbar.navToggle" aria-label="Toggle menu" aria-expanded="false"><span></span><span></span><span></span></button>
       <a class="brand-logo" href="/board" data-route="board" aria-label="spectoflow home">
-        <img class="brand-logo-img is-dark" src="logo-white.png" alt="spectoflow" />
-        <img class="brand-logo-img is-light" src="logo-dark.png" alt="spectoflow" />
+        <img class="brand-logo-img is-dark" src="/logo-white.png" alt="spectoflow" />
+        <img class="brand-logo-img is-light" src="/logo-dark.png" alt="spectoflow" />
       </a>
       <div class="brand-text">
         <div class="brand-line">
@@ -257,6 +257,14 @@
           <div class="settings-saved" id="settingsSaved" data-i18n="settings.saved" hidden>✓ saved</div>
         </div>
         <div class="settings-readonly" id="settingsReadonly"></div>
+
+        <!-- Customize: project-specific dashboards, skills and agents — described or auto-proposed,
+             generated by the configured agent through the same Run/Chat pipeline as any other ask. -->
+        <div class="cz-wrap">
+          <h2 class="panel-title" data-i18n="customize.title">Customize</h2>
+          <p class="panel-sub" data-i18n="customize.sub">Add project-specific dashboards, skills and agents — describe what you want, or let Auto propose candidates from this project.</p>
+          <div id="czRoot"></div>
+        </div>
       </div>
     </section>
   </main>
@@ -264,8 +272,8 @@
   <footer class="app-footer">
     <div class="footer-left">
       <a class="footer-logo" href="/board" data-route="board" aria-label="spectoflow">
-        <img class="brand-logo-img is-dark" src="logo-white.png" alt="spectoflow" />
-        <img class="brand-logo-img is-light" src="logo-dark.png" alt="spectoflow" />
+        <img class="brand-logo-img is-dark" src="/logo-white.png" alt="spectoflow" />
+        <img class="brand-logo-img is-light" src="/logo-dark.png" alt="spectoflow" />
       </a>
       <span class="footer-name">spectoflow</span>
       <span class="footer-ver" id="footerVer"></span>
@@ -323,13 +331,13 @@
     </defs>
   </svg>
 
-  <script src="stats.js"></script>
-  <script src="charts.js"></script>
-  <script src="icons.js"></script>
-  <script src="designs.js"></script>
-  <script src="i18n.js"></script>
-  <script src="app.js"></script>
-  <script src="designs/console.js"></script>
-  <script src="designs/orbit.js"></script>
+  <script src="/stats.js"></script>
+  <script src="/charts.js"></script>
+  <script src="/icons.js"></script>
+  <script src="/designs.js"></script>
+  <script src="/i18n.js"></script>
+  <script src="/app.js"></script>
+  <script src="/designs/console.js"></script>
+  <script src="/designs/orbit.js"></script>
 </body>
 </html>

package/templates/dashboard/public/styles.css

@@ -557,6 +557,33 @@ body.booting .ring-svg circle:last-of-type { transform-origin:center; animation:
 .settings-ro-k { color:var(--muted); font-size:13px; }
 .settings-ro-v { font-family:var(--mono); font-size:12.5px; color:var(--ink); }
 
+/* ---- Customize (Settings → dashboards/skills/agents) — reuses .card/.chat-ta/.btn styling so it
+   reads as part of the same system, not a bolted-on sub-app. ---- */
+.cz-wrap { margin-top:28px; }
+.cz-block { background:var(--surface); border:1px solid var(--line); border-radius:var(--radius); padding:14px 16px; margin-top:12px; }
+.cz-head { display:flex; align-items:center; justify-content:space-between; gap:12px; }
+.cz-head h3 { margin:0; font-size:13.5px; font-weight:700; }
+.cz-add { font-size:12.5px; padding:6px 13px; }
+.cz-add[aria-expanded="true"] { background:var(--signal); color:var(--on-accent); border-color:transparent; }
+.cz-list { display:flex; flex-direction:column; gap:6px; margin-top:10px; }
+.cz-list .empty { padding:10px 2px; font-size:12.5px; color:var(--muted); }
+.cz-item { display:flex; align-items:baseline; gap:10px; padding:8px 10px; border-radius:8px; cursor:pointer; transition:background .15s; }
+.cz-item:hover, .cz-item:focus-visible { background:var(--surface-2); outline:none; }
+.cz-item-title { font-size:13px; font-weight:600; }
+.cz-item-sub { font-size:11.5px; color:var(--muted); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.cz-form { margin-top:12px; padding-top:12px; border-top:1px solid var(--line); display:flex; flex-direction:column; gap:10px; }
+.cz-form .chat-ta { min-height:64px; }
+.cz-form-actions { display:flex; align-items:center; gap:8px; flex-wrap:wrap; }
+.cz-form-actions .chat-agent { flex-shrink:0; }
+
+/* ---- Custom dashboard pages (Customize → generate-dashboard) — every block below is one of the
+   dashboard's own existing components (.ocard/.kpi-row/.stat-tiles/.flatlist/table), so a generated
+   page needs no page-specific CSS: it inherits the active design automatically. ---- */
+.custom-dash-wrap { display:flex; flex-direction:column; gap:14px; }
+.custom-dash-body { display:flex; flex-direction:column; gap:14px; }
+.cd-markdown { background:var(--surface); border:1px solid var(--line); border-radius:var(--radius); padding:16px 18px; font-size:13.5px; line-height:1.6; }
+.cd-markdown :first-child { margin-top:0; }
+
 /* App footer — professional, always at the bottom of the content */
 .app-footer { display:flex; align-items:center; justify-content:space-between; gap:16px; flex-wrap:wrap; padding:14px 22px; border-top:1px solid var(--line); background:var(--surface); color:var(--muted); font-size:12.5px; }
 .footer-left { display:flex; align-items:center; gap:9px; }

package/templates/dashboard/server.js

@@ -70,7 +70,13 @@ function promoteAttention(item){
 }
 
 function watch(dir){ try{ fs.watch(dir,{recursive:false},()=>emit({type:'change'})); }catch(_){} }
-['plans','specs','.spectoflow'].forEach(d=>{ const p=path.join(ROOT,d); if(fs.existsSync(p)) watch(p); });
+// Custom dashboards (Customize page) live in their own subdirectory of .spectoflow, which the
+// top-level `.spectoflow` watch below does NOT cover — fs.watch here is non-recursive on purpose
+// (a recursive watch on the whole .spectoflow tree would also fire on every runtime.json write).
+// Ensure the directory exists before watching it: a project that hasn't used Customize yet won't
+// have it on disk, and `spectoflow init` on an older install won't have created it either.
+try { fs.mkdirSync(path.join(ROOT,'.spectoflow','dashboard','custom'), { recursive: true }); } catch (_) {}
+['plans','specs','.spectoflow','.spectoflow/dashboard/custom'].forEach(d=>{ const p=path.join(ROOT,d); if(fs.existsSync(p)) watch(p); });
 
 // A process restart loses any in-flight orchestration; without this, a stale 'running' or
 // 'awaiting_approval' status wedges the /api/orchestrate 409 guard forever. Not a real

package/templates/lib/custom-dashboard.js

@@ -0,0 +1,76 @@
+'use strict';
+/*
+ * Pure helpers for user-generated custom dashboards (.spectoflow/dashboard/custom/<id>.json).
+ *
+ * A custom dashboard is a DECLARATIVE block spec, never raw HTML/CSS/JS: the generating agent picks
+ * blocks from a fixed vocabulary (BLOCK_TYPES) that the dashboard already knows how to render, using
+ * the exact same token-driven components (kpi cards, bars, donut, tables…) the built-in Board uses.
+ * That is what guarantees a custom dashboard always matches the active design — including any design
+ * the user switches to later — with zero per-dashboard styling to keep in sync, and no arbitrary code
+ * ever running in the dashboard.
+ *
+ * Zero dependency; consumed by templates/dashboard/server.js (Node) via readCustomDashboards() in
+ * store.js. The browser-side renderer (dashboard/public/app.js) re-implements the tiny `resolveBind`
+ * walk independently — sharing code across the Node/browser boundary would need a build step, which
+ * this project avoids on purpose (see CLAUDE.md's zero-runtime-dependency invariant).
+ */
+
+// Every block a generated dashboard may use. Adding a new type here is how the vocabulary grows —
+// pair it with a matching case in app.js's renderCustomBlock().
+const BLOCK_TYPES = new Set([
+  'markdown',       // rendered prose — a spec excerpt, an explanation, a summary
+  'kpi-row',        // a row of big-number stat cards, each optionally live-bound
+  'chart-bars',      // horizontal progress/comparison bars
+  'chart-donut',     // a status/category breakdown donut + legend
+  'table',           // a simple column/row data table
+  'list',            // a flat bullet list
+  'stat-tile-row',   // a row of compact stat tiles (value/label/sub)
+]);
+
+// A small, explicit allow-list of live data paths a block may `bind` to, resolved against the same
+// stats object SpectoStats.stats(P) already computes for the built-in Board — never an arbitrary
+// expression, just a dotted property walk, so there is nothing to sandbox or evaluate.
+// Mirrors the exact shape SpectoStats.stats(P) returns (dashboard/public/stats.js):
+// { total, done, pct, byStatus, phases, toAsk, running, statuses }.
+const BIND_ROOTS = new Set(['pct', 'done', 'total', 'byStatus', 'phases', 'toAsk', 'running', 'statuses']);
+
+const ID_RE = /^[a-z][a-z0-9-]{0,39}$/;
+
+// A conservative, curated icon key set — the same ICON map the rest of the dashboard already uses
+// (icons.js), so a custom dashboard's tab never introduces a one-off, unstyled icon.
+const ICON_KEYS = new Set(['board', 'requests', 'backlog', 'workflow', 'agents', 'chat', 'info', 'attention', 'settings']);
+
+function isPlainObject(v) { return v != null && typeof v === 'object' && !Array.isArray(v); }
+
+// Validates one block. Returns a list of error strings (empty = valid). Deliberately permissive on
+// the *content* fields (labels, values, markdown text are free text) — it only enforces the block's
+// *shape* (a known type, and that any `bind` path starts from an allowed root) so a slightly unusual
+// but well-typed spec still renders rather than being rejected outright.
+function validateBlock(b, i) {
+  const errs = [];
+  const at = `blocks[${i}]`;
+  if (!isPlainObject(b)) { errs.push(`${at} is not an object`); return errs; }
+  if (!BLOCK_TYPES.has(b.type)) errs.push(`${at}.type "${b.type}" is not a known block type (${[...BLOCK_TYPES].join(', ')})`);
+  const binds = [];
+  if (typeof b.bind === 'string') binds.push(b.bind);
+  if (Array.isArray(b.items)) b.items.forEach((it) => { if (it && typeof it.bind === 'string') binds.push(it.bind); });
+  if (Array.isArray(b.rows)) b.rows.forEach((r) => { if (r && typeof r.bind === 'string') binds.push(r.bind); });
+  if (Array.isArray(b.segments)) b.segments.forEach((s) => { if (s && typeof s.bind === 'string') binds.push(s.bind); });
+  binds.forEach((p) => { const root = String(p).split('.')[0]; if (!BIND_ROOTS.has(root)) errs.push(`${at} has an unbound bind path "${p}" (must start with one of: ${[...BIND_ROOTS].join(', ')})`); });
+  return errs;
+}
+
+// Validates a whole dashboard spec as read from disk. Never throws — callers (store.js) should skip
+// an invalid file rather than let one bad custom dashboard break the whole /api/project response.
+function validateSpec(spec) {
+  const errors = [];
+  if (!isPlainObject(spec)) return { valid: false, errors: ['not an object'] };
+  if (!ID_RE.test(String(spec.id || ''))) errors.push('id must be lowercase kebab-case, starting with a letter, 1-40 chars');
+  if (!spec.title || typeof spec.title !== 'string') errors.push('title is required (a short display name)');
+  if (spec.icon != null && !ICON_KEYS.has(spec.icon)) errors.push(`icon "${spec.icon}" is not one of: ${[...ICON_KEYS].join(', ')}`);
+  if (!Array.isArray(spec.blocks) || !spec.blocks.length) errors.push('blocks must be a non-empty array');
+  else spec.blocks.forEach((b, i) => errors.push(...validateBlock(b, i)));
+  return { valid: errors.length === 0, errors };
+}
+
+module.exports = { BLOCK_TYPES, BIND_ROOTS, ICON_KEYS, validateSpec, validateBlock };

package/templates/lib/customize-prompts.js

@@ -0,0 +1,34 @@
+'use strict';
+// Builds the exact natural-language prompts the dashboard's Settings → Customize UI posts to
+// /api/run (see templates/dashboard/public/app.js's CZ_KINDS) — the single source of truth so the
+// CLI (`spectoflow skill/agent/dashboard create`) and the dashboard button never drift apart. The
+// browser side can't require this Node module (no build step), so its literal strings are mirrored
+// there by hand; test/customize-prompts.test.js guards against the two falling out of sync.
+const PROMPTS = {
+  dashboard: {
+    add: (d) => `Add a custom dashboard: ${d}`,
+    auto: 'Propose dashboard candidates for this project (Auto customize)',
+  },
+  skill: {
+    add: (d) => `Create a new skill: ${d}`,
+    auto: 'Propose skill candidates for this project (Auto customize)',
+  },
+  agent: {
+    add: (d) => `Create a new agent: ${d}`,
+    auto: 'Propose agent candidates for this project (Auto customize)',
+  },
+};
+
+// buildCustomizePrompt('skill', { description: 'reviews PRs for accessibility' })
+// buildCustomizePrompt('skill', { auto: true })
+function buildCustomizePrompt(kind, opts) {
+  const p = PROMPTS[kind];
+  if (!p) throw new Error(`Unknown customize kind "${kind}" (expected dashboard, skill or agent).`);
+  const o = opts || {};
+  if (o.auto) return p.auto;
+  const d = o.description && String(o.description).trim();
+  if (!d) throw new Error('A description is required unless --auto is passed.');
+  return p.add(d);
+}
+
+module.exports = { PROMPTS, buildCustomizePrompt };

package/templates/lib/store.js

@@ -17,6 +17,7 @@
  */
 const fs = require('fs');
 const path = require('path');
+const { validateSpec } = require('./custom-dashboard');
 
 // ---- task line parsing -------------------------------------------------------
 // - [ ] T-012 Title here @owner ~level %status
@@ -226,6 +227,23 @@ function readWorkflow(projectRoot) {
   } catch { return []; }
 }
 
+// ---- user-generated custom dashboards (.spectoflow/dashboard/custom/<id>.json) --------------
+// One JSON file per custom dashboard page (see lib/custom-dashboard.js for the block schema this
+// validates against). A malformed file is skipped, never thrown — one bad custom dashboard must
+// never take down the whole /api/project response.
+function readCustomDashboards(projectRoot) {
+  const dir = path.join(projectRoot, '.spectoflow', 'dashboard', 'custom');
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.json')).sort()) {
+    try {
+      const spec = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+      if (validateSpec(spec).valid) out.push(spec);
+    } catch { /* skip malformed */ }
+  }
+  return out;
+}
+
 // ---- unified read for the dashboard -----------------------------------------
 function readProject(projectRoot) {
   const config = readConfig(projectRoot);
@@ -235,6 +253,7 @@ function readProject(projectRoot) {
   const specs = readSpecs(projectRoot);
   const agents = listMd(path.join(projectRoot, '.spectoflow', 'agents'));
   const skills = listSkills(path.join(projectRoot, '.spectoflow', 'skills'));
+  const customDashboards = readCustomDashboards(projectRoot);
 
   // Write-guarded snapshot: readProject is polled continuously by the dashboard (and reacts to
   // fs.watch on .spectoflow). Recording unconditionally on every read would rewrite runtime.json
@@ -260,7 +279,7 @@ function readProject(projectRoot) {
     runtime = writeRuntime(projectRoot, cur);
   }
 
-  return { config, plans, specs, workflow, agents, skills, runtime };
+  return { config, plans, specs, workflow, agents, skills, runtime, customDashboards };
 }
 function frontmatter(text) {
   const m = String(text).replace(/\r\n?/g, '\n').match(/^---\n([\s\S]*?)\n---/);
@@ -274,12 +293,17 @@ function parseFlatList(raw) {
   if (!raw) return [];
   return String(raw).replace(/[[\]]/g, '').split(',').map((s) => s.trim()).filter(Boolean);
 }
+// `origin: user-generated` in a file's front-matter (written by generate-skill/generate-agent, see
+// templates/skills/generate-skill and generate-agent) marks it as created through the Customize page
+// rather than shipped by the framework — the dashboard's Customize section uses this `custom` flag to
+// list only the user's own additions, distinct from the framework-shipped roster.
+const isCustomOrigin = (fm) => fm.origin === 'user-generated';
 function listMd(dir) {
   if (!fs.existsSync(dir)) return [];
   return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).map((f) => {
     const fm = frontmatter(fs.readFileSync(path.join(dir, f), 'utf8'));
     return { file: f, name: fm.name || f.replace(/\.md$/, ''), title: fm.title || fm.name || f, capability: fm.capability || '', description: fm.description || '',
-      standards: parseFlatList(fm.standards), uses: parseFlatList(fm.uses) };
+      standards: parseFlatList(fm.standards), uses: parseFlatList(fm.uses), custom: isCustomOrigin(fm) };
   });
 }
 function listSkills(dir) {
@@ -288,7 +312,7 @@ function listSkills(dir) {
     const sk = path.join(dir, e.name, 'SKILL.md');
     const fm = fs.existsSync(sk) ? frontmatter(fs.readFileSync(sk, 'utf8')) : {};
     return { name: fm.name || e.name, description: fm.description || '', capability: fm.capability || '',
-      inputs: fm.inputs || '', outputs: fm.outputs || '', standard: fm.standard || '' };
+      inputs: fm.inputs || '', outputs: fm.outputs || '', standard: fm.standard || '', custom: isCustomOrigin(fm) };
   });
 }
 function readAgents(projectRoot) {
@@ -298,7 +322,7 @@ function readAgents(projectRoot) {
     const fm = frontmatter(fs.readFileSync(path.join(dir, f), 'utf8'));
     return { name: fm.name || f.replace(/\.md$/, ''), capability: fm.capability || null,
       title: fm.title || '', description: fm.description || '',
-      standards: parseFlatList(fm.standards), uses: parseFlatList(fm.uses) };
+      standards: parseFlatList(fm.standards), uses: parseFlatList(fm.uses), custom: isCustomOrigin(fm) };
   });
 }
 function readSkills(projectRoot) {
@@ -308,5 +332,5 @@ function readSkills(projectRoot) {
 module.exports = {
   parseTaskLine, buildTaskLine, parsePlan, readPlans, readSpecs, updateTaskLine, addTaskComment,
   readRuntime, writeRuntime, parseAgentLine, appendMessage, readConfig, readWorkflow, readProject,
-  readAgents, readSkills, recordSnapshot, resolvePlansDir, resolveSpecsDir,
+  readAgents, readSkills, readCustomDashboards, recordSnapshot, resolvePlansDir, resolveSpecsDir,
 };

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

@@ -0,0 +1,135 @@
+---
+name: generate-agent
+description: Turn a description (or an auto-analysis) into a new agent persona, grounded in real named methods and matching the framework's gold-standard shape.
+capability: customization
+inputs: A description of the role needed (from the Customize page or chat), or a chosen candidate from propose-customizations; the project's existing agents as worked examples.
+outputs: A new .spectoflow/agents/<slug>.md matching docs/agents-skills-standard.md's shape, listed in the dashboard's Agents & Skills tab on the next tick.
+standard: docs/agents-skills-standard.md gold-standard shape
+---
+# Generate agent
+
+Turn a described role into a real agent persona — a stable team member with a clear mandate, named
+operating standards, and guardrails, that reads like it shipped with the framework's own roster.
+
+## When to use
+
+Whenever the user asks (from the Customize page, or directly in chat) to **add an agent** — "I want a
+data-migration specialist", "add an accessibility reviewer", "create an agent for API contract
+reviews" — or when `propose-customizations` proposed an agent candidate the user picked.
+
+## Method
+
+### 1. Clarify before generating
+
+A one-line ask ("add a data agent") is under-specified. Use `.spectoflow/skills/clarify`'s reflex —
+one targeted question at a time, each with a recommended default — until you know:
+- **What this role owns that no existing agent already owns.** Read `.spectoflow/agents/*.md` first —
+  a new agent for a capability an existing one already covers is redundant; either the existing agent
+  should gain a skill instead (see `generate-skill`), or this really is a distinct capability.
+- **Which capability it serves.** Pick the closest match from `.spectoflow/capabilities.md`'s palette,
+  or note that this genuinely needs a new capability name (rare — most real needs fit the existing
+  palette; propose adding to the palette only when nothing fits).
+- **What skill(s) it runs.** An agent without at least one skill in `uses` has no procedure to
+  execute — either an existing skill fits, or this request also needs `generate-skill` (sequence the
+  two: skill first, so the agent's `uses` list is accurate from the start).
+
+### 2. Remember the agent/skill split
+
+Per the framework's own core invariant: **agents are stable personas (the who); skills are the
+evolving procedures (the how).** This agent's file should describe *who* the role is and what it's
+accountable for — the actual step-by-step method belongs in its skill(s), referenced via `uses`, not
+duplicated here. An agent file heavy with procedural detail has blurred the split; move that content
+into a skill instead.
+
+### 3. Ground the operating standards in named, real methods
+
+Per `docs/agents-skills-standard.md`, `## Operating standards` names **cited methods**, each with a
+one-line *why* — the same discipline every shipped agent already follows (open a couple as worked
+examples: `qa-engineer` cites Kent Beck's TDD and Meszaros's xUnit Test Patterns; `security-engineer`
+cites OWASP ASVS and the Top 10; `architect` cites C4 and ADRs). Identify the real, current, named
+authority for this role's domain the same way `generate-skill`'s Method (step 2 there) describes —
+verify it with your environment's research tools rather than relying purely on memory for a
+fast-moving domain, and if no real standard exists for the role's specific angle, say so explicitly
+and reason from first principles instead of fabricating a citation.
+
+### 4. Write the agent in the gold-standard shape
+
+Follow `docs/agents-skills-standard.md`'s agent shape exactly:
+
+```yaml
+---
+name: <slug>
+title: <Team title>
+capability: <the palette capability chosen in step 1>
+uses: [<skill-slug>, ...]
+description: <one line>
+standards: [<named method or source>, ...]
+---
+# <Title>
+<1-2 line intro naming the persona and the capability it serves>
+
+## Mandate
+<who/why, 1-2 lines — what this role owns>
+
+## Operating standards
+<named, cited methods this role applies, each with a one-line why — from step 3>
+
+## Definition of done
+<concrete, checkable exit criteria for this role's contribution>
+
+## Handoff
+<what it produces and to whom — feeds the group-chat identity + orchestrator>
+
+## Guardrails
+<what it must never do — ties to .spectoflow/policy.md where relevant>
+
+## References
+<the real, verified sources from step 3, as titled links>
+```
+
+### 5. Mark it as user-generated
+
+Add `origin: user-generated` to the front-matter (an extra key — never remove or rename the required
+ones: `name`, `title`, `capability`, `uses`, `description`). This is how the dashboard's Customize
+page distinguishes what the user added from the shipped roster; omitting it hides the agent from that
+list.
+
+### 6. Resolve capability collisions explicitly
+
+`.spectoflow/AGENTS.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
+capability with no way to tell which runs.
+
+## Output contract
+
+- One file: `.spectoflow/agents/<slug>.md`, matching the gold-standard shape, with
+  `origin: user-generated` in its front-matter.
+- Progress and completion reported to the orchestrator and group chat:
+
+```
+::spectoflow role=customization kind=progress msg=Drafting agent "<title>" (capability <capability>)
+::spectoflow role=customization kind=need msg=<what's missing, e.g. no skill yet for this agent to use>
+::spectoflow role=customization kind=done msg=Agent "<title>" added — see it in Agents & Skills
+```
+
+## Quality bar
+
+- [ ] Front-matter matches the gold-standard shape exactly, plus `origin: user-generated`.
+- [ ] Body has exactly the five required `##` headings, in order.
+- [ ] `uses` lists at least one real, existing (or just-generated) skill — never an empty list.
+- [ ] `## Operating standards` names real, verified, cited methods — or explicitly says none exist for
+      this angle and reasons from first principles instead. Never a fabricated citation.
+- [ ] No capability collision left unresolved (step 6) — or the `priority` tie-break is explicit and
+      explained to the user.
+- [ ] The role is genuinely distinct from every existing agent — not a duplicate the user could have
+      gotten by adding a skill to one that already exists.
+- [ ] If the ask was ambiguous, it was clarified one question at a time before any file was written.
+
+## References
+
+- `docs/agents-skills-standard.md` — the gold-standard shape this agent's output must match exactly.
+- Any shipped agent under `.spectoflow/agents/` (e.g. `qa-engineer`, `security-engineer`,
+  `spec-source-guardian`) — worked examples of real citation density in `## Operating standards`.
+- `.spectoflow/capabilities.md` — the capability palette a new agent's `capability` must fit.