---
name: orchestrator-playbook
description: "orchestratorX complete workflow handbook. Contains planning dialogue, Mode A/B/C workflows, core iteration loop, Hybrid Tree routing, requirement change handling, Auto-Routing, Start Rule."
---

# orchestrator Playbook

> **Positioning**: orchestratorX's complete workflow handbook. Contains main workflow logic and on-demand trigger modules.

## Module Index

| # | Module | Trigger | File Path |
|---|--------|---------|-----------|
| 1 | Environment Init + MCP Degradation | First entry to xwhole/xlocal/xunit | `modules/01-environment-init.md` |
| 2 | Bus Payload Validation | Cross-agent handoff (coderX <-> evaluatorX) | `modules/02-bus-payload.md` |
| 3 | Post-Evaluation Document Update | After evaluatorX returns | `modules/03-post-evaluation.md` |
| 5 | Parallel Setup | `/xwhole -parallel` triggered | `modules/05-parallel-setup.md` |
| 6 | Task Coordination | Module 05 completed, continuous runtime | `modules/06-task-coordination.md` |
| 8 | Discovery & Solution Design | xwhole only: Phase 1 (exploration and design consensus) | `modules/08-requirements-discovery.md` |
| 9 | Workflow State Tracking | All checkpoints during workflow execution | `modules/09-workflow-state.md` |

**Note**: Module 00 (Auto-Routing) has been superseded by `.claude/skills/auto-routing/SKILL.md` — the consolidated routing specification for the main Claude agent. orchestratorX always receives an explicit mode parameter (`Mode: xwhole/xlocal/xunit`) and does NOT perform mode selection itself.

**Loading rule (Optimized)**: 
- **Session Memory Cache**: After first Read, cache module content in session memory (`module_cache`). Subsequent accesses read from cache instead of disk.
- **Cache Key**: Use module file path as cache key.
- **Invalidation**: Cache persists for entire session. Clear only on new session start.
- **Never load all modules at once** — still applies, but cached modules are instant access.

---

## Parameter Parsing

> **orchestratorX responsibility**: Parse parameters from `$ARGUMENTS` before workflow execution.

### Supported Parameters

| Parameter | Format | Scope | Default | Description |
|-----------|--------|-------|---------|-------------|
| `-N` | `-N [number]` | xwhole, xlocal | `2` | Maximum evaluation iteration rounds per Child |
| `-box` | `-box [name]` | xwhole | N/A | Sandbox branch name for isolated execution |
| `-parallel` | `-parallel` | xwhole | off | Enable Agent Teams parallel execution within Mode A |
| `-team` | `-team [name]` | xwhole (with `-parallel`) | `workflow-{timestamp}` | Agent Team name for parallel workflow |

### Parsing Rules

**Step 1: Extract parameters from $ARGUMENTS**

Extract sequentially from `$ARGUMENTS`: command name → optional flags → requirement text.

| Param | Match Rule | Default | Description |
|-------|-----------|---------|-------------|
| mode | Starts with `/xwhole`, `/xlocal`, `/xunit`, `/xprompt` | — | Command determines mode |
| `-N` | Positive integer (1-10) after `-N` | `2` | Max evaluation iterations per Child |
| `-box` | Branch name (alphanumeric, hyphens, underscores) after `-box` | skip | Sandbox branch name |
| `-parallel` | Presence flag | off | Agent Teams parallel mode |
| `-team` | Name after `-team` | `workflow-{timestamp}` | Team name for parallel mode |
| requirement | Remaining text after removing above params | — | User requirement |

**Examples**:

```
/xwhole -N 5 -box feature-test Add user authentication
  → mode=xwhole, N=5, box="feature-test", parallel=false, requirement="Add user authentication"

/xwhole -parallel -team my-team Implement auth module
  → mode=xwhole, N=2, parallel=true, team="my-team", requirement="Implement auth module"
```

**Step 2: Validate parameters**

- `-N`: Must be positive integer (1-10). If invalid or missing, use default `2`.
- `-box`: Must be valid branch name (alphanumeric, hyphens, underscores). If empty, skip sandbox.
- `-parallel`: No value needed. Presence flag enables Agent Teams mode within xwhole.

**Step 3: Remember parsed parameters**

Store extracted results as session working memory (mode, iteration_limit, sandbox_branch, team_name, is_parallel, requirement). Reference directly in subsequent steps, no re-parsing.

### Usage in Workflow

**Iteration Limit (`-N`)**:
- Applied in Core Iteration Loop (Step 6 of xwhole, Step 5 of xlocal)
- Each Child gets max N rounds of coderX ↔ evaluatorX iteration
- If limit reached and still Needs Fix: stop iteration, report to human

**Sandbox Branch (`-box`)**:
- **Conditional Creation**: Only execute sandbox operations when `-box` is explicitly provided
  - Without `-box`: Work directly on current branch, no stash/checkout needed
  - With `-box`: Execute full sandbox lifecycle (below)
- **Sandbox Lifecycle**:
  - Before workflow: `git stash` → record original branch → `git checkout -b {sandbox-branch}` from main
  - After workflow: switch back → attempt fast merge (see below) → restore stash
- **Fast Merge Strategy** (Optimized):
  1. Try `git merge --ff-only {sandbox-branch}` (fastest, no extra commit)
  2. If ff-only fails (diverged), try `git merge --squash {sandbox-branch}` (single commit)
  3. If squash fails, fallback to `git merge --no-commit --no-ff {sandbox-branch}`
  4. If merge conflicts: pause, notify user, wait for manual resolution
- **Incremental Stash** (Optimized):
  - Only stash files actually modified: `git stash push -m "workflowX" -- file1 file2 ...`
  - On restore: `git stash pop` (auto-resolves if no conflicts)

---

## Workflow Modes

### Mode A: whole workflow
- Scope: Large-scale, high-impact, requiring full planning-evaluation cycle.
- **Worktree isolation (auto)**: coderX and evaluatorX are spawned with `isolation="worktree"`. Each agent works in an independent directory; branches merge back after completion.
- **Sandbox (`-box`)**: When specified, creates a physically isolated sandbox branch. Before: stash, record original branch, create sandbox branch. After: merge worktree branches into sandbox, switch back, `--no-commit --no-ff` merge sandbox into original, restore stash.
- **Entry**: Environment init (module 01) -> **Phase 1: Discovery & Solution Design** (module 08: explore, challenge, propose solutions) -> user confirms -> **Phase 2: Document Generation** (Hybrid Tree creation) -> **Core Iteration Loop**
- Iteration limit: Each Child defaults to max 2 rounds (`-N` overrides). If limit reached and still failing, stop and report to human.
- abstracterX is only invoked when user explicitly requests summarization.

#### Mode A-parallel (`-parallel`)
When `-parallel` is specified, Mode A uses Agent Teams for parallel execution instead of sequential sub-agent dispatch:

- **Prerequisites**: Agent Teams enabled (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`), Claude Code v2.1.32+
- **Entry**: Same Planning Phase as Mode A -> Parallel setup (module 05) -> Task coordination (module 06)
- **Core features**:
  - Uses Agent Teams instead of sequential sub-agent mode
  - Multiple coder-teammate + evaluator-teammate working in parallel
  - Each teammate isolated in own worktree (zero file conflicts)
  - Dynamic task scheduling based on dependency graph
  - Real-time requirement change handling
- **Fallback**: If Agent Teams unavailable, fall back to sequential Mode A sub-agent mode
- **Teammate role definitions**:
  - `.claude/agents/coder-teammate.md`: Code implementation teammate
  - `.claude/agents/evaluator-teammate.md`: Code evaluation teammate
- **Detailed flow**: See Module 05 and Module 06

### Mode B: local workflow
- Scope: Requirements relatively clear, limited to a local part of the project.
- **Entry**: Environment init (module 01, **MCP probe must precede everything**) -> **PRD detection** -> Core Iteration Loop.
- **PRD detection (priority order)**:
  1. `.hybrid/[feature]/` directory exists with Hybrid Tree → use directly
  2. $ARGUMENTS contains valid file path → read PRD, wrap into Hybrid Tree
  3. No PRD → auto-generate minimal Hybrid Tree (scan code → build index → decompose AC → write Parent + Child)
- **evaluatorX evaluation criteria**: Always PRD-based (evaluate against Child Section 7 AC). After reading Evaluation Result, orchestratorX assembles Fix Instructions into a fix prompt for coderX.

### Mode C: unit workflow
- Scope: Minimal tasks: single fix, single file, minimal change.
- **Entry**: coderX executes minimal change -> report to user. evaluatorX only invoked when explicitly requested.
- **coderX lightweight mode**: Only loads `karpathy-guidelines`, does not load `codex-spec-implementation`, no Bus Payload needed.

---

## Discovery & Solution Design (Mode A)

> Mode A entry: Environment init (module 01) -> **Phase 1: Discovery & Solution Design** (module 08) -> user confirms -> **Phase 2: Document Generation** (Hybrid Tree creation) -> Core Iteration Loop

### Two-Phase Workflow

**Phase 1: Discovery & Solution Design** (module 08) — thinking and design stage:
- Autonomous exploration, gap identification, risk surfacing
- Propose 2-3 solutions with trade-offs
- Multi-turn refinement with user
- **Output**: Design consensus (no Hybrid Tree yet)
- **Exit signal**: "等待你确认方案后，我会生成 Hybrid Tree 并启动开发流程。"

**Phase 2: Document Generation** — triggered by user confirmation:
- **Trigger keywords**: "确认" / "开始实现" / "生成文档" / "开始开发" / "start implementation"
- Generate Hybrid Tree (Parent + Children) based on Phase 1 consensus
- Write to `.hybrid/[feature]/` directory
- Enter Core Iteration Loop

**Core behaviors (Phase 1)**:
- Ask pointed questions, then **autonomously search** the codebase for answers
- Present findings as "here's what I found" rather than "can you tell me"
- Challenge assumptions based on **actual code evidence**
- Propose 2-3 solutions with trade-offs derived from exploration
- Iterate with user to refine approach

### Discovery Turn Structure

Each turn follows this flow:

1. **Confirm Understanding**: Restate user's latest input (1-2 sentences)
2. **Identify Critical Gaps**: Analyze across 6 dimensions (Target User, Functional Scope, Technical Constraints, Boundary Conditions, Acceptance Criteria, NFRs) — prioritize gaps that impact design decisions
3. **Autonomous Exploration**: 
   - Search codebase (Glob, Grep, rg) for related files, patterns, constraints
   - Build File Index in session memory (accumulates → written to Hybrid Tree §8.1)
   - Extract insights: existing patterns, constraints, edge cases, conflicts
4. **Present Findings & Challenge**: Surface discoveries and challenge the requirement across 6 categories (Contradictions, Edge Cases, Technical Risks, Hidden Assumptions, Cross-Module Conflicts, Missing NFRs)
5. **Propose Solutions**: When ready, present 2-3 concrete approaches with trade-offs based on codebase context

### Dialogue Rules

- **One topic per turn** — address the most critical gap/risk first
- **Explore before asking** — always search code before presenting questions
- **Build on previous turns** — reference earlier findings, accumulate context
- **Evidence over speculation** — cite file paths, line ranges, specific patterns
- **Propose solutions, not just problems** — every challenge includes suggested approach
- **Respect user decisions** — record acknowledged risks and move on

Full specification: `modules/08-requirements-discovery.md`

### Phase Transition

**Phase 1 exit criteria:**
- User signals confirmation with keywords: "确认" / "开始实现" / "生成文档" / "开始开发" / "start implementation"
- Output design consensus summary, then **wait for explicit confirmation before Phase 2**

**Phase 1 exit signal template:**
```
方案设计完成。以下是推荐方案：

[Brief design consensus summary]

等待你确认方案后，我会生成 Hybrid Tree 并启动开发流程。
```

**Phase 2 entry:**
- After user confirms, generate Hybrid Tree with all discoveries written to appropriate sections
- Proceed to Core Iteration Loop

### Knowledge Graph Writeback

When the user triggers Summary:

1. Read confirmed facts from `mcp/server-memory` for the current session, generate a structured knowledge graph
2. Clean up: retain only user-confirmed facts, delete speculation and pending items
3. Serialize and write to Parent Section 8.4
4. If old snapshot exists, overwrite with timestamp preserved, do not add duplicates

### Findings → Hybrid Tree Mapping

Write confirmed findings into appropriate sections during Hybrid Tree creation:

| Finding Type | Target Section |
|-------------|---------------|
| Confirmed scope | Parent §1 Project Overview |
| Technical constraints | Parent §3 Technical Constraints |
| Edge cases | Child §7 AC |
| NFRs (security, perf) | Parent §4 NFR |
| Risk mitigations | Child §7 AC |
| Accepted risks | Parent §4 NFR |
| Cross-module dependencies | Parent §8.3 Dependencies |
| File index | Parent §8.1 (shared), Child §8.1 (private) |
| Knowledge insights | Parent §8.2 Knowledge Graph |

### Hybrid Tree Creation

**All planning outputs must use the Hybrid Tree structure.** Regardless of requirement size, generate one Parent + at least one Child.

**Design principles**:
1. **Parent-Child separation of responsibility**: Parent is the routing layer (global spec, routing table, global index, knowledge graph). Child is the requirement layer (branch AC, branch index).
2. **MECE**: Children scopes are mutually exclusive and collectively exhaustive, no gaps or overlaps.
3. **High cohesion, low coupling**: Each Child contains tightly related requirements. Cross-Child dependencies minimized and recorded in Parent 8.3.
4. **Prevent over-splitting**: Each Child must have independent scope justifying its existence.
5. **Temporal and causal continuity**: Sequential dependencies reflected in Child ordering and dependency annotations.

**Creation flow**:
1. Create directory `.hybrid/[feature-name]/`
2. Create Parent hybrid: fill Sections 0-6, Section 7 routing table, 8.1 shared files, 8.2 knowledge graph, 8.3 cross-branch dependencies
3. Create Child hybrids: one per sub-module, fill Section 7 AC, 8.1 private files
4. Pass Parent path to orchestratorX, orchestratorX routes to each Child for development

**Template**: Strictly follow `hybrid-template.md`. Section numbers and physical order must not change (adapted for Token caching: static sections first, incremental middle, dynamic last).

### Quality Gates

- Must not lock specific business rules without user confirmation
- Do not output low-level code snippets or overly detailed API designs during discovery
- Maintain exploratory dialogue mode outside Summary stage
- Focus on product context, high-level boundaries, and executable acceptance criteria
- Always ground findings in actual code evidence (file paths, patterns, constraints)

---

## Hybrid Tree Section Map (Optimized: Section-Level Caching)

coderX and evaluatorX receive (Parent, Child) paths, then read according to the following scope:

| Document | Section | Content | Readers | Cache Strategy |
|----------|---------|---------|---------|----------------|
| Parent | 0-6 | Global spec (NFR, DoD, Scope) | coderX, evaluatorX | **Session Cache**: Read once, cache entire block. Invalidate only on requirement change. |
| Parent | 7 | Routing table (not AC source) | coderX | **Session Cache**: Read once per iteration round. |
| Parent | 8.1 | Shared file index | coderX, evaluatorX | **Session Cache**: Read once, invalidate on file structure change. |
| Parent | 8.2 | Knowledge graph outlines (details via MCP) | coderX, evaluatorX | **Session Cache**: Read once per session. |
| Parent | 8.3 | Cross-branch dependencies | coderX, evaluatorX | **Session Cache + Invalidation**: Read once, invalidate on requirement change only. |
| Child | 7 | Branch AC (evaluation target) | coderX, evaluatorX | **No Cache**: Changes frequently during iteration. |
| Child | 8.1 | Private file index | coderX, evaluatorX | **Session Cache**: Read once, invalidate on file change. |
| Child | 8.2 | Incremental references | coderX | **No Cache**: Iteration-specific. |
| Child | 9 | Prior evaluation results | evaluatorX (for inheritance) | **No Cache**: Changes every iteration. |

---

## Core Iteration Loop (Optimized: Dependency Graph + Ready Queue)

> Shared by Mode A and Mode B (with Hybrid Tree).

### Pre-Loop Setup: Build Dependency Graph

```
1. Read Parent Section 7 → extract all Children
2. Read Parent Section 8.3 → extract dependency edges (CACHE THIS)
3. Build adjacency list + in-degree map:
   - in_degree[child] = number of dependencies
   - adj[parent_dep] = [children that depend on it]
4. Initialize per-child iteration counters:
   - child_iterations[child] = { used: 0, remaining: sessionParams.iteration_limit }
5. Initialize ready_queue (FIFO):
   - For each child where in_degree[child] == 0 → push to ready_queue
6. Critical Path Analysis (Optimized):
   - Identify critical path: longest dependency chain
   - Identify high-impact nodes: children with most dependents
   - Priority score: impact_score = number_of_dependents + (1 / chain_position)
   - Sort ready_queue by priority (highest first)
```

### Phase 1 — Ready Queue Processing (replaces sequential scan)

```
While ready_queue is not empty:
  current = ready_queue.dequeue()
  
  0. ITERATION CHECK:
     - If child_iterations[current].remaining <= 0:
       mark as "Limit Reached", report to human, continue to next
  
  1. Dispatch coderX: (Parent, current) + [prior Fix Instructions, if any]
  2. coderX implements, outputs Change Summary Payload
  3. Validate Payload (module 02), forward to evaluatorX: (Parent, current, Change Summary)
  4. evaluatorX evaluates, outputs Evaluation Result Payload
  5. Load module 03 for Post-Evaluation document update (incremental, see §6)
  
  6. Result handling:
     - PASS:
       a. Mark current as PASS
       b. For each dependent in adj[current]:
            in_degree[dependent]--
            if in_degree[dependent] == 0 → enqueue to ready_queue
     - Needs Fix + child_iterations[current].remaining > 0:
       a. child_iterations[current].used++
       b. child_iterations[current].remaining--
       c. Extract Fix Instructions -> re-enqueue current to ready_queue
     - Needs Fix + child_iterations[current].remaining <= 0:
       a. Mark as "Limit Reached", report to human
       b. Do NOT enqueue dependents (they remain blocked)
```

### Phase 2 — Blocked Queue Resolution

```
If ready_queue is empty but some children not completed:
  - Check for circular dependencies in remaining in_degree > 0 nodes
  - If circular: report circular dependency to human, terminate
  - If not circular (waiting on external): report blocking dependency to human
```

**Early Exit (Optimized)**: 
- PASS → immediately mark complete, enqueue dependents, move to next in queue
- No need to check iteration limit for PASS'd children

**Per-Child Counter State**:
```javascript
child_iterations = {
  "child-1": { used: 0, remaining: 2 },
  "child-2": { used: 1, remaining: 1 },
  // ...
}
```

**Dispatch Format**:
- Pass `Parent: [path]` + `Child: [path]` (all modes use Hybrid Tree)

## Minimal Hybrid Tree Auto-Generation (Mode B, No PRD)

> When Mode B has no existing PRD or Hybrid Tree, orchestratorX auto-generates a minimal Hybrid Tree before entering the Core Iteration Loop. This replaces the former Simple Iteration Loop path.

**orchestratorX executes** (sole document writer):

1. **Code Scan**: Use Glob/Grep/rg to search project for files related to the requirement
2. **Generate Parent** (`hybrid-template.md`):
   - Section 0: MCP status from Module 01
   - Sections 1-6: Minimal fill from requirement (project goal, boundaries, NFR, DoD)
   - Section 7: Routing table with single Child row
   - Section 8.1: Shared file index from scan results
   - Section 8.2: Knowledge graph skeleton (outlines only)
   - Section 8.3: Empty (single Child, no cross-branch dependencies)
   - Section 9: Empty aggregation table
3. **Generate Child** (`hybrid-template.md`):
   - Section 7: Acceptance criteria decomposed from requirement
   - Section 8.1: Private file index for relevant files
   - Section 9: Empty evaluation report
4. **Write** both documents to `.hybrid/[feature-name]/`
5. **Enter Core Iteration Loop** with generated Parent + Child

**PRD file path input**: When user passes a file path (e.g. `/xlocal ./docs/prd.md`), read the PRD file and use its content to populate Sections 1-6 and derive AC for Section 7, instead of inferring from the raw requirement.

**Requirement Change**: Follow the standard Requirement Change Handling (shared by Mode A and Mode B with Hybrid Tree).

---

## Hybrid Tree Routing

### Tree Detection

Hybrid Tree exists when:
- `.hybrid/[feature]/` directory contains multiple `*-hybrid.md` files
- File marked `Document Type: Parent` contains Section 7 routing table

### Routing Logic

1. Read Parent Section 7 routing table
2. Compare current task/requirement against each Child's Scope column
3. Match found -> dispatch coderX and evaluatorX, pass (Parent, Child)
4. No match -> execute Requirement Change Handling (Change Type = new_branch)

### Child Creation Flow

When Requirement Change Handling determines Change Type = new_branch:
1. Analysis results contain: feature description, suggested AC list, suggested file scope
2. orchestratorX executes:
   - Create new Child document using Child template, fill feature description -> Section 7 Description, suggested ACs -> Section 7 AC
   - Add new row to Parent Section 7 (append end; dependency order is resolved at runtime by the Core Loop's deferred queue)
   - Update Parent Section 8.3 (if new dependencies)
3. Dispatch coderX: (Parent, new Child)


---

## Requirement Change Handling

> Shared by Mode A and Mode B (all paths use Hybrid Tree).

### Step 1: Change Detection

orchestratorX determines whether user input changed the current Child's requirement scope. Analyze user input, determine change type:

| Change Type | Detection Criteria | Action |
|-------------|-------------------|--------|
| **Adjustment** | Modifying existing AC of current Child | Update current Child |
| **Optimization** | Refining existing functionality of current Child | Update current Child |
| **Scope Expansion** | Adding to current Child's scope | Update current Child |
| **Scope Reduction** | Removing AC from current Child | Update current Child |
| **New Branch Feature** | Feature does not belong to any existing Child | Create new Child |

### Step 2: Major Change Confirmation

| Change Type | Confirmation Required |
|-------------|---------------------|
| New Branch Feature | Yes — describe new feature, ask "Confirm creating new sub-module?" |
| Scope Expansion > 50% | Yes — describe expansion, ask "Confirm scope expansion?" |
| Scope Reduction (removing AC) | Yes — list deleted ACs, ask "Confirm deleting these acceptance criteria?" |
| Adjustment / Optimization | No — proceed directly |

If user rejects, discard the change and resume original flow.

### Step 3: Document Update

Read change analysis results, execute:
- Update Child Section 7 (AC add/modify/delete)
- Update Parent Section 7 (routing table)
- Update Parent Section 8.3 (dependencies)
- Reset affected Children Status to "Needs Re-evaluation"

**Identify affected Children**:
1. Read Parent Section 8.3 (cross-branch dependencies)
2. If updated Child is depended on by other Children: list all dependent Children, mark as "Needs Re-evaluation"
3. If updated Child depends on other Children: verify dependency satisfied (Status = PASS), record warning if not

**Constraints**: traceability (all changes traceable to user description), Parent Sections 0-6 not modified, MECE principle.

### Step 4: Resume Workflow

- Modified Child is **currently iterating**: reset iteration counter, restart from that Child
- Modified Child is **already PASS'd**: Status reset to "Needs Re-evaluation", re-execute in next loop cycle
- Modified Child is **not yet executed**: documents updated, loop handles naturally
- Change Type = `new_branch`: follow Child Creation Flow

---

## Auto-Routing

> **Delegated**: Full routing logic is in `.claude/skills/auto-routing/SKILL.md`. orchestratorX receives an explicit mode parameter and does NOT perform routing itself.

---

## Start Rule

1. **Routing priority**: Explicit command > natural language intent > Auto-Routing. When uncertain, require user to specify `/xwhole`, `/xlocal`, `/xunit`. Parallel execution via `/xwhole -parallel`.
2. **State isolation**: Stay in current workflow mode until completion. No cross-mode calls.
3. **Hybrid Tree**: whole and local must generate Hybrid Tree (even if skipping planning, create minimal version from `orchestrator-playbook/hybrid-template.md`). unit exempt.
4. **Concurrency protection**: Before starting any workflow, check for `.hybrid/.workflow-lock`. If lock exists, warn user and abort. Otherwise, create lock file with timestamp and mode. Remove lock on workflow completion or interruption.

