OBSIDIAN_CONVENTIONS.md

skills/cowork-project-architect/OBSIDIAN_CONVENTIONS.md

1. # Obsidian Vault Conventions
3. Reference for the vault structure conventions this skill enforces. Use this when generating projects, when explaining the structure to a user, or when iterating on the convention itself.
5. ## Why an Obsidian vault structure
7. - **Bidirectional links** make project navigation discoverable. Wikilinks survive renames and feed graph view.
8. - **Frontmatter** is queryable via Dataview. Even without Dataview, it's load-bearing for Obsidian search and tag-based navigation.
9. - **Folder ordering by numeric prefix** is the only way to reliably control file explorer sort order in Obsidian.
10. - **Numbered + named folders** map cleanly to mental models: 01- is "primary content," 02- is "in progress," 03- is "done."
11. - **Underscored utility folders** (`_attachments/`, `_templates/`) sort to the bottom and stay out of the way.
12. - **Maps of Content** (MOC files) are the established Obsidian pattern for navigation. Two MOCs in this convention: CLAUDE.md (agent-facing) and 00-Index.md (human-facing).
14. ## Folder naming
16. | Prefix | Meaning | Sort order |
17. |--------|---------|------------|
18. | `00-` | Project MOC, sorts first | First |
19. | `01-` to `09-` | Primary content folders | Ordered |
20. | `10-` to `99-` | Less-frequent or archive | Late |
21. | `_` | Utility folders | Last |
22. | `.` | Hidden (`.obsidian/`, `.git/`) | Hidden |
24. Default folder set:
25. - `01-Knowledge/`: primary domain content
26. - `02-Working/`: in-progress files, scratchpad
27. - `03-Outputs/`: finished deliverables
28. - `04-Archive/`: optional, project-dependent
29. - `_attachments/`: images, PDFs, binaries
30. - `_templates/`: Obsidian note templates
32. Adapt names to project. A research project might use `01-Sources/`, `02-Notes/`, `03-Drafts/`. A code project might use `01-Specs/`, `02-Code/`, `03-Reviews/`. Pattern stays.
34. ## File naming
36. | File type | Pattern | Example |
37. |-----------|---------|---------|
38. | Root Claude reference | ALL CAPS | `CLAUDE.md`, `MEMORY.md` |
39. | Subdirectory Claude reference | `CLAUDE-[scope].md` | `CLAUDE-knowledge.md` |
40. | Project MOC | `00-Index.md` | `00-Index.md` |
41. | Sub-MOC | `[Folder]-Index.md` | `Clients-Index.md` |
42. | General notes | kebab-case | `client-onboarding.md` |
43. | Canonical references | Title-Case | `Project-Charter.md` |
44. | Templates | `[name]-template.md` | `brief-template.md` |
45. | Daily notes | `YYYY-MM-DD.md` | `2025-05-07.md` |
47. ## Frontmatter standard
49. Every `.md` file generated by this skill starts with:
51. ```yaml
52. ---
53. type: [type-tag]
54. scope: [project-root | subdirectory-name]
55. tags:
56. - [tag]
57. - [tag]
58. created: [YYYY-MM-DD]
59. updated: [YYYY-MM-DD]
60. aliases:
61. - [optional]
62. ---
63. ```
65. Required fields: `type`, `scope`, `created`, `updated`.
66. Optional fields: `tags`, `aliases`, `status` (for HEARTBEAT and similar).
68. ## Wikilinks vs. Markdown links
70. | Use case | Format |
71. |----------|--------|
72. | File-to-file in vault | `[[FILENAME]]` |
73. | With display text | `[[FILENAME\|display text]]` |
74. | Section anchor | `[[FILENAME#Section]]` |
75. | Block reference | `[[FILENAME#^block-id]]` |
76. | External web | `[text](https://url)` |
77. | Image (in vault) | `![[image.png]]` |
78. | Image (external) | `![alt](https://url)` |
80. When piping display text inside a Markdown table cell, escape the pipe: `[[FILENAME\|display]]`.
82. ## Maps of Content
84. **CLAUDE.md**: agent-facing MOC.
85. - Custom instructions body (this is what gets pasted into Cowork)
86. - Reference index of all Claude reference files in vault, including subdirectory CLAUDE-[scope].md files
88. **00-Index.md**: human-facing MOC.
89. - Project navigation
90. - Key concepts with wikilinks into `01-Knowledge/`
91. - Workflow shortcuts
92. - Tag taxonomy
94. These do not merge. They serve different audiences.
96. ## Subdirectory CLAUDE files
98. When to generate `CLAUDE-[scope].md`:
99. - Subdirectory has operational rules distinct from root
100. - Granular instructions would clutter root CLAUDE.md
101. - Specific data type or workflow lives in that folder
103. When generated, it MUST be logged in root CLAUDE.md under "Subdirectory reference files" with:
104. - Wikilink to the file
105. - One-line description of scope
106. - Trigger condition (when to read it)
108. When NOT generated, root CLAUDE.md says explicitly: "None. Root CLAUDE.md covers everything in this vault." This prevents future ambiguity.
110. ## Tag taxonomy
112. Every project seeds a tag taxonomy in [[MEMORY]]. Tags should be:
113. - Project-specific where possible (`#client-acme` not just `#client`)
114. - Hierarchical when useful (`#status/draft`, `#status/final`, `#status/archived`)
115. - Documented (every active tag has a one-line meaning in MEMORY.md)
117. Avoid single-use tags. Avoid `#todo` as a tag; use Obsidian's checkbox syntax `- [ ]` instead, which is queryable.
119. ## Plugins assumed
121. This skill produces vaults that work with vanilla Obsidian. No plugins required. Optional plugins that enhance the experience:
123. - **Templater:** for the `_templates/` folder
124. - **Dataview:** to query frontmatter (turns MEMORY.md tag taxonomy into live views)
125. - **Tasks:** better task tracking with checkboxes
126. - **Tag Wrangler:** taxonomy maintenance
128. Don't generate Dataview queries by default. They only render if the plugin is installed and the user knows it. If the user asks for them, add them.
130. ## Anti-patterns
132. - Folders without numeric prefixes (sort order becomes alphabetical, hard to control)
133. - Spaces in filenames (works in Obsidian but breaks command-line tooling)
134. - Markdown links instead of wikilinks for in-vault references
135. - Skipping frontmatter to save lines
136. - Subdirectory CLAUDE files that aren't logged in root CLAUDE.md
137. - Merging the agent-facing and human-facing MOCs
138. - Tags that duplicate folder structure (`#knowledge` for files in `01-Knowledge/`)