gc_workflow
Runs and manages YAML-defined deterministic workflows, supporting synchronous or async execution, listing, resuming, monitoring, and repairing workflow runs.
Instructions
Run deterministic workflows from ~/.config/gc/workflows/. Workflows are YAML pipelines with step types: tool, prompt, dispatch, shell, each, branch, halt.
Actions:
run (sync by default, or async: true)
list_workflows — list YAML definitions (defaults to summary: name/file/description/size)
list_executions — list past runs (defaults to summary: no runtime blob)
list — alias for list_executions (backward compat)
show (alias: get_execution) — one execution with full runtime
report — reliability summary, stale-running detection, recent failures
detail — per-step breakdown for an execution
context — inspect runtime context/keys for an execution
resume — re-run from a checkpoint
wait — bounded poll until terminal state or timeout
watch — stream daemon SSE continuity through MCP progress notifications, then return the terminal event
cancel — stop one execution and cancel any backing Oban workflow job
dismiss — hide an execution from default listings
delete — remove one execution (and checkpoint)
prune — bulk-delete old terminal executions
repair_stale — mark stale running executions failed and clear checkpoints
Response shaping:
run (sync):
- Default shape: { execution_id, status: "complete", last_step, result }.
result carries the last MEANINGFUL step's output — the shaper walks
the trace backwards and skips nil-returning tail steps (gc.retain /
gc.notify side-effects). last_step names whichever step produced
result. If every step returns nil, result is null but
last_step still names the actual final step.
- select: "step_id" — return one specific step's result (bypasses the
walk-past-nil default; use when you want an intermediate step or a
specific side-effect's receipt).
- select: "step_a,step_b" — return multiple specific steps (selected
map + result unset).
- return: "full" — everything (all step results + trace).
- return: "steps" — all step results keyed by step_id, no trace.
- return: "trace" — trace only, no results.
run (async: true): - Returns { ok: true, status: "started", execution_id } immediately. - Goes through Oban; survives daemon restart (idempotent resume — crash mid-run → row marked failed with reason "crashed-resume").
list_workflows: - Default: summary — name, file, description, size_bytes (no YAML body) - return: "full" — includes the YAML 'body' field for every workflow - select: "name1,name2" — return full bodies for the named workflows only
list_executions: - Default: summary — id, workflow, status, started_at, updated_at (no runtime blob) - return: "full" — includes 'runtime' JSON for every row (can be large) - select: "id,status" — return only the named fields per row
Use timeout to control client-side HTTP deadline, or "none" for no timeout.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Execution ID (for show/resume/detail/context/wait/watch). | |
| key | No | Context key to inspect (for context action) | |
| async | No | If true, run returns immediately with execution_id (run action only) | |
| force | No | Force deletion of running execution (for action=delete) | |
| limit | No | Max rows for list_executions (default 20) | |
| action | Yes | Action to perform | |
| params | No | JSON parameters for the workflow. Pass an object encoded as JSON, for example {"since":"2026-05-02T00:00:00+03:00","projects":["gc_daemon"],"mode":"draft"}. Use JSON arrays for list<string> params such as projects. | |
| reason | No | Dismiss reason (for action=dismiss) | |
| return | No | Response shape. run: "result" (default)/"full"/"steps"/"trace". list_workflows + list_executions: "summary" (default)/"full". | |
| select | No | Cherry-pick fields/steps. run: step IDs ("step_a,step_b"). list_workflows: workflow names (returns full body). list_executions: execution field names. Takes priority over return. | |
| status | No | Filter list_executions by status (running/completed/failed/halted) | |
| dry_run | No | Preview repair_stale without mutating | |
| timeout | No | Client-side HTTP timeout in seconds. Default: 300 (5 min) for run/resume, 15 for others. "none" / "infinity" / "infinite" disable timeout entirely. Accepts string-of-int ("600") so LLM stringification is safe. | |
| interval | No | Poll interval in seconds for wait (default: 5). Accepts string-of-int. | |
| workflow | No | Workflow name (for run/resume) | |
| run_timeout | No | Server-side workflow execution timeout in seconds for action=run only. Distinct from client timeout. "none" / "infinity" / "infinite" disable the server-side run deadline. | |
| execution_id | No | Execution ID (alias for id) | |
| include_hidden | No | Include hidden rows in list/prune (default false for list, true for prune) | |
| older_than_hours | No | Minimum age in hours for action=prune (default 24) | |
| execution_timeout | No | Alias for run_timeout |