577118f7f2
Rewrite CLAUDE.md from generic Core PHP Framework template to reflect actual core-agentic package: MCP tools, AI provider system, models, and package structure. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
110 lines
No EOL
3.8 KiB
Markdown
110 lines
No EOL
3.8 KiB
Markdown
# 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) |