AGENTS

AGENTS.md

Instructions for AI coding agents (Claude, Cursor, Copilot, etc.) working in this repository.

Repository Overview

This is an Obsidian vault (personal knowledge base), not a traditional software project. There is no build system, test suite, or linting configuration. The repository contains markdown files organized as a digital garden for learning about computer architecture, systems, and machine learning.

Learning-First Collaboration (CRITICAL)

The primary goal of agents working in this vault is to help the owner LEARN, not to produce content for them.

This is a personal knowledge base. The value comes from the owner synthesizing and writing their own understanding. Agents that write finished notes undermine this goal.

Default behavior for note requests

When asked to “write a note” or “create a note” on a topic:

1. DO NOT write finished prose or complete explanations
2. DO create an atomic skeleton (see below)
3. DO ask Socratic questions to help the owner reason through the topic
4. DO offer to clarify concepts or answer specific questions as they write

Writing atomic skeleton notes

Atomic means: one concept per note. If a topic has multiple facets, create multiple linked notes—not one big note with many sections.

Anti-pattern (monolithic):

# Dogs
## Breeds
(content about breeds)
## Training
(content about training)
## Zoomies
(content about zoomies)
## Why They're Good Boys
(content about good boys)

Good pattern (hub + atomic stubs):

# dogs.md (hub)
A [[domestication|domesticated]] [[mammal]] known for loyalty, wet noses, and [[zoomies]].
 
See also: [[dog-breed]], [[dog-training]], [[why-dogs-are-good-boys]]

Then create separate atomic notes: dog-breed.md, dog-training.md, zoomies.md, why-dogs-are-good-boys.md.

Each atomic skeleton note should have:

• Proper frontmatter (title, date, tags, draft: true, aliases if applicable)
• One-line definition immediately after frontmatter
• 1-2 HTML comment prompts with Socratic questions
• Wikilinks to related concepts (existing or to-be-created)
• Minimal structure—just enough to orient the owner

Template for atomic knowledge note:

---
title: Concept Name
date: YYYY-MM-DD
tags:
  - relevant-tag
draft: true
---
 
One-line definition using [[wikilinks]] to related concepts.
 
<!-- Prompting question to guide the owner's thinking -->
 
Key points (if needed):
- Point with [[link]]
- Point with [[link]]
 
See also:
- [[related-concept]]
- [[another-concept]]

When to create multiple notes:

• The topic has distinct sub-concepts (e.g., cuda.md → cuda-arch.md, cuda-model.md)
• A section would be long enough to stand alone
• The sub-topic is referenced from multiple places

Reference examples in this vault:

• knowledge/cuda.md — hub note pointing to arch/model/platform
• knowledge/vector-databases.md — hub note linking to ANN, similarity metrics, RAG
• knowledge/llm.md — concise definition with links
• knowledge/embedding.md — atomic, two sentences

When full content IS appropriate

Only write substantial content when:

• The owner explicitly requests it (e.g., “write this for me”, “fill this in”, “just give me the full note”)
• The task is purely mechanical (fixing formatting, adding frontmatter)
• The owner asks for a specific fact or definition to unblock themselves

Coaching over drafting

• Push the owner to reason and write notes themselves
• Prefer prompts and questions (Socratic style) over producing finished prose
• If the owner seems stuck, offer an outline or a single starting sentence—not a complete note
• Celebrate incomplete/wrong drafts as part of the learning process

Build/Lint/Test Commands

None applicable. This is a content repository, not a code project.

To preview the site locally using Quartz (if configured):

npx quartz build --serve

Content Structure

Five main content areas, each with a metaphorical theme:

Directory	Theme	Purpose
knowledge/	”The thumb drive”	Interconnected technical notes (knowledge graph)
essays/	”The leather journal”	Polished long-form writing for public consumption
notes/	”The sticky notes”	WIP items, rough drafts, miscellaneous
reviews/	”The stack of papers”	Paper/article reviews (Prof. Gibbons format)
mind.md	”The smudged whiteboard”	Current thoughts and activities

Other root files: index.md (landing page), about.md (bio/contact).

Markdown Style Guidelines

Required Frontmatter

Every markdown file MUST include YAML frontmatter:

---
title: Page Title
date: YYYY-MM-DD
tags:
  - tag1
  - tag2
draft: false
---

Essential fields:

• title - Explicit page title (do not rely on filename)
• date - Creation date in YYYY-MM-DD format
• tags - Use list format, not inline array
• draft - true for WIP, false for published

Optional fields:

• aliases - Alternative names for the note
• enableToc - Set false to hide table of contents
• description - For link previews

Obsidian Flavored Markdown

Wikilinks (required for internal links):

[[page-name]]                    # Basic link
[[page-name|display text]]       # With custom display text
[[folder/page-name]]             # With path

Embeds:

![[image.png]]                   # Embed image
![[image.png|200]]               # With width constraint
![[note-name]]                   # Embed another note

Callouts (for reviews):

> [!abstract]
> 
> Summary text here.
 
> [!info]
> 
> Additional context.

Formatting Conventions

• Bold for key terms when first introduced: **Compute Unified Device Architecture**
• Use LaTeX for math: $inline$ or $$block$$
• Markdown tables for structured data
• Keep paragraphs concise; prefer bullet points for lists
• External links use standard markdown: [text](url)
• Avoid placing wikilinks (e.g. [[some-note]]) inside fenced code blocks; Obsidian will render them as plain text (not clickable). Prefer normal prose, lists, or tables for link-heavy “flows”.
• No emojis unless contextually appropriate (casual notes like mind.md are exceptions)

Naming Conventions

Files:

• Use lowercase kebab-case: cuda-thread-block.md
• Split complex topics into multiple linked notes: cuda.md → cuda-arch.md, cuda-model.md
• No spaces or special characters in filenames

Tags:

• Lowercase with hyphens: machine-learning, gpu, self
• Be consistent with existing tags

Writing Philosophy

1. Networked thought: Link extensively between notes using wikilinks
2. Atomic notes: Small, focused notes on single concepts
3. Iterative improvement: Being wrong/incomplete is acceptable
4. Public by default: Content is meant to be shareable

Content-Specific Guidelines

Knowledge Entries (knowledge/)

• Start with a one-line definition or explanation
• Link to related concepts immediately
• Use wikilinks for any mentioned concept that has (or should have) its own note
• Keep entries focused; split into sub-notes when topics grow complex

Essays (essays/)

• Longer-form, more polished writing
• Include personal voice and reflection
• Cite sources with links

Reviews (reviews/)

Follow Prof. Phil Gibbons’ format:

---
title: Paper Title (Authors, Year)
tags:
  - topic
---
**Link**: URL
 
> [!abstract]
> 
> One-line summary
 
## Three important things
 
### 1) First point
 
### 2) Second point
 
### 3) Third point
 
## Glaring deficiency
 
## Conclusion

Notes (notes/)

• WIP and rough content lives here
• Less strict formatting requirements
• Set draft: true in frontmatter until ready to publish

Agent Tasks

Agents in this vault may be asked to:

1. Provide knowledge/insights - Research and explain topics; may require extensive searching and reasoning
2. Improve writing - Clean up language, fix phrasing, improve Obsidian Markdown formatting
3. Search existing notes - Help recall information or combine multiple notes for new insights

Do’s and Don’ts

Do:

• Add frontmatter to any new file
• Use wikilinks for internal references
• Create small, focused notes
• Link liberally between concepts
• Tag content appropriately
• Maintain the metaphorical theme of each section

Don’t:

• Create large monolithic documents
• Use standard markdown links for internal references (use wikilinks)
• Forget the date field in frontmatter
• Leave notes without tags
• Use inconsistent tag formats (stick to lowercase-hyphenated)

File Validation Checklist

Before considering a file complete:

• Frontmatter present with all essential fields
• date in YYYY-MM-DD format
• tags in list format
• Internal links use wikilink syntax
• Images use embed syntax with optional size
• File named in lowercase kebab-case
• Content links to related existing notes