Epics

When a request is too big for one spek, the interview tends to end with acceptance criteria too thin to build from, and the implementing agent fills the gaps with its own assumptions. An epic fixes that by grouping several speks that together deliver the one request, each with its own testable criteria.

An epic holds an overview and the list of its speks with the dependencies between them, and nothing else. Requirements, constraints, non-goals and every acceptance criterion live in the speks. An epic is never planned or implemented itself: each of its speks is planned and implemented on its own, exactly like a standalone spek, and everything a plan needs is in its spek. To plan or implement every spek in an epic with one request, see “Planning and implementing an epic” further down this page.

An epic lists its speks in specs, each entry carrying the speks in the same epic it depends on. depends_on is always present, and is [] when there are none. List order is display order:

---
created_date: "2026-09-28"
document_status: draft
spec: 000060_epics-and-seeded-specs
specs:
    - name: 000060_epics-and-seeded-specs
      depends_on: []
    - name: 000061_epic-split
      depends_on: [000060_epics-and-seeded-specs]
sources:
    - uri: https://github.com/hivecommons/spektacular/issues/55
      retrieved_date: "2026-09-28"
---

spec names the spek whose split produced the epic, and sources records the material the epic was started from. Each spek in the epic names it in epic, and Spek always writes both sides of that link together:

---
created_date: "2026-09-28"
document_status: final
epic: 000060_epics-and-seeded-specs
---

A spek belongs to at most one epic, and epics don’t nest. Using epics is optional: a project that never splits a spek sees no change in behaviour.

How readily the check fires is set by epic_split_threshold in .spektacular/config.yaml:

epic_split_threshold: moderate   # strict | moderate | lenient

• strict: only on a strong signal, and only when each proposed spek could ship on its own today. Weak signals alone never lead to an offer.
• moderate (default): one strong signal, or two weak signals together.
• lenient: one strong signal, or a single weak signal, is enough.

The setting moves only the signal counts. The gate, the supporting-work rule and the counter-signals apply at every level. It is separate from spec_trigger_threshold, which sets how readily the agent offers to start a spek in the first place, and the agent reads it at the moment it decides, so a change takes effect immediately. See the configuration reference.

From a tracker epic. When you start a spek from a source that already lists child items, such as a tracker epic with sub-issues, Spek offers to create an epic first, with the parent as its source and no speks yet. Each child is then specified as its own spek in that epic, through the normal spec workflow, seeded from that child.

Chaining. When a spek in the epic finishes, the agent re-reads the epic’s source and offers to start a spek for the next child item that has none yet. You can stop at any point and pick up later. The offer stops at specifying: it never offers to plan or implement the next spek.

Joining an epic. In a project that has epics, starting a new spek has the agent ask whether it belongs to one, unless your request already says. When it does, the agent reads the epic and every spek in it first, so the interview builds on what they already cover and offers to record dependencies on them. The CLI call it makes carries the epic:

spektacular spec new --data '{"name":"spec-list-json","epic":"000060_epics-and-seeded-specs"}'

Adding to a completed epic. An epic is complete once every one of its speks is implemented. Adding a spek to it, whether by starting one in it, listing one with epic write or splitting into it, is refused with epic_complete and nothing is written. Once you confirm, the agent repeats the call with "confirm_completed_epic": true, the spek is added, and the epic is reported as in progress again until the new spek is implemented.

Each spek still gets an ordinary plan and an ordinary implementation, the same as if it had been run on its own. What changes is that your agent runs them for you: one agent per spek, side by side wherever the dependencies allow, each following the standard plan or implement workflow.

Plan this epic

• Speks that are ready are planned side by side by separate agents.
• A spek waits until the speks it depends on are planned, so its plan can build on theirs.
• Speks that already have a plan are skipped.
• Planning keeps a summary document with the epic: the decisions you settled come first, then any order Spektacular added, then one section for each plan, listing the manual checks its test plan will ask for. Making the same request again adds sections for newly planned speks and keeps the others.
• Speks whose plans change the same files, and that nothing orders yet, are ordered for you: the spek listed later waits for the one listed earlier. Nothing is re-planned, and the summary names the shared files.
• Planning ends with a review that walks the summary before anything is implemented. Changes you ask for are made to the plan and to its section together, and you can remove an added order there. Once removed, it is never added back.

Implement this epic

• It refuses up front if any spek has no plan, naming it, and implements nothing. A dependency cycle, or a dependency on an unimplemented spek outside the epic, is refused the same way.
• Each ready spek is built in its own git worktrees, one for each repo it changes, on a branch named spek/<spek> in each. Inside them, every repo the spek touches resolves to the spek’s own copy, so speks running side by side never touch each other’s files.
• A spek is merged back before anything that depends on it starts. Its changes are merged into every repo together, or not at all if any repo would conflict.
• A conflict stops the run and is shown to you, with the conflicting files for each repo. Spektacular never resolves one itself.

What still stops for you

Only genuine open questions: a decision with no reasonable default that only you can make, such as “planning 000071_a needs to know whether the export keeps the old field”. The other speks keep going while you answer. Planning also stops once at the end, for the review. Everything else the agents decide themselves and record, so you can check it in the review.

Planning also stops to ask when a plan would contradict something you already decided: a choice in the spek, in a design it references, or an entry in the knowledge base. It never leaves that as a task for a person or a note for the review, and the other speks keep planning while you answer. This applies when you plan a single spek too. When plans disagree with each other on a rule for the whole project, such as how the changelog is kept, you are asked once every spek is planned, with one proposed answer. Your answer is applied to every plan involved before the summary is written, so the summary never holds an open question.

When something fails

If a spek fails, or you choose not to answer a question yet, nothing new starts. Work already running is allowed to finish. You are told which spek stopped the run, why, and what completed.

Picking up where you left off

Make the same request again. Finished speks are skipped, and an interrupted spek resumes at the step it reached rather than starting over. While a run goes, your agent reports progress after each change:

Planning 2 of 5 speks: 000071_a (tasks), 000073_c (discovery). 2 remaining.

Seeing where an epic stands

Your agent works out what is left from spektacular status, and you can ask it too. Naming an epic adds a run view: for planning and for implementing, whether each spek is done, in progress, awaiting merge, ready or blocked, and what blocks the epic from being implemented. Trimmed:

spektacular status 000070_example --format json

{
  "epic": {
    "name": "000070_example",
    "run": {
      "order": ["000071_a", "000073_c", "000072_b"],
      "plan": { "done": 3, "in_progress": 0, "ready": 0, "blocked": 0, "remaining": 0 },
      "implement": { "done": 1, "in_progress": 1, "awaiting_merge": 0, "ready": 0, "blocked": 1, "remaining": 2 },
      "dirty": false,
      "problems": []
    }
  },
  "specs": [
    {
      "name": "000073_c",
      "run": {
        "plan": { "state": "done" },
        "implement": { "state": "in_progress", "current_step": "verify", "repos": ["app", "docs"] }
      }
    },
    {
      "name": "000072_b",
      "run": {
        "plan": { "state": "done" },
        "implement": { "state": "blocked", "waiting_on": ["000073_c"] }
      }
    }
  ]
}