@crewx/doc 0.1.2 → 0.1.3

package/SKILL.md

@@ -0,0 +1,392 @@
+---
+name: doc
+description: Document management and knowledge tools. TOC extraction, section reader, frontmatter indexing, BM25 search, knowledge graph, and tag aggregation.
+version: 0.2.0
+---
+
+# Doc Skill
+
+문서 관리 및 지식 도구입니다. 마크다운 문서의 목차 추출, 섹션 읽기, 프론트매터 기반 인덱싱, BM25 검색, 문서 간 지식 그래프, 태그 집계를 제공합니다.
+
+## When to Use This Skill
+
+다음 상황에서 이 스킬을 사용하세요:
+
+- "새 문서 만들어줘" / "연구 문서 생성해줘"
+- "설계서 목차 보여줘" / "TOC 추출해줘"
+- "설계서에서 API 설계 부분만 봐줘"
+- "구현 상태 요약해줘"
+- 긴 마크다운 문서를 분석하기 전에 구조 파악이 필요할 때
+- "문서 검색해줘" / "온보딩 관련 문서 찾아줘"
+- "문서 간 관계를 보여줘" / "지식 그래프 보여줘"
+- "어떤 태그가 많이 쓰이는지 알려줘"
+- docs/ 디렉토리의 문서 현황을 한눈에 파악하고 싶을 때
+
+## Quick Start
+
+```bash
+# 새 문서 생성
+npx doc create docs/research "새 문서 제목" --tags=tag1,tag2 --category=research
+
+# 목차 추출
+npx doc toc docs/설계서.md
+
+# 특정 섹션만 추출
+npx doc section docs/설계서.md "API 설계"
+
+# 구현 상태 요약
+npx doc summary docs/설계서.md
+
+# 문서 인덱싱 (프론트매터 기반)
+npx doc index
+
+# BM25 문서 검색
+npx doc find "온보딩"
+
+# 문서 간 지식 그래프
+npx doc graph
+
+# 태그 집계
+npx doc tags
+```
+
+## Commands
+
+### create - 새 문서 생성
+
+```bash
+npx doc create <dir> "<title>" [--tags=t1,t2] [--category=cat] [--author=agent] [--body="content"]
+```
+
+지정한 디렉토리에 프론트매터가 포함된 새 마크다운 문서를 생성합니다.
+
+**인수:**
+- `dir`: 생성할 디렉토리 경로 (없으면 자동 생성)
+- `title`: 문서 제목 (파일명 슬러그로 변환됨)
+
+**옵션:**
+- `--tags=t1,t2`: 태그 목록 (쉼표 구분)
+- `--category=cat`: 카테고리 (기본값: `general`)
+- `--author=agent`: 작성자 (에이전트 ID 등)
+- `--body="내용"`: 본문 내용
+
+**파일명 규칙:**
+- 영문: kebab-case로 변환 (소문자, 공백→하이픈)
+- 한글: 그대로 유지
+- 예) `"테스트 문서"` → `테스트-문서.md`
+- 예) `"My API Design"` → `my-api-design.md`
+
+**출력 예시:**
+```
+Created: docs/research/테스트-문서.md
+```
+
+**예시:**
+```bash
+# 기본 생성
+npx doc create docs/research "테스트 문서" --tags=test --category=research
+
+# 작성자와 본문 포함
+npx doc create docs/research "API 설계서" --tags=api,design --category=design --author=core_dev --body="## 개요\n\nAPI 설계서입니다."
+```
+
+**주의:** 동일한 경로의 파일이 이미 존재하면 에러가 발생합니다.
+
+### toc - 목차 추출
+
+```bash
+npx doc toc <file> [--depth=N]
+```
+
+마크다운 파일에서 모든 헤딩(#, ##, ### 등)을 추출하여 트리 형태로 출력합니다.
+
+**옵션:**
+- `--depth=N`: 최대 헤딩 깊이 (기본값: 6)
+
+**출력 예시:**
+```
+   L1 # Aden 설계서
+   L8   ## 목차
+  L20   ## 개요
+  L22     ### 인프라
+  L32     ### 기술 스택
+```
+
+### section - 특정 섹션 추출
+
+```bash
+npx doc section <file> <heading>
+```
+
+특정 헤딩과 그 하위 내용을 추출합니다. 전체 문서를 읽지 않고 필요한 부분만 볼 때 유용합니다.
+
+**예시:**
+```bash
+# "API 설계" 섹션만 추출
+npx doc section docs/설계서.md "API 설계"
+
+# ID로 검색
+npx doc section docs/설계서.md "api-설계"
+```
+
+### status - 상태 마커와 함께 목차 보기
+
+```bash
+npx doc status <file>
+```
+
+목차를 출력하면서 각 섹션의 구현 상태를 표시합니다.
+
+**인식되는 상태 마커:**
+- ✅ / `[x]` / `구현됨` → Done
+- ❌ / `[ ]` / `미구현` → Todo
+- ⚠️ / `부분` → Partial
+- 🚧 / `진행` → WIP
+
+### summary - 구현 상태 요약
+
+```bash
+npx doc summary <file>
+```
+
+문서 전체의 구현 상태를 집계하여 요약합니다.
+
+### index - 문서 인덱싱
+
+```bash
+npx doc index [dir]
+```
+
+디렉토리 내 마크다운 파일의 프론트매터를 파싱하여 인덱싱합니다.
+
+**옵션:**
+- `dir`: 대상 디렉토리 (기본값: `docs/`)
+
+**인덱싱 조건:** 프론트매터에 `type` 또는 `summary` 중 하나 이상 있어야 인덱싱됩니다.
+
+**출력 예시:**
+```
+Indexed 17 documents from docs/
+  CLI-설계서 (design) [cli, routing, architecture] — CrewX CLI 설계서 — 라우팅 아키텍처, 빌트인 도구, 서브커맨드 확장
+  PRD (prd) [product, requirements] — 제품 요구사항 문서
+```
+
+### find - BM25 문서 검색
+
+```bash
+npx doc find <query> [dir]
+```
+
+프론트매터 기반 BM25 검색으로 관련 문서를 찾습니다.
+
+**옵션:**
+- `query`: 검색 키워드 (필수)
+- `dir`: 대상 디렉토리 (기본값: `docs/`)
+
+**필드 가중치:** `summary: 3`, `tags: 2`, `body: 1`
+
+**출력 예시:**
+```
+Found 3 results:
+  [4.52] CLI-설계서 — CrewX CLI 설계서
+  [2.31] cli-proxy-design — CLI 프록시 설계
+  [1.87] PRD — 제품 요구사항 문서
+```
+
+### graph - 문서 지식 그래프
+
+```bash
+npx doc graph [dir]
+```
+
+문서 간 관계를 자동 분석하여 지식 그래프를 생성합니다.
+
+**옵션:**
+- `dir`: 대상 디렉토리 (기본값: `docs/`)
+
+**엣지 유형 (자동 추론):**
+- `shared-tags`: 공통 태그가 있는 문서 (가중치: 0.4 + (공통태그수 - 1) × 0.1, 최대 0.8)
+- `same-category`: 같은 카테고리의 문서 (가중치: 0.2, `general` 제외)
+- `same-day`: 같은 날짜의 문서
+
+**출력 예시:**
+```
+Graph: 17 nodes, 22 edges
+Edges:
+  CLI-설계서 ↔ cli-proxy-design (shared-tags, w=0.6)
+  PRD ↔ 설계서 (same-category, w=0.2)
+```
+
+### tags - 태그 집계
+
+```bash
+npx doc tags [dir]
+```
+
+모든 문서의 태그를 수집하여 사용 빈도순으로 집계합니다.
+
+**옵션:**
+- `dir`: 대상 디렉토리 (기본값: `docs/`)
+
+**출력 예시:**
+```
+Tags (51 unique):
+  architecture: 5
+  cli: 4
+  api: 3
+```
+
+### properties - 프론트매터 속성값 조회
+
+```bash
+npx doc properties [dir]
+```
+
+문서들에서 사용된 프론트매터 속성의 고유값을 수집하여 표시합니다. 현재 `type`과 `category` 필드를 집계합니다.
+
+**옵션:**
+- `dir`: 대상 디렉토리 (기본값: `docs/`)
+
+**출력 예시:**
+```
+Frontmatter properties:
+  type: document
+  category: design, guide, prd, research
+```
+
+## Frontmatter Schema
+
+`doc index`가 인식하는 프론트매터 필드입니다. 문서 상단에 YAML 프론트매터로 작성합니다.
+
+### 필수 조건
+
+`type` 또는 `summary` 중 **하나 이상** 있어야 인덱싱됩니다.
+
+### 필드 목록
+
+| 필드 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `type` | `'document' \| 'memory'` | `'document'` | 엔트리 유형 |
+| `category` | `string` | `'general'` | 문서 분류 (design, guide, prd, research 등) |
+| `tags` | `string[]` | `[]` | 태그 목록 (kebab-case 권장) |
+| `summary` | `string` | `''` | 한 줄 요약 (index/find 출력에 표시) |
+| `date` | `string` | `''` | 날짜 (YYYY-MM-DD) |
+
+### 프론트매터 예시
+
+```yaml
+---
+type: document
+category: design
+tags: [cli, routing, architecture]
+summary: CrewX CLI 설계서 — 라우팅 아키텍처, 빌트인 도구, 서브커맨드 확장
+date: 2026-02-20
+---
+```
+
+## Document Graph Connections
+
+`doc graph`는 명시적 연결 필드 없이 **프론트매터 메타데이터로 관계를 자동 추론**합니다.
+
+### 연결이 생성되는 조건
+
+1. **공통 태그** (`shared-tags`): 두 문서가 같은 태그를 1개 이상 공유하면 연결됩니다. 공통 태그가 많을수록 가중치가 높습니다.
+2. **같은 카테고리** (`same-category`): 같은 `category`를 가진 문서는 연결됩니다. (`general`은 제외)
+3. **같은 날짜** (`same-day`): 같은 `date`를 가진 문서는 연결됩니다.
+
+### 그래프 연결을 강화하는 방법
+
+```yaml
+# 관련 문서들에 공통 태그를 부여하면 자동으로 연결됩니다
+---
+tags: [cli, routing]          # CLI-설계서
+---
+
+---
+tags: [cli, proxy]            # cli-proxy-design → 'cli' 태그로 연결
+---
+```
+
+- 태그를 **구체적이고 일관되게** 사용하면 의미 있는 연결이 생깁니다
+- 같은 `category`를 사용하면 추가 연결이 생깁니다
+- `general` 카테고리는 그래프 연결에서 제외됩니다
+
+## 추천 워크플로우
+
+### 1. 큰 설계서 분석 시
+
+```bash
+# 1. 먼저 목차 구조 파악
+npx doc toc docs/설계서.md --depth=2
+
+# 2. 관심 있는 섹션만 상세 조회
+npx doc section docs/설계서.md "정산 관리"
+```
+
+### 2. 구현 진행 상황 추적
+
+```bash
+# 상태 요약 확인
+npx doc summary docs/설계서.md
+
+# 상세 목차에서 미구현 항목 확인
+npx doc status docs/설계서.md
+```
+
+### 3. Knowledge Graph 활용
+
+```bash
+# 1. 전체 문서 현황 파악
+npx doc index
+
+# 2. 관련 문서 검색
+npx doc find "인증"
+
+# 3. 문서 간 관계 시각화
+npx doc graph
+
+# 4. 태그 분포 확인 — 분류 체계 점검
+npx doc tags
+
+# 5. 속성값 현황 — 프론트매터 일관성 검증
+npx doc properties
+```
+
+### 4. 새 문서 작성 시 프론트매터 추가
+
+```bash
+# 1. 기존 카테고리/태그 확인
+npx doc properties
+npx doc tags
+
+# 2. 적절한 프론트매터로 문서 작성
+# 3. 인덱싱 확인
+npx doc index
+```
+
+## 설계서 작성 권장사항
+
+구현 상태를 효과적으로 추적하려면 다음 형식을 사용하세요:
+
+```markdown
+## API 설계
+
+### GLD001. 혈맹 정보 조회 ❌ 미구현
+### GLD002. 혈맹 쿼터 조회 ✅ 구현됨
+### GLD003. 혈맹 설정 변경 🚧 진행중
+```
+
+또는 별도의 "구현 상태" 섹션을 만들어 테이블로 관리:
+
+```markdown
+# 구현 상태
+
+| ID | 항목 | 상태 |
+|----|------|------|
+| GLD001 | 혈맹 정보 조회 | ❌ 미구현 |
+| GLD002 | 혈맹 쿼터 조회 | ✅ 구현됨 |
+```
+
+## 의존성
+
+- `@crewx/knowledge-core`: 프론트매터 파싱, BM25 검색, 그래프 빌더

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewx/doc",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Markdown TOC extraction and section management for CrewX",
   "type": "commonjs",
   "main": "dist/src/engine.js",
@@ -12,7 +12,7 @@
     }
   },
   "bin": { "doc": "./dist/cli.js" },
-  "files": ["dist"],
+  "files": ["dist", "SKILL.md"],
   "scripts": {
     "build": "tsc",
     "dev": "ts-node cli.ts",
@@ -21,7 +21,7 @@
   "keywords": ["crewx", "markdown", "toc", "documentation"],
   "license": "MIT",
   "dependencies": {
-    "@crewx/knowledge-core": "^0.1.2"
+    "@crewx/knowledge-core": "^0.1.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",