Epic

Feature Epic

Overview

Create a structured, decomposed epic under the tasks role resolved from AGENTS.md for features too large for a single agent session. The template default uses today's date as a directory hierarchy; the file slug begins with epic- (no date prefix in the slug).

When to Use

• Use epic when feature spans >3 files AND requires >2 sessions, OR has >5 phases
• Use plan for tasks completable within one agent session
• When unsure: start with plan; if it outgrows a single task, upgrade to epic

Context

Rules & Constraints

Question Format (FR-UNIVERSAL.QA-FORMAT)

For clarifying / uncertainty-resolution questions asked during research (Step 2):

• Each question MUST be a numbered list item (1., 2., …) — not a heading, bold-only line, or paragraph.
• For multi-select questions, when the user delegates with agent's choice (or equivalent), pick the subset yourself, emit a one-line justification of the pick, and proceed without re-asking for confirmation.

Phase approval (Step 4) and critique-points selection (Step 7) are exempt — phase decomposition is a multi-section content presentation (the same prior that drives variant analysis), and critique triage is auto-classified by the agent without asking the user.

Instructions

1. Initialize

   • Use a task management tool (e.g., todo_write, todowrite) to create a plan based on these steps.
   • Compute today's date in YYYY-MM-DD format (e.g. via date +%Y-%m-%d). Hold it as <DATE>. Derive <YYYY>, <MM>, <DD> (zero-padded). Resolve tasks from AGENTS.md and derive the eventual epic path from that role's layout.

2. Deep Context & Research

   • Resolve SRS and SDS from AGENTS.md. If you don't know their current content — read the resolved files now.
   • Follow Proactive Resolution from AGENTS.md: analyze prompt, codebase, search for gaps.
   • Use search tools (e.g., glob, grep, ripgrep, search, webfetch) for unknowns.
   • If uncertainties remain: ask user clarifying questions. STOP and wait.

3. Draft Spec Header

   • Create the resolved epic file's parent directories (use mkdir -p).
   • Write to the resolved epic file the following sections:
     • YAML frontmatter with all required keys (rule 12): date, status: to do, tags, related_tasks, optional implements.
     • Title and metadata table (Status: Draft, Created/Updated dates)
     • Goal (business/user value — why are we building this?)
     • Overview (current state, why now, relevant context)
     • Non-Goals (explicit exclusions — critical for AI agents)
     • Architecture & Boundaries (three-tier: Always / Ask First / Never)
     • Definition of Done (measurable acceptance criteria)
   • CRITICAL: Do NOT fill Phases yet.

4. Decompose into Phases (Chat Only)

   • Present phase breakdown in chat:
     • Each phase: goal, scope (files/components), dependencies, estimated task count
     • Phases ordered by dependency (foundations first)
     • Target: ≤30-50 requirements per phase (within ~150-200 instruction limit)
   • Present to user. STOP and wait for approval/adjustments.

5. Detail Phases

   • Write approved phases into the resolved epic file. Each phase contains:
     • Status (not-started / in-progress / done)
     • Prerequisites (which phases must be done first)
     • Goal (what this phase achieves)
     • Scope (files/components affected, target 1-5 files per task)
     • Tasks (numbered list of atomic, testable tasks)
     • Verification (specific commands/checks to confirm phase completion)
     • Notes (implementation hints, gotchas, references)

6. Critique

   • Present epic to user in chat and offer to critique it before finalizing.
   • If user agrees, critically analyze the epic for:
     • Missing phases or hidden dependencies
     • Tasks too large (should be split) or too small (should be merged)
     • Vague verification criteria
     • Missing non-goals or boundary gaps
     • Over-specification of trivial parts
   • Present critique in chat.

7. Refine & Finalize

   • Ask the user which critique points to address.
   • Update the resolved epic file with accepted improvements.
   • Update the metadata table Status from "Draft" to "Ready". (Frontmatter status: is auto-derived from DoD; do not change it manually.)

7a. Write SRS-inline **Tasks:** Back-Pointer (FR-DOC-TASK-LINK) — execute immediately, no permission needed. This is a write step.

• For each FR-ID in the epic's implements: frontmatter, locate the heading ### <FR-ID>: in the resolved SRS.
• If the heading does not exist (new FR introduced by the epic), SKIP this FR and emit a chat note: "FR-XXX SRS section pending — task back-pointer deferred."
• If the heading exists, find the section's **Description:** bullet. Look at the line(s) immediately following it.
  • If a - **Tasks:** [...] bullet already exists: append , [epic-<name>](tasks/<YYYY>/<MM>/epic-<name>.md) to the comma-separated list. Idempotent: skip if the exact link is already present.
  • If no **Tasks:** bullet exists yet: insert a new line - **Tasks:** [epic-<name>](tasks/<YYYY>/<MM>/epic-<name>.md) immediately AFTER the **Description:** bullet.
• Surgical edit only: rest of the SRS file MUST remain byte-identical.

8. TOTAL STOP

Output Format

---
date: YYYY-MM-DD
status: to do
implements:
  - FR-XXX
tags: []
related_tasks: []
---
# Epic: {Feature Name}

| Field   | Value                       |
|---------|-----------------------------|
| Status  | Draft/Ready/In-Progress/Done |
| Created | YYYY-MM-DD                  |
| Updated | YYYY-MM-DD                  |

## Goal

{Why are we building this? Business/user value.}

## Overview

{Current state, why now, relevant context.}

## Non-Goals

<!-- Examples: "No backward compatibility with v1 API", "No UI changes in this phase", "No performance optimization", "No migration of existing data" -->
- {Explicit exclusion 1}
- {Explicit exclusion 2}

## Architecture & Boundaries

### Always (agent autonomy)

- {Things agent can always do}

### Ask First

- {Things requiring user confirmation}

### Never

- {Things agent must never do}

## Definition of Done

- [ ] {Measurable criterion 1}
- [ ] {Measurable criterion 2}

---

## Phase 1: {Name}

**Status:** not-started | **Prerequisites:** none

### Goal

{What this phase achieves.}

### Scope

- {file/component 1}
- {file/component 2}

### Tasks

1. {Atomic, testable task}
2. {Atomic, testable task}

### Verification

- [ ] {Specific check or command}

### Notes

- {Implementation hints, gotchas}

---

## Phase 2: {Name}

...

Verification