| name | pgflow |
| description | Work with PgFlow — a PostgreSQL-based workflow engine for Elixir/Phoenix. Dispatches subcommands via `/pgflow [subcommand] [args]`. Use when the user says '/pgflow bootstrap', '/pgflow flow', '/pgflow job', '/pgflow step', '/pgflow dashboard', '/pgflow liveview', '/pgflow debug', '/pgflow help', 'add pgflow', 'bootstrap pgflow', 'add workflows', 'new flow', 'new job', 'debug run', or wants to set up, build, or manage PgFlow flows and jobs in a Phoenix project. |
PgFlow
Multi-subcommand skill for working with PgFlow — a PostgreSQL-based DAG workflow engine for Elixir/Phoenix. PgFlow replaces Redis queues and external orchestration with pure PostgreSQL, using PGMQ for message queuing and OTP for execution.
Subcommands
/pgflow help
Display a list of all available subcommands. Output the following exactly:
/pgflow subcommands:
bootstrap — Add PgFlow to a Phoenix app (deps, migrations, config, supervision tree)
flow [Module] — Scaffold a new flow module and compile to database
job [Module] — Scaffold a new job module and compile to database
step [Module] [name] — Add a step to an existing flow
dashboard [path] — Add the PgFlow LiveView dashboard to the router
liveview [Module] [:slug] — Scaffold a LiveView with real-time flow tracking
debug [run_id|:slug|failed] — Inspect a run, flow, or recent failures
help — Show this help message
If /pgflow is invoked without a subcommand, show the help output above and ask which to run.
Dispatch
- Parse the subcommand and args from the user's invocation. Examples:
/pgflow bootstrap → subcommand bootstrap, no args/pgflow flow MyApp.Flows.ProcessOrder → subcommand flow, arg MyApp.Flows.ProcessOrder/pgflow job MyApp.Jobs.SendEmail → subcommand job, arg MyApp.Jobs.SendEmail/pgflow step MyApp.Flows.ProcessOrder notify → subcommand step, args MyApp.Flows.ProcessOrder notify/pgflow step notify → subcommand step, arg notify (ask which flow)/pgflow dashboard → subcommand dashboard, no args/pgflow dashboard /admin/pgflow → subcommand dashboard, arg /admin/pgflow/pgflow liveview MyAppWeb.OrderLive :process_order → subcommand liveview, args/pgflow debug abc123-uuid → subcommand debug, arg is a run ID/pgflow debug :process_order → subcommand debug, arg is a flow slug/pgflow debug failed → subcommand debug, show recent failures/pgflow help → show help
- If the subcommand is unknown, list available subcommands from the table above and stop.
- Read the matching reference file from
references/ and follow its workflow exactly.
- Pass any remaining arguments through to the subcommand.
PgFlow Quick Reference
These core concepts apply across all subcommands:
- Flows: Multi-step DAG workflows defined with
use PgFlow.Flow and step/map macros
- Jobs: Single-step background tasks defined with
use PgFlow.Job and perform macro
- Runs: Instances of a flow/job execution, tracked in
pgflow.runs
- Steps: Individual units of work in a flow, forming a DAG via
depends_on:
- PGMQ: PostgreSQL Message Queue — the underlying queue transport
- LiveClient:
PgFlow.LiveClient for real-time flow tracking in LiveView
Key API
# Start a flow
{:ok, run_id} = PgFlow.start_flow(:flow_slug, %{"key" => "value"})
# Start and wait for completion
{:ok, run} = PgFlow.start_flow_sync(:flow_slug, input, timeout: 30_000)
# Enqueue a job
{:ok, run_id} = PgFlow.enqueue(MyApp.Jobs.MyJob, %{"key" => "value"})
# Check status
{:ok, run} = PgFlow.get_run(run_id)
{:ok, run} = PgFlow.get_run_with_states(run_id)
Mix Tasks
| Task | Purpose |
|---|
mix pgflow.copy_migrations | Copy core schema migrations |
mix pgflow.gen.extensions_migration | Generate worker extensions migration |
mix pgflow.gen.flow Module | Generate migration to compile a flow |
mix pgflow.gen.job Module | Generate migration to compile a job |
mix pgflow.check_schema | Verify database schema compatibility |
Reference Files
Detailed guides available in references/:
$ARGUMENTS
