How it works

GitHub PR comment
       │
       ▼
┌──────────────┐     WebSocket      ┌─────────────────┐
│ Orchestrator │ ◄────────────────► │ Agent(s)        │
│ webhooks,    │                    │ clone, plan,    │
│ jobs, locks, │                    │ apply           │
│ PR comments  │                    └─────────────────┘
└──────────────┘

1. A PR comment like terraplane plan -s stg-apse2-foundation hits the orchestrator.
2. The orchestrator reads terraplane.yaml from the repo, resolves stacks, and dispatches work to the named agent.
3. The agent runs Terraform and streams results back.
4. The orchestrator posts plan/apply/unlock feedback on the PR.

Repo config

Stacks map a logical name to an agent and a working directory:

stacks:
  - name: stg-apse2-foundation
    agent: agent-dev
    dir: terraform/environments/staging/ap-southeast-2/foundation

The agent value must match the AGENT_ID of a connected agent.

What the orchestrator owns

• GitHub webhook verification and event handling
• Job and lock state (Postgres)
• Dispatching work to the right agent
• Writing results back to the PR

What agents own

• Dialing out to the orchestrator (AGENT_ORCHESTRATOR_URL)
• Cloning with the configured deploy key
• Running plan / apply in the stack directory
• Streaming output home

That boundary is intentional: keep secrets and network reachability with the agent, keep GitHub-facing coordination with the orchestrator.