Spec-Driven Development: the workflow I actually use

1. What problem this solves

The failure mode is old and still common: the plan mostly lives in chat.

That looks fast for a day or two. Then the task spans another session, another engineer, or another agent, and the shape of the work starts to drift.

What usually breaks first:

• the original intent gets watered down
• architecture gets re-decided in fragments
• tickets stop matching the real plan
• handoff depends on memory and optimism

That is the part I want to remove.

2. What SDD means in practice

In practice the workflow is compact:

1. write a project brief
2. gather focused research
3. make architecture decisions explicit
4. sync the backlog into concrete tickets
5. implement against the open ticket
6. clean up status and close what is actually done

None of this is exotic. That is the point. I am not trying to invent a new religion for software delivery. I want a repo trail that survives more than one conversation.

3. What SDDRush actually gives you

SDDRush is the small toolkit I built around this workflow.

It handles the parts I got tired of recreating by hand:

• sdd-init creates the .sdd workspace and the basic file structure
• sdd-prompts renders repo-aware prompts from the current project state
• sdd-backlog syncs and maintains backlog tickets
• sdd-status gives you a quick read on what is still open and what has already moved

That is enough for a lot of work already. If the repo matters, the task spans multiple sessions, and you do not want the project brief to dissolve into folklore, the toolkit is useful.

Quick start

bash bin/sdd-init /path/to/project --stack "Python/FastAPI" --domain "legal"
python bin/sdd-prompts /path/to/project
python bin/sdd-backlog sync /path/to/project
python bin/sdd-status /path/to/project

Then fill the core .sdd files, implement against backlog/open, and run janitor/status once the repo evidence catches up.

4. Where Kotef fits

If you want to push the same workflow further, Kotef is the agent layer I built around the same ideas.

I would frame it as the more ambitious companion, not the thing you need first.

Kotef can:

• bootstrap SDD state for a repo
• reason over tickets instead of freestyling from a naked prompt
• run a planner -> researcher -> coder -> verifier -> janitor loop
• keep runtime state, checkpoints, and resume paths for longer tasks

That makes it interesting when you want a durable coding and research agent for real repositories. It does not change the underlying point: the workflow needs structure before the agent deserves autonomy.

5. When this approach pays off

I reach for this setup when:

• the task has more than one non-trivial decision
• the repo context matters
• the work will span more than one session
• another engineer may need to audit the path later

I do not reach for it when the task is tiny and the overhead would outweigh the value.

This is also the kind of workflow I trust for benchmark-style work where grounding, latency, and telemetry all matter at once. A current example is the Agentic RAG Legal Challenge, where the system is judged as a full pipeline rather than as a clever prompt.

What translated well there was not drama, but discipline:

• small diffs with obvious lineage
• explicit gates on grounding, latency, and provenance
• fast rejection of branches that looked clever but made the evidence trail worse

What did not help was broadening context indiscriminately, changing too many variables at once, or trusting a cleaner-looking answer before the path behind it was stable.

6. What not to do

The common mistakes are predictable:

• turning every small bugfix into a ceremony
• starting with the agent while the task is still vague
• treating prompt output as durable project memory
• writing specs that sound complete but do not constrain implementation

The method should reduce guesswork. If it mainly produces prettier paperwork, something has gone wrong.

7. Closing note

This workflow is useful because it makes intent easier to inspect, implementation easier to hand off, and backlog state harder to fake. SDDRush exists because I use this pattern enough to want the boring parts scaffolded. Kotef exists because sometimes I want to automate more of the same loop without throwing the structure away.

Repositories

• SDDRush on GitHub
• Kotef on GitHub