Playbook Laravel Package

Technical Evaluation

Architecture fit jiannius/playbook is a Laravel package that ships opinionated engineering process as artifacts — artisan commands (boost:install, boost:update, playbook:sync, playbook:check), generated files under .claude/, and a config/playbook.php surface. v0.6.0 significantly widens that footprint: it is no longer just skills/guidelines, it now writes 11 Claude Code task agents into .claude/agents/playbook/ plus a routing rule in .claude/rules/playbook/, each agent carrying its own model and effort settings. That is a meaningful architectural shift: the package is now a distributable agent configuration layer tied to a specific vendor's tooling (Claude Code), not just PHP-side conventions.

The design choices visible in the notes are sound for this pattern: playbook:sync is deliberately narrow (byte-for-byte copies, only within the two playbook/ folders, refuses symlinked folders), and there is an explicit opt-out model (agents.except, agents.enabled, plus per-developer Agent(<name>) deny in personal settings). That separation between org-level opt-out (config, committed) and individual opt-out (personal settings) is the right split.

Integration feasibility Feasible and, for existing consumers, largely mechanical — the package already owns boost:* and the .claude/ tree, so this is an additive write plus a stricter verification gate. Effort concentrates in three places:

1. The CI gate change: playbook:check now exits 1 on stale/missing agent files and exit 2 on gitignore or name collisions. Any pipeline running that check turns red immediately after the version bump until boost:update output is committed.
2. Name collisions with agents the team already authored — a per-agent decision (opt out of theirs vs. delete yours), not automatable.
3. Git / repo hygiene: exit 2 triggers if either playbook/ directory is gitignored. Repos that broad-ignore .claude/ or generate it at container build time will hard-fail.

Technical risk

• CI breakage on upgrade (high likelihood, low severity). Deliberate: exit 1 until files are regenerated and committed. Contained, but it lands on whoever bumps the constraint first.
• Agent name collisions (medium likelihood, medium severity). Silent behavioural change if ours wins; the check catches it, but resolution is a human judgement call per agent.
• claude.yml behaviour change reaches all @v0 callers (high blast radius). @claude replies can no longer start task agents (--disallowedTools "Agent"). This is not gated behind an application-level upgrade — it propagates the moment the v0 ref moves. Teams that wire @claude into triage/automation should treat this as an independent, near-immediate change.
• Staging access for data investigation/backfills (policy risk). Now permitted "when the person who asked for the task explicitly gives it." Production remains off-limits, but the control is a social one (who asked), not a technical one. Worth a written internal policy and an audit trail before enabling.
• Vendor coupling. The agents' model and effort settings are Claude-specific by design (the notes say so explicitly for the routing rule). This makes the package's process layer non-portable to other assistants and exposes you to Claude Code's own release cadence.
• Tooling prerequisite. qa-tester requires a browser tool (Playwright) in Claude Code; without it that agent is dead weight or fails at use time.
• Symlink refusal will break monorepo/symlinked-config setups that previously worked.

Key questions

• Which of the 11 agents do we actually want enabled, and who decides? Default is all-on — do we start from agents.enabled = false and opt in, or accept the default and prune?
• Do we have a committed post-update-cmd running boost:update? If not, this becomes a manual step people will forget.
• How is "the person who asked for the task explicitly gives it" for staging recorded — ticket, PR comment, Slack? Without an artifact, this policy is unenforceable.
• Are any .claude/ paths gitignored or symlinked in our repos or CI images?
• Do we consume @v0 of the shared workflow, and if so, who owns the impact of --disallowedTools "Agent" on our @claude automations?
• Is Playwright available in the Claude Code environments where qa-tester would run?
• What is our rollback story if a generated agent misbehaves — pin back to ^0.5, or agents.except the offender?

Integration Approach

Stack fit This fits naturally into an existing Laravel repo that already runs boost:* in Composer scripts and has Claude Code enabled. The footprint is confined to config/playbook.php and the two .claude/*/playbook/ folders, so blast radius on application code is zero. Teams without Claude Code enabled get nothing written — the agents only land in repos with Claude Code on — which keeps the change scoped, but also means the value is invisible to non-Claude users on the team.

Migration path Follow the documented upgrade, but split it into a controlled two-step rather than one:

1. On a branch: raise to ^0.6, composer update jiannius/playbook -W.
2. If coming from below 0.5, do step 4 of the adoption guide first (CLAUDE.md → @AGENTS.md). Do not skip this — it is a prerequisite, not a nicety.
3. Run php artisan boost:update, then php artisan playbook:check and require exit 0.
4. Resolve exit-2 conditions before merging: un-gitignore the playbook/ folders, fix symlinks, and decide collisions per agent (opt out via config/playbook.php, or delete the incumbent).
5. Commit as one atomic change: composer.*, AGENTS.md, .claude/skills/, .claude/agents/, .claude/rules/. Splitting these across commits is what makes the check flap in CI.
6. Confirm post-update-cmd includes boost:update so future bumps self-heal; if it doesn't, add it in the same PR.

Compatibility

• Backward-compatible at the PHP level; breaking at the workflow and CI level — the check gate, the stale-agent state, and the @v0 workflow change.
• Treat the claude.yml --disallowedTools "Agent" change as a separate workstream: it is not something you opt into via composer.json, so it can hit production automation before anyone runs the upgrade.
• The laravel/pint ^1.17 bump is dev-only; verify it doesn't shift formatting expectations and create a large unrelated diff in the same PR.

Sequencing

1. Policy first. Decide the enabled-agent set and write down the staging-approval rule before generating anything.
2. Pilot in one repo, ideally one with clean .claude/ hygiene and no hand-rolled agents, to surface exit-2 conditions cheaply.
3. Regenerate, resolve, commit atomically.
4. Roll to the rest repo by repo, watching CI on each.
5. Separately assess and, if needed, mitigate the @v0 / @claude Agent restriction.
6. Announce the restart requirement before people pull — a brand-new agents folder is only picked up at Claude Code startup.

Operational Impact

Maintenance Ongoing cost is low but non-zero: the generated files are now versioned artifacts that must be regenerated whenever the package's guidelines change. v0.6.0 itself proves the point — the guidelines changed, so agent files are "STALE until boost:update." Budget for a regeneration commit on most package bumps, and keep it in the same commit as the version bump to avoid stale-check failures.

Support Support load concentrates in two predictable places: developers whose Claude Code still shows the old agent set (answer: restart Claude Code), and developers hitting exit 2 (answer: gitignore or name collision — check .claude/ ignores and config/playbook.php). Both want a short runbook in the repo rather than a Slack thread. Expect a spike in both in the first week after rollout, near zero after.

Scaling Scales fine across repos because playbook:sync is deterministic, idempotent, and confined to two folders — no merge conflicts with application code, no per-repo bespoke setup. The scaling limit is organisational, not technical: config/playbook.php is per-repo, so 11 agent opt-out decisions multiplied across N repos becomes configuration drift. Consider a shared baseline (a standard config/playbook.php in your repo template) and require justification for deviation.

Failure modes

• Stale agents after a pull. Teammates who don't restart Claude Code run yesterday's agents, with different model/effort settings. Symptom is confusing and non-obvious; the fix is a restart.
• CI red after bump. playbook:check exit 1 — expected, resolved by regenerating and committing.
• Exit 2 hard-stop. Gitignored playbook/ folders, symlinked folders, or agent name collisions block the pipeline entirely rather than degrading.
• @claude silently loses agent routing. The --disallowedTools "Agent" change fails closed but quietly; automation that assumed agent delegation will produce plain replies instead. Needs monitoring, not just a changelog entry.
• qa-tester without Playwright. Fails at use time, not at install time — a late, confusing failure.
• Staging overreach. The staging allowance rests on an honour-system approval; without a recorded approval artifact, the failure mode is an unaudited staging data mutation.
• Divergent local agent edits. Hand-editing generated agent files is overwritten by the next boost:update; the correct path (personal Agent(<name>) deny, or agents.except) needs to be documented or people will lose work.

Ramp-up Low for the mechanics, moderate for the judgement. Day one: run the upgrade, restart, done. First two weeks: expect questions on agent selection and collision resolution. The real ramp is cultural — teams need to learn when to hand work to each of the 11 agents, which is exactly what the routing rule encodes, so the rule is the onboarding document. Recommend a short internal demo covering the agent roster, the staging-approval rule, and the restart requirement, run once per team rather than per developer.