Orchestrator — questions and answers

Answers about the ten-role AI team: what you do, what it does, and which guarantees are enforced by code rather than by a prompt.

1. What is Orchestrator?

   Orchestrator staffs an AI team for a company of one. You say one sentence; it reads your repository, splits the work into slices, drafts a plan for you to approve, then builds, tests and reviews inside containers you never have to open, and opens a pull request. It ships as one binary under the MIT licence at github.com/pamin-labs/orchestrator.

2. What do I actually have to do?

   Three things. You say one sentence. You approve the plan — or send it back and it writes another. You merge. Every step that is not a decision with evidence attached is delegated. Blockers reach you; noise does not.

3. How is this different from one coding agent?

   Ten roles with real boundaries. Only the Engineer writes code. Two others review it and neither is the author: QA checks one slice's diff against its acceptance criteria, and an Auditor sits outside the group, on a different model, and reads the whole branch. A Dispatcher turns your sentence into slices, an Architect assigns each group its own file paths so two groups can never collide, and a Scribe writes the commit and the PR from the finished diff. Adding a role is a YAML file, not code.

4. How do I know a task is really done?

   A slice counts once your own commands pass — test, typecheck, lint. Exit codes decide, not the agent's summary, and there are no percentages: the panel shows which checks passed. At the end of every slice, what the agent claimed it changed is compared against what git actually shows, so a mismatch surfaces there rather than while you read the pull request.

5. What does the sandbox stop?

   Three things. Touching your computer: a container holds one clone of one project, so your other projects, home directory and working copy are not in there. Seeing your real tokens: the container holds values that are the right shape and do not work, and the real token is swapped in outside, the moment the request leaves. Pushing to your repository: a group's credential can only fetch, and pushing happens in a separate container with no agent in it.

6. What does the sandbox not stop?

   Two things, said plainly. Your data leaving — the network is open by default because agents need documentation and packages, so fill in sandbox.denyDomains before your first run if that matters to you. And roles inside one group: a group shares one container, so the boundary is between groups, not between the roles in a group.

7. Why not just tell the agent the rules in a prompt?

   Because prompts get forgotten by turn twenty. Anything a check can catch is enforced in code instead: which files a group may touch, how long a note may be, who pushes a stuck state, and the twelve-line cap on the card that blocks you. You approve a direction and acceptance criteria, never a wall of implementation detail.

8. What do I need to run it?

   Docker, uv, and a Claude and/or ChatGPT subscription. No bun, no node, no toolchain. Two steps: start the sandbox server once on the machine with Docker, then run the orchestrator.