AI Development System Documentation

Core Components

1. Base AI Agent (Claude Sonnet 4.5)

Main orchestrator with 40+ tools for file operations, code search, testing, and git. Routes tasks to specialized agents and spawns multiple agents in parallel for complex features.

2. Specialized Sub-Agent System

15+ domain-expert agents with deep expertise in specific technologies. Agents run autonomously and work in parallel for maximum efficiency.

3. MCP (Model Context Protocol) Servers

Laravel Boost provides version-specific tools:

Database: Schema inspection, read-only SQL queries
Development: Artisan commands, PHP Tinker debugging
Documentation: Semantic search for Laravel 11, Passport v12, Lighthouse v6, etc.
Introspection: Package versions, config values, routes, environment variables
Debugging: Error logs (backend & browser), exception details

4. Project Intelligence Layer

CLAUDE.md: Tech stack definitions, coding conventions, agent routing rules, and project-specific constraints

Beads: Distributed task tracking with persistent memory across sessions (bd ready, bd create, bd close, bd update)

Git Integration: Automatic status awareness, standardized commits, PR management

The Specialized Agent Network

Backend Specialists

@laravel-backend-expert - Controllers, services, middleware, authentication, API endpoints, queue jobs

Laravel 11 on L10 structure, Passport OAuth2, Horizon queues, Reverb WebSockets
Enforces: final classes, explicit return types, idempotent jobs, docker-prefixed commands

@laravel-eloquent-expert - Database schemas, migrations, models, query optimization, relationships

Complex relationships, N+1 prevention, eager loading, factories/seeders
Project rules: NO foreign keys, use dateTime not timestamps(), explicit return types

@api-architect - GraphQL schema design, API contracts, subscription patterns, versioning

Lighthouse GraphQL, WebSocket patterns, resource modeling
Designs specifications that other agents implement

Frontend Specialists

@react-component-architect - Components, hooks, state management, UI architecture

React 18+ patterns, WebSocket subscriptions, Vite bundling, component composition

@typescript-pro - TypeScript migration, advanced types, type safety, .d.ts files

Advanced type system, generic constraints, conditional types, strict typing

@vitest-expert - React component tests, frontend unit tests

Vitest patterns, component coverage, mocking strategies, test organization

Quality & Performance

@code-reviewer ⚠️ REQUIRED BEFORE MERGE

Security vulnerabilities, performance issues, coding standards, bug detection
Runs automatically before all PR merges (configured in CLAUDE.md)

@performance-optimizer - Query tuning, N+1 detection, caching, Redis optimization

Bottleneck identification, workload profiling, query optimization, Horizon tuning
Use before traffic spikes or when slowness is reported

Meta-Agents

@tech-lead-orchestrator - Complex multi-step tasks, feature planning, architectural decisions

@code-archaeologist - Exploring unfamiliar/legacy codebases, pre-refactor analysis

@documentation-specialist - READMEs, API docs, architecture guides (only when requested)

@team-configurator - Project setup, tech stack detection, agent team configuration

Workflow Orchestration Examples

Complex Full-Stack Feature

User: "Build real-time workflow status dashboard"
  ↓
@tech-lead-orchestrator (planning phase)
  - Analyzes requirements, creates 8-step plan, user approves
  ↓
PARALLEL (Phase 1: Design & Data):
  @api-architect                          @laravel-eloquent-expert
    - Designs GraphQL subscription          - Creates WorkflowStatus model
    - WebSocket event contracts             - Optimizes queries, prevents N+1
    - Documents permissions                 - Creates factory & seeder
  ↓
SEQUENTIAL (Phase 2: Implementation):
  @laravel-backend-expert → @react-component-architect → @typescript-pro → @vitest-expert
  ↓
PARALLEL (Phase 3: Optimization & Review):
  @performance-optimizer                  @code-reviewer
    - Reviews query performance             - Security audit
    - Adds caching                          - Authentication review
    - Optimizes subscriptions               - Race condition checks
  ↓
All tests pass → PR created

GraphQL API Development

User: "Add filtering and pagination to workflow queries"
  ↓
@api-architect → Designs schema, input types, permissions
  ↓
@laravel-backend-expert → Implements resolvers with Lighthouse directives
  ↓
@laravel-eloquent-expert → Optimizes queries, adds indexes, prevents N+1
  ↓
@code-reviewer → Verifies authorization, SQL injection checks, performance

Tool Integration & Capabilities

Laravel Boost MCP Server

Intelligent Documentation Search

User: "How do I rate limit API routes in Laravel 11?"
  ↓
search-docs → Laravel 11.0 + Passport v12 specific documentation
  ↓
Agent implements correctly first try, no version incompatibilities

Live Application Debugging

User: "Why is my workflow query slow?"
  ↓
database-query: EXPLAIN shows full table scan on 50k records
  ↓
tinker: Tests optimized version with ->with(['nodes', 'actions'])
  ↓
@laravel-eloquent-expert: Creates index, refactors with eager loading
  ↓
database-query: Confirms 95% speed improvement (2.3s → 0.12s)

Development Velocity Tools

TodoWrite: Real-Time Task Tracking

User: "Implement user dashboard with metrics"
  ↓
Agent creates todo list with live progress updates:
  ☑ Create UserMetrics model and migration
  🔄 Building metrics calculation service  ← Currently here
  ☐ Create dashboard API endpoint
  ☐ Build React dashboard component

Beads: Persistent Memory System

bd ready                    # Find next work
bd create "Bug" -t bug      # Create discovered issues
bd dep add <id> <parent>    # Link dependencies
bd close <id> --reason "Done" # Complete with rationale

Work persists across sessions with zero context loss.

Parallel Agent Execution

User: "Add authentication to the API"
  ↓
Main agent spawns 3 agents simultaneously:
  @laravel-backend-expert → Passport OAuth2, middleware, route protection
  @react-component-architect → Login/register forms, token management
  @vitest-expert → Auth flow tests
  ↓
Results merge automatically → 3x faster than sequential

Key Advantages

1. Domain Expertise at Scale

Traditional AI: Generic programming knowledge, no framework-specific patterns

This System: Agents know Laravel 11 conventions, React 18+ patterns, prevent N+1 queries automatically, follow project rules (no foreign keys, final classes)

// Traditional AI generates:
class WorkflowController {
    public function index() { return Workflow::all(); }
}

// @laravel-backend-expert generates:
final class WorkflowController extends Controller
{
    public function index(): JsonResponse
    {
        return response()->json(
            WorkflowResource::collection(
                Workflow::query()->with(['nodes', 'actions'])->get()
            )
        );
    }
}

2. Enforced Quality Gates

@code-reviewer automatically spawned before every merge. Reviews security (SQL injection, XSS, CSRF), performance (N+1, indexes), code style (return types, final classes). No human reviewer needed for routine checks.

3. Version-Specific Intelligence

Laravel Boost knows: Laravel 11.0, Passport v12, Lighthouse v6, Horizon v5, Telescope v5. Prevents deprecated APIs, outdated tutorials, incompatible packages.

4. Parallel Execution

Sequential: Migration (2m) → Model (3m) → API (5m) → Frontend (8m) → Tests (6m) = 24 minutes

Parallel: All agents work simultaneously = 8 minutes (3x faster)

5. Persistent Context

Beads tracks work across sessions. Agent remembers completed tasks, architectural decisions, and what's left to do. No re-explanation needed.

6. Self-Correcting Workflows

Agent creates migration → runs it → database-schema verifies → detects mismatch → corrects and re-runs → verifies again → guarantees correctness

Configuration in Action

CLAUDE.md Routing Rules

User Request → @laravel-backend-expert
  ├─ Database changes? → @laravel-eloquent-expert
  ├─ GraphQL schema? → @api-architect → @laravel-backend-expert
  └─ Before merge → @code-reviewer

Example: User requests "Add workflow retry mechanism"

Main agent reads CLAUDE.md, matches "Queue/Job design"
Spawns @laravel-backend-expert
Agent needs database → auto-spawns @laravel-eloquent-expert
Both collaborate → Eloquent creates table, Backend implements logic
Auto-spawns @code-reviewer → verifies idempotency

No manual orchestration. CLAUDE.md defines the flow.

Project-Specific Constraints

// Agent CANNOT generate (violates constraints):
$table->foreignId('workflow_id')->constrained(); // ❌ No foreign keys
$table->timestamps(); // ❌ Must use dateTime
class WorkflowService { } // ❌ Must be final
public function process($workflow) { } // ❌ No return type

// Agent WILL generate (follows constraints):
$table->unsignedBigInteger('workflow_id'); // ✓
$table->dateTime('created_at'); // ✓
final class WorkflowService { } // ✓
public function process(Workflow $w): WorkflowResult { } // ✓

Real-World Example: GraphQL Code Generation

Files Modified:

M graphql/Apps/workflow.graphql
M resources/js/vite/apps/Goldilocks/codegen.ts
M resources/js/vite/utilities/types/*.ts

Workflow:

User: "Add type-safe GraphQL queries for workflow automation"
  ↓
@api-architect → Designs schema, filtering, pagination, permissions
  ↓
@laravel-backend-expert → Implements resolvers, @can directives, subscriptions
  ↓
@typescript-pro → Configures GraphQL Code Generator, generates types/hooks
  ↓
@react-component-architect → Updates components with generated types
  ↓
@code-reviewer → Verifies type safety, unused fragments, optimization
  ↓
Result: Fully type-safe GraphQL with zero runtime type errors

All coordination automatic via CLAUDE.md routing rules.

Comparison: Traditional vs Multi-Agent

Scenario: Add user activity tracking

Traditional Single-Model AI:

Generates code with project violations (timestamps(), non-final classes, no return types)
N+1 queries, outdated Laravel syntax, no types, no tests
Developer spends 30 min fixing + writing tests + manual code review
Total: 2 hours

Multi-Agent System:

Agents spawn in parallel, each enforces project rules
Creates migration with dateTime ✓, final classes ✓, explicit types ✓, prevents N+1 ✓, Laravel 11 syntax ✓, TypeScript types ✓, tests ✓
@code-reviewer runs automatically
Total: 15 minutes (8x faster, zero violations, automatic quality gate)

Summary

Traditional AI Coding

❌ Single model, generic solutions, no quality enforcement, sequential only, no memory, guesses conventions, outdated docs, no verification

This Multi-Agent System

✅ Domain Experts: Laravel 11 not generic PHP, React 18+ patterns, advanced TypeScript

✅ Project-Specific Rules: No foreign keys, final classes with return types, idempotent jobs—impossible to violate

✅ Mandatory Code Review: @code-reviewer runs automatically—security, performance, style checks

✅ Parallel Execution: Database + API + Frontend work simultaneously (3-5x faster)

✅ Persistent Memory: Beads tracks work across sessions, zero context loss

✅ Live Debugging: Run queries, execute Tinker, read logs, check config via MCP servers

✅ Version-Specific Docs: Laravel 11.0, Passport v12, no outdated tutorials

✅ Self-Correcting: Agents verify changes, auto-fix issues, guarantee correctness

The Bottom Line

Virtual engineering team where:

Each "developer" is a world-class domain expert
They follow your project's conventions perfectly (via CLAUDE.md)
They work 24/7 in parallel
They have X-ray vision into your application (via Laravel Boost MCP)
They never forget context (via Beads)
They self-review and self-correct

Result: 5-10x development velocity with production-quality code.

ninetwentyfour/claude.md