CAP-011: Orchestrator

Structured Data

Capability Metadata

FieldValue
IDCAP-011
Versionv1.7
DomainAgent Orchestration
StatusDocumented
RelatedCAP-009, CAP-012, CAP-013, CAP-014, CAP-015
Sourcesrc/orchestration/master-orchestrator.ts
Classification5-stage pipeline

Configuration Reference

HITL gates: human-in-the-loop confirmation thresholds

{
  "orchestrator": {
    "hitl_confidence_threshold": 0.75,
    "hitl_always_confirm": ["deploy", "delete"],
    "verbosity": "standard",
    "work_state_persist": true,
    "work_state_path": ".planning/STATE.md",
    "max_classification_retries": 2
  }
}

Verbosity levels: silent | standard | verbose | debug

YOLO mode: set hitl_confidence_threshold: 0 to suppress all confirmation prompts

Technical Specifications

Class: MasterOrchestrator

// Intent classification pipeline
type ClassificationStage =
  | "exact_match"
  | "lifecycle_filter"
  | "bayesian"
  | "semantic_fallback"
  | "confidence_resolution";

// Work state persisted between sessions
interface OrchestratorWorkState {
  session_id: string;
  current_phase: string | null;
  pending_command: string | null;
  confidence_history: number[];
  last_updated: string; // ISO 8601
}

class MasterOrchestrator {
  classify(intent: string): ClassificationResult;
  route(result: ClassificationResult): GSDCommand;
  persistState(state: OrchestratorWorkState): void;
  loadState(): OrchestratorWorkState;
}

Output: Routed GSD command with confidence score and reasoning trace

Overview

The GSD Master Orchestrator is the central nervous system of the GSD Skill Creator system. Where most GSD capabilities handle one specific concern — observing sessions, loading skills, managing token budgets — the Orchestrator coordinates all of them. It sits at the entry point of every user interaction and translates natural language intent into precise GSD commands.

When you type something like "let's verify phase 3" or "plan the next feature set," the Orchestrator runs your words through a five-stage intent classification pipeline. Each stage narrows the field of possible GSD commands until one emerges with enough confidence to act on. If the Orchestrator isn't confident enough — if your request is ambiguous — it asks you to clarify rather than guessing and doing the wrong thing.

Beyond routing, the Orchestrator maintains persistent work state across sessions. If you interrupted a planning workflow yesterday, the Orchestrator remembers where you left off today. It also enforces HITL (human-in-the-loop) confirmation gates for high-consequence operations — no deployments or deletions happen silently.

History

The Orchestrator was introduced in v1.7 as the flagship feature of the GSD Master Orchestration release — the single most architecturally significant update in the Foundation era. Before v1.7, routing user intent to GSD commands was ad hoc: Claude would interpret natural language through general LLM reasoning, with no systematic approach to ambiguity resolution, no confidence tracking, and no persistent work state.

The v1.7 design team drew from two disciplines: information retrieval (for the exact-match and Bayesian stages) and probabilistic reasoning (for confidence thresholds and fallback handling). The five-stage pipeline emerged from empirical testing — they found that exact matching caught ~60% of requests immediately, lifecycle filtering eliminated another ~20% of candidates, and only the remaining ~20% needed the more expensive Bayesian and semantic stages.

The persistent work state feature was added in response to a specific pain point: long-running documentation workflows where context resets were common. Without persistent state, the Orchestrator would lose track of the user's position in a multi-phase workflow every time the context window was cleared. With persistent state written to STATE.md, the workflow could survive any number of context resets.

Key Concepts

For Students & Teachers

Think of the Orchestrator like a really good hotel concierge. You walk up and say "I want to see something cultural tonight." A bad concierge would say "I don't understand, please be more specific." A mediocre concierge would hand you a map. A great concierge figures out that you like contemporary art, books you tickets to the exhibit that's closing this weekend, and arranges transport — all from that one vague sentence.

The Orchestrator is that great concierge. When you say "let's finish what we were working on," it checks your work state to find where you left off, figures out which GSD command picks up from there, and routes you directly to it — no manual lookup required.

The five classification stages are its toolkit for figuring out what you mean. First it checks for an exact match (you said exactly the command name). If that fails, it narrows by what phase you're in (you're in Phase 3, so plan-phase 3 is more likely than plan-phase 7). Then probabilistic reasoning. Then meaning-based similarity. If it still isn't sure enough, it asks you — because a wrong routing is worse than a clarifying question.

Usage Examples

Example 1: Natural language routing

# User says: "let's verify phase 3"
# Orchestrator classification trace:
Stage 1 (exact_match):      no direct command match
Stage 2 (lifecycle_filter): current phase = 3, narrows to phase-3 commands
Stage 3 (bayesian):         "verify" → verify-work (p=0.91)
Stage 4 (semantic):         skipped (confidence sufficient)
Stage 5 (resolution):       0.91 > threshold 0.75 → route
→ Routed to: /gsd:verify-work 3

Example 2: Ambiguity triggers clarification

# User says: "next"
# Orchestrator classification trace:
Stage 1 (exact_match):      no match
Stage 2 (lifecycle_filter): multiple candidates remain
Stage 3 (bayesian):         split between execute-phase/plan-phase (p=0.48/0.41)
Stage 4 (semantic):         neither exceeds threshold
Stage 5 (resolution):       max confidence 0.48 < threshold 0.75 → ask
→ Response: "Did you mean: (1) execute the next plan, (2) plan the next phase,
             or (3) continue from where we left off?"

Example 3: HITL gate on destructive operation

# User says: "delete phase 5 plans"
# Orchestrator detects "delete" in hitl_always_confirm list
→ HITL gate triggered regardless of confidence score
→ Response: "This will permanently delete Phase 5 plans. Confirm? (yes/no)"

Example 4: Work state persistence across context resets

# Session 1: user starts a planning workflow, context is cleared
# STATE.md now contains:
# orchestrator.pending_command: "plan-phase 4"
# orchestrator.current_phase: "3"

# Session 2: user says "continue"
# Orchestrator reads STATE.md, finds pending_command
→ Routed to: /gsd:plan-phase 4 (resumed from persistent work state)
Detailed Reference: 5-Stage Classification Pipeline

The classification pipeline runs sequentially, stopping as soon as a stage produces a result with sufficient confidence. Each stage is progressively more expensive — the pipeline is ordered to minimize compute cost for common cases.

Intent Input
     │
     ▼
┌─────────────────────────────────────┐
│  Stage 1: exact_match               │
│  Direct string lookup in command    │
│  registry. Catches ~60% of inputs.  │
│  Cost: O(1)                         │
└──────────────┬──────────────────────┘
               │ no match
               ▼
┌─────────────────────────────────────┐
│  Stage 2: lifecycle_filter          │
│  Narrows candidates by current GSD  │
│  phase. "plan" in Phase 3 → plan-   │
│  phase 3, not plan-phase 1.         │
│  Cost: O(phases)                    │
└──────────────┬──────────────────────┘
               │ multiple candidates remain
               ▼
┌─────────────────────────────────────┐
│  Stage 3: bayesian                  │
│  Probabilistic matching using word  │
│  frequency priors trained on        │
│  historical command usage.          │
│  Cost: O(commands × features)       │
└──────────────┬──────────────────────┘
               │ confidence < threshold
               ▼
┌─────────────────────────────────────┐
│  Stage 4: semantic_fallback         │
│  Embedding-based similarity search  │
│  for ambiguous or novel phrasings.  │
│  Cost: O(embedding_dim)             │
└──────────────┬──────────────────────┘
               │ result from any stage
               ▼
┌─────────────────────────────────────┐
│  Stage 5: confidence_resolution     │
│  Compare final confidence vs        │
│  hitl_confidence_threshold.         │
│  Above → route. Below → ask user.   │
└─────────────────────────────────────┘

Stage 1 — exact_match: The simplest stage. The input is lowercased, whitespace-normalized, and matched directly against the command registry. If the user typed "execute-phase" or "/gsd:execute-phase," this stage fires immediately.

Stage 2 — lifecycle_filter: Reads the current GSD phase from STATE.md and eliminates commands that are not relevant to the current lifecycle position. A user in Phase 3 execution is unlikely to want to plan Phase 7 — the filter prunes implausible candidates before the expensive probabilistic stages.

Stage 3 — bayesian: A Naive Bayes classifier trained on historical command invocations. Each word in the user's input is scored against a frequency table of words associated with each GSD command. The classifier returns a probability distribution over commands; the highest-scoring command is selected if its probability exceeds the confidence threshold.

Stage 4 — semantic_fallback: When Bayesian classification is insufficient (novel phrasing, low-frequency words, ambiguous input), semantic similarity search is used. The input is embedded using the same model as the command descriptions, and cosine similarity is computed against all candidate commands. This handles creative paraphrasing and metaphorical expressions that the Bayesian stage misses.

Stage 5 — confidence_resolution: The terminal stage. If the best result from any prior stage exceeds hitl_confidence_threshold, the command is routed immediately. If it falls below threshold, the Orchestrator presents the top candidates to the user and asks for confirmation. This is the safety valve that prevents confident wrong answers from executing destructive operations.

Developer Reference: Orchestrator Integration API

The MasterOrchestrator class exposes a clean integration surface for extending the routing system with new commands and configuration.

Adding a new command route

// Register a new command in the command registry
// (src/orchestration/command-registry.ts)
const registry = MasterOrchestrator.getRegistry();
registry.register({
  id: "my-custom-command",
  aliases: ["custom", "my command"],
  description: "Does something custom in the GSD workflow",
  lifecycle_phases: ["execution", "verification"],
  handler: async (args) => { /* ... */ }
});

// The Orchestrator automatically picks up registered commands
// in all five classification stages on next invocation.

Configuring confidence thresholds

// integration.json — per-command confidence override
{
  "orchestrator": {
    "hitl_confidence_threshold": 0.75,
    "command_overrides": {
      "remove-phase": { "hitl_confidence_threshold": 0.95 },
      "quick":        { "hitl_confidence_threshold": 0.60 }
    }
  }
}

Work state schema

// Work state is persisted to STATE.md under the orchestrator section
// Programmatic access:
const orch = new MasterOrchestrator(config);
const state = orch.loadState();

// state.pending_command — command awaiting execution after context reset
// state.current_phase   — phase detected from last STATE.md read
// state.confidence_history — last N confidence scores (for diagnostics)
// state.last_updated    — ISO 8601 timestamp of last state write

HITL gate extension

// Add custom HITL gate conditions
registry.addHITLRule({
  command_pattern: /^deploy.*/,
  condition: (ctx) => ctx.environment === "production",
  message: "Production deploy detected — confirm to proceed"
});
Advanced: Verbosity & HITL Configuration

Verbosity levels

The Orchestrator's verbosity setting controls how much classification reasoning is surfaced to the user during routing.

// silent   — no output during classification; only the routed command appears
// standard — announces which command was selected (default)
// verbose  — shows the winning stage and confidence score
// debug    — full pipeline trace: all stages, all candidates, all scores

// Example: verbose output
// → Routing to /gsd:verify-work 3 (bayesian stage, confidence=0.91)

// Example: debug output
// Stage 1 (exact_match): no match
// Stage 2 (lifecycle_filter): 12→4 candidates (phase=3)
// Stage 3 (bayesian): verify-work=0.91, execute-phase=0.06, plan-phase=0.03
// Stage 4 (semantic): skipped
// Stage 5 (resolution): 0.91 > 0.75 → routing
// → Routing to /gsd:verify-work 3

HITL gate configuration

// Three layers of HITL control:
{
  "orchestrator": {
    // 1. Global threshold: confidence below this → always ask
    "hitl_confidence_threshold": 0.75,

    // 2. Command allowlist: always require confirmation regardless of confidence
    "hitl_always_confirm": ["remove-phase", "delete", "deploy"],

    // 3. YOLO mode: set threshold to 0 to disable all HITL gates
    //    (hitl_always_confirm list is still respected in YOLO mode)
    "yolo_mode": false
  }
}

Tuning for YOLO mode vs interactive mode

YOLO mode (config.json "mode": "yolo") is the intended mode for experienced GSD users who know what they're doing and don't want confirmation prompts slowing down autonomous workflows. In YOLO mode, the Orchestrator still runs all five classification stages, but the confidence threshold for routing is set to zero — even low-confidence routes are executed without asking. The hitl_always_confirm list remains active in YOLO mode as a last-resort safety net.

Interactive mode (the default) is appropriate for new users, complex decisions, or when working in a shared or production environment. The default threshold of 0.75 means roughly 3 in 4 intents must be unambiguous before the Orchestrator acts without asking.

Related Capabilities