[sync] agent: 58 commits from Forge

.claude-plugin/marketplace.json

@@ -7,22 +7,10 @@
   },
   "plugins": [
     {
-      "name": "code",
-      "source": "./claude/code",
-      "description": "Core development hooks, auto-approve workflow, and research data collection",
-      "version": "0.2.0"
-    },
-    {
-      "name": "review",
-      "source": "./claude/review",
-      "description": "Code review automation - PR review, security checks",
-      "version": "0.2.0"
-    },
-    {
-      "name": "verify",
-      "source": "./claude/verify",
-      "description": "Work verification - ensure tests pass, no debug statements",
-      "version": "0.1.0"
+      "name": "core",
+      "source": "./claude/core",
+      "description": "Core agent platform — dispatch (local + remote), verify+merge, CodeRabbit/Codex review queue, GitHub mirror, cross-agent messaging, OpenBrain integration",
+      "version": "0.10.0"
     },
     {
       "name": "core-php",

.gitignore

@@ -1,2 +1,8 @@
 .idea/
 .core/
+docker/.env
+ui/node_modules
+# Compiled binaries
+core-agent
+mcp
+*.exe

.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "core": {
+      "type": "stdio",
+      "command": "core-agent",
+      "args": ["mcp"]
+    }
+  }
+}

CLAUDE.md

@@ -1,163 +1,138 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to Claude Code when working with code in this repository.
 
-## Overview
+## Session Context
 
-**core-agent** is a polyglot monorepo (Go + PHP) for AI agent orchestration. The Go side handles agent-side execution, CLI commands, and autonomous agent loops. The PHP side (Laravel package `lthn/agent`) provides the backend API, persistent storage, multi-provider AI services, and admin panel. They communicate via REST API.
+Running on **Claude Max20 plan** with **1M context window** (Opus 4.6).
 
-The repo also contains Claude Code plugins (5), Codex plugins (13), a Gemini CLI extension, and two MCP servers.
+## Overview
 
-## Core CLI — Always Use It
+**core-agent** is the AI agent orchestration platform for the Core ecosystem. Single Go binary (`core-agent`) that runs as an MCP server — either via stdio (Claude Code integration) or HTTP daemon (cross-agent communication).
 
-**Never use raw `go`, `php`, or `composer` commands.** The `core` CLI wraps both toolchains and is enforced by PreToolUse hooks that will block violations.
+**Module:** `forge.lthn.ai/core/agent`
 
-| Instead of... | Use... |
-|---------------|--------|
-| `go test` | `core go test` |
-| `go build` | `core build` |
-| `go fmt` | `core go fmt` |
-| `go vet` | `core go vet` |
-| `golangci-lint` | `core go lint` |
-| `composer test` / `./vendor/bin/pest` | `core php test` |
-| `./vendor/bin/pint` / `composer lint` | `core php fmt` |
-| `./vendor/bin/phpstan` | `core php stan` |
-| `php artisan serve` | `core php dev` |
+## Build & Test
 
-## Build & Test Commands
+```bash
+go build ./...                        # Build all packages
+go build ./cmd/core-agent/            # Build the binary
+go test ./... -count=1 -timeout 60s   # Run tests
+go vet ./...                          # Vet
+go install ./cmd/core-agent/          # Install to $GOPATH/bin
+```
 
+Cross-compile for Charon (Linux):
 ```bash
-# Go
-core go test                                        # Run all Go tests
-core go test --run TestMemoryRegistry_Register_Good # Run single test
-core go qa                                          # Full QA: fmt + vet + lint + test
-core go qa full                                     # QA + race detector + vuln scan
-core go cov                                         # Test coverage
-core build                                          # Verify Go packages compile
-
-# PHP
-core php test                                       # Run Pest suite
-core php test --filter=AgenticManagerTest            # Run specific test file
-core php fmt                                        # Format (Laravel Pint)
-core php stan                                       # Static analysis (PHPStan)
-core php qa                                         # Full PHP QA pipeline
-
-# MCP servers (standalone builds)
-cd cmd/mcp && go build -o agent-mcp .               # Stdio MCP server
-cd google/mcp && go build -o google-mcp .           # HTTP MCP server (port 8080)
-
-# Workspace
-make setup                                          # Full bootstrap (deps + core + clone repos)
-core dev health                                     # Status across repos
+GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o core-agent-linux ./cmd/core-agent/
 ```
 
 ## Architecture
 
 ```
-                Forgejo
-                  |
-         [ForgejoSource polls]
-                  |
-                  v
-+-- Go: jobrunner Poller --+      +-- PHP: Laravel Backend --+
-| ForgejoSource            |      | AgentApiController       |
-| DispatchHandler ---------|----->| /v1/plans                |
-| CompletionHandler        |      | /v1/sessions             |
-| ResolveThreadsHandler    |      | /v1/plans/*/phases       |
-+--------------------------+      +-------------+------------+
-                                                |
-                                        [Eloquent models]
-                                        AgentPlan, AgentPhase,
-                                        AgentSession, BrainMemory
+cmd/core-agent/main.go          Entry point (mcp + serve commands)
+pkg/agentic/                     MCP tools — dispatch, verify, remote, mirror, review queue
+pkg/brain/                       OpenBrain — recall, remember, messaging
+pkg/monitor/                     Background monitoring + repo sync
+pkg/prompts/                     Embedded templates + personas (go:embed)
 ```
 
-### Go Packages (`pkg/`)
+### Binary Modes
 
-- **`lifecycle/`** — Core domain layer. Task, AgentInfo, Plan, Phase, Session types. Agent registry (Memory/SQLite/Redis backends), task router (capability matching + load scoring), allowance system (quota enforcement), dispatcher (orchestrates dispatch with exponential backoff), event system, brain (vector store), context (git integration).
-- **`loop/`** — Autonomous agent reasoning engine. Prompt-parse-execute cycle against any `inference.TextModel` with tool calling and streaming.
-- **`orchestrator/`** — Clotho protocol for dual-run verification and agent orchestration.
-- **`jobrunner/`** — Poll-dispatch engine for agent-side work execution. Polls Forgejo for work items, executes phases, reports results.
+- `core-agent mcp` — stdio MCP server for Claude Code
+- `core-agent serve` — HTTP daemon (Charon, CI, cross-agent). PID file, health check, registry.
 
-### Go Commands (`cmd/`)
+### MCP Tools (33)
 
-- **`tasks/`** — `core ai tasks`, `core ai task [id]` — task management
-- **`agent/`** — `core ai agent` — agent machine management (add, list, status, fleet)
-- **`dispatch/`** — `core ai dispatch` — work queue processor (watch, run)
-- **`workspace/`** — `core workspace task`, `core workspace agent` — git worktree isolation
-- **`mcp/`** — Standalone stdio MCP server exposing `marketplace_list`, `marketplace_plugin_info`, `core_cli`, `ethics_check`
+| Category | Tools |
+|----------|-------|
+| Dispatch | `agentic_dispatch`, `agentic_dispatch_remote`, `agentic_status`, `agentic_status_remote` |
+| Workspace | `agentic_prep_workspace`, `agentic_resume`, `agentic_watch` |
+| PR/Review | `agentic_create_pr`, `agentic_list_prs`, `agentic_create_epic`, `agentic_review_queue` |
+| Mirror | `agentic_mirror` (Forge → GitHub sync) |
+| Scan | `agentic_scan` (Forge issues) |
+| Brain | `brain_recall`, `brain_remember`, `brain_forget` |
+| Messaging | `agent_send`, `agent_inbox`, `agent_conversation` |
+| Plans | `agentic_plan_create`, `agentic_plan_read`, `agentic_plan_update`, `agentic_plan_delete`, `agentic_plan_list` |
+| Files | `file_read`, `file_write`, `file_edit`, `file_delete`, `file_rename`, `file_exists`, `dir_list`, `dir_create` |
+| Language | `lang_detect`, `lang_list` |
 
-### PHP (`src/php/`)
+### Agent Types
 
-- **Namespace**: `Core\Mod\Agentic\` (service provider: `Boot`)
-- **Models/** — 19 Eloquent models (AgentPlan, AgentPhase, AgentSession, BrainMemory, Task, Prompt, etc.)
-- **Services/** — AgenticManager (multi-provider: Claude/Gemini/OpenAI), BrainService (Ollama+Qdrant), ForgejoService, AI services with stream parsing and retry traits
-- **Controllers/** — AgentApiController (REST endpoints)
-- **Actions/** — Single-purpose action classes (Brain, Forge, Phase, Plan, Session, Task)
-- **View/** — Livewire admin panel components (Dashboard, Plans, Sessions, ApiKeys, Templates, Playground, etc.)
-- **Mcp/** — MCP tool implementations (Brain, Content, Phase, Plan, Session, State, Task, Template)
-- **Migrations/** — 10 migrations (run automatically on boot)
+| Agent | Command | Use |
+|-------|---------|-----|
+| `claude:opus` | Claude Code | Complex coding, architecture |
+| `claude:sonnet` | Claude Code | Standard tasks |
+| `claude:haiku` | Claude Code | Quick/cheap tasks, discovery |
+| `gemini` | Gemini CLI | Fast batch ops |
+| `codex` | Codex CLI | Autonomous coding |
+| `codex:review` | Codex review | Deep security analysis |
+| `coderabbit` | CodeRabbit CLI | Code quality review |
 
-## Claude Code Plugins (`claude/`)
+### Dispatch Flow
 
-Five plugins installable individually or via marketplace:
+```
+dispatch → agent works → closeout sequence (review → fix → simplify → re-review)
+    → commit → auto PR → inline tests → pass → auto-merge on Forge
+    → push to GitHub → CodeRabbit reviews → merge or dispatch fix agent
+```
 
-| Plugin | Commands |
-|--------|----------|
-| **code** | `/code:remember`, `/code:yes`, `/code:qa` |
-| **review** | `/review:review`, `/review:security`, `/review:pr`, `/review:pipeline` |
-| **verify** | `/verify:verify`, `/verify:ready`, `/verify:tests` |
-| **qa** | `/qa:qa`, `/qa:fix`, `/qa:check`, `/qa:lint` |
-| **ci** | `/ci:ci`, `/ci:workflow`, `/ci:fix`, `/ci:run`, `/ci:status` |
+### Personas (pkg/prompts/lib/personas/)
 
-### Hooks (code plugin)
+116 personas across 16 domains. Path = context, filename = lens.
 
-**PreToolUse**: `prefer-core.sh` blocks destructive operations (`rm -rf`, `sed -i`, `xargs rm`, `find -exec rm`, `grep -l | ...`, `mv/cp *`) and raw go/php commands. `block-docs.sh` prevents random `.md` file creation.
+```
+prompts.Persona("engineering/security-developer")   # code-level security review
+prompts.Persona("smm/security-secops")              # social media incident response
+prompts.Persona("devops/senior")                     # infrastructure architecture
+```
 
-**PostToolUse**: Auto-formats Go (`gofmt`) and PHP (`pint`) after edits. Warns about debug statements (`dd()`, `dump()`, `fmt.Println()`).
+### Templates (pkg/prompts/lib/templates/)
 
-**PreCompact**: Saves session state. **SessionStart**: Restores session context.
+Prompt templates for different task types: `coding`, `conventions`, `security`, `verify`, plus YAML plan templates (`bug-fix`, `code-review`, `new-feature`, `refactor`, etc.)
 
-## Other Directories
+## Key Patterns
 
-- **`codex/`** — 13 Codex plugins mirroring Claude structure plus ethics, guardrails, perf, issue, coolify, awareness
-- **`agents/`** — 13 specialist agent categories (design, engineering, marketing, product, testing, etc.) with example configs and system prompts
-- **`google/gemini-cli/`** — Gemini CLI extension (TypeScript, `npm run build`)
-- **`google/mcp/`** — HTTP MCP server exposing `core_go_test`, `core_dev_health`, `core_dev_commit`
-- **`docs/`** — `architecture.md` (deep dive), `development.md` (comprehensive dev guide), `docs/plans/` (design documents)
-- **`scripts/`** — Environment setup scripts (`install-core.sh`, `install-deps.sh`, `agent-runner.sh`, etc.)
+### Shared Paths (pkg/agentic/paths.go)
 
-## Testing Conventions
+All paths use `CORE_WORKSPACE` env var, fallback `~/Code/.core`:
+- `WorkspaceRoot()` — agent workspaces
+- `CoreRoot()` — ecosystem config
+- `PlansRoot()` — agent plans
+- `AgentName()` — `AGENT_NAME` env or hostname detection
+- `GitHubOrg()` — `GITHUB_ORG` env or "dAppCore"
 
-### Go
+### Error Handling
 
-Uses `testify/assert` and `testify/require`. Name tests with suffixes:
-- `_Good` — happy path
-- `_Bad` — expected error conditions
-- `_Ugly` — panics and edge cases
+`coreerr.E("pkg.Method", "message", err)` from go-log. Always 3 args. NEVER `fmt.Errorf`.
 
-Use `require` for preconditions (stops on failure), `assert` for verifications (reports all failures).
+### File I/O
 
-### PHP
+`coreio.Local.Read/Write/EnsureDir` from go-io. `WriteMode(path, content, 0600)` for sensitive files. NEVER `os.ReadFile/WriteFile`.
 
-Pest with Orchestra Testbench. Feature tests use `RefreshDatabase`. Helpers: `createWorkspace()`, `createApiKey($workspace, ...)`.
+### HTTP Responses
 
-## Coding Standards
+Always check `err != nil` BEFORE accessing `resp.StatusCode`. Split into two checks.
+
+## Plugin (claude/core/)
+
+The Claude Code plugin provides:
+- **MCP server** via `mcp.json` (auto-registers core-agent)
+- **Hooks** via `hooks.json` (PostToolUse inbox notifications, auto-format, debug warnings)
+- **Agents**: `agent-task-code-review`, `agent-task-code-simplifier`
+- **Commands**: dispatch, status, review, recall, remember, scan, etc.
+- **Skills**: security review, architecture review, test analysis, etc.
 
-- **UK English**: colour, organisation, centre, licence, behaviour
-- **Go**: standard `gofmt`, errors via `core.E("scope.Method", "what failed", err)`
-- **PHP**: `declare(strict_types=1)`, full type hints, PSR-12 via Pint, Pest syntax for tests
-- **Shell**: `#!/bin/bash`, JSON input via `jq`, output `{"decision": "approve"|"block", "message": "..."}`
-- **Commits**: conventional — `type(scope): description` (e.g. `feat(lifecycle): add exponential backoff`)
-- **Licence**: EUPL-1.2 CIC
+## Testing Conventions
 
-## Prerequisites
+- `_Good` — happy path
+- `_Bad` — expected error conditions
+- `_Ugly` — panics and edge cases
+- Use `testify/assert` + `testify/require`
 
-| Tool | Version | Purpose |
-|------|---------|---------|
-| Go | 1.26+ | Go packages, CLI, MCP servers |
-| PHP | 8.2+ | Laravel package, Pest tests |
-| Composer | 2.x | PHP dependencies |
-| `core` CLI | latest | Wraps Go/PHP toolchains (enforced by hooks) |
-| `jq` | any | JSON parsing in shell hooks |
+## Coding Standards
 
-Go module is `forge.lthn.ai/core/agent`, participates in a Go workspace (`go.work`) resolving all `forge.lthn.ai/core/*` dependencies locally.
+- **UK English**: colour, organisation, centre, initialise
+- **Commits**: `type(scope): description` with `Co-Authored-By: Virgil <virgil@lethean.io>`
+- **Licence**: EUPL-1.2
+- **SPDX**: `// SPDX-License-Identifier: EUPL-1.2` on every file

CODEX.md

@@ -0,0 +1,56 @@
+# CODEX.md
+
+Instructions for OpenAI Codex when working in the Core ecosystem.
+
+## MCP Tools Available
+
+You have access to core-agent MCP tools. Use them:
+
+- `brain_recall` — Search OpenBrain for context about any package, pattern, or decision
+- `brain_remember` — Store what you learn for other agents (Claude, Gemini, future LEM)
+- `agentic_dispatch` — Dispatch tasks to other agents
+- `agentic_status` — Check agent workspace status
+
+**ALWAYS `brain_remember` significant findings** — your deep analysis of package internals, error patterns, security observations. This builds the shared knowledge base.
+
+## Core Ecosystem Conventions
+
+### Go Packages (forge.lthn.ai/core/*)
+
+- **Error handling**: `coreerr.E("pkg.Method", "what failed", err)` from `go-log`. NEVER `fmt.Errorf` or `errors.New`.
+  - Import as: `coreerr "forge.lthn.ai/core/go-log"`
+  - Always 3 args: operation, message, cause (use `nil` if no cause)
+  - `coreerr.E` returns `*log.Err` which implements `error` and `Unwrap()`
+
+- **File I/O**: `coreio.Local.Read/Write/Delete/EnsureDir` from `go-io`. NEVER `os.ReadFile/WriteFile/MkdirAll`.
+  - Import as: `coreio "forge.lthn.ai/core/go-io"`
+  - Security: go-io validates paths, prevents traversal
+
+- **Process management**: `go-process` for spawning external commands. Supports Timeout, GracePeriod, KillGroup.
+
+- **UK English**: colour, organisation, centre, initialise (never American spellings)
+
+- **Test naming**: `TestFoo_Good` (happy path), `TestFoo_Bad` (expected errors), `TestFoo_Ugly` (panics/edge cases)
+
+- **Commits**: `type(scope): description` with `Co-Authored-By: Virgil <virgil@lethean.io>`
+
+### PHP Packages (CorePHP)
+
+- **Actions pattern**: Single-purpose classes with `use Action` trait, static `::run()` helper
+- **Tenant isolation**: `BelongsToWorkspace` trait on ALL models with tenant data
+- **Strict types**: `declare(strict_types=1)` in every file
+- **Testing**: Pest syntax, not PHPUnit
+
+## Review Focus Areas
+
+When reviewing code, prioritise:
+
+1. **Security**: Path traversal, injection, hardcoded secrets, unsafe input
+2. **Error handling**: coreerr.E() convention compliance
+3. **File I/O**: go-io usage, no raw os.* calls
+4. **Tenant isolation**: BelongsToWorkspace on all tenant models (PHP)
+5. **Test coverage**: Are critical paths tested?
+
+## Training Data
+
+Your reviews generate training data for LEM (our fine-tuned model). Be thorough and structured in your findings — every observation helps improve the next generation of reviews.