Vault Project

Manage multi-note research projects in an Obsidian vault with phased subdirectory structure.

Prerequisites

Skill Required Purpose

doc-obsidian Yes Vault CRUD via notesmd-cli + search via qmd

Directory Structure

projects/{project-slug}/ ├── _index.md # MOC: status, component links, linked research ├── concept/ # Problem definition, threat models, requirements ├── research/ # Deep dives per component, tech evaluation ├── design/ # Architecture, API design, data models └── implementation/ # Build plans, code refs, test plans

Projects live in projects/ (top-level). Separate from research/ (knowledge).

Four phases are always created. Empty dirs signal "not started yet."

Step 0: Setup

Run before every operation:

VAULT=$(notesmd-cli print-default --path-only) qmd status

If either fails, stop and tell the user to set up doc-obsidian first.

Commands

init — Scaffold New Project

Trigger: "create project {name}", "new project {name}", "project init {name}"

Workflow

• Parse project name → kebab-case slug (max 40 chars)

• Check if projects/{slug}/ exists — if yes, abort and show existing project

• Create directory structure:

VAULT=$(notesmd-cli print-default --path-only) mkdir -p "$VAULT/projects/{slug}/concept" mkdir -p "$VAULT/projects/{slug}/research" mkdir -p "$VAULT/projects/{slug}/design" mkdir -p "$VAULT/projects/{slug}/implementation"

• Load references/index-template.md and references/frontmatter-schemas.md

• Build _index.md with project frontmatter and empty status table

• Write _index.md :

Use Write tool → "$VAULT/projects/{slug}/_index.md"

• Re-index: qmd update && qmd embed

• Confirm:

Created: [[{slug}]] Path: projects/{slug}/ Phases: concept/ research/ design/ implementation/ Components: 0

add — Add Component Note

Trigger: "add {note} to project {name}", "project add {note} to {phase}"

Workflow

• Identify project slug and target phase (concept/research/design/implementation)

• If phase not specified, infer from content:

• Problem/threat/requirement → concept

• Deep dive/evaluation/comparison → research

• Architecture/API/data model → design

• Plan/code/test/deploy → implementation

• If ambiguous, ask the user

• Generate note slug (kebab-case, max 60 chars)

• Check for duplicates in the phase directory

• Load frontmatter schema from references/frontmatter-schemas.md

• Build component note with type: project-component frontmatter

• Save:

VAULT=$(notesmd-cli print-default --path-only)

Write tool → "$VAULT/projects/{project-slug}/{phase}/{note-slug}.md"

• Update _index.md :

• Add wikilink under the correct phase section

• Update status table counts

• Update components: and updated: in frontmatter

• Re-index: qmd update && qmd embed

• Confirm:

Added: [[{note-slug}]] Path: projects/{project-slug}/{phase}/{note-slug} Phase: {phase} Status: pending Project components: {N}

status — Show Project Status

Trigger: "project status", "project status {name}", "how is project {name}"

Workflow

• If no project specified, list all projects:

VAULT=$(notesmd-cli print-default --path-only) ls "$VAULT/projects/"

• For a specific project, read _index.md frontmatter and list components:

VAULT=$(notesmd-cli print-default --path-only)

Read _index.md for project metadata

List files in each phase directory

Read frontmatter status from each component

• Display:

Project: {name} Status: {project-status} Updated: {date}

Progress: 1/3 complete

link — Link Existing Research

Trigger: "link research to project {name}", "project link {note} to {name}"

Workflow

• Identify project and target research notes

• If no specific notes given, search for related research:

qmd vsearch "{project topic}" --json -n 10

• Filter results: only notes in research/ , exclude score < 0.3

• Present candidates with scores, let user pick

• Read project _index.md

• Add wikilinks under ### Linked Research section:

Linked Research

• [[existing-note]] — {brief relevance}

• Do NOT move files — research stays in research/

• Update updated: in frontmatter

• Re-index: qmd update && qmd embed

• Confirm:

Linked to [[{project}]]:

• [[note-1]] — {relevance}
• [[note-2]] — {relevance}

promote — Promote Research Topic to Project

Trigger: "promote {topic} to project", "make {topic} a project"

Workflow

• Find existing research notes on the topic:

qmd vsearch "{topic}" --json -n 15

• Present candidates, let user confirm which notes relate

• Run init to scaffold the project

• Run link to wikilink the existing research notes

• Optionally create initial component notes in concept/ if the research already covers problem definition

• Confirm:

Promoted: {topic} → [[{project}]] Linked research: {N} notes Components: {N} created

Promote does NOT move existing notes. It creates a project that references them.

Constraints

DO:

• Always run Step 0 first

• Always use fixed four phases (concept/research/design/implementation)

• Always update _index.md after adding/linking components

• Always re-index after changes

• Resolve vault path dynamically via notesmd-cli print-default --path-only

• Keep research notes in research/ — link, don't move

• Read notes before editing

DON'T:

• Create custom phases or skip phase directories

• Move existing research notes into project directories

• Create projects without _index.md

• Skip re-indexing

• Hardcode vault paths

• Auto-trigger — only respond to explicit project commands

References

• references/frontmatter-schemas.md — Frontmatter for _index.md and component notes, field rules, status transitions

• references/index-template.md — _index.md scaffold template, status table update rules, linked research format