spectoflow 0.17.5 → 0.18.0

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/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.

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

@@ -0,0 +1,152 @@
+---
+name: generate-dashboard
+description: Turn a description (or an auto-analysis) into a new custom dashboard page, as a declarative block spec that automatically matches every design the dashboard ships.
+capability: customization
+inputs: A description of what the dashboard should show (from the Customize page or chat), or a chosen candidate from propose-customizations; the project's specs/plans/code as source material.
+outputs: A validated block-spec JSON file at .spectoflow/dashboard/custom/<id>.json, live in the dashboard's nav on the next tick.
+standard: declarative UI generation; Few's dashboard design principles
+---
+# Generate dashboard
+
+Turn a described need into a new dashboard page for *this* project — added to the dashboard's own
+navigation, rendered by the dashboard's own components, so it looks and behaves like it shipped with
+the framework, not like a plugin bolted on.
+
+## When to use
+
+Whenever the user asks (from the Customize page, or directly in chat) to **add a dashboard** —
+"I want a dashboard that shows my architecture", "add a page tracking API endpoint coverage", "show me
+a dashboard of open security findings" — or when `propose-customizations` proposed a dashboard
+candidate the user picked.
+
+## Method
+
+### 1. Never generate raw markup — only the declarative block vocabulary
+
+The dashboard renders a custom page from a **JSON block spec**, using the exact same components the
+built-in Board uses (`kpiCard`, `ocard`, `bars`, `donut`, a table builder, `mdLite` for markdown —
+see `dashboard/public/app.js`). This is not a stylistic preference: it is the mechanism that makes the
+result correct.
+
+- Every block type is styled entirely through the active design's CSS custom properties
+  (`--signal`, `--surface`, `--line`, `--s-done`, …). Nothing in a block spec ever sets a literal
+  color, font, radius, or shadow.
+- Because of that, a dashboard generated under one design (say, the default Spectral Console) renders
+  correctly, unmodified, under every other shipped design (Orbit, Control Room, Obsidian Ops, Neon
+  Command, Mission Control) — including any the user switches to **after** this dashboard was
+  generated. There is nothing design-specific to regenerate or maintain.
+- It is also the safety boundary: a block spec is data, never executable code, so nothing this skill
+  writes can run arbitrary script in the user's dashboard.
+
+**Never** write HTML, CSS, or JS for a custom dashboard, and never suggest doing so "for more
+flexibility" — if the vocabulary genuinely can't express what's needed, say so explicitly (raise a
+`need`) rather than stepping outside it.
+
+### 2. Clarify before generating
+
+A one-line ask ("add a dashboard for my project") is under-specified — you don't yet know what it
+should show. Use `.spectoflow/skills/clarify`'s reflex: reflect the ask back, then ask one targeted
+question at a time, each with a recommended default, until you know:
+- **What it should show** (which data/content — an architecture overview, security posture, a
+  specific spec's status, custom KPIs…).
+- **Static or live.** Does it need to update as the project changes (task counts, phase progress), or
+  is a point-in-time snapshot the actual intent (e.g. "show my chosen architecture" — a design
+  decision doesn't change every time a task ships)?
+
+Skip clarification only when the ask is already unambiguous, or the user picked a fully-specified
+candidate from `propose-customizations`.
+
+### 3. Gather the source material
+
+Read what the dashboard needs to show from the project itself — `specs/*.md`, `plans/*.md`, ADRs,
+`.spectoflow/agents/`, `.spectoflow/skills/`, or the codebase, as the ask requires. For "my
+architecture", that typically means reading a spec/ADR that documents it and turning its structure
+into `markdown` blocks (rendered as-is) plus maybe a `list`/`table` block for components or decisions.
+For "task/security/coverage tracking", that typically means **live-bound** blocks reading the same
+computed stats the Board already uses (see step 5).
+
+### 4. Choose blocks — the vocabulary
+
+Pick from exactly these block types (anything else is invisible to the renderer — see
+`.spectoflow/lib/custom-dashboard.js` for the enforced schema):
+
+| `type` | Shape | Use for |
+|---|---|---|
+| `markdown` | `{ type, content }` — content is the markdown text to render (via the dashboard's own light markdown renderer: headings, lists, `code`, **bold**) | Explaining, documenting, an architecture write-up, a decision summary |
+| `kpi-row` | `{ type, items: [{ label, value?, bind?, sub?, color? }] }` | A row of big-number stat cards (mirrors the Board's own KPI row) |
+| `chart-bars` | `{ type, title, rows: [{ label, pct?, bind?, sub? }] }` | Progress or comparison bars (mirrors "Phase progress") |
+| `chart-donut` | `{ type, title, segments: [{ key, value?, bind?, colorVar }] }` | A status/category breakdown + legend (mirrors "Status distribution") — `colorVar` is a design token name, e.g. `--s-done`, never a literal color |
+| `table` | `{ type, title, columns: [string], rows: [[cell, ...]] }` | Structured tabular data |
+| `list` | `{ type, title, items: [string] }` | A flat bullet list |
+| `stat-tile-row` | `{ type, items: [{ value?, bind?, label, sub? }] }` | Compact stat tiles (mirrors the Info tab's counts) |
+
+Apply Stephen Few's information-dashboard discipline while choosing: **one dashboard, one purpose** —
+don't cram unrelated concerns onto the same page just because they were mentioned in the same request
+(propose two dashboards instead, or ask which matters more); prefer the plainest block that carries
+the point (a `stat-tile-row` over a `chart-donut` when there's nothing to compare); keep it scannable
+in one screen — 4-8 blocks is a healthy page, not 20.
+
+### 5. Static content vs. live bindings
+
+- **Static**: give the block its content directly (`content`, `rows`, `items`, `value` fields) —
+  baked in at generation time. This is the default, and the right choice whenever the ask is about a
+  point-in-time view (architecture, a decision record, a written summary).
+- **Live**: instead of `value`/`pct`, set `bind` to a dotted path into the same stats object the Board
+  already computes (`SpectoStats.stats(P)` — see `dashboard/public/stats.js`). Allowed roots only:
+  `pct`, `done`, `total`, `byStatus` (per-status counts, e.g. `byStatus.done`), `phases` (per-phase
+  `{title,done,total,pct}`), `toAsk` (tasks awaiting review), `running` (active agents/orchestration),
+  `statuses` (the status key list). Anything else is rejected — there is no free-form expression, only
+  this fixed, safe set of paths. Use `bind` whenever the ask is explicitly about *tracking* something
+  over time ("show my task progress", "how many findings are open").
+
+### 6. Pick an id, a title, an icon
+
+- `id`: lowercase kebab-case, unique among existing custom dashboards (list
+  `.spectoflow/dashboard/custom/*.json` first) — this becomes the URL segment and the file name.
+- `title`: short, a few words, shown as the nav tab label.
+- `icon`: one of `board`, `requests`, `backlog`, `workflow`, `agents`, `chat`, `info`, `attention`,
+  `settings` (the same set the rest of the dashboard uses — pick the closest match; default to `info`
+  when nothing fits well). An icon outside this set fails validation.
+
+### 7. Write and verify
+
+Write the spec to `.spectoflow/dashboard/custom/<id>.json` (pretty-printed, 2-space indent). Then
+**verify it, don't assume it's valid** — run:
+```
+node -e "console.log(JSON.stringify(require('./.spectoflow/lib/custom-dashboard').validateSpec(JSON.parse(require('fs').readFileSync('./.spectoflow/dashboard/custom/<id>.json','utf8')))))"
+```
+If `valid` is `false`, fix the reported errors and re-run before reporting done — a spec the
+dashboard's own validator rejects is never a finished deliverable, it would simply be skipped and the
+user would see nothing.
+
+## Output contract
+
+- One file: `.spectoflow/dashboard/custom/<id>.json`, valid against
+  `.spectoflow/lib/custom-dashboard.js`'s `validateSpec` (verified per step 7, not assumed).
+- Progress and completion reported to the orchestrator and group chat:
+
+```
+::spectoflow role=customization kind=progress msg=Drafting dashboard "<title>" — <n> blocks
+::spectoflow role=customization kind=need msg=<what's missing and why generation can't proceed>
+::spectoflow role=customization kind=done msg=Dashboard "<title>" added — open it from the nav (<id>)
+```
+
+## Quality bar
+
+- [ ] Every block's `type` is one of the seven documented types — nothing else.
+- [ ] No block, anywhere, sets a literal color/font/size — `colorVar` values are design-token names
+      (`--s-*`, `--signal`, `--cool`, …), never hex/rgb literals.
+- [ ] Every `bind` path's root is one of `pct`/`done`/`total`/`byStatus`/`phases`/`toAsk`/`running`/`statuses`.
+- [ ] The generated file passes `validateSpec` — actually run, not assumed (step 7).
+- [ ] `id` is unique, kebab-case; `icon` is one of the nine allowed keys.
+- [ ] The page has a clear, single purpose — not an unrelated grab-bag of blocks.
+- [ ] If the ask was ambiguous, it was clarified one question at a time before any file was written.
+
+## References
+
+- Stephen Few, *Information Dashboard Design* (O'Reilly/Analytics Press) — one purpose per dashboard,
+  the plainest chart that carries the point, single-screen legibility.
+  https://www.perceptualedge.com/library.php
+- `.spectoflow/lib/custom-dashboard.js` — the enforced block schema and bind allow-list (source of
+  truth; this document summarizes it, the code is authoritative).
+- `dashboard/public/stats.js` — the exact shape of the live stats object bindable via `bind`.

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

@@ -0,0 +1,153 @@
+---
+name: generate-skill
+description: Turn a description (or an auto-analysis) into a new skill file, grounded in a real, cited domain standard and matching the framework's gold-standard shape.
+capability: customization
+inputs: A description of the procedure needed (from the Customize page or chat), or a chosen candidate from propose-customizations; the project's existing skills as worked examples.
+outputs: A new .spectoflow/skills/<slug>/SKILL.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 skill
+
+Turn a described need for a new procedure into a real `SKILL.md` — one that reads like it shipped
+with the framework: grounded in a named, current, cited standard for its domain, not generic advice
+dressed up as a procedure.
+
+## When to use
+
+Whenever the user asks (from the Customize page, or directly in chat) to **add a skill** — "create a
+skill for security review grounded in OWASP", "I want a skill for accessibility audits", "add a skill
+for database migration reviews" — or when `propose-customizations` proposed a skill candidate the
+user picked.
+
+## Method
+
+### 1. Clarify before generating
+
+A one-line ask ("add a security skill") is under-specified. Use `.spectoflow/skills/clarify`'s
+reflex — one targeted question at a time, each with a recommended default — until you know:
+- **The exact procedure's scope.** "Security review" could mean a dozen different things (dependency
+  vulnerabilities? authn/authz review? secrets scanning? infra hardening?) — narrow it before writing
+  a method for the wrong one.
+- **Which capability it belongs to** — pick the closest match from `.spectoflow/capabilities.md`'s
+  palette (security, quality, architecture, testing, operations, …); propose one, don't leave it open.
+- **Who runs it** — an existing agent whose capability matches, or does this need a new agent too
+  (if so, this request also needs `generate-agent` — say so and sequence the two).
+
+### 2. Identify the real domain standard — don't skip this, and don't fabricate it
+
+This is the step that separates a real skill from a plausible-sounding one. For the procedure's
+domain, identify the **actual, named, current authority** practitioners in that field defer to, the
+same way the framework's own shipped skills already do (open a couple as worked examples —
+`write-e2e-tests` cites Playwright's own docs page-by-page; `security-review` cites OWASP ASVS and the
+OWASP Top 10; `write-adr` cites the ADR/C4 literature). Concretely:
+
+| Domain | Look for | 2026-current example anchors |
+|---|---|---|
+| Security (general) | OWASP's current flagship guides | OWASP Top 10, OWASP ASVS, OWASP Cheat Sheet Series |
+| Web app auth/session | OWASP-specific cheat sheets | Authentication/Session-Management Cheat Sheets |
+| Accessibility | The current W3C recommendation | WCAG (check the current version — 2.2 at last knowledge, verify) |
+| Architecture / ADRs | The established literature | C4 model (Simon Brown), Michael Nygard's ADR format |
+| API design | A widely-adopted style guide | Google API Design Guide, Microsoft REST API Guidelines |
+| Testing (any level) | The tool's own official docs | e.g. Playwright's own best-practices pages, not a blog summary of them |
+| Performance | Vendor/W3C measurement standards | Core Web Vitals (web.dev), the relevant runtime's own profiling docs |
+| Database/migrations | The database's own official docs + a recognized migration-safety pattern | e.g. "expand/contract" schema migration pattern |
+| Accessibility, i18n, privacy, or any domain not listed here | Whatever is genuinely the field's own authority — never a generic listicle | — |
+
+**Verify the standard is real and current before citing it** — use whatever research tool your
+environment provides (web search/fetch) to confirm the standard's name, current version, and a real
+URL; do not rely purely on training-time memory for a fast-moving domain (security guidance, W3C
+specs, and vendor docs all revise). If you cannot verify a specific standard exists for the requested
+domain, **say so explicitly and generate the method from first principles instead**, clearly flagged
+in the skill's own body as "no single authoritative standard identified; method reasoned from
+[whatever sound engineering principles apply]" — never invent a citation to fill the References
+section. A skill honestly grounded in reasoned first principles is worth more than one dressed up with
+a fabricated source.
+
+### 3. Write the skill in the gold-standard shape
+
+Follow `docs/agents-skills-standard.md`'s skill shape exactly:
+
+```yaml
+---
+name: <slug>
+description: <one line — reads as a trigger>
+capability: <the palette capability chosen in step 1>
+inputs: <what it needs>
+outputs: <what it produces>
+standard: <the named standard from step 2>
+---
+# <Skill name>
+<1-line purpose>
+
+## When to use
+<the trigger — when does the workflow, or a direct request, reach for this>
+
+## Method
+<opinionated, numbered, SOURCED procedure — this is where the domain standard actually lives, applied
+step by step, not just name-dropped in the References section>
+
+## Output contract
+<the exact artifact produced and where it's written; how progress is reported — see step 4>
+
+## Quality bar
+<a checkable checklist of what "good" looks like for this skill's output>
+
+## References
+<the real, verified sources from step 2, as titled links>
+```
+
+Match the depth and citation density of the framework's own shipped skills — a Method section that
+just says "follow best practices" has failed this step; one that names the specific technique
+(e.g. "apply OWASP ASVS V2 Authentication requirements, specifically…") has succeeded.
+
+### 4. Own the `::spectoflow` sentinel
+
+Per the gold standard's conventions: **the skill owns the exact reporting syntax** — write out real
+`::spectoflow role=<capability> kind=progress|need|done msg=…` lines in the new skill's Output
+contract, matching the pattern every other skill uses (see any shipped skill for the exact grammar).
+Do not leave this section vague or reference "the standard sentinel format" without spelling it out.
+
+### 5. Mark it as user-generated
+
+Add `origin: user-generated` to the front-matter (an extra key — never remove or rename the required
+ones). This is how the dashboard's Customize page distinguishes what the user added from what shipped
+with the framework; omitting it hides the skill from that list.
+
+### 6. Wire it up if it belongs to the workflow
+
+If the new skill is meant to run as part of the delivery pipeline (not just on-demand), tell the user
+it can be added as a step in `.spectoflow/workflow.md` (or from the dashboard's Workflow tab) — but do
+**not** edit `workflow.md` yourself without being asked; a new skill existing is not the same decision
+as it being wired into every request's pipeline.
+
+## Output contract
+
+- One file: `.spectoflow/skills/<slug>/SKILL.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=Researching the standard for "<domain>" — checking <source>
+::spectoflow role=customization kind=need msg=<what's missing, e.g. no authoritative standard found for X>
+::spectoflow role=customization kind=done msg=Skill "<slug>" added (capability <capability>) — grounded in <standard>
+```
+
+## Quality bar
+
+- [ ] Front-matter matches the gold-standard shape exactly, plus `origin: user-generated`.
+- [ ] Body has exactly the five required `##` headings, in order.
+- [ ] `## Method` names and applies a real, verified, current standard — or explicitly says none was
+      found and reasons from first principles instead. Never a fabricated citation.
+- [ ] `## References` links are real and were verified (not assumed from memory) when the domain is
+      fast-moving (security, web standards, vendor APIs).
+- [ ] The `::spectoflow` sentinel syntax is spelled out in full in the Output contract, not just
+      referenced.
+- [ ] If the ask was ambiguous, it was clarified one question at a time before any file was written.
+- [ ] `.spectoflow/workflow.md` was left untouched unless the user explicitly asked to enable this
+      skill as a pipeline step.
+
+## References
+
+- `docs/agents-skills-standard.md` — the gold-standard shape this skill's output must match exactly.
+- Any shipped skill under `.spectoflow/skills/` (e.g. `security-review`, `write-e2e-tests`,
+  `write-adr`) — worked examples of real citation density and Method-section depth to match.