htmlspec-kit 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# 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:
+
+```html
+<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`.
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+bun bin/htmlspec.ts init
+bun bin/htmlspec.ts new add-dark-mode --title "Add dark mode"
+```
+
+## Project Layout
+
+```text
+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
+
+```bash
+bun install
+bun run check
+bun run e2e
+```

package/bin/htmlspec.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+
+import { runCli } from "../src/cli";
+
+runCli().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Error: ${message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "htmlspec-kit",
+  "version": "0.1.0",
+  "description": "HTML-backed spec-driven development artifacts and CLI.",
+  "type": "module",
+  "bin": {
+    "htmlspec": "bin/htmlspec.ts",
+    "htmlspec-kit": "bin/htmlspec.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills/htmlspec-kit",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "bun x tsc --noEmit",
+    "test": "bun test",
+    "e2e": "bun test e2e",
+    "e2e:agent": "bun scripts/agent-e2e.ts"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "parse5": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.3",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  }
+}