Claude Agent System — Optimization

Claude Agent System — Optimization Release

Overview

This release refactors the Claude Code agent configuration from a monolithic, knowledge-heavy setup into a lean, rules-driven orchestration system. The main agent now acts as a pure dispatcher — it classifies requests and delegates immediately to specialized subagents rather than performing inline analysis.

---

What Changed

Orchestrator Discipline (HARD LIMITS)

CLAUDE.md and .claude/rules/workflow.md now explicitly prohibit the main agent from reading project source code (app/, resources/, database/, tests/, routes/, config/) before dispatching. A new "Orchestrator Tool Policy" section enumerates allowed tools and forbidden paths. A triage decision tree replaces the vague "evaluate pipeline triggers" instruction — the agent now classifies the request type first, then dispatches, with zero inline exploration.

Agent File Slimming

All 17 subagent definition files were stripped of inline knowledge that belongs in shared rules. Each agent now contains only its behavioral contract and routing metadata; domain knowledge (Eloquent conventions, Inertia patterns, queue idempotency, etc.) lives in the centralized rules files below.

Rules Extracted into Dedicated Files

Five new rule files were added to .claude/rules/ to serve as single sources of truth shared across agents:

File	Content
docker-commands.md	Canonical Docker command reference for all agents
forms-authorization.md	Form Request + Policy patterns
inertia-vue.md	Inertia v2 + Vue 3 conventions
mcp-stack.md	MCP tool usage guide (Laravel Boost, Context7, GitHub, Figma)
migrations-queue.md	Migration conventions and queue job patterns via AsJob

Skills Updated

• Added laravel-actions-patterns — encodes the lorisleiva/laravel-actions pattern used throughout the project.
• Added octane-frankenphp-gotchas — documents Octane/FrankenPHP-specific pitfalls (shared state, singleton lifecycle, Swoole caveats).
• Removed laravel-specialist (with 5 reference files), vue-expert-js, api-design-principles, github-actions-templates, and orphaned database-optimizer references — superseded by agent-level rules or the new shared rule files.

CI/CD Engineer Agent Removed

The ci-cd-engineer agent was removed; its responsibilities are now covered by the existing devops agent, which was updated accordingly.

README Streamlined

Removed outdated plugin installation steps that no longer apply to the current Docker-based setup.

---

Why

The previous setup duplicated knowledge across agent files, CLAUDE.md, and skill files. When one source drifted, agents produced inconsistent output. Centralizing conventions in rules files and enforcing strict orchestrator boundaries means:

• Subagents always work from the same shared context.
• The main agent no longer burns context on codebase reads that specialized agents do better.
• Updates to conventions require a change in one place, not across 17 agent files.