# `AgentWorkshop.Workflow`
[🔗](https://github.com/joshrotenberg/agent_workshop/blob/main/lib/agent_workshop/workflow.ex#L1)

Declarative workflows -- staged pipelines with file inputs.

A workflow defines a sequence of stages, each assigned to an agent or profile.
Stages can depend on previous stages (result piping) or read from files.
Under the hood, workflows expand into work board items with dependencies,
so board workers execute them automatically.

## Defining a workflow

    workflow(:feature, [
      {:plan, :planner, "Break this into tasks", from: "specs/feature.md"},
      {:implement, :coder, "Implement the plan", from: :plan},
      {:test, :tester, "Write tests", from: :implement},
      {:review, :reviewer, "Review everything", from: [:implement, :test]}
    ])

## Running

    run_workflow(:feature)       # expands stages into work items
    workflow_status(:feature)    # check progress
    reset_workflow(:feature)     # clear and re-run

## Stage options

- `from: "path/to/file.md"` -- read file content into spec
- `from: :stage_name` -- pipe previous stage's result
- `from: [:a, :b]` -- fan-in from multiple stages
- `type: :code` -- work board type (default: :custom)
- `priority: 1` -- priority (default: 3)

# `stage`

```elixir
@type stage() :: %{
  name: atom(),
  work_id: atom(),
  agent: atom(),
  title: String.t(),
  type: atom(),
  priority: non_neg_integer(),
  depends_on: [atom()],
  from_stages: [atom()],
  file_input: String.t() | nil
}
```

# `t`

```elixir
@type t() :: %AgentWorkshop.Workflow{
  created_at: DateTime.t(),
  name: atom(),
  stages: [stage()],
  status: :defined | :running | :completed | :failed
}
```

# `check_completion`

```elixir
@spec check_completion(atom()) :: :ok
```

Check if a workflow is complete (all stages done) and update status.
Called after a work item completes to detect workflow completion.

# `define`

```elixir
@spec define(atom(), list()) :: :ok | {:error, term()}
```

Define a workflow. Validates and stores the stage definitions.

# `get`

```elixir
@spec get(atom()) :: t() | nil
```

Get a workflow definition.

# `list`

```elixir
@spec list() :: [t()]
```

List all defined workflows.

# `reset`

```elixir
@spec reset(atom()) :: :ok | {:error, term()}
```

Reset a workflow -- removes all its work items and sets status back to :defined.

# `run`

```elixir
@spec run(atom()) :: :ok | {:error, term()}
```

Run a workflow by expanding its stages into work board items.

# `status`

```elixir
@spec status(atom()) :: {t(), [AgentWorkshop.Work.t() | nil]} | {:error, :not_found}
```

Get workflow status with all stage items.

# `workflow_for_item`

```elixir
@spec workflow_for_item(atom()) :: atom() | nil
```

Find which workflow (if any) a work item belongs to.

---

*Consult [api-reference.md](api-reference.md) for complete listing*