# Workflows and watchdogs Documented against OpenRig 0.5.14. Help text uses "node" where these pages say **seat**, for a seat's position in the running rig. ## What it is for A workflow turns an intended sequence of work into durable state. You write a spec as a plain file, start an instance of it, and the daemon tracks where that instance is: which step is active and who owns it. When a step's owner closes it, the runtime records the closure and projects the next step's queue row in one transaction, so nobody has to carry the work between seats by hand. The owner decides when a step is done; the runtime is the scribe, not the gate. A watchdog is the alarm you set for yourself, because a seat cannot wake itself. Jobs are persisted in the database and survive daemon restarts. A job can fire a periodic reminder, wait for a pool of artifacts, keep a workflow moving, gate on an idle queue, or watch a seat's context usage and act before the wall. ## The three commands you will use first **Start an instance from a spec.** `--rig` binds it to a rig so roles resolve to seats there. ``` rig workflow instantiate workflows/conveyor.workflow.md --root-objective "Ship the search page" --rig my-rig ``` **Close your step and let the next one appear.** One daemon transaction: close the current packet, project the next. ``` rig workflow project --instance --current-packet --exit handoff --result-note "candidate ready" ``` **Ask what needs you.** `status` answers "what needs me" with counts and one row per failed, stuck or waiting instance, plus the next action; `list` answers "what exists". ``` rig workflow status rig workflow list ``` ## Arming a wake `rig watchdog register` takes a policy: periodic-reminder, artifact-pool-ready, edge-artifact-required, workflow-keepalive, idle-gate-qitem, or context-usage-threshold. A parked queue row can attach a live watchdog id as its wake. `list`, `show` and `status` tell you whether a job fired and whether it is still live; quiet skips are not recorded, so an idle job and a job that never ran can look alike until you read `show`. ``` rig watchdog register --policy context-usage-threshold --target-session dev-impl@my-rig rig watchdog list rig watchdog status ``` ## The workflow and watchdog families [//]: # (table:start) | Command | What it does (from help) | Help source | |---|---|---| | `rig watchdog` | Coordination Watchdog , daemon-native scheduler for reminders, artifact gates, workflow health, idle gates, and context usage | watchdog.txt | | `rig watchdog list` | List watchdog jobs (default: active + compact + at most 100) | watchdog.list.txt | | `rig watchdog register` | Register a watchdog; queue block --wake-watchdog attaches its job id. Context transcripts measured 113K–153K tokens/MB. The margin is the protection because prompt-bound consumers act only at turn boundaries | watchdog.register.txt | | `rig watchdog show` | Show one watchdog job | watchdog.show.txt | | `rig watchdog status` | Show one watchdog job + recent evaluation history | watchdog.status.txt | | `rig watchdog stop` | Stop a watchdog job (operator-stopped; scheduler skips it) | watchdog.stop.txt | | `rig workflow` | Daemon-native Workflow Runtime , declarative spec + transactional-scribe step projection (PL-004 Phase D) | workflow.txt | | `rig workflow abort` | Transactionally cancel every live packet and abort the whole workflow instance | workflow.abort.txt | | `rig workflow compile` | Compile project.yaml → mission.yaml → slice.yaml into an inspectable lifecycle graph (read-only) | workflow.compile.txt | | `rig workflow continue` | Inspect an instance's current frontier + step trail (read-only; advancing happens via 'rig workflow project') | workflow.continue.txt | | `rig workflow guidance` | Read current selected SDLC teaching, original intent and authored/bound provenance | workflow.guidance.txt | | `rig workflow instantiate` | Create a workflow instance + entry-step qitem from a spec | workflow.instantiate.txt | | `rig workflow instantiate-lifecycle` | Compile and instantiate an eligible lifecycle; recover a lost response with workflow operation | workflow.instantiate-lifecycle.txt | | `rig workflow list` | List workflow instances; optionally filter by status | workflow.list.txt | | `rig workflow operation` | Recover a lifecycle creation or revision effect by its stable key, even after a lost response or source edit | workflow.operation.txt | | `rig workflow project` | Close a current packet AND project the next-step packet (transactional-scribe; one daemon transaction) | workflow.project.txt | | `rig workflow resume` | Redrive a FAILED instance from its failed step (completed steps never re-run; one fresh max_hops window) | workflow.resume.txt | | `rig workflow revise` | Compare authored and running lifecycle graphs; deliberately adopt compatible changes without replaying work | workflow.revise.txt | | `rig workflow route` | Re-route the current frontier step to a new owner (same step, honest handoff closure; never advances) | workflow.route.txt | | `rig workflow run` | Instantiate a workflow AND follow it live to a terminal state (exit 0 completed / 3 failed) | workflow.run.txt | | `rig workflow show` | Show current work, exception-owner readiness and existing exception obligations | workflow.show.txt | | `rig workflow specs` | List registered workflow specs; built-in starters tagged with (built-in) | workflow.specs.txt | | `rig workflow status` | Which instances need attention: counts + one row per failed/stuck/waiting instance with reason + next action (read-only) | workflow.status.txt | | `rig workflow trace` | Show one workflow instance + its append-only step trail (audit-only verdict) | workflow.trace.txt | | `rig workflow validate` | Validate a workflow spec file (returns structured ok/error report) | workflow.validate.txt | | `rig workflow watch` | Attach to an in-flight instance and follow it live (read-only; exit mirrors the outcome) | workflow.watch.txt | [//]: # (table:end) ## What it does not do - `rig workflow continue` is read-only despite its name; `project` is the verb that advances. - The runtime does not judge whether a step was done well. Closure authority stays with the queue's closure rules; acceptance stays with the next stage. - `compile` and `revise` are for lifecycle graphs authored in project, mission and slice files; they inspect and adopt changes without replaying completed work. Editing the source file alone does not change a running instance. - A watchdog with a stale message is worse than none. When the thread it refers to closes, stop it or rewrite it. ## Where it goes next - [Coordination](/docs/coordination): the queue rows a workflow projects and the closure reasons it records. - [The work tree](/docs/work-tree): the project, mission and slice files a lifecycle graph is compiled from.