@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. 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):

pi install git:github.com/cleevio/cleepi/packages/sdd

Project-local (recommended for repos that adopt SDD as their process):

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 — what this package is and isn't.
• CHANGELOG.md — release history.
• Root cleepi spec 0005 — the v0.2.0 redesign rationale.