Orchestra

A workstream-centered CLI for turning tickets into verified work through coordinated agents.

v1 is:

• local-first
• zellij-first
• Pi-first by default
• backend-neutral by design
• local-markdown ticket runtime

What it does

• creates and manages workstreams
• runs ticket orchestration
• uses git worktrees for isolated work
• tracks local and central orchestration state
• supports approval gates
• supports Telegram for status, routing, and approvals
• supports persona and mode-specific backend, transport, and prompt tuning
• ships built-in playbooks and templates with project/local override support

Prerequisites

Required:

• git
• a git repository
• git worktree support
• bun

Recommended for full workflow:

• zellij
• pi

Install

Install globally from npm:

bun add -g pi-orchestra
# or: npm install -g pi-orchestra

This installs the orchestra command. Check it is available:

orchestra --help

For local development from this checkout:

bun install
bun run orchestra --help

Quick start

Navigate to the project you want Orchestra to manage, then initialize it:

cd /path/to/your/project
orchestra init --yes --ticket-provider local-markdown --strictness enforced --transport direct

Check project status:

orchestra status

Create a workstream:

orchestra workstream create my-task

Run a ticket:

orchestra run feature/01-my-ticket --agent-mode backend

Inspect effective config for a persona:

orchestra config effective architect
orchestra config effective engineer --mode planner
orchestra config effective engineer --mode planner --show-prompt

Inspect a workstream:

orchestra workstream show my-task
orchestra workstream cockpit my-task

Close a workstream:

orchestra workstream close my-task --cleanup-runtime

Persona and mode configuration

agentBackend is the project default backend. Persona and mode backend settings are overlays on top of that default.

Example:

{
  "agentBackend": {
    "kind": "pi",
    "model": "sonnet",
    "thinking": "medium"
  },
  "transport": {
    "kind": "direct"
  },
  "personas": {
    "architect": {
      "backend": {
        "model": "opus",
        "thinking": "high"
      },
      "prompt": {
        "mode": "append",
        "text": "Prefer simple architecture and explicit tradeoffs."
      }
    },
    "reviewer": {
      "backend": {
        "model": "sonnet",
        "thinking": "medium"
      }
    },
    "engineer": {
      "modes": {
        "planner": {
          "backend": {
            "model": "opus",
            "thinking": "high"
          },
          "transport": {
            "kind": "rtk"
          }
        },
        "worker": {
          "backend": {
            "model": "sonnet",
            "thinking": "medium"
          }
        }
      }
    }
  }
}

Prompt customization supports:

• append
• replace
• inline text
• repo-internal prompt file

Prompt composition is inspectable with:

orchestra config effective engineer --mode planner
orchestra config effective engineer --mode planner --show-prompt

Prompt overrides cannot remove Orchestra's runtime, safety, or structured-output contract.

Private local overrides

Use .orchestra.local/config.json for private local overrides layered over orchestra.config.json.

Use these conventions:

• private/local prompts: .orchestra.local/prompts/
• committed team/project prompts: docs/orchestra/prompts/

Example:

{
  "personas": {
    "engineer": {
      "modes": {
        "planner": {
          "backend": {
            "model": "opus",
            "thinking": "high"
          },
          "prompt": {
            "mode": "append",
            "file": ".orchestra.local/prompts/engineer-planner.md"
          }
        }
      }
    }
  }
}

Config inspection and diagnostics redact env values. Orchestra also warns about likely secrets in committed project config and does not allow local config to silently weaken approval or publishing safeguards.

Playbooks, templates, and task artifacts

Built-in v1 playbooks:

• planning
• tdd
• review
• handoff
• to-prd
• to-issues
• diagnose
• adr-decision

Built-in v1 templates:

• task-plan
• task-progress
• handoff
• prd
• issue
• adr
• review
• status-summary
• decision

Override resolution order:

built-in
-> project convention
-> project explicit config
-> local convention
-> local explicit config

Recommended override conventions:

docs/orchestra/playbooks/
docs/orchestra/templates/
.orchestra.local/playbooks/
.orchestra.local/templates/

Explicit config shapes:

{
  "templates": {
    "overrides": {
      "task-plan": "docs/orchestra/templates/task-plan.md"
    }
  },
  "playbooks": {
    "overrides": {
      "planning": {
        "manifest": "docs/orchestra/playbooks/planning/playbook.json",
        "instructions": "docs/orchestra/playbooks/planning/PLAYBOOK.md"
      }
    }
  }
}

orchestra init does not bulk-copy all built-in playbooks or templates.

Planner/worker task artifacts live under:

.workstreams/<name>/.orchestra/tasks/<task-id>/plan.md
.workstreams/<name>/.orchestra/tasks/<task-id>/progress.md

These are runtime operational artifacts. Central workstream summaries remain separate under .orchestra/workstreams/.

Ticket format

v1 runtime uses local markdown tickets.

Convention:

.scratch/orchestra/<feature>/PRD.md
.scratch/orchestra/<feature>/issues/<NN>-<slug>.md

Ticket ref format:

<feature>/<issue>

Example:

billing/02-fix-rounding-bug

Telegram

Telegram is optional.

Use it for:

• run <ticket-ref>
• run <ticket-ref> as <workstream>
• new <workstream>
• status <workstream>
• approve <approval-id>
• decline <approval-id>
• <workstream> <message>

Config lives in orchestra.config.json under telegram.

Main commands

orchestra init
orchestra status
orchestra doctor
orchestra config get <key>
orchestra config effective <persona> [--mode <mode>] [--show-prompt]
orchestra run <ticket-ref> [--workstream <name>] [--agent-mode fake|backend]
orchestra workstream list
orchestra workstream create <name>
orchestra workstream show <name>
orchestra workstream cockpit <name>
orchestra workstream resume <name>
orchestra reconcile-once [workstream]
orchestra workstream close <name> [--retrospective <text>] [--cleanup-runtime]
orchestra approval approve <approval-id>
orchestra approval decline <approval-id>

More docs

• User guide: docs/user-guide.md
• Story cases: docs/story-cases.md
• Project context: CONTEXT.md
• Architecture decisions: docs/adr/