yadflow 3.13.2 → 3.15.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [3.15.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.14.0...v3.15.0) (2026-08-10)
+
+
+### Features
+
+* **testing:** add maestro as a testing-tool adapter ([7718b50](https://github.com/abdelrahmannasr/yadflow/commit/7718b502814ee8e0eb46f5e6f20342fc2471dbd7))
+
+# [3.14.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.13.2...v3.14.0) (2026-08-10)
+
+
+### Features
+
+* **next:** emit the action object with --json ([40d34dd](https://github.com/abdelrahmannasr/yadflow/commit/40d34ddba2492821700c7a877de28938faa74f3e))
+
 ## [3.13.2](https://github.com/abdelrahmannasr/yadflow/compare/v3.13.1...v3.13.2) (2026-08-10)
 
 

package/bin/yad.mjs

@@ -68,6 +68,8 @@ ${c.bold('Where am I / what next')}
   yad next <epic>                      The single next action for one epic (skill or yad command)
   yad next <epic> --check <step>       Exit 0 if <step> is runnable now, else 1 (precondition guard)
   yad next --all                       Every active epic's next action at once
+  yad next [<epic>] --json             The same answer as a machine-readable action object (for
+                                       agents/CI) — always every epic, so --all is implied
   yad skip <epic> ui-design --reason <text>   Mark an optional step N/A for this epic (only
                                        ui-design today) — a backend/API/data epic with no UI.
                                        Stays visible & auditable (pre-done, gate short-circuited);
@@ -257,7 +259,7 @@ async function main() {
       const [, epic] = o._;
       // `--check` with no step is a malformed guard call — fail loudly rather than silently print.
       if (o.check === true) { log(c.red('usage: yad next <epic> --check <step>')); process.exitCode = 1; break; }
-      await runNext(o.dir, { epic, check: typeof o.check === 'string' ? o.check : undefined, all: o.all });
+      await runNext(o.dir, { epic, check: typeof o.check === 'string' ? o.check : undefined, all: o.all, json: o.json });
       break;
     }
     case 'skip': {

package/cli/manifest.mjs

@@ -135,7 +135,7 @@ export const DESIGN_PRIMARY = 'figma';
 // is the fallback `registerTesting`/setup use when an unknown tool is named, and `none` is the explicit
 // artifacts-only choice. (doctor does NOT fall back — an unknown tool there is a hard YAD-CFG-003 fail,
 // mirroring the design-tool YAD-CFG-002.)
-export const TESTING_TOOLS = ['playwright', 'cypress', 'pytest'];
+export const TESTING_TOOLS = ['playwright', 'cypress', 'pytest', 'maestro'];
 export const TESTING_PRIMARY = 'playwright';
 
 // Supported learning-tool adapters (mirrors skills/sdlc/config.yaml `learning.tools`); `LEARNING_PRIMARY`

package/cli/next.mjs

@@ -9,10 +9,11 @@
 //   yad next <epic>           the single next action for one epic
 //   yad next <epic> --check <step>   exit 0 if <step> is runnable now, else 1 (the precondition guard)
 //   yad next --all            every active epic's next action at once
+//   yad next [<epic>] --json  the same answer as an action object, for an agent or CI
 import fs from 'node:fs';
 import path from 'node:path';
 import { c, log, ok, info, warn, hand, fail, readJSON, exists } from './lib.mjs';
-import { PROJECT_FILES } from './manifest.mjs';
+import { PROJECT_FILES, VERSION } from './manifest.mjs';
 import { epicRoot, loadLedger, nextAction, preconditionsMet, isValidEpicId, epicLineage, kindNoun, DISCOVERY_EPIC } from './epic-state.mjs';
 
 // Is solo mode on? Persisted in hub.json by setup (Phase C/D); default false. Read defensively so a
@@ -37,6 +38,14 @@ function listEpics(root) {
     .sort();
 }
 
+// The action object for ONE epic, with its lineage kind attached. The single shape both surfaces
+// consume — `printAction` renders it, `--json` emits it verbatim — so the prose and the machine
+// answer can never drift apart.
+const actionFor = (root, id) => ({
+  ...nextAction(loadLedger(epicRoot(root, id)), { epic: id }),
+  lineageKind: epicLineage(root, id).kind,
+});
+
 // EP-istifta-inquiries-S03 → S03 (the compact lane label for the roll-up). Falls back to the full id.
 const shortStory = (s) => (s && s.match(/S\d+$/i)?.[0]) || s || '(story)';
 
@@ -128,9 +137,7 @@ function generalNext(root, { all } = {}) {
   const allEpics = listEpics(root);
   const hasDiscovery = allEpics.includes(DISCOVERY_EPIC);
   const featureEpics = allEpics.filter((id) => id !== DISCOVERY_EPIC);
-  const discoveryAction = hasDiscovery
-    ? nextAction(loadLedger(epicRoot(root, DISCOVERY_EPIC)), { epic: DISCOVERY_EPIC })
-    : null;
+  const discoveryAction = hasDiscovery ? actionFor(root, DISCOVERY_EPIC) : null;
   const discoveryOpen = !!discoveryAction && discoveryAction.kind !== 'discovery-done';
 
   if (!featureEpics.length) {
@@ -142,10 +149,7 @@ function generalNext(root, { all } = {}) {
     return;
   }
 
-  const actions = featureEpics.map((id) => ({
-    ...nextAction(loadLedger(epicRoot(root, id)), { epic: id }),
-    lineageKind: epicLineage(root, id).kind,
-  }));
+  const actions = featureEpics.map((id) => actionFor(root, id));
   if (discoveryOpen) printAction(discoveryAction, { solo });   // an unfinished discovery comes first
 
   if (featureEpics.length === 1 || all) {
@@ -171,14 +175,59 @@ function checkPrecondition(root, epic, stepId) {
   process.exitCode = 1;
 }
 
+// ---- machine-readable output (`--json`) --------------------------------------------------------
+// `nextAction` already computes exactly what a caller needs; until now the ANSI prose renderer was
+// its only consumer, so anything driving yadflow had to regex coloured English. This emits the SAME
+// objects, unrendered. One envelope for every route, so a caller never has to branch on the shape:
+//
+//   { version, ok: true,  actions: [ <action>, … ] }        next / next <epic>
+//   { version, ok,        check: { epic, step, ok, reason } } next <epic> --check <step>
+//   { version, ok: true,  setUp: false, actions: [] }        the project has no `yad setup` yet
+//   { version, ok: false, error }                            bad epic id / no state.json
+//
+// Exit codes are unchanged from the prose path — only the rendering differs.
+const emitJSON = (payload) => log(JSON.stringify({ version: VERSION, ...payload }, null, 2));
+
+// A JSON error still leaves stdout parseable: a caller that pipes us into a parser gets an object
+// explaining the failure, never half a document or a bare ANSI line.
+function jsonError(message) {
+  emitJSON({ ok: false, error: message });
+  process.exitCode = 1;
+}
+
+// `--json` counterpart of runNext's three routes. Kept in one function so the routing reads next to
+// the prose routing it mirrors.
+function jsonNext(root, { epic, check }) {
+  if (epic && check) {
+    const res = preconditionsMet(loadLedger(epicRoot(root, epic)).state, check);
+    emitJSON({ ok: !!res.ok, check: { epic, step: check, ok: !!res.ok, ...(res.reason ? { reason: res.reason } : {}) } });
+    if (!res.ok) process.exitCode = 1;
+    return;
+  }
+  if (epic) {
+    if (!exists(path.join(epicRoot(root, epic), '.sdlc', 'state.json'))) {
+      return jsonError(`no epic state at epics/${epic}/.sdlc/state.json`);
+    }
+    return emitJSON({ ok: true, actions: [actionFor(root, epic)] });
+  }
+  if (!isSetUp(root)) return emitJSON({ ok: true, setUp: false, actions: [] });
+  // Every epic that HAS a ledger, discovery included — its `kind` already says whether it is open
+  // (`discovery-*`) or finished, so filtering it out would hide a fact rather than clarify one.
+  // `--all` is implied: an array always carries everything, so there is nothing left to expand.
+  return emitJSON({ ok: true, actions: listEpics(root).map((id) => actionFor(root, id)) });
+}
+
 // Entry point for the `next` command: route to the precondition check, a single epic's action, or the
 // project-wide general view. Validates the epic id first.
-export async function runNext(root, { epic, check, all } = {}) {
+export async function runNext(root, { epic, check, all, json } = {}) {
   if (epic && !isValidEpicId(epic)) {
-    fail(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`);
+    const message = `invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`;
+    if (json) return jsonError(message);
+    fail(message);
     process.exitCode = 1;
     return;
   }
+  if (json) return jsonNext(root, { epic, check });
   if (epic && check) return checkPrecondition(root, epic, check);
   if (!epic) return generalNext(root, { all });
 
@@ -189,8 +238,5 @@ export async function runNext(root, { epic, check, all } = {}) {
     process.exitCode = 1;
     return;
   }
-  printAction(
-    { ...nextAction(loadLedger(epicDir), { epic }), lineageKind: epicLineage(root, epic).kind },
-    { solo: isSolo(root) },
-  );
+  printAction(actionFor(root, epic), { solo: isSolo(root) });
 }

package/cli/setup.mjs

@@ -590,9 +590,12 @@ export async function runSetup(root, opts = {}) {
     }
 
     // Connect a testing tool (Playwright-first, pluggable; the test-cases step implements automation here)
-    S('Connect a testing tool (playwright / cypress / pytest / none)');
+    // Banner + guide read TESTING_TOOLS rather than spelling the adapters out: this is the list that
+    // actually grows (maestro joined it), and a hardcoded copy here would quietly offer the user fewer
+    // tools than the prompt below accepts.
+    S(`Connect a testing tool (${TESTING_TOOLS.join(' / ')} / none)`);
     guide([
-      'Where yad-test-cases generates automation. playwright/cypress/pytest, or none for artifacts-only.',
+      `Where yad-test-cases generates automation. ${TESTING_TOOLS.join('/')}, or none for artifacts-only.`,
       'Skipping is safe — test-cases authors test-cases.md only.',
     ]);
     if (exists(testingPath) && !(await askYesNo('testing.json exists — reconfigure?', false))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.13.2",
+  "version": "3.15.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, ship, repo, thread, reconcile). A BMAD module + 38 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/sdlc/config.yaml

@@ -198,7 +198,7 @@ design:
 # (test-links.json) is written by yad-test-cases per epic.
 testing:
   registry: "{project-root}/.sdlc/testing.json"      # project-wide testing connection (NOT per-epic)
-  tools: [playwright, cypress, pytest]                # supported adapters; an unknown tool falls back to `primary`
+  tools: [playwright, cypress, pytest, maestro]       # supported adapters; an unknown tool falls back to `primary`
   primary: playwright                                 # the default/named provider
   degrade: artifacts-only                             # no tool / no MCP => yad-test-cases authors test-cases.md only
   links: "{project-root}/epics/EP-<slug>/.sdlc/test-links.json"   # per-epic case->test map (yad-test-cases)

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

@@ -21,7 +21,7 @@ connected, `yad-test-cases` runs artifacts-only exactly as before.
 - `{project-root}` resolves from the project working directory (the **product hub**).
 - The integration is **Playwright-first but pluggable** (`config.yaml` `testing.tools`): a testing-tool
   *adapter*, like the GitHub/GitLab platform adapter or the design-tool adapter. Playwright is the
-  primary provider; `cypress` and `pytest` are second providers; `none` → artifacts-only.
+  primary provider; `cypress`, `pytest` and `maestro` are second providers; `none` → artifacts-only.
 - **The testing tool is reached through its MCP** (a harness MCP server), NOT a subprocess CLI — the
   same shape as the design tool's MCP, not Repomix's `npx`. The skill detects the MCP and degrades when
   it is absent; it never installs an MCP server.
@@ -34,7 +34,7 @@ connected, `yad-test-cases` runs artifacts-only exactly as before.
 ## Inputs
 
 - `action` — `connect` (default) | `refresh` | `list` | `disconnect`.
-- `tool` — `playwright` | `cypress` | `pytest` | another adapter id (`config.yaml` `testing.tools`).
+- `tool` — `playwright` | `cypress` | `pytest` | `maestro` | another adapter id (`config.yaml` `testing.tools`).
   `none` records a deliberate artifacts-only project.
 - `project_url` — the testing tool's project/config reference (e.g. a `playwright.config.ts` path or a
   test-runner project URL). Optional — a connection with no suite yet is valid; `yad-test-cases` can
@@ -51,9 +51,13 @@ way `registerRepo` falls back on an unknown platform). Then **detect the tool's
 - **playwright** → a Playwright MCP server (drives a browser, generates/runs E2E + API specs).
 - **cypress** → the Cypress MCP (generate/run Cypress specs).
 - **pytest** → a pytest MCP (generate/run service-layer tests).
+- **maestro** → the Maestro MCP, bundled in the Maestro CLI and started as `maestro mcp` over STDIO
+  (drives iOS simulators, Android emulators and Chromium; generates/runs Maestro flows). Mobile E2E,
+  where Playwright has no reach.
 - another adapter → its named MCP.
 
-Record `provider` (the concrete MCP, e.g. `playwright-mcp` | `cypress-mcp` | `pytest-mcp`) and whether
+Record `provider` (the concrete MCP, e.g. `playwright-mcp` | `cypress-mcp` | `pytest-mcp` |
+`maestro-mcp`) and whether
 it is available. **Auth is the local user's own** — the user's authenticated MCP session. The skill
 **stores no tokens**; `project_url`/`suites` are plain references, never credentials.
 

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

@@ -15,6 +15,7 @@ Detection is best-effort against the user's own authenticated MCP session:
 | `playwright` | a Playwright MCP | **generate** — author + run E2E/API specs against the app |
 | `cypress` | the Cypress MCP | **generate** — author + run Cypress specs |
 | `pytest` | a pytest MCP | **generate** — author + run service-layer tests |
+| `maestro` | the Maestro MCP (`maestro mcp`, bundled in the CLI, STDIO) | **generate** — author + run Maestro flows on iOS/Android/Chromium |
 | any | a read-only runner MCP | **link** — reference an existing suite and read results back |
 | other | the adapter's named MCP | per that adapter |
 
@@ -34,6 +35,11 @@ the cases `test-cases.md` enumerates and the acceptance criteria the stories def
   the code-maps from `yad-test-cases` Step 2b), one spec per high-priority (P0/P1) case, and runs them
   via the MCP to confirm they execute.
 - **Cypress / pytest** — the lens authors the equivalent specs in that framework's layout.
+- **Maestro** — the lens authors `.yaml` flows under the repo's Maestro directory (one flow per
+  high-priority case), targeting the app id / screen elements the code-maps name rather than invented
+  ones, and runs them via the MCP against a simulator/emulator to confirm they execute. Mobile E2E is
+  the top of that pyramid: keep the flow count small and push detail down to the unit/integration
+  levels the repo already has.
 
 Reuse what already exists: load the connected code repos' code-maps (`yad-test-cases` Step 2b) so
 generated tests target real endpoints/components, not invented ones, and prefer the lowest useful test

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

@@ -14,8 +14,8 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
 
 ```json
 {
-  "tool": "playwright",                              // playwright | cypress | pytest | <adapter id> | none (artifacts-only)
-  "provider": "playwright-mcp",                      // the concrete MCP: playwright-mcp | cypress-mcp | pytest-mcp | null
+  "tool": "playwright",                              // playwright | cypress | pytest | maestro | <adapter id> | none
+  "provider": "playwright-mcp",                      // the concrete MCP: playwright-mcp | cypress-mcp | pytest-mcp | maestro-mcp | null
   "project_url": "tests/playwright.config.ts",       // project/config reference; null if none yet
   "auth": "user",                                    // ALWAYS the user's own MCP session — never a token
   "suites": { "backend": null, "mobile": null },     // optional default suite refs per repo

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

@@ -94,7 +94,8 @@ Read `{project-root}/.sdlc/testing.json` (`config.yaml` `testing.registry`). Dec
   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
+  provider recorded in `testing.json` (Playwright via a Playwright MCP, Cypress/pytest/Maestro via
+  theirs — Maestro authors mobile flows where Playwright has no reach) 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
@@ -120,7 +121,7 @@ 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)
+testing: <none | { tool: <playwright|cypress|pytest|maestro|…>, direction: <generated|linked>, suite: <url/path>, tests: <N> }>   # the connected testing tool (Step 3b)
 ---
 
 ## Test strategy & risk