@cleocode/playbooks

Part of CLEO. Start with the root README; run cleo <command> --help for any command.

Playbook DSL + runtime for CLEO — T889 Orchestration Coherence v3.

Playbooks are .cantbook YAML documents that describe a multi-step agent workflow as a DAG of nodes (agentic, deterministic, and approval gates) connected by typed edges. This package parses them, persists execution state to tasks.db, evaluates HITL auto-policies, and manages HMAC-signed approval tokens for human-in-the-loop gates.

Status

The runtime executor (runtime.ts) is the next ship — parser + state + policy + approval primitives are in place.

Install

This is an internal monorepo package. Consumers use it via workspace dependency:

// package.json
{
  "dependencies": {
    "@cleocode/playbooks": "workspace:*"
  }
}

What a .cantbook looks like

version: "1.0"
name: release-cut
description: Cut a CalVer release and publish to npm

inputs:
  - name: version
    required: true
    description: Target version (e.g. 2026.4.90)

nodes:
  - id: build
    type: deterministic
    command: pnpm
    args: [run, build]

  - id: test
    type: deterministic
    command: pnpm
    args: [run, test]
    depends: [build]

  - id: review
    type: approval
    prompt: "Build + tests green. Publish {{ version }} to npm?"
    depends: [test]

  - id: publish
    type: agentic
    skill: release-publisher
    depends: [review]

edges:
  - from: build
    to: test
    contract:
      requires: [dist-exists]
      ensures: [tests-passed]
  - from: test
    to: review
  - from: review
    to: publish

error_handlers:
  - on: test-failed
    action: abort
    message: "Tests failed — aborting release."

Validation rules enforced by the parser:

• version MUST be "1.0".
• name MUST be non-empty.
• Node ids MUST be unique.
• Every edges[].from / edges[].to MUST reference a known node id.
• Nodes + edges MUST form a DAG (no cycles).
• agentic nodes MUST have skill OR agent (at least one).
• deterministic nodes MUST have command + args.
• approval nodes MUST have prompt.
• depends[] entries MUST be valid node ids.
• iteration_cap / max_iterations MUST be in 0..10 (hard limit).

Quick API

import {
  parsePlaybook,
  createPlaybookRun,
  updatePlaybookRun,
  evaluatePolicy,
  createApprovalGate,
  approveGate,
  rejectGate,
  DEFAULT_POLICY_RULES,
} from '@cleocode/playbooks';

// 1. Parse a .cantbook file
const { playbook, hash } = parsePlaybook(yamlSource);

// 2. Create a persisted run
const run = createPlaybookRun(tasksDb, {
  runId: 'run_abc123',
  playbookName: playbook.name,
  playbookHash: hash,
  bindings: { version: '2026.4.90' },
  epicId: 'T889',
  sessionId: 'ses_xyz',
});

// 3. Evaluate auto-policy at an approval node
const { autoPassed, reason } = evaluatePolicy(node, DEFAULT_POLICY_RULES, context);

// 4. Create an approval gate (pending) or auto-pass it
const approval = createApprovalGate(tasksDb, {
  runId: run.runId,
  nodeId: 'review',
  autoPassed,
});

// 5. Resolve the gate (human approves via the resume token)
approveGate(tasksDb, approval.token, { approver: 'keaton', reason: 'LGTM' });

Database tables

Both tables live in tasks.db. Migration: packages/core/migrations/drizzle-tasks/20260417220000_t889-playbook-tables/.

playbook_runs

playbook_approvals

Approval tokens (HMAC)

Resume tokens are HMAC-SHA-256 signed with the secret resolved from getPlaybookSecret(env):

1. CLEO_PLAYBOOK_SECRET (preferred)
2. CLEO_SECRET (fallback)
3. Hard error if neither is set — approval nodes cannot be created without a secret.

Tokens encode {runId, nodeId, issuedAt} and are verified before any approveGate / rejectGate call. Replay-resistant: an already-decided approval returns E_APPROVAL_ALREADY_DECIDED.

Error codes

Policy evaluator

evaluatePolicy(node, rules, context) matches an approval node against an ordered list of PolicyRules. The first rule that matches decides: autoPassed: true | false plus a reason. Used to let low-risk approval gates auto-pass (e.g. "build dist unchanged from last green run") without bothering a human. DEFAULT_POLICY_RULES ships a safe conservative default set.

Related packages

• @cleocode/contracts — PlaybookDefinition, PlaybookRun, PlaybookApproval type contracts consumed here.
• @cleocode/core — owns tasks.db lifecycle. Playbook migrations are applied by core's drizzle runner.
• @cleocode/cleo — CLI surface that will expose cleo playbook run, cleo playbook approve <token> once the runtime (W4-10) lands.

Testing

pnpm --filter @cleocode/playbooks test

Smoke, parser, schema, state, policy, and approval test suites cover the shipped surface.