# OrchID — Orchestration Identification Pipeline

> **orch** = Orchestration · **ID** = Identification — like the flower: structured, modular, beautiful when in bloom.

## Philosophy

OrchID is a **modular orchestration meta-skill** for AI agent swarms. It decomposes complex multi-agent development into discrete, composable phases — each encapsulating its own agents, skills, and Ralph loops.

### Core Principles

1. **The Orchestrator Does Not Code.** Ever. Investigate, plan, delegate, review.
2. **Skills in Skills.** Each phase is a self-contained sub-skill with its own agent assignments, Ralph loop config, and dependency declarations. Load only what you need.
3. **Ralph Loops Are the Execution Wrapper.** Every delegation goes through a Ralph loop for pacing, progress tracking, and iteration control — not raw subagent fire-and-forget.
4. **Subagents Only.** `interactive_shell` is PROHIBITED for work. It is exclusively for external engine evals (Claude Code, Gemini CLI, Codex, Cursor). All internal delegation uses `subagent()`.
5. **Model-Agnostic.** No hardcoded models. Inherit the orchestrator's model by default. Ask the user if cost optimization is desired. Respect agent-defined model preferences.
6. **Doctor First.** Before any pipeline runs, verify all dependencies exist. Fail fast, fail clear.
7. **Zero File Overlap.** Lanes never share files. The file ownership matrix is law.

### The 9-Phase Pipeline

```
PHASE 1: INVESTIGATE  →  PHASE 2: DOCUMENT  →  PHASE 3: ISSUES
                              ↓
PHASE 4: DECOMPOSE  →  PHASE 5: .ralph/ FILES  →  PHASE 6: LAUNCH
                                                           ↓
                                              PHASE 7: CONVERGE  →  PHASE 8: REVIEW
                                                                           ↓
                                                               PHASE 9: GAP CLOSURE + CLEANUP
```

### Sub-Skill Architecture

```
orchID/
├── SKILL.md                    ← Master: overview, dependency table, triggers
├── orchID-doctor/SKILL.md      ← Health check / dependency verification
├── orchID-investigate/SKILL.md ← Phases 1-2: Scout, map, document
├── orchID-decompose/SKILL.md   ← Phases 3-5: Issues, ownership, .ralph/ files
├── orchID-launch/SKILL.md      ← Phase 6: Subagent dispatch via Ralph loops
├── orchID-converge/SKILL.md    ← Phases 7-8: Pull, wire, review gate
└── orchID-cleanup/SKILL.md     ← Phase 9: Gap closure, .ralph/ archive
```

Each sub-skill declares:
- **Which agents** it uses (from `references/agents/`)
- **Which skills** it depends on (from `references/`)
- **Ralph loop configuration** (iterations, pacing, reflection)
- **Model policy** (inherit / ask / agent-defined)

### Delegation Architecture

```
┌──────────────────────────────────────────────────────────┐
│                    ORCHESTRATOR                           │
│                   (YOU — the brain)                       │
│                                                          │
│   Loads orchID master skill                              │
│   Runs orchID-doctor first                               │
│   Steps through phases, loading sub-skills as needed     │
│                                                          │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│   │ orchID-      │  │ orchID-      │  │ orchID-      │    │
│   │ investigate  │  │ decompose    │  │ launch       │    │
│   │              │  │              │  │              │    │
│   │ Agent: scout │  │ Agent: planner│  │ Agent: worker│    │
│   │ Ralph: no   │  │ Ralph: no    │  │ Ralph: YES   │    │
│   └─────────────┘  └─────────────┘  └─────────────┘    │
│                                                          │
│   Each sub-skill is a "skill in a skill" —              │
│   encapsulating agent + loop + project skills            │
│   as a single composable unit.                           │
└──────────────────────────────────────────────────────────┘
```

## Delegation Rules (Non-Negotiable)

### subagent() — Internal Work (USE THIS)

For ALL coding, investigation, review, and testing delegation:

```
subagent({
  agent: "worker",
  task: "Implement X...",
  async: true,
  skill: "ms-rust"        // project-specific skills injected here
})
```

### interactive_shell — External Eval ONLY (DO NOT USE for work)

```
interactive_shell is PROHIBITED for any implementation, debugging,
review, or testing task. It is EXCLUSIVELY for launching external
coding agent CLIs for evaluation/benchmarking:

interactive_shell({
  command: 'claude "Review the diffs"',
  mode: "dispatch"
})

Allowed CLIs: claude, gemini, codex, cursor
Purpose: engine comparison, benchmark, eval — NEVER production work.
```

| Dimension | subagent() | interactive_shell |
|-----------|-----------|-------------------|
| Token cost | One agent | Two agents (you + child) |
| Model control | Explicit per-task | Whatever pi launches with |
| Context | Clean fork | TUI overlay burns context |
| Progress | Structured output | Must poll/parse terminal |
| Parallelism | Unlimited async | One per terminal tab |
| Chaining | chain/parallel support | Manual glue |
| Skills | Inject per-task | Inherit from parent |

## Dependencies

### Required Agents (must exist in .agents/ or subagent registry)

| Agent | Role | Model | Used By Phase |
|-------|------|-------|---------------|
| scout | Codebase recon | glm-5.1-claude | orchID-investigate |
| researcher | Web research | glm-5.1-claude | orchID-investigate |
| planner | Implementation planning | deepseek-v4-pro | orchID-decompose |
| worker | Implementation execution | deepseek-v4-flash | orchID-launch, orchID-cleanup |
| dev-1 | Focused coding | deepseek-v4-flash | orchID-launch |
| reviewer | Code review | glm-5.1-claude | orchID-converge |
| tester | Test verification | deepseek-v4-flash | orchID-converge |
| brain | Architecture reasoning | (inherit) | Any phase (escalation) |
| delegate | Lightweight passthrough | (inherit) | Any phase (simple tasks) |

### Required Skills

| Skill | Source | Package | Used By |
|-------|--------|---------|---------|
| ralph | src/ | orchid (bundled) | orchID-launch, orchID-cleanup |
| subagents | src/ | orchid (bundled) | orchID-launch (all delegation) |
| orchID-decompose | src/ | orchid (bundled) | Task authoring + issue decomposition |

### Project-Specific Skills (loaded per language)

| Skill | When | Source |
|-------|------|--------|
| ms-rust | Rust projects | ~/.pi/agent/skills/ms-rust-guidelines |
| rustic-prompt | Rust projects | ~/.pi/agent/skills/rustic-prompt |

### Required Tools

| Tool | Check Command | Used By |
|------|---------------|---------|
| git | `git --version` | All phases |
| gh | `gh auth status` | orchID-decompose (issue creation) |
| cargo | `cargo --version` | Rust projects, orchID-converge |
| Telepathine bus | `agent_memory_telepath_list()` | orchID-launch, orchID-converge |

## Model Policy

OrchID does NOT hardcode models. Instead:

1. **Default**: Omit `model` param → subagent inherits orchestrator's model
2. **User-specified**: Use exactly what the user requested
3. **Capacity-based**: If user says "optimize cost", ASK which model to use for workers
4. **Agent-defined**: `.agents/*.md` files declare model preferences — respect those
5. **Doctor verifies**: orchID-doctor checks that declared agents have valid model configs

## orchID-doctor — Health Check

Run before ANY pipeline execution. Verifies:

- All required agents exist and are reachable
- All required skills are loadable
- Project-specific skills are installed for the detected language
- Tools (git, gh, cargo) are available and authenticated
- Telepathine bus has connectivity
- Git repo is clean and on the correct branch
- Build is green

Reports: ✅ Ready / ⚠️ Warnings / ❌ Missing (with fix suggestions)

## Workspace Contents

```
OrchID/
├── README.md                              ← This file
├── CHANGELOG.md                           ← Release history
├── LICENSE                                ← MIT
├── package.json                           ← npm package manifest
├── ARCHITECTURE.html                      ← Visual architecture guide
├── src/                                   ← Unified source (113 .ts files)
│   ├── index.ts                           ← Barrel exports
│   ├── orchestrator/                      ← Batch orchestration engine (42 files)
│   ├── ralph/                             ← Iterative Ralph loop (1 file)
│   └── subagents/                         ← Subagent dispatch + chains (69 files)
├── extensions/                            ← Pi extension entry points
│   ├── task-orchestrator.ts               ← /orch commands + supervisor
│   ├── reviewer-extension.ts              ← /run review commands
│   └── ralph.ts                           ← /ralph loop commands
├── skills/orchid/                         ← 7 sub-skill pipeline
│   ├── SKILL.md                           ← Master entry point
│   ├── orchID-doctor/SKILL.md             ← Health check
│   ├── orchID-investigate/SKILL.md        ← Phases 1-2
│   ├── orchID-decompose/SKILL.md          ← Phases 3-5
│   ├── orchID-launch/SKILL.md             ← Phase 6
│   ├── orchID-converge/SKILL.md           ← Phases 7-8
│   └── orchID-cleanup/SKILL.md            ← Phase 9
├── agents/                                ← Agent definitions (12)
├── templates/                             ← Agent prompt templates
├── prompts/                               ← Orchestration prompts
├── dashboard/                             ← Web dashboard
├── bin/                                   ← Utility scripts (excluded from npm)
├── sources/                               ← Git submodules (excluded from npm)
└── references/                            ← Design docs (excluded from npm)
```

## Development Roadmap

### v0.1 (Current — Published) — Unified Package
- [x] All 3 source repos merged (taskplane v0.30.1 + ralph-wiggum v0.2.1 + pi-subagents v0.25.0)
- [x] 113 .ts source files across 3 modules
- [x] 20 tools, 18 commands, 4 extensions, 7 sub-skills, 12 agent defs
- [x] Master SKILL.md + all 7 sub-skill SKILL.md files
- [x] orchID-doctor health check with full dependency verification
- [x] orchID-investigate (phases 1-2: investigate + document)
- [x] orchID-decompose (phases 3-5: issues + decompose + ralph files)
- [x] orchID-launch (phase 6: launch + converge + review + cleanup)
- [x] orchID-converge (phases 7-8: converge + review)
- [x] orchID-cleanup (phase 9: cleanup)
- [x] Model policy (inherit/ask/agent-defined)
- [x] interactive_shell prohibition enforced in all sub-skills
- [x] Published as npm-installable pi package
- [x] Per-project `.orchid-config.json` configuration
- [x] Configurable agent model overrides
- [x] Auto-detect project language and load appropriate skills

### v1.0 — Production Hardening
- [ ] Comprehensive test suite
- [ ] Recovery from failed phases (resume where you left off)
- [ ] Telemetry / cost tracking integration
- [ ] Cross-project templates (Rust, TypeScript, Python, etc.)

## Provenance

Born from the RustAPI project (May 2026) where 3 parallel lanes closed 26 issues
in a single session with full reviewer gates, clippy verification, and Go→Rust fidelity audits.

The patterns that worked are captured here. The patterns that failed are documented as pitfalls.