Workflow Patterns

Pattern 1: Service mode

The recommended default. Define your tasks, start the service, and let the coordinator handle everything — claiming, spawning, dead agent detection, and cascading unblocked work.

# Define the work
wg add "Refactor auth module" --skill rust
wg add "Update tests" --after refactor-auth-module --skill testing
wg add "Update docs" --after refactor-auth-module --skill docs

# Start the service
wg service start --max-agents 4

# Monitor
wg agents     # who's working on what
wg list       # task status
wg tui        # interactive dashboard

The coordinator continuously polls the graph, picks up ready tasks, and spawns agents. When one task finishes, its dependents become ready and the coordinator picks them up immediately. No manual intervention needed.

Pattern 2: Agent plans, service executes

A top-level AI agent (or human) designs the task graph, then the service handles execution. This separates planning from doing.

# In your CLAUDE.md or system prompt:
#
# Break down this goal into tasks using workgraph:
# 1. Analyze what needs to be done
# 2. Create tasks with `wg add`, linking dependencies with --after
# 3. Start `wg service start` to dispatch work
# 4. Monitor with `wg list` and `wg agents`
# 5. If you discover more work, add it — the service picks it up

The orchestrating agent acts as a thin coordinator — it creates tasks with descriptions, dependencies, and validation criteria, then delegates execution to the service. It never writes code itself.

Pattern 3: Mixed human + AI

Humans claim the tasks that need judgment. The service handles the rest.

# Human claims the design work
wg claim design-api --actor erik

# Start the service — it waits for design to complete
wg service start

# When Erik marks design-api as done, the service
# spawns agents on all downstream tasks automatically
wg done design-api

This works because the dependency graph doesn't distinguish between human and AI actors. A task is either done or it isn't. When it completes, dependents unblock regardless of who did the work.

Human agents can also receive notifications via Matrix, email, or Slack when their tasks become ready.

Pattern 4: Manual mode

For simple cases where you don't need parallel execution or a background service. Work through tasks one at a time:

# See what's available
wg ready

# Claim and work on a task
wg claim set-up-ci-pipeline --actor claude
# ... do the work ...
wg done set-up-ci-pipeline    # unblocks dependents

# Next task
wg ready

Manual mode is useful for solo work, debugging, or when you want full control over task ordering.

Choosing a pattern

Pattern	Best for	Parallelism
Service mode	Fully automated projects, CI/CD-like workflows	Up to max_agents
Agent plans	Complex projects where planning requires reasoning	Up to max_agents
Mixed	Human judgment + AI execution	Up to max_agents
Manual	Solo work, debugging, learning	Sequential

Patterns can be combined. Start in manual mode to prototype a graph, then switch to service mode when the structure is right. Mix human-claimed tasks with service-dispatched agents in the same graph.