0xray 3.4.1 → 3.4.2

package/scripts/node/version-manager.mjs

@@ -160,8 +160,9 @@ function generateChangelogFromCommits(commits) {
 
 /**
  * Count actual framework components
+ * @param {string} [baseDir]
  */
-function getFrameworkCounts() {
+export function getFrameworkCounts(baseDir = rootDir) {
   const counts = {
     agents: 0,
     mcps: 0,
@@ -169,31 +170,29 @@ function getFrameworkCounts() {
   };
   
   // Count agents (.yml files in src/opencode/agents/ — source of truth)
-  const agentsDir = path.join(rootDir, 'src/opencode/agents');
+  const agentsDir = path.join(baseDir, 'src/opencode/agents');
   if (fs.existsSync(agentsDir)) {
     counts.agents = fs.readdirSync(agentsDir)
       .filter(f => f.endsWith('.yml'))
       .length;
   }
   
-  // Count MCP servers (.server.js files in dist/mcps/)
-  const mcpsDir = path.join(rootDir, 'dist/mcps');
-  if (fs.existsSync(mcpsDir)) {
-    counts.mcps = fs.readdirSync(mcpsDir)
-      .filter(f => f.endsWith('.server.js'))
-      .length;
-  } else {
-    // Try node_modules path for published package
-    const nodeModulesMcps = path.join(rootDir, 'node_modules/xray/dist/mcps');
-    if (fs.existsSync(nodeModulesMcps)) {
-      counts.mcps = fs.readdirSync(nodeModulesMcps)
-        .filter(f => f.endsWith('.server.js'))
-        .length;
+  // Consumer MCP count from .mcp.json SSOT (7 servers), not internal dist/mcps inventory
+  const mcpJsonPath = path.join(baseDir, '.mcp.json');
+  if (fs.existsSync(mcpJsonPath)) {
+    try {
+      const mcpJson = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf-8'));
+      const servers = mcpJson.mcpServers || mcpJson.servers || {};
+      counts.mcps = Object.keys(servers).length;
+    } catch {
+      counts.mcps = 7;
     }
+  } else {
+    counts.mcps = 7;
   }
   
   // Count skills (directories in src/skills/ with SKILL.md)
-  const skillsDir = path.join(rootDir, 'src/skills');
+  const skillsDir = path.join(baseDir, 'src/skills');
   if (fs.existsSync(skillsDir)) {
     counts.skills = fs.readdirSync(skillsDir)
       .filter(f => fs.statSync(path.join(skillsDir, f)).isDirectory())
@@ -230,9 +229,21 @@ ${content}
 `;
 }
 
+function changelogHasVersion(newVersion) {
+  const changelogPath = path.join(rootDir, 'CHANGELOG.md');
+  if (!fs.existsSync(changelogPath)) return false;
+  const changelog = fs.readFileSync(changelogPath, 'utf-8');
+  return new RegExp(`^## \\[${newVersion.replace(/\./g, '\\.')}\\]`, 'm').test(changelog);
+}
+
 function updateChangelog(newVersion, changeDescription) {
   const changelogPath = path.join(rootDir, 'CHANGELOG.md');
   let changelog = fs.readFileSync(changelogPath, 'utf-8');
+
+  if (changelogHasVersion(newVersion)) {
+    console.log(`ℹ️  CHANGELOG.md already has [${newVersion}] — skipping duplicate entry`);
+    return;
+  }
   
   // Find the position after the header and insert new entry
   const headerEnd = changelog.indexOf('## [');
@@ -259,6 +270,12 @@ function updateReadme(counts, newVersion) {
   }
   
   let readme = fs.readFileSync(readmePath, 'utf-8');
+
+  // Update header line: **v3.4.1** — 42 agents · 45 skills · 7 MCP servers · ...
+  readme = readme.replace(
+    /^\*\*v[\d.]+\*\* — \d+ agents · \d+ skills · \d+ MCP servers? · \d+ codex terms(?: · [\d,]+ tests)?/m,
+    `**v${newVersion}** — ${counts.agents} agents · ${counts.skills} skills · ${counts.mcps} MCP servers · 68 codex terms · 3,226 tests`
+  );
   
   // Update version badge: [![Version](https://img.shields.io/badge/version-1.6.x-blue...)]
   readme = readme.replace(
@@ -294,6 +311,84 @@ function updateReadme(counts, newVersion) {
   console.log(`✅ Updated README.md (version: ${newVersion}, agents: ${counts.agents}, mcps: ${counts.mcps}, skills: ${counts.skills})`);
 }
 
+export const DOCS_SITE_HEADER_FILES = [
+  'docs-site/docs/README.md',
+  'docs-site/docs/index.md',
+  'docs-site/docs/introduction.md',
+  'docs-site/docs/guides/getting-started.md',
+  'docs-site/docs/full-reference.md',
+];
+
+export function buildDocsHeader(counts, newVersion) {
+  return `**v${newVersion}** — ${counts.agents} agents · ${counts.skills} skills · ${counts.mcps} MCP servers · 68 codex terms · 3,226 tests`;
+}
+
+function syncDocsSiteHeaders(counts, newVersion) {
+  const header = buildDocsHeader(counts, newVersion);
+  const headerRe = /^\*{0,2}v?[\d.]*\*{0,2}\s*—?\s*\d+ agents · \d+ skills · \d+ MCP servers? · \d+ codex terms(?: · [\d,]+ tests)?/m;
+  for (const rel of DOCS_SITE_HEADER_FILES) {
+    const filePath = path.join(rootDir, rel);
+    if (!fs.existsSync(filePath)) continue;
+    let content = fs.readFileSync(filePath, 'utf-8');
+    if (headerRe.test(content)) {
+      content = content.replace(headerRe, header);
+      fs.writeFileSync(filePath, content);
+      console.log(`✅ Updated ${rel} header`);
+    }
+  }
+}
+
+function updatePluginJsonVersion(newVersion) {
+  const pluginPath = path.join(rootDir, '.grok-plugin/plugin.json');
+  if (!fs.existsSync(pluginPath)) return;
+  const plugin = JSON.parse(fs.readFileSync(pluginPath, 'utf-8'));
+  plugin.version = newVersion;
+  fs.writeFileSync(pluginPath, JSON.stringify(plugin, null, 2) + '\n');
+  console.log(`✅ Updated .grok-plugin/plugin.json (version: ${newVersion})`);
+}
+
+function updateConsumerAgentsHeader(newVersion, counts) {
+  const consumerPath = path.join(rootDir, 'AGENTS-consumer.md');
+  if (!fs.existsSync(consumerPath)) return;
+  let content = fs.readFileSync(consumerPath, 'utf-8');
+  content = content.replace(
+    /^\*\*v[\d.]+\*\* — \d+ MCP servers · \d+ skills · \d+ codex terms/m,
+    `**v${newVersion}** — ${counts.mcps} MCP servers · ${counts.skills} skills · 68 codex terms`
+  );
+  fs.writeFileSync(consumerPath, content);
+  console.log(`✅ Updated AGENTS-consumer.md version header`);
+}
+
+function updateSkillsMd(counts, newVersion) {
+  const skillsPath = path.join(rootDir, 'SKILLS.md');
+  if (!fs.existsSync(skillsPath)) {
+    console.log(`⚠️  SKILLS.md not found, skipping`);
+    return;
+  }
+  let content = fs.readFileSync(skillsPath, 'utf-8');
+  content = content.replace(
+    /^\*\*v[\d.]+\*\* — \*\*\d+ skills\*\*/m,
+    `**v${newVersion}** — **${counts.skills} skills**`
+  );
+  fs.writeFileSync(skillsPath, content);
+  console.log(`✅ Updated SKILLS.md version header`);
+}
+
+function applyAgentCountUpdates(content, counts) {
+  let agentsMd = content;
+
+  // Legacy header count update (min compat for old consumer AGENTS.md files only; xray v2 YML SSOT primary)
+  agentsMd = agentsMd.replace(
+    /0xRay\s*2\.0\s*-\s*\d+\s+Agents|0xRay\s*-\s*\d+\s+Agents/,
+    `xray v2 - ${counts.agents} Agents`
+  );
+
+  agentsMd = agentsMd.replace(/\d+\s+MCPs?/g, `${counts.mcps} MCPs`);
+  agentsMd = agentsMd.replace(/\d+\s+Skills?/g, `${counts.skills} Skills`);
+
+  return agentsMd;
+}
+
 /**
  * Update AGENTS.md with actual framework counts
  */
@@ -303,29 +398,38 @@ function updateAgentsMd(counts) {
     console.log(`⚠️  AGENTS.md not found, skipping`);
     return;
   }
-  
-  let agentsMd = fs.readFileSync(agentsPath, 'utf-8');
-  
-  // Legacy header count update (min compat for old consumer AGENTS.md files only; xray v2 YML SSOT primary)
-  agentsMd = agentsMd.replace(
-    /0xRay\s*2\.0\s*-\s*\d+\s+Agents|0xRay\s*-\s*\d+\s+Agents/,
-    `xray v2 - ${counts.agents} Agents`
-  );
-  
-  agentsMd = agentsMd.replace(
-    /\d+\s+MCPs?/g,
-    `${counts.mcps} MCPs`
-  );
-  
-  agentsMd = agentsMd.replace(
-    /\d+\s+Skills?/g,
-    `${counts.skills} Skills`
-  );
-  
-  fs.writeFileSync(agentsPath, agentsMd);
+
+  fs.writeFileSync(agentsPath, applyAgentCountUpdates(fs.readFileSync(agentsPath, 'utf-8'), counts));
   console.log(`✅ Updated AGENTS.md`);
 }
 
+function updateAgentsConsumerMd(counts) {
+  const agentsPath = path.join(rootDir, 'AGENTS-consumer.md');
+  if (!fs.existsSync(agentsPath)) {
+    console.log(`⚠️  AGENTS-consumer.md not found, skipping`);
+    return;
+  }
+
+  fs.writeFileSync(agentsPath, applyAgentCountUpdates(fs.readFileSync(agentsPath, 'utf-8'), counts));
+  console.log(`✅ Updated AGENTS-consumer.md`);
+}
+
+function updateDocsReadme(newVersion) {
+  const docsReadmePath = path.join(rootDir, 'docs/README.md');
+  if (!fs.existsSync(docsReadmePath)) {
+    console.log(`⚠️  docs/README.md not found, skipping`);
+    return;
+  }
+
+  let readme = fs.readFileSync(docsReadmePath, 'utf-8');
+  readme = readme.replace(
+    /img.shields.io\/badge\/version-[\d.]+/,
+    `img.shields.io/badge/version-${newVersion}`
+  );
+  fs.writeFileSync(docsReadmePath, readme);
+  console.log(`✅ Updated docs/README.md (version: ${newVersion})`);
+}
+
 function getCurrentVersion() {
   const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf-8'));
   return pkg.version;
@@ -375,18 +479,7 @@ function updateVersion(newVersion, changeDescription = '') {
   console.log(`✅ Updated package.json`);
   
   // init.sh legacy version key no longer updated (final xray cutover - no historical scaffolding)
-  
-  // Update docs/README.md version badge
-  const docsReadmePath = path.join(rootDir, 'docs/README.md');
-  if (fs.existsSync(docsReadmePath)) {
-    let readme = fs.readFileSync(docsReadmePath, 'utf-8');
-    readme = readme.replace(
-      /img.shields.io\/badge\/version-[\d.]+/,
-      `img.shields.io/badge/version-${newVersion}`
-    );
-    fs.writeFileSync(docsReadmePath, readme);
-    console.log(`✅ Updated docs/README.md (version: ${newVersion})`);
-  }
+  updateDocsReadme(newVersion);
 
   // Update UVM's own version string
   const uvmPath = path.join(rootDir, 'scripts/node/universal-version-manager.js');
@@ -412,7 +505,12 @@ function updateVersion(newVersion, changeDescription = '') {
   console.log(`\n📊 Framework counts: ${counts.agents} agents, ${counts.mcps} MCPs, ${counts.skills} skills`);
   
   updateReadme(counts, newVersion);
+  syncDocsSiteHeaders(counts, newVersion);
+  updatePluginJsonVersion(newVersion);
+  updateConsumerAgentsHeader(newVersion, counts);
   updateAgentsMd(counts);
+  updateAgentsConsumerMd(counts);
+  updateSkillsMd(counts, newVersion);
   
   console.log(`\n🎉 Version updated to ${newVersion}\n`);
 }
@@ -437,8 +535,74 @@ function createGitTag(version, message) {
   }
 }
 
+/** Paths written by release artifact updates (existing files only). */
+export function getReleaseArtifactPaths() {
+  const candidates = [
+    'package.json',
+    'CHANGELOG.md',
+    'README.md',
+    'AGENTS.md',
+    'AGENTS-consumer.md',
+    'SKILLS.md',
+    '.grok-plugin/plugin.json',
+    'docs/README.md',
+    'docs-site/docs/README.md',
+    'docs-site/docs/index.md',
+    'docs-site/docs/introduction.md',
+    'docs-site/docs/guides/getting-started.md',
+    'docs-site/docs/full-reference.md',
+    'docs-site/docs/guides/integrations.md',
+    'docs-site/docs/guides/features-since-3.1.md',
+    'docs-site/docs/guides/features-json.md',
+    'docs-site/docs/guides/memory-routing.md',
+    'docs-site/docs/guides/aside-context.md',
+    'docs-site/docs/guides/repertoire.md',
+    'docs-site/docs/guides/consumer-migration.md',
+    'docs-site/docs/mcp/README.md',
+    'docs-site/docs/agents/README.md',
+    'docs-site/sidebars.ts',
+  ];
+  return candidates.filter((rel) => fs.existsSync(path.join(rootDir, rel)));
+}
+
+/** Update CHANGELOG + README + AGENTS (+ consumer/docs) for current package.json version (no bump). */
+function updateReleaseArtifactsOnly(changeDescription = '') {
+  const current = getCurrentVersion();
+  console.log(`\n📌 Release artifacts for v${current}\n`);
+  const counts = getFrameworkCounts();
+  console.log(`📊 Framework counts: ${counts.agents} agents, ${counts.mcps} MCPs, ${counts.skills} skills`);
+  updateChangelog(current, changeDescription);
+  updateReadme(counts, current);
+  syncDocsSiteHeaders(counts, current);
+  updatePluginJsonVersion(current);
+  updateConsumerAgentsHeader(current, counts);
+  updateDocsReadme(current);
+  updateAgentsMd(counts);
+  updateAgentsConsumerMd(counts);
+  updateSkillsMd(counts, current);
+  runReleaseDocsValidation();
+  console.log(`\n✅ Release artifacts updated for v${current}\n`);
+}
+
+function runReleaseDocsValidation() {
+  try {
+    execSync('node scripts/node/validate-release-docs.mjs', {
+      cwd: rootDir,
+      stdio: 'inherit',
+    });
+  } catch {
+    console.error('\n❌ Release artifact docs failed validation — fix before tagging\n');
+    process.exit(1);
+  }
+}
+
 function main() {
   const args = process.argv.slice(2);
+
+  if (args.includes('--artifacts-only')) {
+    updateReleaseArtifactsOnly('');
+    return;
+  }
   
   // Handle --help flag first
   if (args.includes('--help') || args.includes('-h')) {
@@ -448,6 +612,7 @@ function main() {
     console.log(`  node scripts/node/version-manager.mjs [major|minor|patch] [description]`);
     console.log(`  node scripts/node/version-manager.mjs 1.6.9 "Description of changes"`);
     console.log(`  node scripts/node/version-manager.mjs patch --tag  # auto-changelog + git tag`);
+    console.log(`  node scripts/node/version-manager.mjs --artifacts-only  # CHANGELOG/README/AGENTS/docs`);
     console.log(`\nExamples:`);
     console.log(`  node scripts/node/version-manager.mjs patch  # 1.6.8 -> 1.6.9 (auto-generates changelog from git)`);
     console.log(`  node scripts/node/version-manager.mjs minor  # 1.6.8 -> 1.7.0`);
@@ -472,7 +637,13 @@ function main() {
     console.log(`📊 Framework counts: ${counts.agents} agents, ${counts.mcps} MCPs, ${counts.skills} skills`);
     updateChangelog(current, '');
     updateReadme(counts, current);
+    syncDocsSiteHeaders(counts, current);
+    updatePluginJsonVersion(current);
+    updateConsumerAgentsHeader(current, counts);
+    updateDocsReadme(current);
     updateAgentsMd(counts);
+    updateAgentsConsumerMd(counts);
+    updateSkillsMd(counts, current);
 
     // Update UVM's own version string to match package.json
     const uvmPath = path.join(rootDir, 'scripts/node/universal-version-manager.js');
@@ -521,4 +692,9 @@ function main() {
   }
 }
 
-main();
+const isMainModule =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMainModule) {
+  main();
+}

package/src/integrations/grok/plugin/0xray/hooks/hooks.json

@@ -20,11 +20,28 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo",
-            "args": ["[0xRay] Grok session started with 0xRay governance enabled"]
+            "command": "node",
+            "args": [
+              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js"
+            ],
+            "timeout": 15000
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${XRAY_AI_PATH:-node_modules/0xray}/dist/integrations/grok/hooks/session-start.js"
+            ],
+            "timeout": 15000
           }
         ]
       }
     ]
   }
-}
+}

package/src/mcps/config/__tests__/server-config-registry.test.ts

@@ -69,6 +69,15 @@ describe('ServerConfigRegistry', () => {
     });
   });
 
+  describe('framework path resolution', () => {
+    it('should resolve MCP paths from 0xray package without fallback warning', () => {
+      const config = registry.get('code-review');
+      expect(config?.args?.[0]).toBeDefined();
+      expect(String(config?.args?.[0])).toMatch(/mcps\/knowledge-skills\/code-review\.server\.js$/);
+      expect(String(config?.args?.[0])).not.toContain('node_modules/0xray/dist/dist');
+    });
+  });
+
   describe('default servers', () => {
     it('should have code-review server registered by default', () => {
       expect(registry.has('code-review')).toBe(true);

package/src/mcps/config/server-config-registry.ts

@@ -44,10 +44,12 @@ function resolveFrameworkPaths(): { frameworkRoot: string; mcpServersPath: strin
     if (fs.existsSync(pkgPath)) {
       try {
         const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-        if (pkg.name === '0xray' && pkg.xray) {
-          const xrayCfg = pkg.xray as Record<string, string>;
+        if (pkg.name === '0xray') {
+          const xrayCfg = (pkg.xray ?? {}) as Record<string, string>;
           const frameworkRoot = currentDir;
-          const declaredMcp = xrayCfg.mcpServersPath || (xrayCfg.dist ? join(xrayCfg.dist, 'mcps') : 'dist/mcps');
+          const declaredMcp =
+            xrayCfg.mcpServersPath ||
+            (xrayCfg.dist ? join(xrayCfg.dist, 'mcps') : 'dist/mcps');
           return {
             frameworkRoot,
             mcpServersPath: join(frameworkRoot, declaredMcp),

package/src/mcps/orchestrator/handlers/complexity-handler.ts

@@ -5,6 +5,11 @@
  */
 
 import { frameworkLogger } from '../../../core/framework-logger.js';
+import {
+  buildLeadDevPlan,
+  isLeadDevModeActive,
+  persistLeadDevPlan,
+} from '../../../nucleus/autonomy-kernel.js';
 import { getExecutionPlanner } from '../execution/execution-planner.js';
 import { addObservations, extractComplexityObservations } from '../aside-context.js';
 import type { OrchestrationTask, ComplexityAnalysis } from '../types.js';
@@ -40,11 +45,36 @@ export class ComplexityHandler {
         addObservations(asideId, extractComplexityObservations(analysis));
       }
 
+      const primaryDescription = tasks.map((t) => t.description).filter(Boolean).join(' ');
+      const taskTypes = tasks.map((t) => t.type).filter(Boolean) as string[];
+      const leadDevPlan =
+        isLeadDevModeActive() && primaryDescription
+          ? buildLeadDevPlan(primaryDescription, taskTypes.length ? taskTypes : ['implement'])
+          : null;
+
+      if (leadDevPlan) {
+        try {
+          persistLeadDevPlan(leadDevPlan);
+        } catch (err) {
+          await frameworkLogger.log(
+            'orchestrator.server',
+            'lead-dev-plan-persist-failed',
+            'warning',
+            { error: err instanceof Error ? err.message : String(err) },
+          );
+        }
+      }
+
       return {
         content: [
           {
             type: 'text',
-            text: this.formatComplexityResponse(analysis, recommendations, tasks.length),
+            text: this.formatComplexityResponse(
+              analysis,
+              recommendations,
+              tasks.length,
+              leadDevPlan,
+            ),
           },
         ],
       };
@@ -98,8 +128,29 @@ export class ComplexityHandler {
   private formatComplexityResponse(
     analysis: ComplexityAnalysis,
     recommendations: string[],
-    taskCount: number
+    taskCount: number,
+    leadDevPlan: ReturnType<typeof buildLeadDevPlan> = null,
   ): string {
+    const leadDevSection = leadDevPlan
+      ? `
+
+**Lead-dev plan (codex ${leadDevPlan.codexTerms.join(', ')}):**
+${leadDevPlan.phases
+  .map(
+    (p) =>
+      `### ${p.id} — ${p.name}\n${p.todos
+        .map((t) => `- [ ] ${t.id} (${t.subagent}): ${t.task}`)
+        .join('\n')}`,
+  )
+  .join('\n\n')}
+
+**Test protocol:** ${leadDevPlan.testProtocol.hint}
+
+\`\`\`json
+${JSON.stringify(leadDevPlan, null, 2)}
+\`\`\``
+      : '';
+
     return `🔍 Complexity Analysis Results
 
 **Tasks Analyzed:** ${taskCount}
@@ -126,6 +177,6 @@ ${analysis.agentAssignments
 ${recommendations.map((r) => `• 💡 ${r}`).join('\n')}
 
 **Execution Estimate:** ${analysis.estimatedDuration}ms
-**Parallel Potential:** ${Math.round(analysis.parallelPotential * 100)}%`;
+**Parallel Potential:** ${Math.round(analysis.parallelPotential * 100)}%${leadDevSection}`;
   }
 }

package/src/mcps/orchestrator/server.ts

@@ -140,7 +140,7 @@ export class OrchestratorServer {
           {
             name: 'analyze-complexity',
             description:
-              'Analyze task complexity and recommend optimal orchestration strategy',
+              'Analyze task complexity and recommend orchestration strategy. When lead_dev_mode is on (features.json), includes phased plan + todos + subagent routes.',
             inputSchema: {
               type: 'object',
               properties: {

package/src/mcps/researcher.server.ts

@@ -13,6 +13,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { frameworkLogger } from "../core/framework-logger.js";
 import { tryLLMGovernance } from "../governance/llm-governance-provider.js";
+import { initializeMemoryRouting } from "../memory-routing/index.js";
 import {
   buildMemoryRoutingEvidence,
   formatMemoryRoutingBlock,
@@ -53,6 +54,9 @@ class XrayLibrarianServer extends XrayKnowledgeSkillBase {
   constructor() {
     super("researcher", "3.1.0");
 
+    // Kick off MemoryRoutingProvider load so trap routing is ready in MCP subprocess mode.
+    initializeMemoryRouting();
+
     this.tools = [
       {
         name: "search_codebase",

package/src/skills/boot-orchestrator/SKILL.md

@@ -28,10 +28,6 @@ Framework initialization and boot orchestration.
 - **initialization**: Initialization
 - **framework_startup**: Framework startup
 
-## Usage
-
-This skill provides infrastructure capabilities for boot orchestrator functionality.
-
 ## Integration
 
-Activated when infrastructure capabilities are requested through the skills system.
+Lead-dev boot is handled by SessionStart hook + `orchestrator` skill — see `multi_agent_orchestration.lead_dev_mode` in features.json.

package/src/skills/orchestrator/SKILL.md

@@ -1,11 +1,11 @@
 ---
 source: framework
 name: orchestrator
-description: Multi-agent workflow coordination and task delegation
+description: Multi-agent workflow coordination, lead-dev operating model (codex 67-68), and task delegation. Default when suit is worn — no keywords required.
 author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
-tags: [orchestration, orchestrator]
+tags: [orchestration, orchestrator, lead-dev]
 capabilities:
   - coordinate_agents
   - delegate_tasks
@@ -18,20 +18,43 @@ mcp:
     args: [node_modules/0xray/dist/mcps/orchestrator.server.js]
 ---
 
-# Orchestrator Skill
+# Orchestrator Skill — includes lead-dev operating model
 
-Multi-agent workflow coordination and task delegation.
+When `multi_agent_orchestration.lead_dev_mode` is true in `features.json` (default when suit is worn), this is the **default OS behavior** — not a separate skill or MCP.
 
-## Tools Available
+## Seven rules (codex 67–68)
 
-- **task_coordination**: Task coordination
-- **agent_delegation**: Agent delegation
-- **workflow_management**: Workflow management
+1. Phased plan + detailed todos; assign best subagent; monitor output
+2. Lead dev loops test→fix until green; no permission pings
+3. Per-suite test triage after major changes; full suite last
+4. Lead stays main thread; subagents execute; update todos
+5. Read all console and test output; triage fix rerun
+6. Never defer errors as "pre-existing" — add todo and resolve
+7. Resolve all errors before phase completion
 
-## Usage
+## MCP loop (one tool surface — no autonomy-intake)
 
-This skill provides orchestration capabilities for orchestrator functionality.
+| Step | MCP tool | Notes |
+|------|----------|-------|
+| **Intake + classify** | `analyze-complexity` | Pass `tasks` array; response includes **lead-dev plan JSON** when mode is on |
+| Delegate | `orchestrate-task` | Include agent + sessionId (codex 67) |
+| Monitor | `get-orchestration-status` | Lead updates todos |
+| Major work | researcher + architect-tools + code-review | Auto-listed in plan when complexity > threshold |
 
-## Integration
+## Subagent routing
 
-Activated when orchestration capabilities are requested through the skills system.
+| Task | Subagent |
+|------|----------|
+| Phasing | strategist |
+| Architecture | architect-tools |
+| Research | researcher |
+| Implementation | backend-engineer / frontend-engineer |
+| Test failures | bug-triage |
+| Review | code-review |
+
+## Hooks (rewired, not new MCPs)
+
+- **SessionStart** → `session-start.js` boots lead_dev_mode
+- **PreToolUse** → hints `per_suite_triage_required` on full `npm test`
+
+Config: `features.json` → `multi_agent_orchestration.lead_dev_mode`

package/src/skills/researcher/SKILL.md

@@ -28,10 +28,23 @@ Multi-repo analysis, documentation lookup, and implementation examples.
 - **find_implementations**: Find implementations
 - **analyze_documentation**: Analyze documentation
 
-## Usage
+## When to invoke (autonomy-command)
 
-This skill provides research capabilities for researcher functionality.
+Lead dev dispatches researcher **before** major planning, refactors, or cross-repo work — not only when user says "research."
 
-## Integration
+| Trigger | Action |
+|---------|--------|
+| Major refactor / new phase | `search_codebase`, `get_documentation`, `find_implementation` |
+| Prior art / patterns | Search sibling repos (xray, groover, repertoire) |
+| Proposal analysis | `analyze_proposal` via xray-researcher MCP |
 
-Activated when research capabilities are requested through the skills system.
+## MCP tools (xray-researcher)
+
+- `get_documentation` — module/class docs (`target` required)
+- `search_codebase` — text search in workspace
+- `find_implementation` — locate implementations
+- `analyze_proposal` — governance-aware proposal review
+
+## Return shape for lead
+
+Summarize: findings (3–5 bullets), file paths, recommended next todos. Do not defer work back to lead without concrete patches or todos.