@kontextmind/kxm 0.7.105 → 0.7.106

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.105",
+      "version": "0.7.106",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -345,6 +345,17 @@ All notable user-facing changes are documented here. The project follows [Semant
   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.
+- **`kxm role add --pick <global-id>` copies the global role.** In local scope, picking a
+  global role wrote an empty `Role <id>` with no skills or roster under its ID. It now
+  writes the global role's content, with `--description`, `--skills` and `--model`
+  replacing those fields the way they do for a built-in template.
+- **`kxm role add` no longer leaves a project that refuses to load.** A local add now needs
+  a KXM project (`project_not_found` otherwise, and no stray `.kxm/` that would make
+  `kxm init` refuse), writes under the project root from any subdirectory, and is checked
+  by the project loader first with the new role in place of any file of that ID. A
+  `writer` role whose roster leaves out the `implementer` agent's model, including the
+  built-in `writer` template for such a project, is refused with `role_invalid`, exit 2,
+  and nothing is written, also under `--dry-run`.
 - **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

@@ -67,6 +67,8 @@ to run one file is in [Develop KXM](development.md#run-one-file-or-one-test).
 | Explicit local YAML validates with runner schema/transitions; webhook environment sources retain JSON/secret checks | `gate-validation.test.ts` |
 | `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") |
+| `kxm role add --pick <global-id>` copies the global role into the project, not an empty role, with `--description`, `--skills` and `--model` applied over it | `role-and-workflow-manager.test.ts` ("role add --pick <global-id> copies that global role into the project, with --description, --skills and --model applied over it") |
+| `kxm role add` writes a local role only at the project root and only if the project still loads, so a `writer` roster without the implementer's model is refused; outside a project it refuses | `role-and-workflow-manager.test.ts` ("role add writes a local role only at the project root, and only if the project loader accepts it") |
 | `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

@@ -1197,7 +1197,7 @@ Not run with a configured role; in a fresh project it exits 1 with `kxm: role 'w
 kxm role add [roleId] [--file <path>] [--description <text>] [--skills <skills>] [--harness <harness>] [--model <model>] [--scope global|local] [--overwrite] [--pick [selection]]
 ```
 
-Adds a role definition. Without a role ID, or with `--pick`, you choose from the built-in templates (`writer`, `planner`, `critic-arch`, `critic-cli`, `verifier`) and, for local scope, existing global roles. With `--file`, the YAML file is used and its `id` is replaced by the role ID.
+Adds a role definition. Without a role ID, or with `--pick`, you choose from the built-in templates (`writer`, `planner`, `critic-arch`, `critic-cli`, `verifier`) and, for local scope, existing global roles; a global role 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 role's file, with `--description`, `--skills`, and `--model` (with `--harness`) replacing its description, skills, and roster. With `--file`, the YAML file is used and its `id` is replaced by the role ID. Otherwise a role with only the given options is written.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
@@ -1211,6 +1211,8 @@ Adds a role definition. Without a role ID, or with `--pick`, you choose from the
 | `--pick` | `[selection]` | none | Pick from available role templates (index or id) |
 
 - Writes `<scope dir>/roles/<id>.yaml`. `--dry-run` plans the write and writes nothing.
+- Local scope belongs to a KXM project: the file lands in the project root's `.kxm/roles/` 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 role in place of any file of that ID. The loader reads only `writer.yaml`, whose enabled roster must include the `implementer` agent's model (see [Roles](config-reference.md#kxmrolesroleyaml-kxmrolev1)). If the project would not load, the command refuses with `role_invalid`, lists each issue and writes nothing, also under `--dry-run`, and `--overwrite` replaces a `writer.yaml` the loader refuses. Global scope is not checked, because no loader reads it.
+- Refusals exit 2 and honor `--json`: `project_not_found` and `role_invalid` (with `issues`, each `{phase, code, file, message}`). An existing role without `--overwrite` exits 1 with a plain `role add failed: role_already_exists: ...` line, also under `--dry-run`.
 - JSON keys: `roleId`, `id`, `filePath`, `scope`.
 
 > [!WARNING]

package/docs/reference/config-reference.md

@@ -965,7 +965,7 @@ read different fields:
 |---|---|---|---|
 | Project loader (`validateBundle`) | `.kxm/roles/writer.yaml` only | `roster[].model`, `roster[].enabled` | Cross-checks the writer roster against the `implementer` agent's model (see below). Parsed as restricted YAML. |
 | Runtime route check (`listRoleBindings` in `plugins/kxm/src/routes.ts`) | `.kxm/roles/<role>.yaml`, role = agent ID, `writer` for `implementer` | `roster[].model` | The agent's `provider/model` must appear exactly. `enabled` is ignored, so a disabled entry still admits. The role name comes from the filename. |
-| `kxm role` commands (`plugins/kxm/src/role.ts`) | `.kxm/roles/*.yaml` and `~/.config/kxm/roles/*.yaml` | Everything below | Listing and editing only. A file without `schema: kxm.role.v1` is silently skipped. A local file overrides a global one with the same ID. |
+| `kxm role` commands (`plugins/kxm/src/role.ts`) | `.kxm/roles/*.yaml` and `~/.config/kxm/roles/*.yaml` | Everything below | Listing and editing only. A file without `schema: kxm.role.v1` is silently skipped. A local file overrides a global one with the same ID. A local `kxm role add` runs the project loader check above first and refuses with `role_invalid` a role the loader would reject. |
 
 The loader check applies when the agent `implementer` (or else `writer`)
 declares a model and the roster has at least one enabled entry. One enabled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.105",
+  "version": "0.7.106",
   "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.105",
+  "version": "0.7.106",
   "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

@@ -23246,7 +23246,7 @@ function validateModelReferences(models, issues) {
   };
   for (const id of models.keys()) walk(id, []);
 }
-function validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, projectRoot) {
+function validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, projectRoot, writerRole) {
   const issues = [];
   const entries = valuesOf(project.value, "repositories").map((candidate) => objectValue(candidate)).filter((candidate) => Boolean(candidate));
   const repositoryIds = /* @__PURE__ */ new Set();
@@ -23317,9 +23317,9 @@ function validateBundle(project, repositories, agents, models, workflows, enviro
   if (projectRoot) {
     const writerRolePath = join6(projectRoot, ".kxm", "roles", "writer.yaml");
     const implementerAgent = agents.get("implementer") ?? agents.get("writer");
-    if (existsSync6(writerRolePath) && implementerAgent) {
+    if ((writerRole !== void 0 || existsSync6(writerRolePath)) && implementerAgent) {
       try {
-        const rawRole = parseRestrictedYaml2(readFileSync5(writerRolePath, "utf8"));
+        const rawRole = parseRestrictedYaml2(writerRole ?? readFileSync5(writerRolePath, "utf8"));
         const roleObj = objectValue(rawRole);
         const rosterEntries = valuesOf(roleObj ?? {}, "roster").map((candidate) => objectValue(candidate)).filter((entry) => Boolean(entry));
         const enabledRosterModels = rosterEntries.filter((entry) => entry.enabled !== false).map((entry) => stringValue(entry.model)).filter((m2) => Boolean(m2));
@@ -23390,15 +23390,23 @@ function loadKxmProject(projectRoot, options = {}) {
   return loadProjectBundle(projectRoot, options);
 }
 function kxmWorkflowWriteIssues(projectRoot, workflowId, document, options = {}) {
+  return candidateIssues(projectRoot, options, { kind: "workflow", id: workflowId, document });
+}
+function kxmRoleWriteIssues(projectRoot, roleId, document, options = {}) {
+  return candidateIssues(projectRoot, options, { kind: "role", id: roleId, document });
+}
+function candidateIssues(projectRoot, options, candidate) {
   try {
-    loadProjectBundle(projectRoot, options, { id: workflowId, document });
+    loadProjectBundle(projectRoot, options, candidate);
     return [];
   } catch (error) {
     if (error instanceof KxmConfigError) return error.issues;
     throw error;
   }
 }
-function loadProjectBundle(projectRoot, options, workflowCandidate) {
+function loadProjectBundle(projectRoot, options, candidate) {
+  const workflowCandidate = candidate?.kind === "workflow" ? candidate : void 0;
+  const writerRole = candidate?.kind === "role" && candidate.id.toLocaleLowerCase("en-US") === "writer" ? candidate.document : void 0;
   assertNoRegisteredGates(options);
   const root = resolve3(projectRoot);
   const legacyPresent = legacyConfigFilesAt(root);
@@ -23421,7 +23429,7 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
       earlyIssues.push(issue2("semantic", "template_provenance_project_mismatch", ".kxm/template-provenance.yaml", "template provenance belongs to a different project identity"));
     }
   }
-  const declaredRepositoryIds = new Set(valuesOf(project.value, "repositories").map((candidate) => stringValue(objectValue(candidate)?.id)).filter((candidate) => candidate !== void 0));
+  const declaredRepositoryIds = new Set(valuesOf(project.value, "repositories").map((candidate2) => stringValue(objectValue(candidate2)?.id)).filter((candidate2) => candidate2 !== void 0));
   for (const repositoryId of Object.keys(options.repositoryBindings ?? {}).sort(compareCodeUnits3)) {
     if (!resourceIdentifier(repositoryId)) {
       earlyIssues.push(issue2("path", "repository_binding_id_invalid", ".kxm/project.yaml", `host-local binding identity ${repositoryId} is invalid`));
@@ -23437,7 +23445,7 @@ function loadProjectBundle(projectRoot, options, 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"));
+    const collision = [...workflows.keys()].find((candidate2) => candidate2.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") });
   }
@@ -23456,8 +23464,8 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
     }
   }
   const seenBindings = /* @__PURE__ */ new Map();
-  for (const candidate of valuesOf(project.value, "repositories")) {
-    const entry = objectValue(candidate);
+  for (const candidate2 of valuesOf(project.value, "repositories")) {
+    const entry = objectValue(candidate2);
     const repositoryId = entry && stringValue(entry.id);
     const pathHint = entry && stringValue(entry.pathHint);
     const role = entry && stringValue(entry.role);
@@ -23554,7 +23562,7 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
     }
   }
   if (loadIssues.length > 0) throw new KxmConfigError(loadIssues);
-  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root);
+  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root, writerRole);
   if (issues.length > 0) throw new KxmConfigError(issues);
   const resources = [project, ...repositories.values(), ...agents.values(), ...models.values(), ...workflows.values(), ...environments, ...gateRegistry ? [gateRegistry] : []].sort((left, right) => compareCodeUnits3(left.logicalPath, right.logicalPath));
   return {
@@ -29074,6 +29082,7 @@ async function cmdRoleGet(runtime, roleId, options) {
 }
 async function cmdRoleAdd(runtime, roleId, options) {
   const scope = options.scope ?? "local";
+  let base;
   if (!roleId || options.pick) {
     const candidates = Object.values(DEFAULT_ROLES).map((r) => ({
       id: r.id,
@@ -29084,8 +29093,9 @@ async function cmdRoleAdd(runtime, roleId, options) {
     if (scope === "local") {
       const globalRoles = listRoles({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
       for (const gr of globalRoles) {
-        if (!candidates.some((c) => c.id === gr.id)) {
-          candidates.push({ id: gr.id, description: gr.description, label: "global", payload: gr });
+        const definition = parseRoleFile(gr.filePath);
+        if (definition && !candidates.some((c) => c.id === gr.id)) {
+          candidates.push({ id: gr.id, description: gr.description, label: "global", payload: definition });
         }
       }
     }
@@ -29097,63 +29107,62 @@ async function cmdRoleAdd(runtime, roleId, options) {
       }
     } else {
       roleId = picked.id;
-      if (!options.file && picked.payload && DEFAULT_ROLES[picked.id]) {
-        const base = DEFAULT_ROLES[picked.id];
-        const roleDef2 = {
-          ...base,
-          description: options.description || base.description,
-          skills: options.skills ? options.skills.split(",").map((s) => s.trim()).filter(Boolean) : base.skills,
-          roster: options.model ? [{ harness: options.harness ?? "pi", model: options.model }] : base.roster
-        };
-        try {
-          const res = addRole(roleDef2, {
-            scope,
-            repoRoot: runtime.cwd,
-            userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
-            overwrite: options.overwrite,
-            dryRun: runtime.dryRun
-          });
-          if (runtime.dryRun) {
-            printPlan(runtime, { command: "role add", roleId, ...res }, [{ action: "write", target: res.filePath }], `add role '${roleId}' to ${res.scope}`);
-            return 0;
-          }
-          print(
-            runtime.io,
-            runtime.json,
-            { ok: true, command: "role add", roleId, ...res },
-            `Added role '${roleId}' to ${res.scope} (${res.filePath})
-`
-          );
-          return 0;
-        } catch (err) {
-          runtime.io.stderr(`role add failed: ${err.message}
-`);
-          return 1;
-        }
-      }
+      base = picked.payload;
     }
   }
+  const skills = options.skills ? options.skills.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+  const roster = options.model ? [{ harness: options.harness ?? "pi", model: options.model }] : void 0;
   let roleDef;
   if (options.file) {
     const filePath = resolve15(runtime.cwd, options.file);
     const content = readFileSync19(filePath, "utf8");
     roleDef = (0, import_yaml10.parse)(content);
     roleDef.id = roleId;
+  } else if (base) {
+    roleDef = {
+      ...base,
+      description: options.description || base.description,
+      skills: skills ?? base.skills,
+      roster: roster ?? base.roster
+    };
   } else {
-    const skills = options.skills ? options.skills.split(",").map((s) => s.trim()).filter(Boolean) : [];
-    const roster = options.model ? [{ harness: options.harness ?? "pi", model: options.model }] : [];
     roleDef = {
       schema: "kxm.role.v1",
       id: roleId,
       description: options.description || `Role ${roleId}`,
-      skills,
-      roster
+      skills: skills ?? [],
+      roster: roster ?? []
     };
   }
+  let repoRoot = runtime.cwd;
+  if (scope === "local") {
+    const projectRoot = discoverKxmProjectRoot(runtime.cwd);
+    if (!projectRoot) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "role add", error: "project_not_found" },
+        "role add failed: local roles belong to a KXM project; run kxm init at the repository root, or pass --scope global"
+      );
+      return 2;
+    }
+    const issues = kxmRoleWriteIssues(projectRoot, roleDef.id, (0, import_yaml10.stringify)(roleDef));
+    if (issues.length > 0) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "role add", error: "role_invalid", issues },
+        `role add failed: with this role the project would not load, so nothing was written
+${issues.map((entry) => `  ${entry.file}: ${entry.code}: ${entry.message}`).join("\n")}`
+      );
+      return 2;
+    }
+    repoRoot = projectRoot;
+  }
   try {
     const res = addRole(roleDef, {
       scope,
-      repoRoot: runtime.cwd,
+      repoRoot,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
       overwrite: options.overwrite,
       dryRun: runtime.dryRun

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

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

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

@@ -17151,7 +17151,7 @@ function validateModelReferences(models, issues) {
   };
   for (const id of models.keys()) walk(id, []);
 }
-function validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, projectRoot) {
+function validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, projectRoot, writerRole) {
   const issues = [];
   const entries = valuesOf(project.value, "repositories").map((candidate) => objectValue(candidate)).filter((candidate) => Boolean(candidate));
   const repositoryIds = /* @__PURE__ */ new Set();
@@ -17222,9 +17222,9 @@ function validateBundle(project, repositories, agents, models, workflows, enviro
   if (projectRoot) {
     const writerRolePath = join2(projectRoot, ".kxm", "roles", "writer.yaml");
     const implementerAgent = agents.get("implementer") ?? agents.get("writer");
-    if (existsSync3(writerRolePath) && implementerAgent) {
+    if ((writerRole !== void 0 || existsSync3(writerRolePath)) && implementerAgent) {
       try {
-        const rawRole = parseRestrictedYaml2(readFileSync(writerRolePath, "utf8"));
+        const rawRole = parseRestrictedYaml2(writerRole ?? readFileSync(writerRolePath, "utf8"));
         const roleObj = objectValue(rawRole);
         const rosterEntries = valuesOf(roleObj ?? {}, "roster").map((candidate) => objectValue(candidate)).filter((entry) => Boolean(entry));
         const enabledRosterModels = rosterEntries.filter((entry) => entry.enabled !== false).map((entry) => stringValue(entry.model)).filter((m) => Boolean(m));
@@ -17290,7 +17290,9 @@ function assertNoRegisteredGates(options) {
 function loadKxmProject(projectRoot, options = {}) {
   return loadProjectBundle(projectRoot, options);
 }
-function loadProjectBundle(projectRoot, options, workflowCandidate) {
+function loadProjectBundle(projectRoot, options, candidate) {
+  const workflowCandidate = candidate?.kind === "workflow" ? candidate : void 0;
+  const writerRole = candidate?.kind === "role" && candidate.id.toLocaleLowerCase("en-US") === "writer" ? candidate.document : void 0;
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
   const legacyPresent = legacyConfigFilesAt(root);
@@ -17313,7 +17315,7 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
       earlyIssues.push(issue2("semantic", "template_provenance_project_mismatch", ".kxm/template-provenance.yaml", "template provenance belongs to a different project identity"));
     }
   }
-  const declaredRepositoryIds = new Set(valuesOf(project.value, "repositories").map((candidate) => stringValue(objectValue(candidate)?.id)).filter((candidate) => candidate !== void 0));
+  const declaredRepositoryIds = new Set(valuesOf(project.value, "repositories").map((candidate2) => stringValue(objectValue(candidate2)?.id)).filter((candidate2) => candidate2 !== void 0));
   for (const repositoryId of Object.keys(options.repositoryBindings ?? {}).sort(compareCodeUnits3)) {
     if (!resourceIdentifier(repositoryId)) {
       earlyIssues.push(issue2("path", "repository_binding_id_invalid", ".kxm/project.yaml", `host-local binding identity ${repositoryId} is invalid`));
@@ -17329,7 +17331,7 @@ function loadProjectBundle(projectRoot, options, 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"));
+    const collision = [...workflows.keys()].find((candidate2) => candidate2.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") });
   }
@@ -17348,8 +17350,8 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
     }
   }
   const seenBindings = /* @__PURE__ */ new Map();
-  for (const candidate of valuesOf(project.value, "repositories")) {
-    const entry = objectValue(candidate);
+  for (const candidate2 of valuesOf(project.value, "repositories")) {
+    const entry = objectValue(candidate2);
     const repositoryId = entry && stringValue(entry.id);
     const pathHint = entry && stringValue(entry.pathHint);
     const role = entry && stringValue(entry.role);
@@ -17446,7 +17448,7 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
     }
   }
   if (loadIssues.length > 0) throw new KxmConfigError(loadIssues);
-  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root);
+  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root, writerRole);
   if (issues.length > 0) throw new KxmConfigError(issues);
   const resources = [project, ...repositories.values(), ...agents.values(), ...models.values(), ...workflows.values(), ...environments, ...gateRegistry ? [gateRegistry] : []].sort((left, right) => compareCodeUnits3(left.logicalPath, right.logicalPath));
   return {

package/plugins/kxm/dist/runtime.js

@@ -17321,7 +17321,7 @@ function validateModelReferences(models, issues) {
   };
   for (const id of models.keys()) walk(id, []);
 }
-function validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, projectRoot) {
+function validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, projectRoot, writerRole) {
   const issues = [];
   const entries = valuesOf(project.value, "repositories").map((candidate) => objectValue(candidate)).filter((candidate) => Boolean(candidate));
   const repositoryIds = /* @__PURE__ */ new Set();
@@ -17392,9 +17392,9 @@ function validateBundle(project, repositories, agents, models, workflows, enviro
   if (projectRoot) {
     const writerRolePath = join2(projectRoot, ".kxm", "roles", "writer.yaml");
     const implementerAgent = agents.get("implementer") ?? agents.get("writer");
-    if (existsSync3(writerRolePath) && implementerAgent) {
+    if ((writerRole !== void 0 || existsSync3(writerRolePath)) && implementerAgent) {
       try {
-        const rawRole = parseRestrictedYaml2(readFileSync(writerRolePath, "utf8"));
+        const rawRole = parseRestrictedYaml2(writerRole ?? readFileSync(writerRolePath, "utf8"));
         const roleObj = objectValue(rawRole);
         const rosterEntries = valuesOf(roleObj ?? {}, "roster").map((candidate) => objectValue(candidate)).filter((entry) => Boolean(entry));
         const enabledRosterModels = rosterEntries.filter((entry) => entry.enabled !== false).map((entry) => stringValue(entry.model)).filter((m) => Boolean(m));
@@ -17460,7 +17460,9 @@ function assertNoRegisteredGates(options) {
 function loadKxmProject(projectRoot, options = {}) {
   return loadProjectBundle(projectRoot, options);
 }
-function loadProjectBundle(projectRoot, options, workflowCandidate) {
+function loadProjectBundle(projectRoot, options, candidate) {
+  const workflowCandidate = candidate?.kind === "workflow" ? candidate : void 0;
+  const writerRole = candidate?.kind === "role" && candidate.id.toLocaleLowerCase("en-US") === "writer" ? candidate.document : void 0;
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
   const legacyPresent = legacyConfigFilesAt(root);
@@ -17483,7 +17485,7 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
       earlyIssues.push(issue2("semantic", "template_provenance_project_mismatch", ".kxm/template-provenance.yaml", "template provenance belongs to a different project identity"));
     }
   }
-  const declaredRepositoryIds = new Set(valuesOf(project.value, "repositories").map((candidate) => stringValue(objectValue(candidate)?.id)).filter((candidate) => candidate !== void 0));
+  const declaredRepositoryIds = new Set(valuesOf(project.value, "repositories").map((candidate2) => stringValue(objectValue(candidate2)?.id)).filter((candidate2) => candidate2 !== void 0));
   for (const repositoryId of Object.keys(options.repositoryBindings ?? {}).sort(compareCodeUnits3)) {
     if (!resourceIdentifier(repositoryId)) {
       earlyIssues.push(issue2("path", "repository_binding_id_invalid", ".kxm/project.yaml", `host-local binding identity ${repositoryId} is invalid`));
@@ -17499,7 +17501,7 @@ function loadProjectBundle(projectRoot, options, 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"));
+    const collision = [...workflows.keys()].find((candidate2) => candidate2.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") });
   }
@@ -17518,8 +17520,8 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
     }
   }
   const seenBindings = /* @__PURE__ */ new Map();
-  for (const candidate of valuesOf(project.value, "repositories")) {
-    const entry = objectValue(candidate);
+  for (const candidate2 of valuesOf(project.value, "repositories")) {
+    const entry = objectValue(candidate2);
     const repositoryId = entry && stringValue(entry.id);
     const pathHint = entry && stringValue(entry.pathHint);
     const role = entry && stringValue(entry.role);
@@ -17616,7 +17618,7 @@ function loadProjectBundle(projectRoot, options, workflowCandidate) {
     }
   }
   if (loadIssues.length > 0) throw new KxmConfigError(loadIssues);
-  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root);
+  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root, writerRole);
   if (issues.length > 0) throw new KxmConfigError(issues);
   const resources = [project, ...repositories.values(), ...agents.values(), ...models.values(), ...workflows.values(), ...environments, ...gateRegistry ? [gateRegistry] : []].sort((left, right) => compareCodeUnits3(left.logicalPath, right.logicalPath));
   return {

package/plugins/kxm/package.json

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

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

@@ -15,9 +15,10 @@ import {
   loadRoleHostsConfig,
   setRoleSeatHost,
   resolveRoleSeat,
+  parseRoleFile,
   type KxmRoleDefinition,
 } from "../role.ts";
-import { discoverKxmProjectRoot } from "../project-config.ts";
+import { discoverKxmProjectRoot, kxmRoleWriteIssues } from "../project-config.ts";
 import { ensureKxmSupervisor, kxmRuntimeRequest } from "../runtime-supervisor.ts";
 import { projectRuntimeOwnsRun } from "../runtime-store.ts";
 import { resumeWorkflowFromRuling, type WorkflowRun } from "../workflow.ts";
@@ -156,6 +157,7 @@ export async function cmdRoleAdd(
   },
 ): Promise<number> {
   const scope = options.scope ?? "local";
+  let base: KxmRoleDefinition | undefined;
   if (!roleId || options.pick) {
     const candidates: PickCandidate[] = Object.values(DEFAULT_ROLES).map((r) => ({
       id: r.id,
@@ -166,8 +168,10 @@ export async function cmdRoleAdd(
     if (scope === "local") {
       const globalRoles = listRoles({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
       for (const gr of globalRoles) {
-        if (!candidates.some((c) => c.id === gr.id)) {
-          candidates.push({ id: gr.id, description: gr.description, label: "global", payload: gr });
+        // The listing is a summary; the copy needs the definition, read from the listed file (it may be `.yml`).
+        const definition = parseRoleFile(gr.filePath);
+        if (definition && !candidates.some((c) => c.id === gr.id)) {
+          candidates.push({ id: gr.id, description: gr.description, label: "global", payload: definition });
         }
       }
     }
@@ -179,63 +183,66 @@ export async function cmdRoleAdd(
       }
     } else {
       roleId = picked.id;
-      if (!options.file && picked.payload && DEFAULT_ROLES[picked.id]) {
-        const base = DEFAULT_ROLES[picked.id]!;
-        const roleDef: KxmRoleDefinition = {
-          ...base,
-          description: options.description || base.description,
-          skills: options.skills ? options.skills.split(",").map((s) => s.trim()).filter(Boolean) : base.skills,
-          roster: options.model ? [{ harness: options.harness ?? "pi", model: options.model }] : base.roster,
-        };
-        try {
-          const res = addRole(roleDef, {
-            scope,
-            repoRoot: runtime.cwd,
-            userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
-            overwrite: options.overwrite,
-            dryRun: runtime.dryRun,
-          });
-          if (runtime.dryRun) {
-            printPlan(runtime, { command: "role add", roleId, ...res }, [{ action: "write", target: res.filePath }], `add role '${roleId}' to ${res.scope}`);
-            return 0;
-          }
-          print(
-            runtime.io,
-            runtime.json,
-            { ok: true, command: "role add", roleId, ...res },
-            `Added role '${roleId}' to ${res.scope} (${res.filePath})\n`,
-          );
-          return 0;
-        } catch (err: unknown) {
-          runtime.io.stderr(`role add failed: ${(err as Error).message}\n`);
-          return 1;
-        }
-      }
+      base = picked.payload as KxmRoleDefinition;
     }
   }
 
+  const skills = options.skills ? options.skills.split(",").map((s) => s.trim()).filter(Boolean) : undefined;
+  const roster = options.model ? [{ harness: options.harness ?? "pi", model: options.model }] : undefined;
   let roleDef: KxmRoleDefinition;
   if (options.file) {
     const filePath = resolve(runtime.cwd, options.file);
     const content = readFileSync(filePath, "utf8");
     roleDef = parseYaml(content) as KxmRoleDefinition;
     roleDef.id = roleId!;
+  } else if (base) {
+    roleDef = {
+      ...base,
+      description: options.description || base.description,
+      skills: skills ?? base.skills,
+      roster: roster ?? base.roster,
+    };
   } else {
-    const skills = options.skills ? options.skills.split(",").map((s) => s.trim()).filter(Boolean) : [];
-    const roster = options.model ? [{ harness: options.harness ?? "pi", model: options.model }] : [];
     roleDef = {
       schema: "kxm.role.v1",
       id: roleId!,
       description: options.description || `Role ${roleId}`,
-      skills,
-      roster,
+      skills: skills ?? [],
+      roster: roster ?? [],
     };
   }
 
+  // A local role file sits in the project the loader reads, and the loader refuses the
+  // whole project over a writer roster it rejects, so the role is checked before it lands.
+  let repoRoot = runtime.cwd;
+  if (scope === "local") {
+    const projectRoot = discoverKxmProjectRoot(runtime.cwd);
+    if (!projectRoot) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "role add", error: "project_not_found" },
+        "role add failed: local roles belong to a KXM project; run kxm init at the repository root, or pass --scope global",
+      );
+      return 2;
+    }
+    const issues = kxmRoleWriteIssues(projectRoot, roleDef.id, stringifyYaml(roleDef));
+    if (issues.length > 0) {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "role add", error: "role_invalid", issues },
+        `role add failed: with this role 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;
+  }
+
   try {
     const res = addRole(roleDef, {
       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.105";
+const VERSION = "0.7.106";
 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

@@ -1124,6 +1124,7 @@ function validateBundle(
   options: KxmConfigOptions,
   gateRegistry?: KxmResource,
   projectRoot?: string,
+  writerRole?: string,
 ): KxmConfigIssue[] {
   const issues: KxmConfigIssue[] = [];
   const entries = valuesOf(project.value, "repositories").map((candidate) => objectValue(candidate)).filter((candidate): candidate is JsonObject => Boolean(candidate));
@@ -1200,9 +1201,9 @@ function validateBundle(
   if (projectRoot) {
     const writerRolePath = join(projectRoot, ".kxm", "roles", "writer.yaml");
     const implementerAgent = agents.get("implementer") ?? agents.get("writer");
-    if (existsSync(writerRolePath) && implementerAgent) {
+    if ((writerRole !== undefined || existsSync(writerRolePath)) && implementerAgent) {
       try {
-        const rawRole = parseRestrictedYaml(readFileSync(writerRolePath, "utf8"));
+        const rawRole = parseRestrictedYaml(writerRole ?? readFileSync(writerRolePath, "utf8"));
         const roleObj = objectValue(rawRole);
         const rosterEntries = valuesOf(roleObj ?? {}, "roster")
           .map((candidate) => objectValue(candidate))
@@ -1304,8 +1305,32 @@ export function kxmWorkflowWriteIssues(
   document: string,
   options: KxmConfigOptions = {},
 ): readonly KxmConfigIssue[] {
+  return candidateIssues(projectRoot, options, { kind: "workflow", id: workflowId, document });
+}
+
+/**
+ * What `loadKxmProject` would refuse once `.kxm/roles/<roleId>.yaml` held `document`,
+ * found without writing it. The loader reads only the writer role, so for any other
+ * id this is the project's load as it stands.
+ */
+export function kxmRoleWriteIssues(
+  projectRoot: string,
+  roleId: string,
+  document: string,
+  options: KxmConfigOptions = {},
+): readonly KxmConfigIssue[] {
+  return candidateIssues(projectRoot, options, { kind: "role", id: roleId, document });
+}
+
+interface WriteCandidate {
+  kind: "workflow" | "role";
+  id: string;
+  document: string;
+}
+
+function candidateIssues(projectRoot: string, options: KxmConfigOptions, candidate: WriteCandidate): readonly KxmConfigIssue[] {
   try {
-    loadProjectBundle(projectRoot, options, { id: workflowId, document });
+    loadProjectBundle(projectRoot, options, candidate);
     return [];
   } catch (error) {
     if (error instanceof KxmConfigError) return error.issues;
@@ -1316,8 +1341,11 @@ export function kxmWorkflowWriteIssues(
 function loadProjectBundle(
   projectRoot: string,
   options: KxmConfigOptions,
-  workflowCandidate?: { id: string; document: string },
+  candidate?: WriteCandidate,
 ): KxmProjectBundle {
+  const workflowCandidate = candidate?.kind === "workflow" ? candidate : undefined;
+  // A case-insensitive filesystem serves `Writer.yaml` to the loader's `writer.yaml` lookup.
+  const writerRole = candidate?.kind === "role" && candidate.id.toLocaleLowerCase("en-US") === "writer" ? candidate.document : undefined;
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
   const legacyPresent = legacyConfigFilesAt(root);
@@ -1484,7 +1512,7 @@ function loadProjectBundle(
   }
   if (loadIssues.length > 0) throw new KxmConfigError(loadIssues);
 
-  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root);
+  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root, writerRole);
   if (issues.length > 0) throw new KxmConfigError(issues);
   const resources = [project, ...repositories.values(), ...agents.values(), ...models.values(), ...workflows.values(), ...environments, ...(gateRegistry ? [gateRegistry] : [])]
     .sort((left, right) => compareCodeUnits(left.logicalPath, right.logicalPath));