Simplex

01 / Overview

Specify what you want, not the implementation.

Simplex is a semi-structured specification for work assigned to autonomous agents.

A Simplex specification defines required behavior, completion criteria, examples, and error responses. The autonomous agent selects the implementation.

Uppercase landmarks organize the specification. Each landmark ends when the next one begins.

02 / Quick start

Write the smallest useful specification.

Every Simplex specification needs one function. Each function needs rules, completion criteria, examples, and error responses.

minimal.simplex Simplex 0.6

FUNCTION: add(a, b) → sum

RULES:
  - return the sum of a and b

DONE_WHEN:
  - the returned value equals a + b

EXAMPLES:
  - (2, 3) → 5

ERRORS:
  - any unhandled condition → fail with descriptive message

03 / Landmarks

Simplex defines 18 landmarks.

Five landmarks are always required. EVAL is required when BASELINE exists. All other landmarks are optional.

Always required

Landmark	Role
`FUNCTION`	Introduces one unit of work, its inputs, and its return type.
`RULES`	States observable behavior. Rules describe outcomes, not implementation steps.
`DONE_WHEN`	Defines observable completion criteria.
`EXAMPLES`	Provides input-output pairs or other observable evidence. Every conditional path needs an example.
`ERRORS`	Maps known failure conditions to responses and defines default failure behavior.

Conditionally required

Landmark	Role
`EVAL`	Defines grading and repeat thresholds. It is required when BASELINE exists.

Optional structural landmarks

Landmark	Role
`SIMPLEX`	Declares the language version. The declaration can appear only once.
`DATA`	Defines named data shapes. A referenced return type must conform to its DATA schema.
`CONSTRAINT`	States an invariant that applies throughout the specification.
`BASELINE`	Defines the prior state, preserved behavior, and planned evolution.

Optional function landmarks

Landmark	Role
`COVERS`	Links examples to requirements and completion criteria.
`READS`	Lists shared memory that the function consumes.
`WRITES`	Lists shared memory that the function produces.
`TRIGGERS`	States when an autonomous agent should select the work.
`NOT_ALLOWED`	Defines actions or outcomes that the function must avoid.
`HANDOFF`	Defines what the next stage receives after success or failure.
`UNCERTAIN`	Defines conditions that require a low-confidence signal or clarification.
`DETERMINISM`	Defines expected output consistency for repeated calls with identical inputs.

04 / Traceability

Identifiers connect examples to requirements.

Identifiers label requirements, completion criteria, examples, errors, and constraints. COVERS links an example to the items that it demonstrates.

Declared coverage Optional

RULES:
  - [R1] return the sum of a and b

DONE_WHEN:
  - [D1] the returned value equals a + b

EXAMPLES:
  - [E1] value: (2, 3) → 5

COVERS:
  - E1 → R1, D1

05 / Authoring method

Start with behavior that a reviewer can observe.

01
Write the function signature and concrete examples.
02
Describe observable behavior in RULES. Do not prescribe implementation steps.
03
Make each DONE_WHEN criterion externally checkable.
04
State expected responses to known failures in ERRORS.
05
Add optional landmarks only when they clarify a requirement.
06
Split a specification when a function or rule set becomes difficult to understand.

06 / Linter

Check specification structure.

Repository root Shell

make test
make build
./build/simplex-lint examples/minimal.simplex

07 / Resources

Reference material.

Normative specification Quick start Examples Linter design Changelog