spectoflow 0.18.0 → 0.19.0

package/README.md

@@ -167,7 +167,17 @@ uses, so a generated dashboard automatically matches whatever design is active,
 keeps matching if you switch designs later. Blocks can bind live to project stats (`bind:
 "phases.0.pct"`) or hold a static value. Generated skills and agents follow the same gold-standard
 shape as the shipped ones, cite real domain standards (OWASP, WCAG, C4/ADR, …) instead of generic
-advice, and are marked `origin: user-generated` so they're easy to tell apart in the UI.
+advice, and are marked `origin: user-generated` so they're easy to tell apart in the UI. The same
+generators are available from the terminal:
+
+```bash
+spectoflow skill create "reviews PRs for accessibility"      # or: --auto to propose candidates
+spectoflow agent create "owns accessibility review"          # or: --auto
+spectoflow dashboard create "a KPI overview for support"     # or: --auto
+```
+
+Each streams the agent's run live and exits with its status — the same pipeline the dashboard's
+Generate/Auto buttons use, just from a shell.
 
 ## Agents vs skills
 

package/bin/spectoflow.js

@@ -10,6 +10,8 @@ const detect = require('../lib/detect');
 const ownership = require('../lib/ownership');
 const manifest = require('../lib/manifest');
 const mcp = require('../lib/mcp');
+const { startRun } = require('../templates/dashboard/runner');
+const { buildCustomizePrompt } = require('../templates/lib/customize-prompts');
 
 const KIT = path.resolve(__dirname, '..');
 const TPL = path.join(KIT, 'templates');
@@ -257,9 +259,62 @@ async function dashboard() {
   if (sub === 'stop') return stopDashboard();
   if (sub === 'status') return dashboardStatus();
   if (sub === 'restart') return restartDashboard();
+  if (sub === 'create') return runCustomize('dashboard');
   return startDashboard();
 }
 
+// ---- Customize: `spectoflow skill/agent/dashboard create` — the CLI mirror of the dashboard's
+// Settings → Customize UI. Both surfaces build the same natural-language prompt (customize-prompts.js)
+// and post it through the same pipeline (runner.js's startRun — the function /api/run itself calls),
+// so a generation triggered from the terminal behaves identically to one triggered from a click.
+function requireProjectRoot() {
+  const root = process.cwd();
+  if (!fs.existsSync(path.join(root, '.spectoflow'))) {
+    console.log('No spectoflow project here. Run: spectoflow init');
+    return null;
+  }
+  return root;
+}
+// "create <description words…> [--auto] [--agent=name]" → { description, auto, agentOverride }.
+// Words are re-joined with spaces so an unquoted multi-word description works the same as a quoted one.
+function parseCreateArgs(args) {
+  return {
+    auto: args.includes('--auto'),
+    agentOverride: (args.find((a) => a.startsWith('--agent=')) || '').split('=')[1] || undefined,
+    description: args.filter((a) => !a.startsWith('--')).join(' ').trim(),
+  };
+}
+function printCreateUsage(kind) {
+  console.log(`Usage: spectoflow ${kind} create "<description>" ${c.dim('[--agent=name]')}`);
+  console.log(`   or: spectoflow ${kind} create --auto ${c.dim('[--agent=name]')}`);
+}
+// Streams the same events the dashboard's SSE feed would show: raw output lines as-is, and
+// structured ::spectoflow sentinel messages as "[role] text" (skip the echoed user prompt — printed
+// separately, up front, so it isn't shown twice).
+function cliEmit(evt) {
+  if (evt.type === 'run-line') process.stdout.write(evt.chunk);
+  else if (evt.type === 'message' && evt.message && evt.message.role !== 'user') {
+    console.log(`${c.cy('[' + evt.message.role + ']')} ${evt.message.text}`);
+  }
+}
+async function runCustomize(kind) {
+  const root = requireProjectRoot();
+  if (!root) return;
+  if (argv[1] !== 'create') return printCreateUsage(kind);
+  const { auto, agentOverride, description } = parseCreateArgs(argv.slice(2));
+  let prompt;
+  try { prompt = buildCustomizePrompt(kind, { auto, description }); }
+  catch (e) { console.log(c.y(e.message)); console.log(''); return printCreateUsage(kind); }
+  console.log(c.dim(`→ ${prompt}`));
+  const code = await new Promise((resolve) => {
+    const r = startRun(root, { prompt, agent: agentOverride }, cliEmit);
+    if (r.error) { console.log(c.y(r.error)); return resolve(1); }
+    if (!r.child) return resolve(1); // spawn failed — cliEmit already printed the error
+    r.child.on('close', (exitCode) => resolve(exitCode == null ? 1 : exitCode));
+  });
+  process.exitCode = code;
+}
+
 // 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() {
@@ -396,6 +451,11 @@ ${c.bold('Dashboard')}
   ${c.g('dashboard stop')}               stop it ${c.dim('(alias: stop)')}
   ${c.g('dashboard restart')}            stop then start
 
+${c.bold('Customize')} ${c.dim('— same as Settings → Customize, from the terminal')}
+  ${c.g('skill create')} ${c.dim('"<description>" | --auto')}      generate a project skill
+  ${c.g('agent create')} ${c.dim('"<description>" | --auto')}      generate a project agent
+  ${c.g('dashboard create')} ${c.dim('"<description>" | --auto')}  generate a custom dashboard
+
 ${c.bold('Explore')}
   ${c.g('list')}                        agents, skills and the workflow at a glance
   ${c.g('agents')}                      list the team personas
@@ -421,12 +481,22 @@ const HELP = {
   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
+  dashboard: `${c.bold('spectoflow dashboard')} ${c.dim('[--port=NNNN] [status|stop|restart|create]')}\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`,
+    ${c.g('restart')}   stop then start
+    ${c.g('create')}    generate a custom dashboard, e.g. ${c.dim('spectoflow dashboard create "..." --auto')}`,
+  skill: `${c.bold('spectoflow skill create')} ${c.dim('"<description>" [--agent=name]')}\n${c.bold('spectoflow skill create')} ${c.dim('--auto [--agent=name]')}\n
+  Generate a project-specific skill — the CLI mirror of Settings → Customize → ${c.bold('Skills')} →
+  ${c.bold('Add skill')} in the dashboard. Describe what it should do, or pass ${c.g('--auto')} to have
+  the agent survey the project and propose candidates instead. Runs the configured agent headless
+  (${c.dim('config.json → agent')}, or override with ${c.g('--agent=')}), streaming its output live;
+  it clarifies first if the ask is ambiguous, and marks what it writes ${c.dim('origin: user-generated')}.`,
+  agent: `${c.bold('spectoflow agent create')} ${c.dim('"<description>" [--agent=name]')}\n${c.bold('spectoflow agent create')} ${c.dim('--auto [--agent=name]')}\n
+  Generate a project-specific agent — the CLI mirror of Settings → Customize → ${c.bold('Agents')} →
+  ${c.bold('Add agent')}. Same behaviour as ${c.g('spectoflow skill create')}, for an agent persona instead.`,
   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.`,
@@ -446,6 +516,8 @@ const fns = {
   agents: () => { console.log(wordmark()); printAgents(false); },
   skills: () => { console.log(wordmark()); printSkills(false); },
   workflow: () => { console.log(wordmark()); printWorkflow(false); },
+  skill: () => runCustomize('skill'),
+  agent: () => runCustomize('agent'),
 };
 const wantsHelp = argv.slice(1).some((a) => a === '-h' || a === '--help');
 

package/package.json

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

package/templates/README.md

@@ -33,7 +33,9 @@ sit at the project root and just point back here.
 - **Extend spectoflow itself** from Settings → **Customize**: describe a project-specific dashboard,
   skill, or agent (or hit **Auto** to have it propose candidates from your project), and it's generated
   for you — a dashboard appears in the nav immediately, a skill/agent follows the same gold-standard
-  shape as the shipped ones and is marked `origin: user-generated`.
+  shape as the shipped ones and is marked `origin: user-generated`. Same thing from the terminal:
+  `spectoflow skill create "<description>"` / `agent create` / `dashboard create` (each also takes
+  `--auto`).
 - **Update the framework** to a newer kit: `spectoflow update` (preserves your edits; a file you
   changed is kept and its new version is written next to it as `*.new`).
 

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 };