Epic Planner Agent

The Epic Planner agent (EPIC-PLANNER) is your feature decomposition specialist. It breaks down large features into properly scoped epics and stories with clear acceptance criteria, estimates, dependencies, and agent assignments.

Capabilities

• Break features into 3-8 story epics with clear goals
• Write Given/When/Then acceptance criteria for each story
• Estimate story complexity (0.5d, 1d, 2d)
• Map dependencies between stories
• Extract architecture context from design documents
• Assign stories to specialized agents (AG-UI, AG-API, AG-CI, AG-DEVOPS)
• Create test stubs aligned with acceptance criteria
• Update status.json and coordinate via bus/log.jsonl

When to Use

Use the Epic Planner agent when:

• You have a large feature request to decompose into smaller stories
• You need help estimating story complexity
• You want to plan dependencies between stories
• You need to extract architecture context for developer guidance
• You're unsure how to break work across team members
• You want to ensure stories follow INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)

How It Works

1. Context Loading: Agent reads expertise, status.json, roadmap, and architecture docs
2. Clarification: Agent asks about feature scope, constraints, and priorities
3. Research: Agent checks docs/10-research/ for relevant patterns
4. Planning: Agent proposes epic structure with 3-8 child stories
5. Architecture Extraction: Agent pulls relevant architecture context with source citations
6. Definition of Ready: Agent ensures each story has AC, test stub, and no blockers
7. Creation: Agent creates epic/story files, test stubs, and updates status.json
8. Coordination: Agent appends assign messages to bus/log.jsonl
9. Self-Improvement: Agent runs self-improve.md to update expertise

Example

Copy# Via /babysit (recommended)
/agileflow:babysit
> "I need to plan the user authentication feature"

The Epic Planner will:

1. Ask clarifying questions (JWT vs session? Social login? MFA?)
2. Check docs/04-architecture/ for auth patterns already documented
3. Propose: EP-0015: User Authentication (5 stories)
   • US-0150: Setup JWT infrastructure (AG-API, 1d)
   • US-0151: Implement login endpoint (AG-API, 1d)
   • US-0152: Create login form (AG-UI, 1d)
   • US-0153: Implement logout (AG-API, 0.5d)
   • US-0154: Add auth tests (AG-CI, 1d)
4. Write acceptance criteria for each story
5. Identify dependencies (form depends on endpoint)
6. Create files with architecture context included
7. Update status.json with all 5 stories marked as "ready"

Or spawn directly:

CopyTask(
  description: "Plan the payment processing feature",
  prompt: "Break into stories with AC and estimates. Stripe integration required.",
  subagent_type: "agileflow-epic-planner"
)

Key Behaviors

• INVEST Criteria: Every story is Independent, Negotiable, Valuable, Estimable, Small, Testable
• 0.5-2 Day Estimates: Stories should be completable in a single work session
• Vertical Slices: Each story delivers user-visible value when possible
• Architecture Context Extraction: Includes relevant sections from docs/04-architecture/ with source citations
• Source Citations: Every technical detail includes [Source: architecture/file.md#section] for verification
• Definition of Ready: Each story has AC, test stub, no blockers, and agent assignment
• Autonomous Commands: Directly invokes /agileflow:board, /agileflow:velocity, /agileflow:research:ask
• Status Updates: Creates stories with status=ready in docs/09-agents/status.json
• Bus Messages: Appends "assign" messages for each story to docs/09-agents/bus/log.jsonl

Tools Available

This agent has access to: Read, Write, Edit, Glob, Grep

Acceptance Criteria Format

Every story uses Given/When/Then format for clarity:

Copy## Acceptance Criteria
 
- **Given** a user is logged out
  **When** they click "Login"
  **Then** the login form appears with email and password fields
 
- **Given** valid credentials entered
  **When** they click "Sign In"
  **Then** they're redirected to dashboard and JWT token is stored
 
- **Given** invalid credentials
  **When** they click "Sign In"
  **Then** error message displays and form remains visible

Estimation Guidelines

• 0.5d: Simple component, basic CRUD endpoint, config change, bug fix
• 1d: Moderate component with state, API endpoint with tests, small feature
• 2d: Complex feature, integration with external service, significant refactoring
• >2d: Break into smaller stories (violates size principle)

Agent Assignment Guide

When creating stories, assign based on scope:

• AG-UI: Frontend components, styling, design systems, accessibility, user interactions
• AG-API: Backend endpoints, business logic, data models, database access, integrations
• AG-CI: Test infrastructure, CI/CD pipelines, linting, code coverage, quality gates
• AG-DEVOPS: Dependencies, deployment, technical debt, impact analysis, changelogs

Cross-Agent Stories: If a story spans multiple agents (full-stack), break into separate stories with documented dependency.

Architecture Context Extraction

When creating stories, EPIC-PLANNER automatically extracts relevant architecture context:

1. Identifies Relevant Sections: Reads story type (Backend/Frontend/Full-Stack) and finds matching docs
2. Extracts Only Relevant Details: Includes data models, API specs, component patterns, file paths
3. Cites All Sources: Every detail includes [Source: docs/04-architecture/{filename}.md#{section}]
4. Never Invents Details: Only extracts from actual architecture docs
5. Includes Previous Story Insights: If related story exists, extracts lessons learned

Example architecture context in story:

Copy### Data Models & Schemas
User model with fields: id, email, password_hash, created_at, updated_at
[Source: architecture/data-models.md#user-model]
 
### API Specifications
POST /api/auth/login: Accepts email/password, returns JWT token
[Source: architecture/api-spec.md#authentication]
 
### File Locations
Backend services: src/services/auth.ts following naming convention
[Source: architecture/project-structure.md#services]

Key Files

• Expertise: packages/cli/src/core/experts/epic-planner/expertise.yaml (agent memory)
• Workflow: packages/cli/src/core/experts/epic-planner/workflow.md (Plan → Build → Self-Improve)
• Epics: docs/05-epics/ (epic definitions)
• Stories: docs/06-stories/ (user stories organized by epic)
• Test Stubs: docs/07-testing/test-cases/ (one per story)
• Status: docs/09-agents/status.json (story tracking)
• Bus: docs/09-agents/bus/log.jsonl (coordination messages)
• Architecture: docs/04-architecture/ (extract context with citations)
• Research: docs/10-research/ (check before planning)
• Roadmap: docs/08-project/roadmap.md (priorities)

Workflow Steps

1. Load Expertise: Read expertise.yaml
2. Check Capacity: Review status.json for team WIP limits
3. Check Priorities: Read docs/08-project/roadmap.md
4. Check Research: Review docs/10-research/ for relevant patterns
5. Clarify Scope: Ask user about feature boundaries
6. Propose Epic: Suggest epic structure with 3-8 stories
7. Extract Architecture: Pull context from docs/04-architecture/ with citations
8. Show Preview: Display diff for review
9. Create Files: Epic, stories (with architecture context), test stubs
10. Update Status: Add stories to docs/09-agents/status.json as "ready"
11. Update Bus: Append "assign" messages
12. Self-Improve: Run self-improve.md after completion

Quality Checklist

Before finalizing stories:

• Epic has clear goal and success metrics
• Each story has 2-5 testable acceptance criteria
• Estimates are realistic (0.5-2d range)
• All dependencies identified and documented
• Owners assigned based on scope (UI, API, CI, DevOps)
• Test stubs reference acceptance criteria
• Architecture context extracted with source citations
• Stories marked as "ready" in status.json
• Assign messages appended to bus/log.jsonl

Related Agents

• mentor - Orchestrates overall workflow, delegates planning to Epic Planner
• api - Implements API/backend stories created by Epic Planner
• ui - Implements UI/frontend stories created by Epic Planner