Update more prompts based on Buffy's feedback

Author: jahooma

.agents/base2/base2.ts

@@ -89,7 +89,7 @@ export function createBase2(
 - **Proactiveness:** Fulfill the user's request thoroughly, including reasonable, directly implied follow-up actions.
 - **Confirm Ambiguity/Expansion:** Do not take significant actions beyond the clear scope of the request without confirming with the user. If asked *how* to do something, explain first, don't just do it.
 - **Stop and ask for guidance:** You should feel free to stop and ask the user for guidance if you're stuck or don't know what to try next, or need a clarification.
-- **Be careful about terminal commands:** Be careful about instructing subagents to run terminal commands that could be destructive or have effects that are hard to undo (e.g. git push, running scripts that could alter production environments, installing packages globally, etc). Don't do any of these unless the user explicitly asks you to.
+- **Be careful about terminal commands:** Be careful about instructing subagents to run terminal commands that could be destructive or have effects that are hard to undo (e.g. git push, git commit, running any scripts -- especially ones that could alter production environments (!), installing packages globally, etc). Don't do any of these unless the user explicitly asks you to.
 - **Do what the user asks:** If the user asks you to do something, even running a risky terminal command, do it.
 
 # Code Editing Mandates
@@ -121,12 +121,11 @@ export function createBase2(
 Use the spawn_agents tool to spawn specialized agents to help you complete the user's request.
 
 - **Spawn multiple agents in parallel:** This increases the speed of your response **and** allows you to be more comprehensive by spawning more total agents to synthesize the best response.
-- **Sequence agents properly:** Keep in mind dependencies when spawning different agents. Don't spawn agents in parallel that depend on each other. Be conservative sequencing agents so they can build on each other's insights:
+- **Sequence agents properly:** Keep in mind dependencies when spawning different agents. Don't spawn agents in parallel that depend on each other.
   - Spawn file pickers, code-searcher, directory-lister, glob-matcher, commanders, and web/docs researchers before making edits.
   ${buildArray(
     `- Spawn a ${isGpt5 ? 'editor-best-of-n-gpt-5' : 'editor-best-of-n'} agent to implement the changes after you have gathered all the context you need.`,
   ).join('\n  ')}
-- **Spawn with the correct prompt and/or params:** Each agent has a schema for the input it expects. The prompt is a string, and the params is a json object. Some agents require prompts and/or params, and some require you to NOT include any input prompt or params.
 - **No need to include context:** When prompting an agent, realize that many agents can already see the entire conversation history, so you can be brief in prompting them without needing to include context.
 
 # Codebuff Meta-information
@@ -139,11 +138,13 @@ The user can use the "/usage" command to see how many credits they have used and
 
 For other questions, you can direct them to codebuff.com, or especially codebuff.com/docs for detailed information about the product.
 
-
-# Response guidelines
+# Other response guidelines
 
 ${buildArray(
-  "- NEVER write out <tool_result> tags in your response. Tools will automatically append the results of their tool calls for you -- it's not something you need to do.",
+  '- Your goal is to produce the highest quality results, even if it comes at the cost of more credits used.',
+  '- Speed is a secondary goal.',
+  '- If a tool fails, try again, or try a different tool or approach.',
+  '- Context is managed for you. The context-pruner agent will automatically run as needed. Gather as much context as you need without worrying about it.',
   isSonnet &&
     `- **Don't create a summary markdown file:** The user doesn't want markdown files they didn't ask for. Don't create them.`,
   '- **Keep final summary extremely concise:** Write only a few words for each change you made in the final summary.',
@@ -200,7 +201,7 @@ ${PLACEHOLDER.GIT_CHANGES_PROMPT}
   }
 }
 
-const EXPLORE_PROMPT = `- Spawn file pickers, code-searcher, directory-lister, glob-matcher, commanders, and web/docs researchers to gather context as needed. The file-picker agent in particular is very useful to find relevant files -- try spawning multiple in parallel to explore different parts of the codebase. Read all the relevant files using the read_files tool. Read as many files as possible so that you have comprehensive context on the user's request.`
+const EXPLORE_PROMPT = `- Iteratively spawn file pickers, code-searchers, directory-listers, glob-matchers, commanders, and web/docs researchers to gather context as needed. The file-picker agent in particular is very useful to find relevant files -- try spawning multiple in parallel (say, 2-5) to explore different parts of the codebase. Use read_subtree if you need to grok a particular part of the codebase. Read all the relevant files using the read_files tool. Read as many files as possible so that you have comprehensive context on the user's request.`
 
 function buildImplementationInstructionsPrompt({
   isSonnet,
@@ -225,10 +226,10 @@ The user asks you to implement a new feature. You respond in multiple steps:
 
 ${buildArray(
   EXPLORE_PROMPT,
-  `- Important: Read as many files as could possibly be relevant to the task to improve your understanding of the user's request and produce the best possible code changes. This is frequently 12-20 files, depending on the task.`,
-  `- For multi-step tasks, use the write_todos tool to write out your step-by-step implementation plan. Include ALL of the applicable tasks in the list.${hasNoValidation ? '' : ' You should include at least one step to validate/test your changes: be specific about whether to typecheck, run tests, run lints, etc.'} Skip write_todos for trivial tasks like single-line edits or simple questions.`,
+  `- Important: Read as many files as could possibly be relevant to the task over several steps to improve your understanding of the user's request and produce the best possible code changes. Find more examples within the codebase similar to the user's request, dependencies that help with understanding how things work, tests, etc. This is frequently 12-20 files, depending on the task.`,
+  `- For multi-step tasks (3+ steps), use the write_todos tool to write out your step-by-step implementation plan. Include ALL of the applicable tasks in the list.${hasNoValidation ? '' : ' You should include at least one step to validate/test your changes: be specific about whether to typecheck, run tests, run lints, etc.'} Skip write_todos for simple tasks like quick edits or answering questions.`,
   !isFast &&
-    `- You must spawn the ${isGpt5 ? 'editor-best-of-n-gpt-5' : 'editor-best-of-n'} agent to implement non-trivial code changes, since it will generate the best code changes from multiple implementation proposals. This is the best way to make high quality code changes -- strongly prefer using this agent over the str_replace or write_file tools, unless the change is very small and trivial.`,
+    `- You must spawn the ${isGpt5 ? 'editor-best-of-n-gpt-5' : 'editor-best-of-n'} agent to implement non-trivial code changes, since it will generate the best code changes from multiple implementation proposals. This is the best way to make high quality code changes -- strongly prefer using this agent over the str_replace or write_file tools, unless the change is very straightforward and obvious.`,
   !hasNoValidation &&
     `- Test your changes${isMax ? '' : ' briefly'} by running appropriate validation commands for the project (e.g. typechecks, tests, lints, etc.).${isMax ? ' Start by type checking the specific area of the project that you are editing and then test the entire project if necessary.' : ' If you can, only typecheck/test the area of the project that you are editing, rather than the entire project.'} You may have to explore the project to find the appropriate commands. Don't skip this step!`,
   `- Inform the user that you have completed the task in one sentence or a few short bullet points.${isSonnet ? " Don't create any markdown summary files or example documentation files, unless asked by the user." : ''}`,

.agents/base2/best-of-n/editor-best-of-n.ts

@@ -14,11 +14,9 @@ export function createBestOfNEditor(
   return {
     publisher,
     model: isGpt5 ? 'openai/gpt-5' : 'anthropic/claude-sonnet-4.5',
-    displayName: isGpt5
-      ? 'Best-of-N GPT-5 Implementation Editor'
-      : 'Best-of-N Fast Implementation Editor',
+    displayName: isGpt5 ? 'Best-of-N GPT-5 Editor' : 'Best-of-N Editor',
     spawnerPrompt:
-      'Edits code by orchestrating multiple implementor agents to generate implementation proposals, selects the best one, and applies the changes. Do not specify an input prompt for this agent; it reads the context from the message history.',
+      'Edits code by orchestrating multiple implementor agents to generate implementation proposals, selects the best one, and applies the changes. Do not specify an input prompt for this agent; it inherits the context of the entire conversation with the user. Make sure to read any files intended to be edited before spawning this agent.',
 
     includeMessageHistory: true,
     inheritParentSystemPrompt: true,

.agents/file-explorer/code-searcher.ts

@@ -49,7 +49,7 @@ const codeSearcher: SecretAgentDefinition = {
   id: 'code-searcher',
   displayName: 'Code Searcher',
   spawnerPrompt:
-    'Mechanically runs multiple code search queries (using ripgrep line-oriented search) and returns all results',
+    'Mechanically runs multiple code search queries (using ripgrep line-oriented search) and returns up to 250 results across all source files, showing each line that matches the search pattern. Excludes git-ignored files.',
   model: 'anthropic/claude-sonnet-4.5',
   publisher,
   includeMessageHistory: false,

.agents/file-explorer/file-picker.ts

@@ -17,7 +17,7 @@ const definition: SecretAgentDefinition = {
     exclude: false,
   },
   spawnerPrompt:
-    'Spawn to find relevant files in a codebase related to the prompt. Cannot do string searches on the codebase, but does a fuzzy search. Unless you know which directories are relevant, omit the directories parameter. This agent is extremely effective at finding files in the codebase that could be relevant to the prompt.',
+    'Spawn to find relevant files in a codebase related to the prompt. Outputs up to 12 file paths with short summaries for each file. Cannot do string searches on the codebase, but does a fuzzy search. Unless you know which directories are relevant, omit the directories parameter. This agent is extremely effective at finding files in the codebase that could be relevant to the prompt.',
   inputSchema: {
     prompt: {
       type: 'string',

packages/agent-runtime/src/templates/prompts.ts

@@ -66,17 +66,20 @@ params: None`
 
   return `\n\n## Spawnable Agents
 
-Use the spawn_agents tool to spawn agents to help you complete the user request. Below are the *only* available agents by their agent_type. Other agents may be referenced earlier in the conversation, but they are not available to you.
+Use the spawn_agents tool to spawn agents to help you complete the user request.
 
-Note: You can not call the agents as tool names directly: you must use the spawn_agents tool with the correct parameters to spawn them!
+Notes:
+- You can not call the agents as tool names directly: you must use the spawn_agents tool with the correct parameters to spawn them!
+- There are two types of input arguments for agents: prompt and params. The prompt is a string, and the params is a json object. Some agents require only one or the other, some require both, and some require none.
+- Below are the *only* available agents by their agent_type. Other agents may be referenced earlier in the conversation, but they are not available to you.
 
 Example:
 
 ${getToolCallString('spawn_agents', {
   agents: [
     {
       agent_type: 'example-agent',
-      prompt: 'Example prompt for the example agent',
+      prompt: 'Do an example task for me',
     },
   ],
 })}

packages/agent-runtime/src/tools/definitions/tool/read-subtree.ts

@@ -13,5 +13,8 @@ ${getToolCallString(toolName, {
 })}
 
 Purpose: Read a directory subtree and return a blob containing subdirectories, file names, and parsed variable/functions names from source files. For files, return only the parsed variable names. If no paths are provided, returns the entire project tree. The output is truncated to fit within the provided token budget.
+
+- Use this tool on particular subdirectories when you need to know all the nested files and directories. E.g. for a refactoring task, or to understand a particular part of the codebase.
+- In normal use, don't set maxTokens beyond 10,000.
     `.trim(),
 } satisfies ToolDescription