arcane-cli 1.3.1 → 1.4.0

package/README.md

@@ -237,12 +237,16 @@ Codex, VS Code Copilot and Claude Code each discover the user tier from their ow
 
 ```bash
 spell agents init --user   # ~/.arcane/agents.yaml plus one definition file per role
-spell agents sync --user   # renders ~/.copilot/agents/<name>.agent.md — VS Code agent modes
+spell agents sync --user   # renders ~/.claude/agents/<name>.md — read by VS Code and Claude Code
 spell agents list --user   # the roster the tier holds
 ```
 
 Unlike spells, agent files are never delivered by `spell init` or `spell update`: they are rendered from your roster, whose naming strategy decides each file's name and contents, so an upgrade leaves them alone by design (ARC-047). And unlike skills, VS Code does **not** collapse two agents that share a name — a repository carrying its own `.github/agents` files adds a second entry beside the tier's rather than replacing it, so opting the repository out is what produces one set.
 
+`~/.claude/agents` is read by VS Code **and** by Claude Code, so one file gives you the persona in both. Each description ends by saying the persona is for when you ask for it by name: Claude Code reads that field to decide whether to route work to a subagent unprompted, and twelve personas installed once per machine would otherwise start answering in projects that have nothing to do with Arcane. Change that sentence in `renderUserTierAgent` if you want the opposite.
+
+A repository that opts in and has no roster of its own now takes the machine-wide one for its roster tables, rather than refusing.
+
 **Then let a repository stop carrying its own copies.** `spell init` offers this when the machine already has a tier, and an existing repository opts in by setting one field:
 
 ```jsonc

package/dist/assets/.arcane/governance/portable-bootstrap.md

@@ -52,7 +52,7 @@ Paste this entire file into any AI client (Claude web, ChatGPT, etc.) to give it
 ## Where Documents Live
 
 - **Framework-managed standards:** `.arcane/governance/`. Spells reference this single installed layer; **do not create a duplicate root `governance/` tree. Enforcement: explicitly advisory prose (ARC-023) — no check scans a repo for a duplicate root-level `governance/` directory.**
-- **Framework-managed spells:** `.arcane/spells/<id>.md` is each spell's one authored source (ARC-045). The files each AI client discovers — `.github/prompts/<id>.prompt.md` for Copilot, `.claude/commands/<id>.md` for Claude Code, `.agents/skills/<id>/SKILL.md` for Codex — are thin generated shims that point back at it; edit the canonical file, never a shim. **Enforcement: executable check (ARC-023) — `npm run check:self-host-parity` re-renders every shim from its canonical file and fails on any difference; `spell update` keeps a hand-edited shim untouched and names it rather than merging into it.** The same canonical spells can also be installed once per machine — `spell init --user` puts them at `~/.arcane/spells/<id>.md` with one Codex/Copilot skill under `~/.agents/skills/` and one Claude Code command under `~/.claude/commands/` per spell (ARC-045 decision 3); governance never moves up a tier. The agent roster follows the same shape (ARC-047): `spell agents init|sync --user` keeps `agents.yaml` and the role definitions at `~/.arcane` and renders one `~/.copilot/agents/<name>.agent.md` per agent, which is where VS Code looks for machine-wide agent modes. Agent files are never installed by `spell init`/`spell update` at either tier -- they are rendered from the roster, whose naming strategy picks each file's name, which is why an upgrade never touches them. A repository may then opt out of carrying its own copies entirely with `spell_scope: "user"` in `.arcane.json` (ARC-045 decision 4) — `spell update --prune` removes what it no longer manages, keeping anything you edited, and `spell doctor` fails loudly if the tier it now depends on is missing.
+- **Framework-managed spells:** `.arcane/spells/<id>.md` is each spell's one authored source (ARC-045). The files each AI client discovers — `.github/prompts/<id>.prompt.md` for Copilot, `.claude/commands/<id>.md` for Claude Code, `.agents/skills/<id>/SKILL.md` for Codex — are thin generated shims that point back at it; edit the canonical file, never a shim. **Enforcement: executable check (ARC-023) — `npm run check:self-host-parity` re-renders every shim from its canonical file and fails on any difference; `spell update` keeps a hand-edited shim untouched and names it rather than merging into it.** The same canonical spells can also be installed once per machine — `spell init --user` puts them at `~/.arcane/spells/<id>.md` with one Codex/Copilot skill under `~/.agents/skills/` and one Claude Code command under `~/.claude/commands/` per spell (ARC-045 decision 3); governance never moves up a tier. The agent roster follows the same shape (ARC-047): `spell agents init|sync --user` keeps `agents.yaml` and the role definitions at `~/.arcane` and renders one `~/.claude/agents/<name>.md` per agent -- the one home location read by both VS Code and Claude Code, so a persona shows up once in each rather than twice in one (ARC-047 decisions 3 and 11). Agent files are never installed by `spell init`/`spell update` at either tier -- they are rendered from the roster, whose naming strategy picks each file's name, which is why an upgrade never touches them. A repository may then opt out of carrying its own copies entirely with `spell_scope: "user"` in `.arcane.json` (ARC-045 decision 4) — `spell update --prune` removes what it no longer manages, keeping anything you edited, and `spell doctor` fails loudly if the tier it now depends on is missing.
 - **Project-owned orientation and continuity:** `README.md`, `project.md`, `TODO.md`, `DECISIONS.md`, `ai-context/`, and `journal/`. Arcane creates missing files once and preserves existing content.
 - **Project/domain documents:** use explicit descriptive paths such as `docs/`, `security/`, `infrastructure/`, or a configured business root. These add project context alongside framework standards.
 - **Overrides survive `arcane update`:** editing a managed `.arcane/governance/` standard no longer risks silent loss. Additive project documents were always safe; a hand-edit to a shipped standard now is too. **Enforcement: executable check (ARC-038, shipped BC-31)** — `spell update` compares each file's on-disk content against its recorded hash at install time: unchanged, it refreshes normally; edited, it fetches the exact previously-installed published version as a three-way merge base against your edit and the new vendor content, auto-merging non-overlapping changes and leaving standard conflict markers only on genuine collisions. If the prior published version can't be fetched, your edit is left untouched with a warning rather than replaced.

package/dist/index.js

@@ -1035,25 +1035,27 @@ function spellIdsInStore(components) {
   }
   return [...ids].sort();
 }
-var USER_AGENT_FANOUT_DIR = ".copilot/agents";
+var USER_AGENT_FANOUT_DIR = ".claude/agents";
+var LEGACY_USER_AGENT_FANOUT_DIR = ".copilot/agents";
 var SPELL_FANOUT_CLIENTS = ["codex", "claude"];
 var USER_FANOUT_PATHS = {
   codex: (id) => `.agents/skills/${id}/SKILL.md`,
   claude: (id) => `.claude/commands/${id}.md`
 };
 function userAgentFanoutPath(slug) {
-  return `${USER_AGENT_FANOUT_DIR}/${slug}.agent.md`;
+  return `${USER_AGENT_FANOUT_DIR}/${slug}.md`;
 }
 var FANOUT_CLIENT_LABELS = {
   codex: "Codex/Copilot skills",
   claude: "Claude Code commands",
-  "copilot-agents": "Copilot agent modes"
+  "copilot-agents": "agent personas (VS Code + Claude Code)"
 };
 function clientOfFanoutPath(relativePath) {
   const normalized = relativePath.replace(/\\/g, "/");
   if (normalized.startsWith(".agents/skills/")) return "codex";
   if (normalized.startsWith(".claude/commands/")) return "claude";
   if (normalized.startsWith(`${USER_AGENT_FANOUT_DIR}/`)) return "copilot-agents";
+  if (normalized.startsWith(`${LEGACY_USER_AGENT_FANOUT_DIR}/`)) return "copilot-agents";
   return void 0;
 }
 async function readSpellSource(storeRoot, id, fallbackDir) {
@@ -2050,6 +2052,16 @@ ${allowed}
 ${denied}
 `;
 }
+function renderUserTierAgent(def, name) {
+  const collapsed = def.persona.description.replace(/\s+/g, " ").trim();
+  const firstSentence = /^.*?[.!?](?=\s|$)/.exec(collapsed)?.[0] ?? def.role;
+  const repoFile = renderCopilotAgent(def, name);
+  const body = repoFile.slice(repoFile.indexOf("---", 3) + 3);
+  return `---
+name: ${name}
+description: ${def.role}. ${firstSentence} Use only when explicitly asked for ${name} by name; do not delegate to this persona automatically.
+---${body}`;
+}
 function renderCopilotAgent(def, name) {
   const firstLine = def.persona.description.split("\n")[0]?.trim() ?? def.role;
   const rules = def.persona.behavioral_rules.map((r) => `- ${r}`).join("\n");
@@ -2130,7 +2142,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
   const repoOptedOut = !userTier && options.spellScope === "user";
   const userAgentFiles = [];
   const unmanagedAgentFiles = [];
-  const projectDefs = projectAgentsDir(targetDir, userTier ? "user" : "repo");
+  const projectDefs = options.definitionsDir ?? projectAgentsDir(targetDir, userTier ? "user" : "repo");
   const bundledDefs = join3(assetsDir, "agents");
   const resolved = [];
   for (const entry of roster.roster) {
@@ -2224,7 +2236,7 @@ async function syncAgents(targetDir, assetsDir, roster, options = {}) {
       if (!def.clients.copilot?.agent_file) continue;
       const slug = displayName.toLowerCase().replace(/\s+/g, "-");
       const fileName = `${slug}.agent.md`;
-      const content = renderCopilotAgent(def, displayName);
+      const content = userTier ? renderUserTierAgent(def, displayName) : renderCopilotAgent(def, displayName);
       if (userTier) {
         const relativePath = userAgentFanoutPath(slug);
         userAgentFiles.push({ relativePath, client: "copilot-agents", content });
@@ -2301,6 +2313,24 @@ async function requireUserStore(storeRoot) {
     throw new Error("unreachable");
   }
 }
+async function resolveRoster(targetDir, scope, homeDir) {
+  try {
+    return {
+      roster: await loadRoster(targetDir, scope),
+      definitionsDir: projectAgentsDir(targetDir, scope),
+      fromUserTier: scope === "user"
+    };
+  } catch (err) {
+    const missing = err instanceof AgentRosterNotFoundError;
+    if (!missing || scope !== "repo" || await repoSpellScope(targetDir) !== "user") throw err;
+    const storeRoot = homeDir === void 0 ? userTierRoot() : userTierRoot(homeDir);
+    return {
+      roster: await loadRoster(storeRoot, "user"),
+      definitionsDir: projectAgentsDir(storeRoot, "user"),
+      fromUserTier: true
+    };
+  }
+}
 async function repoSpellScope(targetDir) {
   try {
     return effectiveSpellScope(await readManifest(targetDir));
@@ -2487,7 +2517,7 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
   printSuccess("Agent roster initialized");
   console.log(`    \u{1F4CB} Profile: ${profileId} \xB7 Naming: ${namingStrategy} \xB7 Agents: ${rosterEntries.length}`);
   console.log(
-    `    \u{1F504} Synced: ${synced.length} outputs (${scope === "user" ? "Copilot agent modes in ~/.copilot/agents" : "Copilot, Claude, Codex, OpenClaw"})`
+    `    \u{1F504} Synced: ${synced.length} outputs (${scope === "user" ? "agent personas in ~/.claude/agents" : "Copilot, Claude, Codex, OpenClaw"})`
   );
   if (skipped.length > 0) {
     console.log(`    \u26A0\uFE0F  Skipped: ${skipped.length} (${skipped.join(", ")})`);
@@ -2507,8 +2537,10 @@ All 12 roles across ${allCategories.join(", ")}` : "\nPick individual roles from
 async function runAgentsSync(options, targetDir, assetsDir) {
   const scope = options.scope ?? "repo";
   let roster;
+  let definitionsDir;
+  let fromUserTier = false;
   try {
-    roster = await loadRoster(targetDir, scope);
+    ({ roster, definitionsDir, fromUserTier } = await resolveRoster(targetDir, scope));
   } catch (err) {
     if (err instanceof AgentRosterNotFoundError || err instanceof AgentConfigValidationError) {
       console.error(err.message);
@@ -2522,11 +2554,16 @@ async function runAgentsSync(options, targetDir, assetsDir) {
   } else {
     console.log("\n  Syncing agents...\n");
   }
+  if (fromUserTier && scope === "repo") {
+    console.log(
+      "  This repository has no roster of its own and takes its spells from the user tier,\n  so its roster tables are built from ~/.arcane/agents.yaml.\n"
+    );
+  }
   const { synced, skipped, hasUnresolvedRoles } = await performAgentSync(
     targetDir,
     assetsDir,
     roster,
-    { ...options, scope }
+    { ...options, scope, ...definitionsDir === void 0 ? {} : { definitionsDir } }
   );
   if (options.dryRun) {
     console.log(`