From 577118f7f2bcfa8bdd7f4a264616920447f40081 Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Wed, 28 Jan 2026 14:02:45 +0000
Subject: [PATCH] docs: update CLAUDE.md to be package-specific

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>
---
 CLAUDE.md | 132 ++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 88 insertions(+), 44 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 138e17b..18e7976 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,66 +1,110 @@
-# Core PHP Framework Project
+# CLAUDE.md
 
-## Architecture
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-Modular monolith using Core PHP Framework. Modules live in `app/Mod/{Name}/Boot.php`.
+## Package Overview
 
-**Event-driven registration:**
-```php
-class Boot
-{
-    public static array $listens = [
-        WebRoutesRegistering::class => 'onWebRoutes',
-        ApiRoutesRegistering::class => 'onApiRoutes',
-        AdminPanelBooting::class => 'onAdminPanel',
-    ];
-}
-```
+`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 dev              # Dev server (if configured)
-php artisan serve             # Laravel dev server
-npm run dev                   # Vite
-./vendor/bin/pint --dirty     # Format changed files
-php artisan test              # All tests
-php artisan make:mod Blog     # Create module
+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
 ```
 
-## Module Structure
+## Architecture
 
-```
-app/Mod/Blog/
-├── Boot.php              # Event listeners
-├── Models/               # Eloquent models
-├── Routes/
-│   ├── web.php          # Web routes
-│   └── api.php          # API routes
-├── Views/               # Blade templates
-├── Livewire/            # Livewire components
-├── Migrations/          # Database migrations
-└── Tests/               # Module tests
+### 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',
+];
 ```
 
-## Packages
+### MCP Tools Structure
+Tools live in `Mcp/Tools/Agent/` organised by domain:
 
-| Package | Purpose |
-|---------|---------|
-| `host-uk/core` | Core framework, events, module discovery |
-| `host-uk/core-admin` | Admin panel, Livewire modals |
-| `host-uk/core-api` | REST API, scopes, rate limiting, webhooks |
-| `host-uk/core-mcp` | Model Context Protocol for AI agents |
+| 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
-- Livewire + Flux Pro for UI
+
+## 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
 
-- `Core\` namespace and vendor packages: EUPL-1.2 (copyleft)
-- `app/Mod/*`, `app/Website/*`: Your choice (no copyleft)
-
-See LICENSE for full details.
+EUPL-1.2 (European Union Public Licence)
\ No newline at end of file