agent-conductor

# Agent Conductor 🎼 **You conduct. Agents perform.** Route all implementation work — file changes, scripts, data processing — to coding sub-agents. The orchestrating session stays lean: it plans, decides, and validates. Agents do the execution. ## Supported Agents Agent-agnostic. Set your invoke command once: | Agent | Invoke Command | |-------|---------------| | Claude Code | `claude '<task>'` | | OpenAI Codex | `codex '<task>'` | | Cursor Agent | `cursor-agent '<task>'` | | Gemini Code | `gemini-code '<task>'` | | Any other | `your-agent-cmd '<task>'` | Use `AGENT_CMD` as a placeholder in the examples below. ## When to Dispatch Dispatch when the task involves **any** of: - Writing or modifying files (even one line) - Running scripts or processing data - Execution time > 10 seconds - Batch operations over multiple items *If it produces file changes → dispatch it.* ## Dispatch Template ``` ## Task: [name] ### Requirement [One sentence: what to produce and where] ### Context - Project: [name and purpose] - Relevant files: [paths] - Data format: [brief description of inputs/outputs] ### Acceptance Criteria - [ ] Output file exists at [path] - [ ] Contains [N] records / passes [specific check] - [ ] No errors in [error field / log] ### Gotchas - [Known pitfall 1] - [Known pitfall 2] ### Environment - Language/runtime: [python3 / node / go / etc.] - Working directory: [path] - Special config: [proxy, auth, env vars if needed] When done, notify with: [your completion notification command] ``` ## Execution Mechanism | Duration | Mechanism | |----------|-----------| | < 5 min | Foreground: `exec pty:true command:"AGENT_CMD '...'"` | | 5–30 min | Background: `exec pty:true background:true timeout:1800 command:"AGENT_CMD '...'"` | | > 30 min | Agent writes script → run in `screen` / `tmux` | > Use `pty:true` if your platform requires it (needed for Claude Code; check other agents' docs). ## Task Decomposition Split large projects by **stage**, not by feature. Each stage must be independently verifiable. **Split when any of these apply:** - Runtime > 30 minutes - More than one script needed - Batch > 100 items - Output of one step feeds the next ``` Stage 1: Prepare data → clean_data.csv (< 2 min) Stage 2: Process → results.json (needs Stage 1) Stage 3: Report → report.md (needs Stage 2) ``` See [references/patterns.md](references/patterns.md) for parallel coordination, checkpoint/resume, and domain examples. ## Acceptance Checklist After any "done" signal, always verify: 1. **File exists** — confirm output path 2. **Count correct** — expected N vs. actual N records 3. **Non-empty** — spot-check 2–3 outputs 4. **No silent errors** — check error fields and null rates *A completion signal ≠ acceptance. Run the checklist.* ## Error Handling | Symptom | Action | |---------|--------| | Timeout, no output | Check process log → kill and re-dispatch with more context | | File missing after "done" | Read execution log → add context → re-dispatch | | Partial completion | Check `progress.json` → resume from checkpoint | | Fails twice in a row | Stop re-dispatching → debug in orchestrator session | ## What NOT to Dispatch - Simple reads → use read tools directly - Orchestrator config changes → orchestrator session only - Messages/notifications → use messaging tools directly - Design decisions → orchestrator decides first, agent implements