Metadata-Version: 2.5
Name: ai-playbook
Version: 1.2.0
Summary: CLI tool for deploying ai-playbook agents to Claude, Copilot, Codex, Cursor, or Kiro
Project-URL: Homepage, https://github.com/meenumathew/ai-playbook
Project-URL: Repository, https://github.com/meenumathew/ai-playbook
Project-URL: Issues, https://github.com/meenumathew/ai-playbook/issues
Project-URL: Documentation, https://github.com/meenumathew/ai-playbook/tree/main/docs
Project-URL: Changelog, https://github.com/meenumathew/ai-playbook/blob/main/CHANGELOG.md
Author: Meenu Mathew
Maintainer: Meenu Mathew
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,claude,codex,copilot,cursor,kiro,playbook,tdd,xp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Shells
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: rich<16.0,>=13.0.0
Requires-Dist: typer<1.0,>=0.9.0
Description-Content-Type: text/markdown

# AI Playbook

[![CI](https://github.com/meenumathew/ai-playbook/actions/workflows/ci.yml/badge.svg)](https://github.com/meenumathew/ai-playbook/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/meenumathew/ai-playbook/branch/main/graph/badge.svg)](https://codecov.io/gh/meenumathew/ai-playbook)
[![CodeQL](https://github.com/meenumathew/ai-playbook/actions/workflows/codeql.yml/badge.svg)](https://github.com/meenumathew/ai-playbook/actions/workflows/codeql.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/meenumathew/ai-playbook/badge)](https://scorecard.dev/viewer/?uri=github.com/meenumathew/ai-playbook)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13487/badge)](https://www.bestpractices.dev/projects/13487)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

A developer workflow framework for AI-assisted software development. Eight agents take a change from idea to reviewed, release-ready code and support production-incident response using **Extreme Programming (XP)**, **Test-Driven Development (TDD)**, and **Domain-Driven Design (DDD)** practices. Planning, audit, and incident work is captured in markdown artifacts, so work is resumable across sessions and AI tools.

> **Audience.** Developers building production-minded software who are comfortable with TDD, refactoring, and code review.

## Prerequisites

The playbook is most useful when you are already comfortable with:

- **Test-Driven Development**: the red-green-refactor cycle, test doubles, the test pyramid.
- **Refactoring**: code smells; extract, inline, and move patterns; working in small steps.
- **Code review**: reading diffs, giving and receiving feedback.
- **Git**: branching, rebasing, conventional commits.
- **At least one backend language**: Python, TypeScript, Go, or Rust.

## When the Playbook Is a Good Fit

- You ship production code and want AI tools to follow your team's standards.
- AI tools have produced code that ignores your architecture, skips tests, or drifts from requirements.
- You work across multiple AI tools (Claude, Copilot, Codex, Cursor, Kiro) and want a consistent workflow.
- Your team uses any methodology (Scrum, Kanban, Shape Up, or no formal process) with any project-management tool or issue tracker (Jira, GitHub Issues/Projects, GitLab Issues, Bitbucket Issues, Linear, or none).

## When It Is Not

- You are learning to code for the first time: start with tutorials and courses.
- You want a plug-and-play AI copilot with no configuration: this is an opinionated workflow framework, not a chat wrapper.
- Your team does not write tests: the playbook enforces TDD, and without buy-in it will feel like friction.

---

## What the Playbook Does

AI coding tools are capable but unguided: they write code without grounding in requirements, skip tests, ignore existing patterns, and drift from intent. The playbook gives AI tools a structured workflow: refine the idea or tracker work item, research the codebase, plan in vertical slices, build test-first, review against standards. The workflow uses markdown story artifacts, research, plans, audits, reviews, and incidents where durable context matters, so context survives across sessions, project-management tools, and AI tool switches.

### Established practices vs playbook policy

The knowledge base is not a claim that every rule is an industry standard.
It combines established practices (XP/TDD, DDD, Semantic Versioning,
OWASP-aligned security review, DORA metrics, and Diataxis documentation) with
opinionated operating policy for AI-assisted delivery.

Approval gates, agent handoffs, read budgets, artifact formats, quality tiers,
and advisor/executor model routing are playbook defaults. They are
contract-tested here, but teams should adapt them through documented
configuration or adopter packs and measure results in their own environment.
Python is the maintained language reference; other language templates require
team-owned conventions. See [Known limitations](docs/limitations.md) for the
current evidence boundary and unbenchmarked areas.

---

## Key Features

- **Eight specialised agents**: story-refiner, slice-planner, xp-pair-programmer, diff-reviewer, release-captain, incident-responder, code-inspector, docs-maintainer.
- **Two-layer testing (acceptance tests + unit TDD)**: acceptance tests written from story acceptance criteria verify *built the right thing*; unit TDD drives the implementation, verifying *built it right*. xp-pair-programmer enforces both layers.
- **Quality tiers**: set `prototype` or `production` globally, then override individual agents in `.ai-playbook.toml` when one needs different ceremony.
- **Language-agnostic workflow**: agents and the starter harness detect common project configs. Python is the maintained reference implementation; other stacks start from team-owned convention templates.
- **Tool-aware deployment** *(CLI)*: `ai-playbook deploy` writes the right files to the right places for Claude, GitHub Copilot, Codex, Cursor, and Kiro. Claude, Copilot, and Cursor get slash commands; Codex and Kiro use natural-language invocation.
- **Measurable static context**: `ai-playbook context-report --agent all` reports the fixed rules, each agent, and declared KB preloads as characters plus a clearly labelled token estimate. It supports pack overlays and does not misrepresent the estimate as provider billing telemetry.
- **Privacy-minimal local telemetry**: optional Claude `Stop` and Codex `SessionEnd` hooks record only timestamp, source, approximate turns, and best-effort active-agent name. They never store or transmit session identifiers, content, model details, token counts, repository content, or credentials.
- **Adopter-local packs**: extend or override the playbook core with project-specific agents, knowledge-base files, skills, or templates via `.ai-playbook.toml`. Optional `pack.toml` metadata records pack versions and compatibility bounds. Core updates flow through `uv tool upgrade ai-playbook` (or `pip install -U ai-playbook`); pack content survives. Commands are core-only in v1. See [CLI Reference § Packs](docs/cli-reference.md#packs).
- **Model-agnostic tiers**: agents declare `advisor` or `executor` tier in frontmatter; map tiers to whatever models you use (Anthropic, OpenAI, Google, Ollama-backed local models, mixed). Source files never hard-code model IDs. Deploying to Claude materializes your `[model_tiers]` mapping into deployed agent frontmatter, and deploying to Codex materializes `[model_tiers]` plus optional `[model_reasoning_efforts]` into native custom-agent TOML; other tools map tiers in their own config. See [`knowledge-base/model-tier.md`](knowledge-base/model-tier.md).
- **Resumable**: file-based artifacts (stories, research, plans, audits, reviews, incidents) let any AI tool pick up where another left off.
- **Project-management-tool agnostic** *(work item in, story artifact out)*: `skills/issue-fetch/SKILL.md` accepts a Jira issue key, GitHub issue or Project item, GitLab issue, Bitbucket Cloud issue, Linear issue ID, tracker URL, or pasted work item. The agent preserves the original reference in `issue-ref:`, resolves local story artifacts first, then fetches via the configured CLI, MCP server, or provider API. The CLI itself does not call any tracker.
- **Host-agnostic** *(skill contract)*: `skills/host-adapter/SKILL.md` defines stable operation IDs (`host.pr.create`, `host.pr.review`, `host.pr.merge`) for GitHub, GitLab, Bitbucket Cloud, and Gitea/Forgejo. Adopters satisfy the contract with their host CLI (`gh`, `glab`, `tea`) or REST. This is a markdown contract for agents, not a Python runtime adapter inside the CLI.
- **Eval-backed** *(harness)*: each agent ships input + expected pairs in `evals/` plus a structural validator in `evals/run_eval.py`. An optional, opt-in LLM-as-judge workflow (`.github/workflows/eval-drift.yml`) catches semantic drift; it is manual by default (run it from the Actions tab via `workflow_dispatch`, or re-enable the weekly cron in the workflow) because that step calls the Anthropic API and requires the `ANTHROPIC_API_KEY` repo secret (it fails closed without it). The structural pass is offline and vendor-neutral. The judge scores committed baselines in `evals/samples/`: one captured live-agent baseline (story-refiner, repo-grounded) plus hand-curated seeds for the rest: alongside adversarial baselines (must pass) and deliberately-flawed negative controls (must fail, catching judge leniency drift). A green eval run proves rubric-baseline-judge agreement, not full live agent behaviour (see `evals/samples/README.md` § Scope).
- **Self-improving**: the built-in retrospective skill turns session friction into knowledge-base updates.

---

## Quick Start

```bash
# 1. Install the CLI. Requires Python 3.12+ and uv on PATH.

# (a) From PyPI (recommended).
uv tool install ai-playbook
# or:  pipx install ai-playbook
# or:  pip install ai-playbook

# (b) From source (for contributors or pre-release evaluation).
git clone https://github.com/meenumathew/ai-playbook.git
cd ai-playbook
uv tool install --editable .           # tracks local edits
# or:  pipx install --editable .
# or:  uv tool install .                # immutable install from source

# 2. Deploy into your project.
cd /path/to/your-project
ai-playbook init
ai-playbook deploy --agent all --tool claude

# 3. Wire the deployed pre-commit hooks (one-time per clone).
# Required so the Teach-back commit-msg gate, gitleaks secret scan,
# and shellcheck/markdownlint hooks run locally: not just in CI.
uvx pre-commit==4.3.0 install
uvx pre-commit==4.3.0 install --hook-type commit-msg
```

Set the **quality tier** in the deployed `CLAUDE.md`: `prototype` or `production`. Every agent calibrates ceremony to that tier.

Then open your AI tool and run:

```text
Use story-refiner: here's the feature: <describe the outcome>
```

Recommended invocation sequence: **story-refiner** → **slice-planner** → **xp-pair-programmer** → **diff-reviewer** → **release-captain**. Invoke each step deliberately; the CLI does not auto-run an agent chain.

For trivial changes, skip story-refining:

```text
Use xp-pair-programmer: <describe the change>
```

---

## The Dev Loop

```text
story-refiner    →  Refine the idea, research the codebase, write a verified story
     ↓
slice-planner    →  Design approach, structure vertical slices, write tactical plan
     ↓
xp-pair-programmer          →  Acceptance tests from acceptance criteria (outer loop), then unit TDD (inner loop)
     ↓
diff-reviewer    →  Verify against acceptance criteria, knowledge base standards, and Definition of Done
     ↓
release-captain  →  Open PR/MR, watch CI, merge on approval, merge a release PR, tag, post-deploy smoke
```

When production breaks, **incident-responder** triages, ranks hypotheses, writes the blameless postmortem, and proposes follow-up artifacts. It is read-only on production; humans, with release-captain, execute mitigations.

**code-inspector** runs health checks and **docs-maintainer** writes documentation and Architectural Decision Records. See the [User Guide](docs/user-guide.md) for all workflow paths: minimal, spike, solo, and team.

### Scope: what release-captain does and does not do

release-captain ships up to the tag, not into production. The playbook deliberately keeps deploy execution outside the agent surface so adopters wire their own CD pipeline.

| release-captain does | release-captain does NOT |
|---|---|
| Open PR/MR via the host-adapter (GitHub, GitLab, Bitbucket Cloud, Gitea) | Auto-merge: every merge requires explicit user approval |
| Watch CI and refuse to proceed on red | Run `kubectl`, `terraform`, `ansible`, `helm`, `docker push`, or any deploy command |
| Bump version and update `CHANGELOG` through a release PR, then tag its merged remote commit | Push a tag without explicit user approval for that push |
| Run the post-deploy smoke checklist after a deploy lands | Execute the deploy itself: your CI/CD picks up from the tag |
| Hand off to incident-responder if smoke fails | Roll back deploys, toggle feature flags, scale services, rotate secrets |

For auto-deploy on tag push, configure your CI/CD pipeline (GitHub Actions, GitLab CI, Bitbucket Pipelines, ArgoCD) to react to `v*` tags. Deploy is environment-specific, and the failure mode of an over-eager agent is high: the playbook stays out of that loop by design. See [`knowledge-base/release.md`](knowledge-base/release.md) for the full gate list.

This repository's own [auto-release workflow](.github/workflows/auto-release.yml)
also preserves that boundary: it opens a release PR for generated version and
changelog changes, waits for humans and branch protection to govern the merge,
then tags the exact merged commit. Credential setup and
`Permission denied (publickey)` recovery are documented in
[`RELEASING.md`](RELEASING.md#auto-release-credentials).

---

## Your First Feature: Walkthrough

An end-to-end example for a small change. Time: about 5 minutes.

**Scenario.** Add input validation to an existing function.

**Step 1. Start xp-pair-programmer.**

```text
Use xp-pair-programmer: Add input validation to create_user in src/users.py.
Reject empty names and emails without an @ symbol.
```

**Step 2. xp-pair-programmer writes acceptance tests first (outer loop).**

Before any production code, xp-pair-programmer writes a failing acceptance test for each acceptance criterion at the system boundary:

```python
# tests/acceptance/test_create_user.py
def test_create_user_rejects_empty_name():
    with pytest.raises(ValueError, match="name"):
        create_user(name="", email="valid@example.com")

def test_create_user_rejects_invalid_email():
    with pytest.raises(ValueError, match="email"):
        create_user(name="Alice", email="no-at-symbol")
```

Both fail, confirming the acceptance criteria are testable and the team is building the right thing.

**Step 3. xp-pair-programmer drives implementation with unit TDD (inner loop).**

One acceptance criterion at a time, with the simplest code that passes:

```python
if not name:
    raise ValueError("name must not be empty")
```

Run the first acceptance test: green. Move to the next criterion, write code, refactor.

**Step 4. All acceptance tests pass.**

```text
AC 1: rejects empty name
AC 2: rejects invalid email

Changes staged. Say 'commit' to proceed.
```

**Step 5. Reply `commit`.** Done. Optionally run diff-reviewer on the diff.

**Why two layers.** Acceptance tests verify *what*: built the right thing, from acceptance criteria. Unit tests verify *how*: built it right, from the implementation. The two-layer pattern is from [Acceptance Test-Driven Development (ATDD)](https://agilealliance.org/glossary/atdd/).

---

## Which Path?

```text
Is the change trivial? (typo, rename, one-liner, config)
  └─ YES → Minimal: xp-pair-programmer → diff-reviewer
  └─ NO → Is the requirement clear and the design obvious?
           ├─ YES, ≤ 5 ACs → xp-pair-programmer (from story) → diff-reviewer
           ├─ YES, 6–7 ACs → slice-planner → xp-pair-programmer → diff-reviewer
           ├─ YES, 8+ ACs → story-refiner to split/trim → slice-planner → xp-pair-programmer → diff-reviewer
           └─ NO → Do you understand the problem space?
                    ├─ YES → story-refiner → slice-planner → xp-pair-programmer → diff-reviewer
                    └─ NO  → Spike (timebox) → story-refiner → ...
```

---

## Project-Specific Knowledge Base

Some files are project-specific: adopters fill them in for their own codebase. You must edit them by hand; agents only seed, they do not infer your domain.

Seeding happens at one of two times. **Agent-time:** an agent notices the file is missing, copies it from `templates/`, and warns you that it is unedited. **Deploy-time:** `deploy` installs the file on first run and never overwrites it afterwards, so your edits survive every upgrade (`doctor` calls these `adopter-owned (seeded)`; see [Seeded Files](docs/architecture.md#seeded-files-adopter-owned-state)).

| File | Purpose | Seeded from |
|------|---------|-------------|
| `knowledge-base/domain-language.md` | Project glossary: terms used in stories, plans, code, and tests | the shipped file, at deploy time |
| `knowledge-base/quality-gates.md` | Project quality contract: the gate commands this project runs and the critical paths it protects | the shipped file, at deploy time |
| `knowledge-base/languages/<lang>.md` | Per-language conventions (auto-detected from `pyproject.toml`, `package.json`, and similar config) | `templates/language-conventions-template.md` |
| `knowledge-base/languages/testing-<lang>.md` | Per-language testing conventions | `templates/testing-language-template.md` |
| `docs/limitations.md` | Known limitations: what the system does not do, does not support, or assumes | `templates/limitations-template.md` |
| `docs/adr/NNNN-*.md` | One ADR per architectural decision | `templates/adr-template.md` |
| `knowledge-base/lessons.md` | What this project taught you the hard way: dead ends, environmental constraints, references that took too long to find | the shipped file, at deploy time |

When an agent seeds a file, it reports: `Seeded docs/limitations.md from template: review and edit.` Open the file and replace the placeholders with your own content. The deploy-time files arrive filled in with the playbook's own examples instead of placeholders, so replace those with your project's terms and commands. Until you do, plans and stories may drift toward generic language.

Files seeded at deploy time keep your edits through every upgrade; the health check reports them as `adopter-owned (seeded)` rather than stale, and the change comparison leaves them out. `docs/limitations.md` and `docs/adr/` are never deployed, so they were always safe. The `languages/` pair is still maintainer content and is overwritten by the next `deploy`, with the previous copy in `.playbook-backup/`; those files are mostly generic language convention rather than your project's specifics, so extending seeding to them is a separate decision.

---

## Documentation

Docs follow the [Diataxis framework](https://diataxis.fr/). The canonical docs map is [Documentation Index](docs/README.md); this root README stays the project landing page.

| Need | Start here |
|------|------------|
| First successful walkthrough | [Getting Started](docs/getting-started.md) |
| Day-to-day tasks | [User Guide](docs/user-guide.md) and [How-to Guides](docs/how-to/) |
| Exact commands and contracts | [CLI Reference](docs/cli-reference.md) |
| Design context and rationale | [Architecture](docs/architecture.md) and [Methodology and References](docs/references.md) |
| Full Diataxis map | [Documentation Index](docs/README.md) |

---

## Quality Enforcement (Harness Engineering)

The playbook does not stop at documenting rules: it enforces them mechanically.

| Layer | Mechanism | How it blocks violations |
|-------|-----------|--------------------------|
| **Context** | `CLAUDE.md`, knowledge-base, stories, templates | Agents read the rules before acting |
| **Constraints** | Architecture tests (`test_architecture.py`) | Build fails if a module imports from a higher layer |
| **Linters** | Make targets, local hooks, and GitHub Actions CI | Commit or merge blocked when lint, types, tests, or secrets checks fail |
| **Mutation testing** | Dedicated PR/scheduled workflow with a committed regression baseline | New surviving/no-test mutants block until reviewed |

Quality gates use a language-neutral contract:

```text
make format    make format-check    make lint    make typecheck    make test    make quality
```

Local hooks can be pre-commit, lefthook, husky, or none. CI and agents share the same Make-target contract.

**Cognitive health gates** prevent AI-generated code from outrunning understanding:

- **Teach-back**: before committing non-trivial code, the developer explains what it does, where to debug it, and how it would change.
- **Commit rationale + Teach-back trailer**: non-trivial commits explain *why* in the body and carry a one-line `Teach-back:` trailer.

See [Architecture § Harness Engineering](docs/architecture.md#harness-engineering) for details.

---

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (package manager)
- An AI coding tool such as [Claude Code](https://claude.ai/code), [GitHub Copilot](https://github.com/features/copilot), [Cursor](https://cursor.com), [Kiro](https://kiro.dev), or another tool that can read deployed markdown instructions

---

## Scope and Limitations

This is an opinionated playbook, not a finished framework. It works well for the cases below and is explicit about its bounds elsewhere.

**Designed for:**

- Solo developers and small teams (roughly 2–10 engineers) using AI tools day-to-day.
- Production code with genuine test, review, and release discipline.
- Teams comfortable adapting markdown rules to their stack.

**Highlights from the limitations registry**: see [`docs/limitations.md`](docs/limitations.md) for the full list:

- **Single-maintainer project.** Designed and maintained by one person. Governance, the RFC process, and the compatibility promise are documented in [`GOVERNANCE.md`](GOVERNANCE.md), [`docs/rfcs/README.md`](docs/rfcs/README.md), and [`docs/deprecation-policy.md`](docs/deprecation-policy.md). Multi-maintainer transition criteria are explicit; until they are met, the maintainer has final say.
- **Not benchmarked against alternatives.** No published comparison versus Cursor rules, Aider conventions, Cline, Continue, or other agent frameworks. Quality claims rest on the playbook's own evals, not external baselines.
- **Runtime token telemetry depends on the host.** Use `ai-playbook context-report` for a provider-neutral static estimate. Optional Claude/Codex local telemetry is deliberately privacy-minimal; actual conversation, tool-schema, cache, model, token, and cost data stays with provider-native reports.
- **Eval suite is v1.** Adversarial pairs, committed baselines, structural calibration, generated standard-agent discovery, and schema-backed rubrics for all standard agents are in place. Multi-turn agent simulation, judge-ensemble scoring, and historical regression budgets are not yet implemented. The drift job is opt-in (manual `workflow_dispatch`, weekly cron off by default), makes a single-judge call against committed baselines, and fails closed if no baselines or judge secret are configured.
- **Python is the only fully supported language.** Other languages (Go, Rust, Java, TypeScript, and others) are auto-detected and work, but team-owned conventions in `knowledge-base/languages/<lang>.md` start from blank templates.
- **Bitbucket Server / Data Center is not supported.** Bitbucket Cloud only: see [ADR-0001](docs/adr/0001-bitbucket-server-not-supported.md).
- **No paging integration.** The notifier covers Slack, email, and generic webhooks only; PagerDuty and Opsgenie are intentionally out of scope.
- **release-captain stops at "tag pushed".** Adopters wire their own deploy pipeline triggered by tags; the playbook does not deploy.

**Not the right tool if** you need a polished commercial product with SLAs, a vendor support contract, or guaranteed backward compatibility across versions.

---

## Contributing

See **[CONTRIBUTING.md](CONTRIBUTING.md)** for development setup, testing, and how to submit changes.

---

## License

[MIT](LICENSE): Meenu Mathew
