orchestrate

Orchestrate (internal primitive)

This skill ships the four primitives every OMCR engine depends on. It is not something a user invokes directly — there is no /orchestrate command and there should never be one. Engines (the user-facing skills listed above) import its phase files and compose them.

If you are reading this because Claude Code's skill auto-discovery surfaced it: please pick the engine you actually wanted to run, e.g. /iterate-revision for revising a section against a reviewer.

When this skill's phase files are referenced from another skill, follow them exactly as written. Do not re-derive behavior from the primitives doc — that doc is the design source; these phase files are the implementation contract.

The 4 primitives

#	Primitive	Purpose	File
1	state-read	Read + validate + bootstrap a state JSON under .claude/omcr-state/.	phases/01-state-read.md
2	dispatch	Invoke a persona subagent via the Agent tool with inlined prompt.	phases/02-dispatch.md
3	evaluate	Apply an engine-supplied verdict rule to the last output + state.	phases/03-evaluate.md
4	loop	Drive dispatch → evaluate → repeat with max_iter and budget safeties.	phases/04-loop.md

Each phase is short by design — engines do the domain work, the primitives just keep state, dispatch, and counters honest.

The state store

Five files under .claude/omcr-state/ in the user's project. Layout is flat — no logs/ subdirectory — per Phase 0 decision §1.

File	Owner-by-convention	Append-only?
paper.json	engines + /omcr-setup + /start-research	no
reviews.json	engines that dispatch @reviewer	yes
citations.json	@literature-curator + verify-citation skill	no
figures.json	engines that dispatch @figure-descriptor + cropfig	no
_run-log.jsonl	every engine (every run start + completion)	yes

schema_version is a JSON string ("1" for now). On mismatch the primitive warns and proceeds — there is no migration runner yet. See Phase 0 decision §2 for the rationale and the deferred plan.

Full per-field documentation and populated examples live in:

• ../../develop/example-state/README.md — schema reference + populated examples
• ../../develop/phase-0-primitives.md — original design doc

Ownership is convention only — there is no runtime enforcement. Engines declare what they write via a writes: frontmatter field on their SKILL.md (see "Composition contract" below).

Composition contract — how an engine uses this skill

An engine skill (e.g. skills/iterate-revision/SKILL.md) must:

1. List the orchestrate phases it imports in its ## Composition section. Example:

   ## Composition
   
   This engine imports the following primitives from `skills/orchestrate/`:
   - `phases/01-state-read.md` — read `paper.json` + `reviews.json`
   - `phases/02-dispatch.md`   — dispatch `@paper-writer`, `@reviewer`
   - `phases/03-evaluate.md`   — verdict rule defined in `phases/04-evaluate.md` of this engine
   - `phases/04-loop.md`       — `max_iter` default 3, `on_iter_end: git-commit`
   

2. Declare writes: in frontmatter — list the state files this engine mutates (e.g. writes: [paper, reviews]). Reviewers grep writes: across skills/*/SKILL.md to audit which engines touch which files. Append-only files (reviews, _run-log.jsonl) still require declaration if the engine appends.

3. Declare cost_estimate_tokens: in frontmatter (optional but recommended for Phase 3 autonomous mode) — a coarse constant the /supervisor-drive scheduler uses for budget gating. Phase 3 decision §6 adds rolling-median actuals on top.

4. Provide a verdict rule. The engine's own phase files contain the verdict-rule spec; orchestrate/phases/03-evaluate.md is the primitive that applies it. The rule is passed in as data; the primitive does not know engine-specific logic.

5. Never call another engine. Engines are leaves (Phase 2 decision §5, Phase 3 decision §3). If composition between engines is needed, /supervisor-drive is the only thing that may chain — and it re-evaluates state between every step rather than invoking engines from inside engines.

Cost model

Each dispatch is one Agent-tool invocation. Engines should budget max_iter * len(dispatch_plan) calls. The loop primitive records actual tokens_used to _run-log.jsonl after each iteration. There is no pre-flight tokenizer (Phase 0 decision §6) — budget_tokens is a post-hoc cap that triggers HALT at the iteration boundary if cumulative usage exceeds the cap.

Safety invariants

• Serial execution only (Phase 0 decision §4). OMCR does not currently ship a lock file. One engine at a time per project.
• max_iter is hard. The loop never silently exceeds it — when reached without DONE/BLOCKED, the loop emits HALT and exits cleanly.
• Dispatch errors break the loop. If the Agent tool errors mid-run, the loop emits BLOCKED and the partial state is already on disk.
• State persists across interruption. A user Ctrl-C leaves .claude/omcr-state/*.json in a consistent state because each primitive writes atomically (write-tmp + rename).

When to extend vs. when to fork

Add a phase to orchestrate/phases/ only when every engine would benefit. Engine-specific logic (e.g. "scan for [TBD: markers" from /iterate-revision Phase 0 decision §1.2) goes in that engine's own phase files. The four primitives here should stay at four for now.

If a fifth primitive looks tempting (e.g. "parallel dispatch fanout"), that is a Phase 3 concern — the autonomous supervisor is the only caller that can benefit, and concurrency is deferred per Phase 0 decision §4.

See also

• ../../wiki/Orchestration-Model.md — public-facing pattern doc
• ../../develop/decisions-summary.md — all 21 locked decisions
• wiki/Specializing.md — preset authoring (includes writes: and cost_estimate_tokens: frontmatter conventions)