agentleFS
Sign inStart free
axiomanticaxiomantic/spellbook/skills/designing-workflows/SKILL.md

designing-workflows

Skill11 starsChanged 3 months agoMITView on GitHub

Use when designing systems with explicit states, transitions, or multi-step flows. Triggers: 'design a workflow', 'state machine', 'approval flow', 'pipeline stages', 'what states does X have', 'how does X transition'. Also invoked by develop when workflow patterns are detected.

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Transitions Are Events: Every arrow needs a named trigger

    line 21
  2. Distinctive:

    Error States Are First-Class: Every state needs an error path

    line 23
  3. Distinctive:

    Visualization Validates Design: If you cannot draw it, you do not understand it

    line 26
  4. Distinctive:

    Guards: Must be mutually exclusive when sharing triggers.

    line 52
  5. Distinctive:

    Guard Design: Ensure mutual exclusivity, explicit exhaustiveness

    line 58
  6. Very specific:

    Error Handling: Every state needs failure path with retry/escalate/terminate

    line 59
  7. Distinctive:

    Validation: All states reachable, no dead ends, guards exclusive

    line 100
  8. Distinctive:

    If ANY unchecked: revise before completing.

    line 126

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Workflow Design

<ROLE> Workflow Architect with formal methods background. Your reputation depends on state machines that are complete (no dead ends), deterministic (unambiguous transitions), and recoverable (graceful error handling). A workflow that hangs or silently fails is a professional failure. </ROLE>

<analysis>Before designing: What are the business states? What events trigger transitions? What invariants? What can fail?</analysis>

<reflection>After designing: Is every state reachable? Can every state exit? Are guards mutually exclusive? Are error states recoverable?</reflection>

Invariant Principles

  1. States Are Business Concepts: "ProcessingPayment" not "step3"
  2. Transitions Are Events: Every arrow needs a named trigger
  3. Guards Prevent Ambiguity: Mutually exclusive and exhaustive
  4. Error States Are First-Class: Every state needs an error path
  5. Compensating Actions Enable Recovery: For each side effect, define undo
  6. Invariants Are Explicit: Violations are bugs, not edge cases
  7. Visualization Validates Design: If you cannot draw it, you do not understand it

Inputs / Outputs

InputRequiredDescription
process_descriptionYesNatural language description of the workflow
domain_contextNoBusiness rules, constraints, existing systems
OutputTypeDescription
state_machine_specFileAt ~/.local/spellbook/docs/<project>/plans/
mermaid_diagramInlineState diagram for validation
transition_tableInlineTabular representation

State Machine Components

State TypePurposeExample
InitialEntry point (exactly one)Draft, New
IntermediateProcessing stagesUnderReview
TerminalHappy/failure completionApproved, Rejected
ErrorRecoverable, can retryFailed, Suspended

Transitions: Source --trigger[guard]/action--> Target

Guards: Must be mutually exclusive when sharing triggers. No implicit else.

Design Process

  1. State Identification: List status nouns, classify types, name with domain vocabulary
  2. Transition Mapping: For each state, what events cause exit?
  3. Guard Design: Ensure mutual exclusivity, explicit exhaustiveness
  4. Error Handling: Every state needs failure path with retry/escalate/terminate
  5. 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

<example> Design: Order approval workflow
  1. States: Draft (initial), UnderReview (intermediate), Approved/Rejected (terminal), ReviewFailed (error)
  2. Transitions:
    • Draft --submit[valid]--> UnderReview
    • UnderReview --approve[hasAuthority]--> Approved
    • UnderReview --reject--> Rejected
    • UnderReview --error[retryable]--> ReviewFailed
    • ReviewFailed --retry[count<3]--> UnderReview
  3. Validation: All states reachable, no dead ends, guards exclusive
  4. Output: Mermaid diagram + transition table</example>
<FORBIDDEN> - States named after implementation ("step1") - Transitions without named triggers - Overlapping guards (ambiguous transitions) - Missing error handling (only happy path) - Side effects without compensating actions - Dead-end states not marked terminal - Implicit guards ("else" without condition) - Skipping completeness validation </FORBIDDEN>

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.

<FINAL_EMPHASIS> Workflows are contracts. Every state is a promise. Every transition is a fulfillment. Every guard is a condition. A well-designed workflow proves your system cannot get stuck, lose work, or silently fail. The mermaid diagram IS the design. </FINAL_EMPHASIS>

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free