AI Agent Playbook

Languages

• English (canonical): this file
• Korean (한국어): README.ko.md

What This Is

AI Agent Playbook is a local-first AI harness for real software repositories. It combines capability-focused skills, copyable project memory, a dependency-light runtime CLI, and an optional local MCP server so agents can inspect, plan, verify, and hand off work without guessing.

It helps coding agents stop guessing. The playbook nudges agents to inspect the repository first, respect local rules, keep API boundaries clear, write useful worklogs, and verify changes before calling work done.

The repository is agent-agnostic. Codex, Claude Code, and other coding agents can use the same source material, while adapters/ keeps agent-specific setup notes separate.

It is not a slash-command pack, a Codex plugin, or an always-on hosted agent service. Local operation remains available without a forge. Automation starts only from an approved plan or an explicitly applied schedule, and preview-first commands keep remote and operating-system changes reviewable. MCP remains an optional local tool surface whose default tools are read-only.

What You Get

Quick Start

The package is published as ai-agent-playbook. The simplest path is to run it through npm with npx:

npx ai-agent-playbook --help
npx ai-agent-playbook skills install --dry-run
npx ai-agent-playbook skills install
npx ai-agent-playbook bootstrap <target-project> --dry-run
npx ai-agent-playbook bootstrap <target-project>
npx ai-agent-playbook operator check <target-project> --json

New to this playbook? Start with First 10 minutes. It explains what npx, global install, skills, and project bootstrap do before you write files.

In examples, names inside angle brackets are placeholders. Replace <target-project> with the project folder you want to inspect, or use . when your terminal is already inside that project. Quote paths that contain spaces, and keep private local paths out of shared issues, docs, and PRs.

If your AI app supports MCP, register a local server command such as npx ai-agent-playbook mcp. Then you can ask the AI to inspect playbook context, read the capability/skill/workflow/adapter/usage/reference-adoption resources, run writing or operator checks, or do deep local analysis without remembering every CLI command. MCP tools are read-only by default.

If you want the shorter aapb command from any directory, install the package globally:

npm install -g ai-agent-playbook
aapb --help

aapb is short for AI Agent Playbook. It is the global command name provided by the ai-agent-playbook npm package.

Python is optional but recommended for deeper local language checks. Node remains the stable CLI and MCP facade; when Python 3.11+ is available, commands such as writing naturalness-check --engine auto and writing naturalness-report --engine auto merge Python-backed Korean/English prose analysis with the built-in JavaScript fallback.

py -3.11 -m venv .venv
.\.venv\Scripts\python -m pip install -U pip kss kiwipiepy
$env:AI_AGENT_PLAYBOOK_PYTHON = ".\.venv\Scripts\python.exe"
npx ai-agent-playbook runtime python-status --json
npx ai-agent-playbook writing naturalness-check <target-project> --path README.md --lang auto --engine auto --json
npx ai-agent-playbook writing naturalness-report <target-project> --root docs --lang ko --engine auto --json

From a source checkout, .\scripts\bootstrap-python.ps1 creates a local .venv and installs the optional Python extras for development. Without Python, the CLI and MCP server still work and return JavaScript fallback results with an engines.unavailable warning for Python-backed checks.

The npm package installs the CLI. It does not automatically copy skills, create .ai-agent-playbook/, enable hooks, or register slash commands. Keep those actions explicit:

• skills install, skills update, and skills uninstall manage reusable user-level skills.
• bootstrap, guides sync, managed *, contracts *, operator *, and qa * manage or inspect one target project.
• mcp starts a local stdio MCP server for AI apps. It does not write files by itself.
• Runtime hooks and adapter settings are optional and are never installed by default.

For command-by-command usage, see Command guide. For update, uninstall, local checkout, PowerShell compatibility, ownership markers, and cleanup details, see Lifecycle guide.

Forge Automation Compatibility

Version 0.5.10 keeps the resumable local execution loop and the human-facing Forge coordination model introduced in 0.5.5. Fine-grained tasks stay in the local ledger, while roadmap and delivery-group issues, Projects, Views, milestones, and reviewable PRs present the shared work. Generated and copyable hosted workflows now run the same exact AAPB release as the package that ships them, Forge requests report that release consistently, and a broken platform Python alias no longer aborts discovery of other interpreters. The 0.5.9 monotonic attempt-reset recovery, 0.5.8 idempotent Forge reconciliation, interrupted supersede recovery, and Projects authorization gates remain in place.

Only the row that explicitly says “verified” identifies a tool version exercised as a verification reference. API and provider target rows define the compatibility contract; they do not claim that a live remote write smoke test ran.

• Without a usable remote—or when --no-remote or --offline narrows the request—the same run continues against the local ledger without calling the forge transport. Missing authentication or write permission disables mutations but can still allow anonymous capability probes or permitted remote reads.
• forge status separates configured policyWrites from permission-checked verifiedWrites and reports server/API version, authentication without token material, repository permission, and probe evidence. Effective writes remains false until authentication and repository write permission are verified.
• GitHub Projects and Views require the corresponding project scopes. Preferred Project coordination pauses before every remote write when either capability is missing. forge status, bootstrap, and synchronization previews print the browser-auth and recheck commands; blocked bootstrap previews report zero executable operations while preserving the requested artifact counts. An explicit projects,views fallback is required to use milestone coordination instead. The harness never expands authentication scopes automatically.
• Managed Projects create the neutral Delivery Status field with Planned, Ready, In Progress, In Review, Blocked, and Done options, plus Priority, Risk, Phase, Progress, Area, and Task ID. Existing AAPB * fields remain read-compatible aliases and are reused without creating duplicates, renaming, or deleting remote assets. User-owned Project field and View REST paths consistently use the owner login, so an interrupted bootstrap can resume against its existing titled Project. Presentation reconciliation transfers managed classification labels before removing them from issues and stops later mutations if a Project transfer fails.
• Reconcile preflight uses the provider adapter with a mutation-blocking transport. Provider-confirmed reusable operations move to noOps, executable artifact counts reflect only remaining changes, and the original intent count remains in plannedOperations. GitHub's omitted empty text fields converge with an empty target instead of being rewritten on every run.
• GitHub automatically creates View 1 for a new Project. The stable public View API does not rename or delete that system view, so AAPB reuses it for the managed all role instead of creating a duplicate table view; it does not claim that the visible name changed.
• Reviewed supersede reconciliation closes an attached obsolete issue before updating its marker comment, removes its Project card before the final hierarchy unlink, and blocks later group mutations after a failure. If a prior run already unlinked an open issue, the next preview recovers it only from the exact approved-plan supersede marker and removes its Project card before closing it. Issues, comments, and label definitions remain preserved.
• Gitea uses Issues, Labels, Milestones, pull requests, and Actions only where the server OpenAPI advertises the required methods. Draft review uses the public pull-request API with Gitea's documented WIP: title convention. A self-hosted hostname hint remains non-writable until forge.provider: "gitea" or a credential-free forge.apiBaseUrl ending in /api/v1 is configured. Version and OpenAPI probes run without a token before authenticated permission checks. Project/View state falls back to labels and milestone filters, and a decision issue can replace Discussions.
• gh agent-task is an explicit preview adapter, not an automatic executor choice. Forge bootstrap and scheduler installation are also preview-first and require an explicit apply step.

See the 0.5.10 hosted runtime version change note for release-aligned Actions generation and upgrade guidance, and the 0.5.10 Python candidate recovery change note for isolated interpreter probing. The 0.5.9 attempt reset recovery change note covers append-only retry recovery, while the 0.5.8 Forge idempotent reconcile change note remains the reference for provider-confirmed no-op filtering, Project convergence, and legacy body migration.

Everyday Flow

npx or global install
  -> skills install or update
  -> restart the agent
  -> inspect the target project
  -> bootstrap .ai-agent-playbook/ only when the project needs local playbook files
  -> use operator checks/search and managed cleanup as explicit commands

For existing projects, start with a dry run and inspect conflicts before writing files:

npx ai-agent-playbook bootstrap <target-project> --local-only --dry-run
npx ai-agent-playbook bootstrap <target-project> --local-only
npx ai-agent-playbook operator check <target-project> --json
npx ai-agent-playbook operator preflight <target-project> --intent "planned change" --json
npx ai-agent-playbook operator research <target-project> --query "project risks" --json

See Command guide for search, managed cleanup, adapter setup, plan, and worklog commands.

After bootstrapping .ai-agent-playbook/, agents should start from START_HERE.md, then read CURRENT.md, questions.md, relevant memory/maps/contracts, and the matching workflow recipe. Generated files under runtime/ are evidence candidates, not trusted memory, until reviewed and promoted.

Repository Map

bin/                  aapb CLI entrypoint
src/                  CLI runtime implementation
skills/
  ai-harness/        MCP, forge automation, agent, context, fact gate, witness, cache, and index design skills
  architecture/      Boundary, feature slice, domain model, and monorepo/package architecture skills
  backend/           API, backend change safety, request/error contract, job/worker, connector, and server-rendered flow skills
  data/              Data pipeline, analytics, source registry, reporting, and migration integrity skills
  database/          Schema, migration, SQL, and data integrity skills
  delivery/          Planning, eval, verification, testing, Git, PR, and worklog skills
  devops/            CI/CD, container, package release, deployment, and operations triage skills
  design/            Design direction, brand identity, reference analysis, and image/Figma handoff skills
  frontend/          UI, browser, state/data, accessibility, visual QA, design-system, and interactive media skills
  mobile/            Native release, permission, offline sync, hybrid, WebView, and device QA skills
  security/          Auth, dependency supply chain, license/notice, security review, compliance gate, and risk skills
  project/            Bootstrap, onboarding, project planning, documentation, natural writing, and project-memory skills
  quality/            UI quality review, cleanup, compatibility routes, and lightweight review skills
  git/                Commit, PR, push, and worklog skills
  meta/               Skill-authoring skills
  legacy/             Legacy-system maintenance skills
templates/
  agents/             Root agent instruction templates and project profiles
  codex-home/         Optional personal Codex home AGENTS.md template
  project-playbook/   Copyable AI Agent Playbook project-memory template
examples/             Worklog, prompt, and handoff examples
translations/         Human translations; never install these as skills
adapters/             Agent-specific install notes and optional hook PoCs
docs/                 Quick start, lifecycle, command, architecture, and capability references
docs/assets/          README and documentation images
scripts/              Validation and local sync helpers
test/                 Node CLI and adapter tests
.github/              GitHub Actions validation workflow

Skill Catalog

Detailed triggers live in Skill catalog. The README keeps the public map short so the English and Korean versions stay aligned.

• Project and docs: bootstrap, repository onboarding, project memory, ADR/spec handoff, requirements, issue planning, release notes, natural writing review, and documentation packages.
• Delivery and verification: Git/worklogs, verification strategy, CI gates, flaky test triage, test fixtures, and eval harnesses.
• AI harness: MCP surface design, context and memory design, agent handoff, forge automation control, skill-pack governance, runtime indexes/caches, capability witnesses, and fact gates.
• Architecture and backend: boundaries, feature slices, domain modeling, monorepos, API contracts, backend change safety, request/error contracts, job/worker reliability, connectors, and server-rendered flows.
• Data and database: analytics, lineage, migrations, retrieval knowledge bases, source registries, schema changes, query performance, and data integrity.
• DevOps and release: containers, deployment, package publishing, release readiness, and incident/observability triage.
• Design and frontend: design direction, brand identity, visual references, image/Figma handoff, style policy, UI polish, accessibility, state/data flow, visual regression, and 3D interaction.
• Mobile: native release, device permissions, offline sync, and WebView bridges.
• Security and compliance: security review, authentication/authorization, dependency supply chain, license/notice evidence, and release gates.
• Legacy: hidden coupling, old web stacks, server-rendered systems, WebView hybrids, IE/ActiveX compatibility, reporting/printing, batch/file transfer, and database-heavy systems.

Documentation

• Repository context: core terms and design intent for the playbook.
• First 10 minutes: beginner-friendly first run, glossary, and safe command order.
• Command guide: what each CLI command does, when to use it, and whether it writes files.
• Lifecycle guide: npm/npx usage, global CLI setup, skill lifecycle, project bootstrap/removal, cleanup, and legacy PowerShell paths.
• Runtime harness: runtime principles, JSON contract notes, overwrite policy, and target-project flow.
• Structured playbook layout: .ai-agent-playbook directory roles and migration commands.
• Capability taxonomy: capability-first categories and compatibility wrapper policy.
• Skill catalog: long-form skill list and trigger summary.
• MCP permission model: read, scaffold, managed-write, and project-write tiers.
• Reference adoption: how to distill external references into local capabilities without prompt noise.
• Runtime roadmap: staged hardening plan and optional hook-layer boundaries.
• Codex adapter: Codex-specific local sync behavior and Codex App on Windows workflow.
• Claude Code adapter: Claude Code setup notes and optional read-only context hook example.
• Templates: what to copy into project repositories and what to leave as installable skills.
• Classification: why skills, templates, examples, docs, and adapters are separated.
• Superpowers integration: how to use this playbook alongside external process skills.
• Structured playbook cutover notes: historical notes for the layout and runtime reorganization.
• 0.5.4 forge automation change note: resumable execution, provider fallback, migration, and disable guidance.
• 0.5.5 human-centered Forge coordination change note: roadmap and delivery-group presentation, Projects capability gates, and reviewed reconcile migration.
• 0.5.6 Forge permission guidance change note: pre-write Projects authorization recovery, neutral Project fields, and legacy alias compatibility.
• 0.5.10 hosted runtime version change note: release-aligned hosted workflow pins, request identity, and existing-workflow upgrade safety.
• 0.5.10 Python candidate recovery change note: isolated process failures during interpreter discovery.
• 0.5.9 attempt reset recovery change note: monotonic attempt event IDs across explicit retry-budget resets.
• 0.5.8 Forge idempotent reconcile change note: provider-confirmed no-op filtering, Project convergence, and strict legacy body migration.
• 0.5.7 Forge reconcile recovery change note: interrupted supersede recovery, CAS-safe ordering, and obsolete Project item cleanup.

License

Licensed under MIT.