yadflow 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -1,16 +1,9 @@
-# [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-13)
-
-
-### Bug Fixes
-
-* address code review on the design-tool connection ([1275146](https://github.com/abdelrahmannasr/yadflow/commit/1275146e9e24251d481d90eb26894a729e894997))
+# [2.3.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.2.0...v2.3.0) (2026-06-13)
 
 
 ### Features
 
-* add yad-connect-design skill (Figma-first, pluggable) ([d1de46d](https://github.com/abdelrahmannasr/yadflow/commit/d1de46d2b08995db0228e60a58877649649b5cd0))
-* materialize the feature design in yad-ui (generate or link) ([e440571](https://github.com/abdelrahmannasr/yadflow/commit/e44057131e86fed45d9a9c4151cd762eb98f24e8))
-* wire the design-tool connection through the CLI ([1867ed4](https://github.com/abdelrahmannasr/yadflow/commit/1867ed433dd57025ae4143f5a236db32f1a99c41))
+* add parallel test-cases step with pluggable testing-tool connection ([#45](https://github.com/abdelrahmannasr/yadflow/issues/45)) ([19c282f](https://github.com/abdelrahmannasr/yadflow/commit/19c282f6bd737364bca122179b05de8ea94493a9))
 
 # [1.1.0](https://github.com/abdelrahmannasr/sdlc-workflow/compare/v1.0.3...v1.1.0) (2026-06-09)
 

package/README.md

@@ -49,8 +49,9 @@ human**. Detailed walkthroughs for each phase follow below.
 | `skills/yad-architecture/` | Front state 3: author `architecture.md` + the locked `contract.md`; hash-lock the contract surface. |
 | `skills/yad-ui/` | Front state 5: author `ui-design.md` + `DESIGN.md` (Impeccable slash-commands, or graceful fallback). |
 | `skills/yad-stories/` | Front state 7: break the epic into repo-tagged stories with stable `EP-<slug>-S0N` IDs. |
+| `skills/yad-test-cases/` | Front state 9: with the test architect author `test-cases.md`; implement the automation in the connected testing tool, or produce artifacts only. |
 | `skills/yad-connect-repos/` | Connect code repos to the hub (GitHub/GitLab, local-user auth); cache a Repomix pack + **code-map** per repo so the front phases are code-aware. |
-| `skills/yad-review-gate/` | The reusable **team review + approve gate** (used for all four reviews). |
+| `skills/yad-review-gate/` | The reusable **team review + approve gate** (used for all five reviews). |
 | `skills/yad-spec/` | Build Step A: run the Spec Kit ceremony once per story per repo → `specs/<story-id>/`. |
 | `skills/yad-implement/` | Build Step B: implement ONE atomic task as a small diff on its own branch. |
 | `skills/yad-checks/` | Build Step C: wire + run the CI gates (spec-link, contract-check, build/test/lint, verified-commits). |
@@ -122,18 +123,21 @@ a manual `yad gate sync` racing CI, or GitLab pipelines — two simultaneous syn
 *commits* via the rebase retry but each works from the state it read at start, so the rarer of two
 simultaneous advancements can be lost; the next event or scheduled sweep re-syncs and converges.
 
-### What `setup` walks you through (8 steps)
+### What `setup` walks you through (9 steps)
 
 1. **Preflight** — confirm the hub is a git repo (offers `git init`); check `git`/`node`/`npx`.
-2. **Install the module** — copy all 18 `yad-*` skills into the IDE skill dirs you pick
+2. **Install the module** — copy all 20 `yad-*` skills into the IDE skill dirs you pick
    (`.claude/`, `.agents/`, `.zencoder/`, `.opencode/`) and register `_bmad/sdlc/`.
 3. **Hub platform & roster** — detect GitHub/GitLab from the remote; record reviewers → `.sdlc/hub.json`.
 4. **Connect a design tool** — record the design tool (Figma / pencil / none) → `.sdlc/design.json` so
    the UI step can materialize the design; the MCP itself is confirmed later by `yad-connect-design`.
-5. **Connect code repos** — register each repo into `.sdlc/repos.json` and cache a Repomix pack.
-6. **Wire each repo** — CI gates, PR/MR template, and review-comment scaffold.
-7. **AI review** — optionally write `.coderabbit.yaml`.
-8. **Done** — stamp `.sdlc/cli-version.json` and hand off the AI-only steps (code-maps; first epic).
+5. **Connect a testing tool** — record the testing tool (Playwright / cypress / pytest / none) →
+   `.sdlc/testing.json` so the test-cases step can implement the automation; the MCP itself is confirmed
+   later by `yad-connect-testing`.
+6. **Connect code repos** — register each repo into `.sdlc/repos.json` and cache a Repomix pack.
+7. **Wire each repo** — CI gates, PR/MR template, and review-comment scaffold.
+8. **AI review** — optionally write `.coderabbit.yaml`.
+9. **Done** — stamp `.sdlc/cli-version.json` and hand off the AI-only steps (code-maps; first epic).
 
 The deterministic file work runs automatically; the AI-only steps are handed to the Claude Code skills
 with a printed next-action. Re-run `… check --fix` any time the workflow updates — it never re-asks for
@@ -170,10 +174,11 @@ with a fix-it hint per finding. Failures carry stable, greppable codes, also pri
 | `YAD-STATE-003` | a registered repo path is missing or not a git repo | fix the path in `.sdlc/repos.json` or re-connect the repo |
 | `YAD-CFG-001` | `hub.json` names an unknown platform | expected `github`, `gitlab`, or `null` — fix it or re-run `yad setup` |
 | `YAD-CFG-002` | `design.json` names an unknown design tool | expected one of `config.yaml` `design.tools` (e.g. `figma`, `pencil`), or `none` — fix it or re-run `yad setup` |
+| `YAD-CFG-003` | `testing.json` names an unknown testing tool | expected one of `config.yaml` `testing.tools` (e.g. `playwright`, `cypress`, `pytest`), or `none` — fix it or re-run `yad setup` |
 
 Filing a bug? Attach `yad doctor --json` — it contains no secrets (names, paths, and check results only).
 
-## Agent skills (all 18)
+## Agent skills (all 20)
 
 The CLI **installs and wires** the module; the skills below are the **agents you invoke by name** in your
 AI IDE (e.g. *“run `yad-epic`”*) to actually do the work. State lives in files you can also edit
@@ -191,12 +196,17 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
   Records the tool + project/file references in `.sdlc/design.json` (local-user / MCP-session auth, no
   stored tokens), detecting the design-tool MCP and degrading to markdown-only when absent. Idempotent
   and refreshable; one connection per project.
+- **`yad-connect-testing`** — Connects a testing tool (Playwright-first, pluggable) so the test-cases
+  step can implement the actual automation tests inside it, alongside the Markdown. Records the tool +
+  project/suite references in `.sdlc/testing.json` (local-user / MCP-session auth, no stored tokens),
+  detecting the testing-tool MCP and degrading to artifacts-only when absent. Idempotent and
+  refreshable; one connection per project.
 
 ### Front half — author the "thinking" (once per epic, human-gated)
 
 - **`yad-analysis`** — *Optional* front state 1. 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). If skipped, the epic step does this shaping inline.
+  (the 12-step chain that puts analysis before epic). If skipped, the epic step does this shaping inline.
 - **`yad-epic`** — The epic front state. Shape the idea with the analyst (or read `analysis.md`
   when it already ran), then write the epic with the pm into `epic.md`. The entry point when analysis is
   skipped: assigns the `EP-<slug>` ID and seeds `.sdlc/` state.
@@ -211,6 +221,13 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
 - **`yad-stories`** — Front state 7. With the pm, break the approved epic into user stories, each
   tagged with the repos that must implement it. Assigns zero-padded `EP-<slug>-S0N` IDs, one file per
   story under `stories/`. Reads epic + architecture + contract + UI.
+- **`yad-test-cases`** — Front state 9, a **parallel, non-blocking** track: it opens when the stories
+  gate passes (the epic is already `ready-for-build`, so the build half runs alongside it). With the
+  test architect (Murat), author `test-cases.md` covering the approved stories (risk-based P0–P3 cases +
+  story→case traceability). When a testing tool is connected (`yad-connect-testing`), also **implements
+  the automation tests** in the connected code repo(s) (generate or link), recording the case→test map in
+  `test-links.json`; degrades to artifacts-only otherwise. Reads epic + architecture + contract + UI +
+  stories.
 
 ### The review gate (cross-cutting — used by every review)
 
@@ -269,7 +286,7 @@ merging the approved, fully-resolved review PR — never on a machine.
 
 As of **Phase 4a** the `automation` dial is no longer inert: the orchestrator `yad-run` reads it and,
 for the safe **back** steps, advances on its own when a step is set to `machine_advance` (and has
-*earned* it — see "Run the back half on the dial" below). The engineer review and all four front
+*earned* it — see "Run the back half on the dial" below). The engineer review and all five front
 states stay `human_approve` forever.
 
 ## Using the workflow end to end (all the steps, in order)
@@ -320,7 +337,10 @@ threads are resolved. Details: **“Run the full front half by hand”** below.
 7. `yad-architecture` → `architecture.md` + locked `contract.md` → review (**escalated**: contract).
 8. `yad-ui` → `ui-design.md` + `DESIGN.md` → review (base rule).
 9. `yad-stories` → repo-tagged `stories/EP-<slug>-S0N.md` → review (**per-repo**).
-   → `state.json` reaches `currentStep: ready-for-build`.
+   → `state.json` reaches `currentStep: ready-for-build` — **the build half can start now.**
+10. `yad-test-cases` → `test-cases.md` (+ automation tests when a testing tool is connected) → review (base rule).
+    **Parallel, non-blocking:** opens when the stories gate passes and runs alongside the build half; its
+    review never moves `currentStep` off `ready-for-build`.
 
 ### B — Build half (per story, per repo)
 From a `ready-for-build` story, for **each** repo the story is tagged with. Details: **“Run the full
@@ -355,12 +375,13 @@ Details: **“Run the back half on the dial”** below.
 ## Run the full front half by hand
 
 The front half walks **epic → review → architecture+contract → review → UI design → review → stories
-→ review → `ready-for-build`**. It is all files under `epics/EP-<slug>/`. The skills below guide you,
-but you can also edit the files directly — that's the point.
+→ review → `ready-for-build`**, then **test cases → review** runs as a **parallel, non-blocking track**
+alongside the build half. It is all files under `epics/EP-<slug>/`. The skills below guide you, but you
+can also edit the files directly — that's the point.
 
 Each authoring step is the same shape: an author skill produces an artifact, sets its step `done`,
 moves `currentStep` to the matching review, and **stops at the gate**. Then **`yad-review-gate`**
-(one gate, reused for all four reviews) takes `open → comment → approve → advance`. When the hub is on a
+(one gate, reused for all five reviews) takes `open → comment → approve → advance`. When the hub is on a
 platform, the **`yad gate`** CLI runs that gate over a real PR/MR — `open` raises the review PR, `sync`
 pulls approvals + comment threads into the ledger, and the step **auto-advances when the approved,
 fully-resolved PR is merged** (the merge is the human approval act).
@@ -417,7 +438,7 @@ accumulate, and the step moves forward only when the rule is met. **File-only**
   in any story's `repos`**.
 
 ### Check status anytime
-Invoke **`yad-status`** (read-only) to see the full 8-step chain, every step's dials/status, the
+Invoke **`yad-status`** (read-only) to see the full 10-step chain, every step's dials/status, the
 contract lock, story repo tags, and which approvals the active gate still needs.
 
 ## Worked example (already in this repo)

package/cli/doctor.mjs

@@ -5,7 +5,7 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { c, log, ok, info, warn, fail, hand, run, has, exists, readJSON, readJSONStrict } from './lib.mjs';
-import { VERSION, PROJECT_FILES, DESIGN_TOOLS } from './manifest.mjs';
+import { VERSION, PROJECT_FILES, DESIGN_TOOLS, TESTING_TOOLS } from './manifest.mjs';
 import { loadLedger, epicRoot } from './epic-state.mjs';
 import { gitHead } from './setup.mjs';
 import { cliFor } from './platform.mjs';
@@ -88,13 +88,33 @@ export function projectChecks(checks, root) {
     }
     if (designBroken) { /* reported above */ }
     else if (typeof design !== 'object' || Array.isArray(design) || design === null) check(checks, 'design', 'project', 'fail', `${PROJECT_FILES.designConfig} has the wrong shape [YAD-STATE-002]`, 'expected a JSON object');
-    else if (![...DESIGN_TOOLS, 'none', null, undefined].includes(design.tool)) check(checks, 'design', 'project', 'fail', `${PROJECT_FILES.designConfig}: unknown design tool '${design.tool}' [YAD-CFG-002]`, `expected one of ${DESIGN_TOOLS.join(', ')}, or none`);
-    else if (!design.tool || design.tool === 'none') check(checks, 'design', 'project', 'ok', 'design: markdown-only');
+    else if (design.tool === 'none') check(checks, 'design', 'project', 'ok', 'design: markdown-only');
+    else if (!DESIGN_TOOLS.includes(design.tool)) check(checks, 'design', 'project', 'fail', `${PROJECT_FILES.designConfig}: unknown or missing design tool '${design.tool}' [YAD-CFG-002]`, `expected one of ${DESIGN_TOOLS.join(', ')}, or none`);
     else if (design.source && design.source !== 'unavailable') check(checks, 'design', 'project', 'ok', `design: ${design.tool} (${design.source})`);
     else if (design.source === 'unavailable') check(checks, 'design', 'project', 'warn', `design: ${design.tool} MCP unavailable — yad-ui runs markdown-only`, 'connect the MCP, then run `yad-connect-design` (action: refresh)');
     else check(checks, 'design', 'project', 'warn', `design: ${design.tool} recorded but the MCP is not confirmed`, 'run `yad-connect-design` in Claude Code to detect the MCP');
   }
 
+  // testing.json: parse + shape + tool + MCP confirmation (absent is the normal artifacts-only default —
+  // pre-feature projects have none, so silence rather than warn when the file does not exist).
+  const testingPath = path.join(root, PROJECT_FILES.testingConfig);
+  if (exists(testingPath)) {
+    let testing = null, testingBroken = false;
+    try {
+      testing = readJSONStrict(testingPath, null);
+    } catch (e) {
+      testingBroken = true;
+      check(checks, 'testing', 'project', 'fail', `${PROJECT_FILES.testingConfig} does not parse [${e.code || 'YAD-STATE-001'}]`, e.hint || 'fix the JSON or restore it from git');
+    }
+    if (testingBroken) { /* reported above */ }
+    else if (typeof testing !== 'object' || Array.isArray(testing) || testing === null) check(checks, 'testing', 'project', 'fail', `${PROJECT_FILES.testingConfig} has the wrong shape [YAD-STATE-002]`, 'expected a JSON object');
+    else if (testing.tool === 'none') check(checks, 'testing', 'project', 'ok', 'testing: artifacts-only');
+    else if (!TESTING_TOOLS.includes(testing.tool)) check(checks, 'testing', 'project', 'fail', `${PROJECT_FILES.testingConfig}: unknown or missing testing tool '${testing.tool}' [YAD-CFG-003]`, `expected one of ${TESTING_TOOLS.join(', ')}, or none`);
+    else if (testing.source && testing.source !== 'unavailable') check(checks, 'testing', 'project', 'ok', `testing: ${testing.tool} (${testing.source})`);
+    else if (testing.source === 'unavailable') check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} MCP unavailable — yad-test-cases runs artifacts-only`, 'connect the MCP, then run `yad-connect-testing` (action: refresh)');
+    else check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} recorded but the MCP is not confirmed`, 'run `yad-connect-testing` in Claude Code to detect the MCP');
+  }
+
   // repos.json: parse + every entry is a live git repo; staleness vs syncedHead
   let registry = { repos: [] };
   let regBroken = false;

package/cli/epic-state.mjs

@@ -197,9 +197,24 @@ export function gatePredicate({
 
 // Advance the step in state.json once the predicate passes. Mirrors yad-review-gate Step 3:
 // mark this review step done, unblock the next step, or set `ready-for-build` for the last one.
+//
+// `test-cases` is a PARALLEL, non-blocking track so the build half can start while the tester works:
+// approving `stories-review` makes the epic `ready-for-build` (the build half keys off this) AND opens
+// `test-cases` for the tester; completing `test-cases-review` never pulls `currentStep` back from
+// `ready-for-build`. Both rules degrade safely for an old chain that has no test-cases steps.
 export function advanceState(state, step) {
   const i = state.steps.findIndex((s) => s.id === step.id);
   state.steps[i] = { ...state.steps[i], status: 'done' };
+  if (step.id === 'stories-review') {
+    const tc = state.steps.find((s) => s.id === 'test-cases');
+    if (tc && tc.status === 'blocked') tc.status = 'in_progress';
+    state.currentStep = 'ready-for-build';
+    return state;
+  }
+  if (step.id === 'test-cases-review') {
+    state.currentStep = 'ready-for-build';
+    return state;
+  }
   const next = state.steps[i + 1];
   if (next) {
     next.status = next.type === 'review+approve' ? 'in_review' : 'in_progress';
@@ -210,11 +225,13 @@ export function advanceState(state, step) {
   return state;
 }
 
-// Mark a step in-review (idempotent) and point currentStep at it.
+// Mark a step in-review (idempotent) and point currentStep at it — EXCEPT once the epic is
+// `ready-for-build`: the parallel `test-cases` track must not pull currentStep back (the build half
+// runs alongside the tester, and only the test-cases review is in flight at that point).
 export function markInReview(state, step) {
   const i = state.steps.findIndex((s) => s.id === step.id);
   if (state.steps[i].status !== 'done') state.steps[i].status = 'in_review';
-  state.currentStep = step.id;
+  if (state.currentStep !== 'ready-for-build') state.currentStep = step.id;
   return state;
 }
 

package/cli/errors.mjs

@@ -21,6 +21,7 @@ export const CODES = {
   'YAD-STATE-003': 'a registered repo path is missing or not a git repository',
   'YAD-CFG-001': 'hub.json names an unknown platform (expected github, gitlab, or null)',
   'YAD-CFG-002': 'design.json names an unknown design tool (expected one of config.yaml design.tools, or none)',
+  'YAD-CFG-003': 'testing.json names an unknown testing tool (expected one of config.yaml testing.tools, or none)',
 };
 
 export const err = (code, message, hint) => new YadError(code, message, hint);

package/cli/manifest.mjs

@@ -10,15 +10,17 @@ import { readFileSync } from 'node:fs';
 const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 export const VERSION = version;
 
-// The 18 hand-authored yad-* skills (mirrors skills/sdlc/install.sh).
+// The 20 hand-authored yad-* skills (mirrors skills/sdlc/install.sh).
 export const 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',
@@ -87,11 +89,19 @@ export const MODULE_FILES = ['config.yaml', 'module-help.csv'];
 export const DESIGN_TOOLS = ['figma', 'pencil'];
 export const DESIGN_PRIMARY = 'figma';
 
+// Supported testing-tool adapters (mirrors skills/sdlc/config.yaml `testing.tools`); `TESTING_PRIMARY`
+// is the fallback `registerTesting`/setup use when an unknown tool is named, and `none` is the explicit
+// artifacts-only choice. (doctor does NOT fall back — an unknown tool there is a hard YAD-CFG-003 fail,
+// mirroring the design-tool YAD-CFG-002.)
+export const TESTING_TOOLS = ['playwright', 'cypress', 'pytest'];
+export const TESTING_PRIMARY = 'playwright';
+
 // Project-level files setup produces (used by `check` to spot missing setup).
 export const PROJECT_FILES = {
   reposRegistry: '.sdlc/repos.json',
   hubConfig: '.sdlc/hub.json',
   designConfig: '.sdlc/design.json',
+  testingConfig: '.sdlc/testing.json',
   version: '.sdlc/cli-version.json',
 };
 

package/cli/setup.mjs

@@ -5,7 +5,7 @@ import {
   c, log, step, ok, info, warn, hand, fail, ask, askYesNo, run, has,
   exists, readJSON, writeJSON,
 } from './lib.mjs';
-import { VERSION, IDE_FOLDER_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY } from './manifest.mjs';
+import { VERSION, IDE_FOLDER_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY, TESTING_TOOLS, TESTING_PRIMARY } from './manifest.mjs';
 import { moduleActions, repoActions, hubActions, authorsActions } from './plan.mjs';
 
 const ALL_IDES = [...IDE_FOLDER_TARGETS, '.opencode'];
@@ -87,6 +87,34 @@ export function registerDesign(root, { tool, project_url = null, files = null, t
   return design;
 }
 
+// Record the project's testing-tool connection into .sdlc/testing.json (the deterministic half of the
+// connect loop; MCP detection itself is an AI step, handed off to `yad-connect-testing`). An unknown
+// tool falls back to the primary adapter rather than being rejected — mirrors registerDesign. `none` is
+// the explicit artifacts-only choice.
+export function registerTesting(root, { tool, project_url = null, suites = null, today = null } = {}) {
+  // Idempotent re-connect: carry the original first-connect date forward; only lastSyncedAt moves.
+  const testingPath = path.join(root, PROJECT_FILES.testingConfig);
+  const prev = readJSON(testingPath, null);
+  const connectedAt = prev && prev.connectedAt ? prev.connectedAt : today;
+  let t = (tool || '').toLowerCase();
+  if (t === 'none' || t === '') {
+    const off = { tool: 'none', provider: null, project_url: null, auth: 'user',
+      suites: {}, connectedAt, lastSyncedAt: today, source: 'unavailable' };
+    writeJSON(testingPath, off);
+    return off;
+  }
+  if (!TESTING_TOOLS.includes(t)) { warn(`unknown testing tool '${tool}' — using ${TESTING_PRIMARY}`); t = TESTING_PRIMARY; }
+  // source stays null until `yad-connect-testing` detects the MCP in the harness (AI step). doctor
+  // reports a recorded-but-unconfirmed connection as a warning pointing at that skill.
+  const testing = {
+    tool: t, provider: null, project_url: project_url || null, auth: 'user',
+    suites: suites || {},
+    connectedAt, lastSyncedAt: today, source: null,
+  };
+  writeJSON(testingPath, testing);
+  return testing;
+}
+
 function applyActions(actions, { force = false } = {}) {
   let changed = 0;
   for (const a of actions) {
@@ -100,7 +128,7 @@ function applyActions(actions, { force = false } = {}) {
 }
 
 export async function runSetup(root, opts = {}) {
-  const total = 8;
+  const total = 9;
   log(c.bold(`\nSDLC Workflow setup  ${c.dim('v' + VERSION)}`));
   log(c.dim(`target: ${root}`));
 
@@ -178,8 +206,26 @@ export async function runSetup(root, opts = {}) {
       : `wrote ${PROJECT_FILES.designConfig} (${tool})`);
   }
 
-  // 5. Connect code repos
-  step(5, total, 'Connect code repos');
+  // 5. Connect a testing tool (Playwright-first, pluggable; the test-cases step implements automation here)
+  step(5, total, 'Connect a testing tool (playwright / cypress / pytest / none)');
+  const testingPath = path.join(root, PROJECT_FILES.testingConfig);
+  if (exists(testingPath) && !(await askYesNo('testing.json exists — reconfigure?', false))) {
+    info('keeping existing .sdlc/testing.json');
+  } else {
+    let tool = (await ask(`Testing tool (${TESTING_TOOLS.join('/')}/none)`, TESTING_PRIMARY)).toLowerCase();
+    if (![...TESTING_TOOLS, 'none'].includes(tool)) {
+      warn(`unknown testing tool '${tool}' — using ${TESTING_PRIMARY}`);
+      tool = TESTING_PRIMARY;
+    }
+    const project_url = tool === 'none' ? null : (await ask('  project/config reference (blank to set later)', '')) || null;
+    registerTesting(root, { tool, project_url, today: opts.today ?? null });
+    ok(tool === 'none'
+      ? `wrote ${PROJECT_FILES.testingConfig} (artifacts-only)`
+      : `wrote ${PROJECT_FILES.testingConfig} (${tool})`);
+  }
+
+  // 6. Connect code repos
+  step(6, total, 'Connect code repos');
   const regPath = path.join(root, PROJECT_FILES.reposRegistry);
   const registry = readJSON(regPath, { repos: [] });
   const known = new Set(registry.repos.map((r) => r.name));
@@ -202,8 +248,8 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 6. Wire each connected repo + the hub itself
-  step(6, total, 'Wire connected repos + the hub (CI gates, PR template, comment scaffold, gate-sync)');
+  // 7. Wire each connected repo + the hub itself
+  step(7, total, 'Wire connected repos + the hub (CI gates, PR template, comment scaffold, gate-sync)');
   if (registry.repos.length === 0) info('no repos to wire');
   for (const repo of registry.repos) {
     log(`  ${c.bold(repo.name)} ${c.dim(`(${repo.platform})`)}`);
@@ -218,8 +264,8 @@ export async function runSetup(root, opts = {}) {
   // author allowlists for the verified-commits gate (hub + every repo), from the roster emails
   applyActions(authorsActions(root, registry.repos), { force: true });
 
-  // 7. Optional CodeRabbit
-  step(7, total, 'AI review (CodeRabbit)');
+  // 8. Optional CodeRabbit
+  step(8, total, 'AI review (CodeRabbit)');
   for (const repo of registry.repos) {
     const cr = path.join(path.resolve(root, repo.path), '.coderabbit.yaml');
     if (exists(cr)) { info(`${repo.name}: .coderabbit.yaml present`); continue; }
@@ -229,8 +275,8 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 8. Summary + version stamp
-  step(8, total, 'Done');
+  // 9. Summary + version stamp
+  step(9, total, 'Done');
   writeJSON(path.join(root, PROJECT_FILES.version), { version: VERSION, ideTargets, updatedAt: opts.today ?? null });
   ok(`stamped ${PROJECT_FILES.version} (v${VERSION})`);
   log('');
@@ -240,6 +286,10 @@ export async function runSetup(root, opts = {}) {
   if (design && design.tool && design.tool !== 'none') {
     hand(`confirm the design tool: run \`yad-connect-design\` to detect the ${design.tool} MCP (or it degrades to markdown-only)`);
   }
+  const testing = readJSON(testingPath, null);
+  if (testing && testing.tool && testing.tool !== 'none') {
+    hand(`confirm the testing tool: run \`yad-connect-testing\` to detect the ${testing.tool} MCP (or it degrades to artifacts-only)`);
+  }
   hand('author your first epic: run `yad-epic`');
   log('');
   log(c.dim('Re-run anytime: `yad check` (report) / `yad check --fix` (reconcile).'));

package/docs/index.html

@@ -284,7 +284,7 @@
     <div class="lane">
       <div class="lane-title">0 · One-time setup (team lead, per project)</div>
       <div class="flow-v">
-        <div class="node plain"><strong>Install the module</strong><small><code>npx yadflow setup</code> — copies the 18 skills into your IDE dirs</small></div>
+        <div class="node plain"><strong>Install the module</strong><small><code>npx yadflow setup</code> — copies the 20 skills into your IDE dirs</small></div>
         <div class="arrow-v">▼</div>
         <div class="node plain"><strong>Wire each repo</strong><small><code>yad-checks</code> · <code>yad-pr-template</code> · <code>yad-review-comments</code> (CI gates, PR template, comment scaffold)</small></div>
         <div class="arrow-v">▼</div>
@@ -292,6 +292,8 @@
         <div class="arrow-v">▼</div>
         <div class="node plain"><strong>Connect a design tool</strong><small><code>yad-connect-design</code> → <code>design.json</code> (Figma-first, pluggable) so <code>yad-ui</code> can materialize the screens <em>(optional — degrades to markdown-only)</em></small></div>
         <div class="arrow-v">▼</div>
+        <div class="node plain"><strong>Connect a testing tool</strong><small><code>yad-connect-testing</code> → <code>testing.json</code> (Playwright-first, pluggable) so <code>yad-test-cases</code> can implement the automation <em>(optional — degrades to artifacts-only)</em></small></div>
+        <div class="arrow-v">▼</div>
         <div class="node plain"><strong>Optional: hub on a platform</strong><small>detect GitHub/GitLab + reviewer roster, so reviews run on real PRs/MRs</small></div>
       </div>
     </div>
@@ -321,7 +323,9 @@
         <div class="arrow-v">▼</div>
         <div class="node gate">gate · stories review<small><strong>per-repo:</strong> base rule + the engineer of each touched repo</small></div>
         <div class="arrow-v">▼</div>
-        <div class="node sentinel"><strong>ready-for-build</strong><small>the front half is done — building can start</small></div>
+        <div class="node sentinel"><strong>ready-for-build</strong><small>the gating front half is done — building can start (and <code>yad-test-cases</code> opens in parallel)</small></div>
+        <div class="arrow-v">▼</div>
+        <div class="node artifact"><strong>yad-test-cases</strong> <em>(parallel · non-blocking)</em><small>opens when the stories gate passes and runs <strong>alongside the build half</strong> — with the test architect → <code>test-cases.md</code> + the automation tests in the connected testing tool (<code>test-links.json</code>) → its own base-rule review. Never blocks <code>ready-for-build</code>.</small></div>
       </div>
     </div>
 
@@ -371,9 +375,10 @@
     contract.md          the LOCKED shared surface (APIs, events, data model)
     ui-design.md         + DESIGN.md (+ the screens in the connected design tool)
     stories/             one file per story (EP-&lt;slug&gt;-S01.md …)
+    test-cases.md        the test cases (+ the automation tests when a testing tool is connected)
     reviews/             reviewer comments, per artifact
     .sdlc/               state.json · approvals.json · contract-lock.json
-                         design-links.json · build-state/ · trust-log.json · build-log.json
+                         design-links.json · test-links.json · build-state/ · trust-log.json · build-log.json
 
 each code repo/
   specs/&lt;story-id&gt;/      spec, plan, tasks (+ link.md back to the story)
@@ -440,8 +445,8 @@ each code repo/
   <div class="term"><strong>State machine</strong><span class="badge b-core">core</span><br>The core design: the workflow is a fixed set of <em>states</em> (steps). Each state does its work and waits at a gate. The states never change — only the <em>trigger</em> (who moves work forward) changes. That is what lets the team start fully manual and automate gradually without rebuilding anything.</div>
   <div class="term"><strong>Product hub (product repo)</strong><span class="badge b-core">core</span><br>The git repo that holds the shared “thinking”: epics, architecture, the contract, UI design, stories, reviews and all state. The brain of the project. Code never lives here.</div>
   <div class="term"><strong>Code repo</strong><span class="badge b-core">core</span><br>A separate git repo holding real application code (e.g. backend, mobile, dashboard). Each story’s spec lives inside the code repo it belongs to, with a link back to the story in the hub.</div>
-  <div class="term"><strong>Skills source (this repo)</strong><span class="badge b-core">core</span><br>The <code>yadflow</code> repo itself — where the 18 skills live and where you pull updates from. No real product work happens inside it.</div>
-  <div class="term"><strong>Front half (“decide” / the brain)</strong><span class="badge b-core">core</span><br>The first half of the workflow, run once per epic in the product hub: analysis (optional) → epic → architecture + contract → UI design → stories — each followed by a human review gate. Permanently human-approved.</div>
+  <div class="term"><strong>Skills source (this repo)</strong><span class="badge b-core">core</span><br>The <code>yadflow</code> repo itself — where the 20 skills live and where you pull updates from. No real product work happens inside it.</div>
+  <div class="term"><strong>Front half (“decide” / the brain)</strong><span class="badge b-core">core</span><br>The first half of the workflow, run once per epic in the product hub: analysis (optional) → epic → architecture + contract → UI design → stories — each followed by a human review gate, ending at <code>ready-for-build</code>. <strong>Test cases</strong> is a parallel, non-blocking track that opens at the stories gate and runs alongside the build half. Permanently human-approved.</div>
   <div class="term"><strong>Back half / build half (“build”)</strong><span class="badge b-core">core</span><br>The second half, run once per story per code repo, inside that repo: spec → implement → checks → PR → ship. These mechanical steps may earn automation over time.</div>
   <div class="term"><strong>Gate</strong><span class="badge b-core">core</span><br>A stopping point after a step. The step writes its output and <em>waits</em>; a human must approve before the workflow moves on. “Every step stops at a gate” is the heart of the whole system.</div>
   <div class="term"><strong>Assistance dial</strong><span class="badge b-core">core</span><br>A per-step setting for how much AI helps with the work: <code>none</code>, <code>review</code> (AI checks human work), or <code>heavy</code> (AI does the drafting, human directs).</div>
@@ -520,7 +525,7 @@ each code repo/
   <div class="term"><strong>Trust threshold</strong><span class="badge b-auto">automation</span><br>The bar a step must clear to earn automation — by default at least 5 runs with ≥80% “approved-unchanged” (configurable in <code>config.yaml</code>).</div>
   <div class="term"><strong>Run verdicts</strong><span class="badge b-auto">automation</span><br>How each engineer review scores an automated run: <code>approved-unchanged</code> (merged exactly as authored — the strongest signal), <code>approved-with-edits</code> (a human fixed it first), <code>rejected</code> (failed).</div>
   <div class="term"><strong>Kill switch</strong><span class="badge b-auto">automation</span><br><code>yad-run action: kill</code> — one move that forces <em>every</em> step system-wide back to <code>human_approve</code> instantly, no code change needed. <code>unkill</code> restores earned automation. Automation is always reversible in one move.</div>
-  <div class="term"><strong>Locked steps</strong><span class="badge b-auto">automation</span><br>The steps that may <em>never</em> be set to <code>machine_advance</code>: all four front authoring steps, their reviews, and the engineer review. A front state advances only on a human act.</div>
+  <div class="term"><strong>Locked steps</strong><span class="badge b-auto">automation</span><br>The steps that may <em>never</em> be set to <code>machine_advance</code>: all five front authoring steps, their reviews, and the engineer review. A front state advances only on a human act.</div>
   <div class="term"><strong>Fleet roll-up</strong><span class="badge b-auto">automation</span><br>The cross-epic summary <code>yad-status</code> prints: where every epic stands, which steps are “earned but still manual” (nudge cost), at a glance.</div>
 
   <h3>Tools the workflow builds on</h3>
@@ -531,7 +536,7 @@ each code repo/
   <div class="term"><strong>CodeRabbit</strong><span class="badge b-tool">tools</span><br>An AI code-review service used as the advisory first pass on PRs. Optional; never the merge authority.</div>
   <div class="term"><strong>Graceful degradation</strong><span class="badge b-tool">tools</span><br>The rule that every optional tool (Spec Kit, Impeccable, Repomix, CodeRabbit) can be absent: the workflow falls back to doing the work directly and <em>records</em> that the tool was missing. You can start with none of them.</div>
   <div class="term"><strong>Tool-agnostic rule</strong><span class="badge b-tool">tools</span><br>Talk to every tool through its commands and files, never through its internal code — so each tool stays swappable.</div>
-  <div class="term"><strong>Skill</strong><span class="badge b-tool">tools</span><br>One of the 18 named agents (e.g. <code>yad-epic</code>) you invoke by name in your AI IDE. Each skill does one step’s work, writes files, and stops at its gate.</div>
+  <div class="term"><strong>Skill</strong><span class="badge b-tool">tools</span><br>One of the 20 named agents (e.g. <code>yad-epic</code>) you invoke by name in your AI IDE. Each skill does one step’s work, writes files, and stops at its gate.</div>
   <div class="term"><strong>The <code>yad</code> CLI</strong><span class="badge b-tool">tools</span><br>A zero-dependency command-line tool (npm: <code>yadflow</code>) that installs, wires and reconciles the workflow (<code>setup</code>, <code>check --fix</code>, <code>update</code>) and runs the deterministic pieces (<code>gate</code>, <code>commit</code>, <code>open-pr</code>, <code>repo</code>).</div>
 
   <h3>People &amp; AI roles</h3>
@@ -574,7 +579,7 @@ each code repo/
     <div class="flow-v">
       <div class="node plain"><strong>Setup</strong><small>install skills · create the hub repo · create empty code repos · wire each repo (CI gates + PR template) · <s>connect-repos</s> <em>skipped — nothing to map yet</em></small></div>
       <div class="arrow-v">▼</div>
-      <div class="node artifact"><strong>Front half</strong><small>(analysis) → epic → architecture + contract → UI (<code>craft</code> → <code>extract</code>) → stories — all human-gated</small></div>
+      <div class="node artifact"><strong>Front half</strong><small>(analysis) → epic → architecture + contract → UI (<code>craft</code> → <code>extract</code>) → stories — all human-gated; then test cases runs in parallel with the build half</small></div>
       <div class="arrow-v">▼</div>
       <div class="node"><strong>Build half</strong><small>spec → implement → checks → PR → ship, per story per repo — specs exist for 100% of the code from day one</small></div>
       <div class="arrow-v">▼</div>
@@ -674,7 +679,7 @@ each code repo/
 
 <!-- ======================================================= -->
 <section id="skills">
-  <h2>6. The 18 skills — what each does, how to use it, and when</h2>
+  <h2>6. The 20 skills — what each does, how to use it, and when</h2>
   <p>A <strong>skill</strong> is an agent you invoke <em>by name</em> in your AI IDE — you just ask in
   plain words, e.g. <em>“run <code>yad-epic</code>”</em>, adding any inputs the skill needs
   (<code>repo: backend</code>, <code>story: EP-…-S01</code>, <code>action: wire</code>, …).
@@ -685,11 +690,13 @@ each code repo/
     <tr><th>Skill</th><th>Half</th><th>One line</th></tr>
     <tr><td><a href="#sk-connect"><code>yad-connect-repos</code></a></td><td>Setup</td><td>Register a code repo with the hub + cache its code-map.</td></tr>
     <tr><td><a href="#sk-connect-design"><code>yad-connect-design</code></a></td><td>Setup</td><td>Connect a design tool (Figma-first) so <code>yad-ui</code> can materialize the screens.</td></tr>
+    <tr><td><a href="#sk-connect-testing"><code>yad-connect-testing</code></a></td><td>Setup</td><td>Connect a testing tool (Playwright-first) so <code>yad-test-cases</code> can implement the automation.</td></tr>
     <tr><td><a href="#sk-analysis"><code>yad-analysis</code></a></td><td>Front</td><td><em>(Optional)</em> pressure-test an idea into <code>analysis.md</code>.</td></tr>
     <tr><td><a href="#sk-epic"><code>yad-epic</code></a></td><td>Front</td><td>Start a feature: write <code>epic.md</code>, assign the ID.</td></tr>
     <tr><td><a href="#sk-arch"><code>yad-architecture</code></a></td><td>Front</td><td>Author <code>architecture.md</code> + the locked <code>contract.md</code>.</td></tr>
     <tr><td><a href="#sk-ui"><code>yad-ui</code></a></td><td>Front</td><td>Author <code>ui-design.md</code> + <code>DESIGN.md</code>; materialize the screens in the connected design tool.</td></tr>
     <tr><td><a href="#sk-stories"><code>yad-stories</code></a></td><td>Front</td><td>Break the epic into repo-tagged stories.</td></tr>
+    <tr><td><a href="#sk-test-cases"><code>yad-test-cases</code></a></td><td>Front</td><td>With the test architect, author the test cases; implement the automation when a testing tool is connected.</td></tr>
     <tr><td><a href="#sk-gate"><code>yad-review-gate</code></a></td><td>Cross-cutting</td><td>Review / comment / approve / advance <strong>any</strong> gate.</td></tr>
     <tr><td><a href="#sk-bridge"><code>yad-hub-bridge</code></a></td><td>Cross-cutting</td><td>Run front-half reviews over real PRs/MRs and sync them back.</td></tr>
     <tr><td><a href="#sk-comments"><code>yad-review-comments</code></a></td><td>Setup</td><td>Install the structured review-comment scaffolds.</td></tr>
@@ -729,6 +736,17 @@ yad-connect-design action: disconnect</code></pre>
     <div class="row"><span class="lbl lbl-when">When</span> During one-time setup (the wizard records it), and again any time you switch design tools. <strong>No design tool? Skip it</strong> — <code>yad-ui</code> simply authors the Markdown, exactly as before.</div>
   </div>
 
+  <div class="skillcard" id="sk-connect-testing">
+    <h4><code>yad-connect-testing</code></h4>
+    <div class="row"><span class="lbl lbl-what">What</span> Connects a <strong>testing tool</strong> to the product hub so the test-cases step can implement the <em>actual</em> automation tests inside it, alongside the Markdown. <strong>Playwright-first but pluggable</strong> (a testing-tool adapter; <code>cypress</code> and <code>pytest</code> are second providers). It records the tool + project/suite references in <code>testing.json</code> through your own authenticated MCP session — <strong>no tokens are ever stored</strong> — and degrades to artifacts-only when no testing-tool MCP is available.</div>
+    <div class="row"><span class="lbl lbl-how">How</span> Run it in the product hub, once per project:</div>
+<pre><code>yad-connect-testing action: connect tool: playwright project_url: tests/playwright.config.ts
+yad-connect-testing action: list                 # show the connection + whether the MCP is available
+yad-connect-testing action: refresh              # re-detect the MCP (after authenticating a session)
+yad-connect-testing action: disconnect</code></pre>
+    <div class="row"><span class="lbl lbl-when">When</span> During one-time setup (the wizard records it), and again any time you switch testing tools. <strong>No testing tool? Skip it</strong> — <code>yad-test-cases</code> simply authors the test cases, exactly as before.</div>
+  </div>
+
   <h3>Front half — author the thinking (in the product hub)</h3>
 
   <div class="skillcard" id="sk-analysis">
@@ -768,7 +786,15 @@ yad-connect-design action: disconnect</code></pre>
     <div class="row"><span class="lbl lbl-what">What</span> With the pm AI, slices the approved epic into user stories small enough to build — one file each under <code>stories/</code>, with stable IDs (<code>EP-&lt;slug&gt;-S01</code>…) and a <code>repos:</code> tag naming which code repos must implement each one. Reads epic + architecture + contract + UI as input.</div>
     <div class="row"><span class="lbl lbl-how">How</span> In the product hub, after the UI gate passes:</div>
 <pre><code>run yad-stories — epic: EP-istifta-inquiries</code></pre>
-    <div class="row"><span class="lbl lbl-when">When</span> The last front-half author step. Stops at the <strong>stories review gate</strong> (per-repo rule). When that gate passes, the epic is <code>ready-for-build</code>.</div>
+    <div class="row"><span class="lbl lbl-when">When</span> After the UI gate passes. Stops at the <strong>stories review gate</strong> (per-repo rule). When it passes the epic is <code>ready-for-build</code> — the build half can start, and <code>yad-test-cases</code> opens in parallel.</div>
+  </div>
+
+  <div class="skillcard" id="sk-test-cases">
+    <h4><code>yad-test-cases</code></h4>
+    <div class="row"><span class="lbl lbl-what">What</span> With the <strong>test architect</strong> AI (Murat), authors the risk-based test cases that cover the approved stories → <code>test-cases.md</code> (cases prioritised P0–P3, with story→case traceability). When a testing tool is connected (<code>yad-connect-testing</code>), it also <strong>implements the automation tests in that tool</strong> — generating them into the connected code repo(s) or linking an existing suite — and records the case→test map in <code>test-links.json</code>; otherwise it stays artifacts-only. Reads epic + architecture + contract + UI + stories as input.</div>
+    <div class="row"><span class="lbl lbl-how">How</span> In the product hub, after the stories gate passes:</div>
+<pre><code>run yad-test-cases — epic: EP-istifta-inquiries</code></pre>
+    <div class="row"><span class="lbl lbl-when">When</span> A <strong>parallel, non-blocking</strong> track: it opens the moment the stories gate passes — the epic is already <code>ready-for-build</code>, so this runs <strong>alongside the build half</strong>, not before it. Stops at its own <strong>test-cases review gate</strong> (base rule); that review never blocks building.</div>
   </div>
 
   <h3>The review gate &amp; its plumbing (cross-cutting)</h3>
@@ -897,7 +923,7 @@ yad-status EP-istifta-inquiries     # one epic in detail</code></pre>
 
   <div class="skillcard">
     <h4><code>npx yadflow setup</code></h4>
-    <div class="row"><span class="lbl lbl-what">What</span> The guided first-run wizard. Eight steps: preflight (git/node check), install all 18 skills into the IDE dirs you pick, detect the hub’s platform + record the reviewer roster, connect a design tool (Figma-first; optional), connect your code repos, wire each one (CI gates, PR template, comment scaffold), optionally write the AI-review config, and stamp the installed version.</div>
+    <div class="row"><span class="lbl lbl-what">What</span> The guided first-run wizard. Nine steps: preflight (git/node check), install all 20 skills into the IDE dirs you pick, detect the hub’s platform + record the reviewer roster, connect a design tool (Figma-first; optional), connect a testing tool (Playwright-first; optional), connect your code repos, wire each one (CI gates, PR template, comment scaffold), optionally write the AI-review config, and stamp the installed version.</div>
     <div class="row"><span class="lbl lbl-how">How</span></div>
 <pre><code>cd &lt;product-hub-repo&gt;
 npx yadflow setup</code></pre>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, repo). A BMAD module + 17 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",