Skip to content

Concepts ​

Two ways to use it. One task: with the CLAUDE.md snippet every conversation starts the master workflow, which picks a bundled one (bug-fix, coding, new-feature, ...) and hands the agent one prompt at a time; a named one starts with start({ workflow: "bug-fix" }) or by asking. A queue: for many tasks, a queue file plus the batch workflow runs one task workflow per line, several at once, each under a driver agent. A workflow of your own comes from asking the agent (it loads the bundled workflow-authoring skill) or from writing the YAML by hand. Step by step: Getting started.

The vocabulary ​

  • Workflow — a YAML state machine: a name, an initial state and a map of states. Bundled ones live in the plugin, yours in .claude/workflows/ (Workflow YAML).
  • State — one step. A prompt state hands the agent a prompt and lists the transitions it may take; an action state (exec, fetch) runs a command or request by itself and routes on the result (Action states); a terminal state ends the workflow with an outcome.
  • Session — one run of a workflow, with its current state, context and visit counts, persisted as JSON. start() creates it.
  • Transition — a move from the current state to another, named by the agent through transition(); the engine validates it, advances and returns the next prompt.
  • Child session — a state with sub_workflow: pushes a nested workflow as a child session; when it ends the parent continues at on_complete or on_fail. A parent can also spawn child sessions for sub-agents (the task queue does this for each task).

How It Works ​

Agent                       Engine                          Storage
  │                           │                               │
  ├── start() ───────────────►├─ snapshot workflows ─────────►├ session.json
  │◄── initial state prompt ──┤                               │
  │                           │                               │
  ├── transition() ──────────►├─ validate & advance ─────────►├ update JSON
  │◄── new state prompt ──────┤  (push/pop sub-workflows)     │
  │                           │                               │
  ├── transition() ──────────►├─ terminal state? ────────────►├ mark complete
  │◄── done ──────────────────┤  (auto-pop to parent)         │
  1. start() — creates a session, snapshots all workflow definitions, returns the initial state prompt
  2. transition() — validates the transition, advances state, handles sub-workflow push/pop, returns the new prompt
  3. Every mutation is atomically persisted to JSON (temp file + rename + lockfile)
  4. Dashboard visualizes sessions and workflow graphs at localhost:3100
  5. Sub-workflows form a stack: a state with sub_workflow: pushes a nested workflow (max depth 10) and the engine pops it when it completes
  6. Snapshot isolation: workflow definitions are frozen at session start, so a hot-reload never changes a running session
  7. Runtime overlays: modify adds, changes or removes states and transitions of one session without touching the YAML files
  8. The SessionStart hook auto-provisions missing skills and injects the workflow context

Bundled Workflows ​

WorkflowDescription
masterSingle entry point — analyzes task, loads skills, routes to sub-workflows
codingCode writing pipeline: think → delegate → write → review → verify
docsText-only edits (skills, prompts, CLAUDE.md, memory, reports): write → verify — no lint, tests, or reviewer agent
bug-fixStandard bug fix: classify → diagnose → fix → verify
new-featureNew feature implementation with planning and testing
debuggingDiagnose first, fix never (until diagnosed)
code-reviewCode review with per-file deep analysis
exploreCodebase exploration — understand structure, trace code, find patterns
investigateResolve unknowns before deciding on action
planningExplore, design plan (tasks and steps), record workflow context
testingTesting verification — unit tests first, then integration
web-researchCheck existing knowledge, then delegate to web subagents
reflectionSelf-reflection after significant tasks — evaluate, classify, act
subagentLightweight routing for sub-agents (no chat/plan/reflect)
file-codePer-file coding — spawned by coding/bug-fix for each file
file-reviewPer-file deep review — spawned by code-review for each file
lint-reviewTrivial-diff review — engine-run lint, act on findings, one intent re-read
batchLong-running task queue: the engine admits lines into the window (after: / touches: / owner: / pause), one batch-task child per task, one fresh-eyes review of the combined diff
batch-taskOne queued task, run by a haiku driver (driver:): difficulty → model/effort (model_table) → worktree → worker → reviewer chosen by the diff → merge + land_test under the repo's land lock → mark done → cleanup
review-pushReview uncommitted changes, then commit and push to GitHub
github-initInitialize git repo and create private GitHub repository

The coding workflow, drawn by the dashboard's own renderer (click a state to read its prompt; the landing page draws every bundled workflow):

Loading the workflows…

Bundled Skills ​

Skills are reusable knowledge modules loaded by workflows via Skill(). Auto-provisioned to ~/.claude/skills/ on first run if missing. Edit your local copy to override the bundled version — the hook never overwrites existing files.

Methodology

SkillDescription
preferencesTemplate for personal coding preferences (fill in your own)
architectureSimplicity-first architecture decisions
task-delegationWhen and how to delegate to subagents
debuggingDebugging meta-patterns — what to do when fixes don't stick
coding-skill-selectorSelect and load coding skills by file extensions and domains
workflow-authoringReference for creating workflows with exec/fetch action states

Languages

SkillDescription
lang-haxeHaxe language gotchas (incl. macros, null safety, hxcpp)
lang-pythonPython language gotchas
lang-as3AS3 / AIR 51 language gotchas

Domains

SkillDescription
domain-yoloYOLO object detection model selection
domain-pixiPixi.js v8 masking and graphics gotchas
domain-reidPerson re-identification ML gotchas
domain-gamedevGame dev precision and physics gotchas
domain-ponyPony (Haxe cross-library) gotchas
domain-uiUI component architecture — ownership, state, events

Platforms & Tooling

SkillDescription
target-openfl-nativeOpenFL/hxcpp native target gotchas
build-cmakeCMake build system gotchas
ci-github-actionsGitHub Actions workflow gotchas
aws-lambdaAWS Lambda .NET deployment gotchas
mcp-setupMCP server setup and troubleshooting
claude-code-configClaude Code configuration gotchas
hxqWhen and how to use hxq for structural Haxe navigation
browser-verifyBrowser-automation verification gotchas — stale captures, caches, headless limits
debug-bridge-scaffoldMeta-skill for creating debug bridges for new technologies
ide-zedZed IDE integration rules

Utility

SkillDescription
web-readingFetch web content via subagents
skill-managerCreate, install, update, optimize skills
cleanupClean .claude directory data

MCP Tools ​

All tools are registered under the wf server. Full tool prefix: mcp__plugin_workflow_wf__.

ToolDescriptionKey Parameters
listList all available workflow definitions—
startStart a workflow, return initial promptworkflow, actor, parent_session_id, cwd (absolute existing dir — a sub-agent's worktree), priority (low/normal/high/urgent; default: the parent's level, else normal), context (string map the session starts with; not cwd), reply: "id" (answer only SESSION: <id> @ <state>, no prompt or rules), force: "<reason>" (a second root; without parent_session_id a start in a process that already has an active root is refused, naming the root by workflow and state, never its id — a sub-agent never gets a root) — a workflow with driver: ends the answer with the driver's Agent call
statusGet current state, stack, transitions, context (values cut to 200 chars), history — of any session, incl. a finished child; with key, only that context value, wholesession_id, key
transitionAdvance to next state (auto push/pop sub-workflows). A call with a caller_session_id outside the caller's subtree is refused unless force: true with a reason; a transition naming no caller_session_id is not judged (the engine's own prompts step other sessions without one, and a step ends no one); the guard stops an agent that names itselfsession_id, transition, caller_session_id, force + reason
context_setSave key-value data in session contextsession_id, key, value
modifyRuntime overlay — add/change/remove states and transitionssession_id, add_state, add_transition
createCreate new workflow definition (saves YAML)name, definition, scope
deleteDelete a workflow definitionname, scope
abortAbort workflow, pop all stack frames (its active descendants end with it; the cascade is logged to stderr with the caller and the session count). Refused for a root or a session with active descendants unless caller_session_id is the target or an ancestor of it, or force: true with a reasonsession_id, caller_session_id, force, reason
sessionsList all sessions (active first); [STALE: …] marks one whose state saw no engine call past its stale_afterall
set_prioritySet the priority level of a session and its descendants; re-rank their waiting pool entries (no preemption)session_id, level
pool_statusThe machine-wide pool: one line per lease and waiter (as wf-run --status)—
resumeContinue a suspended session in this process (and own its sub-tree); finishes an exec state it stopped in; lists the sub-agents to wakesession_id
suspendedSuspended sessions of this project (or all)all
link_agentRecord the Agent-tool id of the sub-agent driving a child session (named by the parent's resume) and the parent's state + visit (the parent's status marks it current or stale); every agent linked stays on the session (linked_agents) and every call is recorded with its time, the parent's state and that state's stage (agent_links) for the ledger's spend, in total and per agent and stage (spend.by_agent)session_id, agent_id
queue_nextAdmit the next tasks of a YAML task queue and set them running (§ Task queue)queue, file, dry_run, explain
queue_markMove one task's status (running / done / failed / released / promoted / shelved; retry restarts a failed task)queue, file, id, to, note, retry, force
queue_addAdd a task (pending or backlog) to a queue, checked as a pick reads itqueue, file, task, after_id, before_id
queue_editSet / remove a task's fields, append a note to its notes:queue, file, id, set, append_note, from
queue_headerSet a queue's batch_size (0 = pause) with its reason, and/or its archive_after_days, exclusive_holdqueue, file, batch_size, reason, archive_after_days, exclusive_hold