SDD HARNESS — Speaking the same language before the first line
A 5-phase wizard so agents build what I had in my head · Internal tool · Specification-Driven Development
- Client
- Side project / internal tool — RBT Studio
- Role
- Skill design and development
- Timeline
- May 2026 · in active use
- Stack
- Claude Code · skill, Specification-Driven Development, Multi-agent architecture, TDD
Every time I started a new project with agents, the starting point was different: sometimes straight into code, sometimes a spec improvised in a message. The result was always the same — specs inconsistent from one project to the next, and a disconnect between what I had in my head and what the agents ended up building.
The problem: What existed was either too little or too much
The simplest planning skills had no real depth: a spec template with nothing behind it to ensure the resulting code met it. The most complete ones went to the other extreme — heavy processes designed for large teams that, on a personal or mid-sized client project, are pure friction: lots of ceremony, little agility.
How it was approached
- Search first, build later. Before writing anything I looked for existing solutions — other structured-planning skills — and none fitted. The simplest ones had no real depth: a spec template with nothing behind it to ensure the resulting code met that spec. The most complete ones went to the other extreme: heavy processes designed for large teams, which on a personal or mid-sized client project turned into pure friction. I needed something in between.
- Treat it as a Lean system, not project management in disguise. The key design decision. Instead of a single-document template, I structured it as a 5-phase wizard, each phase with a concrete responsibility and a clear output that feeds the next: SPEC (what and why), ARCHITECT (how and which decisions), SCAFFOLD (base structure), HARNESS AGENTS (coordination) and HANDOFF (delivery and context).
- TDD as the only non-negotiable discipline. The system’s pivot point is TDD: every implementation phase requires the tests to pass before it is accepted, which acts as a real anchor against drift — both mine and the agents’. It’s the difference between “I think this meets the spec” and “this meets the spec because the tests confirm it”. Adding more phases or more ceremony would have reintroduced the friction I wanted to avoid; removing the test discipline would have taken me back to square one.
5-phase wizard: SPEC → ARCHITECT → SCAFFOLD → HARNESS AGENTS → HANDOFF → TDD as the anchor in every phase
Solution: A Lean system with one non-negotiable discipline
Five sequential phases, each with a concrete responsibility and a clear output that feeds the next, generating the documentation artefacts before touching implementation code. Adding more phases would have reintroduced the friction; removing the test discipline would have taken me back to square one — good intentions without verification.
Product decisions
- my role: Skill design and development
- the 5 phases: SPEC what and why
ARCHITECT how and which decisions
SCAFFOLD base structure
HARNESS AGENTS coordination
HANDOFF delivery and context - the anchor: TDD. Every implementation phase requires the tests to pass before it is accepted — the difference between "I think this meets the spec" and "this meets the spec because the tests confirm it".
- status: Created in May 2026, in active use. The complete PRD for Job Search OS came out of this process.
Results
There’s no single metric that sums up the impact, but the change in how I work is clear. There is confidence that nothing gets lost between the initial idea and the finished project, because every phase leaves an artefact the next one can consult. There is a shared language between me and the agents: with an explicit spec and architecture before implementing, there’s no ambiguity left for each agent to interpret its own way. And there is less rework, because the TDD approach catches interpretation errors early rather than at the end. I’ve already used it to kick off real projects — the complete PRD for Job Search OS came out of this process, pivoting from an initial idea of a manual CRM to an event-driven Career Operating System with a far more solid architecture than starting straight from code would have produced.
- 5 phases — each with an artefact the next one can consult
- 1 anchor — TDD — the system’s only non-negotiable discipline
- In use — since May 2026, on personal and client projects
"The right structure isn’t in the minimal template or in the exhaustive process, but in a Lean system with well-defined phases and a single non-negotiable discipline that acts as the anchor."
What was learned
- Confidence that nothing gets lost between the initial idea and the finished project — every phase leaves a traceable artefact.
- A shared language between me and the agents. With an explicit spec and architecture before implementing, there’s no ambiguity left for each agent to interpret its own way.
- Less rework. The TDD approach catches interpretation errors early, not at the end — for example, pivoting from a manual CRM to an event-driven Career Operating System before writing any code.
Internal tool, in active use since May 2026.