moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-cc-mcp-plugins/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: moai-cc-mcp-plugins
+description: "Configuring MCP Servers & Plugins for Claude Code. Set up Model Context Protocol servers (GitHub, Filesystem, Brave Search, SQLite). Configure OAuth, manage permissions, validate MCP structure. Use when integrating external tools, APIs, or expanding Claude Code capabilities."
+allowed-tools: "Read, Write, Edit, Bash, Glob"
+---
+
+## Skill Metadata
+
+| Field | Value |
+| ----- | ----- |
+| Version | 1.0.0 |
+| Tier | Ops |
+| Auto-load | When setting up MCP servers |
+
+## What It Does
+
+MCP (Model Context Protocol) server 및 plugin 설정을 위한 전체 가이드를 제공합니다. GitHub, Filesystem, SQLite 등 다양한 MCP server의 OAuth 설정, 권한 관리, 구조 검증 방법을 다룹니다.
+
+## When to Use
+
+- 새로운 MCP server를 설정할 때
+- OAuth 인증을 구성할 때
+- External tool이나 API를 통합할 때
+- MCP plugin의 permissions이나 구조를 검증할 때
+
+
+# Configuring MCP Servers & Plugins
+
+MCP servers extend Claude Code with external tool integrations. Each server provides tools that Claude can invoke directly.
+
+## MCP Server Setup in settings.json
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-server-github"],
+      "oauth": {
+        "clientId": "your-client-id",
+        "clientSecret": "your-client-secret",
+        "scopes": ["repo", "issues", "pull_requests"]
+      }
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
+    },
+    "sqlite": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]
+    },
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": {
+        "BRAVE_SEARCH_API_KEY": "${BRAVE_SEARCH_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+## Common MCP Servers
+
+| Server | Purpose | Installation | Config |
+|--------|---------|--------------|--------|
+| **GitHub** | PR/issue management, code search | `@anthropic-ai/mcp-server-github` | OAuth required |
+| **Filesystem** | Safe file access with path restrictions | `@modelcontextprotocol/server-filesystem` | Path whitelist required |
+| **SQLite** | Database queries & migrations | `@modelcontextprotocol/server-sqlite` | DB file path |
+| **Brave Search** | Web search integration | `@modelcontextprotocol/server-brave-search` | API key required |
+
+## OAuth Configuration Pattern
+
+```json
+{
+  "oauth": {
+    "clientId": "your-client-id",
+    "clientSecret": "your-client-secret",
+    "scopes": ["repo", "issues"]
+  }
+}
+```
+
+**Scope Minimization** (principle of least privilege):
+- GitHub: `repo` (code access), `issues` (PR/issue access)
+- NOT `admin`, NOT `delete_repo`
+
+## Filesystem MCP: Path Whitelisting
+
+```json
+{
+  "filesystem": {
+    "command": "npx",
+    "args": [
+      "-y",
+      "@modelcontextprotocol/server-filesystem",
+      "${CLAUDE_PROJECT_DIR}/.moai",
+      "${CLAUDE_PROJECT_DIR}/src",
+      "${CLAUDE_PROJECT_DIR}/tests"
+    ]
+  }
+}
+```
+
+**Security Principle**: Explicitly list allowed directories, no wildcards.
+
+## Plugin Marketplace Integration
+
+```json
+{
+  "extraKnownMarketplaces": [
+    {
+      "name": "company-plugins",
+      "url": "https://github.com/your-org/claude-plugins"
+    },
+    {
+      "name": "community-plugins",
+      "url": "https://glama.ai/mcp/servers"
+    }
+  ]
+}
+```
+
+## MCP Health Check
+
+```bash
+# Inside Claude Code terminal
+/mcp                    # List active MCP servers
+/plugin validate        # Validate plugin structure
+/plugin install         # Install from marketplace
+/plugin enable github   # Enable specific server
+/plugin disable github  # Disable specific server
+```
+
+## Environment Variables for MCP
+
+```bash
+# Set in ~/.bash_profile or .claude/config.json
+export GITHUB_TOKEN="gh_xxxx..."
+export BRAVE_SEARCH_API_KEY="xxxx..."
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+# Launch Claude Code with env
+GITHUB_TOKEN=gh_xxxx claude
+```
+
+## MCP Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Server not connecting | Invalid JSON in mcpServers | Validate with `jq .mcpServers settings.json` |
+| OAuth error | Token expired or invalid scopes | Check `claude /usage`, regenerate token |
+| Permission denied | Path not whitelisted | Add to Filesystem MCP args |
+| Slow response | Network latency or server overload | Check server logs, reduce scope |
+
+## Best Practices
+
+✅ **DO**:
+- Use environment variables for secrets
+- Whitelist Filesystem paths explicitly
+- Start with minimal scopes, expand only if needed
+- Test MCP connection: `/mcp` command
+
+❌ **DON'T**:
+- Hardcode credentials in settings.json
+- Use wildcard paths (`/` in Filesystem MCP)
+- Install untrusted plugins
+- Give admin scopes unnecessarily
+
+## Plugin Custom Directory Structure
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   ├── deploy.md
+│   └── rollback.md
+├── agents/
+│   └── reviewer.md
+└── hooks/
+    └── pre-deploy-check.sh
+```
+
+## Validation Checklist
+
+- [ ] All server paths are absolute
+- [ ] OAuth secrets stored in env vars
+- [ ] Filesystem paths are whitelisted
+- [ ] No hardcoded tokens or credentials
+- [ ] MCP server installed: `which npx`
+- [ ] Health check passes: `/mcp`
+- [ ] Scopes follow least-privilege principle
+
+---
+
+**Reference**: Claude Code MCP documentation
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-cc-mcp-plugins/templates/settings-mcp-template.json

@@ -0,0 +1,39 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-server-github"],
+      "oauth": {
+        "clientId": "${GITHUB_CLIENT_ID}",
+        "clientSecret": "${GITHUB_CLIENT_SECRET}",
+        "scopes": ["repo", "issues"]
+      }
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "${CLAUDE_PROJECT_DIR}/.moai",
+        "${CLAUDE_PROJECT_DIR}/src"
+      ]
+    },
+    "sqlite": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/db.sqlite"]
+    },
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": {
+        "BRAVE_SEARCH_API_KEY": "${BRAVE_SEARCH_API_KEY}"
+      }
+    }
+  },
+  "extraKnownMarketplaces": [
+    {
+      "name": "company-plugins",
+      "url": "https://github.com/your-org/claude-plugins"
+    }
+  ]
+}

moai_adk/templates/.claude/skills/moai-cc-memory/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: moai-cc-memory
+description: "Managing Claude Code Session Memory & Context. Understand session context limits, use just-in-time retrieval, cache insights, manage memory files. Use when optimizing context usage, handling large projects, or implementing efficient workflows."
+allowed-tools: "Read, Write, Glob, Bash"
+---
+
+## Skill Metadata
+
+| Field | Value |
+| ----- | ----- |
+| Version | 1.0.0 |
+| Tier | Ops |
+| Auto-load | When optimizing context usage |
+
+## What It Does
+
+Session memory 및 context 관리 전략을 제공합니다. Just-in-time retrieval, insight caching, memory file 관리를 통해 context window를 효율적으로 사용하는 방법을 다룹니다.
+
+## When to Use
+
+- Context limit에 도달할 위험이 있을 때
+- 대규모 프로젝트에서 효율적인 context 관리가 필요할 때
+- Session handoff를 준비할 때
+- Memory file 구조를 설계하거나 정리할 때
+
+
+# Managing Claude Code Session Memory & Context
+
+Claude Code operates within context windows (~100K-200K tokens). Effective memory management ensures productive sessions without hitting limits.
+
+## Context Budget Overview
+
+```
+Total Context Budget
+├── System Prompt (~2K)
+├── Tools & Instructions (~5K)
+├── Session History (~30K)
+├── Project Context (~40K)
+└── Available for Response (~23K)
+```
+
+## Just-in-Time (JIT) Retrieval Strategy
+
+### High-Freedom: Core Principles
+
+**Principle 1: Pull Only What You Need**
+- Don't load entire codebase upfront
+- Load files relevant to immediate task
+- Use Glob/Grep for targeted searches
+- Cache results for reuse
+
+**Principle 2: Prefer Explore Over Manual Hunting**
+```bash
+# ❌ Manual approach: Search many files, load all
+rg "authenticate" src/ | head -20
+
+# ✅ JIT approach: Use Explore agent
+@agent-Explore "Find authentication implementation, analyze"
+```
+
+**Principle 3: Layered Context Summaries**
+```
+1. High-level brief (purpose, success criteria)
+   ↓
+2. Technical core (entry points, domain models)
+   ↓
+3. Edge cases (known bugs, constraints)
+```
+
+### Example: Feature Implementation
+
+```
+Task: "Add email verification to signup"
+
+JIT Retrieval:
+├── Read: User model (src/domain/user.ts)
+├── Read: Signup endpoint (src/api/auth.ts)
+├── Grep: "email" in tests (understand patterns)
+├── Glob: Find email service (src/infra/email.*)
+└── Cache: Signup flow diagram in memory
+```
+
+## Medium-Freedom: Memory File Patterns
+
+### Pattern 1: Session Summary Cache
+
+**File**: `.moai/memory/session-summary.md`
+
+```markdown
+# Session Summary
+
+## Current Task
+- Feature: User email verification
+- SPEC: AUTH-015
+- Status: In RED phase (writing tests)
+
+## Key Files
+- Test: tests/auth/email_verify.test.ts
+- Impl: src/domain/email_service.ts
+- Config: src/config/email.ts
+
+## Important Context
+- Email service uses SendGrid API
+- Verification tokens expire in 24h
+- Already have similar flow for password reset (AUTH-012)
+
+## Assumptions Made
+- Assuming transactional emails only
+- Async email sending OK
+- No SMS verification needed
+```
+
+### Pattern 2: Architecture Reference
+
+**File**: `.moai/memory/architecture.md`
+
+```markdown
+# Architecture Reference
+
+## Data Flow for Email Verification
+
+```
+User(Browser)
+    ↓ [POST /auth/signup]
+Server
+    ↓ [Create user + token]
+DB
+    ↓ [sendEmail async]
+Queue
+    ↓ [Process job]
+Email Service (SendGrid)
+    ↓
+User receives email with link
+User clicks link
+    ↓ [GET /auth/verify?token=...]
+Server validates token
+    ↓ [Mark user verified]
+DB
+    ↓
+User logged in
+```
+
+## Module Boundaries
+- `domain/`: Business logic (no framework)
+- `api/`: HTTP endpoints only
+- `infra/`: External services (SendGrid, DB)
+```
+
+### Pattern 3: Known Gotchas Cache
+
+**File**: `.moai/memory/gotchas.md`
+
+```markdown
+# Common Pitfalls in This Project
+
+## Email Service
+- SendGrid has rate limit: 100 emails/sec per account
+- Test mode uses fake email (won't actually send)
+- Async job failures don't alert (check logs)
+
+## Database
+- Migrations must be reviewed before prod deploy
+- Test DB is reset after each suite
+- Foreign key constraints enforced (plan deletions)
+
+## Authentication
+- JWT tokens stored in httpOnly cookies (XSRF protected)
+- Refresh token rotation required (not automatic)
+- Session timeout: 7 days (hardcoded, not configurable yet)
+```
+
+## Low-Freedom: Memory Management Practices
+
+### Practice 1: Caching Key Insights
+
+```
+After reading code:
+1. Note file locations (~5 min read)
+2. Summarize key logic (~2 min)
+3. Write to memory file (~1 min)
+4. Reference in next session
+```
+
+**Example memory entry**:
+```
+# USER-002: Email verification flow
+
+## Key Code Locations
+- Token generation: src/domain/user.ts:generateVerificationToken()
+- Email sending: src/infra/email_service.ts:sendVerificationEmail()
+- Token validation: src/api/auth.ts:POST /verify
+
+## Logic Summary
+1. User submits email → server generates token (16 chars, base64)
+2. Token stored in DB with 24h expiry
+3. Email sent async via SendGrid
+4. User clicks link → token validated → user marked verified
+5. Token deleted after use (can't reuse)
+
+## Related TESTs
+- tests/auth/email_verify.test.ts (GREEN phase - needs implementation)
+- Similar flow: password reset (PASSWORD-001)
+```
+
+### Practice 2: Session Boundary Management
+
+**Before switching between tasks**:
+```markdown
+# Session Handoff Note
+
+## Completed
+✓ RED phase: 3 test cases for email verification
+✓ GREEN phase: Minimal implementation passing tests
+✓ REFACTOR: Added input validation
+
+## Status
+- Current: Ready for /alfred:3-sync
+- Next action: Run full test suite, then sync docs
+
+## Context for Next Session
+- SPEC: .moai/specs/SPEC-AUTH-015/spec.md
+- Tests: tests/auth/email_verify.test.ts (all passing)
+- Code: src/domain/email_service.py
+- Database migration: pending (see migrations/ directory)
+
+## Assumptions
+- SendGrid API key set in .env
+- Test mode uses mock email service
+- Database schema includes email_verified_at column
+```
+
+### Practice 3: Cleanup Before Session End
+
+```bash
+# Remove unnecessary cached files
+rm .moai/memory/temp-*.md
+
+# Archive completed memory files
+mv .moai/memory/feature-x-* .moai/memory/archive/
+
+# Keep only active session memory
+ls -la .moai/memory/
+# session-summary.md (current)
+# architecture.md (reference)
+# gotchas.md (patterns)
+```
+
+## Memory File Organization
+
+```
+.moai/
+├── memory/
+│   ├── session-summary.md      # Current session state
+│   ├── architecture.md         # System design reference
+│   ├── gotchas.md             # Common pitfalls
+│   ├── spec-index.md          # List of all SPECs + status
+│   ├── api-reference.md       # API endpoints quick lookup
+│   └── archive/               # Completed session notes
+│       ├── feature-auth-*
+│       └── feature-api-*
+└── specs/                      # Requirement specifications
+    ├── SPEC-AUTH-001/
+    ├── SPEC-USER-002/
+    └── SPEC-API-003/
+```
+
+## Context Optimization Checklist
+
+- [ ] Memory files describe architecture (not code)
+- [ ] Session summary updated before handoff
+- [ ] Key file locations cached (don't re-search)
+- [ ] Assumptions explicitly documented
+- [ ] No duplicate information between memory files
+- [ ] Archive files moved after session completion
+- [ ] All cached insights reference file paths
+- [ ] Memory files are Markdown (human-readable)
+
+## Best Practices
+
+✅ **DO**:
+- Use Explore for large searches
+- Cache results in memory files
+- Keep memory files < 500 lines each
+- Update session-summary.md before switching tasks
+- Reference memory files in handoff notes
+
+❌ **DON'T**:
+- Load entire src/ or docs/ directory upfront
+- Duplicate context between memory files
+- Store memory files outside `.moai/memory/`
+- Leave stale session notes (archive or delete)
+- Cache raw code (summarize logic instead)
+
+## Commands for Memory Management
+
+```bash
+# View current session memory
+cat .moai/memory/session-summary.md
+
+# List all memory files
+ls -la .moai/memory/
+
+# Archive completed work
+mv .moai/memory/feature-old-* .moai/memory/archive/
+
+# Search memory files
+grep -r "email verification" .moai/memory/
+
+# Count context usage estimate
+wc -w .moai/memory/*.md  # Total words
+```
+
+---
+
+**Reference**: Claude Code Context Management
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-cc-memory/templates/session-summary-template.md

@@ -0,0 +1,18 @@
+# Session Summary
+
+## Current Task
+- Feature: [description]
+- SPEC: [ID]
+- Status: [phase]
+
+## Key Files
+- Test: [path]
+- Impl: [path]
+- Config: [path]
+
+## Important Context
+- [Key insights]
+- [Related features]
+
+## Assumptions Made
+- [List assumptions]