Design Documents

A design document holds the settled shape of something: an API, a user-facing flow, a data format, or a worked example of one. It is the detail a spek needs to be built correctly but cannot carry without becoming unreadable.

Spektacular (Spek) owns the reference, not the document. It resolves a declared source to a folder, reads and writes bytes there, and reports a reference it cannot resolve. It never imposes a structure on a design document’s content, whoever wrote it.

Beyond that, there are two kinds of design document and they are treated differently. A design your team already had is never changed. It gains no frontmatter, is never reformatted, and comes back byte for byte as you supplied it, so a folder of designs you already keep is read exactly as it stands. A design Spek authors with you is different: it carries the same lifecycle record every spek and plan carries, so you can see where it stands, which spek’s conversation produced it, and which speks depend on it.

That is why design documents are declared rather than filed. You point Spek at wherever your designs already live, give each place a name, and reach the documents there by that name. Nothing moves.

Not every design arrives finished. Where the shape of something has been settled in conversation but never written down, Spek can help you work it out and then write the document from it. That is a guided interview: it states what it is trying to learn, asks questions that follow from your answers rather than working through a fixed list, and stops.

It is the same Flipped Interaction pattern the spec workflow uses for its own interview, aimed at a different goal: understanding the design well enough to write a document someone could build from.

The stopping condition is the part that matters most in practice. The interview ends once a further answer would not change the document, not once every conceivable detail has been asked about. What gets written is the design, not a transcript of the conversation that produced it, so an authored design is the size of the design rather than the size of the discussion.

Agent:  You have described the shape of the retry policy twice now, and it is
        settled. Shall I help you write it up as a design document?
You:    yes
Agent:  What triggers a retry: any failure, or only specific ones?
You:    only 5xx and timeouts, never a 4xx
Agent:  And what stops it retrying forever?
You:    three attempts, doubling the wait each time
Agent:  That is enough to write it. Nothing further would change the
        document. Here is the draft, shall I store it?

Nothing is written without your explicit agreement, and declining leaves no file behind. A design can be authored before any spek exists; the reference is recorded later, if a spec ever needs one.

A spek records references. Each one names both the source it belongs to and the document within that source, so it can always be resolved back to a real place. References live in the spek’s own record rather than its prose, which is what makes them validated when written and durable afterwards: they survive the spek being rewritten.

A plan resolves and reads every one before designing. The plan workflow is obliged to read each referenced design in full, to build on it rather than re-derive it, and to name each document and the source it came from in the finished plan’s dependencies. A design you referenced is guaranteed a reader.

Once the work ships, the design is a historical record. Nothing requires a shipped design to match the implementation, and no command rewrites one to make it match. It records what was agreed.

A design document holds no back-links, so any number of speks may reference the same design and it outlives the feature that introduced it. Here is how a spek carries its references:

---
created_date: "2026-09-20"
document_status: final
designs:
  - source: api
    path: payments/v2.md
---

The declared sources, with the absolute location each one resolved to:

spektacular design sources

Every design document, across all sources at once, each tagged with the source it came from. Add --source to narrow to one:

spektacular design list
spektacular design list --source api

Read one document by naming its source and its path within that source. The bytes go to stdout unchanged:

spektacular design read --data '{"source":"api","path":"payments/v2.md"}'

Write one into a declared source. The content comes from a file, and is stored exactly as given:

spektacular design write --data '{"source":"api","path":"payments/v2.md"}' --from ./draft.md

Write one that Spek authored with you, stamping its lifecycle record. Name the spek the conversation belonged to, and set a status, if either applies:

spektacular design author --data '{"source":"api","path":"payments/v2.md"}' --from ./draft.md
spektacular design author --data '{"source":"api","path":"payments/v2.md"}' --from ./draft.md --spec 000055_example --document-status final

Use design write for a document you wrote and are handing over, and design author for one Spek wrote with you. Re-running design author on an existing authored design updates it in place, keeping its original capture date and the speks already referencing it. Running design write over an authored design is refused rather than silently stripping that record.

Remove one from a declared source. A document nothing references is removed outright, and removing one that is already gone reports success rather than an error, so a tidy-up that retries is safe:

spektacular design delete --data '{"source":"api","path":"payments/v2.md"}'

A design that a spek still references is not removed. The refusal names every spek that references it and gives you the step to clear each one, and neither the document nor any spek is changed by the attempt, so a spek can never be left pointing at a design that is not there.

Removing a design and removing a reference to one are different things, and it is worth being clear which you want. design ref remove drops the pointer a spek carries and deliberately leaves the document where it is. design delete removes the document, and refuses while any pointer remains. Clearing the references first, then deleting, is the order the refusal walks you through. Anyone looking for a way to delete a design meets the reference command first, and it appears to succeed while the document is still sitting there.

Record a reference on a spek, or remove one. A reference naming a source the project has not declared is refused, and nothing is recorded:

spektacular design ref add --data '{"spec":"000054_example","source":"api","path":"payments/v2.md"}'
spektacular design ref remove --data '{"spec":"000054_example","source":"api","path":"payments/v2.md"}'

Ask what a spek references, and whether each reference resolves:

spektacular design ref list --data '{"spec":"000054_example"}'

{
  "error": false,
  "spec": "000054_example",
  "refs": [
    {
      "source": "api",
      "path": "payments/v2.md",
      "resolved": true,
      "location": "/work/design/api/payments/v2.md"
    },
    {
      "source": "ux",
      "path": "checkout-flow.md",
      "resolved": false,
      "location": "/work/ux-designs/checkout-flow.md"
    }
  ],
  "unresolved": 1,
  "next_action": "1 of 2 design references do not resolve; run 'design list' to see what each declared source holds, write the missing document with 'design write', or drop the reference with 'design ref remove'"
}

The spek stays readable because the design is referenced, not absorbed. The complaint that motivated design documents was speks that became unusable once a worked API shape was pasted into them. A reference keeps the spek at the altitude it reads best at while still binding the work to the design that was agreed.

A shipped design is never force-synced against the code. There is no drift detection, no checksums, and no command that requires a design to match the implementation. A design records what was agreed at the time it was agreed. Treating it as something to keep in step with the code would make it a second copy of the code, which is exactly what nobody maintains.

Storage is declared, not imposed. Teams already keep designs somewhere: a folder in the repo, a shared directory, a sibling checkout. Requiring them to move into a Spek-owned directory would be the one thing guaranteed to stop them adopting design documents at all. So you name the places, and nothing moves.