Spec-Driven Development with Tessl

Spec-driven development is a workflow where your AI coding agent gathers requirements and writes specifications before writing any code. You review and approve the specs, then the agent implements them.

The Problem with Vibecoding

When you prompt an agent without structure, you get vibecoded output:

• The agent assumes what you want instead of asking

• It hallucinates APIs from stale training data

• There's no way to verify the result matches your intent

• When you restart the session, the agent has no easy way to regain context

This creates an intent-to-code chasm — a gap between what you meant and what you got. The agent produced something, but you have no systematic way to check if it's the right thing.

Vibecoding is fine for throwaway prototypes. For anything you actually care about, you need a process that bridges that gap.

Quick Start

Assuming Tessl is already set up and ready to go in your terminal, install the spec-driven development tile:

tessl init
tessl install tessl-labs/spec-driven-development

Then include "use spec-driven development" in your prompt:

Build a REST API for managing team projects. Use spec-driven development.

That's it. The agent now follows a structured workflow instead of diving straight into code.

What Happens Next

1

The agent asks questions first

Instead of making assumptions, the agent interviews you:

• What endpoints do you need?

• How should authentication work?

• What happens when a resource isn't found?

• Should deleted items be soft-deleted or permanently removed?

One question at a time, until requirements are clear.

2

The agent writes specs before code

The agent creates specification documents in a specs/ folder. These are markdown files that capture:

• Functional requirements

• API contracts

• Edge cases and error handling

• Links to tests that verify each requirement

3

You approve before implementation begins

The agent pauses while you (and all the stakeholders) review the specs. This is your checkpoint — if something's wrong or missing, you catch it before any code is written.

4

Implementation follows the specs

Once you approve, the agent builds against the documented requirements. When it's done, it verifies that all requirements are satisfied and updates specs with anything discovered during development.

Combining with Documentation Tiles

The spec-driven development tile teaches your agent how to work. Tiles with documentation from the Tessl Registry teach it what tools to use correctly.

Together, they're powerful:

tessl install tessl-labs/spec-driven-development
tessl install tessl/npm-express
tessl install tessl/npm-langchain

Now your agent:

• Follows a structured workflow (spec-driven tile)

• Uses Express APIs correctly without hallucinating (Express tile)

• Implements LangChain patterns properly (LangChain tile)

Process without library context gives you well-organized hallucinations. Documentation and code samples without process yield correctly spelled chaos. You need both.

Learn More

For details on the spec format, the [@test] linking syntax, and what's inside the tile: see the tile documentation on GitHub.