CLAUDE.md git:20260625.c996d95A

Immutable. This exact content is served forever at /api/v1/blob/6d52669a2f5ff99a.

@AGENTS.md

## Claude Code

This is the Claude Code bridge file. All portable project guidance lives in
`AGENTS.md` (imported above). Add **only** genuinely Claude-Code-specific notes
below — if a note applies to any agent, it belongs in `AGENTS.md` instead. (A CI
lint enforces that this file's first line is `@AGENTS.md` and that `AGENTS.md`
stays tool-agnostic.)

### Loading & invocation

- Plugins are surfaced via `.claude/` symlinks; restart Claude Code to reload after editing
  `plugins/*/`. Changes are distributed via the Claude Code plugin marketplace.
- Invoke skills with the slash prefix: `/plugin-name:skill-name` (e.g. `/catalyst-dev:create-plan`).

### Orchestration runtime

- Phase-agent workers run as `claude --bg` jobs; the legacy oneshot mode runs a long-lived
  `claude -p /catalyst-legacy:oneshot` per ticket.

### Code understanding (Serena MCP)

Serena is wired into the research/analysis agents for semantic code retrieval — see
`AGENTS.md` → "Code Understanding (Serena)" for what it is and how it's used. Register it
once per machine as a **user-scope** MCP (the absolute `serena` path lets restricted-`PATH`
`claude --bg` phase-agent workers launch it; the headless flags keep it browser-free on servers):

```bash
uv tool install -p 3.13 serena-agent
claude mcp add --scope user serena -- "$HOME/.local/bin/serena" start-mcp-server \
  --context claude-code --enable-web-dashboard False --enable-gui-log-window False
```

It connects with no startup project and activates lazily, so a fresh session connects fast and pays
the language-server startup cost only when an agent first calls `activate_project`.

### Always-loaded reference docs

`@`-imports are a Claude Code feature and load the file in full at session start (they do **not**
reduce context), so keep this list minimal. Architecture is the one doc worth keeping always-on;
ADRs and the release process are referenced by path in `AGENTS.md` for on-demand reading.

@docs/architecture.md