Agent Playbook Suite
coding-agent project state in Markdown
Last verified:
What is Agent Playbook Suite?
Agent Playbook Suite is an open-source workflow plugin for Codex and Claude Code that bundles five workflow skills plus the docs skill to make AI agent work resumable across multiple sessions. It addresses the core problem of state drift in coding agents by keeping project state on disk as validated Markdown records instead of in chat transcripts, enabling fresh agents to resume work without reconstructing context from 70,000-token chat histories.
The suite includes five workflow skills: project-foundation (creates charter, scope, architecture, milestone plan), create-milestones (interactive operator-driven delivery loop), ship-milestone (autonomous conductor delegating to fresh sub-agents), sync-and-commit (verifies work and updates docs to match reality), and simplify (reduces complexity while preserving behavior). It uses docs-cli as its runtime substrate, treating Markdown files with metadata blocks as records with lifecycle, role, project, update date, and typed relationships.
This tool is for developers using Claude Code or Codex for multi-session development, greenfield projects, multi-milestone features, internal tools, paused side projects, and codebases where different agents may need to resume work. It follows a ten-phase TDD sequence with explicit doc touchpoints and implements a fresh-agent pattern where fresh sub-agents perform planning, implementation, review, and simplification as a review primitive.
Agent Playbook Suite pricing
Pricing model: Freemium
Free and open-source. The docs-cli package is distributed publicly on PyPI for free installation. The Agent Playbook Suite plugin is installed from the public marketplace at no cost. No paid tiers or subscription plans exist.
Agent Playbook Suite pros
- Makes agent work resumable across multiple sessions
- Keeps project state on disk instead of fragile chat transcripts
- Open-source and free to use
- Bundles five workflow skills in one installable plugin
- Fresh-agent pattern uses fresh context as a review primitive
- Ten-phase TDD sequence with explicit exit conditions and log entries
- docs-cli validates Markdown records with CLI exit codes for CI
- Generated index moves together with records automatically
- Migration tool supports dry-run mode before applying changes
- Works with Codex and Claude Code through marketplace installation
- Ships as public PyPI distribution for docs-cli package
- Fresh sub-agents prevent agents from relying on self-told stories
- Close to how useful human review actually works
- Record convention is readable in terminal and editable in any editor
- Reviewable in git with structured metadata for tool checking
Agent Playbook Suite cons
- Requires accepting a documentation convention
- Poor fit for one-off scripts and tiny bug fixes
- Must maintain useful project instruction file
- Requires working in milestone-sized slices
- Risk of ceremony creep if docs become second product
- Higher overhead than letting agent improvise freely
- All rationale cannot stay in chat as some users prefer
- Human must resolve some ambiguities in workflow
Frequently asked questions about Agent Playbook Suite
What is Agent Playbook Suite?
Agent Playbook Suite is a workflow plugin for Codex and Claude Code that bundles five workflow skills (project-foundation, create-milestones, ship-milestone, sync-and-commit, simplify) plus the docs skill. It makes AI agent work resumable by keeping project state on disk as validated Markdown records instead of in chat transcripts.
How do I install Agent Playbook Suite?
First install the CLI with 'python3 -m pip install --upgrade docs-cli'. Then install the suite plugin from the public marketplace. For Codex: 'codex plugin marketplace add ArtRichards/agent-playbook-suite --ref main' followed by 'codex plugin add agent-playbook-suite@agent-playbook-suite'. For Claude Code: 'claude plugin marketplace add ArtRichards/agent-playbook-suite' followed by 'claude plugin install agent-playbook-suite@agent-playbook-suite'.
What is the docs-cli?
docs-cli is the runtime substrate for Agent Playbook Suite. It treats managed Markdown files as records with lifecycle, role, project, update date, and typed relationships. It can create, archive, move, touch, list, check, index, and migrate records. The command is 'docs' while the PyPI package is named 'docs-cli'.
What are the five workflow skills?
project-foundation runs once near the start creating charter, scope, architecture, milestone plan, living status, definition of ready, and project instructions. create-milestones is the operator-driven delivery loop creating milestone records and paired implementation logs. ship-milestone is the autonomous conductor delegating to fresh sub-agents. sync-and-commit verifies work and updates docs tree to match reality. simplify reduces complexity while preserving behavior.
What is the fresh-agent pattern?
The fresh-agent pattern is ship-milestone's most opinionated choice. Instead of preserving one large context, it uses a lightweight conductor and fresh sub-agents: one sets up the milestone, one plans early phases, another implements from fresh context, a separate agent performs fresh-eyes review, and a final pass simplifies. Fresh context becomes a review primitive rather than a limitation.
What is the ten-phase TDD sequence?
The milestone loop follows ten phases: 1) Define Contract, 2) Write Tests, 3) Create Fixtures, 4) Confirm RED baseline, 5) Update Interfaces, 6) Implement Core, 7) Update Wrappers, 8) Reach GREEN, 9) Integrate, 10) Quality, Docs, Refactor. Each phase has an exit condition and log entry so a fresh session can read the milestone record and implementation log to understand what happened.
Who is Agent Playbook Suite for?
It is for developers using Claude Code or Codex for serious multi-session development. It is a good fit when restart cost is high: greenfield projects, multi-milestone features, internal tools, paused side projects, and codebases where a different agent may need to resume work next week. It is a poor fit for one-off scripts, tiny bug fixes, or when you want the agent to improvise freely with rationale in chat.
What is the cost of using this workflow?
You must accept a documentation convention, maintain a useful project instruction file, work in milestone-sized slices, and treat status records and implementation logs as part of the build not optional housekeeping. The tradeoff is structure for resumability. The risk is ceremony creep if docs become a second product to maintain.
How do I try it with an existing repository?
For an existing repo, start smaller than automating shipping. Run migration in dry-run mode against an existing Markdown tree, inspect the ambiguities, then validate the result before applying changes. Decide whether the convention makes the tree easier to reason about. If it does, apply it and then bring in the skills.
How do I start with a new project?
For a new project, start with project-foundation to create the project front-half including charter, scope, architecture, milestone plan, living status, and definition of ready. Then choose whether you want the interactive loop using create-milestones or the autonomous conductor using ship-milestone.