core/agent
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: refresh marketplace and mcp docs

Browse source 
Summary:\n- updated README and CLAUDE docs for unified marketplace structure\n- documented shared MCP server tools and ethics kernel\n- added updated repo tree covering claude, codex, google, and mcp
This commit is contained in:
Snider 2026-02-05 20:48:31 +00:00
parent a8424ee8c4
commit d01c71d665
2 changed files with 166 additions and 213 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

206
CLAUDE.md
View file

@ -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 <fact>` - Save context that persists across compaction
- `/code:yes <task>` - 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 <issue>` - 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 <type>` - 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/<name>/.claude-plugin/plugin.json`
2. Add commands to `claude/<name>/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/<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
- 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

173
README.md
View file

@ -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 <issue>` - Fix a specific issue
- `/qa:check` - Check without fixing
### ci
CI/CD integration:
- `/ci:ci` - Check CI status
- `/ci:workflow <type>` - Generate GitHub Actions workflow
- `/ci:fix` - Analyse and fix failing CI
## Development
### Adding a new plugin
1. Create `claude/<name>/.claude-plugin/plugin.json`
2. Add commands to `claude/<name>/commands/`
3. Add hooks to `claude/<name>/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