diff --git a/README.md b/README.md index 3bec544..96d6b9c 100644 --- a/README.md +++ b/README.md @@ -324,6 +324,49 @@ Deployment steps, test commands, coding standards, acceptance criteria — all i --- +## The orchestrator's role + +The orchestrator is a **planner and dispatcher** — not a coder. This separation is intentional and enforced. + +### What the orchestrator does + +- **Plans**: Analyzes requirements, breaks down work, decides priorities +- **Dispatches**: Creates issues, assigns developer levels, starts workers +- **Coordinates**: Monitors queue, handles status checks, answers questions +- **Reads**: Can inspect code to understand context (but never writes) + +### What goes through workers + +All implementation work flows through the issue → worker pipeline: + +| Action | Goes through worker? | Why | +|---|---|---| +| Writing or editing code | ✅ Yes | Audit trail, tier selection | +| Git operations (commits, branches, PRs) | ✅ Yes | Workers own their worktrees | +| Running tests | ✅ Yes | Part of the dev/QA workflow | +| Fixing bugs | ✅ Yes | Even quick fixes need tracking | +| Refactoring | ✅ Yes | Sonnet/Opus for complexity | +| Reading code to answer questions | ❌ No | Orchestrator can read | +| Creating issues | ❌ No | Orchestrator's job | +| Status checks | ❌ No | Orchestrator's job | +| Architecture discussions | ❌ No | Orchestrator's job | + +### Why this boundary exists + +1. **Audit trail** — Every code change links to an issue. You can trace any line of code back to a tracked task. + +2. **Right model for the job** — A typo fix uses Haiku (~$0.001). A migration uses Opus (~$0.20). Without tier selection, you're either overpaying or underperforming on every task. + +3. **Parallelization** — While workers code, the orchestrator stays free to handle new requests, answer questions, create more issues. No bottleneck. + +4. **QA pipeline** — Code goes through review before merging. Skip the worker pipeline, skip QA. + +5. **Session reuse** — Workers accumulate codebase context over multiple tasks. The orchestrator starting fresh every time wastes tokens. + +The orchestrator saying "I'll just make this quick fix myself" is like a manager saying "I'll just write that feature instead of assigning it." Technically possible, but it breaks the system that makes everything else work. + +--- + ## Getting started ### Prerequisites diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index c73b7a3..14ec94a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -589,11 +589,13 @@ graph LR Z[Zombie cleanup] end - subgraph "Orchestrator handles" + subgraph "Orchestrator handles (planning only)" MSG[Telegram announcements] HB[Heartbeat scheduling] DEC[Task prioritization] M[Developer assignment
junior/medior/senior] + READ[Code reading for context] + PLAN[Requirements & planning] end subgraph "Sub-agent sessions handle" @@ -609,6 +611,8 @@ graph LR end ``` +**Key boundary:** The orchestrator is a planner and dispatcher — it never writes code. All implementation work (code edits, git operations, tests) must go through sub-agent sessions via the `task_create` → `work_start` pipeline. This ensures audit trails, tier selection, and QA review for every code change. + ## IssueProvider abstraction All issue tracker operations go through the `IssueProvider` interface, defined in `lib/providers/provider.ts`. This abstraction allows DevClaw to support multiple issue trackers without changing tool logic. diff --git a/lib/templates.ts b/lib/templates.ts index c47c8f7..47c476e 100644 --- a/lib/templates.ts +++ b/lib/templates.ts @@ -88,7 +88,34 @@ These are orchestrator-only tools. Do not call them: ## Orchestrator -You are a **development orchestrator**. You receive tasks via Telegram, plan them, and use **DevClaw tools** to manage the full pipeline. +You are a **development orchestrator** — a planner and dispatcher, not a coder. You receive tasks via Telegram, plan them, and use **DevClaw tools** to manage the full pipeline. + +### ⚠️ Critical: You Do NOT Write Code + +**Never write code yourself.** All implementation work MUST go through the issue → worker pipeline: + +1. Create an issue via \`task_create\` +2. Dispatch a DEV worker via \`work_start\` +3. Let the worker handle implementation, git, and PRs + +**Why this matters:** +- **Audit trail** — Every code change is tracked to an issue +- **Tier selection** — Junior/medior/senior models match task complexity +- **Parallelization** — Workers run in parallel, you stay free to plan +- **QA pipeline** — Code goes through review before closing + +**What you CAN do directly:** +- Planning, analysis, architecture discussions +- Requirements gathering, clarifying scope +- Creating and updating issues +- Status checks and queue management +- Answering questions about the codebase (reading, not writing) + +**What MUST go through a worker:** +- Any code changes (edits, new files, refactoring) +- Git operations (commits, branches, PRs) +- Running tests in the codebase +- Debugging that requires code changes ### DevClaw Tools @@ -154,6 +181,7 @@ Workers receive role-specific instructions appended to their task message. These ### Safety +- **Never write code yourself** — always dispatch a DEV worker - Don't push to main directly - Don't force-push - Don't close issues without QA pass