htmlspec-kit 0.1.0

package/skills/htmlspec-kit/SKILL.md

@@ -0,0 +1,584 @@
+---
+name: htmlspec-kit
+description: HTMLSpec is a spec-driven workflow that stores each change as a single browser-rendered .html dossier whose JSON payload lives in `script#SPEC`. Use when the user wants to plan, draft, validate, implement, or archive HTMLSpec changes - especially proposals, requirement specs, design notes, tasks, JSON Patch updates, or htmlspec-kit/htmlspec CLI commands such as `htmlspec task done`, `task in-progress`, `spec update`, `design update`, or `patch`.
+---
+
+# HTMLSpec Kit
+
+HTMLSpec is the HTML-backed spec driven development. The visible page is template chrome; the editable source of truth is the JSON inside `script#SPEC`. The default project folder is `spec/`. Run the CLI with `npx htmlspec-kit` (or `bunx htmlspec-kit`); either is fine, pick whichever the project already uses.
+
+## TL;DR Quick Checklist
+
+- Search existing work: `npx htmlspec-kit list`, then `npx htmlspec-kit show <change-id> --json` for any candidate. Use `rg` only for full-text searches across `spec/`.
+- Decide scope: new capability vs modify existing capability.
+- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`).
+- Scaffold: one `spec/changes/<change-id>.html` containing `proposal`, `spec` deltas, `design` (only if needed), and `tasks`.
+- Write deltas: in `spec.operations[]` use `ADDED | MODIFIED | REMOVED | RENAMED`; every requirement MUST have at least one scenario with `when` and `then`.
+- Validate: `npx htmlspec-kit validate <change-id>` and fix issues.
+- Request approval: do not start implementation until the proposal is approved.
+
+## Three-Stage Workflow
+
+### Stage 1: Creating Changes
+
+Create a change when you need to:
+
+- Add features or functionality
+- Make breaking changes (API, schema)
+- Change architecture or patterns
+- Optimize performance (changes behavior)
+- Update security patterns
+
+Triggers (examples):
+
+- "Help me create a change proposal"
+- "Help me plan a change"
+- "Help me create a proposal"
+- "I want to create a spec proposal"
+- "I want to create a spec"
+
+Loose matching guidance:
+
+- Contains one of: `proposal`, `change`, `spec`, `htmlspec`
+- With one of: `create`, `plan`, `make`, `start`, `help`
+
+Skip a change for:
+
+- Bug fixes that restore intended behavior
+- Typos, formatting, comments
+- Dependency updates (non-breaking)
+- Configuration changes
+- Tests for existing behavior
+
+**Workflow**
+
+1. Review `spec/specs/`, `npx htmlspec-kit list`, and any project conventions to understand current context.
+2. Choose a unique verb-led `change-id` and scaffold one `spec/changes/<change-id>.html` containing the four sections (`proposal`, `spec`, `design`, `tasks`).
+3. Draft `spec.operations` using `ADDED | MODIFIED | REMOVED | RENAMED` with at least one scenario per requirement.
+4. Run `npx htmlspec-kit validate <change-id>` and resolve any issues before sharing the change.
+
+### Stage 2: Implementing Changes
+
+Track these as TODOs and complete them one by one.
+
+1. **Read the SPEC JSON** with `npx htmlspec-kit show <change-id> --json`. Do not load the whole HTML file for routine work.
+2. **Read `proposal`** to understand what is being built.
+3. **Read `design`** when it exists to understand the technical decisions.
+4. **Read `tasks`** to get the implementation checklist.
+5. **Implement tasks sequentially**: mark each one in progress, edit code, then mark it done.
+6. **Confirm completion**: ensure every task in `tasks[].items[]` is `done` before changing the change status.
+7. **Approval gate**: do not start implementation until the change is reviewed and approved.
+
+Apply through CLI commands so the parser only rewrites the JSON payload:
+
+```bash
+npx htmlspec-kit task in-progress <change-id> 2.1
+npx htmlspec-kit task done <change-id> 2.1
+npx htmlspec-kit state <change-id> in-progress
+```
+
+### Stage 3: Archiving Changes
+
+After deployment, in a separate PR:
+
+- Move `spec/changes/<change-id>.html` to `spec/archive/YYYY-MM-DD-<change-id>.html`.
+- Update `spec/specs/` if capabilities changed.
+- Use `npx htmlspec-kit state <change-id> archived` to record the transition.
+- Run `npx htmlspec-kit validate <change-id>` to confirm the archived change still passes.
+
+## Before Any Task
+
+**Context Checklist**
+
+- [ ] Read relevant specs in `spec/specs/<capability>/spec.html`
+- [ ] Check pending changes in `spec/changes/` for conflicts
+- [ ] Check project conventions if present (for example `AGENTS.md` or `README.md`)
+- [ ] Run `npx htmlspec-kit list` to see active changes
+- [ ] Run `npx htmlspec-kit list --json` to see all dossiers with their status
+
+**Before Creating Specs**
+
+- Always check whether the capability already exists.
+- Prefer modifying existing specs over duplicating.
+- Use `npx htmlspec-kit show <change-or-spec> --json` to review current state.
+- If the request is ambiguous, ask one or two clarifying questions before scaffolding.
+
+### Search Guidance
+
+- Enumerate dossiers: `npx htmlspec-kit list` (or `--json` for scripts).
+- Show details: `npx htmlspec-kit show <change-id> --json`.
+- Full-text search: use ripgrep against the SPEC payloads.
+
+```bash
+rg -n '"id"|"title"|"status"' spec/changes
+```
+
+## Quick Start
+
+### CLI Commands
+
+```bash
+# Essential commands
+npx htmlspec-kit list                                         # List active changes
+npx htmlspec-kit list --json                                  # Machine readable
+npx htmlspec-kit show <change-id> --json                      # Show SPEC JSON
+npx htmlspec-kit validate <change-id>                         # Validate one change
+npx htmlspec-kit validate                                     # Validate every dossier under spec/
+npx htmlspec-kit state <change-id> archived                   # Mark archived after deploy
+
+# Project management
+npx htmlspec-kit init                                         # Initialize spec/ folder
+npx htmlspec-kit new <change-id> --title "<human title>"      # Scaffold a change
+
+# Mutations (parser-safe)
+npx htmlspec-kit task add <change-id> "Title" --group "Implementation"
+npx htmlspec-kit task in-progress <change-id> <task-id>
+npx htmlspec-kit task done <change-id> <task-id>
+npx htmlspec-kit spec update <change-id> --from /tmp/spec-fragment.html
+npx htmlspec-kit design update <change-id> --from /tmp/design-fragment.html
+npx htmlspec-kit patch <change-id> --patch '[{"op":"replace","path":"/status","value":"ready"}]'
+npx htmlspec-kit patch <change-id> --replace /proposal/whyHtml --string-value '<p>Why now...</p>'
+```
+
+`bunx htmlspec-kit ...` works the same way. Either is fine.
+
+### Command Flags
+
+- `--json` - machine-readable output
+- `--from <file>` - read HTML or JSON fragment from a file
+- `--patch '<rfc6902>'` - inline JSON Patch array
+- `--replace <pointer>` - shorthand for a single replace operation
+- `--value <json>` / `--string-value <text>` - value for `--replace`
+
+## Reading and Editing Rules
+
+Most of the time, read and edit only the SPEC JSON. Direct HTML edits are allowed when adjusting visual chrome, Alpine rendering, CSS, metadata, or carefully scoped manual JSON edits. For ordinary proposal/spec/design/task changes, prefer the CLI so the parser rewrites only the JSON payload.
+
+Use `npx htmlspec-kit patch` for targeted edits. It accepts RFC 6902 JSON Patch arrays (`add`, `replace`, `remove`, `move`, `copy`, `test`) and a convenience replace mode.
+
+## Project Layout
+
+```
+spec/
+├── specs/                   # Current truth - capabilities that are built
+│   └── <capability>/
+│       └── spec.html        # Requirements and scenarios for that capability
+├── changes/                 # Proposed - dossiers for changes in flight
+│   └── <change-id>.html     # Single dossier per change (proposal, spec, design, tasks)
+├── archive/                 # Completed changes
+│   └── YYYY-MM-DD-<change-id>.html
+└── templates/
+    └── change-template.html # Project-local copy of the bootstrap template
+```
+
+## Creating Changes
+
+### Decision Tree
+
+```
+New request?
+├─ Bug fix that restores spec behavior? → Fix directly
+├─ Typo/format/comment? → Fix directly
+├─ New feature/capability? → Create change
+├─ Breaking change? → Create change
+├─ Architecture change? → Create change
+└─ Unclear? → Create change (safer)
+```
+
+### Scaffolding
+
+1. **Create the dossier**:
+
+   ```bash
+   npx htmlspec-kit new <change-id> --title "<human title>"
+   ```
+
+2. **Draft the `proposal` section** so the SPEC JSON looks like:
+
+   ```json
+   {
+     "proposal": {
+       "whyHtml": "<p>1-2 sentences on the problem or opportunity.</p>",
+       "whatChanges": [
+         "Bullet list of changes. Mark breaking changes with BREAKING."
+       ],
+       "capabilities": {
+         "new": [
+           {
+             "name": "user-auth",
+             "description": "Brief capability description."
+           }
+         ],
+         "modified": []
+       },
+       "impact": ["Affected code, APIs, dependencies, or systems."]
+     }
+   }
+   ```
+
+   Apply with `npx htmlspec-kit patch <change-id>` or by editing the SPEC JSON directly.
+
+3. **Draft `spec` deltas** for every capability listed in `proposal.capabilities`:
+
+   ```json
+   {
+     "spec": {
+       "overviewHtml": "<p>Describe observable behavior.</p>",
+       "operations": [
+         {
+           "type": "ADDED",
+           "requirements": [
+             {
+               "id": "REQ-001",
+               "title": "Two-Factor Authentication",
+               "bodyHtml": "<p>Users MUST provide a second factor during login.</p>",
+               "scenarios": [
+                 {
+                   "id": "SCN-001",
+                   "title": "OTP required",
+                   "given": "valid credentials are provided",
+                   "when": "the user submits the login form",
+                   "then": "an OTP challenge is required"
+                 }
+               ]
+             }
+           ]
+         }
+       ]
+     }
+   }
+   ```
+
+4. **Draft `tasks`**:
+
+   ```json
+   {
+     "tasks": [
+       {
+         "id": "1",
+         "title": "Implementation",
+         "items": [
+           { "id": "1.1", "title": "Create database schema", "status": "todo" },
+           { "id": "1.2", "title": "Implement API endpoint", "status": "todo" },
+           { "id": "1.3", "title": "Add frontend component", "status": "todo" },
+           { "id": "1.4", "title": "Write tests", "status": "todo" }
+         ]
+       }
+     ]
+   }
+   ```
+
+5. **Draft `design` only when needed**. Create the `design` section if any of the following apply, otherwise leave it as the placeholder:
+   - Cross-cutting change (multiple services/modules) or a new architectural pattern
+   - New external dependency or significant data model changes
+   - Security, performance, or migration complexity
+   - Ambiguity that benefits from technical decisions before coding
+
+   Minimal `design` shape:
+
+   ```json
+   {
+     "design": {
+       "contextHtml": "<p>Background, constraints, stakeholders.</p>",
+       "goals": ["What this design achieves."],
+       "nonGoals": ["What is explicitly out of scope."],
+       "decisions": [
+         {
+           "id": "architecture",
+           "title": "Architecture",
+           "decisionHtml": "<p>What and why.</p>",
+           "rationaleHtml": "<p>Why this approach over alternatives.</p>",
+           "alternatives": ["Alternative considered + rationale."]
+         }
+       ],
+       "risksTradeoffs": ["Risk -> mitigation."],
+       "migrationPlan": ["Steps to deploy, rollback strategy."],
+       "openQuestions": ["Outstanding decisions or unknowns."]
+     }
+   }
+   ```
+
+## Spec Authoring Format
+
+### Critical: Scenario Shape
+
+Every requirement MUST have at least one scenario with `when` and `then`. `given` is optional.
+
+CORRECT:
+
+```json
+{
+  "id": "SCN-101",
+  "title": "User login success",
+  "when": "valid credentials are provided",
+  "then": "the system returns a JWT token"
+}
+```
+
+WRONG:
+
+- Free-form prose mixed into `bodyHtml` instead of a real scenario record.
+- Empty `scenarios` arrays.
+- Missing `when` or `then`.
+
+### Requirement Wording
+
+Use SHALL / MUST for normative requirements; avoid `should`/`may` unless intentionally non-normative.
+
+### Delta Operations
+
+`spec.operations[].type` must be one of:
+
+- `ADDED` - new capabilities
+- `MODIFIED` - changed behavior (carry over the full requirement before editing)
+- `REMOVED` - deprecated features (include `reasonHtml` and `migrationHtml`)
+- `RENAMED` - name changes (use `from` and `to` strings on the requirement)
+
+Headers and ids are matched after trimming whitespace.
+
+#### When to use ADDED vs MODIFIED
+
+- `ADDED` when the change is orthogonal to existing requirements.
+- `MODIFIED` when you change behavior, scope, or acceptance criteria of an existing requirement. Always paste the full updated requirement (including all scenarios) - the archiver replaces the entire requirement with what you provide.
+- `RENAMED` when only the name changes; combine with `MODIFIED` if behavior also changes.
+
+Common pitfall: using `MODIFIED` with partial content. That loses detail at archive time. If you are not actually changing the existing requirement, add a new one under `ADDED`.
+
+Authoring a `MODIFIED` requirement correctly:
+
+1. Locate the existing requirement in `spec/specs/<capability>/spec.html` (read the SPEC JSON, not the whole HTML file).
+2. Copy the entire requirement object (including every scenario).
+3. Place it under a `{ "type": "MODIFIED", "requirements": [ ... ] }` operation in the change dossier.
+4. Edit to reflect the new behavior. Keep at least one scenario with `when` and `then`.
+
+`RENAMED` example:
+
+```json
+{
+  "type": "RENAMED",
+  "requirements": [
+    {
+      "id": "REQ-203",
+      "title": "User Authentication",
+      "from": "Login",
+      "to": "User Authentication"
+    }
+  ]
+}
+```
+
+## JSON Schema
+
+The full JSON Schema for the `script#SPEC` payload is bundled at `assets/spec.schema.json`. Use it when creating or patching dossiers. Required top-level fields: `format`, `version`, `id`, `title`, `status`, `owner`, `createdAt`, `updatedAt`, `summaryHtml`, `proposal`, `spec`, `design`, `tasks`, `history`.
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://htmlspec.dev/schemas/spec.schema.json",
+  "title": "HTMLSpec SPEC payload",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "format",
+    "version",
+    "id",
+    "title",
+    "status",
+    "owner",
+    "createdAt",
+    "updatedAt",
+    "summaryHtml",
+    "proposal",
+    "spec",
+    "design",
+    "tasks",
+    "history"
+  ],
+  "properties": {
+    "format": { "const": "htmlspec" },
+    "version": { "type": "string" },
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "title": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["draft", "ready", "in-progress", "done", "archived"] },
+    "owner": { "type": "string" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "summaryHtml": { "type": "string" },
+    "proposal": { "$ref": "#/$defs/proposal" },
+    "spec": { "$ref": "#/$defs/spec" },
+    "design": { "$ref": "#/$defs/design" },
+    "tasks": { "type": "array", "items": { "$ref": "#/$defs/taskGroup" } },
+    "history": { "type": "array", "items": { "$ref": "#/$defs/historyEntry" } }
+  }
+}
+```
+
+The `$defs` for `proposal`, `capability`, `spec`, `requirementDelta`, `requirement`, `scenario`, `design`, `designDecision`, `taskGroup`, `task`, and `historyEntry` are in `assets/spec.schema.json`. Read the bundled file when you need the full constraints.
+
+## Troubleshooting
+
+### Common Errors
+
+**Change must have at least one delta**
+
+- Check that `spec.operations` has at least one entry under `spec/changes/<change-id>.html`.
+- Each operation must declare `type` (`ADDED`/`MODIFIED`/`REMOVED`/`RENAMED`).
+
+**Requirement must have at least one scenario**
+
+- Make sure each requirement object has a non-empty `scenarios` array.
+- Each scenario needs `id`, `title`, `when`, and `then`.
+
+**Silent scenario parsing failures**
+
+- The schema requires the exact shape above. Strings such as `WHEN ...` inside `bodyHtml` are not parsed as scenarios.
+- Debug with: `npx htmlspec-kit show <change-id> --json | jq '.spec.operations'`.
+
+### Validation Tips
+
+```bash
+npx htmlspec-kit validate <change-id>
+npx htmlspec-kit show <change-id> --json | jq '.tasks[] | .items[]'
+npx htmlspec-kit show <change-id> --json | jq '.spec.operations[].requirements[].scenarios'
+```
+
+## Happy Path Script
+
+```bash
+# 1) Explore current state
+npx htmlspec-kit list
+# Optional full-text search:
+# rg -n '"Requirement"|"Scenario"' spec/changes spec/specs
+
+# 2) Choose change id and scaffold
+CHANGE=add-two-factor-auth
+npx htmlspec-kit new "$CHANGE" --title "Add two-factor authentication"
+
+# 3) Add a requirement and a task
+npx htmlspec-kit patch "$CHANGE" --patch '[
+  { "op": "add", "path": "/spec/operations/0/requirements/-", "value": {
+    "id": "REQ-201",
+    "title": "Two-Factor Authentication",
+    "bodyHtml": "<p>Users MUST provide a second factor during login.</p>",
+    "scenarios": [
+      { "id": "SCN-201", "title": "OTP required",
+        "given": "valid credentials are provided",
+        "when": "the user submits the login form",
+        "then": "an OTP challenge is required" }
+    ]
+  } }
+]'
+npx htmlspec-kit task add "$CHANGE" "Implement OTP challenge" --group "Implementation"
+
+# 4) Validate
+npx htmlspec-kit validate "$CHANGE"
+```
+
+## Multi-Capability Example
+
+```
+spec/changes/add-2fa-notify.html
+└── (script#SPEC)
+    └── proposal.capabilities.new = [{ "name": "auth" }, { "name": "notifications" }]
+    └── spec.operations = [
+        { "type": "ADDED", "requirements": [ /* auth: Two-Factor Authentication */ ] },
+        { "type": "ADDED", "requirements": [ /* notifications: OTP Email */ ] }
+      ]
+```
+
+Both capabilities live in the same dossier; their requirements are grouped by the `requirements[]` array inside each `ADDED` operation. Promote them into `spec/specs/<capability>/spec.html` when archiving.
+
+## Best Practices
+
+### Simplicity First
+
+- Default to small dossiers. If a change needs many decisions, prefer splitting into multiple changes.
+- Avoid frameworks without clear justification.
+- Choose boring, proven patterns.
+
+### Complexity Triggers
+
+Only add complexity with:
+
+- Performance data showing the current solution is too slow.
+- Concrete scale requirements (>1000 users, >100 MB data).
+- Multiple proven use cases requiring abstraction.
+
+### Clear References
+
+- Use `file.ts:42` format for code locations.
+- Reference specs as `spec/specs/<capability>/spec.html`.
+- Link related changes and PRs in `proposal.impact`.
+
+### Capability Naming
+
+- Use verb-noun: `user-auth`, `payment-capture`.
+- Single purpose per capability.
+- Ten-minute understandability rule.
+- Split if the description needs "AND".
+
+### Change ID Naming
+
+- Use kebab-case, short and descriptive: `add-two-factor-auth`.
+- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`.
+- Ensure uniqueness; if taken, append `-2`, `-3`, etc.
+
+## Tool Selection Guide
+
+| Task                  | Tool       | Why                      |
+| --------------------- | ---------- | ------------------------ |
+| Find files by pattern | Glob       | Fast pattern matching    |
+| Search code content   | Grep / rg  | Optimized regex search   |
+| Read specific files   | Read       | Direct file access       |
+| Inspect SPEC JSON     | `npx htmlspec-kit` | Parser-safe and scoped   |
+| Explore unknown scope | Subagent   | Multi-step investigation |
+
+## Error Recovery
+
+### Change Conflicts
+
+1. Run `npx htmlspec-kit list` to see active changes.
+2. Check for overlapping capability names in `proposal.capabilities`.
+3. Coordinate with change owners.
+4. Consider combining proposals into one dossier.
+
+### Validation Failures
+
+1. Run `npx htmlspec-kit validate <change-id>`.
+2. Inspect with `--json` to localize the failure.
+3. Verify each requirement has a non-empty `scenarios` array.
+4. Verify task ids follow `X.Y`.
+
+### Missing Context
+
+1. Read project conventions (root `AGENTS.md`, `README.md`) first.
+2. Read related capability dossiers in `spec/specs/`.
+3. Review recent archives in `spec/archive/`.
+4. Ask the user for clarification.
+
+## Quick Reference
+
+### Stage Indicators
+
+- `spec/changes/` - proposed, not yet built.
+- `spec/specs/` - built and deployed.
+- `spec/archive/` - completed changes.
+
+### Section Purposes
+
+- `proposal` - why and what.
+- `spec` - requirements and scenarios.
+- `design` - technical decisions.
+- `tasks` - implementation steps.
+
+### CLI Essentials
+
+```bash
+npx htmlspec-kit list                  # What is in progress?
+npx htmlspec-kit show <change-id>      # View summary
+npx htmlspec-kit show <change-id> --json
+npx htmlspec-kit validate <change-id>  # Is it correct?
+npx htmlspec-kit state <change-id> archived
+```
+
+Remember: the JSON in `script#SPEC` is the truth. Changes are proposals. Keep them in sync.

package/skills/htmlspec-kit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HTMLSpec Kit"
+  short_description: "Plan and run HTMLSpec changes (proposal, spec, design, tasks)."
+  default_prompt: "Plan, draft, validate, implement, or archive an HTMLSpec change. Read script#SPEC JSON, not the whole HTML."