yadflow 4.2.0 → 4.3.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [4.3.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.2.0...v4.3.0) (2026-10-01)
+
+
+### Bug Fixes
+
+* **toolbox:** E85 review 1 — hint order, the folder check looks in, team-wide remove advice ([c7f6592](https://github.com/abdelrahmannasr/yadflow/commit/c7f65922cdad49e9816c4cbe81190283392c1df6))
+* **toolbox:** E85 review 2 — look for tools at the top of the repo, read --dir's Product ([82fb5ed](https://github.com/abdelrahmannasr/yadflow/commit/82fb5ed6a1afcf364a9844d3faf2676bd4a84274))
+* **toolbox:** E85 review 3 — a worktree is its own checkout; look at the deepest top ([4926799](https://github.com/abdelrahmannasr/yadflow/commit/4926799f6db758c7abb59029bd8e71923550c227))
+* **toolbox:** E85 review 4 — find the checkout top under both spellings of a linked folder ([9728384](https://github.com/abdelrahmannasr/yadflow/commit/9728384c140178d55608d2ab2b67037a2f80140d))
+
+
+### Features
+
+* **toolbox:** offer the missing tools in setup, check, update and join (E85) ([53e06c6](https://github.com/abdelrahmannasr/yadflow/commit/53e06c6da8bf585ced68435b052d01ba4ca5e6fa))
+
 # [4.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.1.0...v4.2.0) (2026-10-01)
 
 

package/README.md

@@ -257,7 +257,7 @@ The record is worth trusting because people approve what goes into it.
 - linked changes and `yad thread`
 - `yad history`, `yad next` and `yad usage`
 - `yad detect`, which lists the skills, agents, MCP servers and plugins installed for each AI agent
-- `yad toolbox list`, which shows the external tools yadflow can use, which ones you have, and what happens without each; `yad toolbox add` / `remove` record the tools your team uses, and `yad toolbox check` lists the ones not ready on your machine
+- `yad toolbox list`, which shows the external tools yadflow can use, which ones you have, and what happens without each; `yad toolbox add` / `remove` record the tools your team uses, and `yad toolbox check` lists the ones not ready on your machine (`yad setup`, `check`, `update` and `join` print the same list, and never install anything)
 - draft saving, claims and owners
 - the CI checks
 - the Review Companion

package/bin/commands.mjs

@@ -12,7 +12,7 @@
 
 export { runSetup } from '../cli/setup.mjs';
 export { runNew, runInit, runJoin } from '../cli/workspace.mjs';
-export { findProduct, hasProduct, workspaceProduct, registryEntryFor, WORKSPACE_FILE } from '../cli/find-product.mjs';
+export { findProduct, hasProduct, workspaceProduct, registryEntryFor, toolsFolder, WORKSPACE_FILE } from '../cli/find-product.mjs';
 export { reconcile } from '../cli/reconcile.mjs';
 export { gateOpen, gateSync, gateComments, gateStatus, gateCi, gateReview, gateTrailer, gateWalkthrough, gateRepair } from '../cli/gate.mjs';
 export { gateApprove, gateComment, gateAdvance } from '../cli/gate-local.mjs';

package/bin/yad.mjs

@@ -24,7 +24,8 @@ ${c.bold('Start a workspace')} ${c.dim('(the folder holding product/ and the cod
                        Never commits, pushes, or changes a shared file
 
 ${c.bold('Setup & maintenance')}
-  yad setup            Guided first-run setup (profile interview, install, connect & wire repos)
+  yad setup            Guided first-run setup (profile interview, install, connect & wire repos,
+                       then the tools this project uses that are missing — offered, never installed)
                        profile flags: --solo | --team <n>, --greenfield | --brownfield,
                        --monorepo | --separate, --tools (configure design/testing/learning now)
   yad check            Report what is missing / drifted / modified / stale / legacy (read-only)
@@ -539,8 +540,12 @@ async function main() {
   // registers (through `.yad-workspace.json`) — and says where, on stderr. A code-repo command keeps acting
   // on the repo it runs in, and is handed the Product to read (its registry: name, platform, branch).
   const dirGiven = process.argv.slice(2).some((a) => a === '--dir' || a.startsWith('--dir='));
+  // E85: where `check` and `update` look for tools, and whose choices they read — worked out from the
+  // folder the person ran yad in (or named), before a Product command moves `o.dir` to the Product.
+  let toolboxAt = null;
   if (PRODUCT_CMDS.has(cmd) || REPO_CMDS.has(cmd)) {
     const found = commands.findProduct(dirGiven ? o.dir : shellCwd());
+    toolboxAt = { from: commands.toolsFolder(found, dirGiven ? o.dir : shellCwd()), product: found?.root ?? null };
     const shown = (p) => path.relative(process.cwd(), p) || '.';
     if (found?.problem) warn(`${found.problem} — using ${o.dir}`);
     else if (found?.elsewhere) {
@@ -625,11 +630,11 @@ async function main() {
     }
     case 'check':
       if (noProduct()) break;
-      result = await commands.reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today });
+      result = await commands.reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today, toolbox: toolboxAt });
       break;
     case 'update':
       if (noProduct()) break;
-      result = await commands.reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today });
+      result = await commands.reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today, toolbox: toolboxAt });
       break;
     case 'doctor':
       result = await commands.runDoctor(o.dir, { json: o.json });
@@ -655,7 +660,7 @@ async function main() {
         else if (found?.elsewhere) warn(`this folder is not in a repo the Product registers — the Product is ${rel(found.elsewhere)}: cd there, or pass --dir ${rel(found.elsewhere)}`);
         const productRoot = found?.root ?? null;
         const run = action === 'list' ? commands.runToolboxList : commands.runToolboxCheck;
-        result = run(o.dir || process.cwd(), { json: o.json, productRoot });
+        result = run(commands.toolsFolder(found, o.dir || process.cwd()), { json: o.json, productRoot });
         break;
       }
       if (extra) { refuse(`yad toolbox ${action} takes one tool id (got also: ${extra})`, usage); break; }

package/cli/find-product.mjs

@@ -181,6 +181,30 @@ export function gitTopOf(dir) {
   }
 }
 
+// Where `yad toolbox` and the toolbox section of `check` / `update` look for tools (E85), given
+// `findProduct(from)`'s answer. Finding reads `<folder>/.claude/…` and never walks up, so a subfolder
+// must be lifted to the top of what the person is working in. That is the DEEPEST of these that holds
+// `from`: the git checkout it is in (a worktree inside `api/` is its own checkout, on its own branch — never
+// swapped for api's, as in E80 review 3), the registered repo holding it (`apps/web` in a monorepo is not
+// a checkout of its own), and the Product found from it. A checkout ABOVE the Product (a Product that is
+// not a git repo, inside one that is not ours) is never deeper than the Product, so it never wins. Reads
+// only whether `.git` exists; runs nothing.
+export function toolsFolder(found, from) {
+  const at = real(from);
+  if (!at) return from;
+  // Both spellings: the shell's (through a link) and the one on disk, so `check` (given the shell's
+  // folder) and `yad toolbox check` (given the process's) look in the same place (E85 review 4).
+  const candidates = [gitTopOf(from), gitTopOf(at)];
+  if (found?.root && found.repo && typeof found.repo.path === 'string') candidates.push(path.resolve(found.root, found.repo.path));
+  if (found?.root && (found.via === 'here' || found.via === 'above')) candidates.push(found.root);
+  let best = null;
+  for (const c of candidates) {
+    const cAt = c && real(c);
+    if (cAt && within(at, cAt) && (!best || cAt.length > best.length)) best = cAt;
+  }
+  return best ?? from;
+}
+
 // The registry entry for the code repo a code-repo command runs in (E80), with the folder to work in.
 // It is the CHECKOUT that must be the registered repo — not merely a folder inside it: a worktree or a
 // repo nested in `backend/` is another checkout, on another branch, and must never be swapped for

package/cli/reconcile.mjs

@@ -19,6 +19,7 @@ import {
 import { gitHead, packRepo } from './setup.mjs';
 import { groupByRoot, commitUpdates, repoLabel } from './update-commit.mjs';
 import { hasSiblingRepo, workspaceFileState, writeWorkspaceFile, WORKSPACE_FILE } from './find-product.mjs';
+import { offerToolbox } from './toolbox.mjs';
 
 const MARK = { missing: c.red('missing'), new: c.cyan('new'), outdated: c.yellow('outdated'), modified: c.cyan('modified'), stale: c.yellow('stale'), legacy: c.yellow('legacy'), removed: c.yellow('removed'), ok: c.green('ok') };
 
@@ -30,7 +31,7 @@ const repoShown = (repo) => `product (the code repo at ${forTerminal(repo.path)}
 const shown = (a) => a.shownScope ?? a.scope;
 const itemsOf = (actions) => actions.map((a) => ({ scope: a.scope, item: a.item, status: a.status, product: !a.fromRepo }));
 
-export async function reconcile(root, { fix = false, scope = 'all', force = false, push = false, allowBranch = false, overwriteLocal = false } = {}) {
+export async function reconcile(root, { fix = false, scope = 'all', force = false, push = false, allowBranch = false, overwriteLocal = false, toolbox: toolboxAt = null } = {}) {
   log(c.bold(`\nSDLC reconcile  ${c.dim('v' + VERSION)}`));
   log(c.dim(`target: ${root}\n`));
 
@@ -239,7 +240,9 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
     if (workspaceFile === 'missing') info(`no ${WORKSPACE_FILE} beside the Product — \`yad check --fix\` writes it, so yad finds the Product from its code repos`);
     if (push) warn('--push has no effect without --fix (there is nothing applied to commit).');
     if (fixable.length || gaps.length) hand('run `yad check --fix` to reconcile (or `yad setup` for missing one-time setup).');
-    return { fix: false, counts, gaps, items: itemsOf(actions), applied: 0, modified: modified.length, commits: [], workspaceFile };
+    // After the --fix hint, never above it: --fix installs no tool, and must not read as if it did.
+    const toolbox = toolboxSection(root, toolboxAt);
+    return { fix: false, counts, gaps, items: itemsOf(actions), applied: 0, modified: modified.length, commits: [], workspaceFile, toolbox };
   }
 
   // --- apply --- (collect the applied actions so --push can stage each repo's exact allowlist) ---
@@ -314,5 +317,18 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
       },
     });
   }
-  return { fix: true, counts, gaps, items: itemsOf(actions), applied, modified: modified.length, commits, workspaceFile };
+  const toolbox = toolboxSection(root, toolboxAt);
+  return { fix: true, counts, gaps, items: itemsOf(actions), applied, modified: modified.length, commits, workspaceFile, toolbox };
+}
+
+// E85: `yad check` and `yad update` end with the toolbox check — the tools this Product uses that are not
+// here. Report only: it never adds to what `--fix` applies, never changes the exit code, and installs
+// nothing. Both verbs, because both run here and a release can add a core tool. `at` comes from the
+// command line: `from`, the top of the repo the person ran yad in, where tools are looked for (as
+// `yad toolbox check` does — a code repo's own skills count); `product`, the Product whose choices are
+// read, which is not `root` under `--dir <a code repo>`.
+function toolboxSection(root, at) {
+  log('');
+  log(c.bold('Toolbox'));
+  return offerToolbox(at?.from || root, at?.product || root);
 }

package/cli/setup.mjs

@@ -16,6 +16,7 @@ import {
 import { modeFields, modeOf } from './mode.mjs';
 import { recordActor } from './skip.mjs';
 import { loadSkillBindings, stepSkills } from './epic-state.mjs';
+import { offerToolbox } from './toolbox.mjs';
 
 // Parse a comma/space separated list into a clean, deduped array of trimmed tokens.
 export function parseList(s) {
@@ -322,8 +323,9 @@ export async function runSetup(root, opts = {}) {
 
   // 0. Profile interview — branch the wizard to the user's situation (solo/team, code, repo layout).
   const { solo, team_size, codebase, repo_layout, configureTools } = await resolveProfile(root, opts);
-  // Steps: interview, preflight, install, Product, tools (1 if deferred else 3), repos, wire, coderabbit, done.
-  const total = 8 + (configureTools ? 3 : 1);
+  // Steps: interview, preflight, install, Product, tools (1 if deferred else 3), repos, wire, coderabbit,
+  // toolbox, done.
+  const total = 9 + (configureTools ? 3 : 1);
   let _n = 0;
   const S = (title) => step(++_n, total, title);
 
@@ -672,6 +674,13 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
+  // E85: the external tools this project uses that are not here, and how to get each. AFTER the tools
+  // step, so a connector chosen there counts as in use. It offers and never installs: nothing is run and
+  // no file is written, and a missing tool never fails setup (each has a fallback).
+  S('Toolbox (external tools this project uses)');
+  guide(['Each tool is optional and has a fallback. yad installs nothing: it prints how to get each one, and you choose.']);
+  const toolbox = offerToolbox(root, root);
+
   // Summary + version stamp
   S('Done');
   writeJSON(path.join(root, PROJECT_FILES.version), { version: VERSION, ideTargets, updatedAt: opts.today ?? null });
@@ -713,7 +722,7 @@ export async function runSetup(root, opts = {}) {
   // step has written, so a scripted setup passes every flag (or SDLC_NONINTERACTIVE for the defaults).
   return {
     profile: { solo, team_size, codebase, repo_layout }, ideTargets,
-    repos: registry.repos.map((r) => r.name ?? null), next: epicSkill,
+    repos: registry.repos.map((r) => r.name ?? null), next: epicSkill, toolbox,
   };
 }
 

package/cli/toolbox.mjs

@@ -604,30 +604,61 @@ export function toolboxCheck(root, productRoot, opts = {}) {
   return { used, findings, problems };
 }
 
-// NEVER FAILS (decided with the row): no tool is required, so a missing one is news, not an error. Exit 0.
-export function runToolboxCheck(root, { json = false, productRoot = null, ...opts } = {}) {
-  const { used, findings, problems } = toolboxCheck(root, productRoot, opts);
-  if (json) return emitJSON({ ok: true, ...(productRoot ? where(productRoot) : { product: null, file: null }), used: used.map((r) => r.id), findings, problems });
-  for (const p of problems) warn(p);
-  if (!findings.length) {
-    ok(`all ${used.length} tool(s) this project uses are here: ${used.map((r) => clean(r.name)).join(', ')}`);
-    return undefined;
-  }
-  log(c.bold(`${findings.length} of the ${used.length} tool(s) this project uses ${findings.length === 1 ? 'is' : 'are'} not ready here. None is required.`));
+// The lines a check prints, from `toolboxCheck`'s answer, without the closing hint. One printer for
+// `yad toolbox check` and for the toolbox step of setup, update, check and join (E85), so they cannot
+// say it differently.
+export function toolboxCheckLines({ used, findings }) {
+  if (!used.length) return [`  ${c.dim('•')} this project uses no tool from the toolbox — \`yad toolbox list\` shows them all`];
+  if (!findings.length) return [`  ${c.green('✓')} all ${used.length} tool(s) this project uses are here: ${used.map((r) => clean(r.name)).join(', ')}`];
+  const lines = [c.bold(`${findings.length} of the ${used.length} tool(s) this project uses ${findings.length === 1 ? 'is' : 'are'} not ready here. None is required.`)];
   for (const f of findings) {
     const r = used.find((u) => u.id === f.id);
     const what = f.problem === 'missing' ? 'not found'
       : f.problem === 'disabled' ? 'installed, but its plugin is turned off in your Claude Code settings'
         : `version ${clean(f.version)} is outside the known-good range ${f.versions} — still used`;
-    log(`  ${f.problem === 'out-of-range' ? c.yellow('!') : c.dim('–')} ${c.bold(clean(f.name))}: ${what}`);
-    if (f.problem === 'disabled') log(`      ${c.dim('turn it on with /plugin in Claude Code')}`);
-    else for (const line of howToGet(r)) log(`      ${c.dim(line)}`);
-    if (f.problem !== 'out-of-range') log(`      ${c.dim(`without it: ${clean(f.fallback)}`)}`);
+    lines.push(`  ${f.problem === 'out-of-range' ? c.yellow('!') : c.dim('–')} ${c.bold(clean(f.name))}: ${what}`);
+    if (f.problem === 'disabled') lines.push(`      ${c.dim('turn it on with /plugin in Claude Code')}`);
+    else for (const line of howToGet(r)) lines.push(`      ${c.dim(line)}`);
+    if (f.problem !== 'out-of-range') lines.push(`      ${c.dim(`without it: ${clean(f.fallback)}`)}`);
   }
-  info(productRoot ? 'stop using a tool here with `yad toolbox remove <id>`' : 'no Product here, so this checks the core tools only');
+  return lines;
+}
+
+// NEVER FAILS (decided with the row): no tool is required, so a missing one is news, not an error. Exit 0.
+export function runToolboxCheck(root, { json = false, productRoot = null, ...opts } = {}) {
+  const res = toolboxCheck(root, productRoot, opts);
+  const { used, findings, problems } = res;
+  if (json) return emitJSON({ ok: true, ...(productRoot ? where(productRoot) : { product: null, file: null }), used: used.map((r) => r.id), findings, problems });
+  for (const p of problems) warn(p);
+  for (const line of toolboxCheckLines(res)) log(line);
+  if (findings.length) info(productRoot ? 'stop using a tool, for the whole team, with `yad toolbox remove <id>`' : 'no Product here, so this checks the core tools only');
   return undefined;
 }
 
+// The toolbox step of `yad setup`, `yad check`, `yad update` and `yad join` (E85). It OFFERS: it prints
+// what the project uses that is not here and how to get it. It installs nothing, runs no program and
+// writes no file (decided with the row, as `yad toolbox add` is) — and it never fails the command it is
+// part of. Returns the part of the --json answer it adds: `{ used, findings, problems }`.
+// `canRemove: false` leaves out the `remove` advice — for `yad join`, whose reader just cloned the team's
+// choices: one person's machine lacking a tool is no reason to change what the whole team uses.
+export function offerToolbox(root, productRoot, { canRemove = true, ...opts } = {}) {
+  let res;
+  // A step inside another command: if finding tools throws (a home folder that cannot be read), the
+  // command it is part of still finishes, and says why the step is missing.
+  try { res = toolboxCheck(root, productRoot, opts); } catch (e) {
+    warn(`toolbox: could not check the tools here (${clean(e?.message ?? String(e))}) — run \`yad toolbox check\` to see why`);
+    return { used: [], findings: [], problems: [], error: 'could not check' };
+  }
+  for (const p of res.problems) warn(p);
+  for (const line of toolboxCheckLines(res)) log(line);
+  if (res.findings.length) {
+    info(canRemove
+      ? 'nothing is installed for you: follow the steps you choose, or, for the whole team, stop using a tool with `yad toolbox remove <id>`'
+      : 'nothing is installed for you: follow the steps you choose');
+  }
+  return { used: res.used.map((r) => r.id), findings: res.findings, problems: res.problems };
+}
+
 // `--detect skill:x,plugin:p` → { skills: ['x'], plugins: ['p'] }, or { error }.
 export function parseDetect(text) {
   const out = {};

package/cli/workspace.mjs

@@ -32,6 +32,7 @@ import { productConfigPath, PROJECT_FILES } from './manifest.mjs';
 import { runSetup, insideWorkspace, throughGitDir, selectIdeTargets } from './setup.mjs';
 import { moduleActions, gitHookActions } from './plan.mjs';
 import { writeWorkspaceFile, WORKSPACE_FILE } from './find-product.mjs';
+import { offerToolbox } from './toolbox.mjs';
 
 // E80: the file that lets yad find the Product from inside the repos it registers. Written by all three.
 function noteWorkspaceFile(product) {
@@ -483,13 +484,20 @@ export async function runJoin(cwd, url, folder, opts = {}) {
   const hook = gitHookActions(product);
   for (const a of hook) a.apply();
   if (hook.length) ok('installed the git pre-commit hook in this clone');
+  // E85: the tools the team chose (the Product's toolbox.json, just cloned) that this machine lacks. A
+  // new teammate is the person most likely to miss one. Offered, never installed.
+  log('');
+  log(c.bold('Toolbox'));
+  const toolbox = offerToolbox(product, product, { canRemove: false });
 
+  // Under a heading of its own, so these lines do not read as part of the toolbox list above.
   log('');
+  log(c.bold('Next'));
   if (repos.failed.length) hand(`${repos.failed.length} repo(s) not cloned — fix what is named above and re-run \`yad join ${shown(url)}\`; it keeps what is already there`);
   hand(`start with: cd ${fromShell(product)} && yad next`);
   return {
     workspace, product,
     repos, skills: { installed: skills.installed, stale: skills.stale.length, shared: skills.shared.length },
-    hook: hook.length ? 'installed' : 'unchanged',
+    hook: hook.length ? 'installed' : 'unchanged', toolbox,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "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 38 skills for your AI assistant.",
   "type": "module",
   "author": "AbdelRahman Nasr",