@kontextmind/kxm 0.7.99 → 0.7.100

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.99",
+      "version": "0.7.100",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -319,6 +319,18 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **A local `kxm workflow add` writes only what the project loader accepts, where it reads
+  it.** Local scope needs a KXM project (`project_not_found` outside one, creating nothing)
+  and writes to the project root's `.kxm/workflows/` from any subdirectory. Before writing,
+  also under `--dry-run`, the project loader checks the project with the new document; if
+  it would not load, the command exits 2 with `workflow_invalid`, lists the issues and
+  writes nothing. A `--file` in the shape written through 0.7.92 is refused, and
+  `--overwrite` repairs a file left in that shape. See
+  `docs/reference/cli-reference.md#kxm-workflow-add`.
+- **`kxm workflow add --pick <global-id>` copies the global definition.** In local scope,
+  picking a global definition wrote the one-step scaffold under its id and reported
+  success. It now writes the global definition's content, with `--description` replacing
+  its description, and the loader check refuses one the project cannot load.
 - **Live `kxm runs drive` can author on an audited writer profile.** A write-repository
   step on pi (`-a`, with extensions, skills, and the session off) or grok
   (`--always-approve`, with subagents and web search off) runs against the checkout.

package/docs/contributing/test-matrix.md

@@ -61,6 +61,8 @@ to run one file is in [Develop KXM](development.md#run-one-file-or-one-test).
 | Dispatch context: only committed, pinned memory and hash-verified promoted skills reach an agent; the rest is a `dispatch_context_*` gap | `engine.test.ts` ("dispatch context: agents receive only committed, pinned memory and verified skills; anything else is withheld with a gap and the step still completes") |
 | `kxm run` prints the simulated drive command for the new run | `cli.test.ts` ("kxm run prints the simulated drive command for the created run") |
 | `kxm workflow add --template` writes workflows that validate and plan; an impossible gate outcome is refused | `cli-experience.test.ts` ("workflow add templates validate and plan a run, and a gate outcome the step can never produce is refused") |
+| `kxm workflow add` writes a local workflow only where the loader reads it and only if the project still loads; outside a project it refuses | `role-and-workflow-manager.test.ts` ("workflow add writes only what the project loader accepts, at the project root, and loadKxmProject still loads") |
+| `kxm workflow add --pick <global-id>` copies the global definition into the project, not the scaffold, and the loader check refuses one that does not fit | `role-and-workflow-manager.test.ts` ("workflow add --pick <global-id> copies that global definition into the project, and refuses one the project loader rejects") |
 | `default.yaml` and the 13-step `fix.yaml` compile deterministically; back edges need budgets | `engine-compile.test.ts` |
 | Artifact gate: non-empty regular files pass; missing, empty, non-file and escaping paths fail | `artifacts-exist.test.ts` |
 | Vision gate: strict verdicts, admitted routes only, unreadable images fail closed | `vision-gate.test.ts` |

package/docs/reference/cli-reference.md

@@ -91,7 +91,7 @@ kxm -V
 - The `command` field is not always the words you typed: `hub stop` and `session stop` report `stop`, `session token` reports `auth token`, `routes admit` and `routes disable` report `routes admitted` and `routes disabled`, `models inventory-refresh` reports `models inventory refresh`, `workflow export` reports `retrospective export`, `gate degrade` reports `workflow degrade`, `gate signal` and `workflow signal` report `signal`, `gate github watch` reports `github watch`, `agent worker` reports `worker`, and `improve report` reports `improve`.
 - A result with `ok: false` is written to stderr in both text and JSON mode; everything else goes to stdout. `runtime status` is the exception: when the supervisor is down it prints `ok: true, running: false` on stdout and exits 1.
 - `peer` subcommands and `workflow checkpoint|record|wait` print the hub's result object as returned, tagged with `schema` but without `ok` or `command`. Their failures print `{"ok":false,"error":"command_failed","detail":"..."}`. Text mode prints the same JSON.
-- Several error paths ignore `--json` and print one plain line on stderr: argument checks in `agent worker`, `session start`, `workflow start`, `gate degrade`, `gate signal`, and `gate github watch`; every error from `config`, `role`, `workflow definitions|add|remove|modify` (except the three `workflow add --template` refusals, which honor `--json`), `goal`, `task`, `memory`, `skills` (other than `skills create --dry-run`), `suggest`, `studio`, and `completion`. Check the exit code before parsing stdout.
+- Several error paths ignore `--json` and print one plain line on stderr: argument checks in `agent worker`, `session start`, `workflow start`, `gate degrade`, `gate signal`, and `gate github watch`; every error from `config`, `role`, `workflow definitions|add|remove|modify` (except the `workflow add` refusals listed under it, which honor `--json`), `goal`, `task`, `memory`, `skills` (other than `skills create --dry-run`), `suggest`, `studio`, and `completion`. Check the exit code before parsing stdout.
 - Every `context` subcommand exits 1 with a Node.js stack trace and no JSON when the hub cannot be reached.
 - Output is redacted. Values of environment variables whose names contain `TOKEN`, `SECRET`, `KEY`, or `PASSWORD` are replaced with `[redacted]`, and 64-character hex strings are replaced unless they appear in a known digest field such as `configRevision` or `sha256`. `session brief` and `auth token` print the session token itself; treat their output as a credential.
 
@@ -1961,7 +1961,7 @@ WORKFLOW DEFINITIONS:
 kxm workflow add [workflowId] [--template <name> | --file <path> | --pick [selection]] [--description <text>] [--scope global|local] [--overwrite]
 ```
 
-Add a workflow definition to global or local configuration. With `--template <name>`, the named built-in template is written under the workflow ID. Without a workflow ID, or with `--pick`, you choose from the built-in templates and, for local scope, existing global definitions. With `--file`, the YAML file is copied as-is. Otherwise a one-step scaffold is written: one `implementer` agent step with write access to `control` that ends the run `completed` on `passed` and `failed` on `failed`.
+Add a workflow definition to global or local configuration. With `--template <name>`, the named built-in template is written under the workflow ID. Without a workflow ID, or with `--pick`, you choose from the built-in templates and, for local scope, existing global definitions; a global definition with a template's ID is not offered. The choice is written under its own ID with its content: the template, or a copy of the global definition's file, with `--description` replacing its description. With `--file`, the YAML file is copied as-is once it passes the local check below. Otherwise a one-step scaffold is written: one `implementer` agent step with write access to `control` that ends the run `completed` on `passed` and `failed` on `failed`.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
@@ -1975,7 +1975,8 @@ Add a workflow definition to global or local configuration. With `--template <na
 - Templates: `implement-and-verify` runs the `implementer` agent, then the project's `test` gate, and a failing gate (`implementation-failure`) sends the work back to `implement` at most twice. `dual-critic-review` adds two review steps between them, both run as the `coordinator` agent with read access; point `review-arch` and `review-cli` at your own agents for independent critics. `spec-and-plan` plans and then reviews the plan, both as `coordinator`, reading the repository only.
 - The templates and the scaffold are valid `kxm.workflow.v1` definitions that use only what `kxm init` creates: the `coordinator` and `implementer` agents, the `control` repository, and the `test` gate. Each was checked with `kxm init --json` and `kxm run <id> --dry-run` for this page. A new file under `.kxm/workflows/` is a permission expansion that `kxm trust check` asks you to review before you commit it.
 - Writes `<scope dir>/workflows/<id>.yaml`. `kxm run` loads only `.kxm/workflows/`, so a `--scope global` definition is not runnable until it is copied into a project. `--dry-run` plans the write and writes nothing.
-- `--template` refusals exit 2 and honor `--json`: `workflow_template_unknown` (the text names the three templates), `workflow_id_required` (no workflow ID), and `workflow_add_conflict` (combined with `--file` or `--pick`). An existing definition without `--overwrite` exits 1 with a plain `workflow add failed: workflow_already_exists: ...` line, also under `--dry-run`.
+- Local scope belongs to a KXM project: the file lands in the project root's `.kxm/workflows/` from any subdirectory, and outside a project the command refuses with `project_not_found` and creates nothing. Before writing, the project loader checks the project with the new document in place of any file of that ID, using the parser, schema and bundle rules `kxm run` uses. If the project would not load, the command refuses with `workflow_invalid`, lists each issue and writes nothing, also under `--dry-run`. So `--file` or a picked global definition with a top-level `id` or a `role:` step, the shape `workflow add` wrote through 0.7.92, is refused, and `--overwrite` replaces a file left in that shape. Global scope is not checked, because no loader reads it.
+- Refusals exit 2 and honor `--json`: `workflow_template_unknown` (the text names the three templates), `workflow_id_required` (no workflow ID), `workflow_add_conflict` (`--template` combined with `--file` or `--pick`), `project_not_found`, and `workflow_invalid` (with `issues`, each `{phase, code, file, message}`). An existing definition without `--overwrite` exits 1 with a plain `workflow add failed: workflow_already_exists: ...` line, also under `--dry-run`.
 - JSON keys: `workflowId`, `id`, `filePath`, `scope`.
 
 Start a first workflow from a template:

package/docs/reference/config-reference.md

@@ -889,8 +889,10 @@ compiles and pins the plan, then drives it live, or without models with
 reads). Both are valid `kxm.workflow.v1` definitions that use only what
 `kxm init` creates: the `coordinator` and `implementer` agents, the `control`
 repository, and the `test` gate. The templates route gate failures on
-`implementation-failure`. Review the new file with `kxm trust check` before
-committing it.
+`implementation-failure`. A local add is checked by the project loader first:
+if the project would not load with the new file, it is refused with
+`workflow_invalid` and nothing is written. Review the new file with
+`kxm trust check` before committing it.
 
 ## `.kxm/gates.yaml` (`kxm.gate-registry.v1`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.99",
+  "version": "0.7.100",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.99",
+  "version": "0.7.100",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/cli.js

@@ -164,10 +164,10 @@ var require_code = __commonJS({
     function interpolate(x2) {
       return typeof x2 == "number" || typeof x2 == "boolean" || x2 === null ? x2 : safeStringify(Array.isArray(x2) ? x2.join(",") : x2);
     }
-    function stringify11(x2) {
+    function stringify12(x2) {
       return new _Code(safeStringify(x2));
     }
-    exports.stringify = stringify11;
+    exports.stringify = stringify12;
     function safeStringify(x2) {
       return JSON.stringify(x2).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
     }
@@ -8918,7 +8918,7 @@ var require_stringify = __commonJS({
         props.push(doc.directives.tagString(tag));
       return props.join(" ");
     }
-    function stringify11(item, ctx, onComment, onChompKeep) {
+    function stringify12(item, ctx, onComment, onChompKeep) {
       if (identity.isPair(item))
         return item.toString(ctx, onComment, onChompKeep);
       if (identity.isAlias(item)) {
@@ -8947,7 +8947,7 @@ var require_stringify = __commonJS({
 ${ctx.indent}${str}`;
     }
     exports.createStringifyContext = createStringifyContext;
-    exports.stringify = stringify11;
+    exports.stringify = stringify12;
   }
 });
 
@@ -8957,7 +8957,7 @@ var require_stringifyPair = __commonJS({
     "use strict";
     var identity = require_identity();
     var Scalar = require_Scalar();
-    var stringify11 = require_stringify();
+    var stringify12 = require_stringify();
     var stringifyComment = require_stringifyComment();
     function stringifyPair({ key, value }, ctx, onComment, onChompKeep) {
       const { allNullValues, doc, indent, indentStep, options: { commentString, indentSeq, simpleKeys } } = ctx;
@@ -8979,7 +8979,7 @@ var require_stringifyPair = __commonJS({
       });
       let keyCommentDone = false;
       let chompKeep = false;
-      let str = stringify11.stringify(key, ctx, () => keyCommentDone = true, () => chompKeep = true);
+      let str = stringify12.stringify(key, ctx, () => keyCommentDone = true, () => chompKeep = true);
       if (!explicitKey && !ctx.inFlow && str.length > 1024) {
         if (simpleKeys)
           throw new Error("With simple keys, single line scalar must not span more than 1024 characters");
@@ -9031,7 +9031,7 @@ ${indent}:`;
         ctx.indent = ctx.indent.substring(2);
       }
       let valueCommentDone = false;
-      const valueStr = stringify11.stringify(value, ctx, () => valueCommentDone = true, () => chompKeep = true);
+      const valueStr = stringify12.stringify(value, ctx, () => valueCommentDone = true, () => chompKeep = true);
       let ws = " ";
       if (keyComment || vsb || vcb) {
         ws = vsb ? "\n" : "";
@@ -9172,7 +9172,7 @@ var require_addPairToJSMap = __commonJS({
     "use strict";
     var log = require_log();
     var merge = require_merge();
-    var stringify11 = require_stringify();
+    var stringify12 = require_stringify();
     var identity = require_identity();
     var toJS = require_toJS();
     function addPairToJSMap(ctx, map, { key, value }) {
@@ -9208,7 +9208,7 @@ var require_addPairToJSMap = __commonJS({
       if (typeof jsKey !== "object")
         return String(jsKey);
       if (identity.isNode(key) && ctx?.doc) {
-        const strCtx = stringify11.createStringifyContext(ctx.doc, {});
+        const strCtx = stringify12.createStringifyContext(ctx.doc, {});
         strCtx.anchors = /* @__PURE__ */ new Set();
         for (const node of ctx.anchors.keys())
           strCtx.anchors.add(node.anchor);
@@ -9275,12 +9275,12 @@ var require_stringifyCollection = __commonJS({
   "node_modules/yaml/dist/stringify/stringifyCollection.js"(exports) {
     "use strict";
     var identity = require_identity();
-    var stringify11 = require_stringify();
+    var stringify12 = require_stringify();
     var stringifyComment = require_stringifyComment();
     function stringifyCollection(collection, ctx, options) {
       const flow = ctx.inFlow ?? collection.flow;
-      const stringify12 = flow ? stringifyFlowCollection : stringifyBlockCollection;
-      return stringify12(collection, ctx, options);
+      const stringify13 = flow ? stringifyFlowCollection : stringifyBlockCollection;
+      return stringify13(collection, ctx, options);
     }
     function stringifyBlockCollection({ comment, items }, ctx, { blockItemPrefix, flowChars, itemIndent, onChompKeep, onComment }) {
       const { indent, options: { commentString } } = ctx;
@@ -9305,7 +9305,7 @@ var require_stringifyCollection = __commonJS({
           }
         }
         chompKeep = false;
-        let str2 = stringify11.stringify(item, itemCtx, () => comment2 = null, () => chompKeep = true);
+        let str2 = stringify12.stringify(item, itemCtx, () => comment2 = null, () => chompKeep = true);
         if (comment2)
           str2 += stringifyComment.lineComment(str2, itemIndent, commentString(comment2));
         if (chompKeep && comment2)
@@ -9372,7 +9372,7 @@ ${indent}${line}` : "\n";
         }
         if (comment)
           reqNewline = true;
-        let str = stringify11.stringify(item, itemCtx, () => comment = null);
+        let str = stringify12.stringify(item, itemCtx, () => comment = null);
         reqNewline || (reqNewline = lines.length > linesAtValue || str.includes("\n"));
         if (i < items.length - 1) {
           str += ",";
@@ -10733,7 +10733,7 @@ var require_stringifyDocument = __commonJS({
   "node_modules/yaml/dist/stringify/stringifyDocument.js"(exports) {
     "use strict";
     var identity = require_identity();
-    var stringify11 = require_stringify();
+    var stringify12 = require_stringify();
     var stringifyComment = require_stringifyComment();
     function stringifyDocument(doc, options) {
       const lines = [];
@@ -10748,7 +10748,7 @@ var require_stringifyDocument = __commonJS({
       }
       if (hasDirectives)
         lines.push("---");
-      const ctx = stringify11.createStringifyContext(doc, options);
+      const ctx = stringify12.createStringifyContext(doc, options);
       const { commentString } = ctx.options;
       if (doc.commentBefore) {
         if (lines.length !== 1)
@@ -10770,7 +10770,7 @@ var require_stringifyDocument = __commonJS({
           contentComment = doc.contents.comment;
         }
         const onChompKeep = contentComment ? void 0 : () => chompKeep = true;
-        let body = stringify11.stringify(doc.contents, ctx, () => contentComment = null, onChompKeep);
+        let body = stringify12.stringify(doc.contents, ctx, () => contentComment = null, onChompKeep);
         if (contentComment)
           body += stringifyComment.lineComment(body, "", commentString(contentComment));
         if ((body[0] === "|" || body[0] === ">") && lines[lines.length - 1] === "---") {
@@ -10778,7 +10778,7 @@ var require_stringifyDocument = __commonJS({
         } else
           lines.push(body);
       } else {
-        lines.push(stringify11.stringify(doc.contents, ctx));
+        lines.push(stringify12.stringify(doc.contents, ctx));
       }
       if (doc.directives?.docEnd) {
         if (doc.comment) {
@@ -12914,7 +12914,7 @@ var require_cst_scalar = __commonJS({
 var require_cst_stringify = __commonJS({
   "node_modules/yaml/dist/parse/cst-stringify.js"(exports) {
     "use strict";
-    var stringify11 = (cst) => "type" in cst ? stringifyToken(cst) : stringifyItem(cst);
+    var stringify12 = (cst) => "type" in cst ? stringifyToken(cst) : stringifyItem(cst);
     function stringifyToken(token) {
       switch (token.type) {
         case "block-scalar": {
@@ -12967,7 +12967,7 @@ var require_cst_stringify = __commonJS({
         res += stringifyToken(value);
       return res;
     }
-    exports.stringify = stringify11;
+    exports.stringify = stringify12;
   }
 });
 
@@ -14697,7 +14697,7 @@ var require_public_api = __commonJS({
       }
       return doc.toJS(Object.assign({ reviver: _reviver }, options));
     }
-    function stringify11(value, replacer, options) {
+    function stringify12(value, replacer, options) {
       let _replacer = null;
       if (typeof replacer === "function" || Array.isArray(replacer)) {
         _replacer = replacer;
@@ -14722,7 +14722,7 @@ var require_public_api = __commonJS({
     exports.parse = parse12;
     exports.parseAllDocuments = parseAllDocuments;
     exports.parseDocument = parseDocument2;
-    exports.stringify = stringify11;
+    exports.stringify = stringify12;
   }
 });
 
@@ -22700,10 +22700,13 @@ function readResource(registry, root, file, logicalPath, kind, id, containmentRo
     parent = dirname4(parent);
   }
   if (!stat.isFile()) fail2("path", "resource_not_file", label, "configuration resource must be a regular file");
-  const value = parseRestrictedYaml2(readFileSync5(file), label);
+  return { kind, ...id === void 0 ? {} : { id }, file, logicalPath, value: resourceValue(registry, readFileSync5(file), label, kind) };
+}
+function resourceValue(registry, input, label, kind) {
+  const value = parseRestrictedYaml2(input, label);
   const issues = registry.validate(kind, value, label);
   if (issues.length > 0) throw new KxmConfigError(issues);
-  return { kind, ...id === void 0 ? {} : { id }, file, logicalPath, value };
+  return value;
 }
 function readTemplateProvenance(registry, root) {
   const file = join6(root, ".kxm", "template-provenance.yaml");
@@ -22752,7 +22755,7 @@ function readTemplateProvenance(registry, root) {
   }
   return value;
 }
-function listNamedResources(registry, root, directory, logicalDirectory, kind) {
+function listNamedResources(registry, root, directory, logicalDirectory, kind, replacedId) {
   const resources = /* @__PURE__ */ new Map();
   if (!existsSync6(directory)) return resources;
   const stat = lstatSync(directory);
@@ -22773,6 +22776,7 @@ function listNamedResources(registry, root, directory, logicalDirectory, kind) {
     }
     const id = basename2(entry.name, ".yaml");
     if (kind === "model" && id === "inventory") continue;
+    if (id === replacedId) continue;
     if (!resourceIdentifier(id)) {
       issues.push(issue2("path", "resource_id_invalid", displayPath(root, join6(directory, entry.name)), `filename-derived identity ${id} is invalid or platform-reserved`));
       continue;
@@ -23377,6 +23381,18 @@ function assertNoRegisteredGates(options) {
   }
 }
 function loadKxmProject(projectRoot, options = {}) {
+  return loadProjectBundle(projectRoot, options);
+}
+function kxmWorkflowWriteIssues(projectRoot, workflowId, document, options = {}) {
+  try {
+    loadProjectBundle(projectRoot, options, { id: workflowId, document });
+    return [];
+  } catch (error) {
+    if (error instanceof KxmConfigError) return error.issues;
+    throw error;
+  }
+}
+function loadProjectBundle(projectRoot, options, workflowCandidate) {
   assertNoRegisteredGates(options);
   const root = resolve3(projectRoot);
   const legacyPresent = legacyConfigFilesAt(root);
@@ -23410,7 +23426,15 @@ function loadKxmProject(projectRoot, options = {}) {
   if (earlyIssues.length > 0) throw new KxmConfigError(earlyIssues);
   const agents = listNamedResources(registry, root, join6(root, ".kxm", "agents"), ".kxm/agents", "agent");
   const models = listNamedResources(registry, root, join6(root, ".kxm", "models"), ".kxm/models", "model");
-  const workflows = listNamedResources(registry, root, join6(root, ".kxm", "workflows"), ".kxm/workflows", "workflow");
+  const workflows = listNamedResources(registry, root, join6(root, ".kxm", "workflows"), ".kxm/workflows", "workflow", workflowCandidate?.id);
+  if (workflowCandidate) {
+    const { id, document } = workflowCandidate;
+    const logicalPath = `.kxm/workflows/${id}.yaml`;
+    if (!resourceIdentifier(id)) fail2("path", "resource_id_invalid", logicalPath, `filename-derived identity ${id} is invalid or platform-reserved`);
+    const collision = [...workflows.keys()].find((candidate) => candidate.toLocaleLowerCase("en-US") === id.toLocaleLowerCase("en-US"));
+    if (collision) fail2("path", "resource_id_collision", logicalPath, `${id} case-folds to existing ${collision}`);
+    workflows.set(id, { kind: "workflow", id, file: join6(root, logicalPath), logicalPath, value: resourceValue(registry, document, logicalPath, "workflow") });
+  }
   const gatePath = join6(root, ".kxm", "gates.yaml");
   const gateRegistry = existsSync6(gatePath) ? readResource(registry, root, gatePath, ".kxm/gates.yaml", "gate-registry") : void 0;
   const environments = [];
@@ -28919,6 +28943,7 @@ async function cmdRoleResume(runtime, runId, ruling) {
 }
 
 // plugins/kxm/src/cli/workflows.ts
+var import_yaml12 = __toESM(require_dist(), 1);
 import { randomUUID as randomUUID8 } from "node:crypto";
 import { existsSync as existsSync21, readFileSync as readFileSync20 } from "node:fs";
 import { join as join22, resolve as resolve17 } from "node:path";
@@ -29770,12 +29795,12 @@ async function cmdWorkflowDefinitions(runtime, options) {
 }
 async function cmdWorkflowAdd(runtime, workflowId, options) {
   const scope = options.scope ?? "local";
+  const refuse = (error, text) => {
+    print(runtime.io, runtime.json, { ok: false, command: "workflow add", error }, `workflow add failed: ${text}`);
+    return 2;
+  };
   let content;
   if (options.template !== void 0) {
-    const refuse = (error, text) => {
-      print(runtime.io, runtime.json, { ok: false, command: "workflow add", error }, `workflow add failed: ${text}`);
-      return 2;
-    };
     if (options.file !== void 0 || options.pick !== void 0) {
       return refuse("workflow_add_conflict", "--template cannot be combined with --file or --pick");
     }
@@ -29795,8 +29820,9 @@ async function cmdWorkflowAdd(runtime, workflowId, options) {
     if (scope === "local") {
       const globalDefs = listWorkflowDefinitions({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
       for (const gd of globalDefs) {
-        if (!candidates.some((c) => c.id === gd.id)) {
-          candidates.push({ id: gd.id, description: gd.description, label: "global" });
+        const definition = parseWorkflowFile(gd.filePath);
+        if (definition && !candidates.some((c) => c.id === gd.id)) {
+          candidates.push({ id: gd.id, description: gd.description, label: "global", payload: definition });
         }
       }
     }
@@ -29823,9 +29849,29 @@ async function cmdWorkflowAdd(runtime, workflowId, options) {
     content = scaffoldWorkflowDefinition(options.description || `Workflow ${workflowId}`);
   }
   try {
-    const res = addWorkflowDefinition(workflowId, content, {
+    const document = typeof content === "string" ? content : (0, import_yaml12.stringify)(content);
+    let repoRoot = runtime.cwd;
+    if (scope === "local") {
+      const projectRoot = discoverKxmProjectRoot(runtime.cwd);
+      if (!projectRoot) {
+        return refuse("project_not_found", "local workflows belong to a KXM project; run kxm init at the repository root, or pass --scope global");
+      }
+      const issues = kxmWorkflowWriteIssues(projectRoot, workflowId, document);
+      if (issues.length > 0) {
+        print(
+          runtime.io,
+          runtime.json,
+          { ok: false, command: "workflow add", error: "workflow_invalid", issues },
+          `workflow add failed: with this workflow the project would not load, so nothing was written
+${issues.map((entry) => `  ${entry.file}: ${entry.code}: ${entry.message}`).join("\n")}`
+        );
+        return 2;
+      }
+      repoRoot = projectRoot;
+    }
+    const res = addWorkflowDefinition(workflowId, document, {
       scope,
-      repoRoot: runtime.cwd,
+      repoRoot,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
       overwrite: options.overwrite,
       dryRun: runtime.dryRun
@@ -30249,7 +30295,7 @@ async function cmdRetrospectiveExport(runtime, runId, options) {
 }
 
 // plugins/kxm/src/cli/tasks.ts
-var import_yaml14 = __toESM(require_dist(), 1);
+var import_yaml15 = __toESM(require_dist(), 1);
 import { existsSync as existsSync27, readFileSync as readFileSync25, readdirSync as readdirSync10 } from "node:fs";
 import { basename as basename7, join as join29, resolve as resolve22 } from "node:path";
 
@@ -30360,7 +30406,7 @@ function suggestWorkflowAndRoles(prompt, options = {}) {
 }
 
 // plugins/kxm/src/task-manager.ts
-var import_yaml12 = __toESM(require_dist(), 1);
+var import_yaml13 = __toESM(require_dist(), 1);
 import { randomUUID as randomUUID9 } from "node:crypto";
 import { existsSync as existsSync22, mkdirSync as mkdirSync17, readFileSync as readFileSync21, readdirSync as readdirSync8, writeFileSync as writeFileSync17 } from "node:fs";
 import { join as join23, resolve as resolve18 } from "node:path";
@@ -30394,7 +30440,7 @@ function createGoal(repoRoot, input, options = {}) {
   };
   if (options.dryRun) return record;
   mkdirSync17(goalsDirectory(repoRoot), { recursive: true });
-  writeFileSync17(goalFilePath(repoRoot, id), (0, import_yaml12.stringify)(record).trim() + "\n", "utf8");
+  writeFileSync17(goalFilePath(repoRoot, id), (0, import_yaml13.stringify)(record).trim() + "\n", "utf8");
   return record;
 }
 function listGoals(repoRoot) {
@@ -30406,7 +30452,7 @@ function listGoals(repoRoot) {
     if (entry.isFile() && (entry.name.endsWith(".yaml") || entry.name.endsWith(".yml"))) {
       try {
         const text = readFileSync21(join23(dir, entry.name), "utf8");
-        const doc = (0, import_yaml12.parse)(text);
+        const doc = (0, import_yaml13.parse)(text);
         if (doc && doc.schema === GOAL_SCHEMA) goals.push(doc);
       } catch {
       }
@@ -30438,7 +30484,7 @@ function createTask(repoRoot, input, options = {}) {
   };
   if (options.dryRun) return record;
   mkdirSync17(tasksDirectory(repoRoot), { recursive: true });
-  writeFileSync17(taskFilePath(repoRoot, id), (0, import_yaml12.stringify)(record).trim() + "\n", "utf8");
+  writeFileSync17(taskFilePath(repoRoot, id), (0, import_yaml13.stringify)(record).trim() + "\n", "utf8");
   return record;
 }
 function listTasks(repoRoot, options = {}) {
@@ -30450,7 +30496,7 @@ function listTasks(repoRoot, options = {}) {
     if (entry.isFile() && (entry.name.endsWith(".yaml") || entry.name.endsWith(".yml"))) {
       try {
         const text = readFileSync21(join23(dir, entry.name), "utf8");
-        const doc = (0, import_yaml12.parse)(text);
+        const doc = (0, import_yaml13.parse)(text);
         if (doc && doc.schema === TASK_SCHEMA) {
           if (options.goalId && doc.goalId !== options.goalId) continue;
           if (options.status && doc.status !== options.status) continue;
@@ -30468,7 +30514,7 @@ function getTask(repoRoot, taskId) {
   if (!existsSync22(filePath)) return void 0;
   try {
     const text = readFileSync21(filePath, "utf8");
-    const doc = (0, import_yaml12.parse)(text);
+    const doc = (0, import_yaml13.parse)(text);
     return doc && doc.schema === TASK_SCHEMA ? doc : void 0;
   } catch {
     return void 0;
@@ -30482,7 +30528,7 @@ function updateTaskStatus(repoRoot, taskId, status, options = {}) {
   task.status = status;
   if (options.workflowRunId) task.workflowRunId = options.workflowRunId;
   task.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  if (!options.dryRun) writeFileSync17(taskFilePath(repoRoot, taskId), (0, import_yaml12.stringify)(task).trim() + "\n", "utf8");
+  if (!options.dryRun) writeFileSync17(taskFilePath(repoRoot, taskId), (0, import_yaml13.stringify)(task).trim() + "\n", "utf8");
   return task;
 }
 function syncTaskWithTracker(repoRoot, taskId, options = {}) {
@@ -30497,7 +30543,7 @@ function syncTaskWithTracker(repoRoot, taskId, options = {}) {
   task.trackerSync.syncStatus = "synced";
   task.trackerSync.lastSyncedAt = now;
   task.updatedAt = now;
-  if (!options.dryRun) writeFileSync17(taskFilePath(repoRoot, taskId), (0, import_yaml12.stringify)(task).trim() + "\n", "utf8");
+  if (!options.dryRun) writeFileSync17(taskFilePath(repoRoot, taskId), (0, import_yaml13.stringify)(task).trim() + "\n", "utf8");
   return task;
 }
 
@@ -31269,7 +31315,7 @@ import { join as join28, resolve as resolve21 } from "node:path";
 import { createInterface as createInterface2 } from "node:readline";
 
 // plugins/kxm/src/model-inventory.ts
-var import_yaml13 = __toESM(require_dist(), 1);
+var import_yaml14 = __toESM(require_dist(), 1);
 import { mkdirSync as mkdirSync18, writeFileSync as writeFileSync18 } from "node:fs";
 import { join as join24 } from "node:path";
 var OR_URL = "https://openrouter.ai/api/v1/models";
@@ -31358,7 +31404,7 @@ async function refreshModelInventory(options) {
   for (const item of nous.data) add(item, "nous", "discount");
   const inventory = { schema: "kxm.model-inventory.v1", fetchedAt, currency: "USD", sources, models: [...byId.values()].sort((a, b2) => a.id.localeCompare(b2.id)) };
   mkdirSync18(join24(options.outputRoot, ".kxm", "models"), { recursive: true });
-  writeFileSync18(join24(options.outputRoot, ".kxm", "models", "inventory.yaml"), (0, import_yaml13.stringify)(inventory), "utf8");
+  writeFileSync18(join24(options.outputRoot, ".kxm", "models", "inventory.yaml"), (0, import_yaml14.stringify)(inventory), "utf8");
   return inventory;
 }
 
@@ -34539,7 +34585,7 @@ steps:
         maxTransitions: 2
 `;
     }
-    const parsedYaml = (0, import_yaml14.parse)(yamlContent);
+    const parsedYaml = (0, import_yaml15.parse)(yamlContent);
     const plan = compileKxmWorkflow({ id: workflowId, value: parsedYaml });
     const layout = generateStudioLayout(plan);
     print(runtime.io, runtime.json, { ok: true, command: "studio layout", layout }, JSON.stringify(layout, null, 2));
@@ -34581,7 +34627,7 @@ async function cmdStudioServe(runtime, options) {
           }
           if (targetPath && existsSync27(targetPath)) {
             const raw = readFileSync25(targetPath, "utf8");
-            const parsed = (0, import_yaml14.parse)(raw);
+            const parsed = (0, import_yaml15.parse)(raw);
             const wfId = basename7(targetPath).replace(/\.(yaml|yml)$/, "");
             return compileKxmWorkflow({ id: wfId, value: parsed });
           }
@@ -45227,7 +45273,7 @@ function resolveInstallKind(probe, npmGlobalRoot) {
 }
 
 // plugins/kxm/src/kxm-update-config.ts
-var import_yaml15 = __toESM(require_dist(), 1);
+var import_yaml16 = __toESM(require_dist(), 1);
 import { existsSync as existsSync31, readFileSync as readFileSync30 } from "node:fs";
 import { join as join39 } from "node:path";
 function loadKxmUpdateConfig(env = process.env) {
@@ -45235,7 +45281,7 @@ function loadKxmUpdateConfig(env = process.env) {
   if (!existsSync31(path4)) return { schema: KXM_UPDATE_SCHEMA, auto: false, source: "github" };
   let parsed;
   try {
-    parsed = (0, import_yaml15.parse)(readFileSync30(path4, "utf8"));
+    parsed = (0, import_yaml16.parse)(readFileSync30(path4, "utf8"));
   } catch {
     throw new KxmUpdateConfigError("update.yaml is not valid YAML");
   }
@@ -46602,7 +46648,7 @@ function loadRoutingSources(options) {
 }
 
 // plugins/kxm/src/modes.ts
-var import_yaml16 = __toESM(require_dist(), 1);
+var import_yaml17 = __toESM(require_dist(), 1);
 import { existsSync as existsSync36, readFileSync as readFileSync34 } from "node:fs";
 import { join as join43 } from "node:path";
 var DEFAULT_MODES_CONFIG = Object.freeze({
@@ -46673,7 +46719,7 @@ function loadModesConfig(projectRoot) {
   }
   try {
     const raw = readFileSync34(modesPath, "utf8");
-    const parsed = (0, import_yaml16.parse)(raw);
+    const parsed = (0, import_yaml17.parse)(raw);
     if (parsed && parsed.schema === "kxm.modes.v1" && parsed.majorModes) {
       return {
         schema: "kxm.modes.v1",
@@ -47661,7 +47707,7 @@ ${line}
 }
 
 // plugins/kxm/src/init-guide-setup.ts
-var import_yaml17 = __toESM(require_dist(), 1);
+var import_yaml18 = __toESM(require_dist(), 1);
 import { existsSync as existsSync39, mkdirSync as mkdirSync30, writeFileSync as writeFileSync27 } from "node:fs";
 import { dirname as dirname24, join as join46 } from "node:path";
 var ADMITTED_GUIDE_BINDINGS = Object.freeze({
@@ -48057,13 +48103,13 @@ function renderGuideSetupFiles(projectRoot, plan) {
     if (!stage) continue;
     files.push({
       path: join46(projectRoot, ".kxm", "agents", `${role}.yaml`),
-      content: (0, import_yaml17.stringify)(agentDocument(role, stage, binding))
+      content: (0, import_yaml18.stringify)(agentDocument(role, stage, binding))
     });
   }
   for (const workflow of plan.workflows) {
     files.push({
       path: join46(projectRoot, ".kxm", "workflows", `${workflow.slug}.yaml`),
-      content: (0, import_yaml17.stringify)(workflowDocument(workflow))
+      content: (0, import_yaml18.stringify)(workflowDocument(workflow))
     });
   }
   return files;
@@ -48081,7 +48127,7 @@ function mergeGuideRouteAdmission(projectRoot, plan) {
   policy.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
   const path4 = join46(projectRoot, ".kxm", "routes.yaml");
   mkdirSync30(dirname24(path4), { recursive: true });
-  writeFileSync27(path4, (0, import_yaml17.stringify)(policy), "utf8");
+  writeFileSync27(path4, (0, import_yaml18.stringify)(policy), "utf8");
   return added;
 }
 function writeGuideSetupFiles(files) {

package/plugins/kxm/dist/mcp-server.js

@@ -17308,7 +17308,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.99";
+var VERSION = "0.7.100";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/dist/runtime-supervisor.js

@@ -16611,10 +16611,13 @@ function readResource(registry, root, file, logicalPath, kind, id, containmentRo
     parent = dirname2(parent);
   }
   if (!stat.isFile()) fail2("path", "resource_not_file", label, "configuration resource must be a regular file");
-  const value = parseRestrictedYaml2(readFileSync(file), label);
+  return { kind, ...id === void 0 ? {} : { id }, file, logicalPath, value: resourceValue(registry, readFileSync(file), label, kind) };
+}
+function resourceValue(registry, input, label, kind) {
+  const value = parseRestrictedYaml2(input, label);
   const issues = registry.validate(kind, value, label);
   if (issues.length > 0) throw new KxmConfigError(issues);
-  return { kind, ...id === void 0 ? {} : { id }, file, logicalPath, value };
+  return value;
 }
 function readTemplateProvenance(registry, root) {
   const file = join2(root, ".kxm", "template-provenance.yaml");
@@ -16663,7 +16666,7 @@ function readTemplateProvenance(registry, root) {
   }
   return value;
 }
-function listNamedResources(registry, root, directory, logicalDirectory, kind) {
+function listNamedResources(registry, root, directory, logicalDirectory, kind, replacedId) {
   const resources = /* @__PURE__ */ new Map();
   if (!existsSync3(directory)) return resources;
   const stat = lstatSync(directory);
@@ -16684,6 +16687,7 @@ function listNamedResources(registry, root, directory, logicalDirectory, kind) {
     }
     const id = basename(entry.name, ".yaml");
     if (kind === "model" && id === "inventory") continue;
+    if (id === replacedId) continue;
     if (!resourceIdentifier(id)) {
       issues.push(issue2("path", "resource_id_invalid", displayPath(root, join2(directory, entry.name)), `filename-derived identity ${id} is invalid or platform-reserved`));
       continue;
@@ -17284,6 +17288,9 @@ function assertNoRegisteredGates(options) {
   }
 }
 function loadKxmProject(projectRoot, options = {}) {
+  return loadProjectBundle(projectRoot, options);
+}
+function loadProjectBundle(projectRoot, options, workflowCandidate) {
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
   const legacyPresent = legacyConfigFilesAt(root);
@@ -17317,7 +17324,15 @@ function loadKxmProject(projectRoot, options = {}) {
   if (earlyIssues.length > 0) throw new KxmConfigError(earlyIssues);
   const agents = listNamedResources(registry, root, join2(root, ".kxm", "agents"), ".kxm/agents", "agent");
   const models = listNamedResources(registry, root, join2(root, ".kxm", "models"), ".kxm/models", "model");
-  const workflows = listNamedResources(registry, root, join2(root, ".kxm", "workflows"), ".kxm/workflows", "workflow");
+  const workflows = listNamedResources(registry, root, join2(root, ".kxm", "workflows"), ".kxm/workflows", "workflow", workflowCandidate?.id);
+  if (workflowCandidate) {
+    const { id, document } = workflowCandidate;
+    const logicalPath = `.kxm/workflows/${id}.yaml`;
+    if (!resourceIdentifier(id)) fail2("path", "resource_id_invalid", logicalPath, `filename-derived identity ${id} is invalid or platform-reserved`);
+    const collision = [...workflows.keys()].find((candidate) => candidate.toLocaleLowerCase("en-US") === id.toLocaleLowerCase("en-US"));
+    if (collision) fail2("path", "resource_id_collision", logicalPath, `${id} case-folds to existing ${collision}`);
+    workflows.set(id, { kind: "workflow", id, file: join2(root, logicalPath), logicalPath, value: resourceValue(registry, document, logicalPath, "workflow") });
+  }
   const gatePath = join2(root, ".kxm", "gates.yaml");
   const gateRegistry = existsSync3(gatePath) ? readResource(registry, root, gatePath, ".kxm/gates.yaml", "gate-registry") : void 0;
   const environments = [];

package/plugins/kxm/dist/runtime.js

@@ -16781,10 +16781,13 @@ function readResource(registry, root, file, logicalPath, kind, id, containmentRo
     parent = dirname2(parent);
   }
   if (!stat.isFile()) fail2("path", "resource_not_file", label, "configuration resource must be a regular file");
-  const value = parseRestrictedYaml2(readFileSync(file), label);
+  return { kind, ...id === void 0 ? {} : { id }, file, logicalPath, value: resourceValue(registry, readFileSync(file), label, kind) };
+}
+function resourceValue(registry, input, label, kind) {
+  const value = parseRestrictedYaml2(input, label);
   const issues = registry.validate(kind, value, label);
   if (issues.length > 0) throw new KxmConfigError(issues);
-  return { kind, ...id === void 0 ? {} : { id }, file, logicalPath, value };
+  return value;
 }
 function readTemplateProvenance(registry, root) {
   const file = join2(root, ".kxm", "template-provenance.yaml");
@@ -16833,7 +16836,7 @@ function readTemplateProvenance(registry, root) {
   }
   return value;
 }
-function listNamedResources(registry, root, directory, logicalDirectory, kind) {
+function listNamedResources(registry, root, directory, logicalDirectory, kind, replacedId) {
   const resources = /* @__PURE__ */ new Map();
   if (!existsSync3(directory)) return resources;
   const stat = lstatSync(directory);
@@ -16854,6 +16857,7 @@ function listNamedResources(registry, root, directory, logicalDirectory, kind) {
     }
     const id = basename(entry.name, ".yaml");
     if (kind === "model" && id === "inventory") continue;
+    if (id === replacedId) continue;
     if (!resourceIdentifier(id)) {
       issues.push(issue2("path", "resource_id_invalid", displayPath(root, join2(directory, entry.name)), `filename-derived identity ${id} is invalid or platform-reserved`));
       continue;
@@ -17454,6 +17458,9 @@ function assertNoRegisteredGates(options) {
   }
 }
 function loadKxmProject(projectRoot, options = {}) {
+  return loadProjectBundle(projectRoot, options);
+}
+function loadProjectBundle(projectRoot, options, workflowCandidate) {
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
   const legacyPresent = legacyConfigFilesAt(root);
@@ -17487,7 +17494,15 @@ function loadKxmProject(projectRoot, options = {}) {
   if (earlyIssues.length > 0) throw new KxmConfigError(earlyIssues);
   const agents = listNamedResources(registry, root, join2(root, ".kxm", "agents"), ".kxm/agents", "agent");
   const models = listNamedResources(registry, root, join2(root, ".kxm", "models"), ".kxm/models", "model");
-  const workflows = listNamedResources(registry, root, join2(root, ".kxm", "workflows"), ".kxm/workflows", "workflow");
+  const workflows = listNamedResources(registry, root, join2(root, ".kxm", "workflows"), ".kxm/workflows", "workflow", workflowCandidate?.id);
+  if (workflowCandidate) {
+    const { id, document } = workflowCandidate;
+    const logicalPath = `.kxm/workflows/${id}.yaml`;
+    if (!resourceIdentifier(id)) fail2("path", "resource_id_invalid", logicalPath, `filename-derived identity ${id} is invalid or platform-reserved`);
+    const collision = [...workflows.keys()].find((candidate) => candidate.toLocaleLowerCase("en-US") === id.toLocaleLowerCase("en-US"));
+    if (collision) fail2("path", "resource_id_collision", logicalPath, `${id} case-folds to existing ${collision}`);
+    workflows.set(id, { kind: "workflow", id, file: join2(root, logicalPath), logicalPath, value: resourceValue(registry, document, logicalPath, "workflow") });
+  }
   const gatePath = join2(root, ".kxm", "gates.yaml");
   const gateRegistry = existsSync3(gatePath) ? readResource(registry, root, gatePath, ".kxm/gates.yaml", "gate-registry") : void 0;
   const environments = [];

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.99",
+  "version": "0.7.100",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/cli/workflows.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
+import { stringify } from "yaml";
 import { openReadOnlyDatabase } from "../sqlite.ts";
 import { buildRetrospective, writeRetrospective } from "../retrospective.ts";
 import { redactSecrets } from "../redact.ts";
@@ -10,6 +11,7 @@ import {
   addWorkflowDefinition,
   removeWorkflowDefinition,
   modifyWorkflowDefinition,
+  parseWorkflowFile,
   scaffoldWorkflowDefinition,
   WORKFLOW_TEMPLATES,
 } from "../workflow-manager.ts";
@@ -21,7 +23,7 @@ import {
   type WorkflowJournalEntry,
   type WorkflowRun,
 } from "../workflow.ts";
-import { discoverKxmProjectRoot } from "../project-config.ts";
+import { discoverKxmProjectRoot, kxmWorkflowWriteIssues } from "../project-config.ts";
 import { ensureKxmSupervisor, kxmRuntimeRequest } from "../runtime-supervisor.ts";
 import { projectRuntimeOwnsRun } from "../runtime-store.ts";
 import type { WorkerOutcome } from "../envelope.ts";
@@ -213,12 +215,12 @@ export async function cmdWorkflowAdd(
   },
 ): Promise<number> {
   const scope = options.scope ?? "local";
+  const refuse = (error: string, text: string): number => {
+    print(runtime.io, runtime.json, { ok: false, command: "workflow add", error }, `workflow add failed: ${text}`);
+    return 2;
+  };
   let content: Record<string, unknown> | string | undefined;
   if (options.template !== undefined) {
-    const refuse = (error: string, text: string): number => {
-      print(runtime.io, runtime.json, { ok: false, command: "workflow add", error }, `workflow add failed: ${text}`);
-      return 2;
-    };
     if (options.file !== undefined || options.pick !== undefined) {
       return refuse("workflow_add_conflict", "--template cannot be combined with --file or --pick");
     }
@@ -238,8 +240,10 @@ export async function cmdWorkflowAdd(
     if (scope === "local") {
       const globalDefs = listWorkflowDefinitions({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
       for (const gd of globalDefs) {
-        if (!candidates.some((c) => c.id === gd.id)) {
-          candidates.push({ id: gd.id, description: gd.description, label: "global" });
+        // Read the listed file itself: it may be `.yml`, which a lookup by `<id>.yaml` misses.
+        const definition = parseWorkflowFile(gd.filePath);
+        if (definition && !candidates.some((c) => c.id === gd.id)) {
+          candidates.push({ id: gd.id, description: gd.description, label: "global", payload: definition });
         }
       }
     }
@@ -268,9 +272,30 @@ export async function cmdWorkflowAdd(
   }
 
   try {
-    const res = addWorkflowDefinition(workflowId!, content, {
+    const document = typeof content === "string" ? content : stringify(content);
+    // A local workflow is read by the project loader, which refuses the whole
+    // project over one bad file, so it is checked by that loader before it lands.
+    let repoRoot = runtime.cwd;
+    if (scope === "local") {
+      const projectRoot = discoverKxmProjectRoot(runtime.cwd);
+      if (!projectRoot) {
+        return refuse("project_not_found", "local workflows belong to a KXM project; run kxm init at the repository root, or pass --scope global");
+      }
+      const issues = kxmWorkflowWriteIssues(projectRoot, workflowId!, document);
+      if (issues.length > 0) {
+        print(
+          runtime.io,
+          runtime.json,
+          { ok: false, command: "workflow add", error: "workflow_invalid", issues },
+          `workflow add failed: with this workflow the project would not load, so nothing was written\n${issues.map((entry) => `  ${entry.file}: ${entry.code}: ${entry.message}`).join("\n")}`,
+        );
+        return 2;
+      }
+      repoRoot = projectRoot;
+    }
+    const res = addWorkflowDefinition(workflowId!, document, {
       scope,
-      repoRoot: runtime.cwd,
+      repoRoot,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
       overwrite: options.overwrite,
       dryRun: runtime.dryRun,

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.99";
+const VERSION = "0.7.100";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/project-config.ts

@@ -453,10 +453,14 @@ function readResource(
     parent = dirname(parent);
   }
   if (!stat.isFile()) fail("path", "resource_not_file", label, "configuration resource must be a regular file");
-  const value = parseRestrictedYaml(readFileSync(file), label);
+  return { kind, ...(id === undefined ? {} : { id }), file, logicalPath, value: resourceValue(registry, readFileSync(file), label, kind) };
+}
+
+function resourceValue(registry: KxmSchemaRegistry, input: string | Uint8Array, label: string, kind: KxmResourceKind): JsonObject {
+  const value = parseRestrictedYaml(input, label);
   const issues = registry.validate(kind, value, label);
   if (issues.length > 0) throw new KxmConfigError(issues);
-  return { kind, ...(id === undefined ? {} : { id }), file, logicalPath, value };
+  return value;
 }
 
 function readTemplateProvenance(registry: KxmSchemaRegistry, root: string): JsonObject | undefined {
@@ -513,6 +517,7 @@ function listNamedResources(
   directory: string,
   logicalDirectory: string,
   kind: "agent" | "model" | "workflow",
+  replacedId?: string,
 ): Map<string, KxmResource> {
   const resources = new Map<string, KxmResource>();
   if (!existsSync(directory)) return resources;
@@ -534,6 +539,7 @@ function listNamedResources(
     }
     const id = basename(entry.name, ".yaml");
     if (kind === "model" && id === "inventory") continue;
+    if (id === replacedId) continue;
     if (!resourceIdentifier(id)) {
       issues.push(issue("path", "resource_id_invalid", displayPath(root, join(directory, entry.name)), `filename-derived identity ${id} is invalid or platform-reserved`));
       continue;
@@ -1284,6 +1290,34 @@ export function assertNoRegisteredGates(options: object): void {
 
 /** Load and semantically validate one complete, path-derived KXM configuration bundle. */
 export function loadKxmProject(projectRoot: string, options: KxmConfigOptions = {}): KxmProjectBundle {
+  return loadProjectBundle(projectRoot, options);
+}
+
+/**
+ * What `loadKxmProject` would refuse once `.kxm/workflows/<workflowId>.yaml` held
+ * `document`, found without writing it: the same parser, schema and bundle rules,
+ * with `document` standing in for any file of that name.
+ */
+export function kxmWorkflowWriteIssues(
+  projectRoot: string,
+  workflowId: string,
+  document: string,
+  options: KxmConfigOptions = {},
+): readonly KxmConfigIssue[] {
+  try {
+    loadProjectBundle(projectRoot, options, { id: workflowId, document });
+    return [];
+  } catch (error) {
+    if (error instanceof KxmConfigError) return error.issues;
+    throw error;
+  }
+}
+
+function loadProjectBundle(
+  projectRoot: string,
+  options: KxmConfigOptions,
+  workflowCandidate?: { id: string; document: string },
+): KxmProjectBundle {
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
   const legacyPresent = legacyConfigFilesAt(root);
@@ -1323,7 +1357,15 @@ export function loadKxmProject(projectRoot: string, options: KxmConfigOptions =
 
   const agents = listNamedResources(registry, root, join(root, ".kxm", "agents"), ".kxm/agents", "agent");
   const models = listNamedResources(registry, root, join(root, ".kxm", "models"), ".kxm/models", "model");
-  const workflows = listNamedResources(registry, root, join(root, ".kxm", "workflows"), ".kxm/workflows", "workflow");
+  const workflows = listNamedResources(registry, root, join(root, ".kxm", "workflows"), ".kxm/workflows", "workflow", workflowCandidate?.id);
+  if (workflowCandidate) {
+    const { id, document } = workflowCandidate;
+    const logicalPath = `.kxm/workflows/${id}.yaml`;
+    if (!resourceIdentifier(id)) fail("path", "resource_id_invalid", logicalPath, `filename-derived identity ${id} is invalid or platform-reserved`);
+    const collision = [...workflows.keys()].find((candidate) => candidate.toLocaleLowerCase("en-US") === id.toLocaleLowerCase("en-US"));
+    if (collision) fail("path", "resource_id_collision", logicalPath, `${id} case-folds to existing ${collision}`);
+    workflows.set(id, { kind: "workflow", id, file: join(root, logicalPath), logicalPath, value: resourceValue(registry, document, logicalPath, "workflow") });
+  }
   const gatePath = join(root, ".kxm", "gates.yaml");
   const gateRegistry = existsSync(gatePath) ? readResource(registry, root, gatePath, ".kxm/gates.yaml", "gate-registry") : undefined;
   const environments: KxmResource[] = [];