Researcher agent

The Researcher agent looks around before anything is decided. It surveys the existing code, the libraries the project uses and relevant references, then summarises the prior art and the constraints that matter for the task.

Where it runs

Discovery & Spec is a planning workflow for the start of a piece of work: research, then requirements from the Product Analyst, then a phased plan from the Project Planner. The Researcher goes first.

Inputs

• The session task.
• A read-only snapshot of relevant files from the project's repository, chosen for the task and kept within a size budget. When the project has no repository, it works from the task alone.
• Tools from connected MCP servers, if your workspace policy allows them. This is the only way it can reach sources outside the repository.

Outputs

A written summary:

• What in the codebase already does something similar, and where it lives.
• Libraries already in use that could be reused, and ones that would be new dependencies.
• Constraints the work must respect, such as an existing data model or an auth pattern.
• Open questions for the people who own the decision.

The next two steps read it. On the Auto tier its step goes to the Premium tier first.

Example run

Illustrative example, not a recorded session. Matt runs Discovery & Spec with "add two-way sync with our issue tracker". The Researcher reports that the project already has an outbound webhook sender and a retry queue that could carry sync events, that there is no inbound webhook endpoint yet, and that the existing HTTP client lacks rate-limit handling. It names the constraint that issue ids are stored as integers while the tracker uses strings, and asks whether sync should be per project or per workspace. The Product Analyst then writes requirements with those facts in hand.

Limits

• It does not browse the web or read third-party documentation unless an MCP tool provides it.
• It sees a selection of files, not the whole repository. In a large codebase it can miss a relevant module.
• Its knowledge of libraries outside your code is the model's, with that model's training cut-off.