@cleepi/sdd

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.

Packages

Package details

skillprompt

Install @cleepi/sdd from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@cleepi/sdd
Package
@cleepi/sdd
Version
0.2.0
Published
Jun 1, 2026
Downloads
not available
Author
honem
License
MIT
Types
skill, prompt
Size
40.1 KB
Dependencies
0 dependencies · 0 peers
Pi manifest JSON
{
  "skills": [
    "./skills"
  ],
  "prompts": [
    "./prompts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@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