Ai Olympus Laravel Package

Getting Started

• composer require pekral/ai-olympus:0.1.3 --dev — pin the version explicitly; this is a dev-only dependency whose "product" is files, so an unpinned constraint turns every composer update into an unreviewed behaviour change.
• vendor/bin/ai-olympus install --force --prune. Both flags matter: --force overwrites instruction files you may have edited, and --prune removes stale agent/rule files left behind by a previous version. Run it on a clean working tree so you can read the diff.
• Commit the installed artefacts. The agents are now two teams: the originals (daedalus, athena, hephaestus, argus, hermes) and the Ninja Turtles shipped in 0.1.3 (leonardo, donatello, raphael, splinter, casey). Alongside them are rules/compound-engineering/*.md, rules/code-review/*.md, rules/php/core-standards.md, rules/laravel/architecture.md, rules/refactoring/general.md, and the skills/** trees. The diff of an upgrade is the only readable changelog — and with 0.1.3 splitting several skills into references/ subfolders, that diff is also the only way to see where a paragraph moved.
• Authenticate the CLIs first. The issue loaders shell out to gh for GitHub and acli for JIRA; the package carries no credentials of its own. If those binaries aren't on PATH and logged in, nothing else works.
• Start with README.md (handover section): the shared brief, both ledgers, blocking dispatch, the per-dispatch memory slice, and the untrusted-content boundary. In 0.1.3 the shared brief gains a second payload — the YAML impact report produced by blast-radius-analysis — so read that skill's SKILL.md next, then rules/code-review/core-analysis.md, which absorbed the largest batch of changes this release.
• First real use case: point the review gate at a live ticket before you trust it. It is still the highest-value feature and the one with the sharpest edges. Second: run a STANDARD-tier ticket through resolve-issue with blast-radius-analysis enabled and check the impact report it records.

Implementation Patterns

• Gate as a required CI check, not a local habit. Issue Context Analysis derives acceptance criteria from the linked item, and an unsatisfied criterion is reported as a Critical finding that blocks the merge. Installed and run only on developer machines, it is advisory; wire it into the pipeline as a required status or it will be skipped under deadline pressure.
• Let loaders degrade. Both issue loaders are documented to return an empty list rather than fail when a sub-fetch breaks. Code around them accordingly: "no comments" is a legitimate signal, not an error state, and the issue body plus remaining context still reach the agent.
• Write acceptance criteria where the gate can see them deterministically. Comments are still read and their facts still feed the review, but an untrusted comment author cannot contribute a criterion on its own. Put criteria in fields you control — issue body or description — rather than relying on a thread of comments.
• Reference the extracted rules instead of copying them. rules/compound-engineering/concurrency.md, backlog.md and orchestration.md, plus rules/code-review/core-analysis.md, general.md and rules/php/core-standards.md, are first-class files. If your own agent prompts duplicate those contracts, replace the copies with references so behaviour is tuned in one place.
• Let the DRY walk do the whole-repo comparison, and don't hand-roll it. Since 0.1.3, Reuse of existing logic enumerates every new Action, every changed __invoke(), and every entry point moved onto an Action, then compares each against every Action under app/Actions/** — not just the same domain folder. Two shapes are Critical: a duplicate Action with the same use case, and a sequence of two or more steps that another flow repeats. A repeated sequence is one finding listing every copy, so don't file per-site duplicates. Give your implementers the mirror rule in rules/laravel/architecture.md Before you create an Action and the Action scope bullet, so one fragment never raises two findings.
• Distinguish the copied-override finding from the duplicate finding. A subclass that copies a parent method to change one step is a Moderate finding (Template Method when you own the parent, composition when the step varies multiple ways or the parent is vendor code) — and rules/code-review/general.md deliberately does not re-raise it as a Critical duplicate. Calibrate your severity dashboards to that split, or you will see the same override counted twice.
• Treat refactoring-only reviews as behaviour-preservation checks first. rules/refactoring/general.md now makes "logic stayed the original" the primary lens, compared before every other lens. A behaviour change — bug fix included — is Moderate, still blocks the merge, and is never deferred to a sub-issue at round 3, because the loop restores the old behaviour. An S1–S3 security change keeps its security severity.
• Run blast-radius-analysis before implementation, not after. Depth follows the tier that classify-risk.sh already owns: FAST skips it, STANDARD walks direct callers and write paths, CRITICAL adds one hop over shared symbols and every touched risk area. Findings carry an evidence grade (Verified, Likely, Unknown) and land in a short YAML report that travels in the shared brief: donatello names it in the handoff, leonardo verifies its claims rather than trusting them and raises Moderate when the diff reaches an unlisted shared interface, schema, or security boundary, raphael turns its runtime scenarios into regression rows. Use the scope-change procedure — stop the affected step, analyse only the new part — instead of re-running the whole walk.
• Keep the MySQL lane advisory. splinter dispatches casey once per diff, after convergence, when the diff touches MySQL/MariaDB database operations (or an unresolved engine). It runs mysql-problem-solver with MODE=cr-report and posts one PR comment in the mysql-report marker namespace. It never enters review counts, the convergence gate, or the merge gate. On PostgreSQL, postgres-patterns stays the inline lens. If a caller cannot dispatch casey, have it write MySQL report not run — dispatch casey so a missing lane is visible rather than silent.
• Use interactive-testing's local readiness instead of a bespoke setup script. Before the first scenario it checks the head under test, lock-file-matched dependencies, .env, migrated database, caches, front-end assets, and a responding app URL on the project URL. Each item is prepared with the project's own documented command, only on a local target, without editing tracked files or discarding uncommitted changes; the run stops the processes it started, returns to the branch it started on, deletes any local branch it created, and pulls with git pull --ff-only. An item that cannot be made ready blocks only the scenarios depending on it — so keep scenario dependencies explicit.
• Route work to the right effort tier. hephaestus, argus and hermes run at medium; daedalus and athena stay at high. Send broad mechanical sweeps and repetitive review passes to the medium tier and reserve the high tier for planning and adjudication — the cheapest lever you have on cost and latency.
• Use the handover seam for custom tooling. The shared brief and per-dispatch memory slice are the integration point; the blast-radius report is the worked example of how to add a payload to it. Feed external context through the brief rather than standing up a parallel channel the agents don't know about.

Gotchas and Tips

• --force is destructive to local edits. Any tweak to agents/*.md, rules/*.md or skills/** is gone on reinstall. Keep customisations in a separate, referenced file, or hold your patches as a diff you re-apply and test after each upgrade. 0.1.3 moved text between skill bodies and references/ subfolders — a patch against the old location will silently fail to apply.
• There are now two independent size ceilings. Instruction files are loaded in full and capped at 150,000 characters, guarded by a test; daedalus sits at ~75% since the 0.1.1 extraction, and 0.1.3 added more agents and rules on top, so re-check locally when you extend one. Separately, skill bodies are capped at 5,000 tokens — 0.1.3 brought merge-github-pr and pr-summary back under it by pushing content into references/merge-exemptions.md, references/terse-output-style.md and references/markup-per-target.md. Detail belongs in references; composer build warns via skill-check when you get it wrong, so run it before committing.
• Put new skill detail in the reference file, not the body. Splitting is now the house style: the FAST-tier / dependency-only / HOTFIX merge cases and the terse output style no longer live in the skill body at all. If you are hunting for a rule you remember reading, check references/ before concluding it was dropped.
• CLI coupling is the main source of CI fragility. Anything that reshapes PATH, rotates credentials, or bumps the gh/acli version can break a loader that works on a laptop. Copy the package's own testing approach: contract tests drive both loaders against fake binaries on an isolated PATH, proving you can exercise the full path with no call leaving the machine. composer shell-self-tests now runs scripts/run-shell-self-tests.sh, printing one aligned row per script with status, check count and duration, and full indented output only for the failing script — so a red row is now a single script to isolate, not a wall of mixed formats.
• Empty comment lists deserve a second look. Comment fetching is the historically fragile step. If a familiar ticket suddenly loads with no comments, inspect the fetch path before concluding the thread is genuinely empty.
• The trust test lives in the rule layer, not the loader. When the gate's behaviour around a comment surprises you, look in the compound-engineering rule that owns author trust rather than in the analysis step.
• A blast-radius report is a set of claims, not ground truth. leonardo is specified to verify each claim, and Unknown is a legitimate grade — do not promote the YAML into a merge gate or copy it into a ticket as fact. Treat an unlisted shared interface, schema, or security boundary in the diff as the signal that the walk was too shallow.
• casey's report is deliberately outside the gates. Don't wire the mysql-report comment into a required check, and don't read its absence as a pass: convergence happens before dispatch, so a report may never appear on a diff that failed review.
• interactive-testing mutates your working copy. It installs from committed lock files, migrates, rebuilds assets and pulls — with a documented cleanup and no edits to tracked files. Run it on a clean tree anyway. Note that the lock-file install is the single named exception to the outbound-request ban in rules/compound-engineering/orchestration.md, and it appears in the consent table — make sure whoever approves runs understands that.
• Severities moved in 0.1.3; recalibrate any dashboards. Refactoring-only behaviour changes and copied-override findings are Moderate (both still block), while duplicate Actions and repeated multi-step sequences are Critical. If you track "Critical findings per PR", the number will drop for overrides and rise for cross-domain duplication without any change in real risk.
• 0.1.3 supersedes 0.1.2, which superseded 0.1.1. New installs should start here. Treat 0.1.1 as the security floor regardless: the comment-to-merge-gate fix is worth taking immediately even on an old tree, because the prior behaviour let any commenter block a merge.