arcane-cli 0.22.3 → 0.22.4

package/dist/assets/.arcane/governance/naming-conventions.md

@@ -92,6 +92,19 @@ Arcane ships with twelve default agent personas, organized by functional cluster
 
 Twelve legendary agents — the Arcanos. Every namesake is public domain: golden-age stage magicians (Kellar, Lafayette, Adelaide, Alexander, Bess), myth and classic literature (Merlin, Circe, Iris, Prospero, Mercurio), and coinages from living vocabulary (Lince — *ojo de lince*; Custodio — *ángel custodio*). Lince is never anglicized.
 
+### Agent Definition Schema — Fields for Template/Renderer Authors
+
+The table above is the human-readable roster; agent definitions (`agents/*.yaml`) and the generated roster (`.arcane/agents.yaml`) carry the same data as structured fields. This is where they live, for anyone building a third-party renderer (DMC is renderer #1):
+
+| Field | Lives on | Populated by | Consumed by |
+| --- | --- | --- | --- |
+| `persona.description` / `behavioral_rules` | Agent definition (role-level, naming-strategy-agnostic) | Template author | Every client renderer (Copilot, Claude, Codex, OpenClaw) |
+| `persona.personality` / `persona.voice` / `persona.catchphrases` | Agent definition | Template author | Renderers that want tone/flavor beyond the bare role |
+| `persona.visual_description` | Agent definition | Template author | **Declared, not yet rendered by any client this repo ships.** Kept with the definition rather than a renderer, by design — data belongs with the thing it describes, not with any one consumer. A third-party image/avatar renderer reads this field directly from the YAML; no other wiring is required. |
+| `epithet` (e.g. "the Archmage") | **Roster entry**, not the agent definition — see below | Naming strategy (`arcanos` only; `generic`/`random`/`custom` are deliberately epithet-less) | `.arcane/generated/openclaw-roster.json`'s `identity.epithet`, when present |
+
+**Why `epithet` is schema v2's roster field, not a persona field:** an agent definition YAML (e.g. `architecture-lead.yaml`) is a role archetype reused across every naming strategy — "the Archmage" belongs to the persona *Merlin*, not to the "architecture-lead" role itself. Putting it in the definition would leak Arcanos-specific flavor into naming strategies designed to be epithet-neutral (`generic`'s plain role labels). It is populated during `spell agents init`'s naming step and flows through the roster entry (`.arcane/agents.yaml`) to `openclaw-roster.json` — never guessed or re-derived by a renderer.
+
 **Role consolidation (ADR-031):** Framework-specific dev roles (.NET, Blazor, React, Flutter, MAUI) are consolidated into generic roles (Full-Stack, Frontend, Mobile). The framework/stack is a prompt parameter, not an agent identity. This scales without needing a new agent for every technology.
 
 **Naming policy:** All agent names should be positive characters — beings, not objects — with a clear thematic connection to their role.

package/dist/assets/.github/agents/mercurio.agent.md

@@ -35,7 +35,7 @@ deliverables; every word in motion.
 - Follow platform guidelines (HIG for iOS, Material Design for Android)
 - App store submissions require a complete release checklist — no shortcuts
 - Performance profiling is required before marking any feature complete
-- [object Object]
+- Backward compatibility: support at least the two previous major OS versions
 
 ## Tools
 

package/dist/index.js

@@ -946,6 +946,20 @@ var ARCANOS_NAME_MAP = {
   "collaborator": "Iris",
   "security-ops": "Custodio"
 };
+var ARCANOS_EPITHET_MAP = {
+  "orchestrator": "the Maestro",
+  "architecture-lead": "the Archmage",
+  "fullstack-dev": "the Conjuror",
+  "qa-lead": "the Unmasker",
+  "devops": "the Stormcaller",
+  "frontend-dev": "the Illusionist",
+  "mobile-dev": "the Swift",
+  "research-analyst": "the Man Who Knows",
+  "marketing-strategist": "the Charmweaver",
+  "operations-comms": "the Herald",
+  "collaborator": "the Emissary",
+  "security-ops": "the Warden"
+};
 var RANDOM_NAME_POOL = [
   "Aiden",
   "Blake",
@@ -985,10 +999,11 @@ function applyGenericNames(roleIds) {
   }));
 }
 function applyArcanosNames(roleIds) {
-  return roleIds.map((id) => ({
-    definition: id,
-    name: ARCANOS_NAME_MAP[id] ?? GENERIC_NAME_MAP[id] ?? id
-  }));
+  return roleIds.map((id) => {
+    const name = ARCANOS_NAME_MAP[id] ?? GENERIC_NAME_MAP[id] ?? id;
+    const epithet = ARCANOS_NAME_MAP[id] ? ARCANOS_EPITHET_MAP[id] : void 0;
+    return epithet ? { definition: id, name, epithet } : { definition: id, name };
+  });
 }
 function applyRandomNames(roleIds) {
   const shuffled = [...RANDOM_NAME_POOL].sort(() => Math.random() - 0.5);
@@ -1182,6 +1197,7 @@ function validateAgentRoster(value, source) {
       requireString(item.definition, `roster[${index}].definition`, issues);
       if (item.name !== null) requireString(item.name, `roster[${index}].name`, issues);
       requireString(item.id, `roster[${index}].id`, issues);
+      if (item.epithet !== void 0) requireString(item.epithet, `roster[${index}].epithet`, issues);
     });
   }
   if (issues.length > 0) throw new AgentConfigValidationError(source, issues);
@@ -1442,6 +1458,7 @@ ${rows}
 async function syncAgents(targetDir, assetsDir, roster, options = {}) {
   const synced = [];
   const skipped = [];
+  let hasUnresolvedRoles = false;
   const projectDefs = projectAgentsDir(targetDir);
   const bundledDefs = join2(assetsDir, "agents");
   const resolved = [];
@@ -1454,6 +1471,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
         def = await loadAgentDefinition(bundledDefs, entry.definition);
       } catch {
         skipped.push(`${entry.definition} (definition not found)`);
+        hasUnresolvedRoles = true;
         continue;
       }
     }
@@ -1506,6 +1524,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
         id: entry.id,
         identity: {
           name: entry.name ?? entry.definition,
+          ...entry.epithet ? { epithet: entry.epithet } : {},
           role: def.role
         }
       }))
@@ -1575,7 +1594,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
     );
     if (codexMerged) synced.push("AGENTS.md (agents section)");
   }
-  return { synced, skipped };
+  return { synced, skipped, hasUnresolvedRoles };
 }
 
 // src/modules/agents.ts
@@ -1660,9 +1679,9 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
   }
   printStep("Assigning names...");
   const named = await applyNamingStrategy(namingStrategy, selectedRoleIds);
-  const rosterEntries = named.map(({ definition, name }) => {
+  const rosterEntries = named.map(({ definition, name, epithet }) => {
     const id = definition === "orchestrator" ? "main" : name.toLowerCase().replace(/\s+/g, "-");
-    return { definition, name, id };
+    return epithet ? { definition, name, id, epithet } : { definition, name, id };
   });
   const roster = {
     schema_version: 2,
@@ -1706,7 +1725,7 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
     return;
   }
   printStep("Syncing agent definitions to all clients...");
-  const { synced, skipped } = await syncAgents(
+  const { synced, skipped, hasUnresolvedRoles } = await syncAgents(
     targetDir,
     assetsDir,
     roster,
@@ -1721,6 +1740,12 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
   console.log();
   console.log(`    \u{1F4A1} Customize: edit .arcane/agents.yaml \u2192 spell agents sync`);
   console.log();
+  if (hasUnresolvedRoles) {
+    console.error(
+      '  \u2717 One or more rostered roles could not be resolved (see "Skipped" above) \u2014 a malformed or missing agent template must not pass silently.'
+    );
+    process.exitCode = 1;
+  }
 }
 async function runAgentsSync(options, targetDir, assetsDir) {
   let roster;
@@ -1739,7 +1764,7 @@ async function runAgentsSync(options, targetDir, assetsDir) {
   } else {
     console.log("\n  Syncing agents...\n");
   }
-  const { synced, skipped } = await syncAgents(
+  const { synced, skipped, hasUnresolvedRoles } = await syncAgents(
     targetDir,
     assetsDir,
     roster,
@@ -1763,6 +1788,12 @@ async function runAgentsSync(options, targetDir, assetsDir) {
     }
   }
   console.log();
+  if (hasUnresolvedRoles) {
+    console.error(
+      '  \u2717 One or more rostered roles could not be resolved (see "Skipped" above) \u2014 a malformed or missing agent template must not pass silently.'
+    );
+    process.exitCode = 1;
+  }
 }
 async function runAgentsList(targetDir) {
   let roster;