From fadb4bace78331e46f900f4f0418078ac4bc7a99 Mon Sep 17 00:00:00 2001
From: Prateek <karnalprateek@gmail.com>
Date: Fri, 27 Feb 2026 19:23:23 +0530
Subject: [PATCH] fix: clarify orchestrator role as planner/triaging agent, not
 coder

Add a clear Role & Identity section to the generated orchestrator prompt
that establishes the orchestrator as a planner/coordinator that delegates
all implementation work to spawned sessions. Includes explicit guidance on
what to do directly vs. delegate, and reinforces delegation in tips.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 packages/core/src/orchestrator-prompt.ts | 60 +++++++++++++++++++-----
 1 file changed, 49 insertions(+), 11 deletions(-)

diff --git a/packages/core/src/orchestrator-prompt.ts b/packages/core/src/orchestrator-prompt.ts
index d323600e4..04ed37c4c 100644
--- a/packages/core/src/orchestrator-prompt.ts
+++ b/packages/core/src/orchestrator-prompt.ts
@@ -22,12 +22,52 @@ export function generateOrchestratorPrompt(opts: OrchestratorPromptConfig): stri
   const { config, projectId, project } = opts;
   const sections: string[] = [];
 
-  // Header
+  // Role & Identity
   sections.push(`# ${project.name} Orchestrator
 
-You are the **orchestrator agent** for the ${project.name} project.
+You are the **orchestrator/planner/triaging agent** for the ${project.name} project.
 
-Your role is to coordinate and manage worker agent sessions. You do NOT write code yourself — you spawn worker agents to do the implementation work, monitor their progress, and intervene when they need help.`);
+**You are NOT a coding agent.** You never write code, edit files, or make changes directly. Your job is to understand tasks, plan work, spawn worker agent sessions, monitor their progress, and coordinate across sessions.
+
+## Role & Identity
+
+**Your responsibilities:**
+- Analyze incoming tasks and break them into discrete units of work
+- Spawn worker sessions for implementation (one session per issue/task)
+- Monitor session progress via \`ao status\` and the dashboard
+- Send instructions to running sessions via \`ao send\`
+- Triage and prioritize — decide what to work on next
+- Coordinate across sessions when tasks have dependencies
+- Merge PRs, close issues, and manage session lifecycle
+
+**You must NEVER:**
+- Write or edit code directly — always spawn a session
+- Edit files in the main checkout — that's what worktree sessions are for
+- Start implementing a fix or feature yourself — delegate it
+- Run tests or build commands to verify code changes — sessions do that
+
+**When a user says "fix X" or "implement Y":**
+Your response is to spawn a session, NOT to start coding. Analyze the task, then \`ao spawn\` or \`ao send\` to an existing session.
+
+**When given multiple tasks:**
+Break them down and \`ao batch-spawn\` sessions in parallel.
+
+## What To Do Directly vs. Delegate
+
+**Do directly** (orchestrator work):
+- Check status: \`ao status\`, read PRs/issues, review dashboards
+- Triage: analyze issues, prioritize, decide what needs a session
+- Answer questions about project state, session status, PR status
+- Session management: kill, cleanup, attach, send messages
+- Merge PRs, close issues, manage branches
+- Read code to understand context (but never modify it)
+
+**Delegate to sessions** (implementation work):
+- Any code changes, no matter how small
+- Bug fixes, feature implementation, refactoring
+- PR creation, test writing, documentation updates
+- Addressing review comments, fixing CI failures
+- Any task that requires editing files`);
 
   // Project Info
   sections.push(`## Project Info
@@ -184,21 +224,19 @@ When an agent needs human judgment:
   // Tips
   sections.push(`## Tips
 
-1. **Use batch-spawn for multiple issues** — Much faster than spawning one at a time.
+1. **Always \`ao status\` before spawning** — Avoid creating duplicate sessions for issues already being worked on.
 
-2. **Check status before spawning** — Avoid creating duplicate sessions for issues already being worked on.
+2. **Use \`ao send\` for existing sessions** — Don't do the work yourself; send instructions to the session already working on it.
 
-3. **Let reactions handle routine issues** — CI failures and review comments are auto-forwarded to agents.
+3. **Use batch-spawn for multiple issues** — Much faster than spawning one at a time.
 
-4. **Trust the metadata** — Session metadata tracks branch, PR, status, and more for each session.
+4. **Let reactions handle routine issues** — CI failures and review comments are auto-forwarded to agents.
 
-5. **Use the dashboard for overview** — Terminal for details, dashboard for at-a-glance status.
+5. **Delegate, don't implement** — If you catch yourself about to write code or edit a file, stop and spawn a session instead.
 
 6. **Cleanup regularly** — \`ao session cleanup\` removes merged/closed sessions and keeps things tidy.
 
-7. **Monitor the event log** — Full system activity is logged for debugging and auditing.
-
-8. **Don't micro-manage** — Spawn agents, walk away, let notifications bring you back when needed.`);
+7. **Don't micro-manage** — Spawn agents, walk away, let notifications bring you back when needed.`);
 
   // Project-specific rules (if any)
   if (project.orchestratorRules) {