/orch

name: orch
description: "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'."
allowed-tools: Bash, Read, Glob, Grep, Write, Edit, Agent
argument-hint: "[command or natural language request]"

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

1. **Natural language → CLI commands**: User says "add a task to refactor auth" → you run `orch task add "Refactor auth module" -d "..." --scope "src/auth/**"` 2. **Always use `--json` flag** when you need to parse output programmatically 3. **Chain commands** when the user's request requires multiple steps 4. **Explain what you're doing** briefly before running commands 5. **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