Spec-driven development¶

Intent lives in a spec. The coding agent builds; tuvl referees. Every tuvl step below is deterministic and spends no tokens — only the agents you build (llm, loop, decision models) call models at run time.

spec (.md) ──spec check──▶ checked spec ──coding agent (skills)──▶ task list + workflows, models, code, tests
   ▲                                                                        │
   │ spec diff / P005: stale tasks                                          ▼
   │                                              codegen: schemas, stubs, prompt placeholders, tests
   │                                                                        │
   └── derived task status ◀── spec verify · validate · test (honest) ◀─────┘
                                                                            │
                                                                     lock · ship

1. Write the spec¶

A spec is Markdown. Prose sections (# Intent, # Policies, anything else) are for people and the coding agent. Three sections are structured and checked: # Data, # Flows and the tuvl-example blocks under # Acceptance. tuvl spec new refund-request writes a template that passes tuvl spec check.

---
name: refund-request
owner: payments-team
---
# Intent
Customers request refunds. Small ones are paid automatically; large ones need a finance lead.

# Data
- **Order** (existing) — `id` (uuid), `customer_email` (string; secure), `total` (numeric)
- **Refund** (new) — `order_id` (uuid → Order; required), `amount` (numeric; required),
  `status` (enum: requested | approved | rejected | paid; required; default requested)

# Flows

## Flow: refund_request
Trigger: POST /refunds · signed-in
Input: `order_id` (uuid), `amount` (float), `reason` (str)
Ends: default 201 · unknown_order 404 · rejected 200 · failed 500

1. `load_order` — tool db read Order · in `order_id` · out `order` (Order)
   - not_found → END.unknown_order
2. `check_amount` — decide rules · in `amount` · out `lane` (enum[auto, review])
   - `amount <= 100` → auto
   - otherwise → review
   - auto → `record_refund`
   - review → `finance_review`
3. `finance_review` — human group finance_lead · expires 24h · in `order`, `amount` · out `approved` (bool)
   - true → `record_refund`
   - false, expired → END.rejected
4. `record_refund` — tool db create Refund · in `order_id`, `amount`, `reason` · out `refund` (Refund)
   - conflict → END.failed

# Acceptance
```tuvl-example
name: a small refund is recorded
given: { Order: [{ id: "6f1c0a52-2a8e-4d0b-9a77-0b9d7c2f1e10", total: 120 }] }
as: { user: u-customer }
input: { order_id: "6f1c0a52-2a8e-4d0b-9a77-0b9d7c2f1e10", amount: 40, reason: "Arrived broken." }
expect: { end: default }
```

Grammar¶

Implicit: default goes to the next numbered step (or END), and error to END.failed.

2. Check it¶

tuvl spec check [SPEC] [--strict] [--json] (MCP spec_check, GET /dev/specs/check) — zero tokens, deterministic. It reports every finding with its line; blocking findings fail.

Prose sections are listed as unchecked. A waived signal or end is reported (·) so a reviewer sees it.

3. Verify the implementation¶

tuvl spec verify [SPEC] [--strict] [--no-tests] [--json] (MCP spec_verify, GET /dev/specs/verify) — zero tokens. It compares each ## Flow: with its workflow, each # Data model with its ModelDefinition, and runs the tests (offline) to see which steps they exercise. Errors are contradictions; warnings are unfinished work (a missing workflow, a pending agent, an untested step), which --strict — the CI gate — also fails.

specs/triage-ticket.md
  triage_ticket
    classify               llm default                  :23   ✓ mocked in 3
    prioritise             code                         :25   ✓ 3 passed
    review                 human group support_leads    :28   ✓ mocked in 1
    store                  tool db create Ticket        :32   ✓ 1 passed
  0 mismatch(es) · steps implemented 4/4 · exercised by real tests 2/4

4. The task list¶

The coding agent writes the task list (skill tuvl-plan) from the checked spec — tuvl doesn't plan with a model. tuvl checks it as part of tuvl spec check and derives each task's status.

kind: TaskPlan
version: tuvl/v2
metadata: { name: refund-request, spec: specs/refund-request.md, spec_hash: 9f2c… }
spec:
  tasks:
    - id: T3
      title: Route refunds by amount (decide rules)
      type: agent                 # model | workflow | agent | artifact | integration | test | policy | manual
      spec_ref: { anchor: flow-refund-request, hash: 41ad… }
      target: { workflow: refund_request, agent: check_amount }
      depends_on: [T2]
    - id: T7
      title: "Example: a small refund is paid automatically"
      type: test
      spec_ref: { anchor: acceptance, hash: 7be0… }
      target: { workflow: refund_request, example: a small refund is paid automatically }
    - id: T9
      title: Payments API credentials
      type: manual                # only manual tasks set a status
      target: { workflow: refund_request, agent: pay_refund }
      status: todo

One task per new model, per step, per example, and a manual task per external integration (tool http/mcp); dependencies follow the flow. No estimates. After a spec change the agent adds tasks for new steps and marks removed ones obsolete: true (never deletes them).

Derived status¶

Only type: manual tasks take a manual status. Models and artifacts skip tested. A task tuvl can't measure is untracked.

tuvl spec status --json     # derived statuses (runs the tests offline; --no-tests caps at implemented)
tuvl spec status --strict   # exit 1 unless every live task is done and none is blocked or stale
tuvl spec diff              # stale tasks and spec sections no task covers

5. Codegen¶

tuvl codegen [<workflow>] [--check] — deterministic, no model:

--check exits 1 if anything would change (the CI drift gate). tuvl never writes function bodies.

6. Lock¶

tuvl lock writes tuvl.lock: the tuvl version, each AgentModel's model id, each artifact:// ref's version and sha256, judge and decision-model versions, and each allowed MCP tool's input-schema hash (listed live; --no-mcp compares by name only). tuvl lock --check verifies it; tuvl ship requires it (V024) and pins the locked tuvl version in the image.

7. The CI gate¶

tuvl spec check && tuvl validate --strict && tuvl codegen --check && tuvl lock --check && tuvl test --strict && tuvl spec verify --strict && tuvl spec status --strict

tuvl init <name> --sample creates a project that passes this gate as created.

Coding agents¶

• tuvl mcp [-d <project>] [--allow-write] serves the same operations over MCP (stdio): validate, spec_check, spec_verify, spec_status, spec_diff, get_contract, list_agents, explain_error, get_run, get_run_events, codegen, test; with --allow-write also codegen_write, run_workflow, pin_fixture. It refuses TUVL_ENV=production.
• .agents/skills/ (refreshed by tuvl skills update [--diff], mirrored to .claude/skills/): tuvl-spec, tuvl-plan, tuvl-task-loop, agent-code, agent-tool, agent-llm, agent-loop, agent-decide, agent-human, tuvl-data, tuvl-test, tuvl-harden, tuvl-ship, plus a root AGENTS.md with the non-negotiable rules.
• Every read command has --json with a documented schema (/dev/schema/cli in dev mode).