# @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.