orch-claude-pi-codex
Skill11 starsChanged 14 days agoMITView on GitHub
Claude architects and commands, pi workers implement in parallel, codex reviews independently, Claude synthesizes. Use for /orch-claude-pi-codex, multi-file features, parallel implementation that needs a separate reviewer, or when the user asks for the Claude→pi→codex→Claude orchestration pattern.
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- obsidian-skills/AGENTS.mdAGENTS.md
- add-just-doctorSkill
- agent-autoresearchSkill
- agent-harness-repairSkill
- change-evidenceSkill
- ci-speedSkill
- verifySkill
- deck-style-gallerySkill
- doneSkill
- longform-fictionSkill
- loop-kitSkill
- loop-nightly-reviewSkill
- loop-triage-githubSkill
- loop-watch-socialSkill
- skills-doctorSkill
- tdd-pstackSkill
- teach-pstackSkill
- windows-leftover-cleanupSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Read references/paradigms.md when choosing a different shape.
- Very specific: line 20
Read the repo's AGENTS.md and every file the change touches.
- Very specific: line 38
Use --deps '["<task_id>"]' only for real ordering.
- Very specific: line 62
Start one codex reviewer with a spec that names the actual diff and the acceptance criteria.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
orch-claude-pi-codex
Role-specialized Orca orchestration. Claude is the architect and commander; pi workers implement in parallel; codex reviews independently; Claude synthesizes and reports.
Read references/paradigms.md when choosing a different shape. Read references/task-specs.md before writing a spec.
Preconditions
- Orca is reachable:
orca statusreportsruntimeState: ready. - Agents
claude,pi, andcodexare enabled in Orca. - You are the root coordinator. A dispatched worker must not use this skill.
1. Architect
Read the repo's AGENTS.md and every file the change touches. Write a brief to .orca-orch/<run_id>/brief.md with:
- Goal and acceptance criteria.
- Work units: name, owned files, verification command, worktree choice.
- Review focus: the risks codex must check.
Choose current when units own disjoint files. Choose new-child per unit when they overlap or need isolation.
Completion: every unit has owned files and a verification command; no two units own the same file unless their worktrees are isolated.
2. Create the Run and tasks
orca orchestration run-create --objective "<goal>" --json
orca orchestration task-create --spec "<unit spec>" --task-title "<unit>" --json
orca orchestration task-list --ready --briefUse --deps '["<task_id>"]' only for real ordering.
Completion: every unit is a task; the first ready wave is listed.
3. Dispatch pi workers
orca orchestration worker-start --task <task_id> --worktree current --agent pi --task-title "<unit>" --jsonFor overlapping files: --worktree new-child --name <unit>. Start every independent worker, then end your turn. Orca wakes you on worker_done.
Completion: every ready task has a dispatch ID and state: ready.
4. Collect and verify
For each worker_done, read the report and check the evidence yourself: files exist, the verification command ran, no out-of-scope edits. Use worker-read --dispatch <id> when the report is thin.
A failed report is not a completed task. Retry the same task with --retry-of, or stop and report the blocker. Follow a failed start's next action; release reclaimable terminals.
Completion: every unit has a verified report or a recorded failure.
5. Codex review gate
Start one codex reviewer with a spec that names the actual diff and the acceptance criteria. The reviewer must see the changes: review in the coordinator's worktree when units used current; collect child-worktree changes into a review worktree when units used new-child (see references/task-specs.md).
The review returns findings ranked by severity, each with file:line and a concrete failure scenario, plus a verdict: approve or request changes.
Completion: codex returns a verdict with evidence.
6. Fix loop
On request changes, send each finding to the pi worker that owns the file as a follow-up task. Re-review after the fixes. Cap the loop at two rounds; at the cap, give the user the open findings.
Completion: codex approves, or the cap is reached and the user has the findings.
7. Synthesize
Report per task: outcome, evidence (files, commands, review verdict), open blockers. Keep the brief and the review report as the durable record. Release workers; remove child worktrees only with the user's confirmation.
Completion: the user has the final report with evidence and blockers.
Guardrails
- One self-contained spec per worker: target, change, constraints, evidence of done.
- pi implements, codex reviews, Claude decides. The owning pi worker makes every edit the review requests.
currentfor disjoint files,new-childfor overlap. A child worktree costs setup and a merge.- End your turn after dispatching; Orca wakes you on
worker_done. - A failed outcome stays failed: retry the same task or report the blocker.
- Cap the review loop at two rounds; at the cap, give the user the open findings.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

