I use a lightweight spec-driven workflow in real projects. The point is simple: move intent, research, architecture, and tickets out of chat memory and into files. Over time I packaged the repeatable parts into SDDRush.
What it solves
The failure mode is old and still common. The plan lives in chat.
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 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.
What SDD looks like in practice
The workflow is compact:
- write a project brief
- gather focused research
- make architecture decisions explicit
- sync the backlog into concrete tickets
- implement against the open ticket
- clean up status and close what is actually done
Nothing 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.
What SDDRush 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 a quick read on what is still open and what has already moved.
Enough for a lot of work. 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/projectThen fill the core .sdd files, implement against backlog/open, and run janitor/status once the repo evidence catches up.
Where Kotef fits
If you want to push the same workflow further, Kotef is the agent layer I built around the same ideas. 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.
Useful when you want a durable coding and research agent for real repositories. Does not change the underlying point. The workflow needs structure before the agent deserves autonomy.
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 outweighs the value.
This is also the workflow I trust for benchmark-style work where grounding, latency, and telemetry matter at once. The Agentic RAG Legal Challenge is a current example, where the system is judged as a full pipeline rather than as a clever prompt.
What translated well there was discipline. Small diffs with visible lineage. Explicit gates for grounding and provenance. Branches that looked good but made the evidence trail worse got killed early.
What did not help. Broadening context for its own sake. Changing too many variables in one run. Trusting a cleaner-looking answer before the path behind it was stable.
What not to do
Common mistakes:
- 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.
This workflow is useful because it makes intent easier to inspect, implementation easier to hand off, 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.