install-orchestrator.sh

#!/usr/bin/env bash
set -euo pipefail

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
BOLD='\033[1m'
RESET='\033[0m'

info()  { printf "${BLUE}▸${RESET} %s\n" "$*"; }
ok()    { printf "${GREEN}✔${RESET} %s\n" "$*"; }
warn()  { printf "${YELLOW}⚠${RESET} %s\n" "$*"; }
err()   { printf "${RED}✘${RESET} %s\n" "$*" >&2; }
fatal() { err "$@"; exit 1; }

# ── Pre-flight checks ────────────────────────────────────────────────

info "Checking prerequisites..."

# Check claude is installed
if ! command -v claude &>/dev/null; then
  fatal "Claude Code CLI not found. Install it first: https://docs.anthropic.com/en/docs/claude-code"
fi
ok "Claude Code CLI found: $(command -v claude)"

# Check codex is installed
if ! command -v codex &>/dev/null; then
  warn "OpenAI Codex CLI not found (optional — needed at runtime for spawning agents)"
  warn "Install it later with: npm install -g @openai/codex"
else
  ok "Codex CLI found: $(command -v codex)"
fi

# Check git
if ! command -v git &>/dev/null; then
  fatal "git not found. Please install git first."
fi
ok "git found"

# ── Install location ─────────────────────────────────────────────────

COMMANDS_DIR="${HOME}/.claude/commands"
TARGET="${COMMANDS_DIR}/orchestrate.md"

if [[ -f "$TARGET" ]]; then
  warn "Orchestrator command already exists at ${TARGET}"
  printf "  Overwrite? [y/N] "
  # If piped (no tty), default to yes
  if [[ -t 0 ]]; then
    read -r answer
  else
    answer="y"
    echo "y (non-interactive)"
  fi
  if [[ ! "$answer" =~ ^[Yy]$ ]]; then
    info "Aborted. Existing file left untouched."
    exit 0
  fi
fi

# ── Create directory ─────────────────────────────────────────────────

if [[ ! -d "$COMMANDS_DIR" ]]; then
  info "Creating ${COMMANDS_DIR}..."
  mkdir -p "$COMMANDS_DIR"
  ok "Directory created"
else
  ok "Directory already exists: ${COMMANDS_DIR}"
fi

# ── Write the command ────────────────────────────────────────────────

info "Installing /orchestrate command..."

cat > "$TARGET" << 'COMMAND'
You are acting as a **multi-agent orchestrator**. The user will describe one or more tasks to be done in this repo. Your job is to break them into independent units of work, delegate each to a Codex agent running in its own git worktree, monitor progress, review the results, and merge back to main.

## Workflow

### 1. Orient yourself
- Read `CLAUDE.md` (and any other repo conventions) so you can write accurate task specs.
- Explore the relevant parts of the codebase to understand current architecture.

### 2. Plan the work
- Break the request into independent tasks that can run in parallel.
- For each task, decide on a short kebab-case name (e.g. `compact-log`, `wait-endpoint`).

### 3. Set up worktrees
For each task:
```bash
git branch feature/<name> main
git worktree add ../<repo>-<name> feature/<name>
```

### 4. Write task specs
Create a `TASK.md` in each worktree root. Each TASK.md must include:
- **Objective**: What to build and why.
- **Current architecture**: Relevant file paths, data structures, and flows (be specific — the agent has no prior context).
- **Requirements**: Numbered list of concrete deliverables.
- **Acceptance criteria**: What "done" looks like, including build/test commands.
- **Out of scope**: What NOT to change.
- **Files to modify**: Explicit list of files likely involved.

Copy any repo conventions from `CLAUDE.md` into the task spec so the agent follows them.

### 5. Launch agents
Spawn all agents in parallel using background bash commands:
```bash
codex exec \
  --full-auto \
  -C <worktree-path> \
  -o <worktree-path>/CODEX_OUTPUT.md \
  "Read TASK.md and implement the task. Follow all conventions. Build and test before finishing."
```

### 6. Monitor
Periodically check:
- `ps aux | grep codex` — are they still running?
- `git -C <worktree> status --short` — are files being modified?
- `git -C <worktree> diff --stat` — scope of changes.

Report progress to the user when there are meaningful updates.

### 7. Review
Once an agent finishes:
- Read its `CODEX_OUTPUT.md` for a summary.
- Review the diff: `git -C <worktree> diff main`
- Check that it builds and tests pass.
- Note any issues to fix (you can either fix them yourself or re-run codex with targeted instructions).

### 8. Merge
After review and approval:
```bash
git checkout main
git merge --no-ff feature/<name> -m "feat: <description>"
```
Clean up:
```bash
git worktree remove ../<repo>-<name>
git branch -d feature/<name>
```

## Rules
- Never commit directly to main. Always use feature branches.
- Each agent gets its own worktree — they must never share one.
- Write thorough TASK.md files. The agent's quality depends entirely on your spec quality.
- If a task depends on another, run them sequentially, not in parallel.
- Always run the project's build/test commands after merging to verify integration.
COMMAND

ok "Installed: ${TARGET}"

# ── Verify ───────────────────────────────────────────────────────────

echo ""
printf "${BOLD}${GREEN}Done!${RESET} The ${BOLD}/orchestrate${RESET} command is now available in Claude Code.\n"
echo ""
echo "  Usage: open any repo in Claude Code and type:"
echo ""
printf "    ${BOLD}/orchestrate${RESET} <describe your tasks here>\n"
echo ""
echo "  Example:"
echo "    /orchestrate refactor the logger to be async and add a health-check endpoint"
echo ""