Repository navigation
Releases
playbook 3.7.0
Playbook 3.7.0 restores both Codex installation choices and adds a requirements check. From the repository root, run python3 codex/install.py --check to check your setup or python3 codex/install.py to install or update your plugins.
- Codex reviews can finish with findings and record completion for the next commit.
- Codex can record review evidence and recurring tasks during project work. Approved task agents use project-local TOML profiles.
- Codex installs its four supported working skills. All five Claude Code and Codex plugin manifests now report version 3.7.0.
3.6.0
Dedicated agents for repeated tasks
At the close of each work, Playbook now records the tasks the agent carried out, and proposes a dedicated agent, on a model that fits the task, for a task that repeats (work task-agents, #44).
-
Tasks recorded. At the close,
prepare-projectreads the git log since the previous work's close, so it also sees the previous release. It records each task it would carry out again, such asreleaseorclose-stage, indocs/wiki/tasks.mdwithtasks.sh, a new script ofplaybook-agents. -
A proposal at 3 works. When a task is held in 3 distinct works, the agent judges its weight:
- mechanical steps go to
haikuwith effortlow; - writing text or judging a small change goes to
sonnetwith effortmedium; - deciding, designing, a push, a merge, or a release stays in the main session.
It proposes one agent at a time and always asks you.
- mechanical steps go to
-
Your answer. On a yes, it writes
.claude/agents/<task>.mdin the project, with only the steps it may run and a line naming those left to you. On a no, the task is marked declined and is not proposed again. -
Six general rules learned from repeated review findings now ship in
evidence-rules.md: three new, and three raised to level 3.
Nothing to migrate: the wiki format stays 5. The step runs only when playbook-agents is installed; docs/wiki/tasks.md is created on the first close.
playbook 3.5.0
Units built in parallel
A work's plan now says which units can be built at the same time, and stage 6 builds them in parallel (work parallel-units, #42).
- Plan by batches. In stage 5 of
prepare-project, each unit names the units it waits for ("Waits for") and the paths it may change ("Changes"). The batches follow from that: batch 1 holds the units that wait for none, batch 2 those that wait only for batch 1, and so on. The plan also names the mostwriteagents at once and how a new worktree is prepared, such aspnpm installor copying.env. You accept all of it with the plan. - Parallel execution. In stage 6, each ready unit gets its own worktree from the work's branch, created with
git worktree add -b, and its ownwriteagent in the background. Each unit is reviewed from the main folder and merged with--no-ff. Then its worktree and branch are removed. A unit starts as soon as what it waits for is Done. - Shared worktree. When preparing a worktree is costly, a batch can share one worktree, with exclusive paths for each unit.
Nothing to migrate: the wiki format stays 5. A plan written before this version is built one unit at a time, as before. Units are also built one at a time without playbook-agents, and when the plan does not deliver through a work branch with local merges.
playbook 3.4.0
Ask before what cannot be undone
Claude Code now asks you before the actions you cannot take back, and a new command protects a repository's secrets (work ask-before-irreversible, #40).
- Delivery hook. Before any form of
git push(includinggit -C <dir> push),gh pr create,gh pr merge, andgh releasecreate, edit, or delete, a hook ofplaybook-agentsmakes Claude Code ask you. It also asks inbypassPermissionsmode and inside subagents. Inclaude -pthe ask becomes a refusal that gives the reason. /playbook-agents:protect. Finds the repository's secret files by name and offers four kinds of protection. You choose which ones and whether they go to.claude/settings.jsonor.claude/settings.local.json. The command only adds to what the file already holds. Only you start it. The four protections:- deny rules so Claude Code cannot read those files;
- ask rules before
rm -r,git reset --hard,git branch -D, andgit clean; - the sandbox;
- optionally, keeping commands from running outside the sandbox.
- One more general rule.
decided-behaviour-changed-without-decisionjoins the playbook's general rules.
Nothing to migrate: the wiki format stays 5.
Known limits:
- A heredoc body can make the hook ask without need.
- Read deny rules do not stop every command; the sandbox covers the rest.
- On Linux the sandbox needs
bwrapandsocat.
playbook 3.3.0
Evidence seeded from past reviews
A repository can now start its evidence page from the reviews it already had (work seed-evidence, #38).
- Seeding.
/playbook-agents:seed-evidencelists the repository's past reviews from your Claude Code transcripts; you choose which ones, andclassifystores each one indocs/wiki/evidence.md.--from <old path>also reads the transcripts of a moved repository. Only you start it. - Rules index. When
writeorreviewstarts, the hook now gives an index of the rules of level 2 and up, one line per kind with when it applies, and the command that prints one rule (evidence.sh indexandrule), instead of the full text of every rule. - General rules. Fifteen kinds, consolidated from this repository's seeded reviews, are raised to the playbook's general rules in
plugins/playbook-agents/evidence-rules.md, so they reach every project.
Nothing to migrate: the wiki format stays 5. A review resumed after a restart is not listed, and transcripts are kept for a limited time.
playbook 3.2.1
Fixed
playbook-agents: when a review ends with findings and starts noclassify, the hook now stops it once per subagent. Before,stop_hook_activewas not set on the repeated stops of one review, so a review that could not start the classifier was stopped again and again (repeated-corrections-31, #36).
playbook 3.2.0
Learned rules from repeated review findings
When review keeps finding the same kind of mistake, the agent now learns from it (work repeated-corrections, #34).
- Evidence. When
reviewhas findings, it starts the new agentplaybook-agents:classify(sonnet), which records each finding under a kind of mistake indocs/wiki/evidence.md. ASubagentStopcheck stops a review that had findings and started no classifier. - Rules at the start. A
SubagentStarthook giveswriteandreviewthe rules of level 2 and up, from the project's page and from the playbook's general rules (plugins/playbook-agents/evidence-rules.md). - Consolidation by level.
evidence.shcounts distinct reviews per kind and level. At the close of a work, a kind that reached 3 distinct reviews is proposed as one concrete rule one level up; the rows it covers are removed, and git keeps them. The owner approves each one, or delegates the new kindconsolidate. - Delegation. When the owner asks for a work in their own words, the agent opens it without asking (this repository only).
Nothing to migrate: the wiki format stays 5, and a project with no evidence page sees no change. Subagent nesting must stay on (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH not set to 1).
playbook 3.1.1
A fix to the version notice of 3.1.0.
What changed
- A marketplace added from a local folder, such as a clone of this repository, loads its plugins in place, so the version that runs is the folder's. The version notice now shows nothing for it and no longer reads
~/.claude/plugins/known_marketplaces.json. With a local clone, pull it and start a new session. - The notice for a marketplace from GitHub is unchanged: it shows once the marketplace's copy on your machine holds a newer version, after
claude plugin marketplace update playbook.
Update
claude plugin marketplace update playbook
claude plugin update playbook-wiki@playbook
claude plugin update playbook-agents@playbookThen start a new session.
Licence
MIT. Issues and pull requests are welcome; see CONTRIBUTING.md.
playbook 3.1.0
Claude Code does not tell you when a plugin from this marketplace has a new version. From 3.1.0, the playbook tells you itself, at the start of a session, and the notice about your wiki's format now reaches you, not only the agent.
What changed
- Version notice. When the marketplace's copy on your machine holds a newer playbook than the one installed, a new session shows you one line with both versions and how to update. The agent is told too, and does not update anything unasked.
- Format notice for you. When your project's wiki is behind the playbook's format, you see a line recommending
/playbook-wiki:doctor. Until now only the agent got it. So after an update that raises the format, the next session tells you to run the doctor. - A wiki ahead of the plugin. When the wiki is at a newer format than your playbook, such as after a teammate updated, you see a line recommending an update, never the doctor.
- Both notices show once per new session (
startup), not again after/clearor a compaction.
Limits
- No hook connects to a network. With automatic update off, as for this marketplace, a new release is seen only after
claude plugin marketplace update playbook. - The version notice exists from this version on: it first shows when a release after 3.1.0 is available.
- Codex sessions keep their format notice as before, without the case of a wiki ahead.
Update
claude plugin marketplace update playbook
claude plugin update playbook-wiki@playbook
claude plugin update playbook-agents@playbookThen start a new session. More in the Updates section of the Claude Code guide.
Install
claude plugin marketplace add andresfrei/playbook
claude plugin install playbook@playbook --scope userThen run /playbook:init in a new session. More in the Install section of the README.
Licence
MIT. Issues and pull requests are welcome; see CONTRIBUTING.md.
playbook 3.0.0
Version 3 lets you delegate a kind of question, so the agent stops asking the ones you always answer "yes" to. It is a major version: it moves a project's wiki to format 5.
What changed
- Delegation. You can decide a kind of question once for a project, such as closing a stage. The agent then decides it without asking, records it as
agent, by <delegation>, and tells you in one line. If you answer "yes but" or "no" to one of those decisions, it proposes revoking the delegation. Four things are never delegated: a new definition of the product, a push or merge into the main branch, an action outside the repository or on your machine, and spending beyond a written ceiling. - Proposals come from your own answers. Each decision of a work now records its kind (such as
close-stage,plan,definition) and how you answered (as recommended,changed,rejected,delegated). When a work closes,prepare-projectrunscheck-wiki.sh --delegations. A kind qualifies with at least 10 answers, at least 80% of them as recommended, and none rejected. It is proposed once, and a "no" is recorded so the proposal is not made again. - Wiki format 5. A work's
decisions.mdhas two more columns, Kind and Answer. A new shared page,01-product/delegations.md, lists the delegations in force and those revoked. - The contract. R6 now reads "Only the owner decides, per case or by a recorded delegation", and R10 is shorter.
From version 2
After the update, the notice at the start of a session says your wiki is behind. In each project with a wiki, run /playbook-wiki:doctor in a new session. It adds the Kind and Answer columns to every work's decisions.md. It fills earlier rows from each decision and your words, marked (estimated), and leaves a cell empty when unsure. It shows you the totals before writing anything. docs/wiki/decisions.md, the history from before format 4, is not touched.
claude plugin marketplace update playbook
claude plugin update playbook-wiki@playbook
claude plugin update playbook-agents@playbookInstall
claude plugin marketplace add andresfrei/playbook
claude plugin install playbook@playbook --scope userThen run /playbook:init in a new session. More in the Install section of the README.
Licence
MIT. Issues and pull requests are welcome; see CONTRIBUTING.md.