spectoflow 0.14.2 → 0.15.0

package/README.md

@@ -158,6 +158,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');
@@ -133,6 +134,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') : '';

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.2",
+  "version": "0.15.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

@@ -0,0 +1,72 @@
+# `.spectoflow/` — what this folder is
+
+You're looking at the **spectoflow** framework for this project. spectoflow is an **agent-agnostic,
+spec-driven development (SDD)** framework with a **real-time local control plane** (a dashboard). You
+talk to your AI coding agent in plain language; spectoflow classifies the intent, runs the right
+workflow, and tracks everything as **markdown artifacts** you can diff and own.
+
+Everything the framework needs lives here in `.spectoflow/`, so your project root stays clean and the
+framework is swappable/updatable. Your per-agent entry files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`)
+sit at the project root and just point back here.
+
+## How you use it
+
+- **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.
+- **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:
+  ```
+  spectoflow dashboard          # → http://localhost:4319   (or: node .spectoflow/dashboard/server.js)
+  spectoflow dashboard stop     # stop it        (alias: spectoflow stop)
+  spectoflow status             # progress + whether the dashboard is running
+  ```
+- **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
+  changed is kept and its new version is written next to it as `*.new`).
+
+## Where your work lives
+
+Your **artifacts are markdown, and they live at the project root, not in here**:
+
+- `specs/` — the specifications (intent, decisions, acceptance criteria) — your source of truth.
+- `plans/` — checkbox task plans (`- [ ] T-001 Title @owner ~level %status`). The dashboard parses
+  these and writes back **one line at a time** (granular), so your agent and the dashboard never
+  clobber each other.
+
+## What each file/folder here is
+
+| Path | What it is |
+|------|------------|
+| `AGENTS.md` | **The brain** — the intent router, the modes, and the standing rules your agent follows. |
+| `workflow.md` | The **single** workflow definition (the pipeline steps and their capability/skill). |
+| `capabilities.md` | The capability palette (intake, analysis, planning, implementation, testing, quality, security, governance…) and how it adapts to the project type. |
+| `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** (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). |
+| `runtime.json` | **Volatile execution state** (running agents, orchestration, group-chat messages, attention items, history). Gitignored — safe to delete; it's rebuilt. |
+| `.dashboard.lock` | Ephemeral pidfile so `spectoflow stop` can find the running dashboard. Gitignored. |
+| `.manifest.json` | Hashes of the framework files at install time, so `update` can tell an untouched file from one you edited. |
+
+## Principles (why it's shaped this way)
+
+- **Artifacts are markdown** in `specs/`/`plans/`; volatile state is `runtime.json`. Writes are granular.
+- **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.
+- **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).
+- **Zero runtime dependencies** — native Node only. The dashboard works offline.
+
+## More
+
+Project & docs: https://github.com/georgesmomo/spectoflow · installed via `npm i -g spectoflow`.

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,83 @@
+---
+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. **Reflect it back.** Restate the request in one sentence and name the goal as you understand it.
+   Surface your assumptions explicitly so a wrong one is easy to correct.
+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.
+
+## 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