OPUS

Open · Plan · Unfold · Seal

A tooling-independent methodology and reference harness for the coordination-class Eidolon — the one that turns user intent into a governed multi-agent run.

OPUS is a sibling to the rest of the roster:

• ATLAS — read-only codebase exploration
• SPECTRA — specification and planning
• APIVR-Δ — brownfield implementation loop
• FORGE — deliberation and verdicts
• IDG (née Scribe) — document synthesis

OPUS sits above them. Its job is to compose the team, route handoffs, and enforce the governance plane — without performing domain work itself.

---

Why this exists

Every frontier agent stack eventually reinvents the same orchestration layer: a supervisor that decomposes intent, dispatches specialists, collects artifacts, and enforces authorization at action boundaries. Most do it ad hoc, tightly coupled to one framework (LangGraph, AutoGen, CrewAI) and one vendor.

OPUS is the distilled methodology, expressed as:

• a four-phase contract (Open → Plan → Unfold → Seal) that survives model, framework, and host swaps
• a bounded topology vocabulary (solo, hierarchical-sequential, hybrid-reflexive, consult, fan-out)
• a Composition Plan as a Canonical Action Representation of the run — deterministic, hashable, replayable
• an Action Authorization Boundary (AAB) derived from Faramesh, enforcing PERMIT | DEFER | DENY on every side-effect action
• progressive-disclosure skills (≤1,300 tokens each) and schema-validated artifacts for handoffs
• a canary evaluation dataset with ≥80% pass target

Implementations can live on top of Claude Code subagents, GitHub Copilot custom agents, Cursor rules, OpenCode agents, or a local harness over open-weight models. MCP is the recommended transport for opus-aab, but not required.

---

Architectural invariants (the non-negotiable bits)

• AAB is non-bypassable. Every side-effect action normalizes to a Canonical Action Representation (CAR) and passes through a deterministic PERMIT | DEFER | DENY evaluator. Fail-closed default DENY.
• Artifact-by-reference, not content. Handoffs carry artifact IDs and schema names, not embedded payloads.
• Per-member token budgets enforced at dispatch. Overflow triggers retrieval JIT, fold, or replan.
• Checkpoint at every handoff. No dispatch without a resumable state snapshot.
• Bounded self-correction. Max 1 [REPLAN], max 3 [ARBITRATION] per run. Past the limit → [ESCALATION].
• FORGE is reachable only through OPUS. Downstream Eidolons signal OPUS when they need deliberation; OPUS opens the arbitration.
• Schema-validated handoffs. Every transfer conforms to its declared schema. Schema drift halts the run.
• OPUS memory is meta, not domain. It records composition patterns and their outcomes. Code, specs, verdicts, and prose live in the respective Eidolon's own memory.
• No domain output from OPUS. OPUS emits only mission.md, composition.v1.yaml, run-report.v1.md, brief wrappers, and structural markers.

See OPUS.md for the full specification.

---

Repository structure

opus/
├── OPUS.md                           # Authoritative methodology spec
├── agent.md                          # Always-loaded entry point (~1,100 tokens)
├── AGENTS.md                         # agents.md open-standard wrapper
├── CLAUDE.md                         # Claude Code pointer
├── README.md                         # This file
├── CHANGELOG.md                      # Keep a Changelog — versioned evolution
├── DESIGN-RATIONALE.md               # Every decision traced to evidence
├── skills/                           # Progressive-disclosure phase skills
│   ├── open/SKILL.md                 # Intent normalization, triage, mission envelope
│   ├── plan/SKILL.md                 # Topology, budgeting, AAB policy authoring
│   ├── unfold/SKILL.md               # Dispatch loop, arbitration, replan
│   └── seal/SKILL.md                 # Provenance validation, Run Report, memory
├── templates/                        # Fill-in-the-blank output artifacts
│   ├── mission.md
│   ├── composition.v1.yaml
│   ├── run-report.v1.md
│   ├── opus-to-atlas-brief.md
│   ├── opus-to-spectra-brief.md
│   ├── opus-to-apivr-brief.md
│   ├── opus-to-forge-brief.md
│   └── opus-to-idg-brief.md
├── schemas/                          # JSON Schema v2020-12 validators
│   ├── mission.v1.json
│   ├── composition.v1.json
│   └── run-report.v1.json
├── tools/                            # Implementation guides
│   ├── aab-spec.md                   # Normative spec for OPUS-AAB
│   └── mcp-server-reference.md       # Reference MCP server design
├── hosts/                            # Host-specific wiring
│   ├── claude-code.md
│   ├── cursor.md
│   ├── copilot.md
│   └── opencode.md
├── evals/
│   └── canary-missions.md            # Evaluation dataset (≥80% pass target)
└── install.sh                        # Idempotent installer with --members flag

---

The four-phase cycle

Each phase produces a schema-validated artifact:

Phase	Output	Hard constraint
O — Open	mission.md	Refuses underspecified intents; may terminate as TRIVIAL (answer inline, no roster) or REJECTED
P — Plan	composition.v1.yaml	Deterministic; hashable (plan_car); topology from bounded vocabulary; handoff schema chain well-formed
U — Unfold	Appends to execution-trace.jsonl + provenance-ledger.jsonl; dispatches members	Every handoff checkpointed; every side-effect action AAB-gated; max 1 replan, max 3 arbitrations
S — Seal	run-report.v1.md	Provenance chain intact; no domain content enters OPUS memory

---

Position in the stack

                          ┌──────────┐
                          │   User   │
                          └────┬─────┘
                               │ raw intent
                          ┌────▼─────┐
                          │   OPUS   │
                          └────┬─────┘
                               │ sealed handoffs
        ┌──────────┬───────────┼───────────┬──────────┐
        │          │           │           │          │
   ┌────▼───┐ ┌────▼───┐ ┌────▼────┐ ┌────▼───┐ ┌────▼───┐
   │ ATLAS  │ │SPECTRA │ │ APIVR-Δ │ │ FORGE  │ │  IDG   │
   │ scout  │ │ plan   │ │ build   │ │ decide │ │ write  │
   └────────┘ └────────┘ └─────────┘ └────────┘ └────────┘

OPUS is above the line. Everything below is a specialist it dispatches and governs.

---

Quick start

Drop-in under a host

# Canonical install for any host that reads agents.md
git clone <this-repo> .opus
# or copy the needed files into an existing project:
./opus/install.sh --target /path/to/project --members opus,atlas,spectra,apivr,forge,idg

Partial-team deployment

# OPUS + IDG only (documentation runs)
./opus/install.sh --target /path/to/project --members opus,idg

# OPUS + ATLAS + SPECTRA (plan without build)
./opus/install.sh --target /path/to/project --members opus,atlas,spectra

OPUS gracefully degrades. Missing members cause the Composition Plan to compose around them (via replan triggers) or refuse (INVALID_COMPOSITION) with actionable guidance.

Canonical workflow

1. User sends a free-form intent.
2. OPUS Opens: normalizes to mission.md. If TRIVIAL, answers inline and ends.
3. OPUS Plans: produces composition.v1.yaml with topology, members, budgets, AAB policy, replan triggers.
4. OPUS Unfolds: dispatches through the pipeline, gates every action, checkpoints every handoff. Arbitrates conflicts through FORGE when needed.
5. OPUS Seals: validates provenance, emits run-report.v1.md, archives under artifacts/OPUS/MISSION-<id>/, updates meta-memory.

---

Reference implementation

opus-aab is a conformant MCP server that exposes the AAB primitives (canonicalize, evaluate, record, verify_chain, replay) over JSON-RPC. It follows the same pattern as atlas-aci — a Python package with mechanical enforcement of every guarantee in tools/aab-spec.md.

Status: opus-aab is the planned reference implementation. OPUS-the-methodology is usable today with any host that can enforce AAB guarantees (SDK-embedded, sidecar, proxy, or managed service).

---

Design principles

1. Layered loading. Entry point + one active skill + one template. Typical working set: ~2,900 tokens. Consistent with the roster.
2. Single responsibility. OPUS coordinates. It does not reason, plan, explore, build, or write. Boundary violations degrade the whole team.
3. Mechanical invariants over prompt reminders. AAB, bounded ACI, schema validation, checkpoint-on-handoff — enforced by the harness, not asked of the model.
4. Evidence over assertion. Every design decision traces to a cited source in DESIGN-RATIONALE.md. No "because it feels right."
5. Vendor-agnostic. No hard dependencies on any framework, model, or host. Capability classes, not model names.
6. Security and privacy as first-class. See OPUS.md §10 and the security surface section of DESIGN-RATIONALE.md.

---

Research foundation

OPUS's design decisions are grounded in:

• Faramesh (Fatmi, 2026, arXiv:2601.17744) — Action Authorization Boundary, Canonical Action Representation, fail-closed semantics.
• Agent-OS (Koubaa et al., 2025, TechRxiv) — latency-class taxonomy (HRT/SRT/DT), Agent Contracts for portability.
• Benchmarking Multi-Agent LLM Architectures (Kulkarni & Kulkarni, 2026, arXiv:2603.22651) — empirical Pareto frontier for hierarchical supervisor-worker vs reflexive vs sequential.
• Context Engineering survey (Mei et al., 2025, arXiv:2507.13334) — context as a first-class engineering discipline.
• APIVR-Δ, SPECTRA, ATLAS, FORGE, IDG — the existing Eidolons, whose handoff artifacts OPUS speaks natively.

For the full mapping, see DESIGN-RATIONALE.md.

---

License

Apache 2.0. See LICENSE.

---

Contributing

This is a methodology spec in active design. For iteration proposals, open an issue using the templates under .github/ISSUE_TEMPLATE/. Breaking changes require a semver bump and migration notes in CHANGELOG.md.

---

OPUS v1.0.0 — coordination-class Eidolon.