doc-vault-project（文档库项目）

Vault Project

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

Prerequisites

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

1. Parse project name → kebab-case slug (max 40 chars)
2. Check if projects/{slug}/ exists — if yes, abort and show existing project
3. 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"

1. Load references/index-template.md and references/frontmatter-schemas.md
2. Build _index.md with project frontmatter and empty status table
3. Write _index.md:

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

1. Re-index: qmd update && qmd embed
2. 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

1. Identify project slug and target phase (concept/research/design/implementation)
2. 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

1. If ambiguous, ask the user
2. Generate note slug (kebab-case, max 60 chars)
3. Check for duplicates in the phase directory
4. Load frontmatter schema from references/frontmatter-schemas.md
5. Build component note with type: project-component frontmatter
6. Save:

VAULT=$(notesmd-cli print-default --path-only)
# Write tool → "$VAULT/projects/{project-slug}/{phase}/{note-slug}.md"

1. Update _index.md:

- Add wikilink under the correct phase section - Update status table counts - Update components: and updated: in frontmatter

1. Re-index: qmd update && qmd embed
2. 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

1. If no project specified, list all projects:

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

1. 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

1. 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

1. Identify project and target research notes
2. If no specific notes given, search for related research:

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

1. Filter results: only notes in research/, exclude score < 0.3
2. Present candidates with scores, let user pick
3. Read project _index.md
4. Add wikilinks under ### Linked Research section:

### Linked Research

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

1. Do NOT move files — research stays in research/
2. Update updated: in frontmatter
3. Re-index: qmd update && qmd embed
4. 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

1. Find existing research notes on the topic:

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

1. Present candidates, let user confirm which notes relate
2. Run init to scaffold the project
3. Run link to wikilink the existing research notes
4. Optionally create initial component notes in concept/ if the research already covers problem definition
5. 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