@skitterbyte/skitterspec 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reuben Greaves
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @skitterbyte/skitterspec
+
+Spec-driven-development (SDD) workflow for [Claude Code](https://claude.com/claude-code),
+packaged so you can drop the same spec lifecycle into any project.
+
+It installs the **eight spec-lifecycle skills** plus a general **`/commit`**
+skill, two governing rules, and the `specs/` folder structure. The lifecycle is
+`backlog → in-progress → complete / cancelled`, with `.core` holding always-apply
+project rules.
+
+| Skill | Action | Status | Folder |
+|-------|--------|--------|--------|
+| `/spec` | (Feature) Grill to a shared understanding, then write a concise spec | `Draft` | `specs/backlog/` |
+| `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
+| `/spec-ready` | Confirm the spec is groomed | `Ready` | `specs/backlog/` |
+| `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
+| `/spec-go` | Implement the next phase (with tests) | `In Progress` | `specs/in-progress/` |
+| `/spec-complete` | Verify all phases done + tests green | `Complete` | `specs/complete/` |
+| `/spec-cancel` | Record progress, stamp a reason | `Cancelled` | `specs/cancelled/` |
+| `/spec-init` | Bootstrap/repair the workflow (manual path) | — | — |
+| `/commit` | Stage the task's files, run typecheck + tests, write a conventional commit (+ release-note footer) | — | (unchanged) |
+
+## Install into a project
+
+From the root of the target project:
+
+```bash
+npx @skitterbyte/skitterspec init
+```
+
+On a terminal it runs an **interactive setup** (skip it with `--yes` or drive it
+with the flags below). It's idempotent — it creates only what's missing and
+never clobbers customised files. It writes:
+
+```
+.claude/skills/spec*/SKILL.md   # the 8 spec-lifecycle skills
+.claude/skills/commit/SKILL.md  # the /commit skill
+.claude/rules/spec-planning.md  # governing rule (the single source of truth)
+.claude/rules/commit-messages.md # commit message + release-note grammar
+specs/{.core,backlog,in-progress,complete,cancelled}/
+specs/backlog/00-index.md            # live backlog view (skill-maintained)
+specs/complete/00-index.md           # append-only completion log
+CLAUDE.md                       # adds a "## Spec workflow" section (created if absent)
+```
+
+If you enable the **release tooling** (see below) it also writes:
+
+```
+skitterspec.config.json         # which artifacts to generate, filenames, scope→area map
+scripts/generate-changelog.js   # dev-facing CHANGELOG generator   (if changelog enabled)
+scripts/generate-releases.js    # user-facing RELEASES generator    (if releases enabled)
+scripts/lib/                     # shared git + config helpers
+package.json                    # adds a "version" hook + changelog/releases npm scripts
+```
+
+### Options
+
+```bash
+npx @skitterbyte/skitterspec init ./path/to/project   # target a dir (default: cwd)
+npx @skitterbyte/skitterspec init --yes               # accept defaults, skip the prompts
+npx @skitterbyte/skitterspec init --force             # overwrite existing skill/rule/script files
+npx @skitterbyte/skitterspec init --no-claude-md      # don't touch CLAUDE.md
+npx @skitterbyte/skitterspec update                   # re-copy skills + rule + scripts, leave specs/ + config alone
+```
+
+Release-tooling flags (drive setup without the prompts):
+
+```bash
+--changelog / --no-changelog        # enable/disable CHANGELOG generation
+--releases  / --no-releases         # enable/disable user-facing release notes
+--changelog-file=NAME               # changelog filename (default CHANGELOG.md)
+--releases-file=NAME                # release-notes filename (default RELEASES.md)
+--product-name=NAME                 # product name shown in the release-notes header
+--version-hook / --no-version-hook  # wire (or skip) the npm "version" hook
+```
+
+`update` pulls newer skill/rule/script versions after upgrading the package,
+without disturbing your specs or `skitterspec.config.json`. The CLAUDE.md section
+is wrapped in `<!-- skitterspec:start -->`…`<!-- skitterspec:end -->` markers so
+`update` can refresh it in place.
+
+## Changelog & release-note tooling (opt-in)
+
+Conventional commits already say what changed; skitterspec can turn them into two
+generated artifacts at `npm version`:
+
+- **`CHANGELOG.md`** — dev-facing, built from commit **subjects** (Keep a Changelog
+  format: feat→Added, fix→Fixed, perf/refactor→Changed, breaking→Changed).
+- **`RELEASES.md`** — user-facing, built **only** from `Release-Note:` commit
+  **footers**, grouped by area and bucket (New / Improved / Fixed / Action
+  required). The `/commit` skill writes these footers; the grammar lives in
+  `.claude/rules/commit-messages.md`.
+
+Both walk *commits since the last version tag*. Generation is opt-in per artifact
+and recorded in **`skitterspec.config.json`** at the repo root:
+
+```json
+{
+  "version": 1,
+  "changelog": { "enabled": true, "file": "CHANGELOG.md" },
+  "releases":  { "enabled": true, "file": "RELEASES.md",
+                 "productName": "My App", "scopeAreas": {} },
+  "versionHook": true
+}
+```
+
+`scopeAreas` maps a commit scope to a user-facing area (e.g. `{"reqs":
+"Requisitions"}`); unmapped scopes fall back to Title-Case, and a `Release-Area:`
+footer overrides per-commit. When `versionHook` is on, `init` wires npm scripts:
+
+```bash
+npm run changelog          # regenerate CHANGELOG.md from commits since last tag
+npm run releases           # regenerate RELEASES.md
+npm run changelog:retro -- 5   # backfill the last 5 tagged releases
+npm version <patch|minor|major>  # bumps, regenerates both, and stages them
+```
+
+The generators are plain Node (no `tsx`/`ts-node`); the only runtime dependency
+the package itself adds is [`prompts`](https://www.npmjs.com/package/prompts) for
+the interactive `init`.
+
+## Spec structure
+
+Every spec is a **folder**, never a bare file:
+
+```
+specs/backlog/feat-<name>/
+  00-overview.md     # dashboard: problem, decisions, solution, phase index, logs
+  01-<phase-slug>.md # phase 1 — goal + task checkboxes (tests included)
+  02-<phase-slug>.md # phase 2 …
+```
+
+`00-overview.md` is the index — it carries a **phase table** linking to each
+phase file with its status (`⬜`/`🔄`/`✅`). **Each phase is its own file** so it's
+easy to dive into one phase without wading through the whole spec. The lifecycle
+skills keep the index and phase files in sync.
+
+## After install — tailor it
+
+The shipped skills are **stack-agnostic**. They say things like "run the
+project's typecheck and test commands" and "honour the project's conventions".
+Make those concrete once, in **`.claude/rules/spec-planning.md`** (the
+*Project conventions* section): set your real typecheck/test/lint commands and
+link your other `.claude/rules/*.md`. The skills point at that file, so you don't
+edit seven files per project.
+
+## How it's distributed
+
+The skills, rule, and generator scripts are plain assets under
+[`assets/`](./assets). The CLI ([`bin/skitterspec.js`](./bin/skitterspec.js) →
+[`src/`](./src)) copies them into place, patches `CLAUDE.md`, and (for the release
+tooling) writes `skitterspec.config.json` and npm scripts. It needs Node 18+ and
+one runtime dependency, [`prompts`](https://www.npmjs.com/package/prompts), used
+only for the interactive `init`. The copied generator scripts are dependency-free
+and read their config from `skitterspec.config.json` — they never call back into
+this package.
+
+Because the files are copied into the consumer repo (not symlinked), each project
+pins its own version and can diverge. Re-run `update` to re-sync from a newer
+package release.
+
+## License
+
+MIT

package/assets/claude-md-section.md

@@ -0,0 +1,34 @@
+## Spec workflow
+
+Spec-driven development runs through eight skills — use them so structure and
+lifecycle stay consistent (see `.claude/rules/spec-planning.md`):
+
+| Skill | Action | Status | Folder |
+|-------|--------|--------|--------|
+| `/spec` | (Feature) Grill to a clear shared understanding, then write a concise spec | `Draft` | `specs/backlog/` |
+| `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
+| `/spec-ready` | Confirm the spec is groomed (no open questions, phases + tests defined) | `Ready` | `specs/backlog/` |
+| `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
+| `/spec-go` | Implement the next phase (with tests) | `In Progress` | `specs/in-progress/` |
+| `/spec-complete` | Verify all phases done + tests green | `Complete` | `specs/complete/` |
+| `/spec-cancel` | Record progress, stamp a reason on the header | `Cancelled` | `specs/cancelled/` |
+| `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
+
+Every spec has a **type** (`> **Type:** Feature\|Bug`) and a filename prefix
+(`feat-<name>` / `bug-<name>`) — never `[BUG]` brackets (glob hazard). Specs use
+markdown checkboxes (`- [ ]`) for task tracking and are the single source of
+truth for progress. Every spec is a folder: `00-overview.md` is the dashboard
+(problem, decisions, solution, **phase index**, logs) and **each phase is its own
+file** (`01-<slug>.md`, `02-…`) holding that phase's tasks — never a bare file,
+never phases lumped into the overview. **Every phase ends with creating and
+running tests**; decisions go in the spec's Changelog, state transitions in its
+State log.
+
+> Tailor the per-phase test commands and project conventions referenced by the
+> spec skills to this project's stack (see `.claude/rules/spec-planning.md`).
+
+Also installed: **`/commit`** — stage only the task's files, run typecheck +
+tests, then write a conventional-commit message with a `Release-Note:` footer
+for user-visible changes (grammar in `.claude/rules/commit-messages.md`). If the
+release tooling is enabled (`skitterspec.config.json`), those footers feed the
+generated `CHANGELOG.md`/`RELEASES.md` at `npm version`.

package/assets/rules/commit-messages.md

@@ -0,0 +1,85 @@
+# Commit Messages
+
+## Format
+
+`type(scope): subject` — [Conventional Commits](https://www.conventionalcommits.org/)
+
+## Length limits
+
+- **Subject line:** 50 characters max
+- **Body lines:** 72 characters max
+
+(These match the common commitlint defaults — if your project runs commitlint,
+they'll be enforced; otherwise treat them as the convention.)
+
+## Template
+
+```
+type(scope): subject
+
+- Bullet point 1
+- Bullet point 2
+```
+
+## Types
+
+`feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `style`
+
+## Rules
+
+- Start bullets with a verb (Add, Fix, Refactor, Remove, Update)
+- Be specific about what changed (file, module, feature)
+- No emojis, no trailing punctuation
+- No **authorship** trailers — `Co-authored-by`, `Signed-off-by`, etc.
+  (The `Release-Note:` footers below are the one permitted exception — they
+  carry content, not attribution.)
+- Use plain `git commit -m "message"` only
+- Output ONLY the commit message — no explanations before or after
+
+## Release notes footer (user-facing changes)
+
+When a change is **user-visible** (a feature, fix, or improvement an end user
+would notice), add a `Release-Note:` footer. The terse subject feeds the
+dev-facing changelog (`CHANGELOG.md` by default); the footer feeds the
+user-facing release notes (`RELEASES.md` by default) via
+`scripts/generate-releases.js`, run at `npm version`. Both are generated from
+the same commit. Filenames, the product name, and the scope→area map are
+configured in `skitterspec.config.json` (this whole section applies only when
+the release tooling is installed — see the project README).
+
+```
+feat(tasks): explicit state/created dates + sort-by
+
+- Add stateEnteredAt column, sortBy param
+
+Release-Note: You can now sort your task inbox by when an item entered its
+current state or when it was created, with both dates shown on every row.
+```
+
+Grammar:
+
+- `Release-Note: <text>` — a plain-English, benefit-framed sentence aimed at
+  users (not "add column X" — say what they can now do). Multi-line is fine;
+  wrap continuation lines at 72 like the body.
+- `Release-Note!: <text>` — same, but also promoted into the release's
+  **Highlights** line. Use for the headline change of a release.
+- `Release-Area: <name>` — optional. Overrides the scope→area mapping (from
+  `skitterspec.config.json` → `releases.scopeAreas`) when the dev scope isn't a
+  user area (e.g. scope `engine` but area `Platform`).
+- `Release-Note: none` — explicit "not user-facing" marker (same effect as
+  omitting it; documents the decision).
+
+Rules:
+
+- **Opt-in.** Omit the footer for internal/dev-only changes (`chore`, `test`,
+  `docs`, `style`, refactors with no user effect, plumbing). Only commits with a
+  footer appear in `RELEASES.md`.
+- Put a **blank line before** the footer (so it's a proper commit footer).
+- `feat`→New, `fix`→Fixed, `perf`/`refactor`→Improved, breaking→Action required
+  — the bucket is derived from the commit type, so just write the note.
+
+## Abbreviations
+
+Common short forms are fine in subjects — e.g. `config`, `ctx`, `impl`, `util`,
+`id`, `repo`. List any project-specific abbreviations your team allows in your
+own `.claude/rules/`.

package/assets/rules/spec-planning.md

@@ -0,0 +1,130 @@
+# Spec Planning
+
+Spec-driven development is driven by eight skills — use them rather than
+hand-rolling specs so the structure and lifecycle stay consistent. Each sets a
+status on the spec header (`> **Status:** …`):
+
+| Skill | Purpose | Status | Folder |
+|-------|---------|--------|--------|
+| `/spec` | (Feature) Grill to a clear shared understanding, then write a new spec | `Draft` | `specs/backlog/` |
+| `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
+| `/spec-ready` | Confirm it's groomed (no open questions, phases + tests defined) | `Ready` | `specs/backlog/` |
+| `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
+| `/spec-go` | Implement the next phase (with tests) | `In Progress` | `specs/in-progress/` |
+| `/spec-complete` | Verify all phases done + tests green | `Complete` | `specs/complete/` |
+| `/spec-cancel` | Record progress, stamp a reason on the header | `Cancelled` | `specs/cancelled/` |
+| `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
+
+Status flow: `Draft → Ready → In Progress → Complete` (or `Cancelled` from any
+state). `/spec-ready` is a grooming gate only — it does not move the folder.
+`/spec-bug` is test-first and starts straight in `In Progress` (work begins
+immediately), so it skips Draft/Ready.
+
+## Project conventions (fill this in)
+
+The spec skills tell you to run "your project's typecheck and test commands" and
+to "honour project conventions". Make those concrete here so specs stay
+consistent with the codebase:
+
+- **Typecheck command:** `<e.g. npm run typecheck>`
+- **Test command:** `<e.g. npm test>` (single file/dir: `<e.g. npx vitest run path>`)
+- **Lint/format:** `<e.g. npm run lint>`
+- **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
+  (architecture, code style, testing, database, etc.) rather than restating them.
+
+## Spec types — Feature vs Bug
+
+Every spec is one of two types, recorded **both** in the header and the filename:
+
+- **Header field:** `> **Type:** Feature` or `> **Type:** Bug` (authoritative,
+  greppable: `grep -rl 'Type:.*Bug' specs/`).
+- **Filename prefix:** `feat-<name>` for features, `bug-<name>` for bugs
+  (visible in listings; glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
+
+Both types share the same lifecycle folders below — type is orthogonal to status.
+
+## Header fields & State log (audit trail)
+
+Every spec header carries:
+
+- `> **Author:**` — who created the spec (set at `/spec` / `/spec-bug`, defaults
+  to `git config user.name`).
+- `> **Developer:**` — who implements it (`—` until `/spec-go` starts work, then
+  set to `git config user.name`; `/spec-bug` sets it immediately).
+
+Every spec also has a **State log** table — the audit trail of folder/status
+transitions. Each lifecycle skill appends exactly one row when it changes state:
+
+```
+## State log
+
+| Date | Status | Folder | By |
+|------|--------|--------|----|
+| 2026-01-01 | Draft | backlog | Jane Dev |
+| 2026-01-02 | In Progress | in-progress | Jane Dev |
+```
+
+Keep the **State log** (state transitions) separate from the **Changelog**
+(decisions and course-corrections) — state moves go in the table, not the
+changelog.
+
+When asked for a plan, implementation strategy, or feature breakdown:
+
+1. Create or update a spec under `specs/` — never plan only in chat.
+2. Reach a clear shared understanding of the requirement AND the proposed
+   solution before writing (the `/spec` skill grills for this).
+3. Use markdown checkboxes `- [ ]` for tasks, `- [x]` when done.
+4. Organise work into phased sections with short goal descriptions.
+5. Tasks must be granular enough to complete in one coding session.
+6. Every phase ends with creating and running tests — a phase is not done until
+   its tests are green (run the project's typecheck + test commands above).
+7. Keep specs **as concise as possible**.
+8. Record decisions and course-corrections in the spec's **Changelog** section.
+
+## Lifecycle folders
+
+```
+specs/backlog/       Draft + Ready specs (/spec, /spec-ready)
+specs/in-progress/   under active implementation (/spec-go, /spec-bug)
+specs/complete/      finished (/spec-complete)
+specs/cancelled/     abandoned, with a reason on the header (/spec-cancel)
+specs/.core/         project rules — ALWAYS APPLY, never moved
+```
+
+Every spec is a **folder** `specs/<bucket>/<name>/` — never a bare file, even for
+simple changes. Inside it:
+
+- `00-overview.md` is the entry point / dashboard: header, Problem, Decisions,
+  Solution overview, the **phase index** (a table linking to each phase file with
+  its status), Open questions, State log, Changelog. **No per-phase task lists
+  live here.**
+- **One file per phase** — `01-<phase-slug>.md`, `02-<phase-slug>.md`, … in
+  execution order. Each holds that phase's goal, its task checkboxes (tests
+  included), and any phase-specific notes. Even a single-phase spec gets `01-….md`
+  — so each phase is easy to open and work on its own.
+
+Keep the index and the phase files in sync (`⬜`/`🔄`/`✅`). Legacy specs may be a
+bare `<name>.md`, or a `00-overview.md` with inline phases — the skills read
+those, but new specs always use the folder + phase-file form.
+
+## Folder indexes (`00-index.md`)
+
+Two folders keep a skill-maintained `00-index.md` file (never hand-edit):
+
+- `specs/backlog/00-index.md` — **live view** of the backlog (`Added | Spec | Type |
+  Status`, newest first). `/spec` prepends a row; `/spec-ready` updates its
+  status; `/spec-go` and `/spec-cancel` remove the row when the spec leaves.
+- `specs/complete/00-index.md` — **append-only completion log** (`Completed | Spec |
+  Type`, newest first). `/spec-complete` prepends a row — use it to find the
+  latest completed specs.
+
+`/spec-init` ensures both exist. No index for `in-progress` or `cancelled`.
+
+## Rules
+
+- If a spec already exists, update it — don't rewrite from scratch.
+- Preserve completed `[x]` tasks.
+- Add new tasks to the appropriate phase.
+- Never delete historical notes.
+- The spec file is the single source of truth for implementation progress.
+- Move specs between buckets with `git mv` to preserve history.