yadflow 2.2.0 → 2.3.0

package/skills/sdlc/config.yaml

@@ -20,12 +20,12 @@ output_folder: "{project-root}/_bmad-output"
 defaults:
   assistance: review          # none | review | heavy
   automation: human_approve   # human_approve | machine_advance
-  # Front steps (analysis [optional], epic, architecture, ui-design, stories) are locked to
+  # Front steps (analysis [optional], epic, architecture, ui-design, stories, test-cases) are locked to
   # human_approve and may NOT be set to machine_advance in this version (build plan §1, §8.7).
   front_steps_locked: true
   # Each front authoring step opens its own branch at the start of the step (the <step> is the step id:
-  # analysis | epic | architecture | ui-design | stories). Git/greenfield-safe; distinct from the
-  # bridge's review branch (hub.artifact_branch). See yad-epic/references/state-schema.md.
+  # analysis | epic | architecture | ui-design | stories | test-cases). Git/greenfield-safe; distinct
+  # from the bridge's review branch (hub.artifact_branch). See yad-epic/references/state-schema.md.
   front_authoring_branch: "<step>/EP-<slug>"
 
 # Team review gate defaults (build plan §3 piece 2, §4).
@@ -134,6 +134,22 @@ design:
   # NO tokens in the registry (project_url/files are plain references, never credentials).
   auth: user
 
+# Testing tool (yad-connect-testing) — the test-cases step (yad-test-cases) materializes the actual
+# automation tests inside a connected testing tool, alongside test-cases.md. The tool is reached through
+# its MCP (a harness MCP server, like the design tool — NOT a CLI), detected per provider and DEGRADING
+# to artifacts-only when absent. Playwright-first but PLUGGABLE: a testing-tool adapter, like the
+# design-tool adapter. Connection is one-per-project, recorded at setup; the per-epic case->test map
+# (test-links.json) is written by yad-test-cases per epic.
+testing:
+  registry: "{project-root}/.sdlc/testing.json"      # project-wide testing connection (NOT per-epic)
+  tools: [playwright, cypress, pytest]                # supported adapters; an unknown tool falls back to `primary`
+  primary: playwright                                 # the default/named provider
+  degrade: artifacts-only                             # no tool / no MCP => yad-test-cases authors test-cases.md only
+  links: "{project-root}/epics/EP-<slug>/.sdlc/test-links.json"   # per-epic case->test map (yad-test-cases)
+  # Auth: `yad-connect-testing` connects through the LOCAL user's own authenticated MCP session and stores
+  # NO tokens in the registry (project_url/suites are plain references, never credentials).
+  auth: user
+
 # Hub platform + front-half review bridge (yad-connect-repos `detect-hub`; yad-review-gate + yad-hub-bridge).
 # The product hub is itself a git repo on a platform. With the bridge enabled, the front-half review/
 # comment/approval cycle runs through a real PR/MR on the hub: a review PR is opened per artifact, reviewers
@@ -166,7 +182,7 @@ automation:
   # Hard lock — the dial-setter REFUSES machine_advance for these, regardless of trust evidence.
   # The front authoring steps (already locked:true in state.json; analysis is optional) + the human
   # merge gate.
-  locked_steps: [analysis, epic, architecture, ui-design, stories, engineer-review]
+  locked_steps: [analysis, epic, architecture, ui-design, stories, test-cases, engineer-review]
   # Kill switch (phase-4-build-plan.md §Safety): true => every step forced to human_approve
   # system-wide, no per-step edits. One line, instantly reversible. Toggle via `yad-run action: kill`.
   kill_switch: false

package/skills/sdlc/install.sh

@@ -11,7 +11,7 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$ROOT"
 
-SKILLS=(yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-connect-repos yad-connect-design yad-spec yad-implement yad-checks yad-pr-template yad-review-comments yad-hub-bridge yad-ship yad-backfill yad-run yad-review-gate yad-status)
+SKILLS=(yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-connect-design yad-connect-testing yad-spec yad-implement yad-checks yad-pr-template yad-review-comments yad-hub-bridge yad-ship yad-backfill yad-run yad-review-gate yad-status)
 
 echo "Installing sdlc module from $ROOT/skills ..."
 

package/skills/sdlc/module-help.csv

@@ -1,11 +1,13 @@
 module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
 SDLC Workflow,yad-epic,Author Epic,AE,"Front state 1: shape an idea with analyst then pm into epic.md; assign EP-<slug> ID and seed .sdlc state. Never auto-advances.",,{idea: one-line feature idea},1-front,,yad-review-gate,true,epics/EP-<slug>/,epic.md state.json
-SDLC Workflow,yad-review-gate,Team Review Gate,RG,"Reusable review+approve gate for all four reviews. Shares an artifact for review, records comments and approvals as files, enforces owner + 1 reviewer (escalates on contract/auth/payments; per-repo routing for stories), advances state only when approved.",,{artifact: file under the epic} {action: open|comment|approve|advance},1-front,,,true,epics/EP-<slug>/reviews/,reviews/*.md approvals.json state.json
+SDLC Workflow,yad-review-gate,Team Review Gate,RG,"Reusable review+approve gate for all five reviews. Shares an artifact for review, records comments and approvals as files, enforces owner + 1 reviewer (escalates on contract/auth/payments; per-repo routing for stories), advances state only when approved.",,{artifact: file under the epic} {action: open|comment|approve|advance},1-front,,,true,epics/EP-<slug>/reviews/,reviews/*.md approvals.json state.json
 SDLC Workflow,yad-architecture,Author Architecture,AA,"Front state 3: with the architect author architecture.md and the locked contract.md; hash-lock the contract surface. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,architecture.md contract.md contract-lock.json state.json
 SDLC Workflow,yad-ui,Author UI Design,AU,"Front state 5: with the ux-designer author ui-design.md and DESIGN.md, driving Impeccable slash-commands when installed. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,ui-design.md DESIGN.md state.json
 SDLC Workflow,yad-stories,Author Stories,AS,"Front state 7: with the pm break the epic into repo-tagged stories with stable EP-<slug>-S0N IDs, one file each under stories/. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/stories/,stories/EP-<slug>-S0N.md state.json
+SDLC Workflow,yad-test-cases,Author Test Cases,TC,"Front state 9 (PARALLEL, non-blocking): opens when the stories gate passes — the epic is already ready-for-build, so the build half can start at the same time the tester works here. With the test architect (Murat) author test-cases.md covering the approved stories, and — when a testing tool is connected (.sdlc/testing.json) — generate/link the actual automation tests in it, recording test-links.json; otherwise produce the test-case artifact only. Its review never moves currentStep off ready-for-build. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,test-cases.md test-links.json state.json
 SDLC Workflow,yad-connect-repos,Connect Code Repos,CR,"Setup/maintenance: connect code repos to the product hub so the front/brain phases are code-aware. Registers each repo (GitHub or GitLab, local-user auth, no stored tokens) in .sdlc/repos.json and caches a Repomix pack + a lightweight code-map (existing endpoints/events/data-models/modules, secret-scanned). Idempotent and refreshable; staleness tracked by HEAD sha. Run at setup or any time a new repo is added. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {repo: <name>} {path: <path-or-absolute>} {git_url: <ssh-or-https>} {domain_owner: <who>},0-setup,,yad-epic,false,.sdlc/,repos.json code-context/<repo>/pack.md code-context/<repo>/code-map.md
 SDLC Workflow,yad-connect-design,Connect Design Tool,CD,"Setup/maintenance: connect a design tool (Figma-first, pluggable) to the product hub so the UI design step can materialize the actual feature design (mobile screens / web pages) inside it, alongside ui-design.md + DESIGN.md. Records the tool + project/file references in .sdlc/design.json (local-user / MCP-session auth, no stored tokens), detecting whether a design-tool MCP is available and degrading to markdown-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: figma|pencil|none} {project_url: <team/project/file url>} {files: {web,mobile}},0-setup,,yad-ui,false,.sdlc/,design.json
+SDLC Workflow,yad-connect-testing,Connect Testing Tool,CT,"Setup/maintenance: connect a testing tool (Playwright-first, pluggable) to the product hub so the test-cases step can implement the actual automation tests in it, alongside test-cases.md. Records the tool + project/suite references in .sdlc/testing.json (local-user / MCP-session auth, no stored tokens), detecting whether a testing-tool MCP is available and degrading to artifacts-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: playwright|cypress|pytest|none} {project_url: <project/config reference>} {suites: {<repo>}},0-setup,,yad-test-cases,false,.sdlc/,testing.json
 SDLC Workflow,yad-spec,Author Spec,SP,"Build-half Step A: for one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony once (specify→clarify→plan→analyze→checklist→tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit's layout (drives /speckit.* when installed, else hand-authors and records speckit: not-installed). References the locked contract; never re-invents the surface. Writes link.md back to the story. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>},3-build,yad-review-gate,,false,demo-repos/<repo>/specs/<story-id>/,spec.md research.md data-model.md contracts/ plan.md tasks.md link.md
 SDLC Workflow,yad-implement,Implement Task,IM,"Build-half Step B: with the dev lens, implement ONE atomic task from a story's tasks.md as a small diff (<=3 files) on its own branch feat/<story>-<task>-<slug> in the code repo. Diff stays inside the task's declared files (flag and STOP if it grows beyond them). Commit ends with a Task: <story>-<task> trailer; add Contract-Change: yes only when the locked contract surface is touched (routes back to the architecture gate). Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>} {task: T0N},3-build,yad-spec,,false,demo-repos/<repo>/,branch+commit per atomic task
 SDLC Workflow,yad-checks,Check Gates,CK,"Build-half Step C: wire and run the three production-safety CI gates on a code repo — spec-link (every change links a real story/spec via its Task trailer), contract-check (a contract-surface change without Contract-Change + an updated re-locked contract FAILS and routes back to the architecture gate), and build/test/lint. CI-agnostic bash invoked by GitHub Actions and GitLab CI. Blocking in CI; the human still owns the merge. Never auto-advances.",,{repo: <one of an epic's repos>} {action: wire|run} {base: target branch},3-build,yad-implement,,false,demo-repos/<repo>/,checks/*.sh .github/workflows/yad-checks.yml .gitlab-ci.yml

package/skills/yad-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-analysis
-description: 'Optional front state 1 of the gated SDLC. With the analyst, pressure-test a feature idea and write the discovery brief into analysis.md. Assigns the EP-<slug> ID and seeds .sdlc/ state (the 10-step chain that puts analysis before epic). Never auto-advances — hands off to the team review gate. Optional: if skipped, the epic step does this shaping inline. Use when the user says "analyse the idea", "start with analysis", or "author the analysis".'
+description: 'Optional front state 1 of the gated SDLC. With the analyst, pressure-test a feature idea and write the discovery brief into analysis.md. Assigns the EP-<slug> ID and seeds .sdlc/ state (the 12-step chain that puts analysis before epic). Never auto-advances — hands off to the team review gate. Optional: if skipped, the epic step does this shaping inline. Use when the user says "analyse the idea", "start with analysis", or "author the analysis".'
 ---
 
 # SDLC — Author Analysis (optional front state 1)
@@ -11,8 +11,8 @@ state machine in `.sdlc/`. This is a **front state**: human-authored with AI ass
 auto-advances**. When the analysis is drafted, control passes to `yad-review-gate`.
 
 This step is **optional**. When it runs, it is the entry point: it assigns the ID and seeds the
-**10-step** chain (`analysis` before `epic`). When it is **skipped**, `yad-epic` does the same
-analyst shaping inline and seeds the **8-step** chain — no behaviour change for teams that skip it.
+**12-step** chain (`analysis` before `epic`). When it is **skipped**, `yad-epic` does the same
+analyst shaping inline and seeds the **10-step** chain — no behaviour change for teams that skip it.
 
 This skill enforces the build plan's core rules: all state lives in files; IDs are generated by the
 engine (never typed by hand); front steps are locked to `human_approve`.
@@ -88,7 +88,7 @@ code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # which code-maps in
 Fill the body with the user; leave `owner` for the user to set.
 
 ### Step 6 — Seed the state machine
-Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **10-step** front-state
+Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **12-step** front-state
 sequence (analysis before epic), all steps defaulting to `automation: human_approve`, with every
 authoring step **locked**. Use this exact shape (see `references/state-schema.md`):
 
@@ -107,7 +107,9 @@ authoring step **locked**. Use this exact shape (see `references/state-schema.md
     { "id": "ui-design",          "type": "author",         "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
     { "id": "ui-design-review",   "type": "review+approve", "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
     { "id": "stories",            "type": "author",         "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
-    { "id": "stories-review",     "type": "review+approve", "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] }
+    { "id": "stories-review",     "type": "review+approve", "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "test-cases",         "type": "author",         "artifact": "test-cases.md",    "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "test-cases-review",  "type": "review+approve", "artifact": "test-cases.md",    "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] }
   ]
 }
 ```
@@ -116,6 +118,9 @@ Notes:
 - `analysis-review` carries no `risk_tags` — it is the **base** rule (owner + 1 reviewer).
 - `architecture-review` carries `risk_tags: ["contract"]` so the gate escalates it by default
   (build plan §4): the contract review needs domain owners, not just owner + 1.
+- `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `blocked` and open
+  when `stories-review` passes — the epic is already `ready-for-build` by then, so the build half runs
+  alongside the tester (see `../yad-epic/references/state-schema.md`).
 - Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
   and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
   `[]`, and the `reviews/` directory.

package/skills/yad-connect-design/SKILL.md

@@ -20,7 +20,7 @@ markdown-only exactly as before.
 
 - `{project-root}` resolves from the project working directory (the **product hub**).
 - The integration is **Figma-first but pluggable** (`config.yaml` `design.tools`): a design-tool
-  *adapter*, like the `github`/`gitlab` platform adapter. Figma is the primary provider; `pencil`
+  *adapter*, like the GitHub/GitLab platform adapter. Figma is the primary provider; `pencil`
   (the `.pen` web/mobile editor) is a second, write-capable provider; `none` → markdown-only.
 - **The design tool is reached through its MCP** (a harness MCP server), NOT a subprocess CLI — the same
   shape as Impeccable's slash-commands, not Repomix's `npx`. The skill detects the MCP and degrades when

package/skills/yad-connect-design/references/design-registry.md

@@ -27,8 +27,10 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
 
 ## Rules
 
-- **`tool`** selects the adapter; it MUST be one of `config.yaml` `design.tools` (or `none`). An unknown
-  tool falls back to `design.primary` with a warning — never silently accepted.
+- **`tool`** selects the adapter; it MUST be one of `config.yaml` `design.tools` (or `none`). At
+  **connect** time an unknown tool is normalized to `design.primary` with a warning (so the registry
+  never persists an unknown value); a registry hand-edited to an unknown or missing tool **fails
+  `doctor`** with `YAD-CFG-002` and must be fixed.
 - **Auth is never stored.** No Figma PAT, OAuth token, or any credential in the registry. `project_url`
   and `files` are plain references; `connect` reaches the tool through the user's authenticated MCP
   session.

package/skills/yad-connect-testing/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: yad-connect-testing
+description: 'Connects a testing tool (Playwright, or another tool — pluggable) to the product hub so the test-cases step can implement the actual automation tests, not just Markdown test cases. Registers the tool into the project-wide .sdlc/testing.json (local-user / MCP-session auth, no stored tokens), detecting whether a testing-tool MCP is available and degrading to artifacts-only when it is not. Run at setup or any time the testing tool changes. Reusable, idempotent, refreshable. Use when the user says "connect Playwright", "connect a testing tool", "refresh the testing connection", or "list the testing connection".'
+---
+
+# SDLC — Connect a Testing Tool (make the test-cases step automation-aware)
+
+**Goal:** Let the test-cases step (`yad-test-cases`) produce the **actual automation tests** — the
+runnable specs in a connected code repo — alongside the Markdown artifact (`test-cases.md`). This skill
+**connects** a testing tool such as **Playwright** to the product hub and records *how* to reach it (the
+tool, the suite references, which MCP runs it) — never a credential.
+
+This is **setup/maintenance**, not a gated front state — it never touches `.sdlc/state.json` or any
+epic's approvals. It only writes the project-wide testing registry. `yad-test-cases` consumes it: when a
+tool is connected and its MCP is available, the `test architect` lens **generates** automation tests
+into the connected repo(s) (or **links** an existing suite and reads it back); when nothing is
+connected, `yad-test-cases` runs artifacts-only exactly as before.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory (the **product hub**).
+- The integration is **Playwright-first but pluggable** (`config.yaml` `testing.tools`): a testing-tool
+  *adapter*, like the GitHub/GitLab platform adapter or the design-tool adapter. Playwright is the
+  primary provider; `cypress` and `pytest` are second providers; `none` → artifacts-only.
+- **The testing tool is reached through its MCP** (a harness MCP server), NOT a subprocess CLI — the
+  same shape as the design tool's MCP, not Repomix's `npx`. The skill detects the MCP and degrades when
+  it is absent; it never installs an MCP server.
+- Registry: `{project-root}/.sdlc/testing.json` (project-wide, shared across all epics — NOT per-epic),
+  the sibling of `.sdlc/repos.json`, `.sdlc/hub.json`, and `.sdlc/design.json`.
+- Per-epic test→suite links are written later by `yad-test-cases`
+  (`epics/EP-<slug>/.sdlc/test-links.json`), not here.
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## Inputs
+
+- `action` — `connect` (default) | `refresh` | `list` | `disconnect`.
+- `tool` — `playwright` | `cypress` | `pytest` | another adapter id (`config.yaml` `testing.tools`).
+  `none` records a deliberate artifacts-only project.
+- `project_url` — the testing tool's project/config reference (e.g. a `playwright.config.ts` path or a
+  test-runner project URL). Optional — a connection with no suite yet is valid; `yad-test-cases` can
+  create one on first generate.
+- `suites` — optional default suite mapping per repo (`{ <repo>: <ref> }`).
+
+## On Activation
+
+### Step 1 — Resolve the tool and its MCP (the testing-tool adapter)
+Determine which tool is being connected from `tool` (default `playwright`); reject a `tool` not in
+`config.yaml` `testing.tools` (fall back to the configured `testing.primary` with a warning, the same
+way `registerRepo` falls back on an unknown platform). Then **detect the tool's MCP** in this harness:
+
+- **playwright** → a Playwright MCP server (drives a browser, generates/runs E2E + API specs).
+- **cypress** → the Cypress MCP (generate/run Cypress specs).
+- **pytest** → a pytest MCP (generate/run service-layer tests).
+- another adapter → its named MCP.
+
+Record `provider` (the concrete MCP, e.g. `playwright-mcp` | `cypress-mcp` | `pytest-mcp`) and whether
+it is available. **Auth is the local user's own** — the user's authenticated MCP session. The skill
+**stores no tokens**; `project_url`/`suites` are plain references, never credentials.
+
+**Graceful degradation:** if no testing-tool MCP is available, record `source: "unavailable"` and report
+that `yad-test-cases` will run **artifacts-only** until an MCP is connected (no error — the testing tool
+is purely additive, exactly like the design tool being absent). Do **not** install an MCP server as part
+of this step.
+
+### Step 2 — Record the connection in the registry
+Upsert into `{project-root}/.sdlc/testing.json` (create the file + parent `.sdlc/` if absent):
+
+```json
+{
+  "tool": "playwright",
+  "provider": "playwright-mcp",
+  "project_url": "tests/playwright.config.ts",
+  "auth": "user",
+  "suites": { "backend": null, "mobile": null },
+  "connectedAt": "<YYYY-MM-DD>",
+  "lastSyncedAt": "<YYYY-MM-DD>",
+  "source": "playwright-mcp"
+}
+```
+
+- `tool: "none"` records a deliberate artifacts-only project: `{ "tool": "none", "provider": null,
+  "source": "unavailable", ... }`.
+- `connect` is **idempotent** — re-running it overwrites the single connection in place (a project has
+  one testing tool at a time; switching tools is just another `connect`).
+
+### Step 3 — Report (never auto-advance)
+Report the connected `tool`, its `provider`, whether the MCP is available (or that `yad-test-cases` will
+degrade to artifacts-only), the `project_url`, and that **`yad-test-cases` will now generate/link the
+automation tests here**. Nothing auto-advances; this is setup.
+
+## Other actions
+
+- **`refresh`** — re-detect the MCP and update `lastSyncedAt` (after the user authenticates a session or
+  changes tools). Same machinery as `connect`. Re-detection may flip `source` between an MCP id and
+  `unavailable` — report the change.
+- **`list`** — print the current connection: `tool`, `provider`, `project_url`, the suite mapping, and a
+  **available/unavailable** flag for the MCP (best-effort, the user's own session). No testing tool
+  connected ⇒ "artifacts-only".
+- **`disconnect`** — remove the registry file (or set `tool: "none"`). The testing tool's own
+  project/suites are **never touched** — only the hub's record of them.
+
+## Hard rules
+
+- **Local-user / MCP-session auth only; store no tokens.** Connect through the user's authenticated MCP
+  session; never embed a token or any credential in the registry. `project_url`/`suites` are plain
+  references.
+- **Degrade gracefully.** No testing tool / no MCP → `yad-test-cases` runs artifacts-only with no error.
+  The testing tool is additive, never a blocker — the same discipline as the design tool and Impeccable.
+- **Setup, not a gate.** Never touch `.sdlc/state.json`, approvals, or the contract lock from here.
+- **Idempotent + refreshable.** `connect`/`refresh` are safe to re-run; a project carries one testing
+  connection at a time.
+- **Describe the connection; do not author tests here.** This skill records *how to reach* the tool. The
+  actual automation tests are generated/linked by `yad-test-cases`, per epic.
+
+## Reference
+- Registry schema + freshness rule: `references/testing-registry.md`.
+- MCP detection per provider, the generate-vs-link recipes, the degrade path, and the honest
+  write-vs-read-only MCP capability note: `references/testing-context.md`.
+- The connect pattern this mirrors (design tool): `../yad-connect-design/SKILL.md`.
+- The consumer — how `yad-test-cases` generates/links and writes `test-links.json`:
+  `../yad-test-cases/SKILL.md`.

package/skills/yad-connect-testing/references/testing-context.md

@@ -0,0 +1,67 @@
+# Testing context — MCP detection, generate vs link, and the degrade path
+
+How a connected testing tool turns into the actual automation tests the test-cases step materializes.
+The testing tool is reached through its **MCP** (a harness MCP server), the same shape as the design
+tool — detect it, use it when present, degrade cleanly when absent. This is the testing-side analogue of
+`yad-connect-design`'s design-context.
+
+## Provider detection
+
+`connect`/`refresh` records `provider` (the concrete MCP) and `source` (the MCP id, or `unavailable`).
+Detection is best-effort against the user's own authenticated MCP session:
+
+| `tool` | MCP / provider | Capability |
+|--------|----------------|------------|
+| `playwright` | a Playwright MCP | **generate** — author + run E2E/API specs against the app |
+| `cypress` | the Cypress MCP | **generate** — author + run Cypress specs |
+| `pytest` | a pytest MCP | **generate** — author + run service-layer tests |
+| any | a read-only runner MCP | **link** — reference an existing suite and read results back |
+| other | the adapter's named MCP | per that adapter |
+
+**Honest capability note:** not every testing-tool MCP can *write* tests. A read-only runner MCP
+supports **link + read-back** only; *generate* needs a write-capable provider. `yad-test-cases` picks
+the direction the connected provider actually supports and records which one it used
+(`direction: generated | linked`). It never claims to have generated tests a read-only MCP cannot
+produce.
+
+## Generate (write automation tests into the repo)
+
+When the connected provider is write-capable, the `test architect` lens (Murat, `bmad-tea` +
+`bmad-testarch-automate`) produces the epic's automation tests in the connected code repo(s), covering
+the cases `test-cases.md` enumerates and the acceptance criteria the stories define:
+
+- **Playwright** — the lens authors `*.spec.ts` E2E/API specs (reusing the repo's existing fixtures and
+  the code-maps from `yad-test-cases` Step 2b), one spec per high-priority (P0/P1) case, and runs them
+  via the MCP to confirm they execute.
+- **Cypress / pytest** — the lens authors the equivalent specs in that framework's layout.
+
+Reuse what already exists: load the connected code repos' code-maps (`yad-test-cases` Step 2b) so
+generated tests target real endpoints/components, not invented ones, and prefer the lowest useful test
+level (unit > integration > E2E) per Murat's principles.
+
+## Link (reference an existing suite)
+
+When a suite already exists (or the provider is read-only), point `yad-test-cases` at it and **read the
+suite back** so `test-cases.md` reflects the real tests: list each test as a case, capture its
+path/name + URL, and map it to the story it covers.
+
+## Write back the linkage (done by `yad-test-cases`, per epic)
+
+Either direction ends by writing `epics/EP-<slug>/.sdlc/test-links.json` — the machine-readable
+case→test map — and a `## Automation (<tool>)` section in `test-cases.md` linking each case to its test.
+The tests themselves live in the code repo; the hub keeps the *links* and the Markdown spec beside the
+other epic artifacts.
+
+## Degrade path (no MCP / no tool)
+
+If `testing.json` is absent, `tool: "none"`, or `source: "unavailable"`, `yad-test-cases` runs
+**artifacts-only**: it authors `test-cases.md` exactly as before and records `testing: none` in the
+frontmatter with a one-line note (mirroring the `design: none` degrade). No error — the testing tool is
+purely additive.
+
+## Staleness / refresh
+
+A re-generated or hand-edited suite is like a moved code repo: `yad-test-cases` **flags** a divergence
+and lets a human decide (re-run the step, or `yad-connect-testing` action: refresh). It never silently
+overwrites a hand-written suite — refreshing the automation is a human decision, the same discipline as
+`code_context.refresh: human`.

package/skills/yad-connect-testing/references/testing-registry.md

@@ -0,0 +1,55 @@
+# Testing registry — schema + freshness rule
+
+The registry is the product hub's record of which testing tool is connected and how to reach it. It is
+**project-wide** (one testing tool per project, shared across every epic), so it lives at the product
+root, not under any `epics/EP-<slug>/.sdlc/`.
+
+## Location
+
+`{project-root}/.sdlc/testing.json`
+
+(`config.yaml` `testing.registry`.) Create the file and its parent `.sdlc/` on the first `connect`.
+
+## Schema
+
+```json
+{
+  "tool": "playwright",                              // playwright | cypress | pytest | <adapter id> | none (artifacts-only)
+  "provider": "playwright-mcp",                      // the concrete MCP: playwright-mcp | cypress-mcp | pytest-mcp | null
+  "project_url": "tests/playwright.config.ts",       // project/config reference; null if none yet
+  "auth": "user",                                    // ALWAYS the user's own MCP session — never a token
+  "suites": { "backend": null, "mobile": null },     // optional default suite refs per repo
+  "connectedAt": "2026-06-13",                       // first connect (YYYY-MM-DD)
+  "lastSyncedAt": "2026-06-13",                       // last connect/refresh
+  "source": "playwright-mcp"                          // the MCP detected at connect | unavailable (degraded)
+}
+```
+
+## Rules
+
+- **`tool`** selects the adapter; it MUST be one of `config.yaml` `testing.tools` (or `none`). At
+  **connect** time an unknown tool is normalized to `testing.primary` with a warning (so the registry
+  never persists an unknown value); a registry hand-edited to an unknown or missing tool **fails
+  `doctor`** with `YAD-CFG-003` and must be fixed.
+- **Auth is never stored.** No token, API key, or any credential in the registry. `project_url` and
+  `suites` are plain references; `connect` reaches the tool through the user's authenticated MCP session.
+- **`connect` overwrites in place** — a project carries exactly one testing connection at a time;
+  switching tools is just another `connect`. There is no array (unlike `repos.json`).
+- **`source`** is the authority for availability: an MCP id (`playwright-mcp` / `cypress-mcp` / …) means
+  `yad-test-cases` can generate/link; `unavailable` means `yad-test-cases` degrades to artifacts-only.
+  `refresh` re-detects and may flip it.
+- **`tool: "none"`** is a valid, deliberate state: a project that has chosen artifacts-only.
+  `yad-test-cases` treats it exactly like an absent registry.
+- **`disconnect`** removes the file (or sets `tool: "none"`). The testing tool's own project/suites are
+  never touched.
+
+## Git tracking
+
+Commit the **registry** (`testing.json`) — it is small, reviewable, and holds no secrets (references
+only). This mirrors how `repos.json`, `hub.json`, and `design.json` are committed.
+
+## Greenfield
+
+A brand-new product hub has no `testing.json`. That is valid — `yad-test-cases` treats "no testing tool
+connected" the same as `tool: "none"` and produces the Markdown test-case artifact only. The registry
+appears the first time `connect` runs.

package/skills/yad-epic/SKILL.md

@@ -14,7 +14,7 @@ drafted, control passes to `yad-review-gate`.
 - **Analysis ran** — `.sdlc/state.json` already exists with `currentStep == "epic"`. The epic **reads
   `analysis.md`** as its shaped input and does not re-seed state.
 - **Analysis skipped** (the default) — no `state.json` yet. The epic is the entry point: it shapes the
-  idea inline with the analyst, assigns `EP-<slug>`, and seeds the **8-step** chain.
+  idea inline with the analyst, assigns `EP-<slug>`, and seeds the **10-step** chain.
 
 This skill enforces the build plan's core rules: all state lives in files; IDs are generated by the
 engine (never typed by hand); front steps are locked to `human_approve`.
@@ -105,9 +105,9 @@ Fill the body with the user; leave `owner` / `technical_product_owner` for the u
 `repos` to the repos this epic will touch.
 
 ### Step 5 — Seed the state machine — analysis-skipped only
-*(Skip when analysis ran — `yad-analysis` already seeded the 10-step chain. Go to Step 5b.)*
-Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **8-step** front-state
-sequence (no analysis), all steps defaulting to `automation: human_approve`, with the four authoring
+*(Skip when analysis ran — `yad-analysis` already seeded the 12-step chain. Go to Step 5b.)*
+Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **10-step** front-state
+sequence (no analysis), all steps defaulting to `automation: human_approve`, with the five authoring
 steps **locked**. Use this exact shape (see `references/state-schema.md`):
 
 ```json
@@ -123,7 +123,9 @@ steps **locked**. Use this exact shape (see `references/state-schema.md`):
     { "id": "ui-design",          "type": "author",         "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
     { "id": "ui-design-review",   "type": "review+approve", "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
     { "id": "stories",            "type": "author",         "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
-    { "id": "stories-review",     "type": "review+approve", "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] }
+    { "id": "stories-review",     "type": "review+approve", "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "test-cases",         "type": "author",         "artifact": "test-cases.md",    "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
+    { "id": "test-cases-review",  "type": "review+approve", "artifact": "test-cases.md",    "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] }
   ]
 }
 ```
@@ -131,6 +133,9 @@ steps **locked**. Use this exact shape (see `references/state-schema.md`):
 Notes:
 - `architecture-review` carries `risk_tags: ["contract"]` so the gate escalates it by default
   (build plan §4): the contract review needs domain owners, not just owner + 1.
+- `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `blocked` and open
+  when `stories-review` passes — at which point the epic is already `ready-for-build`, so the build half
+  runs alongside the tester. They never gate `ready-for-build` (see `references/state-schema.md`).
 - Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
   and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
   `[]`, and the `reviews/` directory. (`comments.json` is the machine-readable counterpart to the

package/skills/yad-epic/references/state-schema.md

@@ -17,7 +17,7 @@ Each `steps[]` entry:
 
 | Field | Values | Meaning |
 |-------|--------|---------|
-| `id` | `analysis`, `analysis-review`, `epic`, `epic-review`, `architecture`, `architecture-review`, `ui-design`, `ui-design-review`, `stories`, `stories-review` | Step identity. |
+| `id` | `analysis`, `analysis-review`, `epic`, `epic-review`, `architecture`, `architecture-review`, `ui-design`, `ui-design-review`, `stories`, `stories-review`, `test-cases`, `test-cases-review` | Step identity. |
 
 ### Two valid chain shapes (analysis is optional)
 
@@ -26,20 +26,37 @@ ran `yad-analysis` before the epic. The entry-point skill (whichever runs first)
 that assigns `EP-<slug>` and seeds `state.json` + the empty ledgers; the other skill detects an
 existing `state.json` and does **not** re-seed.
 
-- **With analysis** (10 steps — `yad-analysis` seeded the chain):
+- **With analysis** (12 steps — `yad-analysis` seeded the chain):
   `analysis → analysis-review → epic → epic-review → architecture → architecture-review → ui-design →
-  ui-design-review → stories → stories-review`. Seeded `currentStep` is `analysis-review`; `epic`
-  starts `blocked`.
-- **Without analysis** (8 steps — `yad-epic` is the entry point, the default):
-  `epic → epic-review → … → stories-review`. Seeded `currentStep` is `epic-review`.
-
-After `stories-review` passes, `currentStep` becomes the `ready-for-build` sentinel either way.
-`analysis-review` carries no `risk_tags` (base rule: owner + 1 reviewer).
+  ui-design-review → stories → stories-review → test-cases → test-cases-review`. Seeded `currentStep`
+  is `analysis-review`; `epic` starts `blocked`.
+- **Without analysis** (10 steps — `yad-epic` is the entry point, the default):
+  `epic → epic-review → … → stories-review → test-cases → test-cases-review`. Seeded `currentStep` is
+  `epic-review`.
+
+`analysis-review`, `ui-design-review`, and `test-cases-review` carry no `risk_tags` (base rule:
+owner + 1 reviewer).
+
+### `test-cases` is a parallel, non-blocking track
+
+`test-cases` (and its `test-cases-review` gate) sit in `steps[]` after `stories-review`, but they are a
+**parallel track that does not gate the build half**. When `stories-review` passes, `advanceState`:
+- sets `currentStep` to the **`ready-for-build`** sentinel — so the build half (`yad-spec` → … keyed off
+  `currentStep == "ready-for-build"`) can start **immediately**, and
+- opens `test-cases` (`blocked` → `in_progress`) so the tester can work **in parallel**.
+
+The `test-cases` track is therefore driven by its own step `status`, **not** by `currentStep`:
+`yad-test-cases` proceeds when `test-cases.status == "in_progress"`, and neither it nor the
+`test-cases-review` gate (`advanceState` / `markInReview`) ever moves `currentStep` away from
+`ready-for-build`. So implementation and test-case authoring run at the same time; the epic is
+`ready-for-build` the moment the **stories** gate passes, whether or not test cases are done. (For an old
+epic seeded before this step existed, `stories-review` → `ready-for-build` with no test-cases track —
+unchanged.)
 
 ### Authoring branches
 
 Each front **authoring** step opens its own git branch at the start of the step, named
-`<step>/EP-<slug>` where `<step>` ∈ `analysis | epic | architecture | ui-design | stories`
+`<step>/EP-<slug>` where `<step>` ∈ `analysis | epic | architecture | ui-design | stories | test-cases`
 (`config.yaml` `defaults.front_authoring_branch`). This is **distinct** from the review branch
 `review/EP-<slug>/<artifact-base>` that `yad-hub-bridge` opens later for the review PR/MR.
 
@@ -99,6 +116,20 @@ chain is unchanged — this is an *output enrichment*, mirrored by the `design:`
   "source": "<mcp id>" }
 ```
 
+## `test-links.json`
+Present only when the `test-cases` step materialized automation in a connected testing tool
+(`yad-connect-testing` → `.sdlc/testing.json`). Written by `yad-test-cases`, the machine-readable
+case→test map (sibling of `contract-lock.json` / `design-links.json`; the locked `state.json` step shape
+is untouched). The `test-cases` step chain is unchanged — this is an *output enrichment*, mirrored by the
+`testing:` frontmatter block and the `## Automation (<tool>)` section in `test-cases.md`. Absent when the
+step ran artifacts-only (`testing: none`).
+
+```json
+{ "tool": "playwright", "suite": "<url/path>", "generatedAt": "<YYYY-MM-DD>", "direction": "generated|linked",
+  "tests": [ { "case": "<id>", "story": "EP-<slug>-S0N", "repo": "<name>", "level": "unit|integration|e2e", "path": "<test path>", "url": "<url>" } ],
+  "source": "<mcp id>" }
+```
+
 ## `reviews/`
 Human-readable review records, one file per round:
 `reviews/<artifact-base>--<YYYY-MM-DD>--<status>.md` where `status` ∈ `comments` | `approved`
@@ -106,7 +137,7 @@ and `<artifact-base>` is the artifact without extension (e.g. `epic`, `architect
 
 ## Dial defaults & locks
 - Every step defaults to `automation: human_approve` (build plan §2).
-- The four authoring front steps and their reviews are `locked: true` — the engine refuses to set
+- The five authoring front steps and their reviews are `locked: true` — the engine refuses to set
   them to `machine_advance` in this version (build plan §1, §8.7). Only back states (build pipeline,
   steps 9–14) may move toward machine-advance in a later iteration.
 

package/skills/yad-hub-bridge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-hub-bridge
-description: 'The templated PR/MR bridge for the front-half review gate. When the product hub has a platform (.sdlc/hub.json), it opens a review PR/MR on the hub for an authored artifact (the optional analysis / epic / architecture+contract / ui-design / stories), sets the required reviewers/labels from the routing rule, and provides the read-only gh/glab recipes that yad-review-gate uses to pull platform comments + approvals back into the file ledger. Can also wire event-driven sync on the hub: a CI workflow that runs `yad gate ci` whenever a reviewer approves / requests changes / a human merges, committing the ledger to the default branch. Local-user auth only — no stored tokens. The file ledger stays the source of truth; degrades to the file-only gate when there is no platform / no CLI. Use when the user says "open the review PR", "route the review", "wire the gate sync", or it is invoked by yad-review-gate open/sync.'
+description: 'The templated PR/MR bridge for the front-half review gate. When the product hub has a platform (.sdlc/hub.json), it opens a review PR/MR on the hub for an authored artifact (the optional analysis / epic / architecture+contract / ui-design / stories / test-cases), sets the required reviewers/labels from the routing rule, and provides the read-only gh/glab recipes that yad-review-gate uses to pull platform comments + approvals back into the file ledger. Can also wire event-driven sync on the hub: a CI workflow that runs `yad gate ci` whenever a reviewer approves / requests changes / a human merges, committing the ledger to the default branch. Local-user auth only — no stored tokens. The file ledger stays the source of truth; degrades to the file-only gate when there is no platform / no CLI. Use when the user says "open the review PR", "route the review", "wire the gate sync", or it is invoked by yad-review-gate open/sync.'
 ---
 
 # SDLC — Hub Review Bridge (the templated PR/MR bridge)
@@ -29,7 +29,7 @@ keeps platform mechanics out of the gate). `yad-review-gate` *calls* it; it neve
 ## Inputs
 
 - `epic`     — the `EP-<slug>` under review.
-- `artifact` — the artifact file (`analysis.md` | `epic.md` | `architecture.md` | `ui-design.md` | `stories/`).
+- `artifact` — the artifact file (`analysis.md` | `epic.md` | `architecture.md` | `ui-design.md` | `stories/` | `test-cases.md`).
 - `action`   — `open` | `route` | `wire` (default `route`). (`sync`'s ledger writes live in
   `yad-review-gate`; this skill provides the read recipes `sync` calls — see `references/bridge.md`.)
 

package/skills/yad-review-gate/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: yad-review-gate
-description: 'The reusable team review + approve gate for the SDLC. Shares an authored artifact for review, records reviewer comments and approvals as files, enforces the owner + 1 reviewer rule (escalating to domain owners on contract/auth/payments), and advances the epic state ONLY when approval is recorded. Use when the user says "review the analysis/epic/architecture/UI/stories", "comment", "approve", or "advance the gate".'
+description: 'The reusable team review + approve gate for the SDLC. Shares an authored artifact for review, records reviewer comments and approvals as files, enforces the owner + 1 reviewer rule (escalating to domain owners on contract/auth/payments), and advances the epic state ONLY when approval is recorded. Use when the user says "review the analysis/epic/architecture/UI/stories/test-cases", "comment", "approve", or "advance the gate".'
 ---
 
 # SDLC — Team Review Gate (build plan §3 piece 2, §4, §5)
 
 **Goal:** One reusable step type that turns any authored artifact into a gated, human-approved
 review. Every `review+approve` step in the workflow (the optional analysis, epic, architecture+contract,
-UI, stories) uses this exact gate. **No step advances until its review is approved** and recorded as a
-file. The `analysis-review` and `epic`/`ui-design` reviews use the **base** rule (owner + 1 reviewer);
-escalation applies only where `risk_tags` or per-repo routing call for it.
+UI, stories, test-cases) uses this exact gate. **No step advances until its review is approved** and
+recorded as a file. The `analysis-review`, `epic`/`ui-design`, and `test-cases` reviews use the **base**
+rule (owner + 1 reviewer); escalation applies only where `risk_tags` or per-repo routing call for it.
 
 This gate is **swappable and file-driven**: it talks only through files. A front step advances only on a
 human act — recording an approval and `advance`, or (with the bridge) **merging the approved,
@@ -87,7 +87,7 @@ counterpart to `approvals.json`):
 Then help the **owner address the comments** using the agent lens listed for this step
 (analysis → `analyst`; epic → `pm`; architecture → `architect`; ui-design → `ux-designer`;
 stories → `pm`, with `architect` for technical detail — there is **no `sm` agent**, Phase 0
-Deviation 1). Update the authored artifact in place.
+Deviation 1; test-cases → `test architect` / Murat, `bmad-tea`). Update the authored artifact in place.
 Repeat comment→address rounds until reviewers are satisfied. **Commenting never advances the gate.**
 
 **`approve`** — Record an approval. Append to `.sdlc/approvals.json`:
@@ -153,13 +153,16 @@ If the predicate **fails**: report exactly which approvals are still missing and
 
 If the predicate **passes**:
 - Mark this review step `status: "done"`.
-- If there **is** a next step in `steps[]`: set it `status` from `blocked` to `in_progress`
-  (authoring) or `in_review`, and set `currentStep` to that next step.
-- If this is the **last** step (`stories-review`, the final review): there is no further front step —
-  set `currentStep: "ready-for-build"` (the Phase 3 handoff sentinel; it is intentionally not a
-  `steps[]` entry). The front half is complete.
+- **`stories-review`** is the end of the gating chain: set `currentStep: "ready-for-build"` (the Phase 3
+  handoff sentinel; intentionally not a `steps[]` entry) **and** open the parallel **`test-cases`** track
+  (set its step `blocked` → `in_progress`). The build half can now start **and** the tester can work
+  `test-cases` at the same time.
+- **`test-cases-review`** is the parallel track's gate: mark it `done` but **leave `currentStep` at
+  `ready-for-build`** — completing test cases must never pull the epic back from the build half.
+- Any **other** review step: set the next step in `steps[]` from `blocked` to `in_progress` (authoring)
+  or `in_review`, and set `currentStep` to that next step.
 - Write `state.json`. Report the advance and what the next authored artifact is (or that the epic is
-  now `ready-for-build`).
+  now `ready-for-build`, with `test-cases` running in parallel).
 
 ### PR-driven automation (the `yad gate` CLI)
 When the hub has a platform, the mechanical `open`/`sync`/`advance` is performed deterministically by the