integration guides output styles

Tier 5: Output Styles — Workflow Orchestrator Mode

Prerequisites: Tier 4: Plugin: Skills and Hooks installed and working · Claude Code CLI with output style support

Cross-references: Quick Start · API Reference · Workflow Guide · Self-Improving Workflow

---

What You Get

• Claude never implements directly — it plans, delegates, tracks, and reports
• Structured delegation model: haiku for bulk MCP ops, sonnet for implementation, opus for architecture
• Worktree isolation for parallel implementation without file conflicts
• Agent-owned phase transitions with orchestrator-controlled terminal advancement
• Session task visibility alongside persistent MCP tracking

---

What Output Styles Are

Output styles are persistent behavioral instructions that shape how Claude operates throughout a session. Unlike CLAUDE.md (which provides project context), output styles define Claude's working mode — how it approaches tasks, delegates work, and communicates.

Output styles are personal — they live in ~/.claude/output-styles/ and are activated via .claude/settings.local.json (gitignored). They are not shared with the team.

---

Activating the Workflow Orchestrator

The plugin includes a Workflow Orchestrator output style. To activate it:

Via settings file

Add to .claude/settings.local.json:

{
  "outputStyle": "Workflow Orchestrator"
}

Via CLI

/output-style

Then select Workflow Orchestrator from the list.

---

Key Behavioral Changes

Never Implement Directly

The orchestrator delegates all coding and file changes to subagents. It reads files, plans, reviews diffs, and coordinates — but never edits code itself.

Plan Before Acting

Non-trivial features trigger plan mode (EnterPlanMode). The pre-plan hook fires automatically, gathering MCP state before the plan is written.

Materialize Before Implement

All MCP work items must exist before dispatching implementation agents. The post-plan hook handles this — creating work trees, wiring dependencies, and filling queue-phase notes from the approved plan.

Agent-Owned Phases

Phase transitions follow a strict ownership model:

Transition	Owner	Mechanism
queue → work	Implementation agent	advance_item(trigger="start") — phase entry
work → review/terminal	Orchestrator	advance_item(trigger="start") — routes based on schema
review → terminal	Orchestrator	advance_item(trigger="start") after review verdict

Implementation agents enter their assigned phase and fill its notes. The orchestrator owns all subsequent transitions — it advances the item and inspects newRole to determine the next phase. If the schema has review-phase notes, the item moves to review and a reviewer is dispatched. If not, the item moves directly to terminal.

---

The Delegation Model

The orchestrator always sets the model parameter explicitly on every agent dispatch:

Task type	Model	Rationale
MCP bulk ops, materialization, simple queries	haiku	Fast, cheap, structured output
Code reading, implementation, test writing	sonnet	Strong coding, good cost/quality balance
Architecture, complex tradeoffs, multi-file synthesis	opus	Deep reasoning for cross-file synthesis

Omitting model causes the agent to inherit the orchestrator's model — typically opus — wasting tokens on sonnet-eligible work.

Rule: Never make 3+ MCP write calls in a single orchestrator turn. Delegate bulk MCP write work (multiple item/dependency/note creates) to a haiku agent to keep the orchestrator context clean. Parallelized reads (e.g., get_context + query_items overview) are fine and encouraged.

---

Worktree Isolation

When dispatching multiple implementation agents in parallel, use isolation: "worktree" to give each agent an isolated copy of the repository.

When to use: Independent tasks that modify different files and have no dependency edges between them.

When not to use: Tasks with dependency edges (dispatch sequentially instead). Tasks that change shared domain models or test infrastructure should run first — dispatch the parallel wave only after the test suite passes on the changed baseline.

Lifecycle

1. Orchestrator dispatches agent with isolation: "worktree"
2. Agent works in isolated copy, commits to a worktree branch
3. Agent returns — result includes worktree path and branch name
4. Orchestrator spot-checks diff: git -C <worktree-path> diff main --stat
5. Review agent dispatched into the same worktree path
6. After review passes: push worktree branch to origin and create PR
7. Run full test suite before pushing to catch integration issues
8. After PR merges: sync local main and clean up branch

Tracking Table

Record each dispatched agent immediately:

| Item UUID | Worktree Path | Branch | Status |
|-----------|--------------|--------|--------|
| a1b2c3d4  | /path/to/wt  | fix/x  | in-progress |

---

Session Tasks vs MCP Items

The orchestrator uses two tracking systems in parallel:

System	Persistence	Purpose
Session tasks (TaskCreate)	Current session only	Terminal progress visibility — what is happening right now
MCP items	Cross-session	Persistent tracking — what needs to be done and what has been done

Pattern: Create a session task when dispatching a subagent. Complete it when the agent returns. The MCP item tracks the work across sessions; the session task shows real-time progress in the terminal.

---

Example: Multi-Task Feature

Feature: "Refactor authentication into three components"

1. Plan: Enter plan mode. Pre-plan hook gathers MCP state. Write plan with three tasks. User approves.
2. Materialize: Post-plan creates root item + three children with fan-out dependencies.
3. Dispatch: Three worktree agents in parallel. Each gets a child UUID + target files. Each creates a session task.
4. Phase entry: Each agent calls advance_item(trigger="start") once — queue→work at start. Fills work-phase notes and returns.
5. Orchestrator advances: Calls advance_item(trigger="start") on each item. Items with review-phase notes move to review; lightweight items move to terminal.
6. Review: For items now in review, orchestrator dispatches review agents into each worktree path. After review passes, advances review→terminal.
7. Cascade: Parent auto-cascades to terminal when all children reach terminal.
8. Merge: Squash-merge each worktree branch into local main. Run tests after each merge.

---

Visual Conventions

The output style uses unicode symbols for status:

Symbol	Meaning
✓	Terminal (complete)
◉	Work or review (active)
⊘	Blocked
○	Queue (pending)
—	Cancelled

Completion format:

✓ `d5c9c5ed` Design API schema → completed
✓ Unblocked: Implement data models (`2089ba1e`), Build REST endpoints (`26f2fa20`)

Narration uses the ↳ prefix for background operations — one line each, skim-friendly. Decisions and blockers use > blockquotes with a bold lead-in, only when user action is needed.

---

Retrospective

When items reach terminal after an implementation run — whether via advance_item, complete_tree, or auto-cascade — the orchestrator nudges:

↳ Implementation run complete. Consider running `/session-retrospective` to capture learnings.

The nudge appears at most once per run and is never auto-invoked.

---

Next Step

Tier 6: Self-Improving Workflow — close the loop by having Claude monitor its own MCP usage, log friction points as persistent observations, and self-correct discipline issues via auto-memory.