Pao Laravel Package

Product Decisions This Supports

• Agent-driven development economics. If any meaningful share of engineering work runs through Claude Code, Cursor, Devin, or Gemini CLI, tool output is a recurring token cost and a context-window tax. PAO gives us a concrete number to act on: up to 99.8% fewer tokens on large test suite summaries (constant-size regardless of suite size) and 73–75% on Artisan commands like about and db:show. That turns "AI tooling costs" from an untracked line item into a tunable parameter.
• Build vs. buy for output shaping. The alternative is writing and maintaining our own JSON/truncation layer across PHPUnit, Pest, Paratest, PHPStan, Rector, and Artisan. The release history is effectively a list of upstream compatibility patches (PHPUnit ^13.3.0, Paratest with PHPUnit 13.2.x, unsupported Pest versions, missing PHPStan/Rector output on non-analysis command paths). That maintenance treadmill is the real cost comparison, and it favors taking the MIT dependency.
• Roadmap input for "agent-ready" internal tooling. PAO is a cheap probe of a bigger question: should agent legibility be a first-class requirement for tools we build internally? One composer require --dev in one repo produces evidence before we commit roadmap capacity to a broader initiative.
• Standardization decision. It offers a de facto output shape (tool, result, counts, *_details, raw) we can either standardize on or write a spec against for our own instrumentation. Deciding now whether we want a house standard for machine-readable tool output is a decision this package forces into the open.
• Scoping the adoption slice. We can ship the low-risk, high-value portion (Pest/PHPUnit summary compaction plus Artisan cleanup) and explicitly defer the risky portion (PHPStan's 30-error cap, Rector file_diffs which scales with content) until guardrails exist. Adoption is not all-or-nothing.
• Ecosystem positioning. 728 stars, zero declared dependents, README and releases as the only maturity artifacts, now under the Laravel org. It's a "standard Laravel-ecosystem bet" for shops already comfortable with that, and "unproven third-party risk" for shops that aren't. Naming which one we are is itself the decision.

When to Consider This Package

Adopt (or pilot) when:

• A real fraction of the team uses AI agents on PHP repos, often enough that token spend or context exhaustion is a felt problem rather than a hypothetical.
• Test suites are large enough for the constant-size win to matter — hundreds or thousands of tests, or heavy --parallel usage.
• The stack sits inside supported versions: PHP 8.3+, PHPUnit 12–13, Pest 4–5, Laravel 12+, with Paratest, PHPStan, and Rector covered. Non-Laravel projects (Symfony, Laminas, vanilla PHP) still get the test and static-analysis benefits even without Artisan cleanup.
• Developer experience is a hard constraint. The conditional switch — human terminal sessions get byte-identical output — is the single strongest adoption argument in orgs that resist tooling churn, and it means no retraining, no docs, no workflow migration.
• We own a CI matrix and can treat a PHPUnit/Pest/PHPStan upgrade as requiring a quick PAO compatibility check, and we can pin the version.
• We treat the output as agent-facing diagnostics, not as a contract our own systems parse.

Look elsewhere or wait when:

• We need a versioned, documented schema for internal systems to consume. The JSON shape churned within 1.x and nothing signals a stability guarantee; parsing it couples us to an unversioned format.
• Workflows depend on complete static-analysis output. The deliberate 30-error PHPStan cap is a correctness hazard in an agent remediation loop — the agent can declare the codebase clean with 40 errors unseen — and is disqualifying without a separate full-report path.
• We're outside supported versions, or locked down enough that autoloader interception and implicit environment-based behavior switching require a security review first.
• We cannot get an explicit per-repo and per-CI override for agent detection. "Detects an AI agent" is a marketing statement until the mechanism is documented: false negatives cost tokens silently, false positives break scripts expecting human output.
• Nobody uses agents yet — the package is inert. Adopting is nearly free and speculative; deferring costs nothing.

How to Pitch It (Stakeholders)

For executives: This is a single dev-only Composer dependency, MIT licensed, zero configuration, that converts verbose test and static-analysis console output into compact JSON only when an AI agent is driving the tools. Reported reductions are up to ~99.8% fewer tokens on test summaries and ~75% on Artisan commands, with the output size staying flat as the suite grows. There is no change to human developer workflows, no application code touched, and no lock-in — removal is one composer remove. Frame it as an operating-cost lever on AI-assisted development, not an architecture commitment.

For engineering: PAO is an interception layer at the output boundary, not a library with an API. It hooks in through Composer's autoloader plus an auto-discovered service provider for Artisan, so there is nothing to call and nothing to integrate. The risks are real and should be stated up front: it tracks undocumented internals of five fast-moving tools, so every tool upgrade becomes a PAO compatibility event; the JSON schema is unversioned and has already churned inside 1.x; PHPStan output is deliberately truncated at 30 errors; the raw pass-through preserves Pest --coverage/--profile output but scales with content, so the constant-size claim applies to summaries, not everything; and agent detection is implicit and needs a documented, forceable override.

Recommended ask: approve a time-boxed pilot in one repository rather than a team-wide rollout. Pin the version, add a CI job that runs the suite both ways to confirm human output is unchanged and JSON is correct on failures, verify that agent detection can be forced on and off per repo and per CI job, keep a full PHPStan report alongside PAO for remediation loops, and measure token spend and agent task success before and after. Ship the Pest/PHPUnit and Artisan slice; hold Rector and PHPStan until the guardrails above are confirmed.