ReddRadar
Agent skill
designing-workflows
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.
Install this agent skill to your Project
npx add-skill https://github.com/axiomantic/spellbook/tree/main/skills/designing-workflows
SKILL.md
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.
<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>
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
axiomantic/spellbook
spellbook-auditing
Meta-audit skill for spellbook development. Spawns parallel subagents to factcheck docs, optimize instructions, find token savings, and identify MCP candidates. Produces actionable report.
axiomantic/spellbook
documentation-updates
Use after modifying library skills, library commands, or agents to ensure CHANGELOG, README, and docs are updated
axiomantic/spellbook
project-encyclopedia
[DEPRECATED] Use project-level AGENTS.md files instead. Previously used for first-session codebase onboarding and persistent glossary creation.
axiomantic/spellbook
reviewing-impl-plans
Use when reviewing implementation plans before execution. Triggers: 'is this plan solid', 'review the plan', 'check before I start building', 'anything missing from this plan', 'will this plan work', 'audit the implementation plan'. NOT for: reviewing design documents (use reviewing-design-docs) or creating plans (use writing-plans).
axiomantic/spellbook
session-resume
Session resume protocol and session repairs handling. Loaded when spellbook_session_init returns resume_available: true, or when session_init returns a repairs array. Triggers: 'resume', 'continue', 'where were we', session resume, session repairs.
axiomantic/spellbook
brainstorming
Use when exploring design approaches, generating ideas, or making architectural decisions. Triggers: 'explore options', 'what are the tradeoffs', 'how should I approach', 'let's think through', 'sketch out an approach', 'I need ideas for', 'how would you structure', 'what are my options'. Also invoked by develop when design decisions are needed.
Didn't find tool you were looking for?