add: m3ta-brain skill — shared vault workflows

Skill for the m3ta-brain Obsidian vault (ssh://gitea@code.m3ta.dev/m3tam3re/m3ta-brain.git). Agent-agnostic — works with Hermes, Pi, OpenCode, Claude Code. Workflows: 1. Session Start (Auto-Recall): pull, read core context, load project state 2. Session End: write summary, decisions, project updates, memory candidates 3. Decision Note creation (ADR-style) 4. Person Profile creation (with sensitivity rules) 5. Nightly/Weekly Digest: process inbox, check freshness, link audit, report Conventions: - Standard Markdown links with relative paths (NOT wikilinks) - Git commit/push patterns - Write policy (direct vs draft vs forbidden) - Relationship to Tech Wiki, Nemoti Wiki, qmd, session search References: - vault-map.md: full directory layout, tag taxonomy, link audit command
2026-06-29 20:55:12 +02:00
parent 920c00313a
commit 6fac485813
2 changed files with 541 additions and 0 deletions
@@ -0,0 +1,392 @@
+---
+name: m3ta-brain
+description: "Shared Obsidian vault for human-agent collaboration. Use when: (1) Loading project context at session start (auto-recall), (2) Writing session summaries, decisions, project updates, or learning notes, (3) Searching for past decisions or project state, (4) Running nightly/weekly digest passes, (5) Creating or updating person profiles, (6) Any reference to 'the vault', 'shared brain', 'our context', 'what did we decide'. Triggers: m3ta-brain, shared brain, vault, session summary, decision note, project update, memory candidate, brain vault, auto-recall, digest, nightly pass."
+compatibility: opencode
+---
+
+# m3ta-brain
+
+Shared Obsidian vault — the persistent, compounding working memory between Sascha and all AI agents. Git-versioned, standard Markdown, works in Obsidian and Gitea.
+
+## Prerequisites
+
+- Vault cloned at `/var/lib/hermes/workspace/m3ta-brain` (server) or local machine
+- Git configured with push access to `ssh://gitea@code.m3ta.dev/m3tam3re/m3ta-brain.git`
+- Obsidian settings (auto-configured via `.obsidian/app.json`): Wikilinks OFF, relative paths ON
+
+Always pull before reading or writing:
+
+```bash
+cd /var/lib/hermes/workspace/m3ta-brain && git pull --rebase
+```
+
+## Vault Structure (Quick Reference)
+
+See `references/vault-map.md` for full layout. Key directories:
+
+| Dir | Purpose | Write Access |
+|---|---|---|
+| `00-Telos/` | Identity, goals, constraints | Draft only |
+| `10-Preferences/` | Communication, tech stack, do's & don'ts | Draft only |
+| `20-Projects/` | Active project cards (state, next actions) | Direct |
+| `30-Decisions/` | Architecture Decision Records | Direct |
+| `40-People/` | Person profiles | Draft + confidential |
+| `50-Knowledge/` | Systems, concepts, companies | Direct |
+| `60-Learning/` | Sessions, patterns, corrections, inbox | Direct (inbox = candidates) |
+| `70-Collaboration/` | How-we-work, agent conventions | Draft only |
+| `80-Templates/` | Note templates | Read-only reference |
+
+---
+
+## Workflow 1: Session Start (Auto-Recall)
+
+**When:** At the beginning of any substantial work session, or when the user references past context.
+
+### Step 1: Pull latest
+
+```bash
+cd /var/lib/hermes/workspace/m3ta-brain && git pull --rebase
+```
+
+### Step 2: Read core context
+
+Read in this order (stop early if context is sufficient — do NOT read the entire vault):
+
+1. `AGENTS.md` — the rules (skim if already known)
+2. `INDEX.md` — dashboard, what's new, stats
+3. `10-Preferences/do-dont.md` — hard rules to respect THIS session
+
+### Step 3: Load project-specific context
+
+Determine the relevant project(s) from the user's message or working directory. Read only the relevant project cards:
+
+```
+20-Projects/{project-slug}.md
+```
+
+If the topic is ambiguous, read `20-Projects/overview.md` for the dashboard.
+
+### Step 4: Search for relevant history (optional, when deeper context needed)
+
+If qmd is installed:
+
+```bash
+qmd query "{topic}" -c brain --md -n 5
+```
+
+If qmd is NOT installed, use `search_files` on the vault directory:
+
+```
+search_files(pattern="{topic}", path="/var/lib/hermes/workspace/m3ta-brain", target="content")
+```
+
+### Step 5: Recall relevant decisions
+
+For architectural or strategic questions, check recent decisions:
+
+```
+30-Decisions/INDEX.md
+```
+
+### Token budget
+
+Cap auto-recall to ~2000 tokens of injected context. Summarize rather than dumping full notes.
+
+---
+
+## Workflow 2: Session End (Persist Learnings)
+
+**When:** After substantial work — at minimum when explicitly asked, ideally proactively for any session that produced decisions, project changes, or learnings.
+
+### Step 1: Write session summary
+
+File: `60-Learning/sessions/YYYY-MM-DD-{slug}.md`
+
+Use template `80-Templates/session-summary.md`. Fill all sections:
+
+```yaml
+---
+type: session-summary
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+session_date: YYYY-MM-DD
+projects: []
+tags: [session]
+---
+```
+
+Content sections: What We Discussed → Decisions Made → New Context Learned → Project Updates → Open Questions → Suggested Memory Candidates → Next Actions.
+
+### Step 2: Create/update decision notes
+
+If a clear decision was made during the session, create `30-Decisions/YYYY-MM-{slug}.md` using the decision template. Link it from the project card.
+
+### Step 3: Update project cards
+
+If project state changed, update the relevant `20-Projects/{project}.md`: Current State, Next Actions, Active Threads.
+
+### Step 4: File memory candidates
+
+If something new was learned about the user, a person, or a pattern — write to `60-Learning/inbox/YYYY-MM-DD-{slug}.md` with `status: draft`. These get reviewed in the digest pass.
+
+### Step 5: Commit and push
+
+```bash
+cd /var/lib/hermes/workspace/m3ta-brain
+git add -A
+git commit -m "session: {brief description}
+
+- {what was written/updated}
+- {key files}"
+git push origin main
+```
+
+---
+
+## Workflow 3: Decision Note
+
+**When:** A clear architectural, strategic, or process decision is made.
+
+File: `30-Decisions/YYYY-MM-{slug}.md`
+
+Required frontmatter:
+
+```yaml
+---
+type: decision
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+decided: YYYY-MM-DD
+decision_status: accepted  # accepted | proposed | superseded
+impact: high  # high | medium | low
+alternatives: []
+tags: [decision]
+---
+```
+
+Required sections: Context → Decision → Rationale → Consequences → Revisit When → Related.
+
+Update `30-Decisions/INDEX.md` with a new row.
+
+---
+
+## Workflow 4: Person Profile
+
+**When:** The user mentions a colleague, client, or contact with enough detail to warrant a profile.
+
+### Rules
+
+- **sensitivity: confidential** for all person profiles
+- **status: draft** until the user confirms the content is accurate
+- Only write confirmed facts — mark speculation as `(unsicher)`
+- Do NOT create profiles for people mentioned in passing
+- Do NOT write sensitive personal details without explicit consent
+- Prefer the `60-Learning/inbox/` candidate workflow for new observations about existing people
+
+### File location
+
+```
+40-People/colleagues/{firstname-lastname}.md  — work colleagues
+40-People/external/{firstname-lastname}.md    — external contacts
+40-People/family.md                           — family (already exists)
+```
+
+### When to add to an existing profile vs. write a new one
+
+- New person → new file
+- New observation about existing person → append to their profile under "Interaction History"
+- Pattern observed across multiple people → `60-Learning/patterns/` note instead
+
+---
+
+## Workflow 5: Nightly / Weekly Digest
+
+**When:** Run as a cronjob (daily or weekly). Can also be triggered manually.
+
+### Purpose
+
+The vault accumulates drafts, candidates, and potentially stale information. The digest pass:
+1. Consolidates inbox candidates
+2. Promotes stable patterns
+3. Flags stale projects
+4. Reports broken links
+5. Sends a summary to the user
+
+### Step 1: Pull and scan
+
+```bash
+cd /var/lib/hermes/workspace/m3ta-brain && git pull --rebase
+```
+
+### Step 2: Process inbox
+
+Read all files in `60-Learning/inbox/`. For each:
+
+- **Promote**: if the candidate is confirmed and stable → move to `60-Learning/patterns/` or update the relevant `10-Preferences/` note. Remove from inbox.
+- **Keep**: if still uncertain → leave in inbox with a `reviewed: YYYY-MM-DD` frontmatter field.
+- **Discard**: if proven wrong or stale → move to `90-Archive/`.
+
+### Step 3: Check project freshness
+
+For each `20-Projects/*.md`, check the `updated` frontmatter field:
+
+- **> 30 days without update** → flag as "stale" in the digest report
+- **Next Actions all checked** → suggest moving to `90-Archive/`
+
+### Step 4: Link health check
+
+Run a link audit script (see `references/vault-map.md` for the audit command). Report any broken links.
+
+### Step 5: Update INDEX.md
+
+Refresh stats, recent decisions, recent sessions.
+
+### Step 6: Commit and push
+
+```bash
+git add -A
+git commit -m "digest: {date} pass
+
+- {N} inbox items processed
+- {N} patterns promoted
+- {N} stale projects flagged
+- {N} broken links found"
+git push origin main
+```
+
+### Step 7: Report to user
+
+Send a concise digest message:
+
+```
+📋 m3ta-brain Digest {date}
+
+- {N} neue Session-Summaries
+- {N} Inbox-Candidates verarbeitet ({promoted} promoted, {kept} kept)
+- {N} Decisions hinzugefügt
+- Projekte als stale markiert: {list}
+- Broken Links: {N}
+```
+
+### Cronjob setup
+
+```
+schedule: "0 6 * * 1"  # Weekly Monday 6am
+deliver: origin  # back to chat
+skills: ["m3ta-brain"]
+prompt: "Run the m3ta-brain weekly digest pass. Follow the Nightly/Weekly Digest workflow in the m3ta-brain skill. Pull the vault, process inbox, check freshness, run link audit, commit, and report a concise summary."
+```
+
+---
+
+## Link Conventions
+
+**CRITICAL:** Use standard Markdown links with file-relative paths. NOT `[[wikilinks]]`.
+
+```markdown
+<!-- Same directory -->
+[Project Name](project-name.md)
+
+<!-- Cross-directory (from 30-Decisions/ to 20-Projects/) -->
+[AZ-Gruppe](../20-Projects/az-gruppe.md)
+
+<!-- Cross-directory (from 60-Learning/patterns/ to 20-Projects/) -->
+[Hermes](../../20-Projects/m3-hermes.md)
+```
+
+Rules:
+- File-relative paths only (`../dir/file.md`)
+- Always include `.md` extension
+- URL-encode spaces in filenames as `%20` (avoid spaces in filenames instead)
+- Minimum 2 internal links per note
+- Every note should be linked FROM at least one other note (no orphans)
+- Templates may contain `[[]]` placeholders — these are Obsidian template syntax, leave as-is
+
+---
+
+## Git Conventions
+
+### Commit messages
+
+```
+session: {brief description}      — after a work session
+decision: {slug}                   — new decision note
+update: {project} status           — project card update
+digest: {date} pass                — nightly/weekly digest
+fix: {what was fixed}              — corrections
+add: {what was added}              — new note or section
+```
+
+### When to push
+
+- After writing session summaries or decision notes
+- After updating project cards
+- After digest passes
+- NOT after every single small edit — batch related changes
+
+### Conflict handling
+
+If `git pull --rebase` fails:
+
+```bash
+# Check what conflicted
+git status
+# Resolve manually, then:
+git add -A && git rebase --continue
+```
+
+Do NOT force-push. The vault is shared — last-writer-wins via normal Git.
+
+---
+
+## What NOT to Do
+
+- **Do NOT** write secrets, passwords, API keys, or tokens to the vault
+- **Do NOT** write intimate/private details without explicit consent
+- **Do NOT** create profiles for people mentioned only in passing
+- **Do NOT** dump full chat transcripts — use summaries
+- **Do NOT** use `[[wikilinks]]` — they don't render in Gitea
+- **Do NOT** assume facts — mark speculation as `(unsicher)` or `status: draft`
+- **Do NOT** duplicate content from the Tech Wiki or Nemoti Wiki — link to them instead
+- **Do NOT** modify `80-Templates/` during a session — they are structural
+- **Do NOT** force-push (`git push --force`) — the vault is shared
+
+---
+
+## Relationship to Other Systems
+
+| System | Role | When to use |
+|---|---|---|
+| m3ta-brain (this vault) | Shared working memory, project context, decisions, learnings | Session start, session end, decisions |
+| Hermes internal memory | Hot cache of critical facts for fast recall | Automatic, small entries only |
+| Tech Wiki (`/var/lib/hermes/wiki`) | Research, concepts, entities (English) | Deep research, new technology |
+| Nemoti Wiki (`/var/lib/hermes/wiki-nemoti`) | Lore, characters, art strategy (German) | Nemoti creative work |
+| Session Search | Raw session transcripts | "What did we do about X?" |
+| qmd | Hybrid search across vaults (if installed) | Cross-vault semantic queries |
+| Agent Hub | Cross-agent task coordination | Beads task queue |
+
+Rule: **m3ta-brain is the working context layer.** Research goes to Tech Wiki. Lore goes to Nemoti Wiki. Raw session history stays in session search. m3ta-brain holds the glue: decisions, project state, preferences, learnings, people.
+
+---
+
+## Multi-Agent Compatibility
+
+This vault is designed for ANY agent (Hermes, Pi, OpenCode, Claude Code, Codex). Rules:
+
+- No agent-specific assumptions in note content
+- Agent identity stays in commit messages, not in note bodies
+- Multiple agents may read/write — last-writer-wins via Git
+- The vault is the single source of truth — agent-internal memory is a cache
+- If another agent made changes, `git pull` before writing
+
+---
+
+## Pitfalls
+
+- **Forgetting to pull**: Always `git pull --rebase` before reading or writing. The vault may have been updated by another agent or by Sascha from another device.
+- **Using wikilinks**: `[[wikilinks]]` do NOT render as links in Gitea. Always use `[Text](relative/path.md)`.
+- **Wrong relative paths**: Links must be relative FROM the source file, not from vault root. From `30-Decisions/X.md` to `20-Projects/Y.md` → `../20-Projects/Y.md`.
+- **Overwriting drafts**: `00-Telos/`, `10-Preferences/`, `40-People/` are `status: draft`. Do not overwrite without explicit user confirmation.
+- **INDEX.md drift**: When adding notes, update `INDEX.md` in the same commit. Stale indexes defeat the purpose.
+- **Orphan notes**: Every note must be linked FROM at least one other note. Unlinked notes are invisible in the graph.
+- **External wiki duplication**: Do not copy Tech Wiki or Nemoti Wiki content into m3ta-brain. Summarize and link: `[Tech Wiki: Nix CLI](/var/lib/hermes/wiki/concepts/nix-cli-migration.md)`.
@@ -0,0 +1,149 @@
+# Vault Map — m3ta-brain Structure Reference
+
+> Full directory layout with purpose and content guidelines for each section.
+
+## Root Files
+
+| File | Purpose |
+|---|---|
+| `AGENTS.md` | Universal agent instructions: read order, write policy, conventions |
+| `SCHEMA.md` | Frontmatter types, tag taxonomy, naming conventions, quality rules |
+| `README.md` | Human-facing intro and quick-start guide |
+| `INDEX.md` | Dashboard: stats, active projects, recent decisions, recent sessions |
+| `.obsidian/app.json` | Obsidian settings: Wikilinks OFF, relative paths ON |
+| `.gitignore` | Ignores workspace state, OS files, sync conflicts |
+
+## Directory Detail
+
+### 00-Telos/ (Identity)
+
+| File | Content | Write Rule |
+|---|---|---|
+| `sascha.md` | Identity card: name, role, tech background, traits, motivation | Draft only |
+| `goals.md` | Professional + personal goals with timeframes | Draft only |
+| `constraints.md` | Hard constraints: team skills, budget, self-hosting, security | Draft only |
+
+### 10-Preferences/ (How Sascha Works)
+
+| File | Content | Write Rule |
+|---|---|---|
+| `communication.md` | Communication style: terse text, modality matching, language | Draft only |
+| `tech-stack.md` | Full tech stack organized by category | Draft only |
+| `working-style.md` | Delegation vs oversight, test-driven infra, iterative debugging | Draft only |
+| `do-dont.md` | Explicit Do's and Don'ts table — HARD RULES | Draft only |
+
+### 20-Projects/ (Active Work)
+
+| File | Content | Write Rule |
+|---|---|---|
+| `overview.md` | Dashboard table of all projects with status/priority | Direct |
+| `az-gruppe.md` | CTO role, Bestellungs-Pipeline, Appsmith, K8s | Direct |
+| `nemoti.md` | Nemoti art support, YouTube/TikTok/Twitch/Website | Direct |
+| `m3ta-home.md` | Portable NixOS profile framework | Direct |
+| `m3-hermes.md` | Hermes Agent, Matrix gateway | Direct |
+| `honcho.md` | Honcho self-hosting on m3-atlas | Direct |
+| `hermes-nixos-setup.md` | Livestream + Blogpost standalone repo | Direct |
+| `agent-hub.md` | Cross-agent coordination, Beads task queue | Direct |
+| `infrastructure.md` | Server overview, domains, services | Direct |
+
+### 30-Decisions/ (ADR-style)
+
+| File | Content |
+|---|---|
+| `INDEX.md` | Table of all decisions sorted by date |
+| `YYYY-MM-{slug}.md` | Individual decision records |
+
+Each decision note has: Context → Decision → Rationale → Consequences → Revisit When → Related.
+
+### 40-People/ (Contacts)
+
+| File/Dir | Content | Sensitivity |
+|---|---|---|
+| `INDEX.md` | Index of all people | Internal |
+| `family.md` | Nemoti profile | Confidential |
+| `colleagues/README.md` | Placeholder + guidance for colleague profiles | Internal |
+| `colleagues/{name}.md` | Individual colleague profiles | Confidential |
+| `external/{name}.md` | External contacts | Internal |
+
+### 50-Knowledge/ (Reference)
+
+| Dir | Content |
+|---|---|
+| `systems/` | Infrastructure systems (Traefik, Netbird, Authentik, etc.) |
+| `concepts/` | Methods, patterns, frameworks |
+| `companies/` | Organization profiles |
+
+### 60-Learning/ (Accumulated Wisdom)
+
+| Dir | Content | Write Rule |
+|---|---|---|
+| `sessions/` | Session summaries (YYYY-MM-DD-slug.md) | Direct |
+| `patterns/` | Recurring observations about work habits, preferences | Direct |
+| `corrections/` | Things that were wrong and got fixed | Direct |
+| `inbox/` | Candidates pending review (drafts before promotion) | Direct |
+
+### 70-Collaboration/ (Working Agreement)
+
+| File | Content | Write Rule |
+|---|---|---|
+| `how-we-work.md` | Delegation model, when to ask vs decide, session workflow | Draft only |
+| `agent-conventions.md` | Rules for any agent working in this vault | Draft only |
+| `multi-agent-setup.md` | How Pi/OpenCode/other agents use the vault | Draft only |
+
+### 80-Templates/ (Note Templates)
+
+Read-only reference. Contains: `project.md`, `decision.md`, `person.md`, `session-summary.md`, `learning.md`.
+
+### 90-Archive/ (Deprecated)
+
+Completed projects, superseded decisions, discarded candidates.
+
+## Link Audit Command
+
+To check for broken links across the vault:
+
+```bash
+python3 -c "
+import os, re
+from collections import defaultdict
+
+VAULT = '/var/lib/hermes/workspace/m3ta-brain'
+md_files = []
+for root, dirs, files in os.walk(VAULT):
+    if '.git' in root or '.obsidian' in root: continue
+    for f in files:
+        if f.endswith('.md'):
+            md_files.append(os.path.relpath(os.path.join(root, f), VAULT))
+
+# Build index
+paths = set(md_files)
+broken = []
+for f in md_files:
+    with open(os.path.join(VAULT, f)) as fh:
+        for i, line in enumerate(fh, 1):
+            for m in re.finditer(r'\[([^\]]+)\]\(([^)]+\.md)\)', line):
+                target = m.group(2)
+                if target.startswith('http'): continue
+                resolved = os.path.normpath(os.path.join(os.path.dirname(f), target))
+                if resolved not in paths:
+                    broken.append((f, i, target))
+print(f'Broken links: {len(broken)}')
+for f, i, t in broken:
+    print(f'  {f}:{i} → {t}')
+"
+```
+
+## Tag Taxonomy (from SCHEMA.md)
+
+| Tag | Use for |
+|---|---|
+| `infrastructure` | Servers, domains, networks, services |
+| `nixos` | NixOS/Flakes/Nix-related |
+| `work` | AZ-Gruppe / AZ-Intec related |
+| `creative` | Nemoti art, music, lore |
+| `decision` | Architecture/system decisions |
+| `agent` | AI agent infrastructure |
+| `security` | Security-relevant info |
+| `process` | How-we-work conventions |
+| `person` | Person profiles |
+| `deprecated` | No longer current |