agent/CLAUDE.md

# CLAUDE.md

This file guides Claude Code when working inside the Host UK core-agent repository.

## Overview

**core-agent** is a unified marketplace hosting Claude and Codex plugin suites plus the Gemini CLI extension. A shared MCP server powers marketplace discovery and ethics checks across tools.

## Marketplace

Install everything via the unified marketplace:

```bash
claude plugin add host-uk/core-agent
```

Install a specific Claude plugin:

```bash
claude plugin add host-uk/core-agent/claude/code
```

The marketplace manifest lives at `core-agent/.claude-plugin/marketplace.json`.

## Shared MCP Server

The vendor-neutral MCP server is registered in `core-agent/.mcp.json` and runs via stdio:

```bash
go run ./mcp/
```

Tools exposed:

- `marketplace_list` — returns the full marketplace registry as structured data
- `marketplace_plugin_info` — returns plugin metadata, commands, and skills by name
- `core_cli` — runs approved `core` CLI commands (`dev`, `go`, `php`, `build` only)
- `ethics_check` — returns the ethics modal and axioms kernel

## Ethics Kernel

The Axioms of Life ethics kernel is first-class and lives at:

- `core-agent/codex/ethics/MODAL.md`
- `core-agent/codex/ethics/kernel/axioms.json`

## Repository Structure

```
core-agent/
├── .claude-plugin/           # Unified marketplace manifest
├── .mcp.json                  # MCP server registry
├── claude/                    # Claude plugin suite
├── codex/                     # Codex plugin suite + ethics kernel
├── google/                    # Gemini CLI extension
├── mcp/                       # Shared MCP stdio server
├── CLAUDE.md
└── README.md
```

## Plugin Suites

Claude plugins:

- `claude/api`
- `claude/ci`
- `claude/code`
- `claude/collect`
- `claude/coolify`
- `claude/core`
- `claude/issue`
- `claude/perf`
- `claude/qa`
- `claude/review`
- `claude/verify`

Codex plugins:

- `codex/awareness`
- `codex/ethics`
- `codex/guardrails`
- `codex/api`
- `codex/ci`
- `codex/code`
- `codex/collect`
- `codex/coolify`
- `codex/core`
- `codex/issue`
- `codex/perf`
- `codex/qa`
- `codex/review`
- `codex/verify`

Gemini extension:

- `google/gemini-cli`

## Core CLI Philosophy

Always use `core` CLI instead of raw commands. The `core` binary handles the full E2E development lifecycle for Go and PHP ecosystems.

### Command Mappings

| Instead of... | Use... |
|---------------|--------|
| `go test` | `core go test` |
| `go build` | `core build` |
| `go fmt` | `core go fmt` |
| `golangci-lint` | `core go lint` |
| `composer test` | `core php test` |
| `./vendor/bin/pint` | `core php fmt` |
| `./vendor/bin/phpstan` | `core php stan` |

## Development

Adding a new Claude plugin:

1. Create `claude/<name>/.claude-plugin/plugin.json`
2. Add commands to `claude/<name>/commands/`
3. Register in `.claude-plugin/marketplace.json`

Adding a new Codex plugin:

1. Create `codex/<name>/.codex-plugin/plugin.json`
2. Add commands to `codex/<name>/commands/`
3. Register in `.claude-plugin/marketplace.json`

## Coding Standards

- UK English: colour, organisation, centre
- Shell scripts: use `#!/bin/bash`, read JSON with `jq`
- Hook output: JSON with `decision` (approve/block) and optional `message`
- License: EUPL-1.2 CIC