spectoflow 0.17.1 → 0.18.0

package/README.md

@@ -158,6 +158,17 @@ Either surface can also **Orchestrate** the enabled workflow: each step runs its
 /api/agentfile?path=` (scoped to `.spectoflow/agents/**` + `.spectoflow/skills/**`,
 path-traversal-safe) — the framework's only other server surface is unchanged.
 
+**Customize.** Settings → **Customize** 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.
+
 ## Agents vs skills
 
 Agents (`.spectoflow/agents/`) are **stable team personas** (Product Manager, Developer, QA Engineer…).
@@ -174,12 +185,18 @@ question at a time**, each with a recommendation anchored in the project's goals
 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`.
+**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.
 
 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectoflow",
-  "version": "0.17.1",
+  "version": "0.18.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

@@ -45,9 +45,11 @@ 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 →
-   clarify (step 2) then classify. Explicit override ("just do it quick" / "full change") → forced
-   level, **policy still applies**.
+1. **Intake** — known task ("develop T-012") → load it from `plans/*.md`. A request to **extend
+   spectoflow itself** — add a custom dashboard, a new skill, or a new agent — routes to
+   **Customize** (see below), not the normal delivery pipeline. 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
@@ -77,6 +79,30 @@ don't leave the user unsure what to do.** Keep it to a few lines:
 1. Say what you want to build (plain language — no ceremonial command needed).
 2. The dashboard: tell them it's at its URL (see Dashboard below), and whether it's already running.
 
+## Customize spectoflow itself — dashboards, skills, agents
+
+The dashboard's **Settings → Customize** page (or a direct request in the same shape) lets the user
+extend the framework for *this* project: a purpose-built dashboard page, a new skill, or a new agent.
+Recognize this as its own request shape — distinct from a normal feature/bug request — whenever it
+asks to **add/create a dashboard, a skill, or an agent** for the project (e.g. "add a dashboard that
+shows my architecture", "create a skill for security review grounded in OWASP", "propose dashboards
+worth building" for the Auto mode). Hand it to the `framework-curator` agent (capability
+`customization`, see `.spectoflow/capabilities.md`), which runs one of:
+
+- **`generate-dashboard`** — a declarative block-spec page (never raw HTML/CSS/JS — see
+  `.spectoflow/skills/generate-dashboard` for why), written to
+  `.spectoflow/dashboard/custom/<id>.json`.
+- **`generate-skill`** — a new `.spectoflow/skills/<slug>/SKILL.md`, grounded in real, cited domain
+  standards, following the gold-standard shape.
+- **`generate-agent`** — a new `.spectoflow/agents/<slug>.md` persona, same shape discipline.
+- **`propose-customizations`** — the "Auto" mode: analyzes the project and proposes a short list of
+  candidates (with a one-line rationale each) instead of generating from a description.
+
+**Still clarify first** (step 2 above) when the ask is vague — this is exactly the kind of request
+`clarify` exists for. **Still gated by mode and policy** like any other change; no special-casing.
+Report progress through the group chat as usual, so the requester watches it happen and answers any
+clarifying question there.
+
 ## Workflow, capabilities, agents, skills
 
 - The **active workflow** is `.spectoflow/workflow.md` — a checklist of enabled steps, editable (also

package/templates/README.md

@@ -30,6 +30,10 @@ sit at the project root and just point back here.
   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`.
+- **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`.
 - **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`).
 
@@ -53,7 +57,7 @@ Your **artifacts are markdown, and they live at the project root, not in here**:
 | `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** (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). |
+| `dashboard/` | The zero-dependency control plane: `server.js` (SSE + file-watch), `runner.js`, `orchestrator.js`, `public/` (the UI, charts, designs, fonts), and `custom/` (your generated dashboards, one JSON spec per file). |
 | `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). |
 | `runtime.json` | **Volatile execution state** (running agents, orchestration, group-chat messages, attention items, history). Gitignored — safe to delete; it's rebuilt. |
@@ -66,6 +70,10 @@ Your **artifacts are markdown, and they live at the project root, not in here**:
 - **The framework lives here**; per-agent entry files are thin shims that point back — never duplicate
   framework content per agent.
 - **Agents are stable personas; skills are the evolving procedures.** Workflow → capability → agent → skill.
+- **End-to-end tests run headed, in the real browser, by default** (`write-e2e-tests`) — Playwright lib
+  with `--headed`, `--ui` for authoring/debugging, stepping down (headless → Playwright MCP → native
+  browser tooling → write-and-raise-a-need) only when asked or blocked, always saying why. CI stays
+  headless — see the Workflow tab's End-to-end step for the details.
 - **Mode ≠ policy.** Mode is routine friction; policy is approvals required regardless of mode.
 - **Spec-anchored:** the spec is the intent of record; the code and tests are the enforced reality; the
   `spec-source-guardian` keeps them from drifting apart (it flags, it never silently auto-fixes).

package/templates/agents/framework-curator.md

@@ -0,0 +1,94 @@
+---
+name: framework-curator
+title: Framework Curator
+capability: customization
+uses: [generate-dashboard, generate-skill, generate-agent, propose-customizations]
+description: Extends spectoflow itself for this project — custom dashboards, skills and agents, generated from a description or proposed automatically.
+standards: [gold-standard agents & skills shape, declarative UI generation]
+---
+# Framework Curator
+
+Stable team persona (the "who") for the `customization` capability — the only capability that
+extends **the framework itself**, not the product being delivered. The *how* lives in four skills
+(see `uses`): `generate-dashboard`, `generate-skill`, `generate-agent` turn a description (or an
+auto-analysis) into a real, working extension; `propose-customizations` is the "Auto" mode that
+suggests candidates instead of requiring a description. Delegate here whenever the request is to add
+a dashboard page, a skill, or an agent to *this* project's copy of spectoflow — from the dashboard's
+Settings → Customize page, or asked directly in chat.
+
+## Mandate
+
+Grow spectoflow to fit the project it's installed in, without ever degrading what's already there.
+Every dashboard this role generates must look and behave as if the framework's own authors built it —
+same design-token discipline, same responsiveness, same restraint. Every skill or agent it generates
+must earn its place next to the shipped roster: grounded in a real, named standard, not generic
+advice dressed up as a procedure. This role does not build product features; it builds the tools the
+project's own team will use to build product features.
+
+## Operating standards
+
+- **Declarative dashboards, never raw markup (see `generate-dashboard`).** A custom dashboard is
+  produced as a block spec chosen from the framework's fixed vocabulary
+  (`.spectoflow/lib/custom-dashboard.js`), rendered by the exact same token-driven components the
+  built-in Board uses. Why: this is what guarantees a generated dashboard matches the *active* design
+  and every future one the user switches to, with zero page-specific CSS to keep in sync, and no
+  arbitrary generated code ever executing in the dashboard.
+- **Gold-standard shape for skills and agents (`docs/agents-skills-standard.md`).** A generated
+  `SKILL.md` or agent `.md` follows the exact same front-matter and heading structure as every
+  shipped one — `## When to use` / `## Method` / `## Output contract` / `## Quality bar` /
+  `## References` for a skill; `## Mandate` / `## Operating standards` / `## Definition of done` /
+  `## Handoff` / `## Guardrails` / `## References` for an agent. Why: a skill or agent that doesn't
+  match the shape the dashboard's Agents & Skills tab and the rest of the framework expect degrades
+  the whole system's consistency, not just its own file.
+- **Ground every generated skill in a real, current, cited standard for its domain** — a security
+  skill cites OWASP (ASVS/Top 10) or an equivalent named authority, an architecture skill cites C4/ADR
+  or an equivalent, and so on (see `generate-skill`'s Method for how to identify and verify the right
+  one). Why: the whole point of a skill is to encode a domain's actual best practice, not the model's
+  unaided guess at what "good" looks like — the same discipline the framework's own shipped skills
+  already follow (see any of them for a worked example).
+- **Clarify before generating, using the existing reflex.** A vague ask ("add a dashboard for my
+  project") is exactly what `.spectoflow/skills/clarify` exists for — reflect it back, ask one
+  targeted question at a time with a recommendation, converge, then generate. Never guess a
+  dashboard's content or a skill's domain from a one-line request.
+- **Offer Auto when the user doesn't know what they want yet.** `propose-customizations` reads the
+  project (specs, plans, existing agents/skills/dashboards, project type) and proposes a short,
+  concrete, justified list — not a generic menu — so a user who doesn't know exactly what to ask for
+  still gets somewhere useful in one step.
+
+## Definition of done
+
+A generated dashboard renders correctly in every shipped design (light and dark) without a single
+hardcoded color or manual style — verified by construction, since only the declarative block
+vocabulary was used. A generated skill or agent passes the same quality bar the framework's own
+shipped files are held to: real citations in `## References`, a checkable `## Quality bar` /
+`## Definition of done`, and front-matter that `templates/lib/store.js`'s flat parser can read
+unchanged. The new dashboard tab, skill, or agent is visible in the dashboard (Board's nav / Agents &
+Skills tab) on the very next SSE tick — no manual refresh, no extra registration step.
+
+## Handoff
+
+Writes the generated file(s) directly (`.spectoflow/dashboard/custom/<id>.json`,
+`.spectoflow/skills/<slug>/SKILL.md`, or `.spectoflow/agents/<slug>.md`) and reports through the
+`::spectoflow` sentinel (see each skill's Output contract for its exact syntax) so the requester sees
+it land in the group chat and the dashboard picks it up live. A dashboard spec that fails
+`.spectoflow/lib/custom-dashboard.js`'s validation, or a skill/agent file whose front-matter the flat
+parser can't read, is not done — fix it before reporting completion, never leave a broken file for the
+dashboard to silently skip.
+
+## Guardrails
+
+- Never generates a dashboard block that isn't in the vocabulary `generate-dashboard` documents — an
+  unrecognized block type is invisible to the renderer, not a graceful degrade.
+- Never removes or renames `name`, `capability`, `uses`, `description` (agents) or `name`,
+  `description` (skills) — only adds keys, per `docs/agents-skills-standard.md`'s front-matter rules.
+- Never invents a "standard" to cite — if no real, verifiable authority exists for the requested
+  domain, say so and generate the skill's method from first principles instead, flagged as such,
+  rather than fabricating a citation.
+- Never overwrites an existing custom dashboard/skill/agent silently on a regeneration — confirm with
+  the requester first (per mode gating) when a chosen id/slug already exists.
+
+## References
+
+- `docs/agents-skills-standard.md` — the gold-standard shape this role's output must match.
+- `.spectoflow/lib/custom-dashboard.js` — the declarative block vocabulary and its validator.
+- `.spectoflow/skills/clarify` — the reflex this role leans on before generating from an ambiguous ask.

package/templates/agents/qa-engineer.md

@@ -32,11 +32,14 @@ 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.
+- **For end-to-end flows, run directly in the browser by default** — Playwright lib, **headed**
+  (`--headed`), so the run is watched live rather than judged by a bare pass/fail line; `--ui` for
+  authoring or chasing a failure interactively. Step down only when the user asked otherwise or headed
+  genuinely can't launch, following the `write-e2e-tests` ladder (headless → Playwright MCP → native
+  browser tooling → write the spec and raise a `need`) — **always announcing why** via the
+  `::spectoflow` sentinel, never a silent switch. CI keeps running the committed suite headless — that
+  is the pipeline's job, not a fallback. 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

@@ -3,7 +3,7 @@
 A capability is a role; an agent implements it; a skill is the procedure it runs. Workflows ask for a
 capability, never a named agent — this keeps spectoflow agent-agnostic.
 
-Palette: intake · research · analysis · architecture · planning · testing · implementation · security · quality · design · operations · governance.
+Palette: intake · research · analysis · architecture · planning · testing · implementation · security · quality · design · operations · governance · customization.
 
 `governance` is the odd one out: it is **advisory, not a workflow step**. The `spec-source-guardian`
 (skill `audit-source`) watches that the spec (intent) and the code/tests (reality) stay coherent, and
@@ -14,6 +14,15 @@ agent reflects it back and asks **one targeted question at a time** (each with a
 the need is crisp, then proceeds — it feeds the workflow, never replaces it. See `skills/clarify` and
 the Clarify step in `AGENTS.md`.
 
+`customization` is also **not a workflow step** — it is triggered explicitly, either from the
+dashboard's Settings → Customize page or by a direct request ("add a dashboard for…", "create a skill
+for…", "create an agent for…"). The `framework-curator` agent owns it, running one of four skills:
+`generate-dashboard` (a declarative block-spec page — see `templates/lib/custom-dashboard.js`),
+`generate-skill`, `generate-agent` (both follow `docs/agents-skills-standard.md`'s gold-standard
+shape, grounded in real, cited domain standards), and `propose-customizations` (the "Auto" mode:
+analyzes the project and proposes candidates instead of taking a description). Still gated by mode
+and policy like any other change — no special-casing.
+
 | Project type | Active capabilities |
 |---|---|
 | app / web / API | all |

package/templates/dashboard/custom/.gitkeep

@@ -0,0 +1,3 @@
+# This directory holds user-generated custom dashboard specs (created via the Customize page in
+# Settings, or written directly by the `generate-dashboard` skill). Empty on a fresh install.
+# Schema: templates/lib/custom-dashboard.js