planning-agents-guide

Planning Agents Guide

Purpose: Comprehensive guide to the planning agent ecosystem — when to use each agent, how they integrate, and best practices for DDD, story mapping, prioritization, contract testing, and ADRs.

---

Overview

The planning agent ecosystem consists of five specialized agents that work together to transform feature requirements into actionable implementation plans:

1. ArchitectureAnalyzer — DDD-driven architecture analysis
2. StoryMapper — User journey mapping and story decomposition
3. PrioritizationEngine — RICE/WSJF scoring and MVP identification
4. ContractManager — API contract definition for parallel development
5. ADRManager — Architecture decision record management

Key Principle: Each agent is context-aware and ALWAYS calls ContextScout before executing to ensure alignment with project standards.

---

Quick Decision Tree

Feature Request
    │
    ├─ Complex domain logic? ──YES──> ArchitectureAnalyzer
    │                          NO
    │                          ↓
    ├─ User journey unclear? ──YES──> StoryMapper
    │                          NO
    │                          ↓
    ├─ Need prioritization? ──YES──> PrioritizationEngine
    │                          NO
    │                          ↓
    ├─ Parallel dev needed? ──YES──> ContractManager
    │                          NO
    │                          ↓
    └─ Architectural decision? ─YES──> ADRManager

---

1. ArchitectureAnalyzer

When to Use

Use ArchitectureAnalyzer when:

• Feature spans multiple domains or business capabilities
• Need to identify bounded contexts before task breakdown
• Complex domain logic requires aggregate/entity modeling
• Module boundaries are unclear or need formalization
• Feature involves cross-context integration
• Need to establish architectural constraints before implementation

Do NOT use when:

• Feature is purely technical (no domain logic)
• Single, well-defined module with clear boundaries
• Simple CRUD operations with no complex domain rules
• Architecture is already well-defined and documented