npm package: @maskweaver/plugin
Description: Maskweaver plugin for opencode - Expert AI personas with auto-installation
Author: ULJI SOFT
Latest version: 0.6.0

# @maskweaver/plugin

> 🎭 Give your AI coding assistant expert personalities - 가면술사

전문가 가면을 통해 AI 코딩 어시스턴트를 강화하세요.

## 원클릭 설치

### 방법 1: CLI 사용 (권장)

```bash
# npx 사용
npx @maskweaver/plugin install

# 또는 bunx 사용
bunx @maskweaver/plugin install
```

### 방법 2: 수동 설치

`~/.config/opencode/opencode.json` 또는 프로젝트의 `opencode.json`에 추가:

```json
{
  "plugin": ["@maskweaver/plugin"]
}
```

## 삭제

```bash
# CLI로 제거
npx @maskweaver/plugin uninstall

# 또는 프로젝트별 제거
npx @maskweaver/plugin uninstall --local
```

삭제 후 다음 파일들을 수동으로 정리할 수 있습니다:
- `~/.config/opencode/maskweaver.json` (전역 설정)
- `.opencode/maskweaver.json` (프로젝트 설정)
- `.opencode/masks/` (사용자 정의 가면)
- `.opencode/agents/` (사용자 정의 에이전트)

## 설치 상태 확인

```bash
npx @maskweaver/plugin status
```

## 설정

`.opencode/maskweaver.json` 파일을 생성하여 플러그인을 구성할 수 있습니다:

```json
{
  "$schema": "https://unpkg.com/@maskweaver/plugin/schema.json",
  "masks": {
    "default": "kent-beck",
    "autoActivate": true
  },
  "disabled_tools": [],
  "disabled_masks": [],
  "agents": {
    "coder": {
      "model": "anthropic/claude-sonnet-4-5"
    }
  },
  "logging": {
    "verbose": false
  }
}
```

### 설정 옵션

| 옵션 | 설명 |
|------|------|
| `masks.default` | 세션 시작 시 자동 활성화할 가면 ID |
| `masks.autoActivate` | 기본 가면 자동 활성화 여부 |
| `disabled_tools` | 비활성화할 도구 목록 |
| `disabled_masks` | 비활성화할 가면 목록 |
| `agents` | 에이전트별 설정 오버라이드 |
| `logging.verbose` | 상세 로깅 활성화 |

## 사용법

### 1. 가면 목록 확인

AI에게 `list_masks` 도구를 사용하도록 요청:
```
사용 가능한 가면을 보여줘
```

### 2. 가면 선택

`select_mask` 도구로 가면 활성화:
```
Kent Beck 가면을 적용해줘
```

### 3. 가면 해제

`deselect_mask` 도구로 가면 제거:
```
현재 가면을 해제해줘
```

### 4. 상태 확인

`maskweaver_status` 도구로 상태 확인:
```
maskweaver 상태를 보여줘
```

## 사용 가능한 가면

### Software Engineering
- **kent-beck**: 테스트 주도 개발(TDD)의 창시자
- **martin-fowler**: 리팩토링과 엔터프라이즈 패턴의 대가
- **linus-torvalds**: 리눅스와 Git의 창시자
- **dan-abramov**: React와 Redux의 핵심 개발자

### Architecture
- **jeff-dean**: 구글의 시스템 아키텍처 대가

### AI/ML
- **andrew-ng**: 머신러닝 교육의 선구자

## Tools

Maskweaver 플러그인은 메모리, 컨텍스트, 회고를 위한 7개의 강력한 도구를 제공합니다.

### Memory Tools

#### memory_search

의미 기반 검색으로 이전 대화, 결정 사항, 사용 기록, 유저 선호도를 찾습니다.

**Parameters:**
- `query` (required): 검색할 텍스트
- `maxResults` (optional): 최대 결과 수
- `minScore` (optional): 최소 유사도 점수
- `sources` (optional): 검색 범위 (`memory`, `masks`, `retrospect`, `daily`, `user`)

**Example:**
```typescript
// "OAuth 구현"과 관련된 이전 대화 검색
memory_search({ query: "OAuth 구현", maxResults: 5 })

// 유저 정보만 검색
memory_search({ query: "선호하는 코딩 스타일", sources: ["user"] })
```

#### memory_write

마크다운 파일에 메모리를 저장합니다.

**Parameters:**
- `content` (required): 저장할 내용
- `target` (required): 저장 위치
  - `daily`: 오늘의 작업 기록 (자동으로 오늘 날짜 파일에 추가)
  - `memory`: 장기 기억 (MEMORY.md에 추가)
  - `user`: 유저 정보 (USER.md 업데이트)
- `section` (optional): 섹션 이름

**Example:**
```typescript
// 오늘의 작업 기록
memory_write({ 
  content: "OAuth 로그인 기능 구현 완료", 
  target: "daily" 
})

// 장기 기억 저장
memory_write({ 
  content: "JWT 토큰은 7일 만료 정책 사용", 
  target: "memory",
  section: "인증 정책"
})

// 유저 선호도 저장
memory_write({ 
  content: "TypeScript strict 모드 선호", 
  target: "user" 
})
```

#### memory_get

메모리 파일의 상세 내용을 조회합니다.

**Parameters:**
- `path` (required): 파일 경로
- `from` (optional): 시작 라인 번호
- `lines` (optional): 읽을 라인 수

**Example:**
```typescript
// memory_search로 찾은 파일의 전체 내용 읽기
memory_get({ path: ".memory/daily/2026-02-01.md" })

// 특정 범위만 읽기
memory_get({ path: ".memory/MEMORY.md", from: 10, lines: 20 })
```

#### memory_indexer

파일을 의미 검색용으로 인덱싱합니다.

**Parameters:**
- `action` (required): 작업 타입
  - `index`: 새 파일 인덱싱
  - `reindex`: 기존 파일 재인덱싱
  - `index-all`: 모든 메모리 파일 인덱싱
- `path` (required): 파일 경로

**Example:**
```typescript
// 새 파일 인덱싱
memory_indexer({ action: "index", path: ".memory/daily/2026-02-01.md" })

// 전체 재인덱싱
memory_indexer({ action: "index-all", path: ".memory" })
```

### Context Tools

#### context

피처 기반 컨텍스트 관리로 작업을 구조화하고 추적합니다.

**Actions:**
- `start`: 새 피처 시작 (name, goal 필요)
- `switch`: 피처 전환 (id 또는 name 필요)
- `status`: 현재 활성 피처 상태 표시
- `done`: 피처 완료 처리 (id 없으면 현재 피처)
- `add`: 현재 피처에 파일 추가 (file 필요)
- `drop`: 현재 피처에서 파일 제거 (file 필요)
- `goal`: 현재 피처 목표 변경 (goal 필요)
- `list`: 모든 피처 목록 조회

**Example:**
```typescript
// 새 피처 시작
context({ action: "start", name: "login-oauth", goal: "OAuth 로그인 구현" })

// 파일 추가
context({ action: "add", file: "src/auth/oauth.ts" })

// 상태 확인
context({ action: "status" })

// 목표 변경
context({ action: "goal", goal: "OAuth 2.0 + PKCE 구현" })

// 피처 완료
context({ action: "done" })

// 모든 피처 목록
context({ action: "list" })
```

### Retrospect Tools

#### retrospect

세션 회고를 수행하여 작업을 분석하고 개선점을 기록합니다.

**Parameters:**
- `trigger` (required): 회고 트리거
  - `manual`: 유저가 명령으로 요청
  - `session_end`: 세션 종료 시 자동 실행
  - `periodic`: 더미인간 5번 소환 후 자동 실행
- `summary` (required): 작업 요약
- `masksUsed` (optional): 사용한 가면 목록
  - `name`: 가면 이름
  - `task`: 수행한 작업
  - `effectiveness`: 효과성 점수 (0-10)
- `wellDone` (optional): 잘된 점 목록
- `improvements` (optional): 개선점 목록
- `lessons` (optional): 배운 교훈 목록
- `depth` (optional): 회고 깊이
  - `quick`: 요약만 기록 (빠른 회고)
  - `standard`: 요약 + 잘된점/개선점 (기본)
  - `deep`: 전체 + 상세 교훈 (심층 회고)

**Example:**
```typescript
// 기본 회고
retrospect({ 
  trigger: "manual",
  summary: "OAuth 로그인 기능 구현 완료",
  wellDone: ["TDD로 개발하여 버그 최소화", "PKCE 적용으로 보안 강화"],
  improvements: ["에러 처리 더 세밀하게", "문서화 추가 필요"]
})

// 심층 회고 (가면 사용 기록 포함)
retrospect({
  trigger: "session_end",
  summary: "인증 시스템 리팩토링",
  masksUsed: [
    { name: "kent-beck", task: "TDD로 테스트 작성", effectiveness: 9 },
    { name: "martin-fowler", task: "코드 리팩토링", effectiveness: 8 }
  ],
  wellDone: ["테스트 커버리지 95%", "순환 참조 제거"],
  improvements: ["성능 테스트 추가", "API 문서 업데이트"],
  lessons: ["TDD가 리팩토링 신뢰도를 크게 높임", "작은 단위로 커밋하니 롤백이 쉬움"],
  depth: "deep"
})
```

#### mask_save

효과적인 가면을 라이브러리에 저장합니다.

**Parameters:**
- `name` (required): 가면 이름
- `expertise` (required): 전문 분야
- `thinkingStyle` (required): 사고 방식
- `strengths` (required): 강점
- `suitableFor` (required): 적합한 작업
- `effectivenessScore` (required): 효과성 점수 (0-10)
- `usageNote` (optional): 사용 노트

**Example:**
```typescript
mask_save({
  name: "test-architect",
  expertise: "테스트 아키텍처 설계 및 전략 수립",
  thinkingStyle: "체계적이고 계층적인 접근. 테스트 피라미드 우선 고려",
  strengths: "E2E/통합/단위 테스트 균형, 테스트 유지보수성",
  suitableFor: "테스트 전략 수립, 테스트 코드 리팩토링, CI/CD 파이프라인",
  effectivenessScore: 9,
  usageNote: "복잡한 시스템의 테스트 전략 수립에 매우 효과적"
})
```

## 커스텀 더미인간 추가

기본적으로 `dummy-human` (기본 모델 상속) 하나만 제공됩니다.
다른 모델을 사용하고 싶다면 직접 더미인간을 추가할 수 있습니다.

### 1. 템플릿 복사

`.opencode/agents/dummy-template.md`를 참고하여 새 파일 생성:

```bash
# 예: Gemini Flash 모델용 더미인간
cp .opencode/agents/dummy-template.md .opencode/agents/dummy-flash.md
```

### 2. 모델 지정

```yaml
---
description: 더미인간(Flash) - Gemini Flash. 빠르고 저렴한 단순 작업용
model: google/gemini-2.5-flash
mode: subagent
---
가면술사가 전달한 지시사항을 충실히 수행합니다.
```

### 추천 모델 예시

| 파일명 | 모델 | 용도 |
|-------|------|------|
| `dummy-flash.md` | `google/gemini-2.5-flash` | 빠르고 저렴한 단순 작업 |
| `dummy-premium.md` | `anthropic/claude-opus-4` | 복잡한 추론, 아키텍처 |
| `dummy-coder.md` | `deepseek/deepseek-coder` | 코드 생성 특화 |
| `dummy-gpt.md` | `openai/gpt-4o` | 범용 작업 |

## oh-my-opencode 패턴

이 플러그인은 [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) 패턴을 따릅니다:

- ✅ 원클릭 설치/삭제
- ✅ 설정 파일을 통한 비활성화
- ✅ 자동 에셋 설치
- ✅ 이벤트 훅 지원
- ✅ 에이전트 설정 오버라이드

## 라이선스

MIT © [ULJI SOFT](https://github.com/ulgerang)