From 7178ae32be7fb1deac607a98f37ed857c0ec49c9 Mon Sep 17 00:00:00 2001 From: Mathias Bergqvist Date: Fri, 15 May 2026 09:53:09 +0200 Subject: [PATCH] chore: re-sync context adapters --- .aider.conventions.md | 71 ++++++++++++++++++++++++++++++++++++-- .context/system-prompt.txt | 71 ++++++++++++++++++++++++++++++++++++-- .cursorrules | 71 ++++++++++++++++++++++++++++++++++++-- AGENTS.md | 71 ++++++++++++++++++++++++++++++++++++-- CLAUDE.md | 64 ++++++++++++++++++++++++++++++++++ 5 files changed, 336 insertions(+), 12 deletions(-) diff --git a/.aider.conventions.md b/.aider.conventions.md index d1730a9..230796d 100644 --- a/.aider.conventions.md +++ b/.aider.conventions.md @@ -49,9 +49,10 @@ These rules apply to every task across every project, regardless of harness. | Build | Task (taskfile.dev) | Make | — | | Containers | Docker Compose (dev), k3s (prod) | — | — | | DB | PostgreSQL + sqlc | SQLite | — | -| Search | Qdrant (vector), BM25 | — | — | +| Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — | | Logging | slog (structured) | — | — | | Testing | Table-driven, testify | — | — | +| Agents (Go) | google.golang.org/adk + pkg/litellm adapter | — | — | Exploratory: Rust, Zig — I'll tell you when I want these. @@ -63,7 +64,7 @@ Exploratory: Rust, Zig — I'll tell you when I want these. - **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 +- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message ## Infrastructure @@ -71,7 +72,7 @@ Three machines on Tailscale: | Machine | Role | Key specs | |---------|------|-----------| -| koala | GPU inference, heavy compute | RTX 5070, runs llama-swap, Qdrant | +| 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 | @@ -251,3 +252,67 @@ When acting as a coding agent on this project: 4. Never modify files outside the project root without explicit permission 5. When adding a dependency, explain why in the commit message 6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM + +## Current sprint — gitea-mcp v0.2 (2026-05-14) + +### Context +This sprint implements new MCP tools needed for `hyperguild new-project` — +the automated project creation flow triggered from claude.ai. See brain knowledge +nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline` +for full background. + +### Issues to implement (priority order) + +**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)** + +| Issue | Tool | Gitea API | +|-------|------|-----------| +| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos | +| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors | +| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} | + +**Batch 2 — quality of life (second PR: `feat/repo-ux`)** + +| Issue | Tool | Gitea API | +|-------|------|-----------| +| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response | +| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true | +| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics | + +**Batch 3 — can wait** + +| Issue | Tool | Note | +|-------|------|------| +| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name | +| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases | + +### How to add a tool (pattern) + +Every tool = 4 files following `internal/tools/repo_get.go` exactly: + +1. `internal/gitea/.go` — API client method (use PostJSON/PatchJSON/DeleteJSON) +2. `internal/tools/repo_.go` — tool handler with Descriptor() + Call() +3. `internal/tools/repo__test.go` — table-driven tests with httptest.NewServer +4. Registration in main — find where `NewRepoGet` is registered, add new tool same place + +Key rules: +- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard) +- Use `textOK(result)` for success output +- For `repo_mirror_push`: NEVER log or return `remote_password` in any output +- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name + +### Token permissions needed + +New tools require these additional Gitea token scopes: +- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create +- `delete_repo` — repo_delete + +Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user` +If scopes are missing, update token in Gitea settings before running tests. + +### Definition of done + +- `task check` passes (all tools, all batches) +- Each new tool manually callable via `claude mcp call` +- PR #1 (batch 1) merged before starting batch 2 +- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed diff --git a/.context/system-prompt.txt b/.context/system-prompt.txt index 7475daf..61d4351 100644 --- a/.context/system-prompt.txt +++ b/.context/system-prompt.txt @@ -54,9 +54,10 @@ These rules apply to every task across every project, regardless of harness. | Build | Task (taskfile.dev) | Make | — | | Containers | Docker Compose (dev), k3s (prod) | — | — | | DB | PostgreSQL + sqlc | SQLite | — | -| Search | Qdrant (vector), BM25 | — | — | +| Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — | | Logging | slog (structured) | — | — | | Testing | Table-driven, testify | — | — | +| Agents (Go) | google.golang.org/adk + pkg/litellm adapter | — | — | Exploratory: Rust, Zig — I'll tell you when I want these. @@ -68,7 +69,7 @@ Exploratory: Rust, Zig — I'll tell you when I want these. - **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 +- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message ## Infrastructure @@ -76,7 +77,7 @@ Three machines on Tailscale: | Machine | Role | Key specs | |---------|------|-----------| -| koala | GPU inference, heavy compute | RTX 5070, runs llama-swap, Qdrant | +| 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 | @@ -257,4 +258,68 @@ When acting as a coding agent on this project: 5. When adding a dependency, explain why in the commit message 6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM +## Current sprint — gitea-mcp v0.2 (2026-05-14) + +### Context +This sprint implements new MCP tools needed for `hyperguild new-project` — +the automated project creation flow triggered from claude.ai. See brain knowledge +nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline` +for full background. + +### Issues to implement (priority order) + +**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)** + +| Issue | Tool | Gitea API | +|-------|------|-----------| +| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos | +| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors | +| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} | + +**Batch 2 — quality of life (second PR: `feat/repo-ux`)** + +| Issue | Tool | Gitea API | +|-------|------|-----------| +| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response | +| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true | +| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics | + +**Batch 3 — can wait** + +| Issue | Tool | Note | +|-------|------|------| +| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name | +| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases | + +### How to add a tool (pattern) + +Every tool = 4 files following `internal/tools/repo_get.go` exactly: + +1. `internal/gitea/.go` — API client method (use PostJSON/PatchJSON/DeleteJSON) +2. `internal/tools/repo_.go` — tool handler with Descriptor() + Call() +3. `internal/tools/repo__test.go` — table-driven tests with httptest.NewServer +4. Registration in main — find where `NewRepoGet` is registered, add new tool same place + +Key rules: +- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard) +- Use `textOK(result)` for success output +- For `repo_mirror_push`: NEVER log or return `remote_password` in any output +- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name + +### Token permissions needed + +New tools require these additional Gitea token scopes: +- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create +- `delete_repo` — repo_delete + +Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user` +If scopes are missing, update token in Gitea settings before running tests. + +### Definition of done + +- `task check` passes (all tools, all batches) +- Each new tool manually callable via `claude mcp call` +- PR #1 (batch 1) merged before starting batch 2 +- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed + --- diff --git a/.cursorrules b/.cursorrules index b2a35f0..1e224a4 100644 --- a/.cursorrules +++ b/.cursorrules @@ -52,9 +52,10 @@ These rules apply to every task across every project, regardless of harness. | Build | Task (taskfile.dev) | Make | — | | Containers | Docker Compose (dev), k3s (prod) | — | — | | DB | PostgreSQL + sqlc | SQLite | — | -| Search | Qdrant (vector), BM25 | — | — | +| Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — | | Logging | slog (structured) | — | — | | Testing | Table-driven, testify | — | — | +| Agents (Go) | google.golang.org/adk + pkg/litellm adapter | — | — | Exploratory: Rust, Zig — I'll tell you when I want these. @@ -66,7 +67,7 @@ Exploratory: Rust, Zig — I'll tell you when I want these. - **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 +- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message ## Infrastructure @@ -74,7 +75,7 @@ Three machines on Tailscale: | Machine | Role | Key specs | |---------|------|-----------| -| koala | GPU inference, heavy compute | RTX 5070, runs llama-swap, Qdrant | +| 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 | @@ -254,3 +255,67 @@ When acting as a coding agent on this project: 4. Never modify files outside the project root without explicit permission 5. When adding a dependency, explain why in the commit message 6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM + +## Current sprint — gitea-mcp v0.2 (2026-05-14) + +### Context +This sprint implements new MCP tools needed for `hyperguild new-project` — +the automated project creation flow triggered from claude.ai. See brain knowledge +nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline` +for full background. + +### Issues to implement (priority order) + +**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)** + +| Issue | Tool | Gitea API | +|-------|------|-----------| +| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos | +| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors | +| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} | + +**Batch 2 — quality of life (second PR: `feat/repo-ux`)** + +| Issue | Tool | Gitea API | +|-------|------|-----------| +| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response | +| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true | +| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics | + +**Batch 3 — can wait** + +| Issue | Tool | Note | +|-------|------|------| +| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name | +| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases | + +### How to add a tool (pattern) + +Every tool = 4 files following `internal/tools/repo_get.go` exactly: + +1. `internal/gitea/.go` — API client method (use PostJSON/PatchJSON/DeleteJSON) +2. `internal/tools/repo_.go` — tool handler with Descriptor() + Call() +3. `internal/tools/repo__test.go` — table-driven tests with httptest.NewServer +4. Registration in main — find where `NewRepoGet` is registered, add new tool same place + +Key rules: +- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard) +- Use `textOK(result)` for success output +- For `repo_mirror_push`: NEVER log or return `remote_password` in any output +- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name + +### Token permissions needed + +New tools require these additional Gitea token scopes: +- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create +- `delete_repo` — repo_delete + +Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user` +If scopes are missing, update token in Gitea settings before running tests. + +### Definition of done + +- `task check` passes (all tools, all batches) +- Each new tool manually callable via `claude mcp call` +- PR #1 (batch 1) merged before starting batch 2 +- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed diff --git a/AGENTS.md b/AGENTS.md index d1730a9..230796d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,9 +49,10 @@ These rules apply to every task across every project, regardless of harness. | Build | Task (taskfile.dev) | Make | — | | Containers | Docker Compose (dev), k3s (prod) | — | — | | DB | PostgreSQL + sqlc | SQLite | — | -| Search | Qdrant (vector), BM25 | — | — | +| Search | pgvector (vector), BM25 | Qdrant (when >1M vectors or hybrid retrieval) | — | | Logging | slog (structured) | — | — | | Testing | Table-driven, testify | — | — | +| Agents (Go) | google.golang.org/adk + pkg/litellm adapter | — | — | Exploratory: Rust, Zig — I'll tell you when I want these. @@ -63,7 +64,7 @@ Exploratory: Rust, Zig — I'll tell you when I want these. - **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 +- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message ## Infrastructure @@ -71,7 +72,7 @@ Three machines on Tailscale: | Machine | Role | Key specs | |---------|------|-----------| -| koala | GPU inference, heavy compute | RTX 5070, runs llama-swap, Qdrant | +| 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 | @@ -251,3 +252,67 @@ When acting as a coding agent on this project: 4. Never modify files outside the project root without explicit permission 5. When adding a dependency, explain why in the commit message 6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM + +## Current sprint — gitea-mcp v0.2 (2026-05-14) + +### Context +This sprint implements new MCP tools needed for `hyperguild new-project` — +the automated project creation flow triggered from claude.ai. See brain knowledge +nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline` +for full background. + +### Issues to implement (priority order) + +**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)** + +| Issue | Tool | Gitea API | +|-------|------|-----------| +| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos | +| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors | +| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} | + +**Batch 2 — quality of life (second PR: `feat/repo-ux`)** + +| Issue | Tool | Gitea API | +|-------|------|-----------| +| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response | +| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true | +| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics | + +**Batch 3 — can wait** + +| Issue | Tool | Note | +|-------|------|------| +| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name | +| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases | + +### How to add a tool (pattern) + +Every tool = 4 files following `internal/tools/repo_get.go` exactly: + +1. `internal/gitea/.go` — API client method (use PostJSON/PatchJSON/DeleteJSON) +2. `internal/tools/repo_.go` — tool handler with Descriptor() + Call() +3. `internal/tools/repo__test.go` — table-driven tests with httptest.NewServer +4. Registration in main — find where `NewRepoGet` is registered, add new tool same place + +Key rules: +- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard) +- Use `textOK(result)` for success output +- For `repo_mirror_push`: NEVER log or return `remote_password` in any output +- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name + +### Token permissions needed + +New tools require these additional Gitea token scopes: +- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create +- `delete_repo` — repo_delete + +Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user` +If scopes are missing, update token in Gitea settings before running tests. + +### Definition of done + +- `task check` passes (all tools, all batches) +- Each new tool manually callable via `claude mcp call` +- PR #1 (batch 1) merged before starting batch 2 +- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed diff --git a/CLAUDE.md b/CLAUDE.md index e89a596..934bde5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -77,3 +77,67 @@ When acting as a coding agent on this project: 4. Never modify files outside the project root without explicit permission 5. When adding a dependency, explain why in the commit message 6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM + +## Current sprint — gitea-mcp v0.2 (2026-05-14) + +### Context +This sprint implements new MCP tools needed for `hyperguild new-project` — +the automated project creation flow triggered from claude.ai. See brain knowledge +nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline` +for full background. + +### Issues to implement (priority order) + +**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)** + +| Issue | Tool | Gitea API | +|-------|------|-----------| +| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos | +| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors | +| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} | + +**Batch 2 — quality of life (second PR: `feat/repo-ux`)** + +| Issue | Tool | Gitea API | +|-------|------|-----------| +| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response | +| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true | +| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics | + +**Batch 3 — can wait** + +| Issue | Tool | Note | +|-------|------|------| +| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name | +| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases | + +### How to add a tool (pattern) + +Every tool = 4 files following `internal/tools/repo_get.go` exactly: + +1. `internal/gitea/.go` — API client method (use PostJSON/PatchJSON/DeleteJSON) +2. `internal/tools/repo_.go` — tool handler with Descriptor() + Call() +3. `internal/tools/repo__test.go` — table-driven tests with httptest.NewServer +4. Registration in main — find where `NewRepoGet` is registered, add new tool same place + +Key rules: +- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard) +- Use `textOK(result)` for success output +- For `repo_mirror_push`: NEVER log or return `remote_password` in any output +- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name + +### Token permissions needed + +New tools require these additional Gitea token scopes: +- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create +- `delete_repo` — repo_delete + +Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user` +If scopes are missing, update token in Gitea settings before running tests. + +### Definition of done + +- `task check` passes (all tools, all batches) +- Each new tool manually callable via `claude mcp call` +- PR #1 (batch 1) merged before starting batch 2 +- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed