tomevault-io Workflow Design
Before designing: What are the business states? What events trigger transitions? What invariants? What can fail?
After designing: Is every state reachable? Can every state exit? Are guards mutually exclusive? Are error states recoverable?
Invariant Principles
- States Are Business Concepts: "ProcessingPayment" not "step3"
- Transitions Are Events: Every arrow needs a named trigger
- Guards Prevent Ambiguity: Mutually exclusive and exhaustive
- Error States Are First-Class: Every state needs an error path
- Compensating Actions Enable Recovery: For each side effect, define undo
- Invariants Are Explicit: Violations are bugs, not edge cases
- Visualization Validates Design: If you cannot draw it, you do not understand it
Inputs / Outputs
| Input | Required | Description |
|---|---|---|
process_description |
Yes | Natural language description of the workflow |
domain_context |
No | Business rules, constraints, existing systems |
| Output | Type | Description |
|---|---|---|
state_machine_spec |
File | At ~/.local/spellbook/docs/<project>/plans/ |
mermaid_diagram |
Inline | State diagram for validation |
transition_table |
Inline | Tabular representation |
State Machine Components
| State Type | Purpose | Example |
|---|---|---|
| Initial | Entry point (exactly one) | Draft, New |
| Intermediate | Processing stages | UnderReview |
| Terminal | Happy/failure completion | Approved, Rejected |
| Error | Recoverable, can retry | Failed, Suspended |
Transitions: Source --trigger[guard]/action--> Target
Guards: Must be mutually exclusive when sharing triggers. No implicit else.
Design Process
- State Identification: List status nouns, classify types, name with domain vocabulary
- Transition Mapping: For each state, what events cause exit?
- Guard Design: Ensure mutual exclusivity, explicit exhaustiveness
- Error Handling: Every state needs failure path with retry/escalate/terminate
- Validation: Reachable, no dead ends, deterministic
Visualization
stateDiagram-v2
[*] --> Draft
Draft --> UnderReview: submit [isValid]
Draft --> Draft: submit [!isValid]
UnderReview --> Approved: approve
UnderReview --> Rejected: reject
Approved --> [*]
Rejected --> [*]
Workflow Patterns
Saga Pattern: Side effects + compensating actions in reverse order on failure.
Step 1: reserveInventory() | Compensate: releaseInventory()
Step 2: chargePayment() | Compensate: refundPayment()
On failure at N: Execute compensations N-1 through 1
Token-Based Enforcement: Tokens validate allowed transitions, prevent stage skipping.
Checkpoint/Resume: Load checkpoint, restore state, re-enter at saved stage.
Example
- States: Draft (initial), UnderReview (intermediate), Approved/Rejected (terminal), ReviewFailed (error)
- Transitions:
- Draft --submit[valid]--> UnderReview
- UnderReview --approve[hasAuthority]--> Approved
- UnderReview --reject--> Rejected
- UnderReview --error[retryable]--> ReviewFailed
- ReviewFailed --retry[count<3]--> UnderReview
- Validation: All states reachable, no dead ends, guards exclusive
- Output: Mermaid diagram + transition table
Self-Check
- States use business domain vocabulary
- Every transition has named trigger
- Guards mutually exclusive and exhaustive
- Every non-terminal state has exit
- Error states with retry/escalate paths
- Side effects have compensating actions
- Mermaid diagram renders correctly
- Completeness validated
If ANY unchecked: revise before completing.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.