# OpenCodeKit Template - Configuration Guide

**Project-specific OpenCode configuration and custom extensions.**

---

## Quick Start

### 1. Environment Setup

```bash
# Copy environment template
cp .opencode/.env.example .opencode/.env

# Add required API keys (minimum)
# Edit .opencode/.env and add:
CONTEXT7_API_KEY=your_context7_api_key_here
EXA_API_KEY=your_exa_api_key_here
```

### 2. Verify Configuration

```bash
# Start OpenCode (should load without errors)
opencode

# Test MCP services
# In OpenCode chat: "search context7 for Next.js documentation"
```

---

## Directory Structure

```
.opencode/
├── .env.example           # Environment variables template (COPY TO .env)
├── README.md              # This file
├── opencode.json          # OpenCode configuration
├── AGENTS.md              # Global agent rules
├── INTEGRATION_OVERVIEW.md  # Architecture docs
│
├── agent/                 # Custom agents (7 total)
├── command/               # Custom commands (45+ workflows)
├── skills/                # Domain expertise (24 skills)
├── tool/                  # Custom MCP tools (4 tools)
└── memory/                # Persistent context
```

---

## Required Environment Variables

**Minimum setup (.opencode/.env):**

```bash
# Required for core functionality
CONTEXT7_API_KEY=your_context7_api_key_here  # Library docs
EXA_API_KEY=your_exa_api_key_here            # Web search
```

**Optional (enable specific features):**

```bash
# Code-mode execution
OPENAI_API_KEY=your_openai_api_key_here
# OR
GEMINI_API_KEY=your_gemini_api_key_here

# Figma integration
FIGMA_API_KEY=your_figma_api_key_here

# Cloud deployments (devops skill)
CLOUDFLARE_API_TOKEN=your_token_here
CLOUDFLARE_ACCOUNT_ID=your_account_id_here
GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
```

**Get API keys:**

- Context7: https://context7.com
- Exa: https://exa.ai
- Gemini: https://aistudio.google.com/apikey
- OpenAI: https://platform.openai.com/api-keys

---

## Agent System (7 Agents)

**Primary Agents:**

- **@build** - Main agent (Claude Sonnet 4.5) - handles 70% of work
- **@rush** - Fast agent (Claude Haiku 4.5) - same capabilities, faster/cheaper

**Subagents (Delegated):**

- **@plan** - Planning for 3+ phase tasks
- **@orchestrator** - Multi-agent coordination (5+ phases, 3+ agents)
- **@code-auditor** - Security + code review + testing
- **@researcher** - Web + codebase research
- **@general** - Simple tasks and fallback

---

## Custom Commands (45+ workflows)

**Invoke with `/` prefix:**

- `/commit` - Intelligent git commits
- `/pr` - Create pull requests
- `/design/good` - Thoughtful design
- `/fix/hard` - Systematic debugging
- `/research` - Deep documentation search
- `/review/codebase` - Comprehensive audit

**See:** `.opencode/command/` for all commands

---

## Skills System (24 skills)

**Core (8):** memory, code-review, debugging, devops, databases  
**Stack (7):** web-frameworks, frontend-design, ai-multimodal, better-auth  
**Specialized (9):** mcp-builder, shopify, thymeleaf, repomix

**Note:** Skills load via custom commands, NOT auto-load based on files

---

## Memory System (2-Layer Architecture)

```
Memory (Permanent)     → Backlog (Multi-session) → Git (Audit Trail)
.opencode/memory/       backlog/tasks/            .git/
```

**Memory:** Permanent knowledge, decisions, learnings  
**Backlog:** Multi-session projects, Facts/Guesses/Plans in notes  
**Git:** Automatic execution history

**See:** `INTEGRATION_OVERVIEW.md` for complete architecture

---

## MCP Services

**Enabled by default (7 total):**

1. **context7** - Up-to-date library documentation (37.6k+ libraries)
   - Requires: CONTEXT7_API_KEY
   - GitHub: https://github.com/upstash/context7

2. **exa** - Web search + code context (3.3k+ repos)
   - Requires: EXA_API_KEY
   - GitHub: https://github.com/exa-labs/exa-mcp-server

3. **gh_grep** - Search 1M+ public GitHub repositories
   - No API key needed (public service)
   - GitHub: https://github.com/Shachlan/grep.app-mcp

4. **gkg** - GitLab Knowledge Graph (local codebase semantic search)
   - No API key needed (runs locally on port 27495)
   - Docs: https://gitlab-org.gitlab.io/rust/knowledge-graph/
   - Install: Follow https://gitlab-org.gitlab.io/rust/knowledge-graph/getting-started/install/

5. **backlog** - Backlog.md task management (git-based project board)
   - No API key needed (runs locally)
   - GitHub: https://github.com/MrLesk/Backlog.md (4k+ stars)
   - Install: `npm install -g backlog-md`

**Disabled (enable in opencode.json):**

6. **code-mode** - Python code execution with LLM assistance
   - Requires: OPENAI_API_KEY or GEMINI_API_KEY
   - GitHub: https://github.com/draphonix/mcp-code-mode
   - Enable: Set `"code-mode": { "enabled": true }` in opencode.json

7. **Framelink MCP for Figma** - Extract Figma layouts and design tokens
   - Requires: FIGMA_API_KEY
   - GitHub: https://github.com/GLips/Figma-Context-MCP (11.9k+ stars)
   - Enable: Set `"Framelink MCP for Figma": { "enabled": true }` in opencode.json

---

## Getting Started Examples

### Simple Task

```
User: "Find all TypeScript files"
@build: [executes directly]
Result: 42 files found
```

### Research Task

```
User: "Research Next.js 14 App Router"
@build → @researcher
Result: Comprehensive research doc
```

### Complex Feature

```
User: "Build auth system"
@build → @plan (4 phases)
@plan → @researcher, @code-auditor
Result: Secure auth with tests
```

### Using Commands

```
User: "/design/good implement dashboard"
@build: [loads frontend-design skill]
Result: Dashboard with shadcn/ui
```

---

## Troubleshooting

**"API key not found":**

- Check .env location (.opencode/.env or ~/.config/opencode/.env)
- No quotes around values (CONTEXT7_API_KEY=abc not "abc")
- Restart OpenCode after changes

**"MCP server failed":**

- Check enabled: true in opencode.json
- Verify command path (python, npx in PATH)
- Check logs: ~/.config/opencode/logs/

**"Skills not loading":**

- Skills load via commands, NOT file types
- Use /design/good to load frontend-design
- Use /fix/hard to load debugging skills

---

## Best Practices

**Environment:**

- Use .opencode/.env for project keys
- Use ~/.config/opencode/.env for global keys
- Never commit .env files
- Rotate API keys regularly

**Memory:**

- Update memory.md after major phases
- Document decisions in architecture-decisions.md
- Log blockers in blockers.md
- Keep research organized (YYYY-MM-DD-topic.md)

**Delegation:**

- Use @build for 70% of work
- Delegate to @plan for 3+ phases
- Use @code-auditor before deployment
- Use @researcher for unfamiliar libraries

---

## Resources

- **OpenCode Docs:** https://opencode.ai/docs
- **Context7 API:** https://context7.com
- **Exa API:** https://exa.ai
- **Skills Documentation:** `skills/README.md`
- **Architecture Guide:** `INTEGRATION_OVERVIEW.md`

---

**OpenCodeKit Template v2.0**  
**Architecture:** Two-Layer (Memory + Backlog + Git)  
**Last Updated:** November 20, 2025
