codex-mmo/docs/PROFILES.md

Bundled profile portfolio

The bundled portfolio is a set of workload-specific compositions, not a ranking of model vendors. It deliberately separates four kinds of diversity:

• model maker and model family;
• API operator and access product;
• wire protocol and billing route;
• actual serving provider when an aggregator reports it.

Those are not interchangeable. An OpenRouter route, for example, identifies an aggregator until the serving provider is recorded in telemetry. GLM-5.3 roles in the bundled profiles always use the Z.AI Coding Plan Responses route and ZAI_CODING_API_KEY; they never fall back to the Z.AI General API.

The 8.0.0 portfolio belongs to one breaking development generation. Every MMO-owned document uses schema 8 and every profile declares exact version 8.0.0. Old profile IDs, model keys, flat control lists, active-work fields, lifetime-spawn fields, rollout state, and records from any other generation fail validation. There are no aliases, migration readers, alternate hosts, automatic rewrites, compatibility profiles, or independent profile-version upgrade paths.

Every role receives profile-derived guidance in its generated Codex home. For spawn-capable roles, the compiled AGENTS.md requires a delegation decision within three substantive task calls. Every spawn- or control-capable role receives mmo-profile-orchestration/SKILL.md with its exact spawn/action graph, backend choices, goal/turn lifecycle, warning-only stalls, task-brief requirements, root/native/MCP controls, result lifecycle, and root-productivity workflow. A nontrivial decomposable task launches an eligible branch early; an atomic task may remain single-agent only with a concrete reason. A control-only role is told to inspect or intervene only at a real dependency/risk boundary and is not given spawn or result-disposition authority. True leaf guidance states the no-spawn/no-control boundary and disables the inherited skill. Every root and supervised MCP worker owns a canonical Unix app-server host and durable thread; native participants are durable child threads inside the root host, with advisory guarantees where Codex exposes no interception hook.

Choosing a profile

Profile	Choose it for	Main trade-off
adaptive-engineering	General, decomposable engineering	Selective external calls and integration overhead
codex-harness-team	ChatGPT-only access or a homogeneous control	Less provider diversity and less mechanical visibility for native roles
high-confidence-debugging	Ambiguous bugs where reproduction and falsification matter	Sequential evidence gates increase latency
research-backed-engineering	Changes whose correctness depends on current external sources	Source retrieval and audit cost
secure-change	Security-sensitive changes and vulnerability remediation	Expensive, deliberately skeptical review path
visual-engineering	UI work driven by images and browser output	Requires an intact multimodal transport and browser fixture
contract-first-refactoring	Compatibility-sensitive refactors	Contract discovery happens before implementation
incident-hypothesis-triage	Read-only incident diagnosis	Produces hypotheses and evidence, never remediation writes

Use a lab only to run its stated experiment. Do not select a lab merely because its topology is novel.

Featured profiles

adaptive-engineering

The Sol root owns diagnosis, the canonical workspace, integration, and final validation. It can launch independent work early while continuing the critical path:

Sol root (Codex/ChatGPT, writer)
├── Luna repository scout (native, read-only)
├── DeepSeek V4 Pro implementation specialist (Go, isolated writer)
└── Opus 5 adversarial reviewer (Zen, read-only)

The specialist receives one disjoint, objectively testable branch. Its Git patch is not canonical until the root reads and accepts the result and explicitly integrates the patch. The reviewer is for material architecture or post-change risk, not a mandatory council call. Maximum depth is one and each worker has one spawn.

Why it exists: it is the broad default and demonstrates selective hybrid delegation, economical implementation, cross-maker review, and an active flagship root without forcing every task through a council.

codex-harness-team

This is the portfolio’s homogeneous-maker control:

Sol root (writer)
├── Luna repository scout (native, read-only)
├── Terra invariant designer (native, read-only)
└── fresh Sol critic (Agent MCP, read-only)

All roles use ChatGPT-backed Codex access. The value comes from context isolation, parallel reconnaissance, role specialization, and a fresh critic—not maker diversity. Native roles are advisory and read-only; the Agent-MCP critic has strict lineage and a result contract. The root is the sole writer.

Why it exists: users with only Codex access still get a meaningful team, and evaluations gain a control against the claim that heterogeneous models are always necessary.

high-confidence-debugging

DeepSeek V4 Pro debug lead (Go, writer)
├── Sonnet 5 independent reproducer (Zen, isolated writer)
└── Sol fix verifier (Codex Agent MCP, read-only; one follow-up allowed)

The reproducer creates a minimal failing test or empirical reproduction independently of the lead’s suspected cause. Repair cannot be accepted merely from a plausible explanation. The verifier starts from a fresh context, attacks the proposed fix, and may be relaunched once after a correction. The root remains productive by investigating likely causes while reproduction runs, but the repair barrier is real.

Why it exists: independent reproduction and post-fix falsification address correlated debugging errors that a fast single pass often misses.

research-backed-engineering

MiniMax M3 research/engineering lead (Go, writer)
├── Luna primary-source researchers (Codex Agent MCP, read-only; up to two)
└── Sonnet 5 source-to-code auditor (Zen, read-only)

Researchers return claim-level URLs, publication/access times, and bounded excerpts. The lead re-fetches pivotal claims rather than treating summaries as truth, implements in the repository, and asks the auditor to compare source requirements with the actual change. Unavailable Tool MCP research servers degrade the research branch; they are not silently replaced by a different model or route.

Why it exists: current-source verification and repository work demand different context management and benefit from independent source-to-code checking.

secure-change

Opus 5 security lead (Zen, writer)
├── GLM-5.3 vulnerability hunter (Z.AI Coding Plan, read-only; up to two passes)
└── DeepSeek V4 Pro finding verifier (Go, read-only)

The lead frames assets, trust boundaries, and remediation scope. GLM supplies independent candidate findings; DeepSeek must reproduce consequential claims with commands or repository evidence. The root remediates only confirmed findings and owns regression/security validation. A structured contract constrains shape and requires evidence correlation, but no contract makes a model’s security conclusion true.

Why it exists: it combines deliberately different security-analysis and empirical-verification roles without granting either worker write authority.

visual-engineering

multimodal Sol visual lead (Codex, writer)
├── Terra reference analyst (native, read-only)
└── fresh multimodal Sol verifier (Agent MCP, read-only; one follow-up allowed)

The root implements directly from supplied references. The verifier receives the original reference and an actual Playwright browser render through an image-preserving route, checks layout and accessibility evidence, and emits a strict visual result. Compilation rejects a model/transport path that loses image modality. Native analysis remains optional and advisory.

Why it exists: visual correctness is not adequately tested by DOM text or synthetic prose descriptions alone.

contract-first-refactoring

Sonnet 5 refactor lead (Zen, writer)
├── MiniMax M3 invariant miner (Go, read-only)
├── Luna contract-test author (Codex Agent MCP, isolated writer)
└── DeepSeek V4 Pro compatibility verifier (Go, read-only)

The lead freezes public behavior before changing implementation. The invariant miner inspects callers and edge cases; the test author produces a disjoint patch against that contract; the lead explicitly reviews, accepts, and integrates it. Verification then attacks compatibility with economical independent execution.

Why it exists: separating specification, tests, implementation, and verification materially reduces self-consistent but wrong refactors.

incident-hypothesis-triage

GLM-5.3 incident lead (Z.AI Coding Plan, read-only)
├── DeepSeek V4 Flash evidence runner (Go, read-only; up to two probes)
└── Nemotron causal challenger (OpenRouter, read-only)

The entire profile is read-only. The lead constructs and ranks falsifiable hypotheses. The runner collects bounded logs and command evidence; the challenger uses a pinned OpenRouter serving policy to attack causal assumptions. Provider routing telemetry records the requested route and any reported serving provider. Evidence, not votes, determines the final hypothesis order.

Why it exists: fast operational evidence and independent causal challenge improve triage while mechanically preventing an analysis profile from modifying production code.

Experimental labs

access-efficient-escalation-lab

A Luna writer routes only literal, bounded reconnaissance to local Qwen3.5-9B; routine isolated patches go to DeepSeek V4 Flash; difficult read-only judgment may escalate to GLM-5.3 Coding Plan. The weak local role is MCP-only, read-only, persistent-thread hosted, literal-task constrained, strict-contract bound, and always verified. It cannot architecture, debug ambiguously, write, delegate, control another worker, or adjudicate. Persistence prevents evidence loss; it does not expand the weak role's authority.

This cannot be represented by adaptive-engineering: its object of study is access cost and escalation thresholds, including a mechanically contained weak model.

route-resilience-lab

A Terra observer sends matched read-only tasks to DeepSeek V4 Pro through OpenCode Go and through OpenRouter. The OpenRouter route has a typed provider policy with fallback disabled; requested route, actual serving provider, policy, latency, usage, and errors are retained separately.

This cannot be folded into incident triage: its workload is deliberately controlled so that route behavior—not agent specialization—is the independent variable.

bounded-research-organization-lab

A Sol engineering root compares flat source scouts with a Kimi K3 research lead that may run at most two instances of the same MiniMax M3 scout role concurrently, under delegation depth two. All delegated work is read-only. Completed scouts release their slots, allowing later evidence-driven follow-ups without an arbitrary session-lifetime ceiling.

This cannot be represented by the flat research profile because bounded nested organization is the feature under evaluation.

competing-implementations-lab

A Terra judge defines one objective contract, then DeepSeek V4 Pro and Sonnet 5 build independent patches in isolated Git worktrees. Both writers may run concurrently because their branches are isolated. The judge tests both patches, explicitly accepts one result, integrates only that patch, and rejects the other.

This cannot be represented by a normal implementation profile: matched competition and empirical selection are the experiment, not merely a second reviewer.

Availability and failure behavior

The root route is startup-critical. A missing root credential or unavailable root model prevents session creation. Missing optional worker credentials do not invalidate the whole snapshot: the role is marked unavailable, attempts to spawn it return a typed route_unavailable admission error, and no job is created. Profiles must explain how the productive root proceeds without that branch.

There is no silent model, maker, provider, access-product, or reasoning fallback. OpenRouter fallback is allowed only when a route’s typed policy explicitly permits it; bundled OpenRouter examples pin allowed serving providers and disable fallback.

MCP worker results follow an explicit lifecycle: unread → read → accepted or rejected; accepted isolated-writer results may then become integrated. agents_wait returns compact job state and per-job progress_revision values, returning at the first durable change when those revisions are supplied as after_revision; bounded result previews are opt-in. agent_result provides lossless cursor pages until next_cursor is null, and agent_trace_record does the same for a checksummed oversized filtered trace event. Generated guidance requires result/inspect/trace APIs and prohibits direct reads of MMO supervisor files. Transitions are monotonic and audited. Reading is not acceptance, and acceptance is not patch application.

Rebinding

Bindings use exact route-qualified keys:

codex-mmo run \
  --profile adaptive-engineering \
  --bind implementation_specialist=opencode_go_openai_chat__deepseek_v4_pro

The compiler revalidates route availability, protocol, modalities, reasoning levels, tool behavior, trust policy, and role constraints. A syntactically valid replacement is not accepted if the complete route cannot perform the role.

Evaluation status

Every profile has a generation-8 smoke test and matched generation-8 evaluation suite. Smoke wall limits belong to the external harness and do not replace profile goal-token limits or warning-only stall policy. Bundling means the composition is implemented and testable; it does not claim universal superiority. Featured status still requires authenticated live inventory evidence and the suite’s release-trial promotion gates. Labs remain labs unless their matched controls and ablations establish the stated benefit.