yadflow 2.1.0 → 2.3.0

package/skills/yad-test-cases/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: yad-test-cases
+description: 'Front state 9 of the gated SDLC — a PARALLEL, non-blocking track. Opens when the stories gate passes (the epic is already ready-for-build, so the build half can start at the same time) and runs alongside implementation. With the test architect (Murat), author test-cases.md for the approved stories, and — when a testing tool is connected — generate/link the actual automation tests in it; otherwise produce the test-case artifact only. Reads epic + architecture + contract + UI + stories as input. Never auto-advances — hands off to the team review gate. Use when the user says "author the test cases" or after the stories gate passes.'
+---
+
+# SDLC — Author Test Cases (front state 9 — parallel, non-blocking)
+
+**Goal:** Produce a human-authored, AI-assisted `test-cases.md` for an approved epic — the risk-based
+test cases that cover the stories' acceptance criteria — **and**, when a testing tool is connected, the
+**actual automation tests** inside the connected code repo(s), linked back from the artifact. This is a
+**front state**: human-authored with AI assist, **never auto-advances**. When the test cases are
+drafted, control passes to `yad-review-gate` (base rule: owner + 1 reviewer).
+
+**This step does NOT block the build half.** It opens when the **stories** gate passes — at which point
+the epic is already `ready-for-build`, so implementation (`yad-spec` → `yad-implement` → …) can start
+**at the same time** the tester works here. The test-cases track is driven by its own step `status`
+(it opens to `in_progress` when `stories-review` passes) and its review **never moves `currentStep`
+away from `ready-for-build`**, so the two run in parallel.
+
+Test work is shaped by the **test architect** lens — **Murat** (`bmad-tea`), driving
+`bmad-testarch-test-design` for the cases and `bmad-testarch-automate` for the automation. The
+automation is materialized in the **testing tool connected via `yad-connect-testing`**
+(`.sdlc/testing.json`), reached through its MCP. When a tool is connected the lens **generates** tests
+into it (or **links** an existing suite and reads it back); when none is connected, the step degrades to
+the Markdown artifact only — the testing tool is additive, exactly like the design tool.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory.
+- Artifacts live under `{project-root}/epics/EP-<slug>/` (build plan §6).
+- The connected testing tool is recorded in `{project-root}/.sdlc/testing.json` (`config.yaml`
+  `testing`), written by `yad-connect-testing`. The per-epic case→test map is `test-links.json`
+  (Step 4b).
+- Speak in the configured `communication_language`; write documents in `document_output_language`.
+
+## On Activation
+
+### Step 1 — Resolve the epic and check the track
+Resolve the `EP-<slug>` (ask if not provided). Read `.sdlc/state.json`. Only proceed when the
+**`test-cases` step's `status == "in_progress"`** — it opens when `stories-review` passes (the epic is
+already `ready-for-build` by then; `currentStep` stays there because this is a parallel track, so do
+**not** gate on `currentStep`). If `test-cases` is still `blocked`, the stories review has not passed —
+stop and point the user at `yad-status` / the gate.
+
+### Step 1b — Open the authoring branch
+Open the test-cases authoring branch `test-cases/EP-<slug>` per the shared procedure
+(`../yad-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if
+`{project-root}` is not a git work tree), check out the branch if it exists, else create it from the
+hub's default branch. Author and commit `test-cases.md` on it. This is **distinct** from the bridge's
+`review/…` branch.
+
+### Step 2 — Read inputs
+Read `epic.md` (user-level acceptance signals, scope), `architecture.md` (flows, components by repo),
+`contract.md` (the shared surface under test), `ui-design.md` (screens/states the tests exercise), and
+**all** approved `stories/EP-<slug>-S0N.md`. Each story's **acceptance criteria are the source of truth**
+for the cases — the test cases must collectively verify every story's criteria.
+
+### Step 2b — Load existing-code context (make the brain code-aware)
+Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **each repo in
+`epic.repos`**, load the code-map `{project-root}/.sdlc/code-context/<repo>/code-map.md` so the
+automation **targets real existing endpoints/components and reuses existing fixtures** rather than
+inventing parallel ones.
+
+- **Greenfield-safe:** if `repos.json` is absent/empty, note "no repos connected" and proceed.
+- **Staleness:** if a repo's current HEAD ≠ its registry `syncedHead`, warn and suggest
+  `yad repo refresh <repo>` (a human decision — flag and stop, never auto-refresh); stamp
+  `code-context: stale` in the frontmatter.
+- **Traceability:** record the loaded maps in the `test-cases.md` `code-context:` frontmatter field.
+
+### Step 3 — Author the test cases (assist: test architect)
+Adopt the **test architect** lens (`bmad-tea`, Murat), driving `bmad-testarch-test-design`. For each
+story / user flow shape risk-based test cases:
+
+- **Risk assessment** — categorize and score what can fail (probability × impact); depth scales with
+  impact (Murat's "risk-based testing" principle).
+- **Coverage plan** — assign each case a priority **P0 (critical) / P1 (high) / P2 (medium) / P3 (low)**
+  and a level, preferring the lowest useful level (unit > integration > E2E).
+- **Entry/exit criteria** and any **NFR** thresholds (security, performance, reliability) in scope.
+- Each case: a stable label, the story it covers, preconditions, steps, and expected result.
+
+### Step 3b — Materialize the automation in the connected tool (generate or link)
+Read `{project-root}/.sdlc/testing.json` (`config.yaml` `testing.registry`). Decide the path:
+
+- **No tool / `tool: "none"` / `source: "unavailable"`** (or the file is absent): **degrade** — author
+  the Markdown artifact only and record `testing: none` in the frontmatter with a one-line note
+  (mirrors the `design: none` degrade). Skip to Step 4.
+- **A tool is connected and its MCP is available:** adopt the `test architect` lens and, using the
+  provider recorded in `testing.json` (Playwright via a Playwright MCP, Cypress/pytest via theirs) drive
+  `bmad-testarch-automate`:
+  - **Generate** — when the provider is write-capable, author one automation test per high-priority
+    (P0/P1) case into the connected code repo(s) for the repos in `epic.repos`, reusing the code-maps
+    (Step 2b) and existing fixtures so tests target built endpoints/components, then run them via the MCP
+    to confirm they execute.
+  - **Link** — when the user points at an existing suite (or the provider is read-only), reference it and
+    **read the tests back** so `test-cases.md` reflects the real suite.
+
+  Capture each test's `name`, `repo`, `level`, `path`, and `url`. Record which direction was used
+  (`generated | linked`). Honest-capability rule: a read-only MCP supports **link** only — never claim a
+  test was generated that the provider cannot produce. See
+  `../yad-connect-testing/references/testing-context.md`.
+
+### Step 4 — Write the test-cases artifact
+Write `{project-root}/epics/EP-<slug>/test-cases.md` using EXACTLY this template:
+
+```markdown
+---
+id: EP-<slug>
+epic: EP-<slug>
+artifact: test-cases
+status: draft
+owner: <inherit from epic.md owner>   # the epic owner carries through; not retyped
+repos: [<inherit from epic>]
+code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # code-maps that informed the tests (Step 2b)
+testing: <none | { tool: <playwright|cypress|pytest|…>, direction: <generated|linked>, suite: <url/path>, tests: <N> }>   # the connected testing tool (Step 3b)
+---
+
+## Test strategy & risk
+<!-- risk assessment (category, probability, impact, score), entry/exit criteria, NFR thresholds in scope -->
+
+## Test cases
+<!-- one row/subsection per case: id, story covered, priority (P0–P3), level, preconditions, steps, expected -->
+
+## Coverage & traceability
+<!-- story -> case map; confirm every story's acceptance criteria are covered -->
+
+## Automation (<tool>)
+<!-- omit this section when testing: none. one row per automation test, linking to it in the repo.
+     mirrors test-links.json (Step 4b). -->
+<!-- - <Case id> -> <repo>:<test path> (<level>) — <url> -->
+```
+
+### Step 4b — Write the test-links map (when a tool was used)
+When Step 3b generated or linked automation, write the machine-readable case→test map to
+`{project-root}/epics/EP-<slug>/.sdlc/test-links.json` (sibling of `contract-lock.json` /
+`design-links.json`):
+
+```json
+{
+  "tool": "playwright",
+  "suite": "tests/playwright.config.ts",
+  "generatedAt": "<YYYY-MM-DD>",
+  "direction": "generated | linked",
+  "tests": [
+    { "case": "TC-01", "story": "EP-<slug>-S01", "repo": "backend", "level": "e2e",
+      "path": "tests/inquiry.spec.ts", "url": "<repo url to the test>" }
+  ],
+  "source": "playwright-mcp"
+}
+```
+
+Keep the `## Automation (<tool>)` section of `test-cases.md` in step with this file. When Step 3b
+degraded (`testing: none`), do **not** write `test-links.json`.
+
+### Step 5 — Advance the authoring step (NOT the gate)
+In `state.json`: set `test-cases.status: "done"` and set `test-cases-review.status: "in_review"`. **Leave
+`currentStep` at `ready-for-build`** — this is the parallel track; moving `currentStep` would pull it
+back from the build half. Write `state.json`. Do **not** touch `approvals.json`.
+
+### Step 6 — Stop at the gate (do NOT advance)
+Report: the path to `test-cases.md`, the connected testing tool and what it produced (e.g. "Playwright —
+6 tests generated", the suite path + `test-links.json` path, or "no testing tool — artifacts-only"), that
+the build half may already be underway in parallel, 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
+- Test-cases frontmatter, body template, and the `test-links.json` schema: `references/test-cases-schema.md`.
+- State schema and field meanings: `../yad-epic/references/state-schema.md`.
+- Connecting a testing tool (Playwright, pluggable) + generate-vs-link recipes and the degrade path:
+  `../yad-connect-testing/SKILL.md` (+ `references/testing-context.md`).
+- Connecting code repos + the code-context the brain reads: `../yad-connect-repos/SKILL.md`.

package/skills/yad-test-cases/references/test-cases-schema.md

@@ -0,0 +1,70 @@
+# Test-cases schema
+
+The test cases authored at front state 9 are one Markdown file under `epics/EP-<slug>/`, named
+`test-cases.md` (one per epic — mirrors `ui-design.md`, not a per-story folder). The optional automation
+linkage is a sibling `test-links.json`.
+
+## Frontmatter
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| `id` | `EP-<slug>` | The epic ID — the artifact is epic-level. |
+| `epic` | `EP-<slug>` | Parent epic ID — the unbroken link back to the epic. |
+| `artifact` | `test-cases` | Marks the artifact kind (mirrors `ui-design`). |
+| `status` | `draft` \| `in_review` \| `approved` | Lifecycle within the test-cases gate. |
+| `owner` | name | Inherited from `epic.md` `owner` (the single source — not retyped). |
+| `repos` | subset of the epic's `repos` | Which repos the automation targets. |
+| `code-context` | `{ repos: [<name@sha>], loaded: <date> }` | Optional. Which connected-repo code-maps anchored the tests (Step 2b). The `@sha` (a repo's `syncedHead`) is recommended so freshness is recorded but may be omitted; the SKILL template shows the empty placeholder `{ repos: [], loaded: <date or none> }`. `none` / `[]` when no repos are connected. |
+| `testing` | `none` \| `{ tool, direction, suite, tests }` | The connected testing tool and what it produced (Step 3b). `none` when the step ran artifacts-only. |
+
+## Body
+
+```markdown
+## Test strategy & risk
+<!-- risk assessment (category, probability, impact, score), entry/exit criteria, NFR thresholds -->
+
+## Test cases
+<!-- one row/subsection per case: id, story covered, priority (P0–P3), level, preconditions, steps, expected -->
+
+## Coverage & traceability
+<!-- story -> case map; every story's acceptance criteria must be covered -->
+
+## Automation (<tool>)
+<!-- omit when testing: none. one row per automation test, linking to it in the repo. mirrors test-links.json -->
+```
+
+## `test-links.json` (sibling, when a tool was used)
+
+Written by `yad-test-cases` Step 4b. Absent when the step ran artifacts-only (`testing: none`).
+
+```json
+{
+  "tool": "playwright",
+  "suite": "tests/playwright.config.ts",
+  "generatedAt": "<YYYY-MM-DD>",
+  "direction": "generated | linked",
+  "tests": [
+    { "case": "TC-01", "story": "EP-<slug>-S01", "repo": "backend", "level": "e2e",
+      "path": "tests/inquiry.spec.ts", "url": "<repo url to the test>" }
+  ],
+  "source": "playwright-mcp"
+}
+```
+
+## Rules
+
+- **Cover every story.** The "Coverage & traceability" section must map each story's acceptance criteria
+  to at least one case — an unmapped criterion is a gap the reviewer should catch.
+- **Priorities are risk-based.** P0 = critical (run on every commit) … P3 = low (on-demand); depth
+  scales with impact (Murat's principle).
+- **Prefer the lowest useful level.** unit > integration > E2E when a case can be verified lower.
+- **`repos` is a subset of `epic.repos`.** Automation cannot target a repo the epic does not declare.
+- **Single-file, not a folder.** `test-cases.md` resolves through the gate's default content-hash path
+  (the file's bytes), so the review gate, revoke-on-change, and review-PR machinery work unchanged.
+- **Automation is additive.** When no testing tool is connected, the step still produces a complete
+  `test-cases.md`; `testing: none` and no `test-links.json`.
+
+## Review routing (the test-cases gate)
+
+The test-cases gate uses the **base rule** (owner + 1 reviewer) — it is not escalated. The natural
+reviewer is the test architect / QA owner, but the gate predicate requires only owner + 1.

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`.