# Claude Code Agents

Custom agents for [Claude Code](https://claude.ai/code) — specialised AI assistants with deep knowledge of specific parts of The Orchard's stack.

This directory contains two things:

- `agents/` — agent definition files (system prompt + tool config)
- `agent-memory/` — persistent knowledge stores that agents load at conversation start

## What are agents?

Claude Code supports custom sub-agents: domain experts that can be invoked automatically or on demand within a conversation. Each agent has its own system prompt, tool access, and embedded knowledge base. They're defined as markdown files with a YAML frontmatter block.

## Available agents

### `graphql-expert`
Deep expertise on The Orchard's 19-service Apollo Federation graph.

Use for:
- Schema analysis and service ownership questions
- Federation troubleshooting and entity resolution
- Query optimisation (N+1, DataLoader patterns)
- Design review for new types, fields, and cross-service relationships
- Neo4j knowledge graph schema and Cypher patterns
- Explicit content feature design (Track + Product)

Has access to: live schema introspection (QA router), Neo4j (via `mcp__music-graph-qa`), codebase search.

### `playlist-pages-expert`
Deep expertise on the Playlist Pages feature across the full stack.

Use for:
- Data flow from Snowflake ingestion through dbt, ows-playlist, GraphQL, to frontend-insights
- Performance Over Time (POT) chart, tracklist, and Details popup
- Spotify vs Apple Music nuances and feature gating
- Priority vs Hourly playlist datasets
- Search integration and playlist list page

Has a pre-built knowledge base in `agent-memory/playlist-pages-expert/` covering:
- Snowflake data model and dbt tier-split architecture
- API endpoints (ows-playlist, graphql-analytics, graphql-knowledge)
- Feature flags (Split.io, per-service)
- Infrastructure (Terraform, Snowflake task graph)
- Frontend component tree (frontend-insights)
- Search implementation
- Changelog of knowledge updates

## Agent memory

Agent memory is a set of markdown files that an agent reads at the start of a conversation. This avoids re-exploring the codebase from scratch each time, giving the agent immediate context on architecture, data models, and known gotchas.

**Location convention**: `claude/agent-memory/<agent-name>/`

**Key files**:
- `MEMORY.md` — index file; always loaded first. Contains a high-level summary and links to topic files.
- Topic files (e.g. `data-model.md`, `api-endpoints.md`) — detailed knowledge on specific areas.

**To update memory**: edit the relevant topic file directly. If you're adding a new topic file, add a pointer to it in `MEMORY.md`.

## Installation

Copy the agents you want to use into your local Claude Code agents directory:

```bash
cp cbeesley/claude/agents/*.md ~/.claude/agents/
```

Or symlink them to keep in sync with this repo:

```bash
ln -s $(pwd)/cbeesley/claude/agents/graphql-expert.md ~/.claude/agents/graphql-expert.md
ln -s $(pwd)/cbeesley/claude/agents/playlist-pages-expert.md ~/.claude/agents/playlist-pages-expert.md
```

To make agent memory available, symlink the memory directory:

```bash
ln -s $(pwd)/cbeesley/claude/agent-memory ~/.claude/agent-memory
```

Agents look for their memory files at `~/.claude/agent-memory/<agent-name>/`.

## Usage

Once installed, Claude Code will automatically invoke the relevant agent when your question matches its domain. You can also invoke explicitly:

```
use the graphql-expert agent to check the LabelSoundRecording federation key
```

## Contributing

Add your own agents under your personal folder (e.g. `yourname/claude/agents/`). Each agent is a single markdown file — frontmatter defines the name, description, tools, and model; the body is the system prompt with embedded knowledge.

```markdown
---
name: my-agent
description: One sentence description — used by Claude to decide when to invoke this agent.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Your system prompt and knowledge base here.
```

The `description` field is the most important — Claude Code uses it to decide when to route questions to your agent.

Optionally, add a `claude/agent-memory/<agent-name>/` directory alongside your agent definition to pre-load domain knowledge. Start with a `MEMORY.md` index and add topic files as the knowledge base grows.