maskweaver 0.8.5 → 0.8.7

package/README.md

@@ -24,10 +24,10 @@ While it can be used as a standalone library, it works great with OpenCode to ad
 - **Expert Personas (Masks)**: Standardized YAML profiles for legendary developers.
 - **Smart Delegation**: Multi-agent workflows optimized for OpenCode.
 - **Project Memory**: Hybrid semantic search for your entire codebase.
-- **🆕 Weave Workflow**: Phase-driven development with AI self-verification.
-- **🔗 GDC Integration**: Graph-Driven Codebase support for enhanced research and design-time verification gates.
-
----
+- **🆕 Weave Workflow**: Phase-driven development with AI self-verification.
+- **🔗 GDC Integration**: Graph-Driven Codebase support for enhanced research and design-time verification gates.
+
+---
 
 ## Why Maskweaver?
 
@@ -78,30 +78,58 @@ npm install maskweaver
 bun add maskweaver
 ```
 
-### OpenCode Plugin Setup
-
-Add to your OpenCode config - that's it!
-
-**Global** (`~/.config/opencode/opencode.json`):
-```json
-{
-  "plugin": ["maskweaver"]
-}
-```
-
-**Or per-project** (`opencode.json` in project root):
-```json
-{
-  "plugin": ["maskweaver"]
-}
-```
-
-> Note: OpenCode installs npm packages by name. Use `maskweaver` (not `maskweaver/plugin`).
+### OpenCode Plugin Setup
+
+Add to your OpenCode config - that's it!
+
+**Global** (`~/.config/opencode/opencode.json`):
+```json
+{
+  "plugin": ["maskweaver"]
+}
+```
+
+**Or per-project** (`opencode.json` in project root):
+```json
+{
+  "plugin": ["maskweaver"]
+}
+```
+
+> Note: OpenCode installs npm packages by name. Use `maskweaver` (not `maskweaver/plugin`).
 
 OpenCode automatically installs the plugin to `~/.cache/opencode/node_modules/` on startup.
 
 **Windows:** `%USERPROFILE%\.config\opencode\opencode.json`
 
+### Completion Sound (Optional)
+
+Maskweaver can play a notification sound when generation finishes (`session.idle`).
+
+Create `.opencode/maskweaver.json` (project) or `~/.config/opencode/maskweaver.json` (global):
+
+```jsonc
+{
+  "notifications": {
+    "completionSound": {
+      "enabled": true
+    }
+  }
+}
+```
+
+Turn it off:
+
+```jsonc
+{
+  "notifications": {
+    "completionSound": {
+      "enabled": false
+    }
+  }
+}
+```
+
 ### Checking Installed Version
 
 Multiple ways to verify your Maskweaver version:
@@ -181,58 +209,58 @@ Smart subagents for cost-efficient multi-agent workflows:
 | `@dummy-human` | Balanced | 💰💰 | Code writing, reviews, general work |
 | `@dummy-premium` | Powerful | 💰💰💰 | Architecture, complex debugging |
 
-### 🧵 Weave Workflow
-
-**Phase-Driven Development** — "AI verifies, Human validates"
-
-Weave is Maskweaver's flagship workflow. It breaks work into testable phases, auto-selects expert masks, and provides structured verification before handoff.
-
-#### Commands
-
-| Command | Description |
-|---------|-------------|
-| `/weave init` | Initialize Weave (once per repo) |
-| `/weave research [docs]` | Deep-read docs + workspace context and generate persistent `tasks/research.md` |
-| `/weave prepare [docs]` | (Manual path) Generate research + baseline spec + phase plan (auto-split if oversized) |
-| `/weave refine-plan` | Apply structured plan notes (`tasks/plan-notes.md`) to active plan |
-| `/weave approve-plan` | Explicit human approval gate before implementation |
-| `/weave flow [docs]` | (Recommended) One-command path: prepare -> auto-approve -> craft -> verify -> finalize |
-| `/weave spec [docs]` | Generate baseline spec only (optional) |
-| `/weave design [docs]` | Analyze requirements → Generate phase plan (`/weave plan` alias, auto-split if oversized) |
-| `/weave craft [P#]` | Prepare phase execution context and guidance |
-| `/weave verify` | Run build/test verification (auto-detect) |
-| `/weave worktree ...` | Manage git worktrees for parallel work |
-| `/weave status` | View project progress and stats |
-| `/weave help` | Show documentation |
-
-> Tip: In OpenCode chat you can use `/weave ...` commands, and they map to the underlying `weave command=...` tool calls.
-
-#### Workflow
-
-```
-0. INIT (once): /weave init
-       ↓
-1. ONE-COMMAND (recommended): /weave flow docs/
-    - runs: prepare -> auto-approve -> craft -> verify -> finalize
-       ↓
-   (or manual path)
-       ↓
-2. PLAN (manual path): /weave prepare docs/
-    - or: /weave research docs/ → /weave spec docs/ → /weave design docs/
-       ↓
-3. REFINE (optional): /weave refine-plan
-    - apply annotation notes from tasks/plan-notes.md
-       ↓
-4. APPROVAL GATE: /weave approve-plan
-    - required before craft execution
-       ↓
-5. CRAFT: /weave craft
-     - Generates an execution plan and next actions
-     - Implement/verify changes, then finalize with approve-plan
-     - Use `/weave verify` anytime for build/test checks
-       ↓
-6. HANDOFF: You validate UX/intent and move to next phase
-```
+### 🧵 Weave Workflow
+
+**Phase-Driven Development** — "AI verifies, Human validates"
+
+Weave is Maskweaver's flagship workflow. It breaks work into testable phases, auto-selects expert masks, and provides structured verification before handoff.
+
+#### Commands
+
+| Command | Description |
+|---------|-------------|
+| `/weave init` | Initialize Weave (once per repo) |
+| `/weave research [docs]` | Deep-read docs + workspace context and generate persistent `tasks/research.md` |
+| `/weave prepare [docs]` | (Manual path) Generate research + baseline spec + phase plan (auto-split if oversized) |
+| `/weave refine-plan` | Apply structured plan notes (`tasks/plan-notes.md`) to active plan |
+| `/weave approve-plan` | Explicit human approval gate before implementation |
+| `/weave flow [docs]` | (Recommended) One-command path: prepare -> auto-approve -> craft -> verify -> finalize |
+| `/weave spec [docs]` | Generate baseline spec only (optional) |
+| `/weave design [docs]` | Analyze requirements → Generate phase plan (`/weave plan` alias, auto-split if oversized) |
+| `/weave craft [P#]` | Prepare phase execution context and guidance |
+| `/weave verify` | Run build/test verification (auto-detect) |
+| `/weave worktree ...` | Manage git worktrees for parallel work |
+| `/weave status` | View project progress and stats |
+| `/weave help` | Show documentation |
+
+> Tip: In OpenCode chat you can use `/weave ...` commands, and they map to the underlying `weave command=...` tool calls.
+
+#### Workflow
+
+```
+0. INIT (once): /weave init
+       ↓
+1. ONE-COMMAND (recommended): /weave flow docs/
+    - runs: prepare -> auto-approve -> craft -> verify -> finalize
+       ↓
+   (or manual path)
+       ↓
+2. PLAN (manual path): /weave prepare docs/
+    - or: /weave research docs/ → /weave spec docs/ → /weave design docs/
+       ↓
+3. REFINE (optional): /weave refine-plan
+    - apply annotation notes from tasks/plan-notes.md
+       ↓
+4. APPROVAL GATE: /weave approve-plan
+    - required before craft execution
+       ↓
+5. CRAFT: /weave craft
+     - Generates an execution plan and next actions
+     - Implement/verify changes, then finalize with approve-plan
+     - Use `/weave verify` anytime for build/test checks
+       ↓
+6. HANDOFF: You validate UX/intent and move to next phase
+```
 
 #### Multi-Layer AI Verification
 
@@ -247,55 +275,55 @@ Before handing off to you, AI runs these verification layers:
 | 5️⃣ E2E Tests | Test | **Playwright** |
 | 6️⃣ Screenshot | Visual | Playwright / browser capture |
 | 7️⃣ API Check | API | `fetch` health checks |
-| 8️⃣ A11y | Accessibility | `axe-core` |
-| 0️⃣ GDC Check | Design | `gdc check --machine` |
-
-#### GDC Integration (Graph-Driven Codebase)
-
-Weave integrates with [GDC](https://github.com/ulgerang/gdc) (Graph-Driven Codebase) to enhance research quality and add design-time verification gates:
-
-**Research Enhancement:**
-- Automatic `.gdc` workspace detection
-- `weave init` probe chain (`version`/`sync`/`check`/`stats`) for quick integration health check
-- GDC `stats`, `graph`, and `check` results embedded in `tasks/research.md`
-- Dependency blast radius analysis from graph edges
-- Candidate reuse nodes matched against feature keywords
-- New report sections: `GDC Node Coverage`, `Dependency Blast Radius`, `Existing Spec vs Implementation Drift`, `Candidate Reuse Nodes`
-
-**Execution Enhancements:**
-- `weave craft` can generate node context files via `gdc extract` and link them in `tasks/todo.md`
-- `weave status` includes GDC node/check metrics (`total/implemented/tested`, issue summary)
-- `weave worktree create` can bootstrap `.gdc/config.yaml` and `.gdc/nodes/**` (without `.gdc/graph.db`)
-
-**Pre-Verify Gate:**
-When GDC is detected, `weave verify` and `weave flow` automatically run:
-1. `gdc sync --machine` - Sync specs with implementation
-2. `gdc check --machine` - Validate spec/implementation alignment
-
-Blocking errors from GDC check will halt verification (configurable via `strictVerify` mode).
-
-**Configuration** (`maskweaver.config.json`):
-```json
-{
-  "gdc": {
-    "enabled": "auto",
-    "strictVerify": false,
-    "autoSyncOnPrepare": true,
-    "extractContext": {
-      "withImpl": true,
-      "withTests": true,
-      "withCallers": true
-    }
-  }
-}
-```
-
-- `enabled`: `true` | `false` | `"auto"` (default: auto-detect from `.gdc` directory)
-- `strictVerify`: If `true`, GDC check failures block verification; if `false`, continues with warning
-- `autoSyncOnPrepare`: Run `gdc sync` during `weave prepare`
-- `extractContext`: Controls `gdc extract` evidence flags during `weave craft`
-
-#### Autonomous Mask Selection
+| 8️⃣ A11y | Accessibility | `axe-core` |
+| 0️⃣ GDC Check | Design | `gdc check --machine` |
+
+#### GDC Integration (Graph-Driven Codebase)
+
+Weave integrates with [GDC](https://github.com/ulgerang/gdc) (Graph-Driven Codebase) to enhance research quality and add design-time verification gates:
+
+**Research Enhancement:**
+- Automatic `.gdc` workspace detection
+- `weave init` probe chain (`version`/`sync`/`check`/`stats`) for quick integration health check
+- GDC `stats`, `graph`, and `check` results embedded in `tasks/research.md`
+- Dependency blast radius analysis from graph edges
+- Candidate reuse nodes matched against feature keywords
+- New report sections: `GDC Node Coverage`, `Dependency Blast Radius`, `Existing Spec vs Implementation Drift`, `Candidate Reuse Nodes`
+
+**Execution Enhancements:**
+- `weave craft` can generate node context files via `gdc extract` and link them in `tasks/todo.md`
+- `weave status` includes GDC node/check metrics (`total/implemented/tested`, issue summary)
+- `weave worktree create` can bootstrap `.gdc/config.yaml` and `.gdc/nodes/**` (without `.gdc/graph.db`)
+
+**Pre-Verify Gate:**
+When GDC is detected, `weave verify` and `weave flow` automatically run:
+1. `gdc sync --machine` - Sync specs with implementation
+2. `gdc check --machine` - Validate spec/implementation alignment
+
+Blocking errors from GDC check will halt verification (configurable via `strictVerify` mode).
+
+**Configuration** (`maskweaver.config.json`):
+```json
+{
+  "gdc": {
+    "enabled": "auto",
+    "strictVerify": false,
+    "autoSyncOnPrepare": true,
+    "extractContext": {
+      "withImpl": true,
+      "withTests": true,
+      "withCallers": true
+    }
+  }
+}
+```
+
+- `enabled`: `true` | `false` | `"auto"` (default: auto-detect from `.gdc` directory)
+- `strictVerify`: If `true`, GDC check failures block verification; if `false`, continues with warning
+- `autoSyncOnPrepare`: Run `gdc sync` during `weave prepare`
+- `extractContext`: Controls `gdc extract` evidence flags during `weave craft`
+
+#### Autonomous Mask Selection
 
 The AI automatically picks the best expert for each task:
 
@@ -399,51 +427,51 @@ import { MaskLoader } from 'maskweaver/core';
 import { WeaveOrchestrator, GlobalKnowledge } from 'maskweaver/weave';
 ```
 
-**Modules:**
-- `maskweaver/core` - Mask loading, validation (YAML/JSON)
-- `maskweaver/memory` - Embeddings + vector search (5 providers)
-- `maskweaver/context` - Feature-based work tracking
-- `maskweaver/verify` - Cross-mask code review
-- `maskweaver/retrospect` - Session effectiveness analysis
-- `maskweaver/weave` - Phase-driven development workflow
-- `maskweaver/gdc` - GDC (Graph-Driven Codebase) integration utilities
-- `maskweaver/plugin` - OpenCode plugin entry point
+**Modules:**
+- `maskweaver/core` - Mask loading, validation (YAML/JSON)
+- `maskweaver/memory` - Embeddings + vector search (5 providers)
+- `maskweaver/context` - Feature-based work tracking
+- `maskweaver/verify` - Cross-mask code review
+- `maskweaver/retrospect` - Session effectiveness analysis
+- `maskweaver/weave` - Phase-driven development workflow
+- `maskweaver/gdc` - GDC (Graph-Driven Codebase) integration utilities
+- `maskweaver/plugin` - OpenCode plugin entry point
 
 ---
 
-## 🧵 Weave Usage Guide
-
-### Step 0: Initialize (Once)
-
-```bash
-/weave init
-```
-
-### Step 1: Create a Plan (Flow Recommended)
-
-Fastest path (one command):
-
-```bash
-/weave flow docs/
-```
-
-This runs `prepare -> auto-approve -> craft -> verify -> finalize` in one shot.
-
-Manual happy path (research + spec + plan in one command):
-
-```bash
-/weave prepare docs/
-/weave approve-plan
-```
-
-Or run the full pipeline separately:
-
-```bash
-/weave research docs/
-/weave spec docs/
-/weave design docs/
-/weave approve-plan
-```
+## 🧵 Weave Usage Guide
+
+### Step 0: Initialize (Once)
+
+```bash
+/weave init
+```
+
+### Step 1: Create a Plan (Flow Recommended)
+
+Fastest path (one command):
+
+```bash
+/weave flow docs/
+```
+
+This runs `prepare -> auto-approve -> craft -> verify -> finalize` in one shot.
+
+Manual happy path (research + spec + plan in one command):
+
+```bash
+/weave prepare docs/
+/weave approve-plan
+```
+
+Or run the full pipeline separately:
+
+```bash
+/weave research docs/
+/weave spec docs/
+/weave design docs/
+/weave approve-plan
+```
 
 The AI will:
 1. Read all documents in the path
@@ -468,43 +496,43 @@ Build a modern emotion diary app with AI-powered insights
 Is this plan okay? Let me know if changes are needed.
 ```
 
-### Step 2: Approve the Plan (Required)
-
-```bash
-/weave approve-plan
-```
-
-### Step 3: Craft a Phase (Auto-select if omitted)
-
-Start with the first phase:
-
-```bash
-/weave craft
-```
-
-`/weave craft` returns execution context for the phase. Implement changes, then rerun `/weave craft` if you want to refresh the plan view.
-
-### Step 4: Continue Implementation
-
-```txt
-weave command=craft phaseId="P1"
-weave command=verify
-```
-
-One-command resume:
-
-```txt
-weave command=flow
-```
-
-### Step 5: Finalize the Phase
-
-```txt
-weave command=verify
-weave command=approve-plan
-```
-
-### Step 6: Handoff & Validate
+### Step 2: Approve the Plan (Required)
+
+```bash
+/weave approve-plan
+```
+
+### Step 3: Craft a Phase (Auto-select if omitted)
+
+Start with the first phase:
+
+```bash
+/weave craft
+```
+
+`/weave craft` returns execution context for the phase. Implement changes, then rerun `/weave craft` if you want to refresh the plan view.
+
+### Step 4: Continue Implementation
+
+```txt
+weave command=craft phaseId="P1"
+weave command=verify
+```
+
+One-command resume:
+
+```txt
+weave command=flow
+```
+
+### Step 5: Finalize the Phase
+
+```txt
+weave command=verify
+weave command=approve-plan
+```
+
+### Step 6: Handoff & Validate
 
 When all verifications pass:
 
@@ -533,7 +561,7 @@ http://localhost:5173
 **[Approve]** **[Request Changes]** **[Later]**
 ```
 
-### Step 6: Check Status Anytime
+### Step 6: Check Status Anytime
 
 ```bash
 /weave status

package/assets/agents/squad-operator.md

@@ -133,56 +133,56 @@ permission:
 3. **진행 관리**: task 상태 모니터링 및 업데이트
 4. **결과 통합**: 워커 결과를 수집하고 가면술사에게 보고
 
-## 사용 가능한 도구
-
-### squad 도구
-- `squad({ action: "assign", squadId, description, assignee, priority })` - task 할당
-- `squad({ action: "update", squadId, taskId, status })` - 상태 업데이트
-- `squad({ action: "complete", squadId, taskId, success, output })` - 완료 처리
-- `squad({ action: "status", squadId })` - 현재 상태 조회
-- `squad({ action: "watchdog", dryRun: true })` - 건강 체크
-- `squad({ action: "models" })` - **모델 풀 상태 조회** (가용 슬롯, 능력, 동시실행 현황)
-
-### Task 도구
-- 더미인간 소환 가능 (다른 워커에게 위임)
-
-## 모델 풀 기반 워커 할당
-
-### 모델 풀 시스템
-사용자의 AI 구독 모델들은 **풀(pool)**로 관리됩니다. 각 모델은:
-- **동시실행 제한**: `maxConcurrent` 개까지만 동시에 사용 가능
-- **능력 태그**: 모델마다 잘하는 분야가 다름 (coding, architecture, debugging 등)
-- **비용 등급**: low / medium / high
-
-### 작업 할당 전 모델 확인
-작업 할당 전 반드시 `squad({ action: "models" })`로 가용 모델을 확인하세요:
-```
-squad({ action: "models" })
-→ {
-    totalCapacity: 6,
-    totalAvailable: 4,
-    models: [
-      { id: "gemini-flash", agentName: "dummy-gemini-flash", tier: "flash", 
-        maxConcurrent: 5, activeCount: 1, remainingSlots: 4, capabilities: [...] },
-      { id: "claude-opus", agentName: "dummy-claude-opus", tier: "premium",
-        maxConcurrent: 1, activeCount: 1, remainingSlots: 0, available: false },
-    ]
-  }
-```
-
-### 할당 전략
-1. **모델 확인**: `squad({ action: "models" })`로 가용 현황 파악
-2. **작업 매칭**: 작업의 복잡도와 특성에 맞는 모델 선택
-   - 단순 작업 (파일 정리, 포매팅) → flash 티어 모델
-   - 일반 코딩 → human 티어 모델
-   - 복잡한 설계/디버깅 → premium 티어 모델
-3. **동시실행 고려**: 해당 모델의 `remainingSlots`이 0이면 다른 모델 사용
-4. **fallback**: 원하는 티어가 꽉 찼으면 비슷한 능력의 다른 모델 사용
-
-### assignee 지정 방식
-`assignee` 필드에 **에이전트 이름**을 사용합니다:
-- 풀 모델: `"dummy-{모델id}"` (예: `"dummy-gemini-flash"`, `"dummy-claude-opus"`)
-- 레거시: `"dummy-flash"`, `"dummy-human"`, `"dummy-premium"`
+## 사용 가능한 도구
+
+### squad 도구
+- `squad({ action: "assign", squadId, description, assignee, priority })` - task 할당
+- `squad({ action: "update", squadId, taskId, status })` - 상태 업데이트
+- `squad({ action: "complete", squadId, taskId, success, output })` - 완료 처리
+- `squad({ action: "status", squadId })` - 현재 상태 조회
+- `squad({ action: "watchdog", dryRun: true })` - 건강 체크
+- `squad({ action: "models" })` - **모델 풀 상태 조회** (가용 슬롯, 능력, 동시실행 현황)
+
+### Task 도구
+- 더미인간 소환 가능 (다른 워커에게 위임)
+
+## 모델 풀 기반 워커 할당
+
+### 모델 풀 시스템
+사용자의 AI 구독 모델들은 **풀(pool)**로 관리됩니다. 각 모델은:
+- **동시실행 제한**: `maxConcurrent` 개까지만 동시에 사용 가능
+- **능력 태그**: 모델마다 잘하는 분야가 다름 (coding, architecture, debugging 등)
+- **비용 등급**: low / medium / high
+
+### 작업 할당 전 모델 확인
+작업 할당 전 반드시 `squad({ action: "models" })`로 가용 모델을 확인하세요:
+```
+squad({ action: "models" })
+→ {
+    totalCapacity: 6,
+    totalAvailable: 4,
+    models: [
+      { id: "gemini-flash", agentName: "dummy-gemini-flash", tier: "flash", 
+        maxConcurrent: 5, activeCount: 1, remainingSlots: 4, capabilities: [...] },
+      { id: "claude-opus", agentName: "dummy-claude-opus", tier: "premium",
+        maxConcurrent: 1, activeCount: 1, remainingSlots: 0, available: false },
+    ]
+  }
+```
+
+### 할당 전략
+1. **모델 확인**: `squad({ action: "models" })`로 가용 현황 파악
+2. **작업 매칭**: 작업의 복잡도와 특성에 맞는 모델 선택
+   - 단순 작업 (파일 정리, 포매팅) → flash 티어 모델
+   - 일반 코딩 → human 티어 모델
+   - 복잡한 설계/디버깅 → premium 티어 모델
+3. **동시실행 고려**: 해당 모델의 `remainingSlots`이 0이면 다른 모델 사용
+4. **fallback**: 원하는 티어가 꽉 찼으면 비슷한 능력의 다른 모델 사용
+
+### assignee 지정 방식
+`assignee` 필드에 **에이전트 이름**을 사용합니다:
+- 풀 모델: `"dummy-{모델id}"` (예: `"dummy-gemini-flash"`, `"dummy-claude-opus"`)
+- 레거시: `"dummy-flash"`, `"dummy-human"`, `"dummy-premium"`
 
 ## 워크플로우
 
@@ -229,9 +229,9 @@ squad({ action: "plan", squadId })
 - 실패한 task 및 원인 (있는 경우)
 - 총 소요 시간
 
-## 제약사항
-
-- 한 번에 최대 5개 워커 관리
-- task당 최대 5분 타임아웃
-- 실패 시 재시도 1회
-- **모델별 동시실행 제한 준수** (반드시 `squad({ action: "models" })`로 확인 후 할당)
+## 제약사항
+
+- 한 번에 최대 5개 워커 관리
+- task당 최대 5분 타임아웃
+- 실패 시 재시도 1회
+- **모델별 동시실행 제한 준수** (반드시 `squad({ action: "models" })`로 확인 후 할당)