---
name: obsidian-buildout-vault
component: obsidian
description: >-
  Vault structure conventions and buildout patterns for GMD projects.
  Covers directory hierarchy, note naming, index notes (MOC), template
  notes for synced artifacts, and tagging conventions.
type: utility
trigger-patterns:
  - vault setup
  - project structure
  - knowledge organization
category: conventions
tags:
  - obsidian
  - vault
  - structure
  - conventions
---

# Obsidian Buildout Vault

Conventions for structuring an Obsidian vault to hold GMD project artifacts.

## GMD Vault Structure

```
{vaultRoot}/
  GMD/
    Projects/
      {project-name}/
        README.md                    # Project overview (MOC)
        STATE.md                     # Synced from .planning/STATE.md
        ROADMAP.md                   # Synced from .planning/ROADMAP.md
        Phases/
          Phase-01-audit-manifest/
            CONTEXT.md               # Synced from .planning/phases/01-*/01-CONTEXT.md
            RESEARCH.md              # Synced from .planning/phases/01-*/01-RESEARCH.md
            Plans/
              01-01-SUMMARY.md       # Synced from .planning/phases/01-*/01-01-SUMMARY.md
              01-02-SUMMARY.md
              01-03-SUMMARY.md
          Phase-02-rebrand-foundation/
            CONTEXT.md
            RESEARCH.md
            Plans/
              02-01-SUMMARY.md
              ...
    Knowledge/
      Research-Notes/                # Cross-project research
      Decisions/                     # Cross-project decision log
```

## Path Mapping Rules

Source (`.planning/`) to vault path mapping:

| Source Pattern | Vault Pattern |
|----------------|---------------|
| `.planning/STATE.md` | `GMD/Projects/{project}/STATE.md` |
| `.planning/ROADMAP.md` | `GMD/Projects/{project}/ROADMAP.md` |
| `.planning/phases/{phase}/{NN}-CONTEXT.md` | `GMD/Projects/{project}/Phases/Phase-{phase}/CONTEXT.md` |
| `.planning/phases/{phase}/{NN}-RESEARCH.md` | `GMD/Projects/{project}/Phases/Phase-{phase}/RESEARCH.md` |
| `.planning/phases/{phase}/{NN-MM}-SUMMARY.md` | `GMD/Projects/{project}/Phases/Phase-{phase}/Plans/{NN-MM}-SUMMARY.md` |

## Note Naming Conventions

- Use **kebab-case** for file and directory names
- Include phase prefix for phase-specific notes (e.g., `01-01-SUMMARY.md`)
- Descriptive names that indicate content (e.g., `auth-implementation-summary.md`)
- Index notes named `README.md` or use Map of Content (MOC) pattern

## Index Notes (Map of Content)

Each project and phase should have a MOC note linking to all child notes:

### Project MOC

```markdown
---
tags:
  - gmd
  - moc
  - project
---

# {Project Name}

## Phases

- [[Phase-01-audit-manifest/CONTEXT|Phase 1: Audit & Manifest]]
- [[Phase-02-rebrand-foundation/CONTEXT|Phase 2: Rebrand Foundation]]
- ...

## Key Decisions

- [[Decisions/auth-approach|Authentication Approach]]
- ...

## Status

![[STATE]]
```

### Phase MOC

```markdown
---
tags:
  - gmd
  - moc
  - phase-04
---

# Phase 04: Design & Planning Workflows

## Context

![[CONTEXT]]

## Plans

- [[Plans/04-01-SUMMARY|Plan 01: Brainstorming Skill & Spec Reviewer]]
- [[Plans/04-02-SUMMARY|Plan 02: Visual Brainstorming Companion]]
- ...
```

## Template Notes for Synced Artifacts

Vault copies of synced artifacts get additional frontmatter:

```yaml
---
synced_from: .planning/phases/04-design-planning-workflows/04-CONTEXT.md
synced_at: 2026-04-10T06:30:00Z
tags:
  - gmd
  - phase-04
  - context
---
```

The `synced_from` field traces back to the source of truth in `.planning/`.
The `synced_at` timestamp indicates when the vault copy was last updated.

## Tagging Conventions

| Tag | Usage |
|-----|-------|
| `#gmd` | All GMD-related vault notes |
| `#phase-XX` | Notes belonging to phase XX |
| `#decision` | Decision records and rationale |
| `#research` | Research findings and analysis |
| `#summary` | Plan execution summaries |
| `#moc` | Map of Content / index notes |
| `#context` | Phase context documents |
| `#blocker` | Known blockers or concerns |

## When to Use This Skill

- Setting up a new vault for a GMD project
- Syncing `.planning/` artifacts to vault structure
- Creating index notes or MOC pages
- Organizing knowledge notes alongside project artifacts
