playbook

ai-playbook

A Claude Code plugin that gives a small, opinionated workflow for AI-assisted development. The premise: a single well-maintained CLAUDE.md plus a small set of distilled-context files in the project's docs folder beats elaborate process documentation, and a thorough up-front plan with explicit acceptance criteria is the right governance for substantial work — not a meeting.

The plugin contains six skills, three plugin-level hooks, and an optional bundled MCP server. Together they automate the parts of the workflow most often skipped: configuring where durable context lives, writing the initial context file, seeding starter docs for an existing codebase, planning substantial changes properly, recording the decisions behind them, and keeping the permanent context current as work happens.

Installation

Register the marketplace, then install the plugin from it:

/plugin marketplace add SlinkyBMajor/ai-playbook
/plugin install playbook@ai-playbook

Commands are namespaced /playbook:<skill>. After installing, run /reload-plugins (or restart) to activate it.

Scopes — user vs project

/plugin install installs at user scope by default: available in every project on your machine, which is what you usually want. To choose a different scope, run /plugin, open the Discover tab, press Enter on playbook, and pick:

• User (default) — for you, across all your projects.
• Project — for everyone working in this repository; the choice is written to the repo's checked-in .claude/settings.json, so collaborators are prompted to install it when they trust the folder.
• Local — for you, in this repository only.

Or target a scope directly from the command line:

claude plugin install playbook@ai-playbook --scope project

Updating

Refresh the marketplace, then update the plugin:

/plugin marketplace update ai-playbook
/plugin update playbook@ai-playbook

Then /reload-plugins (or restart) to load the new version.

Auto-install for a team

To have a repository offer the playbook to everyone who opens it, commit both the marketplace and the plugin to that project's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "ai-playbook": {
      "source": { "source": "github", "repo": "SlinkyBMajor/ai-playbook" }
    }
  },
  "enabledPlugins": { "playbook@ai-playbook": true }
}

Collaborators are prompted to install it when they trust the folder. Update later with /plugin marketplace update ai-playbook followed by /reload-plugins.

Quickstart

Run these in order in a fresh repo. Each is explained under Usage.

1. /playbook:init — pick where durable context will live (defaults to docs/). Once per repo.
2. /playbook:claude-md-setup — interview to produce the root CLAUDE.md.
3. /playbook:scaffold-docs — on an existing codebase with few docs, suggest and seed starter topic files. Optional, once.
4. Do work. Small change → just edit (the direct path). Substantial change → /playbook:spec-workflow (the spec path).
5. /playbook:distil — when wrapping up, capture anything durable into permanent context.

Concepts

The whole playbook is built from a handful of moving parts. This section names each one so the architecture is legible.

• Scope. A repo or sub-repo with its own CLAUDE.md. Every file the playbook reads or writes is resolved relative to a scope, which is what lets a super-repo and its sub-repos each stay self-contained.

• CLAUDE.md. The root context file Claude Code loads automatically every session. The playbook keeps it to five sections (what it is, stack, directory index, commands, gotchas) and under ~150 lines; anything longer is a signal that content belongs in the docs folder instead.

• Docs folder + marker. Where distilled durable knowledge lives — docs/ by default, configurable via init. The playbook recognises its own folder by a marker: a CLAUDE.md inside it headed # Durable project context. Keeping durable knowledge in a normal docs folder means non-Claude developers find the same thing under a familiar path. (Resolution precedence: shared/docs-folder-resolution.md.)

• The two paths. Small, contained changes take the direct path — just edit, no overhead. Substantial work (multiple files, a new pattern, acceptance criteria you can't hold in your head) takes the spec path, which runs a thorough plan — with explicit acceptance criteria — before any code is written, then verifies the result against it. The playbook never forces the spec path on small work.

• Distillation. The closing step of both paths: lifting anything a future developer would want to know out of a finished change and into permanent context (CLAUDE.md or the docs folder). This is how permanent context grows by distillation rather than accumulation — specs don't pile up, they distil and retire.