type: guide id: OBS-PM-README status: active created: 2026-05-28 updated: 2026-05-28

vaultcraft

vaultcraft is a generic Obsidian-based project management vault for human and Codex collaboration.

It keeps project state in Markdown files with YAML frontmatter so the same source can be read by people, reviewed in Git, queried in Obsidian, and updated by automation.

Core Workflow

Use this flow for work that needs traceability:

Source / QA / Observation
  -> Issue
  -> Task
  -> Result / Evidence
  -> Handoff
  -> Close

Principles:

1. Do not turn every observation directly into a task.
2. Group repeated observations into cause-oriented issues.
3. Create tasks only when the next action is concrete.
4. Do not close a task without Result and Verification.
5. Record session handoff before work context is lost.
6. Keep project-specific scoring, domain terms, and test runners outside the generic core unless they are explicitly introduced as extensions.

Directory Layout

| Path | Purpose | |---|---| | 00-dashboard/ | First-read status and work views | | 05-setup/ | Project setup checks and session runbooks | | 20-issues/ | Cause-oriented issue records | | 30-tasks/ | Actionable work items | | 40-qa/ | QA rounds, intake notes, review summaries | | 50-decisions/ | ADRs and operating decisions | | 60-evidence/ | Verification artifacts and investigation summaries | | 70-handoff/ | Session-end handoffs | | 80-source-docs/ | Raw source documents and imported notes | | scripts/ | Executable automation owned by the project | | skills/ | Codex workflow instructions | | templates/ | Reusable note templates | | schemas/ | Field contracts and status policy |

Recommended Obsidian Features

• Core: Properties, Bases, Templates, Backlinks, Search
• Community: Dataview, Tasks
• Optional: Obsidian Git, Templater

Field Conventions

• Body text can be written in the team's working language.
• Frontmatter keys and enum values should stay stable and English.
• Prefer short stable IDs such as ISSUE-0001, TASK-0001, QA-0001, ADR-0001.
• Use links between related notes instead of duplicating long context.

Status Values

Issue and task status:

todo, in_progress, blocked, review, done, closed

Close reason for non-completion:

cancelled, duplicate, obsolete, wontfix, not-a-bug, out-of-scope

Root cause status:

unknown, observed, confirmed, not-a-bug

Working Rules

• Read 00-dashboard/project-status.md before starting a session.
• Check the latest handoff in 70-handoff/.
• Pick one next working target.
• Record verification evidence in the task and, when useful, in 60-evidence/.
• Keep project-specific extensions documented in 50-decisions/.

CLI (npm) 설치/사용

This repo now includes an npm executable package for initializing the vault structure.

1) 패키지 스크립트 기본

npm install
npm start

npm start runs node bin/vaultcraft.

2) 설치 없이 바로 실행

npx vaultcraft init --path ./hello/obs
npx vaultcraft skill list
npx vaultcraft maker --path ./hello/obs

npm으로 패키지 배포할 때(선택)

원하면 다음 단계로 배포 가능합니다.

npm login
npm version patch   # 또는 minor/major
npm publish --access public

원격 저장소(remote) 생성/푸시는 팀 정책으로 분리하고, 이 저장소에서는 요청한 대로 push 자동화는 넣지 않습니다.

Git 초기 설정(옵션, remote/push 없이)

현재 vault 템플릿 사용 환경 기준:

git init
git add .obsidian .obsidian/workspace.json # .obsidian 자체는 선택
git add README.md src bin assets package.json
git add <프로젝트에서 생성되는 obs 디렉토리>
git commit -m "feat: initialize obs project vault"

원하면 remote는 로컬에서 따로 연결하고, push는 팀 정책 시점에 별도 실행하면 됩니다.

3) 전역 설치 후 사용

npm install -g .
vaultcraft init --path ./hello/obs

4) vaultcraft init 동작

• hello/obs(기본) 또는 --path로 지정한 폴더에 템플릿 뼈대를 생성
• 스킬 목록을 보여주고 선택 가능 (기본은 전부 선택)
• 필요하면 vaultcraft skill add로 추가 설치 가능
• --maker 옵션으로 초기 온보딩(l-maker) 플로우를 바로 이어서 실행

예시:

vaultcraft init --path ./hello/obs --maker
vaultcraft skill add --path ./hello/obs --skills session-start,qa-issue-intake

6) GitHub 연동(요청한 repo)

원격 저장소를 origin으로 지정하려면:

git remote add origin https://github.com/Ryokuman/vaultcraft.git

초기 확인:

git remote -v

5) 리모트/푸시 정책

• 이 프로젝트는 원격 저장소 push를 자동으로 강제하지 않습니다.
• 필요한 경우 로컬 git에서 git init, git add, git commit으로 추적 운영하세요.