In music, the arranger takes a composition and creates the detailed arrangement for the orchestra: which instruments play when, what's simultaneous, what's sequential. The composer writes the music; the arranger makes it performable. Without the arrangement, the conductor has no score to follow, the copyist has no parts to extract, and the musicians have nothing to play.
The arranger skill fills the same gap in the orchestration pipeline. It takes a design document (the Dramaturg's composition) and produces a phased implementation plan — a detailed arrangement that the Conductor can coordinate, the Copyist can decompose into individual parts, and Musicians can execute autonomously. Every implementation decision is settled here: protocols verified, settings validated, integration points identified, phase structure optimized for parallel execution. The Conductor and downstream agents should never need to research protocols, configurations, or integration patterns — that work is done.
| Ad-hoc Conductor planning | Arranger planning | |
|---|---|---|
| Feasibility | Discovered during implementation — failures cascade | Front-loaded — verified before a line of code is written |
| Research | Training-data assumptions | Externally verified via Gemini, web search, code path tracing |
| Decisions | Made by the Conductor mid-execution, under time pressure | Made interactively with the user, backed by evidence |
| Phase structure | Sequential by default | Optimized for parallelization — preparation → dependent → integration |
| Integration | Cross-task issues discovered by Musicians, reported upstream | Integration surfaces identified during planning, made visible in checkpoints |
| User overrides | Invisible to downstream agents | Flagged in conductor checkpoints with full context |
| Context cost | Research consumed during implementation, competing with execution | Research consumed during planning, preserving implementation context |
Dramaturg → Arranger → Conductor → Musician
(vision) (plan) (coordination) (implementation)
Copyist creates individual parts from Arranger's score
Repetiteur re-plans mid-implementation if blockers arise
The Arranger and Repetiteur are siblings — both produce implementation plans in the same format for the same consumers. They differ in when they operate (before vs mid-implementation), how they interact (interactive with user vs autonomous with Conductor), and what they produce (full original plan vs remaining plan subset).
/arranger @path/to/design.md
Direct file reference — begins processing the specified design document.
/arranger
Auto-scan mode — scans docs/plans/designs/ for *-design.md files (excluding superseded/ and *-plan.md). If one design doc is found, auto-selects it. If multiple are found, prompts the user to choose.
The {feature-name} is derived from the design doc filename by stripping the date prefix and -design suffix (e.g., 2026-02-17-background-sync-design.md becomes background-sync). This name is used for the decisions directory path, journal filename, plan frontmatter, and downstream branch naming. Non-standard filenames fall back to the filename stem with a user confirmation prompt.
The Arranger follows 6 phases with loop-back points for user-driven deviations:
1. INGESTION & OVERVIEW
Read design doc, distill dramaturg journal, present summary
Wait for user go-ahead
│
↓
2. FEASIBILITY AUDIT
Verify protocols, trace code paths, validate settings
Read-only subagents + Gemini + web search
All findings journaled
│
↓
3. IMPLEMENTATION DISCUSSION
Research-backed decisions on every implementation question
Decision → Research → Discussion → Decision loops
User overrides journaled with mandatory strength
←── loops to 2 if structural deviation
│
↓
4. PHASE STRUCTURING
Arrange work into phases for parallel execution
Identify cross-task integration surfaces
Define danger files and conductor checkpoints
←── loops to 3 for implementation changes
←── loops to 2 for structural changes
│
↓
5. SECTION WRITING & REVIEW ◄── recommended session split point
Write plan sections one at a time
Interleaved: phase section → conductor checkpoint
User reviews each section
←── loops to 3 or 2 for deviations
│
↓
6. FINALIZATION & COMMIT (explicit user gate)
Verification subagent validates structure
Plan-index generated with line ranges
Commit implementation plan (locked)
Reads the design document, dispatches a subagent to distill the Dramaturg's decision journal (extracting VERIFIED, PARTIAL, UNRESEARCHED items), assesses completeness, and presents an overview. No autonomous work begins until the user acknowledges.
Front-loads all feasibility verification. Unimplemented protocols, platform services, and cross-component integration points are verified via Gemini queries, web search, and read-only code path tracing subagents. Findings are journaled before proceeding.
The core of the Arranger. Every implementation-level decision is settled through research-backed discussion loops. Settings are validated, approaches are compared, and the user makes the final call on each decision. User overrides are journaled with Strength: mandatory and flagged for downstream visibility.
Settled decisions are arranged into phases optimizing for parallel execution. Cross-task integration surfaces are identified for conductor checkpoints. Danger files (modified by multiple phases) are flagged. The Phase Summary is drafted.
Plan sections are written one at a time with user review of each. Each phase section passes the Copyist test — self-contained with all 7 expected components. Authority tags (<mandatory>, <core>, <guidance>, <context>) signal constraint weight to downstream consumers.
Gated behind explicit user confirmation. A verification subagent validates structural integrity (sentinel markers, Tier 2 elements, self-containment). The plan-index is generated after verification passes. The plan is committed and locked.
The Arranger consumes shared contracts from repertoire/:
| Contract | Usage |
|---|---|
output-format.md |
Plan structure, sentinel markers, self-containment rules (Phases 4-6) |
journal-conventions.md |
Journal format, entry categories, checkpoint triggers (all phases) |
verification-rules.md |
Mandatory verification categories, tool selection, truth hierarchy (Phases 2-3, 6) |
priority-chain.md |
Trade-off ordering for choosing between valid approaches (Phase 3) |
The Arranger uses threshold-based context monitoring. The user is present for judgment calls — no mandatory exits.
| Threshold | Action |
|---|---|
| 50% | Note context usage, prioritize remaining work by downstream impact |
| 65% | Recommend session split or /lethe compact to the user |
| 75% | Strongly recommend compaction or split before continuing |
| Phase 4/5 boundary | Always presented as recommended split point |
The decision journal preserves all state from Phases 1-4. A fresh session can resume at Phase 5 with full context for writing.
The Arranger reads runtime configuration from .orchestra_configs/arranger:
| Key | Values | Default | Description |
|---|---|---|---|
USE_GEMINI |
true / false |
true |
Enable/disable Gemini MCP for research and verification |
Per-key precedence across two locations:
<project-dir>/.orchestra_configs/arranger(most specific — wins per key)<project-dir>/../.orchestra_configs/arranger(parent — fallback per key)
Both files are read. For each key, the most-specific value wins. Keys not found in any file use defaults.
A Tier 2 hybrid document at docs/plans/designs/{feature}-plan.md. Contains:
- YAML frontmatter (title, date, type, feature, design-doc, tier)
- Plan-index with line ranges and verified timestamp
<sections>index and<section>tags- Overview and Phase Summary (for Conductor)
- Self-contained phase sections with authority tags (for Copyist)
- Conductor checkpoint sections with verification checklists
Flat markdown at docs/plans/designs/decisions/{feature-name}/arranger-journal.md. Records all decisions, research findings, user overrides, and phase structuring rationale. Persists for reference by the Repetiteur and Conductor.
bash skills/arranger/scripts/validate-plan.sh <plan-file>Validates structural integrity of an implementation plan: sentinel marker pairs, YAML frontmatter fields, <sections> index completeness, plan-index presence, section tag consistency, and orphaned tag detection.
arranger/
├── skill/
│ ├── SKILL.md # Skill definition (entry point)
│ ├── references/
│ │ ├── ingestion.md # Phase 1: Design doc reading, journal distillation
│ │ ├── feasibility-audit.md # Phase 2: Verification, code path tracing
│ │ ├── implementation-discussion.md # Phase 3: Decision loops, research
│ │ ├── phase-structuring.md # Phase 4: Parallelization, integration surfaces
│ │ ├── section-writing.md # Phase 5: Plan section authoring, review
│ │ └── finalization.md # Phase 6: Verification, index generation, commit
│ ├── examples/
│ │ ├── example-implementation-plan.md # Complete plan in Tier 2 format
│ │ └── example-arranger-journal.md # Journal with all entry types
│ └── scripts/
│ ├── arranger-config.py # Config resolver (Python primary)
│ ├── arranger-config.sh # Config resolver (shell fallback)
│ └── validate-plan.sh # Plan structural validation
└── docs/
├── README.md # Documentation directory guide
├── archive/ # Historical documents
│ └── repertoire-audit/ # Shared file audit artifacts
├── designs/ # Design specifications
├── working/ # Active work-in-progress
└── plans/ # Implementation plans
- Claude Code with skill/plugin support
- Gemini MCP — desired for research and verification. Configurable via
USE_GEMINI. Without Gemini, the Arranger operates in degraded mode (UNRESEARCHED marking on unverified items). - comms-link MCP — listed for future orchestration state management. The current Arranger workflow does not perform database operations.
- Context thresholds are advisory — the Arranger reads token usage from system messages and compares against the 50%/65%/75% thresholds. These are recommendations for the interactive user, not hard stops.
- Gemini dependency — without Gemini, the Arranger cannot independently verify protocols, platform specifics, or configuration values. Degraded mode marks these as UNRESEARCHED but does not prevent planning.
- Single design doc per session — each Arranger session processes one design document. Multiple features require multiple sessions.
- No code writing — the Arranger validates and decides but never writes production code. Mental implementation is read-only verification only.
- User presence required — the Arranger is interactive. Every phase involves user discussion and approval. It cannot operate autonomously like the Repetiteur.
Part of The Elevated Stage orchestration system. Design docs: stagecraft/docs/designs/2026-02-17-arranger-skill-design.md, stagecraft/docs/designs/2026-03-01-arranger-skill-build-design.md.