Agent Workloads

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

Common Agent Workloads

This reference is the operational expansion for skills/agent-workloads/SKILL.md.

Joel Steering Inputs

When Joel is steering coding/repo work, capture these first:

• objective — the outcome, not the mechanism
• acceptance — what proves the work is done
• scope — repo(s), files, or subsystems that are in / out
• autonomy — inline, supervised, AFK, or blocked pending review
• proof posture — dry-run, canary, soak, full implementation
• risk posture — reversible only, sandbox required, deploy allowed, human sign-off needed
• sequence constraints — what must happen before what
• artifacts — patch, tests, summary, docs, ADR, deploy evidence, etc.

If two or more of those are fuzzy, stop and shape the workload before dispatch.

Map the task into the canonical schema

Use the vocabulary from docs/workloads.md.

Minimum shape for a sane plan:

{
  "kind": "repo.patch|repo.refactor|repo.docs|repo.review|research.spike|runtime.proof|cross-repo.integration",
  "shape": "auto|serial|parallel|chained",
  "mode": "inline|durable|sandbox|loop|blocked",
  "backend": "host|local-sandbox|k8s-sandbox|queue|restate|none",
  "autonomy": "inline|supervised|afk|blocked",
  "proof": "none|dry-run|canary|soak|full",
  "artifacts": [
    "patch",
    "tests",
    "verification",
    "summary",
    "docs",
    "adr",
    "handoff"
  ]
}

If your summary cannot fit that shape, the task is still mush.

First move when possible:

joelclaw workload plan "<intent>"

Then inspect the canonical request + plan output before dispatching anything. Read the guidance block too — that is where the planner now says whether to execute inline, tighten scope, or dispatch, which skills should be loaded/installed first, and what the approval → execute/watch → summarize loop should be.

Helpful ergonomics that are now real:

# seed scope from active repo work
joelclaw workload plan "<intent>" --repo /abs/repo --paths-from recent:3

# use a preset instead of restating the obvious shape every time
joelclaw workload plan "<intent>" --preset refactor-handoff

# write a reusable plan artifact
joelclaw workload plan "<intent>" --write-plan ~/.joelclaw/workloads/

# turn the saved plan into a stage-specific dispatch contract
joelclaw workload dispatch ~/.joelclaw/workloads/WL_20260308_191410.json --write-dispatch ~/.joelclaw/workloads/

Choosing the Shape

Serial

Use serial when:

• stage B depends on stage A being correct
• one operator needs to keep a tight feedback loop
• the work is risky or canary-driven
• docs/ADR truth must follow code truth immediately

Examples:

• bug triage → fix → verify → commit
• runtime canary → cleanup → truth update
• refactor → tests → deploy verification → docs

Few-shot setup/execution pattern:

1. install/repair any missing repo-local skills (joelclaw skills ensure <name>) 2. reserve the scoped files 3. do the bounded change 4. run narrow validation 5. commit the slice cleanly before moving on

Parallel

Use parallel when:

• branches are independent
• uncertainty is high and comparison is useful
• research or spikes can happen without overlapping files
• one lead agent will synthesize the branches later

Examples:

• compare two migration strategies
• inspect three codepaths in parallel
• spike local sandbox vs k8s sandbox vs loop path

Rules:

• each branch must have a clear goal
• each branch must own a non-overlapping file scope or stay read-only
• there must be one merge/synthesis owner

Few-shot setup/execution pattern:

1. split the work into independent branches before anyone edits 2. load/install the repo skill once, then dispatch branch-specific work 3. keep branch artifacts explicit (notes, diffs, comparisons) 4. run one synthesis pass that chooses the next path

Chained

Use chained when:

• different stages want different specializations
• artifacts should flow forward explicitly
• implementation is not the final stage

Examples:

• implement → verify → docs
• patch → canary → truth update
• research → planner → implementor → reviewer

Rules:

• downstream stage consumes artifacts, not vague conversation memory
• every stage has an explicit pass/fail contract
• if the prompt includes a Goal: section, keep those milestones visible instead of collapsing everything into execute primary work
• if the prompt includes Acceptance:, preserve it unless the caller explicitly overrides with --acceptance
• handoff text must say what changed, what remains, and what must not be re-litigated

Few-shot setup/execution pattern:

1. write the plan artifact up front 2. dispatch the right stage instead of re-planning from scratch 3. reserve the scoped files for the executing stage 4. execute the stage, validate narrowly, then either close out or dispatch the next stage

Bounded local slice posture

If the problem is one repo, one failing surface, and local verification is cheap, default to direct execution.

• shape it
• ask approved?
• reserve scope
• inspect → patch → verify → commit
• summarize outcome and ask whether to push

Do not widen that into dispatch, queue submission, or adjacent ops churn unless the operator explicitly asked for a wider blast radius.

Handoff Contract

Every handoff should include:

• workload id / story id / stage id
• goal
• current state
• artifacts produced
• verification already done
• remaining gates
• reserved files / released files
• known risks / caveats
• next command or next action

If the next worker has to reconstruct the plan from raw chat, the handoff is bad.

Workload Patterns

Single-pass patch

Use when the task is obvious and local.

Suggested schema:

{
  "kind": "repo.patch",
  "shape": "serial",
  "mode": "inline",
  "backend": "host",
  "artifacts": ["patch", "verification", "summary"]
}

Expected outputs:

• code diff
• verification output
• commit
• minimal summary

Scoped cleanup chain

Use when the work is still basically repo.patch, but the prompt carries multiple cleanup milestones and you need them to stay visible.

Suggested schema:

{
  "kind": "repo.patch",
  "shape": "chained",
  "mode": "inline",
  "backend": "host",
  "artifacts": ["patch", "verification", "summary", "handoff"]
}

Prompt pattern that works well:

• Goal: with semicolon-separated milestones
• Acceptance: with explicit completion criteria
• --paths-from recent:<n> or explicit --paths
• optional --write-plan when another agent will pick it up

Expected outputs:

• visible milestone stages instead of generic sludge
• preserved scoped paths on implementation stages
• optional reflect and update plan stage when the prompt asks for it
• a reusable plan artifact if requested
• a stage-specific dispatch contract via joelclaw workload dispatch when the work is ready to hand off
• dispatch guidance that says whether handing it off is actually smart, or whether the agent should just execute the selected stage now

Multi-step refactor

Use serial or chained.

Suggested schema:

{
  "kind": "repo.refactor",
  "shape": "chained",
  "mode": "sandbox",
  "backend": "local-sandbox",
  "artifacts": ["patch", "tests", "verification", "docs", "handoff"]
}

Expected outputs:

• stage checkpoints
• explicit regression checks
• follow-through docs/ADR updates

Parallel research / spikes

Use parallel with a synth owner.

Suggested schema:

{
  "kind": "research.spike",
  "shape": "parallel",
  "mode": "inline",
  "backend": "host",
  "artifacts": ["research-note", "comparison", "summary"]
}

Expected outputs:

• one finding note per branch
• recommendation with tradeoffs
• selected path

Implementation + review chain

Use chained.

Suggested schema:

{
  "kind": "repo.review",
  "shape": "chained",
  "mode": "sandbox",
  "backend": "local-sandbox",
  "artifacts": ["patch", "tests", "verification", "handoff", "summary"]
}

Expected outputs:

• implementation artifact
• independent verification artifact
• final judgment / next step

Supervised runtime drill

Use serial.

Suggested schema:

{
  "kind": "runtime.proof",
  "shape": "serial",
  "mode": "durable",
  "backend": "restate",
  "artifacts": ["telemetry-proof", "summary", "rollback-plan"]
}

Expected outputs:

• anchors (since, run ids, snapshot ids)
• earned / unearned proof
• cleanup evidence
• restored steady state

Selection Heuristics

Prefer:

• inline for obvious, local, low-risk work
• serial for dependent or risky work
• parallel for uncertainty reduction or independent branches
• chained when specialist stages add value

Avoid:

• parallel edits on the same files without a designated integrator
• giving a coding agent substrate docs when it really needs a workload plan
• “just use Restate” as a user-facing answer
• dispatching before acceptance / artifacts / risk posture are clear

joelclaw workload Surface

Shipped now:

joelclaw workload plan "<intent>"

Shipped now in addition to planning:

joelclaw workload dispatch <plan-artifact>

Still planned:

joelclaw workload run "<intent>"
joelclaw workload status <id>
joelclaw workload explain <id>
joelclaw workload cancel <id>

The contract should answer:

• what shape is this?
• what runtime path should carry it?
• why?
• what artifacts and gates exist?
• what should happen next?