create-workflow

Create Workflow — State Machine Designer

Design a YAML workflow that enforces a multi-step process with state transitions, per-state tool restrictions, and permission modes.

When to Use Workflows vs Skills

Use a Skill	Use a Workflow
Repeatable task with steps	Process with enforced stages
Agent follows instructions voluntarily	System enforces what tools are available per stage
No state tracking needed	State tracked across interactions
e.g., "Run a DCF valuation"	e.g., "Plan → Implement → Review → Ship"

Rule of thumb: If the agent must NOT skip a stage or use certain tools before completing a prior stage, use a workflow. If it's guidance the agent follows, use a skill.

Process

Step 1: Understand the Process

Ask one at a time:

1. What process does this workflow enforce?

   • e.g., "Code change: plan → implement → review → verify"
   • e.g., "Research: gather → analyze → validate → present"
   • e.g., "Incident: triage → investigate → remediate → postmortem"

2. What are the stages (states)?

   • List each stage and what happens there
   • What marks a stage as complete (transition condition)?

3. Should tools be restricted per stage?

   • e.g., Planning stage: read-only tools only
   • e.g., Review stage: no file writes
   • e.g., Implementation: all tools available

4. What permission mode per stage?

   • plan — read-only, agent proposes but doesn't act
   • ask — agent asks before each action
   • allow — agent can read/write freely
   • bypass — full autonomy including shell execution

Step 2: Design the State Machine

Map out states and transitions:

[initial] → [state-2] → [state-3] → [done]
              ↑                        |
              └────── (rejected) ──────┘

For each state, define:

• name: Short identifier (snake_case)
• allowed_tools: Tool allowlist (null = all)
• permission_mode: plan | ask | allow | bypass (optional, derived from tools if omitted)
• on_entry: Instructions when entering this state
• on_exit: Cleanup when leaving (optional)
• transitions: List of possible next states with optional conditions