A field guide to the playbooks

Using and learning them

• Load one. fm playbooks show NAME fills in the project's facts and adds its own notes from .claude/playbooks/.
• Practise. fm playbooks kata NAME gives held-out briefs to answer; --answer FILE scores yours.
• Score a run. fm playbooks score NAME --task ID shows which steps a finished task followed.
• Learn from a change. fm playbooks lesson RANGE is a five-minute read of a diff: what changed, where, what its tasks learned and the checklists to read it with.
• Grow your own. fm playbooks draft ID turns a finished task into a draft; mine and counter read the repo's history for what changes together and what failed.

build

build/cpp-build C++ Build Error Resolver

build/csharp-build C# build errors (dotnet, MSBuild, NuGet)

Use when `dotnet build`, `dotnet test` or `dotnet restore` fails. The goal is a green build with the smallest diff that fixes the cause. Built on the library cards `fm lib show csharp` (the baseline), `fm lib show dotnet-cli` (MSBuild, restore, solution-wide settings) and `fm lib show nuget` (package references, central versions, audit).

build/go-build Go build errors

Use when `go build`, `go vet` or `go test` fails to compile. The goal is a green build with the smallest diff that fixes the cause: no refactors, no silenced checks. Built on the library cards `fm lib show go` (the baseline), `fm lib show go-modules` (go.mod, go.sum, toolchains), `fm lib show go-errors` (multi-value returns, wrapping) and `fm lib show go-testing` (when the failure is in a `_test.go` file).

build/jvm-build JVM build errors (Gradle, Maven, Java, Kotlin)

Use when a Gradle or Maven build of Java or Kotlin code fails: in configuration, dependency resolution or compilation. Test failures are a different job (see `references/verify/`). The goal is a green build with the smallest diff that fixes the cause. Built on the library cards `fm lib show java`, `fm lib show kotlin`, `fm lib show gradle`, `fm lib show gradle-version-catalogs` and `fm lib show maven`.

build/rust-build Rust Build Error Resolver

build/shell-build Shell script errors (bash -n, ShellCheck, bats)

Use when a shell script fails to parse, fails ShellCheck, dies under strict mode, or fails its bats tests. Shell has no compiler, so "the build" here is three checks: the parser (`bash -n`), the linter (`shellcheck`) and the tests (`bats`). The goal is all three green with the smallest diff. Built on the library cards `fm lib show bash` (strict mode, bats), `fm lib show shellcheck` (the SC codes, directives), `fm lib show shell-scripting` (quoting, traps, POSIX sh) and `fm lib show cli-tests` (testing a script through its real entry point).

build/swift-build Swift build errors (SwiftPM, Xcode)

Use when `swift build`, `swift test` or `xcodebuild` fails to compile. The goal is a green build with the smallest diff that fixes the cause. Built on the library cards `fm lib show swift` (the baseline), `fm lib show swift-package-manager` (Package.swift, resolution), `fm lib show xcodebuild` (schemes, destinations, signing) and `fm lib show swift-concurrency` (Swift 6 isolation and Sendable errors).

build/typescript-build Build Error Resolver

clean

clean/characterisation-tests Characterisation tests: pin behaviour before a refactor

Use when you must change code that has thin or no tests and nobody can say exactly what it does: a refactor, a port to another language or library, a performance rewrite, or a cleanup that should change nothing. The tests record what the code does today, right or wrong; they are a safety net, not a specification.

clean/code-simplifier Code Simplifier Agent

clean/deprecation Deprecation: announce, shim, remove

Use when a public function, CLI flag, config key, endpoint, file format or setting is going away or changing shape, and someone outside this change may depend on it. Internal code with every caller in this repo needs no deprecation: change the callers in the same commit.

clean/refactor-cleaner Refactor & Dead Code Cleaner

clean/repo-sweep Whole-repo cleanup sweep (Foreman's own, T-0364)

Use when asked to "clean up the repo / docs / code / briefs / dead code / unused or replaced functionality". A dead-code tool that finds nothing is one row of evidence, never the verdict: a sweep is done when every area has been checked by a stated method, not when a gate stays green.

context

context/context-budget Context Budget

context/decks-and-reports Decks and reports: the answer first

Use when making something people read to decide or to stay informed: a slide deck, a written report, a status update, a results write-up, a proposal. Charts inside follow `../ui/data-viz.md`; a page someone follows to do a task is `docs.md`.

context/docs Docs: task-first pages, examples that run

Use when writing or reworking documentation a person reads to get something done: a README, a guide, a how-to, a reference page, CLI help. For keeping a whole repo's doc set owned and fresh over time, use `living-docs.md`.

context/living-docs Living Docs Governance

context/strategic-compact Strategic Compact Skill

evals

evals/eval-harness Eval Harness Skill

evals/loop-design-check Loop Design + Review

fix

fix/flaky-tests Flaky tests

Use when a test passes and fails without a code change.

fix/migration Schema and data migrations

Use when a change alters a live database: a new, renamed or dropped column or table, a type change, a new constraint or index, or a backfill. The rule underneath: old code and new code both run against the schema during a deploy, so every step must work with both.

fix/sql SQL: query review, indexes and plans

Use when a query is slow, a page times out on the database, a new query or index goes into review, or an ORM call might be issuing more SQL than it looks. Schema changes belong in `migration.md`.

fix/text-time-bytes Text, time, bytes and money: encodings, time zones, amounts

Use when code reads or writes text from outside (files, HTTP, a database, a terminal), stores or compares timestamps, schedules anything by the calendar, or handles prices, totals, tax or currency. Bugs here pass every test written in one locale, one time zone and round numbers.

ground

ground/code-architect Code Architect Agent

ground/code-explorer Code Explorer Agent

ground/search-first /search-first — Research Before You Code

lang

lang/cpp-coding-standards C++ Coding Standards (C++ Core Guidelines)

lang/cpp-testing C++ Testing (Agent Skill)

lang/python-patterns Python Development Patterns

lang/python-testing Python Testing Patterns

lang/rust-patterns Rust Development Patterns

lang/rust-testing Rust Testing Patterns

lang/stdlib-python Python: the standard library first

Use when you are about to add a Python dependency, write a helper, or review code that rebuilds something the standard library already has. Every dependency is code you didn't read, a version to keep current and a supply-chain risk; the standard library ships with the interpreter and is already reviewed.

ops

ops/incident Incident: stop the harm, then learn

Use when something people depend on is broken or wrong right now, or about to be: an outage, errors or slowness users can see, wrong data being written, a security event in progress. A bug that hurts nobody yet is an ordinary FIX (the intake skill's `references/debugging.md`). In Foreman, capture it with the urgent tag (`FIX!:`) so the current task is checkpointed and the incident takes the focus.

ops/observability Observability: signals worth having

Use when adding a service, endpoint, job or queue; when an incident timeline had a gap ("we couldn't tell when it started"); or when someone asks to "add logging". Every signal costs money and attention, so each one must answer a question someone will ask during an incident (`incident.md`).

perf

perf/benchmark-loop Benchmark Optimization Loop

perf/latency-critical Latency Critical Systems

perf/profiling Profiling

Use when you know something is slow but not where (pair with benchmark-loop.md for the before/after).

plan

plan/api-design API design

Use when adding or changing a public interface: a CLI, HTTP/RPC endpoint, library function, config format or file format.

plan/decision-memo Decision memo: options, choice, why, revisit

Use when a choice is costly to reverse, someone else has to approve it, or the same question keeps coming back: picking a library, a data store, an approach for an M or L task, a vendor, a policy. A memo is short and made before the work; for a lasting architecture choice, also write an ADR (`../reflect/architecture-decision-records.md`).

plan/intent-driven-development Intent-Driven Development

plan/planner Implementation Plan: [Feature Name]

reflect

reflect/agent-introspection Agent Introspection Debugging

reflect/architecture-decision-records Architecture Decision Records

release

release/demo-production Demo production: scripted, seeded, short

Use when making a product demo: a release video, a GIF for a README or pull request, a terminal recording, or a live walkthrough. A demo is a claim about the product, so it is held to the same evidence rule as the code: it shows only what the shipped build really does.

release/dependency-admission Dependency admission: before adding one

Use when you are about to add any new package, library, plugin, action, container base image or vendored file to a project, including a dev-only or transitive one you pull in on purpose. Upgrading one already admitted is `dependency-upgrade.md`.

release/dependency-upgrade Dependency upgrade

Use when bumping a library, toolchain or runtime.

release/release-and-changelog Release and changelog

Use when cutting a version, tagging, or publishing.

review

review/code-reviewer code-reviewer

review/cpp cpp

review/python python

review/rust rust

review/security Security Reviewer

review/silent-failures Silent Failure Hunter Agent

review/test-coverage PR Test Analyzer Agent

review/type-design Type Design Analyzer Agent

review/typescript typescript

security

security/bounty-triage Security Bounty Hunter

security/cloud-infrastructure Cloud & Infrastructure Security Skill

security/security-review Security Review Skill

ui

ui/composition Composition, depth and states

Use when a web or app screen gets its layout: where things sit, what is in front of what, how a landing page runs from top to bottom, and what every screen looks like when the data is missing, slow, broken or too long. For terminals see `terminal-ui.md`.

ui/data-viz Data viz: one claim, one axis, colour by job

Use when a screen, report or doc shows numbers as a chart, a sparkline or a big number. It builds on `type-and-colour.md` (palette roles, reserved status colours, contrast) and `motion.md` (tokens, reduced motion); those rules hold here unchanged.

ui/design-direction Design direction before pixels

ui/game-feel Game feel: juice with intensity caps

Use when a game or a playful interface needs to feel responsive and physical: hits that land, jumps that pop, buttons that squish, rewards that burst. Applies to Phaser, Pygame, Godot, LÖVE, Unity and canvas or DOM games alike; the engine APIs live in the cards at the end.

ui/interaction Interaction: feedback, keyboard, forms, words and the phone

Use when a web or app screen gets something to do: a form, a button that saves or sends, a menu, a list you act on, a sign-up, a checkout, a settings page. The sibling playbooks decide how a screen looks; this one decides how it behaves in the hand. Most UI that looks finished fails here first: the button that gives no sign it was pressed, the error that says "Invalid", the field hidden behind the phone's keyboard, the menu a keyboard can't leave.

ui/motion Motion: choreography, timing and reduced motion

Use when adding or reworking animation in a web or app UI: transitions, enter and exit, loading, list changes, page changes. For terminals see `terminal-ui.md`; for library code see the cards at the end.

ui/scene-3d 3D on the web: a designed scene that never breaks the page

Use when a page gets a WebGL scene: a hero object, a product viewer, a data sculpture, an ambient background. Applies to three.js, React Three Fiber and raw WebGL alike. The API lives in the cards (`fm lib show three-js`, `fm lib show react-three-fiber`, `fm lib show postprocessing`, `fm lib show webgl`, `fm lib show glsl`, `fm lib show shader-performance`); this playbook holds the decisions, the numbers and the failure handling.

ui/scrollytelling Scrollytelling: steps the reader controls

Use when a story or explainer changes a sticky graphic (a chart, a map, a diagram) as the reader scrolls through text steps. It builds on `motion.md` (tokens, reduced motion as its own path) and `data-viz.md` (the graphic's claim, colour and table view); their rules hold here unchanged.

ui/sound-design Sound design: off by default, earcons, volume caps

Use when a web or app UI plays sound: notification chimes, confirmations, alerts, timers, ambient beds. Games and playful UI start from `game-feel.md`, whose sound caps this file shares; the two never disagree.

ui/terminal-ui Terminal and mod UI

Use when building or reworking UI inside a terminal app or a Claude Code mod (panes, bands, status lines, tool rows), or a command-line tool's own output. Each rule below can be marked pass or fail by a reviewer. Foreman's own worked examples: `fmcodeterm.py` (the terminal: keys, paste, resize, colour depth, the session) and `fmcodetui.py` (the app drawn on it: `width`, `fit`, `render`).

ui/type-and-colour Type and colour that read as chosen

Use when a web or app screen gets its type and colour: a new product, a restyle, a dark mode, or "the text looks off". `design-direction.md` picks the stance (the family class, the scale ratio, the ink); this playbook turns that stance into a scale, a pairing, a palette and the proof that they hold. For terminals see `terminal-ui.md`.

ui/visual-qa Visual QA: screenshots, an eyeball pass and a receipt

Use when a task changes what a web screen looks like: a new view, a restyle, a dark mode, a layout fix, a motion change. Green tests say the code does what the tests ask; only a frame says the screen looks right. This playbook proves a UI change by looking at it: `fm smoke` for the defects a crawler can name, the start page's frames and hostile profiles, a small frame script for the other views and fixtures, a checklist for the eye, and a receipt in the task's evidence.

verify

verify/tdd-guide Required: 80%+ branches, functions, lines, statements

verify/tdd-workflow Test-Driven Development Workflow

verify/verification-loop Verification Loop Skill