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)`.