0xray 3.5.4 → 4.0.0

package/.opencode/skills/researcher/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: researcher
 description: Multi-repo analysis, documentation lookup, and implementation examples
-author: StrRay Framework
+author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
 tags: [research, researcher]
@@ -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.

package/.opencode/skills/security-audit/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: security-audit
 description: Security auditing and compliance validation
-author: StrRay Framework
+author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
 tags: [security, security, audit]

package/.opencode/skills/security-scan/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: security-scan
 description: Security vulnerability scanning and assessment
-author: StrRay Framework
+author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
 tags: [security, security, scan]

package/.opencode/skills/session-management/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: session-management
 description: Manage user sessions and persistent state
-author: StrRay Framework
+author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
 tags: [infrastructure, session, management]

package/.opencode/skills/state-manager/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: state-manager
 description: Application state management and persistence
-author: StrRay Framework
+author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
 tags: [infrastructure, state, manager]

package/.opencode/skills/storyteller/SKILL.md

@@ -96,7 +96,7 @@ codex_terms: [5, 7, 32]  # Related Codex term numbers
 ```markdown
 ## What Next?
 
-- Related Codex terms: [codex.json](../../.opencode/xray/codex.json)
+- Related Codex terms: [codex.json](../../../../.xray/codex.json)
 - Next story to write: [suggestion]
 ```
 

package/.opencode/skills/strategist/SKILL.md

@@ -30,3 +30,15 @@ Think deeply before recommending. Consider trade-offs and long-term implications
 - Risk analysis and mitigation planning
 - High-level system design and framework evolution
 - Technical debt identification and prioritization
+
+## When to invoke (autonomy-command)
+
+Lead dev dispatches strategist when `analyze-complexity` score **>25** or work spans multiple repos/phases.
+
+| Output required | Format |
+|-----------------|--------|
+| Phased plan | Phase N + goal + definition of done |
+| Todo breakdown | ID, task, subagent assignment |
+| Risks | Top 3 with mitigations |
+
+Use `orchestrate-task` or Task subagent. Return actionable todos — not essays.

package/.opencode/skills/testing-best-practices/SKILL.md

@@ -0,0 +1,37 @@
+---
+source: framework
+name: testing-best-practices
+description: Testing best practices and quality assurance
+author: Xray Framework
+version: 1.0.0
+schema_version: "1.0"
+tags: [testing, testing, best, practices]
+capabilities:
+  - write_unit_tests
+  - write_integration_tests
+  - analyze_coverage
+dependencies: []
+
+mcp:
+  testing-best-practices:
+    command: node
+    args: [node_modules/0xray/dist/mcps/knowledge-skills/testing-best-practices.server.js]
+---
+
+# Testing Best Practices Skill
+
+Testing best practices and quality assurance.
+
+## Tools Available
+
+- **testing_practices**: Testing practices
+- **quality_assurance**: Quality assurance
+- **best_practices**: Best practices
+
+## Usage
+
+This skill provides testing capabilities for testing best practices functionality.
+
+## Integration
+
+Activated when testing capabilities are requested through the skills system.

package/.opencode/skills/testing-strategy/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: testing-strategy
 description: Design comprehensive testing strategies and optimize test coverage
-author: StrRay Framework
+author: Xray Framework
 version: 1.0.0
 schema_version: "1.0"
 tags: [testing, strategy, coverage, quality]
@@ -38,6 +38,17 @@ This skill helps design and optimize testing strategies for:
 - Test coverage optimization
 - Testing best practices implementation
 
-## Integration
+## Per-suite triage (autonomy-command rule 3)
 
-Provides testing expertise and coverage analysis when requested through the skills system.
+After major changes, **do not** run the full test suite first.
+
+```text
+1. Identify affected test file(s) from the diff
+2. Run ONE suite: npm test -- path/to/focused.test.ts
+3. Read ALL failure output — triage root cause
+4. Fix → rerun that suite until green
+5. Repeat for each affected suite
+6. Only then: npm test (full suite gate)
+```
+
+Lead dev owns every failure. No "pre-existing" deferrals.

package/.opencode/skills/ui-ux-design/SKILL.md

@@ -2,7 +2,7 @@
 source: framework
 name: ui-ux-design
 description: User interface and user experience design with mobile-first approach, cognitive simplicity, and accessibility-first principles
-author: StrRay Framework
+author: Xray Framework
 version: 2.1.0
 schema_version: "1.0"
 tags: [design, ui, ux, accessibility, mobile-first, visual-hierarchy, wcag, contrast, color-theory, dont-make-me-think]

package/.opencode/skills/xray-orchestrator/index.ts

@@ -0,0 +1,267 @@
+/**
+ * xray Orchestrator Skill
+ *
+ * OpenClaw skill that provides xray orchestration commands.
+ *
+ * @since 2026-03-14
+ */
+
+const API_BASE = process.env.XRAY_API_URL || 'http://localhost:18431';
+const API_KEY = process.env.XRAY_API_KEY;
+
+interface ParsedArgs extends Record<string, unknown> {
+  _?: string[];
+}
+
+function parseArgs(input: string): { command: string; args: ParsedArgs } {
+  const parts = input.trim().split(/\s+/);
+  const command = parts[0] || '';
+  const args: ParsedArgs = {};
+
+  for (const part of parts.slice(1)) {
+    if (part.startsWith('--')) {
+      const key = part.slice(2);
+      args[key] = true;
+    } else if (part.includes(':')) {
+      const colonIdx = part.indexOf(':');
+      const key = part.slice(0, colonIdx);
+      const value = part.slice(colonIdx + 1);
+      if (key && value) args[key] = value;
+    } else if (!args._) {
+      args._ = [];
+      args._.push(part);
+    } else {
+      args._.push(part);
+    }
+  }
+
+  return { command, args };
+}
+
+async function callAPI(endpoint: string, data?: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+
+  if (API_KEY) {
+    headers['Authorization'] = `Bearer ${API_KEY}`;
+  }
+
+  const response = await fetch(`${API_BASE}${endpoint}`, {
+    method: data ? 'POST' : 'GET',
+    headers,
+    body: data ? JSON.stringify(data) : null,
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+    throw new Error(error.error || `HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+export async function handleSkill(input: string): Promise<string> {
+  const { command, args } = parseArgs(input);
+
+  try {
+    switch (command.toLowerCase()) {
+      // xray primary
+      case 'xray':
+      case 'xray-status':
+        return await handleStatus();
+
+      case 'xray-analyze':
+        return await handleAnalyze(args);
+
+      case 'xray-code':
+        return await handleCodeReview(args);
+
+      case 'xray-file':
+        return await handleFileRead(args);
+
+      case 'xray-exec':
+        return await handleExec(args);
+
+      case 'xray-help':
+        return handleHelp(args._ as string | undefined);
+
+      default:
+        return formatHelp();
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `❌ Error: ${message}`;
+  }
+}
+
+async function handleStatus(): Promise<string> {
+  const health = await callAPI('/health') as { status: string; version: string; uptime: number };
+
+  return `🤖 xray Status
+
+• Status: ${health.status}
+• Version: ${health.version}
+• Uptime: ${formatUptime(health.uptime)}
+
+Use /xray-help for available commands.`;
+}
+
+async function handleAnalyze(args: Record<string, unknown>): Promise<string> {
+  const filePath = (args._ as string[])?.[0];
+
+  if (!filePath) {
+    return '❌ Usage: /xray-analyze <file-path>';
+  }
+
+  const result = await callAPI('/api/agent/invoke', {
+    command: 'analyze',
+    args: { filePath },
+  }) as { success: boolean; result?: unknown; error?: string };
+
+  if (!result.success) {
+    return `❌ Analysis failed: ${result.error}`;
+  }
+
+  return `✅ Analysis complete for ${filePath}\n\n${JSON.stringify(result.result, null, 2)}`;
+}
+
+async function handleCodeReview(args: Record<string, unknown>): Promise<string> {
+  const filePath = (args._ as string[])?.[0];
+  const fix = args.fix === true;
+
+  if (!filePath) {
+    return '❌ Usage: /xray-code <file-path> [--fix]';
+  }
+
+  const result = await callAPI('/api/agent/invoke', {
+    command: 'code-review',
+    args: { filePath, fix },
+  }) as { success: boolean; result?: unknown; error?: string };
+
+  if (!result.success) {
+    return `❌ Code review failed: ${result.error}`;
+  }
+
+  return `✅ Code review complete for ${filePath}\n\n${JSON.stringify(result.result, null, 2)}`;
+}
+
+async function handleFileRead(args: Record<string, unknown>): Promise<string> {
+  const rest = args._ as string[] | undefined;
+  const filePath = rest?.[0];
+  const range = rest?.[1];
+
+  if (!filePath) {
+    return '❌ Usage: /xray-file <file-path> [line-start:line-end]';
+  }
+
+  let lineRange: { start?: number; end?: number } | undefined;
+  if (range?.includes(':')) {
+    const [rawStart, rawEnd] = range.split(':');
+    lineRange = {};
+    if (rawStart) lineRange.start = Number(rawStart);
+    if (rawEnd) lineRange.end = Number(rawEnd);
+  }
+
+  const result = await callAPI('/api/agent/invoke', {
+    command: 'read',
+    args: { filePath, ...lineRange },
+  }) as { success: boolean; result?: unknown; error?: string };
+
+  if (!result.success) {
+    return `❌ File read failed: ${result.error}`;
+  }
+
+  return `📄 ${filePath}\n\`\`\`\n${result.result}\n\`\`\``;
+}
+
+async function handleExec(args: Record<string, unknown>): Promise<string> {
+  const command = (args._ as string[])?.[0];
+
+  if (!command) {
+    return '❌ Usage: /xray-exec <command>';
+  }
+
+  const result = await callAPI('/api/agent/invoke', {
+    command: 'exec',
+    args: { command },
+  }) as { success: boolean; result?: unknown; error?: string };
+
+  if (!result.success) {
+    return `❌ Execution failed: ${result.error}`;
+  }
+
+  return `✅ Command executed\n\n${JSON.stringify(result.result, null, 2)}`;
+}
+
+function handleHelp(command?: string): string {
+  if (command) {
+    switch (command) {
+      case 'xray-analyze':
+        return `📖 /xray-analyze <file-path>
+
+Analyze code in a file.
+
+Example: /xray-analyze src/index.ts`;
+
+      case 'xray-code':
+        return `📖 /xray-code <file-path> [--fix]
+
+Perform code review on a file.
+Use --fix to attempt automatic fixes.
+
+Example: /xray-code src/utils/helper.ts
+Example: /xray-code src/utils/helper.ts --fix`;
+
+      case 'xray-file':
+        return `📖 /xray-file <file-path> [line-start:line-end]
+
+Read a file.
+Optionally specify line range.
+
+Example: /xray-file src/index.ts
+Example: /xray-file src/index.ts 1:50`;
+
+      case 'xray-exec':
+        return `📖 /xray-exec <command>
+
+Execute an arbitrary command.
+
+Example: /xray-exec list files src/`;
+
+      default:
+        return `Unknown command: ${command}`;
+    }
+  }
+
+  return formatHelp();
+}
+
+function formatHelp(): string {
+  return `🤖 xray Orchestrator
+
+Available Commands:
+• /xray - Show status
+• /xray-analyze <file> - Analyze code
+• /xray-code <file> [--fix] - Code review
+• /xray-file <file> [lines] - Read file
+• /xray-exec <command> - Execute command
+• /xray-help [command] - Show help
+
+Use /xray-help <command> for detailed usage.`;
+}
+
+function formatUptime(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) return `${days}d ${hours % 24}h`;
+  if (hours > 0) return `${hours}h ${minutes % 60}m`;
+  if (minutes > 0) return `${minutes}m`;
+  return `${seconds}s`;
+}
+
+// Export for OpenClaw
+export default { handleSkill };

package/.xray/codex.json

@@ -1,6 +1,6 @@
 {
   "version": "3.1.0",
-  "lastUpdated": "2026-06-05",
+  "lastUpdated": "2026-08-24",
   "errorPreventionTarget": 0.998,
   "terms": {
     "1": {
@@ -546,6 +546,14 @@
       "category": "process",
       "zeroTolerance": false,
       "enforcementLevel": "high"
+    },
+    "69": {
+      "number": 69,
+      "title": "No New MCP, Skill, or Handler Surface",
+      "description": "Do not add parallel APIs. Rewire existing MCP servers, skills, and orchestrator handlers. PreToolUse denies creating new src/mcps/*.server.ts, src/skills/*/SKILL.md, or orchestrator *-handler files. Existing files may be rewritten.",
+      "category": "process",
+      "zeroTolerance": true,
+      "enforcementLevel": "blocking"
     }
   },
   "interweaves": [
@@ -589,10 +597,11 @@
     "No type errors or any usage": true,
     "Agent spawns go through governor": true,
     "Subagent spawning prevented": true,
-    "PostProcessor validation passes": true
+    "PostProcessor validation passes": true,
+    "No new MCP/skill/handler surface": true
   },
   "frameworkAlignment": {
     "OpenCode": "v1.1.1",
-    "0xRay": "v2.0.0"
+    "0xRay": "v4.0.0"
   }
 }

package/.xray/features.json

@@ -1,7 +1,17 @@
 {
   "$schema": "./features.schema.json",
-  "version": "3.4.3",
+  "version": "4.0.0",
   "description": "0xRay Framework - Unified Feature Configuration",
+  "suit_temperament": {
+    "profile": "auto",
+    "host_defaults": {
+      "grok": "frontier",
+      "hermes": "guided",
+      "opencode": "guided",
+      "openclaw": "guided",
+      "generic": "guided"
+    }
+  },
   "token_optimization": {
     "enabled": true,
     "max_context_tokens": 20000,
@@ -36,7 +46,19 @@
     "phased_plan_threshold": 25,
     "auto_consult_major_work": true,
     "no_new_surface": true,
-    "auto_chain_delegations": true
+    "auto_chain_delegations": true,
+    "plan_stale_hours": 8,
+    "plan_archive_marker_hours": 24,
+    "user_asides": {
+      "enabled": true,
+      "auto_provision_worktree": false
+    }
+  },
+  "grok_postprocessor_light": true,
+  "inference_session_capture": {
+    "enabled": true,
+    "min_commits": 3,
+    "lookback_commits": 20
   },
   "autonomous_reporting": {
     "enabled": true,
@@ -136,10 +158,14 @@
     "min_success_rate": 0.7
   },
   "memory_routing": {
-    "enabled": false,
-    "provider": "null",
-    "module_path": "",
-    "config": {}
+    "enabled": true,
+    "provider": "repertoire",
+    "module_path": "node_modules/@0xray/repertoire/dist/provider/memory-routing-provider.js",
+    "config": {
+      "signalsPath": "node_modules/@0xray/repertoire/data/curated_signals.json",
+      "statePath": ".xray/state/repertoire/inference-state.json",
+      "feedbackDir": ".xray/state/repertoire/feedback"
+    }
   },
   "synthesis": {
     "enabled": false,

package/.xray/features.schema.json

@@ -28,6 +28,93 @@
         "required": ["module_path"]
       }
     },
+    "multi_agent_orchestration": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "lead_dev_mode": { "type": "boolean" },
+        "plan_stale_hours": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Archive lead-dev-plan when all todos still pending after N hours"
+        },
+        "plan_archive_marker_hours": {
+          "type": "number",
+          "minimum": 1,
+          "description": "How long spawn-plan-stale persists after a stale plan was archived (hours)"
+        },
+        "confer_on_synthesis": {
+          "type": "boolean",
+          "description": "Auto-run 3-agent confer quorum at synthesis checkpoint (default true)"
+        },
+        "confer": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "on_synthesis": { "type": "boolean" }
+          },
+          "description": "Mandatory researcher/architect-tools/code-review quorum"
+        },
+        "sibling_repos": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "type": "string" },
+              {
+                "type": "object",
+                "properties": {
+                  "path": { "type": "string" },
+                  "label": { "type": "string" }
+                },
+                "required": ["path"]
+              }
+            ]
+          },
+          "description": "Sibling workspace roots (e.g. UI repo when MCP host is cwd)"
+        },
+        "user_asides": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "auto_provision_worktree": {
+              "type": "boolean",
+              "description": "Run guarded git worktree add on analyze-complexity aside intake when worktree+branch set"
+            }
+          }
+        }
+      }
+    },
+    "grok_postprocessor_light": {
+      "type": "boolean",
+      "description": "Opt-in lightweight postprocessor marker + activity.log on Grok write tools"
+    },
+    "inference_session_capture": {
+      "type": "object",
+      "description": "git post-commit → captureSessionInference when commit threshold is met",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "min_commits": { "type": "integer", "minimum": 1 },
+        "lookback_commits": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "suit_temperament": {
+      "type": "object",
+      "description": "0xRay 4.0 — constitution always on; ceremony scales by host. Missing key = guided (existing consumers unchanged).",
+      "properties": {
+        "profile": {
+          "type": "string",
+          "enum": ["auto", "frontier", "guided", "strict"],
+          "description": "auto = host_defaults (grok→frontier, hermes/opencode/openclaw→guided)"
+        },
+        "host_defaults": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "enum": ["frontier", "guided", "strict"]
+          }
+        }
+      }
+    },
     "synthesis": {
       "type": "object",
       "properties": {