# Machine playbook summaries (agents)

**Agents:** ordered checklists live in **`.ai/playbooks/*.md`** (attach with `@`). **Maintainers** also have rendered copies under `docs/maintainers/playbooks/` after **`pnpm run generate-maintainer-docs-from-ai`**. Attach requestable Cursor rules when the editor supports it. **Sprint wording:** machine synonyms for **sprint** / phase execution slices live under **`term|name=sprint|…`** in **`.ai/TERMS.md`** and **`.ai/TERMS.index.json`**.

## Single task → phase integration branch (delivery loop)

1. Ensure **`release/phase-<N>`** exists (from `main` if new phase); branch a **task branch** from that line.
2. **Before the first implementation commit:** Tier A `run-transition` **`start`** (JSON **`policyApproval`**) if the task is still **`ready`**; pass **`expectedPlanningGeneration`** when policy **`require`**. Staying **`ready`** while coding is wrong — see playbook step **0b**. Read **`resolve-maintainer-delivery-policy`** / **`resolve-task-intake-policy`** when you need resolved defaults (CLI JSON — no config spelunking).
3. Implement with commits; run `pnpm run check` / `pnpm run test` as appropriate. Optional: Tier C **`update-task`** on **`summary`** / **`metadata`** at milestones (PR opened, CI green).
4. Open **PR targeting `release/phase-<N>`** when the resolved delivery profile expects GitHub-style review (default); iterate review; merge into the phase branch. If policy selects a non-PR evidence path, still land work on the **phase integration branch** unless the resolved policy explicitly relaxes it.
5. After merge: Tier A **`complete`** with JSON **`policyApproval`** so the store matches shipped work.

### Repair: accidental bulk starts

If multiple tasks were started accidentally, keep only the actively worked task in `in_progress` and run `pause` on the others immediately.

Example:

```bash
pnpm exec wk run run-transition '{"taskId":"T123","action":"pause","expectedPlanningGeneration":<from-last-read>,"policyApproval":{"confirmed":true,"rationale":"repair accidental bulk start; returning non-active task to ready"}}'
```

Handoff note must include: task kept active, tasks paused, and the planning generation used for repair transitions.

Optional Cursor rule: `.cursor/rules/playbook-task-to-phase-branch.mdc`. Full checklist: **`.ai/playbooks/task-to-phase-branch.md`**.

## Phase closeout → `main` + release

When the phase is done: validate and fix on **`release/phase-<N>`**, obtain human approval, **merge phase branch to `main`**, then follow **`.ai/RELEASING.md`** on the **`main`** tip.

After publish and evidence (**playbook §6**), end with **§7 Phase delivery summary**: compact copy-paste block, **`{placeholders}`** only — counts from **`list-tasks`** / task store + roadmap scope (see playbook **§7 evidence rules**), not chat memory.

Full checklist: **`.ai/playbooks/phase-closeout-and-release.md`**.

Optional Cursor rule: `.cursor/rules/playbook-phase-closeout.mdc`.

## Improvement discovery (research → log)

Research transcripts/docs/architecture first, then persist a **problem report** (`metadata.issue` + `metadata.supportingReasoning`, scoped body)—not raw trace paste. Use Tier B `workspace-kit run` commands from `.ai/machine-cli-policy.md` / **`.ai/AGENT-CLI-MAP.md`** to persist—never chat-only approval for gated commands.

Full checklist: **`.ai/playbooks/improvement-task-discovery.md`**.

## Improvement scout (bounded rehearsal → optional persist)

Use **`improvement-scout`** when you want **capped** candidate findings (1–3), **lens + zone rotation**, and an **evidence floor** before opening tasks. Read-only JSON: `workspace-kit run scout-report '{}'` (no task persistence). Persist only via **`create-task`** or Tier B ingest/generate with **`policyApproval`**.

Full checklist: **`.ai/playbooks/improvement-scout.md`**.

## Improvement triage (≤3 → ready)

Pick at most three `proposed` improvement tasks, document rationale, **`accept`** to **`ready`** with **`policyApproval`** on the transition args.

Full checklist: **`.ai/playbooks/improvement-triage-top-three.md`**. This remains a dashboard / agent playbook flow, not a user-facing slash command.

## Transcript churn (research → proposed)

Investigate **`transcript_churn` / `research`** rows from transcript pipelines, then **`synthesize-transcript-churn`** to **`improvement` / `proposed`** (or **`run-transition`** **`reject`** to cancel).

Full checklist: **`.ai/playbooks/transcript-churn-research.md`**.

## Wishlist intake → execution

Rank **`wishlist_intake`** items with **`list-wishlist`** / **`get-wishlist`**, confirm operator timing, clarify scope, pick a target **`phaseKey`**, then **`convert-wishlist`** with **`expectedPlanningGeneration`** when policy is **`require`**.

Full checklist: **`.ai/playbooks/wishlist-intake-to-execution.md`**.

Cursor slash: **`/generate-features`** → **`.cursor/commands/generate-features.md`**.

## Planner chat (Ideas → PlanArtifact)

Use **`planner-chat`** when an Ideas row should become a draft/reviewed/accepted PlanArtifact and, optionally, executable phase tasks. Preserve Ideas provenance (`sourceIdeaId`, `previousPlanArtifacts`), ask one planning decision at a time, keep CLI details out of normal user-facing chat, and leave the session resumable on rejection or partial progress.

Full checklist: **`.ai/playbooks/planner-chat.md`**.

Agents attach the **`.ai/playbooks/...`** path; rendered copies under **`docs/maintainers/playbooks/`** are for humans after **`pnpm run generate-maintainer-docs-from-ai`** (see playbook **Agent paths vs maintainer-rendered mirrors**).

Optional Cursor rule: `.cursor/rules/playbook-wishlist-intake-to-execution.mdc`.

## Chat onboarding (`/onboarding`)

Numbered **Your Role** / **Agent Temperament**; persist after each answer; **`get-next-actions`** token before mutating `run` when policy **`require`**.

Full checklist: **`.ai/playbooks/workspace-kit-chat-onboarding.md`**.

Optional Cursor rule: `.cursor/rules/playbook-workspace-kit-chat-onboarding.mdc`.

## Chat behavior interview (`/behavior-interview`)

Six numbered scribe questions; persist each **`interview-behavior-profile`** answer; **`start` resets** — see playbook **gaps** for resume.

Full checklist: **`.ai/playbooks/workspace-kit-chat-behavior-interview.md`**.

Optional Cursor rule: `.cursor/rules/playbook-workspace-kit-chat-behavior-interview.mdc`.

### Confidence tiers (improvement inbox)

Recommendation tasks carry **`metadata.confidenceTier`** (`high` / `medium` / `low`). Filter with:

`pnpm exec wk run list-tasks '{"type":"improvement","status":"ready","confidenceTier":"medium"}'`

## Long-session reload

See `.ai/LONG-SESSION-RELOAD.md`.

## Native SQLite arch mismatch (macOS arm64)

Symptom: `wk run` or `doctor` reports native binding load failures, often with incompatible architecture hints (`have x86_64, need arm64`).

Fix:

1. Ensure Node runtime architecture matches host architecture.
2. Rebuild native addon in the workspace root: `pnpm rebuild better-sqlite3`.
3. Re-run `pnpm exec wk doctor` and then retry the `wk run` command.
