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

```bash
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:

```php
// 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:

```php
$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)