spectoflow 0.14.3 → 0.16.0

package/README.md

@@ -38,13 +38,22 @@ Every command works both ways — `spectoflow <cmd>` when installed globally, or
 ### CLI
 
 ```
-spectoflow init [dir] [--agent=claude,codex]   scaffold a project (auto-detects installed agents)
+spectoflow init [dir] [--agent=claude,codex]   scaffold a project (auto-detects agents; wires Playwright MCP)
 spectoflow update [--dry-run]                  refresh framework files to this kit version
-spectoflow dashboard [--port=NNNN]             run the local control plane (default 4319)
-spectoflow dashboard stop   (or: stop)         stop the running dashboard
 spectoflow status                              progress + whether the dashboard is running
+
+spectoflow dashboard [--port=NNNN]             start the control plane in the background (hands the prompt back)
+spectoflow dashboard status                    is it running? (url + pid)
+spectoflow dashboard stop   (or: stop)         stop the running dashboard
+spectoflow dashboard restart                   stop then start
+
+spectoflow list                                agents, skills and the workflow at a glance
+spectoflow agents                              list the team personas
+spectoflow skills                              list the procedures
+spectoflow workflow                            show the enabled pipeline steps
+
 spectoflow --version   (-v)                    print the version
-spectoflow --help      (-h)                    show help
+spectoflow --help      (-h)                    show help   (append -h to any command for its help)
 ```
 
 `init` scaffolds:
@@ -158,6 +167,20 @@ runs a skill. Improve a skill without touching the agent.
 Agents and skills follow real domain standards, cited in-file — TDD, OWASP ASVS/Top 10, C4/ADR,
 INVEST, Playwright E2E, Conventional Commits, and more — not generic one-liners.
 
+**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`) 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 it's mode-aware.
+
+**End-to-end tests via Playwright MCP.** `init` idempotently wires a `playwright` entry into the target
+project's `.mcp.json` (and `.cursor/mcp.json` for Cursor) so the QA agent can drive a real browser and
+generate/run Playwright specs — `npx` fetches the server on first use, so spectoflow stays zero-dep
+(the config lives in *your* project). If the MCP isn't available, `write-e2e-tests` falls back down a
+ladder (native browser tooling → local Playwright → write the spec and raise a `need`), never faking a
+pass. The durable artifact is always the committed `*.spec.ts`.
+
 A `governance` capability adds a **Spec Source Guardian** (skill `audit-source`): it keeps the spec
 (intent) and the code/tests (reality) coherent — flagging drift in both directions, never auto-fixing,
 surfacing findings to the Attention tab, and gating only at `done`/Major. It ships with a zero-dep

package/bin/spectoflow.js

@@ -9,6 +9,7 @@ const adapters = require('../lib/adapters');
 const detect = require('../lib/detect');
 const ownership = require('../lib/ownership');
 const manifest = require('../lib/manifest');
+const mcp = require('../lib/mcp');
 
 const KIT = path.resolve(__dirname, '..');
 const TPL = path.join(KIT, 'templates');
@@ -21,6 +22,60 @@ const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
 const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
 const c = { g: paint('32'), cy: paint('36'), b: paint('34'), y: paint('33'), dim: paint('2'), bold: paint('1'), amber: paint('38;5;179') };
 
+// ---- branding ---------------------------------------------------------------
+const LOGO = [
+  '┌─┐┌─┐┌─┐┌─┐┌┬┐┌─┐┌─┐┬  ┌─┐┬ ┬',
+  '└─┐├─┘├┤ │   │ │ │├┤ │  │ ││││',
+  '└─┘┴  └─┘└─┘ ┴ └─┘┴  ┴─┘└─┘└┴┘',
+];
+const TAGLINE = 'agent-agnostic spec-driven development · real-time control plane';
+// Full logo block — for init and help (the moments a human is reading, not scripting).
+const banner = () => `\n${LOGO.map((l) => '  ' + c.amber(l)).join('\n')}\n  ${c.dim('v' + VERSION + ' · ' + TAGLINE)}\n`;
+// One-line brand — for the header of secondary command outputs.
+const brandLine = () => `${c.amber('spectoflow')} ${c.dim('v' + VERSION)}`;
+
+// ---- framework introspection (list agents / skills / workflow) --------------
+// Read from the project's .spectoflow when present, else the bundled kit — so `list` works anywhere.
+function frameworkSource() {
+  const local = path.resolve('.spectoflow');
+  return fs.existsSync(local) ? { dir: local, scope: 'project' } : { dir: TPL, scope: 'kit' };
+}
+// Tiny frontmatter reader — a few scalar keys, no YAML dependency.
+function frontmatter(file) {
+  let txt = '';
+  try { txt = fs.readFileSync(file, 'utf8'); } catch { return {}; }
+  const m = txt.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return {};
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    const mm = line.match(/^([A-Za-z_]+):\s*(.*)$/);
+    if (mm) out[mm[1]] = mm[2].replace(/^["']|["']$/g, '').trim();
+  }
+  return out;
+}
+function listAgents(dir) {
+  const d = path.join(dir, 'agents');
+  if (!fs.existsSync(d)) return [];
+  return fs.readdirSync(d).filter((f) => f.endsWith('.md')).map((f) => {
+    const fm = frontmatter(path.join(d, f));
+    return { name: fm.name || f.replace(/\.md$/, ''), capability: fm.capability || '', description: fm.description || '' };
+  }).sort((a, b) => a.name.localeCompare(b.name));
+}
+function listSkills(dir) {
+  const d = path.join(dir, 'skills');
+  if (!fs.existsSync(d)) return [];
+  return fs.readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => {
+    const fm = frontmatter(path.join(d, e.name, 'SKILL.md'));
+    return { name: fm.name || e.name, capability: fm.capability || '', description: fm.description || '' };
+  }).sort((a, b) => a.name.localeCompare(b.name));
+}
+function readWorkflowSteps(dir) {
+  let txt = '';
+  try { txt = fs.readFileSync(path.join(dir, 'workflow.md'), 'utf8'); } catch { return []; }
+  return txt.split('\n').map((l) => l.match(/^- \[([ xX])\]\s+(.+?)\s*(\{.*\})?\s*$/))
+    .filter(Boolean).map((m) => ({ on: m[1].toLowerCase() === 'x', name: m[2] }));
+}
+
 // ---- dashboard port + running-state probe ------------------------------------
 // Precedence: --port=NNNN > SPECTOFLOW_PORT env > 4319 (matches templates/dashboard/server.js).
 function resolvePort(args) {
@@ -133,6 +188,19 @@ function init() {
   // per-agent shims
   const written = adapters.generate(target, agents);
 
+  // wire Playwright MCP into the project's MCP config so the E2E agent can drive a real browser and
+  // generate/run Playwright tests. Idempotent + non-destructive: never touches an existing entry.
+  // npx fetches the server on first use, so this config IS the whole install — spectoflow stays
+  // zero-dep (this writes into the user's project, never into spectoflow).
+  const mcpTargets = [path.join(target, '.mcp.json')];
+  if (agents.includes('cursor')) mcpTargets.push(path.join(target, '.cursor', 'mcp.json'));
+  for (const fp of mcpTargets) {
+    const rel = path.relative(target, fp).split(path.sep).join('/');
+    const r = mcp.mergeMcpServer(fp, 'playwright', mcp.PLAYWRIGHT_MCP);
+    if (r === 'created' || r === 'added') notes.push(`Wired Playwright MCP into ${rel} (npx @playwright/mcp — for the E2E agent; commit it to share).`);
+    else if (r === 'skipped') notes.push(`Left ${rel} as-is (couldn't parse it) — add a 'playwright' MCP server yourself for browser-driven E2E.`);
+  }
+
   // gitignore the volatile runtime
   const gi = path.join(target, '.gitignore');
   const giText = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
@@ -140,16 +208,18 @@ function init() {
     if (!giText.includes(line)) fs.appendFileSync(gi, ((fs.existsSync(gi) && fs.readFileSync(gi, 'utf8').length) ? '\n' : '') + line + '\n');
   }
 
-  console.log('spectoflow installed in', target);
-  console.log('  .spectoflow/   framework (brain, workflow, agents, skills, policy, dashboard, config)');
-  console.log('  specs/ plans/  markdown artifacts (your source of truth)');
-  written.forEach((w) => console.log('  + ' + w));
-  notes.forEach((n) => console.log('  ! ' + n));
+  console.log(banner());
+  console.log(`${c.g('✓')} installed in ${c.bold(target)}`);
+  console.log(`  ${c.dim('.spectoflow/')}   framework — brain, workflow, agents, skills, policy, dashboard, config`);
+  console.log(`  ${c.dim('specs/ plans/')}  markdown artifacts (your source of truth)`);
+  written.forEach((w) => console.log(`  ${c.cy('+')} ${w}`));
+  notes.forEach((n) => console.log(`  ${c.y('!')} ${c.dim(n)}`));
   const port = resolvePort(argv);
-  console.log('\nNext:');
-  console.log('  1) Open your agent here — or just say what you want to build.');
-  console.log('  2) spectoflow dashboard');
-  console.log(`     → http://localhost:${port}`);
+  console.log(`\n${c.bold('Next')}`);
+  console.log(`  ${c.dim('1)')} Open your agent here — or just say what you want to build.`);
+  console.log(`  ${c.dim('2)')} ${c.g('spectoflow dashboard')}  ${c.dim('→ http://localhost:' + port)}`);
+  console.log(`  ${c.dim('3)')} ${c.g('spectoflow list')}       ${c.dim('see the agents, skills & workflow you got')}`);
+  console.log('');
 }
 
 function update() {
@@ -168,7 +238,7 @@ function update() {
     const detail = note ? c.dim(note) : c.dim(list.slice(0, 6).join(', ') + (list.length > 6 ? ` +${list.length - 6} more` : ''));
     console.log(`  ${sym}  ${painter(label.padEnd(9))} ${n}   ${detail}`);
   };
-  console.log('');
+  console.log(banner());
   console.log(`  ${c.bold('spectoflow update')}   ${c.dim(from)} ${c.amber('→')} ${c.bold(r.toVersion)}${dryRun ? c.dim('   (dry-run)') : ''}`);
   console.log('');
   row(c.g('✓'), 'refreshed', r.refreshed, c.g);
@@ -184,21 +254,55 @@ function update() {
   console.log('');
 }
 
-// THE launch command — prints the URL clearly and won't crash on EADDRINUSE: it probes first
-// and, if a dashboard is already up on that port, just reports it instead of spawning a second one.
+// THE launch command — routes the subcommands, then starts. Starting spawns the server DETACHED and
+// hands the prompt straight back (no foreground blocking), then prints the commands to drive it.
 async function dashboard() {
-  if (argv[1] === 'stop' || argv.includes('stop')) return stopDashboard();
+  const sub = argv[1];
+  if (sub === 'stop') return stopDashboard();
+  if (sub === 'status') return dashboardStatus();
+  if (sub === 'restart') return restartDashboard();
+  return startDashboard();
+}
+
+// Start in the background and return control. Probes first so a second start just reports the running
+// one instead of spawning a duplicate (and never crashes on EADDRINUSE).
+async function startDashboard() {
   const port = resolvePort(argv);
   const url = `http://localhost:${port}`;
   if (await probeDashboard(port)) {
-    console.log(`spectoflow dashboard already running → ${url}`);
-    return;
+    console.log(`${c.g('●')} dashboard already running → ${c.bold(url)}`);
+    return printDashboardCommands();
   }
   const local = path.resolve('.spectoflow', 'dashboard', 'server.js');
   const bundled = path.join(TPL, 'dashboard', 'server.js');
   const env = Object.assign({}, process.env, { SPECTOFLOW_PORT: String(port) });
-  spawn('node', [fs.existsSync(local) ? local : bundled], { stdio: 'inherit', env });
-  console.log(`spectoflow dashboard → ${url}`);
+  const child = spawn('node', [fs.existsSync(local) ? local : bundled], { detached: true, stdio: 'ignore', env });
+  child.unref();                                   // let this CLI exit while the server keeps running
+  console.log(`${c.g('✓')} dashboard started → ${c.bold(url)}  ${c.dim('(pid ' + child.pid + ')')}`);
+  printDashboardCommands();
+}
+
+function printDashboardCommands() {
+  console.log('');
+  console.log(`  ${c.dim('status ')}  ${c.g('spectoflow dashboard status')}   ${c.dim('is it up? (url + pid)')}`);
+  console.log(`  ${c.dim('stop   ')}  ${c.g('spectoflow dashboard stop')}     ${c.dim('(alias: spectoflow stop)')}`);
+  console.log(`  ${c.dim('restart')}  ${c.g('spectoflow dashboard restart')}  ${c.dim('stop then start')}`);
+  console.log('');
+}
+
+async function dashboardStatus() {
+  const port = resolvePort(argv);
+  const running = await probeDashboard(port);
+  let pid = null;
+  try { pid = JSON.parse(fs.readFileSync(path.join(process.cwd(), '.spectoflow', '.dashboard.lock'), 'utf8')).pid; } catch {}
+  if (running) console.log(`${c.g('●')} dashboard running → ${c.bold('http://localhost:' + port)}${pid ? c.dim(' (pid ' + pid + ')') : ''}`);
+  else console.log(`${c.dim('○')} dashboard not running`);
+}
+
+async function restartDashboard() {
+  await stopDashboard();
+  await new Promise((r) => setTimeout(r, 400));     // let the port free up before rebinding
+  return startDashboard();
 }
 
 // Stop the running dashboard: read the pidfile it wrote, verify it's actually up, then terminate it
@@ -245,25 +349,107 @@ async function status() {
 
 function version() { console.log(`spectoflow v${VERSION}`); }
 
-const help = () => console.log(`${c.bold('spectoflow')} ${c.amber('v' + VERSION)} — agent-agnostic spec-driven development
+// ---- explore commands -------------------------------------------------------
+function printAgents(withBrand = true) {
+  const { dir, scope } = frameworkSource();
+  const rows = listAgents(dir);
+  if (withBrand) console.log(`${brandLine()} ${c.dim('· agents (' + scope + ')')}`);
+  const w = Math.max(4, ...rows.map((r) => r.name.length));
+  rows.forEach((r) => console.log(`  ${c.g(r.name.padEnd(w))}  ${c.dim((r.capability || '').padEnd(14))} ${r.description}`));
+  if (!rows.length) console.log(c.dim('  (none found)'));
+}
+function printSkills(withBrand = true) {
+  const { dir, scope } = frameworkSource();
+  const rows = listSkills(dir);
+  if (withBrand) console.log(`${brandLine()} ${c.dim('· skills (' + scope + ')')}`);
+  const w = Math.max(4, ...rows.map((r) => r.name.length));
+  rows.forEach((r) => console.log(`  ${c.cy(r.name.padEnd(w))}  ${c.dim((r.capability || '').padEnd(14))} ${r.description}`));
+  if (!rows.length) console.log(c.dim('  (none found)'));
+}
+function printWorkflow(withBrand = true) {
+  const { dir, scope } = frameworkSource();
+  const steps = readWorkflowSteps(dir);
+  if (withBrand) console.log(`${brandLine()} ${c.dim('· workflow (' + scope + ')')}`);
+  steps.forEach((s) => console.log(`  ${s.on ? c.g('●') : c.dim('○')} ${s.on ? s.name : c.dim(s.name + '  (disabled)')}`));
+  if (!steps.length) console.log(c.dim('  (no workflow.md)'));
+}
+function listAll() {
+  const { scope } = frameworkSource();
+  console.log(banner());
+  console.log(`${c.bold('Agents')} ${c.dim('— stable team personas (' + scope + ')')}`);
+  printAgents(false);
+  console.log(`\n${c.bold('Skills')} ${c.dim('— evolving procedures')}`);
+  printSkills(false);
+  console.log(`\n${c.bold('Workflow')} ${c.dim('— enabled pipeline steps')}`);
+  printWorkflow(false);
+  console.log('');
+}
+
+// ---- help (global + per-command) --------------------------------------------
+const help = () => console.log(`${banner()}
+${c.dim('Usage:')} spectoflow ${c.g('<command>')} ${c.dim('[options]')}   ${c.dim('· append -h to any command for its help')}
+
+${c.bold('Project')}
+  ${c.g('init')} ${c.dim('[dir] [--agent=a,b]')}    scaffold a project (auto-detects agents; wires Playwright MCP)
+  ${c.g('update')} ${c.dim('[--dry-run]')}          refresh framework files to this kit version
+  ${c.g('status')}                      progress + whether the dashboard is running
 
-${c.dim('Usage:')} spectoflow <command> [options]
+${c.bold('Dashboard')}
+  ${c.g('dashboard')} ${c.dim('[--port=NNNN]')}     start the control plane in the background (default 4319)
+  ${c.g('dashboard status')}             is it running? (url + pid)
+  ${c.g('dashboard stop')}               stop it ${c.dim('(alias: stop)')}
+  ${c.g('dashboard restart')}            stop then start
 
-${c.bold('Commands:')}
-  ${c.g('init')} [dir] [--agent=claude,codex]   scaffold a project (auto-detects installed agents)
-  ${c.g('update')} [--dry-run]                  refresh framework files to this kit version
-  ${c.g('dashboard')} [--port=NNNN]             run the local control plane (default 4319, or $SPECTOFLOW_PORT)
-  ${c.g('dashboard stop')}                      stop the running dashboard (alias: ${c.g('stop')})
-  ${c.g('status')}                              print progress + whether the dashboard is running
+${c.bold('Explore')}
+  ${c.g('list')}                        agents, skills and the workflow at a glance
+  ${c.g('agents')}                      list the team personas
+  ${c.g('skills')}                      list the procedures
+  ${c.g('workflow')}                    show the enabled pipeline steps
 
-${c.bold('Options:')}
-  -v, --version                       print the version
-  -h, --help                          show this help
+${c.bold('Options')}
+  ${c.g('-v')}, ${c.g('--version')}                print the version
+  ${c.g('-h')}, ${c.g('--help')}                   show this help
 
 ${c.dim('Docs:')} https://github.com/georgesmomo/spectoflow`);
 
-const fns = { init, update, dashboard, stop: stopDashboard, status, help, version };
+// Per-command help — shown when -h/--help follows a command (e.g. `spectoflow dashboard -h`).
+const HELP = {
+  init: `${c.bold('spectoflow init')} ${c.dim('[dir] [--agent=a,b]')}\n
+  Scaffold spectoflow into <dir> (default: current directory).
+  Auto-detects installed agents (${c.dim('claude, codex, cursor, gemini')}) 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.')}`,
+  update: `${c.bold('spectoflow update')} ${c.dim('[--dry-run]')}\n
+  Refresh framework-owned files (engine, dashboard, default agents & skills, AGENTS.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.`,
+  dashboard: `${c.bold('spectoflow dashboard')} ${c.dim('[--port=NNNN] [status|stop|restart]')}\n
+  Start the local control plane in the ${c.bold('background')} (default ${c.dim('4319')} or
+  ${c.dim('$SPECTOFLOW_PORT')}) and hand the prompt back. Subcommands:
+    ${c.g('status')}    is it running? (url + pid)
+    ${c.g('stop')}      stop it            ${c.dim('(alias: spectoflow stop)')}
+    ${c.g('restart')}   stop then start`,
+  status: `${c.bold('spectoflow status')}\n
+  Print project progress from ${c.dim('plans/*.md')} (tasks done, specs, agents, skills, in-progress
+  items) and whether the dashboard is currently running.`,
+  list: `${c.bold('spectoflow list')}\n
+  Show the ${c.g('agents')}, ${c.cy('skills')} and ${c.bold('workflow')} of the current project
+  (or the bundled kit when run outside a project) at a glance.`,
+  agents: `${c.bold('spectoflow agents')}\n  List the stable team personas (name · capability · role).`,
+  skills: `${c.bold('spectoflow skills')}\n  List the evolving procedures (name · capability · what it does).`,
+  workflow: `${c.bold('spectoflow workflow')}\n  Show the pipeline steps, marking which are enabled (●) or disabled (○).`,
+  stop: `${c.bold('spectoflow stop')}\n  Stop the running dashboard (alias for ${c.g('spectoflow dashboard stop')}).`,
+};
+const showHelp = (name) => console.log('\n' + HELP[name].trim() + '\n');
+
+// ---- dispatch ---------------------------------------------------------------
+const fns = { init, update, dashboard, stop: stopDashboard, status, list: listAll, agents: () => printAgents(), skills: () => printSkills(), workflow: () => printWorkflow(), help, version };
+const wantsHelp = argv.slice(1).some((a) => a === '-h' || a === '--help');
+
 if (['-v', '-V', '--version', 'version'].includes(cmd)) version();
-else if (['-h', '--help'].includes(cmd)) help();
+else if (['-h', '--help', 'help'].includes(cmd)) help();
+else if (fns[cmd] && wantsHelp && HELP[cmd]) showHelp(cmd);
 else if (fns[cmd]) fns[cmd]();
 else help();

package/lib/adapters.js

@@ -21,6 +21,10 @@ instructions (intent router, workflow, standing rules).
 > install. Merge its project-specific content into this file, then delete \`CLAUDE.md.tomerge\`,
 > before anything else.
 
+**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\`.
+
 - Command: \`/spectoflow\` (\`init\` / \`status\` / or just a request).
 - Dashboard: \`node .spectoflow/dashboard/server.js\` → http://localhost:4319
 - Artifacts are markdown in \`specs/\` and \`plans/\`; volatile state in \`.spectoflow/runtime.json\`.
@@ -30,6 +34,10 @@ const ROOT_AGENTS_MD = `# AGENTS.md — spectoflow
 
 This project uses **spectoflow**. **Read \`.spectoflow/AGENTS.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\`.
 `;
 
 const GEMINI_MD = `# GEMINI.md — spectoflow
@@ -37,6 +45,10 @@ const GEMINI_MD = `# GEMINI.md — spectoflow
 This project uses **spectoflow**. **Read \`.spectoflow/AGENTS.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\`.
 `;
 
 const SLASH_CMD = `---

package/lib/mcp.js

@@ -0,0 +1,44 @@
+'use strict';
+/*
+ * Idempotent MCP server wiring for `spectoflow init`.
+ *
+ * MCP-capable clients (Claude Code, and others that read a project `.mcp.json`) discover MCP servers
+ * from a JSON file with an `mcpServers` map. init seeds a `playwright` entry so the E2E agent can
+ * drive a real browser and generate/run Playwright tests — WITHOUT ever touching an entry the user
+ * (or another tool) already put there. Nothing is installed globally: the server runs via `npx`,
+ * fetched on first use, so wiring this config IS the whole "install".
+ *
+ * spectoflow's own zero-runtime-dependency invariant is unaffected — this writes into the USER's
+ * project, never into spectoflow.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// The Playwright MCP server (Microsoft). npx fetches it on first use — no global install.
+const PLAYWRIGHT_MCP = { command: 'npx', args: ['@playwright/mcp@latest'] };
+
+// Merge a single MCP server into a project's MCP config file, idempotently and non-destructively.
+// Returns one of:
+//   'created' — file did not exist, created with just this server.
+//   'added'   — file existed; server inserted alongside the existing ones.
+//   'exists'  — server already present; file left exactly as-is (idempotent).
+//   'skipped' — file present but not parseable/shaped as expected; left untouched (never clobbered).
+function mergeMcpServer(filePath, name, config) {
+  if (fs.existsSync(filePath)) {
+    let doc;
+    try { doc = JSON.parse(fs.readFileSync(filePath, 'utf8')); }
+    catch { return 'skipped'; }                 // never clobber a file we can't understand
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return 'skipped';
+    const servers = doc.mcpServers && typeof doc.mcpServers === 'object' && !Array.isArray(doc.mcpServers)
+      ? doc.mcpServers : null;
+    if (servers && Object.prototype.hasOwnProperty.call(servers, name)) return 'exists';
+    doc.mcpServers = { ...(servers || {}), [name]: config };
+    fs.writeFileSync(filePath, JSON.stringify(doc, null, 2) + '\n');
+    return 'added';
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify({ mcpServers: { [name]: config } }, null, 2) + '\n');
+  return 'created';
+}
+
+module.exports = { mergeMcpServer, PLAYWRIGHT_MCP };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectoflow",
-  "version": "0.14.3",
+  "version": "0.16.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/AGENTS.md

@@ -8,6 +8,14 @@
 A spec-driven development (SDD) framework. The user speaks in **plain language**; **you classify the
 intent and run the right workflow.** Simplicity stays on the user's side — no ceremonial command to start.
 
+## Stance — expert analyst, not an order-taker
+
+You are a domain expert, not a passive executor. Reason from **two anchors at once**: the project's own
+objectives (`specs/`, `plans/`, stated goals) **and** software best practices. Advise, recommend, and
+push back when a request is unclear, risky, or contradicts the spec — always with a concrete, reasoned
+recommendation, never a bare "it depends". A framework that blindly does what it's told just ships the
+wrong thing faster; clarify and steer first, then execute.
+
 ## Language
 
 Read `.spectoflow/config.json` → `language` (default `en`). Produce **all output in that language**:
@@ -37,15 +45,26 @@ whole file. This lets the dashboard and you co-edit without clobbering. Reflect
 
 ## The Router (run internally on every request)
 
-1. **Intake** — known task ("develop T-012") → load it from `plans/*.md`. New request or tweak → classify.
-   Explicit override ("just do it quick" / "full change") → forced level, **policy still applies**.
-2. **Classify** — Quick / Standard / Major. Highest signal wins: **scope · risk/reversibility ·
+1. **Intake** — known task ("develop T-012") → load it from `plans/*.md`. New request or tweak →
+   clarify (step 2) then classify. Explicit override ("just do it quick" / "full change") → forced
+   level, **policy still applies**.
+2. **Clarify (before classifying)** — if the request is ambiguous or under-specified (a vague symptom
+   like "login doesn't work" or "displays badly", missing acceptance, several plausible readings,
+   unclear scope/users), **do not guess and do not start**. Reflect it back in one sentence, then **ask
+   ONE targeted question at a time** — each carrying your recommended default and a one-line reason —
+   wait for the answer, and if it's still unclear ask the next. Stop the moment the intent is crisp,
+   then proceed. **Never dump a block of questions at once.** Anchor every question in the project's
+   objectives and best practices, not trivia. Load `.spectoflow/skills/clarify` for the procedure.
+   This step is **additive** — it feeds the steps below, it never replaces them. Mode-aware:
+   `autopilot` states one assumption and proceeds; `semi`/`manual` clarify. "Just do it / you decide"
+   is a valid answer → proceed on explicit, recorded assumptions (policy still applies).
+3. **Classify** — Quick / Standard / Major. Highest signal wins: **scope · risk/reversibility ·
    ambiguity · novelty**. Risk can force the level up even for tiny effort.
-3. **Gate** — by `mode` (`.spectoflow/config.json`): **autopilot** proceeds · **semi** (default)
+4. **Gate** — by `mode` (`.spectoflow/config.json`): **autopilot** proceeds · **semi** (default)
    confirms if ambiguous/borderline/risky **and always for a Major** · **manual** confirms each step.
-4. **Load** — read the enabled steps from `.spectoflow/workflow.md` (single source of truth), plus the
+5. **Load** — read the enabled steps from `.spectoflow/workflow.md` (single source of truth), plus the
    `.spectoflow/skills/` needed for those steps. Load only what this task needs.
-5. **Run** — execute. A **policy gate** (`.spectoflow/policy.md`) can interrupt at any point, any mode.
+6. **Run** — execute. A **policy gate** (`.spectoflow/policy.md`) can interrupt at any point, any mode.
 
 ## New / empty project → Intake
 

package/templates/README.md

@@ -14,12 +14,20 @@ sit at the project root and just point back here.
 - **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
   runs the matching workflow — no ceremonial command.
-- **Watch it live** in the dashboard:
+- **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`).
+- **Watch it live** in the dashboard (it starts in the background and hands the prompt back):
   ```
   spectoflow dashboard          # → http://localhost:4319   (or: node .spectoflow/dashboard/server.js)
+  spectoflow dashboard status   # is it running? (url + pid)
   spectoflow dashboard stop     # stop it        (alias: spectoflow stop)
+  spectoflow dashboard restart  # stop then start
   spectoflow status             # progress + whether the dashboard is running
   ```
+- **See what you got:** `spectoflow list` (agents, skills & workflow at a glance), or `spectoflow
+  agents` / `spectoflow skills` / `spectoflow workflow`. Append `-h` to any command for its help.
 - **Change how it runs** in the dashboard's **Settings** tab (autonomy mode, output language, and the
   dashboard **design**), or by editing `config.json`.
 - **Update the framework** to a newer kit: `spectoflow update` (preserves your edits; a file you
@@ -44,7 +52,7 @@ Your **artifacts are markdown, and they live at the project root, not in here**:
 | `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). |
 | `config.json` | Your settings: `mode`, `language`, active `agent`, `runners`, `design`, plans/specs dir. **Yours to edit** — `update` never overwrites it. |
 | `agents/` | **Stable team personas** (product-manager, developer, qa-engineer, code-reviewer, spec-source-guardian…) — the *who*. |
-| `skills/` | **Evolving procedures** (write-spec, write-plan, implement, code-review, audit-source…) — the *how*. A workflow step → a capability → its agent → runs a skill. |
+| `skills/` | **Evolving procedures** (clarify, brainstorm, write-spec, write-plan, implement, write-e2e-tests, code-review, audit-source…) — the *how*. A workflow step → a capability → its agent → runs a skill. |
 | `dashboard/` | The zero-dependency control plane: `server.js` (SSE + file-watch), `runner.js`, `orchestrator.js`, and `public/` (the UI, charts, designs, fonts). |
 | `lib/` | The markdown storage engine (`store.js`) and helpers (e.g. `spec-drift.js` for the spec-source-guardian). |
 | `hooks/` | Optional Claude Code hooks you can wire in yourself (e.g. `spec-drift.js`, a `Stop` hook that surfaces source-of-truth drift to the Attention tab). |

package/templates/agents/product-manager.md

@@ -2,15 +2,17 @@
 name: product-manager
 title: Product Manager
 capability: intake
-uses: [brainstorm]
+uses: [clarify, brainstorm]
 description: Frames the need: problem, users, scope, out-of-scope.
 standards: [product discovery]
 ---
 # Product Manager
 
-Stable team persona (the "who") for the `intake` capability. The *how* lives in the `brainstorm`
-skill (see `uses`). Delegate here whenever a new need arrives and must be framed before it becomes a
-spec or a plan.
+Stable team persona (the "who") for the `intake` capability. The *how* lives in the `clarify` and
+`brainstorm` skills (see `uses`): `clarify` is the always-on reflex that turns an ambiguous request
+into a crisp, agreed need — one targeted question at a time — before anything else; `brainstorm` then
+frames that need (problem, users, scope, risks) for a new build. Delegate here whenever a new or
+unclear need arrives and must be understood before it becomes a spec or a plan.
 
 ## Mandate
 Turn a raw ask into a framed problem — problem, users, constraints, risks, success metric — before

package/templates/agents/qa-engineer.md

@@ -32,6 +32,11 @@ after-the-fact check. Owns the test suite's health (signal, speed, isolation), n
   edge cases and failure paths — not just the happy path. Prefer the fastest level (unit) that gives
   real confidence; escalate to integration or `write-e2e-tests` only when the behaviour crosses a
   boundary (network, DB, filesystem, another service) that a unit test cannot honestly exercise.
+- **For end-to-end flows, drive the browser via Playwright MCP when available** (wired into the
+  project's `.mcp.json` by `spectoflow init`), falling back down the `write-e2e-tests` capability
+  ladder (native browser tooling → local Playwright headed/codegen → write the spec and raise a
+  `need`). The committed Playwright spec is always the deliverable; live driving is only the means, and
+  a flow you couldn't actually run is reported as such, never as a pass.
 
 ## Definition of done
 Every acceptance criterion has a corresponding test, plus its meaningful edge cases (empty/null,

package/templates/capabilities.md

@@ -9,6 +9,11 @@ Palette: intake · research · analysis · architecture · planning · testing
 (skill `audit-source`) watches that the spec (intent) and the code/tests (reality) stay coherent, and
 surfaces drift to the Attention tab; it gates only at `done`/Major (see `policy.md`), never mid-edit.
 
+`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`.
+
 | Project type | Active capabilities |
 |---|---|
 | app / web / API | all |

package/templates/skills/clarify/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: clarify
+description: When a request is ambiguous, act as an analyst — reflect it back and ask one targeted question at a time (each with a recommendation) until the need is crisp, then execute.
+capability: intake
+inputs: The raw request from the user, plus the project's objectives (specs/, plans/, goals) and the mode/policy.
+outputs: A crisp, confirmed statement of the need (or explicit assumptions to proceed on), ready for classification and the normal workflow.
+standard: requirements elicitation
+---
+# Clarify
+
+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*
+request, including bug reports and change requests on an existing project ("the login page doesn't
+display well, users can't sign in").
+
+## When to use
+Whenever a request is ambiguous or under-specified and acting on it would mean guessing:
+- a **vague symptom** ("doesn't work", "displays badly", "is slow") with no observable, testable meaning;
+- **missing acceptance** — you can't yet name what "done" looks like;
+- **several plausible readings** that would lead to genuinely different work;
+- **unclear scope or users** ("everyone"? one browser? mobile only?);
+- a request that **contradicts the spec** or a best practice — clarify the intent before complying.
+
+Skip it when the request is already unambiguous and testable — over-questioning is its own failure.
+
+## Method — reflect, then one question at a time
+1. **Acknowledge, then reflect it back — warmly and naturally.** Open by showing you've taken the
+   request on board, then lead into the clarification as a way to serve it *better* — never as an
+   interrogation. Restate the request in one sentence, name the goal as you understand it, and surface
+   your assumptions so a wrong one is easy to correct. Vary the wording every time (see **Tone**);
+   never a fixed opener, never a heavy bordered form.
+2. **Ask ONE question — the highest-value one first.** The single question that most reduces
+   uncertainty about what to build. Carry **your recommended default and a one-line reason** ("I'd
+   assume the layout breaks on mobile, since that's the common case — is that it?"). Prefer a small set
+   of concrete options over an open prompt. **Never send a block of questions.**
+3. **Wait, then decide if you still need more.** Read the answer. If the intent is now crisp, stop and
+   proceed. If not, ask the next single question. Keep looping until it's clear — typically 1-3
+   questions, rarely more.
+4. **Anchor every question in the two sources of truth.** Each question and recommendation must follow
+   from (a) the project's objectives (`specs/`, `plans/`, stated goals) and (b) domain best practices —
+   so you're steering like an expert, not fishing. For a login bug that means asking about the
+   observable failure, the affected users/browser, and the acceptance ("signed-in and redirected"),
+   not cosmetic trivia.
+5. **Converge and confirm.** Once clear, restate the crisp need in one or two lines and get a yes
+   before running: "So: <need>, for <users>, done when <acceptance>. Correct?"
+6. **Then hand off** the confirmed need to the normal Router flow (Classify → Gate → Load → Run), or to
+   `brainstorm` / `analyze-requirements` for a new build. Clarify **replaces nothing** downstream.
+
+## Tone — natural and immersive, never templated
+Sound like a thoughtful colleague, not a form. Acknowledge the ask, then segue into the question as a
+way to get it right — in your own words **each time**. The *spirit* is fixed (acknowledge → reflect →
+one question, with a recommendation); the *phrasing* is never fixed. Do **not** copy these sentences
+verbatim — they only show the register:
+> "Got it — I'm with you on <request>. One thing I'd like to nail down before I start: …"
+> "Taken on board. To make sure I build the right thing rather than guess: …"
+> "Understood. So I aim at the real need here, quick check: …"
+
+Match the depth to the request: a small tweak needs at most a light one-line confirm; a genuinely
+complex or new-build request, once the core intent is clear, simply **flows into the normal path**
+(`brainstorm` → analysis → spec → plan) — you already know that road, so don't keep interrogating.
+Keep it light: prose and a question, not a bordered panel of options unless options genuinely help.
+
+## Guardrails
+- **One question at a time** — never a wall of questions. This is the whole point.
+- **Only ask what changes the outcome.** If an answer wouldn't change what you'd do, don't ask it.
+- **Always recommend.** A question without your reasoned default offloads the thinking back onto the
+  user — give the expert view, let them correct it.
+- **Respect the mode** (`config.json`): `autopilot` → state one assumption and proceed (record it);
+  `semi` (default) → clarify when ambiguous/risky; `manual` → clarify. "Just do it / you decide" is a
+  valid answer → proceed on explicit, recorded assumptions (`policy.md` still applies).
+- **Cap the loop.** If it's still unclear after a few rounds, propose the most reasonable
+  interpretation as a recommendation and ask for a yes/no — don't interrogate indefinitely.
+- **Never fabricate the answer** to keep moving; a decision-blocking gap that isn't yours to settle is
+  a `need`, raised per `policy.md`.
+
+## Output contract
+The confirmed need (or the assumptions being proceeded on) is recorded granularly — a note/task
+comment, or the spec if one exists — one line at a time. Report to the orchestrator and group chat:
+
+```
+::spectoflow role=intake kind=clarify msg=<the one crisp question you just asked, or the confirmed need>
+```
+
+## Quality bar
+- [ ] The request was reflected back in one sentence before any question was asked.
+- [ ] Questions were asked **one at a time**, never as a block.
+- [ ] Every question carried a recommended default with a one-line reason.
+- [ ] Each question was anchored in the project's objectives and/or a best practice — not trivia.
+- [ ] The loop stopped as soon as the need was crisp (no over-questioning), and the crisp need was
+      confirmed with the user before execution.
+- [ ] Mode was respected; "you decide" was honored by proceeding on explicit, recorded assumptions.
+
+## References
+- Anthropic, "Claude Code best practices" (be specific; let the agent ask before acting) —
+  https://www.anthropic.com/engineering/claude-code-best-practices
+- IIBA, *A Guide to the Business Analysis Body of Knowledge (BABOK)* — Elicitation & Collaboration —
+  https://www.iiba.org/career-resources/a-business-analysis-professionals-foundation/babok/
+- Gojko Adzic, *Specification by Example* (Manning, 2011) — converging on a shared, testable
+  understanding before building — https://gojko.net/books/specification-by-example/

package/templates/skills/write-e2e-tests/SKILL.md

@@ -44,12 +44,22 @@ Practices below are current Playwright guidance (see References for exact source
 8. **Keep specs scoped to one flow each**, named for the behavior under test, and placed under
    `tests/e2e/*.spec.ts` in the user's project.
 
-**Live/exploratory verification is not this skill's output.** When an agent needs to *see* a change work
-right now (e.g. eyeballing a UI during development), it uses its native browser tooling (for Claude Code,
-the Chrome extension / `claude-in-chrome`) to drive the real browser interactively. If that tooling is
-unavailable, the fallback is Playwright in headed mode or `playwright codegen` for a quick, throwaway
-look — never a substitute for the committed suite. Either way, the durable, CI-runnable artifact this
-skill produces is always the Playwright spec file, not the live session.
+**Driving the browser (live repro + test generation) — use the best available, in this order:**
+1. **Playwright MCP** (`@playwright/mcp`, wired into the project's `.mcp.json` by `spectoflow init`):
+   the **agent-agnostic** way to drive a real browser and **generate** a spec from a recorded flow.
+   Works in any MCP client (Claude Code, Codex, Cursor, …). `npx` fetches it on first use — nothing to
+   install; if it isn't wired yet, add it or run `spectoflow init` again (idempotent).
+2. **The client's native browser tooling** (for Claude Code, the Chrome extension / `claude-in-chrome`)
+   for live/exploratory checks when MCP isn't wired.
+3. **Local Playwright** — `npx playwright codegen` / headed mode for a quick, throwaway look;
+   `npx playwright install` provides the browsers. Needs `@playwright/test` as the project's devDependency.
+4. **If no browser can run at all** (restricted CI, no browsers installed): still **write the durable
+   spec** (the artifact that lasts), then raise a `need` / Attention item with the exact commands to
+   enable it — never report a pass you couldn't actually observe.
+
+**Live/exploratory verification is not this skill's output.** Whichever rung above you're on, the
+durable, CI-runnable artifact this skill produces is always the Playwright **spec file**, not the live
+session — the live drive is only the means to write and check it.
 
 **Playwright is a dependency of the user's project, never of spectoflow.** This skill authors tests
 against whatever Playwright version the target project has (or proposes adding `@playwright/test` as a