AI Olympus — An AI Development Team for Laravel

AI Olympus gives a Laravel/PHP team an AI development team inside Claude Code — five specialized subagents that resolve GitHub issues, open pull requests, review code, audit security, write Pest tests, and report the result back to the tracker. One composer require --dev installs the whole roster together with the coding-standard rules and agent skills they run on. It replaces the hand-maintained CLAUDE.md and the ad-hoc prompt library every project otherwise reinvents.

Quickstart

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

No Composer in the project? Add it as a Claude Code plugin instead — see Installation.

Then point the front-door agent at real work, inside Claude Code:

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

daedalus picks the route, hephaestus implements it, athena reviews it to convergence, and you get a pull request back.

What You Get

Why This Package

• Ship an issue without writing the boilerplate — one agent takes the ticket, implements it, and hands back a reviewed pull request
• Reviews that block on real findings — one review pass covers quality and security together and must reach zero Critical and Moderate before anything merges
• Tests you did not have to remember to write — a change lands with Pest coverage for the lines it touched
• One standard across every repository — the same PHP/Laravel rules travel with the package instead of being copy-pasted per project
• 54 comprehensive Agent skills you can invoke directly when you want the workflow without the agent
• Onboarding measured in one command — a fresh checkout gets the whole team from composer require --dev

Installation

There are two ways in. Composer is the complete one and stays the recommendation for a PHP project. The plugin marketplace exists for everyone else — most of this package is stack-agnostic, and a project without Composer had no way to reach it at all.

Via the plugin marketplace (no Composer)

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

That loads all 54 skills and the five agents. It does not load the rules: Claude Code reads neither rules/ nor a CLAUDE.md out of a plugin directory, so one command copies them into the project once.

/ai-olympus:install-rules

It writes .claude/rules/ and, when the project has none, a CLAUDE.md — it never overwrites one you already have. Restart the session afterwards; rules are read at session start.

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 — the installer targets Claude Code only:

• .claude/rules and .claude/skills in the project
• .claude/agents (the five subagents)
• CLAUDE.md in the project root

Skills install into the project only. Claude Code lets a personal skill (~/.claude/skills) override a project one, so a home copy would shadow this checkout in every project on the machine — --global opts into that deliberately, and --prune-global clears copies an earlier version left behind. See Where skills are installed.

[!IMPORTANT] By default, the installer only copies missing files and keeps existing content untouched. Use the --force flag to overwrite existing files: vendor/bin/ai-olympus install --force. This is particularly useful when you want to update rules to their latest versions or when you've made local changes that should be replaced. The file CLAUDE.md is never overwritten once it exists in the target project, so you can safely customize it.

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 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 is named after Greek mythology by function (see docs/agents.md).

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

Each agent has its own avatar under assets/agents/. Full role definitions live in docs/agents.md.

hephaestus — code-writing implementer

Implements an issue from context or a tracker link, authors its test coverage, runs the tests covering the change, then opens a PR. Also runs as the fast scoped validation gate after a landing step. Stops at the PR — it never reviews its own work, merges, or publishes to a tracker.

Orchestrates: resolve-issue, create-test, create-missing-tests-in-pr, e2e-testing

argus — acceptance tester · read-only

The only agent that runs the application. It starts a local instance and tests it like a real tester — the API through a real HTTP client, the UI in a real browser (the project's own automation, or the bundled browser-drive.sh runner that needs nothing installed in the project) — then returns a per-criterion Met / Not met / Blocked verdict with the exact request/response or clicks it performed. A UI criterion it cannot drive in a browser is Blocked, never satisfied by calling the endpoint behind the page. Dispatched only when the change alters observable behaviour — a refactor or a docs change is skipped — and the browser starts only when the diff actually touched a UI surface, so an API-only task is still exercised over HTTP without paying for a browser run. Its input is the running system, which is where a missing migration or an unstarted queue worker hides from both the diff and a green test suite. It never edits code, authors tests, merges, or publishes.

Orchestrates: tester-cookbook, e2e-testing

daedalus — engineering-workflow orchestrator · the front door

The entry point for a free-form request. Resolves a concrete source, then dispatches athena (security-risk analysis, on demand), hephaestus (implementation, then scoped validation), athena (the single CR pass) and hermes (the post-convergence report) through the Task tool, planning a dependency-aware resolve order. Delegates every engineering step — never implements or reviews itself. It also owns the backlog tier and runs it inline: triage over the open issues, and splitting a subject too broad for one PR into deliverable issues, after which the run ends there.

Orchestrates: hephaestus, athena, hermes (dispatched) · github-issue-triage, create-issues-from-text, create-issue (inline)

athena — the code-review sentinel · read-only

The roster's only CR agent. Two modes: the authoritative code review after hephaestus — code quality, architecture, optimisation and security in one pass, one published review, driven to convergence — and an on-demand pre-implementation security analysis that feeds a remediation plan to hephaestus. Applies every security rule and labels each finding Critical / Moderate / Minor.

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

hermes — release announcer & reporter · read-only

The roster's only publishing agent — anything that reaches a tracker audience routes through it. Turns a merged change or release into announcement content: a Twitter/X tweet (≤280 chars) + thread, release notes, and a marketing summary with pekral.cz promotion. It also publishes the post-convergence report (what changed + how to test) on the source tracker at the end of a daedalus run, composed from the shared brief and hephaestus's validation handoff.

Orchestrates: resolve-issue/references/source-detection, pr-summary

How to use athena in practice

1. Install for Claude Code:

   vendor/bin/ai-olympus install
   

   Agents land in .claude/agents/.

2. Invoke it with a source — a GitHub PR/issue, a JIRA key, a Bugsnag error, or just the current branch/PR:

   @athena review PR #123
   @athena review https://your.atlassian.net/browse/PROJ-42
   @athena review the current diff
   

3. athena detects the tracker, runs the matching code-review-* skill (which drives the full CR skill set), adds the security skills that wrapper does not run, lets it post one consolidated review to the PR, then returns a handoff: CR done + PR link + source link + Critical/Moderate/Minor counts + assignment-conformance verdict.

athena is read-only — it never applies fixes, commits, pushes, or merges. Those belong to separate agents.

How to use hephaestus in practice

1. Install for Claude Code, exactly as for athena — agents land in .claude/agents/.

2. Invoke it with a source — a GitHub issue/PR, a JIRA key, a Bugsnag error, or just the task you want implemented:

   @hephaestus implement #123
   @hephaestus implement https://your.atlassian.net/browse/PROJ-42
   @hephaestus implement the failing upload validation
   

3. hephaestus detects the source, runs resolve-issue to implement the change, runs the tests covering it, then opens a PR and returns a handoff: Impl done + PR link + source link + branch + a summary of what changed and the local-checks result.

hephaestus stops at the PR — it never reviews its own work or merges. The whole code review — quality, architecture, optimisation and security — belongs to athena. Hand the PR to athena for review next.

[!NOTE] If hephaestus reports Blocked: sandbox denied file write: dispatched subagents run non-interactively, so a write is denied unless the path is pre-allowed. Add scoped Edit / Write entries for the project tree to permissions.allow in .claude/settings.local.json ("Edit(//Users/me/Projects/my-app/**)", "Write(//Users/me/Projects/my-app/**)") — or run the installer with --allow-subagent-writes to add them for you — then re-run. See docs/agents.md Troubleshooting — subagent file writes blocked. The run correctly stops instead of silently finishing the work in the main thread.

How to use daedalus in practice

daedalus is the front door — the agent you address with a free-form request when you don't want to pick a specialist yourself.

1. Install for Claude Code, exactly as for the other agents.

2. Invoke it with a request — it resolves the source and chooses the route:

   @daedalus resolve a random Resolve_by_AI issue
   @daedalus resolve https://github.com/owner/repo/issues/123
   @daedalus implement a dark-mode toggle for the settings page
   

3. daedalus resolves a concrete source, then dispatches the matching specialist agent through the Task tool: a security-focused task → athena (security-risk analysis → remediation plan) → hephaestus; everything else → hephaestus directly; then athena for the review-and-fix loop to convergence. A subject too broad for one PR is not pushed into a single PR: daedalus splits it into deliverable issues itself, inline, and the run ends there, so you re-run it per issue. A pure backlog request ("triage the open issues", "what should we work on next") is answered the same way — inline, no PR. It returns a handoff naming the chosen route and reason, written in the same language as your request.

   Ask explicitly for savings mode ("run this in savings/token-efficient mode", "úsporný režim") to opt into a token-efficient variant of the exact same pipeline — same agents, same convergence gate, same PR/review/feedback artifacts, just less duplicate context re-derivation. It is off by default; see docs/agents.md Savings mode for how it works.

daedalus is a read-only orchestrator — it never analyses, implements, or reviews itself; it delegates every step by dispatching the matching specialist agent, and (per the one-level subagent-nesting rule) it runs as the top-level agent you talk to, spending that single nesting level on the dispatch rather than being a nested subagent itself. It owns the backlog tier too — deciding what is worked on and in what order — and runs that part inline rather than delegating it: the same nesting rule leaves no level to spend on a peer backlog agent, which is why the one this roster used to ship (zeus) was folded into daedalus instead.

Skill Catalog

All 54 skills, grouped by what you reach for them for. Each description is the skill's own description: front-matter, trimmed to one line — nothing here claims a capability the skill does not declare.

Issue → PR workflow

Code review

Security

Testing

Databases

Frontend & UI

Infrastructure & performance

Refactoring & code quality

Analysis & planning

Meta & tooling

Unattended Runs

resolve-next hands the oldest unclaimed issue carrying the configured labels to Claude Code as one agent run. One invocation resolves one issue, which makes it a natural fit for cron or Task Scheduler.

vendor/bin/ai-olympus resolve-next --dry-run          # print the chosen issue and the prompt, run nothing
vendor/bin/ai-olympus resolve-next                    # resolve it and leave the pull request for review
vendor/bin/ai-olympus resolve-next --merge            # ...and merge once the review converges
vendor/bin/ai-olympus resolve-next --label=bug --repo=owner/name

The run chains /resolve-issue → /code-review-github → /process-code-review on the issue it picked. Merging is opt-in: without --merge the prompt explicitly tells the agent to leave the pull request open, so an unattended schedule never merges on its own.

An issue already carrying Resolve_by_AI:in-progress is skipped, so two overlapping ticks cannot pick the same issue. An empty backlog exits 0 — a quiet schedule is not a failure.

[!IMPORTANT] The trigger label is the only gate on what an unattended run will work on. Anyone who can apply that label to an issue can decide what the agent spends a run on, so keep it restricted to people you would let open a pull request. The command never passes --dangerously-skip-permissions; grant only the narrow permissions the run needs (the installer's --allow-subagent-writes adds scoped Edit/Write entries for the project tree). If you also want the harness to refuse raw network commands during those runs, --deny-network-bash writes permissions.deny entries for curl, wget, ssh, and similar — session-wide within the project, so it restricts your own interactive Bash there too; see SECURITY.md for what it does not cover.

Requires the GitHub CLI (gh, authenticated) and the claude binary on PATH. Scheduling every two hours:

# Linux / macOS — crontab -e
0 */2 * * * cd /path/to/project && vendor/bin/ai-olympus resolve-next >> storage/logs/agent.log 2>&1

# Windows — Task Scheduler, every 2 hours
schtasks /create /tn "ai-olympus" /sc hourly /mo 2 /tr "cmd /c cd /d C:\path\to\project && vendor\bin\ai-olympus resolve-next"

Rules Overview

Rules included in this package:

The paths: key decides when a rule loads, and it has two settings, not three. Every rule ships as .md, the only extension Claude Code reads from .claude/rules/, and every rule states its reach with one key. A rule with no paths: key loads into every session — the Always scope above. A rule with a paths: list loads once the session reads a file the list matches, and stays absent until then — reading is the trigger, not any tool use, so a session that only writes a matching file may never pull the rule in; the @rules/… references in skills and other rules are what carry a scoped rule into a run its glob misses. There is no third setting. An empty list, paths: [], is read as the first one: measured in a live session, every rule that carried it was present from the opening turn, exactly like a rule with no key at all (issue #45). This package used to spell a Reference scope that way and no longer does — a rule that loads everywhere now says so by omitting the key, so the declaration and the behaviour agree.

Cursor's .mdc extension and its globs: / alwaysApply: keys are gone (issue #187 moved seven rules, issue #277 the remaining eleven). The installer deletes a file the source stopped shipping only under --prune, so run vendor/bin/ai-olympus install --force --prune once when upgrading, or the old .mdc copies stay behind and drift.

Development & Testing

Composer Scripts

composer check              # run full quality check (skill-check, normalize, phpcs, pint, rector, phpstan, audit, tests)
composer fix                # run all automatic fixes (skill-check-fix, normalize, rector, pint, phpcs)
composer build              # install (ai-olympus install --force) then fix then check
composer analyse            # run PHPStan static analysis
composer test:coverage      # run tests with 100% coverage (compact output — failures only)
composer coverage           # same gate with the full per-file coverage report
composer security-audit     # run security audit of dependencies

Individual Commands

composer skill-check                # SKILL.md linter (diagnostics only — silent when every skill passes)
composer skill-check-fix            # SKILL.md linter with auto-fix
composer composer-normalize-check   # validate composer.json normalization (dry-run)
composer composer-normalize-fix     # apply composer.json normalization
composer phpcs-check                # PHP CodeSniffer check
composer phpcs-fix                  # PHP CodeSniffer fix
composer pint-check                 # Laravel Pint check
composer pint-fix                   # Laravel Pint fix
composer rector-check               # Rector check (dry-run)
composer rector-fix                 # Rector fix

Testing

./vendor/bin/pest           # run all tests
composer test:coverage      # run tests with coverage (min. 100%)

Remove coverage.xml before committing if it was produced locally.

Contributing

Pull requests are welcome. CONTRIBUTING.md carries the full flow: the composer build quality gate every change must pass, 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

MIT — see LICENSE. Copyright (c) 2025 Petr Král.

Author

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