spectoflow 0.21.0 → 0.21.1

package/README.md

@@ -16,6 +16,10 @@
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/georgesmomo/spectoflow/main/docs/screenshot-board.png" alt="spectoflow dashboard — Board overview" width="880">
+</p>
+
 An **agent-agnostic** spec-driven development framework with a **real-time local control plane**.
 You speak in plain language; the framework classifies your intent and runs the right workflow. No
 ceremonial command to start.
@@ -30,6 +34,8 @@ silently activating something that isn't there.
 > (Claude Code, Copilot CLI, …). spectoflow's own **team personas** (developer, qa-engineer, …) are a
 > different, unrelated use of "agent" — see [Agents vs skills](#agents-vs-skills) further down.
 
+## Supported coding agents
+
 | Coding agent | Headless run | Docs |
 |---|---|---|
 | Claude Code | ✓ | [code.claude.com/docs/en/cli-reference](https://code.claude.com/docs/en/cli-reference) |
@@ -101,8 +107,8 @@ spectoflow --help      (-h)                    show help   (append -h to any com
   `.claude/commands/spectoflow.md`.
 - `.spectoflow/runtime.json` is gitignored (volatile execution state).
 
-`init` **auto-detects your installed agent(s)** (probes PATH for `claude`, `codex`, `cursor-agent`,
-`gemini`, and existing `.claude`/`.codex`/… dirs): it writes shims for each, sets the active agent in
+`init` **auto-detects your installed agent(s)** (probes PATH for each of the 13 supported CLIs above,
+and existing `.claude`/`.codex`/… dirs): it writes shims for each, sets the active agent in
 `config.json`, and seeds the runner commands. Override with `--agent=claude,codex`; if nothing is
 detected it falls back to claude + codex.
 
@@ -166,56 +172,72 @@ spectoflow dashboard                     # → http://localhost:4319 (or --port=
 
 `spectoflow dashboard` is the simple way — it prints the URL and won't double-start (it detects a
 dashboard already running on the port). `spectoflow status` tells you whether one is up. Running the
-`server.js` directly still works for a manual/embedded setup. Zero dependencies, updates live via SSE +
-file watching. Ten tabs behind a dense icon-tab header (brand logo · subtitle · **active agent** ·
-autonomy mode · language · a slim global-progress meter · a sync dot · a **Run** quick-action): **Board**
-(the control-room Overview — compact KPI cards, a status donut, a **scope-vs-delivered area curve**, a
-workflow-at-a-glance strip, per-phase progress bars, filter chips + search — plus the phase board),
-**Chat** (a full-height group-chat panel with **Summarize**/**Clear**), **Requests** (tasks awaiting
-you — `to_validate`/`to_analyze`), **Attention** (points the agent raised via a `::spectoflow attention
-msg=…` sentinel or that you noted — edit/resolve/delete, or **validate → task**), **Backlog** (a flat
-sortable/filterable, paginated table of every task, defaulting to open work), **Workflow** (the
-pipeline as step cards — click one to enable/disable it, which edits `workflow.md`), **Agents &
-Skills** (enriched cards that open a full-body markdown drawer), **Info** (a project-at-a-glance
-summary), **Documentation** (the supported-agents table above, live with your own install status and
-links, plus the CLI command reference), and **Personalize** (autonomy mode, language, design, the
-active agent, and **Extend spectoflow** — described under *Customize* below). URLs are real routes
-(`/board`, `/backlog/T-012`, …). Charts are zero-dep, hand-rolled SVG in `dashboard/public/charts.js`
-(donut/area/bars/ring, animated, `prefers-reduced-motion`-aware), and every aggregate is computed
-client-side.
-
-**Designs & theme.** The dashboard ships **switchable designs** (Settings → *Dashboard design*):
-**Control Room** (violet), **Obsidian Ops** (near-black lime/cyan, mono), **Neon Command**
-(glassmorphism aurora), and **Mission Control** (indigo control panel). Each works in light and dark
-(the moon toggle). A design is a `data-design`
-skin — a scoped CSS token block plus a one-line entry in `dashboard/public/designs.js`, so adding one
-is trivial. Fonts are **self-hosted** (`dashboard/public/fonts/*.woff2`), keeping the dashboard fully
-offline and dependency-free. Your choice persists per viewer (localStorage) and as the project
-default (`config.design`).
-
-A floating **💬 chat widget** (bottom-right, redesigned) and the **Chat** tab render the same
-`runtime.messages` log via a shared `renderChatLog()`, so they never drift. A running agent identifies
-itself by printing `::spectoflow role=… kind=… msg=…` sentinels, which become labelled messages
-(analyst / developer / qa …); other output streams raw. The board refreshes live as it edits plans.
-Either surface can also **Orchestrate** the enabled workflow: each step runs its agent, gated by mode
-+ policy. The Chat tab can also **Summarize** the recent log into one digest (via the active agent)
-or **Clear** it outright, when it's grown long. The Agents & Skills drawer is served by the one
-read-only endpoint, `GET /api/agentfile?path=` (scoped to `.spectoflow/agents/**` +
-`.spectoflow/skills/**`, path-traversal-safe) — the framework's only other server surface is
-unchanged.
-
-**Customize.** Personalize → **Extend spectoflow** lets you extend the project's own spectoflow
-install: add a
+`server.js` directly still works for a manual/embedded setup. Zero dependencies, updates live via SSE
++ file watching.
+
+The header bar always shows the brand, the **active agent**, autonomy mode, language, a global-progress
+meter, a sync dot, and a **Run** quick-action. Ten tabs:
+
+- **Board** — the control-room Overview (compact KPI cards, a status donut, a **scope-vs-delivered
+  area curve**, a workflow-at-a-glance strip, per-phase progress bars, filter chips + search) plus the
+  phase board.
+- **Chat** — a full-height group-chat panel with **Summarize** / **Clear**.
+- **Requests** — tasks awaiting you (`to_validate` / `to_analyze`).
+- **Attention** — points the agent raised (a `::spectoflow attention msg=…` sentinel) or that you
+  noted yourself — edit / resolve / delete, or **validate → task**.
+- **Backlog** — a flat sortable/filterable, paginated table of every task, defaulting to open work.
+- **Workflow** — the pipeline as step cards; click one to enable/disable it, which edits `workflow.md`.
+- **Agents & Skills** — enriched cards that open a full-body markdown drawer.
+- **Info** — a project-at-a-glance summary.
+- **Documentation** — the live supported-agents table (your own install status + links) plus the CLI
+  command reference.
+- **Personalize** — autonomy mode, language, design, the active agent, and **Extend spectoflow** (see
+  *Customize* below).
+
+URLs are real routes (`/board`, `/backlog/T-012`, …). Charts are zero-dep, hand-rolled SVG in
+`dashboard/public/charts.js` (donut/area/bars/ring, animated, `prefers-reduced-motion`-aware), and
+every aggregate is computed client-side.
+
+### Designs & theme
+
+The dashboard ships **switchable designs** (Personalize → *Dashboard design*): **Spectral Console**
+(dark-first, ⌘K palette — the default), **Orbit** (light, circular radial menu), **Control Room**
+(violet), **Obsidian Ops** (near-black lime/cyan, mono), **Neon Command** (glassmorphism aurora), and
+**Mission Control** (indigo control panel). Each works in light and dark (the moon toggle). A design
+is a `data-design` skin — a scoped CSS token block plus a one-line entry in
+`dashboard/public/designs.js`, so adding one is trivial. Fonts are **self-hosted**
+(`dashboard/public/fonts/*.woff2`), keeping the dashboard fully offline and dependency-free. Your
+choice persists per viewer (localStorage) and as the project default (`config.design`).
+
+### Chat
+
+A floating **💬 chat widget** and the **Chat** tab render the same `runtime.messages` log via a shared
+`renderChatLog()`, so they never drift. A running agent identifies itself by printing `::spectoflow
+role=… kind=… msg=…` sentinels, which become labelled messages (analyst / developer / qa …); other
+output streams raw. The board refreshes live as it edits plans. Either surface can also
+**Orchestrate** the enabled workflow (each step runs its agent, gated by mode + policy), **Summarize**
+the recent log into one digest via the active agent, or **Clear** it outright. The Agents & Skills
+drawer is served by the one read-only endpoint, `GET /api/agentfile?path=` (scoped to
+`.spectoflow/agents/**` + `.spectoflow/skills/**`, path-traversal-safe) — the framework's only other
+server surface is unchanged.
+
+### Customize
+
+Personalize → **Extend spectoflow** lets you extend the project's own spectoflow install: add a
 dashboard, a skill, or an agent by describing what you want (or hit **Auto** to have the agent survey
-the project and propose candidates), and it clarifies first if the ask is ambiguous. Dashboards are
-never raw HTML — they're a small **declarative block spec** (`markdown`, `kpi-row`, `chart-bars`,
-`chart-donut`, `table`, `list`, `stat-tile-row`) rendered by the same components the built-in Board
-uses, so a generated dashboard automatically matches whatever design is active, in both themes, and
-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. The same
-generators are available from the terminal:
+the project and propose candidates) — it clarifies first if the ask is ambiguous.
+
+- Dashboards are never raw HTML — they're a small **declarative block spec** (`markdown`, `kpi-row`,
+  `chart-bars`, `chart-donut`, `table`, `list`, `stat-tile-row`) rendered by the same components the
+  built-in Board uses, so a generated dashboard automatically matches whatever design is active, in
+  both themes, and 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.
+
+The same generators are available from the terminal — each streams the agent's run live and exits
+with its status, the same pipeline the dashboard's Generate/Auto buttons use:
 
 ```bash
 spectoflow skill create "reviews PRs for accessibility"      # or: --auto to propose candidates
@@ -223,9 +245,6 @@ 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
 
 Agents (`.spectoflow/agents/`) are **stable team personas** (Product Manager, Developer, QA Engineer…).
@@ -235,25 +254,38 @@ 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 run headed, in the real browser, by default.** `write-e2e-tests` defaults to
-**Playwright lib, `--headed`** for its own local runs — the browser window is visible so a flow that
-"passes" for the wrong reason gets caught, not just a bare pass/fail line. `--ui` mode is used for
-authoring a flow or chasing a failure interactively. It only steps down — to headless, then
-**Playwright MCP**, then the client's native browser tooling (e.g. Claude Code's Chrome extension), then
-writing the spec and raising a `need` — when you asked for something else or headed genuinely can't
-launch, and it **always says why** via the `::spectoflow` sentinel, never a silent switch. CI keeps
-running the committed suite headless — that's the pipeline's job, not a fallback. `init` idempotently
-wires a `playwright` entry into the target project's `.mcp.json` (and `.cursor/mcp.json` for Cursor) so
-the MCP rung works out of the box — `npx` fetches the server on first use, so spectoflow stays zero-dep
-(the config lives in *your* project). The durable artifact is always the committed `*.spec.ts`; the
-Workflow tab's End-to-end step shows this policy in its dashboard popover.
+### 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 run headed, in the real browser, by default
+
+`write-e2e-tests` defaults to **Playwright lib, `--headed`** for its own local runs — the browser
+window is visible so a flow that "passes" for the wrong reason gets caught, not just a bare pass/fail
+line. `--ui` mode is used for authoring a flow or chasing a failure interactively. It only steps down
+when you asked for something else or headed genuinely can't launch — and it **always says why** via
+the `::spectoflow` sentinel, never a silent switch:
+
+1. Playwright lib, headed (default)
+2. `--ui` (interactive authoring/debugging)
+3. Playwright lib, headless
+4. **Playwright MCP**
+5. the client's native browser tooling (e.g. Claude Code's Chrome extension)
+6. write the spec and raise a `need`
+
+CI keeps running the committed suite headless — that's the pipeline's job, not a fallback. `init`
+idempotently wires a `playwright` entry into the target project's `.mcp.json` (and
+`.cursor/mcp.json` for Cursor) so the MCP rung works out of the box — `npx` fetches the server on
+first use, so spectoflow stays zero-dep (the config lives in *your* project). The durable artifact is
+always the committed `*.spec.ts`; the Workflow tab's End-to-end step shows this policy in its
+dashboard popover.
+
+### Keeping spec and code honest
 
 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,
@@ -263,12 +295,30 @@ drift helper (`lib/spec-drift.js`) and an opt-in Claude Code `Stop` hook (`hooks
 ## Language
 
 `.spectoflow/config.json` → `language` (default `en`, incl. code comments). Switchable from the CLI
-(`config.json`) or the dashboard's **settings** gear (mode + language).
+(`config.json`), the dashboard's **Personalize** tab, or the topbar's language select directly.
 
 ## Studied, not copied
 
-Structure informed by spec-kit, OpenSpec (markdown + per-agent adapters), and BMAD (agent-personas).
-spectoflow keeps the good ideas, removes the ceremony, and adds a real-time control plane.
+spectoflow's design was informed by three open-source projects worth knowing about in their own
+right — credit where it's due:
+
+- **[GitHub spec-kit](https://github.com/github/spec-kit)** — the spec-driven workflow itself
+  (spec → plan → tasks) and its own multi-agent integration list, which shaped how spectoflow thinks
+  about agent-agnosticism.
+- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** by Fission AI — markdown as the source of
+  truth and the per-agent adapter pattern (a thin native entry file per coding agent, pointing back
+  to one canonical brain) that `lib/adapters.js` is built on.
+- **[BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)** — stable, named agent personas
+  (PM, Architect, Developer, QA, …) as the right way to give an AI coding agent a consistent role,
+  rather than one undifferentiated prompt.
+
+spectoflow keeps what worked, drops the ceremony each of those needs from you, and adds what none of
+them had: a real-time local dashboard (board, chat, live agent-run tracking) and a genuinely
+exhaustive, individually-verified agent-CLI compatibility list — see [Supported coding
+agents](#supported-coding-agents) above.
+
+If you use spec-kit, OpenSpec, or BMAD-METHOD today, spectoflow is worth a look; if you're evaluating
+spectoflow, those three are worth a look too.
 
 ## License & author
 

package/package.json

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