🎭 Maskweaver: Expert Persona Framework for OpenCode

The npm for AI personas — Level up your OpenCode assistant with expert personalities

English | 한국어

🔌 OpenCode Plugin

Maskweaver is a handy plugin for OpenCode.

While it can be used as a standalone library, it works great with OpenCode to add expert personas to your coding workflow:

• 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.

Why Maskweaver?

You're stuck debugging a race condition. Wouldn't it be great if Linus Torvalds could review your code?

// Instead of generic AI response...
"You have a potential race condition in your code."

// Get Linus-level insight:
"This is stupid. You're not even using memory barriers. Read the 
assembly - the compiler reordered your loads. Use smp_rmb() or 
better yet, redesign this without the stupid lock."

Maskweaver makes this real. It gives AI assistants expert personas (masks) with deep domain knowledge and distinct thinking styles.

Installation

For Humans

Copy and paste this prompt to your LLM agent (Claude Code, AmpCode, Cursor, etc.):

Install and configure maskweaver by following the instructions here:
https://raw.githubusercontent.com/ulgerang/maskweaver/master/docs/installation.md

Or read the Installation Guide directly—but we strongly recommend letting an agent handle it. Humans make mistakes.

For LLM Agents

Fetch the installation guide and follow it:

curl -s https://raw.githubusercontent.com/ulgerang/maskweaver/master/docs/installation.md

Quick Install

# npm
npm install maskweaver

# bun
bun add maskweaver

OpenCode Plugin Setup

Add to your OpenCode config - that's it!

Global (~/.config/opencode/opencode.json):

{
  "plugin": ["maskweaver"]
}

Or per-project (opencode.json in project root):

{
  "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):

{
  "notifications": {
    "completionSound": {
      "enabled": true
    }
  }
}

Turn it off:

{
  "notifications": {
    "completionSound": {
      "enabled": false
    }
  }
}

Checking Installed Version

Multiple ways to verify your Maskweaver version:

# CLI (terminal)
maskweaver --version
# or
maskweaver -V

# npm
npm list maskweaver

# In OpenCode chat
# Use the maskweaver_status tool or type:
/weave-help

// Programmatic (Node.js / TypeScript)
import { VERSION } from 'maskweaver';
console.log(VERSION); // "0.7.29"

Quick Start

First Use

# In your AI assistant chat:
@maskweaver Use Linus Torvalds mask to review this C code

# Or delegate to dummy-humans:
@dummy-human Linus mask: review my multithreading code
@dummy-flash Find all files with "unsafe" in them
@dummy-premium Design microservices architecture for this monolith

Features

🎭 Expert Personas (Masks)

Apply legendary developer personalities to your AI assistant:

# masks/software-engineering/linus-torvalds.yaml
profile:
  name: Linus Torvalds
  expertise:
    - Kernel-level systems programming
    - Performance optimization
    - Memory management and concurrency
  
  thinkingStyle: |
    Bottom-up, pragmatic. Starts with code, not theory.
    Ruthlessly eliminates complexity.

Current Masks:

• 🐧 Linus Torvalds - Systems, C, Linux, performance
• 🏗️ Martin Fowler - Architecture, refactoring, patterns
• 🧪 Kent Beck - TDD, XP, testing
• 🧠 Andrew Ng - ML/AI systems
• ⚛️ Dan Abramov - React, frontend architecture

🤖 Dummy-Human System

Smart subagents for cost-efficient multi-agent workflows:

| Agent | Model Tier | Cost | Best For | |-------|-----------|------|----------| | @dummy-flash | Fast | 💰 | File search, summaries, simple tasks | | @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-prepare [docs] | Generate research + spec + plan in one step (auto-split if oversized) | | /weave-refine-plan | Apply structured plan notes (tasks/plan-notes.md) to active plan | | /weave-approve | Explicit human approval gate before implementation | | /weave-craft [P#] | Prepare phase execution context and guidance | | /build | Autonomous build loop (action=run/status/stop/list/resume/sync) | | /weave-verify | Run build/test verification (auto-detect) | | /weave-worktree ... | Manage git worktrees for parallel work | | /weave-status | View project progress and stats | | /weave-agents | Sync agent files or init config (sync=true / init=true) | | /weave-troubleshoot | Search global knowledge (record=true to save a solution) | | /weave-archive | Archive the verified active change | | /weave-help | Show documentation |

Tip: In OpenCode chat, use the visible slash commands such as /weave-prepare and /build; they map to the underlying weave command=... tool calls.

Workflow

0. INIT (once): /weave-init
       ↓
1. PLAN: /weave-prepare docs/
    - Generates research + spec + phase plan (auto-splits if oversized)
       ↓
2. REFINE (optional): /weave-refine-plan
    - apply annotation notes from tasks/plan-notes.md
       ↓
3. APPROVAL GATE: /weave-approve
    - required before craft execution
       ↓
4. CRAFT: /weave-craft
     - Generates an execution plan and next actions
     - Implement/verify changes, then finalize with approve
     - Use `/weave-verify` anytime for build/test checks
       ↓
5. HANDOFF: You validate UX/intent and move to next phase

Multi-Layer AI Verification

Before handing off to you, AI runs these verification layers:

| Layer | Type | Tool | |-------|------|------| | 1️⃣ TypeCheck | Build | tsc --noEmit | | 2️⃣ Lint | Build | eslint | | 3️⃣ Build | Build | npm run build | | 4️⃣ Unit Tests | Test | jest / vitest | | 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 (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):

{
  "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:

| Task Type | Auto-Selected Mask | |-----------|-------------------| | Architecture/Design | 🏗️ Martin Fowler | | Testing/TDD | 🧪 Kent Beck | | React/Frontend | ⚛️ Dan Abramov | | Performance/Systems | 🐧 Linus Torvalds | | ML/AI | 🧠 Andrew Ng |

Global Knowledge Base (Cross-Project RAG)

Troubleshooting solutions are stored globally and shared across all projects:

Error occurs → Search ~/.maskweaver/knowledge.sqlite
    ├── Found → Apply solution → Retry
    └── Not found → Fix manually → Record solution for future

🧠 Memory System

Remember past conversations, decisions, and mask effectiveness:

import { memory } from 'maskweaver';

// Index your project knowledge
await memory.indexFile('./docs/architecture.md', embedFn);

// Semantic search with multiple providers:
const results = await memory.hybridSearch(
  'How does authentication work?',
  embedding,
  { limit: 5, minScore: 0.7 }
);

Embedding Providers:

• 🦙 Ollama - Local, private (bge-m3, nomic-embed)
• 🤖 OpenAI - text-embedding-3-large
• 🚀 VoyageAI - Code-specialized embeddings!
• 🔀 OpenRouter - Access to multiple providers
• 📝 Text-only - No embeddings, pure FTS5

🗂️ Context System

Track long-running features with file associations:

# Start a feature
@context start name="oauth-login" goal="Implement OAuth2 flow"

# Add files to feature context
@context add file="src/auth/oauth.ts"

# Check status
@context status

# Mark as done
@context done

🔄 Retrospect System

Evaluate mask effectiveness after each session:

{
  "trigger": "session_end",
  "masksUsed": [
    {
      "name": "linus-torvalds",
      "task": "Review multithreading code",
      "effectiveness": 9.5
    }
  ],
  "wellDone": ["Found 3 critical race conditions"],
  "lessons": ["Linus mask excels at concurrency reviews"]
}

📦 Package Structure

Maskweaver is a single npm package with modular exports:

// Default export - OpenCode plugin
import maskweaver from 'maskweaver';

// Named exports - module namespaces
import { core, memory, context, retrospect, verify, weave } from 'maskweaver';

// Subpath imports - direct module access
import { hybridSearch } from 'maskweaver/memory';
import { createFeature } from 'maskweaver/context';
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

🧵 Weave Usage Guide

Step 0: Initialize (Once)

/weave-init

Step 1: Create a Plan

Generate research + spec + plan in one command:

/weave-prepare docs/

Then approve the plan:

/weave-approve

The AI will:

1. Read all documents in the path
2. Search memory for similar past projects
3. Ask clarifying questions if needed
4. Present a Phase Plan for your approval

Example output:

## 📋 Execution Plan

### Vision
Build a modern emotion diary app with AI-powered insights

### Phases
| Phase | Name | Done When | Est. Time |
|-------|------|-----------|-----------|
| P1 | Emotion Selection UI | User can select emotions | 2-3h |
| P2 | Data Persistence | Emotions saved to storage | 2-3h |
| P3 | History View | User can view past entries | 2-3h |

Is this plan okay? Let me know if changes are needed.

Step 2: Approve the Plan (Required)

/weave-approve

Step 3: Craft a Phase (Auto-select if omitted)

Start with the first phase:

/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

weave command=craft phaseId="P1"
weave command=verify

Autonomous build loop:

weave command=build action=run phaseIds="P1,P2"

Step 5: Finalize the Phase

weave command=verify
weave command=approve

Step 6: Handoff & Validate

When all verifications pass:

## ✅ Phase P1 Verification Complete!

### 🤖 AI Test Results
| Test | Result |
|------|--------|
| Build | ✅ Success |
| Unit Tests | ✅ 15/15 |
| Lint | ✅ Passed |

### 🎭 Masks Used
- Kent Beck (testing)
- Dan Abramov (React components)

### 🔗 Access
http://localhost:5173

### 👤 Human Validation (Only you can judge)
- [ ] Does it feel right?
- [ ] Is the UX good?
- [ ] Is this what you wanted?

**[Approve]** **[Request Changes]** **[Later]**

Step 6: Check Status Anytime

/weave-status

Output:

## 📊 Weave Progress

**Project**: Emotion Diary App
**Progress**: 40%

[████████░░░░░░░░░░░░] 2/5

### Phases
✅ **P1**: Emotion Selection UI (2.5h) [kent-beck, dan-abramov]
🔄 **P2**: Data Persistence
⏳ **P3**: History View
⏳ **P4**: Statistics
⏳ **P5**: Theme Settings

### Global Knowledge Stats
- Total troubleshooting records: 47
- Used in this project: 3
- Newly recorded: 1

🎭 Creating Masks

Masks are simple YAML files:

# masks/my-expert.yaml
metadata:
  id: my-expert
  version: '1.0'
  language: en

profile:
  name: Ada Lovelace
  tagline: Pioneer of Computing - First Programmer
  
  expertise:
    - Algorithm design
    - Mathematical thinking
    - Analytical engines
  
  thinkingStyle: |
    Combines mathematical rigor with poetic imagination.
    Sees patterns others miss.

behavior:
  systemPrompt: |
    You are Ada Lovelace, the first computer programmer.
    
    You see algorithms as poetry - elegant, precise, beautiful.
    You think in terms of mathematical transformations and 
    logical flows.
  
  communicationStyle:
    tone: thoughtful
    verbosity: moderate
    technicalDepth: expert

usage:
  suitableFor:
    - Algorithm design and optimization
    - Mathematical problem-solving
    - Pattern recognition in code

🌍 Multilingual

Infrastructure ready for:

• 🇺🇸 English
• 🇰🇷 Korean
• 🇨🇳 Chinese (coming soon)
• 🇯🇵 Japanese (coming soon)

Masks can have multiple language versions:

masks/
├── linus-torvalds.en.yaml
├── linus-torvalds.ko.yaml
└── linus-torvalds.zh.yaml

🤝 Contributing

We need your help!

Add a Mask

Create a YAML file in masks/ and submit a PR:

• ✅ Real expertise (domain knowledge)
• ✅ Distinct personality (thinking style)
• ✅ Clear use cases (when to use)
• ✅ Examples (expected behavior)

Report Bugs

Open an issue with:

1. What you tried
2. What happened
3. What you expected

See CONTRIBUTING.md for more details.

📄 License

MIT - See LICENSE