diff --git a/CLAUDE.md b/CLAUDE.md index 697aca4..49f4f87 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,86 +1,103 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +This file guides Claude Code when working inside the Host UK core-agent repository. ## Overview -**core-agent** is a monorepo of Claude Code plugins for the Host UK federated monorepo. It contains multiple focused plugins that can be installed individually or together. +**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. -## Plugins +## Marketplace -| Plugin | Description | Install | -|--------|-------------|---------| -| **code** | Core development - hooks, scripts, data collection | `claude plugin add host-uk/core-agent/claude/code` | -| **review** | Code review automation | `claude plugin add host-uk/core-agent/claude/review` | -| **verify** | Work verification | `claude plugin add host-uk/core-agent/claude/verify` | -| **qa** | Quality assurance loops | `claude plugin add host-uk/core-agent/claude/qa` | -| **ci** | CI/CD integration | `claude plugin add host-uk/core-agent/claude/ci` | +Install everything via the unified marketplace: -Or install all via 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/ -│ └── marketplace.json # Plugin registry (enables auto-updates) -├── claude/ -│ ├── code/ # Core development plugin -│ │ ├── .claude-plugin/ -│ │ │ └── plugin.json -│ │ ├── hooks.json -│ │ ├── hooks/ -│ │ ├── scripts/ -│ │ ├── commands/ # /code:remember, /code:yes -│ │ ├── skills/ # Data collection skills -│ │ └── collection/ # Collection event hooks -│ ├── review/ # Code review plugin -│ │ ├── .claude-plugin/ -│ │ │ └── plugin.json -│ │ └── commands/ # /review:review -│ ├── verify/ # Verification plugin -│ │ ├── .claude-plugin/ -│ │ │ └── plugin.json -│ │ └── commands/ # /verify:verify -│ ├── qa/ # QA plugin -│ │ ├── .claude-plugin/ -│ │ │ └── plugin.json -│ │ ├── scripts/ -│ │ └── commands/ # /qa:qa, /qa:fix -│ └── ci/ # CI plugin -│ ├── .claude-plugin/ -│ │ └── plugin.json -│ └── commands/ # /ci:ci, /ci:workflow +├── .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 -└── .gitignore +└── README.md ``` -## Plugin Commands +## Plugin Suites -### code -- `/code:remember ` - Save context that persists across compaction -- `/code:yes ` - Auto-approve mode with commit requirement +Claude plugins: -### review -- `/review:review [range]` - Code review on staged changes or commits +- `claude/api` +- `claude/ci` +- `claude/code` +- `claude/collect` +- `claude/coolify` +- `claude/core` +- `claude/issue` +- `claude/perf` +- `claude/qa` +- `claude/review` +- `claude/verify` -### verify -- `/verify:verify [--quick|--full]` - Verify work is complete +Codex plugins: -### qa -- `/qa:qa` - Iterative QA fix loop (runs until all checks pass) -- `/qa:fix ` - Fix a specific QA issue +- `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` -### ci -- `/ci:ci [status|run|logs|fix]` - CI status and management -- `/ci:workflow ` - Generate GitHub Actions workflows +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. +Always use `core` CLI instead of raw commands. The `core` binary handles the full E2E development lifecycle for Go and PHP ecosystems. ### Command Mappings @@ -94,82 +111,23 @@ core-agent/ | `./vendor/bin/pint` | `core php fmt` | | `./vendor/bin/phpstan` | `core php stan` | -### Key Commands - -```bash -# Development -core dev health # Status across repos -core dev work # Full workflow: status → commit → push - -# Go -core go test # Run tests -core go qa # Full QA pipeline - -# PHP -core php test # Run Pest tests -core php qa # Full QA pipeline - -# Building -core build # Auto-detect and build - -# AI -core ai task # Auto-select a task -core ai task:pr # Create PR for task -``` - -## code Plugin Features - -### Hooks - -| Hook | File | Purpose | -|------|------|---------| -| PreToolUse | `prefer-core.sh` | Block dangerous commands, enforce `core` CLI | -| PostToolUse | `php-format.sh` | Auto-format PHP | -| PostToolUse | `go-format.sh` | Auto-format Go | -| PostToolUse | `check-debug.sh` | Warn about debug statements | -| PreCompact | `pre-compact.sh` | Save state before compaction | -| SessionStart | `session-start.sh` | Restore context on startup | - -### Blocked Patterns - -**Destructive operations:** -- `rm -rf` / `rm -r` (except node_modules, vendor, .cache) -- `mv`/`cp` with wildcards -- `xargs` with rm/mv/cp -- `find -exec` with file operations -- `sed -i` (in-place editing) - -**Raw commands (use core instead):** -- `go test/build/fmt/mod` → `core go *` -- `composer test` → `core php test` - -### Data Collection Skills - -| Skill | Purpose | -|-------|---------| -| `ledger-papers/` | 91+ distributed ledger whitepapers | -| `project-archaeology/` | Dead project excavation | -| `bitcointalk/` | Forum thread archival | -| `coinmarketcap/` | Historical price data | -| `github-history/` | Repository history preservation | - ## Development -### Adding a new plugin +Adding a new Claude plugin: 1. Create `claude//.claude-plugin/plugin.json` 2. Add commands to `claude//commands/` 3. Register in `.claude-plugin/marketplace.json` -### Testing hooks locally +Adding a new Codex plugin: -```bash -echo '{"tool_input": {"command": "rm -rf /"}}' | bash ./claude/code/hooks/prefer-core.sh -``` +1. Create `codex//.codex-plugin/plugin.json` +2. Add commands to `codex//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 +- 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 diff --git a/README.md b/README.md index 836946b..ae41804 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,107 @@ # core-agent -A monorepo of [Claude Code](https://claude.ai/code) plugins for the Host UK federated monorepo. +A unified marketplace of Host UK plugins for Claude Code, Codex, and the Gemini CLI. This repo hosts the Claude and Codex suites alongside a shared MCP server and the Axioms of Life ethics kernel. -## Plugins +## Marketplace -| Plugin | Description | Commands | -|--------|-------------|----------| -| **[code](./claude/code)** | Core development - hooks, scripts, data collection | `/code:remember`, `/code:yes` | -| **[review](./claude/review)** | Code review automation | `/review:review`, `/review:security`, `/review:pr` | -| **[verify](./claude/verify)** | Work verification before commit/push | `/verify:verify`, `/verify:ready` | -| **[qa](./claude/qa)** | Quality assurance fix loops | `/qa:qa`, `/qa:fix`, `/qa:check` | -| **[ci](./claude/ci)** | CI/CD integration | `/ci:ci`, `/ci:workflow`, `/ci:fix` | +The public marketplace manifest lives at `core-agent/.claude-plugin/marketplace.json` and lists all Claude, Codex, and Gemini entries. ## Installation +Claude Code: + ```bash -# Install all plugins via marketplace +# Install everything via marketplace claude plugin add host-uk/core-agent -# Or install individual plugins +# Or install specific Claude plugins claude plugin add host-uk/core-agent/claude/code claude plugin add host-uk/core-agent/claude/review claude plugin add host-uk/core-agent/claude/qa ``` -## Quick Start +Gemini CLI: + +- Extension lives at `core-agent/google/gemini-cli`. + +Codex: + +- Codex plugins live at `core-agent/codex`. + +## Shared MCP Server + +A vendor-neutral MCP server lives in `core-agent/mcp` and is registered in `.mcp.json` at the repo root. + +Run locally: ```bash -# Code review staged changes -/review:review - -# Run QA and fix all issues -/qa:qa - -# Verify work is ready to commit -/verify:verify - -# Check CI status -/ci:ci +go run ./mcp/ ``` -## Codex +Tools: -Codex awareness lives in `core-agent/codex` and provides guardrails plus core CLI guidance via `AGENTS.md`. +- `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 a first-class feature under `core-agent/codex/ethics`. + +- `core-agent/codex/ethics/MODAL.md` +- `core-agent/codex/ethics/kernel/axioms.json` + +## 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` + +## 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 +``` ## Core CLI Integration @@ -56,62 +115,6 @@ These plugins enforce the `core` CLI for development commands: | `composer test` | `core php test` | | `./vendor/bin/pint` | `core php fmt` | -## Plugin Details - -### code - -The core plugin with hooks and data collection skills: - -- **Hooks**: Auto-format, debug detection, dangerous command blocking -- **Skills**: Data collection for archiving OSS projects (whitepapers, forums, market data) -- **Commands**: `/code:remember` (persist facts), `/code:yes` (auto-approve mode) - -### review - -Code review automation: - -- `/review:review` - Review staged changes or commit range -- `/review:security` - Security-focused review -- `/review:pr [number]` - Review a pull request - -### verify - -Work verification: - -- `/verify:verify` - Full verification (tests, lint, format, debug check) -- `/verify:ready` - Quick check if ready to commit - -### qa - -Quality assurance: - -- `/qa:qa` - Run QA pipeline, fix all issues iteratively -- `/qa:fix ` - Fix a specific issue -- `/qa:check` - Check without fixing - -### ci - -CI/CD integration: - -- `/ci:ci` - Check CI status -- `/ci:workflow ` - Generate GitHub Actions workflow -- `/ci:fix` - Analyse and fix failing CI - -## Development - -### Adding a new plugin - -1. Create `claude//.claude-plugin/plugin.json` -2. Add commands to `claude//commands/` -3. Add hooks to `claude//hooks.json` (optional) -4. Register in `.claude-plugin/marketplace.json` - -### Testing locally - -```bash -claude plugin add /path/to/core-agent -``` - ## License EUPL-1.2 @@ -121,11 +124,3 @@ EUPL-1.2 - [Host UK](https://host.uk.com) - [Claude Code Documentation](https://docs.anthropic.com/claude-code) - [Issues](https://github.com/host-uk/core-agent/issues) - -### api - -The `api` plugin generates a TypeScript/JavaScript API client from your project's Laravel routes. - -- `/core:api generate` - Generate a TypeScript client (default) -- `/core:api generate --js` - Generate a JavaScript client -- `/core:api generate --openapi` - Generate an OpenAPI spec