# claude-foundations

Shared infrastructure for Claude Code sessions: hooks, formatters, best practices, and the knowledge distillation pipeline.

## Repository Structure

```
claude-foundations/
  formatters/              # Canonical formatter scripts (one per extension)
    py                     # ruff format + ruff check
    sh                     # shfmt + shellcheck
    ts                     # biome format + biome check
    js -> ts               # symlink (biome handles both)
    sql                    # sqlfluff fix + sqlfluff lint
    json                   # prettier
    yaml -> json           # symlink (prettier auto-detects)
    md -> json             # symlink
  hooks/
    post-edit-lint.sh      # PostToolUse: auto-format/lint on Edit/Write
    pre-commit-lint.sh     # Git pre-commit: lint staged files
    pre-compact-backup.sh  # PreCompact: backup transcript before compaction
  scripts/
    install-hooks.sh       # Symlink hooks into ~/.claude/hooks/
    setup-formatters.sh    # Set up formatters for a project
  best-practices/          # Generalised best practices (one file per topic)
  memory/                  # Session logs and reflections
  settings.yaml            # Knowledge pipeline configuration
  CLAUDE.md                # Global project guidelines (symlinked to ~/dev/claude/)
  HOOKS.md                 # Hook documentation
  TODO.md                  # Improvement backlog
```

## Quick Start

### 1. Install hooks (one-time)

```bash
cd ~/dev/claude/projects/claude-foundations
scripts/install-hooks.sh
```

This symlinks all hooks into `~/.claude/hooks/` and prints the `settings.json` config to add. The PostToolUse hook is what triggers auto-formatting on every Edit/Write.

### 2. Opt a project into auto-formatting

```bash
scripts/setup-formatters.sh ~/dev/claude/projects/<project-name> <ext> [<ext> ...]
```

For example, to enable Python and shell formatting for `cluster-bootstrap`:

```bash
scripts/setup-formatters.sh ~/dev/claude/projects/cluster-bootstrap py sh
```

This creates a `formatters/` directory in the target project with symlinks back to the canonical formatter scripts here. It also installs a git pre-commit hook if one doesn't exist.

**Available formatters:** `py`, `sh`, `ts`, `js`, `sql`, `json`, `yaml`, `md`

Run with no arguments to see the full list:

```bash
scripts/setup-formatters.sh
```

### 3. Install required tools

Each formatter gracefully skips if its tool isn't installed, but for full functionality:

| Formatter | Tools needed | Install |
|-----------|-------------|---------|
| `py` | ruff | `pip install ruff` or `pipx install ruff` |
| `sh` | shfmt, shellcheck | `sudo apt install shfmt shellcheck` |
| `ts`/`js` | biome | `npm i -g @biomejs/biome` |
| `sql` | sqlfluff | `pip install sqlfluff` |
| `json`/`yaml`/`md` | prettier | `npm i -g prettier` |

### 4. Add per-project config (optional)

Formatters respect project-level config files:

| Formatter | Config file | Purpose |
|-----------|------------|---------|
| `py` | `pyproject.toml` | ruff rules, line length, target Python version |
| `sh` | `.editorconfig` | shfmt indent style, binary ops, switch cases |
| `ts`/`js` | `biome.json` | biome rules, formatting options |
| `sql` | `.sqlfluff` | SQL dialect, rules |
| `json`/`yaml`/`md` | `.prettierrc` | prettier options |

Without config files, tools use their defaults.

### 5. Verify setup

Use the `/linter` skill inside a Claude Code session:

```
/linter
```

This scans the project, shows which formatters are active, which tools are installed, and suggests fixes for any gaps.

## How It Works

### PostToolUse hook (auto-format on edit)

When Claude edits or writes a file:

1. The `post-edit-lint.sh` hook fires
2. It walks up from the working directory to find `formatters/`
3. If a formatter exists for the file's extension, it:
   - Creates a checkpoint (git blob hash stored in `.pre-lint`)
   - Runs the formatter (format in place + lint)
   - On clean pass: removes checkpoint, exits silently
   - On lint errors: keeps checkpoint, exits with errors shown to Claude

### Pre-commit hook (lint on commit)

When you `git commit`, the `pre-commit-lint.sh` hook:

1. Finds staged files with matching formatters
2. Runs each formatter
3. Re-stages formatted files
4. Blocks the commit if lint errors remain

### Reverting after lint

If you don't like what the formatter did:

```bash
git cat-file blob "$(cat <file>.pre-lint)" > <file>
rm <file>.pre-lint
```

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/install-hooks.sh` | Symlink all hooks to `~/.claude/hooks/` and print settings.json config |
| `scripts/setup-formatters.sh` | Create formatter symlinks in a target project |