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:

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:

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-workloads.md

Rules

• start with workload shape, not runtime mechanism
• use the canonical vocabulary from

  docs/workloads.md

  ; don't invent fresh field names unless the doc changes too
• implementation intent beats docs follow-through:

  refactor ... then update docs

  or

  extend ... then update README

  should still plan as implementation work
• preserve explicit

  Acceptance:

  clauses from the prompt when they exist; don't throw them away and replace them with mush
• mentioning a sandbox as the topic of research does not automatically mean the work must execute in a sandbox

• deploy-allowed

  should come from explicit release/deploy intent, not from nouns like

  published skills

• supervised repo work mentioning

  canary

  or

  soak

  does not automatically mean

  durable

  /

  restate

• use

  Goal:

  milestones and

  reflect/update plan

  cues to keep chained plans from collapsing into generic sludge
• if you are not inside the target repo and

  workload plan

  warns about the cwd not being a git repo, rerun with

  --repo

• use

  --paths-from status|head|recent:<n>

  when scope should come from actual repo activity instead of hand-typed path lists
• use

  --write-plan

  when another agent should be able to pick up the workload without reading raw chat
• use

  joelclaw workload dispatch

  when a saved plan should become a stage-specific handoff contract

• --write-dispatch

  is for reusable dispatch artifacts;

  --send-mail

  is for actually delivering the contract through clawmail
• never hand a coding agent substrate docs as the only answer to “how should I run this work?”
• serial / parallel / chained are first-class planning choices, not afterthoughts
• use

  clawmail

  for any delegated or shared-file workload
• keep outputs machine-usable and explicit
• if the best execution path is unclear, say so and produce a plan rather than guessing