Example specs

How Tessl's specification documents are formatted, with some examples.

👉 Closed beta notice

Tessl framework is in private beta. Join our community to be updated on our future product releases.

[Is any of this reusable ? Should cover usage vs steering maybe?]

Specifications (specs) are markdown documents that define the requirements and behavior of software modules in Tessl's AI Native Development approach. They serve as structured memory for what your code is supposed to do, and Tessl uses them to generate both implementation code and tests. They have a .spec.md file extension.

A spec describes:

• Module requirements & API

• Test cases to verify the module was implemented correctly

• Dependencies, if any

• Links to generated code & test files

You can learn more about the syntax of specs here: Spec syntax

---

[editor note]: this is framework, we should use usage specsbelow. Maybe even talk tssl generated vs private

Minimal specification example

An absolutely minimal specification document might look like this:

- It adds two numbers together

[@generate](./src/main.py)

More detailed specification example

A slightly more complete specification document for the above might look like this

# Big Math

A simple math library with Big Int support

```ts { .api }
export function add(a: number, b: number): number;
export function subtract(a: number, b: number): number;
```
[@generate](./src/index.ts)

# Addition

- It adds two numbers together 
  [@test](../tests/add.test.ts)
- It throws an exception when adding `NaN` 
  [@test](../tests/add_nan.test.ts)
- It returns `Infinity` when adding `Infinity` 
  [@test](../tests/add_inf.test.ts)

# Subtraction

- It subtracts a number from another number 
  [@test](../tests/subtract.test.ts)
- It throws an exception when subtracting `NaN` 
  [@test](../tests/subtract_nan.test.ts)
- It returns `-Infinity` when subtracting `Infinity` 
  [@test](../tests/sub_inf.test.ts)
- It returns `NaN` when subtracting `Infinity` from `Infinity` 
  [@test](../tests/sub_inf_nan.test.ts)

# Dependencies

## big-int

Provides Big Int support

[@use](./big-int.spec.md)

# Style requirements

The guidelines in the [externally published library standards](path/to/some/other/text/file) document should be observed.

The hierarchy is decided by the author, with no requirement to use specific words or headings.

Context is inferred from this hierarchy. The example above translates to:

Big Math
├── Addition
├── Subtraction
├── API
├── Dependencies
|  └── big-int
└── Style requirements

This example also shows three special link types:

• [@generate]: A code file to be created by tessl build

• [@test]: A test file to be created by tessl build-tests

• [@use]: A dependency (spec file, code file, or package name) that should be used during generation.

It also shows a regular markdown link, which will be loaded and referenced by all of Tessl's tools while generating.