Addressing documents: the rules

Every feature gets one name when its workflow starts, such as 000059_normalise-artifact-addressing. That name, exactly as the workflow records it, is how you reach its spec, its plan documents and its changelog record.

Four rules cover every store command:

A spec or changelog record is addressed by the bare feature name. spektacular spec file read 000059_normalise-artifact-addressing reads that feature’s spec.
A plan document is addressed by the feature name and a document name, as two separate arguments. The document is one of plan, context, research or test-plan.
A name never carries a file extension or a path. .md, a /, or a plan written as one joined path such as <name>/plan.md is refused with unexpected_extension, and the error restates the command correctly spelled.
Every name a list prints is accepted unchanged by read, write, delete and set-document-status. Copy it straight from the list.

Specs: spec file

A spec is one document per feature, addressed by the feature name alone.

List every spec the store holds:

spektacular spec file list

Read one, using a name from that list:

spektacular spec file read 000059_normalise-artifact-addressing

Write one from a staged file, then change its status without touching the body:

spektacular spec file write 000059_normalise-artifact-addressing --from .spektacular/tmp/spec.md
spektacular spec file set-document-status 000059_normalise-artifact-addressing --document-status final

spektacular spec file delete <name> removes a spec by the same name.

Plans: plan file

A plan is a set of documents under one feature, so every plan document command takes two arguments: the feature, then the document.

With no argument, plan file list lists the features that have a plan:

spektacular plan file list

With a feature name, it lists that plan’s documents by their bare names:

spektacular plan file list 000059_normalise-artifact-addressing

{
  "error": false,
  "files": [
    {
      "closed_date": "2026-09-25",
      "created_date": "2026-09-25",
      "document_status": "final",
      "modified_at": "2026-09-25T13:23:54Z",
      "name": "context",
      "path": "plans/000059_normalise-artifact-addressing/context.md"
    },
    {
      "closed_date": "2026-09-25",
      "created_date": "2026-09-25",
      "document_status": "final",
      "modified_at": "2026-09-25T13:44:18Z",
      "name": "plan",
      "path": "plans/000059_normalise-artifact-addressing/plan.md"
    },
    {
      "closed_date": "2026-09-25",
      "created_date": "2026-09-25",
      "document_status": "final",
      "modified_at": "2026-09-25T13:23:54Z",
      "name": "research",
      "path": "plans/000059_normalise-artifact-addressing/research.md"
    }
  ]
}

Read, write, delete or change the status of one document by naming both:

spektacular plan file read 000059_normalise-artifact-addressing plan
spektacular plan file write 000059_normalise-artifact-addressing research --from .spektacular/tmp/research.md
spektacular plan file set-document-status 000059_normalise-artifact-addressing plan --document-status final
spektacular plan file delete 000059_normalise-artifact-addressing test-plan

Naming a feature without a document is refused with document_required, and asking for a document the plan does not hold returns not_found pointing at plan file list <name>.

Changelog records: changelog file

A changelog record is one document per feature, addressed by the bare feature name, in the project’s central store or in a registered repository’s own store.

Read a record from the project’s central changelog:

spektacular changelog file read 000059_normalise-artifact-addressing

Add --repo to route through a registered repository’s own changelog store instead. The name is the same:

spektacular changelog file read 000059_normalise-artifact-addressing --repo docs
spektacular changelog file list --repo docs

write takes --repo in the same way, and delete and set-document-status address a record by its bare name too.

The path a list reports differs between the two stores:

Central store: changelog/<name>.md, relative to the folder holding the project’s config.yaml.
With --repo: changelog/<project>/<name>.md, relative to the folder holding that repository’s repo.yaml, where <project> is the name of the project that wrote the record.

Where documents are stored: name and path

Every list entry carries two separate facts: the name you address the document by, and the place the store keeps it.

name is the address. It is what read, write, delete and set-document-status accept.
path is where the store keeps the document, relative to the folder holding the config file that declares the store: specs/<name>.md, plans/<name> for a plan in a feature list, plans/<name>/plan.md for one of its documents, changelog/<name>.md, or changelog/<project>/<name>.md with --repo.

Entries also carry modified_at and, where the document has them, created_date, document_status and closed_date. A path is for reading or reporting a location; never pass it back to a store command.

The workflow commands follow the same split. The results of the workflow new and goto commands report the plan’s address and its location, never an absolute host path:

{
  "plan_name": "000059_normalise-artifact-addressing",
  "plan_document": "plan",
  "plan_path": "plans/000059_normalise-artifact-addressing/plan.md"
}

plan_name and plan_document together are exactly what plan file read takes. A spec workflow reports spec_path the same way, and plan and implement workflows report plan_path with plan_document, all relative to the folder holding config.yaml. To see where a workflow has got to, run spektacular status, which addresses every spek and plan by name. See Plan tasks for the status view.

Error codes

A refused address returns the standard JSON error envelope, and its next_action gives the command to run instead.

unexpected_extension error

The name carried a file extension or a path separator, or a plan document was written as one joined path such as <name>/plan.md. Nothing is read or written. next_action restates the same command correctly spelled. For spektacular spec file read x.md:

{
  "error": true,
  "code": "unexpected_extension",
  "message": "\"x.md\" carries a file extension or path; spec documents are addressed by the bare feature name",
  "resource": "x.md",
  "next_action": "run `spektacular spec file read x`"
}

document_required error

A plan document command named a feature but no document. next_action reads: run spektacular plan file list <name> to see its documents, then name one, e.g. spektacular plan file read <name> plan.

not_found error

The name is well formed but the store holds no such document. next_action points at the matching list command, such as spektacular spec file list or spektacular plan file list <name>.

Upgrading from earlier spellings

Earlier releases addressed documents by file name. This is a breaking change with no deprecation window: the old spellings are refused with unexpected_extension, whose next_action gives the new form.

Command	Earlier spelling	Now
Spec read	`spec file read <name>.md`	`spec file read <name>`
Spec write	`spec file write <name>.md --from <file>`	`spec file write <name> --from <file>`
Spec delete	`spec file delete <name>.md`	`spec file delete <name>`
Spec status	`spec file set-document-status <name>.md`	`spec file set-document-status <name>`
Spec list	names such as `<name>.md`	names such as `<name>`
Plan read	`plan file read <name>/plan.md`	`plan file read <name> plan`
Plan write	`plan file write <name>/research.md --from <file>`	`plan file write <name> research --from <file>`
Plan delete	`plan file delete <name>/context.md`	`plan file delete <name> context`
Plan status	`plan file set-document-status <name>/plan.md`	`plan file set-document-status <name> plan`
Plan list	document names such as `plan.md`	`plan file list <name>` prints `plan`, `context`, `research`, `test-plan`
Changelog read	`changelog file read <name>.md`	`changelog file read <name>`
Changelog write	`changelog file write <name>.md --from <file>`	`changelog file write <name> --from <file>`
Changelog delete	`changelog file delete <name>.md`	`changelog file delete <name>`
Changelog status	`changelog file set-document-status <name>.md`	`changelog file set-document-status <name>`
Changelog list	names such as `<name>.md`	names such as `<name>`

Two reported locations changed as well. A list’s path and the workflow results’ plan_path are now relative to the folder holding the config file that declares the store, such as plans/<name>/plan.md, rather than an absolute host path. Scripts that read either field as a full path need to resolve it against that folder, or switch to the name for addressing.

The per-kind status commands and plan export are gone too, replaced outright by one top-level status command with no aliases. Its report covers what the old commands reported, from the epic down to each task; see Plan tasks for its fields.

Removed	Replaced by
`spec status`, `plan status`, `implement status`	`status`
`spec status <name>`, `plan status <name>`	`status <name>`
`plan export <name> [--format]`	`status <name> [--format]`

Addressing specs, plans and changelogs