Epic
Use this skill to transform an intake, roadmap, or large initiative into a structured epic with decomposed stories, a roadmap, and acceptance criteria.
Initial context received via slash: $ARGUMENTS
If
is filled (e.g., intake path, description, initiative name), use as starting point.
If empty, ask which initiative will be structured.
Language
Write the artifact in the user's language. Apply correct grammar and any required diacritics or script-specific characters. If the user's language is unclear, ask before generating output. Templates are in English — translate headers and content to match.
Project root
This skill writes artifacts at paths relative to the project root (the repo where the work happens), not the agent's current working directory.
- If invoked from inside the project, use the relative paths shown in this skill.
- If invoked from another directory (e.g., a sibling repo, or when the project lives elsewhere), prepend to every artifact path.
- When the project root is ambiguous, confirm with the user via the harness question tool before writing.
Prompting
Follow the project-wide convention in
/
("Skill Prompting Conventions"). Use the harness's structured-question tool —
(Claude Code),
(Codex), or
(OpenCode) — for the decision points below. Use free-form text only where a path/name/value cannot be enumerated.
| Decision point | Why structured | Suggested options |
|---|
| Save path when user-passed path conflicts with convention | Hard-to-undo write | Use convention · Honor user path · Ask |
| Roadmap diagram type | Affects template fit | Mermaid flowchart · Mermaid gantt |
| Which story to detail first via /agile-story | Branches the next skill | first by dependency · pick |
Free-form prompts (no structured tool):
- Story names (kebab-case)
- Epic title and outcome wording
No-pause mode: if the user has explicitly disabled mid-skill clarification, convert every structured prompt into an entry under Open questions (or equivalent) and proceed without blocking.
Objective
- Decompose large initiatives into proportional, executable stories
- Structure a story backlog with dependencies and order
- Define an epic roadmap (phases, unblocks, intermediate validations)
- Ensure each story can be planned and executed separately
- Produce artifacts that guide execution without replacing individual task plans
When to use
- After an or identified a large initiative
- When the initiative requires multiple coordinated stories
- When there are dependencies between deliveries that need sequencing
- When a roadmap is needed to guide the delivery order
- For medium-to-large work that needs richer structure than a simple
When NOT to use
- The work is small and localized — use directly
- The problem hasn't been captured yet — use first
- You need strategic direction — use first
- You need to validate existing artifacts — use
Process
1. Analyze context
Read the intake, roadmap, or provided material. Identify:
- Macro problem and objective
- Which areas are impacted
- Constraints and premises
- Estimated scope and complexity
- Existing prototypes under
planning/<initiative>/proto/
- Existing business rules under
planning/<initiative>/business/*.md
If the initiative is UI-heavy and prototypes are an agreed gate, do not finalize epics until the relevant prototype routes/screens exist or the user explicitly waives the gate.
2. Decompose into stories
Break by vertical value slice, not by technical layer:
- Each story must deliver something observable
- Prefer independent stories when possible
- Identify dependencies between stories (what unblocks what)
For each story, define:
- Name and objective (1 line)
- Estimated scope (small, medium, or large)
- Dependencies (which stories it depends on)
- Prototype routes/screens involved, when applicable
- Business rule IDs/files involved, when applicable
- Summarized acceptance criteria
3. Structure the epic overview
Fill in the required sections:
- Context: problem, AS-IS, TO-BE, out of scope
- Story backlog: list with objective, size, and dependency of each
- Roadmap: phases/sprints, what unblocks what, intermediate validations
- Risks: what could go wrong and how to mitigate
- Epic acceptance criteria: how to know the initiative is complete
4. Define roadmap
- Group stories by phase/sprint
- Show what can run in parallel
- Highlight the critical path
- Include intermediate validations (milestones)
5. Consider collaborative work
When the team has 2+ developers:
- Identify parallel tracks or lanes so devs can work simultaneously
- Define interface contracts between tracks (types, schemas, APIs) to minimize blocking
- Assign stories to tracks when possible
- Use Mermaid diagrams to visualize parallel work across tracks
6. Generate files
The epic produces multiple files:
planning/<initiative>/epics/NN-<epic-name>/
├── 00-overview.md (the epic overview: context, backlog, roadmap, risks)
├── 01-story-name.md (first story: context + tasks inline)
├── 02-story-name.md (second story: context + tasks inline)
└── ...
- contains the epic-level context, story backlog summary, roadmap, risks, and acceptance criteria.
- Each contains the story context, acceptance criteria, files, tasks, and verification — all in one file.
NN is a zero-padded sequential number. Each epic gets its own folder under
.
Where to save
- Epic folder:
planning/<initiative>/epics/NN-<epic-name>/
- If the initiative doesn't have a folder in , ask the user for the name
- Path-conflict gate: if the user passes a save path that does not match the convention above (e.g.,
planning/<initiative>/<epic-name>/
Roadmap diagram
Pick the Mermaid type that fits the work:
- — preferred for trajectory roadmaps with dependencies but no fixed schedule (the common case for solo dev or long-running initiatives).
- — use only when real team scheduling exists (concrete start dates, capacity per track). For solo dev or no-deadline work, gantt produces fake precision; pick flowchart instead.
Cross-reference
Always include at the top of
:
**Origin:** `planning/<initiative>/intake.md`
Each story file includes:
**Origin:** `planning/<initiative>/epics/NN-<epic-name>/00-overview.md`
When available, also include:
**Prototype refs:** `planning/<initiative>/proto` route/screen IDs
**Business rules:** `planning/<initiative>/business/*.md` rule IDs
Chaining
At the end of the epic, offer:
- "Do you want me to create the execution plan for Story 1 with ?"
- "Do you want me to validate the artifacts with ?"
Ask the user which story they want to detail first.
Reference template
Use
from this skill as base for the overview artifact.
Rules
- The epic now handles decomposition directly — there is no separate refinement step for decomposing. Use only for validation/lint.
- Break by behavior/delivery (vertical slices), not by technical layer.
- Each story in the backlog must have a clear objective and be executable separately.
- The roadmap must show dependencies, not just chronological order.
- Epic acceptance criteria must be verifiable.
- Update story statuses as the epic progresses.
- Each story file must contain enough context to be planned and executed independently.
Required sections for 00-overview.md
- Context (problem, AS-IS, TO-BE, out of scope)
- Traceability (prototype routes/screens and business rule IDs/files)
- Story backlog (list with objective, size, dependency, status)
- Roadmap (phases, parallelism, critical path)
- Epic acceptance criteria
- Risks
Required sections for NN-story-name.md
- Context (problem, objective, value, constraints)
- Traceability (prototype routes/screens and business rule IDs/files)
- Files (exact paths, action, reason)
- Detail (AS-IS, TO-BE, scope, acceptance criteria, dependencies)
- Tasks (verifiable checklist in vertical phases)
- Verification (commands, validations, evidence)
Relationship with the flow
mermaid
flowchart LR
A["/agile-intake"] --> B["/agile-roadmap"]
B --> C["/agile-epic"]
C --> D["/agile-story"]
D --> E[execution]
E --> F["/agile-status"]
F --> G["/agile-retro"]
This skill acts after intake/roadmap and before task-level execution. For validating artifacts, use
. For execution plans, use
.