@geraldmaron/construct 1.0.6 → 1.0.8

package/scripts/{sync-agents.mjs → sync-specialists.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * sync-agents.mjs — regenerate agent adapters for all platforms from agents/registry.json.
+ * sync-specialists.mjs — regenerate agent adapters for all platforms from specialists/registry.json.
  *
  * Reads registry.json, resolves env vars and model tiers, then writes Claude Code,
  * OpenCode, Codex, Copilot, VS Code, and Cursor adapters. Called by 'construct sync'.
@@ -50,7 +50,7 @@ for (const [key, value] of Object.entries(mergedEnv)) {
   if (!(key in process.env)) process.env[key] = value;
 }
 if (!process.env.CX_TOOLKIT_DIR) process.env.CX_TOOLKIT_DIR = root;
-const registryPath = path.join(root, "agents", "registry.json");
+const registryPath = path.join(root, "specialists", "registry.json");
 const registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
 
 function validateRegistry(registry) {
@@ -58,31 +58,32 @@ function validateRegistry(registry) {
   if (!registry.version) errors.push("Missing 'version' field");
   if (!registry.system) errors.push("Missing 'system' field");
   if (!registry.prefix) errors.push("Missing 'prefix' field");
-  if (!Array.isArray(registry.agents)) errors.push("Missing or invalid 'agents' array");
-  if (!Array.isArray(registry.personas)) errors.push("Missing or invalid 'personas' array");
+  if (!registry.orchestrator) errors.push("Missing 'orchestrator' field");
+  if (!Array.isArray(registry.specialists)) errors.push("Missing or invalid 'specialists' array");
   const validTiers = new Set(["reasoning", "standard", "fast"]);
   const names = new Set();
 
-  for (const persona of registry.personas ?? []) {
-    if (!persona.name) { errors.push("Persona missing 'name'"); continue; }
-    if (names.has(persona.name)) errors.push(`Duplicate name: ${persona.name}`);
-    names.add(persona.name);
-    if (!persona.description) errors.push(`${persona.name}: missing 'description'`);
-    if (!persona.promptFile) errors.push(`${persona.name}: missing 'promptFile'`);
-    if (!persona.displayName) errors.push(`${persona.name}: missing 'displayName'`);
+  if (registry.orchestrator) {
+    const o = registry.orchestrator;
+    if (!o.name) errors.push("Orchestrator missing 'name'");
+    if (names.has(o.name)) errors.push(`Duplicate name: ${o.name}`);
+    names.add(o.name);
+    if (!o.description) errors.push("Orchestrator: missing 'description'");
+    if (!o.promptFile) errors.push("Orchestrator: missing 'promptFile'");
+    if (!o.displayName) errors.push("Orchestrator: missing 'displayName'");
   }
 
-  for (const agent of registry.agents ?? []) {
-    if (!agent.name) { errors.push("Agent missing 'name'"); continue; }
-    if (names.has(agent.name)) errors.push(`Duplicate name: ${agent.name}`);
-    names.add(agent.name);
-    if (!agent.prompt && !agent.promptFile) errors.push(`${agent.name}: missing 'prompt' or 'promptFile'`);
-    if (!agent.description) errors.push(`${agent.name}: missing 'description'`);
-    if (!agent.model && !agent.modelTier) errors.push(`${agent.name}: needs 'model' or 'modelTier'`);
-    if (agent.modelTier && !validTiers.has(agent.modelTier)) errors.push(`${agent.name}: invalid modelTier '${agent.modelTier}'`);
-    if (!agent.claudeTools) errors.push(`${agent.name}: missing 'claudeTools'`);
-    if (agent.modelGuidance && typeof agent.modelGuidance !== "object") {
-      errors.push(`${agent.name}: modelGuidance must be an object`);
+  for (const specialist of registry.specialists ?? []) {
+    if (!specialist.name) { errors.push("Specialist missing 'name'"); continue; }
+    if (names.has(specialist.name)) errors.push(`Duplicate name: ${specialist.name}`);
+    names.add(specialist.name);
+    if (!specialist.prompt && !specialist.promptFile) errors.push(`${specialist.name}: missing 'prompt' or 'promptFile'`);
+    if (!specialist.description) errors.push(`${specialist.name}: missing 'description'`);
+    if (!specialist.model && !specialist.modelTier) errors.push(`${specialist.name}: needs 'model' or 'modelTier'`);
+    if (specialist.modelTier && !validTiers.has(specialist.modelTier)) errors.push(`${specialist.name}: invalid modelTier '${specialist.modelTier}'`);
+    if (!specialist.claudeTools) errors.push(`${specialist.name}: missing 'claudeTools'`);
+    if (specialist.modelGuidance && typeof specialist.modelGuidance !== "object") {
+      errors.push(`${specialist.name}: modelGuidance must be an object`);
     }
   }
 
@@ -121,6 +122,18 @@ if (validationErrors.length > 0) {
   process.exit(1);
 }
 
+// Sync-time contract validation: contracts.json shape, schema refs, and
+// producer/consumer name resolution against the registry above.
+{
+  const { validateContractsFile } = await import("../lib/contracts/validate.mjs");
+  const contractsResult = validateContractsFile();
+  if (!contractsResult.ok) {
+    console.error("Contract validation failed:");
+    for (const err of contractsResult.errors) console.error(`  - ${err}`);
+    process.exit(1);
+  }
+}
+
 // --- Dry-run + lockfile + two-phase write infrastructure ---
 
 const DRY_RUN = process.argv.includes("--dry-run");
@@ -168,7 +181,7 @@ const _stagedPairs = []; // [{ staging, real, content }]
 
 function writeFile(file, content) {
   mkdirp(path.dirname(file));
-  const stamped = file.endsWith('.md') ? stampFrontmatter(content, { generator: 'construct/sync-agents' }) : content;
+  const stamped = file.endsWith('.md') ? stampFrontmatter(content, { generator: 'construct/sync-specialists' }) : content;
 
   if (DRY_RUN) {
     // Stage in memory only — compare against current on-disk content.
@@ -216,15 +229,15 @@ const sharedGuidance = registry.sharedGuidance ?? [];
 const platformGuidance = registry.platformGuidance ?? {};
 const globalModelGuidance = registry.modelGuidance ?? {};
 
-const generatedHeader = `# Generated by ${systemName}/sync-agents.mjs. Edit agents/registry.json instead.`;
+const generatedHeader = `# Generated by ${systemName}/sync-specialists.mjs. Edit specialists/registry.json instead.`;
 const generatedMarkdownNote = [
   '<!--',
-  `Generated by construct sync from agents/registry.json.`,
+  `Generated by construct sync from specialists/registry.json.`,
   'Do not edit this file directly — changes will be overwritten on next sync.',
   'Regenerate: construct sync',
   '-->',
   '',
-  '> Generated from `agents/registry.json`. Edit the registry, then run `construct sync`.',
+  '> Generated from `specialists/registry.json`. Edit the registry, then run `construct sync`.',
 ].join('\n');
 
 const standardConstructTools = [
@@ -350,7 +363,7 @@ function resolveModelChain(entry) {
 function mkdirp(dir) { fs.mkdirSync(dir, { recursive: true }); }
 
 function adapterName(entry) {
-  return entry.isPersona ? entry.name : `${agentPrefix}${entry.name}`;
+  return entry.isOrchestrator ? entry.name : `${agentPrefix}${entry.name}`;
 }
 
 function loadPersonaPrompt(persona) {
@@ -386,7 +399,7 @@ function buildRoleFooter(entry) {
   if (collaborators.length > 0) {
     lines.push(`Collaborators: ${collaborators.map((c) => (c.startsWith("cx-") ? c : `cx-${c}`)).join(", ")}.`);
   }
-  if (entry.isPersona !== true && entry.canEdit === false) {
+  if (entry.isOrchestrator !== true && entry.canEdit === false) {
     lines.push("Do not implement code or edit source files.");
   }
   if (entry.returnsStructured !== false) {
@@ -432,7 +445,7 @@ function buildPrompt(entry, allEntries, platform) {
       console.error(
         `[sync] Hard cap exceeded. Options:\n` +
         `   - trim the prompt body or move detail to a skill (preferred)\n` +
-        `   - set "wordCapOverride": <N> on this entry in agents/registry.json with a written reason\n` +
+        `   - set "wordCapOverride": <N> on this entry in specialists/registry.json with a written reason\n` +
         `   - re-run with --force or CONSTRUCT_SYNC_FORCE=1 as a temporary escape hatch\n` +
         `Prompt budget is a hard contract because every over-cap agent degrades every session that dispatches it.`,
       );
@@ -489,18 +502,19 @@ function removeStaleAdapters(dir, ext, entries) {
 function buildEntries() {
   const entries = [];
 
-  for (const persona of registry.personas ?? []) {
-    const personaCanEdit = persona.permissions?.edit === "allow";
+  // Orchestrator entry
+  if (registry.orchestrator) {
+    const orchestratorCanEdit = registry.orchestrator.permissions?.edit === "allow";
     entries.push({
-      ...persona,
-      isPersona: true,
-      prompt: loadPersonaPrompt(persona),
-      codexSandbox: persona.codexSandbox ?? (personaCanEdit ? "workspace-write" : "read-only"),
-      reasoningEffort: persona.reasoningEffort ?? "high",
+      ...registry.orchestrator,
+      isOrchestrator: true,
+      prompt: loadPersonaPrompt(registry.orchestrator),
+      codexSandbox: registry.orchestrator.codexSandbox ?? (orchestratorCanEdit ? "workspace-write" : "read-only"),
+      reasoningEffort: registry.orchestrator.reasoningEffort ?? "high",
     });
   }
 
-  // Filter agents by the active profile's role set. RND lists every specialist
+  // Filter specialists by the active profile's role set. RND lists every specialist
   // so behavior is unchanged for the default; non-RND profiles emit only the
   // specialists they declare. Profiles whose role list is empty (legacy/test)
   // fall through to no filter so callers don't get a silent empty registry.
@@ -509,11 +523,11 @@ function buildEntries() {
     ? new Set(activeProfile.roles)
     : null;
 
-  for (const agent of registry.agents ?? []) {
-    if (profileRoles && !profileRoles.has(agent.name)) continue;
+  for (const specialist of registry.specialists ?? []) {
+    if (profileRoles && !profileRoles.has(specialist.name)) continue;
     entries.push({
-      ...agent,
-      isPersona: false,
+      ...specialist,
+      isSpecialist: true,
     });
   }
 
@@ -638,16 +652,16 @@ function syncClaude(entries, targetDir = null) {
   if (!targetDir) {
     const claudeMdPath = path.join(home, ".claude", "CLAUDE.md");
     const existing = fs.existsSync(claudeMdPath) ? fs.readFileSync(claudeMdPath, "utf8") : "# Claude Global Instructions\n";
-    const personaList = entries.filter((e) => e.isPersona).map((e) => `- \`${adapterName(e)}\`: ${e.role} — ${e.description}`).join("\n");
-    // Only surface non-internal agents in CLAUDE.md — internal agents are dispatched by Construct, not invoked by users
-    const agentList = entries.filter((e) => !e.isPersona && !e.internal).map((e) => `- \`${adapterName(e)}\`: ${e.description}`).join("\n");
+    const personaList = entries.filter((e) => e.isOrchestrator).map((e) => `- \`${adapterName(e)}\`: ${e.role} — ${e.description}`).join("\n");
+    // Only surface non-internal specialists in CLAUDE.md — internal specialists are dispatched by Construct, not invoked by users
+    const specialistList = entries.filter((e) => !e.isOrchestrator && !e.internal).map((e) => `- \`${adapterName(e)}\`: ${e.description}`).join("\n");
     const note = `## ${systemName.charAt(0).toUpperCase() + systemName.slice(1)} Personas
 
 ${personaList}
 
 ## Internal Specialists
 
-${agentList || "(all specialists are internal — routed through Construct)"}`;
+${specialistList || "(all specialists are internal — routed through Construct)"}`;
     writeFile(claudeMdPath, replaceManagedBlock(existing, note, mdManagedStart, mdManagedEnd));
 
     // Sync MCP servers into ~/.claude/settings.json if it exists
@@ -671,9 +685,13 @@ ${agentList || "(all specialists are internal — routed through Construct)"}`;
       if (!settings.mcpServers) settings.mcpServers = {};
       const registryMcp = registry.mcpServers ?? {};
       for (const [id, mcpDef] of Object.entries(registryMcp)) {
-        const existing = JSON.stringify(settings.mcpServers[id] ?? "");
+        const existingEntry = settings.mcpServers[id];
+        const existing = JSON.stringify(existingEntry ?? "");
         const hasPlaceholder = existing.includes("__");
-        if (settings.mcpServers[id] && !hasPlaceholder) continue;
+        const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+        const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
+        const transportMismatch = registryWantsCommand && existingIsRemote;
+        if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
         settings.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
       }
       if (!DRY_RUN) fs.writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + "\n");
@@ -711,8 +729,8 @@ function hasCodexMcpTable(text, id) {
   return new RegExp(`^\\[mcp_servers\\.(?:${escapeRegExp(id)}|${escapeRegExp(tomlString(id))})\\]`, "m").test(text);
 }
 
-function isCodexMcpSupported(id) {
-  return id !== "memory";
+function isCodexMcpSupported() {
+  return true;
 }
 
 function syncCodex(entries) {
@@ -834,9 +852,13 @@ function syncVSCode() {
       if (!settings["github.copilot.mcpServers"]) settings["github.copilot.mcpServers"] = {};
       const mcpServers = settings["github.copilot.mcpServers"];
       for (const [id, mcpDef] of Object.entries(registryMcp)) {
-        const existing = JSON.stringify(mcpServers[id] ?? "");
+        const existingEntry = mcpServers[id];
+        const existing = JSON.stringify(existingEntry ?? "");
         const hasPlaceholder = existing.includes("__");
-        if (mcpServers[id] && !hasPlaceholder) continue;
+        const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+        const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
+        const transportMismatch = registryWantsCommand && existingIsRemote;
+        if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
         mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
       }
       settings["github.copilot.mcpServers"] = mcpServers;
@@ -862,9 +884,13 @@ function syncCursor() {
     const config = JSON.parse(fs.readFileSync(cursorMcpPath, "utf8"));
     if (!config.mcpServers) config.mcpServers = {};
     for (const [id, mcpDef] of Object.entries(registryMcp)) {
-      const existing = JSON.stringify(config.mcpServers[id] ?? "");
+      const existingEntry = config.mcpServers[id];
+      const existing = JSON.stringify(existingEntry ?? "");
       const hasPlaceholder = existing.includes("__");
-      if (config.mcpServers[id] && !hasPlaceholder) continue;
+      const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+      const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
+      const transportMismatch = registryWantsCommand && existingIsRemote;
+      if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
       config.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
     }
     if (!DRY_RUN) fs.writeFileSync(cursorMcpPath, JSON.stringify(config, null, 2) + "\n");
@@ -963,14 +989,21 @@ function syncOpencode(entries) {
     for (const [id, mcpDef] of Object.entries(registryMcp)) {
       const openCodeId = getOpenCodeMcpId(id);
       if (openCodeId !== id) delete config.mcp[id];
-      if (id === 'memory' && config.mcp.cass && !config.mcp[openCodeId]) {
-        config.mcp[openCodeId] = config.mcp.cass;
-      }
       if (id === 'memory') delete config.mcp.cass;
-      const existing = JSON.stringify(config.mcp[openCodeId] ?? "");
-      const hasPlaceholder = existing.includes("__") && existing.includes("__");
+
+      // Migrate the legacy cass-memory HTTP entry to the stdio bridge. cm v0.2.x
+      // rejects the MCP handshake (OpenCode surfaces 405 on the SSE GET), so
+      // any remote/http memory entry must be rewritten when the registry
+      // defines a command-based bridge.
+      const existingEntry = config.mcp[openCodeId];
+      const registryWantsCommand = !mcpDef.type && Array.isArray(mcpDef.args);
+      const existingIsRemote = existingEntry && (existingEntry.type === 'remote' || existingEntry.type === 'http');
+      const transportMismatch = registryWantsCommand && existingIsRemote;
+
+      const existing = JSON.stringify(existingEntry ?? "");
+      const hasPlaceholder = existing.includes("__");
       const argsHaveTemplates = (mcpDef.args ?? []).some((a) => typeof a === 'string' && a.includes('__'));
-      if (!config.mcp[openCodeId] || hasPlaceholder || argsHaveTemplates) {
+      if (!existingEntry || hasPlaceholder || argsHaveTemplates || transportMismatch) {
         config.mcp[openCodeId] = buildOpenCodeMcpEntry(id, mcpDef, process.env).entry;
       }
     }
@@ -980,8 +1013,8 @@ function syncOpencode(entries) {
   const prefixes = [agentPrefix];
   for (const key of Object.keys(config.agent)) {
     const isManaged = prefixes.some((p) => key.startsWith(p));
-    const isPersona = registry.personas.some((p) => p.name === key);
-    if ((isManaged || isPersona) && !entries.find((e) => adapterName(e) === key)) {
+    const isOrchestrator = registry.orchestrator?.name === key;
+    if ((isManaged || isOrchestrator) && !entries.find((e) => adapterName(e) === key)) {
       delete config.agent[key];
     }
   }
@@ -991,10 +1024,10 @@ function syncOpencode(entries) {
     const name = adapterName(entry);
     const perms = opencodePermissions(entry);
     config.agent[name] = {
-      description: entry.isPersona
+      description: entry.isOrchestrator
         ? `${entry.role} — ${entry.description}`
         : entry.description,
-      mode: entry.isPersona ? "all" : "subagent",
+      mode: entry.isOrchestrator ? "all" : "subagent",
       prompt: buildPrompt(entry, entries, "opencode"),
       permission: {
         ...perms,
@@ -1071,6 +1104,75 @@ function syncCommands(targetDir = null) {
   return count;
 }
 
+// --- Skills sync ---
+
+/**
+ * Walk skills/ recursively and collect every .md file (flat) and every
+ * <name>/SKILL.md directory entry. Returns [{ name, content }] where name
+ * is the slash-relative path without extension, e.g. "strategy/narrative-arc".
+ */
+function collectSkills() {
+  const skillsDir = path.join(root, "skills");
+  const results = [];
+
+  function walk(dir, prefix) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+      if (entry.isDirectory()) {
+        // Check if this is a SKILL.md directory form: <name>/SKILL.md
+        const skillMdPath = path.join(full, "SKILL.md");
+        if (fs.existsSync(skillMdPath)) {
+          // Avoid double-walking; record this skill and do not descend further.
+          const name = rel;
+          results.push({ name, content: fs.readFileSync(skillMdPath, "utf8") });
+        } else {
+          walk(full, rel);
+        }
+      } else if (entry.name.endsWith(".md") && entry.name !== "routing.md" && entry.name !== "SKILL.md") {
+        const name = rel.replace(/\.md$/, "");
+        results.push({ name, content: fs.readFileSync(full, "utf8") });
+      }
+    }
+  }
+
+  walk(skillsDir, "");
+  return results;
+}
+
+/**
+ * Prefix prepended to every generated SKILL.md. The comment must survive
+ * round-trips — it is the canonical signal that a file was produced by sync
+ * and must not be hand-edited.
+ */
+const SKILL_GENERATED_PREFIX = "# Generated by construct sync\n\n";
+
+/**
+ * Write collected skills to both .claude/skills/ and .agents/skills/ in
+ * SKILL.md directory format.
+ *
+ * Idempotency: content written is deterministic; writing the same content
+ * twice is a no-op because writeFile skips unchanged files in dry-run mode
+ * and two-phase staging in normal mode produces identical results.
+ */
+function syncSkills() {
+  const skills = collectSkills();
+  if (skills.length === 0) return 0;
+
+  const claudeSkillsDir = path.join(home, ".claude", "skills");
+  const agentsSkillsDir = path.join(home, ".agents", "skills");
+
+  for (const { name, content } of skills) {
+    const generated = `${SKILL_GENERATED_PREFIX}${content}`;
+    writeFile(path.join(claudeSkillsDir, name, "SKILL.md"), generated);
+    writeFile(path.join(agentsSkillsDir, name, "SKILL.md"), generated);
+  }
+
+  return skills.length;
+}
+
 // --- Main ---
 
 const projectDir = process.argv.includes("--project") ? process.cwd() : null;
@@ -1086,7 +1188,7 @@ if (COMPRESS_PERSONAS) {
   let totalIn = 0;
   let totalOut = 0;
   for (const entry of entries) {
-    if (!entry.isPersona || !entry.prompt) continue;
+    if (!entry.isOrchestrator || !entry.prompt) continue;
     const before = entry.prompt;
     try {
       const after = await compressor.compress(before, { ratio: 0.6 });
@@ -1101,7 +1203,7 @@ if (COMPRESS_PERSONAS) {
   }
   if (totalIn > 0) {
     const ratio = ((totalOut / totalIn) * 100).toFixed(0);
-    console.log(`compress-personas: ${totalIn} → ${totalOut} chars (${ratio}%) across ${entries.filter((e) => e.isPersona).length} personas`);
+    console.log(`compress-personas: ${totalIn} → ${totalOut} chars (${ratio}%) across ${entries.filter((e) => e.isOrchestrator).length} personas`);
   }
 }
 
@@ -1117,8 +1219,8 @@ try {
       console.log(`Synced ${entries.length} agents + ${cmdCount} commands to ${path.join(projectDir, ".claude/")} (project mode).`);
     }
   } else {
-    const personaCount = entries.filter((e) => e.isPersona).length;
-    const agentCount = entries.filter((e) => !e.isPersona).length;
+    const personaCount = entries.filter((e) => e.isOrchestrator).length;
+    const specialistCount = entries.filter((e) => !e.isOrchestrator).length;
 
     syncCodex(entries);
     syncClaude(entries);
@@ -1127,6 +1229,7 @@ try {
     const vscodeOk = syncVSCode();
     const cursorOk = syncCursor();
     const cmdCount = syncCommands();
+    const skillCount = syncSkills();
 
     if (DRY_RUN) {
       printDryRunDiff();
@@ -1141,7 +1244,7 @@ try {
         vscodeOk && "VS Code",
         cursorOk && "Cursor",
       ].filter(Boolean).join(", ");
-      console.log(`Synced ${personaCount} personas + ${agentCount} specialists + ${cmdCount} commands to ${targets}.`);
+      console.log(`Synced ${personaCount} orchestrator + ${specialistCount} specialists + ${cmdCount} commands + ${skillCount} skills to ${targets}.`);
 
       // Regenerate shell completions so new commands are immediately tab-completable
       const completionsDir = generateCompletions();

package/skills/ai/prompt-optimizer.md

@@ -6,7 +6,7 @@ and the agent registry + construct sync as the deployment layer.
 -->
 # Prompt Auto-Optimization Loop
 
-Construct's prompt improvement system uses telemetry traces and quality scores as the feedback signal, Claude as the optimizer, and the agent registry (`agents/registry.json`) as the deployment layer. This is a closed loop: production data → failure analysis → improved prompt → staging → promotion.
+Construct's prompt improvement system uses telemetry traces and quality scores as the feedback signal, Claude as the optimizer, and the agent registry (`specialists/registry.json`) as the deployment layer. This is a closed loop: production data → failure analysis → improved prompt → staging → promotion.
 
 ## Running the optimizer
 
@@ -34,7 +34,7 @@ The optimizer requires Python 3.12+ (`pip3` must be available). It will auto-ins
 
 ## Step 1: Gather signal
 
-Retrieve the current production prompt for the target agent from `agents/registry.json` (or the corresponding `promptFile` if using extracted prompts).
+Retrieve the current production prompt for the target agent from `specialists/registry.json` (or the corresponding `promptFile` if using extracted prompts).
 
 Then retrieve recent traces via the telemetry backend REST API:
 
@@ -76,7 +76,7 @@ Write an improved prompt that directly addresses the diagnosed failures. Rules:
 
 ## Step 4: Push to staging
 
-Update the agent's prompt in `agents/registry.json` (or the corresponding `promptFile`) with a staging marker comment. Tag the version by writing to `.cx/decisions/prompt-staging-{agent}-{date}.md`.
+Update the agent's prompt in `specialists/registry.json` (or the corresponding `promptFile`) with a staging marker comment. Tag the version by writing to `.cx/decisions/prompt-staging-{agent}-{date}.md`.
 
 Log the candidate prompt as a span attribute on a test run batch using `cx_trace`. Tag spans with `promptVersion: staging-{timestamp}` and score them with `cx_score` as traces complete.
 

package/skills/exploration/dependency-graph-reading.md

@@ -0,0 +1,98 @@
+<!--
+skills/exploration/dependency-graph-reading.md (Dependency Graph Reading)
+Use when auditing a project's supply chain risk, evaluating upgrade paths,
+or assessing the risk surface of a new codebase. Covers npm/cargo/maven
+lockfile interpretation, transitive dependency patterns, and risk signals.
+-->
+
+# Dependency Graph Reading
+
+Use when assessing the risk surface of a project's dependencies, planning upgrades, or evaluating a new codebase's supply chain posture.
+
+## npm / package-lock.json
+
+The lockfile is the authoritative record of what actually runs in production.
+
+**What `package-lock.json` tells you:**
+- Exact resolved versions of every dependency (direct + transitive).
+- The registry URL each package resolved from (watch for non-npm registry sources).
+- Integrity hashes for tamper detection (missing or mismatched hashes are a supply chain signal).
+
+**Commands:**
+```bash
+# Tree of direct dependencies with their transitive deps
+npm ls --all --depth=5 <package>
+
+# Why is this package installed? (shows the resolution path)
+npm ls <package>
+
+# Outdated direct dependencies
+npm outdated
+
+# Audit for known CVEs
+npm audit --json | jq '.vulnerabilities | to_entries | sort_by(.value.severity) | reverse[]'
+```
+
+**Risk signals in the lockfile:**
+- Packages sourced from `github:`, `file:`, or private registries, higher supply-chain risk.
+- Very old `lockfileVersion` (v1), may not capture integrity hashes properly.
+- Transitive dependencies with `requires: {}` instead of resolved versions, resolution ambiguity.
+
+## Cargo.lock (Rust)
+
+Cargo maintains a flat lockfile with explicit source declarations.
+
+**Key fields:**
+- `[[package]]`: each entry is a resolved crate version.
+- `source = "registry+..."`: standard crates.io source. `source = "git+..."`: git dependency (less auditable).
+- `checksum`: SHA256 of the downloaded crate.
+
+**Commands:**
+```bash
+# Dependency tree with feature flags
+cargo tree
+
+# Find all versions of a crate (version conflicts)
+cargo tree -d
+
+# Audit for known vulnerabilities
+cargo audit
+```
+
+## Maven / gradle (JVM)
+
+The effective POM / resolved configuration tells you what actually runs.
+
+```bash
+# Full dependency tree with transitive
+mvn dependency:tree -Dverbose
+
+# Resolved versions for a specific scope
+mvn dependency:list -Dscope=compile
+
+# Gradle
+./gradlew dependencies --configuration runtimeClasspath
+```
+
+**Risk signals:**
+- Version range declarations (`[1.0,)`), means any future version could be resolved at build time.
+- `SNAPSHOT` versions in non-snapshot builds, unstable artifact references.
+- Duplicate versions of the same artifact (version conflict, one wins, one is silently dropped).
+
+## Cross-ecosystem risk signals
+
+| Signal | Risk | Action |
+|---|---|---|
+| Dependency with <100 weekly downloads | Supply chain (abandoned / obscure) | Evaluate inlining or replacing |
+| Dependency last published >2 years ago | Maintenance risk | Check for forks or replacements |
+| Deep transitive chain (>10 levels) | Blast radius | Map critical path; isolate |
+| Single maintainer with no 2FA | Takeover risk | Monitor; prefer alternatives with org ownership |
+| Package name squatting (typosquat) | Injection risk | Verify exact package name + registry source |
+| Wildcard `*` version pin | Reproducibility failure | Lock to exact version |
+
+## Practical audit workflow
+
+1. **Enumerate the blast radius**: which packages, if compromised, have write access to your production environment or sensitive data? These are the highest-risk nodes.
+2. **Check freshness on the critical path**: `npm audit`, `cargo audit`, `snyk test`. Focus on high/critical severity findings that affect runtime code (not devDependencies).
+3. **Identify orphaned dependencies**: packages no code imports directly but appear in the lockfile. May be safe to remove, reducing surface area.
+4. **Check for version conflicts**: multiple resolved versions of the same package indicate an incomplete deduplication. Usually benign; occasionally a security issue if an old insecure version is in the tree.

package/skills/exploration/tracer-bullet-method.md

@@ -0,0 +1,71 @@
+<!--
+skills/exploration/tracer-bullet-method.md (Tracer Bullet Method)
+Use when starting implementation in an unfamiliar or complex system.
+A tracer bullet is a minimal end-to-end path through the system,
+real code, real infrastructure, real calls, before any deep work begins.
+-->
+
+# Tracer Bullet Method
+
+Use when beginning implementation in a new system, new integration, or new architectural layer. A tracer bullet is not a prototype; it is the thinnest possible complete path through the real system.
+
+## What a tracer bullet is
+
+A tracer bullet hits every layer of the architecture, UI, API, business logic, data store, external service, with real code and real infrastructure. It is not a mock; it is a thin vertical slice.
+
+**The goal:** prove that the end-to-end path works before committing to the full implementation.
+
+**What it is not:**
+- A prototype (a prototype tests a concept; a tracer bullet tests the infrastructure).
+- A spike (a spike is time-boxed exploration; a tracer bullet produces code you keep).
+- A stub (stubs replace real behavior; the tracer bullet uses real behavior).
+
+## When to use it
+
+Use a tracer bullet when:
+- You're integrating two systems for the first time and don't know where the friction is.
+- You're adding a new capability to a system with unfamiliar internals.
+- The architecture requires multiple components to cooperate, and you need to verify the cooperation works before building each component out.
+- You're prototyping a new data model that touches multiple layers.
+
+## How to fire one
+
+**Step 1: Define the thinnest path**
+
+What is the simplest possible user action (or API call) that touches every layer you need to implement? This is your target path.
+
+Example: for a new feature "user uploads an image":
+- Thinnest path: user sends a single 1KB image, it is stored, and the storage URL is returned.
+
+**Step 2: Identify every seam**
+
+Map the layers the path crosses:
+- Presentation: what receives the request?
+- Transport: what format does the request take?
+- Validation: what checks the input?
+- Business logic: what transforms or routes it?
+- Persistence: what stores it?
+- External services: what calls are made?
+
+**Step 3: Implement one thin vertical slice**
+
+Write just enough code to make the tracer path work end-to-end. No error handling, no edge cases, no optimization. The only question is: does the path close?
+
+**Step 4: Verify closure**
+
+Run it. Check each layer produced the expected artifact. A tracer bullet that doesn't reach the end is valuable, it tells you exactly where the friction is before you've invested in the full implementation.
+
+**Step 5: Expand**
+
+Once the path closes, add error handling, validation, edge cases, and tests. You are now implementing on a system you know works.
+
+## Tracer bullet vs. walking skeleton
+
+A walking skeleton (Cockburn) is similar but broader: the minimum architecture that demonstrates a complete feature. A tracer bullet is more specific, it is a single request path through an existing or new system. The terms are used interchangeably in practice; the distinction matters less than the principle.
+
+## Anti-patterns
+
+- **Mocking too much**: if the tracer bullet uses mocked services, you haven't proved the real path works. Mocks are fine for unit tests, not for the tracer.
+- **Doing too much at once**: if the tracer path covers 5 new capabilities, you won't know which one caused the failure. Fire one bullet at a time.
+- **Skipping the tracer for "simple" changes**: the changes most likely to surprise you are the ones that seem simple. Fire anyway.
+- **Throwing the bullet away**: a tracer bullet is production-quality code on a thin path. It is not throwaway. The skeleton expands from it.