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

Four 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.
- **Extensions** (`extensions/`) — TUI tooling that makes the
  workflow drivable from inside pi. Currently: the **spec-review
  cockpit** (see [docs/DRAFT-001-spec-review-tui/spec.md](./docs/DRAFT-001-spec-review-tui/spec.md))
  which surfaces awareness of touched specs, opens a review pane
  for reading and quoting passages back to the agent, and (in
  later phases) adds structured edits for status flips, journal
  appends, and changelog appends. Templates are the shared
  contract: extension actions and slash-command prompts both
  consume `templates/*.md` rather than encoding format inline.

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
  extensions/spec-review/        ← the cockpit (DRAFT-001)
```

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.