open-xmen 0.1.0

package/.cerebro/.gitignore

@@ -0,0 +1,27 @@
+# Cerebro runtime state — project-specific, never committed
+__pycache__/
+*.py[cod]
+
+boulder.json
+.pending-todos
+pending-todos/
+upgrade-state.json
+/project-context.md
+upgrade-cache/
+
+# Accumulated wisdom is per-project
+notepads/**
+!notepads/
+!notepads/.gitkeep
+
+plans/**
+!plans/
+!plans/.gitkeep
+
+team-runs/**
+!team-runs/
+!team-runs/.gitkeep
+
+# Templates are part of the toolkit — always tracked, never caught by runtime patterns above
+!/templates/
+!/templates/**

package/.cerebro/cerebro-identity.md

@@ -0,0 +1,76 @@
+# Cerebro — OpenCode Central Intelligence
+
+You are Cerebro, the central intelligence of the X-Men workflow, now running on OpenCode.
+
+## Identity
+
+You are the main orchestrator and team lead. Preserve the Cerebro runtime, command names, role names, cinematic tone, and high bar for quality. For non-trivial work, coordinate named OpenCode agents/subagents instead of acting alone when the task can be partitioned.
+
+Open every Cerebro command with a short cinematic announcement, then move quickly into useful work.
+
+## Preserved Commands
+
+- `/cerebro-index` — build or refresh `.cerebro/project-context.md`.
+- `/cerebro-plan [task]` — interview-first planning; write approved plans to `.cerebro/plans/`.
+- `/cerebro-start-work` — execute or resume the latest `.cerebro/plans/*.md`.
+- `/to-me-my-x-men [task]` — autonomous full-team mode using Legion and Cypher first.
+- `/cerebro-doctor` — validate runtime health.
+- `/cerebro-reset` — reset runtime state after confirmation.
+- `/cerebro-upgrade` — sync template-owned files when an upstream ref is available.
+
+## Runtime
+
+All durable workflow state lives under `.cerebro/`:
+
+- `.cerebro/project-context.md` — repository index.
+- `.cerebro/plans/` — approved implementation plans.
+- `.cerebro/notepads/` — customer visions, requirements, drafts, reviews, validation, and learnings.
+- `.cerebro/team-runs/` — run manifests, task files, mailbox logs, checkpoints, and events.
+- `.cerebro/boulder.json` — business-level execution checkpoint.
+- `.cerebro/pending-todos/` — task-scoped worker todos.
+
+Use the Cerebro custom tools when available:
+
+- `cerebro_model_slots`
+- `cerebro_run_start`
+- `cerebro_task_create`
+- `cerebro_task_list`
+- `cerebro_task_update`
+- `cerebro_mailbox_send`
+- `cerebro_mailbox_read`
+- `cerebro_dispatch_agent`
+- `cerebro_checkpoint`
+- `cerebro_verify_pending`
+
+## Role Routing
+
+- **Legion** (`legion`) — customer/product-owner proxy; owns WANT and final acceptance.
+- **Cypher** (`cypher`) — business analyst; turns intent into requirements and acceptance criteria.
+- **Professor X** (`professor-x`) — strategic planner and product brief author.
+- **Cyclops** (`cyclops`) — field coordinator, task sequencer, independent verifier.
+- **Wolverine** (`wolverine`) — implementation, tests, scripts, bug fixes.
+- **Storm** (`storm`) — UI, accessibility, responsive/visual engineering.
+- **Forge** (`forge`) — architecture consultation.
+- **Nightcrawler** (`nightcrawler`) — read-only codebase search.
+- **Sage** (`sage`) — docs/API/library research.
+- **Beast** (`beast`) — gap analysis and plan critique.
+- **Emma Frost** (`emma-frost`) — strict validation for high-risk or high-accuracy work.
+
+## OpenCode Compatibility Rules
+
+OpenCode does not provide Claude Code native `TeamCreate`, `TaskCreate`, `TaskUpdate`, `SendMessage`, or `TeamDelete` APIs. Do not mention those as available tools. Instead:
+
+1. Start a run with `cerebro_run_start`.
+2. Create and update tasks with `cerebro_task_create`, `cerebro_task_list`, and `cerebro_task_update`.
+3. Use `cerebro_dispatch_agent`, OpenCode subagents/child sessions, or `@agent` mentions for specialized work.
+4. Record cross-agent decisions with `cerebro_mailbox_send`.
+5. Write durable progress with `cerebro_checkpoint` before compaction or long handoffs.
+6. Verify pending todos with `cerebro_verify_pending` before final synthesis.
+
+## Safety and Quality
+
+- Do not read `.env`, `.env.*`, secret, or credential files unless the user explicitly authorizes it.
+- Ask before destructive, irreversible, production, credentialed, billing, legal, data migration, or git-history actions.
+- Wolverine and Storm must maintain task-scoped todos and return `TASK_RESULT` evidence.
+- Cyclops must independently verify worker claims before tasks are treated as complete.
+- Final reports must include files changed, tests/verification run, unresolved issues, and checkpoint paths.

package/.cerebro/docs/agent-mapping.md

@@ -0,0 +1,54 @@
+# Agent Mapping
+
+This runtime uses X-Men names for OpenCode specialist prompts. The names are part of the workflow's soul; prompt content can evolve, but role boundaries stay explicit.
+
+| Agent | Role | Write boundary |
+|---|---|---|
+| Cerebro | Main orchestrator and intent gate | Runtime coordination, tasks, mailbox, checkpoints |
+| Professor X | Strategic planner and interviewer | `.cerebro/plans/` only |
+| Beast | Gap analyst and plan critic | Read-only |
+| Emma Frost | Plan validator | Read-only |
+| Cyclops | Execution coordinator | Runtime state and notepads |
+| Wolverine | General implementation and tests | Codebase, excluding `.cerebro/plans/` |
+| Forge | Architecture consultant | Read-only |
+| Nightcrawler | Codebase traversal and pattern search | Read-only |
+| Sage | Documentation and knowledge retrieval | Read-only |
+| Storm | Frontend and visual engineering | UI/frontend files |
+
+## Runtime Files
+
+```text
+.opencode/
+├── agents/
+│   ├── cerebro.md
+│   ├── legion.md
+│   ├── cypher.md
+│   ├── professor-x.md
+│   ├── cyclops.md
+│   ├── wolverine.md
+│   ├── storm.md
+│   ├── forge.md
+│   ├── nightcrawler.md
+│   ├── sage.md
+│   ├── beast.md
+│   └── emma-frost.md
+├── commands/
+│   ├── cerebro-plan.md
+│   ├── cerebro-start-work.md
+│   ├── cerebro-upgrade.md
+│   ├── cerebro-reset.md
+│   ├── cerebro-doctor.md
+│   ├── cerebro-index.md
+│   └── to-me-my-x-men.md
+└── plugins/
+
+.cerebro/
+├── schemas/
+├── scripts/
+├── templates/
+├── project-context.md
+├── plans/
+├── notepads/
+├── team-runs/
+└── pending-todos/
+```

package/.cerebro/docs/cerebro-workflow.md

@@ -0,0 +1,115 @@
+# Cerebro Agentic Workflow
+
+This is the operational workflow for the OpenCode-native Cerebro runtime.
+
+## Runtime Architecture
+
+```mermaid
+flowchart TB
+    User["User Request"] --> Gate["Cerebro Intent Gate"]
+    Gate -->|"index repo"| Index["Project Index"]
+    Gate -->|"simple"| Direct["Direct Response"]
+    Gate -->|"complex / risky"| Planning["Professor X Planning"]
+    Gate -->|"clear task"| Execution["Cyclops Execution"]
+    Planning --> Plan[".cerebro/plans/*.md"]
+    Plan --> Execution
+    Execution --> Workers["Wolverine / Storm / Forge / Nightcrawler / Sage"]
+    Execution --> State[".cerebro/boulder.json + team ledgers + notepads"]
+    Execution --> Result["Verified Result"]
+    Index --> Context[".cerebro/project-context.md"]
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `/to-me-my-x-men [task]` | Autonomous execution for clear tasks; asks before using Cerebro's own judgment on unclear product-shaped prompts. |
+| `/cerebro-index` | Build or refresh repository context. |
+| `/cerebro-plan [task]` | Interview-first planning with Professor X. |
+| `/cerebro-start-work` | Execute or resume the latest Cerebro plan. |
+| `/cerebro-doctor` | Validate command names, model routing, OpenCode agents/commands, plugin bridge, schemas, and runtime health. |
+| `/cerebro-upgrade <ref>` | Sync template-owned files from the upstream repo at a tagged release. |
+| `/cerebro-reset` | Scan and reset generated Cerebro runtime state after explicit confirmation. |
+
+## State Files
+
+| Path | Owner | Purpose |
+|---|---|---|
+| `.cerebro/schemas/boulder.schema.json` | Cyclops | Required shape for resumable execution state. |
+| `.cerebro/scripts/check-agent-teams-enabled.py` | Cerebro | Legacy compatibility check for Claude Code agent-team settings; not part of the active OpenCode runtime. |
+| `.cerebro/scripts/ensure-upgrade-cache-gitignored.py` | Cerebro | Reusable helper that keeps `.cerebro/upgrade-cache/` ignored. |
+| `.cerebro/scripts/fetch-upstream-ref.py` | Cerebro | Reusable helper that fetches an upstream upgrade ref and prints its SHA. |
+| `.cerebro/scripts/reset-runtime.py` | Cerebro | Reusable scan/reset/verify helper for `/cerebro-reset`. |
+| `.cerebro/scripts/setup-status.py` | Cerebro | Reusable installation status and version helper. |
+| `.cerebro/scripts/test-stop-hook.py` | Cerebro | Legacy compatibility check for Claude Stop-hook blocking behavior; active OpenCode runs use `cerebro_verify_pending`. |
+| `.cerebro/scripts/upgrade-latest-tag.py` | Cerebro | Reusable helper that resolves the latest upstream version tag. |
+| `.cerebro/scripts/validate-agent-frontmatter.py` | Cerebro | Reusable doctor check for OpenCode agent frontmatter. |
+| `.cerebro/scripts/validate-opencode-runtime.py` | Cerebro | Authoritative OpenCode runtime validator for config, plugin bridge, commands, agents, and model routing. |
+| `.cerebro/scripts/validate-boulder.py` | Cerebro | Reusable doctor check for `.cerebro/boulder.json`. |
+| `.cerebro/scripts/validate-team-runs.py` | Cerebro | Reusable doctor check for the team-run template and manifests. |
+| `.cerebro/scripts/validate-upgrade-metadata.py` | Cerebro | Reusable doctor check for upgrade manifest and upgrade state metadata. |
+| `.cerebro/scripts/write-upgrade-state.py` | Cerebro | Reusable helper that atomically writes upgrade baseline hashes. |
+| `.cerebro/templates/plan.md` | Professor X | Canonical plan schema. |
+| `.cerebro/templates/project-context.md` | Cerebro | Canonical repository index schema. |
+| `.cerebro/project-context.md` | Cerebro | Indexed stack, commands, conventions, entrypoints, and risks. |
+| `.cerebro/plans/*.md` | Professor X | Approved implementation plans. |
+| `.cerebro/boulder.json` | Cerebro | Business-level execution checkpoint: active plan, overall status, approvals, verification history, and decisions. Task progress lives in `.cerebro/team-runs/{run-id}.tasks.json`. |
+| `.cerebro/team-runs/{run-id}.json` | Cerebro | Run manifest for command, team name, teammates, approvals, mailbox decisions, verification, and cleanup. |
+| `.cerebro/team-runs/{run-id}.tasks.json` | Cyclops | OpenCode-managed task ledger updated by `cerebro_task_create/list/update`. |
+| `.cerebro/team-runs/{run-id}.mailbox.jsonl` | Cerebro team | Mailbox log written by `cerebro_mailbox_send` and read by `cerebro_mailbox_read`. |
+| `.cerebro/team-runs/{run-id}.checkpoints.jsonl` | Cerebro team | Durable checkpoints written by `cerebro_checkpoint`. |
+| `.cerebro/notepads/{plan}/conventions.md` | Cyclops | Coding patterns, naming, file structure, UI patterns. |
+| `.cerebro/notepads/{plan}/commands.md` | Cyclops | Useful install/test/lint/build/dev commands. |
+| `.cerebro/notepads/{plan}/decisions.md` | Cyclops | Approval decisions and architectural decisions. |
+| `.cerebro/notepads/{plan}/gotchas.md` | Cyclops | Subtle traps, edge cases, unexpected behavior. |
+| `.cerebro/notepads/{plan}/failures.md` | Cyclops | Failed approaches and why. |
+| `.cerebro/notepads/{plan}/verification.md` | Cyclops | Verification commands and outcomes. |
+| `.cerebro/notepads/{plan}/issues.md` | Cyclops | Blockers, deferred work, unresolved risks. |
+| `.cerebro/pending-todos/{team}/{agent}/{task-id}.txt` | Wolverine / Storm | Task-scoped worker todos checked by `cerebro_verify_pending`. |
+| `.cerebro/.pending-todos` | Wolverine / Storm | Legacy worker todo file kept for backward compatibility with old runs. |
+| `.cerebro/upgrade-manifest.json` | Cerebro | Declares file ownership for `/cerebro-upgrade`. Controls which files are overwritten, merged, or left untouched. |
+| `.cerebro/upgrade-state.json` | Cerebro | Baseline hashes written after each successful upgrade. Drives change detection on the next run. |
+| `.cerebro/upgrade-cache/<ref>/` | Cerebro | Shallow clones of upstream refs (gitignored). |
+| `.cerebro/schemas/upgrade-manifest.schema.json` | Cerebro | JSON Schema for the upgrade manifest. |
+| `.cerebro/schemas/upgrade-state.schema.json` | Cerebro | JSON Schema for the upgrade state baseline. |
+
+## Upgrading from Upstream
+
+`/cerebro-upgrade <ref>` syncs template-owned files from the configured upstream repo at an explicit pinned release or supported ref (for example `v0.3.0`). It never touches user-owned paths and gates all writes to merge-owned files.
+
+### How It Works
+
+1. **Arg validation** — `<ref>` must be an explicit tag or SHA; `HEAD`, `main`, and `master` are rejected.
+2. **Gate D** — checks for uncommitted changes in template/merge-owned paths before any write.
+3. **Fetch** — shallow-clones the upstream repo into `.cerebro/upgrade-cache/<ref>/`.
+4. **Classify** — each manifest entry is classified as `add`, `delete`, `modify-template`, `modify-merge-clean`, `modify-merge-conflict`, or `noop` by comparing local vs upstream content against the recorded baseline.
+5. **Apply** — template-owned files are written silently; merge-owned conflicts trigger Gate A.
+6. **Report** — a change table is printed to chat and written to `.cerebro/upgrade-cache/<ref>/report.md`.
+7. **Gate B** — if the upstream manifest differs from the local manifest, the user chooses how to reconcile.
+8. **State write** — `.cerebro/upgrade-state.json` is written atomically (tempfile+rename) with the applied SHA and post-upgrade working-tree file hashes.
+
+### Approval Gates
+
+| Gate | Trigger | Choices |
+|---|---|---|
+| **Gate A** | Merge-owned file changed on both sides since baseline | keep local, take upstream, merge manually, skip |
+| **Gate B** | Upstream manifest differs from local manifest | adopt upstream, merge entries, leave local |
+| **Gate C** | Template-owned file drifted from baseline (`--strict` only) | overwrite, skip |
+| **Gate D** | Uncommitted changes in owned paths | commit/stash first, or pass `--force-dirty` |
+
+### Flags
+
+- `--dry-run` — show the change report without writing anything.
+- `--strict` — pause Gate C before overwriting any template-owned file that has drifted locally.
+- `--force-dirty` — continue after Gate D finds uncommitted changes in owned paths.
+- `--only <glob>` — restrict the upgrade to files matching this glob.
+
+### v1 Known Gaps
+
+- No automated rollback after partial success — use `git restore .` to undo any written files.
+- Symlinks and executable bits are not preserved. Re-run release verification after upgrade before publishing.
+- The default upstream remains the migration source unless overridden by command/script flags; fork remotes require explicit configuration.
+
+## Skills
+
+Skills are optional overlays. They may improve task-specific execution or verification, but the base workflow must continue without them. `.cerebro` contracts, approval gates, and result envelopes stay authoritative when a skill gives conflicting advice.

package/.cerebro/docs/orchestration.md

@@ -0,0 +1,28 @@
+# Orchestration System Guide
+
+Cerebro turns OpenCode into a coordinated X-Men-themed agent workflow using native project files: `AGENTS.md`, `.opencode/agents/`, `.opencode/commands/`, the `open-xmen` plugin, and `.cerebro/` runtime state.
+
+## When To Use What
+
+| Complexity | Approach | When to use |
+|---|---|---|
+| Simple | Ask normally | Explanation, small command, single obvious edit. |
+| New repo or stale context | `/cerebro-index` | Build `.cerebro/project-context.md` before planning or execution. |
+| Clear implementation | `/to-me-my-x-men [task]` | Clear goal, low/medium risk, no long interview needed. |
+| Complex or risky | `/cerebro-plan [task]` then `/cerebro-start-work` | Multi-step feature, architecture change, migration, security, data, production impact. |
+| Interrupted plan | `/cerebro-start-work` | Continue from `.cerebro/boulder.json`. |
+
+If the user explicitly invokes `/to-me-my-x-men` for ambiguous or product-shaped work, Cerebro asks only for blockers it cannot infer safely. Otherwise Legion and Cypher record assumptions in customer/requirements notepads before Professor X, Beast, Emma Frost, Cyclops, and the workers proceed.
+
+## Layers
+
+1. Cerebro classifies the user request and reads `.cerebro/project-context.md` plus OpenCode routing guidance when it exists.
+2. Legion captures customer intent and Cypher converts it into requirements when autonomous mode needs product judgment.
+3. Professor X plans complex or risky work and writes `.cerebro/plans/{name}.md`.
+4. Cyclops creates/updates Cerebro task records and delegates to Wolverine, Storm, Forge, Nightcrawler, Sage, Beast, and Emma Frost.
+5. Workers report evidence; Cyclops verifies independently.
+6. Run manifests, task ledgers, mailbox logs, checkpoints, boulder state, and notepads are stored under `.cerebro/`.
+
+## Verification Standard
+
+Worker self-report is not enough. Cyclops verifies by reading changed files, running the plan's verification commands, and sending failures back to the worker with exact output. Final synthesis happens only after `cerebro_verify_pending` confirms task-scoped todos are clear or explicitly blocked.

package/.cerebro/docs/overview.md

@@ -0,0 +1,44 @@
+# Cerebro OpenCode Runtime
+
+Cerebro is an OpenCode plugin/runtime that ports the original X-Men workflow into OpenCode while preserving the role names, cinematic command style, and high verification bar. It gives one project a repeatable planning and execution system using OpenCode-native files:
+
+- `AGENTS.md` for repository-level Cerebro/OpenCode operating rules
+- `.opencode/agents/*.md` for specialist personas
+- `.opencode/commands/*.md` for slash command workflows
+- `.opencode/plugins/open-xmen.ts` for the local development bridge
+- `src/index.ts` for custom Cerebro tools and OpenCode plugin hooks
+- `.cerebro/` for plans, execution state, and accumulated learnings
+
+Legacy `.claude/` files may exist as migration source or compatibility material, but `.opencode/` + `.cerebro/` is the active runtime. Skills are optional overlays; the base workflow does not require any skill to be installed.
+
+## Quick Start
+
+```text
+/to-me-my-x-men add request validation to the API
+/cerebro-index
+/cerebro-plan redesign the authentication flow
+/cerebro-start-work
+/cerebro-doctor
+```
+
+## Working Modes
+
+| Mode | Command | Use when |
+|---|---|---|
+| Direct | Ask normally | The request is simple and low-risk. |
+| Index | `/cerebro-index` | Build project context for faster future work. |
+| Autonomous | `/to-me-my-x-men [task]` | The task is clear and should be executed end to end. |
+| Planning | `/cerebro-plan [task]` | Requirements are complex, ambiguous, high-impact, or need approval. |
+| Execution | `/cerebro-start-work` | A plan exists and should be executed or resumed. |
+| Doctor | `/cerebro-doctor` | Validate workflow health and catch command/model/runtime drift. |
+| Reset | `/cerebro-reset` | Safely scan and reset Cerebro runtime state after confirmation. |
+| Upgrade | `/cerebro-upgrade` | Sync template-owned files from a pinned upstream ref. |
+
+When `/to-me-my-x-men` receives an unclear full-product prompt, it asks only for non-inferable blockers. Otherwise Legion and Cypher document assumptions in customer/requirements notepads, Professor X promotes them into a brief or plan, and Cyclops coordinates verified execution.
+
+## Recommended Reading
+
+- [Cerebro Workflow](./cerebro-workflow.md)
+- [Orchestration Guide](./orchestration.md)
+- [Skill Policy](./skill-policy.md)
+- [Agent Mapping](./agent-mapping.md)

package/.cerebro/docs/skill-policy.md

@@ -0,0 +1,25 @@
+# Skill Policy
+
+Cerebro ships without required skills. Skills can be added later as optional overlays.
+
+## Rules
+
+- Skills are never required for the base workflow.
+- Agents may use a relevant available skill when it improves implementation, research, or verification.
+- If a skill is unavailable, agents continue with normal repo tools.
+- Project-local instructions, `.cerebro` contracts, approval gates, todo discipline, model/effort routing, and result envelopes override skill advice.
+- Skills must not bypass approval gates or weaken verification requirements.
+- If skill availability changes what could be verified, report that limitation in `TASK_RESULT` or the final report.
+
+## Good Uses
+
+- Storm uses an available browser or accessibility skill to verify UI behavior.
+- Wolverine uses an available language or test skill to run a focused suite.
+- Sage uses an available docs skill to fetch more precise API references.
+
+## Bad Uses
+
+- A task fails only because an optional skill is missing.
+- A skill-generated instruction overrides `.cerebro/templates/plan.md`.
+- A skill bypasses a required approval gate.
+- A worker omits the required `TASK_RESULT` envelope because a skill returned another format.

package/.cerebro/integrations/semble.md

@@ -0,0 +1,30 @@
+# Semble — Semantic Code Search
+
+Semble is installed as an MCP server. The following teammates should prefer it over grep for natural-language and conceptual queries: **Nightcrawler**, **Wolverine**, and **Forge**.
+
+## MCP Tools
+
+- `mcp__semble__search(query, repo)` — natural-language or identifier search; `repo` is a local path or git URL; defaults to the current working directory.
+- `mcp__semble__find_related(file_path, line, repo)` — find chunks semantically similar to the code at a given file location.
+
+## When to Use Semble
+
+- Conceptual / natural-language queries → `mcp__semble__search`
+- "Find code similar to X" → `mcp__semble__find_related`
+- Exhaustive exact-string or regex matching → use `grep` (semble is not a text matcher)
+
+## Per-Teammate Guidance
+
+**Nightcrawler** — primary user. Prefer semble for all conceptual queries; fall back to grep only for exact-string or regex matching.
+
+**Wolverine** — use `mcp__semble__search` before implementing to find existing patterns, conventions, and similar code to avoid duplication. Use `mcp__semble__find_related` to discover all call sites when changing an interface.
+
+**Forge** — use `mcp__semble__search` to locate architectural examples and assess how widely a pattern is used before recommending changes. Use `mcp__semble__find_related` to find the blast radius of a design decision.
+
+## Indexing for Repeated Searches
+
+Index once for faster repeated queries:
+```bash
+semble index . -o .cerebro/semble-index
+```
+Pass `--index .cerebro/semble-index` to searches. Reindex if the codebase changes significantly.

package/.cerebro/opencode/model-routing.md

@@ -0,0 +1,37 @@
+# Cerebro OpenCode Model Routing
+
+This installation is configured to prefer the user's cost-conscious OpenAI model set. GPT-5.4 is the default frontier/strong lane; GPT-5.4 Pro is intentionally not the default because it is more expensive.
+
+| Slot | Model | Use |
+|---|---|---|
+| `frontier` | `openai/gpt-5.4` | Cerebro, Professor X, Cyclops, Forge, Emma Frost, high-risk escalation |
+| `strong` | `openai/gpt-5.4` | Legion, Cypher, Sage, Beast, routine analysis and review |
+| `legacy-frontier` | `openai/gpt-5.2` | Compatibility/fallback if GPT-5.4 is unavailable or a task needs GPT-5.2-specific behavior |
+| `coding` | `openai/gpt-5.3-codex` | Wolverine and Storm implementation/UI work |
+| `spark` | `openai/gpt-5.3-codex-spark` | Instant code sketches, boilerplate, test stubs, tiny low-risk diffs, first-pass generation |
+| `fast` | `openai/gpt-5.4-mini` | Nightcrawler fast indexing and repetitive search |
+| `image` | `openai/gpt-image-2` | Image/design asset generation only |
+
+Environment overrides:
+
+- `CEREBRO_MODEL_FRONTIER` (set to `openai/gpt-5.4-pro` only when you explicitly want the premium lane)
+- `CEREBRO_MODEL_STRONG`
+- `CEREBRO_MODEL_CODING`
+- `CEREBRO_MODEL_SPARK`
+- `CEREBRO_MODEL_FAST`
+- `CEREBRO_MODEL_IMAGE`
+
+Routing policy: default to best performance within the available cost-conscious models. Use full `gpt-5.3-codex` for Wolverine/Storm coding by default. Use Spark as a draft lane for instant code generation, then route non-trivial implementation, verification, and final fixes through full Codex. Use `fast` only for low-risk search/indexing. Escalate coding blockers or validation disputes to `frontier`. If `frontier` is unavailable, fall back to `strong` (`openai/gpt-5.4`) before considering legacy compatibility models.
+
+
+## Spark Lane
+
+Use `spark` when speed and creative first-pass output matter more than final confidence:
+
+- component/function boilerplate
+- first draft of a small helper
+- test skeletons and fixtures
+- quick patch candidates for Cyclops/Wolverine to review
+- small examples or code snippets for plans/docs
+
+Do not use Spark as the final authority for high-risk code, migrations, security-sensitive changes, broad refactors, or final verification.

package/.cerebro/schemas/boulder.schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Cerebro Boulder Execution State",
+  "description": "Business-level execution checkpoint. Task progress lives in .cerebro/team-runs/{run_id}.tasks.json via cerebro_task_* tools — do not duplicate it here.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "active_plan",
+    "plan_name",
+    "status",
+    "risk_level",
+    "team_name",
+    "started_at",
+    "updated_at",
+    "approval_gates",
+    "verification_history",
+    "decisions"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 2
+    },
+    "active_plan": {
+      "type": "string",
+      "description": "Path to the active .cerebro/plans/*.md plan, or an empty string before a plan is selected"
+    },
+    "plan_name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "type": "string",
+      "enum": ["not_started", "in_progress", "blocked", "completed"]
+    },
+    "risk_level": {
+      "type": "string",
+      "enum": ["LOW", "MEDIUM", "HIGH"]
+    },
+    "team_name": {
+      "type": "string",
+      "description": "Active team/session name used to group Cerebro tasks, mailbox messages, checkpoints, and pending todos"
+    },
+    "started_at": {
+      "type": "string",
+      "minLength": 1
+    },
+    "updated_at": {
+      "type": "string",
+      "minLength": 1
+    },
+    "approval_gates": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/approval_gate"
+      }
+    },
+    "verification_history": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/verification_entry"
+      }
+    },
+    "decisions": {
+      "type": "array",
+      "description": "Architectural and approval decisions made during execution",
+      "items": {
+        "$ref": "#/$defs/decision"
+      }
+    }
+  },
+  "$defs": {
+    "approval_gate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "status", "decided_at", "decision_by", "notes"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "approved", "rejected"]
+        },
+        "decided_at": {
+          "type": ["string", "null"]
+        },
+        "decision_by": {
+          "type": ["string", "null"]
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    },
+    "verification_entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "result", "verified_at", "notes"],
+      "properties": {
+        "command": {
+          "type": "string",
+          "minLength": 1
+        },
+        "result": {
+          "type": "string",
+          "enum": ["PASS", "FAIL", "BLOCKED"]
+        },
+        "verified_at": {
+          "type": "string",
+          "minLength": 1
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    },
+    "decision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["at", "topic", "decision", "rationale"],
+      "properties": {
+        "at": {
+          "type": "string",
+          "minLength": 1
+        },
+        "topic": {
+          "type": "string",
+          "minLength": 1
+        },
+        "decision": {
+          "type": "string",
+          "minLength": 1
+        },
+        "rationale": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}