Docs-Driven Development

# Write the contract. Let the agents build to meet it.

Your docs become the source of truth. Smithers generates them from your code, scans for where the code has drifted, and loops it back until the two agree.

$ smithers workflow run docs-driven-development
Docs are the contract Bug-scan finds the drift The loop closes it
deploy.spec.md — §3 Delivery
10## §3.2 Deploy retries
11
12 The deploy step retries 3× with
13 exponential backoff before failing.
14
15 Partial deploys roll back.
bug-scan · against the contract
drift · §3.2

deploy() throws on first failure. No retry, no backoff.

improve · resolved
- await deploy()
+ await retry(deploy, { tries: 3, backoff })

Why this exists

## The agent shipped green. It still solved the wrong problem.

Tests pass, the PR looks clean, and you merge it. A week later you find it does not do what you meant, because nothing ever pinned the intent. There was no artifact the agent was accountable to.

The loop

## Generate. Scan. Improve. Repeat.

Three workflows that turn a pile of code into a spec, then keep the code honest to it.

1

### Generate the docs

Point it at your code and it writes the reference spec: what each part is supposed to do. That spec becomes the contract.

→
2

### Scan for drift

Bug-scan reads code against the spec and files a ticket wherever the two disagree. Real gaps, not guesses.

→
3

### Improve to match

The improve loop takes a ticket and edits the code until it meets the clause, with a test-coverage pass to prove it.

What you get

## A codebase that stays honest.

§ contract

### Docs the agent answers to

Generated reference docs become the spec every later change is checked against, not throwaway comments.

⌕ bug-scan

### Drift becomes tickets

The scan turns "the code does not match the spec" into concrete, reviewable tickets on a board.

↻ quality loop

### Close the gap, on repeat

The improve and quality-loop workflows keep pulling code toward the contract until they agree.

✓ coverage

### Proof it holds

A test-coverage workflow backs each fix with a test, so the contract stays enforced over time.

## Stop reviewing green PRs that missed the point.

Generate the spec, let the scan find the drift, and let the loop close it.

$ smithers workflow run docs-driven-development