Spec and Epic formats

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, then open the spec or epic format. Each has its own document page, with Content, Properties, Changes and History. Copy link gives teammates a direct, authenticated link to that document. Everyone with workspace access can read it.

Workspace owners maintain both company and project formats. Choose Customize for this company, Customize for this project, or Edit format. Edit the rendered document or switch to Source, then choose Save changes to publish. Cancel keeps the published format unchanged.

Project format writes previously allowed members. They now require a workspace owner on every surface, including existing API and CLI integrations. A member write returns HTTP 403.

If another owner saves first, your draft stays open. Review latest compares both versions; Copy my changes preserves your draft for reconciliation. Discarding your draft requires an explicit choice.

Discuss a format

Readers can comment, reply and suggest edits from the document's Comments panel. Workspace owners review and accept changes, and receive updates about format discussions. A thread has its own shareable link. Formats have no Ask agent or Send to agent action. See Comments and suggested edits for mentions, review and Inbox preferences.

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:

Invalid saves explain the rule and keep your draft. The editor counts UTF-8 bytes against the 28,672-byte limit.

Once you customize, your format is the contract

The Plansmith standard is guidance: it describes a good Spec, and a Spec that covers everything under different headings is never sent back. The moment you save your own Spec format, that changes. Your format is what you asked for, so the agent is held to it three ways:

• A section you always ask for cannot be skipped. Mark a section optional by ending its heading with a trigger list: a short phrase, a colon, then what brings the section in, as in (when the conversation raises: a screen, a form, a list) or (cuando la conversación plantea: pantalla, formulario, listado). A one or two word note like (optional) or (Key functionality) reads as part of the title, not as a marker, so that section stays required.

• The shape you offered is written in full. A shape is one of the named variants your format offers: the bold entries under your Shapes heading, each followed by the sections that variant is made of. A Spec is read as the shape it fits best, and anything that shape lists and the Spec does not have is missing. A section you list somewhere else is never a problem: extra sections are always fine, so a screen described in a bug fix is fine. A format with no Shapes section is not held to this rule at all; only the first and third apply.

  Put a ? straight after a section name in a shape's list to say "this belongs here, but leave it out when it does not apply": Screens and fields? · Permissions?. The section still helps decide which shape a spec is read as, so a spec that has it is still read as that shape. It is simply never reported when it is absent. Use it for the sections your own guidance calls conditional, so a backend spec with no screens skips the screens section.

  The two optional markers answer different rules, and a shape's list wins. A trigger list on the heading answers the first rule above, "the sections you marked always-write are there". A shape naming that same section answers this second rule, and it asks for the section whatever the trigger list says. That override is the reason ? exists: mark the section in both places, or the shape keeps asking for it. A ? on a section you did not give a trigger list to does nothing, and the format editor says so when you save.

• A heading your format never lists is reported rather than quietly accepted, when it claims to be a section of its own. A sub-heading INSIDE a section you do list is that section's own structure and is kept: a format lists sections, it cannot list the screens or scenarios one will hold. The numbered-heading exception below is the other way a nested heading is fine.

Numbered headings are the exception, and you grant it by showing one. Write the pattern in a section's guidance as a code-formatted heading (`### RF01 · short active title`, or `### FR-1: short behaviour name`). The family is the part before the separator with the number standing for any number, so showing ### RF01 · … allows RF02 and RF06.1, and the separator has to match too: after showing ·, a ### RF-1: x is not in the family. A section that shows no pattern has no numbered children, and the refusal says so, so the fix is one line in your format.

⚠ Inside a section that shows a pattern, the words after the number are not checked. Having granted ### RF01 · …, a heading like ### RF07 · Assumptions we made is accepted as a numbered item of that section even though "Assumptions we made" is not a section you list. The family is a naming rule, not a judgement about content, so the third rule above stops at the boundary of a section that declares one.

The refusal names every finding at once plus your shapes and their whole section lists.

This applies to the Spec format only. The epic format keeps the single heading rule above.

Editing a Spec by hand, and editing older Specs

Two deliberate softenings, both so the contract never strands work you already have:

• Your own edits in the Spec editor are never blocked. You can save unfinished work. The editor tells you what does not match so you are not surprised by a refused agent turn later, and a Spec whose saved body breaks the format is held below Ready, the same as everywhere else.
• A Spec written before you customized keeps its existing mismatches. Editing it is judged on what your edit introduces, not on what it inherited, so an unrelated change is never blocked by a heading you are not touching. Sections an issue tracker import wrote, like an imported comment thread or related-work links, are never counted against you. Through the API, a client needing to save a body it did not author anyway can send acceptFormatViolations: true: the Spec saves and is held below Ready with the reason on it.

Removing a customization

Choose More actions → Remove override. The confirmation names the format that will be used. Removing a project format falls back to the company format when one exists, then to the Plansmith standard. History is retained. A newer edit prevents a stale removal.

Unreadable customizations

Choose Retry first. Until the page can read the current revision, it refuses edits and removal so it cannot overwrite a newer change.

If retries still fail, an owner can use the API to remove the broken override. Send DELETE to /v1/formats/{kind} for the company, or /v1/projects/{projectSlug}/formats/{kind} for a project, with an empty JSON object as the body. This uses the legacy direct-removal behavior: it does not check a revision and can remove a change another owner saved in the meantime. Coordinate with other owners before using it. CLI and MCP mutations require a readable revision.

Changing it in conversation

Workspace owners 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 conversation action changes the project's spec format.

API, CLI, and MCP

Read, set, or remove either format at company or project scope through the API, CLI, or either MCP server. All writes require an owner and an active workspace. Reads return the effective source, documentUrl, scopeDocumentUrl, and the destination's overrideRevision.

Once you customize the Spec format, Spec writes that carry content are held to it here too, to the same rules the conversation is held to. A body that breaks them answers 422 and writes nothing; the error lists what is missing, what your format does not list, and the shape it was read as. Creating a Spec with a title and no content is never refused. The CLI prints those lines under the message, and --json gives you the whole details object.

plansmith format show spec --project web --json
plansmith format set spec --project web --file spec-format.md --expected-revision absent
plansmith format reset epic --project web --expected-revision <hash>

The CLI reads the current destination revision before writing when you omit --expected-revision. Supply the hash you reviewed, or absent for a new override, to protect an earlier read.

Both MCP servers expose plansmith_get_format, plansmith_set_format, and plansmith_reset_format. Set and reset require expectedRevision, using the read's overrideRevision, or explicit null for absence. A conflict requires another read and review. API writes accept the same field; omission preserves older clients' unconditional writes.