The Orchestrator - Schaltwerk

The orchestrator is a special terminal that runs directly in your primary repository branch (often main, but it can be a dedicated feature hub). It doesn’t create a worktree; instead it gives you a control room for coordinating agents and managing complex workflows.

Any commands you run in the orchestrator’s terminals modify that branch immediately. Use isolated sessions when you want a disposable sandbox.

What Makes the Orchestrator Special?

Primary Branch Access

Works directly on your primary branch (main or a feature hub)No isolated worktree - full repo access

Planning Hub

Create and manage multiple specsDraft complex features before execution

Agent Coordination

Launch multiple agents in parallelMonitor progress across sessions

MCP Automation

Programmatic session managementExternal tool integration via REST API

Core Capabilities

1. Plan and Create Specs

Draft multiple specs for complex features:

Open orchestrator

Press ⌘1 to switch to orchestrator

Create specs

Use ⌘⇧N to create planning documents:

Feature requirements
Implementation approach
Acceptance criteria
Dependencies

Refine specs

Press ⌘⇧R on a spec to enter Refine Mode:

Switches to the orchestrator session
Opens the spec in the right panel for live preview
Inserts spec reference in agent terminal (requires MCP enabled)
Agent can read and update the spec iteratively

Add context, constraints, examples before launching agents

Organize specs

Group related specs togetherPlan parallel work streams

Refine Mode: Iterative Spec Development

Requires MCP: The orchestrator agent must be able to call schaltwerk_current_spec_update to edit specs. Enable MCP in Settings → Agent Configuration for your agent (Claude Code, Codex, OpenCode, or Gemini).

Refine Mode enables iterative spec development by switching to the orchestrator while keeping the spec visible for live updates:

Enter Refine Mode

Select a spec in the sidebar and press ⌘⇧RWhat happens:

Session switches to the orchestrator
Spec opens in the right panel (live preview)
Agent terminal receives spec reference (e.g., “Refine spec: my-feature (abc123)”)

Iterative refinement

The agent can now:

Read the current spec content via MCP
Ask clarifying questions
Update the spec with schaltwerk_current_spec_update
Preview changes in real-time on the right panel

You watch the spec evolve in the right panel while collaborating with the agent in the terminal.

Exit Refine Mode

Press Esc or switch to another session when doneThe refined spec is ready to start with ⌘N

Without MCP enabled, the agent terminal receives the spec reference text but cannot read or update the spec. The agent will need manual copy-paste of spec content.

2. Launch Agents in Parallel

Start multiple agents working on different specs simultaneously:

Manual Launch
MCP Automation

Select first spec
Press ⌘N to start session
Select next spec
Press ⌘N to start another session
Switch between sessions with ⌘1-9

// Via MCP REST API or Claude
const specs = [
  { name: 'auth-login', prompt: 'Implement login...' },
  { name: 'auth-register', prompt: 'Implement registration...' },
  { name: 'auth-reset', prompt: 'Implement password reset...' }
];

for (const spec of specs) {
  await createSession(spec.name, spec.prompt);
}

3. Review Agent Work

Check diffs, run tests, provide feedback:

Inspect Changes

Switch to session with ⌘2-9
View diffs in right panel
Check git status in bottom terminal
Review file changes

Run Tests

Focus bottom terminal with ⌘/
Execute test suite
Or use Run Mode with ⌘E
Verify all tests pass

Provide Feedback

Focus agent terminal with ⌘T
Send instructions or corrections
Agent receives feedback and continues

Mark Reviewed

Press ⌘R when satisfied
Session moves to Reviewed filter
Ready for merge

4. Integrate Changes

Merge approved sessions back to main branch:

Filter reviewed sessions

Click Reviewed tab to see approved sessions

Verify each session

Tests pass
No merge conflicts
Changes are correct

Merge to main

From session header actions:

Create GitHub PR
Merge directly
Cherry-pick specific commits

Clean up

After successful merge, press ⌘D to cancel session

5. Coordinate Workflows

Chain tasks together for complex automation:

Orchestrator receives: "Build complete authentication system"

1. Break into specs:
   - Spec 1: User registration with email validation
   - Spec 2: Login with JWT tokens
   - Spec 3: Password reset via email
   - Spec 4: Session management

2. Launch agents on each spec in parallel

3. Monitor progress:
   - Check which sessions are complete
   - Identify any blocked sessions
   - Provide additional context if needed

4. Review completed work:
   - Run integration tests
   - Check for conflicts between sessions
   - Verify all acceptance criteria met

5. Integrate in order:
   - Merge dependencies first (e.g., session management)
   - Then merge features (registration, login, reset)
   - Run full test suite after each merge

Orchestrator receives: "Fix all failing tests"

1. Identify failing tests:
   - Run test suite
   - Parse output for failures
   - Group by module/component

2. Create spec for each failure:
   - Spec includes test output
   - Relevant file paths
   - Error messages

3. Assign agents to fix in parallel

4. Collect results:
   - Monitor which fixes are reviewed
   - Run tests to verify fixes
   - Merge passing fixes

5. Iterate if needed:
   - Re-run tests
   - Create new specs for remaining failures

Automated Workflows via MCP

The orchestrator supports MCP (Model Context Protocol), enabling programmatic session management.

What MCP Enables

Session Creation

External tools create sessions via REST APINo manual UI interaction needed

Status Monitoring

Query session states programmaticallyTrack completion and review status

Workflow Automation

Chain operations togetherBuild complex multi-agent pipelines

Customization Options

Claude Slash Commands

Create custom commands that execute orchestrator actions:

Documentation for custom slash commands coming soon. This feature enables you to define shortcuts for common orchestrator workflows.

Action Buttons (F1-F6)

Configure function keys with prompts for common workflows:

Action button configuration coming soon. Map F1-F6 to frequently-used orchestrator commands.

Prompt Templates

Save and reuse complex orchestration patterns:

# Feature: [FEATURE_NAME]

## Goal
[Describe the feature]

## Breakdown
Create the following sessions:
1. [Component 1] - [Description]
2. [Component 2] - [Description]
3. [Component 3] - [Description]

## Dependencies
- [Component 1] must complete before [Component 2]
- All components use [shared dependency]

## Testing Strategy
- Integration tests after each component
- Full E2E tests after all merges

# Bug Triage: [ISSUE_ID]

## Problem
[Describe the bug]

## Investigation
1. Reproduce the issue
2. Identify root cause
3. Assess impact

## Fix Strategy
- Create specs for:
  1. [Fix 1]
  2. [Fix 2]
- Run tests after each fix
- Verify no regressions

Terminal Layout

The orchestrator has the same dual-terminal layout as regular sessions:

Top Terminal
Bottom Terminal

Agent TerminalRun AI assistants that can:

Create and manage specs
Launch sessions programmatically
Monitor session progress
Coordinate multi-agent workflows

Best Practices

Plan Before Launching

Draft all specs first
Identify dependencies
Determine execution order
Consider resource constraints (don’t run 20 agents at once)

Name Sessions Clearly

Use descriptive names that indicate:

What the session does
Which component it affects
Relationship to other sessions

Examples:

auth-login-implementation
api-user-endpoints
fix-email-validation-bug

Monitor Resource Usage

Each session creates 3 OS processes:

Shell process
Agent process
Terminal backend

Don’t run too many sessions simultaneously

Review Frequently

Don’t let reviewed sessions pile up:

Review daily if possible
Merge or provide feedback
Keep the pipeline moving

Document Workflows

Create prompt templates for:

Common feature patterns
Bug fix procedures
Review checklists
Integration strategies

Common Orchestrator Workflows

Feature Development

Receive feature request

User describes desired functionality

Break into components

Create specs for each component:

Backend API
Frontend UI
Database migrations
Tests

Launch agents

Start sessions for each componentAgents work in parallel

Monitor progress

Check which sessions are completeProvide feedback as needed

Integrate

Merge components in dependency orderRun integration tests

Final review

Test complete featureVerify all requirements met

Bug Fixing

Identify bugs

Run test suite or review issue tracker

Create bug specs

One spec per bug with:

Reproduction steps
Expected behavior
Error messages
Related files

Assign agents

Start sessions for each bugAgents investigate and fix

Verify fixes

Run tests for each fixCheck for regressions

Merge fixes

Integrate passing fixesRe-run full test suite

Refactoring

Identify refactoring needs

Code smell, performance issue, or architectural change

Plan refactoring

Break into safe, incremental steps:

Extract methods
Rename variables
Restructure modules
Update tests

Create specs for each step

Small, focused changesEach step maintains functionality

Execute incrementally

Complete one step at a timeVerify tests pass after each

Final verification

Run full test suiteCheck performance metrics

Tips and Tricks

Use Filters Effectively

Specs: Planning queue
Running: Active work
Reviewed: Ready for merge

Switch between views with ⌘←/→

Leverage Keyboard Shortcuts

⌘1 - Back to orchestrator
⌘2-9 - Jump to sessions
⌘↑/↓ - Cycle through sessions
⌘⇧R - Refine spec in orchestrator
⌘N - Start selected spec

Keep Main Clean

Orchestrator works on main branchDon’t make direct changes - use sessions

Document Decisions

Use orchestrator’s bottom terminal to:

Record design decisions
Document workflow patterns
Save useful commands

Limitations

Be aware of these orchestrator limitations:

No Worktree - Orchestrator runs on main branch, not in isolation
Resource Usage - Each session consumes system resources (3 processes)
Concurrent Agents - Don’t run too many agents simultaneously
Manual Merge - Merging sessions still requires manual review and approval

Next Steps

MCP Server Setup

Set up programmatic session management

Using Schaltwerk

Learn the day-to-day workflow

​What Makes the Orchestrator Special?

Primary Branch Access

Planning Hub

Agent Coordination

MCP Automation

​Core Capabilities

​1. Plan and Create Specs

​Refine Mode: Iterative Spec Development

​2. Launch Agents in Parallel

​3. Review Agent Work

​4. Integrate Changes

​5. Coordinate Workflows

​Automated Workflows via MCP

​What MCP Enables

Session Creation

Status Monitoring

Workflow Automation

​Customization Options

​Claude Slash Commands

​Action Buttons (F1-F6)

​Prompt Templates

​Terminal Layout

​Best Practices

​Common Orchestrator Workflows

​Feature Development

​Bug Fixing

​Refactoring

​Tips and Tricks

Use Filters Effectively

Leverage Keyboard Shortcuts

Keep Main Clean

Document Decisions

​Limitations

​Next Steps

MCP Server Setup

Using Schaltwerk

What Makes the Orchestrator Special?

Core Capabilities

1. Plan and Create Specs

Refine Mode: Iterative Spec Development

2. Launch Agents in Parallel

3. Review Agent Work

4. Integrate Changes

5. Coordinate Workflows

Automated Workflows via MCP

What MCP Enables

Customization Options

Claude Slash Commands

Action Buttons (F1-F6)

Prompt Templates

Terminal Layout

Best Practices

Common Orchestrator Workflows

Feature Development

Bug Fixing

Refactoring

Tips and Tricks

Limitations

Next Steps