A Claude Code plugin that transforms Claude Code from a single-session assistant into a team of specialized AI agents that collaborate on software engineering tasks. It's a port of an internal system called "pi orchestration" to the Claude Code environment.
Invocation: /orc:run <task description>
The plugin is never auto-triggered — you invoke it explicitly when you want structured multi-agent workflows.
orc/
├── .claude-plugin/
│ └── plugin.json # Plugin metadata
├── commands/
│ └── run.md # /orc:run entry point
└── agents/
├── researcher.md # Read-only codebase explorer
├── planner.md # Creates implementation plans
├── worker.md # Implements code changes
├── reviewer.md # Audits code for bugs/regressions
├── sceptic.md # Adversarial reviewer
└── session-analyzer.md # Extracts knowledge from sessions
All agents are scoped to the plugin — they are not directly accessible from Claude Code, only through /orc:run.
The system defines a pipeline of specialists, each with strictly scoped capabilities:
- Role: Read-only codebase explorer. First agent in any workflow.
- Model: Opus
- Tools: Read, Write, Bash, Glob, Grep (write access limited to research documents)
- Key behavior: Only writes research outcome documents (
plans/<branch>/RESEARCH.md) — never modifies existing project files. Reads.agent/knowledge/docs before exploring code. Verifies claims against actual code, not just filenames. - Output:
RESEARCH.mddocument in plans folder, plus: Summary, Findings (with file paths + evidence), Recommendations, Open Questions
- Role: Converts research into structured implementation plans. Produces
PLAN.mdandARCHITECTURE.md. - Model: Opus
- Tools: Read, Write, Edit, MultiEdit, Bash, Glob, Grep (has write access)
- Key behavior: Plans go in
plans/<branch-name>/PLAN.md. Plans must be precise enough that the worker agent can execute verbatim. - Output:
PLAN.md(milestones, dependencies, file changes) andARCHITECTURE.md(system overview, data flow, interfaces)
- Role: Implementation specialist. Writes code, runs tests, self-reviews.
- Model: Opus
- Tools: Read, Write, Edit, MultiEdit, Bash, Glob, Grep (full write access)
- Key behavior: Reads
PLAN.mdFIRST — the plan is law. Implements ONLY what the plan specifies. Self-reflects after making changes. - Output: Changes Made (per-file), Specs (test results), Self-Review Findings, Plan Gaps
- Role: Post-implementation code auditor. Reads changed code AND interacting code.
- Model: Opus
- Tools: Read, Bash, Glob, Grep (no write access)
- Key behavior: Reviews changed files AND their callers/dependencies. Checks for race conditions, N+1 queries, missing validations, TOCTOU issues, dead code.
- Output: Verdict (PASS/FAIL), CRITICAL / MODERATE / MINOR issues, plus a "Positive" section
- Role: Adversarial challenger. Finds problems, not confirms solutions.
- Model: Opus
- Tools: Read, Bash, Glob, Grep (no write access)
- Key behavior: Does its OWN independent research — reads actual code to verify/disprove claims. Provides counter-proposals when it finds issues.
- Output: Verdict (SOLID / HAS ISSUES / NEEDS REWORK), Critical Issues, Concerns, Counter-proposals
- Role: Meta-learning agent. Mines conversation transcripts for reusable knowledge.
- Model: Opus
- Tools: Read, Glob, Grep (most restricted — no Bash, no write)
- Key behavior: Distinguishes between SKILLS (techniques, workflows) and MEMORIES (preferences, decisions, conventions).
- Output: Categorized findings (SKILL or MEMORY) with title, description, examples, and source context
| Agent | Can Read | Can Write | Can Run Shell |
|---|---|---|---|
| Researcher | Yes | Research docs only | Yes |
| Planner | Yes | Yes | Yes |
| Worker | Yes | Yes | Yes |
| Reviewer | Yes | No | Yes |
| Sceptic | Yes | No | Yes |
| Session Analyzer | Yes | No | No |
The /orc:run command analyzes your task and selects the appropriate workflow:
When: Architecture decisions, technology evaluations Pipeline: Researcher (explore) -> Sceptic (challenge findings) -> optional Researcher rebuttal Purpose: Structured debate to stress-test technical decisions
When: New features Pipeline: Researcher -> Planner -> Worker -> Reviewer -> Sceptic Purpose: Full lifecycle from research through adversarial review
When: Regression-risk bugs Pipeline: Researcher (root cause analysis) -> Sceptic (stress-test) -> Worker -> Reviewer Purpose: Ensure bug fixes don't introduce new problems
When: Quality backlog items Pipeline: Worker -> Reviewer -> repeat until PASS Purpose: Tight implementation-review cycle for known issues
When: Proactive issue finding Pipeline: Reviewer finds ONE issue -> Worker fixes -> repeat Purpose: Incremental quality improvement, one issue at a time
When: Pre-merge review Pipeline: Pass 1 (structural review) -> Pass 2 (knowledge-check) -> Pass 3 (adversarial) Purpose: Thorough three-layer review before merging
- One task per agent — each sub-agent gets a single focused assignment
- Orchestrator doesn't code — Claude's main session manages, doesn't implement (unless explicitly asked)
- Human gate by default — requires your approval between phases (you can opt into autonomy)
- Self-reflection mandated — implementation agents must re-read and verify their own changes
- Knowledge base first — agents read
.agent/knowledge/before exploring code - Plans are never reverted — only code gets reverted; plans serve as historical record
./install.shOr manually:
claude plugin marketplace add /path/to/claude-skills
claude plugin install orcRestart Claude Code after installation. /orc:run will appear in your available commands.
To uninstall:
claude plugin uninstall orc
claude plugin marketplace remove claude-skills/orc:run Add rate limiting to the /api/upload endpoint
You: /orc:run Add rate limiting to the /api/upload endpoint
Claude: "This looks like a feature development task. I'll start with a
researcher agent to understand the current upload endpoint implementation
and any existing rate limiting patterns in the codebase. Proceed?"
You: "Yes"
Claude: [Spawns orc:researcher agent]
[Researcher returns findings about the upload endpoint]
Claude: "Research complete. Key findings: [summary]. I'll now spawn a
planner to create an implementation plan. Proceed?"
You: "Yes"
Claude: [Spawns orc:planner with research summary]
[Planner writes plans/feat/rate-limit-upload/PLAN.md]
Claude: "Plan created. Ready for implementation?"
You: "Yes"
Claude: [Spawns orc:worker]
[Worker implements the plan, self-reviews]
Claude: "Implementation complete. Spawning reviewer for code audit?"
You: "Yes, and run the sceptic too"
Claude: [Spawns orc:reviewer, then orc:sceptic]
[Both provide independent assessments]
All agent files use Opus by default. For cost optimization, edit the model: field in agent frontmatter:
- Opus for judgment-heavy agents (sceptic, planner, reviewer)
- Sonnet for execution-focused agents (researcher, worker, session-analyzer)
The system expects a .agent/knowledge/ directory in your project repos containing domain-specific docs. Agents read these before exploring code. Without this directory, the agents still work — they just skip the knowledge-loading step.
You (developer)
|
/orc:run
|
v
+------------------+
| Orchestrator | <-- commands/run.md
| (Claude's main |
| conversation) |
+------------------+
| | | |
+----------+ | | +----------+
v v v v
+-----------+ +---------+ +----------+ +---------+
| Researcher| | Planner | | Worker | | Reviewer|
| (read-only| | (writes | | (writes | |(read- |
| explore) | | plans) | | code) | | only) |
+-----------+ +---------+ +----------+ +---------+
|
+-----------+
| Sceptic |
| (adversa- |
| rial) |
+-----------+
[Session Analyzer] -- runs post-session to extract knowledge