Quick Start

A Simplex specification describes what a function should do using landmarks.

A Minimal Specification

Here is a complete, minimal Simplex specification. It uses all five required landmarks to describe a single function:

View Specification
simplex 
FUNCTION: add(a, b) → sum

RULES:
  - return the sum of a and b

DONE_WHEN:
  - result equals a + b

EXAMPLES:
  (2, 3) → 5
  (0, 0) → 0

ERRORS:
  - non-numeric input → "Inputs must be numbers"

Required Landmarks

Every function needs these five sections:

FUNCTION Signature and return type
RULES What the function does
DONE_WHEN Success criteria
EXAMPLES Input/output pairs
ERRORS Failure cases

A minimal valid spec consists of a function with rules, completion criteria, examples, and error handling. Optional landmarks (DATA, CONSTRAINT, BASELINE, EVAL, READS, WRITES, TRIGGERS, NOT_ALLOWED, HANDOFF, UNCERTAIN, DETERMINISM) add precision when needed, but their absence does not invalidate a spec. See the full specification for details on all sixteen landmarks.

Validate with the Linter

Use the Simplex linter to check that your specification meets structural and semantic requirements:

bash 
cd lint
make build
./bin/simplex-lint ../examples/minimal.simplex

The linter enforces the "enforced simplicity" pillar through concrete limits and checks. A spec that passes linting has met the structural and semantic requirements for validity.

Writing Tips

Guidance derived from the specification's recommended workflow:

1

Start with the function signature and examples

The examples force clarity about inputs and outputs before you describe behavior. Many specification errors become obvious when you try to write concrete examples.

2

Write rules as behavior, not implementation

Describe what should be true of the output, not how to compute it. If you catch yourself writing "loop through" or "create a variable," step back.

3

Make completion criteria observable

DONE_WHEN criteria should be observable from outside the function. "Internal data structure is consistent" is not observable. "Output contains no duplicates" is observable.

4

Specify error handling explicitly

At minimum, specify that unhandled conditions fail with descriptive messages. For functions with known failure modes, map specific conditions to specific responses.

5

Decompose when it gets unwieldy

Multiple simple specs are better than one complex spec. If the linter flags complexity errors, that is a signal to break the work into smaller pieces.

Assisted Generation

For assisted specification generation, you can try the experimental planner. It provides an interactive dialogue to help draft Simplex specifications. Manual writing remains the primary approach; the planner is an optional aid for exploring the format.

Next Steps

Full Specification Examples GitHub