ham

# HAM

Use this skill to apply the file-based HAM workflow from this repo in Codex. Work through `CLAUDE.md`, scoped `CLAUDE.md` files, `.memory/*`, and `.ham/*`. Do not introduce MCP-based behavior into this skill.

Current HAM skill version: `2026.02.28`

## Pro Guard

Before any HAM command, check for Pro signals:

- `.ham/config.json` with `"pro": true`
- `enabledImporters` with more than `"claude"`
- any `**/AGENTS.md` files

If Pro is detected:

- allow `go ham` in Pro-aware mode
- allow `ham remove` because it has its own removal logic
- for all other HAM commands, print `HAM Pro detected — this project is managed by HAM Pro. Manage at goham.dev` and stop

Never create, modify, or delete `AGENTS.md` files from this skill.

## Commands

### ham commands / ham help

List the supported HAM workflows and what each one does:

- `go ham`: set up HAM and detect project structure
- `ham remove`: remove HAM safely while preserving Pro-owned files
- `ham update`: run `bash <skill-dir>/scripts/update.sh` and update `.ham/version`
- `ham status`: show version, update status, memory file count, and last setup signal
- `ham route`: add or update `## Context Routing` in root `CLAUDE.md`
- `ham dashboard`: launch the dashboard on port 7777
- `HAM savings`: show token and cost savings
- `ham carbon`: run the carbon report
- `ham insights`: generate actionable inbox items from session data
- `ham benchmark`: compare baseline and HAM performance
- `ham baseline start`: begin baseline capture
- `ham baseline stop`: stop baseline capture early
- `ham metrics clear`: clear benchmark data after confirmation
- `ham audit`: check memory system health

### go ham

0. Compare `.ham/version` to `2026.02.28`. If outdated, print an update notice. Never block setup.
1. Detect platform signals:
   - `*.xcodeproj` or `Package.swift`: iOS
   - `build.gradle*`: Android
   - `pubspec.yaml`: Flutter
   - `package.json` with framework hints: Web or React Native
   - `pyproject.toml` or `requirements.txt`: Python
   - `Cargo.toml`: Rust
   - `go.mod`: Go
2. Detect maturity:
   - 0-2 code directories: greenfield
   - 3+ code directories: brownfield
3. For large repos, apply a monorepo guard:
   - if there are more than 20 candidate code directories, present a sorted list
   - pre-select the top 15 most likely directories
   - let the user adjust when needed
   - never create more than 20 scoped `CLAUDE.md` files
4. Generate files silently, then confirm what was created.

Pro-aware mode:

- if Pro is detected, skip directories that already have `CLAUDE.md`
- fill gaps only
- never touch `AGENTS.md`

Generated structure:

```text
project/
├── CLAUDE.md
├── .ham/
│   ├── version
│   └── metrics/state.json
├── .memory/
│   ├── decisions.md
│   ├── patterns.md
│   ├── inbox.md
│   └── audit-log.md
└── [major code dirs]/CLAUDE.md
```

Greenfield: create root files only.
Brownfield: also create scoped `CLAUDE.md` files in major code areas.

Append the HAM block to `.gitignore` if missing:

```text
# HAM - AI agent scaffolding (local, do not commit)
.ham/
.memory/
**/CLAUDE.md
!CLAUDE.md
# end HAM
```

Before creating files, capture `.memory/baseline.json`:

```json
{"captured_at":"YYYY-MM-DD","existing_claude_md":{"found":true,"chars":4820,"tokens":1205},"notes":"Migrated from monolithic CLAUDE.md"}
```

If no existing root `CLAUDE.md` exists:

```json
{"captured_at":"YYYY-MM-DD","existing_claude_md":{"found":false},"estimated_baseline_tokens":7500}
```

Create `.ham/metrics/state.json` with baseline mode enabled:

```json
{"mode":"baseline","tasks_completed":0,"tasks_target":10,"started_at":"ISO-8601","memory_reads":0,"total_prompts":0}
```

The next 10 non-trivial tasks should log to baseline mode without HAM memory loading. Auto-transition to active after 10 completed tasks.

If root `CLAUDE.md` is over 3,000 tokens, warn that it is oversized, list sections that should probably move into scoped `CLAUDE.md` files, and offer migration guidance one section at a time.

### Operating Instructions

Embed these ideas in the generated root `CLAUDE.md`:

- read root `CLAUDE.md` before work
- read the target directory `CLAUDE.md` before changes
- if root `CLAUDE.md` has `## Context Routing`, use it to find the right scoped file
- check `.memory/decisions.md` before architectural changes
- check `.memory/patterns.md` before implementing common functionality
- check if audit is due: if 14 or more days or 10 or more sessions have passed since the last audit in `.memory/audit-log.md`, suggest running one
- create `CLAUDE.md` in new directories when they need distinct guidance
- update relevant memory files after work
- keep uncertain inferences in `.memory/inbox.md`
- never record secrets or user data
- never overwrite historical decisions; mark them superseded

### ham route

1. Find all scoped `CLAUDE.md` files excluding the root file.
2. Build a `## Context Routing` section in root `CLAUDE.md`.
3. Add or update entries without deleting unrelated user-written content.

### ham status

Report:

- installed version from `.ham/version` if present
- whether root HAM files exist
- scoped memory file count
- last setup signal if discoverable
- whether baseline tracking is active
- whether an update appears available

### ham audit

Check:

- root `CLAUDE.md` size
- oversized scoped `CLAUDE.md` files
- missing scoped memory in major code directories
- `.memory/` entry counts
- unreviewed inbox items

Append a short result to `.memory/audit-log.md`.

### HAM savings / HAM stats

Read `.memory/baseline.json`, estimate token load from all `CLAUDE.md` and `.memory/*.md` files, and compare baseline versus current HAM setup. If no baseline exists, show raw counts and tell the user savings percentage requires a real baseline.

Use this calculation model:

```python
root_tokens = count_tokens(read("CLAUDE.md"))
subdir_files = glob("**/CLAUDE.md", exclude="root")
avg_subdir = sum(count_tokens(read(f)) for f in subdir_files) / len(subdir_files) if sub