Update codebase-explorer, add file-q-and-a agent

Author: jahooma

.agents/base2/base-layer.ts

@@ -36,6 +36,7 @@ const definition: SecretAgentDefinition = {
     'researcher-web',
     'researcher-docs',
     'thinker',
+    'decomposing-thinker',
     'editor',
     'reviewer',
     'context-pruner',
@@ -77,17 +78,21 @@ Continue to spawn layers of agents until have completed the user's request or re
 
 The user asks you to implement a new feature. You respond in multiple steps:
 
-1. Spawn a 3 file pickers with different prompts to find relevant files; spawn 1 code searcher with a few search queries; spawn 1 docs research to find relevant docs;
+1. Spawn 2 file pickers with different prompts to find relevant files; spawn 2 codebase explorers to find more relevant files and answer questions about the codebase; spawn 1 docs research to find relevant docs;
 1a. Read all the relevant files using the read_files tool.
-2. Spawn 2 more file pickers with different prompts to find relevant files; spawn 1 more code searcher with a few search queries; spawn a thinker with a question on a key decision; spawn a thinker to plan a tricky step.
+2. Spawn 1 more file picker and one more codebase explorer with different prompts to find relevant files; spawn a decomposing thinker with a question on a key decision; spawn a decomposing thinker to plan out the feature part-by-part.
 2a. Read all the relevant files using the read_files tool.
+3. Spawn a decomposing thinker to answer final design and implementation questions.
 4. Spawn 2 editors to implement all the changes.
 5. Spawn a reviewer to review the changes made by the editors.
 
 
 ## Guidelines
 
-- **Sequence agents properly:** Keep in mind dependencies when spawning different agents: spawn a file picker or researcher before a thinker because then the thinker can use the file picker's results to come up with a better conclusions. Reviewers should be spawned after editors.
+- **Sequence agents properly:** Keep in mind dependencies when spawning different agents:
+  - Spawn file pickers, codebase explorers, and researchers before thinkers because then the thinkers can use the file/research results to come up with a better conclusions
+  - Spawn thinkers before editors so editors can use the insights from the thinkers.
+  - Reviewers should be spawned after editors.
 - **Spawn editors later** Only spawn editors after gathering all the context.
 - **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.
 - **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.

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

@@ -17,10 +17,25 @@ const paramsSchema = {
       items: {
         type: 'object' as const,
         properties: {
-          pattern: { type: 'string' as const },
-          flags: { type: 'string' as const },
-          cwd: { type: 'string' as const },
-          maxResults: { type: 'number' as const },
+          pattern: {
+            type: 'string' as const,
+            description: 'The pattern to search for',
+          },
+          flags: {
+            type: 'string' as const,
+            description:
+              'Optional ripgrep flags to customize the search (e.g., "-i" for case-insensitive, "-t ts" for TypeScript files only, "-A 3" for 3 lines after match, "-B 2" for 2 lines before match, "--type-not test" to exclude test files)',
+          },
+          cwd: {
+            type: 'string' as const,
+            description:
+              'Optional working directory to search within, relative to the project root. Defaults to searching the entire project',
+          },
+          maxResults: {
+            type: 'number' as const,
+            description:
+              'Maximum number of results to return per file. Defaults to 15. There is also a global limit of 250 results across all files',
+          },
         },
         required: ['pattern'],
       },

.agents/file-explorer/codebase-explorer.ts

@@ -17,6 +17,7 @@ const codebaseExplorer: SecretAgentDefinition = {
     'code-searcher',
     'directory-lister',
     'glob-matcher',
+    'file-q-and-a',
   ],
   inputSchema: {
     prompt: {
@@ -26,36 +27,12 @@ const codebaseExplorer: SecretAgentDefinition = {
   },
   systemPrompt: `You are a codebase exploration orchestrator. Your job is to spawn multiple specialized agents in parallel waves to comprehensively explore the codebase and answer the user's question.
 
-You have access to these agents:
-
-1. **file-explorer** - Spawns multiple file-picker agents to find relevant files
-   - Takes a prompt and a "prompts" param with 1-4 specific focus areas
-   - Example: { prompts: ["authentication logic", "API endpoints", "database models"] }
-
-2. **code-searcher** - Runs multiple ripgrep searches to find code patterns
-   - Takes a "searchQueries" param with array of search queries
-   - Each query has: pattern (required), flags, cwd, maxResults
-   - Example: { searchQueries: [{ pattern: "class.*Auth", flags: "-t ts" }] }
-
-3. **directory-lister** - Lists contents of multiple directories
-   - Takes a "directories" param with array of directory paths
-   - Each has: path (required)
-   - Example: { directories: [{ path: "src/auth" }, { path: "src/api" }] }
-
-4. **glob-matcher** - Matches multiple glob patterns to find files
-   - Takes a "patterns" param with array of glob patterns
-   - Each has: pattern (required), cwd (optional)
-   - Example: { patterns: [{ pattern: "**/*test*.ts" }, { pattern: "*.config.js" }] }
-
 Strategy:
-1. Analyze the user's question to determine what exploration approach would be most effective
-2. Spawn multiple agents in parallel in the first wave to gather information from different angles
-3. Based on the results, you can spawn additional agents in subsequent waves if needed to fill gaps
-4. Synthesize all findings into a comprehensive answer`,
-
-  instructionsPrompt: `Analyze the user's prompt and spawn appropriate exploration agents in parallel.
+1. Analyze the user's question to determine what exploration approach would be most effective.
+2. You may spawn agents to help you answer the user's question. Feel free to spawn multiple agents in parallel to gather information from different angles.
+3. Synthesize all findings into a comprehensive answer.`,
 
-After reviewing the results, spawn additional agents if needed to fill gaps.
+  instructionsPrompt: `Analyze the user's prompt and spawn appropriate exploration agents.
 
 Finally, synthesize all findings into a comprehensive answer.`,
 }

.agents/file-explorer/file-q-and-a.ts

@@ -0,0 +1,61 @@
+import { publisher } from '../constants'
+
+import type { SecretAgentDefinition } from '../types/secret-agent-definition'
+import type { ToolCall } from 'types/agent-definition'
+
+const paramsSchema = {
+  type: 'object' as const,
+  properties: {
+    filePath: {
+      type: 'string' as const,
+      description: 'Path to the file to ask questions about',
+    },
+  },
+  required: ['filePath'],
+}
+
+const fileQAndA: SecretAgentDefinition = {
+  id: 'file-q-and-a',
+  displayName: 'Quinn the File Q&A',
+  spawnerPrompt:
+    'Reads a single file and answers questions about it - can summarize, explain specific parts, or excerpt portions of the file',
+  model: 'x-ai/grok-4-fast',
+  publisher,
+  outputMode: 'last_message',
+  includeMessageHistory: false,
+  toolNames: ['read_files'],
+  spawnableAgents: [],
+  inputSchema: {
+    prompt: {
+      type: 'string',
+      description:
+        'A question about the file - can ask for a summary, explanation of specific functionality, or an excerpt of a particular section',
+    },
+    params: paramsSchema,
+  },
+  systemPrompt:
+    'You are an expert at reading and analyzing code files. Answer questions about files clearly and accurately. You can provide summaries, explain specific functionality, or excerpt portions of the file. When excerpting, reproduce the code exactly as it appears in the file.',
+  instructionsPrompt: `
+Read the file and answer the user's question about it. Depending on what they're asking:
+- For summaries: explain the main purpose, key functions/classes/exports, and important patterns
+- For specific questions: focus on the relevant parts and provide clear explanations
+- For excerpts: reproduce the requested code exactly as it appears in the file
+  `.trim(),
+  stepPrompt: 'Do not use any tools again. Just answer the question about the file.',
+
+  handleSteps: function* ({ prompt, params }) {
+    const filePath = params?.filePath
+    if (!filePath) {
+      throw new Error('filePath parameter is required')
+    }
+
+    yield {
+      toolName: 'read_files',
+      input: { paths: [filePath] },
+    } satisfies ToolCall
+
+    yield 'STEP_ALL'
+  },
+}
+
+export default fileQAndA