laravel-architect

Overview

The laravel-architect is the central decision-making agent in Laravel Agent. When you use /build, this agent analyzes your request, determines the optimal implementation strategy, enforces architectural constraints, and delegates work to specialized builder agents.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                     User Request                            │
│              "/build Invoice management"                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   laravel-architect                         │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 1. Analyze request scope and complexity             │   │
│  │ 2. Check existing codebase patterns                 │   │
│  │ 3. Decide implementation approach                   │   │
│  │ 4. Enforce 5-pattern limit per request              │   │
│  │ 5. Delegate to appropriate builder(s)              │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
           ┌──────────────────┼──────────────────┐
           ▼                  ▼                  ▼
    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
    │  feature-   │    │   module-   │    │  service-   │
    │  builder    │    │   builder   │    │  builder    │
    └─────────────┘    └─────────────┘    └─────────────┘

Responsibilities

Request Analysis - Understands what you're trying to build
Pattern Selection - Chooses appropriate design patterns (max 5)
Codebase Awareness - Checks existing code to avoid duplication
SOLID Enforcement - Ensures code follows SOLID principles
DRY Compliance - Prevents code duplication across the project
Delegation - Routes work to the right specialized builder

Decision Process

When the architect receives a request, it follows this decision tree:

Request Type	Delegates To	Example
Complete feature (CRUD, views, etc.)	`laravel-feature-builder`	"Build invoice management"
Reusable domain module	`laravel-module-builder`	"Create a payment gateway module"
Service or action class	`laravel-service-builder`	"Create PDF generation service"
REST API endpoint	`laravel-api-builder`	"Build products API v1"
Database optimization	`laravel-database`	"Optimize slow queries"
Livewire component	`laravel-livewire`	"Build data table component"
Filament admin resource	`laravel-filament`	"Create user management panel"

Pattern Limit

To prevent over-engineering, the architect enforces a 5-pattern limit per request. This means:

Maximum 5 design patterns in a single implementation
Simpler solutions are preferred over complex ones
Each pattern must justify its inclusion

Use /laravel-agent:patterns to see current pattern usage.

Codebase Analysis

Before delegating, the architect scans your codebase for:

Existing services - Reuse instead of duplicate
Naming conventions - Match your project's style
Directory structure - Follow established patterns
Related code - Identify integration points

Example Decision

# User request
/build Invoice management with PDF export and email notifications

# Architect analysis
→ Request type: Complete feature
→ Components needed: Model, Controller, Views, Service, Notification
→ Patterns selected: Repository (data access), Service (business logic),
                      Observer (events), Factory (test data)
→ Pattern count: 4/5 ✓
→ Delegating to: laravel-feature-builder

Builder Agents

The architect delegates to these specialized builders:

laravel-feature-builder - Complete features with CRUD
laravel-module-builder - Reusable domain modules
laravel-service-builder - Services and actions
laravel-api-builder - REST API resources

Invoked By

/laravel-agent:build - Main entry point

7-Phase Development Protocol

The architect follows a structured approach for every request:

Discovery - Parse request, identify keywords, map dependencies
Exploration - Scan codebase structure, patterns, related code
Questions - Gather missing info (only if confidence < 80%)
Architecture - Design solution, create blueprint
Implementation - Delegate to specialized builders
Review - Validate with parallel reviewers
Summary - Provide actionable completion report

Package-Aware Architecture

The architect detects installed packages and adapts its approach:

Package	Adaptation
`nwidart/laravel-modules`	Uses nwidart module structure instead of app/Modules/
`lorisleiva/laravel-actions`	Uses AsAction pattern for single-purpose operations
`laravel/octane`	Applies Octane-safe practices (no static state)
`stancl/tenancy`	Configures multi-tenant isolation
`laravel/cashier`	Integrates Stripe subscription billing

Agent Capability Matrix

Agent	Creates	Delegates To
`laravel-feature-builder`	Feature structure, views, tests	laravel-api-builder
`laravel-module-builder`	Module structure, contracts	-
`laravel-service-builder`	Services, actions, DTOs	-
`laravel-api-builder`	API controllers, resources, routes	-
`laravel-filament`	Admin resources, pages	laravel-auth

Guardrails

The architect enforces strict boundaries:

NEVER edit .env, .git/*, or CI/CD configs
NEVER add patterns beyond the 5 limit without approval
NEVER create god classes or methods >20 lines
NEVER skip tests
NEVER accept tenant IDs from user input
ALWAYS check existing conventions first

Error Recovery

If an agent fails mid-execution:

Check state - Identify created/modified files
Rollback - Use git checkout -- . to restore
Resume - Run agent with --continue flag