maskweaver 0.9.4 → 0.9.6

package/README.ko.md

@@ -1,594 +1,640 @@
-# ?렚 Maskweaver: OpenCode瑜??꾪븳 ?꾨Ц媛€ ?섎Ⅴ?뚮굹 ?꾨젅?꾩썙??
-<div align="center">
-
-<img src="docs/images/hero.png" width="800" alt="Maskweaver Hero Image">
-
-> **AI ?섎Ⅴ?뚮굹瑜??꾪븳 npm** ??OpenCode ?댁떆?ㅽ꽩?몄뿉寃??낅낫?곸씤 ?꾨Ц媛€ ?멸꺽???뷀븯?몄슂
-
-[![GitHub Release](https://img.shields.io/github/v/release/ulgerang/maskweaver?color=369eff&labelColor=black&logo=github&style=flat-square)](https://github.com/ulgerang/maskweaver/releases)
-[![License](https://img.shields.io/badge/license-MIT-white?labelColor=black&style=flat-square)](LICENSE)
-[![npm](https://img.shields.io/npm/v/maskweaver?color=ff6b35&labelColor=black&style=flat-square)](https://www.npmjs.com/package/maskweaver)
-
-[English](README.md) | [?쒓뎅??(README.ko.md)
-
-</div>
-
----
-
-## ?뵆 OpenCode ?듯빀
-
-**Maskweaver??[OpenCode](https://github.com/sst/opencode) ?앺깭怨꾩쓽 ?듭떖 援ъ꽦 ?붿냼?낅땲??**
-
-蹂??꾨줈?앺듃???낅┰?곸씤 ?쇱씠釉뚮윭由щ줈???ъ슜 媛€?ν븯吏€留? 湲곕낯?곸쑝濡?OpenCode ?먯씠?꾪듃?ㅼ씠 ?뱀젙 遺꾩빞???꾨Ц 吏€?앹쓣 媛뽰텧 ???덈룄濡??ㅺ퀎?섏뿀?듬땲??
-- **?꾨Ц媛€ ?섎Ⅴ?뚮굹 (Masks)**: ?꾩꽕?곸씤 媛쒕컻?먮뱾??泥좏븰???댁? ?쒖? YAML ?꾨줈??
-- **?ㅻ쭏???꾩엫**: OpenCode??理쒖쟻?붾맂 硫€???먯씠?꾪듃 ?뚰겕?뚮줈??
-- **?꾨줈?앺듃 硫붾え由?*: 肄붾뱶踰좎씠???꾩껜???€???섏씠釉뚮━???섎?濡좎쟻 寃€??
-- **?넅 Weave ?뚰겕?뚮줈??*: AI ?먯껜 寃€利앹씠 ?ы븿??Phase 湲곕컲 媛쒕컻.
-- **?뵕 GDC ?듯빀**: Graph-Driven Codebase 吏€?먯쑝濡?由ъ꽌移??덉쭏 ?μ긽 諛??ㅺ퀎 ?쒖젏 寃€利?寃뚯씠??異붽?.
-
----
-
-## ??Maskweaver?멸???
-
-?덉씠??而⑤뵒??踰꾧렇濡?怨좎깮 以묒씠?쇰㈃, **由??좊컻利?*媛€ 肄붾뱶瑜?遊먯??ㅻ㈃ ?쇰쭏??醫뗭쓣源뚯슂?
-
-```typescript
-// ?쇰컲 AI ?듬? ?€??..
-"肄붾뱶???좎옱???덉씠??而⑤뵒?섏씠 ?덉뒿?덈떎."
-
-// 由??좊컻利??섏????몄궗?댄듃:
-"?닿굔 硫띿껌??肄붾뱶?? 硫붾え由?諛곕━?대룄 ???쇱옏?? ?댁뀍釉붾━ 遊먮킄 - 
-而댄뙆?쇰윭媛€ 濡쒕뱶 ?쒖꽌 諛붽엥?? smp_rmb() ?곕뱺吏€, ?꾩삁 ??硫띿껌??
-???놁씠 ?ㅼ떆 ?ㅺ퀎??"
-```
-
-**Maskweaver媛€ ?닿구 媛€?ν븯寃??⑸땲??** AI ?댁떆?ㅽ꽩?몄뿉 ?꾨Ц媛€ ?섎Ⅴ?뚮굹(媛€硫?瑜??뚯썙 源딆? ?꾨찓??吏€?앷낵 ?낇듅???ш퀬諛⑹떇??遺€?ы빀?덈떎.
-
----
-
-## ?ㅼ튂
-
-### 鍮좊Ⅸ ?ㅼ튂
-
-```bash
-# npm
-npm install maskweaver
-
-# bun
-bun add maskweaver
-```
-
-### OpenCode ?뚮윭洹몄씤 ?ㅼ젙
-
-OpenCode ?ㅼ젙??異붽??섎㈃ ??
-
-**?꾩뿭** (`~/.config/opencode/opencode.json`):
-```json
-{
-  "plugin": ["maskweaver"]
-}
-```
-
-**?먮뒗 ?꾨줈?앺듃蹂?* (?꾨줈?앺듃 猷⑦듃??`opencode.json`):
-```json
-{
-  "plugin": ["maskweaver"]
-}
-```
-
-> 李멸퀬: OpenCode??npm ?⑦궎吏€瑜??대쫫?쇰줈 ?ㅼ튂?⑸땲?? `maskweaver`瑜??ъ슜?섏꽭??(`maskweaver/plugin` ?꾨떂).
-
-OpenCode媛€ ?쒖옉 ???먮룞?쇰줈 `~/.cache/opencode/node_modules/`???뚮윭洹몄씤???ㅼ튂?⑸땲??
-
-**Windows:** `%USERPROFILE%\.config\opencode\opencode.json`
-
-### ?꾨즺 ?뚮┝ ?뚮━ (?좏깮)
-
-Maskweaver???앹꽦???앸굹???몄뀡??idle ?곹깭媛€ ?섎㈃(`session.idle`) ?뚮┝ ?뚮━瑜??ъ깮?????덉뒿?덈떎.
-
-`.opencode/maskweaver.json`(?꾨줈?앺듃) ?먮뒗 `~/.config/opencode/maskweaver.json`(?꾩뿭)???ㅼ젙?섏꽭??
-
-```jsonc
-{
-  "notifications": {
-    "completionSound": {
-      "enabled": true
-    }
-  }
-}
-```
-
-?꾨젮硫?
-
-```jsonc
-{
-  "notifications": {
-    "completionSound": {
-      "enabled": false
-    }
-  }
-}
-```
-
-### ?ㅼ튂??踰꾩쟾 ?뺤씤
-
-Maskweaver 踰꾩쟾???뺤씤?섎뒗 ?щ윭 諛⑸쾿:
-
-```bash
-# CLI (?곕???
-maskweaver --version
-# ?먮뒗
-maskweaver -V
-
-# npm
-npm list maskweaver
-
-# OpenCode 梨꾪똿 ?댁뿉??# maskweaver_status ?꾧뎄瑜??ъ슜?섍굅??
-/weave-help
-```
-
-```typescript
-// ?꾨줈洹몃옒諛?諛⑹떇 (Node.js / TypeScript)
-import { VERSION } from 'maskweaver';
-console.log(VERSION); // "0.7.29"
-```
-
----
-
-## 鍮좊Ⅸ ?쒖옉
-
-### 泥??ъ슜
-
-```bash
-# AI ?댁떆?ㅽ꽩??梨꾪똿?먯꽌:
-@maskweaver 由??좊컻利?媛€硫댁쑝濡???C 肄붾뱶 由щ럭?댁쨾
-
-# ?먮뒗 ?붾??멸컙?먭쾶 ?꾩엫:
-@dummy-human 由??좊컻利?媛€硫댁쑝濡?硫€?곗뒪?덈뵫 肄붾뱶 由щ럭
-@dummy-flash "unsafe" ?ㅼ뼱媛??뚯씪 ?꾨? 李얠븘以?@dummy-premium ??紐⑤?由ъ뒪瑜?留덉씠?щ줈?쒕퉬?ㅻ줈 ?ㅺ퀎?댁쨾
-```
-
----
-
-## 湲곕뒫
-
-### ?렚 ?꾨Ц媛€ ?섎Ⅴ?뚮굹 (媛€硫?
-
-?꾩꽕?곸씤 媛쒕컻?먯쓽 ?멸꺽??AI???곸슜:
-
-```yaml
-# masks/software-engineering/linus-torvalds.yaml
-profile:
-  name: Linus Torvalds
-  expertise:
-    - 而ㅻ꼸 ?섏? ?쒖뒪???꾨줈洹몃옒諛?    - ?깅뒫 理쒖쟻??    - 硫붾え由?愿€由?諛??숈떆??  
-  thinkingStyle: |
-    ?곹뼢?? ?ㅼ슜???묎렐. ?대줎???꾨땶 肄붾뱶遺€??
-    蹂듭옟?⑥쓣 臾댁옄鍮꾪븯寃??쒓굅.
-```
-
-**?꾩옱 媛€硫?**
-- ?맕 **由??좊컻利?* - ?쒖뒪?? C, 由щ늼?? ?깅뒫
-- ?룛截?**留덊떞 ?뚯슱??* - ?꾪궎?띿쿂, 由ы뙥?좊쭅, ?⑦꽩
-- ?㎦ **耳꾪듃 踰?* - TDD, XP, ?뚯뒪??- ?쭬 **?ㅻ뱶瑜???* - ML/AI ?쒖뒪??- ?쏉툘 **???꾨툕?쇰え??* - React, ?꾨줎?몄뿏???꾪궎?띿쿂
-
-### ?쨼 ?붾??멸컙 ?쒖뒪??
-鍮꾩슜 ?⑥쑉?곸씤 硫€???먯씠?꾪듃 ?뚰겕?뚮줈?곕? ?꾪븳 ?ㅻ쭏???쒕툕?먯씠?꾪듃:
-
-| ?먯씠?꾪듃 | 紐⑤뜽 ?깃툒 | 鍮꾩슜 | 理쒖쟻 ?⑸룄 |
-|---------|----------|------|-----------|
-| `@dummy-flash` | 鍮좊쫫 | ?뮥 | ?뚯씪 寃€?? ?붿빟, 媛꾨떒???묒뾽 |
-| `@dummy-human` | 洹좏삎 | ?뮥?뮥 | 肄붾뱶 ?묒꽦, 由щ럭, ?쇰컲 ?묒뾽 |
-| `@dummy-premium` | 媛뺣젰 | ?뮥?뮥?뮥 | ?꾪궎?띿쿂, 蹂듭옟???붾쾭源?|
-
-### ?㏊ Weave ?뚰겕?뚮줈??
-**Phase 湲곕컲 媛쒕컻** ??"AI媛€ 寃€利앺븯怨? ?좎?媛€ ?뺤씤?쒕떎"
-
-Weave??Maskweaver???듭떖 ?뚰겕?뚮줈?곗엯?덈떎. ?묒뾽???뚯뒪??媛€?ν븳 Phase濡??섎늻怨? ?꾨Ц媛€ 留덉뒪?щ? ?먮룞 ?좏깮?섎ʼn, ?좎? ?꾨떖 ??援ъ“?붾맂 寃€利??④퀎瑜??쒓났?⑸땲??
-
-#### 紐낅졊??
-| 紐낅졊??| ?ㅻ챸 |
-|--------|------|
-| `/weave-init` | Weave 珥덇린??(?꾨줈?앺듃??1?? |
-| `/weave-prepare [docs]` | research + spec + plan????踰덉뿉 ?앹꽦 (??怨꾪쉷?€ ?먮룞 遺꾪븷) |
-| `/weave-refine-plan` | `tasks/plan-notes.md` 吏€?쒕Ц??active plan??諛섏쁺 |
-| `/weave-approve` | 援ы쁽 ???щ엺??怨꾪쉷 ?뱀씤(寃뚯씠?? |
-| `/weave-craft [P#]` | Phase ?ㅽ뻾 而⑦뀓?ㅽ듃/媛€?대뱶 ?앹꽦 |
-| `/build` | ?먯쑉 鍮뚮뱶 猷⑦봽 (`action=run/status/stop/list/resume/sync`) |
-| `/weave-verify` | 鍮뚮뱶/?뚯뒪??寃€利??ㅽ뻾 (?먮룞 媛먯?) |
-| `/weave-worktree ...` | git worktree 湲곕컲 蹂묐젹 ?묒뾽 愿€由?|
-| `/weave-status` | ?꾨줈?앺듃 吏꾪뻾 ?곹솴 諛??듦퀎 ?뺤씤 |
-| `/weave-agents` | ?먯씠?꾪듃 ?뚯씪 ?숆린???먮뒗 ?ㅼ젙 珥덇린??(`sync=true` / `init=true`) |
-| `/weave-troubleshoot` | 湲€濡쒕쾶 吏€??寃€??(`record=true`濡??붾（???€?? |
-| `/weave-archive` | 寃€利앸맂 蹂€寃쎌궗???꾩뭅?대툕 |
-| `/weave-help` | ?꾩?留??쒖떆 |
-
-> Tip: OpenCode 채팅에서는 위에 보이는 slash command를 사용하세요. 내부적으로는 `weave command=...` 도구 호출로 매핑됩니다.
-
-#### ?뚰겕?뚮줈??
-```
-0. INIT (1??: /weave-init
-       ??1. PLAN: /weave-prepare docs/
-    - research + spec + phase plan????踰덉뿉 ?앹꽦 (??怨꾪쉷?€ ?먮룞 遺꾪븷)
-       ??2. REFINE (?좏깮): /weave-refine-plan
-    - tasks/plan-notes.md 湲곕컲 怨꾪쉷 ?뺤젣
-       ??3. APPROVAL GATE: /weave-approve
-    - craft ?ㅽ뻾 ???꾩닔 ?뱀씤
-       ??4. CRAFT: /weave-craft
-     - Phase ?ㅽ뻾 怨꾪쉷怨??ㅼ쓬 ?≪뀡 ?덈궡 ?앹꽦
-     - 援ы쁽/寃€利???approve濡?phase ?꾨즺 泥섎━
-     - `/weave-verify`濡?鍮뚮뱶/?뚯뒪??寃€利?媛€??       ??5. HANDOFF: ?좎?媛€ UX/?섎룄 ?뺤씤 ???ㅼ쓬 Phase濡?吏꾪뻾
-```
-
-#### ?ㅼ링 AI 寃€利??쒖뒪??
-?좎??먭쾶 ?꾨떖?섍린 ?? AI媛€ ?ㅼ쓬 寃€利??덉씠?대? ?ㅽ뻾?⑸땲??
-
-| ?덉씠??| ?좏삎 | ?꾧뎄 |
-|--------|------|------|
-| 1截뤴깵 TypeCheck | 鍮뚮뱶 | `tsc --noEmit` |
-| 2截뤴깵 Lint | 鍮뚮뱶 | `eslint` |
-| 3截뤴깵 Build | 鍮뚮뱶 | `npm run build` |
-| 4截뤴깵 Unit Tests | ?뚯뒪??| `jest` / `vitest` |
-| 5截뤴깵 E2E Tests | ?뚯뒪??| **Playwright** |
-| 6截뤴깵 Screenshot | ?쒓컖 | Playwright / 釉뚮씪?곗? 罹≪쿂 |
-| 7截뤴깵 API Check | API | `fetch` ?ъ뒪 泥댄겕 |
-| 8截뤴깵 A11y | ?묎렐??| `axe-core` |
-| 0截뤴깵 GDC Check | ?ㅺ퀎 | `gdc check --machine` |
-
-#### GDC ?듯빀 (Graph-Driven Codebase)
-
-Weave??[GDC](https://github.com/ulgerang/gdc)(Graph-Driven Codebase)?€ ?듯빀?섏뼱 由ъ꽌移??덉쭏???μ긽?쒗궎怨??ㅺ퀎 ?쒖젏 寃€利?寃뚯씠?몃? 異붽??⑸땲??
-
-**由ъ꽌移?媛뺥솕:**
-- `.gdc` ?뚰겕?ㅽ럹?댁뒪 ?먮룞 媛먯?
-- GDC `stats`, `graph`, `check` 寃곌낵瑜?`tasks/research.md`???ы븿
-- 洹몃옒???ｌ? 湲곕컲 ?섏〈???곹뼢 踰붿쐞(Blast Radius) 遺꾩꽍
-- 湲곕뒫 ?ㅼ썙?쒖? 留ㅼ묶???ъ궗???꾨낫 ?몃뱶
-- ??蹂닿퀬???뱀뀡: `GDC Node Coverage`, `Dependency Blast Radius`, `Existing Spec vs Implementation Drift`, `Candidate Reuse Nodes`
-
-**Pre-Verify 寃뚯씠??**
-GDC媛€ 媛먯??섎㈃ `weave verify`?€ `weave flow`媛€ ?먮룞?쇰줈 ?ㅽ뻾:
-1. `gdc sync --machine` - ?ㅽ럺怨?援ы쁽 ?숆린??2. `gdc check --machine` - ?ㅽ럺/援ы쁽 ?쇱튂??寃€利?
-GDC check??釉붾줈???먮윭??寃€利앹쓣 以묐떒?쒗궢?덈떎(`strictVerify` 紐⑤뱶濡??ㅼ젙 媛€??.
-
-**?ㅼ젙** (`maskweaver.config.json`):
-```json
-{
-  "gdc": {
-    "enabled": "auto",
-    "strictVerify": false,
-    "autoSyncOnPrepare": true
-  }
-}
-```
-
-- `enabled`: `true` | `false` | `"auto"` (湲곕낯媛? `.gdc` ?붾젆?곕━ ?먮룞 媛먯?)
-- `strictVerify`: `true`硫?GDC check ?ㅽ뙣 ??寃€利?李⑤떒; `false`硫?寃쎄퀬 ??怨꾩냽 吏꾪뻾
-- `autoSyncOnPrepare`: `weave prepare` ??`gdc sync` ?ㅽ뻾
-
-#### 留덉뒪???먮룞 ?좏깮
-
-AI媛€ 媛??묒뾽??媛€???곹빀???꾨Ц媛€瑜??먮룞?쇰줈 ?좏깮?⑸땲??
-
-| ?묒뾽 ?좏삎 | ?먮룞 ?좏깮 留덉뒪??|
-|----------|-----------------|
-| ?꾪궎?띿쿂/?ㅺ퀎 | ?룛截?留덊떞 ?뚯슱??|
-| ?뚯뒪??TDD | ?㎦ 耳꾪듃 踰?|
-| React/?꾨줎?몄뿏??| ?쏉툘 ???꾨툕?쇰え??|
-| ?깅뒫/?쒖뒪??| ?맕 由??좊컻利?|
-| ML/AI | ?쭬 ?ㅻ뱶瑜???|
-
-#### 湲€濡쒕쾶 吏€??踰좎씠??(?꾨줈?앺듃 媛?RAG)
-
-?몃윭釉붿뒋???붾（?섏씠 ?꾩뿭?쇰줈 ?€?λ릺??紐⑤뱺 ?꾨줈?앺듃?먯꽌 怨듭쑀?⑸땲??
-
-```
-?먮윭 諛쒖깮 ??~/.maskweaver/knowledge.sqlite 寃€??    ?쒋??€ 諛쒓껄 ???붾（???곸슜 ???ъ떆??    ?붴??€ 誘몃컻寃???吏곸젒 ?닿껐 ???ν썑瑜??꾪빐 ?붾（??湲곕줉
-```
-
-### ?쭬 硫붾え由??쒖뒪??
-怨쇨굅 ?€?? 寃곗젙, 媛€硫??④낵瑜?湲곗뼲:
-
-```typescript
-import { memory } from 'maskweaver';
-
-// ?꾨줈?앺듃 吏€???몃뜳??await memory.indexFile('./docs/architecture.md', embedFn);
-
-// ?щ윭 ?꾨줈諛붿씠?붾줈 ?섎?濡좎쟻 寃€??
-const results = await memory.hybridSearch(
-  '?몄쬆?€ ?대뼸寃??묐룞?섎굹??',
-  embedding,
-  { limit: 5, minScore: 0.7 }
-);
-```
-
-**?꾨쿋???꾨줈諛붿씠??**
-- ?쬂 **Ollama** - 濡쒖뺄, ?꾨씪?대퉿 (bge-m3, nomic-embed)
-- ?쨼 **OpenAI** - text-embedding-3-large
-- ?? **VoyageAI** - 肄붾뱶 ?뱁솕 ?꾨쿋??
-- ?? **OpenRouter** - ?щ윭 ?꾨줈諛붿씠???묎렐
-- ?뱷 **Text-only** - ?꾨쿋???놁쓬, ?쒖닔 FTS5
-
-### ?뾺截?而⑦뀓?ㅽ듃 ?쒖뒪??
-?뚯씪 ?곌껐濡??κ린 ?ㅽ뻾 湲곕뒫 異붿쟻:
-
-```bash
-# 湲곕뒫 ?쒖옉
-@context start name="oauth-login" goal="OAuth2 ?뚮줈??援ы쁽"
-
-# 湲곕뒫 而⑦뀓?ㅽ듃???뚯씪 異붽?
-@context add file="src/auth/oauth.ts"
-
-# ?곹깭 ?뺤씤
-@context status
-
-# ?꾨즺 ?쒖떆
-@context done
-```
-
-### ?봽 ?뚭퀬 ?쒖뒪??
-媛??몄뀡 ??媛€硫??④낵 ?됯?:
-
-```typescript
-{
-  "trigger": "session_end",
-  "masksUsed": [
-    {
-      "name": "linus-torvalds",
-      "task": "硫€?곗뒪?덈뵫 肄붾뱶 由щ럭",
-      "effectiveness": 9.5
-    }
-  ],
-  "wellDone": ["移섎챸???덉씠??而⑤뵒??3媛?諛쒓껄"],
-  "lessons": ["由??좊컻利?媛€硫댁? ?숈떆??由щ럭???곸썡"]
-}
-```
-
----
-
-## ?벀 ?⑦궎吏€ 援ъ“
-
-Maskweaver??紐⑤뱢??exports瑜?媛€吏??⑥씪 npm ?⑦궎吏€?낅땲??
-
-```typescript
-// 湲곕낯 export - OpenCode ?뚮윭洹몄씤
-import maskweaver from 'maskweaver';
-
-// Named exports - 紐⑤뱢 ?ㅼ엫?ㅽ럹?댁뒪
-import { core, memory, context, retrospect, verify, weave } from 'maskweaver';
-
-// ?쒕툕寃쎈줈 imports - 吏곸젒 紐⑤뱢 ?묎렐
-import { hybridSearch } from 'maskweaver/memory';
-import { createFeature } from 'maskweaver/context';
-import { MaskLoader } from 'maskweaver/core';
-import { WeaveOrchestrator, GlobalKnowledge } from 'maskweaver/weave';
-```
-
-**紐⑤뱢:**
-- `maskweaver/core` - 媛€硫?濡쒕뵫, 寃€利?(YAML/JSON)
-- `maskweaver/memory` - ?꾨쿋??+ 踰≫꽣 寃€??(5媛??꾨줈諛붿씠??
-- `maskweaver/context` - 湲곕뒫 湲곕컲 ?묒뾽 異붿쟻
-- `maskweaver/verify` - 援먯감 媛€硫?肄붾뱶 由щ럭
-- `maskweaver/retrospect` - ?몄뀡 ?④낵 遺꾩꽍
-- `maskweaver/weave` - Phase 湲곕컲 媛쒕컻 ?뚰겕?뚮줈??- `maskweaver/gdc` - GDC(Graph-Driven Codebase) ?듯빀 ?좏떥由ы떚
-- `maskweaver/plugin` - OpenCode ?뚮윭洹몄씤 ?뷀듃由??ъ씤??
----
-
-## ?㏊ Weave ?ъ슜 媛€?대뱶
-
-### 0?④퀎: 珥덇린??(?꾨줈?앺듃??1??
-
-```bash
-/weave-init
-```
-
-### 1?④퀎: ?뚮옖 ?앹꽦
-
-research + spec + plan????踰덉뿉 ?앹꽦:
-
-```bash
-/weave-prepare docs/
-```
-
-洹??ㅼ쓬 怨꾪쉷???뱀씤?⑸땲??
-
-```bash
-/weave-approve
-```
-
-AI媛€ ?섑뻾?섎뒗 ?묒뾽:
-1. 寃쎈줈 ??紐⑤뱺 臾몄꽌 ?쎄린
-2. ?좎궗??怨쇨굅 ?꾨줈?앺듃瑜?硫붾え由ъ뿉??寃€??3. ?꾩슂??紐낇솗??吏덈Ц
-4. ?뱀씤???꾪븳 **Phase 怨꾪쉷??* ?쒖떆
-
-異쒕젰 ?덉떆:
-```markdown
-## ?뱥 ?ㅽ뻾 怨꾪쉷??
-### 鍮꾩쟾
-AI ?몄궗?댄듃媛€ ?ы븿???꾨???媛먯젙 ?쇨린 ??援ъ텞
-
-### Phase 怨꾪쉷
-| Phase | ?대쫫 | ?꾨즺 議곌굔 | ?덉긽 ?쒓컙 |
-|-------|------|----------|----------|
-| P1 | 媛먯젙 ?좏깮 UI | ?좎?媛€ 媛먯젙???좏깮?????덉쓬 | 2-3?쒓컙 |
-| P2 | ?곗씠???€??| 媛먯젙???ㅽ넗由ъ????€?λ맖 | 2-3?쒓컙 |
-| P3 | ?덉뒪?좊━ 酉?| ?좎?媛€ 怨쇨굅 湲곕줉??蹂????덉쓬 | 2-3?쒓컙 |
-
-??怨꾪쉷??愿쒖갖?쇱꽭?? 蹂€寃쎌씠 ?꾩슂?섎㈃ 留먯??댁＜?몄슂.
-```
-
-### 2?④퀎: 怨꾪쉷 ?뱀씤(?꾩닔)
-
-```bash
-/weave-approve
-```
-
-### 3?④퀎: Phase ?ㅽ뻾 怨꾪쉷 ?앹꽦 (Craft)
-
-?뱀씤 ???ㅽ뻾 ?쒖옉:
-
-```bash
-/weave-craft
-```
-
-`/weave-craft`??phase ?ㅽ뻾 而⑦뀓?ㅽ듃瑜??앹꽦?⑸땲??phase 誘몄??????ㅼ쓬 phase ?먮룞 ?좏깮). 援ы쁽 諛섏쁺 ??媛숈? 紐낅졊?쇰줈 怨꾪쉷???ㅼ떆 ?뺤씤?????덉뒿?덈떎.
-
-### 4?④퀎: 援ы쁽 吏꾪뻾
-
-```txt
-weave command=craft phaseId="P1"
-weave command=verify
-```
-
-?먯쑉 鍮뚮뱶 猷⑦봽:
-
-```txt
-weave command=build action=run phaseIds="P1,P2"
-```
-
-### 5?④퀎: Phase ?꾨즺 泥섎━
-
-```txt
-weave command=verify
-weave command=approve
-```
-
-### 6?④퀎: ?몃뱶?ㅽ봽 & 寃€利?
-紐⑤뱺 寃€利앹씠 ?듦낵?섎㈃:
-
-```markdown
-## ??Phase P1 寃€利??꾨즺!
-
-### ?쨼 AI ?뚯뒪??寃곌낵
-| ?뚯뒪??| 寃곌낵 |
-|--------|------|
-| Build | ???깃났 |
-| Unit Tests | ??15/15 |
-| Lint | ???듦낵 |
-
-### ?렚 ?ъ슜??留덉뒪??- 耳꾪듃 踰?(?뚯뒪??
-- ???꾨툕?쇰え??(React 而댄룷?뚰듃)
-
-### ?뵕 ?묒냽
-http://localhost:5173
-
-### ?뫀 ?щ엺留??먮떒 媛€?ν븳 寃?- [ ] ?먮굦???섎룄?€濡쒖씤媛€??
-- [ ] ?ъ슜?깆씠 醫뗭?媛€??
-- [ ] ?먰븯??湲곕뒫??留욌굹??
-
-**[?뱀씤]** **[蹂€寃??붿껌]** **[?섏쨷??**
-```
-
-### 6?④퀎: ?몄젣?좎? ?곹깭 ?뺤씤
-
-```bash
-/weave-status
-```
-
-異쒕젰:
-```markdown
-## ?뱤 Weave 吏꾪뻾 ?곹솴
-
-**?꾨줈?앺듃**: 媛먯젙 ?쇨린 ??**吏꾪뻾瑜?*: 40%
-
-[?댿뻽?댿뻽?댿뻽?댿뻽?묅뼇?묅뼇?묅뼇?묅뼇?묅뼇?묅뼇] 2/5
-
-### Phases
-??**P1**: 媛먯젙 ?좏깮 UI (2.5h) [kent-beck, dan-abramov]
-?봽 **P2**: ?곗씠???€????**P3**: ?덉뒪?좊━ 酉???**P4**: ?듦퀎
-??**P5**: ?뚮쭏 ?ㅼ젙
-
-### 湲€濡쒕쾶 吏€???듦퀎
-- 珥??몃윭釉붿뒋??湲곕줉: 47媛?- ???꾨줈?앺듃?먯꽌 ?쒖슜: 3媛?- ?덈줈 湲곕줉?? 1媛?```
-
----
-
-## ?렚 媛€硫?留뚮뱾湲?
-媛€硫댁? 媛꾨떒??YAML ?뚯씪?낅땲??
-
-```yaml
-# masks/my-expert.yaml
-metadata:
-  id: my-expert
-  version: '1.0'
-  language: ko
-
-profile:
-  name: ?먯씠???щ툕?덉씠??  tagline: 而댄벂?낆쓽 ?좉뎄??- 理쒖큹???꾨줈洹몃옒癒?  
-  expertise:
-    - ?뚭퀬由ъ쬁 ?ㅺ퀎
-    - ?섑븰???ш퀬
-    - ?댁꽍 湲곌?
-  
-  thinkingStyle: |
-    ?섑븰???꾨??④낵 ?쒖쟻 ?곸긽?μ쓣 寃고빀?⑸땲??
-    ?ㅻⅨ ?щ엺?ㅼ씠 ?볦튂???⑦꽩??遊낅땲??
-
-behavior:
-  systemPrompt: |
-    ?뱀떊?€ 理쒖큹??而댄벂???꾨줈洹몃옒癒??먯씠???щ툕?덉씠?ㅼ엯?덈떎.
-    
-    ?뚭퀬由ъ쬁???쒕줈 遊낅땲??- ?곗븘?섍퀬, ?뺥솗?섍퀬, ?꾨쫫?듦쾶.
-    ?섑븰??蹂€?섍낵 ?쇰━???먮쫫??愿€?먯뿉???앷컖?⑸땲??
-  
-  communicationStyle:
-    tone: ?щ젮源딆?
-    verbosity: ?곷떦??    technicalDepth: ?꾨Ц媛€
-
-usage:
-  suitableFor:
-    - ?뚭퀬由ъ쬁 ?ㅺ퀎 諛?理쒖쟻??    - ?섑븰??臾몄젣 ?닿껐
-    - 肄붾뱶???⑦꽩 ?몄떇
-```
-
----
-
-## ?뙇 ?ㅺ뎅??
-吏€??以€鍮??꾨즺:
-- ?눣?눡 ?곸뼱
-- ?눖?눟 ?쒓뎅??- ?눊?눛 以묎뎅??*(以€鍮꾩쨷)*
-- ?눓?눝 ?쇰낯??*(以€鍮꾩쨷)*
-
-媛€硫댁? ?щ윭 ?몄뼱 踰꾩쟾??媛€吏????덉뒿?덈떎:
-```
-masks/
-?쒋??€ linus-torvalds.en.yaml
-?쒋??€ linus-torvalds.ko.yaml
-?붴??€ linus-torvalds.zh.yaml
-```
-
----
-
-## ?쩃 湲곗뿬?섍린
-
-?꾩????꾩슂?⑸땲??
-
-### 媛€硫?異붽?
-
-`masks/`??YAML ?뚯씪??留뚮뱾怨?PR???쒖텧?섏꽭??
-- ???ㅼ젣 ?꾨Ц??(?꾨찓??吏€??
-- ???낇듅???멸꺽 (?ш퀬 諛⑹떇)
-- ??紐낇솗???ъ슜 ?щ? (?몄젣 ?ъ슜?좎?)
-- ???덉떆 (?덉긽 ?숈옉)
-
-### 踰꾧렇 由ы룷??
-?ㅼ쓬 ?댁슜?쇰줈 ?댁뒋瑜??댁뼱二쇱꽭??
-1. 臾댁뾿???쒕룄?덈뒗吏€
-2. 臾댁뒯 ?쇱씠 ?쇱뼱?щ뒗吏€
-3. 臾댁뾿???덉긽?덈뒗吏€
-
-?먯꽭???댁슜?€ [CONTRIBUTING.md](CONTRIBUTING.md)瑜?李몄“?섏꽭??
-
----
-
-## ?뱞 ?쇱씠?좎뒪
-
-MIT - [LICENSE](LICENSE) 李몄“
-
----
-
-<p align="center">
-  <sub>?렚?€ ?④퍡 ?쒖옉 by <a href="https://github.com/ulgerang">ULJI SOFT</a></sub>
-</p>
+# 🎭 Maskweaver: OpenCode를 위한 전문가 페르소나 프레임워크
 
+<div align="center">
 
+<img src="docs/images/hero.png" width="800" alt="Maskweaver Hero Image">
+
+> **AI 페르소나를 위한 npm** — OpenCode 어시스턴트에게 독보적인 전문가 인격을 더하세요
+
+[![GitHub Release](https://img.shields.io/github/v/release/ulgerang/maskweaver?color=369eff&labelColor=black&logo=github&style=flat-square)](https://github.com/ulgerang/maskweaver/releases)
+[![License](https://img.shields.io/badge/license-MIT-white?labelColor=black&style=flat-square)](LICENSE)
+[![npm](https://img.shields.io/npm/v/maskweaver?color=ff6b35&labelColor=black&style=flat-square)](https://www.npmjs.com/package/maskweaver)
+
+[English](README.md) | [한국어](README.ko.md)
+
+</div>
+
+---
+
+## 🔌 OpenCode 통합
+
+**Maskweaver는 [OpenCode](https://github.com/sst/opencode) 생태계의 핵심 구성 요소입니다.**
+
+본 프로젝트는 독립적인 라이브러리로도 사용 가능하지만, 기본적으로 OpenCode 에이전트들이 특정 분야의 전문 지식을 갖출 수 있도록 설계되었습니다:
+- **전문가 페르소나 (Masks)**: 전설적인 개발자들의 철학을 담은 표준 YAML 프로필.
+- **스마트 위임**: OpenCode에 최적화된 멀티 에이전트 워크플로우.
+- **프로젝트 메모리**: 코드베이스 전체에 대한 하이브리드 의미론적 검색.
+- **🆕 Weave 워크플로우**: AI 자체 검증이 포함된 Phase 기반 개발.
+- **🔗 GDC 통합**: Graph-Driven Codebase 지원으로 리서치 품질 향상 및 설계 시점 검증 게이트 추가.
+
+---
+
+## 왜 Maskweaver인가요?
+
+레이스 컨디션 버그로 고생 중이라면, **린 토발즈**가 코드를 봐준다면 얼마나 좋을까요?
+
+```typescript
+// 일반 AI 답변 대신...
+"코드에 잠재적 레이스 컨디션이 있습니다."
+
+// 린 토발즈 수준의 인사이트:
+"이건 멍청한 코드야. 메모리 배리어도 안 썼잖아. 어셈블리 봐봐 - 
+컴파일러가 로드 순서 바꿨어. smp_rmb() 쓰든지, 아예 이 멍청한 
+락 없이 다시 설계해."
+```
+
+**Maskweaver가 이걸 가능하게 합니다.** AI 어시스턴트에 전문가 페르소나(가면)를 씌워 깊은 도메인 지식과 독특한 사고방식을 부여합니다.
+
+---
+
+## 설치
+
+### 빠른 설치
+
+```bash
+# npm
+npm install maskweaver
+
+# bun
+bun add maskweaver
+```
+
+### OpenCode 플러그인 설정
+
+OpenCode 설정에 추가하면 끝!
+
+**전역** (`~/.config/opencode/opencode.json`):
+```json
+{
+  "plugin": ["maskweaver"]
+}
+```
+
+**또는 프로젝트별** (프로젝트 루트의 `opencode.json`):
+```json
+{
+  "plugin": ["maskweaver"]
+}
+```
+
+> 참고: OpenCode는 npm 패키지를 이름으로 설치합니다. `maskweaver`를 사용하세요 (`maskweaver/plugin` 아님).
+
+OpenCode가 시작 시 자동으로 `~/.cache/opencode/node_modules/`에 플러그인을 설치합니다.
+
+**Windows:** `%USERPROFILE%\.config\opencode\opencode.json`
+
+### 완료 알림 소리 (선택)
+
+Maskweaver는 생성이 끝나서 세션이 idle 상태가 되면(`session.idle`) 알림 소리를 재생할 수 있습니다.
+
+`.opencode/maskweaver.json`(프로젝트) 또는 `~/.config/opencode/maskweaver.json`(전역)에 설정하세요:
+
+```jsonc
+{
+  "notifications": {
+    "completionSound": {
+      "enabled": true
+    }
+  }
+}
+```
+
+끄려면:
+
+```jsonc
+{
+  "notifications": {
+    "completionSound": {
+      "enabled": false
+    }
+  }
+}
+```
+
+### 설치된 버전 확인
+
+Maskweaver 버전을 확인하는 여러 방법:
+
+```bash
+# CLI (터미널)
+maskweaver --version
+# 또는
+maskweaver -V
+
+# npm
+npm list maskweaver
+
+# OpenCode 채팅 내에서
+# maskweaver_status 도구를 사용하거나:
+/weave-help
+```
+
+```typescript
+// 프로그래밍 방식 (Node.js / TypeScript)
+import { VERSION } from 'maskweaver';
+console.log(VERSION); // "0.7.29"
+```
+
+---
+
+## 빠른 시작
+
+### 첫 사용
+
+```bash
+# AI 어시스턴트 채팅에서:
+@maskweaver 린 토발즈 가면으로 이 C 코드 리뷰해줘
+
+# 또는 더미인간에게 위임:
+@dummy-human 린 토발즈 가면으로 멀티스레딩 코드 리뷰
+@dummy-flash "unsafe" 들어간 파일 전부 찾아줘
+@dummy-premium 이 모놀리스를 마이크로서비스로 설계해줘
+```
+
+---
+
+## 기능
+
+### 🎭 전문가 페르소나 (가면)
+
+전설적인 개발자의 인격을 AI에 적용:
+
+```yaml
+# masks/software-engineering/linus-torvalds.yaml
+profile:
+  name: Linus Torvalds
+  expertise:
+    - 커널 수준 시스템 프로그래밍
+    - 성능 최적화
+    - 메모리 관리 및 동시성
+  
+  thinkingStyle: |
+    상향식, 실용적 접근. 이론이 아닌 코드부터.
+    복잡함을 무자비하게 제거.
+```
+
+**현재 가면:**
+- 🐧 **린 토발즈** - 시스템, C, 리눅스, 성능
+- 🏗️ **마틴 파울러** - 아키텍처, 리팩토링, 패턴
+- 🧪 **켄트 벡** - TDD, XP, 테스팅
+- 🧠 **앤드류 응** - ML/AI 시스템
+- ⚛️ **댄 아브라모프** - React, 프론트엔드 아키텍처
+
+### 🤖 더미인간 시스템
+
+비용 효율적인 멀티 에이전트 워크플로우를 위한 스마트 서브에이전트:
+
+| 에이전트 | 모델 등급 | 비용 | 최적 용도 |
+|---------|----------|------|-----------|
+| `@dummy-flash` | 빠름 | 💰 | 파일 검색, 요약, 간단한 작업 |
+| `@dummy-human` | 균형 | 💰💰 | 코드 작성, 리뷰, 일반 작업 |
+| `@dummy-premium` | 강력 | 💰💰💰 | 아키텍처, 복잡한 디버깅 |
+
+### 🧵 Weave 워크플로우
+
+**Phase 기반 개발** — "AI가 검증하고, 유저가 확인한다"
+
+Weave는 Maskweaver의 핵심 워크플로우입니다. 작업을 테스트 가능한 Phase로 나누고, 전문가 마스크를 자동 선택하며, 유저 전달 전 구조화된 검증 단계를 제공합니다.
+
+#### 명령어
+
+| 명령어 | 설명 |
+|--------|------|
+| `/weave-init` | Weave 초기화 (프로젝트당 1회) |
+| `/weave-prepare [docs]` | research + spec + plan을 한 번에 생성 (큰 계획은 자동 분할) |
+| `/weave-refine-plan` | `tasks/plan-notes.md` 지시문을 active plan에 반영 |
+| `/weave-approve` | 구현 전 사람이 계획 승인(게이트) |
+| `/weave-craft [P#]` | Phase 실행 컨텍스트/가이드 생성 |
+| `/build` | 자율 빌드 루프 (`action=run/status/stop/list/resume/sync`) |
+| `/weave-verify` | 빌드/테스트 검증 실행 (자동 감지) |
+| `/weave-worktree ...` | git worktree 기반 병렬 작업 관리 |
+| `/weave-status` | 프로젝트 진행 상황 및 통계 확인 |
+| `/weave-agents` | 에이전트 파일 동기화 또는 설정 초기화 (`sync=true` / `init=true`) |
+| `/weave-troubleshoot` | 글로벌 지식 검색 (`record=true`로 솔루션 저장) |
+| `/weave-archive` | 검증된 변경사항 아카이브 |
+| `/weave-help` | 도움말 표시 |
+
+> Tip: OpenCode 채팅에서는 `/weave-prepare`, `/build`처럼 실제로 보이는 slash command를 사용하고, 내부적으로는 `weave command=...` 도구 호출로 매핑됩니다.
+
+#### 워크플로우
+
+```
+0. INIT (1회): /weave-init
+       ↓
+1. PLAN: /weave-prepare docs/
+    - research + spec + phase plan을 한 번에 생성 (큰 계획은 자동 분할)
+       ↓
+2. REFINE (선택): /weave-refine-plan
+    - tasks/plan-notes.md 기반 계획 정제
+       ↓
+3. APPROVAL GATE: /weave-approve
+    - craft 실행 전 필수 승인
+       ↓
+4. CRAFT: /weave-craft
+     - Phase 실행 계획과 다음 액션 안내 생성
+     - 구현/검증 후 approve로 phase 완료 처리
+     - `/weave-verify`로 빌드/테스트 검증 가능
+       ↓
+5. HANDOFF: 유저가 UX/의도 확인 후 다음 Phase로 진행
+```
+
+#### 다층 AI 검증 시스템
+
+유저에게 전달하기 전, AI가 다음 검증 레이어를 실행합니다:
+
+| 레이어 | 유형 | 도구 |
+|--------|------|------|
+| 1️⃣ TypeCheck | 빌드 | `tsc --noEmit` |
+| 2️⃣ Lint | 빌드 | `eslint` |
+| 3️⃣ Build | 빌드 | `npm run build` |
+| 4️⃣ Unit Tests | 테스트 | `jest` / `vitest` |
+| 5️⃣ E2E Tests | 테스트 | **Playwright** |
+| 6️⃣ Screenshot | 시각 | Playwright / 브라우저 캡처 |
+| 7️⃣ API Check | API | `fetch` 헬스 체크 |
+| 8️⃣ A11y | 접근성 | `axe-core` |
+| 0️⃣ GDC Check | 설계 | `gdc check --machine` |
+
+#### GDC 통합 (Graph-Driven Codebase)
+
+Weave는 [GDC](https://github.com/ulgerang/gdc)(Graph-Driven Codebase)와 통합되어 리서치 품질을 향상시키고 설계 시점 검증 게이트를 추가합니다:
+
+**리서치 강화:**
+- `.gdc` 워크스페이스 자동 감지
+- GDC `stats`, `graph`, `check` 결과를 `tasks/research.md`에 포함
+- 그래프 엣지 기반 의존성 영향 범위(Blast Radius) 분석
+- 기능 키워드와 매칭된 재사용 후보 노드
+- 새 보고서 섹션: `GDC Node Coverage`, `Dependency Blast Radius`, `Existing Spec vs Implementation Drift`, `Candidate Reuse Nodes`
+
+**Pre-Verify 게이트:**
+GDC가 감지되면 `weave verify`와 `weave flow`가 자동으로 실행:
+1. `gdc sync --machine` - 스펙과 구현 동기화
+2. `gdc check --machine` - 스펙/구현 일치성 검증
+
+GDC check의 블로킹 에러는 검증을 중단시킵니다(`strictVerify` 모드로 설정 가능).
+
+**설정** (`maskweaver.config.json`):
+```json
+{
+  "gdc": {
+    "enabled": "auto",
+    "strictVerify": false,
+    "autoSyncOnPrepare": true
+  }
+}
+```
+
+- `enabled`: `true` | `false` | `"auto"` (기본값: `.gdc` 디렉터리 자동 감지)
+- `strictVerify`: `true`면 GDC check 실패 시 검증 차단; `false`면 경고 후 계속 진행
+- `autoSyncOnPrepare`: `weave prepare` 시 `gdc sync` 실행
+
+#### 마스크 자동 선택
+
+AI가 각 작업에 가장 적합한 전문가를 자동으로 선택합니다:
+
+| 작업 유형 | 자동 선택 마스크 |
+|----------|-----------------|
+| 아키텍처/설계 | 🏗️ 마틴 파울러 |
+| 테스트/TDD | 🧪 켄트 벡 |
+| React/프론트엔드 | ⚛️ 댄 아브라모프 |
+| 성능/시스템 | 🐧 린 토발즈 |
+| ML/AI | 🧠 앤드류 응 |
+
+#### 글로벌 지식 베이스 (프로젝트 간 RAG)
+
+트러블슈팅 솔루션이 전역으로 저장되어 모든 프로젝트에서 공유됩니다:
+
+```
+에러 발생 → ~/.maskweaver/knowledge.sqlite 검색
+    ├── 발견 → 솔루션 적용 → 재시도
+    └── 미발견 → 직접 해결 → 향후를 위해 솔루션 기록
+```
+
+### 🧠 메모리 시스템
+
+과거 대화, 결정, 가면 효과를 기억:
+
+```typescript
+import { memory } from 'maskweaver';
+
+// 프로젝트 지식 인덱싱
+await memory.indexFile('./docs/architecture.md', embedFn);
+
+// 여러 프로바이더로 의미론적 검색:
+const results = await memory.hybridSearch(
+  '인증은 어떻게 작동하나요?',
+  embedding,
+  { limit: 5, minScore: 0.7 }
+);
+```
+
+**임베딩 프로바이더:**
+- 🦙 **Ollama** - 로컬, 프라이빗 (bge-m3, nomic-embed)
+- 🤖 **OpenAI** - text-embedding-3-large
+- 🚀 **VoyageAI** - 코드 특화 임베딩!
+- 🔀 **OpenRouter** - 여러 프로바이더 접근
+- 📝 **Text-only** - 임베딩 없음, 순수 FTS5
+
+### 🗂️ 컨텍스트 시스템
+
+파일 연결로 장기 실행 기능 추적:
+
+```bash
+# 기능 시작
+@context start name="oauth-login" goal="OAuth2 플로우 구현"
+
+# 기능 컨텍스트에 파일 추가
+@context add file="src/auth/oauth.ts"
+
+# 상태 확인
+@context status
+
+# 완료 표시
+@context done
+```
+
+### 🔄 회고 시스템
+
+각 세션 후 가면 효과 평가:
+
+```typescript
+{
+  "trigger": "session_end",
+  "masksUsed": [
+    {
+      "name": "linus-torvalds",
+      "task": "멀티스레딩 코드 리뷰",
+      "effectiveness": 9.5
+    }
+  ],
+  "wellDone": ["치명적 레이스 컨디션 3개 발견"],
+  "lessons": ["린 토발즈 가면은 동시성 리뷰에 탁월"]
+}
+```
+
+---
+
+## 📦 패키지 구조
+
+Maskweaver는 모듈식 exports를 가진 단일 npm 패키지입니다:
+
+```typescript
+// 기본 export - OpenCode 플러그인
+import maskweaver from 'maskweaver';
+
+// Named exports - 모듈 네임스페이스
+import { core, memory, context, retrospect, verify, weave } from 'maskweaver';
+
+// 서브경로 imports - 직접 모듈 접근
+import { hybridSearch } from 'maskweaver/memory';
+import { createFeature } from 'maskweaver/context';
+import { MaskLoader } from 'maskweaver/core';
+import { WeaveOrchestrator, GlobalKnowledge } from 'maskweaver/weave';
+```
+
+**모듈:**
+- `maskweaver/core` - 가면 로딩, 검증 (YAML/JSON)
+- `maskweaver/memory` - 임베딩 + 벡터 검색 (5개 프로바이더)
+- `maskweaver/context` - 기능 기반 작업 추적
+- `maskweaver/verify` - 교차 가면 코드 리뷰
+- `maskweaver/retrospect` - 세션 효과 분석
+- `maskweaver/weave` - Phase 기반 개발 워크플로우
+- `maskweaver/gdc` - GDC(Graph-Driven Codebase) 통합 유틸리티
+- `maskweaver/plugin` - OpenCode 플러그인 엔트리 포인트
+
+---
+
+## 🧵 Weave 사용 가이드
+
+### 0단계: 초기화 (프로젝트당 1회)
+
+```bash
+/weave-init
+```
+
+### 1단계: 플랜 생성
+
+research + spec + plan을 한 번에 생성:
+
+```bash
+/weave-prepare docs/
+```
+
+그 다음 계획을 승인합니다:
+
+```bash
+/weave-approve
+```
+
+AI가 수행하는 작업:
+1. 경로 내 모든 문서 읽기
+2. 유사한 과거 프로젝트를 메모리에서 검색
+3. 필요시 명확화 질문
+4. 승인을 위한 **Phase 계획서** 제시
+
+출력 예시:
+```markdown
+## 📋 실행 계획서
+
+### 비전
+AI 인사이트가 포함된 현대적 감정 일기 앱 구축
+
+### Phase 계획
+| Phase | 이름 | 완료 조건 | 예상 시간 |
+|-------|------|----------|----------|
+| P1 | 감정 선택 UI | 유저가 감정을 선택할 수 있음 | 2-3시간 |
+| P2 | 데이터 저장 | 감정이 스토리지에 저장됨 | 2-3시간 |
+| P3 | 히스토리 뷰 | 유저가 과거 기록을 볼 수 있음 | 2-3시간 |
+
+이 계획이 괜찮으세요? 변경이 필요하면 말씀해주세요.
+```
+
+### 2단계: 계획 승인(필수)
+
+```bash
+/weave-approve
+```
+
+### 3단계: Phase 실행 계획 생성 (Craft)
+
+승인 후 실행 시작:
+
+```bash
+/weave-craft
+```
+
+`/weave-craft`는 phase 실행 컨텍스트를 생성합니다(phase 미지정 시 다음 phase 자동 선택). 구현 반영 후 같은 명령으로 계획을 다시 확인할 수 있습니다.
+
+### 4단계: 구현 진행
+
+```txt
+weave command=craft phaseId="P1"
+weave command=verify
+```
+
+자율 빌드 루프:
+
+```txt
+weave command=build action=run phaseIds="P1,P2"
+```
+
+### 5단계: Phase 완료 처리
+
+```txt
+weave command=verify
+weave command=approve
+```
+
+### 6단계: 핸드오프 & 검증
+
+모든 검증이 통과되면:
+
+```markdown
+## ✅ Phase P1 검증 완료!
+
+### 🤖 AI 테스트 결과
+| 테스트 | 결과 |
+|--------|------|
+| Build | ✅ 성공 |
+| Unit Tests | ✅ 15/15 |
+| Lint | ✅ 통과 |
+
+### 🎭 사용된 마스크
+- 켄트 벡 (테스트)
+- 댄 아브라모프 (React 컴포넌트)
+
+### 🔗 접속
+http://localhost:5173
+
+### 👤 사람만 판단 가능한 것
+- [ ] 느낌이 의도대로인가요?
+- [ ] 사용성이 좋은가요?
+- [ ] 원하던 기능이 맞나요?
+
+**[승인]** **[변경 요청]** **[나중에]**
+```
+
+### 6단계: 언제든지 상태 확인
+
+```bash
+/weave-status
+```
+
+출력:
+```markdown
+## 📊 Weave 진행 상황
+
+**프로젝트**: 감정 일기 앱
+**진행률**: 40%
+
+[████████░░░░░░░░░░░░] 2/5
+
+### Phases
+✅ **P1**: 감정 선택 UI (2.5h) [kent-beck, dan-abramov]
+🔄 **P2**: 데이터 저장
+⏳ **P3**: 히스토리 뷰
+⏳ **P4**: 통계
+⏳ **P5**: 테마 설정
+
+### 글로벌 지식 통계
+- 총 트러블슈팅 기록: 47개
+- 이 프로젝트에서 활용: 3개
+- 새로 기록됨: 1개
+```
+
+---
+
+## 🎭 가면 만들기
+
+가면은 간단한 YAML 파일입니다:
+
+```yaml
+# masks/my-expert.yaml
+metadata:
+  id: my-expert
+  version: '1.0'
+  language: ko
+
+profile:
+  name: 에이다 러브레이스
+  tagline: 컴퓨팅의 선구자 - 최초의 프로그래머
+  
+  expertise:
+    - 알고리즘 설계
+    - 수학적 사고
+    - 해석 기관
+  
+  thinkingStyle: |
+    수학적 엄밀함과 시적 상상력을 결합합니다.
+    다른 사람들이 놓치는 패턴을 봅니다.
+
+behavior:
+  systemPrompt: |
+    당신은 최초의 컴퓨터 프로그래머 에이다 러브레이스입니다.
+    
+    알고리즘을 시로 봅니다 - 우아하고, 정확하고, 아름답게.
+    수학적 변환과 논리적 흐름의 관점에서 생각합니다.
+  
+  communicationStyle:
+    tone: 사려깊은
+    verbosity: 적당한
+    technicalDepth: 전문가
+
+usage:
+  suitableFor:
+    - 알고리즘 설계 및 최적화
+    - 수학적 문제 해결
+    - 코드의 패턴 인식
+```
+
+---
+
+## 🌍 다국어
+
+지원 준비 완료:
+- 🇺🇸 영어
+- 🇰🇷 한국어
+- 🇨🇳 중국어 *(준비중)*
+- 🇯🇵 일본어 *(준비중)*
+
+가면은 여러 언어 버전을 가질 수 있습니다:
+```
+masks/
+├── linus-torvalds.en.yaml
+├── linus-torvalds.ko.yaml
+└── linus-torvalds.zh.yaml
+```
+
+---
+
+## 🤝 기여하기
+
+도움이 필요합니다!
+
+### 가면 추가
+
+`masks/`에 YAML 파일을 만들고 PR을 제출하세요:
+- ✅ 실제 전문성 (도메인 지식)
+- ✅ 독특한 인격 (사고 방식)
+- ✅ 명확한 사용 사례 (언제 사용할지)
+- ✅ 예시 (예상 동작)
+
+### 버그 리포트
+
+다음 내용으로 이슈를 열어주세요:
+1. 무엇을 시도했는지
+2. 무슨 일이 일어났는지
+3. 무엇을 예상했는지
+
+자세한 내용은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참조하세요.
+
+---
+
+## 📄 라이선스
+
+MIT - [LICENSE](LICENSE) 참조
+
+---
+
+<p align="center">
+  <sub>🎭와 함께 제작 by <a href="https://github.com/ulgerang">ULJI SOFT</a></sub>
+</p>