Author a Playbook

The fastest path to a useful Playbook is a thin, end-to-end slice: one meaningful Outcome, a small set of Claims, only the Variables you truly need, and enough Tasks to prove the result.

1. Name the package

Every package has a stable identity derived from its Workspace namespace and slug, such as @acme/launch-review. Keep the authored slug stable; versions describe compatible package releases, not separate Playbooks.

export default {
  packageKind: "playbook",
  packageIdentity: "@acme/launch-review",
} as const;

2. Define success before work

Create the Claims first. Each Claim has a statement and an evidence requirement. Attach them to an Outcome that describes the user-facing result.

import { claim, definePlaybook, milestone, outcome, task, variable, v } from "@doku/playbook-sdk";

const launchAssessment = variable(
  "launchAssessment",
  v.file({
    title: "Launch assessment",
    purpose: "The release candidate or report to review.",
  }),
).resolution({
  mode: "human",
  freshness: "fresh_required",
  sources: ["uploaded_file", "reference_url"],
});

const risksDocumented = claim("risksDocumented", {
  statement: "Material launch risks are identified and prioritized.",
  evidence: "List each risk, its severity, supporting observation, and recommended mitigation.",
});

const ownerAccepted = claim("ownerAccepted", {
  statement: "The accountable owner accepts the launch recommendation.",
  evidence: "Record the reviewed recommendation, requested changes, and final decision.",
}).approval("human");

const launchDecisionReady = outcome("launchDecisionReady", {
  title: "A launch decision is ready",
  description: "The owner has a risk-backed recommendation and an explicit approval decision.",
  claims: [risksDocumented, ownerAccepted],
});

const inspectCandidate = task("inspectCandidate", {
  title: "Inspect the release candidate",
  instructions: "Review the supplied assessment and record material launch risks.",
});

const prepareRecommendation = task("prepareRecommendation", {
  title: "Prepare the launch recommendation",
  instructions: "Turn the evidence into a clear launch, hold, or revise recommendation.",
  dependsOn: [inspectCandidate],
});

const review = milestone("review", {
  title: "Assess launch readiness",
  tasks: [inspectCandidate, prepareRecommendation],
});

export default definePlaybook({
  slug: "launch-review",
  version: "0.1.0",
  title: "Launch review",
  summary: "Assess a release candidate and produce an evidence-backed launch decision.",
  outcomes: [launchDecisionReady],
  variables: [launchAssessment],
  milestones: [review],
});

3. Keep Tasks bounded

A good Task has one observable purpose. Its instructions tell the agent what to inspect or produce, but completion is not proof by itself. Claims and their evidence remain the completion contract.

Use dependsOn only for real execution dependencies. If two Tasks can proceed independently, leave them independent so Doku can expose both as runnable.

For longer guidance, bind a file instead of embedding a large string:

import { instructions, task } from "@doku/playbook-sdk";

const reviewAccessibility = task("reviewAccessibility", {
  title: "Review accessibility",
  instructions: instructions.file("instructions/review-accessibility.md"),
});

4. Add only required inputs and access

Variables declare information; Capacities declare external abilities. Keep both at the Playbook root so Doku can prepare the Run before Tasks depend on them.

• Make a Variable optional when the work can still succeed without it.
• Require fresh input when reusing an old value would make the result unsafe.
• Narrow connector Capacities to the products and actions the Playbook actually needs.
• Let the agent ask a governed question when a value cannot be resolved safely.

5. Write for another agent

Assume the executing agent has strong general reasoning but no hidden context about your organization.

• State the decision or deliverable each Task must produce.
• Name authoritative sources and boundaries.
• Describe failure and stop conditions.
• Keep business rules in source files, not in a past chat.
• Never instruct an agent to bypass Doku's checkpoints, access decisions, or completion feedback.

Authoring checklist

• The Outcome is a user-facing result, not a task list.
• Every Outcome references at least one Claim.
• Every Claim names concrete evidence.
• Human judgment is modeled as a human-approved Claim.
• Variables and Capacities are no broader than the work requires.
• Tasks form a valid dependency graph.
• Another agent can understand the instructions without the authoring conversation.
• The package version and page copy match the behavior being promoted.

Next, learn how to shape Outcomes and Claims or publish a version.