spectoflow 0.17.0 → 0.17.5

package/README.md

@@ -174,12 +174,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.0",
+  "version": "0.17.5",
   "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

@@ -66,6 +66,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/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,