CLAUDE.md git:20261009.a775151A

Immutable. This exact content never changes and is served at /api/v1/blob/7700b3b37a3a46c7.

# nutmeg

A Claude Code plugin for football data analytics. 11 skills (3 entry points + 8 sub-skills), 3 agents, powered by the football-docs MCP server.

## Architecture: progressive disclosure

Users interact through **three entry points**. Sub-skills are dispatched automatically or invoked directly by power users.

| Layer | Skills | How invoked |
|-------|--------|-------------|
| **Entry** | `/nutmeg` (router) | User describes any football analytics task — routes automatically |
| **Teaching** | `/nutmeg:learn` | Concepts, resources, provider docs, learning paths |
| **Research** | `/nutmeg:research` | Analysis to publish or decide on: question card, plan with reasons, claim ledger |
| **Sub-skills** | `acquire`, `wrangle`, `compute`, `analyse`, `brainstorm`, `store`, `review`, `heal` | Auto-dispatched by router, or directly by power users |

## Structure

```
skills/
  nutmeg/          # Router — single entry point, handles init + dispatch
  learn/           # Teaching + provider documentation (merged from old providers/)
  research/        # Research projects: question, plan with reasons, claim ledger
  acquire/         # Fetch data + credential management (merged from old credentials/)
  analyse/         # Explore and interpret data
  brainstorm/      # Visualisation ideation with research + style options
    references/    # chart-canon.md (conventions), viz-styles.md (4 aesthetic styles)
  compute/         # Derived metrics (xG, PPDA, xT, etc.)
  heal/            # Fix broken scrapers
  review/          # Dispatch data-reviewer + chart-reviewer agents
  store/           # Storage format and publishing
  wrangle/         # Transform, filter, reshape data

core/              # nutmeg command (stdlib Python >= 3.10): ledger, projects, redaction
  nutmeg.py        # Entry point: python3 "${CLAUDE_PLUGIN_ROOT}/core/nutmeg.py" <command>
  nutmeg_core/     # Package; tests in core/tests (python3 -m pytest core/tests)

agents/            # Specialised sub-agents
  data-reviewer.md       # Reviews data code (coordinates, xG, filtering, sample sizes)
  chart-reviewer.md      # Reviews chart code (3 modes: code, visual, interactive)
  pipeline-builder.md    # Designs end-to-end data pipelines

docs/
  accuracy-guardrail.md  # Shared guardrail: always use search_docs, never guess from training
  metric-misuse.md       # Stat-misuse checks (Worville's ten commandments), used by analyse
  understanding.md       # Explainers, the teach-back before publish, outcome steering
  entity-resolution-routing.md  # Reep lookup, joins and routing

hooks/             # SessionStart hook: injects the core football-data and research-project rules every session
evals/             # claude plugin eval suite + football-docs replay mock (see README "Evals")

.mcp.json          # Declares football-docs MCP server dependency
```

## Key conventions

- Every provider-touching skill includes the accuracy guardrail section
- Skills and agents reference plugin files as `${CLAUDE_PLUGIN_ROOT}/...` (a bare `docs/...` path resolves against the user's project, not the plugin)
- Plugin MCP tools are named `mcp__plugin_nutmeg_football-docs__<tool>`; frontmatter tool lists carry that name and the standalone `mcp__football-docs__<tool>`
- Skills and agents do not hard-code provider facts; they look them up with `search_docs` and name the source
- Run the eval suite before a release and compare with the previous version
- Skills use `search_docs` from the football-docs MCP server for all provider-specific facts
- Entity-resolution tasks route through `docs/entity-resolution-routing.md`:
  provider facts in `football-docs`, public ID lookup through Reep Register,
  reusable matching guidance in `reep-toolkit`, and private matching logic pack
  material only when the user has access
- User profile lives at `.nutmeg.user.md` (created by `/nutmeg` on first run)
- Skills adapt to user's language (Python/R/JS), experience level, and available data sources
- Reference docs in skills/brainstorm/references/ are loaded on-demand, not all upfront
- The router mentions sub-skill names during dispatch so users learn the vocabulary naturally

## Related projects

**football-docs** (npm: `football-docs`, repo: `withqwerty/football-docs`)
- MCP server providing searchable documentation for football data providers
  and identity surfaces
- Connected via `.mcp.json` — starts automatically when the plugin loads
- Skills query it via `mcp__football-docs__search_docs`, `list_providers`, `compare_providers`

**nutmeg-site** (local: `../nutmeg-site`)
- Marketing/landing page for the plugin, built with Astro 6 (static output)
- Components: Hero, SkillsGrid, ProvidersGrid, ExampleQueries, InstallRow, etc.

**plugins** (repo: `withqwerty/plugins`, local: `../plugins`)
- Plugin marketplace listing — nutmeg is registered here for discovery via `/plugin marketplace`