Examples

These examples demonstrate Simplex specifications at varying levels of complexity. Each shows how to describe work for autonomous agents using landmarks.

Minimal Specification

The simplest valid Simplex spec with all required landmarks

FUNCTION: greet(name) → greeting

RULES:
  - return a greeting that includes the name

DONE_WHEN:
  - greeting contains the name
  - greeting is friendly

EXAMPLES:
  ("Alice") → "Hello, Alice!"
  ("Bob") → "Hello, Bob!"

ERRORS:
  - empty name → "Name cannot be empty"

Authentication

User authentication with DATA, READS, NOT_ALLOWED, and UNCERTAIN

DATA: User
  id: string
  name: string
  email: string
  role: "admin" | "member" | "guest"

DATA: AuthResult
  success: boolean
  user: User | null
  error: string | null

FUNCTION: authenticate(email, password) → AuthResult

RULES:
  - look up user by email
  - if user not found, return failure
  - verify password matches stored hash
  - if password invalid, return failure
  - return success with user data

DONE_WHEN:
  - valid credentials return user
  - invalid credentials return error
  - result always has either user or error, never both

EXAMPLES:
  ("alice@example.com", "correct")
    → { success: true, user: User, error: null }
  ("alice@example.com", "wrong")
    → { success: false, user: null, error: "Invalid password" }
  ("unknown@example.com", "any")
    → { success: false, user: null, error: "User not found" }

ERRORS:
  - user not found → "User not found"
  - invalid password → "Invalid password"
  - database unavailable → "Service temporarily unavailable"

READS:
  - Database.users

NOT_ALLOWED:
  - store plaintext passwords
  - log password values
  - return password hashes in responses

UNCERTAIN:
  - if login attempts exceed 5 in 1 minute → flag for rate limiting review
  - if user agent is unrecognized → log warning, proceed with caution

CONSTRAINT: password_security
  passwords are never logged or returned in responses

Shopping Cart

Multiple related functions operating on shared data

DATA: Item
  id: string
  name: string
  price: number
  quantity: number

DATA: Cart
  items: list of Item
  total: number

FUNCTION: add_to_cart(cart, item) → Cart

RULES:
  - if item already in cart, increase quantity
  - otherwise add item to cart
  - recalculate total

DONE_WHEN:
  - item is in cart
  - total reflects all items

EXAMPLES:
  (empty_cart, item_a) → { items: [item_a], total: 10.00 }
  (cart_with_a, item_a) → { items: [item_a(qty:2)], total: 20.00 }
  (cart_with_a, item_b) → { items: [item_a, item_b], total: 25.00 }

ERRORS:
  - invalid item → "Item must have id, name, and price"
  - negative quantity → "Quantity cannot be negative"


FUNCTION: remove_from_cart(cart, item_id) → Cart

RULES:
  - find item by id
  - remove it from cart
  - recalculate total

DONE_WHEN:
  - item no longer in cart
  - total is updated

EXAMPLES:
  (cart_with_a_and_b, "a") → { items: [item_b], total: 15.00 }
  (cart_with_a, "a") → { items: [], total: 0.00 }
  (empty_cart, "a") → { items: [], total: 0.00 }

ERRORS:
  - item not found → return cart unchanged (not an error)


FUNCTION: calculate_total(cart) → number

RULES:
  - sum price × quantity for all items

DONE_WHEN:
  - total is accurate

EXAMPLES:
  (empty_cart) → 0.00
  (cart_with_a) → 10.00
  (cart_with_a_and_b) → 25.00

ERRORS:
  - invalid cart → 0.00

Document Pipeline

Swarm coordination with WRITES, TRIGGERS, and HANDOFF

FUNCTION: extract_text(document_path) → ExtractedContent

RULES:
  - read document from path
  - extract text content preserving structure
  - identify document metadata (title, author, date)

DONE_WHEN:
  - text content is extracted
  - metadata is populated where available

EXAMPLES:
  ("report.pdf") → { text: "...", metadata: { title: "Q4 Report" } }
  ("notes.docx") → { text: "...", metadata: { author: "Jane" } }
  ("empty.pdf") → { text: "", metadata: {} }

ERRORS:
  - file not found → "Document not found: {path}"
  - unsupported format → "Cannot process format: {ext}"
  - any unhandled condition → fail with descriptive message

WRITES:
  - SharedMemory.artifacts["extracted_content"]
  - SharedMemory.status["extraction"] = success | failure

TRIGGERS:
  - SharedMemory.queue["pending_documents"] is not empty
  - SharedMemory.status["extraction"] != "in_progress"

HANDOFF:
  - on success: ExtractedContent ready for summarize_content
  - on failure: error details with document path for retry queue

Evolutionary Specification

Modernizing existing systems with BASELINE and EVAL (v0.4)

DATA: AuthSystem
  session_support: boolean
  jwt_support: boolean
  refresh_rotation: boolean
  rate_limiting: boolean

FUNCTION: modernize_authentication(config) → AuthSystem

BASELINE:
  reference: "session-based auth, commit abc123"
  preserve:
    - POST /login returns { session_id, expires_at }
    - session timeout is 30 minutes
    - existing client SDKs continue to work
  evolve:
    - add JWT token issuance alongside sessions
    - implement refresh token rotation
    - add rate limiting on auth endpoints

RULES:
  - authenticate user credentials against user store
  - issue JWT token with configurable expiration
  - issue refresh token that rotates on each use
  - maintain session-based auth for backward compatibility
  - rate limit failed attempts per IP address

DONE_WHEN:
  - valid credentials produce both session and JWT
  - refresh tokens rotate correctly
  - rate limiting activates after threshold
  - existing session-based clients unaffected

EXAMPLES:
  # Preserved behaviors (regression tests)
  (valid_creds, session_mode)
    → { session_id: "...", expires_at: +30min }
  (invalid_creds, any_mode)
    → { error: "unauthorized" }

  # Evolved capabilities (capability tests)
  (valid_creds, jwt_mode)
    → { token: "...", refresh: "...", expires_at: +1hr }
  (expired_token, valid_refresh)
    → { token: "new...", refresh: "new..." }
  (any_creds, after_rate_limit)
    → { error: "rate limited", retry_after: 60 }

ERRORS:
  - user store unavailable → "auth service unavailable"
  - malformed credentials → "invalid request format"
  - rate limit exceeded → "rate limited, retry after {seconds}"

EVAL:
  preserve: pass^3
  evolve: pass@5
  grading: code

CONSTRAINT: backward_compatibility
  existing v1 API clients must work without modification

Key Observations

Required Landmarks

Every function needs five landmarks: FUNCTION, RULES, DONE_WHEN, EXAMPLES, and ERRORS. The minimal example shows just these with no optional landmarks.

DATA Definitions

DATA blocks are optional. Use them when the shape of inputs or outputs would otherwise be unclear. The authentication example uses DATA to define User and AuthResult types; the minimal example omits them because string inputs and outputs are self-evident.

Example Coverage

Each conditional path in RULES should have at least one example. The add_to_cart function has three examples covering: empty cart, existing item (quantity increase), and new item. This ensures agents understand each branch.

Error Handling

ERRORS is required to prevent silent failures during autonomous execution. At minimum, specify default behavior for unhandled conditions. More complete specs map specific failure modes to specific responses.

Boundaries and Confidence

NOT_ALLOWED establishes explicit boundaries—what the function must never do. UNCERTAIN defines thresholds for when agents should signal low confidence rather than proceeding silently. The authentication example shows both: never log passwords, and flag unusual login patterns for review.

Swarm Coordination

For multi-agent workflows, WRITES declares shared state the function produces, TRIGGERS defines when an agent should pick up work, and HANDOFF describes what the next stage receives. The document pipeline example demonstrates all three, enabling agents to coordinate without central orchestration.

Evolutionary Specifications (v0.4)

When evolving existing systems rather than building greenfield, use BASELINE and EVAL to declare what must be preserved versus what is being evolved.

BASELINE contains three fields: reference (the prior state), preserve (behaviors that must not regress), and evolve (capabilities being added or changed).

EVAL declares how to measure success using two threshold notations: pass^k means all k trials must pass (for regression tests), while pass@k means at least one of k trials must pass (for capability tests). The grading field specifies evaluation approach: code for deterministic comparison, model for LLM-as-judge, or outcome for verifying state changes.

EVAL is required when BASELINE is present. This ensures evolutionary specs always define how preservation and progress are measured.