Open-Codining — Multi-Level Orchestration Platform

Fork of opencode-orchestrator (MIT) extended into an AI Delivery Platform: a four-level orchestration hierarchy (Enterprise → Program → Project → Mission) driven by formalized specs and backlogs, with evidence-based verification at every level. The original engine — Commander / Planner / Worker / Reviewer, MVCC todo.md, the autonomous mission loop — is untouched. Everything here is additive.

The hierarchy

EnterpriseCommander   →  portfolio, capacity budget, allocation strategies
        ↓ delegate_task
ProgramCommander      →  projects, priorities, inter-project dependencies
        ↓ delegate_task
ProjectCommander      →  backlog items, spec injection, mission delegation
        ↓ delegate_task
Commander (core)      →  the original autonomous mission engine — untouched
        ↓
Planner / Worker / Reviewer (core)

Each level only knows the level directly below. Level skipping is forbidden by prompt and by design.

Commander Gate

A level is triggered through exactly two doors:

On any other agent the plugin is fully transparent: no loop, no prompt injection, no message transformation, no notification — default OpenCode behavior, as if the plugin were not installed.

Spec & Backlog Driven mode

No work starts from a free-form prompt at the Project level. Work is driven by two files — the mode activates by their presence (absence = legacy core behavior, untouched):

.opencode/
├── spec.md                  stable project spec (scope, constraints, definition of done)
├── backlog.md               prioritized items: B001, B002… (priority, size, status, deps, acceptance criteria)
└── backlog-item-active.md   the item currently being executed

Item lifecycle (one at a time): select (eligibility = deps [x], priority order, age, size) → inject (spec + acceptance criteria prepended to context.md, read by every core agent) → execute (one core mission; every acceptance criterion becomes a verifiable leaf sub-task in todo.md) → close (refused until the core verification passes) → next item.

Multi-project / multi-program storage (swap model)

.opencode/
├── enterprise.md                          portfolio: budget, strategy, PGM-xxx programs
├── programs/<PGM-ID>/
│   ├── program.md                         projects of the program: PRJ-xxx
│   └── projects/<PRJ-ID>/
│       ├── spec.md
│       └── backlog.md

Activating a program installs its program.md + projects/ tree as the working copies; activating a project installs its spec.md + backlog.md the same way. The lower loops run unchanged on the working copies. Closing or failing syncs everything back — including mid-flight state, nothing is ever lost.

Capacity allocation (Enterprise)

enterprise.md header: - Budget de capacité : N and - Stratégie : proportional | equal | priority-first.

The allocation engine is pure and deterministic: paused program → 0 slots · no eligible items → 0 slots (redistributed) · every active candidate gets ≥ 1 slot (anti-famine) · slots never exceed a program's eligible items · ties broken by priority then file order.

Level tools (deterministic state transitions)

The LLM decides when; tested code decides what happens. Closing tools are refused without evidence (R7): an item cannot close until the core mission verification passes; a project cannot close until every item is [x]; a program cannot close until every project is [x].

Real parallelism (opt-in) — execution slots

Add - Parallélisme : activé to enterprise.md (git workspaces only) and the capacity budget becomes a REAL constraint: up to N backlog items run simultaneously, each in its own execution slot — a git worktree placed outside the workspace ($TMPDIR/orchestrator-slots/<hash>/<slotId>, branch orchestrator/<slotId>, node_modules symlinked). No swap: every active program/project is driven directly on its STORED files, and the delegations carry the exact paths.

Closing an item stacks four mechanical locks: the slot's todo.md passes the core verification (R7) → the work is committed → the MAIN workspace is git-clean (a mission that escaped its slot blocks everything, by code) → the slot branch merges sequentially. A merge conflict keeps the slot (conflict state) with resolution instructions; failures keep the branch for post-mortem. The §8.2 budget is enforced portfolio-wide: item starts beyond it are refused wherever they come from.

Crash recovery: validate_workspace reconciles slots.json ⇄ git worktrees ⇄ [/] markers (SLOT_WORKTREE_MISSING, UNREGISTERED_WORKTREE, ITEM_WITHOUT_SLOT), and repair=true resets items to [ ], prunes and cleans — losslessly. Without the flag, everything behaves exactly as before (time-multiplexing, R5).

Recovery — every level, the same principle

DECOMPOSE → RE-PLAN → ESCALATE. Never give up silently. Level 3 at the Enterprise is ASK HUMAN: a structured summary (context, attempts per level, 2–3 documented options, expected decision) is written to enterprise.md and the chain waits. The human is the last resort, nothing else.

Status markers — shared by every file of the hierarchy

[ ] pending · [/] in progress · [x] verified complete · [-] failed · [~] suspended

Every state file (enterprise.md, program.md, project.md, backlog.md) is MVCC-managed (optimistic versioning + mutex + atomic rename), same guarantees as the core todo.md.

Quick start

npm install        # from this repo
npm run build
npm test           # 800 tests

Inside OpenCode, select the Commander of the level you want and prompt:

# Single mission (core, unchanged)
[Commander]            /task "Implement JWT auth"

# One project driven by a spec + backlog
[ProjectCommander]     "Deliver the backlog"

# A portfolio
[EnterpriseCommander]  "Deliver the portfolio"

Non-regression guarantees

• R1 — zero modification of the core engine's behavior; all additions are layered
• R3 — context.md is enriched (delimited block), never replaced; eject restores it byte-for-byte
• R5 — without spec.md/backlog.md, the system behaves exactly like the original plugin
• R6 — every level state file is MVCC-managed
• R7 — only evidence closes anything, at every level
• R8 — Commander Gate: full plugin transparency on non-Commander agents

License

MIT — original work by agnusdei1207.