# AGENTS.md - Obsidian Vault Guidelines for AI Coding Agents ## Vault Purpose This is the **midimaze** Obsidian vault: an educational knowledge base for Recording Arts & Technology, audio engineering, music theory, and computer science. Content is organized for both public educational use and personal project management. ## Critical Rule: File Placement **ALWAYS ask the user to confirm the target directory before creating any new file.** When in doubt, propose a location based on these rules: ### Public Educational Content (NOT in _Nakul) - **Audio topics** → `Audio Science/`, `Audio Discovery/`, `Microphone Techniques/`, `Mixing and Mastering/`, `Live Sound/`, `DAW Operation/`, `Gear and Plugin Guides/`, `Synthesis/` - **Computer science/programming** → `Computer Tech/Programming Languages/` - Simple language refs: Single file (e.g., `Python.md`, `Rust.md`) - Complex topics needing multiple articles: Create folder (e.g., `PureData/`, `PlugData/`) with articles inside - **Coding tools/dev** → `Computer Tech/` (subdirs: `Docker/`, `Git/`, `Obsidian/`, `Unix/`, `n8n/`, `Web Design/`, `AI/`) - **Network/infra** → `Computer Tech/Network Engineering/` or `Computer Tech/Network Command Reference/` - **Music theory/composition** → `Music Theory, Composition, and Orchestration/` - **Music business** → `Music Business/` - **Academic admin** → `Academic Resources/` ### Personal/Private Content (_Nakul folder) - **SWC work tasks** → `_Nakul/3. SWC Actions/` (with subdirs: `1. Daily and Weekly/`, `2. Beginning of Semester/`, `3. Clients/`, `4. Financial Applications/`, `5. Service Agreements/`, `6. Reviews and Reports/`, `7. End of Semester/`, `Faculty Meetings/`) - **Personal coding projects** → `_Nakul/5. Coding Actions/` (subdirs: `Obsidian/`, `Websites/`, `midimaze/`) - **Music projects** → `_Nakul/4. Music Actions/` - **Home tasks** → `_Nakul/2. Home Actions/` - **Planning documents** → Use "Planning" suffix (e.g., `SWC Actions Planning.md`, `RAT Manuals Midimaze Sync Tool Planning.md`) ## Frontmatter Standards Every new article MUST include this frontmatter block: ```yaml --- created: YYYY-MM-DDTHH:MM:SS-0700 updated: YYYY-MM-DDTHH:MM:SS-0700 edited_seconds: 0 slug: [generate random 11-char alphanumeric] tasks_status: tasks_unfinished: tasks_completed: --- ``` **Rules:** - `created`: Use current Pacific Time (PST/PDT = -0700/-0800) in ISO 8601 format - `updated`: Initially same as `created`, update on edits - `edited_seconds`: Track cumulative editing time (start at 0) - `slug`: Random lowercase alphanumeric, 11 characters (e.g., `gq6ayo74fit`) - Task fields: Leave blank unless the document tracks specific tasks **Example:** ```yaml --- created: 2025-11-02T14:23:00-0700 updated: 2025-11-02T14:23:00-0700 edited_seconds: 0 slug: x7k2m9p4qwt tasks_status: tasks_unfinished: tasks_completed: --- ``` ## MCP Server Context This vault is accessible via **Docker MCP Gateway** using the Obsidian MCP server. Agents can use: - `obsidian_get_file_contents` / `obsidian_batch_get_file_contents` - Read files - `obsidian_append_content` - Add content to existing files - `obsidian_patch_content` - Update specific sections (by heading/block/frontmatter) - `obsidian_simple_search` / `obsidian_complex_search` - Find content - `obsidian_list_files_in_vault` / `obsidian_list_files_in_dir` - Navigate structure - `obsidian_delete_file` - Remove files (requires confirmation) **When to use MCP vs direct file operations:** - Use MCP tools when explicitly working with Obsidian-specific features (wiki links, block references, dataview queries) - Use standard Read/Write/Edit tools for simple file operations within this directory - Both approaches work—prefer MCP when user mentions "Obsidian" or vault-specific features ## Nested AGENTS.md Files Subdirectories can contain their own `AGENTS.md` files for specialized context: - `_Nakul/3. SWC Actions/AGENTS.md` - Canvas API workflows, course IDs, student management automation - `_Nakul/5. Coding Actions/AGENTS.md` - Active website projects, deployment procedures, credentials locations - `Computer Tech/Programming Languages/AGENTS.md` - Language-specific style guides, example code patterns **Load nested context when:** 1. User explicitly references a planning document (e.g., "use the SWC Actions Planning structure") 2. Working deeply within a subdirectory (3+ operations in same subfolder) 3. User says "check the local guidelines" or similar ## Content Style Guidelines - **Headings:** Use sentence case, descriptive titles (e.g., `## Audio Interface Basics`, not `## Basics`) - **Links:** Use wiki-style `[[Article Name]]` for internal links - **Images:** Store in `_attachments/` subdirectory within the topic folder; reference as `![[image-name.webp]]` - **Code blocks:** Specify language (` ```python`, ` ```bash`, etc.) - **Emphasis:** Use **bold** for key terms on first mention, *italic* for emphasis - **Lists:** Use `-` for unordered, `1.` for ordered, `- [ ]` for task items - **Educational tone:** Clear, concise, example-driven; assume intermediate technical knowledge unless specified ## Workflow: Creating a New Article ### Single File vs Folder Structure **When to create a folder:** - Topic will have multiple related articles (e.g., PureData with tutorials, reference, examples) - Complex subject with subtopics (like Audio Effects/Delays/ or Audio Effects/Reverb/) **When to create a single file:** - Simple language reference or single-topic article - Standalone tutorial or guide **Examples:** - ✅ `Computer Tech/Programming Languages/Python.md` - Single file for basic language info - ✅ `Computer Tech/Programming Languages/PureData/` - Folder for multiple PureData articles - ✅ `Audio Science/Audio Effects/Delays/` - Folder with numbered sequence of delay articles ### Article Creation Steps 1. **Ask user:** "I'll create `[Article Title].md` in `[Proposed Directory]/`. Is this the correct location?" - If topic warrants multiple articles: Propose creating a folder first 2. **Generate frontmatter** with current Pacific Time (auto-detect PST -0800 or PDT -0700) and random 11-char slug 3. **Create file** with frontmatter + initial heading matching filename 4. **Confirm:** "Created `[path]` with standard frontmatter." ## Common Pitfalls - ❌ Creating files without confirming directory - ❌ Omitting frontmatter or using wrong timezone - ❌ Putting public knowledge in `_Nakul/` folder - ❌ Using generic titles like "Notes.md" or "Untitled.md" - ❌ Forgetting to update `updated` timestamp when editing existing files ## Project Context - **Owner:** Nakul Tiruviluamala (professor at Southwestern College) - **Primary use:** Teaching RA&T courses (105, 120, 122, 123, 171), maintaining studio documentation - **Secondary use:** Personal project tracking, coding workflows, knowledge management - **Publishing:** Some content published to midimaze.com (via Obsidian Publish or custom tool)