SDD Plugin: Spec-Driven Development for Claude Code

Inspiration

After 30 years of building software, I have a mental model of what good planning looks like, and watching AI coding agents skip past it has been frustrating. People jump straight to prompting without structured planning, which leads to vague instructions, scope creep, and builds that drift from intent. Every new chat session starts from zero. Context evaporates, decisions get re-litigated, and feedback from earlier sessions disappears into the void.

I had been using my own manual workflow for a while: ask the AI to generate a list of planning questions, then answer them one at a time. It worked, but the questions went stale by the time I finished them because ideas evolve as you talk. Then I came across Devpost's hackathon-in-a-plugin curriculum and recognized exactly the structure I had been hand-rolling. So I decided to use the Devpost hackathon plugin to build a more general version of itself.

What it does

The SDD Plugin turns spec-driven development into a guided, repeatable Claude Code workflow. The eleven commands are organized into three phases:

• Planning phase: /sdd:onboard (one-time per machine; captures user profile and communication preferences), /sdd:scope, /sdd:prd, /sdd:spec. Each runs a one-question-at-a-time interview with optional deepening rounds, producing a markdown artifact and updating CLAUDE.md and AGENTS.md so the AI has authoritative operating instructions.
• Sprint loop: /sdd:sprint pulls a logical batch of work from the PRD into a buildable sprint with verification steps. /sdd:build executes it (step-by-step or autonomous mode). /sdd:iterate adds polish work mid-sprint. /sdd:reflect does the sprint retrospective, splits partially-completed stories, and recommends the next move. /sdd:refine runs unvetted PRD additions through a compressed planning interview.
• Project close: /sdd:retro synthesizes a project-level retrospective across all sprints. /sdd:feedback runs at any time, capturing plugin improvement notes with auto-context (timestamp, sprint, last command, project) without interrupting the flow.

The result is markdown artifacts at every stage: scope, PRD, spec, sprint files, CLAUDE.md, AGENTS.md, process notes, reflection, retrospective. All version-controlled in the project directory and read fresh by the AI each session.

It may sound familiar because it is the hackathon plugin, but adapted.

How we built it

I built the plugin as a pure Markdown skills architecture. No runtime code, no build step, no dependencies. All behavior lives in SKILL.md files with YAML frontmatter, plus reference files and templates. I adapted it from the hackathon-in-a-plugin curriculum's pattern but stripped the hackathon-specific framing (no learner profiles, no time-boxing to 3-4 hours, no submission artifacts) and rebuilt around a project-agnostic workflow with sprints, retrospectives, and a backlog.

The build itself ran through the SDD process recursively. I ran /scope, /prd, /spec, and /checklist on the plugin idea, generating the planning documents included in this submission. Then /build worked through 16 checklist items in autonomous mode, with verification checkpoints every 3-4 items and a commit per item. Distribution went to a marketplace repo at github.com/zabuuq/sdd-plugin, so anyone can install it with /plugin marketplace add zabuuq/sdd-plugin.

Challenges we ran into

• Auto-compaction on a parallel project. While running another long build with Claude Code, I hit context-window auto-compaction mid-stream. That pain became architecture: /sdd:build loads only the specific spec subsection and PRD story for the current checklist item, never the full documents. This is the single most important technical decision in the plugin, and it came out of failure, not foresight.
• Lost feedback across sessions. While working on /spec, I went back to old /scope and /prd session outputs and discovered that flagged concerns had evaporated with the conversations. Nothing carried them forward. That gap produced docs/open-concerns.md: a dedicated file every command reads on startup, resolves what it can (including implicit resolutions, marked explicitly), defers what it can't with rationale, and appends new concerns from its own work.
• PRD session pause. The PRD interview ran long enough that I had to pause partway through and resume in a later session. That itself became a useful test of whether the planning artifacts could carry context across a true session break. They could, but it forced me to think harder about state files and resumption.
• Post-sprint ceremony felt too heavy. During dogfooding on three downstream projects, the post-sprint cluster (/sdd:reflect + /sdd:refine + /sdd:retro) started to feel like overhead: too much structured introspection for sprints where the honest answer was "it went fine." I'm now using the plugin on itself to consolidate these into a single more flexible command.

Accomplishments that we're proud of

• All 16 checklist items shipped, validated on three projects. The plugin isn't a demo. One downstream project is complete, two are still in-flight, and the workflow has held up across all three.
• Surgical context loading works. Across multi-sprint dogfooding, I haven't hit auto-compaction once. Exactly the failure mode that motivated the design.
• The self-improvement loop is real. I sketched it during /scope: the plugin captures feedback during use, and later you take that feedback to the plugin's own repo and run the SDD process on the plugin itself. It's now running. I'm using the plugin to redesign the plugin.
• Zero scope creep. The PRD's "What we'd add with more time" list (GitHub integration, Jira/Linear, multi-agent, automated improvement) stayed there. Discipline I credit entirely to the planning process, imposing it.
• Open source under MIT, shipped to a public marketplace. Anyone can install it.

What we learned

Context lives in files, not in chat history. The mechanisms that earned their keep in real use were all about persisting context across /clear boundaries: surgical loading, the open-concerns file, lastCommand tracking, CLAUDE.md as architectural summary. Once you internalize this, a whole class of "the AI forgot" failures stops happening.

Adaptive interviewing beats pre-built question lists. With my old workflow, by the time I finished a stale question list, ideas had evolved past it. Generating questions one at a time, responsive to what's already been said, keeps the conversation fresh and surfaces things upfront that question-batching never could.

Friction at boundaries gets noticed; friction in-flight gets noticed because it's not there. The post-sprint retrospective ceremony felt heavy because it interrupted flow. /sdd:feedback felt right because it captures notes without interrupting anything. The cleanest proof that /feedback works: I used it to flag the heaviness of the other commands.

Building the tool forced me to discover parts of the methodology, rather than only encoding what I already knew. The sprint concept emerged during /prd. The open-concerns mechanism emerged during /spec. The self-improvement loop emerged during /scope. Spec-driven development isn't a fixed practice you apply. It's a thinking discipline that evolves as you push on it.

What's next for SDD Plugin: Spec-Driven Development for Claude Code

• Post-sprint command consolidation. Collapse /sdd:reflect, /sdd:refine, and /sdd:retro into a single, more flexible command that scales effort to what the sprint surfaced. Already in flight, using the plugin on itself.
• GitHub integration as an optional tracking layer. Issues, milestones, labels, and project boards alongside (or replacing) markdown sprint files. Held out of v1 deliberately, but a natural next step.
• Jira and Linear integration. Same concept, different platforms. Would need an abstraction layer on top of the tracking backend.
• Project templates. Pre-seeded scope, PRD, and spec for common project types (web app, API, CLI tool) to accelerate the planning phases when the shape is well-known.
• Multi-agent support. AGENTS.md is generated now, but dedicated config files for Gemini, Codex, and Copilot would broaden where the plugin is useful.
• Sharing with the community. MIT licensed, public marketplace, and I'm planning to share with friends, colleagues, and back to the Devpost hackathon community where the inspiration came from.

Install

/plugin marketplace add zabuuq/sdd-plugin
/plugin install sdd@sdd-marketplace

Built With

• claude-code
• git
• github
• markdown
• plugin-skills
• yaml