From 4ef9db1501b22bb2159e5df1b1a24e0970f7b744 Mon Sep 17 00:00:00 2001 From: Lukas May Date: Wed, 18 Feb 2026 16:41:55 +0900 Subject: [PATCH] =?UTF-8?q?refactor:=20Improve=20shared=20agent=20prompts?= =?UTF-8?q?=20=E2=80=94=20add=20context=20management,=20explain=20git=20ru?= =?UTF-8?q?les,=20slim=20inter-agent=20comms?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add CONTEXT_MANAGEMENT constant: tells agents to keep working through context compaction and parallelize reads - Add "why" reasoning to each GIT_WORKFLOW rule so agents understand the purpose, not just the rule - Slim buildInterAgentCommunication: replace verbose bash code blocks with a brief usage pattern paragraph, condense CLI docs to bullet list --- src/agent/prompts/shared.ts | 100 ++++++++++++++++++------------------ 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/src/agent/prompts/shared.ts b/src/agent/prompts/shared.ts index 4d22ba6..60cc960 100644 --- a/src/agent/prompts/shared.ts +++ b/src/agent/prompts/shared.ts @@ -44,68 +44,68 @@ cw id \`\`\` Use the output as the filename (e.g., \`{id}.md\`).`; +export const CODEBASE_VERIFICATION = ` +## Codebase Verification + +Treat your training knowledge as hypothesis, not fact. The codebase is the source of truth. + +1. **Read before writing**: Before modifying any file, read it first. Before importing a module, verify it exists and exports what you expect. +2. **Follow existing patterns**: Check how similar things are done in the codebase. Match naming conventions, error handling, file organization. +3. **Verify imports**: Don't assume a package or module export exists. Check package.json, check the actual export. +4. **Check recent changes**: Run \`git log --oneline -10\` and \`git diff HEAD~3 --stat\` to see what's been changing. Don't undo recent work. +5. **Test your assumptions**: If you think a function works a certain way, read it. If you think a type has a field, check the definition.`; + +export const DEVIATION_RULES = ` +## Deviation Decision Tree + +When you encounter something unexpected, follow this order: + +1. **Typo in your assigned files** → Fix silently, no need to ask +2. **Bug in files you're modifying** → Fix if < 10 lines changed, otherwise note it and move on +3. **Missing dependency you need** → Check if another agent is creating it (read context files). If yes, ask via cw ask. If no, create it yourself only if it's within your task scope +4. **Architectural mismatch** → STOP. Signal with status "questions" explaining what you found vs. what the task assumes +5. **Ambiguous requirement** → STOP. Signal with status "questions" listing the specific ambiguity and 2-3 concrete options +6. **Task seems wrong or impossible** → STOP. Signal with status "error" explaining why + +Never silently reinterpret a task. If the task says "add a REST endpoint" don't build a GraphQL mutation instead.`; + +export const GIT_WORKFLOW = ` +## Git Workflow + +You are working in an isolated git worktree. Other agents may be working in parallel on separate branches. + +- **Commit frequently**: After each logical unit of work (new function, passing test, config change), commit. Each commit is a recovery checkpoint — if context is compacted or something breaks, you can return to the last good state. +- **Descriptive messages**: "Add user validation to signup endpoint" not "update code" — other agents and humans read these to understand what changed. +- **Stage specific files**: Use \`git add \` not \`git add .\` because \`git add .\` can accidentally include files owned by other agents in shared worktrees. +- **Never force-push**: Other agents may have already inspected or built on top of your branch. +- **Check status first**: Run \`git status\` before committing to see what you're about to include.`; + +export const CONTEXT_MANAGEMENT = ` +## Context Management + +Your context window will be automatically compacted as it approaches its limit, allowing you to continue working from where you left off. Do not stop tasks early due to token budget concerns — commit your progress and keep going. Each commit serves as a recovery checkpoint if context is refreshed. + +When reading multiple files or running independent commands, execute them in parallel rather than sequentially.`; + export function buildInterAgentCommunication(agentId: string): string { return ` ## Inter-Agent Communication -You are working in a multi-agent parallel environment. Other agents may be working on related tasks simultaneously. You can exchange questions and answers with peer agents via CLI commands. - -Your agent ID is: **${agentId}** +You are working in a multi-agent parallel environment. Your agent ID is: **${agentId}** ### CLI Commands -**\`cw listen --agent-id ${agentId}\`** -Waits for an incoming question via server-sent events (SSE). Blocks until a question arrives, then prints one JSON line to stdout and exits with code 0. -Output: \`{ "conversationId": "...", "fromAgentId": "...", "question": "...", "phaseId": "...", "taskId": "..." }\` -Exits with code 1 on connection error. +- **\`cw listen --agent-id ${agentId}\`** — Waits (SSE) for an incoming question. Prints one JSON line (\`{ conversationId, fromAgentId, question, phaseId, taskId }\`) and exits. +- **\`cw ask "" --from ${agentId} --agent-id \`** — Ask another agent a question. Blocks until the answer arrives, then prints the answer to stdout. Target with exactly one of: \`--agent-id \`, \`--task-id \`, \`--phase-id \`. +- **\`cw answer "" --conversation-id \`** — Answer a pending question. -**\`cw ask "" --from ${agentId} --agent-id \`** -Ask another agent a question. Blocks via SSE until the answer arrives, then prints the answer text to stdout and exits with code 0. -Target (exactly one required): - - \`--agent-id \`: Ask a specific agent directly by agent ID - - \`--task-id \`: Ask whichever agent is currently running that task - - \`--phase-id \`: Ask whichever agent is running a task in that phase -Exits with code 1 on connection error. +### Usage Pattern -**\`cw answer "" --conversation-id \`** -Answer a pending question. The conversation ID comes from the \`cw listen\` output. -Output: \`{ "conversationId": "...", "status": "answered" }\` - -### Background Listener Pattern - -At the START of your session, run a background listener that writes to a temp file: -\`\`\`bash -CW_LISTEN_FILE=$(mktemp /tmp/cw-listen-XXXXXX.txt) -cw listen --agent-id ${agentId} > "$CW_LISTEN_FILE" 2>&1 & -LISTEN_PID=$! -\`\`\` - -Periodically check for incoming questions between your work steps: -\`\`\`bash -LISTEN_CONTENT=$(cat "$CW_LISTEN_FILE" 2>/dev/null) -if [ -n "$LISTEN_CONTENT" ]; then - echo "$LISTEN_CONTENT" -fi -\`\`\` - -When a question arrives, parse the JSON, answer it, then restart the listener: -\`\`\`bash -cw answer "" --conversation-id -> "$CW_LISTEN_FILE" -cw listen --agent-id ${agentId} > "$CW_LISTEN_FILE" 2>&1 & -LISTEN_PID=$! -\`\`\` +At session start, run a background listener to a temp file (\`cw listen > "$file" &\`). Check it periodically between work steps. When a question arrives, answer it and restart the listener. Before writing signal.json, kill the listener and clean up. ### When to Communicate - You need interface, schema, or API contract info from another agent's work - You're about to modify a shared resource and want to coordinate - You have a dependency on work another agent is doing -- Do NOT ask questions that you can answer by reading the codebase yourself - -### Cleanup -Before writing \`.cw/output/signal.json\`, kill your listener and clean up: -\`\`\`bash -kill $LISTEN_PID 2>/dev/null -rm -f "$CW_LISTEN_FILE" -\`\`\``; +- Do NOT ask questions you can answer by reading the codebase yourself`; }