ai-engineering-playbook

Run the full acceptance testing pre-flight pipeline for a feature. Use when asked to "run acceptance prep", "run the pre-flight pipeline", "prepare for acceptance testing", "run [ACCEPTANCE-PREP]", or when an [ACCEPTANCE-PREP] issue is open and ready to start. Orchestrates all four pipeline layers: demo agent, adversarial reviewer, real-data stress agent, synthesis agent. Produces the synthesis brief that the human uses to run the [ACCEPTANCE] session.

Walk through a single feature or flow using the demo agent persona. Use when asked to "demo this feature", "walk me through [flow]", "show me what was built", "run acceptance walkthrough for [feature]", or when validating one specific flow without running the full pre-flight pipeline. Produces a focused ACCEPTANCE-DEMO.md for a single flow. Does not run the adversarial reviewer or real-data stress agent — use acceptance-prep for the full pipeline.

Read the project spec and produce a phased implementation plan: modules identified, ordered by dependency, grouped into phases. Use when asked to "break down the spec", "create an implementation plan", "phase the work", "what order do we build things", or "plan the tickets". Output is a phase plan the engineer reviews and approves before draft-tickets runs on each phase. Does not create tickets — that's draft-tickets.

Draft an agent briefing document (CLAUDE.md or equivalent) from the project spec and existing toolchain configuration. Use when asked to "draft CLAUDE.md", "create the agent briefing doc", "write CLAUDE.md from the spec", or "set up CLAUDE.md". Produces a first draft covering all 7 sections of the briefing framework, with [NEEDS INPUT] markers where the spec doesn't provide enough detail. Run review-claudemd on the output before committing.

Draft the [TEST] and [IMPL] ticket content for one phase of the implementation plan. Use when asked to "draft tickets for phase N", "write tickets for [module]", "create the TEST and IMPL issues for [phase]", or "prepare the next phase tickets". Produces filled-in ticket content for every module in the phase, ready for review-issue to validate before the tickets are opened. Run one phase at a time.

Run the decision narration workflow to capture a design or architectural decision made during an AI coding session. Use when asked to "capture this decision", "generate a decision record", "narrate this decision", "let's do a session mini-retro", or "before I close this window." Goal: move reasoning from the engineer's head into a Decision Record while session context is still live. The record goes into the PR alongside the code change.

Run a post-IMPL retro to identify what should be encoded into setup artifacts before the next ticket. Use when asked to "run the retro", "do the retro", "what should we encode from this ticket?", "post-impl retro", or "retro on PR #N". Also triggers after a review-tdd-green run finds gaps. The goal: surface 3–5 specific candidate additions to CLAUDE.md, issue templates, or hooks — not a comprehensive audit, just what's worth making permanent.

Actively test the engineer's understanding of a system — whether they built it, inherited it, or are reviewing it. Use when asked to "quiz me on [system]", "test my understanding of what we built", "quiz me before this PR", or "help me onboard to [system]". The narration technique applied to comprehension: the act of explaining forces the engineer to find where their understanding breaks down.

Interrogate the engineer's mental model of a system they don't primarily own, before they propose a change to it. Use when asked to "run the cross-system probe", "probe my understanding of [system]", "quiz me before I touch [system]", or when a PR crosses a service boundary or shared contract. The goal: surface knowledge gaps before the PR, not after the incident.

Evaluate a software specification for AI agent readiness using the 9-dimension quality scorecard. Use this skill whenever someone asks to score, evaluate, grade, or audit a spec before implementation begins — or asks "is this spec ready?", "can agents implement this?", or "what's missing from our spec?". Also triggers on requests to improve a spec, find ambiguities, or prepare a spec for AI-assisted development. This is the gate that must pass before pre-implementation begins.

Verify that every [IMPL] issue has a corresponding closed [TEST] issue and a matching test file in the repository. Use when someone asks to "verify TDD pairs", "check test coverage for issues", "are all impl tickets paired with tests?", "run the TDD audit", or "which impl issues are missing tests?". Also useful at sprint planning to confirm the board is correctly structured before assigning work to agents. Requires gh CLI access to query GitHub Issues.

Audit a repository to verify all pre-implementation checklist items are complete before sprint 1 begins. Use this skill when someone asks "are we ready to start implementation?", "run the pre-implementation audit", "check if pre-impl is done", or "verify sprint zero is complete". This is the formal gate between pre-implementation and feature development. It checks: spec readiness, agent briefing doc, enforcement layer, issue templates, scaffolding, and prompt templates (if LLM project).

Audit the agent briefing document (CLAUDE.md or equivalent) for quality, size, overlap with hooks, and missing content. Use this skill whenever someone asks to "review CLAUDE.md", "check the agent briefing doc", "audit agent instructions", or "is CLAUDE.md good?". Also triggers on: "is my CLAUDE.md too long?", "does CLAUDE.md overlap with hooks?", "what's missing from CLAUDE.md?". Run before any PR that modifies the briefing document.

Audit the Claude Code hook configuration (or equivalent enforcement layer) for completeness, correctness, handler type appropriateness, and performance risks. Use when someone asks to "review hooks", "audit the enforcement layer", "check hook config", "are my hooks set up correctly?", or "is my settings.json right?". Also triggers on: editing .claude/settings.json, adding a new hook script, or asking whether a hook should use command vs prompt vs agent type.

Evaluate a drafted GitHub Issue for completeness before assigning it to an agent. Use when someone asks to "review this issue", "is this issue ready for an agent?", "check if this ticket is complete", or "review before I open this". Also triggers when someone pastes an issue draft and asks for feedback, or when a [TEST], [IMPL], [SCAFFOLD], or [DECISION] issue is being finalized. The core question: could an agent open this issue, read only its contents and the referenced spec section, and begin work without a follow-up conversation?

Review a GitHub PR that implements a module against a pre-existing test suite. Use when asked to "review this impl PR", "review this green PR", "is this the best implementation?", or "did the tests catch everything?". Also triggers when an [IMPL] PR link is shared. The core questions: is this the simplest correct implementation, does it actually match the spec (not just the tests), and what did the tests fail to catch?

Review a GitHub PR that adds a suite of failing (red) unit or integration tests. Use when asked to "review this test PR", "review this red PR", "check test coverage for this PR", or "is this test suite complete?". Also triggers when a [TEST] PR link is shared and the request is to find missing tests or suggest revisions. The core question: will this test suite catch every bug the spec protects against — before the implementation is written?