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)

Binds on EVERY question you ask — the research questions in Step 2 and the phase-approval question in Step 4 alike:

• Numbered — each question is a numbered list item (1., 2., …), not a heading, a bold-only line, or a paragraph.
• Self-contained — the question is answerable from itself and its options alone. Name what is being decided and what the answer changes, inside the question. "Which of the above?", a bare "Your choice?", and "Which variant do you prefer?" with nothing restated are defects: they send the reader back up the transcript to reconstruct the question.
• agent's choice — on a multi-select where the user delegates with agent's choice (or its language equivalent), pick the subset yourself, justify the pick in one line, and proceed without re-asking for confirmation.

The phase breakdown itself stays ABOVE the question: the phases are a dependency-ordered sequence, not a set of alternatives, so they are not the question's options. That makes the self-containment rule do all the work — the approval question must restate what it is asking about. Critique-points selection (Step 7) is auto-classified by the agent and asks the user nothing.

Instructions

<step_by_step>

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)
   • Then ask ONE numbered question that stands on its own: name the epic and the number of phases being approved, and list the reply options — approve the split as presented, or say which phase to split, merge, or reorder. A bare "Approve?" or "Does this look right?" is a defect: it is unanswerable without scrolling back over the breakdown. STOP and wait for the answer.

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

</step_by_step>

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