A structured spec lifecycle that emits one beautiful self-contained HTML file per artifact. Your spec reads like a quiet essay — packing tables, diagrams, diffs, and decision matrices. Rendered, reviewable, revision-safe.
right — spec-driven and verifiable, not vibe-coded. Intent is decided and reviewed before a line of code ships.
Markdown-based spec tooling produces dense documents that reviewers find tiring. The format limits you to flat prose, fragile tables, and external diagram tools. Three patterns recur:
Long undifferentiated prose; no progressive disclosure. Reviewers lose the thread before they reach what matters.
No diagrams, no real tables, no inline annotation, no semantic anchors past headings. The format runs out before the spec does.
Gated phases duplicate background context across artifacts because cross-linking is weak.
HTML fixes those directly — the challenge is keeping the source as editable as markdown, for humans and LLMs alike. That's what the component vocabulary is for.
A live <spec-budget> gauge, an INVEST self-check in the header, and an estimability gate in /spectastic.plan work together to stop bloated specs from ever reaching the planning phase. Open questions, missing defer-to=, or failing INVEST rows block the gate until they're resolved.
Five cover the core spec lifecycle, two cover ongoing change management, and one runs alongside implementation to capture debug sessions.
/spectastic.principles <name>
outputs
→
principles.html
Establish the project's five non-negotiable principles — the constitution every later artifact is checked against.
Eight commands. propose & apply loop forever as the spec evolves.
Some changes don't need a spec. Drop them into inbox.html as <spec-triage type="just-do"> cards — /spectastic.implement drains the inbox before it touches the active spec, so small batches don't queue behind the next big release.
Each change is one proposal.html — intent, scope, typed deltas, and tasks together. Reviewable in a browser; no git diff needed.
Four ops — added, modified, removed, renamed. A missing or wrong op renders the visible label MISSING OP. Silent failure impossible by construction.
Lifting REQ-AUTH-014 to must implicates the rate limiter — undocumented coupling we'd regret in 30 days.
/propose auto-fires the adversarial critic on must-tier edits, removed deltas, or cross-topic spans. Three risks land in a §5 risk register — identified → mitigated / accepted / rejected. /apply refuses while any risk is still identified.
Withdraw is a first-class outcome too — /apply --withdraw archives the proposal under changes/withdrawn/ and records "considered, withdrew" in the spec's changelog. Nothing is deleted; rejected ideas stay discoverable.
A small set of semantic custom elements covers the spec shape. Everything degrades to readable static HTML if the JS never loads — the spec is still a spec.
The system MUST issue a fresh token whenever a role changes, invalidating the prior token within one request cycle.
Red/green change blocks use semantic <ins> and <del> — reviewable without a git checkout.
| Option | Effort | Risk | Fit |
|---|---|---|---|
| Inline JS | Low | High | — |
| Web component ✓ | Med | Low | High |
| Server render | High | Med | Med |
Option × criterion table with a data-winner row.
In the context of token refresh, facing a race on logout, we observed a double-rotation — so the fix serialises the rotation lock.
Bootstrap the eight-command lifecycle into your repo, then point your AI coding agent at it and start authoring — principles first.
validate into GitHub Actions or GitLab CI and findings land as inline PR annotations.
Then open the project with your favorite AI coding agent and run /spectastic.principles to author your project's principles.