team-coding-orchestrator

# Team Coding Orchestrator Run multi-agent coding work with fixed role routing and observable progress. ## Core routing policy Always follow this role split unless the user explicitly overrides: - Codex: implement backend and complex logic - Claude: frontend implementation and review - planning/modeling: `claude-opus-4-6` - code writing: `claude-sonnet-4-6` - search/scouting/find-information tasks: `claude-haiku-4-5-20251001` (cost-optimized) - Gemini: summarize outputs and perform second-pass review (docs + code) Gemini policy: - Use login-based Gemini CLI flow - Do not introduce Gemini API key flow unless user requests it ## Runtime mode selection Pick runtime by task type: 1. **tmux-first (default)** for interactive or visible collaboration 2. **background process fallback** for unattended long-running jobs Prefer tmux whenever the user wants visibility into progress. ## Bundled script Use bundled script: - `scripts/agent-stack` Recommended env (`~/.config/agent-stack/env.sh`): - `ANTHROPIC_API_KEY` - `CLAUDE_BASE_URL` - `CLAUDE_MODEL` - `DISCORD_WEBHOOK_URL` (for completion notifications) The script supports: - `up` / `down` / `status` - `task [--notify <bot_id>] <agent> "prompt"` - `watch <bot_id> <agent>` (attach completion watcher to running task) - `send <agent> <raw shell command>` - `tail <agent> [lines]` - `doctor` Notification hooks now apply uniformly to **codex / claude / gemini**. When `--notify` is used, agent-stack injects a completion token and watcher reports success/failure back to Discord webhook. ## Standard operating flow 1. Run `scripts/agent-stack up` 2. Run `scripts/agent-stack doctor` 3. Dispatch tasks by role: - Codex for backend logic - Claude Opus for plan, then Sonnet for coding/review - Gemini for summary + second review 4. Use `scripts/agent-stack tail <agent>` to inspect progress 5. Dispatch long tasks with notifier enabled, e.g. `scripts/agent-stack task --notify <dispatcher_bot_id> claude "..."` 6. Report milestones to user (started, in-progress, blocked, finished, ETA) 7. Do not "dead-wait" long CLI jobs: actively tail/checkpoint and send periodic progress updates 8. Avoid fixed short timeouts for long tasks; prefer tmux/background + watcher 9. Run `scripts/agent-stack down` after completion (or keep session if user wants continuity) ## Claude model routing commands Use explicit models for Claude tasks to avoid default-model drift. Plan with Opus: ```bash scripts/agent-stack send claude "ANTHROPIC_BASE_URL=https://gaccode.com/claudecode ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY claude --dangerously-skip-permissions -p --model claude-opus-4-6 'Create an implementation plan for: ...'" ``` Code with Sonnet: ```bash scripts/agent-stack send claude "ANTHROPIC_BASE_URL=https://gaccode.com/claudecode ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY claude --dangerously-skip-permissions -p --model claude-sonnet-4-6 'Implement frontend changes for: ...'" ``` Search/scouting with Haiku (cheap mode): ```bash scripts/agent-stack send claude "ANTHROPIC_BASE_URL=https://gaccode.com/claudecode ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY claude --dangerously-skip-permissions -p --model claude-haiku-4-5-20251001 'Find relevant files/specs for: ...'" ``` ## Response contract to users When coordinating work, provide concise updates: - what is running - what finished - any blocker requiring user input - next step Use templates and examples from `references/routing-playbook.md` when needed. ## CodeX / Gemini hook examples ```bash # Codex with completion callback scripts/agent-stack task --notify 1475340557059625222 codex "Implement ..." # Gemini with completion callback scripts/agent-stack task --notify 1475340557059625222 gemini "Summarize ..." ``` ## Stable dispatch pattern (required for long prompts) When task context is large, **do not** send giant inline prompts directly to CLI. Use this two-step pattern: 1. Write a context brief file into task workspace, e.g. - `03-ACTIVE-TASKS/TASK-xxxx/02-WORKING/shared/cli-brief-<agent>.txt` 2. Send a short command to CLI: - `scripts/agent-stack task --notify <bot_id> claude "Read and execute instructions in <brief-file>. Return final receipt only."` Why: - avoids shell escaping/truncation issues in tmux - keeps prompts auditable/versioned in task folder - improves reproducibility across codex/claude/gemini Minimum brief contents: - objective + deliverable definition - mandatory input file paths - mandatory output file paths - hard constraints - receipt format (`commit hash + clean status + published paths`) ## Preflight for document-generation runs (new) Before dispatching long doc tasks, run a quick agent-specific preflight in pane: - verify target paths are readable - verify output directory writable - verify git repo available for commit Example short preflight prompt: `Check read access to <input paths>, write access to <output dir>, and git status in repo. Return only PASS/FAIL + reason.` If preflight fails, do not start long run. First fix context/path/permission issues. ## Session continuity & multi-turn checkpointing All three CLIs (codex/claude/gemini) support multi-turn continuation **within the same tmux pane**. Continuity keeps working unless one of these happens: - `scripts/agent-stack down` - pane/session killed - host restart/crash Best practice for reliable "断点续传": 1. keep pane alive 2. write checkpoints to files (`02-WORKING/shared/*.txt`) 3. commit meaningful milestones Do not rely on model memory alone for long runs. ## Gemini stability guardrails (required) Gemini has higher risk of pane drift when multiple tasks overlap. Use these guardrails: 1. **single-flight**: never overlap two gemini tasks in one pane. 2. pre-dispatch check: ensure gemini pane is idle (`bash`) before sending new task. 3. always dispatch with short command + context brief file. 4. if watcher/no-marker noise appears, run `scripts/agent-stack down && scripts/agent-stack up` before retry. ## Watcher hygiene If you see delayed timeout messages from old runs, assume stale watcher first. Use current script behavior where `agent-stack down` cleans watcher processes. If needed, manually clean: ```bash pkill -f "team-coding-orchestrator/scripts/agent-stack-watcher" || true ```