commit babfec197938f4217733cfbacbb7e133917801a8
Author: Ben Sima <ben@bensima.com>
Date: Tue Dec 30 22:59:03 2025
Omni/Ide: Add orchestrator documentation
ORCHESTRATOR.md: Key design decisions and usage for pi-orchestrate.
Task-Id: t-298.6
diff --git a/Omni/Ide/ORCHESTRATOR.md b/Omni/Ide/ORCHESTRATOR.md
new file mode 100644
index 00000000..b4c3c731
--- /dev/null
+++ b/Omni/Ide/ORCHESTRATOR.md
@@ -0,0 +1,34 @@
+# Coding Orchestrator
+
+Automated coder→reviewer loop for completing coding tasks.
+
+## Usage
+
+```bash
+./Omni/Ide/pi-orchestrate.sh t-123 # Run with default 3 iterations
+./Omni/Ide/pi-orchestrate.sh t-123 --max=5 # Custom max iterations
+```
+
+## Flow
+
+1. **Coder phase** (`pi-code.sh`): Loads task, runs `pi` coding agent, verifies compilation
+2. **Reviewer phase** (`pi-review.sh`): Runs lint/build/test, evaluates changes, returns verdict
+3. **Iterate** until APPROVE or max iterations reached
+
+## Logs
+
+```
+~/logs/orchestrator/YYYYMMDD-HHMMSS-t-XXX.log
+```
+
+## Key Design Decisions
+
+- **Post-coder verification is mandatory**: LLMs claim success without actually compiling. The script runs `bild` after the coder finishes and fails if compilation fails.
+
+- **Uses OpenRouter, not direct Anthropic**: The `pi` CLI requires browser OAuth for Anthropic. For headless operation, we use OpenRouter with explicit `--api-key`.
+
+- **Reviewer feedback via task comments**: The reviewer should add comments to the task so the coder sees feedback on the next iteration (via "Previous Feedback" in prompt).
+
+## Integration
+
+Ava triggers this via the `work_on_task` tool (`Omni/Agent/Tools/Tasks.hs`).
diff --git a/Omni/Ide/README.md b/Omni/Ide/README.md
index 7511090a..11c9f7c3 100644
--- a/Omni/Ide/README.md
+++ b/Omni/Ide/README.md
@@ -1,5 +1,9 @@
# Development Tools and Workflow
+## Additional Documentation
+
+- **[ORCHESTRATOR.md](ORCHESTRATOR.md)** - Automated coder/reviewer loop (pi-orchestrate)
+
## Tools
### run.sh