README

AI Olympus — An AI Development Team for Laravel

AI Olympus gives Laravel/PHP teams shared coding standards, 59 reusable skills, and six specialist agents for Claude Code and Codex. The workflows cover issue implementation, Pest tests, code and security review, acceptance testing, and tracker reporting.

Requirements

PHP 8.3 or newer (PHP 8.x) and Composer 2 for the installer; Claude Code or Codex for the workflows. GitHub workflows also need an authenticated gh CLI. The Claude plugin does not require Composer.

Installation

Run the two commands in Quickstart from your Composer project root. Composer installs the package; the second command installs its Claude Code and Codex integration.

Configuration

The installer never generates a CLAUDE.md, and it preserves 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). For an existing AGENTS.md, merge the Codex integration section after installation. Review overwrite behaviour and settings before using --force. Automatic installation is off by default; opt-in configuration enables forced refreshes on Composer install/update when the plugin is allowed.

The same extra.ai-olympus key in composer.json is the project manifest: it tells the workflows how your project runs its quality gate and coverage, which extra tools validation may run, which paths are critical, and which language, timezone, and tenancy model apply. Your own instructions — CLAUDE.md, AGENTS.md, .ai/rules/**, and the manifest — take precedence over the packaged rules; only the security floor stays fixed.

Quickstart

composer require pekral/ai-olympus:dev-master --dev
vendor/bin/ai-olympus install --force

This installs the current master development branch, which contains the Ninja Turtles team shown below. Commit your project's composer.lock to keep installations reproducible. The tagged release 0.1.2 still uses the original agent names; see versions and upgrades if you need that release.

Restart the agent session after installation. In Claude Code:

@splinter resolve https://github.com/owner/repo/issues/123

In Codex, request the role by name:

Use the splinter agent to resolve https://github.com/owner/repo/issues/123

splinter routes implementation to donatello, review to leonardo, a page redesign to michelangelo before anything is built, acceptance testing to raphael when needed, and the final report to april. Codex adapters reuse the same role instructions; agent availability and permissions still depend on your Codex environment.

What You Get

Layer	What it is	Installed into
Rules	Project standards; Codex reads the library through `AGENTS.md`	`.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	`/prepare-issue-for-merge`, `/redesign-page`, `/report-code-review`, and `/test-assignment`, the slash commands the package ships	`.claude/commands`

The Markdown files in .codex/rules are an instruction library, not native Codex command-approval rules. The root AGENTS.md tells Codex to read rules whose paths match the task, plus every rule without paths.

Codex exposes no user-defined slash command, so .claude/commands has no Codex counterpart. The same workflow reaches Codex as the skill each command delegates to — mention $verify-merge-readiness, $deliver-page-redesign, $test-assignment, or the tracker's code-review wrapper ($code-review-github, $code-review-jira, $code-review-bugsnag) and Codex loads it from .agents/skills.

Why This Package

Issue-to-PR workflow — separate roles implement, review, test, and report
Adaptive routing — a deterministic classifier picks a FAST, STANDARD, or CRITICAL pipeline per task, so a typo fix does not pay for an authorization rewrite's review
Cheapest model that works — the implementer and the reviewer run at their default tier (Sonnet on Claude Code) and escalate to the strongest model only on a recorded reason; the same contract binds to Codex / OpenAI's own model controls
Explicit review gates — workflows require zero Critical findings and no undeferred Moderate findings before merge
Coverage requirements — implementation skills require tests for the changed behaviour
One standard across every repository — the same PHP/Laravel rules travel with the package instead of being copy-pasted per project
59 comprehensive Agent skills you can invoke directly when you want the workflow without the agent

Installation Details

Use Composer for the dual Claude Code/Codex installation and CLI. The plugin marketplace is a separate Claude Code-only distribution channel.

	Composer	Plugin marketplace
Requires	PHP + Composer	Claude Code only
Skills, agents	Both Claude Code and Codex locations	Claude Code plugin only
Project instructions	Rules, `AGENTS.md`	None
`--deny-network-bash` and the other opt-in switches	✅	❌ Composer only

Via the plugin marketplace (no Composer)

/plugin marketplace add pekral/ai-olympus
/plugin install ai-olympus@ai-olympus

That loads all 60 skills, the six agents, and the /prepare-issue-for-merge, /redesign-page, /report-code-review, and /test-assignment commands. It does not load the rules: Claude Code reads neither rules/ nor a CLAUDE.md out of a plugin directory, and this channel carries no command to copy them across. Use Composer when you want the rules in the project.

The opt-in security switches stay bound to the Composer installer. A plugin install writes nothing to .claude/settings.local.json.

Via Composer

The Quickstart above carries the two commands. This is what they put in your project for Claude Code and Codex:

.claude/rules and .claude/skills in the project
.claude/agents (the six subagents)
.codex/rules (the same rule library), .agents/skills (Codex's native skill location), and .codex/agents (the six custom-agent adapters)
.codex/agent-instructions (the canonical role definitions shared with Claude Code)
.claude/commands (the /prepare-issue-for-merge, /redesign-page, /report-code-review, and /test-assignment slash commands; Codex reaches the same workflows as $verify-merge-readiness, $deliver-page-redesign, $test-assignment, and the tracker's code-review wrapper)
AGENTS.md in the project root

Skills install into the project only. Claude Code uses .claude/skills; Codex discovers the same skills from .agents/skills. --global additionally writes both user locations (~/.claude/skills and ~/.agents/skills), and --prune-global clears this package's copies from both. See Where skills are installed.

Important

install normally copies only missing files; security rule files are refreshed even without --force. The Quickstart's --force also replaces other installed rules, skills, and agents, so save local customizations first. Neither root instruction file 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.

Installation leaves global Claude settings unchanged by default. Pass --disable-co-author-attribution to set includeCoAuthoredBy: false in ~/.claude/settings.json when absent; existing values are preserved. The installer still removes this package's obsolete bash-guard hook from project settings. This cleanup and the opt-in settings switches configure Claude Code only, including when you intend to use Codex; they do not grant Codex permissions. See the trust model.

Everything beyond those two commands — enabling auto-install on composer install, the full command list, the installer flow, and every CLI switch — lives in docs/installation.md.

Claude Code and Codex Subagents

Agents are a thin orchestration layer over the existing skills — they don't replace them and they don't duplicate their prompts. The roster uses Teenage Mutant Ninja Turtles characters matched to each role (see docs/agents.md).

Rules  = long-lived project standards
Skills = reusable workflows
Agents = specialised orchestration roles over multiple skills

The six specialists keep their existing responsibilities and permissions under the new names. Full role definitions live in docs/agents.md.

	Splinter (`splinter`) — engineering-workflow orchestrator · the front door Routes a free-form request to the specialists: `donatello` for implementation, `leonardo` for review, `michelangelo` for a page redesign, `raphael` for acceptance testing when needed, and `april` for the final report. It can request a security analysis or a redesign specification before implementation or prepare an existing PR for merge without merging it. It does not implement or review code itself. Backlog triage and splitting a broad request into deliverable issues run inline. Orchestrates: `donatello`, `leonardo`, `michelangelo`, `raphael`, `april` (dispatched) · `github-issue-triage`, `create-issues-from-text`, `create-issue` (inline)
	Donatello (`donatello`) — code-writing implementer Implements an issue from context or a tracker link, authors its test coverage, runs the relevant tests, then opens a draft PR. It also handles scoped validation after a landing step. The implementation run stops at the PR; authoritative review belongs to `leonardo`, and final tracker reporting belongs to `april`. An explicitly requested merge must use the separate `merge-github-pr` skill. Orchestrates: `resolve-issue`, `create-test`, `create-missing-tests-in-pr`, `e2e-testing`
	Leonardo (`leonardo`) — the code-review sentinel · read-only The roster's only CR agent. Two modes: the authoritative code review after `donatello` — code quality, architecture, optimisation and security in one pass, driven to convergence and published as a single pull-request comment carrying a TL;DR of what changed — and an on-demand pre-implementation security analysis that feeds a remediation plan to `donatello`. Applies every security rule and labels each finding Critical / Moderate. Orchestrates: `code-review-github`, `code-review-jira`, `code-review-bugsnag`, `process-code-review`, `security-review`, `laravel-authorization-review`, `laravel-security`, `security-bounty-hunter`, `security-threat-analysis`, `analyze-problem`
	Raphael (`raphael`) — acceptance tester · read-only Exercises changed behaviour on a local running application: APIs over HTTP and UI scenarios in a real browser. Uses the project's `interactive-testing` skill when available. Returns a per-criterion Met / Not met / Blocked verdict with observed evidence; an untested criterion is never Met. Pure refactors and documentation changes do not need this pass. It never edits code, authors tests, merges, or publishes. Orchestrates: `tester-cookbook`, `e2e-testing`
	Michelangelo (`michelangelo`) — page redesigner · writes only its own proposal Redesigns an existing page around the operator who works in it — a warehouse, workshop, or shop-floor worker who is not an IT person and needs the order out. It maps every state the main screenshot hides, lays the content region out against that operator's task sequence, and hands back a developer-ready specification with one rendered preview per state. The application's main layout shell is never touched without an explicit order, and it proposes rather than implements: it holds no `Edit` tool, so no file the application ships is changeable by it. Orchestrates: `page-redesign`
	April O’Neil (`april`) — release announcer & reporter · read-only Writes release announcements and publishes the final tracker report after review converges: what changed and how to test it. For merge preparation, it publishes one verified source-issue TL;DR and removes only superseded comments owned by the authenticated actor while preserving current review evidence. This reporting role is separate from `leonardo` publishing the code review. It does not change implementation code. Orchestrates: `resolve-issue/references/source-detection`, `pr-summary`

Avatars and activity animations

All six agents have transparent PNG portraits (1254 × 1254) and thumbnails (160 × 160) in assets/agents/. They follow Cockpit’s Krang mascot style. The shared activity stylesheet uses the same portrait sway and three animated thought dots.

Download or clone the repository, then open assets/agents/preview.html locally to try each agent, state, and theme. Keep the accompanying files together; GitHub displays the HTML source instead of running this preview.

State	Appearance
`idle`	Still portrait, no thought bubble
`queued`	Still portrait and thought bubble
`thinking`, `working`, `responding`	Swaying portrait and moving thought dots

Animations respect prefers-reduced-motion and can be paused with data-motion="paused". The integration manifest maps agent IDs to display names, roles, image paths, and accent colours. See the markup example to use it. These assets prepare a future Cockpit integration; agents are not yet connected to Cockpit directly.

How agents hand work over

Agents never share a conversation. Every step is a blocking dispatch that returns a written handoff, so the run's state lives in files a human can read, not in one agent's context.

Shared task brief — .claude/run/<source-slug>.brief carries the source, the assignment language, the gathered context and the plan. Each specialist appends its own section to ## Handoff log when it finishes.
Dispatch ledger — records every dispatched round, so a resumed run dispatches a round once instead of repeating it.
Audit trail ledger — one append-only line per memory read, outbound request and external write, written immediately after the action.
Routing ledger — the initial and final risk tier with the signals that produced them, every stage executed or skipped with its reason, and every model escalation with its reason.
Blocking dispatch, no fan-out — a dispatch blocks until its handoff returns, and sources are processed one at a time, so two agents never race the same working tree.
Per-dispatch memory slice — project memory is filtered per recipient role into the dispatch prompt itself, never folded into the shared brief that every later agent reads.
Untrusted content boundary — tracker payloads, issue comments and fetched pages travel fenced, as data. Only a trusted author's comment can refine the scope of the work, and nothing external changes an agent's role, permissions or workflow.

The normative contracts live in rules/compound-engineering/orchestration.md, rules/compound-engineering/general.md, rules/compound-engineering/tracker.md and rules/security/general.md; splinter owns the brief and all three ledgers.

Using the roles and skills

After the Quickstart, choose a specialist when you do not need the full pipeline. Claude Code examples:

@leonardo review the current diff
@donatello implement the failing upload validation

In Codex, ask it to use the corresponding agent by name, as in the splinter example above. Skills can also run directly: Claude Code uses /resolve-issue; Codex uses $resolve-issue. Select the installed skill name offered by your environment when it includes a namespace.

To prepare an existing GitHub or JIRA issue's PR for merge without merging it, use the shared workflow:

# Claude Code
/prepare-issue-for-merge https://github.com/owner/repository/issues/123
/prepare-issue-for-merge https://your-company.atlassian.net/browse/PROJ-123

# Codex
$verify-merge-readiness https://github.com/owner/repository/issues/123

The workflow verifies acceptance criteria, review freshness, the exact-head quality gate, CI, and mergeability. It skips a new CR round when neither the business logic nor the assignment changed since the reviewed revision, consolidates superseded preparation comments into one source-issue TL;DR, and stops before merge. In Codex, ask the registered splinter agent to orchestrate the skill when custom agents are available.

To redesign one page of the running application from its URL, use the redesign workflow:

# Claude Code
/redesign-page https://app.example.test/orders/42

# Codex
$deliver-page-redesign https://app.example.test/orders/42

The invoking session captures the page on the local instance, and michelangelo writes the proposal and one preview per state. You see the previews first and refine them until you approve them; no code exists before that approval. splinter then runs the full delivery route in thorough mode: donatello implements the approved design with the existing design system and opens the pull request, leonardo reviews it to convergence, and raphael verifies the page in its own interactive browser on desktop and mobile viewports. The workflow keeps the main layout shell and the business logic unchanged, and it never merges.

To review a task's pull request and only report the result, use the review-only workflow:

# Claude Code
/report-code-review https://github.com/owner/repository/issues/123
/report-code-review https://your-company.atlassian.net/browse/PROJ-123

# Codex
$code-review-jira https://your-company.atlassian.net/browse/PROJ-123

splinter dispatches leonardo once. leonardo runs the code-review wrapper that matches the tracker, and the wrapper publishes the technical findings on the GitHub pull request and the non-technical summary on the source issue. In that summary, Review findings replaces How to test: it retells the GitHub report in plain language so a non-technical reader can understand it and reply with feedback. The workflow fixes nothing, changes no tracker status, and never merges.

To test a task's pull request against its assignment and prove that nothing else broke, use the test workflow:

# Claude Code
/test-assignment https://your-company.atlassian.net/browse/PROJ-123
/test-assignment https://github.com/owner/repository/pull/123 fix

# Codex
$test-assignment https://your-company.atlassian.net/browse/PROJ-123

splinter maps every input that reaches the changed behaviour and builds a test matrix of real data. donatello runs the whole test suite and the gate on the final head, and raphael exercises the running application and compares it with the base branch. In report mode (the default) the workflow changes nothing, and april publishes the technical report on the pull request and a plain-language summary on the source issue. In fix mode donatello adds the missing tests and fixes, and the workflow continues as /prepare-issue-for-merge. It never merges.

Adaptive routing — how much pipeline a task gets

Every splinter run classifies the task before it dispatches anything, using skills/_shared/classify-risk.sh — a deterministic shell script, not another model call. The verdict decides the pipeline:

Tier	Who runs	Typical change
`FAST`	implementer (default tier) + deterministic validation	docs, typo, formatting, tests-only, simple config, rename, small isolated fix
`STANDARD`	`+ leonardo` (default tier)	ordinary application and business-logic work
`CRITICAL`	`+ leonardo` analysis where relevant, both at the escalated tier	auth, secrets, payments, migrations, data loss, concurrency, queues, locking, public APIs, core architecture, large refactors

A sensitive area — authentication, authorization, secrets, payments, migrations — forces CRITICAL on its own, whatever the score says.
raphael runs at every tier when the change alters behaviour a user can observe. It checks the UI in a real browser whenever the change reaches a page, and it creates a local test account when it cannot sign in otherwise.
The tier is recomputed against the real diff after implementation and can only rise, so a task that grows into an authorization change is reviewed like one.
Tests, static analysis, linting, CI, and the pre-merge quality gate run at every tier, FAST included. The tier buys LLM reasoning, never a deterministic gate.
Every decision is recorded, so "why was leonardo executed?", "why was the expensive model used?" and "why was this CRITICAL?" are answerable from the run's own ledger.
The classifier is a shell script and the tiers are roles rather than model names, so Codex / OpenAI sessions route identically; codex/agents/*.toml binds the tiers to that platform's model controls.

Deterministic work no longer buys a model. Validation, route planning, and the routine completion report are scripts, and an LLM is the escalation path for each:

Stage	Helper	A model runs only when
Validation	`run-validation.sh`	a check failed and needs interpreting, or the manifest was invalid or refused
Route planning	`plan-route.sh`	never — the plan is the tier's stage list
Completion report	`render-report.sh`	the audience needs real writing (announcement, changelog prose, a language the renderer does not carry)

The implementer writes a validation manifest naming the commands that cover its own diff; the runner executes them without a shell, against an allow-list of project-local tools, and returns a verdict with an explicit escalate field. A FAST task therefore completes with one specialist dispatch.

Agent handoffs are structured and bounded (check-handoff.sh): they carry decisions and artifact paths, never diffs or test output, so a long review loop stops re-tokenising the same evidence at every round.

Override it when you disagree: ask for thorough mode (or --thorough) to run the complete pipeline regardless of the classification, or name a tier directly with --fast / --standard / --critical. An escalating override always applies; a de-escalating one is refused when a sensitive area forced the tier, and the refusal is reported rather than silent.

Context-efficient orchestration is on by default and has no flag. The run assembles each stage's context from a small manifest rather than re-deriving it, executes the route plan instead of re-reasoning about the workflow, and passes scoped context rather than the accumulated history. It is orthogonal to the tier above: routing decides which stages run, context efficiency decides how cheaply the ones that do run reach their result. Ask for verbose orchestration (--verbose-orchestration) only to debug a routing decision — it adds narration, never a check.

Measuring the routing decisions

Each completed run appends counts only to a local store outside the repository — tier, outcome, dispatches, escalations, review rounds, finding counts. No source, diffs, prompts, issue text, branch names, or URLs are ever written.

vendor/bin/ai-olympus stats --last=7d

The summary answers the questions a single run cannot: how often FAST runs escalate (the tier is routing real work past the review), how often reviews find nothing (the tier is buying a pass that changes no outcome), and how often the expensive model tier is used. Token counts appear only where the runtime reports them — an absent number rather than an estimated one.

Role boundaries, handoffs, adaptive routing, context efficiency, and troubleshooting are documented in docs/agents.md. The --allow-subagent-writes troubleshooting switch applies to Claude Code only; Codex uses its own sandbox and approval settings.

Skill Catalog

60 skills, grouped by what you reach for them for — issue → PR workflow, code review, security, testing, databases, frontend, infrastructure, refactoring, analysis, and tooling. The full table, with one line per skill and a link to each, is in docs/skills.md.

Rules Overview

33 rule files: a small always-on baseline every run applies, on-demand rules for code review, trackers, project memory, pull requests, tracker reports, JIRA and refactoring, plus scoped rules for PHP, Laravel, security surfaces, SQL, APIs, and tests. The full table, grouped by scope, is in docs/rules.md.

Claude Code loads the Markdown rules from .claude/rules. Codex uses the explicit loader instructions described in What You Get.

Development & Testing

From a checkout of this repository, install development dependencies with composer install. CI uses PHP 8.5; the package manifest does not declare a minimum PHP runtime version.

vendor/bin/pest tests        # run the test suite
composer test:coverage       # require 100% coverage (PCOV)
composer analyse             # PHPStan
composer security-audit      # dependency audit

composer build is the full pre-merge gate: it runs the installer with --force --prune, automatic fixes, then checks. It changes files, so use it at the merge boundary, not as a read-only verification command. See composer.json for individual scripts and contributor setup for the contribution process.

Contributing

Pull requests are welcome. CONTRIBUTING.md carries the full flow: the composer build quality gate every change must pass before it is merged, how to add or change a skill, and the commit and pull request conventions.

CHANGELOG.md — every notable change, newest first
CODE_OF_CONDUCT.md — the Contributor Covenant this project follows
SECURITY.md — the plugin trust model, the installer security flags, and how to report a vulnerability privately

Questions

Ask in Discussions — the Q&A category takes questions about compatibility, using the rules without the agents, and writing your own skill. Keep the issue tracker for bugs and feature requests, so a real defect does not get buried under questions.

License

Author

Petr Král — PHP Developer & Laravel programmer, open source contributor (pekral.cz).

pekral / ai-olympus

Package info

Security

Statistics