Docs / Workflows / Chaining tasks

Chaining tasks

Chaining connects one scheduled duty to the next so multi-step work runs without you clicking each stage. Reliable pipelines use a single source of truth — usually ~/files/{pipeline-name}/state.json — plus explicit wiring in the dashboard. Recipe deploy sets both; manual workflows need you to design them. See workflows hub and recipe system.

Two ways to hand off

• Run next (next_job_id) — static chain configured on the Team Task Board or at recipe deploy. When duty A finishes successfully, duty B runs automatically. Best for fixed pipelines (research → write → publish on a schedule).
• trigger_duty tool — dynamic handoff from inside an LLM run: the agent picks a target Specialist/duty and fires it now (or reports already running). Best when the next step depends on runtime judgment.

Use one pattern per pipeline segment — do not assume both fire for the same completion. Cycles in Run next links are rejected at save time.

Design a state file

Convention: ~/files/content-pipeline/state.json (replace the folder name with your pipeline). Keep JSON small:

• Items array — each row has id, title or topic, status, error_count, updated_at.
• One item per run — each duty picks the first row matching the status it owns (for example first planned, then first generated). Avoid batching unless you explicitly asked for it.
• One-way statuses — example: planned → generating → generated → publishing → published. Terminal skipped after repeated failures (preset recipes use error_count >= 3).
• Artifacts beside state — write markdown or CSV under ~/files/{pipeline}/output/ or reports/; state holds pointers and status only.

Every duty prompt should name the state path, read it at start, save before exit, and append dated notes to a notes/ folder instead of overwriting history blindly.

Guardrails

• Checkpoint after major artifacts — long chains should produce a file or state transition before the next Specialist runs.
• Explicit ready flags — downstream duties only look for the status they own; no implicit “guess the last message.”
• Error notes — on failure, increment error_count and leave a short reason in state or notes/ so the next run or you can diagnose.
• One canonical state.json — delete stray state (2).json duplicates from the Files tab; numbered copies usually mean accidental non-overwrite writes.
• Concurrent edits — prefer partial JSON updates when two duties might overlap; if a write conflicts, re-read state and retry.

When the next duty runs

Run next fires after a scheduled run completes with a normal finish (not when the provider filters or aborts mid-flight). Only one chain fire per duty execution — duplicate webhook events are deduped. If your account is out of AI credits, continuation turns on an already-running chain may soft-stop with a limit error; the first turn of a cron tick still runs — see limits FAQ.

Team Task Board

The board visualizes static Run next chains (LLM-driven trigger_duty links are not drawn on the graph):

• Upstream badge — which duty must complete before this one starts.
• Downstream badge — which duty fires next on success.
• Run next editing — change the target from the task card without opening deep settings.

The Workflows tab loads the same pipeline graph, run history, optional state.json preview, and health hints.

When a chain stalls

1. Open the duty thread — read the last tool trace and whether state was saved.
2. Inspect ~/files/... in the dashboard Files tab — is the expected output missing?
3. Check state.json — is any row stuck in generating or publishing?
4. Fix or skip the row (set skipped), delete duplicate state files, re-run manually once before trusting cron again.

Deeper fixes: scheduling troubleshooting · general troubleshooting · status.

Related: Threads & memory (dedicated thread per duty) · File editing · File management