gitea-mcp/AGENTS.md

# Agent context — Mathias workspace

<!-- Canonical root context for all AI coding agents.
     Lives at: ~/dev/.context/AGENT.md
     Applies to every project under ~/dev/ unless overridden.
     
     Run `task context:sync` from ~/dev/ to regenerate harness-specific files.
     Project-level context in .context/PROJECT.md layers on top of this. -->

## Who I am

I'm Mathias, a digital product manager and technology consultant based in Sweden.
I build software, research emerging tech, and deliver consulting engagements
for clients under NDA. I work across AI/ML, financial automation, web applications,
and climate/sustainability tech.

## How I work with agents

- I think like a product manager — I care about *why* before *how*
- I want agents to be opinionated and push back, not just execute blindly
- I prefer concise responses; skip ceremony and get to the point
- When I say "build this", I mean production-quality with tests, not a demo
- Ask me before making irreversible changes or adding heavy dependencies
- I work with confidential client data — never send it to cloud APIs unless I explicitly say it's OK

## Behavior rules

These rules apply to every task across every 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).

## Default stack

| Layer | Default | Fallback | Last resort |
|-------|---------|----------|-------------|
| Language | Go | Python | TypeScript, Java, C |
| UI | HTMX + Templ | Server-rendered HTML | React (only if SPA is justified) |
| Build | Task (taskfile.dev) | Make | — |
| Containers | Docker Compose (dev), k3s (prod) | — | — |
| DB | PostgreSQL + sqlc | SQLite | — |
| Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — |
| Logging | slog (structured) | — | — |
| Testing | Table-driven, testify | — | — |

Exploratory: Rust, Zig — I'll tell you when I want these.

## Code conventions

- **Go style**: golines, gofumpt, golangci-lint
- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
- **Naming**: stdlib conventions, no stuttering
- **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), one concern per PR, PR describes *why* not *what*
- **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc are pre-approved; anything else needs justification in the commit message

## Infrastructure

Three machines on Tailscale:

| Machine | Role | Key specs |
|---------|------|-----------|
| koala | GPU inference, heavy compute | RTX 5070, runs k3s + llama-swap + shared postgres18/pgvector |
| iguana | Services, builds | M2 Ultra Mac |
| flamingo | Daily driver, edge | Mac mini, ~/dev is here |

- **Model routing**: LiteLLM in front of llama-swap (local) + cloud APIs (when permitted)
- **Orchestration**: k3s cluster across all three machines
- **Networking**: Tailscale mesh

## Project landscape

All development repos live at `~/dev/` (softlink from `~/Documents/local-dev/`).

Organized in thematic folders:

| Folder | Focus | Count |
|--------|-------|-------|
| `GO/` | Go web frameworks, API integrations, learning projects | ~10 |
| `AI/` | ML research, AI frameworks (FinRL, DSPy, crawl4ai) | ~6 |
| `AGENTS/` | Autonomous agents, coding agents, MCP servers, infra | ~15 |
| `QKX/` | Invoice processing, financial automation, payment systems | ~13 |
| `XT/` | Climate data, sustainability (Klimatkollen, Garbo) | ~2 |

See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.

### Key active projects

- **super-koala** (`AGENTS/`) — multi-component agent stack with LangGraph, DSPy, MCP
- **azure-tiger** (`QKX/`) — invoice extraction → ISO 20022 payment instructions
- **gocrwl** (`AGENTS/`) — Go web crawler with containerized deployment
- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
- **klimatkollen** (`XT/`) — Swedish municipal climate data platform

## Knowledge base

When available, agents can query the shared knowledge base:

- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
- **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`

<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
     name once hyperguild is deployed. Until then, agents that try to
     reach the knowledge service on a host where it isn't running will
     get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`

## Client work rules

When working on a project tagged with a client name:
1. Never send code, data, or context to cloud APIs — use local models only
2. Never reference other client projects or their data
3. Keep all artifacts within the client's git org / directory
4. Treat everything as confidential unless told otherwise

## Harness-agnostic principles

This context is designed to work with any AI coding tool:
- Claude Code, Cursor, Aider, Open WebUI, Charmbracelet Mods/Crush
- Pi Coding Agent, Mistral Vibe, Antigravity
- Any tool that accepts a system prompt or reads a markdown context file

The canonical source is always `.context/AGENT.md` (root) and `.context/PROJECT.md` (per-project).
Derived files are committed (see *How context propagates* below) so a `git pull` on any host yields full agent context with no setup.

## How context propagates

Canonical sources of truth:
- Universal: `~/dev/.context/AGENT.md` (this file)
- Project: `<repo>/.context/PROJECT.md` (per-repo)

Derived files (committed, regenerated by `task context:sync`):
- `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.aider.conventions.md`,
  `.context/system-prompt.txt`

Workflow:
1. Edit a canonical file. Run `task context:sync`. Commit canonical and
   derived together. Push.
2. On any other host, `git pull` brings both. Claude Code (tree-walking)
   uses `CLAUDE.md`; Crush / Pi / Antigravity (cwd-only) use `AGENTS.md`;
   Cursor uses `.cursorrules`; Aider uses `.aider.conventions.md`.
3. `task check` runs `context:sync` then asserts `git status --porcelain`
   is empty over the derived files (catches both modified-tracked drift
   and missing-untracked adapters). A drift fails the check with a
   message telling you to stage the regenerated files.

Behavior rules in this file and per-project rules in `PROJECT.md` apply
unconditionally on every host, every harness.

## Engineering Skills

Shared engineering skills are available in `~/dev/.skills/`. Load on demand via the index.

See `~/dev/.skills/SKILLS_INDEX.md` for the full list with descriptions and "use when" triggers.

Key skills:
- **TDD**: always write tests first — load `tdd` skill
- **Code Review**: load `code-review` skill before any review
- **SOLID/Clean Code**: load `solid` or `clean-code` skill for design work
- **Problem first**: load `problem-analysis` skill before coding non-trivial features

---

# Project context

<!-- Canonical project context. Edit this, run `task context:sync`.
     Root agent context from ~/dev/.context/AGENT.md is automatically
     prepended for harnesses that don't walk the directory tree. -->

## Identity

- **Name**: gitea-mcp
- **Owner**: Mathias
- **Client**: personal
- **Repo**: https://gitea.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:`
- Branch naming: `feat/short-description`, `fix/short-description`
- PRs: one concern per PR, description explains *why* not *what*
- **Branch protection:** always work on a feature branch, open a PR, never push directly to main

### 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. Always work on a feature branch and open a PR — never push directly to main
7. For client projects: never send code or context to cloud APIs — use local models via LiteLLM

## Current sprint — gitea-mcp v0.2 patch (2026-05-14)

### Context
The main v0.2 batch (repo_create, repo_update, repo_mirror_push, repo_delete,
repo_tree, repo_topics_update, file_read dir-fix, issue_get, release_create,
create_project_from_template) was implemented and pushed directly to main.

This sprint fixes three remaining gaps found during code review on 2026-05-14.
These are blockers for `hyperguild new-project`.

### Issues to fix (all three in one PR: `fix/v02-patch`)

#### #12 — repo_update: add `archived` and `template` fields
**File:** `internal/gitea/repos.go` → `UpdateRepoArgs` struct
**File:** `internal/tools/repo_update.go` → input schema + args struct

Add to `UpdateRepoArgs`:
```go
Archived *bool
Template *bool
```

Add to tool input schema:
```json
"archived": {
  "type": "boolean",
  "description": "Mark repo as archived (read-only). Requires confirm=<repo name>."
},
"template": {
  "type": "boolean",
  "description": "Toggle template repo flag."
}
```

Add confirm-guard for `archived=true` (same pattern as `private=false`):
```go
if args.Archived != nil && *args.Archived {
    if args.Confirm != args.Name {
        return nil, fmt.Errorf("setting archived=true is irreversible: set confirm=%q to proceed", args.Name)
    }
}
```

New test cases to add in `repo_update_test.go`:
- `TestRepoUpdateTool_Archive` — happy path with confirm
- `TestRepoUpdateTool_ArchiveRequiresConfirm` — missing confirm returns error
- `TestRepoUpdateTool_SetTemplate` — no confirm needed

#### #24 — create_project_from_template: make template selectable
**File:** `internal/tools/create_project_from_template.go`

Add optional `template_name` param to input schema:
```json
"template_name": {
  "type": "string",
  "enum": ["template-go-web", "template-go-agent"],
  "description": "Template repo to generate from. Defaults to template-go-web.",
  "default": "template-go-web"
}
```

The tool should use `args.TemplateName` if set, fall back to the hardcoded default.
Remove the hardcoded template name from `cmd/gitea-mcp/main.go` constructor call —
the tool resolves it internally.

New test case: `TestCreateProjectFromTemplate_AgentTemplate`

#### #25 — pr_files_diff: fix same diff returned for all files
**File:** `internal/tools/pr_files_diff.go`

There is a loop bug where all file entries in the response contain the same diff
(the first file's diff is reused for every subsequent file). Find the loop and
ensure each iteration reads and assigns the correct diff for its own file.

Reproduce: call `pr_files_diff` on any PR with 3+ files, verify each file has
a distinct diff.

### Definition of done

- [ ] `task check` passes
- [ ] `repo_update` accepts `archived` and `template` params
- [ ] `archived=true` requires `confirm=<repo name>`
- [ ] `create_project_from_template` accepts `template_name` param, defaults to `template-go-web`
- [ ] `pr_files_diff` returns distinct diff per file
- [ ] All new test cases pass
- [ ] PR `fix/v02-patch` merged to main via PR (not direct push)

### After this sprint

Next: `hyperguild new-project` v1 implementation.
See brain node `adr-new-project-gitea-first-github-mirror` for the full flow spec.
Also: verify end-to-end mirror flow (issue #19) once `repo_mirror_push` is confirmed working.