From 05741836599cbf46f4d4d4d9f22d0f3205436d4a Mon Sep 17 00:00:00 2001
From: dj-oyu <68707227+dj-oyu@users.noreply.github.com>
Date: Wed, 25 Feb 2026 05:37:42 +0900
Subject: [PATCH] feat: inject orchestration guidance into system prompt when
 spawn tool is active

When --orchestration is enabled, the spawn tool is registered on the agent.
BuildSystemPrompt() now detects this and prepends an orchestration section
that instructs the agent to act as conductor:
- prefer spawn (non-blocking) for parallel/background tasks
- use subagent (blocking) only when result is needed immediately
- do inline only for single fast tool calls
- fork aggressively, record delegated tasks in MEMORY.md

Without --orchestration the section is omitted entirely.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 pkg/agent/context.go | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/pkg/agent/context.go b/pkg/agent/context.go
index d1f376233..3229c6ca3 100644
--- a/pkg/agent/context.go
+++ b/pkg/agent/context.go
@@ -14,6 +14,31 @@ import (
 	"github.com/sipeed/picoclaw/pkg/tools"
 )
 
+const orchestrationGuidance = `## Orchestration
+
+You are the conductor, not the performer. Prefer delegation over doing everything inline.
+
+Use **spawn** (non-blocking) when:
+- Tasks can run in parallel or in the background
+- Multiple independent tasks can run simultaneously — spawn each one
+- You don't need the result to decide the next step
+- The operation is long-running (builds, fetches, analysis, file processing)
+
+Use **subagent** (blocking) when:
+- You need the result before you can continue
+- Correctness of the next step depends on the outcome
+
+Do inline only when:
+- It's a single fast tool call (read a file, quick search)
+- Delegation overhead clearly outweighs the benefit
+
+Default bias: if a task involves more than 2-3 tool calls or can run independently, delegate it.
+When you spawn, immediately plan what comes next — blocking means you've stopped thinking.
+Fork aggressively: explore multiple directions simultaneously.
+
+After spawning, record the assignment in ## Orchestration > Delegated in MEMORY.md.
+When results come back, synthesize and decide the next fork.`
+
 type ContextBuilder struct {
 	workspace    string
 	workDir      string              // session-specific working directory (worktree or project subdir)
@@ -159,6 +184,13 @@ func (cb *ContextBuilder) BuildSystemPrompt() string {
 	// Core identity section
 	parts = append(parts, cb.getIdentity())
 
+	// Orchestration guidance — injected only when spawn tool is registered
+	if cb.tools != nil {
+		if _, hasSpawn := cb.tools.Get("spawn"); hasSpawn {
+			parts = append(parts, orchestrationGuidance)
+		}
+	}
+
 	// Bootstrap files
 	bootstrapContent := cb.LoadBootstrapFiles()
 	if bootstrapContent != "" {