AI Agent Playbook
Reusable skills, project records, and optional tools for careful software work with coding agents.
## Languages
- English (canonical): this file
- Korean (한국어): [README.ko.md](translations/ko/README.ko.md)
## What This Is
AI Agent Playbook (AAPB) helps coding agents keep useful project records and produce consistent specifications, handoffs, designs, and documents. It combines selected reusable skills, copyable templates, a local command-line tool, and an optional read-only MCP server.
A project's current goal, constraints, verified facts, and next action belong in `CURRENT.md`. Topic knowledge keeps current rules and contracts; monthly worklogs preserve detailed milestone evidence. A registered workspace can share these records across repositories without moving their code or existing local records. The files remain ordinary Markdown and JSON that you and your agent can edit with existing tools.
The source is agent-agnostic. Codex, Claude Code, and other coding agents can use the same records and reference material; host-specific setup belongs in `adapters/`.
AAPB concentrates on portable records, explicit workspace membership, artifact formats, and selected specialist guidance. The agent host and project tools handle execution and scheduling. See [the 1.0 changes and migration choices](docs/redesign.md) if you used the broader 0.5 runtime.
## What You Get
| Piece | What it does | Where it lives |
| --- | --- | --- |
| Reusable skills | Project memory, requested artifact formats, design direction, UI polish, document editing, and optional legacy contracts | `skills/` |
| Reference library | Domain contracts, examples, and exceptions retained from earlier skills, read only when relevant | `references/` |
| Project templates | Root instruction examples and a current-state document; additional records are created as needed | `templates/` |
| Runtime CLI | Explicit installation, bootstrap, record inspection, migration/recovery, advisory checks, and Forge coordination | `bin/`, `src/` |
| MCP tools | Four default record tools, plus optional structural source search | `src/` |
| Human docs | Beginner instructions, worked commands, troubleshooting, architecture, and release guidance | `docs/` |
| Translations | Korean reading copies with localized explanations and navigation | `translations/ko/` |
| Agent adapters | Setup notes for specific agent environments | `adapters/` |
The default MCP tools are `aapb_status`, `aapb_search`, `aapb_read`, and `aapb_validate`. [AST source search](docs/ast-search.md) is available through the CLI and the optional `aapb_ast_search` MCP tool enabled with `--with-ast`. [MCP setup](docs/mcp-permission-model.md) explains how to connect and check them.
## Quick Start
Install the npm package with Node.js 18 or later:
```sh
npm install -g ai-agent-playbook
ai-agent-playbook --help
```
The package and primary command are both `ai-agent-playbook`. `aapb` is a short alias with the same options and behavior. For occasional use without a global installation, run `npx ai-agent-playbook --help`. A source checkout or PowerShell installation script is not required for normal operation.
Choose reusable skills separately. Preview the development profile, inspect the result, then install:
```sh
ai-agent-playbook skills install --profile development --dry-run --json
ai-agent-playbook skills install --profile development --json
ai-agent-playbook skills check --profile development --json
```
Check `ai-agent-playbook --version` before following workspace and authoring examples. For an unpublished candidate, use the [source or local-archive demonstration](docs/demo.md); an npm install or `@latest` call selects the published package.
Reload the agent's skills or start a fresh session. File installation and actual host loading are separate checks.
Run these commands from the project folder. Omitting the project path uses the terminal's current directory:
```sh
ai-agent-playbook records status --json
ai-agent-playbook bootstrap --dry-run
ai-agent-playbook bootstrap
ai-agent-playbook records read --path CURRENT.md
```
In an interactive terminal, bare bootstrap guides you through language, folder preparation for a new setup, explicit choices, and a final review where you can change a setting. AAPB creates the record folder after you choose to apply. For a workspace, prepare or clone the child repositories yourself under the chosen parent folder; AAPB does not move or clone them. Existing records, root instructions, and registered membership are preserved; an AGENTS link is added only when selected.
The guide shows recommendations and current settings separately. It recommends standard guides and local Git exclusion, or no exclusion outside Git, but selects nothing for you. Use numbers or arrow keys, then Enter; repository checkboxes use Space and Enter. `q` cancellation and key help appear above the list. Local exclusion stays visible with a reason when unavailable. [The command guide](docs/commands.md) covers search, rescanning, and back navigation.
Interactive completion shows a readable result and next action; `--dry-run` previews without writes. For scripts, specify choices such as `--kind single --records standard --exclude none --agents preserve --json`. Explicit choices and non-interactive calls retain minimal/no-exclusion defaults unless overridden. `--yes` retains its existing defaults and saved settings, with explicit options taking precedence; `--json` never asks. [Workspaces](docs/workspaces.md) explains repeated `--repo-path` membership selection; [durable records](docs/durable-records.md) covers `worklog new/list` and `knowledge new`.
To work on another folder, add a quoted path, for example `ai-agent-playbook bootstrap "" --dry-run`, or use `--project ""`. [The command guide](docs/commands.md) explains complete command combinations and their options.
[Workspaces](docs/workspaces.md) and [durable records](docs/durable-records.md) cover shared membership and lasting evidence. [First 10 minutes](docs/quick-start.md) provides a practice project, glossary, expected results, and troubleshooting. [Lifecycle](docs/lifecycle.md) covers updates, removal, version selection, and recovery.
Package installation, skill installation, project bootstrap, and MCP registration are separate actions. Python is optional for selected writing checks; see [Runtime engines](docs/runtime-engines.md). Developers can use [Maintenance](docs/maintenance.md) and [Local package testing](docs/demo.md).
## Forge Coordination and Compatibility
AAPB can preview and explicitly apply GitHub/Gitea coordination plans, reuse existing managed identifiers, and report stale remote state or partial failures. It does not execute project tasks or schedule background work.
| Component | When it is needed | What the requirement means |
| --- | --- | --- |
| Node.js `18+` | CLI and MCP | Package runtime minimum; actual tested versions are listed in the verification report |
| Git | Clone/update, Git-local exclusions, and Forge remote discovery | Record creation and reading also work without Git; skipped local exclusion is reported |
| Python `3.11+` | Optional writing engine | Basic record operations and JavaScript writing checks work without it |
| GitHub / Gitea access | Explicitly applied coordination changes | A local preview does not prove remote credentials or permissions |
| An MCP-capable agent host | Optional tool connection | Plain file editing and CLI use remain available independently |
See [Forge coordination](docs/forge-automation.md) for examples and authentication boundaries, and [verification](docs/verification.md) for the distinction between mocked transport tests, local demonstrations, and live platform evidence.
## Everyday Flow
```text
Choose a verified CLI version
-> select skills and reload the agent
-> inspect an existing project, or preview a new playbook
-> read CURRENT.md and relevant linked records
-> implement and test with the project's own tools
-> update current facts, evidence, and the next action
```
For example, ask your agent: “Read CURRENT.md, follow the linked API decision, implement the requested change, run the repository's checks, and update the current state with the results.” AAPB supplies the record structure; your existing project instructions still determine how the work is done.
Use record commands to locate evidence and check document consistency:
```sh
ai-agent-playbook records search "" --query "API decision" --json
ai-agent-playbook records validate "" --json
```
Validation checks records, links, and managed-file integrity. It does not run the application's tests or verify that an old statement is still true. Longer results provide continuation information; [response limits and continuation](docs/record-responses.md) shows how to read the rest.
## Repository Map
```text
bin/ Shared ai-agent-playbook / aapb command entrypoint
src/ Record, installation, MCP, writing, and Forge implementation
skills/
project/ Project memory, artifact formats, and document editing
design/ Product-specific design direction
frontend/ Rendered UI polish
legacy/ Optional stack preservation contracts
references/ Optional domain detail from the earlier catalog
templates/
agents/ Stack-neutral project instructions
codex-home/ Optional personal instruction template
project-playbook/ Current-state template and layout metadata
record-artifacts/ Worklog and knowledge document templates
examples/ Worklog, prompt, and handoff examples
translations/ko/ Korean reading copies; not a second installed skill catalog
adapters/ Host-specific setup notes
docs/ User guides, design decisions, and verification reports
docs/assets/ README and documentation images
scripts/ Validation, packaging-related checks, and local sync helpers
test/ Runtime and adapter tests
.github/ CI and contribution templates
CONTEXT.md Terms and design intent
CHANGELOG.md Versioned changes
```
## Skill Catalog
| Profile | Included skills | Use it for |
| --- | --- | --- |
| `light` | `project-notes` | Brief continuity notes and result-focused replies, with no reference bundle |
| `core` (default) | `project-memory`, `spec-artifacts` | Project continuity and requested specifications, decisions, or handoffs |
| `development` | Core plus `design-brief-direction`, `ui-polish`, `natural-writing-humanization` | Development with design, UI, and document editing |
| `legacy` | `legacy-contracts` | Explicitly selected legacy-system preservation work |
Individual `--skill` selections replace the profile selection. Profiles select guidance, not permissions. See [Skill catalog](docs/skill-catalog.md) for triggers, examples, and combined selections.
For a smaller installation, use `skills install --profile light --dry-run --json` and repeat without `--dry-run` to install. Light selects one compact skill; it does not conceal skill use or change audit settings. Ordinary installation preserves other installed skills. To reduce an existing installation, follow the explicit [profile transition and recovery](docs/lifecycle.md#light-installation-and-switching-profiles). Bootstrap keeps its independent `--records minimal` choice.
The old 94 entrypoints were consolidated or retired. Useful domain references remain in the [reference library](references/README.md), with an [item-by-item migration table](docs/skill-decisions.md). Short skill entrypoints do not require short human documentation or loss of product-specific detail.
## Documentation
Choose a route in the [documentation map](docs/README.md), or open a guide directly:
- [Repository context](CONTEXT.md): terms and design intent.
- [First 10 minutes](docs/quick-start.md): a beginner's practice run, glossary, expected results, and troubleshooting.
- [Command guide](docs/commands.md): commands, options, examples, write behavior, and exit codes.
- [Lifecycle guide](docs/lifecycle.md): package and skill installation, updates, removal, migration, and recovery.
- [Existing repositories](docs/existing-repository-bootstrap.md): inspect existing records and preserve project instructions.
- [Project architecture](docs/project-architecture.md): choose and evolve boundaries without imposing a stack during bootstrap.
- [Project record layout](docs/structured-playbook-layout.md): what belongs in CURRENT.md and when to add detail.
- [Runtime architecture](docs/harness-runtime.md): data flow, ownership, and validation boundaries.
- [MCP setup and permissions](docs/mcp-permission-model.md): connect the four optional read-only tools.
- [Agent use](docs/agent-usage.md): distinguish available skills and tools from actual selection and successful execution.
- [Response limits and continuation](docs/record-responses.md): choose a content size and continue long results.
- [Forge coordination](docs/forge-automation.md): reviewed plans, remote writes, conflicts, and retry behavior.
- [UI and writing review](docs/quality-review.md): preserve product intent, facts, and voice during review.
- [Runtime engines](docs/runtime-engines.md): Node/Python setup and troubleshooting.
- [Local package demonstration](docs/demo.md): test an unpublished archive against project records.
- [Skill catalog](docs/skill-catalog.md), [capability selection](docs/capability-taxonomy.md), and [reference adoption](docs/reference-adoption.md): choose the right guidance.
- [Codex adapter](adapters/codex/README.md), [Claude Code adapter](adapters/claude-code/README.md), and [templates](templates/README.md): adapt the files to your environment.
- [1.0 changes and previous versions](docs/redesign.md), [verification](docs/verification.md), and [release readiness](docs/runtime-roadmap.md): rationale, evidence, and remaining conditions.
- [Maintenance](docs/maintenance.md), [content classification](docs/classification.md), [translation policy](docs/translation-policy.md), and [publishing checklist](docs/publishing-checklist.md): contribute and prepare a release.
- [Environment profiles](docs/environment-profiles.md) and [external process frameworks](docs/superpowers-integration.md): scope optional integrations.
- [Changelog](CHANGELOG.md): versioned user-visible changes.
## License
Licensed under [MIT](LICENSE).