php-agentic/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Package Overview

host-uk/core-agentic is a Laravel package providing AI agent orchestration, MCP (Model Context Protocol) tools, and multi-agent collaboration support. Namespace: Core\Mod\Agentic\.

Commands

composer run lint             # Format with Laravel Pint
composer run test             # Run tests with Pest
./vendor/bin/pest --filter=AgentPlan  # Run specific test

# CLI tools (when installed in a host application)
php artisan plan:create my-feature --title="Feature X"
php artisan plan:list --status=active
php artisan plan:show my-plan --markdown
php artisan plan:check my-plan
php artisan agentic:generate batch-001

Architecture

Boot System (Event-Driven)

Package registers via Laravel service provider with event-driven lazy loading:

// Boot.php - responds to Core framework events
public static array $listens = [
    AdminPanelBooting::class => 'onAdminPanel',
    ConsoleBooting::class => 'onConsole',
    McpToolsRegistering::class => 'onMcpTools',
];

MCP Tools Structure

Tools live in Mcp/Tools/Agent/ organised by domain:

Directory	Tools
Plan/	PlanCreate, PlanGet, PlanList, PlanUpdateStatus, PlanArchive
Phase/	PhaseGet, PhaseUpdateStatus, PhaseAddCheckpoint
Session/	SessionStart, SessionEnd, SessionLog, SessionHandoff, SessionResume
State/	StateGet, StateSet, StateList
Task/	TaskUpdate, TaskToggle
Content/	ContentGenerate, ContentBatchGenerate, ContentBriefCreate
Template/	TemplateList, TemplatePreview, TemplateCreatePlan

All tools extend AgentTool base class which provides:

• Input validation helpers (requireString, optionalInt, requireEnum)
• Circuit breaker protection via withCircuitBreaker()
• Standardised response format (success(), error())

AI Provider System

AgenticManager provides unified access to AI providers:

$ai = app(AgenticManager::class);
$ai->claude()->generate($prompt);  // Anthropic Claude
$ai->gemini()->generate($prompt);  // Google Gemini
$ai->openai()->generate($prompt);  // OpenAI
$ai->provider('gemini')->generate($prompt);  // By name

Key Models

Model	Purpose
AgentPlan	Work plans with phases and status tracking
AgentPhase	Plan phases with tasks and checkpoints
AgentSession	Agent execution sessions with handoff support
WorkspaceState	Key-value state shared between agents
AgentApiKey	API key management with IP whitelisting

Conventions

• UK English (colour, organisation, centre)
• declare(strict_types=1); in all PHP files
• Type hints on all parameters and return types
• PSR-12 coding style (Laravel Pint)
• Pest for testing

Package Structure

├── Boot.php                 # Service provider + event listeners
├── Mcp/
│   ├── Tools/Agent/         # MCP tool implementations
│   ├── Prompts/             # MCP prompt definitions
│   └── Servers/             # MCP server configurations
├── Models/                  # Eloquent models
├── Services/                # Business logic services
├── Middleware/              # API authentication
├── View/
│   ├── Blade/admin/         # Admin panel views
│   └── Modal/Admin/         # Livewire components
├── Jobs/                    # Queue jobs for async work
├── Console/Commands/        # Artisan commands
└── Tests/                   # Pest test suites

Dependencies

Requires host-uk/core which provides the event system and MCP infrastructure.

License

EUPL-1.2 (European Union Public Licence)