Run a complete quality engineering audit on any codebase. Derives behavioral requirements from the code, generates spec-traced functional tests, runs a three-pass code review with regression tests, executes a multi-model spec audit (Council of Three), and produces a consolidated bug report with TDD-verified patches. Finds the 35% of real defects that structural code review alone cannot catch. Works with any language. Trigger on 'quality playbook', 'spec audit', 'Council of Three', 'fitness-to-purpose', or 'coverage theater'.
How to install quality-playbook?
andrewstellman/quality-playbook
$npx -y skills add andrewstellman/quality-playbook --skill quality-playbookInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Run `npx skills use "https://github.com/andrewstellman/quality-playbook" --skill "andrewstellman/quality-playbook"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.
Use the skills in "https://github.com/andrewstellman/quality-playbook" that are relevant to the current task. Run `npx skills add "https://github.com/andrewstellman/quality-playbook"` and select the relevant skills, then follow their instructions.
SKILL.md
| 1 | # Quality Playbook |
| 2 | |
| 3 | **Version:** 1.5.10 | **Author:** [Andrew Stellman](https://github.com/andrewstellman) | **License:** Apache 2.0 |
| 4 | |
| 5 | **Find the bugs that code review misses** |
| 6 | |
| 7 | Most code review looks at how the code is written. The Quality Playbook looks at what the code is supposed to do, and whether it actually does it. |
| 8 | |
| 9 | Here's how Quality Playbook finds bugs in your code. It explores your codebase and works out its behavioral requirements from two sources: the code itself, and your documentation (specs, issues, chat history, post-mortems). Then it runs a three-pass code review and a multi-model spec audit (the Council of Three) against those requirements. The bugs it turns up are the ones that look correct to anyone who doesn't already know the spec: |
| 10 | |
| 11 | - a function that silently returns null instead of throwing |
| 12 | - a duplicate-key check that passes when the first value is null |
| 13 | - sanitization that runs after the branch decision it was supposed to guard |
| 14 | |
| 15 | It even catches bugs that a thorough adversarial code-review prompt with Claude Opus 4.8 misses. It doesn't stop at finding bugs, though. Along the way it builds the quality infrastructure your project keeps reusing, and every later review cycle runs against it: |
| 16 | |
| 17 | - derived requirements |
| 18 | - functional and integration tests |
| 19 | - contracts and a coverage matrix |
| 20 | - the code-review, spec-audit, and TDD verification protocols themselves |
| 21 | |
| 22 | *This isn't theoretical. Bugs the Quality Playbook found have been accepted and merged upstream, in Google's [gson](https://github.com/google/gson/pull/3006) and the Linux kernel's [zram](https://github.com/torvalds/linux/commit/2f529e73d72048743b6eaa241da6ac2bcb28099e).* |
| 23 | |
| 24 | ## Quick start |
| 25 | |
| 26 | **Install** into your project's root directory (pick one): |
| 27 | |
| 28 | ```bash |
| 29 | npx quality-playbook install --into . --ai-tool claude # from npm, no global install |
| 30 | pip install quality-playbook && quality-playbook install --into . --ai-tool claude # from pip |
| 31 | git clone https://github.com/andrewstellman/quality-playbook # or clone and ask your AI to install it |
| 32 | ``` |
| 33 | |
| 34 | Swap `claude` for `cursor`, `copilot`, `continue`, `codex`, `windsurf`, `cline`, or `aider`. (Prerequisite: Python 3.10+ on your `PATH`.) |
| 35 | |
| 36 | **Run** by opening your project in your AI coding tool and telling the agent: |
| 37 | |
| 38 | > *"Run the Quality Playbook on this project."* |
| 39 | |
| 40 | That's it — the agent auto-discovers the installed skill, runs all six phases, and drops the results into a `quality/` folder. Findings start in `quality/BUGS.md`. |
| 41 | |
| 42 | <!-- TOKENS: pending benchmark run — replace with real input/output token usage from arunner recall runs, e.g. "A full baseline run against repos X / Y / Z cost N input / M output tokens." Do not invent numbers. --> |
| 43 | |
| 44 | ## Contents |
| 45 | |
| 46 | - [How to install the Quality Playbook](#how-to-install-the-quality-playbook) |
| 47 | - [How to run the Quality Playbook](#how-to-run-the-quality-playbook) |
| 48 | - [Example output](#example-output) |
| 49 | - [Need help? Just ask your AI](#need-help-just-ask-your-ai) |
| 50 | - [Running the playbook](#running-the-playbook) |
| 51 | - [What the playbook produces](#what-the-playbook-produces) |
| 52 | - [How it works](#how-it-works) |
| 53 | - [Want to learn more?](#want-to-learn-more) |
| 54 | - [Recent releases](#recent-releases) |
| 55 | - [Running across many repos with arunner](#running-across-many-repos-with-arunner) |
| 56 | - [Repository structure](#repository-structure) |
| 57 | - [How we improve the playbook](#how-we-improve-the-playbook) |
| 58 | - [Context](#context) |
| 59 | - [License](#license) |
| 60 | - [Patent notice](#patent-notice) |
| 61 | |
| 62 | ## How to install the Quality Playbook |
| 63 | |
| 64 | **The fastest path: install from npm or pip.** From your project's root directory, pick one: |
| 65 | |
| 66 | ```bash |
| 67 | # From npm — no global install: |
| 68 | npx quality-playbook install --into . --ai-tool <tool> |
| 69 | |
| 70 | # From pip / uvx / pipx (Python 3.10+): |
| 71 | uvx quality-playbook install --into . --ai-tool <tool> # one-shot, no global install |
| 72 | pipx run quality-playbook install --into . --ai-tool <tool> |
| 73 | pip install quality-playbook && quality-playbook install --into . --ai-tool <tool> |
| 74 | ``` |
| 75 | |
| 76 | Where `<tool>` is one of `claude`, `cursor`, `copilot`, `continue`, `codex`, `windsurf`, `cline`, or `aider`. The skill installs into `.<tool>/skills/quality-playbook/` (or `.github/skills/quality-playbook/` for `copilot`). Concrete examples: |
| 77 | |
| 78 | ```bash |
| 79 | npx quality-playbook install --into . --ai-tool claude # Claude Code |
| 80 | npx quality-playbook install --into . --ai-tool cursor # Cursor |
| 81 | npx quality-playbook install --into . --ai-tool copilot # GitHub Copilot |
| 82 | ``` |
| 83 | |
| 84 | **Alternative: install via the Claude Code plugin marketplace.** If you use Claude Code, you can add QPB as a marketplace plugin — one command to add the marketplace, one command to install: |
| 85 | |
| 86 | ``` |
| 87 | /plugin marketplace add https://github.com/andrewstellman/quality-playbook |
| 88 | /plugin install quality-playbook |
| 89 | ``` |
| 90 | |
| 91 | Use the full `https://` URL — the shorthand `github.com/...` form makes Claude Code attempt an SSH clone, which fails on machines without a GitHub SSH key configured. |
| 92 | |
| 93 | After install, the QPB skill is auto-discoverable in any project you open with |
Related
6 picksType
- tddTest-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.Jul 2026
- test-driven-developmentUse when implementing any feature or bugfix, before writing implementation codeJul 2026
- qaInteractive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues.Jul 2026
- verification-before-completionUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output…Jul 2026
- webapp-testingToolkit for interacting with and testing local web applications using Playwright.Jul 2026
- playwright-best-practicesUse when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking…Jul 2026
