# Agile Epic > Structures large initiatives into a decomposed backlog with roadmap, dependencies, and verification. Generates an overview file plus individual story files with tasks. Use when work requires several coordinated stories, has dependencies between deliveries, or needs a roadmap. - Skill: `djalmajr/agile-epic` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add djalmajr/agile-epic` - Raw SKILL.md: https://api.skillmd.com/api/skills/djalmajr/agile-epic/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: djalmajr (https://skillmd.com/u/djalmajr) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/djalmajr/agile-epic --- # 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 `$ARGUMENTS` 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 `CLAUDE.md` / `AGENTS.md` ("Skill Prompting Conventions"). Use the harness's structured-question tool — `AskUserQuestion` (Claude Code), `ask_user_question` (Codex), or `question` (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 `/agile-intake` or `/agile-roadmap` 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 `/agile-story` ## When NOT to use - The work is small and localized — use `/agile-story` directly - The problem hasn't been captured yet — use `/agile-intake` first - You need strategic direction — use `/agile-roadmap` first - You need to validate existing artifacts — use `/agile-refinement` ## 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//proto/`, when UI/product flows matter - Existing business rules under `planning//business/*.md`, when domain behavior matters 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 `gantt` diagrams to visualize parallel work across tracks ### 6. Generate files The epic produces multiple files: ``` planning//epics/NN-/ ├── 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) └── ... ``` - `00-overview.md` contains the epic-level context, story backlog summary, roadmap, risks, and acceptance criteria. - Each `NN-story-name.md` 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 `epics/`. ## Where to save - Epic folder: `planning//epics/NN-/` - If the initiative doesn't have a folder in `planning/`, 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///` instead of the `epics/NN-/` shape), surface the conflict before writing. Honor the user's path only after explicit confirmation; otherwise apply the convention and tell the user why. Use the harness's question tool (see `## Prompting`) to disambiguate. ## Roadmap diagram Pick the Mermaid type that fits the work: - **`flowchart`** — preferred for trajectory roadmaps with dependencies but no fixed schedule (the common case for solo dev or long-running initiatives). - **`gantt`** — 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 `00-overview.md`: ``` **Origin:** `planning//intake.md` ``` Each story file includes: ``` **Origin:** `planning//epics/NN-/00-overview.md` ``` When available, also include: ``` **Prototype refs:** `planning//proto` route/screen IDs **Business rules:** `planning//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 `/agile-story`?" - "Do you want me to validate the artifacts with `/agile-refinement`?" Ask the user which story they want to detail first. ## Reference template Use `templates/epic.md` 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 `/agile-refinement` 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 1. **Context** (problem, AS-IS, TO-BE, out of scope) 2. **Traceability** (prototype routes/screens and business rule IDs/files) 3. **Story backlog** (list with objective, size, dependency, status) 4. **Roadmap** (phases, parallelism, critical path) 5. **Epic acceptance criteria** 6. **Risks** ## Required sections for NN-story-name.md 1. **Context** (problem, objective, value, constraints) 2. **Traceability** (prototype routes/screens and business rule IDs/files) 3. **Files** (exact paths, action, reason) 4. **Detail** (AS-IS, TO-BE, scope, acceptance criteria, dependencies) 5. **Tasks** (verifiable checklist in vertical phases) 6. **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 `/agile-refinement`. For execution plans, use `/agile-story`.