orch

AI agent orchestrator — manage teams of AI agents that work on your codebase in parallel. Use when the user wants to: run multiple agents, coordinate AI work, deploy agent teams, manage tasks/goals/agents, check orchestrator status, or mentions 'orch', 'orchestry', 'agents team', 'agent orchestration'.

install

source · Clone the upstream repo

git clone https://github.com/oxgeneral/ORCH

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/oxgeneral/ORCH "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/orch" ~/.claude/skills/oxgeneral-orch-orch && rm -rf "$T"

manifest: skills/orch/SKILL.md

source content

ORCH — AI Agent Orchestrator

You are the user's assistant for ORCH (

@oxgeneral/orch

) — an AI agent runtime that coordinates teams of LLM agents working on a codebase in parallel.

Your role: interpret user intent and execute the right

orch

CLI commands. The user may speak in natural language — translate their intent into concrete actions.

How to Work

Natural language → CLI commands: User says "add a task to refactor auth" → you run
```
orch task add "Refactor auth module" -d "..." --scope "src/auth/**"
```
Always use
--json
flag when you need to parse output programmatically
Chain commands when the user's request requires multiple steps
Explain what you're doing briefly before running commands
Show results in a readable format after commands complete

Quick Start Flow

If the project is not initialized (no

.orchestry/

directory):

orch init --name "project-name"

If there are no agents:

orch agent shop  # or suggest pre-built org templates

Complete CLI Reference

Project Setup

orch init [--name <name>]          # Initialize .orchestry/ in current directory
orch doctor                        # Check adapters and dependencies
orch update [--check]              # Check/install updates
orch status                        # Show orchestrator overview

Task Management

# Create tasks
orch task add "<title>" [options]
  -d, --description <desc>         # Task description
  -p, --priority <1-4>             # Priority (1=highest, default: 3)
  -l, --labels <a,b,c>             # Comma-separated labels
  --depends-on <id1,id2>           # Dependency task IDs
  --assignee <agent-id>            # Assign to specific agent
  --scope <patterns>               # File scope globs (e.g. src/auth/**,src/session/**)
  --review-criteria <criteria>     # Auto-review: test_pass,typecheck,lint
  --workspace-mode <mode>          # shared|worktree|isolated
  --goal-id <goalId>               # Link to a goal
  --attach <paths>                 # Attach files (screenshots, docs)
  --max-attempts <n>               # Max retry attempts
  -e, --edit                       # Open $EDITOR for description

# List and view
orch task list [--status <status>] # List tasks (filter: todo,in_progress,review,done,failed,cancelled)
orch task show <id>                # Show task details

# Lifecycle
orch task assign <task-id> <agent-id>  # Assign task to agent
orch task cancel <id>              # Cancel task (stops agent if running)
orch task approve <id>             # Approve task in review → done
orch task reject <id> [-r <reason>] # Reject task → back to todo
orch task retry <id>               # Retry failed task
orch task edit <id>                # Edit in $EDITOR

Task Status Flow:

todo → in_progress → review → done

with

retrying

and

failed

branches.

Agent Management

# Create agents
orch agent add "<name>" --adapter <type> [options]
  --adapter <type>                 # REQUIRED: claude|opencode|codex|cursor|shell
  --role <description>             # Agent role/expertise
  --model <model>                  # Model name
  --effort <level>                 # Reasoning effort: low, medium, high (Claude only)
  --command <cmd>                  # Shell command (for shell adapter)
  --max-turns <n>                  # Max turns per run
  --timeout <ms>                   # Timeout in milliseconds
  --approval-policy <policy>       # auto|suggest|manual
  --workspace-mode <mode>          # shared|worktree|isolated
  --skills <skills>                # Comma-separated skills
  -e, --edit                       # Open $EDITOR for role

# Agent shop — pre-built templates
orch agent shop [--list]           # Browse/install templates

# Manage
orch agent list                    # List all agents
orch agent status <id>             # Show agent details + stats
orch agent edit <id>               # Edit agent
orch agent remove <id>             # Remove agent
orch agent disable <id>            # Disable agent
orch agent enable <id>             # Enable agent
orch agent autonomous <id> [--on|--off]  # Toggle autonomous mode

Available Agent Templates: backend-dev, frontend-dev, qa-engineer, code-reviewer, architect, devops-engineer, bug-hunter, tech-writer, marketer, content-creator, growth-hacker, security-auditor, performance-engineer, data-engineer, fullstack-dev

Execution

orch run <task-id>                 # Run single task
orch run --all                     # Run all todo tasks
orch run --watch                   # Continuous orchestration (tick loop)
orch tui                           # Interactive TUI dashboard
orch serve [options]               # Headless daemon mode
  --once                           # Process and exit (CI/CD mode)
  --tick-interval <ms>             # Override poll interval
  --log-file <path>                # Tee logs to file
  --log-format <json|text>         # Log format (default: json)
  --verbose                        # Include agent:output events

Goals (High-Level Objectives)

orch goal add "<title>" [options]
  --description <desc>             # Goal description
  --assignee <agentId>             # Assign to agent for decomposition

orch goal list [--status <status>] # List goals
orch goal show <id>                # Show goal + progress report
orch goal status <id> <status>     # Change status: active|paused|achieved|abandoned
orch goal update <id> [options]    # Update title/description/assignee
orch goal delete <id>              # Delete goal

Teams

orch team create "<name>" --lead <agent-id> [options]
  --members <id1,id2>             # Initial members
  -d, --description <desc>        # Team description
  --no-auto-claim                 # Disable auto-claiming

orch team list                    # List teams
orch team show <id>               # Show team details
orch team join <team-id> <agent-id>    # Add member
orch team leave <team-id> <agent-id>   # Remove member
orch team add-task <team-id> <task-id> # Add task to pool
orch team set-lead <team-id> <agent-id> # Transfer lead
orch team disband <id>            # Disband team

Pre-Built Organizations

orch org list                     # List available templates
orch org deploy <template> [--goal "<objective>"]

Available Templates:

```
startup-mvp
```
— Ship MVP in 48h (CTO + 2 Backend + Frontend + QA + Reviewer)
```
pr-review-corp
```
— Auto-review every PR (Security + Performance + Style + QA)
```
migration-squad
```
— JS→TS migration (CTO + 3 Migrators + QA + Reviewer)
```
security-dept
```
— Multi-layer audit (Lead + Scanner + Secrets + Hunter + Reviewer)
```
test-factory
```
— Coverage 40%→80% (Lead + 2 Backend + 3 QA + Reviewer)
```
bugfix-dept
```
— 100 issues→0 (Triager + 3 Fixers + QA + Reviewer)
```
docs-team
```
— Docs from code (Lead + 2 Writers + Editor + Reviewer)
```
content-agency
```
— Content factory (Strategist + 2 Writers + Editor + SEO)
```
data-lab
```
— CSVs→executive report (Lead Analyst + Data Engineer)
```
sales-machine
```
— Outbound pipeline (Director + 2 SDRs + Copywriter + Growth)

Inter-Agent Communication

# Messages
orch msg send <to-agent-id> "<body>" [-s <subject>] [--from <id>] [--ttl <ms>]
orch msg broadcast "<body>" [-s <subject>] [--team <team-id>]
orch msg inbox <agent-id>          # Pending messages
orch msg list [--agent <id>]       # All messages

# Shared Context
orch context set <key> <value> [--ttl <ms>]
orch context get <key>
orch context list
orch context delete <key>

Configuration

orch config get <key>              # Get config value (dot notation)
orch config set <key> <value>      # Set config value
orch config edit                   # Edit config.yml in $EDITOR

# Global settings (~/.orchestry/global.yml)
orch config global get <key>
orch config global set <key> <value>
orch config global show

Logs

orch logs [run-id]                 # View run logs
  --agent <agent-id>               # Filter by agent
  --task <task-id>                 # Filter by task
  --follow                         # Live stream
  --since <duration>               # Time filter (5m, 1h, 1d)

Common Workflows

"Set up a team to work on my project"

```
orch init
```
(if needed)

orch org deploy startup-mvp --goal "Build feature X"

OR manually create agents

```
orch tui
```
or
```
orch run --watch
```
to start

"Add a task and run it"

orch task add "Fix login bug" -d "The login form crashes on empty email" --scope "src/auth/**" -p 1

```
orch run <task-id>
```

"Check what's happening"

```
orch status
```
— overview
```
orch task list --status in_progress
```
— running tasks
```
orch logs --follow
```
— live output

"Deploy a review team for PRs"

orch org deploy pr-review-corp --goal "Review all open PRs"

Tasks are auto-created and assigned

"I want to refactor X across the codebase"

Create a goal:

orch goal add "Refactor X" --description "..." --assignee <lead-agent>

Lead agent decomposes goal into tasks automatically
```
orch run --watch
```
to execute

Key Concepts

Agents run in isolated git worktrees (no merge conflicts)
Tasks flow through: todo → in_progress → review → done
Goals are decomposed into tasks by a lead agent
Teams coordinate agents with a lead + members
Adapters: claude, opencode, codex, cursor, shell
All state stored in
```
.orchestry/
```
(YAML/JSON, no database)
IDs are prefixed:
```
tsk_
```
,
```
agt_
```
,
```
run_
```
,
```
goal_
```
,
```
team_
```
,
```
msg_
```

When to Use Goals vs Tasks

Use a Task when:

You know exactly what needs to be done — one concrete action
The scope is clear: fix a bug, write a test, update a file, review a PR
You can describe the result in one sentence
Examples: "Fix login crash on empty email", "Add unit tests for auth service", "Update README badges"

orch task add "Fix login crash" -d "Empty email causes TypeError in validate()" --scope "src/auth/**" -p 1

Use a Goal when:

The objective is high-level and needs decomposition — you don't know all the steps upfront
Multiple tasks will be needed, potentially across different agents/skills
You want an agent to autonomously plan and execute the work
Examples: "Implement OAuth2", "Migrate from REST to GraphQL", "Improve test coverage to 80%"

orch goal add "Implement OAuth2 with Google and GitHub" --description "Support social login, add tests, update docs" --assignee <lead-agent>

The assigned agent enters autonomous mode: it analyzes the codebase, creates tasks, assigns them to appropriate agents, and monitors progress until the goal is achieved.

Use a Goal for iterative improvement:

You have a measurable metric and want the agent to keep working until it's met
The agent runs cycles: measure → fix → measure again → repeat
Examples: "Get test coverage to 80%", "Zero TypeScript errors", "All /simplify reviews clean"

orch goal add "Reach 80% test coverage" --description "Run coverage, find gaps, write tests, repeat until ≥80%" --assignee <qa-agent>

Choosing an assignee for a goal

A goal without

--assignee

stays unassigned and no agent picks it up automatically. Always assign a goal to an agent.

Before creating a goal, check available agents:

orch agent list

Pick the agent whose role best matches the goal:

Code quality / testing → QA agent
Architecture / refactoring → CTO / architect agent
Documentation → CTO or dedicated docs agent
Feature work → relevant domain agent (backend, frontend, etc.)
Strategic / cross-cutting → CEO or lead agent

# Example: assign docs update to CTO
orch goal add "Update docs for v2" --description "..." --assignee agt_T0uF5KP

If no suitable agent exists, create one first via

orch agent add

orch agent shop

Rule of thumb

1 agent, 1 action → Task
Multiple agents, unclear steps → Goal
Iterative loop until metric is met → Goal

Configuration Reference

# .orchestry/config.yml
project:
  name: "my-project"
defaults:
  agent:
    adapter: "claude"           # Default adapter
    approval_policy: "auto"     # auto|suggest|manual
    max_turns: 50               # Max LLM turns per run
    timeout_ms: 3600000         # 1 hour timeout
    stall_timeout_ms: 600000    # 10 min stall detection
    workspace_mode: "worktree"  # shared|worktree|isolated
  task:
    max_attempts: 3             # Max retries
    priority: 3                 # Default priority (1-4)
scheduling:
  poll_interval_ms: 10000       # Tick interval (10s)
  max_concurrent_agents: 6      # Parallel agent limit
  retry_base_delay_ms: 10000    # Retry backoff base
  retry_max_delay_ms: 300000    # Max retry delay (5min)

Creating Agents — Sources and Best Practices

Quick: Use Pre-Built Templates

orch agent shop              # Interactive picker — 15 templates
orch agent shop --list       # Print all templates non-interactively
orch org deploy <template>   # Deploy a full team with one command

Agent Shop Templates (src/domain/agent-shop.ts)

Each template includes a detailed role prompt, model, skills, and approval policy:

Template	Role	Model	Skills
`backend-dev`	APIs, services, DB layers	claude-sonnet-4-6	feature-dev
`frontend-dev`	React UI, components, CSS	claude-sonnet-4-6	feature-dev, frontend-design
`qa-engineer`	Tests, coverage analysis	claude-sonnet-4-6	testing-suite
`code-reviewer`	PR review, bugs, security	claude-opus-4-6	feature-dev:code-reviewer
`architect`	System design, architecture	claude-opus-4-6	feature-dev:code-architect
`devops-engineer`	CI/CD, infrastructure	claude-sonnet-4-6	devops-automation
`bug-hunter`	Find bugs, reproduce, fix	claude-sonnet-4-6	feature-dev
`tech-writer`	Docs, READMEs, API docs	claude-sonnet-4-6	perfect-readme
`security-auditor`	Security scanning, vulns	claude-opus-4-6	testing-suite
`performance-engineer`	Optimization, profiling	claude-sonnet-4-6	testing-suite
`data-engineer`	Data pipelines, ETL	claude-sonnet-4-6	—
`fullstack-dev`	End-to-end development	claude-sonnet-4-6	feature-dev
`marketer`	Marketing strategy, copy	claude-sonnet-4-6	marketing-psychology
`content-creator`	Blog posts, social media	claude-sonnet-4-6	—
`growth-hacker`	Growth experiments	claude-sonnet-4-6	marketing-psychology

Org Templates (src/domain/org-shop.ts)

Pre-built teams — deploy with

orch org deploy <key> --goal "..."

Template	Agents	Use Case
`startup-mvp`	CTO + 2 Backend + Frontend + QA + Reviewer	Ship MVP fast
`pr-review-corp`	CTO + Security + Performance + Style + QA	Auto-review PRs
`migration-squad`	CTO + 3 Migrators + QA + Reviewer	JS→TS migration
`security-dept`	Lead + Scanner + Secrets + Hunter + Reviewer	Security audit
`test-factory`	Lead + 2 Backend + 3 QA + Reviewer	Coverage boost
`bugfix-dept`	Triager + 3 Fixers + QA + Reviewer	Issue backlog
`docs-team`	Lead + 2 Writers + Editor + Reviewer	Documentation
`content-agency`	Strategist + 2 Writers + Editor + SEO	Content
`data-lab`	Lead Analyst + Data Engineer	Data analysis
`sales-machine`	Director + 2 SDRs + Copywriter + Growth	Outbound

Custom Agents: Role Prompt Structure

When creating custom agents with

orch agent add

, follow this proven structure from the shop templates:

# [Role Name]

[One-line description of what this agent does]

## WORKFLOW
1) READ — understand the task scope
2) EXPLORE — analyze existing code/data with appropriate skills
3) PLAN — outline approach before executing
4) EXECUTE — do the work following conventions
5) VERIFY — self-review, run tests
6) REPORT — summarize what was done, flag risks

## RULES
- [Convention 1]
- [Convention 2]
- [Safety guardrail]

Skills Available for Agents

Assign skills via

--skills

flag or edit agent YAML. You can mix both types:

--skills "review,feature-dev:code-explorer,investigate"

Library Skills (injected into system prompt — works with ALL adapters)

Content from the skill library is loaded and appended to the agent's system prompt at execution time. Use plain names (no colons):

Skill	Best For
`review`	Pre-landing code review with auto-fix, checklists, adversarial review
`qa`	Full QA testing + browser testing + bug fixing + health scoring
`qa-only`	QA testing without auto-fixes (report only)
`ship`	Automated ship workflow: merge, test, coverage audit, PR creation
`office-hours`	YC-style product thinking, design docs, premise challenge
`investigate`	Systematic debugging with root cause methodology, 3-strike hypothesis
`careful`	Safety guardrails for destructive commands
`guard`	Full safety mode (careful + freeze combined)
`freeze`	Restrict edits to a specific directory
`unfreeze`	Clear freeze boundary
`design-consultation`	Design system creation, visual language definition
`design-review`	Design review with accessibility, responsiveness checks
`plan-ceo-review`	CEO-level strategic review of plans
`plan-eng-review`	Engineering review of technical plans
`plan-design-review`	Design review of plans
`autoplan`	Auto-review pipeline with decision principles
`land-and-deploy`	Merge PR, wait for CI, verify production health
`canary`	Post-deploy canary monitoring
`document-release`	Auto-update documentation after ship
`retro`	Weekly engineering retrospective with trends
`browse`	Headless browser navigation and testing
`benchmark`	Performance benchmarking with before/after metrics
`codex`	OpenAI Codex cross-review / multi-AI challenge
`setup-deploy`	Configure deployment settings
`setup-browser-cookies`	Import browser cookies for authenticated QA
`upgrade`	Upgrade skills to latest version

Claude Code MCP Skills (native — Claude adapter only)

Handled natively by Claude CLI. Use

package:skill-name

format (with colon):

Skill	Best For
`feature-dev:feature-dev`	Guided feature development with architecture focus
`feature-dev:code-explorer`	Deep codebase analysis and tracing
`feature-dev:code-architect`	Architecture design and blueprints
`feature-dev:code-reviewer`	Code review with confidence filtering
`testing-suite:generate-tests`	Test generation with edge cases
`testing-suite:test-coverage`	Coverage analysis and gap identification
`testing-suite:e2e-setup`	End-to-end testing configuration
`testing-suite:test-quality-analyzer`	Test suite quality metrics
`devops-automation:cloud-architect`	Cloud infrastructure, Terraform
`frontend-design:frontend-design`	UI/UX design and implementation
`document-skills:frontend-design`	Frontend design (document-skills variant)
`product-manager-toolkit`	RICE prioritization, PRD templates
`marketing-psychology`	Behavioral science for marketing

Tips

Use
```
claude-opus-4-6
```
for strategic/review roles (architect, reviewer, lead) — higher quality reasoning
Use
```
claude-sonnet-4-6
```
for execution roles (developer, QA, writer) — faster, cheaper
Set
```
--approval-policy suggest
```
for strategic agents so humans review decisions
Set
```
--approval-policy auto
```
for execution agents for fully autonomous operation
Use
```
--effort low|medium|high
```
to control reasoning depth (Claude only) —
```
low
```
for simple tasks,
```
medium
```
for balanced,
```
high
```
for complex reasoning
Use
```
--workspace-mode shared
```
for analysis/strategy agents (they read, don't write code)
Use
```
--workspace-mode worktree
```
for coding agents (isolated branches, no conflicts)

Important Notes

Always run
```
orch doctor
```
first if something seems wrong
Use
```
--json
```
flag for programmatic parsing
```
orch serve --once
```
is ideal for CI/CD pipelines
Stall timeout default is 10 minutes — increase for complex tasks via
```
orch config set defaults.agent.stall_timeout_ms 1200000
```
If tasks are stuck after a crash, the orchestrator auto-cleans stale state on restart (v1.0.6+)