Pao Laravel Package

Product Decisions This Supports

• Build vs. buy for the agentic engineering stack. PAO answers a narrow question we would otherwise be tempted to solve internally: "how do we stop AI coding agents from burning context on test-runner noise?" A one-line dev dependency replaces what would be a custom output formatter we'd own and maintain. Default to buying here and reserve engineering capacity for work that is actually differentiated.

• Whether to fund an "agent efficiency" roadmap line at all. If a meaningful share of PHP work runs through Claude Code, Cursor, Devin, or Gemini CLI, this package is the cheapest available instrument for that initiative — it produces a hard, attributable number (tokens per tool call, before vs. after) with no instrumentation work. That makes it a good first proof point for a broader AI-tooling investment case.

• Per-repo adoption sequencing, not a platform mandate. Because human terminal output is byte-identical, adoption can be phased repo by repo. Product decision: pilot on 1–2 modern, test-heavy PHP repos, measure, then decide whether to standardize.

• Lockstep-upgrade policy as a standing roadmap commitment. Most releases are compatibility patches for PHPUnit/Pest/Paratest printer internals. Adopting PAO means committing to upgrade it alongside the test toolchain indefinitely. That's a recurring tax that must be budgeted, not assumed away.

• Context-budget allocation for agent workflows. Token reduction is a proxy for how much of the agent's window is spent on the actual problem versus progress dots. This feeds decisions about which repos we point agents at first — large test suites and verbose Artisan output (about, db:show, migrate:status) are the highest-yield targets.

• Use cases worth scoping now: onboarding agents onto legacy PHP repos with 1,000+ test suites; reducing inference spend on CI-adjacent agent runs; making PHPStan/Rector output machine-actionable so agents self-correct on lint and static-analysis failures rather than needing a human to re-prompt.

• Signal on ecosystem maturity. 728 stars, MIT, Laravel-org stewardship, active releases — credible. But zero dependents and readme-plus-releases as the only documentation means we are early. Product read: low technical risk, low ecosystem validation. Treat as a low-cost bet, not a foundation.

When to Consider This Package

Adopt when all of these hold:

• Repos run PHP 8.3+ and PHPUnit 12–13, Pest 4–5, Paratest, PHPStan, Rector, or Laravel 12+. Outside those windows, the package simply cannot hook in.
• A material share of engineering work happens inside an AI agent. Where agents aren't in use, PAO is inert — zero cost, zero benefit. No agent usage means no business case.
• The repo's test suite is large or verbose enough that output volume is a real context or log-readability problem. On a 20-test repo the win is negligible.
• We can independently verify exit-code correctness across pass, fail, error, timeout, and partial-run scenarios before the repo gates merges on it.

Look elsewhere — or defer — when:

• Repos are pinned to PHP 8.2 or below, PHPUnit 11 or older, or Pest 3 or older. No path in without a test-toolchain upgrade, which changes the cost calculus entirely.
• The stack isn't PHP, or the test runner isn't one of the supported six.
• CI log consumers expect text. PAO only activates under agent detection, but if agent-detection environment variables leak into our CI images we get JSON where a log parser or a human expects prose. This is the false-positive hazard and it must be ruled out first.
• Dependency resolution is constrained. It's a dev dependency, but it still participates in Composer resolution — long-lived or tightly pinned applications are where transitive conflicts will bite.
• Exit codes can't be proven correct. The changelog shows a recurring pattern of exit-code and runtime-exit fixes. If PAO ever reports success on a failing suite, we have silently disabled our quality gate — strictly worse than verbose logs. Non-negotiable gate.
• We need stable, contractually documented output formats. This is a v1.x package with readme-level documentation and zero dependent packages; the JSON shape is not a public contract yet.
• Large legacy codebases with hundreds of static-analysis errors — PHPStan output is grouped by file and capped at 30 errors. Sound token economics, but truncation is an inherited judgment call we don't control.

Decision rule: pilot on one or two modern, greenfield-adjacent PHP repos with active agent usage and a large suite. Kill it if exit-code verification fails or if agent detection misfires in CI. Otherwise expand, with a named owner for lockstep upgrades.

How to Pitch It (Stakeholders)

For executives — one paragraph: Laravel PAO is a free, MIT-licensed, dev-only package that makes our test and static-analysis tooling far cheaper to run inside AI coding agents. It converts verbose human-readable output — hundreds of lines of progress dots, PHPStan error walls, Artisan tables — into compact JSON, cutting tokens by up to 99.8% on test runs and roughly 70–75% on Artisan commands. It installs as a single dev dependency, changes no application code, ships no production surface, and leaves human terminal output completely unchanged. Reversibility is one line removed from composer.json. The ask is a bounded pilot on two repos with a hard gate on exit-code correctness — this is a low-cost option on lower inference spend and higher agent task completion, not a platform migration.

For engineering — the honest version:

• Zero integration work. composer require laravel/pao --dev. No config file, no CI change, Laravel 12+ service provider auto-discovery. It hooks PHPUnit, Pest, Paratest, PHPStan, Rector, and Artisan through Composer's autoloader.
• No blast radius. It's an output shim, not a runtime dependency. No HTTP surface, no database, no queue path, no performance exposure. It only activates when it detects an AI agent in the environment.
• Your terminal is untouched. Same colors, same formatting. Existing CI log consumers and developer muscle memory are unaffected — which is what makes phased rollout possible.
• Two things we must prove before trusting it. First, exit-code correctness across pass, fail, error, timeout, and partial runs — if PAO ever reports success on a failing suite, we've disabled our quality gate. Second, that agent-detection environment variables don't leak into our CI containers and produce JSON where a parser expects text.
• One thing we must budget for. Most upstream releases are compatibility patches for PHPUnit/Pest/Paratest internals. Adopting this means upgrading it in lockstep with the test toolchain, indefinitely. Assign an owner.
• Be clear-eyed on maturity. 728 stars and Laravel-org backing, but v1.x, readme-only docs, and zero dependent packages. It's a good bet precisely because it's cheap and reversible — not because it's proven at scale.