plugins/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this 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.

Plugins

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

Or install all via marketplace:

claude plugin add host-uk/core-agent

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.md
└── .gitignore

Plugin Commands

code

• /code:remember <fact> - Save context that persists across compaction
• /code:yes <task> - Auto-approve mode with commit requirement

review

• /review:review [range] - Code review on staged changes or commits

verify

• /verify:verify [--quick|--full] - Verify work is complete

qa

• /qa:qa - Iterative QA fix loop (runs until all checks pass)
• /qa:fix <issue> - Fix a specific QA issue

ci

• /ci:ci [status|run|logs|fix] - CI status and management
• /ci:workflow <type> - Generate GitHub Actions workflows

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

Key Commands

# 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

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

echo '{"tool_input": {"command": "rm -rf /"}}' | bash ./claude/code/hooks/prefer-core.sh

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