Skip to content
Skills Library
Management & product · Planning

epic

/epic

Create one epic from .idea and generate its tasks, mid-project. Use when the user has a new idea to turn into work, wants to add an epic or feature to an existing project, says "make this an epic", "add this to the roadmap", "turn this into tasks", or wants to accept or reject an epic the project-manager agent suggested. The narrow, mid-flight counterpart to /shape.

Repository
payday-dev ↗
Licence
MIT
Last repository change
02.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Create one epic from .idea and generate its tasks, mid-project. Use when the user has a new idea to turn into work, wants to add an epic or feature to an existing project, says "make this an epic", "add this to the roadmap", "turn this into tasks", or wants to accept or reject an epic the project-manager agent suggested. The narrow, mid-flight counterpart to /shape.

Triggers from the description

make this an epicadd this to the roadmapturn this into tasks
Original author description

Create one epic from .idea and generate its tasks, mid-project. Use when the user has a new idea to turn into work, wants to add an epic or feature to an existing project, says "make this an epic", "add this to the roadmap", "turn this into tasks", or wants to accept or reject an epic the project-manager agent suggested. The narrow, mid-flight counterpart to /shape.

How it works

  1. An ATT- reference from the dashboard
  2. Phase 1 — Work out which case this is
  3. Phase 2 — Check it belongs
  4. Phase 3 — Write the epic
  5. Phase 4 — Generate the tasks
  6. Phase 5 — Wire it in and hand off
  7. Suggested epics
Original SKILL.md headings · 136 lines, 1,247 words
SKILL.md preview
---
name: epic
description: Create one epic from .idea and generate its tasks, mid-project. Use when the user has a new idea to turn into work, wants to add an epic or feature to an existing project, says "make this an epic", "add this to the roadmap", "turn this into tasks", or wants to accept or reject an epic the project-manager agent suggested. The narrow, mid-flight counterpart to /shape.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, WebSearch, WebFetch, Skill
---

# Epic

One epic, from idea to tasks, without re-shaping the whole plan. `/shape` is for planning a project;
this is for adding to one already underway.

**Plain language.** Everything you say to the person — questions, plans, summaries, reports —
follows `.claude/skills/shared/plain-language.md`: assume they are not a developer, use simple
words, recommend an option when you ask, and explain any technical word the first time it appears.
Notes in `.idea/` may stay technical; explain them, don't paste them.

Read `.claude/skills/shared/vault-contract.md` before writing anything to `.idea/`.


## An `ATT-` reference from the dashboard

`/epic ATT-3C81F0` names an item from **Needs attention** on the management dashboard. Resolve it
before anything else:

1. Read `.management/state.json` and find the blocker whose `ref` matches. If none does, say so and
   list the references that exist rather than guessing at a near match.
2. The item gives you the epic's substance directly: its `title` is the problem, `nextAction` is the
   first concrete step, `epic` names what it holds up, and `since` says how long it has been true.
3. Build the epic against **that**, and say in its `## Why` which attention item it came from and
   what will stop firing once it is done.

A `critical` item is the roadmap's own blocker — it is why a phase cannot finish — so its epic
belongs in the **current** phase unless the user says otherwise. A `warning` can wait.

> [!warning] The attention item is evidence, not the plan
> `.management/` is derived state. The epic still lands in `.idea/epics/` with sources traced back to
> an idea note, like any other. If the item traces to no idea, capture one first — an epic that
> exists only because a dashboard row said so has no recorded reason behind it.

## Phase 1 — Work out which case this is

Read `.idea/INDEX.md`, `SPECS.md`, `ROADMAP.md`, and the existing `epics/`. Then route:

| The user gave you | Do |
|---|---|
| A **subcommand** — `accept`, `reject`, `list` | Jump to *Suggested epics* below |
| An **existing idea note** to promote | Phase 2 |
| A **raw idea**, not yet captured | Capture it first — Phase 1b — then Phase 2 |
| **Nothing** | List idea notes at `promising` or above plus any `suggested` epics, and ask which to work on |

No `.idea/` at all, or no `SPECS.md`? Say so and send them to `/brainstorm` then `/shape`. An epic
with no spec to hang off is a task list, not a plan.

### Phase 1b — Capture first

If the idea is not yet in the vault, **invoke the `brainstorm` skill** to capture it properly, then
return here. Do not write an ad-hoc idea note yourself: brainstorm owns the intent ledger, the
scoring, and the theme grouping, and skipping it produces a note the rest of the workflow cannot use.

Keep it tight — this is one idea, not a full divergence session. Capture the note, score it, link its
theme, then carry on.

## Phase 2 — Check it belongs

Before writing anything, three questions, answered out loud:

1. **Does this already exist?** Compare against every epic. If it overlaps, say which, and propose
   extending that epic instead of creating a near-duplicate.
2. **Does it fit the spec?** If it contradicts `SPECS.md` or a recorded decision in `decisions/`,
   say so plainly. It may still be right — but it is then a spec change, and that is `/shape`.
3. **Which phase?** Existing phase, or after the current one. Never silently insert into a phase
   already in progress; ask, and say what it would displace.

> [!warning] Scope creep enters here
> Mid-project epics are how projects quietly double in size. If this is the third epic added to a
> phase, say so and ask what is being traded away. Naming the cost is not obstruction — it is the
> job.

## Phase 3 — Write the epic

To `.idea/epics/<Epic Title>.md`, per `.claude/skills/shape/references/templates.md`:

- `sources:` pointing back at the idea notes it came from; set `epic:` on those notes and flip them
  to `committed`.
- `phase:` set to the agreed phase.
- Outcome stated as what is observably true when it is done.
- `status: planned`.

If the epic is too big for one — more than about five days, or it needs more than one observable
outcome — **split it** and say why. Two honest epics beat one that hides its size.

## Phase 4 — Generate the tasks

Acceptance criteria are the tasks. For each:

- One observable outcome, finishable in a day or so.
- **Points, then a task reference id as a block ref**:
  `- [ ] The document reopens after a restart (3 pts) ^tsk-4b91c2`. Size relative effort on the
  1, 2, 3, 5, 8, 13 scale, as `/shape` does; a 13 is a criterion to split. When a size is not
  obvious from the notes, ask rather than guess. The validator rejects a criterion with no points.
- The id is six lowercase hex characters, unique across the vault. Assign once, never reassign —
  assignees, effort, and pull requests key on it.
- **Surface the invisible work** the idea note never mentions: migrations, auth, error states, seed
  data, tests, the deploy path. An epic without them is optimistic fiction.
- If confidence in the approach is low, the first task is a **timeboxed spike** whose exit criterion
  is a written decision, not a feature.

## Phase 5 — Wire it in and hand off

- Add the epic to `ROADMAP.md` under its phase, with its tasks counted. If that phase is already
  `verified`, set it back to `in-progress` and say so: it has new work, so `/setup` must build and
  verify it again before `/ship` releases it.
- Update the theme MoC and regenerate `INDEX.md`.
- Write an ADR into `decisions/` for anything consequential that the epic settled.
- Verify traceability both ways: every task has an id, the epic has at least one source note, and
  that note points back.

Close with the epic, its tasks, the phase it landed in, and: **"Run `/setup` when you want it
built."** If it changed the shape of the plan rather than adding to it, say `/shape` instead.

---

## Suggested epics

The `project-manager` agent writes epics at `status: suggested`. They are proposals: they belong to
no phase, count toward nothing, and are never built until a person accepts one.

| Subcommand | Does |
|---|---|
| `/epic list` | Every suggested epic, with why the agent proposed it and the evidence it cited |
| `/epic accept <name>` | Review it with the user, edit as needed, set `status: planned`, assign a phase, generate task ids, and link it from its theme and `INDEX.md` — Phases 2 to 5 above |
| `/epic reject <name>` | Set `status: cut` and add a `## Why rejected` section, after confirming |

Accepting is not rubber-stamping. Run Phase 2 on a suggestion exactly as on a user's idea — the
agent proposed it from evidence, but it did not weigh it against everything else competing for the
phase. Say plainly when you think a suggestion is wrong.

Rejecting **keeps** the note, at `status: cut`, with a `## Why rejected` section in the person's
words. Nothing in the vault is deleted, and this one matters more than most: the `project-manager`
agent reads cut epics before suggesting, so a deleted rejection would simply be proposed again.

Versions

RepositoryScoreLicence
This page · jamesm-dev/payday-dev90MIT
baldaworks/prism100MIT
astillero-ai/astillero90Apache-2.0
the-psi/pai-orbit90MIT

Database snapshot: 13.11.2026 · package version 12151d4618a1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95brainstorm
    Use when starting a new feature or epic — turns a feature idea into a defined, ticket-ready epic through Socratic dialogue with the user. Designs technical approaches, breaks features into milestones, drafts ticket descriptions and success criteria, and writes the epic to the…
  • 100shape-epic
    Shape a product idea into a fully-defined, buildable epic. Composable phases from problem statement through epic definition, design (a UI prototype, an architecture PR, or both), slice planning, test creation, build guide, and a tech lead handoff prompt attached to the epic. Can…
  • 100epic-planner
    Create structured epic hierarchies for new features, major refactorings, and large tasks. Generates speckit-style artifacts (spec.md, plan.md, tasks.md, beads-import.md) in specs/ and creates real beads via `bd` CLI with wired dependencies. Use when the user says things like…
  • 100create-workflow-epic
    Create a complete workflow initiative with an epic, core workflow sub-issues, and launch preparation tasks. Use when the user asks to create a workflow epic, file a workflow task, or start a new workflow initiative.
  • 100epic-hypothesis
    Frame an epic as a testable hypothesis with target user, expected outcome, and validation method. Use when defining a major initiative before roadmap, discovery, or delivery planning.
  • 100nxs-gh-create-epic
    Create a GitHub issue from an Epic document. Use when the user wants to create a GitHub issue from an epic.md file, sync an epic to GitHub, or link an epic document to a GitHub issue. The skill extracts the epic title and type from YAML frontmatter, creates an issue via `gh…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.