AI Olympus is a Composer plugin that gives PHP and Laravel teams shared coding-standard rules, 69 reusable skills, and nine specialist agents for Claude Code and Codex. Its workflows cover issue implementation, Pest tests, code and security review, acceptance testing, and tracker reporting. The skills, agents, and commands are also published as a Claude Code plugin for projects without Composer, without the rules.
- PHP 8.4 or newer and Composer 2, for the Composer installer
- Claude Code or Codex, to run the workflows; GitHub workflows also need an authenticated
ghCLI - Optional: the
pdo_sqliteextension with FTS5, for the code-review memory; without it the agents continue without memory
CI installs the package into a clean Composer project on PHP 8.4, 8.5, and 8.6 and checks that the Claude Code and Codex files are written. It does not run the agents inside Claude Code or Codex, so agent availability and permissions still depend on your agent host. The Claude Code plugin channel needs no PHP; CI checks its manifests but does not install it into Claude Code.
From your Composer project root:
composer require pekral/ai-olympus:0.5 --dev
vendor/bin/ai-olympus install --forceImportant
install normally copies only missing files; security rule files are refreshed even without --force. --force also replaces the other installed rules, skills, and agents, so save local customizations first. Neither root instruction file (CLAUDE.md, AGENTS.md) is overwritten.
During the agent rename, the installer removes verified, unchanged copies of the old definitions once their replacements are installed. Edited old definitions and custom agents are preserved. See the old-to-new name mapping. Use --prune only after reviewing orphaned files: it also removes custom files absent from the package.
The constraint pins release 0.5; commit your project's composer.lock to keep installations reproducible. Composer may ask whether you trust the package as a plugin; see the plugin trust model.
The installer writes, for Claude Code and Codex:
.claude/rulesand.codex/rules— the rule library.claude/skillsand.agents/skills— the skills, in the project only.claude/agents,.codex/agents, and.codex/agent-instructions— the nine agents and their Codex adapters.claude/commands— the five slash commandsAGENTS.mdin the project root, unless one already exists
--global additionally writes the skills to ~/.claude/skills and ~/.agents/skills. Every other switch, the installer flow, and the distribution contents are in docs/installation.md.
/plugin marketplace add pekral/ai-olympus
/plugin install ai-olympus@ai-olympus
This loads all 69 skills, the nine agents, and the five commands into Claude Code only. It does not load the rules: Claude Code reads neither rules/ nor a CLAUDE.md out of a plugin directory. The opt-in security switches stay bound to the Composer installer, and a plugin install writes nothing to .claude/settings.local.json. See which path to choose.
Nothing has to be configured before the first run; restart the agent session after installation.
The installer never generates a CLAUDE.md, and it keeps an existing CLAUDE.md and AGENTS.md. Without a CLAUDE.md, Claude Code 2.1.277+ uses AGENTS.md as its project instructions (except on Bedrock, Vertex, and Foundry). If your project already had an AGENTS.md, merge the Codex integration section into it.
Automatic installation on composer install and composer update is off by default; extra.ai-olympus.auto-install turns it on, and then every install and update runs install --force. The same extra.ai-olympus object is the project manifest, which tells the workflows how your project runs its quality gate and coverage; every key is optional, and an absent key keeps the built-in behaviour. Your own CLAUDE.md, AGENTS.md, .ai/rules/**, and the manifest take precedence over the packaged rules; only the security floor stays fixed.
The manifest key parallel.max-units (1 to 3) caps how many units of a batch run at the same time; without it the planner uses 2 and the batch cap is 3 (see Project manifest in rules/general/general.md).
Agents talk to you in a relaxed, straight-to-the-point voice, in the chat and in the tracker comments people read. The voice key of the project manifest switches it to technical, and your own instruction in the session overrides it; commit messages, handoffs, and machine-parsed text stay technical either way (see the agent-voice skill).
Installation leaves global Claude settings unchanged by default. The opt-in switches, such as --disable-co-author-attribution, --allow-subagent-writes, and --deny-network-bash, configure Claude Code only and grant Codex no permissions; see the trust model.
In Claude Code, start the session as krang, so the session itself orchestrates and dispatches the specialists:
claude --agent krang "resolve https://github.com/owner/repo/issues/123"
A command works in any session, because the session that receives it holds the krang role itself:
/prepare-issue-for-merge https://github.com/owner/repo/issues/123
In Codex, ask the root session to take the krang role, so it spawns the specialists itself:
Follow .codex/agent-instructions/krang.md as krang and resolve https://github.com/owner/repo/issues/123
With several references, or with the optional --merge flag, the same command prepares a batch: the session holds the krang role for every issue and runs one pipeline for each in its own git worktree, at most 3 at a time. Without --merge it stops before merge; with it, each unit rebases onto the latest default branch and merges through merge-github-pr with every gate unchanged.
/prepare-issue-for-merge https://github.com/owner/repo/issues/123 https://github.com/owner/repo/issues/124 --merge
/do-it takes free-form instructions instead of a reference. It splits them into independently deliverable items, reuses the issue of an item that has one (after a trust check on its author), creates one GitHub issue for every other item, orders the queue by priority, difficulty, and duration, and runs every item to a converged pull request through the same batch mechanism. It reports each item with its pull request, status, and blocker, and never merges.
/do-it add the CSV export of orders, then a date filter for it, and fix the typo on the login page
Codex invokes the same workflows as $verify-merge-readiness and $do-it.
rules/compound-engineering/orchestration.md Starting the orchestrator — the top-level role and the nested hand-over explains why krang is not started as a subagent.
krang routes implementation to donatello, each code review round to leonardo, splinter (an independent security view), raphael (interactive testing, when the change is user-visible), and casey (an advisory database report) in parallel, a page redesign to michelangelo before anything is built, context retrieval to shredder when the relevance gate asks for it, and the final report to april. Merging stays a separate, explicit step. For a hotfix, only you can start the merge-github-pr-fast skill (/merge-github-pr-fast in Claude Code, $merge-github-pr-fast in Codex): it runs one security-only check of the diff, stops on a Critical finding or a check that did not complete, and otherwise merges when CI on the head commit is green or the quality gate passed on that exact commit.
A batch unit first tries gh pr update-branch --rebase to reach the latest default branch. When that stops on a conflict, donatello resolves it on a new <branch>-vN branch and opens a new pull request, and nothing is force-pushed. krang alone closes the pull request that the new one supersedes, after a pointer comment; every helper agent only reports the replaced number.
| Layer | What it is | Installed into |
|---|---|---|
| Rules | Project standards for PHP, Laravel, security, SQL, APIs, tests, git, and code review | .claude/rules, .codex/rules |
| Skills | Reusable workflows, from resolve-issue to security-review |
.claude/skills, .agents/skills |
| Agents | Shared role definitions with Codex TOML adapters | .claude/agents, .codex/agents, .codex/agent-instructions |
| Commands | /do-it, /prepare-issue-for-merge, /redesign-page, /report-code-review, /test-assignment |
.claude/commands |
The Markdown files in .codex/rules are an instruction library, not native Codex command-approval rules: the root AGENTS.md tells Codex which of them to read. Codex has no user-defined slash commands, so it reaches each command's workflow through the skill the command delegates to, such as $verify-merge-readiness, $deliver-page-redesign, or $test-assignment.
The workflows require tests for the changed behaviour and zero Critical and no undeferred Moderate review findings before merge. On a pull request from a branch of the same repository, a converged code review with no blocking finding counts as the approval, because GitHub does not let the author approve their own pull request. A pull request from a fork still needs a GitHub approval.
Two rules shape the Laravel work. Date and time code uses Carbon or a Laravel date helper (now(), today(), the Date facade, an Eloquent date cast) instead of date(), strtotime(), or new DateTime(...), and string, array, and collection work reuses Str, Arr, Collection, Number, and data_get() before any hand-written code (rules/laravel/laravel.md Carbon and Framework Helpers). When your project installs laravel/pao, the rules read its compact JSON output of Pest, PHPUnit, Paratest, PHPStan, Rector, and Artisan, and trust only the process exit code.
The roster is named after Teenage Mutant Ninja Turtles characters. Each agent starts on its default model tier and escalates only on a recorded reason; the values come from agents/*.md and codex/agents/*.toml.
| Agent | Role | Claude Code | Codex | |
|---|---|---|---|---|
 |
krang |
orchestrator, the front door | opus · high |
gpt-6.1-sol · high |
 |
donatello |
implementer, opens a draft PR | sonnet · high |
gpt-5.6-terra · high |
 |
leonardo |
code and security reviewer, read-only | opus · high |
gpt-6.1-sol · high |
 |
splinter |
independent security reviewer, read-only | opus · high |
gpt-6.1-sol · high |
 |
raphael |
acceptance tester on a local instance, read-only | sonnet · medium |
gpt-6-luna · medium |
 |
michelangelo |
page redesign proposal | opus · high |
gpt-6-astra · high |
 |
casey |
advisory database report, read-only | sonnet · high |
gpt-6-luna · high |
 |
shredder |
context retrieval, read-only | opus · high |
gpt-6.1-sol · high |
 |
april |
final tracker report and announcements | haiku · medium (not applied to Haiku) |
gpt-6-luna · medium |
Role boundaries, the handoff contract, and the avatar assets are in docs/agents.md. Running a single specialist, the five command workflows, and how agents hand work over are in docs/workflows.md.
Every krang run classifies the task with skills/_shared/classify-risk.sh, a deterministic shell script, and picks a FAST, STANDARD, or CRITICAL pipeline. A sensitive area such as authentication, secrets, payments, or migrations forces CRITICAL, while tests, static analysis, CI, and the pre-merge quality gate run at every tier. The tiers are roles rather than model names, so Codex / OpenAI sessions route identically. Ask for thorough mode (--thorough) to run the complete pipeline regardless of the classification. See Adaptive routing for the tier table and overrides.
A code review covers four areas and nothing else: functionality against the assignment, security, database optimisation, and code rules. It drops every point outside the assignment, proposes no follow-up issue, and still reports a security vulnerability found outside the assignment. Architecture is reviewed through ten principles with one finding shape (changed location, concrete problem, impact, smallest remedy). A duplicated piece of existing logic is a Moderate finding, and a Moderate finding still blocks the merge.
From the second round of a review-and-fix loop, leonardo raises only new Critical findings and every security finding; an earlier finding stays tracked until it is fixed. The Review findings section of the non-technical report (pr-summary) lists only the points that must be resolved before the merge. The owners are rules/code-review/general.md (What a code review checks, and nothing else, Later rounds raise only new Critical findings, Reuse Existing Logic) and rules/code-review/core-analysis.md (Architecture principles).
- One heavy job at a time. Every gate run, dependency install, full test suite, and targeted check (Pest, Rector, or PHPStan on a path list) holds one machine-wide lock in
${XDG_CACHE_HOME:-$HOME/.cache}/ai-olympus(AI_OLYMPUS_LOCK_DIRmoves it), shared by every project and worktree of the account. Agents take it throughskills/_shared/run-gate.sh, andskills/_shared/run-validation.shholds it itself. - No unfixed vulnerability on a public tracker.
create-issue,create-issues-from-text, and/do-itcheck the visibility of the target repository before they create an issue. On a public repository, or when the visibility cannot be shown, they withhold an item that describes an unfixed vulnerability and report it to you with the private routes (GitHub private vulnerability reporting and a draft security advisory). A deferred pre-existing security item ofresolve-issuegoes through the same guard (skills/create-issues-from-text/SKILL.mdGuard for a possible vulnerability).
Resolved Critical code-review findings are kept in a per-user, git-ignored SQLite database (.claude/run/code-review-memory.sqlite, or .codex/run/ under Codex), which krang reads only when a review opens a Critical finding. krang is the only writer: it adds one short TL;DR entry after a human approved it. The installer never creates or deletes it.
vendor/bin/ai-olympus memory migratememory migrate moves the entries of docs/memory/PROJECT_MEMORY.md into the database once. Exit 0 is a result (possibly empty), 1 a usage error, 2 an unavailable memory. The memory add and memory query subcommands, stats for routing metrics, and graph for the repository graph are described in docs/workflows.md.
docs/installation.md— installer flow, every CLI switch, auto-install, the project manifest, and where skills are installeddocs/agents.md— the agent roster, capability model, handoff contract, and troubleshootingdocs/workflows.md— command workflows, adaptive routing, metrics, the repository graph, and the code-review memorydocs/skills.md— the catalog of all 69 skillsdocs/rules.md— the 33 rule files, grouped by scope
From a checkout of this repository, install the development dependencies with composer install, then:
vendor/bin/pest tests # run the test suite
composer test:coverage # require 100% coverage (PCOV)
composer analyse # PHPStan
composer security-audit # dependency auditcomposer build is the full pre-merge gate: it runs the installer with --force --prune, the automatic fixers, then every check. It changes files, so use it at the merge boundary, not as a read-only check. Its skill linter also needs Node.js and npm.
Review the changelog before changing the version constraint, save local customizations, and refresh the installed files with --force --prune after the update. During 0.x, a new minor version may change workflow behaviour or installer options. A project upgraded from a release that always installed skills globally clears the old home copies once with vendor/bin/ai-olympus install --prune-global, which deletes them by name, immediately and without a backup. See versions and upgrades and where skills are installed.
See CHANGELOG.
See CONTRIBUTING for the quality gate, how to add or change a skill, and the commit and pull request conventions. This project follows the Contributor Covenant Code of Conduct. Ask questions in the Discussions Q&A and keep the issue tracker for bugs and feature requests.
See the security policy for the plugin trust model, the installer security switches, and how to report a vulnerability privately.
Created by Petr Král.
The package code is licensed under the MIT License; see LICENSE. The banner artwork is distributed under CC BY-SA 4.0; artwork sources, licences, and trademarks are listed in assets/ATTRIBUTION.md.