compound-orchestrator

Compound Orchestrator

Compound Orchestrator is a reusable plugin and project bootstrapper for making agent-assisted work compound over time. It installs a shared harness for coding, writing, research, documentation, and mixed projects so every meaningful task leaves behind a plan, review, verification trail, ownership record, README update when relevant, and durable learning for the next task.

It works across Windows, macOS, Linux, and WSL. Claude Code and Codex get first-class support, and any other agent runtime can participate by using the same generated CLI, ownership file, review rubric, and cross-platform verifier.

What It Gives You

• README.md maintenance policy for keeping project docs current instead of stale.
• Six core planning contracts: prd.html, planning.html, spec.html, test-cases.html, architecture.html, and users.html.
• An Excalidraw-compatible architecture.excalidraw seed referenced from architecture.html.
• A mandatory two-round cross-review protocol with author responses after each review.
• AGENTS.md and CLAUDE.md managed protocol blocks for shared agent behavior.
• Claude Code slash commands, subagent definitions, hooks, and agent-team enablement.
• A Codex parallel-agent contract that mirrors the Claude team topology.
• Generic ownership claims so Claude Code, Codex, Cursor, Aider, CI agents, or future tools can avoid overlapping edits.
• Cross-tool review roles so one agent runtime reviews work authored by another.
• Project maps, task briefs, review rubrics, handoff templates, scorecards, and durable learning folders.
• Portable generated scripts: scripts/compound_orchestrator.py, scripts/verify.py, scripts/verify.ps1, and scripts/verify.sh.

Supported Work

Use this plugin for:

• Coding projects: apps, libraries, services, monorepos, scripts, tests, and deployment workflows.
• Writing projects: essays, reports, manuscripts, chapters, documentation sites, source notes, and export workflows.
• Research or mixed projects: analysis, notebooks, docs, code, reviews, and artifacts that need coordinated agent work.

The core loop is:

brainstorm -> plan -> six planning contracts -> two-round review -> work -> two-round review -> compound -> repeat

The final step is the point. Each completed task should improve the next task by recording a reusable pattern, decision, failure note, review, or compound note.

Install Into A Project

From this plugin directory on Windows PowerShell:

$py = "python"
& $py .\scripts\compound_orchestrator.py init --target "C:\path\to\project"
& $py .\scripts\compound_orchestrator.py check --target "C:\path\to\project"

If python is not configured on Windows, point $py at a virtualenv, system Python, or bundled agent runtime Python.

From macOS, Linux, or WSL:

python3 scripts/compound_orchestrator.py init --target /path/to/project
python3 scripts/compound_orchestrator.py check --target /path/to/project

The initializer is conservative. It creates missing files, appends managed blocks to existing README.md, AGENTS.md, and CLAUDE.md, and preserves local content unless --force is used for generated files.

After initialization, the target project is portable. Agents can run the copied project-local CLI:

python3 scripts/compound_orchestrator.py check --target .
python3 scripts/verify.py

README Maintenance

README.md is part of the product. Update it whenever setup, usage, architecture, workflow, commands, generated outputs, public behavior, manuscript structure, export process, or review workflow changes.

Every README update should:

1. Remove old information that is no longer true.
2. Keep unchanged information that is still useful.
3. Add the new information readers need.
4. Reorganize the README so it is easy to follow and reflects the latest project state.

The plugin installs this rule into generated projects through both the managed README block and .agent-loop/readme-maintenance.md.

Daily Workflow

Start a task:

python3 scripts/compound_orchestrator.py start --target . --title "Add billing webhook retry handling"

Start a team run:

python3 scripts/compound_orchestrator.py team-start --target . --title "Refactor checkout flow" --mode codex-parallel-agents

Substantial projects should complete the generated planning contracts before implementation:

prd.html -> planning.html -> spec.html -> test-cases.html -> architecture.html -> users.html

Planning should still be parallel where it is independent. Draft PRD, users, architecture, planning, and early test strategy in parallel; then serialize integration, spec.html, test-cases.html, review, and final acceptance.

Claim files or artifacts before editing:

python3 scripts/compound_orchestrator.py claim --target . --tool codex --agent codex-worker --task-id TASK --paths src/payment.py --intent "Implement retry handling"