kookr-playbooks

name	kookr-playbooks
description	How to create, structure, and launch Kookr playbook tasks — reusable agent task templates with dynamic sources and project identity
keywords	playbook, playbooks, task, template, kookr, launch, repeatable, tracked-projects, project, source

Kookr Playbooks

A playbook is a reusable task template stored as a Markdown file in .kookr/playbooks/. It defines a repeatable agent task that users can launch from the Kookr dashboard UI with one click (optionally filling in parameters).

What a playbook IS

• A Markdown file with YAML frontmatter in .kookr/playbooks/*.md
• A task template: when launched, the Markdown body becomes the agent prompt, prefixed by a Kookr-generated context header
• Reusable: can be launched many times with different parameter values
• Visible in the Kookr dashboard under Launch > Playbooks tab

What a playbook is NOT

• Not a Claude Code Agent tool invocation — it's a Kookr-native concept
• Not a skill — skills guide Claude's behavior; playbooks define agent tasks
• Not a one-off task — use the manual Launch tab or curl POST /api/tasks for that

File location

.kookr/playbooks/
├── my-playbook.md
├── another-playbook.md
└── ...

The directory is scanned by src/core/playbook-discovery.ts which reads .kookr/playbooks/*.md from the project CWD.

Frontmatter schema

---
name: Human-Readable Playbook Name        # REQUIRED — displayed in UI
description: One-line description          # Optional — shown on playbook card
cwd: /absolute/path/to/working/directory   # Optional — overrides dialog CWD
parameters:                                # Optional — user fills these in before launch
  - name: repoFullName
    description: "Target repository (owner/repo)"
    required: false
    defaultFrom: git-remote                 # Optional — server resolves blank value from launch CWD remote
    type: select                           # Optional — 'text' (default) or 'select'
    source: tracked-projects               # Optional — dynamic data source
    options:                               # Optional — static fallback options (merged with source)
      - label: "grafana/grafana"
        value: "grafana/grafana"
checklist:                                 # Optional — becomes task completion criteria
  - First thing to verify
  - Second thing to verify
---

Field details

Field	Required	Type	Purpose
name	Yes	string	Display name in UI
description	No	string	Subtitle on playbook card
cwd	No	string	Target working directory (absolute path). If omitted, uses the CWD from the launch dialog. Use this when the playbook targets a specific repo.
parameters	No	array	Parameters with name, description, required, default, defaultFrom, type, source, options.
checklist	No	array of strings	Completion criteria shown in UI and tracked by the supervisor.

Parameter fields

Field	Required	Type	Purpose
name	Yes	string	Parameter name, used in {{name}} interpolation
description	No	string	Placeholder hint shown in the form
required	No	boolean	If true, the Launch button is disabled until filled
default	No	string	Pre-filled value when no history exists
defaultFrom	No	'git-remote'	Server fills a blank launch value from the launch CWD's origin remote. Use for repo params that should follow the current project instead of reusing stale history.
type	No	'text' or 'select'	select renders a dropdown. Default: text
source	No	string	Dynamic data source ID (see below). Merged with static options.
options	No	array of {label, value}	Static dropdown options for type: select

Dynamic sources (source field)

When a parameter has a source, the UI resolves it at render time to populate the dropdown dynamically.

Source ID	Resolves to	Value format
tracked-projects	All hosted ProjectSummary entries from the sidebar (local projects excluded)	owner/repo (e.g., grafana/grafana)

Key behaviors:

• Source options are merged with static options (deduped by value, static labels win)
• When option count > 5, the dropdown becomes a filterable search input
• Project identity: When source: tracked-projects is present, the selected value is automatically converted to a project ID (github.com/owner/repo) and assigned to the task. This makes the task appear under the correct project in the sidebar — not under the Kookr project.
• Project drawer launch: When the user clicks "Run playbook..." from a project's detail drawer, parameters with source: tracked-projects are auto-filled with that project's displayName.
• Git remote defaults: When a parameter has defaultFrom: git-remote, leave it optional in the form. Kookr resolves blank values from the launch CWD's git remote on the server and does not reuse the last manually entered value on future launches.

Why source: tracked-projects matters for OSS playbooks

Without it, all playbook tasks run in the Kookr repo's CWD, so they get assigned to kookr-ai/kookr in the sidebar. With source: tracked-projects:

1. The repo dropdown is populated automatically from tracked projects (no hardcoded YAML edits)
2. The task gets the correct projectId (e.g., github.com/grafana/grafana)
3. The task appears under the target project in the sidebar, not under Kookr
4. Users can launch directly from the project drawer with one click

Every OSS playbook that takes a repo parameter should use source: tracked-projects.

Derived values pattern

For parameters that are mechanically derivable from repoFullName (like repoSlug, forkName, defaultBranch), do NOT add them as user-facing parameters. Instead, add a "Derived values" section at the top of the prompt body:

## Derived values

Compute these from `{{repoFullName}}`:
- **repoSlug**: replace `/` with `-` (e.g., `microsoft/vscode` → `microsoft-vscode`)
- **forkName**: `jeanibarz/<repo>` where `<repo>` is the part after `/`
- **defaultBranch**: look up from recon report at `~/.claude/<repoSlug>-recon/recon-report.md`, or default to `main`

Use these derived values wherever they appear below.

Use <angleBrackets> for derived values in the body (not {{mustache}}) to distinguish them from engine-interpolated parameters.

Body

Everything after the frontmatter closing --- is the agent prompt body. At launch Kookr prepends a one-line context header naming the playbook, its scope, and its definition path — so don't open the body with your own "you are running X" preamble; it is redundant and competes with the header's framing. Structure the body as a comprehensive brief for a fresh agent that has no prior context:

1. Derived values — how to compute repoSlug, forkName, etc. from the primary parameter
2. Objective — what the task achieves
3. Context — repos, labels, tools, conventions the agent needs to know
4. Phases — numbered steps with concrete commands and examples
5. Idempotency Rules — how to safely re-run (critical for recurring tasks)
6. Anti-Patterns — mistakes to avoid

Parameter interpolation

Use {{paramName}} in the body. When the user launches the playbook, values are substituted before the prompt is sent to the agent.

Deploy version {{version}} to {{environment}}.

How playbooks are launched

From the UI — standard path

1. User clicks "+ Launch" button in the Kookr dashboard
2. Switches to the "Playbooks" tab
3. Searches and selects a playbook card
4. Fills in parameters (selects from dropdown for tracked-projects fields)
5. Clicks "Launch Playbook"

From the UI — project drawer path

1. User clicks a project in the sidebar (e.g., grafana)
2. The project detail drawer opens
3. Clicks "Run playbook..." button in the drawer header
4. The launch dialog opens on the Playbooks tab
5. Selects a playbook — repoFullName is auto-filled with the project's name
6. Clicks "Launch Playbook"

Both paths produce identical tasks (same CWD, same prompt, same projectId).

From the API (programmatic)

POST /api/tasks takes a raw prompt — it does not go through playbook launch preparation, so no playbook context header is prepended and playbookId is not recorded. The resulting task is not identical to a UI-launched one: the agent won't know it is running a playbook or where the definition lives. Prefer the UI or the launchPlaybook WS message when you want real playbook semantics.

curl -s -X POST http://localhost:4800/api/tasks \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "<paste the playbook body with params filled in>",
    "cwd": "/path/to/working/dir",
    "criteria": "checklist item 1. checklist item 2."
  }'

When to create a playbook vs a one-off task

Scenario	Use
Repeatable process (triage, audit, analysis)	Playbook
One-time investigation or fix	Manual launch or curl POST /api/tasks
Process that will run on a schedule	Playbook (idempotency rules required)
Quick delegation from within an agent session	spawn-child-task skill

Good playbook design

1. Self-contained prompt: The agent starts fresh — include ALL context it needs
2. Concrete commands: Show exact gh, curl, git commands, not vague instructions
3. Minimal parameters: Only ask for what can't be derived. Use defaultFrom: git-remote for repo fields that should follow the launch project, source: tracked-projects when project-drawer launch should pre-fill the selected project, and derive slug/fork/branch in the prompt body.
4. Checklist items map to phases: Each checklist item should correspond to a verifiable phase outcome
5. Idempotency section: If the playbook will run repeatedly, document how to avoid duplicate work
6. Anti-patterns section: Capture past mistakes so the agent doesn't repeat them
7. CWD field: Set it when the playbook targets a specific repo different from the Kookr project (e.g., cwd: $HOME/git/codex for Codex-specific playbooks)

Template for a new OSS playbook

---
name: OSS <Task Name>
description: <One-line description>
parameters:
  - name: repoFullName
    description: "Target repository (owner/repo)"
    required: true
    type: select
    source: tracked-projects
checklist:
  - <First verifiable outcome>
  - <Second verifiable outcome>
---

## Derived values

Compute these from `{{repoFullName}}`:
- **repoSlug**: replace `/` with `-`
- **forkName**: `jeanibarz/<repo>` where `<repo>` is the part after `/`

## Objective

<What this task achieves for {{repoFullName}}>

## Context

- **Upstream**: `{{repoFullName}}`
- **Fork**: `<forkName>`
- **State**: `~/.claude/<repoSlug>-<task-slug>/`

## Phases

### Phase 1: ...

## Idempotency Rules

1. ...

## Anti-Patterns

- ...

Examples in this project

• oss-pr-lessons.md — Analyzes closed PRs to learn contribution patterns (1 param: repoFullName)
• oss-bug-triage.md — Scores upstream bugs, maintains ranked triage issues (1 param: repoFullName)
• oss-contribution-pipeline.md — End-to-end contribution workflow (2 params: repoFullName, phase)
• codex-bug-triage.md — Codex-specific triage (hardcoded cwd, no tracked-projects source)

Implementation files

• src/core/playbook.ts — Type definitions (Playbook, PlaybookParameter, source field)
• src/core/playbook-parser.ts — Parses frontmatter + body, interpolates {{params}}
• src/core/playbook-discovery.ts — Scans .kookr/playbooks/*.md
• src/server/use-cases/playbook-launch.ts — Prepares launch options, derives projectId from tracked-projects param
• src/server/launch-service.ts — Creates task, sets projectId if provided
• src/server/schedule-validator.ts — Same projectId derivation for scheduled launches
• src/frontend/store/playbook-source-resolver.ts — Resolves tracked-projects source to dropdown options
• src/frontend/components/FilterableSelect.tsx — Searchable dropdown for large option lists
• src/frontend/components/PlaybookBrowser.tsx — UI for browsing, project-context pre-fill
• src/frontend/components/LaunchTaskDialog.tsx — Tabbed dialog (Manual | Playbooks)