feat: better prompts, protocols, and tests

[ian-pascoe]

This pull request introduces a comprehensive plan for improving agent swarm capabilities, focusing on enabling agents in mode: 'all' to handle direct user requests more flexibly and robustly. The plan details phased tasks, protocol enhancements, prompt modifications for multiple agents, temperature tuning for improved output quality, and thorough verification steps. Additionally, a review document is included, confirming that agent and MCP references are properly gated, with a few minor warnings and actionable items noted.

Agent Swarm Improvements Plan:

Major themes and changes:

1. Protocol and Prompt Enhancements

• Introduces two new protocols—clarification and scopeAssessment—to improve how agents handle ambiguous or complex user requests, following the established Prompt.template pattern.
• Expands agent prompts across all major agents (executor, planner, reviewer, designer, documenter, architect, consultant, orchestrator) to handle direct user requests, clarify ambiguity, and support ad-hoc workflows, while maintaining backward compatibility. Each agent receives new or updated prompt sections tailored to its role, e.g., <direct_request_handling>, <ad_hoc_review>, <spec_iteration>, etc.

2. Configuration Adjustments

• Lowers the default temperature in explorer.ts from 0.7 to 0.4 and in researcher.ts from 0.7 to 0.5 to encourage more focused and deterministic responses.

3. Verification and Testing

• Outlines a final verification phase requiring all TypeScript code to typecheck, lint, and build successfully, and specifies behavioral tests for each agent's new capabilities.

4. Risks and Mitigations

• Identifies potential risks (e.g., prompt length, over-clarification, temperature changes, backward compatibility) and mitigation strategies, ensuring a cautious and maintainable rollout.

Review of Agent Prompt Gating:

1. Gating and Reference Safety

• Confirms all agent, MCP, and tool references in prompts are properly gated with capability and availability checks, following best practices (e.g., `Prompt.when(canDelegate,