peach-wiki

peach-wiki — LLM Wiki knowledge management

A single skill applying Andrej Karpathy's LLM Wiki pattern. Both code projects and Obsidian notes are managed with the same structure (docs/wiki/).

Automatic detection logic

When the skill is invoked, it detects the current directory to determine the mode.

.obsidian 존재 → 옵시디언 모드 (DRIFT 없음)
.git 존재      → code 모드 (DRIFT 활성)
둘 다 존재     → code 모드 우선
둘 다 없음     → 일반 모드 (DRIFT 없음, wiki는 정상 동작)

Detection command:

ls -d .obsidian 2>/dev/null && echo "OBSIDIAN=true" || echo "OBSIDIAN=false"
ls -d .git 2>/dev/null && echo "GIT=true" || echo "GIT=false"

wiki storage location (same for all projects)

[프로젝트 루트 또는 옵시디언 보관소]/
└── docs/wiki/
    ├── WIKI-AGENTS.md       ← 운영 규칙 (세션 시작 시 먼저 읽기)
    ├── wiki-index.md        ← 전체 위키 카탈로그
    ├── wiki-log.md          ← 작업 타임라인 (append-only)
    ├── concepts/            ← 아키텍처 패턴·도메인 개념
    ├── entities/            ← 모듈·서비스·컴포넌트·인물·프로젝트
    ├── synthesis/           ← 데이터 흐름·의사결정·트레이드오프
    ├── sources/             ← 원본 문서 요약 (옵시디언 모드)
    └── diagrams/            ← Mermaid 다이어그램

Operation selection

Based on the user's request, execute one of the 5 operations below.

INIT — initial setup

docs/wiki/WIKI-AGENTS.mdRun when there is no .

1. preflight

# 모드 감지
ls -d .obsidian 2>/dev/null && echo "MODE=para" || echo "MODE=code"
ls -d .git 2>/dev/null && echo "GIT=true" || echo "GIT=false"

# 프로젝트 인덱스명 확정 (이후 모든 qmd 명령에 사용)
QMD_INDEX=$(basename $(pwd))
echo "QMD_INDEX=$QMD_INDEX"

# qmd 상태 확인 (named index 기준)
qmd --index "$QMD_INDEX" status 2>/dev/null

If qmd is not installed:

qmd가 미설치 상태입니다.
wiki는 동작하지만 qmd 설치 시 토큰 절약 + 검색 정확도가 크게 향상됩니다.
설치: npm install -g @tobilu/qmd

→ Recommend installation, then continue creating the wiki

qmd installed → Check whether the collection is registered in the corresponding index:
```
qmd --index "$QMD_INDEX" collection list
```

2. Register qmd collection (when qmd is installed)

--index "$QMD_INDEX" Always use the pattern. This flag fully separates the DB (~/.cache/qmd/$QMD_INDEX.sqlite) and settings (~/.config/qmd/$QMD_INDEX.yml) from the default index, so it does not touch other projects' or personal Obsidian collections.

If the collection is unregistered, register it:

# code 모드
qmd --index "$QMD_INDEX" collection add . --name "$QMD_INDEX" --mask "**/*.{ts,vue,md,sql,py,go,js}"

# 옵시디언 모드
qmd --index "$QMD_INDEX" collection add . --name "$QMD_INDEX" --mask "**/*.md"

# 컨텍스트 설명 추가 (검색 품질 핵심)
qmd --index "$QMD_INDEX" context add "qmd://$QMD_INDEX/" "프로젝트 한 줄 설명"

# 인덱싱 (해당 인덱스의 컬렉션만 처리됨)
qmd --index "$QMD_INDEX" update && qmd --index "$QMD_INDEX" embed

On Apple Silicon, if ggml_metal_library_init_from_source halt after an error, treat it as a Metal backend failure and retry with the CPU path:

QMD_LLAMA_GPU=off qmd --index "$QMD_INDEX" update
QMD_LLAMA_GPU=off qmd --index "$QMD_INDEX" embed
QMD_LLAMA_GPU=off qmd --index "$QMD_INDEX" query "키워드" -c "$QMD_INDEX" --no-rerank

Isolation principle: --index When specified, only collections registered in that index are processed. Other projects and para collections registered in the default index.sqliteare not affected at all. (Official docs: "Use separate index for different knowledge base")

Caution: --index Running plain qmd update/embedwithout --indexprocesses all collections in the default index (including the CloudStorage path). Be sure to add

3. Migrating an existing wiki

Detecting an existing wiki folder:

ls -d .wiki 2>/dev/null && echo "기존 .wiki/ 발견"
ls -d 5-Wiki 2>/dev/null && echo "기존 5-Wiki/ 발견"

If found, confirm with the user:

기존 [.wiki/ 또는 5-Wiki/]가 발견되었습니다.
docs/wiki/로 이동합니까? (기존 폴더는 백업 후 이동)
[Y/n]

If approved:

Copy the existing folder to docs/wiki/copy to
Add a .bak suffix to the existing folder name (safe backup)
Update the wiki-index.md and WIKI-AGENTS.md paths

4. Create docs/wiki/

→ references/WIKI-AGENTS-템플릿.md Generate WIKI-AGENTS.md based on → Initialize wiki-index.md, wiki-log.md → Create the concepts/, entities/, synthesis/, sources/, diagrams/ folders

5. Add wiki reference rules to AGENTS.md

프로젝트명 In place of the project name, insert the actual $QMD_INDEX value. (예: my-project, peach-www)

Add the following section to the target project's AGENTS.md (프로젝트명 → replace with the actual project name):

## wiki 참조 (필수)
코드 생성·분석 전 아래 순서를 따른다.
1. `qmd --index 프로젝트명 search "키워드" -c 프로젝트명` 으로 wiki + 소스 위치를 먼저 파악
2. 의미 검색이 꼭 필요할 때만 `qmd --index 프로젝트명 query "질문" -c 프로젝트명 --no-rerank` 사용
3. qmd 미설치 시 `docs/wiki/wiki-index.md` → 관련 페이지 직접 Read
4. `docs/wiki/`도 없으면 기존 방식대로 진행

## qmd 인덱스 (필수)
이 프로젝트의 qmd 인덱스명: `프로젝트명`
모든 qmd 명령에 `--index 프로젝트명`을 붙인다.
plain `qmd update/embed`는 다른 프로젝트 인덱스를 오염시킬 수 있으므로 금지.

qmd 사용 기준:
- 기본 검색은 `qmd search`를 사용한다 (BM25, 빠름).
- 의미 검색이 꼭 필요할 때만 `qmd query --no-rerank`를 사용한다.
- rerank가 꼭 필요하면 `-C 5`처럼 후보 수를 제한한다.
- 한 번에 여러 개의 `qmd query`를 동시에 실행하지 않는다 (CPU 경합으로 더 느려짐).

    # 기본 검색 (위치 파악)
    qmd --index 프로젝트명 search "키워드" -c 프로젝트명

    # 의미 검색 (필요 시)
    qmd --index 프로젝트명 query "질문" -c 프로젝트명 --no-rerank

    # 인덱스 갱신
    qmd --index 프로젝트명 update && qmd --index 프로젝트명 embed

6. Create the project overview page

docs/wiki/entities/project-overview.md Create (after identifying the project structure)

7. Confirm the first ingest area with a human

8. Record in wiki-log.md

INGEST — Raw Source → add to wiki

Trigger: "ingest", "add to wiki", "document this", mention of a file/module

Procedure

source understanding — search first, when semantic search is needed query --no-rerank:

# 기본 (BM25 키워드 검색, 빠름) — named index 필수
qmd --index "$QMD_INDEX" search "모듈명 또는 키워드" -c "$QMD_INDEX"

# 의미 검색이 꼭 필요할 때만
qmd --index "$QMD_INDEX" query "질문" -c "$QMD_INDEX" --no-rerank

# rerank가 꼭 필요할 때만 후보 수 제한
qmd --index "$QMD_INDEX" query "질문" -c "$QMD_INDEX" -C 5

# qmd 미사용 시 (fallback)
# 직접 파일 Read

summary check — after a 3–5 line key summary, confirm with a human
create/update wiki page:
- code: module → entities/module-이름.md, API → entities/api-이름.md, DB → entities/schema-이름.md
- para: note → sources/YYYY-MM-DD-제목.md, person → entities/이름.md, project → entities/project-이름.md
concepts/ update — reflect architecture patterns and domain concepts
related_files path validation (code mode):
- qmd URI and actual file path may differ (hyphen vs dot, etc.)
- Before adding to related_files, ls or Globcheck that it actually exists with
- Exclude non-existent paths or correct them to accurate paths
diagrams/ creation (if needed) — visualize flow with Mermaid
wiki-index.md update + wiki-log.md record
qmd reflection (when qmd is installed):
- Always use the --index "$QMD_INDEX" pattern — prevent contamination of other indexes
- Adding, moving, or bulk-modifying files:
```
qmd --index "$QMD_INDEX" update && qmd --index "$QMD_INDEX" embed
```
- Minor text edits:
```
qmd --index "$QMD_INDEX" update
```
- Do not run if there are no changes
- $QMD_INDEXIf not in the session: QMD_INDEX=$(basename $(pwd))redeclare with

page format

---
tags: [wiki, entities|concepts|synthesis|sources|diagrams]
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [소스 파일 경로]
related_files: [직접 연관된 파일] # code 모드
---

# 제목
> 한 줄 요약

## 핵심 내용
## 연결된 위키 페이지
- [[관련 페이지]]
## 원본 소스
- `경로/파일명`

QUERY — wiki-based question answering

Triggers: "How does it work?", "Explain the flow", "The relationship between ~ and ~", "Summarize ~"

$QMD_INDEX If undeclared: QMD_INDEX=$(basename $(pwd))redeclare with

Procedure

qmd search — search first, when semantic search is needed query --no-rerank:

# 기본: 위치 파악
qmd --index "$QMD_INDEX" search "키워드" -c "$QMD_INDEX"

# 의미 검색이 꼭 필요할 때만
qmd --index "$QMD_INDEX" query "질문 내용" -c "$QMD_INDEX" --no-rerank

# rerank가 꼭 필요할 때만
qmd --index "$QMD_INDEX" query "질문 내용" -c "$QMD_INDEX" -C 5

wiki Read (fallback or augmentation):
- docs/wiki/wiki-index.md read → identify relevant pages
- Read relevant wiki pages
Answer with citations — source: file path (+ line number)

Valuable answers → propose feeding back into the wiki:

이 답변을 docs/wiki/synthesis/YYYY-MM-DD-주제.md로 저장할까요?

wiki-log.md record

DRIFT — update the wiki after detecting git changes

Triggers: "update the wiki", "reflect the changes" Active only in code mode (.git present).

$QMD_INDEX If undeclared: QMD_INDEX=$(basename $(pwd))redeclare with

Procedure

Extract the list of changed files:

git diff --name-only HEAD~1    # 마지막 커밋
git diff --name-only           # 미커밋 변경

Identify affected wiki pages:
- Search wiki pages that have the related_filesof the changed files
Update wiki pages — reflect changes, update the updated date
qmd reflection (when qmd is installed):
```
qmd --index "$QMD_INDEX" update
```
Detect new modules → propose automatic INGEST
wiki-log.md record

LINT — wiki check

Triggers: "wiki check", "lint", "document consistency check"

Check items

Drift Detection (code mode): compare git log vs wiki updated dates
Orphan Pages: pages not present in wiki-index.md
Broken Source Links: whether deleted files are referenced
Contradictions: different explanations for the same topic
Undocumented Items: things that exist in the source but have no wiki page
Template Drift: whether WIKI-AGENTS.md differs from the latest template

Report Format

## [YYYY-MM-DD] lint | [프로젝트명]
- 드리프트 위험: N개 페이지
- 고아 페이지: N개
- 깨진 링크: N개
- 미문서화: [목록]
- 권고: [조치 목록]

Core Principles

Never modify Raw Source — read only (both code and Obsidian notes)
docs/wiki/ write only under — LLM-only space
qmd search first: if installed, handle location finding with qmd searchfirst, and use qmd query --no-rerankonly when semantic search is truly needed (in a CPU environment, querytakes 6+ seconds, rerank can take 20+ seconds). Do not run multiple qmd queryat the same time.
Compounding Effect: the more you ingest, the deeper the cross-references and the higher the query quality
Language: Korean (keep code and technical terms in English)
Links: [[파일명]] Obsidian format (para), file paths (code)

qmd Main Command Reference

Append --index "$QMD_INDEX"to every command. QMD_INDEX=$(basename $(pwd))Declare at session start with.

# 상태 확인
qmd --index "$QMD_INDEX" status
qmd --index "$QMD_INDEX" collection list

# 키워드 검색 (BM25, 빠름 — 위치 파악 기본)
qmd --index "$QMD_INDEX" search "키워드" -c "$QMD_INDEX"

# 하이브리드 검색 (의미 검색 필요 시에만)
qmd --index "$QMD_INDEX" query "질문" -c "$QMD_INDEX" --no-rerank

# rerank 후보 수 제한 (rerank가 꼭 필요할 때)
qmd --index "$QMD_INDEX" query "질문" -c "$QMD_INDEX" -C 5

# 파일 경로만 출력
qmd --index "$QMD_INDEX" search "키워드" -c "$QMD_INDEX" --files

# 특정 파일 읽기
qmd --index "$QMD_INDEX" get "qmd://$QMD_INDEX/경로/파일.md"

# 인덱스 갱신 (대량 변경)
qmd --index "$QMD_INDEX" update && qmd --index "$QMD_INDEX" embed

# 인덱스 갱신 (소규모 수정)
qmd --index "$QMD_INDEX" update

About this skill

Automatic detection logic

wiki storage location (same for all projects)

Operation selection

INIT — initial setup

1. preflight

2. Register qmd collection (when qmd is installed)

3. Migrating an existing wiki

4. Create docs/wiki/

5. Add wiki reference rules to AGENTS.md

6. Create the project overview page

7. Confirm the first ingest area with a human

8. Record in wiki-log.md

INGEST — Raw Source → add to wiki

Procedure

page format

QUERY — wiki-based question answering

Procedure

DRIFT — update the wiki after detecting git changes

Procedure

LINT — wiki check

Check items

Report Format

Core Principles

qmd Main Command Reference