Playbooks

Playbooks turn Waypath from an intelligence surface into an operating layer. There are two flavors that share the same vocabulary but solve different problems:

• Playbook specs: long-form executable programs. A lead source plus a strategy plus adaptation rules that a buddy runs continuously.
• Action playbooks: one-shot quick actions surfaced in the dashboard’s RecommendedActions feed. Click one and the target buddy opens with a pre-filled prompt.

Both concepts are wired into every buddy’s system prompt via a playbook-awareness block, so agents know what programs are active before you even ask.

Playbook specs

A PlaybookSpec is the long-form program. Every spec pairs a lead source (where new candidates come from) with a strategy (what to do with them) plus optional adaptation rules (when to pivot if things aren’t working).

Schema

Endpoints

GET    /api/v1/playbooks                 # list all specs
POST   /api/v1/playbooks                 # create (requires name, mode, buddyId, strategy.hypothesis)
GET    /api/v1/playbooks/:id             # fetch one
PUT    /api/v1/playbooks/:id             # partial update (nested merges)
DELETE /api/v1/playbooks/:id             # remove
POST   /api/v1/playbooks/:id/run         # record a run row
GET    /api/v1/playbooks/:id/runs        # list runs for a spec

All require auth + workspace context.

Runtime

The interim runtime lives client-side in playbook-runtime.ts. Calling POST /api/v1/playbooks/:id/run records a run row; the actual agent invocation happens by opening the target buddy’s chat panel and sending a structured prompt built from the spec. The buddy then executes under its own tool allowlist and streams back.

Each run tracks metrics.samples, metrics.successes, metrics.metricValue, and a pivots[] list of adaptation decisions made over the run’s lifetime.

Action playbooks

Action playbooks are the one-shot cousin. They live client-side in action-playbooks.ts and surface as RecommendedActions cards throughout the dashboard (Reporting, ICP Studio, AgentView home).

Each action has:

• An id (prospect.research-icp, campaign.newsletter-perf, etc.)
• A buddyId (SpecialistBuddyId only, never the orchestrator)
• A label builder and prompt builder, both of which receive a runtime context (topSignal, selectedRecord, active ICP, etc.)

Click an action card and the target buddy’s chat opens with the prebuilt prompt already typed in. Actions are filtered through pickPlaybooks(ctx) so only actions whose required integrations are connected make it to the UI. A Campaign action that needs Customer.io won’t appear in a workspace that hasn’t connected it.

Playbook awareness in the system prompt

renderPlaybooksBlock() in chat-agent-service.ts injects either the workspace’s active playbook inventory or a feature description (when zero specs exist) into every buddy’s system prompt. This means:

• “Tell me about the playbook” returns real answers, not guesses.
• The agent steers outputs toward the active success metric.
• New playbook types added in the future teach all buddies automatically once their renderer lands in the block.

Example: outbound research spec

{
  "name": "Series B SaaS. New head of growth",
  "status": "active",
  "mode": "outbound",
  "buddyId": "prospect",
  "leadSource": {
    "kind": "orange-slice",
    "query": "Head of Growth at Series B SaaS companies, last 90 days",
    "sampleSize": 50
  },
  "strategy": {
    "kind": "gtm-execution",
    "hypothesis": "New growth leaders at post-Series-B SaaS need conversion intelligence in their first 90 days. Highest conversion window is weeks 2-6 after their start date",
    "channels": ["email", "linkedin"],
    "cadence": "3-touch sequence over 10 days, LinkedIn-first",
    "successMetric": "meeting_booked",
    "successTarget": 3
  },
  "adaptation": {
    "enabled": true,
    "minSampleSize": 50,
    "pivotWindowDays": 5,
    "maxPivotsPerWeek": 2
  }
}