Build Your Own SDD Workflow

Spec-driven development works. Planning before you code catches bad assumptions early, keeps scope honest, and gives the AI enough context to write code you'd actually ship. That's not the problem.

The problem is ceremony. GitHub spec-kit gives you seven steps, multiple checkpoints, and templates designed for large teams coordinating across repos. When you're adding a component or fixing a bug, that's a lot of overhead for a Tuesday afternoon.

And it's not like there's a shortage of alternatives. New AI workflow repos show up weekly. Everyone's got an opinion on the "right" way to structure AI-assisted development.

Here's the thing — what if you just built the one that fits how you think?

That's what this article is. We'll build a 4-step SDD workflow from scratch and wire it into SpecKit Companion so you can see and run each phase visually. Four commands, four files, zero ceremony.

What We Kept

GitHub spec-kit gives you seven steps: constitution, clarify, specification, plan, tasks, implement, review. I only needed four.

So the pipeline looks like this: specify → plan → tasks → implement

All four map to SpecKit Companion phases. The first three produce markdown files. Implement runs the sdd.implement command — it doesn't produce a file, it executes the work.

Get the Files

Here's what goes into your project. Seven files — four commands that tell the AI what to do, three templates that define what the output looks like:

Grab the SDD Starter Files (Gist) — drop them in the folders above and you're ready.

Why SpecKit Companion

You could run these commands from the terminal and call it a day. But SpecKit Companion gives you something the terminal doesn't — you can see where you are. Each phase shows up in the sidebar, you click to advance, and you always know what's done and what's next. It turns a set of markdown commands into an actual workflow you can follow.

Here's the config. Add this to .vscode/settings.json:

{
  "speckit.customWorkflows": [
    {
      "name": "sdd",
      "displayName": "SDD",
      "description": "Lean 4-step SDD workflow: specify, plan, tasks, implement",
      "steps": [
        {
          "name": "specify",
          "label": "Specify",
          "command": "sdd.specify",
          "file": "spec.md"
        },
        {
          "name": "plan",
          "label": "Plan",
          "command": "sdd.plan",
          "file": "plan.md"
        },
        {
          "name": "tasks",
          "label": "Tasks",
          "command": "sdd.tasks",
          "file": "tasks.md"
        },
        {
          "name": "implement",
          "label": "Implement",
          "command": "sdd.implement",
          "actionOnly": true
        }
      ]
    }
  ],
  "speckit.defaultWorkflow": "sdd"
}

Four steps — the first three produce markdown files. Implement runs the command but doesn't produce a file; it executes the work.

Walking Through a Feature

Let me walk you through a real feature. We're adding a home page and navigation bar to an empty application — enough to see every phase in action.

Specify

Click "+" in the SpecKit Companion sidebar, describe what you want — "Add a home page with a navigation bar" — and select the SDD workflow.

Once the specification finishes, the new spec appears in the sidebar. Open it and you'll see what we're building. Under the hood, the AI explored two or three relevant files, figured out the scope of the change, and wrote spec.md — summary, requirements with Given/When/Then scenarios, and what's out of scope.

Plan

Hit Plan at the bottom of the Specify phase. The command reads spec.md, researches existing patterns in your repo, and writes plan.md — the approach, files to create or modify, and risks.

Here's the part I like — it stops and shows you the plan before anything moves forward. You approve, edit, or reject. No guessing, no "let me just refactor this real quick" surprises.

Tasks

Click Tasks. The command reads both spec.md and plan.md, then breaks the plan into phased, verifiable tasks. Each task gets a Do/Verify pair — what to build and how to confirm it works. Phase 1 runs in order. Phase 2 tasks are tagged for parallel execution — tests, docs, cleanup that can run as separate agents.

Implement

Drop to the terminal, run /sdd.implement. This is where the AI actually writes code. It reads all three files, executes Phase 1 tasks sequentially, auto-fixes small issues like import errors, but stops for anything architectural. Phase 2 agents launch in parallel. It commits and optionally opens a PR.

Implement lives in the terminal because that's where code belongs. SpecKit Companion handles planning. The terminal handles execution.

For something small like adding a title to the nav bar, you don't need four round-trips. That's where Fast Mode comes in.

Quick Change: Fast Mode

Let's say we want to add a title to the navigation bar. Run /sdd.specify add a title to the nav bar. The command looks at the change, sees it's a single-file fix, and skips the deep codebase exploration, architecture research, and multi-step planning. Instead, it generates spec.md, plan.md, and tasks.md in one pass — all the artifacts, none of the ceremony.

One command, and you're ready to implement.

The Checkpoint

Run /sdd.implement. The AI creates a branch, executes the task, and then stops. Before anything gets pushed, it shows you exactly what happened — every file changed, the commit message, and the PR body. You approve, edit, or reject. Nothing leaves your machine without your sign-off.

Two interactions total. Full traceability. And if you don't like the PR title, you fix it right there.

Make It Yours

Every step is a markdown file. Change the markdown, change the behavior. That's the whole point of building it yourself.

Fast Mode — the quick change above? That's a complexity check in sdd.specify.md. If the change is a single-file fix or bug, it generates all three planning files in one pass and skips straight to implement. You can tune the threshold or disable it entirely.

Branch + PR + Checkpoint — the approval step you just saw? That's worktree isolation and a checkpoint in sdd.implement.md. The AI works on a separate branch, presents the commit and PR for review, and only pushes after you approve.

Custom sections — want "Security Considerations" in every spec? Add one line to sdd.specify.md. Want conventional commits? Add a rule to sdd.implement.md. Want TDD enforced? Add "write tests before implementation" to sdd.tasks.md.

And the workflow commands are just the first layer. Add rules in CLAUDE.md, build a pattern library, wire in specialized agents — each layer makes the next one better.

• Layer 1: Workflow commands — sdd.specify.md, sdd.plan.md, sdd.tasks.md, sdd.implement.md. The structure.
• Layer 2: Rules — CLAUDE.md / AGENTS.md. Naming, testing, commit standards. Written once, applied to every feature.
• Layer 3: Pattern library — "Here's how we do X." Component templates, API patterns. The AI matches your codebase instead of guessing.
• Layer 4: Skills and agents — Specialized tools called during steps. Route TypeScript to a code reviewer, HTML to an accessibility expert.

It's all markdown. Improving it is trivial.

Get Started

1. Grab the SDD Starter Files (Gist) — 4 commands + 3 templates
2. Configure SpecKit Companion — copy the settings.json snippet above
3. Demo repo — the project from this walkthrough, with all commands and config ready to clone
4. Evolving version — I'm building on this at alfredoperez/sdd, a Claude Code plugin incorporating the best patterns from 8+ open-source AI workflows

Install SpecKit Companion from the VS Code Marketplace, drop the files, and start shipping. Next up: how to scale this across a team with shared specs and conventions.