tessl install tessl-labs/spec-driven-development@1.0.5Spec-driven workflow covering task intake, spec format, styleguide, and manual verification practices.
This repository contains the source code of the "Spec Driven Development" tile released by Tessl.
A methodology tile that teaches AI coding agents to gather requirements, write specifications, and get approval before writing code.
When installed, this tile changes how your AI coding agent approaches tasks. Instead of diving straight into code, the agent will:
This is the difference between an agent that assumes what you want and one that asks.
tessl init
tessl install tessl-labs/spec-driven-developmentnpx @tessl/cli install tessl-labs/spec-driven-developmentAfter installation, include "use spec-driven development" in your prompt:
Create an API for managing user subscriptions. Use spec-driven development.The agent will start by asking questions rather than writing code:
Once requirements are clear, the agent creates specs in a specs/ directory, waits for your approval, then implements.
This tile contains methodology guidance (no code, no special tooling):
| File | Purpose |
|---|---|
index.md | Core workflow: requirement gathering → spec creation → approval → implementation → review |
spec-format.md | How to structure spec files: YAML frontmatter, targets, [@test] links |
spec-styleguide.md | Best practices for writing clear, maintainable specs |
spec-verification.md | Manual verification workflow to keep specs and code synchronized |
Specs are markdown files (.spec.md) with YAML frontmatter:
---
name: User Authentication
description: Login and session management
targets:
- ../src/auth/*.py
---
# User Authentication
Users can log in with email and password.
```python
def login(email: str, password: str) -> Session: ...
def logout(session_id: str) -> None: ...[@test] ../tests/auth/test_login.py
Key elements:
- **`targets`**: Files or glob patterns the spec describes
- **`[@test]` links**: Inline references to tests that verify each requirement
## Why Spec-Driven Development?
**Vibecoding** (prompting without structure) produces apps that:
- Hallucinate APIs from stale training data
- Have useless error handling ("Something went wrong, try again")
- Lack tests
- Can't be verified against intent
**Spec-driven development** produces apps where:
- Requirements are explicit and reviewable
- Implementation can be verified against specs
- Tests trace back to documented requirements
- You maintain control over what gets built
## How It Works
This is a **steering tile** — it provides guidance that becomes part of the agent's context. When you install it:
1. Tessl adds the tile's markdown files to your project's `.tessl/` directory
2. Your MCP-compatible agent (Claude Code, Cursor, etc.) reads this context
3. The agent follows the methodology described in the tile
No special commands. No annotations. No framework. Just well-crafted documentation that changes agent behavior.
## Workflow Overview┌─────────────────────────────────────────────────────────────────┐ │ REQUIREMENT GATHERING │ │ • Review existing specs │ │ • Identify ambiguous areas │ │ • Interview stakeholder (one question at a time) │ │ • Create/update specs │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ STAKEHOLDER APPROVAL │ │ • Review specs for accuracy │ │ • Confirm requirements are complete │ │ • Approve to proceed with implementation │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ IMPLEMENTATION │ │ • Build against approved specs │ │ • Create tests linked to requirements │ │ • Follow targets defined in specs │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ REVIEW │ │ • Verify all requirements satisfied │ │ • Update specs with any discovered requirements │ │ • Ensure tests are linked from specs │ └─────────────────────────────────────────────────────────────────┘
## Combining with Library Tiles
This methodology tile works well alongside library/framework tiles from the [Tessl Registry](https://tessl.io/registry). For example:
```bash
tessl install tessl-labs/spec-driven-development
tessl install tessl/maven-io-quarkus--quarkus-coreNow your agent knows how to work (spec-driven methodology) and what tools to use correctly (Quarkus APIs). This prevents both process chaos and API hallucination.
MIT License — see LICENSE for details.