Workflows

Workflows define multi-step execution pipelines with agents, completion conditions, and artifact passing. They are explicit, user-invoked constructs, not the default path for ordinary Weave usage.

Workflows are declared using the workflow block in your .weave configuration:

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
  }
}

Each step in a workflow has a type that determines its execution mode:

The completion field declares how a step signals that it is done. There are five completion methods:

The agent emits an explicit done signal. Used for autonomous steps that complete programmatically.

completion agent_signal

The user explicitly approves the step outcome. Used for interactive steps requiring human confirmation.

completion user_confirm

The agent writes a named plan file. The engine validates that the plan file exists at the specified path.

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

The agent finishes executing a named plan. The engine validates that the plan file has no remaining - [ ] checkboxes.

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

A gate agent returns an approve or reject decision. Only valid for type: gate steps.

completion review_verdict

When a review_verdict signal arrives with approved: false, the engine reads the step’s on_reject field and applies the corresponding policy.

Artifacts flow between steps through explicit inputs and outputs declarations. Both name and description are required for each artifact.

A step declares artifacts it produces using the outputs array:

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

When the step completes successfully, the engine validates that every declared artifact is present before advancing to the next step.

A step declares artifacts it consumes using the inputs array:

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

Before dispatching the step, the engine validates that every declared input artifact is already present in the instance’s artifact store.

Artifact names are available as template variables in downstream step prompts:

prompt "Review the plan at {{artifacts.plan_path}} for: {{instance.goal}}"

Available template variables include:

• {{instance.goal}} - the human-readable goal for this execution
• {{instance.slug}} - the URL-safe slug for this execution
• {{artifacts.<name>}} - artifact values produced by previous steps

Gate steps (type: gate) are approval checkpoints. When a gate step rejects, the on_reject field determines what happens next.

The on_reject field is only valid on type: gate steps. Setting it on an autonomous or interactive step causes a validation error.

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
}

When on_reject is absent and a gate rejects, the engine defaults to pause behavior.

Workflows can be extended by inserting additional steps at specific positions. This is useful for adding organization-specific checks or enriching planning inputs.

A workflow declares that it exposes extension slots using the extension_points block:

workflow plan-and-execute {
  description "Research, plan, implement, and review a feature end-to-end"
  version 1

  extension_points {
    before-plan
  }

  step research {
    name "Research the codebase and external context"
    type autonomous
    agent thread
    prompt "Explore the codebase to understand the relevant area for: {{instance.goal}}"
    completion agent_signal
  }

  step plan {
    name "Create implementation plan"
    role planning
    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" }
    ]
  }
}

Key invariants:

• extension_points { before-plan } is the only publication syntax in v1
• A workflow that publishes before-plan must contain exactly one step with role planning
• The before-plan slot enriches planning inputs; it does not replace the planning step

The extend before-plan directive inserts steps into the before-plan slot of any workflow that publishes it:

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

This is a composition directive, separate from the extension_points publication syntax. The listed step names are inserted into the before-plan slot in the order declared.

v1 contract: There is exactly one global before-plan bucket. The same step list is applied to every workflow that publishes extension_points { before-plan }. Multiple extend before-plan directives in the same config are union-merged into a single ordered step list.

Individual steps can specify their position relative to anchor steps using insert_before or insert_after:

step write-spec {
  name "Write specification"
  type autonomous
  agent pattern
  prompt "Write a detailed specification for: {{instance.goal}}"
  completion agent_signal
  insert_before "plan"
  outputs [
    { name "spec_path" description "Path to the specification document" }
  ]
}

These directives are mutually exclusive: a step cannot specify both insert_before and insert_after.

Here is a complete workflow that demonstrates all major features:

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

  extension_points {
    before-plan
  }

  step research {
    name "Research the codebase"
    type autonomous
    agent thread
    prompt "Explore the codebase to understand: {{instance.goal}}"
    completion agent_signal
  }

  step plan {
    name "Create implementation plan"
    role planning
    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

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

  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
  }
}

1. Research step (autonomous): The thread agent explores the codebase autonomously. When it emits an agent_signal, the workflow advances automatically.

2. Plan step (autonomous, role: planning): The pattern agent creates an implementation plan. The plan_created completion method validates that a plan file exists at .weave/plans/{{instance.slug}}.md. The step produces a plan_path artifact for downstream steps.

3. Review plan step (interactive): The shuttle agent presents the plan for review. The step consumes the plan_path artifact via the {{artifacts.plan_path}} template variable. Execution pauses until the user explicitly confirms via user_confirm.

4. Implement step (autonomous): The shuttle agent executes the plan. The plan_complete completion method validates that the plan file has no remaining - [ ] checkboxes. The step consumes the plan_path artifact as an input.

5. Security review step (gate): The warp agent performs a security audit. The review_verdict completion method expects an approve/reject decision. If the gate rejects, on_reject: pause causes the workflow to pause for user intervention rather than failing immediately.

To add a specification step before planning:

step write-spec {
  name "Write specification"
  type autonomous
  agent pattern
  prompt "Write a detailed specification for: {{instance.goal}}"
  completion agent_signal
  outputs [
    { name "spec_path" description "Path to the specification document" }
  ]
}

step review-spec {
  name "Review specification"
  type gate
  agent weft
  prompt "Review the specification at {{artifacts.spec_path}} for: {{instance.goal}}"
  completion review_verdict
  on_reject pause
  inputs [
    { name "spec_path" description "Path to the specification to review" }
  ]
}

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

The resolved step order becomes:

1. research (inherited from base workflow)
2. write-spec (inserted into before-plan slot, produces spec_path)
3. review-spec (inserted into before-plan slot, consumes spec_path, gate must approve)
4. plan (canonical planning step with role: planning)
5. review-plan (inherited from base workflow)
6. implement (inherited from base workflow)
7. security-review (inherited from base workflow)

The reviewed specification artifact can be passed to the planning step by adding it to the plan step’s inputs array.

Steps are executed in declaration order. The steps array in the workflow configuration is the authoritative sequence. There is no branching or conditional routing; step order is fixed by the DSL declaration.

• Outputs: When a step completes successfully, the engine validates that every artifact named in step.outputs is present. Validation is all-or-nothing: a missing artifact returns a validation error before any state changes.

• Inputs: Before dispatching a step, the engine validates that every artifact named in step.inputs is already present in the instance’s artifact store. A missing input artifact returns a not-found error before the dispatch effect is emitted.

When a step completes, the engine validates the completion signal against the step’s declared completion.method. A method mismatch returns a validation error before any state changes.

• Step completion signals structurally exclude raw prompts, completions, transcripts, credentials, and tokens
• Only safe metadata (outcome, method, approved, message, artifacts, nextStepHint) is accepted
• Prompt metadata in run-agent effects carries only byte length, no raw prompt text
• All lifecycle inputs are validated against a credential denylist before any state changes

• DSL Configuration - Complete .weave syntax reference
• Agents - Agent roles and capabilities
• Prompt Composition - How workflow prompts are composed