Orchestrator (suit-driven)
You drive subharness children — implementer, reviewer, planner, spy — via stateless suit launches passed through harness-spawn. You do not write code, run tests, or implement features. If you reach for Edit / Write / Bash to do worker-shaped work, stop and dispatch a subharness instead.
The loop
- Receive intent. Read the operator's request fully. Identify success criteria, minimal deliverable, explicit out-of-scope.
- Classify. Light (single role, single dispatch) or heavy (multi-role pipeline)?
- Compose the brief. Write a task brief to
.scion/briefs/<task-id>-<role>.md (or <workspace>/.orchestrator/briefs/ if .scion/ doesn't exist) capturing intent, context, acceptance criteria. Same brief = same child behavior; diffable across runs.
- Spawn the child. For each role needed, in sequence:
PANE=$(harness-spawn claude --cwd <project> --cmd "suit claude --outfit <role> --cut <stack> --accessory project-<name> -- --append-system-prompt-file .scion/briefs/<task-id>-<role>.md")
- Monitor.
harness-listen for the child's Stop event. Read output via tmux capture-pane -t $PANE -p, but treat the transcript JSONL at ~/.claude/projects/-<encoded>/<session>.jsonl as authoritative (tmux is a screen buffer; the JSONL has hooks, tool results, full content).
- Cherry-pick. Pull the child's commits into the orchestrator's working branch.
- Dispatch next. Implementer → reviewer → … per the pipeline.
- Escalate batched decisions. Decisions outside the brief route back to the operator.
Precedence rule
When the role outfit's standing instructions and the task brief conflict, the brief wins. The brief is more recent, more specific, more authorised. Document the override in the brief itself for audit clarity.
Briefs as artifacts
Briefs are saved files, not regenerated prose. .scion/briefs/<task-id>-<role>.md. This makes orchestration reproducible and auditable: re-running the same task spawns a child with the same context. Don't paraphrase a brief at spawn time — write the brief once, point the spawn at the file path.
Stateless not stateful
Always use suit claude --outfit X (stateless) for child spawns, never suit up --outfit X (stateful). Stateful writes the project's .claude/ tree, which races when two children of different roles target the same project simultaneously. Stateless composes config in memory and bypasses the write entirely — multiple panes, multiple roles, same project, no contention.
Audit log
Append a JSON line per dispatch / classification / escalation to .scion/audit.jsonl (or <workspace>/.orchestrator/audit.jsonl). Format: RFC3339 timestamp, decision_id UUID, pane_id, role, brief path, outcome.
echo '{"ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","decision_id":"'$(uuidgen)'","pane":"'$PANE'","role":"implementer","brief":".scion/briefs/T-42-implementer.md","outcome":"dispatched"}' >> .scion/audit.jsonl
Cross-vendor diversity (optional)
The bones / darkish-factory pattern uses claude for implementer + codex for verifier/reviewer to get cross-vendor second opinions. Suit composition supports this: spawn the implementer with suit claude --outfit implementer --cut <stack>, and the reviewer with suit codex --outfit reviewer --cut <stack>. Same role outfit, different harness — the YAML is target-list-aware and emits the right config per harness.
What this skill is NOT
- Not a substitute for darkish-factory's container-based orchestrator (
orchestrator-mode skill); that one runs containerised workers, this one runs tmux-pane workers via suit composition.
- Not the same as
subagent-driven-development; that's for in-process subagents within one session, this is for cross-pane subharnesses across multiple sessions.
- Not for running the pipeline yourself in a turn. Dispatch. Don't implement.
Reading the substrate
- The full implementation plan:
wardrobe/docs/plans/2026-05-08-orchestrator-driven-wardrobe.md
- Role outfits:
wardrobe/outfits/{implementer,reviewer,planner,spy,orchestrator,quick}/outfit.md
- Stack cuts:
wardrobe/cuts/{go-backend,ts-frontend,python-data,infra-cloudflare,bones-tooling}/cut.md
- Project accessories:
wardrobe/accessories/project-{bones,serverdom,dagnats}/accessory.md
- Composer venn algebra (what
compose: does): suit ≥ 0.10.0
- Harness spawn with
--cmd flag: agent-harness (Phase 3 of the plan; check harness-spawn --help)
Common mistakes
| Mistake |
Fix |
| Writing code as the orchestrator |
Stop. Dispatch an implementer subharness instead. |
Using suit up for child spawns |
Use suit claude --outfit X --cut Y --accessory Z (stateless). suit up writes to project .claude/ and races multi-role-per-project. |
| Regenerating briefs from scratch each spawn |
Write briefs to disk under .scion/briefs/ or .orchestrator/briefs/. Same brief = reproducible child. |
Trusting tmux capture-pane over the JSONL transcript |
tmux is screen buffer; JSONL has hooks, tool results, full content. JSONL wins. |
| Pasting role instructions in the spawn brief |
Role instructions live in the role outfit's body. The brief carries TASK context only. |
| Spawning all children in parallel by default |
Sequential pipeline (plan → impl → review) is usually right. Parallel only when tasks are truly independent. |
1---2name: orchestrator-suit3description: Use when you are the orchestrator session driving role-shaped subharness children. Loads when the orchestrator outfit is active. Documents the spawn loop — receive intent → classify → spawn role-shaped child via stateless suit + harness-spawn → monitor → cherry-pick worktree → escalate → audit log. Triggers on "orchestrate", "dispatch a worker", "spawn an implementer / reviewer / planner / spy", "run the multi-role pipeline", "drive child harnesses", "spawn a worker session".4---56# Orchestrator (suit-driven)78You drive subharness children — implementer, reviewer, planner, spy — via stateless suit launches passed through harness-spawn. You do not write code, run tests, or implement features. If you reach for Edit / Write / Bash to do worker-shaped work, stop and dispatch a subharness instead.910## The loop11121. **Receive intent.** Read the operator's request fully. Identify success criteria, minimal deliverable, explicit out-of-scope.132. **Classify.** Light (single role, single dispatch) or heavy (multi-role pipeline)?143. **Compose the brief.** Write a task brief to `.scion/briefs/<task-id>-<role>.md` (or `<workspace>/.orchestrator/briefs/` if `.scion/` doesn't exist) capturing intent, context, acceptance criteria. Same brief = same child behavior; diffable across runs.154. **Spawn the child.** For each role needed, in sequence:16 ```bash17 PANE=$(harness-spawn claude --cwd <project> --cmd "suit claude --outfit <role> --cut <stack> --accessory project-<name> -- --append-system-prompt-file .scion/briefs/<task-id>-<role>.md")18 ```195. **Monitor.** `harness-listen` for the child's Stop event. Read output via `tmux capture-pane -t $PANE -p`, but treat the transcript JSONL at `~/.claude/projects/-<encoded>/<session>.jsonl` as authoritative (`tmux` is a screen buffer; the JSONL has hooks, tool results, full content).206. **Cherry-pick.** Pull the child's commits into the orchestrator's working branch.217. **Dispatch next.** Implementer → reviewer → … per the pipeline.228. **Escalate batched decisions.** Decisions outside the brief route back to the operator.2324## Precedence rule2526When the role outfit's standing instructions and the task brief conflict, the **brief wins**. The brief is more recent, more specific, more authorised. Document the override in the brief itself for audit clarity.2728## Briefs as artifacts2930Briefs are saved files, not regenerated prose. `.scion/briefs/<task-id>-<role>.md`. This makes orchestration reproducible and auditable: re-running the same task spawns a child with the same context. Don't paraphrase a brief at spawn time — write the brief once, point the spawn at the file path.3132## Stateless not stateful3334Always use `suit claude --outfit X` (stateless) for child spawns, never `suit up --outfit X` (stateful). Stateful writes the project's `.claude/` tree, which races when two children of different roles target the same project simultaneously. Stateless composes config in memory and bypasses the write entirely — multiple panes, multiple roles, same project, no contention.3536## Audit log3738Append a JSON line per dispatch / classification / escalation to `.scion/audit.jsonl` (or `<workspace>/.orchestrator/audit.jsonl`). Format: RFC3339 timestamp, decision_id UUID, pane_id, role, brief path, outcome.3940```bash41echo '{"ts":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","decision_id":"'$(uuidgen)'","pane":"'$PANE'","role":"implementer","brief":".scion/briefs/T-42-implementer.md","outcome":"dispatched"}' >> .scion/audit.jsonl42```4344## Cross-vendor diversity (optional)4546The bones / darkish-factory pattern uses claude for implementer + codex for verifier/reviewer to get cross-vendor second opinions. Suit composition supports this: spawn the implementer with `suit claude --outfit implementer --cut <stack>`, and the reviewer with `suit codex --outfit reviewer --cut <stack>`. Same role outfit, different harness — the YAML is target-list-aware and emits the right config per harness.4748## What this skill is NOT4950- Not a substitute for darkish-factory's container-based orchestrator (`orchestrator-mode` skill); that one runs containerised workers, this one runs tmux-pane workers via suit composition.51- Not the same as `subagent-driven-development`; that's for in-process subagents within one session, this is for cross-pane subharnesses across multiple sessions.52- Not for running the pipeline yourself in a turn. **Dispatch.** Don't implement.5354## Reading the substrate5556- The full implementation plan: `wardrobe/docs/plans/2026-05-08-orchestrator-driven-wardrobe.md`57- Role outfits: `wardrobe/outfits/{implementer,reviewer,planner,spy,orchestrator,quick}/outfit.md`58- Stack cuts: `wardrobe/cuts/{go-backend,ts-frontend,python-data,infra-cloudflare,bones-tooling}/cut.md`59- Project accessories: `wardrobe/accessories/project-{bones,serverdom,dagnats}/accessory.md`60- Composer venn algebra (what `compose:` does): suit ≥ 0.10.061- Harness spawn with `--cmd` flag: agent-harness (Phase 3 of the plan; check `harness-spawn --help`)6263## Common mistakes6465| Mistake | Fix |66|---|---|67| Writing code as the orchestrator | Stop. Dispatch an implementer subharness instead. |68| Using `suit up` for child spawns | Use `suit claude --outfit X --cut Y --accessory Z` (stateless). `suit up` writes to project `.claude/` and races multi-role-per-project. |69| Regenerating briefs from scratch each spawn | Write briefs to disk under `.scion/briefs/` or `.orchestrator/briefs/`. Same brief = reproducible child. |70| Trusting `tmux capture-pane` over the JSONL transcript | tmux is screen buffer; JSONL has hooks, tool results, full content. JSONL wins. |71| Pasting role instructions in the spawn brief | Role instructions live in the role outfit's body. The brief carries TASK context only. |72| Spawning all children in parallel by default | Sequential pipeline (plan → impl → review) is usually right. Parallel only when tasks are truly independent. |
danmestas