Complete Workflow Guide: Pods, Dispatch, and the Org Team
Status: Production Guide
See also: Agent Teams (Pods) is the canonical reference for docket's agent-team model (scope vs. role, the pipeline, isolation). This guide shows that model in end-to-end use — provisioning a pod, growing it, queueing work, and running the real dispatch loop. Read Agent Teams first; read this for the worked examples.
The Three Actors
1. Engineer (You)
The human who:
- Creates projects (each becomes a pod)
- Sends tasks (CLI docket pod … delegate, or /delegate from a Telegram chat bound to a pod's Lead)
- Reviews diffs and commits the code
- Makes architectural decisions and approves any HITL gates
- Sets budget caps and watches measured token usage
2. Project Pods
One pod per project/codebase, created with docket init. A pod is a small team of
project-scoped agents (scope: project) that owns exactly one codebase — never shared with
another project:
- Lead (
<project>-lead) — orchestrates the pod, owns its memory + human (Telegram) comms, decomposes work and dispatches it. Never edits code. - Implementer (
<project>-implementer) — runs inside the project workspace and writes the code. - Reviewer (optional) — read-only veto on the diff (correctness + security gate).
- Tester (optional) — behaviour-only PASS / FAIL validation.
The default pod is lean (Lead + Implementer). Add Reviewer/Tester when the work warrants it.
3. Org Specialists
A shared team created lazily by the first docket init — genuinely cross-cutting, one instance for
the whole fleet (scope: org):
- manager — cross-cutting coordination (transitional; it has no task queue of its own — per-pod dispatch is the only queue — so this role is being superseded by per-pod Leads).
- knowledge — documentation, research, pattern extraction across projects.
- security — deep security audits and threat modelling.
- portfolio-manager (optional,
docket init --portfolioon the first init) — advisory cross-pod planner over fleet metadata (which pods exist, their queues, budgets, health). Never a pod member, never edits code, never dispatches into pods.
Implement/review/test are per-pod roles, each with its own isolated workspace, so no worker agent ever serves two projects.
Architecture Overview
┌─────────────────────────────────────────────────────────────┐
│ ENGINEER (You) │
│ • delegate tasks (CLI or Telegram) • review diffs + commit│
│ • set budget caps • approve HITL gates │
└──────────────┬───────────────────────────────┬──────────────┘
│ │
per-project │ pod pipeline cross-cutting│ advisory only
▼ ▼
┌──────────────────────────┐ ┌──────────────────────────┐
│ Pod: myapp │ │ Org specialists (shared)│
│ ┌────────────────────┐ │ │ manager · knowledge · │
│ │ lead (never edits)│ │ │ security · portfolio-mgr│
│ └─────────┬──────────┘ │ │ (advisory, no code) │
│ ▼ │ └──────────────────────────┘
│ implementer → reviewer? │
│ → tester? │ ← `docket pod myapp dispatch`
└──────────────────────────┘ one real agent turn per hop
Each pod is isolated: its own per-member workspaces (700/600), its own session-key
namespace (agent:<project>:…), its own queue. There is no cross-pod dispatch path.
End-to-End: a pod from init to committed code
This is the headline workflow — provision a pod, grow it when the work earns it, queue a task, dispatch the real pipeline, then inspect the trace, queue, and cost.
Step 1 — Provision a lean pod
docket init myapp ~/code/myapp # or: cd ~/code/myapp && docket init
# creates two project-scoped agents:
# myapp-lead (orchestrator, never edits code)
# myapp-implementer (writes code inside ~/code/myapp)
docket pod myapp # inspect the pod and its roles
docket list # every pod member shows up like any other agent
A lean pod is the right default for prototyping and low-risk changes: one owner of completion
(the Lead) and one doer (the Implementer). A repository with a committed .docket/ gets that team
instead (validated before anything is provisioned, applied after), and docket init --recipe
secure-build starts from a shipped recipe; see
Configuration §3.11.
Step 2 — Set a budget cap on the Lead
Dispatch is budget-gated against the Lead's cap, so set it before you run work:
docket profile myapp-lead --budget 5 # cap pod spend at $5 (token-based estimate)
Before each hop, docket compares the pod's token-based dollar estimate to this cap — docket's
own turn loop reports real, measured token counts but no billed dollar figure, so the gate always
runs off the labelled estimate (core/dispatch.py's pod_gating_cost), never a claimed "recorded
spend". Over budget → the task is set to blocked and the Lead is paused, never silently
run.
Step 3 — Grow the pod when the work warrants it
A login bug touching auth deserves a correctness/security gate and independent validation, so add a Reviewer and a Tester:
docket pod myapp add reviewer # adds myapp-reviewer (read-only veto on the diff)
docket pod myapp add tester # adds myapp-tester (behaviour-only PASS/FAIL)
docket pod myapp # now: lead, implementer, reviewer, tester
You could have provisioned this up front with
docket init myapp ~/code/myapp --pod fullor--with reviewer,tester. From inside~/code/myapp,docket add reviewerdoes the same asdocket pod myapp add reviewer. The pod also scales doers:docket pod myapp add implementeraddsmyapp-implementer-2for parallel work. A pod always has exactly one Lead.
Step 4 — Delegate a task to the pod
docket pod myapp delegate "Fix the null-token login crash"
docket pod myapp delegate --priority high "Patch the open-redirect on /auth/callback"
The task lands on the pod's own queue (owned by the Lead). Nothing runs yet — delegation only
queues. Each task gets an id (task-<uuid>) and its own per-task trace session
(agent:myapp:<task_id>) so tasks never bleed into each other.
Step 5 — Inspect the queue
docket pod myapp queue
Pod queue — myapp
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID ┃ PRI ┃ STATUS ┃ COST ┃ DESCRIPTION ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ task-6443ff59-cfca │ normal │ pending │ — │ Fix the null-token login crash │
│ task-9c745f95-984d │ high │ pending │ — │ Patch the open-redirect on /auth/callback │
└────────────────────┴────────┴─────────┴──────┴───────────────────────────────────────────┘
Step 6 — Dispatch the pipeline (the real hand-off)
docket pod myapp dispatch
docket drives every pending task through the pod's pipeline, highest priority first, one real, costed agent turn per hop — and only through the roles this pod actually has:
Lead → Implementer → Reviewer → Tester
→ Dispatching 2 pending task(s) through: lead → implementer → reviewer → tester
Pod budget cap: $5.00 (spent $0.00)
[dispatch] verification skipped — verifyCmd not set for myapp-implementer
✓ [task-9c745f95-984d-497b-abdd-1bed9ec9b0b0] done — 4 hop(s), $0.0000
[dispatch] verification skipped — verifyCmd not set for myapp-implementer
✓ [task-6443ff59-cfca-41a5-9ca0-f8686233e0bf] done — 4 hop(s), $0.0000
The per-task dollar figure is recorded cost, and docket's own driver never records one, so it
reads $0.0000; the budget gate uses the labelled token estimate instead (Step 2). The command
exits 1 when a task's run ends failed, so docket pod myapp dispatch && … stops there;
blocked, waiting_approval and waiting_input are expected pauses and exit 0. An unattended
ask — under this same dispatch off a TTY, or under serve --dispatch's sweep — resolves to
waiting_approval without blocking the turn at all (approvalMode: park, the default for an
unattended caller); see SECURITY-SIMPLE.md's operator-loop section and
CONFIGURATION.md §3.15 for
how a human finds out and answers.
docket stays the orchestrator: it invokes each hop through its own turn loop
(core/agent_loop.py), captures the result, and threads it to the next role. The Lead plans,
the Implementer is the single writer, the Reviewer can veto the diff, the Tester gives
an independent PASS/FAIL.
Step 7 — Budget gating in action
Say the pod's estimate crosses its cap partway through a task:
docket pod myapp dispatch
⚠ [task-6443ff59-cfca-41a5-9ca0-f8686233e0bf] blocked — pod budget reached (~$5.02 (estimated — no cost recorded) ≥ $5.00) before implementer
Over-budget tasks are blocked between hops, not abandoned mid-write, and the pod's Lead is paused so no further task is claimed. Raising the Lead's cap un-blocks the pod's budget-blocked tasks and clears the pause; then re-dispatch:
docket profile myapp-lead --budget 10
docket pod myapp dispatch
Step 8 — Inspect the trace
Every hop emits a trace event on the per-task session, so a run is fully auditable with no manual Telegram relay:
docket trace tail myapp # follow the latest session live
docket trace agent:myapp:task-9c745f95-984d-497b-abdd-1bed9ec9b0b0 # just this task's pipeline
Each line is timestamp event_type (role) plus any status and cost/duration fields, for
example (abridged):
2026-09-18T12:01:04 session_start (lead)
2026-09-18T12:01:05 tool_call (lead)
2026-09-18T12:01:05 tool_result (lead)
2026-09-18T12:01:09 tool_call (implementer)
...
2026-09-18T12:01:41 session_end (lead) status=done
The same session is what a trace exporter sends when you enable one: a docket.session span
with a child span per model call and per tool call, so Langfuse or an OpenTelemetry backend
shows the pipeline hop by hop. What each span carries depends on the exporter's privacy level,
structure only by default; docket exporters preview <name> --session <id> prints it for this
exact session before anything is sent
(Configuration §3.14).
Step 9 — Check the cost
docket pod myapp queue # per-task status (COST is recorded spend, so it reads — today)
docket cost # measured token usage across every agent
docket cost myapp-implementer # one agent's measured tokens (no recorded dollar spend)
Token counts are real and measured. Dollar figures are not — docket's own turn loop reports
no billed spend, so docket cost reports "none recorded" for dollars rather than inventing a number.
(The bundled pricing table only powers the budget gate's labelled estimate and docket models'
comparative display — docket never projects dollar savings.) See
Cost reporting and its limits.
Step 10 — Review and commit
docket leaves the commit to you — the Implementer wrote the code, but you own the merge:
cd ~/code/myapp
git diff # review the Implementer's changes
git add -p
git commit -m "Fix open-redirect on /auth/callback"
git push
The Lead records the outcome in the pod's memory log
(~/.docket/workspaces/projects/myapp-lead/memory/YYYY-MM-DD.md).
Autonomous dispatch (opt-in)
docket pod <project> dispatch is a one-shot, run-it-now command. To let docket drain every
pod's queue continuously, run the background loop with the dispatch flag:
docket serve --dispatch # background: drive every pod's queue on each refresh
docket serve # READ-ONLY monitor — health checks only, never dispatches
Because every hop is a real, costed LLM turn, dispatch is never silent: it is either explicit (
docket pod … dispatch) or opt-in (docket serve --dispatch). Plaindocket serveonly watches health. Budget caps gate the autonomous loop exactly as they gate a manual dispatch — an over-budget pod's tasks are set toblocked(notpending) and the pod's Lead is paused. A blocked task does not resume on its own: raise the Lead's cap (docket profile <lead-id> --budget N) or rundocket profile <lead-id> --resume, either of which unpauses the Lead and unblocks the pod's budget-blocked tasks, or requeue one withdocket pod <project> queue --retry <task-id>. Leaving them blocked is deliberate — rewriting them straight back topendingwas the bug that let a budget-capped task retry forever on every sweep.
Pipelines: the one dialect docket runs
Everything in Step 6 above — Lead → Implementer → Reviewer → Tester, one hop per role — is
docket's built-in pipeline. It is not hardcoded prose; it is a real, typed pipeline document
(core/pipeline.py) that docket pod <project> dispatch runs whenever a pod has no pipeline
file of its own. Writing a pipeline file lets you change the step order, add a parallel fan-out,
or swap in a different gate — without touching pod membership at all.
Zero migration: nothing changes until you opt in
A pod with no pipeline file behaves exactly like core/dispatch.py's hardcoded pipeline
always has: Lead (no gate) → Implementer (mechanical check against its own verifyCmd) →
Reviewer (APPROVE/REQUEST-CHANGES, bounded rework back to the Implementer) → Tester
(PASS/FAIL, hard gate, no rework). A lean pod without a Reviewer/Tester simply never reaches
those steps — same skip-absent-roles behavior docket pod <project> dispatch always had.
Installing this feature changes nothing about an existing pod until you write a file and pass
--file.
docket pipeline validate — check a file before you point a pod at it
Pure structural validation, no project or pod involved. Every level of the document rejects an unrecognized key — a typo fails loudly instead of being silently ignored:
$ docket pipeline validate workflows/release.yml
✓ Pipeline 'workflows/release.yml' is valid
$ docket pipeline validate workflows/broken.yml
✗ Error: Pipeline 'workflows/broken.yml' is invalid:
✗ steps.0.verifyCommand: Extra inputs are not permitted
docket pipeline plan — see what would actually run, without running it
plan renders straight from the real executor (core.orchestrator.resolve_plan/render_plan)
— never a second, drift-prone pretty-printer, and never a token spent:
$ docket pipeline plan myapp
Pipeline plan — myapp
Source: built-in default
Pipeline: default
[lead] role=lead -> myapp-lead [gate: none]
[implementer] role=implementer -> myapp-implementer [gate: mechanical(verifyCmd)]
[reviewer] role=reviewer -> myapp-reviewer [gate: verdict(approve, rework->implementer)]
[tester] role=tester -> myapp-tester [gate: verdict(pass)]
A lean pod (no Reviewer/Tester) shows those two lines marked (skipped — role not in pod)
instead of a resolved member id — plan always renders every step the spec declares, it just
tells you honestly which ones this pod's current roster can run.
A custom pipeline: parallel fan-out, bounded rework, a human sign-off
You already scaled myapp's Implementer for parallel work (docket pod myapp add implementer
→ myapp-implementer-2, mentioned above). A pipeline file is how you actually put both
implementers to work on one task, then require a human OK before the fix ships instead of an
automated PASS/FAIL:
# ~/code/myapp/workflows/release.yml
name: release
description: Fan the fix out across both implementers, then require a human OK before it ships.
steps:
- id: plan
role: lead
- id: fanout
parallel:
- id: impl-a
agent: myapp-implementer
- id: impl-b
agent: myapp-implementer-2
- id: review
role: reviewer
gate:
type: verdict
pattern: "^(APPROVE|REQUEST-CHANGES)\\b"
passValues: [approve]
rework:
to: fanout
when: [request-changes]
maxCycles: 2
- id: ship
role: tester
gate:
type: approval
message: "Tests passed — ready to deploy?"
$ docket pipeline plan myapp --file workflows/release.yml
Pipeline plan — myapp
Source: file 'workflows/release.yml'
Pipeline: release
[plan] role=lead -> myapp-lead [gate: none]
[fanout] parallel:
- myapp-implementer -> myapp-implementer [gate: none]
- myapp-implementer-2 -> myapp-implementer-2 [gate: none]
[review] role=reviewer -> myapp-reviewer [gate: verdict(approve, rework->fanout)]
[ship] role=tester -> myapp-tester [gate: approval]
$ docket pipeline run myapp --file workflows/release.yml
run dispatches through cli._pod._pod_dispatch — the exact same rendering, run-registry
recording, budget/approval gating, retries, and crash resume docket pod myapp dispatch uses.
--file only swaps which PipelineSpec is walked; nothing else about how a hop runs changes,
including the exit status: 1 when a task's run ends failed.
Three gate kinds, plus one step kind that isn't a gate at all — it doesn't judge a hop's output, it asks a question before one runs — and what each does to the task:
| Gate | Where it shows up | On failure |
|---|---|---|
mechanical |
Implementer's verifyCmd by default (or a command you set) |
Task → failed, a verification_failed trace event, no advance to the next step. An unset command is never silently skipped — it prints verification skipped — verifyCmd not set for <id> and emits its own trace event |
verdict |
Reviewer's APPROVE/REQUEST-CHANGES (bounded rework), Tester's PASS/FAIL (hard gate) | A rejected/unparseable verdict past the rework budget → task failed. Rework re-runs the named earlier step, up to maxCycles |
approval |
A pipeline approval step, or a pod-level requireApprovalRoles list |
Task → waiting_approval — the hop doesn't run at all until a human decides. See SECURITY-SIMPLE.md for the approval channels |
input (not a gate — no hop runs) |
- ask: {input: {from: <step-id>}}, or the richer per-question schema a Lead's own typed intake brief supplies (the intake recipe) |
Task → waiting_input — a question, not a permission. Routes on answered/declined via the step's own on: map. Answer with docket chat <task-id> or docket pod <p> answer; unanswered past its deadline → blocked (blockedReason: "input_expired"), never failed. See CONFIGURATION.md §3.15 |
Declared variables — interpolated into step instructions
A pipeline can declare variables (defaults, descriptions, required). A step's own
instructions text can reference one with ${name}, and it is substituted from the run's
resolved variable namespace before that hop runs:
steps:
- id: deploy
role: implementer
instructions: "Deploy to ${env}, then verify the health check."
$ docket pipeline run myapp --var env=staging
--var key=value is repeatable and works from docket pipeline run; the docket serve webhook
resolves the same namespace from its JSON body. Either way, resolution happens once, up front: a
required variable with no value supplied is rejected before a run record is even created, and if
any step's instructions still reference a ${name} the resolved namespace doesn't cover, the
whole run refuses before any hop starts rather than sending a literal ${name} to a model. The
resolved namespace is persisted on the run record (docket runs show <id>), so you can see exactly
what a dispatch saw.
The run registry, --follow, and cancellation
Every dispatch invocation — CLI, the serve webhook, a due schedule, the --dispatch sweep loop,
or an MCP client — writes one record to a persisted run registry, so "is it done, did it fail, or
did it never run" has an answer instead of vanishing behind a fire-and-forget thread:
$ docket runs list
Dispatch runs
┌──────────────────────┬─────────┬─────────┬───────────┬───────┬─────────────────────┬───────┐
│ ID │ SOURCE │ PROJECT │ STATE │ TASKS │ CREATED │ ERROR │
├──────────────────────┼─────────┼─────────┼───────────┼───────┼─────────────────────┼───────┤
│ run-3f2a1c9e-... │ cli │ myapp │ succeeded │ 1 │ 2026-07-29T10:02:00 │ │
└──────────────────────┴─────────┴─────────┴───────────┴───────┴─────────────────────┴───────┘
$ docket runs show run-3f2a1c9e-... --json
$ docket runs list --project myapp --json # for scripting/dashboards
--follow on docket pipeline run tails the same durable trace store a hop already writes to,
so you see hop-by-hop progress live instead of only the final summary:
$ docket pipeline run myapp --follow
→ Following dispatch for 'myapp' (Ctrl-C stops watching, not the dispatch)
2026-07-29T10:02:00 tool_call (lead)
2026-07-29T10:02:05 tool_result (lead)
2026-07-29T10:02:05 tool_call (implementer)
...
Ctrl-C stops watching only — the dispatch keeps running and recording in the background,
exactly like closing a tail -f window doesn't kill the process being tailed.
A run stuck mid-hop can be asked to stop:
$ docket runs cancel run-3f2a1c9e-...
✓ requested cancellation for run run-3f2a1c9e-... (1 process group(s) killed)
cancel records one durable request before killing an in-flight hop's whole process group, not
just the immediate child (it may have shelled out further). Queued work is cancelled immediately.
Running work remains visibly running (cancel requested) until its executor observes the request
and fully returns; only then are the task and run terminal cancelled. An in-process model/backend
call already executing is not forcibly aborted, but its late response is discarded at the next
safe checkpoint and no later tool or pipeline hop starts. runs show and its JSON form expose the
request, observation, and stop timestamps. A genuine cancellation writes one runs.cancel audit
entry naming the run, its project, its pre-cancel state, and how many process groups were killed.
Cancelling an already-terminal (or unknown) run changes
nothing and writes no audit entry — but it still exits 1, printed as an error
(run <id> is already <state>), not a silent success; "no-op" describes its side effects, not
its exit code.
Scheduling and webhooks (unattended dispatch)
Two ways to trigger a pod's pipeline without a human typing dispatch:
Schedules — cron, a daily time, or a fixed interval
Schedules live in ~/.docket/docket-schedules.json. Set one with docket pod <project> config set
schedule "<spec>" — it validates the spec and writes the file for you; docket pod <project>
config unset schedule removes the entry. The file's shape:
{
"schedules": {
"myapp": "@every 30m",
"otherapp": "09:00",
"athird": "*/15 9-17 * * 1-5"
}
}
Three formats: @every <N>s|m|h, a daily HH:MM (UTC), or a standard 5-field cron expression
(minute hour dom month dow, UTC, numeric only — no MON/JAN name aliases). A schedule is
checked at most once per matching minute and only while docket serve --dispatch is running
— plain read-only docket serve, or no docket serve at all, never fires one. Each due project
gets its own run record (source: "schedule"), so a scheduled dispatch is exactly as inspectable
via docket runs as a manual one. An invalid spec (however it got into the file) is never treated
as silently never-due: the sweep logs schedule '<project>' skipped — <reason> once per sweep
instead of dropping it quietly; docket doctor reports the same problem outside of serve.
Webhooks — trigger from CI or any external system
docket serve always exposes POST /dispatch/<project> (bearer-token authenticated), independent
of --dispatch — a webhook call is an explicit request, not part of the passive monitor loop:
TOKEN=... # printed at `docket serve` startup, or $DOCKET_SERVE_TOKEN
curl -s -H "Authorization: Bearer $TOKEN" -X POST \
-H "Content-Type: application/json" -d '{"env": "staging"}' \
http://127.0.0.1:7331/dispatch/myapp
# {"ok": true, "run": "run-3f2a1c9e-...", "project": "myapp", "status": "dispatched"}
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7331/runs/run-3f2a1c9e-... | jq .
The JSON body is resolved against the pod's own configured/default pipeline's declared
variables before a run record is even created, exactly like --var on docket pipeline run
(see the section above): a missing required variable is rejected with 400 and no run record is
created at all; an unresolved ${name} in a step's instructions also refuses the run before any
hop starts. The resolved namespace is persisted on the run record (docket runs show <id> shows
it), so you can answer "what did this dispatch actually see". The webhook always uses the pod's own
pipeline; it has no way to supply a --file of its own, only variable values.
There is now one queue: per-pod dispatch
There is no org-level task queue. Per-pod dispatch is the only queue:
| Per-pod dispatch | |
|---|---|
| Command | docket pod <project> delegate / queue / dispatch |
| Scope | one project's pod (scope: project) |
| Runs code? | yes — Implementer writes inside the project workspace |
| Isolation | pod-local; no cross-pod path |
Use it for "do this work in this codebase":
docket pod myapp delegate "Add a contact form to the homepage"
docket pod myapp dispatch
For genuinely cross-cutting planning (not code) — "what should the fleet focus on this week" — there is no queue at all, only the advisory Portfolio Manager described next: it reads fleet metadata and recommends in words; you act on its advice by delegating into the pods it names.
Cross-pod planning, the honest way
There is no command that runs one pod's work from another pod. When you need a cross-pod
plan (where to focus, what to rebalance or pause), use the advisory
Portfolio Manager (docket init --portfolio, read only by the first docket init). It is
scoped to fleet metadata and to recommending, in words, which pods to prioritise. You then
delegate into the chosen pods and dispatch each one. The Portfolio Manager never dispatches
and never touches code.
Today nothing runs a turn for it: dispatch only runs pod members, and Telegram accepts only
/approve,/deny,/status,/delegateand/answer(the last two only for a pod Lead binding), so there is no command that asks it a question. Until one exists, do the cross-pod read yourself withdocket status --all,docket pod <project> queue,docket inbox(every pod that needs you, in one place) anddocket cost, then:
docket pod myapp dispatch
docket pod mywebsite dispatch
Composing a team — how big should a pod be?
Start lean; grow only when the work earns it.
| Situation | Pod |
|---|---|
| Prototyping, low-risk changes, solo project | lean (Lead + Implementer) — the default |
| Code that needs a correctness/security gate before it lands | add a Reviewer (--with reviewer) |
| Behaviour you want validated independently of the diff | add a Tester (--with tester) |
| Production-grade, regulated, or high-blast-radius work | full pod (--pod full) |
| One Implementer is the bottleneck | docket pod <p> add implementer (parallel doers) |
The Reviewer and Tester are the line between "an agent changed the code" and "a change was reviewed and validated before it landed."
Pod configuration
Pod dispatch settings — docket pod <project> config
A pod's dispatch behavior is sixteen typed keys on the Lead's meta, read/written through one
generic command instead of hand-editing files: budgetUsd, maxReworkCycles, turnTimeoutS,
verifyTimeoutS, approvalMode, approvalExpiryHours, inputExpiryHours, allowCommands,
pipeline, schedule, projectInstructions, mcpServers, deniedTools, requireVerify,
maxConsultationsPerTask, network. A repository's .docket/pod.yaml can carry the same keys under
settings:, applied by docket init or docket pod <project> apply.
docket pod myapp config get # every key, with its source (default vs. set)
docket pod myapp config get --json # same, machine-readable
docket pod myapp config set budgetUsd 5
docket pod myapp config unset budgetUsd
Every write is validated before it's stored (bad type, out-of-range, or an unknown key refuses
the write) and audited as pod.config; a value that somehow ends up malformed in storage refuses
dispatch rather than being silently coerced, naming the key. pipeline and schedule are
validate-then-store: config set pipeline <file> checks the file and writes a hashed copy into
the pod's own workspace before recording it, and config set schedule "<spec>" validates the cron/
interval spec the same way (see "Schedules" below). Binding a pipeline this way makes it the
default for every trigger — CLI dispatch, the serve webhook, a due schedule — whereas docket
pipeline run --file <f> only swaps the spec for that one invocation. See
CONFIGURATION.md for the full reference on every key.
To check what will actually run for a given agent before you dispatch, docket config explain
<agent-id> [--json] reports its effective configuration with provenance (policy vs. pinned model,
which pod settings are in play, and where each came from).
What makes a pod member
Each member is an ordinary registered agent with its own permission-locked workspace, so
docket list / info / cost / doctor see every member for free.
~/.docket/workspaces/projects/myapp-implementer/
├── SOUL.md # identity + scope + session key
├── AGENTS.md # session protocol, role boundaries
├── TOOLS.md # project-specific commands (Implementer, when ports or verify are set)
├── HEARTBEAT.md # active tasks/decisions
├── MEMORY.md # curated long-term memory
├── WORKFLOW_AUTO.md # startup contract for reading the workspace by hand
├── .docket-meta.json # docket metadata (role, codebase, model, sessionKey, projectKey)
└── memory/
└── 2026-06-24.md # daily log
Session keys & isolation
Pod members share the project's session-key namespace (agent:myapp:<key>), which keeps the
pod's conversation context together and isolated from every other project. Dispatch runs
each task on its own per-task session (agent:myapp:<task_id>). Change a member's scope with:
docket scope myapp-implementer set myapp-staging
The load-bearing isolation primitive is the per-member workspace — session keys isolate conversation; separate workspaces isolate files, memory, and identity.
Per-role model policy
Each role maps to the cheapest model adequate for its workload. Change a role once and every
policy-following agent re-resolves; pin one agent with docket profile.
| Role | Policy key | Default class |
|---|---|---|
| Lead | manager | cheap (coordination) |
| Implementer | programmer | strong (reasoning-dense) |
| Reviewer | reviewer | cheap |
| Tester | tester | cheap |
| Portfolio Manager | portfolio-manager | cheap |
docket models # show the role→model policy
docket models set programmer anthropic/claude-… # re-resolves every policy-following Implementer
docket profile myapp-implementer anthropic/… # pin ONE agent
docket profile myapp-implementer default # re-attach it to the role policy
Agents record intent in modelSource: policy (follow the role) or pinned (explicit choice).
docket models set … never touches pins.
Engineer's daily workflow
Morning
docket list # every pod member + org specialist
docket doctor # health check (add --fix to repair drift)
Assign and run work
# Queue and run a single project's work:
docket pod myapp delegate "Add contact form to homepage"
docket pod myapp dispatch
# Or let the background loop drain every pod's queue:
docket serve --dispatch
You can also queue work from Telegram: wire the Lead once with docket wire myapp-lead, run
docket serve --telegram, and send /delegate <task> in that group. The task lands on the same
pod queue and the reply is its task id, not the pipeline's output. Plain messages are refused;
the only verbs are /approve, /deny, /status, /delegate and /answer <task-id> <text> (for
a parked question). This bot only ever replies to a message it received — it never messages the
group first. Pushing a notification into the group instead is a separate, opt-in mechanism
(docket channels enable telegram --set actors=<chat-id>, §3.15 in CONFIGURATION.md), scoped to
the chat ids you explicitly list, never every wired binding.
Monitor
docket pod myapp queue # this pod's queue + per-task status/cost
docket trace tail myapp # follow the pod's latest trace session
docket logs myapp-lead # the Lead's activity
Review and commit
cd ~/code/myapp
git diff
git add -p && git commit -m "Feature: contact form" && git push
End of day
docket cost # measured token usage across the fleet
docket doctor # any alerts?
Token & cost notes
These are token estimates — the thing docket's routing actually controls. Dollars are only
ever estimated: the budget gate uses a labelled token-based estimate and docket models shows
comparative pricing; docket cost reports measured tokens and no recorded spend, so we don't
project dollars here. See
Cost reporting and its limits.
A dispatched task is the sum of its hops, each a real costed turn:
Simple change (lean pod, 2 hops):
lead ~2K (plan + decompose, cheap model)
implementer ~2K (small edit, strong model)
── total ~4K · ~2 min
Feature (full pod, 4 hops):
lead ~5K
implementer ~20K (multi-step logic, strong model)
reviewer ~5K (veto on diff)
tester ~3K (PASS/FAIL)
── total ~33K · ~10 min
Refactor (full pod, high blast radius):
lead ~10K
implementer ~50K (multi-file)
reviewer ~10K (security-critical)
tester ~5K
── total ~75K · ~20 min
To bound the dollar cost of any of these, set a per-pod cap on the Lead
(docket profile <project>-lead --budget <usd>) and watch measured tokens with
docket cost; a hop that would cross the cap leaves the task blocked with the estimate in its
reason (docket pod <p> queue). The cap is enforced between hops on every dispatch.
Troubleshooting
Pod/dispatch, scope, and Telegram issues (including "pod not running a delegated task," "pipeline stops after the Implementer," and leftover pre-pods global roles) are all covered in troubleshooting.md's "Pods & Dispatch" and "Agents Not Responding in Telegram" sections — kept in one place rather than duplicated here.
Summary
Project pods (scope: project, one per codebase):
- Lead orchestrates and owns comms — never edits code.
- Implementer is the single writer, inside the project workspace.
- Reviewer/Tester are optional gates you add when the work warrants it.
- docket pod <p> delegate queues; docket pod <p> dispatch runs the real pipeline,
one costed turn per hop, budget-gated, traced, and pod-local.
Org specialists (scope: org, shared once):
- manager / knowledge / security; optional advisory portfolio-manager.
- There is no org-level task queue — per-pod dispatch is the only queue;
the portfolio-manager is advisory-only and never dispatches or touches a project's code.
Engineer: - Sets budget caps, delegates and dispatches, reviews diffs, commits, approves HITL gates.
delegate → dispatch → Lead → Implementer → (Reviewer) → (Tester) → you review + commit
Pipelines (docket pipeline validate/plan/run, docket runs list/show/cancel):
- The docket-native pipeline is the one dialect
docket executes, and a pod with no pipeline file runs the built-in one unchanged.
- Every dispatch — CLI, --follow, a schedule, a webhook, or the sweep loop — lands one record
in the run registry; docket runs cancel kills an in-flight hop's process group for real.
Key guarantees: - One owner of completion (Lead) and one doer (Implementer) — no two-doer ambiguity. - Per-member workspaces — no worker agent ever serves two projects. - Real hand-off — the pipeline actually runs; every hop is costed, budget-gated, and traced. - No cross-pod dispatch — one pod can never run another pod's agents.
Next: Read Agent Teams (Pods) for the canonical model, or QUICK-START-DOCKET.md to run your first pod.