HTMLSpec Kit

HTMLSpec is a lightweight spec-driven workflow for proposal -> specs -> design -> tasks. It stores each change as a browser-rendered HTML dossier. The editable source of truth is the JSON payload inside:

<script id="SPEC" type="application/json">
  { "format": "htmlspec" }
</script>

The default project folder is spec/.

Install Skills

This repo ships an agent-compatible skill under skills/htmlspec-kit.

npx skills add . --skill htmlspec-kit --agent '*' --copy -y
# or
bunx skills add . --skill htmlspec-kit --agent '*' --copy -y

CLI

Run from a project root:

npx htmlspec-kit init
npx htmlspec-kit new add-dark-mode --title "Add dark mode"
npx htmlspec-kit show add-dark-mode --json
npx htmlspec-kit task start add-dark-mode 2.1
npx htmlspec-kit task done add-dark-mode 2.1
npx htmlspec-kit task add add-dark-mode "Add e2e coverage" --group "Validation"
npx htmlspec-kit spec update add-dark-mode --from /tmp/spec-fragment.html
npx htmlspec-kit design update add-dark-mode --from /tmp/design-fragment.html
npx htmlspec-kit patch add-dark-mode --patch '[{"op":"replace","path":"/status","value":"ready"}]'
npx htmlspec-kit patch add-dark-mode --replace /proposal/whyHtml --string-value '<p>Why now...</p>'

bunx htmlspec-kit ... works the same way; pick whichever the project already uses.

For local development in this repo, use:

bun bin/htmlspec.ts init
bun bin/htmlspec.ts new add-dark-mode --title "Add dark mode"

Project Layout

spec/
  changes/              active change dossiers
  specs/                canonical specs, if you promote a change
  archive/              archived change dossiers
  templates/
    change-template.html

Data Model

Each dossier contains proposal, spec, design, tasks, and history sections:

• proposal: why, what changes, capabilities, and impact.
• spec: delta operations (ADDED, MODIFIED, REMOVED, RENAMED) with requirements and scenarios.
• design: context, goals/non-goals, decisions, risks/trade-offs, migration plan, and open questions.
• tasks: grouped tasks with todo, in-progress, or done.
• history: CLI-maintained breadcrumbs.

Agents should usually read npx htmlspec-kit show <id> --json and mutate the SPEC payload through the CLI. Direct HTML edits are allowed when changing the visual template, Alpine rendering, CSS, metadata, or when a scoped manual JSON edit is clearer.

Test

bun install
bun run check
bun run e2e