Auto-research & Goals
Relevant source files
The following files were used as context for generating this wiki page:
- packages/coding-agent/src/prompts/agents/plan.md
- packages/coding-agent/src/prompts/agents/explore.md
- packages/coding-agent/src/prompts/system/plan-mode-active.md
- packages/coding-agent/src/prompts/system/orchestrate-notice.md
- packages/coding-agent/src/prompts/agents/librarian.md
- packages/coding-agent/src/prompts/agents/init.md
The Auto-research & Goals system provides a structured framework for autonomous investigation and task management within the coding agent harness. It enables the agent to decompose complex user requests into verifiable milestones, explore unfamiliar codebases via specialized scouts, and research external dependencies with source-grounded accuracy. This system is primary governed by orchestration logic that manages subagents and specialized research personas like the librarian and explore agents.
At its core, the system utilizes a Plan-Execute-Verify cycle. It transforms high-level objectives into a serialized or parallelized set of goals tracked via a todo tool. By leveraging "Plan Mode," the system ensures that complex architectural decisions are grounded in discovered facts before any state-changing modifications occur.
Architectural Overview
The architecture relies on a hierarchy of agents where an orchestrator or "Plan" agent delegates specific research tasks to specialized subagents.
The Research Pipeline
Research is categorized into internal codebase scouting and external library investigation.
- Internal Scouting: Handled by
exploreagents that perform rapid, read-only scans of the project structure, imports, and data flows. - External Research: Handled by
librarianagents that clone external repositories or read localnode_modulesto verify API signatures and behaviors against actual source code rather than stale documentation.
The following diagram illustrates the delegation flow from a high-level goal to specialized research agents:
The diagram shows how the Orchestrator uses the todo tool to manage research tasks before synthesizing them into a final plan.
Sources: packages/coding-agent/src/prompts/system/orchestrate-notice.md:25-30, packages/coding-agent/src/prompts/agents/plan.md:14-22
Goal Management and Orchestration
Goals are managed through a centralized orchestration contract that emphasizes decomposition and verification. The system is designed to "fan out" work to task subagents rather than performing substantial edits within the main context.
Orchestration Principles
- Maximizing Parallelism: The orchestrator must dispatch all parallelizable units in one message via multiple
taskcalls to avoid serial delays. - Verification Gates: Every goal or phase must pass specific gates (e.g.,
bun check,bun test,lsp diagnostics) before the system proceeds to the next milestone. - Goal Persistence: The
todotool is the source of truth for the current state of the request. The orchestrator must never yield until every item in thetodolist is closed.
Sources: packages/coding-agent/src/prompts/system/orchestrate-notice.md:43-60, packages/coding-agent/src/prompts/system/orchestrate-notice.md:82-90
Goal State Transitions
| Phase | Action | Responsibility |
|---|---|---|
| Ingest | Read referenced files and check git status | Orchestrator |
| Plan | Materialize work surface in todo as ordered phases | Orchestrator / Plan Agent |
| Dispatch | Launch parallel task subagents for specific goals | Subagents |
| Verify | Run type checks and tests on subagent results | Orchestrator |
| Finalize | Close todo items and yield terse status | Orchestrator |
Sources: packages/coding-agent/src/prompts/system/orchestrate-notice.md:92-105
Specialized Research Agents
The Explore Agent
The explore agent is a fast, read-only scout designed to return "compressed context." It avoids reading full files unless they are small and focuses on identifying types, interfaces, and dependencies.
- Tools:
read,grep,glob,web_search. - Output: Returns a summary of findings, architectural connections, and relevant file paths with line ranges.
- Strategy: Uses broad pattern matching and follows imports to map unknown code.
Sources: packages/coding-agent/src/prompts/agents/explore.md:1-20
The Librarian Agent
The librarian researches external APIs by treating source code as the "source of truth." It prioritizes locally installed node_modules before attempting to clone external repositories into /tmp/.
The sequence shows the Librarian's preference for local source verification before falling back to external cloning.
Sources: packages/coding-agent/src/prompts/agents/librarian.md:45-75
Plan Mode and Execution Specs
For complex architectural changes, the system enters "Plan Mode." A plan is defined as an execution spec, not just a design document. It must be written so that a competent implementer can execute it top-to-bottom without making further design decisions.
Plan Structure Requirements
A valid implementation plan must include:
- Context: The literal request and intended end state.
- Approach: Ordered steps with concrete edits (verb + target + behavior).
- Critical Files: A limited list (≤5) of files that disambiguate non-obvious work.
- Verification: Exact commands and expected observable outputs to prove the change works.
Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:15-25, packages/coding-agent/src/prompts/system/plan-mode-active.md:95-120
Fact Discovery in Planning
The system mandates that every path, symbol, and signature stated as a fact in a plan must be grounded in discovery during the session. Guesses must be marked as unverified — confirm first.
Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:65-75
Summary
Auto-research & Goals enables the coding agent to handle high-uncertainty tasks by decomposing them into verifiable research and implementation phases. Through the use of specialized agents like the explore scout and the source-verifying librarian, the system ensures all implementation plans are grounded in code reality rather than speculative training data. The orchestration layer enforces rigorous verification gates, ensuring that goals are only marked as complete when the project's integrity (types, tests, and diagnostics) is maintained.