yadflow 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -1,15 +1,9 @@
-# [2.1.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.0.1...v2.1.0) (2026-06-13)
-
-
-### Bug Fixes
-
-* address CodeRabbit review on the hardening PR ([7dbe9e3](https://github.com/abdelrahmannasr/yadflow/commit/7dbe9e358e731d69ecead6ecac9faa8377c37023))
-* drop useless backtick escapes in a single-quoted doctor hint (lint) ([c0cf1a2](https://github.com/abdelrahmannasr/yadflow/commit/c0cf1a26c15fccc91df15013d6bac83892f2af25))
+# [2.3.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.2.0...v2.3.0) (2026-06-13)
 
 
 ### Features
 
-* yad doctor + structured YAD-* error codes with recovery hints ([94f9e9f](https://github.com/abdelrahmannasr/yadflow/commit/94f9e9f6ff6d6d3c83ed29f1cfcc97e32678615c))
+* 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,16 +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 (7 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 17 `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 code repos** — register each repo into `.sdlc/repos.json` and cache a Repomix pack.
-5. **Wire each repo** — CI gates, PR/MR template, and review-comment scaffold.
-6. **AI review** — optionally write `.coderabbit.yaml`.
-7. **Done** — stamp `.sdlc/cli-version.json` and hand off the AI-only steps (code-maps; first epic).
+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 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
@@ -167,10 +173,12 @@ with a fix-it hint per finding. Failures carry stable, greppable codes, also pri
 | `YAD-STATE-002` | a ledger/config file parses but has the wrong shape | fix the file or restore from git (the message names the field) |
 | `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 17)
+## 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
@@ -183,12 +191,22 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
   `.sdlc/repos.json`, then caches an AI-readable picture of each — a compressed Repomix pack and a
   lightweight code-map (existing endpoints/events/data-models/modules), secret-scanned. Idempotent and
   refreshable; staleness tracked by HEAD sha.
+- **`yad-connect-design`** — Connects a design tool (Figma-first, pluggable) so the UI step can
+  materialize the actual feature design (mobile screens / web pages) inside it, alongside the Markdown.
+  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.
@@ -197,10 +215,19 @@ directly. Each skill stops at a gate and never auto-advances unless a step has *
   `.sdlc/contract-lock.json`. Reads `epic.md`; escalates on the contract risk tag.
 - **`yad-ui`** — Front state 5. With the ux-designer, author `ui-design.md` and `DESIGN.md`,
   driving Impeccable as harness slash-commands (document/extract/craft) when installed, or authoring
-  directly when not. Reads epic + architecture.
+  directly when not. When a design tool is connected (`yad-connect-design`), also **materializes the
+  feature design** — mobile screens / web pages — in the tool (generate or link), recording the
+  screen→frame map in `design-links.json`; degrades to markdown-only otherwise. Reads epic + architecture.
 - **`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)
 
@@ -259,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)
@@ -310,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
@@ -345,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).
@@ -407,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 } 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';
@@ -75,6 +75,46 @@ export function projectChecks(checks, root) {
     }
   }
 
+  // design.json: parse + shape + tool + MCP confirmation (absent is the normal markdown-only default —
+  // pre-feature projects have none, so silence rather than warn when the file does not exist).
+  const designPath = path.join(root, PROJECT_FILES.designConfig);
+  if (exists(designPath)) {
+    let design = null, designBroken = false;
+    try {
+      design = readJSONStrict(designPath, null);
+    } catch (e) {
+      designBroken = true;
+      check(checks, 'design', 'project', 'fail', `${PROJECT_FILES.designConfig} does not parse [${e.code || 'YAD-STATE-001'}]`, e.hint || 'fix the JSON or restore it from git');
+    }
+    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.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

@@ -20,6 +20,8 @@ export const CODES = {
   'YAD-STATE-002': 'a ledger/config JSON file parses but has the wrong shape',
   '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,14 +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 17 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',
@@ -79,10 +82,26 @@ export const IDE_OPENCODE_DIR = '.opencode/commands'; // <skill>.md (flat SKILL.
 // Module registration files copied from skills/sdlc/ into _bmad/sdlc/.
 export const MODULE_FILES = ['config.yaml', 'module-help.csv'];
 
+// Supported design-tool adapters (mirrors skills/sdlc/config.yaml `design.tools`); `DESIGN_PRIMARY` is
+// the fallback `registerDesign`/setup use when an unknown tool is named, and `none` is the explicit
+// markdown-only choice. (doctor does NOT fall back — an unknown tool there is a hard YAD-CFG-002 fail,
+// mirroring how registerRepo falls back on platform while doctor fails on an unknown hub platform.)
+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 } 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'];
@@ -58,6 +58,63 @@ export function registerRepo(root, registry, { name, rpath, platform, domain_own
   return repo;
 }
 
+// Record the project's design-tool connection into .sdlc/design.json (the deterministic half of the
+// connect loop; MCP detection itself is an AI step, handed off to `yad-connect-design`). An unknown tool
+// falls back to the primary adapter rather than being rejected — mirrors registerRepo's platform
+// fallback and the hub step. `none` is the explicit markdown-only choice.
+export function registerDesign(root, { tool, project_url = null, files = null, today = null } = {}) {
+  // Idempotent re-connect: carry the original first-connect date forward (the schema defines
+  // connectedAt as "first connect"); only lastSyncedAt moves. Mirrors repo.mjs refresh.
+  const designPath = path.join(root, PROJECT_FILES.designConfig);
+  const prev = readJSON(designPath, 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',
+      files: { web: null, mobile: null }, connectedAt, lastSyncedAt: today, source: 'unavailable' };
+    writeJSON(designPath, off);
+    return off;
+  }
+  if (!DESIGN_TOOLS.includes(t)) { warn(`unknown design tool '${tool}' — using ${DESIGN_PRIMARY}`); t = DESIGN_PRIMARY; }
+  // source stays null until `yad-connect-design` detects the MCP in the harness (AI step). doctor reports
+  // a recorded-but-unconfirmed connection as a warning pointing at that skill.
+  const design = {
+    tool: t, provider: null, project_url: project_url || null, auth: 'user',
+    files: files || { web: null, mobile: null },
+    connectedAt, lastSyncedAt: today, source: null,
+  };
+  writeJSON(designPath, design);
+  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) {
@@ -71,7 +128,7 @@ function applyActions(actions, { force = false } = {}) {
 }
 
 export async function runSetup(root, opts = {}) {
-  const total = 7;
+  const total = 9;
   log(c.bold(`\nSDLC Workflow setup  ${c.dim('v' + VERSION)}`));
   log(c.dim(`target: ${root}`));
 
@@ -131,8 +188,44 @@ export async function runSetup(root, opts = {}) {
     ok(`wrote ${PROJECT_FILES.hubConfig} (${roster.length} reviewer(s))`);
   }
 
-  // 4. Connect code repos
-  step(4, total, 'Connect code repos');
+  // 4. Connect a design tool (Figma-first, pluggable; the UI step materializes the design here)
+  step(4, total, 'Connect a design tool (Figma / pencil / none)');
+  const designPath = path.join(root, PROJECT_FILES.designConfig);
+  if (exists(designPath) && !(await askYesNo('design.json exists — reconfigure?', false))) {
+    info('keeping existing .sdlc/design.json');
+  } else {
+    let tool = (await ask(`Design tool (${DESIGN_TOOLS.join('/')}/none)`, DESIGN_PRIMARY)).toLowerCase();
+    if (![...DESIGN_TOOLS, 'none'].includes(tool)) {
+      warn(`unknown design tool '${tool}' — using ${DESIGN_PRIMARY}`);
+      tool = DESIGN_PRIMARY;
+    }
+    const project_url = tool === 'none' ? null : (await ask('  project/file URL (blank to set later)', '')) || null;
+    registerDesign(root, { tool, project_url, today: opts.today ?? null });
+    ok(tool === 'none'
+      ? `wrote ${PROJECT_FILES.designConfig} (markdown-only)`
+      : `wrote ${PROJECT_FILES.designConfig} (${tool})`);
+  }
+
+  // 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));
@@ -155,8 +248,8 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 5. Wire each connected repo + the hub itself
-  step(5, 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})`)}`);
@@ -171,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 });
 
-  // 6. Optional CodeRabbit
-  step(6, 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; }
@@ -182,13 +275,21 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 7. Summary + version stamp
-  step(7, 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('');
   log(c.bold('Next — AI-only steps (run in Claude Code):'));
   hand('generate code-maps: run `yad-connect-repos` for each connected repo');
+  const design = readJSON(designPath, null);
+  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).'));