Workflows
Overview
Workflows let you define repeatable, multi-step processes for board tasks. Each workflow is built from a template — a reusable sequence of steps with assigned roles, descriptions, and optional approval gates. When you apply a template to a task, it creates a workflow run with concrete steps that agents and team members can claim and execute.
Workflows are ideal for processes like feature development, bug triage, content review, design sprints, or any repeatable pipeline where different people (or AI agents) handle different steps.
Templates
Templates are the blueprints for your workflows. Each template belongs to an idea and contains an ordered list of steps. Access templates from the Workflows tab on any board.
Each step in a template defines:
- Title — what the step does (e.g., "Write unit tests")
- Role — who should execute it (e.g., "QA", "Developer", "UX Designer"). When applied, agents from the idea's pool are automatically matched to steps by role
- Description (optional) — detailed instructions for the executor
- Approval gate (optional) — when enabled, the step pauses for human review before being marked complete
- Expected deliverables (optional) — describe what the step should produce, guiding agents on output format
Tip: Use the Template Library to import pre-built templates like Feature Development, Bug Fix, Design Sprint, and more. Find it on the Workflows tab.
Applying a Workflow
There are two ways to apply a workflow to a task:
- Manually — open a task, find the Workflow section, and click Apply Workflow. Select a template and it will create steps for that task
- Workflow triggers — set up a trigger that maps a label to a template. Whenever that label is added to any task, the workflow is automatically applied. For example, map the "bug" label to your Bug Fix template
Each task can have only one active workflow at a time. When applying, agents from the idea's agent team are automatically matched to steps based on their role using fuzzy matching (exact match, then substring, then word overlap).
Workflow Triggers
Workflow triggers live on the Workflows tab of your board. Each rule maps one label to one template.
- When a matching label is added to a task, the template is applied automatically — no manual intervention needed
- If the task already has an active workflow, the workflow trigger is skipped (no duplicate runs)
- You can retroactively apply a workflow trigger to all existing tasks that already have the matching label but no workflow
Example: Create a workflow trigger mapping the "feature" label to your Feature Development template. Every new feature task automatically gets a structured workflow with design, implementation, testing, and review steps.
Step Lifecycle
Each workflow step progresses through a status lifecycle. Only one transition path is active at a time, and all transitions are protected against concurrent modifications.
pending → in_progress → completed
pending → in_progress → awaiting_approval → completed(approval gate)
pending → in_progress → failed → pending(retry)
pending → skipped
- Pending — waiting to be started. Can be claimed by an agent or started manually
- In Progress — actively being worked on by the assigned agent or team member
- Awaiting Approval — work is done but the step has an approval gate. A human reviewer must approve or request changes
- Completed — step is finished. Its output is available as context for subsequent steps
- Failed — step encountered an issue. Can be retried, which resets it to pending
- Skipped — step was deemed not applicable. Counts toward workflow completion
Approval Gates
Steps marked with an approval gate pause for human review. When an agent completes such a step, it moves to Awaiting Approval instead of Completed. A human reviewer then has two options:
- Approve — marks the step as completed and the workflow continues to the next step
- Request Changes — fails the step with feedback. You can choose which earlier step to send work back to (cascade rejection), resetting all steps from that point onward back to pending
Important: Only human users can approve steps — AI agents cannot approve their own (or any other) work. This ensures meaningful human oversight at critical checkpoints.
Cascade Rejection & Rework
When a reviewer requests changes, they can choose to send work back to any earlier step in the pipeline — not just the immediately preceding one. This is called cascade rejection.
- All steps from the selected target onward are reset to pending
- The reviewer's feedback is preserved as a changes_requested comment on the step
- When an agent re-claims a previously failed step, they automatically receive rework instructions — the previous failure output plus all reviewer feedback — so they have full context for the retry
Context Chaining
Each step's output is automatically passed forward to subsequent steps as context. When an agent claims a step, they receive:
- The step's own description and expected deliverables
- The outputs from all previously completed and skipped steps in the workflow
- The task description for overall context
- Rework instructions if the step was previously failed
This means later steps can build on earlier work without manual handoffs. For example, a QA agent writing tests can see the code the Developer agent produced in a previous step.
Step Comments
Each step has its own comment thread for communication between agents and reviewers. Comments are typed:
- Comment — general discussion or notes
- Output — automatically created when a step is completed with output
- Failure — details about why a step failed
- Approval — notes from the approving reviewer
- Changes Requested — feedback from a reviewer who rejected the step
Agent Execution via Claude Code
Workflows are designed to be driven by AI agents through Claude Code connected via MCP. There is no separate "orchestrator" — Claude Code itself reads the workflow and executes steps one by one.
The orchestration loop works as follows:
Claim the next step — call claim_next_step with the task ID. This returns the first pending step, its details, available agents, and context from prior steps
Switch identity — call set_agent_identity to assume the persona of the agent assigned to the step
Execute the work — perform the step's task (write code, run tests, create designs, etc.) following the step description and agent prompt
Complete the step — call complete_step with the output. If the step has an approval gate, it pauses for human review
Loop — go back to step 1 and claim the next pending step. When all steps are done, the workflow run is automatically marked as completed
Tip: You can ask Claude Code to "run the workflow on this task" and it will execute the full loop — claiming steps, switching agent personas, doing the work, and completing each step until the workflow is finished or an approval gate is reached.
Agent Role Matching
When a template is applied to a task, VibeCodes automatically matches agents from the idea's agent team to each step based on the step's role. Matching uses three tiers:
- Exact match — the agent's role exactly matches the step's role
- Substring match — the step role appears within the agent's role or vice versa
- Word overlap — shared words between the role strings (e.g., "Frontend Developer" matches "Senior Frontend Dev")
If a step has no matching agent, the UI shows a warning banner. You can add more agents to the idea's team and then use Rematch Agents to re-run the matching on unmatched pending steps.
Managing Workflow Runs
Once a workflow is applied to a task, you can manage it from the task detail dialog:
- Progress bar — shows how many steps are completed or skipped vs. total
- Step list — click any step to see its full details, output, comments, and action buttons
- Skip — mark a pending step as not applicable. Skipped steps count toward workflow completion
- Retry — reset a failed step back to pending for another attempt
- Reset Workflow — reset all steps back to pending and start over
- Remove Workflow — delete the workflow run and all its steps entirely
Template Edit Propagation
When you edit a template's steps, the changes automatically propagate to any pending steps in active workflow runs that were created from that template. Steps that are already in progress, completed, or failed are not affected. If the number of steps has changed (structural edit), propagation is skipped for safety — you should remove and re-apply the workflow in that case.
Real-time Updates
Workflow step changes are synced in real time. If an agent completes a step or a reviewer approves one, you'll see the status update immediately in the task detail dialog without refreshing. Progress bars, status badges, and step outputs all update live.