| Guide ID | A-3 |
|---|---|
| Audience | Developers, Power users |
| Prerequisites | GS-3: How It Works |
| Time | 20 minutes |
| Difficulty | Advanced |
GSD Orchestrator
GSD is powerful. It has 25+ commands spanning project initialization, phase planning, execution, verification, scope management, and milestone completion. For a developer in the middle of a milestone who cannot remember whether to run /gsd:discuss-phase, /gsd:plan-phase, or /gsd:execute-phase next, that power becomes friction. The GSD Orchestrator eliminates this friction by classifying what the user wants to do and routing them to the correct command automatically.
In the chipset architecture, the Orchestrator is Gary — the address router. Just as the original Amiga's Gary gate array decoded memory addresses and routed requests to the correct chip or expansion bus, the GSD Orchestrator decodes user intent and routes requests to the correct GSD command. It does not execute the command itself — it determines which command should execute, with what arguments, in what order.
The Problem
GSD follows a lifecycle: discuss, plan, execute, verify, complete. Each step has a dedicated command. But real projects are not linear. A developer might need to insert an urgent hotfix phase, resume work from a previous session, add a feature to the roadmap, or debug a failing verification. The cognitive overhead of remembering which command handles which situation scales linearly with the number of commands and the complexity of the project state.
The alternative — a single "do what I mean" command — was considered and rejected. A monolithic intent handler would need to handle every possible request in a single code path, making it brittle, hard to test, and impossible to extend. Instead, the Orchestrator uses a staged classification pipeline that progressively narrows the candidate set, from exact keyword matches (fast, cheap, deterministic) through probabilistic classification (slower, more expensive, but handles ambiguity).
5-Stage Classification Pipeline
When the user provides a natural language request, the Orchestrator processes it through five stages in order. Each stage either produces a confident result (short-circuiting the remaining stages) or passes to the next stage with accumulated context. The pipeline is designed so that the cheapest, most deterministic stages run first, and the most expensive, probabilistic stages run only when simpler methods fail.
Stage 1: Exact Match
Mechanism: Direct keyword-to-command mapping. The classifier maintains a lookup table of unambiguous phrases that map to exactly one GSD command. "plan the next phase" maps to /gsd:plan-phase. "what should I work on" maps to /gsd:progress. "ship it" maps to /gsd:complete-milestone (with additional lifecycle validation).
When it short-circuits: When the input matches a known phrase with no ambiguity. This is the fastest path — a dictionary lookup with no computation.
When it passes: When no exact match exists. "I need to work on the authentication stuff" does not match any exact phrase.
Design rationale: Exact matching handles the 80% case. Most user requests use conventional phrasing that maps directly to a GSD command. By handling these with a simple lookup, the Orchestrator avoids running expensive classification on requests that do not need it.
Stage 2: Lifecycle Filtering
Mechanism: The classifier reads the project's .planning/ directory to determine the current lifecycle state: which milestone is active, which phases have been discussed, planned, executed, and verified, and what the logical next step should be. It then eliminates GSD commands that are impossible or nonsensical in the current state. If phase 3 has not been planned yet, /gsd:execute-phase 3 is removed from the candidate set. If no milestone exists, /gsd:complete-milestone is removed.
When it short-circuits: When lifecycle filtering reduces the candidate set to exactly one command. If the user says "let's go" and the only valid next step is /gsd:execute-phase 2, no further classification is needed.
When it passes: When multiple commands remain valid. "I want to work on this" could mean execute, discuss, or plan depending on the phase state.
Design rationale: Lifecycle awareness is the Orchestrator's key advantage over simple keyword matching. A stateless classifier would route "let's plan" to /gsd:plan-phase even when the phase has already been planned. The lifecycle filter prevents this by eliminating commands that are inappropriate given the current project state. This stage reads ROADMAP.md, STATE.md, and the phase directory structure in .planning/phases/.
Stage 3: Bayesian Classification
Mechanism: When the candidate set still contains multiple commands after lifecycle filtering, the classifier applies probabilistic intent matching. It computes the posterior probability of each candidate command given the input text, using prior weights derived from command frequency (how often each command is used in GSD workflows) and likelihood weights derived from keyword co-occurrence (which words tend to appear in requests for each command type).
When it short-circuits: When one command's posterior probability exceeds the confidence threshold (typically 0.8). The classifier has high confidence in its classification.
When it passes: When no command exceeds the confidence threshold, or when two or more commands have similar probabilities. "I need to look at what we built" could plausibly mean /gsd:verify-work (review output) or /gsd:progress (check status).
Design rationale: Bayesian classification provides a principled framework for handling ambiguity. Rather than hard-coding rules for every edge case, the classifier uses probability distributions that can be updated as usage patterns emerge. The prior weights mean that commonly-used commands get a natural advantage in ambiguous situations, which matches user expectations.
Stage 4: Semantic Fallback
Mechanism: When Bayesian classification fails to produce a confident result, the classifier falls back to embedding-based similarity. It computes the semantic similarity between the user's input and the description of each remaining candidate command using local embeddings (or heuristic text similarity when embeddings are unavailable). This handles cases where the user's phrasing is far from any known keyword pattern but semantically close to a command's purpose.
When it short-circuits: When one command's semantic similarity is significantly higher than all others (a clear winner in embedding space).
When it passes: When semantic similarity does not produce a clear winner. The input is genuinely ambiguous.
Design rationale: Embeddings capture meaning that keywords miss. "Let's get this over the finish line" has no keyword overlap with /gsd:complete-milestone, but it is semantically similar to the concept of milestone completion. The semantic fallback ensures the Orchestrator can handle creative, colloquial, or domain-specific phrasing that would defeat keyword-based and Bayesian approaches. However, embeddings are computationally expensive, which is why this stage runs only after cheaper methods have been exhausted.
Stage 5: Confidence Resolution
Mechanism: If all four previous stages fail to produce a confident classification, the Orchestrator does not guess. It presents the top candidates (typically 2-3 commands) to the user and asks for clarification. The presentation includes a brief explanation of why each candidate was considered and what it would do.
Design rationale: A wrong routing is worse than a clarifying question. If the Orchestrator routes "clean up the auth code" to /gsd:remove-phase instead of /gsd:execute-phase, the user might lose planned work. The confidence resolution stage embodies the principle that systems should ask when uncertain rather than act when wrong. This is particularly important for destructive commands like /gsd:complete-milestone (which archives and tags a release) that have human-in-the-loop gates regardless of confidence level.
Dynamic Discovery
The Orchestrator does not maintain a hardcoded list of available commands. At initialization, it scans the filesystem to build a live inventory of everything it can route to: GSD commands (the /gsd: slash commands in .claude/commands/gsd/), agents (the .md agent definitions in .claude/agents/), teams (multi-agent configurations in .claude/teams/), and skills. This discovery process runs against the actual filesystem, so the Orchestrator adapts automatically to whichever version of GSD is installed and whatever custom agents or teams the user has created.
Discovery can be invoked explicitly via skill-creator orchestrator discover (alias: orch disc), which returns a structured inventory of all available routing targets. This is the Orchestrator's map of the territory.
Source: src/orchestrator/discovery/ (filesystem scanning and inventory building)
Lifecycle State Awareness
The Orchestrator reads the .planning/ directory to understand exactly where the project stands in the GSD lifecycle. It inspects ROADMAP.md for phase structure and status, STATE.md for session memory and blockers, and the phases/ subdirectories for plan and summary files that indicate completion state.
This state awareness feeds directly into the lifecycle filtering stage (Stage 2) and enables lifecycle suggestions — proactive recommendations about what the user should do next. If phase 2 has been executed but not verified, the Orchestrator suggests /gsd:verify-work 2. If all phases in a milestone are verified, it suggests /gsd:complete-milestone. If the user is starting fresh with no .planning/ directory, it suggests /gsd:new-project.
Lifecycle state can be queried directly via skill-creator orchestrator state (alias: orch st), and suggestions via skill-creator orchestrator lifecycle (alias: orch lc).
Source: src/orchestrator/state/ (project state reading), src/orchestrator/lifecycle/ (lifecycle coordination and suggestions)
Orchestrator as Agent
The GSD Orchestrator itself is defined as a Claude Code agent at .claude/agents/gsd-orchestrator.md. This means it can be spawned as a subagent by other GSD commands, can have its own tool permissions, model assignment, and skill preloads, and participates in the same agent composition framework described in A-4: Agent Composition.
The Orchestrator agent configuration specifies which tools it can access (filesystem reading for discovery and state, but not writing), which model it runs on, and which skills are preloaded into its context. It also integrates with the verbosity system, supporting three levels: minimal (routes silently), standard (shows classification and asks for confirmation), and verbose (explains reasoning, shows alternatives, details lifecycle state).
Source: src/orchestrator/verbosity/ (output control), src/orchestrator/gates/ (human-in-the-loop approval gates), src/orchestrator/extension/ (gsd-skill-creator detection)
Integration with skill-creator
The Orchestrator detects whether gsd-skill-creator is installed and adapts its behavior accordingly. When skill-creator is present, the Orchestrator can factor active skills, work bundles, and role constraints into its routing decisions. If a "reviewer" role is active (read-only, no code modifications), the Orchestrator will not route to /gsd:execute-phase. If a "frontend" work bundle is active, the Orchestrator tailors lifecycle suggestions to frontend-relevant phases.
The Orchestrator also integrates with the work state persistence system (v1.7). When a session ends mid-workflow, the Orchestrator's current state is saved via skill-creator work-state save. In the next session, skill-creator work-state load restores the context, and the Orchestrator factors this saved state into its lifecycle suggestions alongside the .planning/ directory state.
Completing a GSD command through the Orchestrator can emit inter-skill events that trigger downstream skill activations. The Orchestrator coordinates these event chains as part of its routing logic, ensuring that post-command workflows (like regenerating planning documentation after a phase completes) execute in the correct order.
What's Next
- A-1: Chipset Architecture — Gary's role in the coprocessor model
- UG-1: Command Reference — Complete reference for all GSD commands
- GS-3: How It Works — The six-step workflow that the Orchestrator navigates