Skip to content
gazayPublic

About

No description, website, or topics provided.

Resources

Stars

3 stars

Watchers

1 watching

Forks

Repository files navigation

Orc — multi-agent workflows for Claude Code (and Pi, and Codex)

Orc turns one Claude Code session into an orchestrator that delegates bounded jobs to specialist agents and keeps the decisions for itself.

Skill What it does
/orc:loop <task or milestone> Build loop. Takes one change to commit-ready: contract → implement → trim → review with two model families → triage → fix only blocking findings → verify the delta → stop. At most two fix rounds.
/orc:run <task> Workflow router. Adversarial research (W1), feature (W2), bug fix (W3), branch review (W6), comment trim (W7), session mining. Implementation steps run through the build loop.

Why the build loop looks like this

Reviewers asked to find problems always find some, and fixing every one of them produces defensive code, extra layers, tests for impossible cases and long comments justifying all of it. The loop counters that structurally:

  • One contract: goal, acceptance, out of scope, size estimate. Every agent gets it, and nothing outside it is fixed.

  • Reviewers report everything, the orchestrator triages. Each finding becomes one of these, with a reason:

    • FIX: a realistic failure caused by this change;
    • RIDE-ALONG: a simplification or cheap MINOR, applied only alongside a FIX round or at the end;
    • FOLLOW-UP;
    • REJECT.

    Only FIX starts a round.

  • Decisions live in the plan, not the code. The decision log is passed to every reviewer, so settled points stay settled and workers don't write rebuttals into comments.

  • Fix rounds are reviewed as a delta. A fresh reviewer re-reading the whole diff will always find something new. Working-tree snapshots (scripts/snapshot.sh) make the delta exact.

  • At most two fix rounds, then a person decides: one more round, ship with follow-ups, or rethink.

  • Comments are trimmed before review, not after, under a policy where the burden of proof is on keeping a comment. scripts/diff-stats.sh reports production, test and comment lines every round.

  • Two model families. Claude reviews and Codex reviews in parallel. When Codex wrote the change, the second opinion is a Claude reviewer.

Agents

Agent Role Model
orc:researcher Answers a question about the code with evidence; writes research docs only Opus
orc:planner Smallest plan that meets the goal: acceptance, scope, size, milestones Opus
orc:worker Implements a milestone or triaged fixes; smallest diff, no comment slop Opus
orc:reviewer Correctness review against the contract, plus what to delete. Read-only Opus
orc:sceptic Tries to break a proposal, plan or high-risk change. Read-only Opus
orc:codex-reviewer The same review from the Codex CLI, verified against the code Sonnet driving Codex
orc:codex-trimmer Cuts comment slop through Codex (or itself), verified comment-only against a working-tree snapshot Sonnet driving Codex
orc:session-analyzer Proposes at most ten lessons from a session, and where each belongs Opus

Install

Claude Code:

./install.sh          # adds the local marketplace and installs the plugin; restart Claude Code

Pi and Codex get generated copies. agents/ and skills/ are the only sources; never edit pi/ or codex/, which are generated and gitignored:

./install-pi.sh       # regenerates pi/, links agents into ~/.pi/agent/agents, installs /skill:orc
./install-codex.sh    # regenerates codex/, links the orc skill and orc_* agents into ~/.codex

After editing an agent or skill, rerun the matching install script (or scripts/sync-mirrors.sh).

Optional: the Codex CLI (codex login) for the cross-model reviewer and trimmer. Without it those passes are skipped and the orchestrator says so. Allowlist Bash(codex:*) to avoid a permission prompt per run.

Codex CLI notes

  • codex exec review (built-in review) takes a scope flag (--base, --commit, --uncommitted) and no prompt. codex exec -s read-only "<prompt>" takes a prompt and no scope flag. The loop uses the second, because it needs to pass the contract and the decision log.
  • Always add < /dev/null, or Codex waits on stdin, and -o <file> to capture the final message.
  • --color never works on codex exec, not on codex exec review.
  • No agent may pass --dangerously-bypass-approvals-and-sandbox.

Repository integration

Agents read the repo's AGENTS.md / CLAUDE.md and knowledge docs (.agent/knowledge/ when present) and follow its plan and git rules. The loop writes its contract and decision log into the repo's plan file when one exists, and files follow-ups through the repo's follow-up procedure when there is one.

See CHANGELOG.md for what changed and why.

About

No description, website, or topics provided.

Resources

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages