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

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