gitea-mcp/CLAUDE.md

Project context

Identity

• Name: gitea-mcp
• Owner: Mathias
• Client: personal
• Repo: https://git.d-ma.be/mathias/gitea-mcp
• Status: active

Stack

• Primary language: Go
• UI layer: HTMX + Templ (when applicable)
• Fallback languages: Python, TypeScript (justify in PR if used)
• Build: Task (taskfile.dev), not Make
• Containers: Docker (compose for dev, k3s for deploy)
• Target infra: koala (GPU workloads), iguana (services), flamingo (edge)

Conventions

Code style

• Go: follow golines, gofumpt, golangci-lint with project config
• Tests: table-driven, in _test.go next to source, testify for assertions
• Errors: wrap with fmt.Errorf("operation: %w", err), no naked returns
• Naming: stdlib conventions, no stuttering (http.Client not http.HTTPClient)

Architecture preferences

• Prefer standard library over frameworks (net/http over gin/echo)
• Dependency injection via constructor functions, not containers
• Configuration via environment variables, parsed at startup into a typed struct
• Structured logging via slog

Git

• Conventional commits: feat:, fix:, chore:, docs:, refactor:
• Trunk-Based Development: one logical change per commit, merged to main by PR (main is protected, see below).
• Run task check locally before every push. CI is the quality gate, not branch protection.
• Short-lived branches and PRs are how work reaches main here (tbd_ship/pr_merge); no long-lived feature branches.
• Exception: if a parallel agent session is active on this repo, use a short-lived agent/<description> branch and merge within the same session.

Security

• No secrets in code, ever — use env vars or SOPS-encrypted files
• Client data never leaves local network unless explicitly cleared
• Dependencies: audit with govulncheck before adding

Knowledge base access

This project can query the shared knowledge base via MCP or HTTP:

• MCP endpoint: mcp://localhost:3100/knowledge
• HTTP fallback: http://localhost:3100/api/v1/search
• Scoping: queries are filtered to collection personal + public

Behavior rules

These rules apply to every task in this project, regardless of harness.

1. No assumptions. Don't hide confusion — surface it. Surface tradeoffs explicitly. Think before coding; if the problem is unclear, ask or state assumptions before acting.
2. Minimum viable code. Solve with the smallest change that works. Nothing speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
3. Surgical changes. Touch only what the task requires. Leave unrelated code, files, and formatting alone. Diffs should be small and reviewable.
4. Goal-driven execution. Define clear success criteria up front for every task. Loop — implement, verify, refine — until those criteria are met. Don't claim completion without evidence (tests pass, command output, observed behavior).

Agent instructions

When acting as a coding agent on this project:

1. Read this file and all SKILL.md files in .skills/ before starting work
2. Run task check before committing (lint + test + vet)
3. If unsure about a convention, check DECISIONS.md or ask
4. Never modify files outside the project root without explicit permission
5. When adding a dependency, explain why in the commit message
6. Ship by PR (main is protected, see below). Run task check before every push. Never create long-lived feature branches.
7. For client projects: never send code or context to cloud APIs — use local models via LiteLLM

Current state — v0.2.5 (2026-05-17)

All v0.2 work is complete and deployed. No active sprint.

What shipped

Tag	PR	Tools / fixes
v0.2.2	#21	repo_create, repo_update, repo_mirror_push
v0.2.3	#22	repo_tree, repo_topics_update, file_read dir fix
v0.2.4	#23	issue_get, release_create, repo_delete
v0.2.5	#26	repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix

Current main: e31fd3f. CI green. Deployed via Flux.

Next up

1. hyperguild new-project v1 — primary next target. See brain node adr-new-project-gitea-first-github-mirror for full flow spec.

2. Issue #19 — end-to-end mirror flow verification. repo_mirror_push is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.

main is protected: ship by PR (local-dev#42, decided 2026-10-08)

Gitea refuses direct pushes to main in this repo, and a PR merges only after its CI status (CD / Lint / Test / Vet (pull_request)) passes. Why: local-dev rule 5's reviewed lane (risk/medium+ is reviewed by a human) was enforced on the merge tools (tbd_ship, pr_merge: gitea-mcp v0.17.0/v0.18.0, merge only for an issue labelled exactly risk/low with green CI) but not on a direct commit to main, which bypassed it. This overrides rule 5's "risk/low commits straight to main" for this repo; control code is where the lane matters. How: tbd_ship for a one-file change, or branch -> PR -> pr_merge (name the risk/low issue); above risk/low open the PR and a human merges it in the Gitea UI after review. Tags are not protected. CD jobs push image tags to the infra repo with deploy keys, never to this repo's main. Undo (Mathias only): Settings -> Branches, or PATCH /repos/mathias/gitea-mcp/branch_protections/main {"enable_push": true}.