compound-orchestrator

Compound Orchestrator

Use this skill when the user wants compound engineering to run consistently across Codex, Claude Code, other coding agents, writing agents, or parallel agent teams.

Operating Rule

No meaningful task starts without a task brief or plan. No meaningful task finishes without verification, review, README freshness when relevant, and a compound note.

The loop is:

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

Substantial projects must complete these core planning contracts before implementation:

1. prd.html
2. planning.html
3. spec.html
4. test-cases.html
5. architecture.html with an Excalidraw-compatible architecture.excalidraw
6. users.html

Planning is dependency-aware: parallelize PRD, users, architecture, planning, and early test strategy; then serialize integration, spec.html, test-cases.html, two-round review, and final acceptance.

Bootstrap

Find this plugin directory, then run one of these from any platform:

& <python> <plugin-root>\scripts\compound_orchestrator.py init --target <project-root>
& <python> <plugin-root>\scripts\compound_orchestrator.py check --target <project-root>

python3 <plugin-root>/scripts/compound_orchestrator.py init --target <project-root>
python3 <plugin-root>/scripts/compound_orchestrator.py check --target <project-root>

Use the bundled Codex Python when a system Python is not available. After bootstrap, the target project also has its own scripts/compound_orchestrator.py, scripts/verify.py, scripts/verify.ps1, and scripts/verify.sh, so other agents can use the harness without knowing the original plugin path.

Bootstrap also enables Claude Code agent teams for the project by merging this into .claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "permissions": {
    "deny": ["Read(./.env)", "Read(./node_modules/**)", "Read(./dist/**)"]
  }
}

It also installs project harness templates: README.md policy block, CODEBASE_MAP.md, .agent-loop/readme-maintenance.md, .agent-loop/harness-checklist.md, .agent-loop/module-claude-template.md, .agent-loop/path-scoped-skill-template.md, .agent-loop/lsp-mcp-roadmap.md, and .agent-loop/harness-ownership.md.

It also installs the six core planning artifacts (prd.html, planning.html, spec.html, test-cases.html, architecture.html, architecture.excalidraw, and users.html) plus .agent-loop/core-planning-artifacts.md, .agent-loop/two-round-review-protocol.md, .agent-loop/parallel-agent-team-protocol.md, and .agent-loop/deliverables-checklist.md.

It also installs cross-tool coordination files:

• .agent-loop/coordination/ownership.json
• .agent-loop/cross-tool-protocol.md
• docs/cross-reviews/

During Work

1. Start a task with a stable id:

& <python> <plugin-root>\scripts\compound_orchestrator.py start --target <project-root> --title "<task title>"

2. Work from the generated plan file under docs/plans/.

3. Verify with the target project's scripts/verify.py, scripts/verify.ps1, scripts/verify.sh, or closest native project check.

4. Review the diff or writing artifact before declaring completion.

5. Record learning:

& <python> <plugin-root>\scripts\compound_orchestrator.py learn --target <project-root> --kind pattern --title "<pattern>" --summary "<what future agents should reuse>"

6. Keep README.md current when setup, usage, architecture, workflow, generated outputs, public behavior, manuscript structure, export process, or review workflow changes. Remove old information, keep still-true information, add the new information, and reorganize the README so it reads cleanly.

7. Gate completion:

& <python> <plugin-root>\scripts\compound_orchestrator.py check --target <project-root> --task-id <task-id>

8. Audit the harness when onboarding a repo or after major workflow changes:

& <python> <plugin-root>\scripts\compound_orchestrator.py harness-check --target <project-root>

9. Claim intended files before editing in mixed-agent work:

& <python> <plugin-root>\scripts\compound_orchestrator.py claim --target <project-root> --tool codex --agent codex-worker --task-id <task-id> --paths src/file.py --intent "<planned edit>"

If the claim fails, stop instead of editing. Ask the lead integrator to narrow scope, release stale claims, or serialize the work.

10. Record the two-round opposite-tool review:

& <python> <plugin-root>\scripts\compound_orchestrator.py cross-review --target <project-root> --task-id <task-id> --reviewer-tool codex --author-tool claude --stage round-1-review --summary "<findings summary>"
& <python> <plugin-root>\scripts\compound_orchestrator.py cross-review --target <project-root> --task-id <task-id> --reviewer-tool claude --author-tool codex --stage round-1-response --summary "<revision summary>"
& <python> <plugin-root>\scripts\compound_orchestrator.py cross-review --target <project-root> --task-id <task-id> --reviewer-tool codex --author-tool claude --stage round-2-review --summary "<findings summary>"
& <python> <plugin-root>\scripts\compound_orchestrator.py cross-review --target <project-root> --task-id <task-id> --reviewer-tool claude --author-tool codex --stage round-2-response --summary "<revision summary>"
& <python> <plugin-root>\scripts\compound_orchestrator.py cross-review --target <project-root> --task-id <task-id> --reviewer-tool codex --author-tool claude --stage final-acceptance --summary "<acceptance summary>"

Stop after two rounds unless the user explicitly asks for another loop.

Parallel Agent Policy

Use parallel agents for independent research, planning, test strategy, review, and competing bug hypotheses. Give every agent a role, scope, owned files, output artifact, and verification responsibility.

For planning, use dependency-aware phases:

1. Parallel draft prd.html, users.html, architecture.html, planning.html, and early test risks.
2. Lead integrator reconciles conflicts.
3. Spec agent writes spec.html.
4. Test-case agent writes test-cases.html from spec.html.
5. Run two cross-review rounds and record final acceptance.

Avoid parallel agents for unclear ownership, same-file edits, sequential migrations, and tiny fixes. Codex must still obey the active environment's agent-spawn rules.

For multi-agent runs, use:

& <python> <plugin-root>\scripts\compound_orchestrator.py team-start --target <project-root> --title "<task title>" --mode claude-agent-team

Or for Codex:

& <python> <plugin-root>\scripts\compound_orchestrator.py team-start --target <project-root> --title "<task title>" --mode codex-parallel-agents

Claude Code should create an agent team only when teammate-to-teammate coordination is useful. Codex and other runtimes should mirror the same topology with a lead-integrator hub plus explorer, worker, test-runner, and reviewer agents, each with disjoint scopes.

Claude Code should use compound-cross-tool-reviewer to review Codex-authored changes. Codex should use codex-cross-tool-reviewer to review Claude Code-authored changes.

Large-Codebase Harness Policy

• Root CLAUDE.md and AGENTS.md should be lean: big picture, pointers, and critical gotchas.
• Put local build, test, lint, and domain conventions in subdirectory CLAUDE.md files.
• Start Claude Code in the subdirectory being changed; parent context still loads.
• Generated, vendored, build, coverage, dependency, sourcemap, and secret paths should be denied in .claude/settings.json.
• Repeated instructions should become hooks when automatic or path-scoped skills when task-specific.
• Add LSP for typed/noisy symbol-heavy codebases before relying on broad grep.
• Add MCP only after the context layer, skills, hooks, and ownership are healthy.

Writing Project Policy

• Treat drafts, chapters, reports, source files, export scripts, and review notes as claimable artifacts.
• Review for factual drift, outline consistency, citation/source accuracy, unclear writing, and stale README instructions.
• Keep README.md aligned with the current manuscript or document structure, source workflow, export process, and review cadence.

Claude Code Integration

The initializer writes .claude/commands and .claude/agents templates. These are intentionally plain Markdown so a project can keep them under version control and adapt them.

Durable Memory

Prefer durable notes over chat-only conclusions:

• docs/patterns/
• docs/decisions/
• docs/failures/
• docs/reviews/
• docs/compound/
• .agent-loop/eval-scorecard.md
• .agent-loop/team-topology.md
• .agent-loop/codex-parallel-contract.md
• .agent-loop/cross-tool-protocol.md
• .agent-loop/core-planning-artifacts.md
• .agent-loop/two-round-review-protocol.md
• .agent-loop/parallel-agent-team-protocol.md
• .agent-loop/deliverables-checklist.md
• .agent-loop/harness-checklist.md
• .agent-loop/lsp-mcp-roadmap.md
• .agent-loop/harness-ownership.md

If a lesson should affect all future work, update the managed compound block in AGENTS.md and CLAUDE.md.

If the lesson changes setup, usage, workflow, outputs, or audience expectations, update README.md in the same pass.