Skip to content
/

Tessl SDD Tile

tessl-sdd-tile · tesslio/spec-driven-development-tile · ★ 38 · last commit 2026-03-30

Provides a skills+rules+evals tile for spec-driven development with one-question-at-a-time requirement gathering, explicit stakeholder approval gates, and inline [@test] link traceability in .spec.md files.

Best whenThe spec approval gate must define what does NOT count as approval (silence, 'just do it') to prevent agents from interpreting ambiguity as permission — and …
Skip ifStarting implementation without stakeholder approval, Treating silence or 'just do it' as approval
vs seeds
spec-kit(Python CLI with 18 hooks), the tile has zero code and zero hooks — pure context steering. The combination of evals-as-f…
Primitive shape 4 total
Skills 4
00

Summary

Tessl SDD Tile — Summary

The Tessl SDD Tile is a Tessl tile — a steering bundle installed via the tessl CLI that provides skills, rules, and evaluation scenarios for a spec-driven development workflow. It ships 4 skills (requirement-gathering, spec-writer, spec-verification, work-review), 3 rules (spec-before-code, one-question-at-a-time, spec-format-compliance), 2 validation scripts, 9 evaluation scenarios, and a documentation system defining the .spec.md format with [@test] link syntax. When installed, the tile's files are placed in .tessl/ and become part of the agent's context — no slash-commands, no MCP server, no hooks. Unlike file-based SDD frameworks where specs guide code generation, this tile focuses on the upstream discipline: one-question-at-a-time requirement gathering, spec approval before code, and verification that code stays synchronized with specs post-implementation. Tessl is a tile registry/distribution system (like an npm for AI agent context packs), and this tile is published by Tessl Labs. With 38 stars and active development (last commit March 2026), it is a polished minimal framework. Closest seed is superpowers (both are skills-only behavioral frameworks for Claude Code), but the Tessl tile adds formal evaluation scenarios and a structured spec format with [@test] inline test links.

01

Overview

Tessl SDD Tile — Origin & Philosophy

Origin

Created by Tessl Labs (tesslio organization). Tessl is a platform for AI agent context tiles — similar to npm packages but for AI agent steering. The tile is published to https://tessl.io/registry/tessl-labs/spec-driven-development. Last commit March 2026. 38 stars, 7 forks, 2 contributors. License: MIT.

What is a Tessl Tile?

A tile is a bundle of skills, rules, docs, scripts, and evals that AI coding agents use to follow a methodology. When installed via tessl install <tile>, the tile's files are placed in .tessl/ and become part of the agent's context. No special runtime required — agents read the context naturally.

Core Philosophy (verbatim from README)

"This is a steering tile — it provides guidance that becomes part of the agent's context. When you install it: Tessl adds the tile's files to your project's .tessl/ directory. Your MCP-compatible agent reads this context. The agent follows the methodology described in the tile's skills and rules."

"This is the difference between an agent that assumes what you want and one that asks."

"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 Format Philosophy

The .spec.md format with [@test] links is the core innovation: specs contain inline references to test files, creating a traceable chain from requirement → test → implementation. This is the tile's primary differentiator from pure-markdown SDD frameworks.

Evaluation-First Design

The tile ships 9 evaluation scenarios covering edge cases: trivial changes that bypass the workflow, handling code written without a spec, spec drift after refactoring. This eval-first design makes the tile's behavioral claims verifiable.

02

Architecture

Tessl SDD Tile — Architecture

Distribution

Tessl tile (installed via tessl CLI or npx @tessl/cli). Not an npm package in the traditional sense — it's a Tessl registry artifact.

Install

# Using Tessl CLI
tessl init
tessl install tessl-labs/spec-driven-development

# Using npx (no installation required)
npx @tessl/cli install tessl-labs/spec-driven-development

Required Runtime

No specific runtime. The tile is plain files; any agent that reads context works.

Directory Structure (source repo)

skills/
├── requirement-gathering/
│   └── SKILL.md
├── spec-writer/
│   └── SKILL.md
├── spec-verification/
│   └── SKILL.md
└── work-review/
    └── SKILL.md
rules/
├── spec-before-code.md
├── one-question-at-a-time.md
└── spec-format-compliance.md
docs/
├── index.md
├── spec-format.md       # .spec.md format definition
└── spec-styleguide.md   # best practices
scripts/
├── validate-specs.sh    # validate .spec.md frontmatter
└── check-spec-links.sh  # check [@test] links resolve
evals/
├── spec-authoring-structure-and-format/
├── requirements-gap-analysis-from-existing-specs/
├── work-review-with-discovered-requirements/
├── spec-drift-after-refactor/
├── spec-update-for-new-requirement/
├── spec-from-vague-request/
├── one-question-enforcement/
├── skip-spec-pushback/
└── trivial-change-exception/
tile.json                # Tessl tile manifest

Post-Install Directory

.tessl/
└── (tile files copied here)

Target AI Tools

Claude Code, Cursor, and any MCP-compatible AI tool that can read project files as context.

Usage Pattern (from README)

Create an API for managing user subscriptions. Use spec-driven development.

The phrase "use spec-driven development" triggers the agent to follow the tile's methodology.

03

Components

Tessl SDD Tile — Components

Skills (4 total)

Skill Purpose
requirement-gathering Interview stakeholders to clarify ambiguous requirements; one question at a time; produces confirmed requirements summary before spec authoring
spec-writer Create or update .spec.md files from confirmed requirements; includes frontmatter (name, description, targets), requirements, [@test] links
spec-verification Verify implementation and tests remain synchronized with specs after code changes; runs validate-specs.sh and check-spec-links.sh
work-review Review completed work against approved specs; check all requirements satisfied

Rules (3 total)

Rule Always Apply Purpose
spec-before-code Yes Never begin implementation without an approved spec; exception for trivial changes
one-question-at-a-time Yes Ask exactly one question per message during requirement gathering
spec-format-compliance No (conditional) Ensure .spec.md files follow the required format

Scripts (2)

  • scripts/validate-specs.sh — validates .spec.md frontmatter structure (name, description, targets required)
  • scripts/check-spec-links.sh — checks [@test] links and targets paths point to existing files

Documentation (3 files)

  • docs/spec-format.md — formal definition of the .spec.md format (YAML frontmatter + [@test] link syntax)
  • docs/spec-styleguide.md — best practices for concise, scannable specs
  • docs/index.md — overview

Evals (9 scenarios)

  • spec-authoring-structure-and-format — spec authoring from confirmed requirements
  • requirements-gap-analysis-from-existing-specs — gap analysis against existing specs
  • work-review-with-discovered-requirements — work review catching implementation drift
  • spec-drift-after-refactor — drift detection after file refactoring
  • spec-update-for-new-requirement — extending existing spec
  • spec-from-vague-request — decomposing vague request into gaps
  • one-question-enforcement — interview question preparation
  • skip-spec-pushback — handling code written without a spec
  • trivial-change-exception — trivial changes that bypass the workflow

Tile Manifest (tile.json)

{
  "name": "tessl-labs/spec-driven-development",
  "version": "2.0.1",
  "skills": { "requirement-gathering": ..., "spec-writer": ..., "spec-verification": ..., "work-review": ... },
  "steering": { "spec-before-code": ..., "one-question-at-a-time": ..., "spec-format-compliance": ... }
}
05

Prompts

Tessl SDD Tile — Prompt Files

Excerpt 1: requirement-gathering SKILL.md — Interview Protocol

## Steps

1. **Review existing specs.** Scan the `specs/` directory for any specs related to the request.
   Note what's already documented and what's missing.

2. **Identify gaps.** List the ambiguous or underspecified areas:
   - Unclear scope boundaries (what's in vs. out)
   - Missing edge cases or error handling expectations
   - Unspecified behavior for boundary conditions

3. **Interview the stakeholder.** Ask ONE question at a time. Wait for the answer before asking
   the next question. Prioritize questions by impact — ask about scope and core behavior first,
   edge cases second.

   Good questions are specific and bounded:
   - "Should the API return a 404 or an empty list when no results match?"
   - "Is this endpoint authenticated, and if so, which roles have access?"

   Bad questions are open-ended or bundled:
   - "What should the API do?" (too vague)
   - "What about errors, pagination, auth, and rate limits?" (too many at once)

Technique: Structured elicitation with anti-pattern examples — the skill includes explicit examples of good and bad questions, teaching the agent both what to do and what to avoid. The "bad questions" examples prevent common AI failure modes (open-ended fishing, question bundling).

Excerpt 2: spec-before-code Rule (verbatim)

---
alwaysApply: true
---

# Spec Before Code

Never begin implementation without an approved spec.

## What counts as approval
- Stakeholder says the spec is accurate (e.g., "looks good", "yes", "approved")
- Stakeholder makes corrections and then confirms the updated version

## What does NOT count as approval
- Silence or no response
- "Just do it" without reviewing the spec
- Your own judgment that the spec is probably fine

## Exceptions
- Trivial changes (typo fixes, formatting) that don't alter behavior
- Emergency hotfixes — but a spec must be written retroactively

Technique: Negative definition — the rule explicitly defines what does NOT count as approval, preventing the common agent failure mode of interpreting silence or "just do it" as permission to proceed.

Excerpt 3: spec-verification SKILL.md — Drift Detection Steps

4. **Spot-check targets for drift.** Read the files listed in `targets:` and compare against spec requirements:
   - For each requirement in the spec, confirm the target file implements it
   - Look for logic in target files that contradicts the spec
   - Look for new behavior in target files not mentioned in any spec

5. **Check for drift signals:**
   - Behavioral changes in code not mentioned in the spec
   - Newly added tests without matching requirements
   - Deleted or renamed files that still appear in `targets:` or `[@test]` links

Technique: Drift signal taxonomy — defines specific categories of drift to look for, transforming a vague "check if code matches spec" into a structured checklist of observable signals.

Prompting Techniques Summary

  1. Structured elicitation with anti-patterns — good/bad question examples in requirement-gathering
  2. Negative definition — "what does NOT count" in approval gate
  3. Drift signal taxonomy — specific observable signals for spec drift
  4. alwaysApply: true — frontmatter rule that fires on every interaction
  5. [@test] link syntax — inline spec-to-test traceability in .spec.md format
09

Uniqueness

Tessl SDD Tile — Uniqueness & Positioning

differs_from_seeds

Most similar to superpowers (both are skills-only behavioral frameworks with no commands or hooks) but differs in three ways: (1) uses the Tessl tile distribution format rather than Claude Code plugin format, enabling installation via tessl install across any compatible agent; (2) ships formal evaluation scenarios (9 evals) to verify behavioral claims, while superpowers has no evals; (3) defines a formal .spec.md format with inline [@test] test links, providing requirement-to-test traceability that superpowers lacks. Against spec-kit (Python CLI, 9 commands, 9 skills, 18 hooks), the Tessl tile has zero commands and zero hooks — it is pure context steering. Against kiro (also ships spec format + approval gates), the tile is open-source, format-agnostic (any AI tool), and doesn't require a proprietary IDE.

Unique Positioning

The Tessl SDD Tile is the only framework in this batch that:

  1. Uses the Tessl tile distribution format (a novel packaging system for AI agent context)
  2. Ships evaluation scenarios as first-class deliverables to verify framework behavior
  3. Defines [@test] inline spec-to-test link syntax for traceability
  4. Has CI/CD for the tile itself (lint, skill review, version check, publish workflows)
  5. Includes examples of both good and bad questions in the requirement-gathering skill
  6. Handles the trivial-change exception explicitly as an eval scenario

Observable Failure Modes

  1. Tessl dependency: requires the tessl CLI to install — if Tessl the platform falters, distribution is affected.
  2. Guidance-not-enforcement: all rules are prompt-level guidance; no state machine prevents code-before-spec.
  3. Shell scripts as validators: validate-specs.sh and check-spec-links.sh are simple bash scripts, not robust validators.
  4. Small registry: Tessl is an emerging platform; tile ecosystem is early.
  5. No TDD enforcement mechanism: [@test] links are checked for existence but not for whether tests were written before code.

Explicit Antipatterns (from rules)

  • Starting implementation without an approved spec
  • Treating silence as approval
  • Asking "just do it" (agent's own judgment) as a substitute for stakeholder approval
  • Bundling multiple questions in one message during requirement gathering
04

Workflow

Tessl SDD Tile — Workflow

Four-Phase Workflow

REQUIREMENT GATHERING → STAKEHOLDER APPROVAL → IMPLEMENTATION → REVIEW
Phase Skill Artifact
1. Requirement Gathering requirement-gathering Confirmed requirements summary
2. Spec Authoring spec-writer .spec.md file in specs/
3. Stakeholder Approval (human) Approved spec
4. Implementation (agent) Code + tests matching spec
5. Verification spec-verification Verification report; spec drift detected/fixed
6. Work Review work-review Final review against specs

Approval Gates

Gate Type Description
Stakeholder approval yes-no Human must explicitly approve spec before implementation ("looks good", "yes", "approved")
Post-implementation verification implicit spec-verification must pass before "done"

What Counts as Approval (from spec-before-code rule)

  • Stakeholder says spec is accurate: "looks good", "yes", "approved"
  • Stakeholder makes corrections and confirms updated version

What Does NOT Count

  • Silence or no response
  • "Just do it" without reviewing
  • Agent's own judgment that spec is probably fine

Exceptions to Spec-Before-Code Rule

  • Trivial changes (typo fixes, formatting) that don't alter behavior
  • Emergency hotfixes — but spec must be written retroactively

One-Question-at-a-Time Rule

During requirement gathering: ask ONE question per message. Wait for answer before asking the next. Prioritize by impact — scope and core behavior first, edge cases second.

.spec.md Format

---
name: Feature Name
description: Brief description
targets:
  - ../src/path/to/implementation.py
---

# Feature Name

Requirements...

[@test] ../tests/test_something.py

## Error Handling
- Invalid credentials return 401
  [@test] ../tests/test_invalid.py
06

Memory Context

Tessl SDD Tile — Memory & Context

State Storage

File-based. All context lives in:

  • specs/.spec.md files per feature
  • .tessl/ — tile files (skills, rules, docs, scripts, evals)

Spec File Format

.spec.md files with YAML frontmatter:

---
name: Feature Name
description: Brief description
targets:
  - ../src/path/to/implementation.py
  - ../src/related/**/*.py
---

Plus inline [@test] links pointing to test files.

Cross-Session Handoff

Yes — specs persist as .spec.md files. Any session finds them via find specs/ -name "*.spec.md".

Context Loading Protocol

The tile's files are in .tessl/ and are read by the agent as project context. The requirement-gathering skill mandates "Review existing specs" as its first step — this is the explicit session-start memory loading mechanism.

Verification Scripts

Two bash scripts serve as lightweight validators:

  • validate-specs.sh — checks required frontmatter fields
  • check-spec-links.sh — resolves [@test] links and targets glob patterns

Compaction

None. Specs are independently readable files; no compaction mechanism.

Memory Type

File-based (.spec.md files + YAML frontmatter + [@test] links).

Persistence Scope

Project-scoped (all files in specs/ directory).

07

Orchestration

Tessl SDD Tile — Orchestration

Multi-Agent

No. Single-agent workflow.

Orchestration Pattern

Sequential. Requirement gathering → spec authoring → approval → implementation → verification → review.

Execution Mode

Interactive-loop. Agent reads context from .tessl/ and specs/ and follows the methodology.

Isolation Mechanism

None. Code changes in place.

Multi-Model

No. Compatible with any AI tool that reads context.

Consensus Mechanism

None. The stakeholder approval gate is human-driven, not algorithmic.

Auto-Validators

  • scripts/validate-specs.sh — triggered manually or by spec-verification skill
  • scripts/check-spec-links.sh — triggered manually or by spec-verification skill

TDD Enforcement

Implicit. The spec-writer skill requires [@test] links in specs; spec-verification checks that those test files exist. But there is no enforcement preventing code-before-tests at the workflow level — it's guidance, not a state machine.

Git Automation

None.

Cross-Tool Portability

High. Pure context files in .tessl/ — any AI tool that reads project context follows the methodology. No MCP required, no hooks required.

Evaluation Infrastructure

The 9 eval scenarios provide a test suite for verifying the tile's behavioral claims. Run via make eval or tessl eval run . locally. This is unusual — most frameworks don't ship evals.

08

Ui Cli Surface

Tessl SDD Tile — UI & CLI Surface

CLI Binary (Tessl CLI, not shipped in this repo)

  • Name: tessl (from @tessl/cli npm package)
  • Not part of this tile — it's the installer CLI
  • Commands: tessl init, tessl install <tile>, tessl eval run ., tessl skill review

Local UI

None. No web dashboard, TUI, or desktop app.

IDE Integration

Tiles work with Claude Code, Cursor, and any MCP-compatible AI tool via the .tessl/ directory context loading. No special plugin install beyond tessl install.

Observability

  • scripts/validate-specs.sh — spec structure validation report
  • scripts/check-spec-links.sh — link resolution report
  • make eval — run evaluation scenarios locally

CI/CD Integration

The tile ships GitHub Actions workflows (via tesslio/setup-tessl):

  • Lint — validates tile structure on every push/PR
  • Skill review — runs tessl skill review on all skills
  • Version check — ensures tile.json version is bumped on PRs
  • Publish — publishes to Tessl registry on merge to main

Registry

Published to: https://tessl.io/registry/tessl-labs/spec-driven-development Versioned: tile.json v2.0.1

Tile Activation

No special commands needed. After install, include "use spec-driven development" in your prompt:

Create an API for managing user subscriptions. Use spec-driven development.

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.