# Spec and Epic formats

The sections every Spec and Epic is written to, and how to replace ours with your own.



A **format** is the document structure the agent writes to. There are two:

* **Spec format** shapes every Spec, including its numbered acceptance criteria.
* **Epic format** shapes each plan's Epic, the narrative your issue tracker receives as the
  project or epic description.

Plansmith ships a standard version of each. A company or a project can replace either one outright.

## What ours look like [#what-ours-look-like]

The standard **Spec format** has an Overview and Acceptance Criteria always, plus User flow,
States, Data and Out of scope when the work calls for them. It adapts: a one-line fix does not get
the same eight sections as a new user-facing feature.

The standard **Epic format** is the stakeholder-facing document: a one-liner, the value
proposition, who it is for, the job to be done, background, key functionality, how you will tackle
it, and what is explicitly not in v1.

## Customizing [#customizing]

Open **Settings → Formats** and choose **Customize for this company** or **Customize for this
project**. You are handed the current format as a starting point and you own it from then on.

Resolution is **nearest wins, whole document**: a project copy beats a company copy, which beats
ours. Formats are never merged, because a format assembled from three partial sources produces
output nobody can predict.

## One rule per kind is enforced [#one-rule-per-kind-is-enforced]

Whatever else you change, each format has to keep one thing:

| Format   | The rule                              | Why                                                                                     |
| -------- | ------------------------------------- | --------------------------------------------------------------------------------------- |
| **Spec** | Ends with a `- [ ]` checklist         | Every Spec needs acceptance criteria; the tool that writes Specs enforces it.           |
| **Epic** | Has at least one `## Section` heading | The Epic becomes your issue tracker's description, and headings make it readable there. |

The editor shows the rule beside your draft as you write.

## Removing a customization [#removing-a-customization]

The control is **Remove override**, not "reset to default", and the wording is exact: removing a
*project* format falls back to your *company* format when one exists, not to ours.

<Callout>
  If a format was saved but cannot be read back, the settings card says so and tells you which one
  the agent is actually using. It does not quietly fall through to the default, because "my
  customization is live" and "my customization is broken" should not look the same.
</Callout>

## Changing it in conversation [#changing-it-in-conversation]

You can also adjust the **project** Spec format by asking, in a planning conversation:

```text
Here are two of our tickets. Match this format from now on.
```

That path is project-only on purpose. The company format is an owner act in settings, so a single
conversation cannot re-shape every Spec the whole workspace writes.