Orchestrator vs. Subagent Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• skills/fix/SKILL.md
• skills/review-plan/SKILL.md
• agents/discovery.md
• agents/epic-reviewer.md

Roughly utilizes a specialized architecture that separates pipeline coordination from task execution. In this model, the Orchestrator (the build or fix skill) manages the high-level workflow, state, and human gates, while Subagents are dispatched as isolated Claude processes to perform specific, narrow tasks like discovery, planning, implementation, or review.

This separation of concerns prevents context overflow—the primary failure mode for long AI sessions—by providing each subagent with a fresh, clean context window tailored to its immediate goal. The Orchestrator remains the stable core of the session, while subagents are ephemeral workers.

Sources: README.md:129-132, README.md:143-147, CLAUDE.md:13-16

Core Components

The architecture consists of two primary layers: the coordination layer (Skills) and the execution layer (Agents).

The Orchestrator (Skills)

The Orchestrator is a Roughly "Skill" (e.g., /roughly:build or /roughly:fix) that drives the pipeline sequentially through gated stages. It is responsible for:

• Intake and Parsing: Processing initial user arguments and epic files.
• Human Gating: Prompting the user for confirmation at every stage transition.
• State Management: Storing the current plan, task IDs, and verification results.
• Context Compaction: Systematically reducing context size at critical points to prevent window overflow.
• Subagent Dispatch: Invoking specific agents and passing them only the necessary context.

Sources: README.md:143-147, skills/fix/SKILL.md:11-13, skills/fix/SKILL.md:68-80

Subagents (Agents)

Subagents are specialized workers defined in the agents/ directory. Each subagent is optimized for a specific role and uses a model suited to that task (primarily Sonnet, with Opus reserved for complex epic reviews).

Component	Type	Responsibility
build/fix	Orchestrator	Coordinates the 8-stage pipeline; manages human gates.
discovery	Subagent	Researches codebase patterns and maps the "blast radius."
investigator	Subagent	Diagnoses bugs by tracing code paths.
review-plan	Subagent	Validates implementation plans against the actual codebase.
code-reviewer	Subagent	Checks implementation for bugs, security, and conventions.

Sources: README.md:183-195, CLAUDE.md:13-16, CLAUDE.md:60-65

Communication and Data Flow

The flow of information between the Orchestrator and Subagents is strictly controlled to maintain context hygiene. The Orchestrator prepares a "runtime copy" of prompts and instructions, inlining them into the subagent dispatch.

Pipeline Flow Diagram

The following diagram illustrates how the Orchestrator (Fix Skill) manages the lifecycle of multiple subagents during a bug-fix operation.

Data Exchange via Shared Files

While subagents are isolated, they maintain project awareness by reading canonical shared files. This prevents the Orchestrator from having to pass the entire project history into every subagent call.

1. CLAUDE.md: Project stack, build commands, and coding conventions.
2. .roughly/known-pitfalls.md: A runtime-growing catalog of project-specific gotchas.

Sources: README.md:148-154, agents/agent-preamble.md:18-21, CLAUDE.md:18-29

Task Execution Logic

In Stage 5 (Implementation), the Orchestrator performs a "subagent-per-task" execution loop. It reads the implementation plan and dispatches a fresh subagent for every discrete task (T1, T2, etc.).

Implementation Sequence Diagram

The sequence below detail how the Orchestrator manages the hand-off to an implementation subagent and performs the mandatory two-stage review.

Design Constraints

To ensure the architecture functions as intended, the project enforces several technical constraints:

• Conversational Inhibition: Coordinator skills (Orchestrators) must use disable-model-invocation: true. This forces Claude to execute the skill logic rather than answering the user conversationally.
• Model Reservation: All subagents use Sonnet by default for speed and efficiency, while Opus is strictly reserved for the epic-reviewer to handle complex, cross-story reasoning.
• Context Compaction: The Orchestrator must "compact context" before major stages (Stages 2, 5, 6, 7, and 8) to shed transient data and preserve the window for critical implementation work.
• Manual Sync: Since Claude Code lacks an include mechanism, the agent-preamble.md (which instructs agents to read shared files) must be manually synced across all agent definitions.

Sources: CLAUDE.md:46-55, CLAUDE.md:60-65, skills/fix/SKILL.md:68-70, agents/agent-preamble.md:5-13

Summary

The Orchestrator vs. Subagent architecture is the core mechanism Roughly uses to provide a stable, gated development experience. By centralizing logic in the Orchestrator and offloading specific work to isolated Subagents, the system maintains high technical accuracy and avoids the context degradation typical of long-running AI interactions. This structure ensures that every change is verified against project conventions and subject to human oversight at critical gates.

Sources: README.md:129-140, CLAUDE.md:60-65