open-xmen 0.1.0

package/.opencode/commands/cerebro-start-work.md

@@ -0,0 +1,20 @@
+---
+description: Execute or resume the latest Cerebro plan through Cyclops coordination.
+agent: cerebro
+model: openai/gpt-5.4
+---
+Execute or resume the latest Cerebro plan.
+
+## Required flow
+
+1. Announce field execution mode.
+2. Read the newest `.cerebro/plans/*.md`, `.cerebro/project-context.md` if present, `.cerebro/boulder.json` if present, and relevant `.cerebro/notepads/`.
+3. Call `cerebro_model_slots` and `cerebro_run_start` with command `/cerebro-start-work`, objective from the plan, and the plan risk.
+4. Create task records for each implementation, UI, review, and verification task in the plan.
+5. Use Cyclops to sequence dependencies, assign Wolverine/Storm/Forge/Nightcrawler/Sage/Beast/Emma Frost as needed, and independently verify results. For tiny low-risk boilerplate or test-stub drafts, Cyclops may dispatch a Spark first-pass with `cerebro_dispatch_agent` using `model_slot: "spark"`, but final implementation and verification stay with full Codex/frontier models.
+6. Require Wolverine and Storm to maintain `.cerebro/pending-todos/{team}/{agent}/{task}.txt` and return `TASK_RESULT` evidence.
+7. Record decisions and blockers with `cerebro_mailbox_send`; update task state with `cerebro_task_update`.
+8. Run all verification commands listed in the plan when safe. If a command is destructive, external, credentialed, or production-affecting, ask first.
+9. Update `.cerebro/boulder.json` with status, approvals, verification history, and decisions.
+10. Call `cerebro_verify_pending`; do not final-report while pending todos remain.
+11. Final report: plan path, files changed, tests run, verification evidence, unresolved issues, rollback notes, and checkpoint paths.

package/.opencode/commands/cerebro-upgrade.md

@@ -0,0 +1,19 @@
+---
+description: Sync Cerebro template-owned files from an explicit upstream release.
+agent: cerebro
+model: openai/gpt-5.4
+---
+Upgrade Cerebro template-owned files from upstream ref: $ARGUMENTS
+
+This command is gated and must not silently overwrite user-owned files.
+
+## Required flow
+
+1. Parse args: `[<ref>] [--dry-run] [--strict] [--force-dirty] [--only <glob>]`.
+2. Reject `HEAD`, `main`, and `master`; require explicit release tag or commit SHA.
+3. Load `.cerebro/upgrade-manifest.json`; if absent, propose a manifest and require confirmation before writing.
+4. Check dirty tracked files in template/merge-owned paths. Stop unless clean or `--force-dirty` is explicitly present.
+5. Fetch upstream into `.cerebro/upgrade-cache/` using existing scripts where possible.
+6. Present diffs for merge-owned files and require confirmation before writes.
+7. Never touch user-owned runtime paths: `.cerebro/plans/**`, `.cerebro/notepads/**`, `.cerebro/team-runs/**`, `.cerebro/boulder.json`, pending todos, or project context unless explicitly requested.
+8. Validate and write upgrade state.

package/.opencode/commands/to-me-my-x-men.md

@@ -0,0 +1,27 @@
+---
+description: Autonomous Cerebro full-team mode for best-effort execution.
+agent: cerebro
+model: openai/gpt-5.4
+---
+Assemble the full Cerebro team for autonomous execution of: $ARGUMENTS
+
+## Best-effort standard
+
+The user expects the best the team can produce, not the minimum viable version. Prefer excellent architecture, complete UX states, strong verification, and polished results. Fast is good; generic and under-verified is failure.
+
+## Required flow
+
+1. Announce maximum Cerebro power.
+2. Classify mission shape and risk. If HIGH risk, ask for explicit confirmation before destructive/production/credentialed/data/billing/legal/git-history actions.
+3. Call `cerebro_model_slots` and `cerebro_run_start` with command `/to-me-my-x-men`.
+4. Always start with Legion and Cypher:
+   - Legion writes customer vision under `.cerebro/notepads/customer/`.
+   - Cypher writes requirements under `.cerebro/notepads/requirements/`.
+   Ask one focused, structured confirmation question in plain text only for non-inferable blockers. Do not stack questions or ask for open-ended replies when a safe assumption can be documented.
+5. Promote requirements into a Professor X product brief or implementation plan, reviewed by Beast and validated by Emma Frost when risk/complexity warrants.
+6. Create task records, then use Cyclops to coordinate implementation with Wolverine, Storm, Forge, Nightcrawler, Sage, Beast, and Emma Frost as appropriate.
+7. Maintain task-scoped todos for worker tasks and record mailbox decisions/checkpoints. Use Spark for instant first drafts only when it accelerates the mission without lowering final quality; full Codex/frontier agents own final implementation and verification.
+8. Run verification and final Legion acceptance. A Legion reject creates retry tasks before completion.
+9. Call `cerebro_verify_pending`; final-report only when todos are clear or explicitly blocked.
+
+Final report must include assumptions, files changed, tests/verification, customer acceptance verdict, unresolved issues, and `.cerebro` run paths.

package/AGENTS.md

@@ -0,0 +1,12 @@
+# Cerebro OpenCode Runtime
+
+This project uses the Cerebro workflow ported to OpenCode.
+
+- Primary runtime state lives under `.cerebro/`.
+- Use OpenCode commands `/cerebro-index`, `/cerebro-plan`, `/cerebro-start-work`, and `/to-me-my-x-men` for non-trivial work.
+- Preserve Cerebro role names: Legion, Cypher, Professor X, Cyclops, Wolverine, Storm, Forge, Nightcrawler, Sage, Beast, and Emma Frost.
+- OpenCode does not provide Claude Code native team APIs; use Cerebro custom tools and OpenCode subagents/child sessions for coordination.
+- Never read `.env`, `.env.*`, secret, or credential files unless the user explicitly authorizes it for the current task.
+- Do not write generated build output (`dist/`, `build/`, `target/`) unless the task explicitly targets those directories.
+
+When handling a Cerebro command, read `.cerebro/cerebro-identity.md` and `.cerebro/opencode/model-routing.md` first if they are not already in context.

package/README.md

@@ -0,0 +1,193 @@
+# Open X-Men — Cerebro for OpenCode
+
+A reusable OpenCode plugin/template that ports the original Claude Code Cerebro/X-Men workflow into the OpenCode ecosystem while preserving the parts that matter:
+
+- `.cerebro/` runtime state
+- `/cerebro-index`
+- `/cerebro-plan`
+- `/cerebro-start-work`
+- `/to-me-my-x-men`
+- Cerebro and the X-Men role names
+
+Cerebro coordinates. OpenCode agents execute. The workflow keeps the dramatic X-Men soul, but no longer depends on Claude Code native team APIs.
+
+---
+
+## What Changed
+
+The old Claude workflow used `.claude/agents`, `.claude/commands`, hooks, and native team tools such as `TeamCreate`, `TaskCreate`, `TaskUpdate`, and `SendMessage`.
+
+The OpenCode port uses:
+
+- `.opencode/agents/*.md` — OpenCode-native Cerebro role agents
+- `.opencode/commands/*.md` — preserved Cerebro slash commands
+- `open-xmen` package plugin entry — installed by `open-xmen install`
+- `.opencode/plugins/open-xmen.ts` — local development bridge in this repository only; installed projects use the package plugin entry
+- `src/index.ts` — reusable plugin implementation
+- Cerebro custom tools for run state, tasks, mailbox, checkpoints, model slots, and pending-todo checks
+- `AGENTS.md` and `.cerebro/cerebro-identity.md` — OpenCode instruction surface
+
+The legacy `.claude/` files are still present as migration source/compatibility material, but the active OpenCode runtime is `.opencode/` + `.cerebro/`.
+
+---
+
+## Model Routing
+
+This installation is configured for the user's cost-conscious OpenAI model set. GPT-5.4 is the default; GPT-5.4 Pro can be opted into via `CEREBRO_MODEL_FRONTIER` when the premium lane is worth the cost:
+
+| Slot | Model | Roles |
+|---|---|---|
+| `frontier` | `openai/gpt-5.4` | Cerebro, Professor X, Cyclops, Forge, Emma Frost |
+| `strong` | `openai/gpt-5.4` | Legion, Cypher, Sage, Beast |
+| `legacy-frontier` | `openai/gpt-5.2` | Optional fallback/compatibility lane |
+| `coding` | `openai/gpt-5.3-codex` | Wolverine, Storm |
+| `spark` | `openai/gpt-5.3-codex-spark` | Instant code sketches, boilerplate, test stubs, tiny low-risk diffs |
+| `fast` | `openai/gpt-5.4-mini` | Nightcrawler fast search/indexing |
+| `image` | `openai/gpt-image-2` | image/design asset generation only |
+
+Override with environment variables if your available models change:
+
+```bash
+export CEREBRO_MODEL_FRONTIER="openai/gpt-5.4"
+export CEREBRO_MODEL_STRONG="openai/gpt-5.4"
+export CEREBRO_MODEL_CODING="openai/gpt-5.3-codex"
+export CEREBRO_MODEL_SPARK="openai/gpt-5.3-codex-spark"
+# optional premium lane: export CEREBRO_MODEL_FRONTIER="openai/gpt-5.4-pro"
+# optional legacy fallback: export CEREBRO_MODEL_FRONTIER="openai/gpt-5.2"
+export CEREBRO_MODEL_FAST="openai/gpt-5.4-mini"
+export CEREBRO_MODEL_IMAGE="openai/gpt-image-2"
+```
+
+---
+
+## Quick Start
+
+Install Open X-Men into any OpenCode project with bunx. The installer adds the published `open-xmen` package as an OpenCode plugin entry and installs the repo-local Cerebro runtime files:
+
+```bash
+cd /path/to/your/project
+bunx open-xmen@latest install
+opencode .
+```
+
+No setup slash command is required. Re-running the installer is safe: existing runtime/template files are skipped by default, while `opencode.jsonc` is updated atomically with an `opencode.jsonc.bak` backup when it changes. Use `--reset` or `--force` only when you want to refresh managed Open X-Men files.
+
+Useful installer flags:
+
+```bash
+bunx open-xmen@latest install --dir /path/to/project
+bunx open-xmen@latest install --dry-run
+bunx open-xmen@latest install --reset
+bunx open-xmen@latest install --force
+bunx open-xmen@latest install --no-deps
+```
+
+For local development of this package:
+
+```bash
+npm install
+npm run build
+node dist/cli.js install --dir /path/to/your/project
+```
+
+Then run the Cerebro workflow command you need inside OpenCode:
+
+```text
+/cerebro-index
+/cerebro-plan add a REST API for user authentication
+/cerebro-start-work
+```
+
+For autonomous best-effort mode:
+
+```text
+/to-me-my-x-men build the feature described in the current issue
+```
+
+---
+
+## CLI
+
+```bash
+open-xmen [install] [--dir <path>] [--dry-run] [--reset] [--force] [--no-deps]
+open-xmen doctor [--dir <path>] [--json]
+open-xmen models
+```
+
+- No subcommand defaults to `install`, matching `bunx open-xmen@latest install` behavior.
+- `--dry-run` prints planned writes and does not mutate the target project.
+- `--reset` / `--force` refresh existing managed files; without them, existing files are skipped.
+- `opencode.jsonc` writes are atomic via `opencode.jsonc.tmp` and create `opencode.jsonc.bak` before replacing an existing config.
+- `doctor --json` returns script-friendly diagnostics.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/cerebro-index` | Build `.cerebro/project-context.md` using Nightcrawler, Sage, Forge, and Beast. |
+| `/cerebro-plan [task]` | Interview-first planning with Professor X, Beast, and Emma Frost validation. |
+| `/cerebro-start-work` | Execute or resume the latest Cerebro plan through Cyclops coordination. |
+| `/to-me-my-x-men [task]` | Autonomous full-team mode with Legion + Cypher intent consult and final Legion acceptance. |
+| `/cerebro-doctor` | Validate runtime health. |
+| `/cerebro-reset` | Reset runtime state after confirmation. |
+| `/cerebro-upgrade <ref>` | Gated template sync from an explicit upstream release/ref. |
+
+---
+
+## Team
+
+| Agent | Role | Default model |
+|---|---|---|
+| Cerebro | Main OpenCode primary agent / team lead | `openai/gpt-5.4` |
+| Legion | Customer / product-owner proxy | `openai/gpt-5.4` |
+| Cypher | Requirements analyst | `openai/gpt-5.4` |
+| Professor X | Strategic planner | `openai/gpt-5.4` |
+| Cyclops | Execution sequencer and verifier | `openai/gpt-5.4` |
+| Wolverine | Code/test implementation | `openai/gpt-5.3-codex` |
+| Storm | UI/visual implementation | `openai/gpt-5.3-codex` |
+| Forge | Architecture consultant | `openai/gpt-5.4` |
+| Nightcrawler | Read-only codebase search | `openai/gpt-5.4-mini` |
+| Sage | Docs/API research | `openai/gpt-5.4` |
+| Beast | Gap analysis and critique | `openai/gpt-5.4` |
+| Emma Frost | Strict validation | `openai/gpt-5.4` |
+
+---
+
+## Runtime Files
+
+```text
+.cerebro/
+├── cerebro-identity.md          # OpenCode Cerebro orchestration brain
+├── opencode/model-routing.md    # model slots and routing policy
+├── project-context.md           # repository index from /cerebro-index
+├── plans/                       # approved plans
+├── notepads/                    # customer visions, requirements, drafts, reviews, learnings
+├── team-runs/                   # manifests, task state, mailbox logs, checkpoints, events
+├── pending-todos/               # worker task todos
+├── boulder.json                 # execution checkpoint
+├── schemas/                     # state schemas
+├── templates/                   # plan/context/run templates
+└── scripts/                     # validators and maintenance helpers
+```
+
+---
+
+## Validation
+
+```bash
+npm run build
+npx tsc -p tsconfig.json --noEmit
+npm run doctor
+python3 .cerebro/scripts/validate-opencode-runtime.py
+python3 .cerebro/scripts/validate-team-runs.py
+python3 .cerebro/scripts/validate-upgrade-metadata.py
+npm run verify:release
+```
+
+`npm run verify:release` builds the package, packs it with `npm pack --json --ignore-scripts`, checks the packaged runtime file set exactly, rejects forbidden paths such as dev-only plugin bridges or secret-like files, installs the tarball into a clean temp package, runs `open-xmen install --no-deps`, verifies `plugin: ["open-xmen"]`, and runs `open-xmen doctor`.
+
+`/cerebro-doctor` runs the same class of checks from inside OpenCode.
+
+## Spark Lane
+
+`gpt-5.3-codex-spark` is available as a fast draft lane. Cerebro should use it for instant code generation, boilerplate, test stubs, tiny low-risk diffs, and candidate patches. Full `gpt-5.3-codex` remains the default for Wolverine/Storm final implementation and verification.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};