Spec syntax

Tessl Spec Format reference

👉 Closed beta notice

The full framework is currently part of Tessl’s closed beta program. You can request access here.

The Tessl spec format is a Markdown-like specification format used to structure key information about software modules. Specs serve as the primary artifact for code generation in spec-driven development (SDD).

Spec file names

• Spec files use the extension .spec.md

• Standard structure: specs/{project-name}/{spec-name}.spec.md

Spec file structure

Required sections

1. Title/Name: The module name and brief overview

2. Capabilities: Core functionality with optional test definitions

3. Target: At least one @generate or @describe link

4. API: Interface definition in a { .api } code block

Optional sections

1. Dependencies: External requirements with @use links

2. Implementation Details: Marked with { .impl }

Complete Example

# String Reverser

Reverses strings with optional delimiter support for block-wise reversal.

## Target

[@generate](../src/string-reverser/index.ts)

## Capabilities

### Basic String Reversal { .locked }

Core functionality for reversing any string while preserving case and whitespace.

- "hello" becomes "olleh" [@test](../test/string-reverser/basic.test.ts) { .locked }
- "Hello World!" becomes "!dlroW olleH" [@test](../test/string-reverser/basic.test.ts) { .locked }

### Delimiter-based Reversal

Reverses text within delimiter boundaries, preserving block order.

- ("hello world", " ") becomes "olleh dlrow" [@test](../test/string-reverser/delimiter.test.ts)
- ("a,b,c", ",") becomes "a,b,c" [@test](../test/string-reverser/delimiter.test.ts) { .impl }

### Performance Characteristics { .impl }

- Uses single-pass algorithm for efficiency [@test](../test/string-reverser/performance.test.ts) { .impl }
- Memory usage remains constant [@test](../test/string-reverser/performance.test.ts) { .impl }

## API

```typescript { .api }
export declare function reverseString(
  input: string,
  delimiter?: string,
): string;
```

## Dependencies

### String Utilities

Provides helper functions for string manipulation.
[@use](./utilities/string-helpers.spec.md)

### Performance Testing

External library for benchmarking string operations.
[@use](benchmark)

Target Links

@generate

• Syntax: [@generate](./relative/path/to/code/file)

• Purpose: Links to a code file that will be AI-generated from this spec

• Usage: For projects where code is generated from specs and can be updated at any time

• Example: [@generate](../src/throttle/index.ts)

@describe

• Syntax: [@describe](./relative/path/to/code/file)

• Purpose: Links to an existing code file that this spec describes

• Usage: For incremental development where the spec wraps existing code

• Example: [@describe](./existing/code/file.ts)

Test Links

@test

• Syntax: [@test](./relative/path/to/test/file)

• Purpose: Links test definitions to their corresponding test implementation files

• Usage: Must follow specific test definitions that precisely describe the test, including where possible exact inputs and outputs

• Example: - "hello" becomes "olleh" [@test](../../test/reverser/reverse_string.test.ts)

Dependency Links

@use

• Syntax: [@use](dependency-target)

• Purpose: Declares dependencies on other modules, files, or external libraries

• Types:

  • Local spec dependency: [@use](./relative/path/to/dependency-spec)

  • Code file dependency: [@use](./relative/path/to/code-file)

  • External package: [@use](package-name)

• Example: [@use](jsonc-parser)

• Usage: Each dependency should describe what is expected and include the appropriate @use link

Dependency Types

Local spec dependency: Links to another spec in the project

## String Utilities

Provides string manipulation functions for text processing.
[@use](./utilities/string-utils.spec.md)

Code file dependency: Links to existing code files

## Configuration Loading

Requires access to existing configuration parser.
[@use](./src/config/parser.ts)

External package: References npm packages or external libraries

## JSON Processing

Uses JSONC parser for configuration file handling.
[@use](jsonc-parser)

API Definition

{ .api }

• Syntax: { .api } tag on a code block with language identifier

• Purpose: Defines the module's public interface that code and tests must conform to

• Usage: Every spec must include an API block defining all public functions, types, and parameters

• Requirements: Must match project coding standards and be consistent with language configuration

• Example:

```typescript { .api }
export declare function reverseString(
  input: string,
  delimiter?: string,
): string;
```

Content Tags

Content tags control the priority and editing behavior of spec elements. They help organize test cases and capabilities by importance and stability.

Tag Rules

• By default, content is untagged and considered draft

• Tags applied to a section apply to all tests in that section

• Tests must not have more than one tag type

• Test files must not mix test kinds

• Locked content must never be edited unless explicitly requested

Untagged (Default)

Standard content that can be modified during development as necessary.

• Priority: Medium priority, can be changed as the spec is refined

• Usage: Default behavior, no annotation required

• Example: - "hello" becomes "olleh" [@test](./test/file.ts)

{ .locked }

Core functional requirements that should remain stable over time. Applied after user review and confirmation.

• Priority: High priority, represents confirmed essential behavior

• Usage: Applied to individual tests or section headers

• Example: - "hello" becomes "olleh" [@test](./test/file.ts) { .locked }

{ .impl }

Implementation details inferred by AI rather than explicitly specified by users. Lower priority and can be changed more freely.

• Priority: Lower priority, can be modified if user requirements change

• Usage: Applied to tests, capabilities, or sections covering implementation details

• Special behavior: Test files for .impl elements get _impl suffix

• Example: - "Hello" becomes "olleH" [@test](./test/file.ts) { .impl }