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