Workflows and backlog experience
Workflows and backlog are the operating model for Agentweaver work. Workflows define how a run moves through nodes, edges, triggers, gates, and completion; backlog defines which tasks are not yet committed, which tasks are Ready, and what the coordinator heartbeat may pick up next. The web UI gives humans a visual control room, while MCP exposes the same state and actions as tools.
Scope: this page covers workflow definition management, backlog intake, Ready pickup, autopilot defaults, spec decomposition, board stages, and the MCP tools for those experiences.
Related docs: Overview, Runs & board, Coordinator & orchestration, Operations, Workflow generation, Workflow selection, Workflow library, Workflow binder, and Workflow engine.
The mental model
Agentweaver separates process definition from work intake.
- A workflow is a reusable pipeline. It has an id, name, description, version, trigger, start node, nodes, edges, and optional stage definitions.
- A node is a step in the pipeline: agent work, peer review, RAI check, human review, merge, scribe, terminal, or another supported workflow shape.
- An edge connects nodes and may carry a verdict such as
approved,request-changes,declined,pass,fail,review, orrevise. - A trigger describes how the workflow starts. The Workflows page shows it as Trigger: event (...), Trigger: manual, or Trigger: unknown.
- A default workflow is the project fallback for new work when no better or explicit workflow is selected.
- A backlog task is work that has not been claimed yet. It sits in Backlog or Ready.
- A pickup is the coordinator heartbeat claiming a Ready task and turning it into an unattended coordinator run.
- The board has six logical buckets: Backlog, Ready, Problems, Human Review, Active, and Done. The UI renders Backlog → Ready → Active → Done as four main lanes, with Human Review and Problems in a separate Needs attention / review section.
The user-facing promise is simple: workflows answer how should this run? Backlog answers what should run next? The heartbeat connects them.
Workflows in the web UI
The project Workflows page is reached from a project at Workflows. It is titled Workflows with the subtitle Reusable pipeline definitions. It shows discovered workflow definitions, validation status, source, trigger, and the effective default.
The page groups cards into three sections:
| Section | What the user sees | What it means |
|---|---|---|
| Active workflow | The workflow card marked Active. | This is the effective default for new project runs. |
| Available workflows | Valid workflows that can be chosen through Set as default. | These are runnable definitions discovered by the project registry. |
| Invalid workflows | Workflows marked Invalid with an error message. | These cannot run or become active until fixed. |
Each card shows the workflow name, id, badges, Trigger, and Source. Built-in workflows carry Built-in. Valid non-default workflows carry Valid. Invalid workflows carry Invalid and display the validation error. The active card carries Active because it is already the project default.
Page actions are operational:
- New workflow opens a YAML editor with a blank template.
- Generate workflow opens a plain-language generation dialog.
- Set as default opens a picker with Project workflows, Built-in workflows, and Reset to built-in default.
- Sync re-reads
.agentweaver/workflows/. - View graph expands an inline read-only graph for a valid workflow.
- Edit opens the YAML editor for project-authored workflows.
- Edit visually opens the visual workflow editor for project-authored workflows.
Built-in workflows are inspectable and selectable. Project workflows are editable because they live in the project's workspace.
workflows_list: viewing discovered workflows
MCP mirrors the Workflows page with workflows_list. It returns the discovered workflow set for a project, including validation status and which workflow is the effective default.
Use workflows_list when an assistant needs to:
- see every workflow the project can use,
- identify the default,
- avoid invalid workflows,
- decide whether a task should use the default or an override,
- explain why the UI shows a workflow as Active, Available, or Invalid.
The discovered set includes the built-in default, catalog library workflows allowed for the project, and project-authored YAML files from .agentweaver/workflows/. Discovery and validation are server-side. The UI and MCP render the result; they do not invent workflow validity.
workflow_get: inspecting nodes, edges, and trigger
workflow_get returns a single workflow by id, including its nodes, edges, and trigger. It is the assistant equivalent of opening a workflow and reading the pipeline.
Use it to answer:
- which trigger starts the workflow,
- which node is first,
- which agents, reviews, checks, merges, and terminal paths exist,
- which edge sends failed review back to implementation,
- whether the workflow is event-driven, manual, or otherwise configured.
In the UI, View graph gives the human a compact structural preview. Nodes are laid out left to right. Forward edges show normal progression. Loopback edges show rework paths such as revise or request changes. Card shape follows node type: agent nodes read as main work, gates read as decisions, action nodes read as execution steps, and terminal nodes read as endpoints.
Defaults, sync, and runtime readiness
Set as default changes the project default. Choosing a valid workflow makes it active. Choosing Reset to built-in default clears the project-specific default and returns the project to the built-in fallback.
Default selection is safe by design. A workflow must be valid and bindable before it can become default. Loader-valid definitions that cannot execute are rejected before they can become the project default.
Sync is explicit. It re-reads .agentweaver/workflows/ and refreshes the registry. MCP uses workflows_sync for the same operation. Use it after a workflow file changes on disk. A successful UI sync shows a message like Synced 3 workflows from .agentweaver/workflows/.
If sync finds invalid workflows, they remain visible under Invalid workflows with errors. The experience turns broken definitions into visible operational work.
Generating and saving workflows
Workflow generation is draft-first. The user clicks Generate workflow, describes the pipeline, and receives YAML for review. Nothing is saved to .agentweaver/workflows/ until the user saves.
Web UI generation flow
The Generate workflow dialog has one field:
| UI label | Hint | User action |
|---|---|---|
| Describe the workflow you need | A complete YAML draft will be generated for you to review and edit before saving. | Describe the process and click Generate. |
While generation runs, the primary button reads Generating…. On success, the dialog closes and the editor opens with the YAML draft. The success message says Workflow generated. Review and save the draft. If the generator needed its one correction pass, the message says Workflow generated (one correction pass applied). Review and save the draft.
MCP generation and save
workflow_generate takes project_id and description. It returns:
yaml— the generated workflow YAML draft,workflow_id— the id declared or derived for the draft,was_corrected— whether one correction pass was needed.
The generated YAML is constrained to the project's castable roles when the project has a team. Agent nodes are bound to the matching confirmed member name before the draft is returned. If a role has no cast mapping, including when the team is missing or unreadable, generation, save, and manual run return workflow_team_binding_required with structured unresolved_roles; nothing is saved or submitted until the team is recast or the workflow is mapped.
workflow_save persists YAML into the project workspace. It validates YAML, verifies the declared id matches the workflow_id, dry-run binds the definition to the runtime graph, writes it under .agentweaver/workflows/, syncs the registry, and returns the parsed workflow definition.
The boundary is deliberate: generation can be creative, editing can be iterative, and saving is strict. If validation or binding fails, the user sees an error instead of a half-saved workflow.
Workflow selection during pickup
A Ready task may run with:
- a task-specific workflow override,
- the coordinator's best-fit selection among available workflows,
- the project default as fallback.
The task card workflow menu is the human pre-run override. It opens from the flow icon on a task card and lists valid workflows. Selecting a workflow stores the override. Selecting Use project default clears it.
Once a task is claimed, the workflow override can no longer be changed. If a user or assistant races with pickup, the backend returns a conflict and the UI explains that the task was just claimed.
The coordinator selection model is process-fit oriented. It selects the workflow whose steps and outputs fit the task, not the workflow whose name shares words with the task. If selection fails, the default remains the safe fallback. See Workflow selection for the deeper selection contract.
Workflow definition graph
The Workflows page can expand any valid workflow card with View graph. This is a definition graph, not a live run graph: it shows the reusable pipeline structure before the coordinator applies it to a specific run. Live status-carrying topology remains on the coordinator orchestration page.
Open /projects/:projectId/workflows and choose View graph on a valid definition. Use YAML or visual editing for project-authored definitions, then save explicitly; inspecting a graph does not execute it.
The backlog board experience
The board is the user's work queue. It presents intake tasks and run cards in one place.
Open a project → Board to capture and rank intake tasks. Dragging is limited to Backlog and Ready; the coordinator owns progression after pickup.
| Logical bucket | Stage kind | Description shown in the UI | Who moves work there |
|---|---|---|---|
| Backlog | intake | Captured but not yet committed to. Things you're considering. | User or MCP client. |
| Ready | intake | Committed work that the coordinator and Ralph monitor may pick up next. | User or MCP client, then heartbeat. |
| Problems | workflow | Blocked, failed, declined, or otherwise needs attention. | Coordinator and run lifecycle. |
| Human Review | workflow | Work waiting for a person to review or approve. | Coordinator and review gates. |
| Active | workflow | Work currently moving through the coordinator workflow. | Heartbeat and coordinator. |
| Done | workflow | Completed or merged work. | Coordinator and terminal lifecycle. |
Backlog and Ready are intake columns. They contain draggable task cards. Problems, Human Review, Active, and Done are run-bucket stages. They contain run cards and are owned by the coordinator. Dragging a task into a workflow column is rejected with Only the coordinator moves work into the workflow.
Capturing and editing tasks
The capture bar says Capture a task into Backlog. The user enters a title and clicks Add or presses Enter. Empty titles are blocked in the UI and by the backend.
MCP uses backlog_capture_task with project_id, required title, and optional description. Captured tasks start in Backlog. The card shows the title, optional description, captured-by identity, workflow menu, edit action, and archive action.
Edit task opens Title and Description fields with Cancel and Save. MCP uses backlog_edit_task for the same operation.
backlog_delete_task removes an unclaimed backlog task through MCP. If the task has already been claimed, deletion fails with 409 task_claimed. Once work becomes a run, the run is the accountable record.
Archive task and backlog_archive_task remove the task from the active board. If the task is claimed, archiving also archives the linked coordinator run card.
Promoting Backlog to Ready
Ready is the commitment boundary. A task in Backlog is being considered. A task in Ready is eligible for heartbeat pickup.
The user can promote by dragging Backlog → Ready, using Add to Ready, or clicking Send all to Ready on a non-empty Backlog column.
| Tool | UI equivalent | Notes |
|---|---|---|
backlog_move_to_ready | Drag Backlog → Ready. | Optional zero-based target_index; null appends. |
backlog_move_to_backlog | Drag Ready → Backlog. | Optional zero-based target_index; null appends. |
backlog_reorder_task | Drag within Backlog or Ready. | Reorders within the current intake bucket. |
send_all_backlog_to_ready | Send all to Ready. | Bulk-promotes all Backlog tasks, preserving relative order and appending after existing Ready tasks. |
send_all_backlog_to_ready is idempotent. On an empty backlog, it returns No backlog tasks to promote. In the UI, the button only appears when Backlog has cards.
Board snapshots and stages
backlog_get_board returns the full board: Backlog, Ready, Problems, Human Review, Active, and Done. It accepts include_terminal_history, which controls how much Done history appears.
The web board uses the same model. Done shows recent terminal cards by default and can reveal older cards with Show older. Show less collapses the terminal history again.
Run cards are read-only from a workflow-position perspective. They show title, status, current stage or work-plan status, coordinator or agent identity, Approval needed when tool approval is pending, Retry when failed or merge-failed, and archive.
backlog_get_workflow_stages returns the ordered canonical run buckets:
- Problems
- Human Review
- Active
- Done
These are board buckets, not necessarily workflow nodes. Failed, blocked, declined, or merge-failed work maps to Problems. Awaiting review maps to Human Review. In-progress planning, dispatch, and assembly maps to Active. Completed, merged, or assemble-ready runs map to Done. Terminal does not automatically mean Done: declined and failed runs still need attention.
Pickup and automation
Pickup turns Ready tasks into coordinator runs. The heartbeat scans eligible projects and reads their top Ready candidates. Task claim, coordinator run reservation, and approval-policy snapshot persist in one transaction; only a won claim activates the reserved run unattended.
A project is eligible when it is active and its workspace is available. Unavailable projects leave Ready tasks untouched with priority preserved. A lost claim (another claimant won or the task moved back to Backlog) makes no new reservation. A won claim prevents duplicate task-to-run reservations; it is not a blanket exactly-once guarantee for every later agent action.
After reservation commits, activation starts the coordinator and schedules unattended confirmation attributed to CapturedBy. If activation fails, the service attempts to terminalize the reserved run as Failed with coordinator_start_failed; the task remains Claimed, not silently requeued. Missing/invalid teams or unavailable model-provider authorization can also produce a claimed failed run before activation. Inspect Problems and the recorded reason rather than expecting another heartbeat to retry it automatically.
Pickup settings
The board toolbar includes Pickup settings. The dialog has three controls:
| UI control | Backing setting | Meaning |
|---|---|---|
| Max Ready items per heartbeat | max_ready_per_heartbeat | How many Ready tasks the coordinator may claim per tick. |
| Autopilot | pickup_autopilot | Auto-answer coordinator clarifying questions for automatically picked-up runs. |
| Auto-approve tools | pickup_auto_approve_tools | Automatically approve tool calls for automatically picked-up runs, except sandbox-blocked tools. |
max_ready_per_heartbeat is bounded from 1 to 20. The UI spin button clamps values into range; the backend rejects out-of-range values. MCP uses backlog_get_settings and backlog_set_settings for the same state.
Autopilot UX
Autopilot keeps unattended pickup runs moving through clarifying questions that the coordinator can answer from context. The help text says it auto-answers the coordinator's clarifying questions using the coordinator model so the run does not pause, while tool and permission approvals are still asked, and every auto-answer is logged in the timeline.
The UX contract is:
- Autopilot applies to heartbeat-picked runs and their child runs.
- It auto-answers clarifying questions using the coordinator model.
- It does not silently grant tool or permission approvals.
- Every auto-answer is visible in the run timeline.
- If Auto-approve tools is also enabled, only repository-defined safe tools may be auto-approved. Destructive, privileged, preview, secret, and other network approvals remain gated.
Use autopilot when Ready tasks are well-scoped and the user wants queue throughput. Leave it off when tasks require human judgment at the first clarification gate.
Decomposing a spec into backlog tasks
Spec decomposition turns a markdown document in the project workspace into proposed backlog tasks. It is preview-first: the user sees proposed items before creation.
Web UI flow
The board toolbar has Import from workspace. The user selects a workspace file and clicks Preview tasks. Agentweaver analyzes the markdown file and opens Preview proposed backlog items.
The same preview is reachable from Workspace by selecting a Markdown spec and choosing Import to backlog. Review proposed tasks before choosing Create tasks; merely opening the preview does not create intake items.
The preview dialog shows task titles, optional descriptions, Already exists badges for duplicates, a cap notice when extraction returns more than the cap, No actionable items found in this file. when empty, and Create tasks to confirm persistence.
When the user clicks Create tasks, Agentweaver creates non-duplicate items in Backlog, appends them after existing Backlog tasks, refreshes the board, and shows Tasks imported successfully.
MCP flow with backlog_decompose_spec
backlog_decompose_spec takes project_id, workspace-relative file_path, and confirm. With confirm=false, it previews. With confirm=true, it creates tasks.
The response includes proposed_items, was_capped, and total_found. Each proposed item includes title, optional description, and already_exists.
Recommended MCP flow:
- call
backlog_decompose_specwithconfirm=false, - inspect or present
proposed_items, - call it again with
confirm=truewhen creation is desired, - call
backlog_get_boardto show the new Backlog state.
Results are capped at 50 items. Duplicate detection is scoped to the same project and source file title, so repeated imports from the same spec are safe.
Web UI and MCP parity
| Experience | Web UI | MCP tool |
|---|---|---|
| List workflows and default | Workflows page | workflows_list |
| Inspect one workflow | View graph and editor detail | workflow_get |
| Generate workflow draft | Generate workflow | workflow_generate |
| Save workflow YAML | Editor Save | workflow_save |
| Re-read workflows from disk | Sync | workflows_sync |
| Capture task | Capture a task into Backlog / Add | backlog_capture_task |
| Edit task | Edit task | backlog_edit_task |
| Delete task | MCP-only cleanup path | backlog_delete_task |
| Promote to Ready | Drag, quick-add, Send all to Ready | backlog_move_to_ready, send_all_backlog_to_ready |
| Move back to Backlog | Drag Ready → Backlog | backlog_move_to_backlog |
| Reorder intake | Drag within Backlog or Ready | backlog_reorder_task |
| Archive task | Archive task | backlog_archive_task |
| Read board | Board page | backlog_get_board |
| Read run buckets | Board columns | backlog_get_workflow_stages |
| Read pickup settings | Pickup settings | backlog_get_settings |
| Update pickup settings | Pickup settings → Save | backlog_set_settings |
| Decompose markdown spec | Import from workspace | backlog_decompose_spec |
Edge cases and limits
- Empty backlog: Backlog can be empty. The UI shows a count of 0 and a drop zone.
send_all_backlog_to_readysafely returns No backlog tasks to promote. - Empty workflow list: The UI shows No workflows found and prompts Sync. In normal operation, the built-in default keeps a project from having no usable workflow.
- Invalid workflows: Invalid entries stay visible under Invalid workflows with errors and cannot become active until fixed.
- Claimed task deletion:
backlog_delete_taskreturns 409task_claimedfor claimed tasks. Operate on the run card instead. - Claimed task movement: moving back to Backlog, reordering, or changing workflow override conflicts after pickup wins the claim.
- Settings bounds:
max_ready_per_heartbeatmust be 1-20. - Project unavailable: inactive projects or unavailable workspaces leave Ready tasks untouched for a later heartbeat.
- Save versus sync:
workflow_savewrites and refreshes the saved workflow;workflows_syncre-reads workflow files after out-of-band disk changes.
Product principles
- Preview before persistence: workflow generation and spec decomposition return drafts or previews before saving or task creation.
- Ready is explicit commitment: heartbeat only picks up Ready tasks, never raw Backlog ideas.
- The coordinator owns workflow movement: humans rank intake; run lifecycle moves workflow-stage cards.
- Defaults are visible: the active workflow is explicit on the Workflows page and returned by
workflows_list. - Automation is accountable: pickup records the captured-by user, autopilot logs auto-answers, and tool approvals remain governed by sandbox policy.
- Invalid state is visible: invalid workflows, failed runs, blocked approvals, and problem cards are surfaced where users can act.
Workflows and backlog make Agentweaver predictable: define the process, queue the work, choose what is Ready, let the heartbeat pick up only committed tasks, and watch every run move through visible stages.
Diagram details and constraints
| Element | Contract |
|---|---|
| title | The board is a projection |
| subtitle | Columns reflect persisted task and run state—not a separate workflow engine. |
| group-title0 | Before and during execution |
| group-title1 | Review / terminal outcomes |
| Backlog | Backlog |
| Backlog | Captured task; not queued |
| Backlog | task: backlog |
| Ready | Ready |
| Ready | Queued task |
| Ready | task: ready |
| Active | Active |
| Active | Work is in progress |
| Active | default non-review bucket |
| Problems | Problems |
| Problems | Failed / declined / merge failed |
| Problems | or assembly blocked / failed |
| Human Review | Human Review |
| Human Review | AwaitingReview / InReview |
| Human Review | or assembly stage: Review |
| Done | Done |
| Done | Completed / Merged / AssembleReady |
| Done | or plan Complete / stage Done |
| e1 | queue |
| e2 | claim + start |
| e3 | await review |
| e4 | finish |
| e5 | problem |
| assurance-title | DEFAULT BUCKETS · NOT A NEW STATE MACHINE |
| assurance-line1 | Configured workflow stages may replace the default run columns. Arrows summarize typical changes, not every path. |
| assurance-line2 | The board polls persisted state. Ready tasks with unmet dependencies stay Ready; blocked is a flag. |
| Backlog | Entity |
| Backlog | BacklogTask |
| Backlog | State |
| Backlog | Run |
| Backlog | Not required |
| Backlog | Action |
| Backlog | Move to Ready |
| Ready | Blocked |
| Ready | Dependency metadata |
| Ready | Pickup |
| Ready | Atomic claim |
| Active | Input |
| Active | Coordinator run |
| Active | Status |
| Active | Non-review default |
| Active | Plan |
| Active | Dispatch / assembly |
| Active | Approval |
| Active | Separate pending flag |
| Problems | Failed / Declined |
| Problems | Merge |
| Problems | MergeFailed |
| Problems | Assembly |
| Problems | Blocked / Failed |
| Problems | Also |
| Problems | AssemblyDeclined |
| Human Review | AwaitingReview |
| Human Review | InReview |
| Human Review | Review stage |
| Human Review | Approve |
| Human Review | Resumes execution |
| Done | Completed / Merged |
| Done | AssembleReady |
| Done | Complete |
| Done | Done stage |
| backlog | No run is required yet; Move to Ready to queue work |
| ready | Unresolved dependencies stay here; Blocked is a flag, not a column |
| progress | Claimed tasks link to their run; Pending approval is a separate flag |
| failed | Blocked assembly is recoverable; Not every problem is terminal |
| review | Approval resumes the workflow; Approval alone is not Done |
| done | Persisted-state mapping; Not merely a clicked approval |
| notes | DEFAULT BUCKETS · NOT A NEW STATE MACHINE; Configured workflow stages may replace the default run columns. Arrows summarize typical changes, not every path.; The board polls persisted state. Ready tasks with unmet dependencies stay Ready; blocked is a flag. |
| groups | Before and during execution; Review and terminal outcomes |
Diagram details and constraints
| Element | Contract |
|---|---|
| title | One won claim, one reserved run |
| takeaway | Ready pickup commits claim and reservation before activation; other outcomes do not launch. |
| group-title-0 | SELECTION AND ATOMIC RESERVATION |
| group-title-1 | POST-CLAIM OUTCOMES |
| Ranked Ready tasks | Ranked Ready tasks |
| Ranked Ready tasks | Heartbeat candidates |
| Ranked Ready tasks | eligible project + workspace |
| Ranked Ready tasks | Top-N limits candidates per tick, not total concurrency. |
| Atomic transaction | Atomic transaction |
| Atomic transaction | Claim + run + policy |
| Atomic transaction | task-scoped reservation |
| Atomic transaction | Commit all together; no orphan losing run. |
| Activate winner | Activate winner |
| Activate winner | Use reserved run ID |
| Activate winner | post-commit activation |
| Activate winner | Schedule unattended confirm attributed to CapturedBy. |
| Lost / unavailable | Lost / unavailable |
| Lost / unavailable | No launch by this pickup |
| Lost / unavailable | rollback / preserve rank |
| Lost / unavailable | A winner may own a lost claim; unavailable leaves Ready. |
| Claimed failed run | Claimed failed run |
| Claimed failed run | Visible failure reason |
| Claimed failed run | preflight / activation failure |
| Claimed failed run | Do not silently requeue. Terminalization may log failure. |
| Coordinator work | Coordinator work |
| Coordinator work | Unattended execution |
| Coordinator work | claim-time policy snapshot |
| Coordinator work | No second manual start for the same captured goal. |
| e0 | attempt |
| e1 | won |
| e2 | not won |
| e3 | activate |
| e4 | failure |
| note | A won preflight-failure reservation also stays Claimed/Failed. Claim-once is not tool-execution-once. |
| n0 | Top-N limits candidates per tick, not total concurrency. |
| n1 | Commit all together; no orphan losing run. |
| n2 | Schedule unattended confirm attributed to CapturedBy. |
| n3 | A winner may own a lost claim; unavailable leaves Ready. |
| n4 | Do not silently requeue. Terminalization may log failure. |
| n5 | No second manual start for the same captured goal. |
| groups | SELECTION AND ATOMIC RESERVATION; POST-CLAIM OUTCOMES |