Agentic-Bridle/CLAUDE.md

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.:

  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):

  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:

  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.