agent-workloads

What this skill does

# Agent Workloads

This skill is now a **compatibility alias**.

For new work, load **`workflow-rig`** first. That is the canonical front door for workload planning, runtime mode selection, and workflow-rig dogfood.

Keep using this skill only when an older prompt already names `agent-workloads` or when you need the historical workload-planning guidance below.

If the work is really about external repo bridging or low-level runtime submission mechanics, _then_ the `restate-workflows` skill may matter. For normal coding/repo work, this skill comes first.

## What this skill is for

- turning Joel steering into an execution shape
- choosing between **serial**, **parallel**, and **chained** work
- deciding whether a task should stay inline or move to a durable/sandboxed path
- defining the handoff contract between workers
- keeping repo/coding work agent-first instead of runtime-first

## Load Order

For serious workload design, also load:

- `cli-design` — future `joelclaw workload` surface and JSON contract
- `clawmail` — reservations, ownership, and handoffs
- `system-architecture` — real runtime topology
- `docker-sandbox` — isolation/backends when execution mode matters
- `codex-prompting` — if the workload will dispatch coding agents downstream

Canonical repo doc:

- `docs/workloads.md` — source of truth for workload vocabulary, request/plan/handoff schema, and shipped-vs-planned boundaries

## Core rule

**Do not make the caller choose the substrate unless that tradeoff is the task.**

And do not let an approved bounded local slice drift into planner/dispatch/queue theatre just because those surfaces exist.

The caller should describe intent.
The planner should decide execution.

Bad:

- “Should I use Restate or queue or sandbox or a loop?”

Good:

- “This is a chained repo workload with sandboxed implementation, inline verification, and docs closeout.”

## First pass: classify the workload

Ask or infer these inputs:

- workload kind (`repo.patch`, `repo.refactor`, `repo.docs`, `repo.review`, `research.spike`, `runtime.proof`, `cross-repo.integration`)
- objective
- acceptance criteria
- repo / file scope
- shape (`auto`, `serial`, `parallel`, `chained`)
- autonomy level
- proof posture (`none`, `dry-run`, `canary`, `soak`, `full`)
- risk posture (`reversible-only`, `sandbox-required`, `host-okay`, `deploy-allowed`, `human-signoff`)
- sequence constraints
- required artifacts

If those are fuzzy, shape the workload before dispatch.

## Choose the shape

### Serial

Use when steps depend on each other or risk is high.

Examples:

- fix → verify → commit
- canary → cleanup → truth update
- refactor → deploy check → docs

### Parallel

Use when branches are independent and comparison helps.

Examples:

- spike multiple approaches
- inspect multiple codepaths in parallel
- gather evidence from several repos/surfaces before synthesis

### Chained

Use when specialist stages add value and artifacts should flow forward.

Examples:

- implement → verify → docs
- research → planner → implementor → reviewer
- patch → canary → ADR truth

## Default execution bias

- prefer **inline** for obvious low-risk local tasks
- prefer **serial** for risky or dependent work
- prefer **parallel** to reduce uncertainty, not to look clever
- prefer **chained** when artifacts and stage boundaries matter
- prefer **sandboxed** execution when repo mutation is risky or isolation is the point

## Operator loop

Canonical posture for coding/repo work:

1. operator gives intent + context
2. agent returns a shaped workload plan
3. agent asks **approved?**
4. once approved, follow `guidance.executionLoop.approvedNextStep` instead of re-planning
5. while work is running, let the pi extension/TUI show honest status at real stage boundaries
6. finish with a terse outcome summary: what changed, what was verified, what remains, and whether the next move is push / handoff / stop

For a **bounded local slice** (`mode=inline`, local repo, explicit paths, cheap verification), the honest default is:

- reserve scope
- execute inline
- verify
- commit
- ask whether to push

Not:

- dispatch ceremony
- queue/restate submission theatre
- adjacent ops churn the operator did not ask for

## Handoff rule

Every downstream worker should receive:

- goal
- current state
- artifacts produced
- verification already done
- remaining gates
- reserved file scope
- known risks/caveats
- exact next action

If the next worker has to reconstruct everything from chat history, the workload was shaped badly.

## Runtime boundary

This skill is the **product layer**.

Substrate skills remain implementation details:

- `restate-workflows` — external repo/runtime bridge details
- `docker-sandbox` — isolation/backends
- `agent-loop` — durable coding loop mechanics

Use them only after the workload shape is clear.

## Command surface

Shipped now:

```bash
joelclaw workload plan "<intent>" \
  [--preset docs-truth|research-compare|refactor-handoff] \
  [--repo /abs/path/or/owner/repo] \
  [--paths a,b,c] \
  [--paths-from status|head|recent:<n>] \
  [--write-plan ~/.joelclaw/workloads/]

joelclaw workload dispatch <plan-artifact> \
  [--stage stage-2] \
  [--to BlueFox] \
  [--from MaroonReef] \
  [--send-mail] \
  [--write-dispatch ~/.joelclaw/workloads/]

joelclaw workload run <plan-artifact> \
  [--stage stage-2] \
  [--tool pi|codex|claude] \
  [--execution-mode auto|host|sandbox] \
  [--sandbox-backend local|k8s] \
  [--dry-run]
```

Use `plan` to get the canonical `request` + `plan` envelope, seed scope from real repo activity, and emit a reusable plan artifact. The CLI now also returns `guidance` so the agent gets:

- `recommendedExecution` — execute inline now vs tighten scope first vs dispatch after health check
- `operatorSummary` — plain-spoken next-step recommendation
- `adrCoverage` — which ADRs likely govern the slice already; on fresh repo-local ADR clusters, reconcile nearby follow-on ADRs before declaring coverage complete
- `recommendedSkills` — including `joelclaw skills ensure <name>` for local repo skills or `npx skills add -y -g <source>` for external ones
- `executionExamples` — serial / parallel / chained coding-task few-shot setup + execution examples
- `executionLoop` — the honest plan → approve → execute/watch → summarize contract, including what to do immediately after approval

Use `dispatch` to turn a saved plan into a real handoff contract instead of retyping the whole bloody thing. The CLI now also returns dispatch guidance so it can say when dispatch is overkill for a bounded inline slice, when to health-check before handing off, when the recipient still needs to be made explicit, and what the approval/progress/closeout loop should look like.

Use `run` when the plan is approved and should enter the queue-backed runtime through one canonical bridge. It normalizes the saved plan into `workload/requested` → `system/agent.requested` instead of forcing the operator to hand-roll `joelclaw queue emit` payloads.

Still planned:

```bash
joelclaw workload status <id>
joelclaw workload explain <id>
joelclaw workload cancel <id>
```

Until the rest exists:

1. run `joelclaw workload plan`
2. read the returned `guidance` before doing anything cute
3. present the plan, then ask **approved?**
4. once approved, follow `guidance.executionLoop.approvedNextStep`
5. if `recommendedExecution=execute-inline-now`, reserve the scoped files and just do the work
6. if `recommendedExecution=tighten-scope-first`, rerun the planner with explicit `--paths` or `--paths-from ...`
7. if the approved plan should enter the queue-backed runtime, run `joelclaw workload run` instead of hand-rolling `queue emit`
8. if another worker should take it first, save the plan and run `joelclaw workload dispatch`
9. deliver the dispatch contract through clawmail when appropriate
10. keep the handoff explicit and report the final outcome tersely

## Reference

Read the detailed workload catalog here:

- [references/common-