Quick Reference

One-page cheat sheet for MOTH syntax. Print and keep near your keyboard!

Remember: MOTH is a BLUEPRINT, not a specification. Add detail only where ambiguity would cause architectural problems. Target 80% compression.

Syntax Patterns

# Comments

# Full line comment

key:value # Inline comment

[SECTIONS]

[SECTION_NAME]

[SECTION.subsection]

Key-Value

key:value

key:"value:with:colons"

Lists

key:item1;item2;item3

key:[item1;item2;item3]

Objects

key:{k=v;k2=v2}

key:{k=v;nested:{x=y}}

Modality & Relationships

*required_field:type

(optional_field):type

field→table.id # foreign key

Type System

Primitives

string, int, float, bool

uuid, timestamp, jsonb

Collections

[type] - Array

{key:type} - Object

type|type2 - Union

enum[a,b,c] - Enumeration

Status Codes

C - Complete

P - Planned

R - Risk

D - Deferred

X - Deprecated

Common Sections

[SCHEMAS] - Data models with relationships

[API] - Endpoint inventory

[FEATURES] - Requirements to implement

[WORKFLOWS] - State machines for complex flows

[STACK] - Technology stack

[RISKS] - Known issues and mitigations

Schema Example

[SCHEMAS]
users:{
  *id:uuid;
  *email:string;
  (phone):string;
  *role:enum[admin,user,guest];
  *tenant_id→tenants.id;
  settings:jsonb
}

orders:{
  *id:uuid;
  *user_id→users.id;
  *status:enum[pending,paid,shipped];
  *total:float;
  *created_at:timestamp
}

Workflow Example

[WORKFLOWS]
order_lifecycle:{
  initial:pending;
  pending→paid[on:payment_success];
  paid→shipped[on:fulfillment];
  any→cancelled[on:user_cancel,if:not_shipped]
}

Validation Checklist

✓ File starts with header metadata
✓ At least one [SECTION]
✓ Valid key:value syntax
✓ Proper quote escaping
✓ Consistent indentation (2 spaces)
✓ No trailing whitespace