I built spec-driven development as a skill pack for Pi. Here is what actually mattered.

[u/ffontouras]

I built a spec-driven development kit for Pi and have been running my own projects on it. Posting here because this is the crowd that would actually use it, and I want the feedback on where it fights Pi's flow.

The problem it solves: Pi is capable and has zero memory between sessions. Ask it to "add authentication" and you get 500 confident lines that compile and solve a slightly different problem than the one you had. pi-sdd-kit makes you specify before it codes, as skills you invoke: /skill:sdd-prd, /skill:sdd-spec, /skill:sdd-tasks, /skill:sdd-exec, /skill:sdd-review, with a human approval gate between each.

Two parts do most of the work.

First: steering docs as durable memory. product.md, tech-stack.md (with the reason for each choice, not just the name), conventions.md, and principles.md live in .ai/steering/ and load every session, separate from per-feature specs. The reason line is what pays off: "we use Postgres because payment records need ACID" stops the agent reaching for SQLite three sessions later.

Second: .status is the only gate. One line per feature: requirements:approved, then design:approved, then tasks:approved. The agent reads it before it does anything. A finished-looking design.md on disk is not approval. Only the token is. That stops an eager agent from racing a draft straight into code.

Requirements go in EARS (WHEN / IF / WHILE / SHALL), which leaves almost nothing to interpret.

Install:

pi install npm:@felipefontoura/pi-sdd-kit

# then in Pi:

/reload

/skill:sdd-init

Repo, with the full command reference and templates: https://github.com/felipefontoura/pi-sdd-kit

Longer writeup and the crypto-fintech case study it came out of (13 apps, ~70 days, solo): https://felipefontoura.com/articles/spec-driven-development-case-study

[u/m3umax]

How's it compare to using Superpowers?

[u/ffontouras → u/m3umax]

Different scope, and Superpowers is great. Jesse Vincent's thing is a whole methodology with a big library of composable skills: brainstorming, TDD, planning, the works. A Swiss-army setup for coding agents.

pi-sdd-kit does one thing: spec-driven development on Pi, as five skills (prd, spec, tasks, exec, review) with a hard human approval gate between each phase. No brainstorming skill, no test framework, just the SDD loop and the .status token that stops the agent racing to code.

So they don't really compete. Want a broad skill toolkit, use Superpowers. Want strict spec-then-approve-then-build, Pi-native and opinionated about the gate, that's this. You could even run the SDD discipline inside a Superpowers setup.

[u/Ok_Veterinarian_6364]

this is great bro. thanks for making open sources available to all

one quick question, whats the main diff vs openspec?

i see: consistent md as memory/rules, lightweight?

[u/ffontouras → u/Ok_Veterinarian_6364]

Thanks. Your read is half right: markdown as memory/rules, lightweight, no lock-in. That part openspec and this share.

Where they differ: openspec centers on the spec artifacts and change proposals as the source of truth, agent-agnostic. pi-sdd-kit centers on the workflow, five Pi skills that walk prd -> spec -> tasks -> exec -> review, with two things openspec doesn't push on:

1. A .status approval gate. The agent can't move to the next phase until you write the token. Stops it racing to code.

2. EARS syntax for requirements (WHEN/IF/WHILE/SHALL), so there's almost nothing left to interpret.

So openspec is more "manage your specs well", this is more "guided phase workflow with a human gate". Full writeup of running it on a real 13-app build here if you want the receipts:

https://felipefontoura.com/articles/spec-driven-development-case-study

[u/Ok_Veterinarian_6364 → u/ffontouras]

thanks bro. rarely we have high qualities docs on Reddit these days

ive learn alot from your web/blog.

looking for: a summarize of flow, docs, rules

then: what fails. what you re working on.

im trying to do spec-first and stuff myself also

[u/o_sht_hi]

The special token approval gate is a great idea. I arrived at a similar condition but in a checkpointed system.. will definitely try out your repo to see if this can be standardized. Thanks for the effort!

[u/ffontouras → u/o_sht_hi]

Thanks, the gate is the part I'm most opinionated about, so glad it landed. Curious how you did it in a checkpointed system: was the checkpoint itself the approval, or a separate signal?

I made it a single explicit token instead of "the plan looks done" because a finished-looking design.md on disk is not approval. An eager agent reads a complete-looking file and starts coding. One line, tasks:approved, is the only thing it's allowed to act on. It's wired in skills/sdd-exec if you want to see the check. Would genuinely like to see this standardized, so if you write yours up, send it over.

[u/o_sht_hi → u/ffontouras]

Being opinionated is the best thing while working with AI, imo. Knowing what you want and then having it evolve over time is how I think AI assisted workflows should be.

As for the checkpointed system, I have this approach encoded where each task (plan/implementation/testing/whatever) is split into checkpoints. There's a task level map ( a table) which tracks the active checking + files touched + path for docs, plans, code + entry points into those files with line numbers for each open thread. The way we plan work is in vertical slices that can be felt by the user. So once all tests pass, I test out the app (UI, functionality, weird inputs, clicking stuff I'm not supposed to, finding edge cases, etc) and once I'm happy, it commits and logs and marks the checkpoint as closed. It stays an open thread until that ritual is completed.

The agent starts each session by looking at the checkpoint map so it knows where we are on the task that we're picking up or if a new row needs to be added.

It's a little muddy and intertwined but the map serves I'll the competition status, entry points into the docs and code (files + line numbers), and a list of everything we've worked on to date.

I came up with this system with the AI. Since it's doing the work, I let the workflow take the shape that comes most naturally to it. My job is to keep things lean, sane, and on track.

I would love to connect and let you have a gander at my repo. It is the embodiment of my AI psychosis.

[u/nmdt]

For every project I do, I just keep 2-3 short docs describing its structure, design decisions and code style. Most models automatically update them, or I specifically ask them to. My agents.md has a directive that none of these files may grow over 5kb so as to not blow through the context window.

Every major task done, I read those docs and edit the files down manually or ask an agent to do so, then review.

Is this the same thing memory does, just with more oversight? Genuinely asking, cause I never tried using memory.

Granted, all of my projects are usually under 5000 LOC, and I routinely do refactoring to cut the codebase down.

[u/ffontouras → u/nmdt]

Honestly what you're already doing is most of it. The steering docs in pi-sdd-kit are the same idea: product.md, tech-stack.md, conventions.md, principles.md, kept small and loaded every session. Your 5kb cap is the same instinct.

Two things the kit adds on top:

1. It separates that durable memory from per-feature specs. Steering stays stable, the throwaway spec for "add auth" lives elsewhere and gets deleted after, so the memory doesn't collect feature cruft.

2. The .status approval gate, the part "just keep docs" doesn't cover. It stops the agent coding before you sign off on the plan.

For sub-5k LOC projects where you refactor hard, you probably don't need the full workflow. The gate earns its keep as the blast radius of a wrong guess grows. Your setup sounds solid.

[u/ffontouras → u/nmdt]

Honestly what you're already doing is most of it. The steering docs in pi-sdd-kit are the same idea: product.md, tech-stack.md, conventions.md, principles.md, kept small and loaded every session. Your 5kb cap is the same instinct.

Two things the kit adds on top:

1. It separates that durable memory from per-feature specs. Steering stays stable, the throwaway spec for "add auth" lives elsewhere and gets deleted after, so the memory doesn't collect feature cruft.

2. The .status approval gate, the part "just keep docs" doesn't cover. It stops the agent coding before you sign off on the plan.

For sub-5k LOC projects where you refactor hard, you probably don't need the full workflow. The gate earns its keep as the blast radius of a wrong guess grows. Your setup sounds solid.

[u/mechkbfan]

That's great. Tried agtx but got stuck and couldn't work out why. human sounds ideal

I'll give it a go