yadflow 4.9.0 → 4.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/CHANGELOG.md +87 -0
  2. package/README.md +4 -3
  3. package/bin/commands.mjs +6 -0
  4. package/bin/yad.mjs +101 -6
  5. package/cli/agent-guard.mjs +793 -65
  6. package/cli/agent-rules.mjs +33 -5
  7. package/cli/argv-flags.mjs +1 -1
  8. package/cli/ci-check.mjs +45 -1
  9. package/cli/codeowners-command.mjs +72 -6
  10. package/cli/commit.mjs +17 -3
  11. package/cli/docs.mjs +2 -0
  12. package/cli/doctor.mjs +71 -12
  13. package/cli/epic-state.mjs +94 -4
  14. package/cli/epic.mjs +11 -7
  15. package/cli/fold.mjs +31 -6
  16. package/cli/guide.mjs +3 -1
  17. package/cli/hook.mjs +50 -7
  18. package/cli/issue-links.mjs +61 -0
  19. package/cli/issues-act.mjs +327 -0
  20. package/cli/issues-write.mjs +428 -0
  21. package/cli/issues.mjs +474 -0
  22. package/cli/lifecycle.mjs +7 -0
  23. package/cli/manifest.mjs +9 -3
  24. package/cli/openpr.mjs +24 -4
  25. package/cli/plan.mjs +2 -0
  26. package/cli/platform.mjs +157 -2
  27. package/cli/protection.mjs +21 -3
  28. package/cli/reconcile.mjs +1 -1
  29. package/cli/run-checks.mjs +10 -2
  30. package/cli/scan.mjs +314 -0
  31. package/cli/setup.mjs +12 -3
  32. package/cli/standup.mjs +33 -7
  33. package/cli/story-frames.mjs +17 -6
  34. package/cli/test-agents-file.mjs +378 -11
  35. package/cli/test-build.mjs +25 -0
  36. package/cli/test-ci-check.mjs +469 -10
  37. package/cli/test-guide.mjs +7 -0
  38. package/cli/test-node.mjs +15 -0
  39. package/cli/test-run-checks.mjs +17 -0
  40. package/cli/test-setup-agent.mjs +14 -0
  41. package/cli/test-story-frames.mjs +74 -4
  42. package/cli/toolbox-connect.mjs +244 -0
  43. package/cli/toolbox.mjs +129 -9
  44. package/package.json +7 -3
  45. package/skills/sdlc/config.yaml +1 -1
  46. package/skills/sdlc/module-help.csv +3 -1
  47. package/skills/yad-analysis/SKILL.md +4 -0
  48. package/skills/yad-backfill/SKILL.md +4 -0
  49. package/skills/yad-change/SKILL.md +4 -0
  50. package/skills/yad-checks/SKILL.md +13 -7
  51. package/skills/yad-checks/references/check-gates.md +62 -30
  52. package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
  53. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  54. package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
  55. package/skills/yad-checks/templates/github/yad-checks.yml +357 -69
  56. package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
  57. package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
  58. package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
  59. package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
  60. package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
  61. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +79 -20
  62. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
  63. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
  64. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
  65. package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
  66. package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
  67. package/skills/yad-commit/SKILL.md +3 -1
  68. package/skills/yad-connect-design/SKILL.md +42 -10
  69. package/skills/yad-connect-design/references/design-context.md +35 -5
  70. package/skills/yad-connect-design/references/design-registry.md +3 -3
  71. package/skills/yad-connect-learning/SKILL.md +12 -2
  72. package/skills/yad-connect-repos/SKILL.md +4 -0
  73. package/skills/yad-connect-testing/SKILL.md +22 -5
  74. package/skills/yad-connect-testing/references/testing-context.md +1 -1
  75. package/skills/yad-epic/SKILL.md +4 -0
  76. package/skills/yad-epic/references/state-schema.md +15 -0
  77. package/skills/yad-guide/SKILL.md +8 -4
  78. package/skills/yad-implement/SKILL.md +56 -4
  79. package/skills/yad-implement/references/implement-conventions.md +2 -1
  80. package/skills/yad-issues/SKILL.md +53 -0
  81. package/skills/yad-learn/SKILL.md +4 -0
  82. package/skills/yad-open-pr/SKILL.md +6 -0
  83. package/skills/yad-pr-template/SKILL.md +2 -1
  84. package/skills/yad-pr-template/templates/checks/pr-title.sh +34 -2
  85. package/skills/yad-product-bridge/references/bridge.md +28 -0
  86. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
  87. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
  88. package/skills/yad-run/SKILL.md +5 -0
  89. package/skills/yad-scan/SKILL.md +51 -0
  90. package/skills/yad-spec/SKILL.md +13 -2
  91. package/skills/yad-test-cases/SKILL.md +18 -2
  92. package/skills/yad-ui/SKILL.md +43 -8
  93. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
@@ -248,10 +248,13 @@ test('#358: designPreflight — Pencil is read through the app; Figma only throu
248
248
  assert.deepEqual([pencil.reachable, pencil.appBound, pencil.frame, pencil.file], ['check', true, '12:34', 'design/app.pen'], 'the first frame that resolves is the one probed');
249
249
  assert.match(pencil.stop, /^Open the Pencil desktop app with `design\/app\.pen` loaded/);
250
250
  assert.match(pencil.probe, /get_app_state/);
251
+ // E165: the command to connect the tool, when it is not on this machine at all.
252
+ assert.equal(pencil.connect, 'yad toolbox connect pencil --json');
251
253
  const desk = designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'figma-desktop' } }, links, frames);
252
254
  assert.deepEqual([desk.appBound, /desktop app/.test(desk.stop)], [true, true]);
255
+ assert.equal(desk.connect, undefined, 'the desktop app\'s own server: open the app, never the hosted plugin\'s recipe');
253
256
  const cloud = designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'figma' } }, links, frames);
254
- assert.deepEqual([cloud.appBound, /^Sign in to Figma/.test(cloud.stop)], [false, true]);
257
+ assert.deepEqual([cloud.appBound, /^Sign in to Figma/.test(cloud.stop), cloud.connect], [false, true, 'yad toolbox connect figma --json']);
255
258
  assert.match(cloud.probe, /`12:34`/);
256
259
  const old = designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'figma-mcp' } }, links, frames);
257
260
  assert.deepEqual([old.appBound, /desktop app.*or sign in/.test(old.stop)], [null, true], 'the older figma-mcp: yad cannot tell, so both');
@@ -268,13 +271,38 @@ test('#358: designPreflight — Pencil is read through the app; Figma only throu
268
271
  assert.equal(designPreflight({ state: 'ok', data: { tool: 'figma', provider } }, links, frames).reachable, 'not-checkable', provider);
269
272
  }
270
273
  assert.equal(designPreflight({ state: 'ok', data: { tool: 'figma' } }, { ...links, tool: 'Figma' }, frames).reachable, 'check', 'the same tool in other letters is not a switch');
274
+ for (const r of [pencil, desk, cloud, old]) assert.equal(r.local, false, 'only a provider in reach.local is local');
275
+ });
276
+
277
+ test('E164: designPreflight — OpenPencil\'s CLI needs no app and no sign-in; its MCP server needs the app', () => {
278
+ const frames = [{ id: 'login-mobile', found: true }];
279
+ const links = { state: 'ok', tool: 'openpencil', fileUrl: 'epics/EP-shop/design/screens.fig', screens: [] };
280
+ const cli = designPreflight({ state: 'ok', data: { tool: 'openpencil', provider: 'openpencil-cli' } }, links, frames);
281
+ assert.deepEqual([cli.reachable, cli.appBound, cli.local, cli.frame], ['check', false, true, 'login-mobile']);
282
+ assert.match(cli.probe, /^check that `epics\/EP-shop\/design\/screens\.fig` is in the Product checkout and that `openpencil --version` runs/);
283
+ assert.match(cli.probe, /shared plugin data `yad`\/`nodeId` is `login-mobile`/, 'the frame is found by the ID yad stored on it');
284
+ assert.match(cli.stop, /^Pull the Product so that `epics\/EP-shop\/design\/screens\.fig` is there with frame `login-mobile` in it/);
285
+ for (const text of [cli.probe, cli.stop]) assert.doesNotMatch(text, /desktop app|sign in/i, 'the CLI path never asks for an app or a sign-in');
286
+ assert.equal(cli.connect, 'yad toolbox connect openpencil --json');
287
+ const mcp = designPreflight({ state: 'ok', data: { tool: 'openpencil', provider: 'openpencil-mcp' } }, links, frames);
288
+ assert.deepEqual([mcp.appBound, mcp.local], [true, false]);
289
+ assert.match(mcp.probe, /OpenPencil MCP: its eval tool/);
290
+ assert.match(mcp.stop, /^Open the OpenPencil desktop app with `epics\/EP-shop\/design\/screens\.fig` loaded \(the file must be inside OPENPENCIL_MCP_ROOT\)/);
291
+ assert.equal(mcp.connect, 'yad toolbox connect openpencil --json', 'OpenPencil\'s recipe adds its MCP server, so it is offered');
292
+ const unknown = designPreflight({ state: 'ok', data: { tool: 'openpencil' } }, links, frames);
293
+ assert.deepEqual([unknown.appBound, unknown.local, /runs in your terminal \(the CLI\), or open the OpenPencil desktop app/.test(unknown.stop)], [null, false, true], 'no provider: both ways');
294
+ assert.match(unknown.probe, /^try the CLI first: .*`openpencil eval`.* if that does not find it, find frame .* through the OpenPencil MCP's eval tool.*It fails only when neither finds it/, 'reviews 1-2: the check tries both ways the stop text names, the MCP whenever the CLI does not find the frame');
295
+ assert.equal(designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'figma-mcp' } }, { ...links, tool: 'figma' }, frames).probe.includes('get_metadata'), true, 'a tool with no eitherProbe keeps its probe');
296
+ assert.equal(designPreflight({ state: 'ok', data: { tool: 'openpencil', provider: 'OpenPencil_CLI' } }, links, frames).local, true, 'names are compared on letters and digits');
271
297
  });
272
298
 
273
299
  test('#358: designPreflight — nothing to probe is not-checkable, and no frame means no preflight', () => {
274
300
  const frames = [{ id: '12:34', found: true }];
275
301
  const links = { state: 'ok', fileUrl: 'f', screens: [] };
276
302
  for (const design of [{ state: 'missing' }, { state: 'unreadable' }, { state: 'ok', data: { tool: 'none' } }, { state: 'ok', data: { tool: 'pencil', source: 'unavailable' } }, { state: 'ok', data: { tool: 'sketch' } }]) {
277
- assert.equal(designPreflight(design, links, frames).reachable, 'not-checkable', JSON.stringify(design));
303
+ const r = designPreflight(design, links, frames);
304
+ assert.equal(r.reachable, 'not-checkable', JSON.stringify(design));
305
+ assert.equal(r.connect, undefined, 'nothing to probe, nothing to connect: connecting the team\'s tool is yad-connect-design\'s');
278
306
  }
279
307
  assert.equal(designPreflight({ state: 'ok', data: { tool: 'pencil' } }, links, []), null);
280
308
  const writer = designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'html-to-design' } }, links, frames);
@@ -295,7 +323,16 @@ test('#358: designPreflight — nothing to probe is not-checkable, and no frame
295
323
  test('#358: readDesignConfig, the reach data, and preflight through the command', () => {
296
324
  for (const t of TOOLBOX.filter((x) => x.reach)) assert.deepEqual(toolProblems(t), [], t.id);
297
325
  const figma = TOOLBOX.find((x) => x.id === 'figma');
298
- assert.deepEqual(toolProblems({ ...figma, reach: { app: 'F', probe: 'p', open: 'o', readers: true, appBound: ['x'] } }), ['reach.signIn and reach.either say what to do when the provider needs no app, or yad cannot tell']);
326
+ assert.deepEqual(toolProblems({ ...figma, reach: { app: 'F', probe: 'p', open: 'o', readers: true, appBound: ['x'] } }), ['reach.either says what to do when yad cannot tell whether the provider needs the app']);
327
+ assert.deepEqual(toolProblems({ ...figma, reach: { app: 'F', probe: 'p', open: 'o', appBound: ['x'], either: 'e', signInOnly: ['y'] } }), ['reach.signIn says what to do for a provider in signInOnly']);
328
+ // E164: a local provider (a CLI on the file) carries its own probe and stop text.
329
+ const op = TOOLBOX.find((x) => x.id === 'openpencil');
330
+ assert.deepEqual(toolProblems({ ...op, reach: { ...op.reach, localStop: undefined } }), ['reach.localProbe and reach.localStop say how to check a provider in local, and what to do when that fails']);
331
+ assert.deepEqual(toolProblems({ ...op, reach: { ...op.reach, local: 'openpencil-cli' } }), ['reach.local is absent or a list of providers']);
332
+ assert.deepEqual(toolProblems({ ...figma, reach: { ...figma.reach, ownServer: [1] } }), ['reach.ownServer is absent or a list of providers']);
333
+ assert.deepEqual(toolProblems({ ...op, reach: { ...op.reach, eitherProbe: '' } }), ['reach.eitherProbe is absent or how to check when yad cannot tell the provider']);
334
+ assert.deepEqual(toolProblems({ ...op, reach: { ...op.reach, local: ['openpencil-mcp'] } }), ['a provider is in reach.local or reach.appBound, not both']);
335
+ assert.deepEqual(toolProblems({ ...op, reach: { ...op.reach, local: ['OpenPencil_MCP'] } }), ['a provider is in reach.local or reach.appBound, not both'], 'review 2: compared as the preflight compares them');
299
336
  assert.ok(toolProblems({ ...figma, reach: { readers: true, appBound: true } }).includes('reach has app, probe and open'));
300
337
  assert.ok(toolProblems({ ...figma, reach: null }).length > 0);
301
338
  assert.ok(toolProblems({ ...figma, reach: { ...figma.reach, appBound: false } }).includes('reach.appBound is true, or the providers read through the app'));
@@ -308,7 +345,20 @@ test('#358: readDesignConfig, the reach data, and preflight through the command'
308
345
  put(path.join(T, '.sdlc', 'design.json'), { tool: 'pencil', provider: 'pencil-mcp', source: 'pencil-mcp', auth: 'user' });
309
346
  const j = JSON.parse(yad(T, 'story', 'frames', 'EP-shop-S01', '--json').stdout);
310
347
  assert.deepEqual([j.preflight.reachable, j.preflight.tool, j.preflight.appBound], ['check', 'pencil', true]);
311
- assert.match(yad(T, 'story', 'frames', 'EP-shop-S01').stdout, /before UI work: .* if that fails, stop: Open the Pencil desktop app/);
348
+ assert.match(yad(T, 'story', 'frames', 'EP-shop-S01').stdout, /before UI work: .* if that fails, stop: Open the Pencil desktop app[\s\S]*if pencil is not on this machine at all, your agent can offer to connect it first: `yad toolbox connect pencil --json`/);
349
+ assert.equal(j.preflight.connect, 'yad toolbox connect pencil --json');
350
+ // Review 2: no `connect`, no offer line — Figma's desktop server is opened, never connected.
351
+ put(path.join(T, '.sdlc', 'design.json'), { tool: 'figma', provider: 'figma-desktop', source: 'figma-desktop', auth: 'user' });
352
+ put(path.join(T, 'epics', 'EP-shop', '.sdlc', 'design-links.json'), { ...LINKS, tool: 'figma', source: 'figma' });
353
+ const desk = yad(T, 'story', 'frames', 'EP-shop-S01');
354
+ assert.match(desk.stdout, /before UI work: .* if that fails, stop: .*Figma desktop app/);
355
+ assert.doesNotMatch(desk.stdout, /offer to connect/);
356
+ // E164: OpenPencil's CLI — the local probe and stop, and the connect offer.
357
+ put(path.join(T, '.sdlc', 'design.json'), { tool: 'openpencil', provider: 'openpencil-cli', source: 'openpencil-cli', auth: 'user' });
358
+ put(path.join(T, 'epics', 'EP-shop', '.sdlc', 'design-links.json'), { ...LINKS, tool: 'openpencil', source: 'openpencil-cli' });
359
+ const opj = JSON.parse(yad(T, 'story', 'frames', 'EP-shop-S01', '--json').stdout).preflight;
360
+ assert.deepEqual([opj.reachable, opj.appBound, opj.local, opj.connect], ['check', false, true, 'yad toolbox connect openpencil --json']);
361
+ assert.match(yad(T, 'story', 'frames', 'EP-shop-S01').stdout, /before UI work: check that .* `openpencil --version` runs.* if that fails, stop: Pull the Product[\s\S]*offer to connect it first: `yad toolbox connect openpencil --json`/);
312
362
  assert.equal(JSON.parse(yad(T, 'story', 'frames', 'EP-shop-S02', '--json').stdout).preflight, null, 'no screens, no probe');
313
363
  } finally { done(T); }
314
364
  });
@@ -337,3 +387,23 @@ test('#358: spec and implement probe the design tool first, stop on a failure, a
337
387
  const example = connect.slice(connect.indexOf('### Step 2'), connect.indexOf('### Step 3'));
338
388
  assert.ok(example.includes('"provider": "figma-desktop"') && !example.includes('figma-mcp'), 'the registry example records a provider the preflight can read');
339
389
  });
390
+
391
+ test('E164 PR 2: the skills give each OpenPencil frame yad\'s own ID, fold takes design/, and the probe may be a CLI command', () => {
392
+ const read = (rel) => fs.readFileSync(path.join(REPO, rel), 'utf8');
393
+ const ui = read('skills/yad-ui/SKILL.md');
394
+ const ctx = read('skills/yad-connect-design/references/design-context.md');
395
+ for (const [name, text] of [['yad-ui', ui], ['design-context', ctx]]) {
396
+ assert.match(text, /setSharedPluginData\('yad', 'nodeId', '<id>'\)/, `${name}: yad stores its own ID on the frame`);
397
+ assert.match(text, /getSharedPluginData\('yad', 'nodeId'\) === '<id>'/, `${name}: and finds the frame by it`);
398
+ assert.match(text, /`yad fold` (takes that folder too|commits the\s+`design\/` folder)/, `${name}: fold takes design/`);
399
+ assert.doesNotMatch(text, /not taken by `yad fold` yet|Until E164's second PR/, `${name}: no note from before PR 2`);
400
+ }
401
+ assert.match(ui, /each screen's `nodeId` is the ID yad stored on its frame/);
402
+ assert.match(ctx, /\| `openpencil`, provider `openpencil-cli` \|/);
403
+ assert.doesNotMatch(ctx, /not checked yet: yad has no reach rule/);
404
+ for (const skill of ['yad-spec', 'yad-implement']) {
405
+ const text = read(`skills/${skill}/SKILL.md`);
406
+ assert.match(text, /make the check `preflight\.probe`\s+describes \(an MCP call, or for a tool's\s+CLI — `preflight\.local` is true — a command in your terminal\)/, skill);
407
+ assert.doesNotMatch(text, /make the MCP call/, skill);
408
+ }
409
+ });
@@ -0,0 +1,244 @@
1
+ // `yad toolbox connect <tool>` (E165): what the agent may run to put a toolbox tool on this machine, after
2
+ // one yes from the person, and the record of the team's choice once it is found.
3
+ //
4
+ // E85 made the toolbox print-only, and the install lines (`install` in cli/toolbox.mjs) stay text for people:
5
+ // some start an interactive installer, some are slash commands only a person types, one runs a remote
6
+ // script. So each tool also has a RECIPE here: the exact steps, each marked for the agent or the person.
7
+ // The agent runs only package-manager and plugin installs, pinned to the vetted version (E88) wherever one is
8
+ // vetted; everything else — a remote script, an interactive installer, a slash command, an app, a sign-in —
9
+ // is the person's, with why.
10
+ // The user's decisions (2026-11-05): one yes per tool covers installing it here AND recording the team's
11
+ // choice; nothing here ever installs on its own.
12
+ //
13
+ // yad toolbox connect <tool> [--json] read: the steps, the question to ask, what will be recorded
14
+ // yad toolbox connect <tool> --verify [--json] finds it here, then records the choice (or says what is missing)
15
+ import fs from 'node:fs';
16
+ import path from 'node:path';
17
+ import { emitJSON, hand, info, ok, readJSONStrict, refuse, warn } from './lib.mjs';
18
+ import { clean, detectInstalled } from './detect.mjs';
19
+ import { PROJECT_FILES } from './manifest.mjs';
20
+ import {
21
+ TOOLBOX, connectorFile, loadChoices, onPath, readToolboxFile, recordToolUse, toolStatus, toolUse,
22
+ } from './toolbox.mjs';
23
+ import { registerDesign, registerLearning, registerTesting } from './setup.mjs';
24
+
25
+ // Each shipped tool's recipe. `null`: nothing to install here (the person's app, account or service — the
26
+ // tool's `manual` says how). An agent step is a package-manager or plugin install, pinned to the vetted version
27
+ // wherever one is vetted; `recipeProblems` checks it. The `claude` steps are Claude Code's: with another agent,
28
+ // the connect-tool rule hands every step to the person.
29
+ const A = (run) => ({ who: 'agent', run, scope: 'user' });
30
+ const P = (run, why) => ({ who: 'person', run, why });
31
+ // A person step that is a thing to do, not a command to type.
32
+ const PT = (run, why) => ({ who: 'person', run, why, text: true });
33
+ const INTERACTIVE = 'an interactive installer: it asks you questions, which an agent cannot answer';
34
+ const SCRIPT = 'a remote install script: no version pin covers what it runs, so you read and run it yourself';
35
+ export const RECIPES = Object.freeze({
36
+ repomix: [A('npm install -g repomix@1.18.1')],
37
+ 'spec-kit': [
38
+ A('uv tool install specify-cli==1.0.13'),
39
+ P('specify init <project> --integration claude', 'it sets Spec Kit up inside one code repo, and asks you questions'),
40
+ ],
41
+ impeccable: [P('npx impeccable install', INTERACTIVE)],
42
+ 'bmad-method': [P('npx bmad-method install', INTERACTIVE)],
43
+ ecc: [P('npx ecc-universal install --guided', INTERACTIVE)],
44
+ 'mattpocock-skills': [P('claude plugin install mattpocock-skills', 'it comes from its own plugin marketplace, which you add in your agent first')],
45
+ 'docker-mcp': [PT('set up the MCP Toolkit in Docker Desktop: https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/', 'it is a feature of the Docker Desktop app')],
46
+ 'unity-mcp': [
47
+ PT('in the Unity Editor, open the Package Manager (Window → Package Manager), choose + → Add (in Unity 6: Install) package from git URL, and enter https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v10.3.0', 'it is set up inside the Unity Editor, in your project'),
48
+ PT('then open Window → MCP for Unity → Toggle MCP Window; under Per-client setup, with Claude Code chosen, set Client Project Dir to the folder your agent starts in (the Unity repo, unless you start it elsewhere); press Configure All Detected Clients, and restart your agent', 'the Editor writes the server into your agent\'s settings for that folder only, and an agent loads a new MCP server when it starts'),
49
+ ],
50
+ figma: [
51
+ A('claude plugin install figma@claude-plugins-official'),
52
+ PT('sign in to Figma in your agent (its Figma MCP server)', 'a sign-in is yours: it is your Figma account'),
53
+ ],
54
+ pencil: [PT('install the Pencil desktop app, open a .pen file, then Settings → MCP → enable your agent: https://docs.pencil.dev/getting-started/installation', 'it is a desktop app, set up inside the app')],
55
+ openpencil: [
56
+ A('npm install -g @open-pencil/mcp@0.16.0 @open-pencil/cli@0.16.0'),
57
+ A('claude mcp add --scope user open-pencil -- openpencil-mcp'),
58
+ ],
59
+ playwright: [A('claude mcp add --scope user playwright -- npx @playwright/mcp@0.0.83')],
60
+ cypress: [PT('connect the Cypress Cloud MCP: https://docs.cypress.io/cloud/integrations/cloud-mcp', 'it reads your Cypress Cloud account')],
61
+ pytest: [PT('connect a pytest MCP server you trust, under the name pytest: https://docs.pytest.org/', 'pytest has no official MCP server, and the community ones are not vetted, so the choice is yours')],
62
+ maestro: [
63
+ P('curl -fsSL "https://get.maestro.mobile.dev" | bash', SCRIPT),
64
+ A('claude mcp add --scope user maestro -- maestro mcp'),
65
+ ],
66
+ deeptutor: [
67
+ P('pip install deeptutor==1.6.12', 'where Python packages go (pip, pipx or a virtual environment) is your choice'),
68
+ P('deeptutor init', INTERACTIVE),
69
+ ],
70
+ });
71
+
72
+ // What an agent step may never hold: a version other than a pin, or a way to run what no pin covers.
73
+ const FORBIDDEN = [
74
+ [/@latest\b/, '@latest'],
75
+ [/\|\s*(ba|z)?sh\b/, 'a pipe into a shell'],
76
+ [/\bcurl\b|\bwget\b/, 'a download'],
77
+ [/\bgit clone\b/, 'a git clone'],
78
+ [/^\//, 'a slash command'],
79
+ [/&&|;/, 'two commands on one line'],
80
+ ];
81
+
82
+ // Every way a tool's recipe breaks the rules, as sentences. [] means it is sound.
83
+ export function recipeProblems(tool, steps = Object.hasOwn(RECIPES, tool.id) ? RECIPES[tool.id] : undefined) {
84
+ const out = [];
85
+ if (steps === undefined) return [`${tool.id} has no recipe (null when there is nothing to install)`];
86
+ if (steps === null) return out;
87
+ if (!Array.isArray(steps) || !steps.length) return [`${tool.id}: a recipe is a list of steps, or null`];
88
+ const agentRuns = steps.filter((s) => s.who === 'agent').map((s) => s.run).join('\n');
89
+ for (const s of steps) {
90
+ if (!['agent', 'person'].includes(s.who) || typeof s.run !== 'string' || !s.run) out.push(`${tool.id}: a step has who (agent or person) and run`);
91
+ if (s.who === 'person' && !(typeof s.why === 'string' && s.why)) out.push(`${tool.id}: a person step says why it is the person's`);
92
+ if (s.who === 'agent') for (const [re, what] of FORBIDDEN) if (re.test(s.run)) out.push(`${tool.id}: the agent step \`${s.run}\` holds ${what}`);
93
+ }
94
+ // A vetted package the agent installs is installed at its vetted version, and never another.
95
+ for (const p of tool.vetted?.packages ?? []) {
96
+ const names = new RegExp(`(^|[\\s/])${p.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=[@=\\s]|$)`, 'm');
97
+ if (!names.test(agentRuns)) continue;
98
+ const pin = p.registry === 'pypi' ? `${p.name}==${p.version}` : `${p.name}@${p.version}`;
99
+ if (!agentRuns.includes(pin)) out.push(`${tool.id}: the agent installs ${p.name}, but not at the vetted ${pin}`);
100
+ }
101
+ return out;
102
+ }
103
+
104
+ const tools = () => TOOLBOX;
105
+ const byId = (id) => tools().find((t) => t.id === id) ?? null;
106
+
107
+ // The file `--verify` records the team's choice in: a connector's own file (it is what makes a connector used),
108
+ // else the tool's line in the toolbox file.
109
+ const recordFile = (tool) => (tool.tier === 'connector' ? connectorFile(tool) : null) ?? PROJECT_FILES.toolboxConfig;
110
+
111
+ // What the connector's file names today, read strictly: `{ tool }` (null when there is no file or it names
112
+ // none), or `{ error }` when it does not parse — such a file is never written over.
113
+ function currentConnection(productRoot, tool) {
114
+ const file = tool.tier === 'connector' ? connectorFile(tool) : null;
115
+ if (!file || !productRoot) return { tool: null };
116
+ const abs = path.join(productRoot, file);
117
+ if (!fs.existsSync(abs)) return { tool: null };
118
+ try {
119
+ const doc = readJSONStrict(abs);
120
+ const t = doc && typeof doc.tool === 'string' && doc.tool !== 'none' ? doc.tool : null;
121
+ return { tool: t };
122
+ } catch (e) { return { error: `${file} does not parse (${e.message})` }; }
123
+ }
124
+ const nameOf = (id) => byId(id)?.name ?? id;
125
+
126
+ // On native Windows, a local MCP server started through npx or an npm program (a .cmd shim) needs `cmd /c`
127
+ // (Claude Code's own setup note): the same step, in the form that starts there.
128
+ const forPlatform = (run, platform) => (platform === 'win32' && /^claude mcp add .* -- (?!cmd \/c )/.test(run) ? run.replace(' -- ', ' -- cmd /c ') : run);
129
+
130
+ // The question the agent asks, word for word: every step in order (each of the person's with its reason), where
131
+ // it installs, and what it records — naming the tool it replaces as the team's choice, if any.
132
+ function askText(tool, steps, { found, file, replaces, productRoot }) {
133
+ const recordPart = !productRoot ? 'There is no Product here, so nothing will be recorded.'
134
+ : replaces ? `record it as this team's choice in ${file}, in place of ${nameOf(replaces)} (what that file holds for ${nameOf(replaces)} is dropped)`
135
+ : `record it as this team's choice in ${file}`;
136
+ if (!steps.length && found) return productRoot ? `${tool.name} is already on this machine. ${recordPart[0].toUpperCase()}${recordPart.slice(1)}?` : `${tool.name} is already on this machine. ${recordPart}`;
137
+ const tail = productRoot ? `then I will check that it is found and ${recordPart}.` : `then I will check that it is found. ${recordPart}`;
138
+ if (!steps.length) return `${tool.name} has nothing yad can install: set it up as ${tool.manual ?? tool.source} says; ${tail}`;
139
+ // In the recipe's order: a step of the person's that comes first (Maestro's installer) is said first.
140
+ const parts = [];
141
+ for (const s of steps) {
142
+ const last = parts[parts.length - 1];
143
+ if (last && last.who === s.who) last.runs.push(s);
144
+ else parts.push({ who: s.who, runs: [s] });
145
+ }
146
+ const said = parts.map((p, i) => {
147
+ const lead = i === 0 ? (p.who === 'person' ? 'first, ' : '') : 'then ';
148
+ if (p.who === 'agent') return `${lead}I will run ${p.runs.map((r) => `\`${r.run}\``).join(', then ')} (for your user account on this machine)`;
149
+ return `${lead}you ${p.runs.map((r) => `${r.text ? r.run : `run \`${r.run}\``} (${r.why})`).join(', then ')}`;
150
+ });
151
+ said[0] = said[0][0].toUpperCase() + said[0].slice(1);
152
+ const anyAgent = steps.some((s) => s.who === 'agent');
153
+ return `${anyAgent ? `Connect ${tool.name}? ` : `${tool.name} needs steps only you can do. `}${said.join('; ')}; ${tail}`;
154
+ }
155
+
156
+ const personBlock = (steps, verify) => (steps.length ? {
157
+ act: 'install',
158
+ why: steps.map((s) => s.why).filter((w, i, all) => all.indexOf(w) === i).join('; '),
159
+ steps: steps.map((s) => s.run),
160
+ commands: steps.filter((s) => !s.text).map((s) => s.run),
161
+ verify,
162
+ } : null);
163
+
164
+ // The read: what connecting `id` takes here. Runs nothing, writes nothing.
165
+ export function connectPlan(id, { items = null, has = onPath, detectRoot = process.cwd(), productRoot = null, platform = process.platform } = {}) {
166
+ const tool = byId(id);
167
+ if (!tool) return { error: `${id} is not in the toolbox`, ids: tools().map((t) => t.id) };
168
+ const found = items ?? detectInstalled(detectRoot).items;
169
+ const status = toolStatus(tool, found, { has });
170
+ const recipe = (RECIPES[tool.id] ?? []).map((s) => (s.who === 'agent' ? { ...s, run: forPlatform(s.run, platform) } : s));
171
+ // Already here: nothing to install, only the record.
172
+ const here = status.state === 'installed' || status.state === 'available';
173
+ const steps = here ? [] : recipe;
174
+ const file = recordFile(tool);
175
+ const now = currentConnection(productRoot, tool);
176
+ // Compared without case: a hand-written `Figma` is still Figma.
177
+ const replaces = now.tool && now.tool.toLowerCase() !== tool.id ? now.tool : null;
178
+ const verify = `yad toolbox connect ${tool.id} --verify${replaces ? ' --replace' : ''} --json`;
179
+ return {
180
+ tool: tool.id, name: tool.name, state: status.state, found: status.found,
181
+ steps: steps.map((s) => ({ who: s.who, run: s.run, ...(s.scope ? { scope: s.scope } : {}), ...(s.why ? { why: s.why } : {}), ...(s.text ? { text: true } : {}) })),
182
+ ask: askText(tool, steps, { found: here, file, replaces, productRoot }),
183
+ record: productRoot ? [file] : [],
184
+ replaces,
185
+ ...(now.error ? { recordProblem: now.error } : {}),
186
+ person: personBlock(steps.filter((s) => s.who === 'person'), verify),
187
+ manual: tool.manual,
188
+ verify,
189
+ };
190
+ }
191
+
192
+ export function runToolboxConnect(detectRoot, productRoot, { id, verify = false, replace = false, json = false, items = null, has = onPath, platform = process.platform, today = new Date().toISOString().slice(0, 10) } = {}) {
193
+ if (!id) return refuse('yad toolbox connect needs a tool id', 'usage: yad toolbox connect <id> [--verify] [--json]', { json });
194
+ const plan = connectPlan(id, { items, has, detectRoot, productRoot, platform });
195
+ if (plan.error) return refuse(plan.error, `the tools: ${plan.ids.join(', ')}`, { json });
196
+ if (!verify) {
197
+ if (json) return emitJSON({ ok: true, ...plan });
198
+ info(`${plan.name}: ${plan.state === 'installed' || plan.state === 'available' ? 'found here' : 'not found here'}`);
199
+ for (const s of plan.steps) info(`${s.who === 'agent' ? 'agent runs' : 'you run'}: ${clean(s.run)}${s.why ? ` — ${s.why}` : ''}`);
200
+ hand(plan.ask);
201
+ hand(`then: ${plan.verify}`);
202
+ return plan;
203
+ }
204
+ return verifyAndRecord(productRoot, plan, { json, today, replace });
205
+ }
206
+
207
+ // `--verify`: found here → record the choice; not found → say what is left, and record nothing. Every check runs
208
+ // before the first write, so a refusal leaves every file as it was.
209
+ function verifyAndRecord(productRoot, plan, { json, today, replace }) {
210
+ const found = plan.state === 'installed' || plan.state === 'available';
211
+ if (!found) {
212
+ const left = plan.steps.length ? plan.steps.map((s) => s.run) : [plan.manual].filter(Boolean);
213
+ return refuse(`${plan.name} is not found here yet, so nothing was recorded`,
214
+ left.length ? `still to do: ${left.join('; then ')}` : 'install it, then run this again',
215
+ { json, person: plan.person ?? { act: 'install', why: 'it is not found on this machine yet', steps: left, commands: [], verify: plan.verify } });
216
+ }
217
+ if (!productRoot) return refuse(`${plan.name} is found here, but there is no Product to record it in`, 'run it from the Product, or a repo it registers', { json });
218
+ if (plan.recordProblem) return refuse(plan.recordProblem, 'fix it or restore it from git first: writing over it would lose what it holds', { json });
219
+ const { error } = readToolboxFile(productRoot);
220
+ if (error) return refuse(`${PROJECT_FILES.toolboxConfig} ${error}`, 'fix it (or restore it from git) first — writing over it would delete every choice it holds', { json });
221
+ // Replacing the team's tool is said in the question; only with that yes (--replace) is the file changed.
222
+ if (plan.replaces && !replace) {
223
+ return refuse(`${plan.name} would replace ${nameOf(plan.replaces)} as this team's choice in ${plan.record[0]}, so nothing was recorded`,
224
+ `ask the person first (the \`ask\` of \`yad toolbox connect ${plan.tool} --json\` says it), then run \`yad toolbox connect ${plan.tool} --verify --replace --json\``, { json });
225
+ }
226
+ const tool = byId(plan.tool);
227
+ const written = [];
228
+ const file = tool.tier === 'connector' ? connectorFile(tool) : null;
229
+ const recorded = currentConnection(productRoot, tool).tool;
230
+ if (file && (plan.replaces || !recorded)) {
231
+ const write = { [PROJECT_FILES.designConfig]: registerDesign, [PROJECT_FILES.testingConfig]: registerTesting, [PROJECT_FILES.learningConfig]: registerLearning }[file];
232
+ write(productRoot, { tool: tool.id, today });
233
+ written.push(file);
234
+ }
235
+ if (recordToolUse(productRoot, tool)) written.push(PROJECT_FILES.toolboxConfig);
236
+ const used = toolUse(tool, loadChoices(productRoot)).used;
237
+ const out = { ok: true, tool: tool.id, found: plan.found, used, written, ...(plan.replaces ? { replaced: plan.replaces } : {}) };
238
+ if (json) return emitJSON(out);
239
+ ok(`${plan.name} is found here${used ? ' and used by this team' : ''}${plan.replaces ? `, in place of ${nameOf(plan.replaces)}` : ''}`);
240
+ if (written.length) hand(`recorded in ${written.join(' and ')} — commit ${written.length > 1 ? 'them' : 'it'} with your next change, so the team shares the choice`);
241
+ else info('already recorded — nothing to change');
242
+ if (!used) warn(`${plan.name} is still not used here — a line in ${PROJECT_FILES.toolboxConfig} turns it off`);
243
+ return out;
244
+ }
package/cli/toolbox.mjs CHANGED
@@ -237,6 +237,29 @@ export const TOOLBOX = Object.freeze([
237
237
  note: 'The first gateway start pulls every server image and can outlast a client\'s 30-second timeout: warm it once with `docker mcp gateway run --profile <id> --dry-run`. A server\'s secrets (an access token) are set with `docker mcp secret set`, never in yad.',
238
238
  usedBy: [],
239
239
  },
240
+ {
241
+ // #321 (E168): a Unity code repo's editor, for yad-implement. Recommended, not a connector: it is set up in
242
+ // the Unity Editor of one repo, with no Product file, and yad-implement's "In a Unity repo" section says
243
+ // when to use it (a recommended tool has no generated "When a tool is missing" section).
244
+ id: 'unity-mcp', name: 'Unity MCP (MCP for Unity)', tier: 'recommended', role: 'drives the Unity Editor in a Unity code repo: compile errors, the console, tests',
245
+ licence: 'MIT', source: 'https://github.com/CoplayDev/unity-mcp', checked: '2026-11-08',
246
+ vetted: {
247
+ on: '2026-11-08', licenceFrom: 'https://github.com/CoplayDev/unity-mcp/blob/beta/LICENSE',
248
+ source: 'https://github.com/CoplayDev/unity-mcp', release: 'v10.3.0',
249
+ packages: [{ registry: 'pypi', name: 'mcpforunityserver', version: '10.3.0' }],
250
+ note: 'Formerly justinpbarnett/unity-mcp. The Unity package is added from the repository (Package Manager, a git URL pinned to the tag), not a registry; its Python server is the mcpforunityserver package, which the package itself sets up. It sends anonymous usage telemetry by default (tool names, timings, the Unity version, error text cut to 200–500 characters, with a random install ID): DISABLE_TELEMETRY=true, or its Editor setting, turns it off.',
251
+ },
252
+ // It is set up inside the Unity Editor: none of the four install types fits.
253
+ install: [],
254
+ manual: 'https://github.com/CoplayDev/unity-mcp#quickstart',
255
+ // Claude Code names it UnityMCP, other clients unityMCP: one name, matched whatever its case.
256
+ detect: { mcp: ['UnityMCP'] },
257
+ versions: null,
258
+ fallback: 'files only: yad-implement edits the C# and asks the person to open Unity and report its console errors',
259
+ records: 'Unity not reachable: console checked by <person>',
260
+ note: 'Needs Unity 2021.3 or newer, Python 3.10 or newer with uv, and the Unity Editor open on the repo while the agent works. Unity registers it for Claude Code for the Unity project folder only, so its tools load in an agent started there. Found by its server name only (yad never reads a server\'s settings).',
261
+ usedBy: ['yad-implement'],
262
+ },
240
263
 
241
264
  // ---- connectors: what a Product connects (skills/sdlc/config.yaml names the same adapters) -------
242
265
  {
@@ -260,7 +283,7 @@ export const TOOLBOX = Object.freeze([
260
283
  // `html-to-design` only writes (import-html) and cannot read a frame. Any other provider name — the
261
284
  // MCP id is free text — is probed, with the message that names both servers.
262
285
  reach: {
263
- app: 'Figma', writers: ['html-to-design'], appBound: ['figma-desktop'], signInOnly: ['figma'],
286
+ app: 'Figma', writers: ['html-to-design'], appBound: ['figma-desktop'], signInOnly: ['figma'], ownServer: ['figma-desktop'],
264
287
  probe: 'read frame <frame> through the Figma MCP (get_metadata, with that node ID)',
265
288
  open: 'Open the Figma desktop app with <file> loaded and its Dev Mode MCP server on, then continue',
266
289
  signIn: 'Sign in to Figma in your agent (its Figma MCP server), check that you can open <file>, then continue',
@@ -291,6 +314,55 @@ export const TOOLBOX = Object.freeze([
291
314
  },
292
315
  usedBy: ['yad-connect-design', 'yad-ui'],
293
316
  },
317
+ // E164: an open-source design editor — no account, no paid plan, and the design file lives in the repo
318
+ // (`epics/<epic>/design/`). Two ways in: its CLI works on the file with no app open (`openpencil eval <file>
319
+ // --write` runs Figma Plugin API code and saves), and yad-ui writes screens that way; its MCP server is a
320
+ // bridge to the running desktop app, used only when the app is open with the file. Beside Figma and Pencil,
321
+ // never in place of them: it reads local `.fig` copies only (never Figma's cloud), and opens `.pen` files
322
+ // only partly. Both packages are pinned to an exact version while it is before 1.0, and each bump is vetted
323
+ // again. OpenPencil's own node IDs are NOT stable: it numbers nodes in the order it loads them, so after a
324
+ // frame is deleted or added another frame can take an old ID (checked by hand on 0.16.0, E164 PR 2). So
325
+ // yad-ui stores yad's own ID on each frame (shared plugin data `yad`/`nodeId`) and records that, and every
326
+ // read finds the frame by it. `vetted.handCheck` is the CLI version scripts/openpencil-node-ids.mjs last
327
+ // passed on; moving the pin fails until it is run again.
328
+ {
329
+ id: 'openpencil', name: 'OpenPencil', tier: 'connector', role: 'design tool: yad-ui writes screens into a design file in the repo through its CLI, with no account and no app open',
330
+ licence: 'MIT', source: 'https://github.com/open-pencil/open-pencil', checked: '2026-11-05',
331
+ vetted: {
332
+ on: '2026-11-05', licenceFrom: 'https://github.com/open-pencil/open-pencil/blob/master/LICENSE',
333
+ source: 'https://github.com/open-pencil/open-pencil', release: 'v0.16.0',
334
+ packages: [
335
+ { registry: 'npm', name: '@open-pencil/mcp', version: '0.16.0' },
336
+ { registry: 'npm', name: '@open-pencil/cli', version: '0.16.0' },
337
+ ],
338
+ note: 'Before 1.0, and its own README says "active development … some rough edges": vet each version bump again.',
339
+ // OpenPencil's own node IDs move on reopen; yad's ID stored on each frame must not (E164 PR 2).
340
+ handCheck: { script: 'scripts/openpencil-node-ids.mjs', package: '@open-pencil/cli', version: '0.16.0' },
341
+ },
342
+ // One route: the MCP connection does nothing without the packages (a route is an alternative — E84).
343
+ install: [{ type: 'npm', command: 'npm install -g @open-pencil/mcp@0.16.0 @open-pencil/cli@0.16.0, then claude mcp add --scope user open-pencil -- openpencil-mcp' }],
344
+ // The desktop app is needed only for the MCP path; the CLI path needs nothing else.
345
+ manual: 'https://openpencil.dev',
346
+ // The CLI is the way yad-ui writes, so the program alone counts; the MCP server is found too.
347
+ detect: { bins: ['openpencil'], mcp: ['open-pencil'] },
348
+ versions: null,
349
+ fallback: 'markdown-only: yad-ui writes ui-design.md and DESIGN.md only',
350
+ records: null,
351
+ note: 'The CLI (openpencil) works on the file with no app open. The MCP server only forwards to the running desktop app, and reads and writes only files inside OPENPENCIL_MCP_ROOT (the folder it starts in by default; the home folder on Windows). It opens local .fig copies, never Figma\'s cloud, and a round trip may lose detail; .pen support is partial.',
352
+ // #358 + E164: the CLI (`openpencil-cli`) works on the design file in the Product with no app and no
353
+ // sign-in; the MCP server (`openpencil-mcp`) is a bridge to the running desktop app. Both find a frame by
354
+ // the ID yad stored on it, never by OpenPencil's own node ID, which changes when the file is reopened.
355
+ reach: {
356
+ app: 'OpenPencil', appBound: ['openpencil-mcp'], local: ['openpencil-cli'],
357
+ probe: 'find frame <frame> in <file> through the OpenPencil MCP: its eval tool, looking for the node whose shared plugin data `yad`/`nodeId` is <frame> (figma.root.findAll with getSharedPluginData)',
358
+ open: 'Open the OpenPencil desktop app with <file> loaded (the file must be inside OPENPENCIL_MCP_ROOT), then continue',
359
+ localProbe: 'check that <file> is in the Product checkout and that `openpencil --version` runs, then find frame <frame> with `openpencil eval` on that file: the node whose shared plugin data `yad`/`nodeId` is <frame> (figma.root.findAll with getSharedPluginData)',
360
+ localStop: 'Pull the Product so that <file> is there with frame <frame> in it, and make sure `openpencil` runs in your terminal, then continue',
361
+ either: 'Make sure <file> is in your Product checkout and `openpencil` runs in your terminal (the CLI), or open the OpenPencil desktop app with <file> loaded (its MCP server), then continue',
362
+ eitherProbe: 'try the CLI first: if `openpencil --version` runs and <file> is in the Product checkout, find frame <frame> with `openpencil eval` on that file; if that does not find it, find frame <frame> through the OpenPencil MCP\'s eval tool (the desktop app open with <file>) — either way, the node whose shared plugin data `yad`/`nodeId` is <frame> (figma.root.findAll with getSharedPluginData). It fails only when neither finds it',
363
+ },
364
+ usedBy: ['yad-connect-design', 'yad-ui'],
365
+ },
294
366
  {
295
367
  id: 'playwright', name: 'Playwright MCP', tier: 'connector', role: 'testing tool: generates and runs browser and API tests',
296
368
  licence: 'Apache-2.0', source: 'https://github.com/microsoft/playwright-mcp', checked: CHECKED,
@@ -425,8 +497,13 @@ export function toolProblems(t) {
425
497
  need(t?.tier !== 'connector' || !isStringList(t?.usedBy) || connectorFile(t) !== null, 'a connector names the yad-connect-* skill that connects it');
426
498
  // #358 reach: `appBound` is `true` (every provider) or a list of providers; `writers` (optional) lists the
427
499
  // providers that cannot read a frame. Provider names are compared in lower case. A tool whose
428
- // providers need no app writes `appBound: []`; then `signIn` (a provider in `signInOnly`) and `either`
429
- // (a provider in neither list, so yad cannot tell) say what to do instead.
500
+ // providers need no app writes `appBound: []`; then `either` says what to do when the provider is in no
501
+ // list, so yad cannot tell. Two more kinds of provider need no app: `signInOnly` (a hosted server — the
502
+ // person signs in, said by `signIn`) and, E164, `local` (a CLI that works on the design file on disk —
503
+ // no app and no sign-in: `localProbe` and `localStop` replace `probe` and the stop text). `ownServer`
504
+ // (optional) lists the providers that are an app's own server, which the tool's recipe does not install,
505
+ // so the preflight offers no connect step for them (E165). `eitherProbe` (optional) replaces `probe` when
506
+ // yad cannot tell the provider, so the check tries every way the `either` text names.
430
507
  const r = t?.reach;
431
508
  if (r !== undefined) {
432
509
  const text = (v) => typeof v === 'string' && v.length > 0;
@@ -434,7 +511,15 @@ export function toolProblems(t) {
434
511
  need(r?.writers === undefined || isStringList(r?.writers), 'reach.writers is absent or the providers that cannot read a frame');
435
512
  need(r?.appBound === true || isStringList(r?.appBound), 'reach.appBound is true, or the providers read through the app');
436
513
  need(r?.signInOnly === undefined || isStringList(r?.signInOnly), 'reach.signInOnly is absent or a list of providers');
437
- need(r?.appBound === true || (text(r?.signIn) && text(r?.either)), 'reach.signIn and reach.either say what to do when the provider needs no app, or yad cannot tell');
514
+ need(r?.signInOnly === undefined || text(r?.signIn), 'reach.signIn says what to do for a provider in signInOnly');
515
+ need(r?.local === undefined || isStringList(r?.local), 'reach.local is absent or a list of providers');
516
+ need(r?.local === undefined || (text(r?.localProbe) && text(r?.localStop)), 'reach.localProbe and reach.localStop say how to check a provider in local, and what to do when that fails');
517
+ need(r?.ownServer === undefined || isStringList(r?.ownServer), 'reach.ownServer is absent or a list of providers');
518
+ need(r?.eitherProbe === undefined || text(r?.eitherProbe), 'reach.eitherProbe is absent or how to check when yad cannot tell the provider');
519
+ // Names folded the way the preflight compares them (letters and digits only).
520
+ const fold = (p) => String(p).toLowerCase().replace(/[^a-z0-9]/g, '');
521
+ need(!isStringList(r?.local) || !isStringList(r?.appBound) || !r.local.some((p) => r.appBound.map(fold).includes(fold(p))), 'a provider is in reach.local or reach.appBound, not both');
522
+ need(r?.appBound === true || text(r?.either), 'reach.either says what to do when yad cannot tell whether the provider needs the app');
438
523
  }
439
524
  return out;
440
525
  }
@@ -458,6 +543,16 @@ export function vettingProblems(t) {
458
543
  need(parseVersion(p?.version)?.full === true, 'a vetted package has the full version that was vetted (1.2.3)');
459
544
  }
460
545
  need(v.note === null || (typeof v.note === 'string' && v.note.length > 0), 'vetted.note is null or a sentence');
546
+ // E164: a check run by hand on one package's pinned version (OpenPencil's node IDs). It names the script,
547
+ // the package and the version it last passed on; moving that package's pin without running it again fails
548
+ // here, in the unit suite and the release check, never by itself on a quiet main.
549
+ if (v.handCheck !== undefined) {
550
+ const h = v.handCheck;
551
+ const pkg = Array.isArray(v.packages) ? v.packages.find((p) => p?.name === h?.package) : undefined;
552
+ need(h && typeof h === 'object' && typeof h.script === 'string' && /^scripts\/[\w.-]+\.mjs$/.test(h.script) && pkg !== undefined,
553
+ 'vetted.handCheck names its script (scripts/<name>.mjs) and one of vetted.packages');
554
+ if (pkg) need(h.version === pkg.version, `run ${h.script} again: it last passed on ${h.package}@${h.version}, and the pinned version is ${pkg.version} — then set vetted.handCheck.version`);
555
+ }
461
556
  // A closed tool has no LICENSE file to read, so its proof must be the vendor's terms, not a repo file.
462
557
  need(t.licence !== 'proprietary' || !isRepoLicenceFile(v.licenceFrom), 'a proprietary tool\'s licence proof is its terms page');
463
558
  return out;
@@ -845,7 +940,13 @@ export function skillFallbackSection(skill, tools = TOOLBOX) {
845
940
  '',
846
941
  );
847
942
  }
848
- lines.push('Tell the person which tools you used and which fallbacks, and why.', '');
943
+ lines.push(
944
+ // E165: one offer before a fallback, for a tool the team uses that this machine lacks.
945
+ 'Before you fall back because a tool the team uses is not on this machine (not turned off, not removed',
946
+ 'by the team), offer to connect it, once: run `yad toolbox connect <id> --json` and follow the',
947
+ 'connect-tool rule. On a no, or when a step fails, use the fallback.',
948
+ '',
949
+ 'Tell the person which tools you used and which fallbacks, and why.', '');
849
950
  for (const t of core) {
850
951
  lines.push(`- **${t.name}** (\`${t.id}\`). Use it when its entry has \`used: true\` and \`status.state\` is \`installed\` or \`available\`. Otherwise — not found, its plugin turned off in Claude Code, or the team chose not to use it (\`yad toolbox remove ${t.id}\`) — use the fallback.`);
851
952
  lines.push(` - Fallback — ${t.fallback}.`);
@@ -1086,7 +1187,12 @@ export function toolboxCheck(root, productRoot, opts = {}) {
1086
1187
  const s = r.status;
1087
1188
  const problem = s.state === 'missing' ? 'missing' : s.state === 'disabled' ? 'disabled' : s.inRange === false ? 'out-of-range' : null;
1088
1189
  if (!problem) return [];
1089
- return [{ id: r.id, name: r.name, tier: r.tier, problem, version: s.version, versions: r.versions, install: r.install, manual: r.manual, source: r.source, fallback: r.fallback }];
1190
+ // E165: the command an agent reads to connect it, after one yes — for a shipped tool (each has a recipe)
1191
+ // that is missing. Not for a plugin that is turned off (the person turns it on), nor a team's own tool (yad
1192
+ // has no recipe for it), nor one found outside its range: connecting finds it already here, and --verify
1193
+ // does not check a version (no shipped tool has a range yet).
1194
+ const connect = problem === 'missing' && r.tier !== 'project' && TOOLBOX.some((t) => t.id === r.id) ? `yad toolbox connect ${r.id} --json` : null;
1195
+ return [{ id: r.id, name: r.name, tier: r.tier, problem, version: s.version, versions: r.versions, install: r.install, manual: r.manual, source: r.source, fallback: r.fallback, connect }];
1090
1196
  });
1091
1197
  return { used, findings, problems };
1092
1198
  }
@@ -1139,9 +1245,11 @@ export function offerToolbox(root, productRoot, { canRemove = true, ...opts } =
1139
1245
  for (const p of res.problems) warn(p);
1140
1246
  for (const line of toolboxCheckLines(res)) log(line);
1141
1247
  if (res.findings.length) {
1142
- info(canRemove
1143
- ? 'nothing is installed for you: follow the steps you choose, or, for the whole team, stop using a tool with `yad toolbox remove <id>`'
1144
- : 'nothing is installed for you: follow the steps you choose');
1248
+ // E165: nothing is installed without a yes — but the agent can connect a shipped tool after one.
1249
+ const viaAgent = res.findings.some((f) => f.connect)
1250
+ ? 'nothing is installed without asking: follow the steps you choose, or ask your agent to connect a tool with `yad toolbox connect <id>` (it asks you once first)'
1251
+ : 'nothing is installed for you: follow the steps you choose';
1252
+ info(canRemove ? `${viaAgent}; or, for the whole team, stop using a tool with \`yad toolbox remove <id>\`` : viaAgent);
1145
1253
  }
1146
1254
  return { used: res.used.map((r) => r.id), findings: res.findings, problems: res.problems };
1147
1255
  }
@@ -1187,6 +1295,18 @@ function setShipped(doc, tool, want, connected) {
1187
1295
  }
1188
1296
  const sameJSON = (a, b) => JSON.stringify(a ?? {}) === JSON.stringify(b ?? {});
1189
1297
 
1298
+ // E165: mark a shipped tool as used, quietly, for `yad toolbox connect --verify` (the person's one yes already
1299
+ // covered it). The same write `yad toolbox add <id>` makes for a shipped tool; true when the file changed. The
1300
+ // caller has checked that the file reads. Custom entries are left alone.
1301
+ export function recordToolUse(productRoot, tool) {
1302
+ const { doc, error } = readToolboxFile(productRoot);
1303
+ if (error) return false;
1304
+ const shipped = setShipped(doc, tool, 'use', connectedTools(productRoot));
1305
+ if (sameJSON(shipped, doc.shipped)) return false;
1306
+ save(productRoot, doc, shipped, Array.isArray(doc.custom) ? doc.custom : []);
1307
+ return true;
1308
+ }
1309
+
1190
1310
  // Where the file is, for an answer: the Product as a path from here, since run from a code repo nothing
1191
1311
  // else on stdout names it. Both sides as the disk has them: `process.cwd()` is already resolved, and a
1192
1312
  // Product reached through a link (macOS's /var is /private/var) would otherwise climb to the top and back.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "yadflow",
3
- "version": "4.9.0",
3
+ "version": "4.10.0",
4
4
  "description": "Shared project memory and workflows for teams building with AI: a versioned record of plans, decisions, contracts and reviews across repos, human-approved review gates, and a zero-dependency `yad` CLI plus 39 skills for your AI assistant.",
5
5
  "type": "module",
6
6
  "author": "AbdelRahman Nasr",
@@ -28,6 +28,10 @@
28
28
  "!cli/test-detect.mjs",
29
29
  "!cli/test-members.mjs",
30
30
  "!cli/test-standup.mjs",
31
+ "!cli/test-issues.mjs",
32
+ "!cli/test-issues-write.mjs",
33
+ "!cli/test-scan.mjs",
34
+ "!cli/test-issues-act.mjs",
31
35
  "!cli/test-lifecycle.mjs",
32
36
  "!cli/test-fuzz.js",
33
37
  "!cli/fixtures",
@@ -46,12 +50,12 @@
46
50
  "scripts": {
47
51
  "yad": "node bin/yad.mjs",
48
52
  "lint": "eslint cli bin",
49
- "test": "node --test cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-machine.mjs cli/test-story-frames.mjs cli/test-preview.mjs cli/test-fuzz.js",
53
+ "test": "node --test cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-issues.mjs cli/test-issues-write.mjs cli/test-scan.mjs cli/test-issues-act.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-machine.mjs cli/test-story-frames.mjs cli/test-preview.mjs cli/test-fuzz.js",
50
54
  "test:e2e": "bash test/e2e/run.sh",
51
55
  "test:agents": "bash test/agent-acceptance/run.sh",
52
56
  "test:agents:selftest": "bash test/agent-acceptance/run.sh selftest",
53
57
  "release-check": "bash scripts/release-check.sh",
54
- "coverage": "node --test --test-reporter=tap --experimental-test-coverage --test-coverage-exclude='cli/test*.mjs' --test-coverage-exclude='cli/test*.js' --test-coverage-lines=70 --test-coverage-branches=70 cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-machine.mjs cli/test-story-frames.mjs cli/test-preview.mjs cli/test-fuzz.js",
58
+ "coverage": "node --test --test-reporter=tap --experimental-test-coverage --test-coverage-exclude='cli/test*.mjs' --test-coverage-exclude='cli/test*.js' --test-coverage-lines=70 --test-coverage-branches=70 cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-issues.mjs cli/test-issues-write.mjs cli/test-scan.mjs cli/test-issues-act.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-machine.mjs cli/test-story-frames.mjs cli/test-preview.mjs cli/test-fuzz.js",
55
59
  "diagrams": "npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/sdlc-overview.mmd -o docs/diagrams/sdlc-overview.svg -b transparent && npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/review-loop.mmd -o docs/diagrams/review-loop.svg -b transparent && npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/work-and-memory.mmd -o docs/diagrams/work-and-memory.svg -b transparent && npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/feature-evolution.mmd -o docs/diagrams/feature-evolution.svg -b transparent",
56
60
  "prepublishOnly": "npm test"
57
61
  },