Workflow Runs
Learn how the pieces fit together when creating a workflow run.
New to workflows? Start with How It Works to understand specs and workflows first.
What is a Workflow Run?
A workflow run is a single execution of a workflow. When you create a workflow run, you're asking agentcmd to:
- Take a spec (what to build)
- Execute a workflow (how to build it)
- Make changes in a git workspace (where to build it)
The workflow run ties these three pieces together.
When you create a workflow run, the system determines which workflow to execute based on spec type:
- Feature spec →
implement-feature.ts - Bug spec →
fix-bug.ts - Issue spec →
resolve-issue.ts
The system looks for these files in .agent/workflows/definitions/. If the workflow doesn't exist, you'll see an error.
Creating a Workflow Run
When you create a workflow run, you provide two inputs:
Spec
The spec defines what needs to be built. There are three ways to provide it:
| Method | What Happens | Use When |
|---|---|---|
| Select File | Select existing spec from .agent/specs/ (see Specs) | You already have a spec ready |
| From Planning Session | AI analyzes planning session transcript → generates spec → executes workflow | You've had a planning discussion and want to proceed |
| Write Custom | Write markdown → AI generates full spec → executes workflow | You have clear requirements and want quick implementation |
Example "Write Custom" input:
# Add CSV Export
Add export to CSV button on users table.
Include all visible columns and respect filters.All three methods create a spec that drives the workflow.
Git Workspace
The git workspace determines where changes happen.
Branch
Creates a new branch for the work.
- Isolated from current branch
- Easy to review and rollback
- Requires branch switching
Best for: Most workflows
Worktree
Creates a worktree in separate directory.
- No branch switching
- Run multiple workflows simultaneously
- Requires cleanup
Best for: Concurrent workflows
Stay
Works directly in your current branch.
- No overhead
- Changes mix with your work
- Hard to separate AI changes
Best for: Quick fixes
Execution Lifecycle
When you trigger a workflow run, here's what happens:
Flow:
- Create Run - User selects spec + workspace in UI
- Trigger - System sends event to Inngest
- Queue - Inngest queues the workflow function
- Execute - Steps run sequentially, each checkpointed
- Update - UI shows live progress via WebSocket
- Complete - Success/failure recorded, artifacts saved
Real-Time Updates
WebSocket events keep the UI in sync:
- Step start/complete - Timeline updates
- Output streaming - Logs appear live
- Annotations - Progress markers
- Artifacts - Files/images uploaded
This means you can watch workflows execute in real-time, even from your phone (see Access Anywhere).
Putting It Together
When you create a workflow run:
- Spec defines what to build (from file, planning, or markdown)
- Spec type determines the slash command to execute
- Git workspace determines where changes happen
- Workflow executes, making commits in the chosen workspace
Example:
Planning session "OAuth Implementation" + Feature spec + Branch mode
Result:
- Generates feature spec from planning
- Executes
implement-feature.ts - Creates branch, commits changes, returns to original branch
Next Steps
- Workflow Definitions - Learn how to write workflows
- Spec-Driven Development - Spec structure and usage