Alex' Gardenアレックスの庭

16 min read

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/ — voice-memo transcripts pulled from Monologue (cloud app) by the fetch-monologue skill in Phase 0 of process-inbox. Each carries source: monologue and a monologue_id: UUID for provenance. Only the transcript is brought in — not Monologue’s summary (its style isn’t what this vault wants).
    • 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 — any other markdown files 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. Use Work/ as the umbrella subfolder for work-related material that isn’t tied to a single employer (e.g., general work reflections, cross-employer thoughts); use an employer-specific subfolder when one already exists (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, except the apm-vendored ones (write-in-my-voice, devlog — see 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).
  • index.md — generated file-level map of the live vault (one line per note: path | title | tags | description). Regenerated by the build-index skill (weekly via reconcile, or on demand). Grep this before blind-globbing the vault. Never edit by hand.
  • log.md — append-only operations log, current quarter only. Every process-inbox, reconcile, consolidate, crystallize, triage run appends. Rotated quarterly by reconcile into log/<YYYY-Qn>.md.
  • log/<YYYY-Qn>.md — archived quarters of the operations log. History, never edited.
  • 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.
  • monologue-processed.md — append-only dedup log of Monologue note IDs already pulled into 0_Inbox/transcripts/. Written by fetch-monologue. Never pruned — even after the resulting transcript is routed and deleted from the inbox, the ID stays here so the note is never refetched.
  • 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:

  • description: — one-line summary of the note. Cheap to write at creation time, and it feeds 7_Agent/index.md (the build-index skill prefers it over the first body line). Add it to every note the agent creates unless the title already says everything.
  • 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, transcripts/, notes/, and Clippings/).

  1. Phase 0 — invoke fetch-monologue to pull any new transcripts from Monologue (cloud app) into 0_Inbox/transcripts/. Dedup keyed on monologue_id via 7_Agent/monologue-processed.md.
  2. Pick an item from 0_Inbox/ (root, transcripts/, notes/, or Clippings/).
  3. Decide the route (PARA folder + filename). If ambiguous, leave the item in inbox and log the reason in 7_Agent/log.md. Work-related Monologue transcripts route to 6_Private/Work/ by default, or to an employer-specific subfolder if one already exists.
  4. Create the canonical note with proper frontmatter. Preserve the original body text verbatim — add structure around it (frontmatter, wikilinks, cross-ref sections) but never rewrite, summarize, or editorialize the user’s prose.
  5. Update 10–15 related pages with cross-refs (wikilinks, backlinks, index entries). Aim for graph enrichment, not one-hop linking.
  6. Update the relevant index note in 1_Home/ if one exists.
  7. Append to 7_Agent/log.md.
  8. Delete the inbox item.

Query — conversational, with log-question on gaps

When the user asks something:

  1. Search the vault first — grep 7_Agent/index.md for topic discovery, then read the actual notes. 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 in the same turn, then answer from outside knowledge with that flagged. This step is not optional — an empty questions.md means the loop is broken, not that there are no gaps.
  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. Judgment work is scoped to the diff, not the corpus; whole-corpus mechanical checks run as the deterministic vault-doctor script.

  1. Run vault-tree + recent-changes + vault-doctor to frame the week’s touched set and get the mechanical health report.
  2. Apply mechanical fixes directly (logged, no approval needed): broken wikilinks intersecting the touched set with an unambiguous target, obvious frontmatter gaps on touched pages.
  3. Per touched page: check integration (outbound links, PARA fit, collisions with other touched pages, missing cross-refs within the page).
  4. Route candidates: promotions to crystallize, merges to consolidate, moves to a rename-impact check. Three-strike rule: a promotion candidate recommended in 3 consecutive weekly reports that still meets the bar is auto-promoted (crystallize’s reconcile-invoked mode) with an FYI notification; merges always stay propose-only.
  5. Synthesize: cluster touched pages by topic, propose concept pages, cross-check against questions.md for answered/raised questions.
  6. Write report to 7_Agent/reconcile/<YYYY-Www>-reconcile.md.
  7. Append a summary entry to 7_Agent/log.md.
  8. Notify: fold any prior unwalked reconcile items in notifications.md into one rolling action item covering all outstanding weeks; prune items whose referenced files no longer exist.
  9. Housekeeping: regenerate 7_Agent/index.md (build-index); on the first run of a new quarter, rotate log.md into 7_Agent/log/<YYYY-Qn>.md.

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.

No stacking: recurring items of the same kind (weekly reconcile walk-throughs above all) must fold into one rolling item listing every outstanding instance, instead of accumulating one item per week. A 5-item backlog of identical asks is what makes the human stop triaging. Items whose referenced files no longer exist are stale — prune them (reconcile does this weekly).

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). Sole exception: the three-strike auto-promotion via reconcile — the bar check still applies, only the wait is skipped.
  • Search the live scope by default. 5_Archive/ (~1.4k stale files), 3_Resources/Japanese/ (~3.9k generated vocab helpers), and 6_Private/shinkansen-n2/ (course content) drown naive Glob/Grep in noise. Prefer grep 7_Agent/index.md for discovery; search the heavy subtrees only when the task is actually about them.

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.

Two of them are not authored here. write-in-my-voice and devlog are vendored from the apm marketplace (packages/writing) via this vault’s apm.yml, and apm install overwrites them in place. Do not edit them here — the change will be silently clobbered on the next install. Edit the source in ~/Developer/apm/packages/writing/.apm/skills/<name>/, push, then in this vault:

apm update -y && apm install     # refreshes 7_Agent/skills/{write-in-my-voice,devlog}

They are committed to this repo rather than installed globally because Claude Code cloud sessions have no access to ~/.claude/skills — anything a cloud session needs must live inside the repo. apm install only prunes files tracked in apm.lock.yaml, so the hand-authored skills below are never touched by it.

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

  • process-inbox — Ingest. Drains 0_Inbox/ into the wiki. Phase 0 calls fetch-monologue to pull new cloud transcripts in first.
  • fetch-monologue — Pulls new voice-memo transcripts from Monologue (cloud app) via its MCP server into 0_Inbox/transcripts/. Dedup via monologue-processed.md. Transcripts only, no summaries.
  • collect-quote — Captures a quote (any inbox note whose first body line starts with quote:) verbatim into 6_Private/Quotes/ as a one-quote-per-file note, and adds it to the browsable Quotes.md index. Called by process-inbox (Phase 0.7); runnable directly when the user pastes a quote: line.
  • 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.
  • write-post — draft or edit a blog post in the user’s voice. Loads reference posts from Posts (Notes-style vs. Essay-style) before writing, so drafts don’t sound like generic AI output.
  • weekly-digest — write 0-n private articles synthesizing the week’s vault activity. Runs as reconcile’s final step. Posts live in 6_Private/Digest/, grounded in actual vault content.

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.
  • build-index — regenerate 7_Agent/index.md, the file-level map of the live vault (path | title | tags | description per note). Grep it instead of blind-globbing.
  • vault-doctor — deterministic whole-vault health check (broken wikilinks, orphans, frontmatter gaps, empty files). Read-only; reconcile runs it weekly and interprets.
  • 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

  • Voice memos live in Monologue (cloud app). fetch-monologue (Phase 0 of process-inbox) pulls new transcripts into 0_Inbox/transcripts/ for routing. Audio and Monologue summaries are never imported — transcript text only.
  • Work-related Monologue transcripts route to 6_Private/Work/ by default. Use an employer-specific subfolder (e.g. 6_Private/10ten/) if one already exists for that employer.
  • Quotes: prefix an inbox note (or memo line) with quote: to collect it. process-inbox (Phase 0.7) → collect-quote strips the prefix, stores the quote verbatim in 6_Private/Quotes/, and adds it to the browsable 6_Private/Quotes/Quotes.md index. Pure-quote notes live only in the collection (no double-filing); a quote: line inside a larger memo is extracted while the memo routes normally. The collection is private (quotes can be personal or copyrighted) and exempt from the 10–15-pages enrichment target.
  • 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.

Graph View

Backlinks