yadflow 2.0.1 → 2.2.0

package/CHANGELOG.md

@@ -1,9 +1,16 @@
-## [2.0.1](https://github.com/abdelrahmannasr/yadflow/compare/v2.0.0...v2.0.1) (2026-06-12)
+# [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-13)
 
 
 ### Bug Fixes
 
-* publish README with pre-rendered SVG diagrams so they display on npm ([05382f6](https://github.com/abdelrahmannasr/yadflow/commit/05382f6bfe27bb0604165692ca6fe1cdb74b9a35))
+* address code review on the design-tool connection ([1275146](https://github.com/abdelrahmannasr/yadflow/commit/1275146e9e24251d481d90eb26894a729e894997))
+
+
+### 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))
 
 # [1.1.0](https://github.com/abdelrahmannasr/sdlc-workflow/compare/v1.0.3...v1.1.0) (2026-06-09)
 

package/README.md

@@ -3,6 +3,8 @@
 [![npm version](https://img.shields.io/npm/v/yadflow?logo=npm)](https://www.npmjs.com/package/yadflow)
 [![CI](https://github.com/abdelrahmannasr/yadflow/actions/workflows/ci.yml/badge.svg)](https://github.com/abdelrahmannasr/yadflow/actions/workflows/ci.yml)
 [![provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://docs.npmjs.com/generating-provenance-statements)
+[![node](https://img.shields.io/node/v/yadflow?logo=node.js)](https://github.com/abdelrahmannasr/yadflow/blob/main/package.json)
+[![security policy](https://img.shields.io/badge/security-policy-brightgreen)](https://github.com/abdelrahmannasr/yadflow/blob/main/SECURITY.md)
 [![report](https://img.shields.io/badge/docs-Yadflow%20report-2471a3)](https://abdelrahmannasr.github.io/yadflow/)
 
 > 📖 **Start here: the [Yadflow Terminology & Workflow Structure Report](https://abdelrahmannasr.github.io/yadflow/)** —
@@ -70,12 +72,18 @@ The module ships a zero-dependency CLI, published to npm as
 [`yadflow`](https://www.npmjs.com/package/yadflow). Run it
 with `npx` from your **product hub** repo — no clone needed.
 
+> **Platform support.** Linux and macOS are first-class — the test suite, the bash check gates, and
+> the end-to-end harness all run on both in CI. The CLI shells out to `git` (and the bash gate
+> scripts), so on **Windows use [WSL](https://learn.microsoft.com/windows/wsl/)**; native PowerShell
+> is not yet supported. Requires **Node.js ≥ 18**.
+
 | Command | What it does |
 |---------|--------------|
 | `npx yadflow setup` | Guided first-run wizard (the steps below). |
 | `npx yadflow check` | Read-only report: what is **missing** / **outdated** (drifted) / **stale** (code-context) / **legacy** (pre-2.0 `sdlc-*` names) vs the bundled manifest. |
 | `npx yadflow check --fix` | Reconcile: fill what is missing **and** update what changed — touches nothing already correct. |
 | `npx yadflow update` | Apply drift only (alias for `check --fix --scope=changed`). Also migrates a pre-2.0 install in place: `sdlc-*` skill copies and marker-owned `sdlc-*.yml` CI files are replaced by their `yad-*` names (a same-named file *you* authored is never touched). |
+| `npx yadflow doctor [--json]` | Environment + state health: tools on PATH and platform auth, config files parse and point at real repos, every epic ledger loads. Exit 1 on any failure; `--json` for CI and bug reports. |
 | `yad gate open <epic> <artifact>` | Open the front-half **review PR/MR** for an artifact and mark the step `in_review`. |
 | `yad gate sync <epic> [artifact]` | Pull the PR/MR's reviews + comment threads into the file ledger; **auto-advance** the step when approvals are satisfied, all threads are resolved, and the PR is merged. |
 | `yad gate comments <epic> [artifact]` | Fetch the unresolved review comments to address (then reply on the PR; reviewers resolve their threads). |
@@ -114,16 +122,18 @@ 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 (8 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 18 `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 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).
 
 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
@@ -143,7 +153,27 @@ provenance). See [`RELEASING.md`](RELEASING.md).
 > ships the `CHANGELOG.md` in the tarball, and cuts a GitHub release. No manual `npm publish`. See
 > [`RELEASING.md`](RELEASING.md).
 
-## Agent skills (all 17)
+### Troubleshooting (`yad doctor` + error codes)
+
+When something is off, run `yad doctor` first — it checks the environment (git, gh/glab auth, node
+version), the project state (`.sdlc/*.json` parse and point at real repos), and every epic ledger,
+with a fix-it hint per finding. Failures carry stable, greppable codes, also printed by any failing
+`yad` command:
+
+| Code | Meaning | Fix |
+|------|---------|-----|
+| `YAD-ENV-001` | git is not installed or not on PATH | install git — every yad command needs it |
+| `YAD-ENV-002` | platform CLI (gh/glab) missing or not authenticated | install it and authenticate — `gh auth login` (GitHub) or `glab auth login` (GitLab); the gate degrades to file-only without it |
+| `YAD-ENV-003` | Node.js older than the supported range | install Node >= 18 |
+| `YAD-STATE-001` | a ledger/config JSON file exists but does not parse | fix the file or restore from git — never delete a ledger blindly |
+| `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` |
+
+Filing a bug? Attach `yad doctor --json` — it contains no secrets (names, paths, and check results only).
+
+## Agent skills (all 18)
 
 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
@@ -156,6 +186,11 @@ 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.
 
 ### Front half — author the "thinking" (once per epic, human-gated)
 
@@ -170,7 +205,9 @@ 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.

package/bin/yad.mjs

@@ -9,6 +9,7 @@ import { isValidEpicId } from '../cli/epic-state.mjs';
 import { runCommit } from '../cli/commit.mjs';
 import { runOpenPr } from '../cli/openpr.mjs';
 import { runRepo } from '../cli/repo.mjs';
+import { runDoctor } from '../cli/doctor.mjs';
 
 const HELP = `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
 
@@ -18,6 +19,8 @@ ${c.bold('Setup & maintenance')}
   yad check --fix      Reconcile: fill what is missing, update what changed
   yad update           Apply drift only (alias for: check --fix --scope=changed);
                        also migrates pre-2.0 sdlc-* installs to the yad-* names
+  yad doctor [--json]  Environment + state health: tools/auth, config files,
+                       repo paths, epic ledgers (exit 1 on any failure)
 
 ${c.bold('Review gate (front half)')}
   yad gate open <epic> <artifact>      Open the review PR/MR; mark the step in_review
@@ -62,6 +65,7 @@ function parseArgs(argv) {
     else if (a === '--contract-change') o.contractChange = true;
     else if (a === '--no-push') o.noPush = true;
     else if (a === '--dry-run') o.dryRun = true;
+    else if (a === '--json') o.json = true;
     else if (a === '-h' || a === '--help') o.help = true;
     else if (a === '-v' || a === '--version') o.version = true;
     else if (a.startsWith('--scope=')) o.scope = a.slice('--scope='.length);
@@ -96,6 +100,9 @@ async function main() {
     case 'update':
       await reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, today });
       break;
+    case 'doctor':
+      await runDoctor(o.dir, { json: o.json });
+      break;
     case 'gate': {
       const [, action, epic, artifact] = o._;
       // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).
@@ -130,7 +137,10 @@ async function main() {
 
 main()
   .catch((err) => {
-    log(c.red(`\nyad failed: ${err?.message || err}`));
+    const code = err?.code && /^YAD-/.test(err.code) ? ` [${err.code}]` : '';
+    log(c.red(`\nyad failed${code}: ${err?.message || err}`));
+    if (err?.hint) log(c.yellow(`  → ${err.hint}`));
+    if (code) log(c.dim('  (see README "Troubleshooting" for this code, or run `yad doctor`)'));
     process.exitCode = 1;
   })
   .finally(closePrompts);

package/cli/doctor.mjs

@@ -0,0 +1,166 @@
+// `yad doctor` — environment + state health, the complement of `yad check` (file drift).
+// Three sections: environment (tools on PATH, auth), project state (config files parse and
+// point at real repos), epics (each ledger loads). Pure reporting: exit 1 on any FAIL,
+// 0 with warnings. `--json` emits the checks for CI / bug reports.
+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 { loadLedger, epicRoot } from './epic-state.mjs';
+import { gitHead } from './setup.mjs';
+import { cliFor } from './platform.mjs';
+
+const MIN_NODE = 18;
+
+// Each check: { id, section, status: 'ok'|'warn'|'fail', message, hint? }
+function check(checks, id, section, status, message, hint = '') {
+  checks.push({ id, section, status, message, ...(hint ? { hint } : {}) });
+}
+
+export function envChecks(checks) {
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major >= MIN_NODE) check(checks, 'node', 'environment', 'ok', `node ${process.versions.node}`);
+  else check(checks, 'node', 'environment', 'fail', `node ${process.versions.node} is below the supported range [YAD-ENV-003]`, `install Node.js >= ${MIN_NODE}`);
+
+  if (has('git')) check(checks, 'git', 'environment', 'ok', 'git present');
+  else check(checks, 'git', 'environment', 'fail', 'git not found on PATH [YAD-ENV-001]', 'install git — every yad command needs it');
+
+  for (const tool of ['npx', 'bash']) {
+    if (has(tool)) check(checks, tool, 'environment', 'ok', `${tool} present`);
+    else check(checks, tool, 'environment', 'warn', `${tool} not found on PATH`, tool === 'npx' ? 'repomix packing will be skipped' : 'the check gates are bash scripts');
+  }
+}
+
+export function projectChecks(checks, root) {
+  const hubPath = path.join(root, PROJECT_FILES.hubConfig);
+  const regPath = path.join(root, PROJECT_FILES.reposRegistry);
+  const verPath = path.join(root, PROJECT_FILES.version);
+  if (!exists(hubPath) && !exists(regPath) && !exists(verPath)) {
+    check(checks, 'project', 'project', 'warn', 'no yad project here (.sdlc/ not initialised)', 'run `yad setup` to start one — environment checks above still apply');
+    return null;
+  }
+
+  // version stamp
+  const ver = readJSON(verPath, null);
+  if (!ver) check(checks, 'cli-version', 'project', 'warn', `${PROJECT_FILES.version} missing or unreadable`, 'run `yad check --fix`');
+  else if (ver.version !== VERSION) check(checks, 'cli-version', 'project', 'warn', `project stamped v${ver.version}, CLI is v${VERSION}`, 'run `yad update` to reconcile');
+  else check(checks, 'cli-version', 'project', 'ok', `version stamp matches (v${VERSION})`);
+
+  // hub.json: parse + shape
+  let hub = null;
+  if (!exists(hubPath)) {
+    check(checks, 'hub', 'project', 'warn', `${PROJECT_FILES.hubConfig} absent — file-only gate`, 'run `yad setup` to configure a platform + roster');
+  } else {
+    let hubBroken = false;
+    try {
+      hub = readJSONStrict(hubPath, null);
+    } catch (e) {
+      hubBroken = true;
+      check(checks, 'hub', 'project', 'fail', `${PROJECT_FILES.hubConfig} does not parse [${e.code || 'YAD-STATE-001'}]`, e.hint || 'fix the JSON or restore it from git');
+    }
+    if (hubBroken) { /* reported above */ }
+    else if (typeof hub !== 'object' || Array.isArray(hub) || hub === null) check(checks, 'hub', 'project', 'fail', `${PROJECT_FILES.hubConfig} has the wrong shape [YAD-STATE-002]`, 'expected a JSON object');
+    else if (![null, undefined, 'github', 'gitlab'].includes(hub.platform)) check(checks, 'hub', 'project', 'fail', `${PROJECT_FILES.hubConfig}: unknown platform '${hub.platform}' [YAD-CFG-001]`, 'expected github, gitlab, or null');
+    // Mirror gate.mjs's roster shape check so doctor never reports "ok" on a hub the gate would reject.
+    else if (hub.roster !== undefined && !Array.isArray(hub.roster)) check(checks, 'hub', 'project', 'fail', `${PROJECT_FILES.hubConfig}: \`roster\` must be an array [YAD-STATE-002]`, 'fix the file or re-run `yad setup`');
+    else {
+      check(checks, 'hub', 'project', 'ok', `hub: ${hub.platform || 'file-only'}, ${(hub.roster || []).length} reviewer(s)`);
+      // platform CLI + auth (best-effort; auth probing is the user's own session)
+      const cli = cliFor(hub.platform);
+      if (cli) {
+        if (!has(cli)) check(checks, 'platform-cli', 'project', 'warn', `${cli} not found on PATH [YAD-ENV-002]`, `install ${cli} — the gate degrades to file-only without it`);
+        else if (!run(cli, ['auth', 'status']).ok) check(checks, 'platform-cli', 'project', 'warn', `${cli} present but not authenticated [YAD-ENV-002]`, `run \`${cli} auth login\``);
+        else check(checks, 'platform-cli', 'project', 'ok', `${cli} present and authenticated`);
+      }
+    }
+  }
+
+  // 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_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.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');
+  }
+
+  // repos.json: parse + every entry is a live git repo; staleness vs syncedHead
+  let registry = { repos: [] };
+  let regBroken = false;
+  try {
+    registry = readJSONStrict(regPath, { repos: [] });
+  } catch (e) {
+    regBroken = true;
+    check(checks, 'repos', 'project', 'fail', `${PROJECT_FILES.reposRegistry} does not parse [${e.code || 'YAD-STATE-001'}]`, e.hint || 'fix the JSON or restore it from git');
+  }
+  if (regBroken) { /* reported above */ }
+  else if (!Array.isArray(registry?.repos)) check(checks, 'repos', 'project', 'fail', `${PROJECT_FILES.reposRegistry} has the wrong shape [YAD-STATE-002]`, 'expected a `repos` array');
+  else {
+    for (const repo of registry.repos) {
+      // A missing/empty path must NOT fall back to the project root (which is itself a git repo and
+      // would read as "healthy") — an entry with no path is malformed.
+      if (!repo.path) { check(checks, `repo:${repo.name || '(unnamed)'}`, 'project', 'fail', `${repo.name || '(unnamed)'}: no \`path\` in repos.json [YAD-STATE-003]`, 're-connect the repo (`yad setup`)'); continue; }
+      const repoRoot = path.resolve(root, repo.path);
+      if (!exists(repoRoot)) { check(checks, `repo:${repo.name}`, 'project', 'fail', `${repo.name}: path ${repo.path} does not exist [YAD-STATE-003]`, 'fix the path in repos.json or re-connect the repo'); continue; }
+      const head = gitHead(repoRoot);
+      if (!head) { check(checks, `repo:${repo.name}`, 'project', 'fail', `${repo.name}: ${repo.path} is not a git repository (or has no commits) [YAD-STATE-003]`, 'init/clone the repo, then re-connect it'); continue; }
+      if (repo.syncedHead && head !== repo.syncedHead) check(checks, `repo:${repo.name}`, 'project', 'warn', `${repo.name}: code-context is stale (HEAD moved since last pack)`, 'run `yad repo refresh ' + repo.name + '`');
+      else check(checks, `repo:${repo.name}`, 'project', 'ok', `${repo.name}: git repo, context fresh`);
+    }
+    if (!registry.repos.length) check(checks, 'repos', 'project', 'warn', 'no code repos registered', 'run `yad setup` to connect one');
+  }
+  return { hub, registry };
+}
+
+export function epicChecks(checks, root) {
+  const epicsDir = path.join(root, 'epics');
+  if (!exists(epicsDir)) return;
+  for (const e of fs.readdirSync(epicsDir).sort()) {
+    if (!fs.statSync(path.join(epicsDir, e)).isDirectory()) continue;
+    try {
+      const ledger = loadLedger(epicRoot(root, e));
+      if (!ledger.state) check(checks, `epic:${e}`, 'epics', 'warn', `${e}: no state.json — epic not seeded`, 'author it via yad-epic, or remove the directory');
+      else check(checks, `epic:${e}`, 'epics', 'ok', `${e}: currentStep ${ledger.state.currentStep}`);
+    } catch (err) {
+      check(checks, `epic:${e}`, 'epics', 'fail', `${e}: ${err.message} [${err.code || 'YAD-STATE-001'}]`, err.hint || 'fix the file or restore it from git');
+    }
+  }
+}
+
+export async function runDoctor(root, { json = false } = {}) {
+  const checks = [];
+  envChecks(checks);
+  projectChecks(checks, root);
+  epicChecks(checks, root);
+
+  const failed = checks.filter((x) => x.status === 'fail');
+  const warned = checks.filter((x) => x.status === 'warn');
+  if (json) {
+    log(JSON.stringify({ version: VERSION, ok: failed.length === 0, checks }, null, 2));
+  } else {
+    log(c.bold(`\nyad doctor  ${c.dim('v' + VERSION)}`));
+    let section = '';
+    for (const x of checks) {
+      if (x.section !== section) { section = x.section; log(`\n  ${c.bold(section)}`); }
+      ({ ok, warn, fail })[x.status](x.message);
+      if (x.hint && x.status !== 'ok') hand(x.hint);
+    }
+    log('');
+    if (failed.length) fail(`${failed.length} problem(s) found`);
+    else if (warned.length) info(`healthy with ${warned.length} warning(s)`);
+    else ok('all clear');
+  }
+  if (failed.length) process.exitCode = 1;
+  return { ok: failed.length === 0, failed: failed.length, warned: warned.length, checks };
+}

package/cli/epic-state.mjs

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import { readJSONStrict, writeJSON, fileSha } from './lib.mjs';
+import { err } from './errors.mjs';
 import { epicFiles } from './manifest.mjs';
 
 const RISK_ESCALATORS = ['contract', 'auth', 'payments'];
@@ -98,7 +99,7 @@ export function artifactHash(epicDir, artifact) {
 
 // Shape checks for the ledger files. Fail fast with the exact file named — a wrong-shape ledger
 // silently treated as a default would be rewritten by the next sync, destroying the real data.
-const badShape = (file, what) => new Error(`${file}: ${what} — fix the file or restore it from git`);
+const badShape = (file, what) => err('YAD-STATE-002', `${file}: ${what}`, 'fix the file or restore it from git');
 function requireArray(v, file) {
   if (!Array.isArray(v)) throw badShape(file, 'expected a JSON array');
   return v;

package/cli/errors.mjs

@@ -0,0 +1,26 @@
+// Structured error codes for the `yad` CLI. A YadError carries a stable code (greppable,
+// documented in README "Troubleshooting") and a one-line recovery hint that the top-level
+// catch in bin/yad.mjs prints after the message. Plain Errors still work everywhere; codes
+// are reserved for the failures users actually hit and need to act on.
+export class YadError extends Error {
+  constructor(code, message, hint = '') {
+    super(message);
+    this.name = 'YadError';
+    this.code = code;
+    this.hint = hint;
+  }
+}
+
+// The catalog — single source for doctor, the top-level catch, and the README table.
+export const CODES = {
+  'YAD-ENV-001': 'git is not installed or not on PATH',
+  'YAD-ENV-002': 'the platform CLI (gh/glab) is missing or not authenticated',
+  'YAD-ENV-003': 'Node.js is older than the supported range (>=18)',
+  'YAD-STATE-001': 'a ledger/config JSON file exists but does not parse',
+  '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)',
+};
+
+export const err = (code, message, hint) => new YadError(code, message, hint);

package/cli/gate.mjs

@@ -14,6 +14,7 @@ import {
   artifactPaths, upsertHubPr,
 } from './epic-state.mjs';
 import { readPr, mapApprovers, createPr } from './platform.mjs';
+import { err } from './errors.mjs';
 
 // ---- tiny frontmatter reader (key: value, and `repos: [a, b]`) ----------------------------------
 function frontmatter(file) {
@@ -64,18 +65,23 @@ function warnUnlockedContract(epicDir, artifact) {
 function loadHub(root) {
   const hubFile = path.join(root, PROJECT_FILES.hubConfig);
   const regFile = path.join(root, PROJECT_FILES.reposRegistry);
+  // Distinguish an ABSENT hub.json (null default → fine, file-only gate) from one that exists but
+  // holds literal `null` (malformed — must not silently downgrade to file-only).
   const hub = readJSONStrict(hubFile, null);
+  if (hub === null && fs.existsSync(hubFile)) {
+    throw err('YAD-STATE-002', `${hubFile}: contains \`null\` — expected a config object`, 'fix the file or re-run `yad setup`');
+  }
   if (hub !== null) {
-    if (typeof hub !== 'object' || Array.isArray(hub)) throw new Error(`${hubFile}: expected a JSON object`);
+    if (typeof hub !== 'object' || Array.isArray(hub)) throw err('YAD-STATE-002', `${hubFile}: expected a JSON object`, 'fix the file or re-run `yad setup`');
     if (![null, undefined, 'github', 'gitlab'].includes(hub.platform)) {
-      throw new Error(`${hubFile}: unknown platform '${hub.platform}' — expected github, gitlab, or null`);
+      throw err('YAD-CFG-001', `${hubFile}: unknown platform '${hub.platform}'`, 'expected github, gitlab, or null — fix the file or re-run `yad setup`');
     }
     if (hub.roster !== undefined && !Array.isArray(hub.roster)) {
-      throw new Error(`${hubFile}: expected \`roster\` to be an array`);
+      throw err('YAD-STATE-002', `${hubFile}: expected \`roster\` to be an array`, 'fix the file or re-run `yad setup`');
     }
   }
   const registry = readJSONStrict(regFile, { repos: [] });
-  if (!Array.isArray(registry?.repos)) throw new Error(`${regFile}: expected a \`repos\` array`);
+  if (!Array.isArray(registry?.repos)) throw err('YAD-STATE-002', `${regFile}: expected a \`repos\` array`, 'fix the file or re-run `yad setup`');
   return { hub, repos: registry.repos };
 }
 
@@ -131,7 +137,7 @@ function writeComments(epicDir, base, today, blocking) {
 // Upsert machine-readable participation records into the comments ledger (the counterpart to the
 // markdown side file) so the ledger — not just reviews/*.md — reflects platform thread state. One
 // record per (step, commenter, round); `round` is the count of prior synced rounds for the step.
-function recordComments(comments, { artifact, stepId, today, roster, repos, blocking }) {
+function recordComments(comments, { artifact, stepId, today, roster, blocking }) {
   if (!blocking.length) return comments;
   const byName = (login) => (roster.find((r) => r.login === login)?.name) || login || 'reviewer';
   const roleOf = (login) => (roster.find((r) => r.login === login)?.role) || 'reviewer';
@@ -386,8 +392,8 @@ export async function gateStatus(root, { epic } = {}) {
   }
 }
 
-export async function gateOpen(root, { epic, artifact, today } = {}) {
-  const { hub, repos } = loadHub(root);
+export async function gateOpen(root, { epic, artifact } = {}) {
+  const { hub } = loadHub(root);
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
   if (!ledger.state) { fail(`no epic state at ${epicDir}`); process.exitCode = 1; return; }

package/cli/lib.mjs

@@ -1,5 +1,6 @@
 // Shared helpers for the `yad` CLI. Node >=18 built-ins only — no dependencies.
 import { createHash } from 'node:crypto';
+import { err } from './errors.mjs';
 import { spawnSync } from 'node:child_process';
 import * as readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
@@ -108,7 +109,7 @@ export function readJSONStrict(p, def = null) {
   try {
     return JSON.parse(fs.readFileSync(p, 'utf8'));
   } catch (e) {
-    throw new Error(`corrupt JSON in ${p}: ${e.message} — fix or delete the file`);
+    throw err('YAD-STATE-001', `corrupt JSON in ${p}: ${e.message}`, 'fix the file or restore it from git — never delete a ledger blindly');
   }
 }
 // Atomic: serialize first, write a sibling tmp file (same dir = same filesystem),

package/cli/manifest.mjs

@@ -10,7 +10,7 @@ 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 18 hand-authored yad-* skills (mirrors skills/sdlc/install.sh).
 export const SKILLS = [
   'yad-analysis',
   'yad-epic',
@@ -18,6 +18,7 @@ export const SKILLS = [
   'yad-ui',
   'yad-stories',
   'yad-connect-repos',
+  'yad-connect-design',
   'yad-spec',
   'yad-implement',
   'yad-checks',
@@ -79,10 +80,18 @@ 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';
+
 // 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',
   version: '.sdlc/cli-version.json',
 };
 

package/cli/reconcile.mjs

@@ -3,7 +3,7 @@
 // manifest: missing setup, drifted files, stale code-context.
 import path from 'node:path';
 import {
-  c, log, ok, info, warn, hand, fail, readJSON, writeJSON, exists,
+  c, log, ok, info, warn, hand, readJSON, writeJSON, exists,
 } from './lib.mjs';
 import { VERSION, PROJECT_FILES } from './manifest.mjs';
 import {

package/cli/setup.mjs

@@ -3,9 +3,9 @@ import path from 'node:path';
 import fs from 'node:fs';
 import {
   c, log, step, ok, info, warn, hand, fail, ask, askYesNo, run, has,
-  exists, asset, copyFile, readJSON, writeJSON,
+  exists, readJSON, writeJSON,
 } from './lib.mjs';
-import { VERSION, IDE_FOLDER_TARGETS, IDE_OPENCODE_DIR, PROJECT_FILES } from './manifest.mjs';
+import { VERSION, IDE_FOLDER_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY } from './manifest.mjs';
 import { moduleActions, repoActions, hubActions, authorsActions } from './plan.mjs';
 
 const ALL_IDES = [...IDE_FOLDER_TARGETS, '.opencode'];
@@ -58,6 +58,35 @@ 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;
+}
+
 function applyActions(actions, { force = false } = {}) {
   let changed = 0;
   for (const a of actions) {
@@ -71,7 +100,7 @@ function applyActions(actions, { force = false } = {}) {
 }
 
 export async function runSetup(root, opts = {}) {
-  const total = 7;
+  const total = 8;
   log(c.bold(`\nSDLC Workflow setup  ${c.dim('v' + VERSION)}`));
   log(c.dim(`target: ${root}`));
 
@@ -131,8 +160,26 @@ 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 code repos
+  step(5, 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 +202,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)');
+  // 6. Wire each connected repo + the hub itself
+  step(6, 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 +218,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)');
+  // 7. Optional CodeRabbit
+  step(7, 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 +229,17 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 7. Summary + version stamp
-  step(7, total, 'Done');
+  // 8. Summary + version stamp
+  step(8, 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)`);
+  }
   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,12 +284,14 @@
     <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 17 skills into your IDE dirs</small></div>
+        <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="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>
         <div class="node plain"><strong>Connect code repos</strong><small><code>yad-connect-repos</code> → <code>repos.json</code> + a cached code-map per repo <em>(skip if greenfield)</em></small></div>
         <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>Optional: hub on a platform</strong><small>detect GitHub/GitLab + reviewer roster, so reviews run on real PRs/MRs</small></div>
       </div>
     </div>
@@ -311,7 +313,7 @@
         <div class="arrow-v">▼</div>
         <div class="node gate">gate · architecture review<small><strong>escalated:</strong> base rule + a domain owner for every repo in the epic</small></div>
         <div class="arrow-v">▼</div>
-        <div class="node artifact"><strong>yad-ui</strong><small><code>ui-design.md</code> + <code>DESIGN.md</code></small></div>
+        <div class="node artifact"><strong>yad-ui</strong><small><code>ui-design.md</code> + <code>DESIGN.md</code> + the screens in the connected design tool (<code>design-links.json</code>)</small></div>
         <div class="arrow-v">▼</div>
         <div class="node gate">gate · UI review<small>base rule</small></div>
         <div class="arrow-v">▼</div>
@@ -367,11 +369,11 @@
     epic.md              the feature, agreed
     architecture.md      how it will be built
     contract.md          the LOCKED shared surface (APIs, events, data model)
-    ui-design.md         + DESIGN.md
+    ui-design.md         + DESIGN.md (+ the screens in the connected design tool)
     stories/             one file per story (EP-&lt;slug&gt;-S01.md …)
     reviews/             reviewer comments, per artifact
     .sdlc/               state.json · approvals.json · contract-lock.json
-                         build-state/ · trust-log.json · build-log.json
+                         design-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)
@@ -438,7 +440,7 @@ 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 17 skills live and where you pull updates from. No real product work happens inside it.</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>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>
@@ -529,7 +531,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 17 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 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>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>
@@ -672,7 +674,7 @@ each code repo/
 
 <!-- ======================================================= -->
 <section id="skills">
-  <h2>6. The 17 skills — what each does, how to use it, and when</h2>
+  <h2>6. The 18 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>, …).
@@ -682,10 +684,11 @@ each code repo/
   <table>
     <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-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>.</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-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>
@@ -715,6 +718,17 @@ yad-connect-repos action: roster login: alice-gh name: alice role: owner   # onc
     <div class="row"><span class="lbl lbl-when">When</span> During one-time setup, and again any time you add a new code repo. Re-run <code>refresh</code> when a skill warns a repo is stale. <strong>Greenfield with no code yet? Skip it entirely</strong> — the brain proceeds without it.</div>
   </div>
 
+  <div class="skillcard" id="sk-connect-design">
+    <h4><code>yad-connect-design</code></h4>
+    <div class="row"><span class="lbl lbl-what">What</span> Connects a <strong>design tool</strong> to the product hub so the UI step can materialize the <em>actual</em> feature design — mobile screens / web pages — inside it, alongside the Markdown. <strong>Figma-first but pluggable</strong> (a design-tool adapter; <code>pencil</code> is a second provider). It records the tool + project/file references in <code>design.json</code> through your own authenticated MCP session — <strong>no tokens are ever stored</strong> — and degrades to markdown-only when no design-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-design action: connect tool: figma project_url: https://figma.com/files/project/…
+yad-connect-design action: list                  # show the connection + whether the MCP is available
+yad-connect-design action: refresh               # re-detect the MCP (after authenticating a session)
+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>
+
   <h3>Front half — author the thinking (in the product hub)</h3>
 
   <div class="skillcard" id="sk-analysis">
@@ -743,7 +757,7 @@ yad-connect-repos action: roster login: alice-gh name: alice role: owner   # onc
 
   <div class="skillcard" id="sk-ui">
     <h4><code>yad-ui</code></h4>
-    <div class="row"><span class="lbl lbl-what">What</span> With the ux-designer AI, authors the UI design for the epic: <code>ui-design.md</code> (this feature’s screens and flows) + <code>DESIGN.md</code> (the reusable design language). Drives Impeccable’s <code>document / extract / craft</code> commands when installed; writes the files directly when not (and records that).</div>
+    <div class="row"><span class="lbl lbl-what">What</span> With the ux-designer AI, authors the UI design for the epic: <code>ui-design.md</code> (this feature’s screens and flows) + <code>DESIGN.md</code> (the reusable design language). Drives Impeccable’s <code>document / extract / craft</code> commands when installed; writes the files directly when not (and records that). When a design tool is connected (<code>yad-connect-design</code>), it also <strong>materializes the screens in that tool</strong> — generating them from the spec or linking an existing design — and records the screen→frame map in <code>design-links.json</code>; otherwise it stays markdown-only.</div>
     <div class="row"><span class="lbl lbl-how">How</span> In the product hub, after the architecture gate passes:</div>
 <pre><code>run yad-ui — epic: EP-istifta-inquiries</code></pre>
     <div class="row"><span class="lbl lbl-when">When</span> After architecture, before stories. Skip-able only if the epic genuinely has no UI. Stops at the <strong>UI review gate</strong> (base rule).</div>
@@ -883,7 +897,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. Seven steps: preflight (git/node check), install all 17 skills into the IDE dirs you pick, detect the hub’s platform + record the reviewer roster, 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. 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-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.0.1",
+  "version": "2.2.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",
@@ -20,6 +20,7 @@
     "bin/",
     "cli/",
     "!cli/test.mjs",
+    "!cli/test-checks.mjs",
     "skills/",
     "docs/index.html",
     "README.md",
@@ -35,7 +36,10 @@
   },
   "scripts": {
     "yad": "node bin/yad.mjs",
-    "test": "node --test cli/test.mjs",
+    "lint": "eslint cli bin",
+    "test": "node --test cli/test.mjs cli/test-checks.mjs",
+    "test:e2e": "bash test/e2e/run.sh",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-exclude='cli/test*.mjs' --test-coverage-lines=70 --test-coverage-branches=70 cli/test.mjs cli/test-checks.mjs",
     "diagrams": "npx -y @mermaid-js/mermaid-cli -i docs/diagrams/sdlc-overview.mmd -o docs/diagrams/sdlc-overview.svg -b transparent && npx -y @mermaid-js/mermaid-cli -i docs/diagrams/review-loop.mmd -o docs/diagrams/review-loop.svg -b transparent",
     "prepublishOnly": "npm test"
   },
@@ -49,7 +53,9 @@
     "spec-driven-development"
   ],
   "devDependencies": {
+    "@eslint/js": "^9.39.4",
     "@semantic-release/changelog": "^6.0.3",
+    "eslint": "^9.39.4",
     "semantic-release": "^25.0.3"
   }
 }

package/skills/sdlc/config.yaml

@@ -118,6 +118,22 @@ code_context:
   # works for both github and gitlab (and self-hosted), and stores NO tokens in the registry.
   platforms: [github, gitlab]
 
+# Design tool (yad-connect-design) — the UI design step (yad-ui) materializes the actual feature design
+# (mobile screens / web pages) inside a connected design tool, alongside ui-design.md + DESIGN.md. The
+# tool is reached through its MCP (a harness MCP server, like Impeccable's slash-commands — NOT a CLI),
+# detected per provider and DEGRADING to markdown-only when absent. Figma-first but PLUGGABLE: a
+# design-tool adapter, like the github/gitlab platform adapter. Connection is one-per-project, recorded
+# at setup; the per-epic screen->frame map (design-links.json) is written by yad-ui per epic.
+design:
+  registry: "{project-root}/.sdlc/design.json"       # project-wide design connection (NOT per-epic)
+  tools: [figma, pencil]                              # supported adapters; an unknown tool falls back to `primary`
+  primary: figma                                      # the default/named provider
+  degrade: markdown-only                              # no tool / no MCP => yad-ui authors ui-design.md + DESIGN.md only
+  links: "{project-root}/epics/EP-<slug>/.sdlc/design-links.json"   # per-epic screen->frame map (yad-ui)
+  # Auth: `yad-connect-design` connects through the LOCAL user's own authenticated MCP session and stores
+  # NO tokens in the registry (project_url/files 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

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-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-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)
 
 echo "Installing sdlc module from $ROOT/skills ..."
 

package/skills/sdlc/module-help.csv

@@ -5,6 +5,7 @@ SDLC Workflow,yad-architecture,Author Architecture,AA,"Front state 3: with the a
 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-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-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-connect-design/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: yad-connect-design
+description: 'Connects a design tool (Figma, or another tool — pluggable) to the product hub so the UI design step can materialize the full feature design (mobile screens / web pages) inside it, not just Markdown. Registers the tool into the project-wide .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 it is not. Run at setup or any time the design tool changes. Reusable, idempotent, refreshable. Use when the user says "connect Figma", "connect a design tool", "refresh the design connection", or "list the design connection".'
+---
+
+# SDLC — Connect a Design Tool (make the UI step design-tool aware)
+
+**Goal:** Let the UI design step (`yad-ui`) produce the **actual feature design** — the mobile screens
+and/or web pages — inside a design tool such as **Figma**, alongside the Markdown artifacts
+(`ui-design.md` / `DESIGN.md`). This skill **connects** a design tool to the product hub and records
+*how* to reach it (the tool, the project/file references, which MCP renders 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 design registry. `yad-ui` consumes it: when a tool is
+connected and its MCP is available, the `ux-designer` lens **generates** screens into the tool (or
+**links** an existing human-made design and reads it back); when nothing is connected, `yad-ui` runs
+markdown-only exactly as before.
+
+## Conventions
+
+- `{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`
+  (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
+  it is absent; it never installs an MCP server.
+- Registry: `{project-root}/.sdlc/design.json` (project-wide, shared across all epics — NOT per-epic),
+  the sibling of `.sdlc/repos.json` and `.sdlc/hub.json`.
+- Per-epic screen→frame links are written later by `yad-ui` (`epics/EP-<slug>/.sdlc/design-links.json`),
+  not here.
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## Inputs
+
+- `action` — `connect` (default) | `refresh` | `list` | `disconnect`.
+- `tool` — `figma` | `pencil` | another adapter id (`config.yaml` `design.tools`). `none` records a
+  deliberate markdown-only project.
+- `project_url` — the design tool's team/project/file reference (e.g. a Figma project or file URL).
+  Optional — a connection with no file yet is valid; `yad-ui` can create one on first generate.
+- `files` — optional default file mapping per platform (`{ web: <ref>, mobile: <ref> }`).
+
+## On Activation
+
+### Step 1 — Resolve the tool and its MCP (the design-tool adapter)
+Determine which tool is being connected from `tool` (default `figma`); reject a `tool` not in
+`config.yaml` `design.tools` (fall back to the configured `design.primary` with a warning, the same way
+`registerRepo` falls back on an unknown platform). Then **detect the tool's MCP** in this harness:
+
+- **figma** → a Figma MCP server (Dev Mode MCP for read/link; html.to.design for HTML→Figma *generate*).
+- **pencil** → the `pencil` MCP (`batch_design` writes `.pen` web/mobile screens — generate-capable).
+- another adapter → its named MCP.
+
+Record `provider` (the concrete MCP, e.g. `figma-mcp` | `html-to-design` | `pencil-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`/`files` are plain references, never credentials.
+
+**Graceful degradation:** if no design-tool MCP is available, record `source: "unavailable"` and report
+that `yad-ui` will run **markdown-only** until an MCP is connected (no error — the design tool is purely
+additive, exactly like Impeccable 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/design.json` (create the file + parent `.sdlc/` if absent):
+
+```json
+{
+  "tool": "figma",
+  "provider": "figma-mcp",
+  "project_url": "https://www.figma.com/files/project/<id>/<name>",
+  "auth": "user",
+  "files": { "web": null, "mobile": null },
+  "connectedAt": "<YYYY-MM-DD>",
+  "lastSyncedAt": "<YYYY-MM-DD>",
+  "source": "figma-mcp"
+}
+```
+
+- `tool: "none"` records a deliberate markdown-only project: `{ "tool": "none", "provider": null,
+  "source": "unavailable", ... }`.
+- `connect` is **idempotent** — re-running it overwrites the single connection in place (a project has
+  one design 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-ui` will degrade
+to markdown-only), the `project_url`, and that **`yad-ui` will now generate/link the design 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 file mapping, and a
+  **available/unavailable** flag for the MCP (best-effort, the user's own session). No design tool
+  connected ⇒ "markdown-only".
+- **`disconnect`** — remove the registry file (or set `tool: "none"`). The design tool's own
+  project/files 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 Figma PAT or any credential in the registry. `project_url`/`files` are plain
+  references.
+- **Degrade gracefully.** No design tool / no MCP → `yad-ui` runs markdown-only with no error. The design
+  tool is additive, never a blocker — the same discipline as Impeccable and the `gh`/`glab` bridge.
+- **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 design
+  connection at a time.
+- **Describe the connection; do not design here.** This skill records *how to reach* the tool. The actual
+  screens are generated/linked by `yad-ui`, per epic.
+
+## Reference
+- Registry schema + freshness rule: `references/design-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/design-context.md`.
+- The connect pattern this mirrors (code repos): `../yad-connect-repos/SKILL.md`.
+- The consumer — how `yad-ui` generates/links and writes `design-links.json`: `../yad-ui/SKILL.md`.

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

@@ -0,0 +1,64 @@
+# Design context — MCP detection, generate vs link, and the degrade path
+
+How a connected design tool turns into the actual feature design the UI step materializes. The design
+tool is reached through its **MCP** (a harness MCP server), the same shape as Impeccable's
+slash-commands — detect it, use it when present, degrade cleanly when absent. This is the design-side
+analogue of `yad-connect-repos`'s code-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 |
+|--------|----------------|------------|
+| `figma` | a Figma Dev Mode MCP | **read/link** — reference a file, read frames back into `ui-design.md` |
+| `figma` | html.to.design MCP (`import-html`) | **generate** — render HTML/CSS screens into a Figma file |
+| `pencil` | the `pencil` MCP (`batch_design`) | **generate** — author `.pen` web/mobile screens directly |
+| other | the adapter's named MCP | per that adapter |
+
+**Honest capability note:** not every design-tool MCP can *write*. A read-only Figma Dev Mode MCP
+supports **link + read-back** only; *generate* needs a write-capable provider (html.to.design for Figma,
+or `pencil`). `yad-ui` picks the direction the connected provider actually supports and records which one
+it used (`direction: generated | linked`). It never claims to have generated screens a read-only MCP
+cannot produce.
+
+## Generate (push screens into the tool)
+
+When the connected provider is write-capable, the `ux-designer` lens produces the epic's screens in the
+tool, covering the screens/states `ui-design.md` enumerates and the user flows the architecture defines:
+
+- **Figma via html.to.design** — the lens drafts each screen as HTML/CSS (reusing `DESIGN.md` tokens),
+  then imports it into the Figma file via the MCP's `import-html`, one frame per screen.
+- **pencil** — the lens calls `batch_design` to author the screens as `.pen` frames directly (mobile
+  and/or web per the epic).
+
+Reuse what already exists: load the connected code repos' code-maps (`yad-ui` Step 2b) and any
+Impeccable `DESIGN.md` tokens so generated screens match built components, not invented ones.
+
+## Link (reference a human-made design)
+
+When a designer has already built the screens (or the provider is read-only), point `yad-ui` at the
+existing file and **read the frames back** so `ui-design.md` reflects the real design: list each frame as
+a screen, capture its node id + URL, and map components/tokens into `DESIGN.md`.
+
+## Write back the linkage (done by `yad-ui`, per epic)
+
+Either direction ends by writing `epics/EP-<slug>/.sdlc/design-links.json` — the machine-readable
+screen→frame map — and a `## Design (<tool>)` section in `ui-design.md` linking each screen to its frame
+URL. The design itself lives in the tool; the hub keeps the *links* and the Markdown spec beside the
+other epic artifacts.
+
+## Degrade path (no MCP / no tool)
+
+If `design.json` is absent, `tool: "none"`, or `source: "unavailable"`, `yad-ui` runs **markdown-only**:
+it authors `ui-design.md` / `DESIGN.md` exactly as before and records `design: none` in the frontmatter
+with a one-line note (mirroring the `impeccable: not-installed` degrade). No error — the design tool is
+purely additive.
+
+## Staleness / refresh
+
+A re-generated or designer-edited file is like a moved code repo: `yad-ui` **flags** a divergence and
+lets a human decide (re-run the step, or `yad-connect-design` action: refresh). It never silently
+overwrites a designer's frames — refreshing the design is a human decision, the same discipline as
+`code_context.refresh: human`.

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

@@ -0,0 +1,54 @@
+# Design registry — schema + freshness rule
+
+The registry is the product hub's record of which design tool is connected and how to reach it. It is
+**project-wide** (one design 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/design.json`
+
+(`config.yaml` `design.registry`.) Create the file and its parent `.sdlc/` on the first `connect`.
+
+## Schema
+
+```json
+{
+  "tool": "figma",                                   // figma | pencil | <adapter id> | none (markdown-only)
+  "provider": "figma-mcp",                           // the concrete MCP: figma-mcp | html-to-design | pencil-mcp | null
+  "project_url": "https://www.figma.com/files/project/123/feature", // team/project/file reference; null if none yet
+  "auth": "user",                                    // ALWAYS the user's own MCP session — never a token
+  "files": { "web": null, "mobile": null },          // optional default file refs per platform
+  "connectedAt": "2026-06-13",                       // first connect (YYYY-MM-DD)
+  "lastSyncedAt": "2026-06-13",                      // last connect/refresh
+  "source": "figma-mcp"                              // the MCP detected at connect | unavailable (degraded)
+}
+```
+
+## 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.
+- **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.
+- **`connect` overwrites in place** — a project carries exactly one design 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 (`figma-mcp` / `pencil-mcp` / …) means
+  `yad-ui` can generate/link; `unavailable` means `yad-ui` degrades to markdown-only. `refresh`
+  re-detects and may flip it.
+- **`tool: "none"`** is a valid, deliberate state: a project that has chosen markdown-only. `yad-ui`
+  treats it exactly like an absent registry.
+- **`disconnect`** removes the file (or sets `tool: "none"`). The design tool's own project/files are
+  never touched.
+
+## Git tracking
+
+Commit the **registry** (`design.json`) — it is small, reviewable, and holds no secrets (references
+only). This mirrors how `repos.json` and `hub.json` are committed.
+
+## Greenfield
+
+A brand-new product hub has no `design.json`. That is valid — `yad-ui` treats "no design tool connected"
+the same as `tool: "none"` and produces the Markdown artifacts only. The registry appears the first time
+`connect` runs.

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

@@ -86,6 +86,19 @@ PR/MR opened on the hub (sibling of `approvals.json`, so the locked `state.json`
 { "step": "<review step id>", "artifact": "<artifact>", "platform": "github|gitlab", "number": <n>, "url": "<pr/mr url>", "branch": "review/EP-<slug>/<artifact-base>", "lastSyncedAt": "<YYYY-MM-DD or null>" }
 ```
 
+## `design-links.json`
+Present only when the `ui-design` step materialized the design in a connected design tool
+(`yad-connect-design` → `.sdlc/design.json`). Written by `yad-ui`, the machine-readable screen→frame map
+(sibling of `contract-lock.json`; the locked `state.json` step shape is untouched). The `ui-design` step
+chain is unchanged — this is an *output enrichment*, mirrored by the `design:` frontmatter block and the
+`## Design (<tool>)` section in `ui-design.md`. Absent when the step ran markdown-only (`design: none`).
+
+```json
+{ "tool": "figma", "fileUrl": "<url>", "generatedAt": "<YYYY-MM-DD>", "direction": "generated|linked",
+  "screens": [ { "name": "<screen>", "platform": "mobile|web", "nodeId": "<id>", "url": "<frame 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`

package/skills/yad-ui/SKILL.md

@@ -6,18 +6,28 @@ description: 'Front state 5 of the gated SDLC. With the ux-designer, author ui-d
 # SDLC — Author UI Design (front state 5)
 
 **Goal:** Produce a human-authored, AI-assisted `ui-design.md` and `DESIGN.md` for an approved
-architecture. This is a **front state**: human-authored with AI assist, **never auto-advances**. When
-the UI is drafted, control passes to `yad-review-gate` (base rule: owner + 1 reviewer).
+architecture **and**, when a design tool is connected, the **actual feature design** — the mobile
+screens and/or web pages — inside that tool (e.g. Figma), linked back from the artifacts. This is a
+**front state**: human-authored with AI assist, **never auto-advances**. When the UI is drafted, control
+passes to `yad-review-gate` (base rule: owner + 1 reviewer).
 
 UI work is shaped by **Impeccable**, invoked as **harness slash-commands** (not a subprocess CLI) per
 the Phase 0 deviation. If Impeccable is not installed, the `ux-designer` lens authors the same outputs
 directly — the workflow does not block on the tool.
 
+The visual design is materialized in the **design tool connected via `yad-connect-design`**
+(`.sdlc/design.json`), reached through its MCP. When a tool is connected the `ux-designer` lens
+**generates** screens into it (or **links** an existing human-made design and reads it back); when none
+is connected, the step degrades to the Markdown artifacts only — the design tool is additive, exactly
+like Impeccable.
+
 ## Conventions
 
 - `{project-root}` resolves from the project working directory.
 - Artifacts live under `{project-root}/epics/EP-<slug>/` (build plan §6).
 - `DESIGN.md` is Impeccable's conventional root design-system file (RESEARCH-NOTES §4).
+- The connected design tool is recorded in `{project-root}/.sdlc/design.json` (`config.yaml` `design`),
+  written by `yad-connect-design`. The per-epic screen→frame map is `design-links.json` (Step 4b).
 - Speak in the configured `communication_language`; write documents in `document_output_language`.
 
 ## On Activation
@@ -66,6 +76,25 @@ components/tokens into the design system; `/impeccable craft` is shape-then-buil
 that Impeccable was not used**. Do not run `npx impeccable skills install` as part of this step — tool
 installation is out of scope for the front half.
 
+### Step 3b — Materialize the design in the connected tool (generate or link)
+Read `{project-root}/.sdlc/design.json` (`config.yaml` `design.registry`). Decide the path:
+
+- **No tool / `tool: "none"` / `source: "unavailable"`** (or the file is absent): **degrade** —
+  author the Markdown artifacts only and record `design: none` in the frontmatter with a one-line note
+  (mirrors the `impeccable: not-installed` degrade). Skip to Step 4.
+- **A tool is connected and its MCP is available:** adopt the `ux-designer` lens and, using the provider
+  recorded in `design.json` (Figma via a Figma/html.to.design MCP, `pencil` via its MCP, etc.):
+  - **Generate** — when the provider is write-capable, produce one frame per screen the design covers,
+    for the platforms in `epic.repos` (mobile and/or web), reusing the code-maps (Step 2b) and
+    `DESIGN.md` tokens so screens match built components rather than inventing parallel ones.
+  - **Link** — when the user points at an existing design file (or the provider is read-only), reference
+    it and **read the frames back** so `ui-design.md` reflects the real design.
+
+  Capture each screen's `name`, `platform`, `nodeId`, and `url`. Record which direction was used
+  (`generated | linked`). Honest-capability rule: a read-only MCP supports **link** only — never claim a
+  screen was generated that the provider cannot produce. See
+  `../yad-connect-design/references/design-context.md`.
+
 ### Step 4 — Write the UI artifacts
 Write `{project-root}/epics/EP-<slug>/ui-design.md` using EXACTLY this template:
 
@@ -78,6 +107,7 @@ owner: <inherit from epic.md owner>   # the epic owner carries through; not rety
 repos: [<inherit from epic>]
 impeccable: <used | not-installed>
 code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # code-maps that informed component reuse (Step 2b)
+design: <none | { tool: <figma|pencil|…>, direction: <generated|linked>, file: <url>, screens: <N> }>   # the connected design tool (Step 3b)
 ---
 
 ## Screens & states
@@ -91,23 +121,52 @@ code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # code-maps that inf
 
 ## Accessibility & responsiveness
 <!-- a11y notes; breakpoints/viewports covered -->
+
+## Design (<tool>)
+<!-- omit this section when design: none. one row per screen, linking to its frame in the tool.
+     mirrors design-links.json (Step 4b). -->
+<!-- - <Screen name> (<mobile|web>) — <frame url> -->
 ```
 
 Also create/update `{project-root}/epics/EP-<slug>/DESIGN.md` (Impeccable's design-system file, or a
 hand-authored equivalent when degraded) capturing the design tokens/components the screens rely on.
 
+### Step 4b — Write the design-links map (when a tool was used)
+When Step 3b generated or linked a design, write the machine-readable screen→frame map to
+`{project-root}/epics/EP-<slug>/.sdlc/design-links.json` (sibling of `contract-lock.json`):
+
+```json
+{
+  "tool": "figma",
+  "fileUrl": "https://www.figma.com/file/<key>/<name>",
+  "generatedAt": "<YYYY-MM-DD>",
+  "direction": "generated | linked",
+  "screens": [
+    { "name": "Submit Inquiry", "platform": "mobile",
+      "nodeId": "123:45", "url": "https://www.figma.com/file/<key>/?node-id=123-45" }
+  ],
+  "source": "figma-mcp"
+}
+```
+
+Keep the `## Design (<tool>)` section of `ui-design.md` in step with this file. When Step 3b degraded
+(`design: none`), do **not** write `design-links.json`.
+
 ### Step 5 — Advance the authoring step (NOT the gate)
 In `state.json`: set `ui-design.status: "done"`, set `ui-design-review.status: "in_review"`, and set
 `currentStep: "ui-design-review"`. Write `state.json`. Do **not** touch `approvals.json`.
 
 ### Step 6 — Stop at the gate (do NOT advance)
-Report: the paths to `ui-design.md` and `DESIGN.md`, whether Impeccable was used, and that the next
-action is **review** via `yad-review-gate` (base rule: owner + 1 reviewer). **Never record approval
-here.** Front states do not auto-advance. When the hub has a platform, the gate opens a review PR on the
+Report: the paths to `ui-design.md` and `DESIGN.md`, whether Impeccable was used, the connected design
+tool and what it produced (e.g. "Figma — 4 screens generated", the file URL + `design-links.json` path,
+or "no design tool — markdown-only"), and that the next action is **review** via `yad-review-gate` (base
+rule: owner + 1 reviewer). **Never record approval here.** Front states do not auto-advance. When the hub has a platform, the gate opens a review PR on the
 hub (via `yad-hub-bridge`) and `yad-review-gate action: sync` pulls platform approvals/comments into
 the ledger; otherwise the review is recorded file-only.
 
 ## Reference
 - Impeccable commands and the slash-command-vs-CLI deviation: `RESEARCH-NOTES.md` §4 + Deviation 3.
 - State schema and field meanings: `../yad-epic/references/state-schema.md`.
+- Connecting a design tool (Figma, pluggable) + generate-vs-link recipes and the degrade path:
+  `../yad-connect-design/SKILL.md` (+ `references/design-context.md`).
 - Connecting code repos + the code-context the brain reads: `../yad-connect-repos/SKILL.md`.