@taejung3852/project-scaffold 0.1.0

package/skills/wiki/references/capture.md

@@ -0,0 +1,119 @@
+# wiki capture — 회의·결정 기록
+
+작업 중 발생하는 회의와 결정을 `raw/`에 저장한다.
+저장된 파일은 `ingest_status: "⏳ pending"` 상태가 되어 `/wiki ingest`가 자동으로 탐지한다.
+
+## 목차
+
+- 캡처 타입 결정
+- 정보 수집
+- raw 파일 생성
+- ingest 확인
+- 자동 devlog와 보존 규칙
+
+
+## Step 0 — 캡처 타입 결정
+
+`/wiki capture` 실행 시 타입을 확인한다.
+
+| 타입 | 트리거 | 저장 경로 |
+|---|---|---|
+| `meeting` | `/wiki capture meeting` | `raw/meetings/` |
+| `decision` | `/wiki capture decision` | `raw/decisions/` |
+
+인자가 없으면 묻는다:
+
+> "어떤 내용을 기록할까요?
+> 1. meeting — 회의·논의 내용
+> 2. decision — 아키텍처·기술 결정"
+
+dev-log는 `/wiki devlog`를 사용한다.
+
+---
+
+## Step 1 — 정보 수집
+
+### meeting 타입
+
+다음을 한 번에 묻는다:
+
+1. 회의 제목이 뭐야?
+2. 참석자가 누구야?
+3. 주요 결정 사항이 뭐야?
+4. 다음 액션 아이템이 있어?
+
+### decision 타입
+
+다음을 한 번에 묻는다:
+
+1. 결정 제목이 뭐야? (예: "DB를 PostgreSQL로 선택")
+2. 선택지가 뭐였어? (A vs B vs C)
+3. 왜 이걸 선택했어?
+4. 이 결정의 트레이드오프는?
+5. 재검토 조건이 있어? (예: "사용자 1만 명 초과 시")
+
+**decision은 ambiguity-check 적용**: `skills/wiki/references/ambiguity-check.md` 기준으로 이유와 트레이드오프가 구체적인지 확인. 모호하면 follow-up.
+
+---
+
+## Step 2 — 파일 생성
+
+**파일명 규칙:**
+- 제목에서 슬러그 생성: 공백 → `-`, 특수문자 제거, 최대 40자
+- 날짜 자동: `YYYY-MM-DD`
+
+| 타입 | 파일명 형식 |
+|---|---|
+| meeting | `raw/meetings/YYYY-MM-DD_meeting_슬러그.md` |
+| decision | `raw/decisions/YYYY-MM-DD_decision_슬러그.md` |
+
+**frontmatter 템플릿:**
+
+```yaml
+---
+title: "[제목]"
+raw_type: "[meeting|decision]"
+date: YYYY-MM-DD
+created: YYYY-MM-DD
+ingest_status: "⏳ pending"
+tags:
+  - "raw/[타입]"
+---
+```
+
+본문은 수집한 정보를 구조화해서 작성한다. 사용자 답변은 원문 그대로 유지.
+
+---
+
+## Step 3 — 확인 및 완료
+
+파일 생성 후:
+
+1. 생성된 경로와 내용 요약을 보여준다
+2. 바로 인제스트할지 묻는다:
+   - **Yes** → `/wiki ingest [파일경로]` 실행
+   - **No** → "저장 완료. `/wiki ingest` 로 나중에 처리하세요." 안내
+
+---
+
+## devlog 자동 생성 (git commit 연동)
+
+`.hooks/devlog-auto.sh` 훅이 커밋 후 다음을 수행한다:
+
+1. 커밋 메시지·변경 파일 목록 수집
+2. `raw/dev-logs/YYYY-MM-DD_dev-log_auto.md` 자동 생성 (ingest_status: "⏳ pending")
+3. 당일 두 번째 이상 커밋이면 기존 dev-log 파일에 append
+
+**일일 요약**: 하루가 끝날 때 `/wiki devlog`로 수동 보완한다.
+
+---
+
+## 규칙
+
+| 항목 | 규칙 |
+|---|---|
+| raw/ 본문 | 사용자 답변 원문 유지. 과도한 편집 금지 |
+| ingest_status | 항상 `"⏳ pending"` 으로 생성 |
+| decision ambiguity | 이유·트레이드오프 모호하면 반드시 follow-up |
+| 덮어쓰기 | 동일 파일명 존재 시 경고 후 확인 |
+| 자동 devlog | 커밋마다 raw/ 파일 생성. 직접 편집하지 않음 |

package/skills/wiki/references/clear-path.md

@@ -0,0 +1,82 @@
+# clear-path — CLEAR 경로 상세 절차
+
+`ambiguity-check.md`에서 **CLEAR** 또는 **FENCE**로 분류된 항목의 처리 절차.
+
+---
+
+## Step 1 — 두 필터 (질문 생략 여부 결정)
+
+순서대로 적용한다. **두 필터가 모두 NO일 때만 실제 질문으로 제시한다.**
+
+```text
+필터 1. Step 0.5 스캔 결과로 답할 수 있나?
+  → YES: 질문 생략. "(감지: pytest) 이걸로 확정할게요." 제시 후 확인만
+
+필터 2. 합리적인 기본값(defensible default)으로 답할 수 있나?
+  → YES: 기본값 채택. "기본값으로 [X]로 설정했어. 다르면 말해줘." 기록 후 진행
+
+→ 둘 다 NO: 진짜 질문으로 제시 (WHY 한 줄 함께)
+```
+
+**FENCE 예외:** 필터 결과와 관계없이 CLEAR 경로로 처리하되, 경계 확정을 위한 확인 질문을 정확히 1개만 제시한다. 질문을 생략하거나 2개 이상 제시하지 않는다.
+
+---
+
+## Step 2 — 평가 기준
+
+답변이 다음 조건을 **모두** 충족해야 통과다:
+
+| 조건 | 판정 기준 |
+|---|---|
+| **구체성** | 두 개발자가 동일하게 해석할 수 있는가? |
+| **실행 가능성** | 에이전트가 추가 질문 없이 따를 수 있는가? |
+| **예시 가능성** | 올바른 예와 잘못된 예를 들 수 있는가? |
+| **완결성** | 엣지케이스가 명확한가? |
+
+---
+
+## 모호한 답변 패턴 (즉시 follow-up)
+
+- **과도한 유연성**: "상황에 따라", "적절히", "필요시", "가능하면"
+- **재진술**: 질문을 그대로 돌려준 답변 ("네이밍은 읽기 쉽게")
+- **미완성**: "아직 모르겠어", "나중에 정할게"
+- **너무 짧음**: 단어 1~2개, 맥락 없는 답변
+- **과도한 일반화**: "일반적인 방식으로", "표준적으로"
+
+---
+
+## Follow-up 방식
+
+| 상황 | 전략 |
+|---|---|
+| 모호한 표현 | "'{표현}'이 구체적으로 어떤 의미야? 예시 하나만 들어줄 수 있어?" |
+| 재진술 | "그 규칙을 따를 때 어떻게 보여야 해? 올바른 예 하나만 들어줘" |
+| 미완성 | "지금 결정 안 해도 되는데, 가장 흔한 케이스 기준으로 일단 정해볼까?" |
+| 너무 짧음 | "조금 더 풀어서 말해줄 수 있어? 이유도 같이 알고 싶어" |
+
+같은 질문 반복 금지. 답변 내용을 기반으로 구체화를 유도한다.
+
+**루프 가드**: follow-up 2회 초과 후에도 모호하면 → `references/unclear-path.md`의 TBD 처리로 위임.
+
+---
+
+## 예시
+
+**네이밍 컨벤션:**
+- ❌ "읽기 쉽게 써줘" → "읽기 쉽다는 게 어떤 형식이야? snake_case? camelCase? 예시 하나만"
+- ✅ "Python이니까 변수·함수는 snake_case, 클래스는 PascalCase, 상수는 UPPER_SNAKE_CASE"
+
+**Git 컨벤션:**
+- ❌ "커밋 잘 써줘" → "커밋 메시지 형식이 어때야 해? feat:/fix: 같은 접두사가 있어?"
+- ✅ "feat:/fix:/chore: + 콜론 + 공백 + 한국어 설명. 예: feat: 로그인 기능 추가"
+
+**TDD:**
+- ❌ "테스트는 꼼꼼하게" → "꼼꼼하다는 게 커버리지 몇 %야? 단위·통합·E2E 중 어디까지?"
+- ✅ "pytest, 커버리지 80% 이상, 단위+통합까지. E2E는 나중에"
+
+---
+
+## 판정 출력
+
+- **통과 (or 필터 생략)**: 다음 서브 질문으로 진행. 별도 출력 없음.
+- **실패**: follow-up 즉시 제시. 최대 2회. 초과 시 `unclear-path.md` TBD 처리.

package/skills/wiki/references/devlog.md

@@ -0,0 +1,111 @@
+# wiki devlog — 세션 기반 개발 기록
+
+현재 세션을 먼저 분석해 초안을 만들고 확인·보완만 받는다.
+
+## 목차
+
+- 컨텍스트 자동 수집
+- devlog 초안 작성
+- 사용자 확인·보완
+- raw 파일 생성과 ingest 연결
+
+
+## Step 0 — 컨텍스트 자동 수집
+
+다음을 병렬로 수집한다:
+
+```bash
+git log --since="00:00" --oneline          # 오늘 커밋
+git diff HEAD~1 --stat 2>/dev/null         # 변경 파일 목록
+git status --short                          # 현재 상태
+```
+
+대화 컨텍스트(현재 세션에서 오간 내용)도 함께 참조한다.
+
+---
+
+## Step 1 — 에이전트가 초안 생성
+
+수집한 컨텍스트를 바탕으로 다음 5개 필드를 먼저 채운다:
+
+| 필드 | 자동 추론 방법 |
+|---|---|
+| 제목 | 오늘 커밋 메시지 + 주요 변경 파일에서 추출 |
+| 오늘 한 일 | 커밋 메시지 + 변경 파일 목록 기반 서술 |
+| 막혔던 부분 | 대화에서 "왜", "에러", "안 돼", "해결" 키워드 감지 |
+| 다음 할 일 | 대화의 미완 항목, TODO, 열린 질문 추출 |
+| 배운 것 | 대화에서 새로운 발견·결정·인사이트 추출 |
+
+추론이 불가능한 필드는 빈 칸으로 두고 Step 2에서 확인한다.
+
+---
+
+## Step 2 — 확인·보완 (추천값 포함)
+
+초안을 보여주며 각 필드를 한 번에 확인한다. 형식:
+
+```
+[devlog 초안]
+
+📌 제목: init.sh UX 개선 — 경로 입력 필수화
+✅ 오늘 한 일: Node CLI 수정, raw/ gitignore 추가, skills/wiki/SKILL.md 업데이트
+❓ 막혔던 부분: (감지 못했어. 있었어?)
+✅ 다음 할 일: devlog 스킬 추가, README 업데이트
+❓ 배운 것: (있으면 추가해줘)
+
+수정할 내용 있으면 말해줘. 없으면 그대로 저장할게.
+```
+
+- `✅` — 자신 있게 추론된 항목
+- `❓` — 확인 필요한 항목만 질문
+
+사용자가 "없어" / "그냥 저장해" 하면 빈 칸 그대로 저장한다. 억지로 채우지 않는다.
+
+---
+
+## Step 3 — 파일 생성
+
+**저장 경로:** `raw/dev-logs/YYYY-MM-DD_dev-log_슬러그.md`
+
+**슬러그 규칙:** 제목에서 추출, 공백 → `-`, 특수문자 제거, 최대 40자
+
+**frontmatter 템플릿:**
+
+```yaml
+---
+title: "[제목]"
+raw_type: "dev-log"
+date: YYYY-MM-DD
+created: YYYY-MM-DD
+ingest_status: "⏳ pending"
+tags:
+  - "raw/dev-log"
+---
+```
+
+당일 파일이 이미 존재하면 덮어쓰지 않고 `_2`, `_3` suffix를 붙인다.
+
+---
+
+## Step 4 — 완료 안내
+
+```
+저장 완료: raw/dev-logs/2026-06-19_dev-log_init-sh-ux.md
+
+바로 wiki에 반영할까? (y/n)
+```
+
+- **y** → `/wiki ingest [파일경로]` 실행
+- **n** → "나중에 `/wiki ingest`로 처리하세요." 안내
+
+---
+
+## 규칙
+
+| 항목 | 규칙 |
+|---|---|
+| 컨텍스트 우선 | 질문 전에 반드시 git log + 대화 먼저 읽기 |
+| 추천값 제시 | 확인 질문엔 항상 에이전트 추론값을 함께 보여줌 |
+| 빈 칸 허용 | 사용자가 건너뛰면 해당 필드 생략하고 저장 |
+| 원문 유지 | 사용자 답변은 편집 없이 그대로 기록 |
+| 덮어쓰기 금지 | 동일 날짜 파일 존재 시 suffix 붙이기 |

package/skills/wiki/references/ingest.md

@@ -0,0 +1,118 @@
+# wiki ingest — 원본을 wiki에 반영
+
+`raw/` 에 새로운 소스가 추가됐을 때 실행한다.
+소스를 읽고 wiki/ 전체에 통합한다. 단일 소스가 10~15개 페이지에 영향을 줄 수 있다.
+
+## 목차
+
+- 대상 raw 파일 결정
+- 소스 요약
+- wiki 페이지 생성·갱신
+- index·log·상태 동기화
+- Graphify 갱신
+
+
+## Step 0 — 대상 파일 결정
+
+**인자가 있으면**: 해당 경로를 바로 사용한다.
+
+**인자가 없으면**: `raw/` 하위 전체를 스캔하여 `ingest_status: "⏳ pending"` 인 파일을 수집한다.
+- 1개 → 바로 진행
+- 여러 개 → 목록 보여주고 선택 요청
+- 0개 → "처리할 파일이 없습니다. raw/ 에 새 파일을 추가해주세요."
+
+> raw/ 파일은 절대 수정하지 않는다. 읽기만 허용. (ingest_status 필드 제외)
+
+---
+
+## Step 1 — 소스 읽기 & 요약
+
+소스 파일을 읽고 다음 3개 섹션으로 요약한다:
+
+**핵심 내용 (Key Points)**
+- 번호 목록으로 5~8개
+
+**관련 컨벤션**
+- 이 소스가 `wiki/conventions/` 중 어떤 페이지와 연관되는지
+
+**영향받는 wiki 페이지 예상 목록**
+- 업데이트가 필요한 기존 페이지들
+
+---
+
+## Step 2 — wiki/ 반영
+
+### 2-1. 소스 요약 페이지 생성
+
+`wiki/sources/[슬러그].md` 생성:
+
+```yaml
+---
+title: "[소스 제목]"
+type: source
+tags: [관련태그]
+source_path: "raw/[경로]"
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+섹션: Key Points / 관련 컨벤션 / 영향 범위
+
+### 2-2. 관련 wiki 페이지 업데이트
+
+다음 우선순위로 관련 페이지를 업데이트한다:
+
+1. **wiki/conventions/**: 이 소스가 기존 컨벤션을 확인·수정·보완하는가?
+2. **wiki/decisions/**: 이 소스가 새로운 아키텍처 결정을 담고 있는가?
+3. **wiki/devlog/**: 개발 진행 기록이면 devlog에 반영
+4. **wiki/index.md**: 새 페이지가 생성됐으면 반드시 업데이트
+
+모순 발견 시: `> ⚠️ 모순` 블록으로 양쪽 출처 모두 표시.
+
+### 2-3. log.md 기록
+
+`wiki/log.md` 맨 위에 append:
+
+```text
+## [YYYY-MM-DD] ingest | [소스 제목]
+
+- **소스:** `raw/[경로]`
+- **생성된 페이지:** 목록
+- **업데이트된 페이지:** 목록
+- **컨벤션 변경:** 있으면 명시, 없으면 "없음"
+```
+
+### 2-4. raw/ 상태 업데이트
+
+```yaml
+ingest_status: "✅ done"
+```
+
+---
+
+## Step 3 — Graphify 그래프 갱신
+
+wiki/ 반영이 끝나면 Graphify 설치 여부를 확인한다.
+
+```bash
+command -v graphify
+```
+
+- **설치되어 있으면**: `graphify update wiki/` 를 실행해 그래프를 최신 wiki/ 상태로 동기화한다
+- **설치 안 되어 있으면**: 조용히 건너뛰지 않는다. 안내한다 — "Graphify가 설치되어 있지 않아요. wiki/ 쿼리 토큰을 최대 71.5배 절감할 수 있는 도구인데, 설치할까요? (`pip install graphifyy && graphify install`)"
+  - 설치를 원하면: 안내한 명령어로 설치 후 `graphify update wiki/` 실행
+  - 원치 않으면: 그래프 갱신 없이 ingest를 종료 (wiki/ 반영 자체는 이미 완료된 상태)
+
+---
+
+## 규칙
+
+| 항목 | 규칙 |
+|---|---|
+| raw/ 본문 | 절대 수정 금지 |
+| raw/ frontmatter | `ingest_status` 필드만 수정 허용 |
+| 모순 처리 | 덮어쓰지 말고 양쪽 인용 + ⚠️ 블록 |
+| 기존 페이지 우선 | 신규 생성보다 기존 업데이트를 먼저 검토 |
+| index.md | 새 페이지 생성 시 반드시 갱신 |
+| graphify 갱신 | 미설치 시 건너뛰지 않고 설치 여부 확인 |

package/skills/wiki/references/lint.md

@@ -0,0 +1,83 @@
+# wiki lint — wiki 품질 점검
+
+wiki/ 전체를 스캔해서 구조적 문제를 탐지한다.
+lint는 읽기 전용 — 자동 수정하지 않는다. 결과를 보고하고 사용자가 결정한다.
+
+
+## Step 1 — 전체 스캔
+
+`wiki/` 하위 전체 파일을 스캔한다.
+
+스캔 항목:
+
+| 항목 | 설명 |
+|---|---|
+| **고아 페이지** | inbound wikilink가 0개인 페이지 |
+| **깨진 wikilink** | `[[페이지명]]` 이 존재하지 않는 파일을 가리키는 경우 |
+| **누락 백링크** | A가 B를 언급하지만 B가 A를 가리키지 않는 경우 |
+| **모순 블록** | `> ⚠️ 모순` 이 있는 페이지 (미해결 상태) |
+| **stale 페이지** | `updated` 날짜가 90일 이상 지났고 소스도 없는 페이지 |
+| **frontmatter 누락** | `title`, `type`, `created`, `updated` 중 하나라도 없는 경우 |
+| **index.md 미등록** | wiki/ 에 페이지가 있지만 index.md에 없는 경우 |
+
+---
+
+## Step 2 — 결과 리포트
+
+다음 형식으로 결과를 보여준다:
+
+```text
+## /wiki lint 결과 — YYYY-MM-DD
+
+### 🔴 즉시 수정 필요
+1. [깨진 wikilink] wiki/concepts/Foo.md → [[Bar]] 없음
+2. [frontmatter 누락] wiki/projects/Baz.md — updated 필드 없음
+
+### 🟡 검토 권장
+3. [고아 페이지] wiki/concepts/Qux.md — 아무도 링크하지 않음
+4. [미해결 모순] wiki/synthesis/Alpha.md — ⚠️ 모순 블록 존재
+
+### 🟢 참고
+5. [stale] wiki/concepts/Beta.md — 120일 미업데이트
+6. [누락 백링크] wiki/projects/Gamma.md → [[Delta]] 언급하지만 역링크 없음
+
+전체: 🔴 2개 / 🟡 2개 / 🟢 2개
+```
+
+---
+
+## Step 3 — 사용자 결정 대기
+
+리포트 후 다음을 묻는다:
+
+> "어떤 항목을 수정할까요? 번호를 입력하거나(예: 1 3 5), all이면 전체, skip이면 log만 기록합니다."
+
+- 선택한 항목은 **사용자와 함께 수정** (AI가 수정안 제안 → 확인 후 적용)
+- 자동 일괄 수정은 금지
+
+---
+
+## Step 4 — log.md 기록
+
+`wiki/log.md` 맨 위에 append:
+
+```text
+## [YYYY-MM-DD] wiki-lint
+
+- **🔴 즉시 수정:** n개
+- **🟡 검토 권장:** n개
+- **🟢 참고:** n개
+- **처리 내역:** 수정한 항목 목록 또는 "skip"
+```
+
+---
+
+## 규칙
+
+| 항목 | 규칙 |
+|---|---|
+| 자동 수정 | 금지. 리포트만 한다 |
+| raw/ | 절대 스캔하지 않음 |
+| 수정 범위 | 사용자가 명시적으로 선택한 항목만 |
+| log.md | 수정 여부와 관계없이 항상 기록 |
+| 실행 주기 | 수동 실행. 자동 스케줄 없음 |

package/skills/wiki/references/query.md

@@ -0,0 +1,81 @@
+# wiki query — 프로젝트 지식 질의응답
+
+wiki/ 를 기반으로 질문에 답한다.
+좋은 답변은 wiki/synthesis/ 에 저장해 지식이 복리로 쌓이게 한다.
+
+
+## Step 0.5 — 그래프 우선 탐색
+
+`graphify-out/graph.json` 존재 여부를 확인한다.
+
+- **있으면**: 그래프에서 질문과 연관된 노드를 먼저 탐색해 관련 문서 범위를 좁힌다. 이 결과를 Step 1의 index.md 전체 스캔보다 우선한다
+- **없으면**: `command -v graphify`로 설치 여부를 확인한다
+  - **설치는 됐지만 graph.json이 없는 경우(아직 update 안 함)**: `graphify update wiki/` 실행을 제안한다. 사용자가 거절하면 Step 1로 진행
+  - **설치 자체가 안 되어 있는 경우**: 조용히 건너뛰지 않는다. 안내한다 — "Graphify를 쓰면 쿼리 토큰을 최대 71.5배 절감할 수 있어요. 설치할까요? (`pip install graphifyy && graphify install`)" 원치 않으면 Step 1(index.md 우선)로 진행
+
+---
+
+## Step 1 — index.md 먼저 읽기
+
+Step 0.5에서 충분히 좁혀지지 않았거나 Graphify를 안 쓰는 경우 여기서 진행한다.
+
+`wiki/index.md` 를 읽어 질문과 관련된 페이지를 파악한다.
+
+우선순위:
+1. `wiki/conventions/` — 컨벤션 관련 질문
+2. `wiki/decisions/` — 아키텍처 결정 관련 질문
+3. `wiki/devlog/` — 개발 진행 관련 질문
+4. `wiki/dashboard.md` — 할 일·우선순위 관련 질문
+5. `wiki/meetings/` — 회의 결정 관련 질문
+
+---
+
+## Step 2 — 관련 페이지 읽기 & 답변 합성
+
+파악한 페이지들을 읽고 답변을 합성한다.
+
+**답변 형식:**
+- 출처는 반드시 `[[페이지명]]` wikilink로 인용
+- 사실과 해석을 구분한다
+- 모순이 있으면 `> ⚠️ 모순` 블록으로 양쪽 제시
+
+**답변 유형별 형식:**
+- 컨벤션 질문 → 규칙·이유·예시 포함
+- 진행 상황 질문 → 타임라인 형식
+- 의사결정 질문 → 결정 배경과 근거 포함
+
+---
+
+## Step 3 — raw/ 보충 (필요 시)
+
+wiki/ 에 정보가 부족한 경우에만 `raw/` 를 추가로 읽는다.
+raw/ 에서 가져온 정보는 "(raw/ 직접 참조)" 표시를 붙인다.
+
+---
+
+## Step 4 — 좋은 답변은 wiki에 저장
+
+다음 조건이면 `wiki/synthesis/[슬러그].md` 로 저장한다:
+- 여러 소스를 종합했거나
+- 새로운 연결 고리를 발견했거나
+- 이 질문이 다시 올 가능성이 있으면
+
+저장 시 log.md에 기록:
+```text
+## [YYYY-MM-DD] query | [질문 요약]
+
+- **참조 페이지:** 목록
+- **Synthesis 저장:** [[페이지명]] 또는 "없음"
+```
+
+---
+
+## 규칙
+
+| 항목 | 규칙 |
+|---|---|
+| 읽기 순서 | graph.json(있으면) → index.md → wiki/ → raw/ (raw/는 최후 수단) |
+| 그래프 미설치 | 건너뛰지 않고 설치 여부 확인 후 index.md 폴백 |
+| 인용 형식 | `[[페이지명]]` wikilink 필수 |
+| raw/ | 절대 수정 금지 |
+| 답변 없을 때 | "현재 wiki에 충분한 정보가 없습니다. /wiki ingest 로 관련 소스를 추가해보세요." |