docs: Add comprehensive GSD agent selection guide

[castrojo]

Summary

• Adds .planning/AGENT-SELECTION-GUIDE.md with detailed guidance on choosing the right GSD agent for different tasks
• Updates AGENTS.md with MANDATORY agent selection checkpoint protocol
• Addresses user feedback: "having a hard time choosing an agent for each gsd task" and "make it so you always remind me when moving between gsd steps"

Contents

Decision Tree:

• Quick flowchart to determine which agent to use

Agent Profiles:

• gsd-debugger (bug investigation)
• gsd-researcher (understanding implementation)
• gsd-planner (task breakdown)
• gsd-executor (systematic implementation)
• quick task (simple changes)

Guidance:

• When to use each agent with concrete examples
• Red flags indicating wrong agent choice
• Common patterns (Research → Plan → Execute)
• Anti-patterns to avoid
• Real session example: The module system disaster

Practical Tools:

• Summary cheat sheet table
• "When to just do it yourself" guidance
• Tips for effective agent use

AGENTS.md Updates (CRITICAL)

Added new section at top of AGENTS.md requiring agents to:

Before starting GSD work:

• Present agent recommendation with reasoning
• List alternatives and when to use them
• Ask user to confirm or choose different approach
• Reference the agent selection guide

When transitioning between phases:

• Summarize what was completed
• Explain what's next
• Recommend appropriate agent with reasoning
• Provide example workflow context
• Ask user to confirm or redirect

Key principles enforced:

• ✅ ALWAYS pause to confirm agent choice
• ✅ ALWAYS explain reasoning
• ✅ ALWAYS offer alternatives
• ❌ NEVER auto-spawn without confirmation

This ensures agents never proceed without user understanding and agreement on approach.

Real Example Documented

Includes detailed analysis of the recent "type": "module" incident:

• What we should have done (use gsd-debugger to investigate)
• What we actually did (trial and error)
• How proper agent selection would have saved 1-2 hours

Target Audience

• Developers working with GSD system
• Anyone struggling to pick the right agent
• Reference for future agent spawning decisions

Files Changed

• .planning/AGENT-SELECTION-GUIDE.md - Comprehensive reference guide (new file)
• AGENTS.md - Added mandatory checkpoint protocol at top