ai-playbook

Use when the user wants the laziest solution that actually works — types /ponytail, says "be lazy", "lazy mode", "simplest solution", "minimal solution", "yagni", "do less", or "shortest path", or complains about over-engineering, bloat, boilerplate, or unnecessary dependencies. Supports intensity levels lite, full, ultra (default). Pairs with caveman, which compresses prose, not code.

Use when the user wants a whole-repo audit for over-engineering — says "audit this codebase", "audit for over-engineering", "what can I delete from this repo", "find bloat", or invokes /ponytail-audit. Like ponytail-review but scans the entire tree, not a diff. One-shot report, applies no fixes. Gated by the ponytail audit_ponytail component.

Use when the user wants to harvest every `ponytail:` comment in the codebase into a tracked debt ledger — says "ponytail debt", "/ponytail-debt", "what did ponytail defer", "list the shortcuts", "ponytail ledger", or "what did we mark to do later". One-shot report, changes nothing. Gated by the ponytail debt_ponytail component.

Use when the user asks how ponytail mode works, what intensity levels exist, what the slash commands are, how to toggle it, or wants a quick-reference card before turning the mode on. One-shot display, not a persistent mode. Trigger: /ponytail-help, "ponytail help", "what ponytail commands", "how do I use ponytail".

Use when the user wants a code review focused exclusively on over-engineering — says "review for over-engineering", "what can we delete", "is this over-engineered", "simplify review", or invokes /ponytail-review. Complements correctness/security review; this one only hunts complexity in the current diff. Gated by the ponytail review_ponytail component.

Use when navigating an unfamiliar codebase, tracing how code connects (callers, dependencies, the blast radius of a change), or whenever the repo ships a graphify-out/graph.json knowledge graph. Query the graph before grepping/reading raw source for orientation.

Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.

Use when the user asks for a commit message, wants a Conventional Commit, or wants a terse commit subject that fits in fifty characters and focuses on why over what.

Use when the user wants to shrink a long markdown file like AGENTS.md, CLAUDE.md, a README, or a runbook to roughly half its size while keeping code blocks, headings, URLs, and file paths intact.

Use when the user asks how caveman mode works, what intensities exist, what the slash commands are, or wants a quick-reference card before turning the mode on.

Use when the user wants a pull-request review delivered as one-line comments with severity emoji, line references, and direct fix suggestions instead of paragraphs.

Use when the user wants compressed agent output, types /caveman, asks to talk like caveman, requests shorter responses, or asks to cut output tokens.

Run the cross-cutting advisory orchestrator that audits the current consumer repo against every playbook rule and offers opt-in remediation for rules whose `.rule.py` implements `apply`. Use when the user asks to "audit playbook compliance", "check what's drifted", "see what the playbook would change", or "fix playbook drift".

Strategic business analyst and requirements expert. Use when the user asks to talk to Mary or requests the business analyst.

Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate.

Guide human-centered design processes using empathy-driven methodologies. Use when the user says "lets run design thinking" or "I want to apply design thinking"

Identify disruption opportunities and architect business model innovation. Use when the user says "lets create an innovation strategy" or "I want to find disruption opportunities"

Apply systematic problem-solving methodologies to complex challenges. Use when the user says "guide me through structured problem solving" or "I want to crack this challenge with guided problem solving techniques"

Craft compelling narratives using story frameworks. Use when the user says "help me with storytelling" or "I want to create a narrative through storytelling"

Create architecture solution design decisions for AI agent consistency. Use when the user says "lets create architecture" or "create technical architecture" or "create a solution design"

Create a PRD from scratch. Use when the user says "lets create a product requirements document" or "I want to create a new PRD"

Lossless LLM-optimized compression of source documents. Use when the user requests to 'distill documents' or 'create a distillate'.

Validate a PRD against standards. Use when the user says "validate this PRD" or "run PRD validation"

Review code changes adversarially using parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor) with structured triage into actionable categories. Use when the user says "run code review" or "review this code"

Plan UX patterns and design specifications. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"

Orchestrate the canonical task↔PR↔release flow end-to-end. Two modes — `/dev-flow start <description>` scaffolds an OpenSpec change + branch + (optional) worktree + git hook ready for commits; `/dev-flow ship` validates the current branch + pushes + opens PR + monitors CI. Use whenever you start any non-trivial change in a playbook-consuming project. LLM-agnostic — works for Claude Code, Cursor, Antigravity, Gemini CLI, OpenCode, and humans.

Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.

Implement an OpenSpec change in parallel using multiple subagents (one per disjoint task group inside the same slice). Use when the slice's tasks.md has ≥2 task groups with disjoint write-paths AND >30 min of parallelisable work. For sequential implementation use openspec-apply-change instead.

Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.

Mine architecture decision records (ADRs), gotcha files, runbooks, and docs/archive for cross-project lessons that warrant ai-playbook canonical specs. Use when a project lacks a populated retros/ directory but has equivalent material in other forms.

Builds, edits or analyzes Agent Skills through conversational discovery. Use when the user requests to "Create an Agent", "Analyze an Agent" or "Edit an Agent".

Sets up BMad Builder module in a project. Use when the user requests to 'install bmb module', 'configure BMad Builder', or 'setup BMad Builder'.

Sets up {module-name} module in a project. Use when the user requests to 'install {module-code} module', 'configure {module-name}', or 'setup {module-name}'.

Plans, creates, and validates BMad modules. Use when the user requests to 'ideate module', 'plan a module', 'create module', 'build a module', or 'validate module'.

Builds, converts, and analyzes workflows and skills. Use when the user requests to "build a workflow", "modify a workflow", "quality check workflow", "analyze skill", or "convert a skill".

Master Test Architect and Quality Advisor. Use when the user asks to talk to Murat or requests the Test Architect.

Teach testing progressively through structured sessions. Use when user says "lets learn testing" or "I want to study test practices"

Generate red-phase acceptance test scaffolds using the TDD cycle. Use when the user says "lets write acceptance tests" or "I want to do ATDD"

Expand test automation coverage for codebase. Use when user says "lets expand test coverage" or "I want to automate tests"

Scaffold CI/CD quality pipeline with test execution. Use when the user says "lets setup CI pipeline" or "I want to create quality gates"