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
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
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
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
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.
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.
Changing it in conversation
You can also adjust the project Spec format by asking, in a planning conversation:
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.