AI Agent Playbook

Languages

• English (canonical): this file
• Korean (한국어): 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. Detailed decisions and evidence can live in linked documents when they are needed. 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/.

In 1.0, AAPB concentrates on records, artifact formats, and selected specialist guidance. The agent host and project tools handle execution and scheduling. See the 1.0 changes and migration choices if you used the broader 0.5 runtime.

What You Get

The optional MCP tools are aapb_status, aapb_search, aapb_read, and aapb_validate. MCP setup explains how to connect and check them.

Quick Start

Install the npm package with Node.js 18 or later:

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:

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

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:

ai-agent-playbook records status --json
ai-agent-playbook bootstrap --dry-run
ai-agent-playbook bootstrap
ai-agent-playbook records read --path CURRENT.md

Bootstrap preserves existing AGENTS.md and records. For a new playbook it creates CURRENT.md and two metadata files. Add --local-only to both bootstrap commands when this is a Git repository and records should remain local.

To work on another folder, add a quoted path, for example ai-agent-playbook bootstrap "<project>" --dry-run, or use --project "<project>". The command guide explains complete command combinations and their options.

First 10 minutes provides a practice project, glossary, expected results, and troubleshooting. Lifecycle 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. Developers can use Maintenance and Local package testing.

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.

See Forge coordination for examples and authentication boundaries, and verification for the distinction between mocked transport tests, local demonstrations, and live platform evidence.

Everyday Flow

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:

ai-agent-playbook records search "<project>" --query "API decision" --json
ai-agent-playbook records validate "<project>" --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 shows how to read the rest.

Repository Map

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/   Minimal current-state template and layout metadata
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

Individual --skill selections replace the profile selection. Profiles select guidance, not permissions. See Skill catalog for triggers, examples, and combined selections.

The old 94 entrypoints were consolidated or retired. Useful domain references remain in the reference library, with an item-by-item migration table. Short skill entrypoints do not require short human documentation or loss of product-specific detail.

Documentation

Choose a route in the documentation map, or open a guide directly:

• Repository context: terms and design intent.
• First 10 minutes: a beginner's practice run, glossary, expected results, and troubleshooting.
• Command guide: commands, options, examples, write behavior, and exit codes.
• Lifecycle guide: package and skill installation, updates, removal, migration, and recovery.
• Existing repositories: inspect existing records and preserve project instructions.
• Project architecture: choose and evolve boundaries without imposing a stack during bootstrap.
• Project record layout: what belongs in CURRENT.md and when to add detail.
• Runtime architecture: data flow, ownership, and validation boundaries.
• MCP setup and permissions: connect the four optional read-only tools.
• Agent use: distinguish available skills and tools from actual selection and successful execution.
• Response limits and continuation: choose a content size and continue long results.
• Forge coordination: reviewed plans, remote writes, conflicts, and retry behavior.
• UI and writing review: preserve product intent, facts, and voice during review.
• Runtime engines: Node/Python setup and troubleshooting.
• Local package demonstration: test an unpublished archive against project records.
• Skill catalog, capability selection, and reference adoption: choose the right guidance.
• Codex adapter, Claude Code adapter, and templates: adapt the files to your environment.
• 1.0 changes and previous versions, verification, and release readiness: rationale, evidence, and remaining conditions.
• Maintenance, content classification, translation policy, and publishing checklist: contribute and prepare a release.
• Environment profiles and external process frameworks: scope optional integrations.
• Changelog: versioned user-visible changes.

License

Licensed under MIT.