workflow-rig

What this skill does

# Workflow Rig

Use this skill as the **canonical front door** for agent-driven work in joelclaw.

The user should not have to choose between `agent-workloads`, `restate-workflows`, queue internals, or runtime trivia.

If the user says the magic words —
- "run this through the workflow rig"
- "dogfood this with the workflow rig"
- "kick this off"
- "start a canary"
- "run this as a workload"

— load this skill first.

## What this skill owns

- workload shaping (`serial`, `parallel`, `chained`)
- choosing between inline work, durable runtime, or a pure handoff
- `joelclaw workload plan` / `dispatch` / `run`
- explicit stage DAGs via `--stages-from`
- honest runtime truth: what the restate-worker can do today, and what it still cannot do
- canary/dogfood posture for real workload proofs

## Core rule

**Intent first, substrate second.**

The caller describes the work.
The workflow rig chooses the narrowest honest execution path.

Do not push Redis vs Restate vs sandbox trivia back onto the caller unless that tradeoff is the actual decision.

## Current proven state (as of 2026-03-17, session StubbornFerret)

- `joelclaw workload plan`, `joelclaw workload dispatch`, and `joelclaw workload run` are real.
- Proven durable path: `joelclaw workload plan` → Redis queue → Restate `dagOrchestrator` → `dagWorker` → execution.
- Multi-stage DAGs with `dependsOn` are proven across 3-5 stage pipelines. Downstream stages can consume earlier outputs via `{{nodeId}}` interpolation.
- `--stages-from stages.json` is proven: duplicate ids, unknown deps, self-deps, and cycles are rejected before runtime admission; critical path and phase grouping are calculated.
- `shell` handler ✅ runs commands in the k8s `restate-worker` pod. Git clone, pi agent file writes, git commit, and git push are proven.
- `infer` handler ✅ **full pi agent with tools** — read, edit, write, bash. `pi -p` mode enables all tools. It can read files, edit them, run commands, and produce working code changes. Not just text generation — full agent-style codegen.
- `microvm` handler ⏸️ code works (one-shot exec model proven via bun test in pod) but ADR-0230 is **paused** — Colima nestedVirtualization crashes the VM under load. Don't use.
- The `restate-worker` image is a full agent environment: pi 0.58.4, 76 skills, GitHub push auth from k8s secret, pi auth mounted from host (stays fresh).
- Autonomous codegen proven: infer handler reads files + edits them via pi tools. Shell handler handles git clone/commit/push. Chain them in a DAG for full autonomous coding loops.
- Pre-cloned repo cache at `/app/repo-cache` (~200ms copy vs ~3s clone). `dagWorker` uses 15m inactivity timeout and 30m hard abort.
- Retry caps: dagWorker maxAttempts=5, dagOrchestrator maxAttempts=3. No more infinite retry poisoning.

## What does not work yet

- `microvm` handler paused (ADR-0230) — needs dedicated Linux hardware with native KVM
- DAG completion notifications to the gateway not wired (operators poll or check OTEL)
- large-file pi agent edits can be slow (3-5 minutes) but succeed within the 15m timeout

## Canonical operator flow

1. Shape the work with `joelclaw workload plan`
2. Present the shaped workload and ask **approved?**
3. After approval:
   - execute inline if it is bounded, local, and reversible
   - use `joelclaw workload run` for real durable execution
   - use `joelclaw workload dispatch` only for a real baton pass
4. If you enqueue runtime work, poll for progress with `joelclaw runs`, `joelclaw run <run-id>`, or OTEL. There is no automatic completion ping yet.
5. Report outcome tersely: changed, verified, remaining, next move

## Magic words → canonical commands

### Plan only
```bash
joelclaw workload plan "<intent>" --repo <repo> [--paths a,b,c] [--stages-from <path>] [--write-plan <path>]
```

### Real runtime canary / dogfood
```bash
joelclaw workload run <plan-artifact> \
  [--stage <stage-id>] \
  [--tool pi|codex|claude] \
  [--timeout <seconds>] \
  [--model <model>] \
  [--execution-mode auto|host|sandbox] \
  [--sandbox-backend local|k8s] \
  [--sandbox-mode minimal|full] \
  [--repo-url <git-url>] \
  [--dry-run] \
  [--skip-dep-check]
```

### Handoff, not execution
```bash
joelclaw workload dispatch <plan-artifact> \
  [--stage <stage-id>] \
  [--project <mail-project>] \
  [--from <agent>] \
  [--to <agent>] \
  [--send-mail] \
  [--write-dispatch <path>]
```

## Sandbox mode guidance

Use `--sandbox-mode full` when the proof needs real runtime surfaces:
- service/network lifecycle
- full environment materialization
- cleanup evidence
- anything where a minimal local sandbox would hide the real failure mode

Use `--sandbox-mode minimal` for cheap code/doc/test slices where full runtime provisioning is overkill.

Use `--stages-from` when you already have a real stage DAG. The planner preserves per-stage acceptance, validates dependencies/cycles, calculates critical path metadata, and keeps the DAG instead of collapsing it into template stages.

Use `--skip-dep-check` only for deliberate manual recovery. Normal `joelclaw workload run` blocks a stage until its explicit dependencies have terminal truth.

Do **not** use `microvm` — ADR-0230 is paused. Colima nestedVirtualization is unstable. Use `shell` + `infer` for all work.

## Current runtime truth

- `joelclaw workload run` is the real bridge from workload artifacts to runtime admission.
- The durable path is Redis queue admission → Restate `dagOrchestrator` → `dagWorker`.
- `dagOrchestrator` resolves dependency waves correctly for chained multi-stage DAGs.
- `{{nodeId}}` interpolation is proven for passing upstream outputs into downstream stages.
- The `shell` handler is the proven path for git operations (clone, commit, push) and arbitrary CLI work.
- The `infer` handler is a **full pi agent** — it reads, edits, and writes files via tools. Use it for codegen, analysis, and any task that benefits from LLM + file access.
- Chain `infer` (edit files) → `shell` (git commit + push) for autonomous coding loops.
- The `microvm` handler is paused (ADR-0230). Do not use.
- Completion is poll-based for now. No gateway finish event is emitted when a DAG lands.

## Real chained example

This is an honest four-stage shape the rig can run today:

```json
[
  {
    "id": "research",
    "name": "Research current state",
    "acceptance": ["Facts gathered"],
    "executionMode": "manual"
  },
  {
    "id": "plan",
    "name": "Turn research into an execution plan",
    "dependsOn": ["research"],
    "acceptance": ["Implementation plan written"],
    "executionMode": "manual"
  },
  {
    "id": "implement",
    "name": "Apply the change in the worker",
    "dependsOn": ["plan"],
    "acceptance": ["Requested files updated", "Commit pushed"],
    "executionMode": "pi",
    "notes": "Use {{plan}} as the downstream input."
  },
  {
    "id": "verify",
    "name": "Verify and summarize",
    "dependsOn": ["implement"],
    "acceptance": ["Verification captured", "Closeout ready"],
    "executionMode": "manual",
    "notes": "Use {{implement}} for verification context."
  }
]
```

Run it through the front door:

```bash
joelclaw workload plan "Research, plan, implement, then verify the change" \
  --repo ~/Code/joelhooks/joelclaw \
  --stages-from stages.json \
  --write-plan plan.json
```

## When to reach for compatibility skills

- `agent-workloads` — only when an older prompt already names it; treat it as a compatibility alias
- `restate-workflows` — only when the work is specifically about external-repo runtime bridging or low-level substrate contracts

## Dogfood posture

When proving runtime work:
- prefer a canary first
- use the real front door (`joelclaw workload run`), not hand-rolled `system/agent.requested`, unless you are debugging below the rig
- capture honest evidence from queue admission, Restate, `dagWorker`, and resulting git/verification artifacts
- poll the run yourself; there is no completion event to the gateway yet
- inside a sandbo