wtclaude
7fdde56560
Tracks the two files that were sitting untracked in the working tree: the original Agentic Bridle MCP design doc, and CLAUDE.md carrying the repo's git/Gitea, SonarQube, and contribution conventions. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019RZerbsHGF9Ka3bKhCjJ9m
79 lines
4.1 KiB
Markdown
79 lines
4.1 KiB
Markdown
# 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.**
|