From c4bd3396c479d7a76feb995ca0e559e94ffb70a3 Mon Sep 17 00:00:00 2001 From: Mathias Date: Mon, 18 May 2026 07:51:17 +0200 Subject: [PATCH] chore: re-sync context adapters from updated root AGENT.md --- .aider.conventions.md | 64 ++++++++++++++++++++++++++++++++------ .context/system-prompt.txt | 64 ++++++++++++++++++++++++++++++++------ .cursorrules | 64 ++++++++++++++++++++++++++++++++------ AGENTS.md | 64 ++++++++++++++++++++++++++++++++------ 4 files changed, 220 insertions(+), 36 deletions(-) diff --git a/.aider.conventions.md b/.aider.conventions.md index 3a48fa7..ef0b69e 100644 --- a/.aider.conventions.md +++ b/.aider.conventions.md @@ -116,18 +116,64 @@ See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project. - **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management - **klimatkollen** (`XT/`) — Swedish municipal climate data platform -## Knowledge base +## Knowledge base — actively use it -When available, agents can query the shared knowledge base: +A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions, +hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems, +Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional +reference material — query it actively, not just when explicitly told.** -- **MCP**: `mcp://hyperguild..ts.net:3100/knowledge` -- **HTTP**: `http://hyperguild..ts.net:3100/api/v1/search` +### When to query (treat as a reflex) - -- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public` +- **Before** starting a non-trivial task — search for prior art with the symptom + AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours. +- **When debugging** — search for the error string, the stack frame, the affected + service. Past you may have already paid this tax. +- **Before adopting** a pattern, library, framework, or model name — check if it + was tried and rejected, or what the integration footguns are. +- **When making architectural decisions** — search for the domain + "ADR" or + "decision" to find prior reasoning before re-deriving it. +- **When a recommendation feels novel** — challenge yourself: "has this been + documented?" The brain often has it. + +### When to write + +After you discover something that **future-you would forget** and that **isn't +recoverable from the code, git log, or PR description alone**: + +- Bugs whose root cause is non-obvious and generalisable beyond this project. +- Framework / library / model-name quirks that bit you and would bite anyone. +- Design principles validated under fire (e.g. "every `_get` needs a `_list`"). +- Postmortems for incidents: what broke, why, how diagnosed, what to do next time. + +DON'T write project status, sprint progress, PR summaries, or "what I did this +session" — those rot fast and the originals are in git/gitea anyway. Brain +entries that age well are about *why*, *how to avoid*, and *what to do when*. + +### How to access (per harness) + +| Harness | Query | Write | +|---------|-------|-------| +| **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool | +| **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same | +| **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` | +| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files | + +- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`. +- **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as + fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml` + on the koala k3s cluster; don't hardcode local-only model names into the + berget URL (see knowledge entry on namespace mismatches). + +### Quick reflex checks + +If you find yourself about to say any of these out loud, you owe yourself a brain query first: + +- "I think the issue might be..." +- "Let me try X and see..." +- "I'll just write a script to..." +- "This is probably a new bug..." +- "Has anyone done this before?" — *yes, probably, go check.* ## Client work rules diff --git a/.context/system-prompt.txt b/.context/system-prompt.txt index b348d6c..376e49f 100644 --- a/.context/system-prompt.txt +++ b/.context/system-prompt.txt @@ -121,18 +121,64 @@ See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project. - **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management - **klimatkollen** (`XT/`) — Swedish municipal climate data platform -## Knowledge base +## Knowledge base — actively use it -When available, agents can query the shared knowledge base: +A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions, +hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems, +Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional +reference material — query it actively, not just when explicitly told.** -- **MCP**: `mcp://hyperguild..ts.net:3100/knowledge` -- **HTTP**: `http://hyperguild..ts.net:3100/api/v1/search` +### When to query (treat as a reflex) - -- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public` +- **Before** starting a non-trivial task — search for prior art with the symptom + AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours. +- **When debugging** — search for the error string, the stack frame, the affected + service. Past you may have already paid this tax. +- **Before adopting** a pattern, library, framework, or model name — check if it + was tried and rejected, or what the integration footguns are. +- **When making architectural decisions** — search for the domain + "ADR" or + "decision" to find prior reasoning before re-deriving it. +- **When a recommendation feels novel** — challenge yourself: "has this been + documented?" The brain often has it. + +### When to write + +After you discover something that **future-you would forget** and that **isn't +recoverable from the code, git log, or PR description alone**: + +- Bugs whose root cause is non-obvious and generalisable beyond this project. +- Framework / library / model-name quirks that bit you and would bite anyone. +- Design principles validated under fire (e.g. "every `_get` needs a `_list`"). +- Postmortems for incidents: what broke, why, how diagnosed, what to do next time. + +DON'T write project status, sprint progress, PR summaries, or "what I did this +session" — those rot fast and the originals are in git/gitea anyway. Brain +entries that age well are about *why*, *how to avoid*, and *what to do when*. + +### How to access (per harness) + +| Harness | Query | Write | +|---------|-------|-------| +| **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool | +| **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same | +| **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` | +| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files | + +- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`. +- **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as + fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml` + on the koala k3s cluster; don't hardcode local-only model names into the + berget URL (see knowledge entry on namespace mismatches). + +### Quick reflex checks + +If you find yourself about to say any of these out loud, you owe yourself a brain query first: + +- "I think the issue might be..." +- "Let me try X and see..." +- "I'll just write a script to..." +- "This is probably a new bug..." +- "Has anyone done this before?" — *yes, probably, go check.* ## Client work rules diff --git a/.cursorrules b/.cursorrules index d6aa3bb..1cfeef1 100644 --- a/.cursorrules +++ b/.cursorrules @@ -119,18 +119,64 @@ See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project. - **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management - **klimatkollen** (`XT/`) — Swedish municipal climate data platform -## Knowledge base +## Knowledge base — actively use it -When available, agents can query the shared knowledge base: +A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions, +hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems, +Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional +reference material — query it actively, not just when explicitly told.** -- **MCP**: `mcp://hyperguild..ts.net:3100/knowledge` -- **HTTP**: `http://hyperguild..ts.net:3100/api/v1/search` +### When to query (treat as a reflex) - -- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public` +- **Before** starting a non-trivial task — search for prior art with the symptom + AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours. +- **When debugging** — search for the error string, the stack frame, the affected + service. Past you may have already paid this tax. +- **Before adopting** a pattern, library, framework, or model name — check if it + was tried and rejected, or what the integration footguns are. +- **When making architectural decisions** — search for the domain + "ADR" or + "decision" to find prior reasoning before re-deriving it. +- **When a recommendation feels novel** — challenge yourself: "has this been + documented?" The brain often has it. + +### When to write + +After you discover something that **future-you would forget** and that **isn't +recoverable from the code, git log, or PR description alone**: + +- Bugs whose root cause is non-obvious and generalisable beyond this project. +- Framework / library / model-name quirks that bit you and would bite anyone. +- Design principles validated under fire (e.g. "every `_get` needs a `_list`"). +- Postmortems for incidents: what broke, why, how diagnosed, what to do next time. + +DON'T write project status, sprint progress, PR summaries, or "what I did this +session" — those rot fast and the originals are in git/gitea anyway. Brain +entries that age well are about *why*, *how to avoid*, and *what to do when*. + +### How to access (per harness) + +| Harness | Query | Write | +|---------|-------|-------| +| **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool | +| **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same | +| **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` | +| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files | + +- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`. +- **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as + fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml` + on the koala k3s cluster; don't hardcode local-only model names into the + berget URL (see knowledge entry on namespace mismatches). + +### Quick reflex checks + +If you find yourself about to say any of these out loud, you owe yourself a brain query first: + +- "I think the issue might be..." +- "Let me try X and see..." +- "I'll just write a script to..." +- "This is probably a new bug..." +- "Has anyone done this before?" — *yes, probably, go check.* ## Client work rules diff --git a/AGENTS.md b/AGENTS.md index 3a48fa7..ef0b69e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -116,18 +116,64 @@ See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project. - **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management - **klimatkollen** (`XT/`) — Swedish municipal climate data platform -## Knowledge base +## Knowledge base — actively use it -When available, agents can query the shared knowledge base: +A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions, +hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems, +Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional +reference material — query it actively, not just when explicitly told.** -- **MCP**: `mcp://hyperguild..ts.net:3100/knowledge` -- **HTTP**: `http://hyperguild..ts.net:3100/api/v1/search` +### When to query (treat as a reflex) - -- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public` +- **Before** starting a non-trivial task — search for prior art with the symptom + AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours. +- **When debugging** — search for the error string, the stack frame, the affected + service. Past you may have already paid this tax. +- **Before adopting** a pattern, library, framework, or model name — check if it + was tried and rejected, or what the integration footguns are. +- **When making architectural decisions** — search for the domain + "ADR" or + "decision" to find prior reasoning before re-deriving it. +- **When a recommendation feels novel** — challenge yourself: "has this been + documented?" The brain often has it. + +### When to write + +After you discover something that **future-you would forget** and that **isn't +recoverable from the code, git log, or PR description alone**: + +- Bugs whose root cause is non-obvious and generalisable beyond this project. +- Framework / library / model-name quirks that bit you and would bite anyone. +- Design principles validated under fire (e.g. "every `_get` needs a `_list`"). +- Postmortems for incidents: what broke, why, how diagnosed, what to do next time. + +DON'T write project status, sprint progress, PR summaries, or "what I did this +session" — those rot fast and the originals are in git/gitea anyway. Brain +entries that age well are about *why*, *how to avoid*, and *what to do when*. + +### How to access (per harness) + +| Harness | Query | Write | +|---------|-------|-------| +| **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool | +| **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same | +| **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` | +| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files | + +- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`. +- **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as + fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml` + on the koala k3s cluster; don't hardcode local-only model names into the + berget URL (see knowledge entry on namespace mismatches). + +### Quick reflex checks + +If you find yourself about to say any of these out loud, you owe yourself a brain query first: + +- "I think the issue might be..." +- "Let me try X and see..." +- "I'll just write a script to..." +- "This is probably a new bug..." +- "Has anyone done this before?" — *yes, probably, go check.* ## Client work rules