epic-template

name	epic-template
description	Epic and task structure patterns for SpecFlux. Use when breaking PRDs into epics and tasks. Epics should be self-contained with clear acceptance criteria.

Epic & Task Templates

When breaking down PRDs into epics and tasks, follow these patterns.

Design Principles

1. Self-contained epics - AI should be able to implement from epic alone
2. Independent first - Create non-dependent epics before dependent ones
3. Testable criteria - Every acceptance criterion must be verifiable
4. 1-4 hour tasks - Tasks should be completable in one session

Epic Structure

API Format

{
  "title": "User Authentication",
  "description": "## Overview\n...",
  "prdRef": "SPEC-P1",
  "acceptanceCriteria": [
    {"criteria": "Users can self-register with email/password"},
    {"criteria": "Users can log in with existing credentials"},
    {"criteria": "Password reset flow works end-to-end"}
  ]
}

CRITICAL: acceptanceCriteria must be [{"criteria": "..."}, ...] NOT ["...", ...]

Description Template (Agent-Optimized)

Use structured format for efficient agent consumption. Every word costs context window tokens.

## Context
- Tech stack: {relevant technologies}
- Database: {relevant tables/schemas with file:line refs}
- Related code: {directory or file paths}

## Scope
- {What's included - bullet points}
- {Another inclusion}

## NOT in scope
- {Explicit exclusion to prevent scope creep}
- {Another exclusion}

Format Principles:

Principle	Rationale
Bullet points over paragraphs	Faster to parse, less ambiguity
File:line references	Agent can jump directly to code (e.g., src/auth/User.java:42)
Explicit NOT in scope	Prevents scope creep, saves iterations
No redundant context	PRD is linked, don't repeat it

Validation: If description exceeds 500 characters without structured sections, it's likely too verbose.

Acceptance Criteria Guidelines

Good criteria (outcome-focused):

• "Users can complete registration in under 60 seconds"
• "Users can recover access without support intervention"
• "Profile changes persist across sessions"

Bad criteria (too implementation-focused):

• "API returns 200 status code" → belongs in task
• "Use bcrypt for password hashing" → belongs in task
• "Add button to header" → too vague

Epic Dependencies

Order epics by dependencies:

E1: User Authentication (independent - foundation)
    ↓
E2: User Profile (depends on E1 - needs auth)
    ↓
E3: Team Management (depends on E1, E2)

Create independent epics FIRST, then dependent ones.

Task Structure

API Format

{
  "epicRef": "SPEC-E1",
  "title": "Create user database schema",
  "description": "## Objective\n...",
  "priority": "HIGH"
}

Description Template (Agent-Optimized)

Use structured format for agent efficiency. Include specific file paths.

## Files
- Modify: {existing file paths}
- Create: {new file paths}
- Reference: {files to read for context}

## Implementation
- {Step 1}
- {Step 2}

Example:

## Files
- Modify: src/controllers/AuthController.java:85
- Modify: src/services/AuthService.java
- Create: src/dto/LoginRequest.java
- Reference: src/config/SecurityConfig.java

## Implementation
- Add POST /auth/login endpoint
- Validate email/password format
- Return JWT on success, 401 on failure

File Reference Conventions:

• Use file:line for specific locations (e.g., AuthController.java:85)
• Use file for general references (e.g., AuthService.java)
• Use directories for broader scope (e.g., src/auth/)

Acceptance Criteria for Tasks

Each criterion should be testable. Tag with test type:

[Unit] hashPassword returns bcrypt hash with cost 12
[Integration] POST /auth/register returns 201 for valid input
[Integration] POST /auth/register returns 409 for duplicate email
[E2E] User completes registration and sees dashboard

Task Size Guidelines

Size	Duration	Scope
Small	1-2 hours	Single file, clear change
Medium	2-4 hours	Multiple files, one feature
Too Large	4+ hours	Should be split

If a task takes more than 4 hours, it should be broken down further.

Task Dependencies

{
  "dependsOnTaskRef": "SPEC-41"
}

Create tasks in dependency order:

1. Database schema (no dependencies)
2. Repository layer (depends on schema)
3. Service layer (depends on repository)
4. API endpoints (depends on service)
5. UI components (depends on API)

Example Breakdown

PRD Feature

"Users can register and log in with email/password"

Epic: User Authentication

## Overview
Secure user authentication system. Users register with email/password,
log in to access the platform, and can reset forgotten passwords.

## Scope
**IN:** Email/password registration, login, password reset, JWT sessions
**OUT:** Social login, 2FA, session management UI

## Technical Approach
- bcrypt (cost 12) for password hashing
- JWT tokens (24h expiry)
- httpOnly cookies for token storage
- Rate limiting on auth endpoints

## Reference Documents
- `.specflux/prds/user-management/prd.md` - Requirements
- `.specflux/prds/user-management/user-flows.md` - Auth flows

## Edge Cases
- Duplicate email registration → 409 Conflict
- Invalid credentials → 401 + generic message (no email enumeration)
- Expired reset token → redirect to request new token

Tasks

Task 1: User database schema

Objective: Create users and password_reset_tokens tables

Files:
- migrations/001_create_users.sql
- migrations/002_create_password_reset_tokens.sql

Acceptance Criteria:
[Unit] users table has id, email, password_hash, created_at, updated_at
[Unit] email column has unique constraint
[Unit] password_reset_tokens has user_id FK, token, expires_at
[Unit] Migration rollback removes tables

Task 2: User repository

Objective: CRUD operations for users table

Files:
- src/repositories/UserRepository.kt
- src/test/repositories/UserRepositoryTest.kt

Acceptance Criteria:
[Unit] create() inserts user and returns with generated ID
[Unit] findByEmail() returns user or null
[Unit] findById() returns user or null
[Unit] updatePassword() updates password_hash

Task 3: Registration endpoint

Objective: POST /api/auth/register

Files:
- src/routes/auth/RegisterRoute.kt
- src/test/routes/auth/RegisterRouteTest.kt

Acceptance Criteria:
[Integration] Returns 201 with user object for valid input
[Integration] Returns 400 for invalid email format
[Integration] Returns 400 for password under 8 characters
[Integration] Returns 409 for duplicate email
[Unit] Password is hashed with bcrypt cost 12

Coverage Verification

Before finishing breakdown, verify 100% PRD coverage:

## Coverage Report

| PRD Requirement | Epic | Tasks |
|-----------------|------|-------|
| User registration | E1 | T1, T2, T3 |
| User login | E1 | T4, T5 |
| Password reset | E1 | T6, T7, T8 |
| Profile management | E2 | T9, T10, T11 |

✓ All requirements covered

Quick Reference

Epic Statuses

• PLANNING - Being defined
• IN_PROGRESS - Implementation started
• BLOCKED - Waiting on dependency
• COMPLETED - All tasks done
• CANCELLED - Abandoned

Task Statuses

• BACKLOG - Not started
• READY - Dependencies met, ready to start
• IN_PROGRESS - Being worked on
• IN_REVIEW - Awaiting review
• BLOCKED - Stuck on something
• COMPLETED - Done and verified
• CANCELLED - Abandoned

Task Priorities

• CRITICAL - Blocks everything
• HIGH - Important for epic completion
• MEDIUM - Normal priority
• LOW - Nice to have