Orchestrator Agent

The Orchestrator is the director of the pipeline. It never builds — it enforces gates, manages state, routes to the correct template, coordinates spec changes, and captures patterns. Every session starts and ends with the Orchestrator.

Activation

Start agent 0

On activation, the Orchestrator runs a two-path startup check before anything else.

Startup Protocol

On Start agent 0 (case-insensitive, whitespace-forgiving), the Orchestrator executes a fixed startup sequence — no HANDOFF.json or TASK-GRAPH.md is read first because they don't exist on a cold start. The protocol runs identically in every supported CLI and IDE.

1. 1
   Read config/context.json

   Checks _setup_complete. If false or file is absent, outputs the setup block and stops:

   ⛔ Setup required before starting the pipeline.
   Run:  bash SETUP.sh       (Linux / macOS)
         .\SETUP.ps1          (Windows)

2. 2
   Check registered projects

   If registered_projects has entries, displays a numbered resume menu and waits. The user picks a number to resume from last_active_agent, or types N for a new project. If empty, continues immediately.
3. 3
   Output status line

   ✅ Setup verified — no registered projects found. Starting new project kickoff.
4. 4
   Output ASCII banner + info table

   Displays the CodeSleuth ASCII art banner followed by the info table with live values from config/context.json: Pipeline stages, Context Backends (coordination, semantic search, agent memory, external registry), Design Contract status, and the full command reference.
5. 5
   Output build targets + welcome

   Displays the CodeSleuth Build Targets table (Web, Linux, Windows, macOS, Android, iOS) then the welcome message asking for: what the project does, the target platform, and the project directory (must be outside the agents directory).

Human Gate Protocol

The Orchestrator enforces all human gates. No agent advances automatically — every transition requires an explicit command from the human.

Spec Change Protocol

The !change command initiates a formal spec change review. No implementation changes happen until the human approves the blast radius report.

1. 1
   Human issues !change [description]

   Example: !change add a dark mode toggle to the settings page
2. 2
   Orchestrator emits Blast Radius Report

   Lists affected tasks (PENDING/IN-PROGRESS/DONE), files, contracts, and tests. Classifies scope as Small / Medium / Large. Warns about any DONE tasks that will become STALE.
3. 3
   Human approves or cancels

   !change-approve proceeds. !change-cancel discards the change and resumes normal pipeline.
4. 4
   CHANGE_LOG.md updated; affected tasks marked STALE

   The Builder detects STALE tasks and re-derives their implementation before execution.

Pattern Library Commands

The Orchestrator manages the Pattern Library across projects.

Living Documentation

The !docs command generates human-readable documentation from the current pipeline artifacts — useful for onboarding, handoffs, and project wikis.

Platform Routing

The Orchestrator detects the target platform from the project brief and surfaces the correct toolchain, signing, and distribution requirements. See Platform Capabilities for the full reference.

All Orchestrator Commands

Session Forking (!fork)

The !fork command creates two isolated copies of the current project, each on its own git branch, and runs two independent pipeline paths in parallel.

1. 1
   Human issues !fork [name]

   The Orchestrator calls session_fork.py, which creates two project copies with branches fork/[name]-A and fork/[name]-B.
2. 2
   Orchestrator spawns two parallel Agent calls

   Both branches execute concurrently in a single Claude Code response — each with its own isolated working directory and pipeline state.
3. 3
   Human reviews both branches and issues !merge [A|B]

   session_fork.py merges the winning branch back into main and cleans up the losing branch. The pipeline resumes on the merged codebase.

Pipeline Replay (!replay)

The !replay command restores the codebase to the git checkpoint immediately after a specific task completed, then resumes the Builder from that point.

!replay TASK-003

Internally, pipeline_replay.py:

1. Reads the git commit SHA stored in TASK-003's checkpoint entry in HANDOFF.json
2. Performs a git reset to that commit
3. Marks all tasks after TASK-003 as PENDING in TASK-GRAPH.md
4. Resumes Builder execution from TASK-004

Natural Language Gate Hints

The Orchestrator monitors user messages for intent phrases that indicate readiness to advance the pipeline. When detected, it surfaces the correct gate command without auto-advancing.

Token Budget (!budget)

The !budget command runs token_tracker.py and displays a real-time cost summary for the current session.

token_tracker.py runs automatically after every agent turn and appends a telemetry row to artifacts/telemetry/token_log.jsonl. Use !budget at any time to see the live summary.

Migration Sub-Commands

When migration_safety.py detects a HIGH severity schema change risk, it emits a Migration Risk Report and the pipeline pauses. Two sub-commands become available — they exist only while an active migration risk report is pending: