agent/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 the advanced in-house Claude Code plugin for the Host UK federated monorepo. The public version lives at `core-claude`.

This repository contains:
- Claude Code hooks, commands, and automation scripts
- Data collection skills for archiving OSS project data across platforms (since 2019)

## Repository Structure

```
core-agent/
└── claude/
    ├── hooks/                 # Claude Code hooks
    │   ├── hooks.json         # Hook definitions
    │   └── prefer-core.sh     # PreToolUse: block dangerous commands
    ├── scripts/               # Automation scripts
    │   ├── pre-compact.sh     # Save state before compaction
    │   ├── session-start.sh   # Restore context on startup
    │   ├── php-format.sh      # Auto-format PHP after edits
    │   ├── go-format.sh       # Auto-format Go after edits
    │   └── check-debug.sh     # Warn about debug statements
    ├── commands/
    │   └── remember.md        # /core:remember command
    ├── collection/            # Data collection event hooks
    │   ├── hooks.json         # Collection hook registration
    │   ├── dispatch.sh        # Hook dispatcher
    │   └── *.sh               # Event handlers
    └── skills/                # Data collection skills
        ├── ledger-papers/     # Whitepaper archive (91+ papers)
        ├── project-archaeology/ # Dead project excavation
        ├── bitcointalk/       # BitcoinTalk thread collection
        ├── coinmarketcap/     # Market data collection
        ├── github-history/    # Git history preservation
        └── ...                # Other collectors
```

## Claude Plugin Features

### Hooks

| Hook | File | Purpose |
|------|------|---------|
| PreToolUse | `prefer-core.sh` | Block destructive commands, enforce `core` CLI |
| PostToolUse | `php-format.sh` | Auto-format PHP files after edits |
| PostToolUse | `go-format.sh` | Auto-format Go files after edits |
| 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 Commands

The plugin blocks these patterns to prevent accidental damage:

- `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)
- `grep -l | ...` (mass file targeting)
- Raw `go` commands (use `core go *`)
- Raw `php artisan` / `composer test` (use `core php *`)

### Commands

- `/core:remember <fact>` - Save context that persists across compaction

### Context Preservation

State is saved to `~/.claude/sessions/` before compaction:
- Working directory and branch
- Git status (modified files)
- In-progress todos
- User-saved context facts

## Data Collection Skills

### ledger-papers

Archive of 91+ distributed ledger whitepapers across 15 categories (genesis, cryptonote, MRL, privacy, smart-contracts, etc).

```bash
./discover.sh --all              # List all papers
./discover.sh --category=privacy # Filter by category
```

### project-archaeology

Excavates abandoned CryptoNote projects before data is lost.

```bash
./excavate.sh masari             # Full dig
./excavate.sh masari --scan-only # Check what's accessible
```

### Other collectors

- `bitcointalk/` - BitcoinTalk thread archival
- `coinmarketcap/` - Historical price data
- `github-history/` - Repository history preservation
- `wallet-releases/` - Binary release archival
- `block-explorer/` - Blockchain data indexing

## Development

### Testing hooks locally

```bash
# Simulate PreToolUse hook input
echo '{"tool_input": {"command": "rm -rf /"}}' | bash ./claude/hooks/prefer-core.sh
```

### Adding new hooks

1. Add script to `claude/scripts/`
2. Register in `claude/hooks/hooks.json`
3. Test with simulated input

### Collection skill structure

Each skill follows this pattern:

```
claude/skills/<name>/
├── SKILL.md           # Documentation
├── discover.sh        # Job generator (outputs URL|FILENAME|TYPE|METADATA)
├── process.sh         # Job processor (optional)
└── registry.json      # Data registry (optional)
```

## 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

## Integration with Host UK

This plugin is designed for use across the Host UK federated monorepo. It enforces the `core` CLI for multi-repo operations instead of raw git/go/php commands. See the parent `/Users/snider/Code/host-uk/CLAUDE.md` for full monorepo documentation.