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}

| Phase | Component | Status |
|-------|-----------|--------|
| concept | [[threat-model]] | complete |
| concept | [[gap-analysis]] | in-progress |
| research | [[endpoint-security]] | pending |
| design | — | — |
| implementation | — | — |

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

doc-vault-project

Vault Project

Prerequisites

Directory Structure