Laravel Ai Harness Laravel Package

Product Decisions This Supports

• Standardizing AI-assisted development across the team. The harness manages the config files AI agents (Claude, Codex) use — CLAUDE.local.md, AGENTS.override.md, per-project config — so you can make a call on one supported agent workflow instead of letting each engineer assemble their own. 0.6.0's global Composer install + init --global turns that from "a per-repo dev dependency" into "a machine-level tool", which is the version of this decision that actually scales past a handful of repos.
• Build vs. buy on internal tooling. This package is squarely in the "buy" column for runtime/agent scaffolding: PHP version selection, HTTPS site setup, worktree hooks, health checks, and per-runtime cleanup for Herd, Valet, and now Yerd 2.x. Writing and maintaining that matrix in-house is a recurring tax with no product differentiation.
• Onboarding cost and time-to-first-commit. update / doctor / setup as a repeatable three-command path — including for linked worktrees, which now inherit configuration — is a measurable onboarding lever. doctor in particular gives you a supportable failure mode instead of "my local env is broken".
• Roadmap sequencing for developer-experience work. The 0.6.0 breaking rename (herd_php/valet_php/yerd_php → php_version, *_secure → site_secure, services → service_manager) is a forced coordinated migration with no compatibility aliases. That is a scheduling decision: pick a quiet week, budget each engineer a personal-config migration, and don't stack it against a release deadline.
• Secrets and machine-specific config hygiene. local_env.* overrides plus generated integrations excluded via .git/info/exclude mean machine-specific values stop leaking into shared .gitignore/committed config — a policy win you can point at during a security or repo-hygiene review.
• Use cases worth scoping against: multi-repo Laravel estates, teams running parallel feature worktrees, mixed Herd/Valet/Yerd fleets, and any org piloting AI coding agents where you need reproducibility before you can measure the productivity claim.

When to Consider This Package

Consider adoption when:

• Your team is Laravel-first and already standardizing on an AI coding agent (Claude Code / Codex) rather than trialing several.
• You run more than a couple of repos, or you use git worktrees for parallel work — the inheritance and per-worktree refresh logic is the highest-value part, and it's the part you'd never build yourself.
• You have a heterogeneous local runtime fleet (some on Herd, some Valet, some Yerd, some Sail). 0.6.0's shared runtime abstraction is the release that makes this defensible; before it, the config surface was runtime-fragmented.
• You can absorb a short, coordinated migration: 0.6.0 rejects all seven old keys outright — no aliases, no auto-migration — and Composer's refresh hook and harness commands fail if any remain. This is a config-file rename with a hard failure mode, not a soft deprecation.
• You have an owner for tooling maintenance who will read the upgrade guide and can be the person collaborators ask about their personal files.

Look elsewhere or defer when:

• You are not on Laravel, or your PHP version matrix is outside 8.2–8.5 (the CI-validated range).
• You need stability guarantees. Pre-1.0, breaking config changes between minor versions, and a required host-Composer transition step (^0.5 does not include 0.6.0) all say "pin exactly, upgrade deliberately".
• Your team is small and homogeneous — one repo, one runtime, one agent. The abstraction cost likely exceeds the benefit.
• You can't tolerate the global-install blast radius. The global path is convenient, but a bad version affects every project on the machine at once; the per-project --dev install is the safer default for a first rollout.
• You need agent/tooling coverage beyond Claude and Codex, or enterprise SSO/audit controls the package doesn't claim to provide.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is low-cost developer tooling that standardizes how our engineers' AI coding assistants are configured and how their local Laravel environments are provisioned. It replaces per-engineer setup folklore with three repeatable commands, supports every local runtime we use, and — as of 0.6.0 — installs once per machine and inherits cleanly across parallel worktrees. The business case is onboarding speed, fewer "works on my machine" hours, and the ability to actually measure AI-assistant productivity because the environment is reproducible. Cost is a dev dependency plus a one-time, roughly hour-per-engineer migration to rename seven configuration keys; risk is contained because the tool is pre-1.0 and easily removed.

For engineering leads: 0.6.0 consolidates three runtime-specific key sets into one (php_version, site_secure, service_manager), adds Yerd 2.x as a first-class runtime, adds uncommitted local_env.* overrides for machine-specific values, and adds a global install path that keeps generated agent integrations out of the shared .gitignore via .git/info/exclude. Validation is solid for this stage: 325 tests / 1,455 assertions, CI green on PHP 8.2–8.5, plus ShellCheck and static analysis, with explicit regression tests for the removed keys.

For the migration conversation (be blunt): this is a breaking release with no compatibility aliases. The seven removed keys must be renamed in .ai-harness.config.dist, .ai-harness.config, .ai-harness.config.global, and .ai-harness.config.local before Composer runs, including inherited personal files and every worktree override. ^0.5 constraints won't pull 0.6.0, so the upgrade is explicit. The recovery path if the Composer hook already failed is --no-scripts, rename, then update / doctor / setup — worth putting in the ticket so nobody debugs it live. Commit shared config and refreshed managed files; each collaborator still migrates their own personal files.