# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Subagents

Use subagents (the Agent tool) when a task genuinely benefits from one — and match the model to the
work:

- **Reach for a subagent** for broad, read-heavy fan-out that would otherwise flood the main context:
  sweeping many files across services, tracing a change through multiple components, or researching
  where/how something is wired. Prefer `Explore` (read-only search) or `general-purpose` for these.
  Use `Plan` to design a multi-step implementation before editing. Keep narrow, single-file edits and
  quick lookups on the main thread — spawning a cold agent for those costs more than it saves.
- **Assign the model to the task.** Route heavy reasoning — architecture decisions, contract/protocol
  changes, security-sensitive work (auth, secrets, credential handling) — to a stronger model (Opus).
  Route routine, well-scoped mechanical work — bulk search, boilerplate, simple refactors,
  running/reporting tests — to a faster, cheaper model (Sonnet or Haiku). State the model explicitly
  when spawning rather than defaulting.

## Git & Gitea access

- **All commits and pushes use the `wtclaude` bot identity, authenticated with the token at
  `C:\Users\colby\.gitea_token_claude`.** Do not use the human user's git credentials. Configure the
  remote (or a one-off push) to carry the token and set the author/committer to `wtclaude`, e.g.:

  ```bash
  TOKEN=$(cat /c/Users/colby/.gitea_token_claude)
  git -c http.extraHeader="Authorization: token $TOKEN" \
      -c user.name=wtclaude -c user.email=claude@whitlocktech.net \
      push origin <branch>
  ```

  Keep the token out of committed files, remote URLs, and command output/logs (pass it via
  `http.extraHeader` or a credential helper, never inline in the `origin` URL).
- **Use the Gitea MCP tools (`mcp__gitea__*`) for all server-side Gitea operations** — opening and
  reviewing pull requests, issues, releases, branches, labels, and reading repo contents. Prefer the
  MCP over shelling out to `git`/`gh`/`tea` or the raw REST API for these. Reserve local `git` for
  working-tree operations (commit, push, branch checkout) using the token above.
- **Sync `main` before you start coding.** Before creating any new branch, switch to `main` and pull
  so the local copy matches the remote (branches are always cut from an up-to-date `main`, never a
  stale one):

  ```bash
  TOKEN=$(cat /c/Users/colby/.gitea_token_claude)
  git checkout main
  git -c http.extraHeader="Authorization: token $TOKEN" pull --ff-only origin main
  git checkout -b <type>/<branch>
  ```

  If the working tree has uncommitted changes that block the checkout/pull, stop and surface it
  rather than discarding them.

## SonarQube (code quality / security scanning)

- **SonarQube is at `https://sonar.whitlocktech.com`.** The API token lives in a local file in
  `SONAR_TOKEN=squ_…` (KEY=value) format — extract the value after `=`. Read it at call time, and
  keep it out of committed files, remote URLs, and command output/logs. **Authenticate with HTTP
  Basic auth (token as username, empty password) — `-u "$TOKEN:"`; the `Authorization: Bearer` header
  returns 401 on this instance.** Example:

  ```bash
  TOKEN=$(grep -oP '(?<=SONAR_TOKEN=).*' /path/to/sonar_token.txt)
  curl -s -u "$TOKEN:" \
    "https://sonar.whitlocktech.com/api/issues/search?componentKeys=<projectKey>&types=VULNERABILITY"
  ```

- **Project key(s):** _fill in once the Sonar project(s) for this repo are created._

## Conventions

- **Conventional Commits** (`type(scope): summary`, e.g. `feat(gateway): add token vault`).
- **AI-assisted contributions must be disclosed** (org policy): tick the PR-template box naming the
  tool, and mark AI-authored commits with a trailer such as `Co-Authored-By: Claude <noreply@anthropic.com>`.
  Undisclosed AI-generated contributions may be closed. See `CONTRIBUTING.md`.
- Branch from `main` (`feature/…`, `fix/…`, `docs/…`, `chore/…`).
- **All architectural and design decisions must be asked and approved by the org lead (Colby
  Whitlock) before implementation. You must ask before writing code.**