Workflows

Workflows let you define reusable, multi-step agent pipelines in the .weave DSL. Each step specifies which agent to use, what prompt to give it, and how to detect completion.

Workflows are explicit, user-invoked constructs. They are not the default path for ordinary Weave usage. Ordinary usage is Loom-led: Loom handles conversational triage and delegates bounded tasks to Shuttle. A workflow begins only when a user explicitly invokes one.

In-harness lifecycle maturity

Workflow execution lifecycle support (step dispatch, state persistence, resume-after-pause) is implemented in the engine and the OpenCode adapter. Full parity across all adapters is still in progress. See Adapters for current status.

Quick Start

1. Add a workflow to your .weave/config.weave:

workflow quick-fix {
  description "Fix a bug and get it reviewed"
  version 1

  step fix {
    name "Implement the fix"
    type autonomous
    agent shuttle
    prompt "Fix the following issue: {{instance.goal}}. Identify the root cause, implement the fix, and write a test to prevent regression."
    completion agent_signal
  }

  step review {
    name "Code review"
    type gate
    agent weft
    prompt "Review the fix for: {{instance.goal}}. Respond with [APPROVE] or [REJECT] with feedback."
    completion review_verdict
    on_reject pause
  }
}

2. Start it (exact command depends on your harness adapter; see Adapters):

/weave:start quick-fix "Fix the login button not responding on mobile"

Workflow Fields

Field	Type	Description
description	string	Human-readable workflow label
version	number	Schema version for migration compatibility (currently 1)
step	named block	One or more step declarations

Step Fields

Field	Type	Description
name	string	Display name for the step
type	autonomous | interactive | gate	Step execution mode
agent	identifier	Agent to execute this step
prompt	string	Prompt template. Supports {{instance.*}} and {{artifacts.*}} placeholders.
completion	identifier or block	Completion method. See Completion Methods
on_reject	pause	Action when a gate step rejects
inputs	array	Artifact inputs consumed by this step: { name "..." description "..." }
outputs	array	Artifact outputs produced by this step: { name "..." description "..." }

Step Types

Type	Description
autonomous	Agent works alone without user intervention
interactive	User can intervene during execution
gate	Approve/reject checkpoint. Execution pauses for a verdict

Autonomous Steps

The agent receives the prompt and works until it signals completion. Use for coding, building, or running tests.

step implement {
  name "Implement the feature"
  type autonomous
  agent shuttle
  prompt "Implement: {{instance.goal}}"
  completion agent_signal
}

Interactive Steps

The agent works with the user. The step completes when the user confirms they are satisfied.

step review-plan {
  name "Review the plan with user"
  type interactive
  agent shuttle
  prompt "Present the plan at {{artifacts.plan_path}} for: {{instance.goal}}. Discuss any changes with the user."
  completion user_confirm
}

Gate Steps

The agent reviews work and produces a verdict. If it approves, the workflow advances. If it rejects, the workflow pauses (when on_reject pause is set).

step security-review {
  name "Security audit"
  type gate
  agent warp
  prompt "Audit all changes for: {{instance.goal}}. Respond with [APPROVE] or [REJECT]."
  completion review_verdict
  on_reject pause
}

Multi-Model Review Fan-Out

When the agent assigned to a gate step has review_models configured, the engine fans out the review prompt to every model in that list instead of running a single review. Each model runs as a read-only variant, and the results are collated into one verdict:

• If at least one variant approves, the gate passes (any failures are recorded as warnings).
• If every variant fails, the gate rejects and the on_reject action applies.

agent warp {
  models ["anthropic/claude-opus-4"]
  review_models ["openai/gpt-5", "anthropic/claude-sonnet-4-5"]
}

workflow secure-feature {
  # ...
  step security-review {
    name "Multi-model security audit"
    type gate
    agent warp
    prompt "Audit all changes for: {{instance.goal}}. Respond with [APPROVE] or [REJECT]."
    completion review_verdict
    on_reject pause
  }
}

Fan-out only occurs for gate steps with completion review_verdict. Other step types and completion methods are not affected. See Review Models for configuration details.

Completion Methods

Method	Syntax	Meaning
agent_signal	bare identifier	Agent emits a completion signal
user_confirm	bare identifier	User explicitly confirms completion
plan_created	block with plan_name	A plan file was created at the given path
plan_complete	block with plan_name	A plan file was fully executed
review_verdict	bare identifier	A gate agent emits approve or reject

Plan-Based Completion

For plan_created and plan_complete, specify the plan name in a block:

completion plan_created {
  plan_name "{{instance.slug}}"
}

The plan_name supports template variables. {{instance.slug}} is derived from the user's goal, so each workflow run produces a uniquely named plan.

Template Variables

Step prompts support template variables using double-brace syntax:

Variable	Description
{{instance.goal}}	The user's goal for this workflow run
{{instance.slug}}	URL-safe slug derived from the goal
{{artifacts.X}}	Value of artifact X from a previous step

Artifacts (Inputs and Outputs)

Steps can declare inputs and outputs to create a data flow between steps.

step plan {
  name "Create implementation plan"
  type autonomous
  agent pattern
  prompt "Create a detailed implementation plan for: {{instance.goal}}"

  completion plan_created {
    plan_name "{{instance.slug}}"
  }

  outputs [
    { name "plan_path" description "Path to the generated plan file" }
  ]
}

step implement {
  name "Execute the plan"
  type autonomous
  agent shuttle
  prompt "Execute the plan at {{artifacts.plan_path}} for: {{instance.goal}}"

  completion plan_complete {
    plan_name "{{instance.slug}}"
  }

  inputs [
    { name "plan_path" description "Path to the plan to execute" }
  ]
}

Workflow Extension

Workflows support composition directives for inserting steps at defined extension points.

Extension Points

A workflow can declare extension points where external steps can be injected:

workflow plan-and-execute {
  description "Plan work then execute it"
  version 1

  extension_points { before-plan }

  step plan {
    name "Create implementation plan"
    type autonomous
    agent pattern
    prompt "Create a detailed implementation plan for: {{instance.goal}}"
    completion plan_created {
      plan_name "{{instance.slug}}"
    }
  }

  # ... more steps
}

The extension_points { before-plan } declaration inside the workflow block marks where steps can be inserted. In this example, any steps extended into before-plan will run before the plan step.

Extend Directive

Use the top-level extend directive to inject steps into workflows that publish matching extension points:

extend before-plan ["write-spec", "review-spec"]

This inserts the write-spec and review-spec steps into every workflow that declares extension_points { before-plan }. There is no per-workflow targeting in v1. Multiple extend before-plan directives union-merge their step lists.

The extended steps must be defined elsewhere in your configuration as normal step blocks.

Builtin Workflows

Weave includes three builtin workflows that are invoked explicitly by the user. These are not the default path for ordinary usage (which is Loom-led conversational triage with Shuttle delegation).

plan-and-execute

Purpose: Plans work in detail, then delegates execution to specialist agents.

This workflow creates a structured implementation plan and hands it off to execution specialists. It is ideal for complex features or changes that benefit from upfront design.

Invocation: Explicitly started by the user (exact command depends on your harness adapter).

quick-fix

Purpose: Fast single-agent fix without planning overhead.

This workflow skips the planning phase and goes straight to implementation. Use it for small bug fixes, typos, or other changes where a full plan would be overkill.

Invocation: Explicitly started by the user.

tapestry-execution

Purpose: Coordinates plan execution through specialist delegation.

This workflow takes an existing plan and orchestrates its execution by delegating tasks to the appropriate specialist agents. It is typically used as a follow-on step after a planning workflow or when resuming work on an existing plan.

Invocation: Explicitly started by the user.

Full Example

workflow secure-feature {
  description "Plan, implement, build, and review a feature with security audit"
  version 1

  step plan {
    name "Create implementation plan"
    type autonomous
    agent pattern
    prompt "Create a detailed implementation plan for: {{instance.goal}}"

    completion plan_created {
      plan_name "{{instance.slug}}"
    }

    outputs [
      { name "plan_path" description "Path to the generated plan file" }
    ]
  }

  step review-plan {
    name "Review the plan"
    type interactive
    agent shuttle
    prompt "Review the plan at {{artifacts.plan_path}} for: {{instance.goal}}"
    completion user_confirm
  }

  step implement {
    name "Execute the plan"
    type autonomous
    agent shuttle
    prompt "Execute the plan at {{artifacts.plan_path}} for: {{instance.goal}}"

    completion plan_complete {
      plan_name "{{instance.slug}}"
    }

    inputs [
      { name "plan_path" description "Path to the plan to execute" }
    ]
  }

  step security-review {
    name "Security audit"
    type gate
    agent warp
    prompt "Perform a security audit of all changes for: {{instance.goal}}"
    completion review_verdict
    on_reject pause
  }
}

Tips

Start Simple

Begin with 2-3 step workflows. Add complexity as you learn which patterns work best for your team.

Use Gate Steps for Quality Control

Gate steps with on_reject pause are a natural checkpoint. The workflow pauses so you can address feedback and resume, rather than failing outright.

See Also

• Custom Agents: define new agents to use in workflow steps
• Skills: inject domain expertise into agents used by workflows
• Workflow Customization: reshape Weave's default delegation behavior
• Configuration Files: where config files live and how they are loaded