# xray Agents

Quick reference for the 0xRay suit (**4.1**).

**4.1** — a suit that survives the context window.

Confer votes. Burst runs the swarm.

**The suit is the wear.** Three-subsystem autonomous engine (Inference · External Governance · Autonomous Engine) · constitution always on · temperament by host · 4 floors · **Repertoire preferred** (vendored 0.2.9, dest = laws).

**Temperament:** ceremony (analyze-complexity before spawn, confer) is **guided** by default so free-model OpenCode/Hermes stay in check. Frontier hosts (Grok 4.6 class) with `suit_temperament.profile: auto` **warn** on spawn-without-plan; Codex 11/29/69 still **deny**. Missing `suit_temperament` stays guided. See `docs-site/docs/architecture/v3-from-v2.md`.

## Hot-swap

Before other work, Read `.xray/state/STATION.md`. Compaction and host change are the same cut. Continue the card. A packet and its card follow the house packet rule (`grok-bot/OP-PROC.md` #packet). The card key is the issue or pull. Do not hand-post a card. When Bifrost is on, the only TUI monitor is `$XRAY_MAIN/house/live/tools/inbox-watch.sh <seat>`. Do not restart the job. Grok does not inject the card (OpenCode does) — this Read is the Grok contract. Do not thicken the Grok exo.

**Lead cadence:** a peer wearing this file + Station + Repertoire continues without a command stream. Dummy bodies test `SKILLS.md`. Same-sess bodies wear the suit and keep a Station card. Always branch + worktree + PR. Ship when mill-gate D + `foundry gate` PASS (`grok-bot/OP-PROC.md` Decision matrix) — green CI is not ship. npm OTP in a browser, then poll the new version before moving on. Loop until Station is done. Live ticks and moving workstreams — not idle pacers. Same critic (resume only). Disk SSOT: `grok-bot/OP-PROC.md` (team specifics live in `house/`). Playbook: `orchestrator` skill.

## What is xray?

0xRay is a three-subsystem autonomous engine. The suit is the wear. The host you already run wears it. When the window closes, the next session wakes with the job.

- **Inference** — proposals, reflection, memory routing (Repertoire organ on in 4.0)
- **External Governance** — Dynamo Solar SSOT, 69-term Codex. Judgement stays on.
- **Autonomous Engine** — thinDispatch 7-flow, AsideContext, confidence gate

Agents are declared in `src/opencode/agents/*.yml` — the YML SSOT. Skills live in `src/skills/*/SKILL.md` — see [SKILLS.md](SKILLS.md) for the exo catalog. Consumer default plant is **mill + inspect**. The mill suit also wears every catalog skill and every role file (`AGENTS-consumer.md` → `AGENTS.md`). Factory hangar shops coexist via shop plant. See [llms.txt](llms.txt).

## Consumer MCP surface (7 servers)

Registered in `.mcp.json`, invoked via `npx -y 0xray mcp <cmd>`:

| Server | Role |
|--------|------|
| `xray-governance` | Proposal governance, codex snapshot, quality gates |
| `xray-skills` | 45 knowledge skills + `invoke-skill` |
| `xray-orchestrator` | thinDispatch, AsideContext, confidence gate |
| `xray-enforcer` | Codex compliance, rule validation |
| `xray-researcher` | Codebase exploration, memory-routing enrichment |
| `xray-code-review` | Proposal quality, code review deliberation |
| `xray-architect-tools` | System design, architecture decisions |

Governance deliberation: **code-review**, **security-audit**, **researcher** within the 7-server set.

## Postinstall

`postinstall.cjs` links vendored `@0xray/repertoire` and prints `npx 0xray wear`. It does not write `.mcp.json` or the chat bridges.

`npx 0xray wear` runs `installAllBridges()` from `install-bridges.cjs`:

1. `AGENTS-consumer.md` → `AGENTS.md` (does **not** write consumer-root `SKILLS.md`)
2. Fasten mill plant (`mill` + `inspect`). Fasten is **foundry-plant/0**: builtin plant is mill+inspect only. `foundry.json` `"plant": "@0xray/blip"` (aliases `"plant": "blip"` / `"plant": "sound"`) fastens whatever that mill package declares (looker, vibe, mixer, blip-inspect, blip-vibe, blip-looker, sound-inspect, sound-mixer live in the mill). The mill suit also wears every catalog skill and every OpenCode role file. A blip or sound seat fastens that plant only. A name outside the fastened set still fails inspect.
3. `.gitignore.default` → `.gitignore` (if absent)
4. `.xray/` config (`codex.json`, `features.json`, `config.json`) then overlay their plant
5. `.mcp.json` (7 servers)
6. Four chat bridges: OpenCode, Grok, Hermes, OpenClaw. Grok last-mile dest is project `.grok/plugins/0xray` (shared HOME does not last-wins clobber machine `~/.grok/plugins/0xray`)
7. Cursor fifth wear: fasten `.cursor/hooks.json` + relative `.cursor/hooks/*.sh`. Rewrite leftover `XRAY_AI_PATH=` one-liners. Not a fifth chat TUI.
8. Optional git hooks

**Shop plant:** `shop-extract`, `shop-witness`, `shop-pin` (groover-hangar) are first-class with mill plant. Extra shops: `foundry.json` `shopPlant`. Not `"costume": true`. `npx @0xray/foundry inspect --skip-live` is the receipt.

**Sound plant:** Dist audio beds are a mill (`@0xray/blip`), not a foundry organ catalog. Alias `"plant": "sound"` + `npx @0xray/foundry sound render` writes a crystal-clear wav (Rippel membrane/metal/mixer, not a sine toy) and a bed receipt. `sound-mixer` (`npx @0xray/foundry sound mix`) lives in the mill and levels every genre × tempo × motif — hats, plate, glue — not just the last bed. CLI shim `foundry sound` remains (0.1.11+). Inspect is mill-exported — not fake code-mill skills on a sound seat.

**Blip plant:** Product mill `@0xray/blip` (not a mill copy). Hangar shop pair later. Alias `"plant": "blip"` + `npx @0xray/foundry blip render --brief "..." --mode still|motion:orb` writes a 4.44s mp4 **with an audio bed**. Registry v0: still + Rippel five (`orb` `swirl` `snap` `waves` `spark`). Motions are Rippel v2 `VisualConfig.circles` at ≥720p — sharp look + tempo/frequency animation on all five (wireframe is `--engine wireframe` only). Auto bed syncopates to the motion grid. Each mint wears a sparse seed mesh plus field accents (stars, grids, gradients, blinkers); receipt `visualConfig.mesh` + `visualConfig.field` are the fingerprints. `kapow` is a design opt (`motion:kapow`) — two-tier comic stamp on the same stanza. Organs live in the mill: `blip-vibe` (`npx @0xray/foundry blip vibe`) scores stamp density; `blip-looker` (`npx @0xray/foundry blip look`) is the friend hitting replay; appeal 0–10; ship bar is **8**. `still` is the Power Plant ident — plate dissolves over 4.44s at ≥720p (`#08090B` `#F5F7FA` `#3DE0E8` `#F5C518` `#4A7FD4`), not a frozen poster. Adding an organ is a mill publish, not an xray catalog PR. CLI shim `foundry blip` remains (0.1.11+). Inspect checks duration / mode id / file / audio.

## Memory routing + Repertoire (preferred, v3.3+)

**Wear Repertoire.** It is the long-term judgment organ. Dest is named invariants (factory + stack laws), not hangar `repo-*` or git slugs. **Station is the wake ticket** (Read `.xray/state/STATION.md`) — not a substitute for Repertoire. The worn mill reads the **project copy** under `.xray/state/repertoire/`. 0.1.0–0.1.8 were the same judgment organ; do not pin 0.1.8. Split: `docs-site/docs/guides/station-vs-repertoire.md`.

`xray/features.json` → `memory_routing` (schema: `features.schema.json`):

```json
"memory_routing": {
 "enabled": true,
 "provider": "repertoire",
 "module_path": "node_modules/@0xray/repertoire/dist/provider/memory-routing-provider.js",
 "config": {
 "signalsPath": ".xray/state/repertoire/curated_signals.json",
 "statePath": ".xray/state/repertoire/inference-state.json",
 "feedbackDir": ".xray/state/repertoire/feedback"
 }
}
```

| Integration | Surface |
|-------------|---------|
| ExecutionPlanner | `enrichTasks`, `getTaskConfidence`, `selectAgent` |
| thinDispatch | `resolveThinDispatch` |
| Researcher | `researcher-confidence.ts`, `MEMORY_ROUTING:` block |
| AsideContext | `buildInheritedContext` → `inheritedContext.memoryRouting` |
| Feedback | Per-task `ingestFeedback` |

**External MCP:** `npx @0xray/repertoire mcp` — `repertoire__get_task_confidence`, etc.

## AsideContext (v3.2+)

`src/mcps/orchestrator/aside-context.ts` — bounded subcontexts for orchestration:

- `spawnAside` / `closeAside` on `orchestrate-task`, `analyze-complexity`, `govern-and-apply`
- Observation extractors: governance, orchestration, complexity
- Repertoire context flows via `ExecutionPlan.memoryContext`

## User asides (parallel work tracks)

**Not** AsideContext — user-declared parallel tracks (worktree-like):

- SSOT: `.xray/state/asides/{id}.json` + `_active.json`; todos use `{asideId}.a.*` (namespaced)
- Intake: `analyze-complexity` with `userAsideId` (+ optional `worktree`, `branch`)
- Activate / resume main: `orchestrate-task` with `userAsideId` or `clearActiveAside: true`
- Spawn gate routes to active aside plan; session-boot exposes `activeAside`
- Config: `features.json` → `multi_agent_orchestration.user_asides.enabled`

## Confidence gate (v3.3.1)

`ExecutionPlanner.calculateTaskComplexity()` + `getTaskConfidence()` — complexity boost and ontological-trap routing.

## Nucleus exports (v3.4.0)

`0xray/nucleus` and `0xray/nucleus/*` — `handleGovernRequest`, plugin-registry, thinDispatch.

## Changes since 3.1

| Version | Change |
|---------|--------|
| **3.4.1** | `install-bridges.cjs`, 7 MCPs `npx`, release pipeline + docs sync |
| **3.4.0** | Nucleus exports, governance closure, verify gate |
| **3.3.1** | Confidence gate, repertoire researcher wiring |
| **3.3.0** | Memory routing + Repertoire provider |
| **3.2.0** | AsideContext wired, SelfProposalEngine, pre-tool-use hook |
| **3.1.1** | 0xRay rename, marketplace, AGENTS/SKILLS consumer seeding |

**Removed:** `hermes bridge`, `.opencode/xray/` fallback, `advanced-features/`.

## Default operating mode: autonomy-command

When the suit is worn, **autonomy-command** is ON by default (codex 67–68). Lead dev: phased todos, subagent dispatch, per-suite test triage, loop until green. Ships to consumers via `AGENTS-consumer.md`.

Docs: [guides/autonomy-command](docs-site/docs/guides/autonomy-command.md) · Skill: `src/skills/autonomy-command/SKILL.md`

## Core tenets

- YML agents + SKILL.md are the SSOT
- Zero manual registration
- Governance precedes action (Dynamo)
- MCP surfaces are the primary skill interface
- frameworkLogger only (never `console.*`)

## File organization

| File Type | Save To |
|-----------|---------|
| Reflections | `docs/reflections/` |
| Logs | `logs/` |
| Scripts | `scripts/` or `scripts/bash/` |
| Tests | `src/__tests__/` |
| Source | `src/` |
| Config | `.xray/` or `config/` |

**Root essentials only:** `README.md`, `CHANGELOG.md`, `package.json`, `AGENTS.md`, `SKILLS.md`, `llms.txt`, `tsconfig.json`.

## Available agents (42 YML surfaces)

Invoke via `@agent-name` in OpenCode:

| Agent | Purpose |
|-------|---------|
| `@enforcer` | Codex compliance & error prevention |
| `@orchestrator` | Multi-step task coordination |
| `@architect` | System design & technical decisions |
| `@security-auditor` | Vulnerability detection |
| `@code-reviewer` | Quality assessment |
| `@refactorer` | Technical debt elimination |
| `@testing-lead` | Testing strategy |
| `@bug-triage-specialist` | Error investigation |
| `@researcher` | Codebase exploration |
| `@frontend-engineer` | React, Vue, Angular, responsive design |
| `@backend-engineer` | REST/GraphQL APIs, microservices |
| `@database-engineer` | Schema design, query optimization |
| `@devops-engineer` | CI/CD, infrastructure, containers |
| `@mobile-developer` | iOS, Android, React Native, Flutter |
| `@storyteller` | Narrative reflections, technical stories |
| `@strategist` | Architecture decisions, risk analysis |
| `@performance-engineer` | Profiling, benchmarking |
| `@frontend-ui-ux-engineer` | Visual design, accessibility |
| `@multimodal-looker` | Media / screenshot analysis |
| `@log-monitor` | Log diagnostics |
| `@code-analyzer` | Code metrics, pattern detection |
| `@content-creator` | SEO copy, technical content |
| `@growth-strategist` | Marketing strategy |
| `@seo-consultant` | Technical SEO |
| `@tech-writer` | API docs, READMEs, changelogs |
| `@hermes-agent` | Hermes bridge operations |
| `@boot-orchestrator` | Framework boot orchestration |
| `@processor-pipeline` | Data processing pipelines |
| `@state-manager` | Session / state persistence |
| `@session-management` | Session lifecycle |
| `@inference-improve` | Autonomous inference improvement |
| `@model-health-check` | Model health diagnostics |
| `@framework-compliance-audit` | Framework compliance |
| `@lint` | Code linting |
| `@auto-format` | Automated formatting |
| `@git-workflow` | Git workflow management |
| `@api-design` | REST/GraphQL API design |
| `@architecture-patterns` | Architecture patterns |
| `@performance-analysis` | Performance analysis |
| `@performance-optimization` | Performance optimization |
| `@project-analysis` | Project health metrics |
| `@security-scan` | Security vulnerability scanning |
| `@testing-best-practices` | Testing QA |
| `@ui-ux-design` | UI/UX design |

Full skill mapping: [SKILLS.md](SKILLS.md).

## thinDispatch routing

- Simple (≤15): single-agent
- Moderate (≤25): multi-agent
- Complex (≤50): orchestrator-led
- Enterprise (>50): orchestrator-led

## Documentation

| Topic | Path |
|-------|------|
| Agent map (`llms.txt`) | `llms.txt` |
| Foundry / mill plant | `docs-site/docs/architecture/v4-foundry.md` |
| Features since 3.1 | `docs-site/docs/guides/features-since-3.1.md` |
| features.json | `docs-site/docs/guides/features-json.md` |
| Platform integrations | `docs-site/docs/guides/integrations.md` |
| Memory routing | `docs-site/docs/guides/memory-routing.md` |
| Repertoire | `docs-site/docs/guides/repertoire.md` |
| Station vs Repertoire 0.1 | `docs-site/docs/guides/station-vs-repertoire.md` |
| AsideContext | `docs-site/docs/guides/aside-context.md` |
| Consumer migration | `docs-site/docs/guides/consumer-migration.md` |
| Bifrost board | `docs-site/docs/plates/bifrost.md` |
| Seat wake | `grok-bot/templates/house/fleet/WAKE-ROUTINE.md` |
| Fleet lexicon | `grok-bot/LEXICON.md` |
| Docusaurus site | https://docs.0xray.dev/ |

## Live board

When `LIVE_URL` is set, the board seats see is the collector board (`house/live/feed/live_mesh.py`). When `LIVE_URL` is unset, the board is hand-kept `house/WAVEBOARD.md`. A cloud agent is a board row (`bcId`, owning seat, linked card, state `running`, `finished`, or `failed`). The seat wake is `grok-bot/templates/house/fleet/WAKE-ROUTINE.md`: `live-inbox <seat> --turn start` on every turn, and `--turn end` on every exit. `live-inbox` requires `LIVE_URL` and `SEAT_KEYS_DIR`. A missing or empty one exits 2 and names it. `LIVE_CURSORS` is not required. The cursor folder rule is `grok-bot/OP-PROC.md#cursor-folder`. A stuck card sends L1 to the next owner or the card owner, and L3 repeats to that seat. An unacked line and a missing handoff stay on that seat through L3. CoS is not woken to reassign.

## Release artifacts

`npm run release:patch` updates: `package.json`, `CHANGELOG.md`, `README.md`, `AGENTS.md`, `AGENTS-consumer.md`, `SKILLS.md`, `llms.txt`, Docusaurus guides.