AGENTS.md

Contract and schema for Claude (and any other agent) working in this vault. CLAUDE.md is a symlink to this file so Claude Code and other tools see the same source of truth.

Project Overview

This repository is an Obsidian vault for personal knowledge management, not a software project. It is run as an LLM-maintained wiki (Karpathy pattern, April 2026): the agent compiles ingested material into cross-referenced markdown, maintains graph integrity, and runs periodic health checks. The human curates direction and approves substantive changes.

• Obsidian is the IDE. The agent is the programmer. The vault is the codebase.
• Everything here is plain markdown + git. No proprietary formats. The substrate outlasts any specific agent.

Directory Structure

Modified PARA, with two non-PARA folders for the agent loop:

• 0_Inbox — drain queue. Raw inputs land here, get routed into the wiki, then deleted. Not immutable raw. Four areas:
  • transcripts/ — raw Whisper output from the Apple Shortcut. Cleaned into 0_Inbox/ root by the audio-inbox skill, which process-inbox invokes as its Phase 0 so the full inbox drains in one run. audio-inbox can also be invoked directly on a single transcript.
  • notes/ — small typed notes the user jots during the day. No cleanup needed. Processed directly by process-inbox.
  • Clippings/ — Obsidian Web Clipper output (web articles, already in markdown with URL frontmatter). Default route: 3_Resources/Clippings/. Processed directly by process-inbox.
  • root — intermediate stage (cleaned voice-memo notes from audio-inbox) awaiting routing by process-inbox.
• 1_Home — entry points, dashboards, daily notes.
• 2_Areas — ongoing responsibilities and domains of activity.
  • _Canon/ — crystallized high-signal pages (durable, load-bearing). Promoted here by the crystallize skill.
• 3_Resources — reference materials and general knowledge.
• 4_Projects — active projects with clear goals and deadlines.
• 5_Archive — anything from 1–4 that’s older and not actively used.
• 6_Private — content that must not publish. Three reasons something lands here:
  1. Personal/sensitive — Zettel, Memo, Thoughts, private reflections.
  2. Copyrighted — third-party material held personally but not republishable (e.g. shinkansen-n2/ Japanese N2 course).
  3. Work-confidential — employer/client material under NDA or professional confidentiality (e.g. 10ten/). Quartz excludes this folder unconditionally. The agent must not move items out of 6_Private/ without explicit user approval, even when the topic looks public-safe.
• 7_Agent — agent artifacts (see below). Excluded from publishing.
• Templates — reusable templates for creating consistent notes.
• .obsidian — configuration files for the Obsidian app.
• 7_Agent/skills — single source of truth for all agent skills. Every skill lives here, visible in the Obsidian sidebar.
• .agents/skills, .claude/skills — symlinks to 7_Agent/skills. Any new agent folder (.codex/, .gemini/, …) must symlink its skills subfolder back to 7_Agent/skills/, never duplicate. See the add-skill skill.

7_Agent/ contents

• questions.md — append-only log of things Claude couldn’t answer from the vault (log-question writes here).
• log.md — append-only operations log. Every process-inbox, reconcile, consolidate, crystallize, triage run appends.
• notifications.md — pruned feed of high-signal items the agent wants the human to see — both action items (need input) and FYI items (just notifying). See Notifications below. Drained by triage.
• reconcile/<YYYY-Www>-reconcile.md — weekly reconcile reports (created on first run).

Frontmatter Schema

Required on every new note the agent creates:

---
created: 2026-04-17       # ISO date
lang: en                  # one of: de, en, ja, mixed
tags: [tag1, tag2]        # English, lowercase-kebab
source: voice-memo        # or: article, book, conversation, derived, manual
---

Optional, per note type:

• audio-file: path/to/memo.m4a — voice-memo notes.
• url: — clippings, web sources.
• crystallized: true — set on the source when promoted to _Canon/.
• aliases: [...] — for disambiguation.
• draft: true — excludes from Quartz publishing. Use on notes that should stay in their PARA location but must not be published (e.g., a work-related note in 4_Projects/ that isn’t sensitive enough for 6_Private/ but shouldn’t go on the public site).

Human-authored notes are exempt from the schema. The agent does not retrofit frontmatter onto existing notes except during reconcile, and only for mechanical gaps on touched pages (e.g., obvious missing created: where the filename has a date).

Privacy Classification

This vault is published publicly via Quartz. Every note the agent creates or edits must be classified for privacy. When in doubt, default to private — a public note accidentally made private is a minor inconvenience; a private note accidentally published is a real problem.

What is private

Content is private if it matches any of these:

• Personal/introspective — diary entries, inner thoughts, reflections, emotions, personal goals, relationship matters, health notes.
• Professional/work-confidential — anything about employers, clients, colleagues, internal processes, meetings, work projects, compensation, or material under NDA.
• Confidential — third-party information shared in confidence, legal matters, financial details.
• Copyrighted — third-party material that can’t be republished (course content, book excerpts beyond fair use).

How to make a note private

Two mechanisms, choose based on fit:

1. Route to 6_Private/ — for content that is inherently private (personal reflections, work-confidential material, copyrighted content). Use the same subfolder conventions already present (e.g., 6_Private/Zettel/, 6_Private/Memo/, employer-specific folders).
2. Add draft: true to frontmatter — for content that belongs in its PARA location for graph connectivity but must not be published. Good for: a project note with some sensitive detail, a resource page that references confidential work, mixed-sensitivity topics.

Rules

• Default private when uncertain. If routing is ambiguous on the privacy axis, route to 6_Private/ or add draft: true. Log the decision in 7_Agent/log.md.
• Never move notes out of 6_Private/ without explicit user approval.
• Cross-references are fine. A public note may wikilink to a private note — Quartz simply won’t resolve the link. The graph connection still works in Obsidian.
• Don’t retroactively classify existing notes. The agent only classifies notes it creates or substantially edits. Existing human-authored notes are left as-is.

Multilang Rules

German, English, and Japanese all appear in this vault. Rules keep the graph queryable while preserving content fidelity.

• Body text: in the source language. Do not translate.
• Wikilinks and note filenames: English where possible. If the concept is language-specific (a Japanese grammar point, a German idiom), use the source-language term as the filename and add an English alias.
• Structural headings (## Summary, ## References): English.
• Tags: English, lowercase-kebab.
• lang: frontmatter: de, en, ja, or mixed.

Furigana

When writing furigana in Japanese notes, use the novel syntax: 長い｜文章《ぶんしょう》. The Furigana plugin renders this correctly in view mode.

Three-Op Protocol

All agent activity in this vault reduces to three operations. Each is implemented as a skill in 7_Agent/skills/.

Ingest — process-inbox

New source → 10–15 pages touched out. process-inbox drains the entire 0_Inbox/ (root, notes/, Clippings/, and transcripts/).

0. If 0_Inbox/transcripts/ has files, invoke the audio-inbox skill for each — it cleans them and drops the result into 0_Inbox/ root.
1. Pick an item from 0_Inbox/ (root, notes/, or Clippings/).
2. Decide the route (PARA folder + filename). If ambiguous, leave the item in inbox and log the reason in 7_Agent/log.md.
3. Create the canonical note with proper frontmatter.
4. Update 10–15 related pages with cross-refs (wikilinks, backlinks, index entries). Aim for graph enrichment, not one-hop linking.
5. Update the relevant index note in 1_Home/ if one exists.
6. Append to 7_Agent/log.md.
7. Delete the inbox item.

Query — conversational, with log-question on gaps

When the user asks something:

1. Search the vault first. Synthesize with page citations ([[wikilinks]]).
2. If the answer is not derivable from the vault, invoke log-question to append to 7_Agent/questions.md, then answer from outside knowledge with that flagged.
3. If an answer is reusable (novel synthesis, research, a concept worth keeping), offer to file it as a new page. Explorations compound.

Reconcile — reconcile (weekly)

Integration pass over the last 7 days. Scoped to the diff, not the corpus — a full-vault health check doesn’t work at this vault’s size.

1. Run vault-tree + recent-changes to frame the week’s touched set.
2. Per touched page: check integration (outbound links, PARA fit, collisions with other touched pages, missing cross-refs within the page).
3. Route candidates: promotions to crystallize, merges to consolidate, moves to a rename-impact check.
4. Synthesize: cluster touched pages by topic, propose concept pages, cross-check against questions.md for answered/raised questions.
5. Write report to 7_Agent/reconcile/<YYYY-Www>-reconcile.md.
6. Append a summary entry to 7_Agent/log.md.
7. Append a single notification to 7_Agent/notifications.md linking to the report.

Notifications — notifications.md + triage

7_Agent/notifications.md is the agent’s notification center for the human — a pruned feed of high-signal items the human should see. Two kinds of items:

• Action items (- [ ] …) — require human judgment (review reconcile findings, approve a merge, decide on a promotion).
• FYI items (- …) — just notifying; no action required (a topic cluster grew, an idea got implemented, a question got answered).

The point is to guarantee the human never misses anything noteworthy — not just things that need approval.

Who writes to it:

• Non-interactive agent runs — Claude Code routines, scheduled triggers, or any session where the agent can’t prompt the user. Skills that normally propose-and-wait (crystallize, consolidate) must instead append an action item to notifications.md when invoked non-interactively.
• Batch-output skills — reconcile always appends an action item linking to its weekly report, regardless of session type, because the report is inherently a deferred-review artifact.
• Any skill that surfaces something noteworthy — even from an interactive session — may append an FYI item if the human would want to know about it later (a successful crystallize, a pattern noticed, etc.). Use sparingly; high-value only.

Who drains it: the triage skill. Runs interactively, walks each item with the user, delegates to the right skill for action items (crystallize, consolidate, direct edit), and dismisses FYIs after the user has seen them.

Format:

- [ ] YYYY-MM-DD — <action>: <one-line message> → [[link to source]]      # action item
- YYYY-MM-DD — <fyi>: <one-line message> → [[link to source]]             # fyi item

Link, don’t duplicate — the source file has the detail. A full reconcile report is linked as one item, not expanded into per-finding items.

Pruning: items are deleted when actioned (action items) or dismissed (FYIs), not struck through. log.md is the history; notifications.md is only what’s still outstanding. This keeps the feed readable and prevents duplicate-information bloat.

Interactive vs. non-interactive: in a normal conversational session, skills ask the user directly for action items — no queue needed. FYIs may still be appended for anything the user would want to revisit later.

Git Workflow

• obsidian-git auto-commits to main every few minutes (vault backup: YYYY-MM-DD HH:MM:SS).
• Agent skills edit files directly and let obsidian-git persist. No agent branches, no PRs.
• Rollback = git revert on the relevant commit. Keep it simple.

Scheduled routines (daily process-inbox, weekly reconcile) may wrap skill runs in their own branch/merge logic at the routine level — skills themselves stay git-unaware.

Publishing (Quartz)

• Vault is published at https://alexanderweichart.de via Quartz, which runs from outside this repository.
• Excluded from publishing:
  • 0_Inbox/**
  • 7_Agent/**
  • 6_Private/** — unconditional. Covers personal, copyrighted, and work-confidential content (see Directory Structure).
  • Any note with draft: true in frontmatter.
• Exclusion rules must be applied wherever the Quartz build reads from — not in this repo.

Obsidian CLI

• The obsidian CLI is available for inspecting vault state from the command line. If the command isn’t installed in a given environment, don’t try to install it — skip and proceed with filesystem tools.
• When the user refers to “this article” or “this note” without further context, assume they mean the focused open note (obsidian read).

Guidelines

• Treat this as a database of markdown notes. No build steps, no compilation, no tests.
• Strict Obsidian markdown formatting. Wikilinks for internal links, Markdown links for external URLs.
• Don’t translate. Preserve source language in bodies. See Multilang Rules.
• Frontmatter on every new note the agent writes. Follow the schema above.
• Never silent-merge pages. consolidate proposes; human approves.
• _Canon/ is load-bearing. Don’t promote without meeting the bar (see crystallize skill).

Skills

All skills live in 7_Agent/skills/. Agent-specific folders (.agents/skills/, .claude/skills/, future .codex/skills/, etc.) are symlinks to that directory — never duplicate a skill per agent, and never create or edit skills through a symlinked path. To add a skill or onboard a new agent, follow add-skill.

Vault-operational (three-op protocol + supporting ops):

• audio-inbox — raw transcript → structured inbox note (cleanup, concise version, filename, frontmatter).
• process-inbox — Ingest. Drains 0_Inbox/ into the wiki.
• warmup — session-start digest. Recent commits + open questions + last reconcile.
• log-question — append to 7_Agent/questions.md on query gaps.
• reconcile — weekly integration pass over the last 7 days of changes. Replaced the old whole-vault lint.
• consolidate — merge near-duplicate pages. Propose, don’t silent-merge.
• crystallize — promote high-signal pages to 2_Areas/_Canon/.
• triage — drain notifications.md interactively. Walks each item with the user, delegates to the right skill for action items, dismisses FYIs once seen.
• reflect — end-of-session reflection. Proposes routing durable, non-obvious learnings to the right destination (skill edit, AGENTS.md edit, log-question, crystallize). Stays silent by default; asks once, never silent-applies. Alternative to a memory.md junk drawer.

Meta:

• add-skill — contract for adding a new skill (where it lives, frontmatter, agent-folder symlink pattern). Read this before creating or moving a skill.

Shared utilities (portable across agents):

• vault-tree — depth-limited folder overview. Orient on structure before routing or reconciling.
• recent-changes — summarize git activity over the last N days, grouped by folder, auto-commit noise stripped.
• obsidian-markdown — Obsidian-flavored markdown dialect (wikilinks, embeds, callouts, properties).
• obsidian-cli — obsidian CLI usage.

Tips

• Audio-file notes land in 0_Inbox/ (not in PARA) until process-inbox routes them.
• If a note exists in _Canon/, it’s canonical. Prefer citing it over upstream sources.
• When in doubt about routing, leave the item in inbox and log the reason. Human resolves ambiguity; agent doesn’t guess.