yadflow 4.0.1 → 4.2.0

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+# [4.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.1.0...v4.2.0) (2026-10-01)
+
+
+### Bug Fixes
+
+* **toolbox:** a turned-off plugin is disabled, and ranges read only full versions (E84 review 1) ([56a9864](https://github.com/abdelrahmannasr/yadflow/commit/56a9864bf91b764b736c6da12b2d30cc1d1fd861))
+* **toolbox:** add and remove report a shipped-tool edit through one function (E86 review 4) ([161ece4](https://github.com/abdelrahmannasr/yadflow/commit/161ece48cffd879fe0106747ae10698f7b5e67cf))
+* **toolbox:** clearer remove and dead-copy wording (E86 review 5 notes) ([33ba0b7](https://github.com/abdelrahmannasr/yadflow/commit/33ba0b7bae11462d9b81a739df302fe20bbd2a7c))
+* **toolbox:** npx before a turned-off plugin, Claude Code switches only, Windows PATH rules (E84 review 2) ([f052979](https://github.com/abdelrahmannasr/yadflow/commit/f052979a3018790c1d7c94fe5b761ce32bf15e55))
+* **toolbox:** offer an undo only when the tool's use changed (E86 review 3) ([32e5105](https://github.com/abdelrahmannasr/yadflow/commit/32e5105bb83f856b9b37b8bc0e96e7bf15e396e1))
+* **toolbox:** one remove clears everything under an id; add agrees with the list (E86 review 2) ([da75777](https://github.com/abdelrahmannasr/yadflow/commit/da75777496e4c705e52423c77c553f35e5c99002))
+* **toolbox:** truthful edit messages, remove clears dead lines, --dir is the Product (E86 review 1) ([2159543](https://github.com/abdelrahmannasr/yadflow/commit/21595432d611e190c93d97fc707f27c432ba936f))
+
+
+### Features
+
+* **toolbox:** yad toolbox add, remove and check (E86) ([715cd4c](https://github.com/abdelrahmannasr/yadflow/commit/715cd4c6cc63ffdcfdc33c97a9d2df8078965b64))
+* **toolbox:** yad toolbox list and the shipped toolbox of external tools (E84) ([3f5374b](https://github.com/abdelrahmannasr/yadflow/commit/3f5374b830c83782b884f48a7e760943bc2349d4))
+
+# [4.1.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.0.1...v4.1.0) (2026-10-01)
+
+
+### Bug Fixes
+
+* **detect:** a non-object mcpServers is a problem in every file (E50 review 3) ([d917c72](https://github.com/abdelrahmannasr/yadflow/commit/d917c7229f98c61b5904659b82ece3cf13612ce9))
+* **detect:** read Codex TOML keys only, keep plugins inside their folder (E50 review 1) ([be11fd2](https://github.com/abdelrahmannasr/yadflow/commit/be11fd2fcad238f994a2a68db609ddd8db2a0c8b))
+* **detect:** report plugin MCP paths that leave or miss, keep lines in order (E50 review 4) ([84c0a6a](https://github.com/abdelrahmannasr/yadflow/commit/84c0a6ae44458ba78cbc4c418b1c307090150a8e))
+* **detect:** report unreadable settings and a non-object mcpServers (E50 review 2) ([a4f7f20](https://github.com/abdelrahmannasr/yadflow/commit/a4f7f20ba5728bcd33ed4a2498026ab3ef6baa43))
+* **detect:** zero-width names, and a plugin that names .mcp.json itself (E50 review 5) ([6704c9d](https://github.com/abdelrahmannasr/yadflow/commit/6704c9db3ea5a03db968445ec9eb5b36922c4c55))
+
+
+### Features
+
+* **detect:** yad detect lists installed skills, agents, MCP servers and plugins (E50) ([ccd7142](https://github.com/abdelrahmannasr/yadflow/commit/ccd71428ac6e64624160b9b2cb867c4ec2522653))
+
 ## [4.0.1](https://github.com/abdelrahmannasr/yadflow/compare/v4.0.0...v4.0.1) (2026-09-30)
 
 

package/README.md

@@ -155,7 +155,8 @@ unless CI runs it), or `yad gate advance` with no platform, is the human decisio
 - `yad skip` and `yad defer` pass over optional steps, such as the UI design.
 
 **Already using Yadflow?** Follow [staying up to date](docs/CLI.md#staying-up-to-date). Coming from
-3.x, read [upgrading to 4.0](docs/migrations/upgrading-to-4.md) first.
+3.x, read [upgrading to 4.0](docs/migrations/upgrading-to-4.md) first, then follow the
+[step-by-step upgrade guide](docs/migrations/upgrade-guide-3x-to-4x.md).
 
 ## How the project record evolves
 
@@ -255,6 +256,8 @@ The record is worth trusting because people approve what goes into it.
 - the Shape and Build steps with review gates
 - 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
 - draft saving, claims and owners
 - the CI checks
 - the Review Companion
@@ -279,7 +282,8 @@ The record is worth trusting because people approve what goes into it.
   - [all 38 skills](docs/SKILLS.md)
   - [the by-hand walkthrough](docs/WALKTHROUGH.md)
 - **Upgrade:** [staying up to date](docs/CLI.md#staying-up-to-date) ·
-  [upgrading to 4.0](docs/migrations/upgrading-to-4.md)
+  [upgrading to 4.0](docs/migrations/upgrading-to-4.md) ·
+  [step-by-step upgrade guide](docs/migrations/upgrade-guide-3x-to-4x.md)
 - **Project:**
   - [CONTRIBUTING.md](CONTRIBUTING.md)
   - [SECURITY.md](SECURITY.md)

package/bin/commands.mjs

@@ -35,6 +35,8 @@ export { runRepo } from '../cli/repo.mjs';
 export { runRiskMap } from '../cli/riskmap-command.mjs';
 export { runCodeowners } from '../cli/codeowners-command.mjs';
 export { runDocs } from '../cli/docs.mjs';
+export { runDetect } from '../cli/detect.mjs';
+export { runToolboxAdd, runToolboxCheck, runToolboxList, runToolboxRemove } from '../cli/toolbox.mjs';
 export { runDoctor } from '../cli/doctor.mjs';
 export { runMigrate, warnIfProjectAhead } from '../cli/migrate.mjs';
 export { runNext } from '../cli/next.mjs';

package/bin/yad.mjs

@@ -116,6 +116,22 @@ ${c.bold('Where am I / what next')}
                                        Bind a step to a skill of your own. Several skills run in
                                        the order given, one after another — each costs tokens
   yad skill unbind <step>              Drop the binding; the step goes back to the engine's default
+  yad toolbox list [--json] [--dir <folder>]
+                                       The external tools yadflow can use — core (offered at setup),
+                                       recommended pools, the design/testing/learning connectors and
+                                       this project's own — whether each is found here, whether this
+                                       project uses it, and what yadflow does without it. Installs nothing
+  yad toolbox check [--json]           The tools this project uses that are not ready here, each with
+                                       its install command and fallback. Never fails: none is required
+  yad toolbox add <id>                 Use a tool in this Product (.sdlc/toolbox.json); prints how to
+                                       install it, installs nothing. Your own tool: add <id> --custom
+                                       --role "<text>" --fallback "<text>" --detect <kind>:<name>[,…]
+                                       [--install "<type>: <command>"] [--source <https URL>]
+  yad toolbox remove <id>              Stop using a tool in this Product, or drop one of your own
+  yad detect [--json] [--dir <folder>] Which skills, agents, MCP servers and plugins are installed
+                                       for the agents that work here — in this folder and in your
+                                       home folder, and which agents read each place. Read-only;
+                                       MCP servers are named, never their commands or settings
   yad skip <epic> <step> --reason <text>   Mark an optional step N/A for this epic. Which steps
                                        those are comes from the epic's lifecycle route — on classic
                                        and analysis-first, ui-design: a backend/API/data epic with no
@@ -322,7 +338,7 @@ ${c.bold('Environment')}
   YAD_NO_REPORT=1            Never offer to file a bug report after a failure
   YAD_PLATFORM_LOGIN=0       Name a record's author by git user.name; never ask gh/glab who is logged in`;
 
-const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--team', '--body', '--out', '--since', '--until', '--member', '--format', '--reason', '--profile', '--parent', '--inherits', '--to', '--retro-ship', '--merge-commit', '--path', '--ide-targets', '--theme', '--thread', '--by', '--count', '--engagement', '--keep']);
+const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--team', '--body', '--out', '--since', '--until', '--member', '--format', '--reason', '--profile', '--parent', '--inherits', '--to', '--retro-ship', '--merge-commit', '--path', '--ide-targets', '--theme', '--thread', '--by', '--count', '--engagement', '--keep', '--role', '--fallback', '--detect', '--install', '--source']);
 
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -369,6 +385,7 @@ function parseArgs(argv) {
     // The roadmap and the release check spell the default `--preview`. Accepting it means a script can
     // say what it means rather than relying on the absence of a flag.
     else if (a === '--preview') o.apply = false;
+    else if (a === '--custom') o.custom = true;
     else if (a === '--json') o.json = true;
     else if (a === '-h' || a === '--help') o.help = true;
     else if (a === '-v' || a === '--version') o.version = true;
@@ -418,6 +435,7 @@ const ACTIONS = {
   docs: { known: ['list', 'build', 'deploy', 'sync'], default: 'list' },
   reconcile: { known: ['check', 'refresh', 'wire'] },
   hook: { known: ['ledger-guard'] },
+  toolbox: { known: ['list', 'check', 'add', 'remove'], default: 'list' },
 };
 // E80 — how each command finds its folder. A PRODUCT command works on the Product; a REPO command works
 // on the code repo it runs in and reads the Product beside it. The rest take their folder as given:
@@ -553,12 +571,12 @@ async function main() {
   // A project written by a newer yadflow is warned about before any command reads it (docs/migrations/
   // shape-8.md). Not on `hook` — its stderr is the channel a block reason reaches a model on — and not
   // where the command reports the same thing itself (doctor, migrate) or runs before a project exists.
-  if (!['hook', 'doctor', 'migrate', 'setup', 'report', 'new', 'init', 'join'].includes(cmd)) commands.warnIfProjectAhead(o.dir || process.cwd());
+  if (!['hook', 'doctor', 'migrate', 'setup', 'report', 'detect', 'toolbox', 'new', 'init', 'join'].includes(cmd)) commands.warnIfProjectAhead(o.dir || process.cwd());
   // E122: the Product's settings (or an epic's PR ledger) under two names that say different things.
   // Every command refuses rather than pick one — whichever it picked, somebody's edit would be silently
   // ignored. Not `doctor` (it reports the drift), `migrate` (it ends it) or `report` (it files a bug
   // about a broken flow, and reads nothing it could get wrong). `hook` returned above: it guards.
-  if (!['doctor', 'migrate', 'report'].includes(cmd)) {
+  if (!['doctor', 'migrate', 'report', 'detect', 'toolbox'].includes(cmd)) {
     // Both the folder the command runs on and, for a code-repo command, the Product it reads.
     for (const root of new Set([o.dir || process.cwd(), o.product].filter(Boolean))) {
       const drift = commands.productDriftError(root);
@@ -619,6 +637,56 @@ async function main() {
     case 'migrate':
       result = await commands.runMigrate(o.dir, { apply: o.apply, json: o.json, keep: o.keep ?? null });
       break;
+    case 'toolbox': {
+      // E84 + E86. Finding a tool reads the folder yad runs in (a code repo's own skills count); the
+      // team's choices are the Product's `.sdlc/toolbox.json`, found the way every Product command finds
+      // it. So `toolbox` is not in PRODUCT_CMDS: that would move the finding to the Product's folder.
+      const [, action = 'list', id, extra] = o._;
+      const usage = 'usage: yad toolbox list | check | add <id> [--custom …] | remove <id>   [--json] [--dir <folder>]';
+      if (!['list', 'check', 'add', 'remove'].includes(action)) { refuse(`unknown toolbox action: ${action} (list, check, add, remove)`, usage); break; }
+      const found = commands.findProduct(dirGiven ? o.dir : shellCwd());
+      const rel = (p) => path.relative(process.cwd(), p) || '.';
+      if (action === 'list' || action === 'check') {
+        if (id) { refuse(`yad toolbox ${action} takes no more words (got: ${id})`, usage); break; }
+        // A reader may be pointed at a code repo with --dir: it finds tools there and reads the Product
+        // that repo belongs to. Why no Product was found is said, as every Product command says it —
+        // otherwise the team's choices would be missing from the answer without a word.
+        if (found?.problem) warn(`${found.problem} — showing the defaults`);
+        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 });
+        break;
+      }
+      if (extra) { refuse(`yad toolbox ${action} takes one tool id (got also: ${extra})`, usage); break; }
+      // A writer: the Product's file, never a code repo's, and the same refusals every writer has. With
+      // --dir it is the Product itself, as for every other Product command (`yad skill bind --dir`) —
+      // never a folder a walk up from it happens to reach.
+      const productRoot = dirGiven ? (found?.via === 'here' ? found.root : null) : (found?.root ?? null);
+      if (!productRoot) {
+        const near = found?.root ?? found?.elsewhere;
+        const where = dirGiven ? `with --dir, name the Product folder itself (the one holding .sdlc/product.json)${near ? `: --dir ${rel(near)}` : ''}`
+          : found?.elsewhere ? `the Product is ${rel(found.elsewhere)}: cd there, or pass --dir ${rel(found.elsewhere)}`
+            : `${found?.problem ? `${found.problem}. ` : ''}run it from the Product, from inside a repo it registers, or pass --dir <the Product>; \`yad new\` / \`yad init\` start one`;
+        refuse(`no Product here (${o.dir}) — yad toolbox ${action} writes the Product's .sdlc/toolbox.json`, where);
+        break;
+      }
+      if (found.via !== 'here') process.stderr.write(c.dim(`Product: ${rel(productRoot)}\n`));
+      commands.warnIfProjectAhead(productRoot);
+      const drift = commands.productDriftError(productRoot);
+      if (drift) throw drift;
+      result = action === 'add'
+        ? commands.runToolboxAdd(productRoot, { id, custom: o.custom, role: o.role, fallback: o.fallback, detect: o.detect, install: o.install, source: o.source, json: o.json })
+        : commands.runToolboxRemove(productRoot, { id, custom: o.custom, role: o.role, fallback: o.fallback, detect: o.detect, install: o.install, source: o.source, json: o.json });
+      break;
+    }
+    case 'detect': {
+      // E50. Reads the folder and the home folder; writes nothing.
+      const [, extra] = o._;
+      if (extra) { refuse(`yad detect takes no words (got: ${extra})`, 'usage: yad detect [--json] [--dir <folder>]'); break; }
+      result = commands.runDetect(o.dir || process.cwd(), { json: o.json });
+      break;
+    }
     case 'report':
       result = await commands.runReport(o.dir, { message: o.message });
       break;
@@ -990,7 +1058,9 @@ main()
       // block reason travels on — an update banner there would land in front of a model.
       // Resolved the way main() resolves it, NOT from argv[2]: that is the first raw argument, so
       // `yad --dir <path> hook ledger-guard` puts `--dir` there and the banner slips through.
-      if (parseArgs(process.argv.slice(2))._[0] !== 'hook') {
+      // Nor `detect` (E50) or `toolbox` (E84): they promise no network and no file written, and the
+      // check does both.
+      if (!['hook', 'detect', 'toolbox'].includes(parseArgs(process.argv.slice(2))._[0])) {
         const { maybeNotifyUpdate } = await import('./commands.mjs');
         await maybeNotifyUpdate();
       }