Ai Olympus Laravel Package

Product Decisions This Supports

• Whether to standardise AI-assisted delivery in-repo vs. let engineers improvise. ai-olympus ships agent definitions, shared rules, and a handover protocol (shared brief, ledgers, blocking dispatch) as versioned files in the repository. That turns "how we use AI on this codebase" from tribal knowledge into a reviewable artefact you can diff, gate, and roll back — a governance decision, not just a tooling one.
• Whether your merge gate is allowed to enforce architecture, not just correctness. 0.1.3 upgrades duplication from a local check to a repo-wide one: code review now walks every Action in app/Actions/**, and two cases are Critical (a duplicate Action for the same use case, and a multi-step sequence another flow already repeats). A Moderate finding is added for subclass overrides that copy a parent method body to change one step. That means an agent's opinion about your architecture pattern can now block a merge. PMs should decide explicitly whether architectural duplication is blocking or advisory — and whether the Action pattern is a standard you actually want enforced before you turn this on.
• How severity semantics are governed. In the same patch, behaviour change in a refactoring-only diff moved from Critical to Moderate (still blocking, still never deferred at round 3, security carve-out preserved). That is a deliberate softening of one rule and a hardening of another inside a single patch release. Treat the severity table as a document you own and review at each bump, not an implementation detail.
• A reusable pattern for adding advisory lenses without blocking delivery. The new casey agent writes a MySQL/MariaDB analysis as a separate PR comment and is explicitly excluded from review counts, the convergence gate, and the merge gate; on PostgreSQL the inline postgres-patterns lens is unchanged. This is the template to copy: new analysis capabilities land as advisory output first, and only earn gate authority after you have measured their false-positive rate. The explicit fallback string (MySQL report not run — dispatch casey) also means a skipped lens is visible rather than silently absent.
• Trust boundary for external input. 0.1.1's security fix remains the decision-relevant precedent: previously any commenter on a linked issue could plant a criterion that hard-blocks a merge — a delivery-denial vector open to customers, contractors, and bots. The fix keeps untrusted comments as context but denies them gate authority. If you adopt, treat "who can influence the gate" as an explicit, documented policy.
• Trust boundary for the local machine. interactive-testing now prepares the environment before the first scenario: git pull --ff-only, dependency install from committed lock files only, .env creation, migrations, cache refresh, asset build, and starting the processes a scenario needs — all local-target only, without editing tracked files or discarding uncommitted changes, with a reported step log and cleanup (stop processes, return to the original branch, delete a branch it created). A lock-file install is now the single named exception to the outbound-request ban, recorded in the consent table. PMs should decide whether agents may mutate developer machines at all, and whether unready items blocking only their dependent scenarios is the right blast radius.
• How much pre-implementation analysis you require. The new blast-radius-analysis skill maps a change to its dependents before implementation, with depth by risk tier (FAST skips it, STANDARD walks direct callers and write paths, CRITICAL adds a hop over shared symbols and touched risk areas), three evidence grades (Verified / Likely / Unknown), a YAML impact report carried in the shared brief, and a scope-change procedure. leonardo verifies the report's claims rather than trusting them and raises a Moderate finding when a diff reaches an unlisted shared interface, schema, or security boundary. This is a policy choice about upfront cost per change tier and about how much Unknown evidence you will tolerate on a CRITICAL task.
• Build vs. buy for internal agent orchestration. This remains a thin, dev-only Composer package that installs instruction files and drives existing CLIs (gh, acli) rather than a hosted platform — cheap to trial, cheap to abandon, no vendor lock-in, no support contract.
• Model cost/latency tiering. medium reasoning effort for hephaestus/argus/hermes and high for daedalus/athena remains the cost lever, now with a larger roster (the Ninja Turtles team plus casey, dispatched once per diff after convergence and only when the diff touches MySQL/MariaDB or an unresolved engine). Track cost-per-PR, not cost-per-agent.
• Context budget as a recurring maintenance constraint. Two hard limits are now in play: the 150k-character instruction-file limit and the 5,000-token skill body limit. 0.1.3 had to move merge exemptions, terse output style, and markup rules into references/ files to clear composer build without a skill-check warning. Instruction files are a scarce resource, and enforcing that budget consumes real maintainer effort every release — budget for it in the ownership cost.
• CI/network posture. Contract tests drive both loaders against fake gh/acli binaries on an isolated PATH, and composer shell-self-tests now prints one aligned row per script with status, check count, and duration, showing full indented output only for failures. The accurate claim is now narrower than before: no call leaves the machine except the consented, logged lock-file install on a local target.

When to Consider This Package

Consider it when most of the following hold:

• Your repositories are PHP/Laravel and already use Composer, so a --dev dependency adds no runtime footprint to the application.
• Your issues live in GitHub Issues or JIRA, the two trackers the loaders target. There is no evidence of GitLab, Linear, Bitbucket, or Azure DevOps support.
• You use, or want to enforce, the Action pattern. A meaningful share of 0.1.3's review value — repo-wide duplicate-Action detection, Action scope, Template Method guidance — is noise on a codebase organised differently.
• You want agent behaviour versioned alongside the code and reviewable in pull requests, rather than configured in a SaaS dashboard.
• You have at least one named owner for the agent instructions and rules — someone who reads changelogs like this one, decides on severity changes, and re-tunes the rules.
• You are comfortable with the pre-1.0 stability profile and will pin exact versions.
• Your developers' local environments are reproducible enough to be prepared by script (lock files, migrations, asset build, a known project URL), or you are willing to disable interactive-testing.

Look elsewhere, or wait, when:

• Any of this is true: you need vendor support, SLAs, an audit trail for compliance, or a security review of a third party. This is a single-maintainer package with no stated support model.
• You need version numbers to communicate blast radius. 0.1.3 is a patch release that adds two new agents, a new skill, a new blocking Critical check, and a severity downgrade. Combined with 0.1.1 (which changed merge-gate semantics and per-agent reasoning effort under a patch digit) and 0.1.1 being superseded by 0.1.2 the same day, the pattern is consistent: read every changelog in full, never trust the patch number.
• Your tracker is not GitHub or JIRA, or your team is polyglot and needs the same workflow outside Composer-managed repos.
• You cannot tolerate a merge gate that depends on an external system's availability. A failed JIRA fetch previously crashed the whole issue load; it now degrades to an empty list — which means no criteria, a different failure mode worth understanding before you rely on the gate.
• You do not want agents mutating developer machines or starting processes. Local readiness pulls, installs, migrates, builds, and runs the app; the cleanup guarantees are documented but the activity is real.
• Nobody will own the instruction files. Unattended, these accumulate and drift; both size limits exist precisely because that happens.

Practical note for adoption: install 0.1.3, not 0.1.1 (superseded by 0.1.2) or 0.1.2 (superseded by 0.1.3), using --force --prune so removed rule files do not linger. Pin exactly, and re-read the changelog on every bump.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost, dev-only addition that makes our use of AI coding agents auditable and reversible — the instructions that shape agent behaviour live in the repository, go through code review like any other change, and can be rolled back with a commit. It adds no runtime dependency and no customer-facing surface. The most useful signal in this release is how new capability was introduced: the MySQL analysis ships as an advisory PR comment that is explicitly excluded from review counts and the merge gate, which is exactly the discipline we would want — add a lens, measure its noise, then decide whether it may block anything. The trade-off remains maturity: pre-1.0, single maintainer, no support contract, and a patch release that adds two agents, changes a blocking rule, and softens another — version numbers do not yet signal blast radius. My recommendation is a scoped pilot in one or two repositories with a named owner, pinned versions, and a review at the next release, rather than an organisation-wide standard.

To engineering: Adopt as a --dev Composer dependency and install with --force --prune; it installs agent definitions and shared rules into the repo and drives the gh and acli CLIs you already use. Changes since the last assessment worth knowing before you upgrade: code review now compares every new or changed Action against all Actions under app/Actions/** and raises Critical for a duplicate use case or a repeated multi-step sequence, with a matching Moderate finding for subclass overrides that copy a parent method body (the fix is Template Method when you own the parent, composition otherwise); behaviour change in a refactoring-only diff is now Moderate rather than Critical — still blocking, still not deferred at round 3, security carve-out preserved; blast-radius-analysis adds risk-tiered impact mapping with Verified/Likely/Unknown evidence and a YAML report carried in the shared brief, which leonardo verifies rather than trusts; casey writes an advisory MySQL report after convergence, dispatched only for MySQL/MariaDB or unresolved-engine diffs and never counted in the gate; interactive-testing now prepares the local environment (ff-only pull, lock-file install, migrations, caches, assets, processes) with a step log and cleanup, and a lock-file install is the one consented outbound exception, logged via outbound-request. merge-github-pr and pr-summary were split to fit the 5,000-token skill body limit — no rule text lost. composer shell-self-tests now prints aligned per-script rows and only dumps output for failures. Pin whatever you land on and read the changelog on every bump.