Tighten subagent guidance around Explore's evidence-only role

[m-aebrer]

Summary

Tighten the generated system prompt's subagent guidance so it presents delegation as an optional, role-matched tool rather than an unconditional default. In particular, define the default Explore agent as a concrete evidence-retrieval agent and explicitly keep root-cause diagnosis, requirements interpretation, design, and implementation planning with the primary agent.

Explore agents remain useful in every workflow mode, including issue creation. The problem is not their use; it is assigning them ownership of abstract diagnosis or planning instead of concrete codebase and documentation retrieval.

Current Behavior

The subagent tool currently injects this imperative into the system prompt:

Use subagent to delegate focused, independent tasks to child agents

The default agent description is broad:

Codebase and web exploration — find files, search code, search the web, answer questions. Read-only.

The model-routing guideline further says:

Most subagent tasks (exploration, file discovery, grep, navigation, summarization) are handled well by the defaults.

Together, phrases such as "answer questions," "exploration," and "summarization" leave enough latitude for the primary agent to delegate prompts such as "investigate the root cause" or "plan the implementation" to the default Explore agent. That loses primary-agent ownership of the substantive conclusion and can import confident but incorrect synthesis.

The repository already states the intended boundary more clearly in the model-routing-guide skill:

Explore is for factual collection, codebase navigation, file discovery, web research, and answering bounded questions. Planning, architecture ownership, implementation, editing, and feature development are not Explore work.

The generated system prompt should enforce the same role boundary directly rather than depending on a separately invoked skill or local memory.

Proposed Behavior

Replace the unconditional delegation instruction with capability-oriented guidance along these lines:

subagent can be used to delegate focused, independent work that matches a child agent's defined role. When no agent type is specified, the default is Explore, which is intended for concrete evidence gathering: locating relevant files or documentation, enumerating call sites, and returning exact code snippets.

Add an explicit ownership boundary:

Do not ask the default Explore agent to diagnose root causes, interpret ambiguous requirements, make architecture or design decisions, recommend an implementation, or produce an implementation plan. The primary agent must synthesize the evidence and own those conclusions.

Include concrete examples:

Good Explore tasks:

• Find every file that renders a named component.
• List tests covering a specific behavior.
• Quote the code that limits a rendered collection.
• Locate documented examples of an existing UI pattern.
• Enumerate call sites or trace an explicit data flow.

Bad Explore tasks:

• Investigate or determine the root cause.
• Decide how an ambiguous behavior should work.
• Recommend the best implementation.
• Design an architecture or refactor.
• Produce an implementation plan.

Also clarify that parallel and chain modes do not make an otherwise role-inappropriate task suitable for Explore. Specialized agents should continue to perform the work described by their own definitions.

Acceptance Criteria

• The generated system prompt no longer unconditionally tells the primary agent to delegate focused tasks.
• The prompt explicitly states that omitting agent selects the default Explore agent.
• Explore is defined in terms of concrete retrieval: files, symbols, documentation, call sites, exact snippets, and other bounded evidence.
• The prompt explicitly prohibits assigning root-cause diagnosis, ambiguous-requirement interpretation, architecture/design decisions, implementation recommendations, and implementation planning to default Explore agents.
• The prompt states that the primary agent owns synthesis and final conclusions from Explore evidence.
• Positive and negative examples make the retrieval-versus-synthesis boundary concrete.
• Parallel and chain guidance requires role fit before delegation.
• Specialized agent roles remain available and are not incorrectly restricted by the default Explore boundary.
• The bundled Explore description and system prompt align with the tightened guidance.
• User-facing subagent documentation is updated consistently.
• Tests assert that the generated prompt contains the role boundary and no longer contains the unconditional delegation wording.

Technical Notes

Relevant implementation and documentation:

• packages/coding-agent/src/core/tools/subagent.ts
  • Tool description
  • promptSnippet
  • promptGuidelines
• packages/coding-agent/agents/explore.md
  • Broad description ending in "answer questions"
  • Minimal body that currently defines only read-only behavior
• packages/coding-agent/test/subagent-model-fallback.test.ts
  • Existing promptGuidelines assertions
• packages/coding-agent/test/system-prompt.test.ts
  • Generated prompt coverage
• packages/coding-agent/README.md and the root README.md
  • User-facing subagent documentation
• packages/coding-agent/skills/model-routing-guide/SKILL.md
  • Existing role-fit language to align with

This should be a prompt and role-definition correction, not a runtime ban on Explore usage and not a restriction tied to CREATE versus ASSESS workflows.