Machina Authoring

Machina Machine Authoring

Guidance for writing state-machine definitions that open cleanly in the Machina simulator and score well against its compliance scorer.

Glossary

Use these terms consistently — in prompts, output, and code comments:

Minimal viable machine

Every state machine definition needs at minimum: id, non-empty states, initial resolving to a state key, and every transition target pointing at an existing state key.

{
  "id": "order-fulfillment",
  "name": "Order Fulfillment",
  "version": "1.0.0",
  "spec_version": "3.0.0",
  "initial": "pending",
  "context": { "attempts": 0 },
  "scenarios": [
    { "id": "default", "label": "Default", "initial": "pending", "interface": "API" }
  ],
  "states": {
    "pending": {
      "description": "Awaiting payment confirmation.",
      "on": {
        "PAY": { "target": "paid", "actions": [{ "type": "assign", "key": "attempts", "value": 0 }] },
        "RETRY_PAY": { "target": "pending", "guard": { "type": "compare", "key": "attempts", "op": "lt", "value": 3 }, "actions": [{ "type": "increment", "key": "attempts" }] }
      }
    },
    "paid": { "description": "Payment confirmed.", "on": { "SHIP": { "target": "shipped" } } },
    "shipped": { "type": "final", "description": "Order delivered to carrier." }
  }
}

Authoring workflow

1. Read references/schema-spec.md — full field reference, naming conventions, guard/action semantics.
2. Model states first: identify every distinct status, mark true final states "type": "final" explicitly (never rely on implicit finals).
3. Wire events with declarative objects only — guards {type:"compare",…}, actions {type:"increment"/"assign",…}. Never embed code strings; the format must stay shareable and safe to ingest.
4. Add scenarios[] entry points ({id, label, initial, interface ∈ "UI"|"API"}) — one per meaningful way the workflow starts.
5. If any path can loop (retry, rework), add a genuine counter in context (retry/attempt naming) and gate the looping transition with a compare lt guard against it — this is the only pattern the compliance scorer recognizes as cycle protection.
6. Give every state a real, human description — placeholder text is auto-detectable (generated: true) and reads as a gap.
7. Validate & score — use the bundled deterministic engine (see below) or open in Machina: validate → iterate → target ≥90 ("Excellent") via score --text.
   • Gaps flagged auto can be applied deterministically with the script's apply (or "Generate missing" in-app).
   • Gaps flagged review need your judgment: missing transitions, convention renames, event/state naming, unreachable states. Fix these by hand — see references/machine-quality.md for what each check demands.

Hard rules

• Declare "spec_version": "3.0.0" explicitly so scoring never assumes latest silently.
• Event names UPPER_SNAKE; state keys kebab-case.
• Guard value may be a literal number/string or a context-key name (resolved then numeric-coerced).
• Context paths support dotted notation ("payment.attempts").
• Terminal = type:"final" or no outgoing transitions — prefer an explicit final state.

Deterministic tooling — use the bundled script

All deterministic authoring logic from the Machina simulator (validation, the 23-check compliance scorer, gap analysis, autofill patching, scenario generation, cycle detection, coverage building) is bundled as a standalone CLI. Run it instead of re-deriving logic or loading simulator source:

# From workspace root; python3 on Linux/WSL
python3 skills/machina-authoring/scripts/machine-validator.py <command> <machine.json> [options]

Typical authoring loop: validate → iterate → score --text until ≥90 → gaps for remaining auto-fillable items → apply (or hand-fix review items) → final score.

Known divergence (deliberate): the simulator source's check-inclusion filter (specRank(since) <= specRank(target) over newest-first ranks) inverts v1/v2 inclusion versus §14's documented model. The ported script implements the documented semantics (all 17 checks at v2.0.0, weight = 100). When editing the simulator itself, follow the machina-simulator extension's canonical maintenance docs and keep this divergence in mind.

Compliance boundary — what the scorer does and does not verify

The scorer analyzes the machine declaration only; it never executes anything:

Consequences to teach authors and consumers alike:

• "Score 100 / Excellent" means declaration-sound, not runtime-sound. A machine can score 100 while a tool's script fails in practice — the scorer never runs it.
• The scorer never executes checker scripts. Only the driver actually runs them; see the companion machina-driving skill's "Trust boundary" for where runtime verification happens.
• tools-exist is informational (weight 0): a dangling cmd reports a warn/review gap without lowering the score, because the scorer has no execution context. When the machine file is scored from disk (score <file>), its machine-relative paths are stat'd; in in-memory or workspace-copied contexts with no resolvable directory the check passes trivially.
• validate + --blocking findings are the soundness gate; the semantic checks above are quality guidance.

Reference map (load on demand)

Naming discipline in generated output

When authoring definitions or writing about them: say "state machine" or "machine definition" (never bare "machine"), qualify "Machina simulator" vs "Machina schema spec", and use "final state", "compliance scorer", and "gap (auto/review)" per the glossary. Field-level vocabulary (guard, action, event, transition, context, scenario) is already industry-standard — keep it verbatim.