@cleepi/sdd 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog — @cleepi/sdd
+
+All notable changes to this package are documented here.
+
+Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/).
+Versioning: [SemVer](https://semver.org/spec/v2.0.0.html). Pre-`1.0.0`, minor
+bumps may include breaking changes.
+
+## [Unreleased]
+
+## [0.2.0] — 2026-05-27
+
+**BREAKING.** Substantial redesign of the SDD workflow per
+[cleepi spec 0005](../../docs/specs/0005-sdd-redesign.md). New
+artifact ontology, new folder layout, new slash commands. Migration
+steps below.
+
+### Added
+
+- **Journal** as a new artifact type. Per-ticket
+  (`docs/<ticket-id>-slug/journal.md`), append-only log of in-flight
+  thinking — dead ends, blockers, surprises. Stack-pointer-plus-log
+  shape: `## Current state` overwritten each session, `## Log`
+  append-only.
+- **Constitution** as a new optional artifact type. `CONSTITUTION.md`
+  at repo or package root, for projects with real invariants worth
+  codifying. Invariants only — code rules live in `AGENTS.md`,
+  process rules live in the sdd skill, one-off design choices live
+  in spec Decision sections.
+- `/journal <text>` slash command. Appends entry to current
+  ticket's journal; overwrites Current state.
+- `templates/journal.md` — stack-pointer-plus-log skeleton with
+  inline discipline guidance.
+- `templates/constitution.md` — invariants-only skeleton with
+  anti-examples (what does NOT belong here).
+- **Voice and length discipline** in the skill: principles, six
+  anti-patterns, the delete test, length cues per artifact. Long
+  artifacts when short would do are now a defect, not a preference.
+- **Discriminator test** in the skill: "what happens if violated?"
+  routes content to the right artifact (CONSTITUTION / AGENTS.md /
+  spec Decision section / sdd skill).
+- **Ticket-keyed folder layout** (`docs/AC-NNN-slug/`,
+  `docs/LIN-NNN-slug/`, `docs/DRAFT-NNN-slug/`, etc.). Folder name
+  is the cross-link to the tracker; no `jira:` frontmatter to
+  forget. Generic format — tracker prefix is unvalidated.
+- Spec frontmatter gains optional `ticket:` and `ticket-url:`
+  fields.
+- Required `## Decision` section in specs (Alternatives considered
+  / Rationale / Consequences). Required before flipping to
+  `accepted`.
+
+### Changed
+
+- **Spec body structure.** From 8 fixed sections to 3 required
+  (What / Why / Decision) + 5 opt-in (Concrete surface / Phased
+  rollout / Open questions / Non-goals / Risks). Optional sections
+  appear only when they add information — the delete test enforces
+  this.
+- **Spec section names.** `Problem` → `What` (works for features,
+  not just bug-fix framing). `Why now` collapses into `Why`.
+- **`/spec` prompt** now asks for a ticket ID interactively;
+  defaults to `DRAFT-NNN` if no tracker exists.
+- **`/changelog` prompt** updated: spec link format is now
+  `[spec AC-NNN](docs/AC-NNN-slug/spec.md)`. No more ADR-link
+  suggestion.
+- **`packages/sdd/SPEC.md`** rewritten to the purpose-and-scope
+  shape the new skill describes (was structured as a feature spec).
+- **`packages/sdd/README.md`** rewritten for v0.2.0 conventions.
+
+### Removed
+
+- **ADR as a separate artifact type.** Decision rationale moves to
+  the required spec `## Decision` section. Durable rules move to
+  the optional `CONSTITUTION.md`.
+- `/adr` slash command.
+- `templates/adr.md`.
+- `prompts/adr.md`.
+
+### Migration from v0.1.x
+
+Breaking change. Full guide in [README “Migration from v0.1.x”](./README.md#migration-from-v01x). Summary:
+
+1. Move existing ADR content into the relevant spec's
+   `## Decision` section. Mark old ADRs `superseded by spec <id>`
+   (preserve bodies).
+2. Old `docs/specs/NNNN-*.md` and `docs/adr/NNNN-*.md` files don't
+   have to move. New work uses ticket-keyed folders
+   (`docs/<ticket-id>-slug/`).
+3. Start writing journals for active work. Skip retroactive
+   journals for already-shipped specs.
+4. Add `CONSTITUTION.md` *only if* your project has real invariants.
+   Most don't need one.
+
+No automated migration tooling — intentional, unhurried transition.
+
+## [0.1.0] — 2026-05-24
+
+### Added
+- Initial package scaffold.
+- `skills/sdd/SKILL.md` teaching the SDD workflow (spec, ADR, changelog
+  conventions; scope resolution; numbering; status transitions; bootstrap
+  exception).
+- Slash command prompts: `/spec`, `/adr`, `/changelog`.
+- File templates under `templates/`: `spec.md`, `adr.md`,
+  `changelog-section.md`.
+- README documenting conventions for human readers.
+- [SPEC.md](./SPEC.md) — package purpose, scope, non-goals.
+- [ADR 0001](./docs/adr/0001-template-format-madr-lite.md) — chose MADR-lite
+  with YAML frontmatter for spec and ADR templates.
+
+[Unreleased]: https://github.com/cleevio/cleepi/compare/sdd-v0.2.0...HEAD
+[0.2.0]: https://github.com/cleevio/cleepi/releases/tag/sdd-v0.2.0
+[0.1.0]: https://github.com/cleevio/cleepi/releases/tag/sdd-v0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# @cleepi/sdd
+
+Spec-Driven Development as a pi package. Install in any repo where
+you want Spec + Journal + Changelog (and optional Constitution)
+discipline. Your pi sessions will know the workflow.
+
+## What's in the box
+
+- **Skill** (`skills/sdd/SKILL.md`) — the canonical SDD workflow.
+  Loaded automatically when you ask about specs / journals /
+  changelogs / constitution, or explicitly with `/skill:sdd`.
+- **Prompts** — slash commands:
+  - `/spec <title>` — scaffold a new spec in a ticket-keyed folder.
+  - `/journal <text>` — append an entry to the current ticket's
+    journal; update Current state.
+  - `/changelog <type> <text>` — add an entry to the `[Unreleased]`
+    section of the current scope's `CHANGELOG.md`.
+- **Templates** (`templates/`) — markdown skeletons the prompts fill in.
+
+"Current scope" = the nearest package (`packages/<name>/`) you're
+working in, or the repo root.
+
+## The 30-second version
+
+Three artifacts + one optional declarative file. Each answers one
+question:
+
+| Artifact | Question | Lifecycle |
+|---|---|---|
+| **Spec** | What are we building, and why this approach? | `draft` → `accepted` → `shipped` / `superseded` |
+| **Journal** | What's been tried? Where are we now? | Append-only; per-ticket |
+| **Changelog** | What shipped in version N? | Append-only by SemVer / date |
+| **Constitution** *(optional)* | What invariants must always be true? | Living document |
+
+ADRs are not a separate artifact type in v0.2.0. Their "X over Y"
+function lives in a required `## Decision` section inside specs.
+Durable invariants live in the optional `CONSTITUTION.md`.
+
+For the full discipline (discriminator test, voice/length rules,
+invariant-vs-rule distinction, folder layout, status lifecycles),
+see [`skills/sdd/SKILL.md`](skills/sdd/SKILL.md). It's the source
+of truth.
+
+## Folder layout (in your repo)
+
+```
+<repo>/
+  CHANGELOG.md                   ← repo-level releases
+  CONSTITUTION.md                ← optional, when project has invariants
+  docs/
+    AC-101-pricing-page/         ← ticket-keyed; AC-NNN, LIN-NNN, gh-NN, DRAFT-NNN
+      spec.md
+      journal.md
+  packages/<name>/
+    SPEC.md                      ← purpose-and-scope (singular)
+    CHANGELOG.md                 ← per-package SemVer
+    docs/AC-NNN-slug/
+      spec.md
+      journal.md
+```
+
+The folder name is the cross-link to the tracker — no `jira:` or
+`ticket-id:` frontmatter to forget.
+
+## Install
+
+Global (every pi session anywhere gets the workflow):
+
+```bash
+pi install git:github.com/cleevio/cleepi/packages/sdd
+```
+
+Project-local (recommended for repos that adopt SDD as their
+process):
+
+```bash
+cd <repo>
+pi install -l git:github.com/cleevio/cleepi/packages/sdd
+```
+
+## Migration from v0.1.x
+
+v0.2.0 is a breaking change. If you have an existing project on
+v0.1.x:
+
+- **`/adr` is gone.** Move ADR content into the relevant spec's
+  `## Decision` section. Mark old ADRs `status: superseded by
+  spec <id>` (preserve bodies as historical record).
+- **Existing `docs/specs/NNNN-*.md` and `docs/adr/NNNN-*.md` files
+  don't have to move.** They stay in place as archive. New specs
+  go in ticket-keyed folders (`docs/<ticket-id>-slug/spec.md`).
+- **Start writing journals** for active work
+  (`docs/<ticket-id>-slug/journal.md`). Skip retroactive journals
+  for already-shipped specs.
+- **Add `CONSTITUTION.md`** at repo root *only if* your project
+  has real invariants worth codifying (e.g., "we use Postgres",
+  "all auth is server-side"). Most projects don't need one.
+
+No automated migration tooling. The transition is intentional and
+unhurried.
+
+## Related
+
+- [SPEC.md](./SPEC.md) — what this package is and isn't.
+- [CHANGELOG.md](./CHANGELOG.md) — release history.
+- Root cleepi [spec 0005](../../docs/specs/0005-sdd-redesign.md) —
+  the v0.2.0 redesign rationale.

package/SPEC.md

@@ -0,0 +1,104 @@
+---
+title: "@cleepi/sdd"
+status: shipped
+created: 2026-05-24
+updated: 2026-05-27
+owner: Honza
+related:
+  - ../../docs/specs/0001-development-process.md (partially superseded)
+  - ../../docs/specs/0005-sdd-redesign.md (drives v0.2.0)
+  - ../../docs/adr/0004-extract-sdd-as-package.md
+---
+
+# `@cleepi/sdd`
+
+## What this package is
+
+A pi package that ships the Cleepi Spec-Driven Development workflow
+as durable instructions. Install it in any repo and pi sessions there
+know how to write specs, journals, changelogs, and (optionally) a
+constitution.
+
+Three things ship:
+
+- **Skill** (`skills/sdd/SKILL.md`) — canonical SDD workflow doc.
+  Loaded on demand or explicitly with `/skill:sdd`.
+- **Prompts** — `/spec`, `/journal`, `/changelog`.
+- **Templates** (`templates/`) — file skeletons the prompts fill in.
+
+The workflow itself is documented in the skill, not here. Read
+[`skills/sdd/SKILL.md`](skills/sdd/SKILL.md) for the canonical
+version, including the discriminator test, voice/length discipline,
+and folder layout.
+
+## What this package is not
+
+- **Not a lint or CI enforcer.** The skill instructs; it doesn't
+  police. Enforcement is deferred until friction shows up.
+- **Not an ADR framework.** ADRs as a separate artifact type were
+  dropped in v0.2.0. Decision rationale lives in the required
+  `## Decision` section inside specs. Durable invariants live in
+  the optional `CONSTITUTION.md`.
+- **Not a project management tool.** No status boards, ownership
+  tracking, or dashboards.
+- **Not a generic spec framework for non-pi contexts.** The skill
+  assumes pi conventions and a Cleepi-shaped workflow.
+- **Not opinionated about ticket trackers.** `AC-NNN`, `LIN-NNN`,
+  `gh-NN`, `DRAFT-NNN` all work as folder prefixes; the skill
+  validates none of them.
+- **Not a constitution requirement.** `CONSTITUTION.md` is an
+  *optional* artifact consumer projects opt into when they have
+  real invariants worth codifying.
+
+## Design at a glance
+
+```
+packages/sdd/
+  package.json
+  README.md
+  SPEC.md                        ← this file
+  CHANGELOG.md
+  skills/sdd/SKILL.md            ← the canonical workflow
+  prompts/spec.md                ← /spec
+  prompts/journal.md             ← /journal
+  prompts/changelog.md           ← /changelog
+  templates/spec.md
+  templates/journal.md
+  templates/constitution.md
+  templates/changelog-section.md
+```
+
+In a consumer repo using the workflow, layout looks like:
+
+```
+<consumer-repo>/
+  CHANGELOG.md                   ← repo-level releases
+  CONSTITUTION.md                ← optional, when project has invariants
+  AGENTS.md                      ← code rules + interaction style (project-shipped)
+  docs/
+    AC-101-pricing-page/
+      spec.md
+      journal.md
+  packages/<name>/
+    SPEC.md                      ← purpose-and-scope (singular, unnumbered)
+    CHANGELOG.md
+    docs/AC-201-billing-api/
+      spec.md
+      journal.md
+```
+
+## Versioning
+
+Per-package SemVer. Pre-`1.0.0`, minor bumps may include breaking
+changes (per SemVer §4).
+
+**v0.2.0 is a breaking change from v0.1.x.** Artifact ontology,
+folder layout, and slash commands all changed. See
+[CHANGELOG.md](./CHANGELOG.md) for the migration path.
+
+## Related
+
+- [skills/sdd/SKILL.md](./skills/sdd/SKILL.md) — canonical workflow.
+- [CHANGELOG.md](./CHANGELOG.md) — release history with migration.
+- Root cleepi [spec 0005](../../docs/specs/0005-sdd-redesign.md) —
+  the v0.2.0 redesign that drove this package's rewrite.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@cleepi/sdd",
+  "version": "0.2.0",
+  "description": "Spec-Driven Development workflow for pi: skill, prompts, and templates for specs, journals, changelogs, and optional constitution. v0.2.0+ replaces ADRs with spec Decision sections.",
+  "keywords": [
+    "pi-package",
+    "cleepi",
+    "sdd",
+    "spec",
+    "journal",
+    "changelog",
+    "constitution",
+    "spec-driven"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/honzanemecek/cleepi.git",
+    "directory": "packages/sdd"
+  },
+  "bugs": "https://github.com/honzanemecek/cleepi/issues",
+  "homepage": "https://github.com/honzanemecek/cleepi/tree/main/packages/sdd#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ]
+  },
+  "files": [
+    "skills",
+    "prompts",
+    "templates",
+    "SPEC.md",
+    "CHANGELOG.md",
+    "README.md"
+  ]
+}

package/prompts/changelog.md

@@ -0,0 +1,39 @@
+---
+description: Add an entry to the [Unreleased] section of the current scope's CHANGELOG
+argument-hint: "<added|changed|deprecated|removed|fixed|security> <text>"
+---
+
+The user wants to add a changelog entry. Arguments: **$ARGUMENTS**
+
+First token is the section name (one of `added`, `changed`, `deprecated`,
+`removed`, `fixed`, `security`). Everything after is the entry text.
+
+Follow the cleepi SDD workflow (load `/skill:sdd` if you haven't):
+
+1. **Resolve scope.** Determine which `CHANGELOG.md` to edit:
+   - If the change only affects one package, target =
+     `packages/<name>/CHANGELOG.md`.
+   - If it's a repo-level event (tooling, conventions, new package), target =
+     `/CHANGELOG.md` at the repo root.
+   - If ambiguous, ask the user.
+
+2. **Validate the section name.** Must be one of: `Added`, `Changed`,
+   `Deprecated`, `Removed`, `Fixed`, `Security`. Capitalize properly.
+
+3. **Read the target CHANGELOG.** Find the `## [Unreleased]` section. If it
+   doesn't exist, add it at the top (just under the file header), then
+   proceed. If the file doesn't exist at all, stop and ask the user — a
+   missing CHANGELOG suggests a missing package or wrong scope.
+
+4. **Find or create the subsection** (`### Added`, etc.) within `[Unreleased]`.
+   Preserve the conventional ordering (Added, Changed, Deprecated, Removed,
+   Fixed, Security) — insert new subsections in that order.
+
+5. **Append the entry** as a bullet point. If the entry text references a
+   spec the user mentioned, append a link in the form
+   `(see [spec AC-NNN](docs/AC-NNN-slug/spec.md))`. ADRs are no longer a
+   separate artifact — link to the spec whose `## Decision` section
+   records the rationale instead.
+
+6. **Report.** Tell the user which file you edited and show the new bullet.
+   Do not modify any released version sections — those are frozen.

package/prompts/journal.md

@@ -0,0 +1,50 @@
+---
+description: Append an entry to the current ticket's journal; overwrite Current state
+argument-hint: "<entry text>"
+---
+
+The user wants to append a journal entry. Text: **$ARGUMENTS**
+
+Follow the @cleepi/sdd workflow (load `/skill:sdd` if you haven't,
+specifically the "Journal discipline" and "Voice and length" sections).
+
+1. **Resolve the current ticket folder.**
+   - If `cwd` is inside `docs/<ticket-id>-slug/` or
+     `packages/<n>/docs/<ticket-id>-slug/`, use that folder.
+   - Otherwise ask: *"Which ticket is this entry for? Provide the
+     folder path or ticket ID."*
+
+2. **Find or create `<folder>/journal.md`.**
+   - If it exists, read it.
+   - If not, scaffold from the @cleepi/sdd `templates/journal.md`
+     template (substitute the ticket ID and slug into the header).
+
+3. **Append the log entry.**
+   - Find the `## Log` section.
+   - Insert a new dated entry at the **top** of the log
+     (newest first):
+     ```
+     ### YYYY-MM-DD — <author or session label>
+     - <entry text, broken into 1–5 bullets if multi-line>
+     ```
+   - Date = today.
+   - Author = the session user; ask if unclear.
+
+4. **Update Current state.**
+   - Ask the user: *"What's the current state in one line, after
+     this entry?"*
+   - Replace the bullets under `## Current state` with the
+     response. Don't append — overwrite.
+
+5. **Write the file. Report what changed** (one line: path +
+   what was appended + what Current state now says).
+
+6. **Discipline check.** If the entry text has no dead end,
+   blocker, surprise, or reasoning behind it, gently flag:
+   *"This looks like a changelog entry rather than journal
+   material — should I run `/changelog` instead?"* Don't refuse;
+   just ask.
+
+Be concise (see skill "Voice and length"). The journal entry
+itself goes in as the user wrote it — apply the delete test
+only to your own surrounding output, not the user's content.

package/prompts/spec.md

@@ -0,0 +1,58 @@
+---
+description: Scaffold a new SDD spec in a ticket-keyed folder under the current scope
+argument-hint: "<title>"
+---
+
+The user wants to create a new spec titled: **$ARGUMENTS**
+
+Follow the @cleepi/sdd workflow (load `/skill:sdd` if you haven't).
+
+1. **Resolve scope.**
+   - Inside `packages/<n>/` or the spec is clearly about one package
+     → scope = package. Target = `packages/<n>/docs/`.
+   - Otherwise → scope = repo. Target = `docs/`.
+   - Ambiguous → ask.
+
+2. **Resolve the ticket ID.** Ask: *"Ticket ID for this spec (e.g.
+   `AC-101`)? Leave empty if there's no tracker ticket yet."*
+   - User provides one → use it as the folder prefix and the
+     frontmatter `id` and `ticket` fields.
+   - User leaves empty → use `DRAFT-NNN` where `NNN` is the next
+     monotonic number among existing `DRAFT-*` folders in the
+     target. No `ticket:` field in frontmatter.
+
+3. **Slugify the title.** Lowercase, kebab-case, drop articles.
+   Folder name = `<ticket-id>-<slug>/`.
+
+4. **Create the folder** if it doesn't exist. **Refuse** if it
+   exists AND already contains a `spec.md`. (Don't overwrite.)
+
+5. **Load the spec template** from the installed @cleepi/sdd
+   package's `templates/spec.md`. In this repo:
+   `packages/sdd/templates/spec.md`.
+
+6. **Fill frontmatter:**
+   - `id`: ticket ID, or `DRAFT-NNN`.
+   - `title`: user's title (preserve human-readable casing).
+   - `status`: `draft`.
+   - `created`: today's date in `YYYY-MM-DD`.
+   - `owner`: ask if you don't know.
+   - `ticket`: ticket ID (omit field entirely if no tracker).
+   - `ticket-url`: ask if relevant; omit otherwise.
+   - `related`: leave empty.
+
+7. **Body.** Keep the three required sections (`## What`,
+   `## Why`, `## Decision`) from the template. Replace placeholder
+   text with a short first-draft sketch only if you already know
+   enough — never fabricate. Leave the "optional sections" comment
+   block at the bottom untouched; the author opts in as needed.
+
+8. **Write `<folder>/spec.md`.** Report the path.
+
+9. **Next step.** Tell the user: *"Spec drafted at `<path>`. Status
+   is `draft`. Iterate on What / Why / Decision, then flip to
+   `accepted` before we touch code (strict SDD). Use `/journal
+   <text>` to log friction as you work."*
+
+Be concise throughout (see skill "Voice and length"). No throat-
+clearing; no restating what the user just typed.

package/skills/sdd/SKILL.md

@@ -0,0 +1,432 @@
+---
+name: sdd
+description: Spec-Driven Development workflow for cleepi-style repos. Use when the user asks to write a spec, journal entry, changelog entry, or constitution entry; when starting non-trivial work that should be designed before coding; or when about to release a package version. Covers the three-artifact ontology (spec/journal/changelog) + optional constitution, the discriminator test for where content belongs, ticket-keyed folder layout, scope resolution (package vs repo), status lifecycles, and Keep-a-Changelog 1.1.0 conventions.
+---
+
+# Spec-Driven Development (SDD)
+
+The cleepi workflow for designing before coding, capturing in-flight
+thinking so it doesn't get lost, and remembering what shipped.
+
+## Core idea
+
+Three artifacts + one optional declarative file. Each has a single
+responsibility — never conflate them.
+
+| Artifact | Question it answers | When written | Lifecycle |
+| --- | --- | --- | --- |
+| **Spec** | *What* are we going to build, and *why this approach* over alternatives? | Before coding | `draft` → `accepted` → `shipped` (frozen) or `superseded` |
+| **Journal** | *What's been tried, where are we now?* | During work, append-only | No formal status; per-ticket |
+| **Changelog** | *What* shipped in version N? | At release | Append-only by SemVer (package) or date (repo) |
+| **Constitution** *(optional)* | *What invariants* must always be true for this project? | When the project has real invariants worth codifying | Living document; entries cite originating spec when one exists |
+
+ADRs are not used. Their "X over Y" function lives in a required
+`## Decision` section inside specs. Their durable-rule function (for
+true project invariants) lives in `CONSTITUTION.md` when a project
+has one.
+
+## Voice and length
+
+SDD artifacts are written by tired humans for tired humans. Straight
+to the point. No padding. Nobody likes reading a long spec that
+says nothing.
+
+The default failure mode — especially for AI agents — is wordy
+prose that says nothing concrete. This rule is not advisory: a long
+artifact when a short one would do is a defect. Reviewers (human or
+AI) reject it the same way they'd reject a missing Decision section.
+
+### Principles
+
+- **Bullets over paragraphs.** Paragraphs connect ideas. Bullets
+  list things. SDD artifacts are mostly listing.
+- **Specifics over generalities.** "Refactor pricing logic" is
+  generality. "Move `pricingEngine.compute()` from `billing/` to
+  `pricing/` and update three call sites" is specific.
+- **Show the thing, don't describe it.** A file path, a code
+  snippet, a citation beats ten lines of prose.
+- **No throat-clearing.** No "This document describes…", no
+  "In this section we will…", no "In conclusion…".
+- **No filler adjectives.** Cut "comprehensive", "robust",
+  "elegant", "seamlessly", "industry-leading". They mean nothing.
+- **No hedging.** "Could potentially" → "may". "It might be the
+  case that" → cut.
+- **No restating the title or task.** The reader just read it.
+
+### The delete test
+
+Read each sentence. *Can you delete it without losing information?*
+If yes, delete it. Apply recursively until no sentence survives.
+Reading time of an SDD artifact should equal the reading time of
+its information content. Nothing else.
+
+### Length cues per artifact
+
+- **Spec.** As long as the work demands; no longer. 100–300 lines
+  is typical for a non-trivial feature spec. Over 500 lines is
+  almost always a smell — either the scope is too big (split it)
+  or the prose is padded (cut it).
+- **Journal entry.** 3–5 bullets per entry. One line if nothing
+  surprising happened. The whole journal is 3–10 entries for a
+  ticket.
+- **Changelog entry.** One bullet. Cites the spec with a link.
+- **Constitution entry.** One line. Cites the spec with a link.
+  If you can't state the invariant in one line, it's probably not
+  an invariant — it's a rule (see AGENTS.md).
+
+If you find yourself writing "this section is more detailed than
+usual because of X," delete the section and write a shorter version.
+
+## The discriminator test — where does this belong?
+
+When unsure where to put something, ask: *what happens if it's
+violated?*
+
+- The codebase becomes a *fundamentally different project* (we suddenly
+  aren't a Bun project anymore) → **CONSTITUTION**.
+- A PR gets review feedback ("use repository pattern here") →
+  **AGENTS.md** (or whatever the project's code-conventions file is).
+- It was a choice for one specific feature ("we picked Stripe SDK
+  directly for this billing work") → the spec's **`## Decision`
+  section**.
+- It's about how SDD itself works ("specs go draft → accepted →
+  shipped") → this **sdd skill**.
+
+### Worked examples
+
+**Constitution** — tribal knowledge, foundational, "crossing this
+changes what the project is":
+
+- We use Bun, not Node or Deno.
+- We use PostgreSQL, not MySQL.
+- Deployed only to AWS eu-central-1.
+- All authentication through Auth0.
+- Production data never leaves AWS.
+
+**AGENTS.md** — current code rules, evolves with the codebase:
+
+- Don't do unnecessary `as unknown as` casts.
+- Prefer `unknown` over `any`.
+- Database access through the repository pattern.
+- Test files live next to source: `foo.ts` + `foo.test.ts`.
+- Use Zod at trust boundaries.
+- Be a partner not order-taker (AI interaction style).
+
+**Spec `## Decision` section** — one-off, per-feature:
+
+- "Used Stripe SDK directly rather than abstracting; revisit if we
+  add a second payment provider."
+- "Picked nock over msw for mocking; msw doesn't intercept the SDK's
+  internal HTTPS validation."
+
+**Sdd skill** — process, not content:
+
+- Specs go `draft` → `accepted` → `shipped`.
+- Numbering is per-directory monotonic for repo-level specs; ticket-ID
+  for ticket-keyed folders.
+- Ticket-keyed folder layout is `docs/<ticket-or-slug>/`.
+
+## Folder layout
+
+Ticket-keyed, flat. The folder name is the link to the tracker
+(Jira, Linear, GitHub Issues, or a project-local convention).
+
+```
+my-repo/
+├── README.md
+├── CHANGELOG.md                  ← repo-level events
+├── CONSTITUTION.md               ← OPTIONAL; only when the project
+│                                   has real invariants to codify
+├── AGENTS.md                     ← code rules + interaction style
+│                                   (project-specific; not shipped here)
+└── docs/
+    ├── AC-100-billing-revamp/
+    │   ├── spec.md
+    │   └── journal.md
+    ├── AC-101-pricing-page/
+    │   ├── spec.md
+    │   └── journal.md
+    └── AC-999-decide-monorepo/   ← meta-tickets for cross-cutting
+        ├── spec.md                 decisions are just ticket folders too
+        └── journal.md
+```
+
+In a monorepo, each package can have the same structure inside
+`packages/<name>/docs/`, with the package's own `CHANGELOG.md`,
+`SPEC.md` (singular, purpose-and-scope), and optional
+`CONSTITUTION.md`.
+
+**Ticket ID format is not validated.** `AC-101-slug`, `LIN-42-slug`,
+`gh-7-slug`, `CLEEPI-001-slug` all work. For pre-tracker work, use
+`DRAFT-NNN-slug` and rename when a ticket is cut.
+
+## Scope resolution
+
+When creating a spec, journal, or changelog entry, determine **scope**
+first:
+
+- **Package scope** — when working inside `packages/<n>/`, write to:
+  - `packages/<n>/docs/<ticket-or-slug>/spec.md` (and `journal.md`)
+  - `packages/<n>/CHANGELOG.md`
+  - `packages/<n>/CONSTITUTION.md` (if applicable)
+- **Repo scope** — when the change is cross-cutting (affects multiple
+  packages, repo tooling, conventions, adding/removing a package),
+  write to:
+  - `docs/<ticket-or-slug>/spec.md` (and `journal.md`)
+  - `/CHANGELOG.md`
+  - `/CONSTITUTION.md` (if applicable)
+
+When in doubt: if it only affects one package, it's package scope.
+
+The package's own `SPEC.md` (singular, capitalized, at
+`packages/<n>/SPEC.md`) is a special file — it describes the
+package's *purpose and scope*, not a feature. It is not numbered,
+has no formal lifecycle, and isn't replaced by ticket folders.
+
+## Status lifecycle (specs)
+
+- `draft` — being written, open for changes. No `## Decision` section
+  required yet.
+- `accepted` — design agreed; implementation can start (strict mode).
+  `## Decision` section **must** be populated before flipping to this
+  status.
+- `shipped` — implementation complete and released; spec is now
+  **frozen**. Future changes go in a new spec marked
+  `supersedes: docs/<old-folder>/spec.md`.
+- `superseded` — replaced by a later spec. Set
+  `superseded-by: docs/<new-folder>/spec.md` in frontmatter.
+
+## Spec format
+
+Every spec has frontmatter plus a body. Required sections:
+
+```yaml
+---
+id: AC-101                     # the ticket ID, or a project-local
+                               # identifier for non-tracker specs
+title: <human-readable title>
+status: draft                  # → accepted → shipped/superseded
+created: YYYY-MM-DD
+accepted: YYYY-MM-DD           # added when flipped to accepted
+shipped: YYYY-MM-DD            # added when flipped to shipped
+owner: <human>
+ticket: AC-101                 # tracker ticket ID (optional for
+                               # repo-internal specs)
+ticket-url: https://...        # optional, full URL
+related:
+  - docs/<other-folder>/spec.md
+---
+```
+
+Body sections — minimal core, everything else opt-in.
+
+**Required:**
+
+- **`## What`** — what's being built. Concrete, specific. Works for
+  features, refactors, and bug fixes equally. Show the thing.
+- **`## Why`** — the reason. Both the motivation and the timing,
+  in one section.
+- **`## Decision`** — required before `status: accepted` (stub OK
+  while draft). Format:
+  - **Alternatives considered** (honest summary + why rejected, for each)
+  - **Rationale** (why the picked option wins, anchored on What and Why)
+  - **Consequences** (what becomes easier, harder, locked-in)
+
+**Optional — include only when they add information:**
+
+- **`## Concrete surface`** — the files this delivers/changes.
+  Often filled during iteration by analysis (scout phase), not at
+  initial draft. Skip when obvious.
+- **`## Phased rollout`** — for multi-phase work. Each phase has
+  deliverables and acceptance criteria. Skip for single-pass
+  changes.
+- **`## Open questions`** — unresolved choices, with default-
+  proposed answers where possible. Mark which phase resolves each.
+- **`## Non-goals`** — only when scope is genuinely ambiguous.
+  Forced "we won't boil the ocean" filler fails the delete test.
+- **`## Risks`** — real risks with mitigations. Synthetic "what if
+  it breaks" risks fail the delete test.
+
+Apply the delete test to every section. A spec with three sections
+(What / Why / Decision) is better than a spec with eight where five
+are filler.
+
+A spec without a Decision section is fine as `draft`; it cannot be
+promoted to `accepted` until the section is populated.
+
+## Journal discipline
+
+Each ticket folder may contain a `journal.md` capturing in-flight
+thinking. Two sections:
+
+```markdown
+# Journal — <ticket-id> <slug>
+
+## Current state
+*(overwritten each session — kept terse)*
+
+- <where things stand right now>
+- <what's blocked, what's next>
+
+## Log
+
+### YYYY-MM-DD — <author or session id>
+- <what was tried, what worked, what didn't, what's blocked>
+
+### YYYY-MM-DD — earlier session
+- <older entries below>
+```
+
+**Hard rules:**
+
+- One entry per work session, not per action.
+- Capture **friction** (dead ends, blockers, surprises, decisions
+  that changed). If everything went smoothly, one line is enough.
+- No code in the journal. Reference commits/PRs.
+- Bullets over paragraphs.
+- 3–10 log entries per ticket is normal; 20+ is a smell (split the
+  ticket, or stop logging routine progress).
+- Append-only on the log; "Current state" is overwritten.
+- On ticket ship: final entry citing the changelog version, then
+  the log stops appending. Not deleted.
+
+**Journal vs Changelog (one-line litmus):** *if an entry has no dead
+end, blocker, or reasoning, it's not journal material — it's a
+changelog entry waiting to happen.*
+
+## Constitution discipline (when used)
+
+`CONSTITUTION.md` is **optional**. Use it when the project has real
+invariants worth making explicit — things everyone on the team
+already follows but never wrote down, and that crossing would
+fundamentally change what the project is.
+
+**Don't use it** for:
+
+- Code style or lint rules → AGENTS.md
+- "Prefer X over Y" conventions → AGENTS.md
+- Per-feature design choices → spec Decision sections
+- Process rules → this sdd skill
+
+**Maintenance:** when a spec is promoted to `accepted`, the author
+considers whether the spec's Decision section establishes a new
+invariant (commits the project to something indefinitely, not just
+a one-off). If yes, a corresponding CONSTITUTION entry is added in
+the same change. Most specs do NOT establish invariants — they
+establish features.
+
+**To change an invariant:** write a new spec that supersedes the
+originating one. Don't edit CONSTITUTION.md directly.
+
+## Strict-mode workflow
+
+For non-trivial work:
+
+1. Cut a ticket (Jira / Linear / GitHub Issue / local `DRAFT-NNN`).
+2. Create the ticket folder: `docs/<ticket-id>-<slug>/`.
+3. Draft `spec.md`. Status `draft`. Use the `/spec` slash command.
+4. Iterate on the spec; populate the Decision section. Flip status
+   to `accepted` when ready.
+5. Implement. Append to `journal.md` as you go — friction, blockers,
+   surprises only (`/journal` slash command).
+6. When merged/released: flip spec status to `shipped`. Add a
+   `CHANGELOG.md` entry for the relevant scope (`/changelog`).
+7. If the spec's Decision section established a new invariant,
+   propagate it to CONSTITUTION.md in the same change.
+
+### What's "trivial" (skip the dance)
+
+No spec required for: typo fixes, formatting, documentation polish,
+mechanical renames, dependency bumps that don't change behavior,
+obvious bug fixes. Trivial changes still go in the relevant changelog
+if user-visible.
+
+### Bootstrap exception
+
+The single commit that *introduces* SDD into a repo is allowed without
+a pre-existing accepted spec, because the spec defining the process is
+created in that same commit. One-off. Does not apply to any later
+work.
+
+## Changelog conventions
+
+[Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/). One
+file per package at `packages/<n>/CHANGELOG.md`, plus one at the
+repo root for repo-level events (tooling, new packages,
+conventions).
+
+Section names (use only the ones with content): `Added`, `Changed`,
+`Deprecated`, `Removed`, `Fixed`, `Security`.
+
+Always keep an `## [Unreleased]` section at the top. On release,
+rename it to the new version with today's date, then re-add an empty
+`[Unreleased]`.
+
+```markdown
+## [Unreleased]
+
+## [0.2.0] — 2026-06-01
+
+### Added
+- Thing A (see [spec AC-101](docs/AC-101-thing-a/spec.md)).
+
+### Fixed
+- Thing B.
+```
+
+## SemVer
+
+Each package versions independently. Pre-`1.0.0`, minor bumps may
+include breaking changes (per SemVer §4). At `1.0.0`, commit to
+standard SemVer.
+
+The repo itself isn't versioned — root `CHANGELOG.md` uses
+`[Unreleased]` and dated sections without version numbers.
+
+## Templates
+
+Live in `packages/sdd/templates/`:
+
+- `spec.md` — the four required sections + Decision template
+- `journal.md` — stack-pointer-plus-log skeleton
+- `constitution.md` — invariants-only skeleton with inline
+  guidance on what belongs vs doesn't
+- `changelog-section.md` — Keep-a-Changelog section block
+
+The `/spec`, `/journal`, `/changelog` prompts use these. If invoked
+manually:
+
+```bash
+# Make the ticket folder, copy template:
+mkdir -p docs/AC-101-pricing-page
+cp <sdd-pkg>/templates/spec.md docs/AC-101-pricing-page/spec.md
+# Fill frontmatter and body.
+```
+
+## Quick reference
+
+| You want to... | Use |
+| --- | --- |
+| Start a non-trivial change | `/spec <title>` (asks for ticket ID interactively) |
+| Log a session's friction / progress | `/journal <text>` |
+| Note something shipped | `/changelog <added\|changed\|fixed\|...> <text>` |
+| Add a project invariant | Edit `CONSTITUTION.md` directly (no slash command) |
+| Freeze a shipped spec | Edit frontmatter `status: shipped` |
+| Replace a spec | New spec; old one's status becomes `superseded`, with `superseded-by:` set |
+
+## Migration from sdd v0.1.x
+
+If you're upgrading from sdd v0.1.x:
+
+- `/adr` is gone. Move ADR content into the spec's `## Decision`
+  section. Mark old ADRs as `superseded by spec <id>`.
+- `docs/specs/NNNN-*.md` files don't have to move. New specs go
+  in ticket-keyed folders; old ones stay as historical record
+  (with `status: shipped` or `superseded`).
+- `docs/adr/` becomes a read-only archive directory.
+- Add an optional `CONSTITUTION.md` at the relevant scope if the
+  project has invariants to codify.
+- Start using `journal.md` for active work.
+
+No automated migration tooling. The transition is intentional and
+unhurried.

package/templates/changelog-section.md

@@ -0,0 +1,28 @@
+<!--
+  Use one or more of these subsections under [Unreleased] or a
+  version heading. Only include subsections that have content.
+  Order is conventional (Added → Security), not enforced by
+  Keep-a-Changelog.
+
+  One bullet per entry. Cite the spec with a link.
+
+  See @cleepi/sdd skill "Voice and length" section.
+-->
+
+### Added
+- New feature description. See [spec AC-NNN](docs/AC-NNN-slug/spec.md).
+
+### Changed
+- What changed in existing behavior. See [spec AC-NNN](docs/AC-NNN-slug/spec.md).
+
+### Deprecated
+- Feature scheduled for removal in version X.Y.0.
+
+### Removed
+- Feature removed. Note migration path if any.
+
+### Fixed
+- Bug description. Link to issue/PR if applicable.
+
+### Security
+- Vulnerability fixed. CVE if applicable. Affected versions.

package/templates/constitution.md

@@ -0,0 +1,39 @@
+<!--
+  Invariants only. Things that must always be true for this project.
+  If violated, the project becomes something else.
+
+  Not for:
+    - Code rules ("prefer X over Y")          → put in AGENTS.md
+    - Process rules ("specs go draft→accepted") → @cleepi/sdd skill
+    - One-off design choices                   → spec Decision section
+
+  One line per invariant. Cite the spec that established it when
+  one exists. Most invariants pre-date specs and are codified
+  retroactively — citation optional in that case.
+
+  This file is OPTIONAL. Many projects don't need one. Add it only
+  when the project has real invariants worth making explicit.
+
+  See @cleepi/sdd skill "Constitution discipline" section.
+-->
+
+# Constitution
+
+The invariants for this project — things that must always be true.
+
+To change an invariant, write a new spec that supersedes the
+originating one. Don't edit this file directly to amend an invariant
+— surface the change through SDD.
+
+## Stack
+
+- We use <X>, not <Y>. ([spec](docs/<folder>/spec.md))
+- <invariant>.
+
+## Process
+
+- <invariant>. ([spec](docs/<folder>/spec.md))
+
+## Domain
+
+- <invariant>. ([spec](docs/<folder>/spec.md))

package/templates/journal.md

@@ -0,0 +1,33 @@
+<!--
+  Stack pointer + log. Overwrite "Current state" each session;
+  append to "Log". Capture friction (dead ends, blockers, surprises),
+  not flow. One entry per work session, not per action. 3–5 bullets
+  per entry. Whole journal is 3–10 entries for a ticket.
+
+  If an entry has no dead end, blocker, or reasoning, it's not
+  journal material — it's a changelog entry waiting to happen.
+
+  See @cleepi/sdd skill "Journal discipline" and "Voice and length"
+  sections.
+-->
+
+# Journal — <ticket-id> <slug>
+
+## Current state
+
+*(overwritten each session — kept terse)*
+
+- <where things stand right now>
+- <what's blocked, what's next>
+- <active branch / PR if applicable>
+
+## Log
+
+### YYYY-MM-DD — <author or session id>
+
+- <what was tried, what worked, what didn't, what's blocked>
+- <reference commits/PRs, no inline code>
+
+### YYYY-MM-DD — <earlier session>
+
+- <older entries below; append-only>

package/templates/spec.md

@@ -0,0 +1,75 @@
+---
+id: AC-NNN                  # ticket ID, or DRAFT-NNN for pre-tracker
+title: <Specific title, not "X improvements">
+status: draft               # draft → accepted → shipped/superseded
+created: YYYY-MM-DD
+accepted:                   # filled when flipped to accepted
+shipped:                    # filled when flipped to shipped
+owner: <human>
+ticket: AC-NNN              # tracker ID; optional for repo-internal specs
+ticket-url:                 # optional, full URL
+related: []
+---
+
+<!--
+  Be concise. Apply the delete test before flipping to accepted.
+  See @cleepi/sdd skill "Voice and length" section.
+-->
+
+# Spec AC-NNN: <Title>
+
+## What
+
+What's being built. Concrete, specific. Show the thing, don't
+describe it. Works equally for features, refactors, and bug fixes.
+
+## Why
+
+Why this work. Cite prior specs, constitution entries, or package
+SPEC.md if relevant.
+
+## Decision
+
+<!-- Required before status: accepted. Stub OK while draft. -->
+
+We chose **<X>** over **<Y>**.
+
+### Alternatives considered
+
+- **<X>** (chosen) — what it is, why it wins.
+- **<Y>** — what it is, why rejected.
+
+### Rationale
+
+Why <X> wins, anchored on What and Why.
+
+### Consequences
+
+- What becomes easier or possible.
+- What becomes harder or locked-in.
+- What we accept as the cost.
+
+<!--
+  Optional sections — add only when they add information.
+  Apply the delete test: if a section would be filler, omit it.
+
+  ## Concrete surface
+    The files this delivers or changes. Often filled during
+    iteration by analysis (scout) rather than at initial draft.
+
+  ## Phased rollout
+    For multi-phase work. Each phase: deliverables + acceptance
+    criteria. Skip for single-pass changes.
+
+  ## Open questions
+    Unresolved choices. Include default-proposed answer where
+    possible. Mark which phase resolves each.
+
+  ## Non-goals
+    Only when scope is genuinely ambiguous. "We won't boil the
+    ocean" filler fails the delete test — skip it.
+
+  ## Risks
+    Real risks with mitigations. Synthetic "what if it breaks"
+    risks fail the delete test — skip them.
+-->