Documentation

Get started with spectastic

A directory you copy into your project. One self-contained HTML file per artifact, an eight-verb lifecycle, and a calm typographic system that prioritises readability over chrome.

Install

One CLI, two subcommands. @spectastic/cli provides init (bootstrap a project) and validate (check spec-html files against the canonical grammar — emits human, JSON, or SARIF).

# one-off via npx
npx @spectastic/cli init
npx @spectastic/cli validate "specs/**/*.html"
# or install globally
npm i -g @spectastic/cli
cd my-new-project && spectastic init

Then open the project with your favorite AI coding agent and run /spectastic.principles to author your project's principles.

The eight commands

Eight commands. Five cover the core lifecycle, two cover ongoing change, one runs alongside implementation.

01

/spectastic.principles

Establish project principles

principles.html

02

/spectastic.spec

Specify one feature

spec.html

03

/spectastic.plan

Plan the build

plan.html

04

/spectastic.tasks

Derive ordered tasks

tasks.html

05

/spectastic.implement

Build a task

code + tick

06

/spectastic.propose

Propose a change

proposal.html

07

/spectastic.apply

Apply an approved change

patched + archived

08

/spectastic.triage

Triage a defect

triage-log.html

Two more verbs sit outside the core eight — the opt-in extended commands, explain and explore.

Component vocabulary

Tag name is schema. Sixteen semantic custom elements cover the spec shape, grouped by job — everything degrades to readable static HTML if the JS never loads. The full reference documents another ten editorial helpers (admonitions, tabs, glossary, conformance index).

Core

<spec-meta>

Header metadata — status, owner, version, dates.

<spec-tldr>

Boxed abstract — always near the top.

<spec-requirement>

Unit of conformance — stable id + priority="must|should|may".

<spec-decision>

ADR card — context, decision, consequences.

Discipline

<spec-budget>

Live size gauge — words / reqs / read-time vs configurable budgets. Amber at 70%, red over.

<spec-out-of-scope>

Deferral register — every entry requires defer-to=. Cuts become tracked deferrals.

<spec-questions>

Numbered open-question register — blocks the estimability gate until resolved.

<spec-parent>

Marks a spec as a slice of a larger umbrella — specid="…" required.

Change

<spec-change>

Proposal wrapper — intent, scope, deltas, tasks; status pill proposed → applied / withdrawn.

<spec-delta op=…>

One typed change. added | modified | removed | renamed. Wrong op renders MISSING OP.

<spec-risk>

Adversarial finding — identified → mitigated / accepted / rejected. /apply refuses on any identified.

<spec-diff>

Red/green change block via semantic <ins> and <del>.

Editorial

<spec-matrix>

Option × criterion table with a data-winner row.

<spec-tradeoff>

Inline bar sparklines scoring options on a few axes.

<spec-triage>

One-screen debug card — Y-statement, expected/actual, regen-test pill.

<spec-sidenote>

Margin note for asides that would interrupt the reading flow.

Editing principles

Five rules keep the source LLM-editable and diff-friendly.

1 Source order is reading order — don't reorder content via JS.
2 Semantic tags over class soup — a concept gets a tag, not a div.
3 IDs are contracts — REQ-AUTH-001, D-001, T-110 — stable forever.
4 Progressive enhancement — JS adds polish; the spec works without it.
5 Calm density — generous line-height, narrow measure, no idle chrome.

See the worked examples → ← Home