opencodekit 0.0.1

package/dist/template/.opencode/.env.example

@@ -0,0 +1,193 @@
+# OpenCodeKit - Environment Variables Template
+# ============================================================================
+# Copy this file to .env and fill in your actual values
+# Location: .opencode/.env (project-specific) or ~/.config/opencode/.env (global)
+# ============================================================================
+
+# Configure bash command timeout (default: 120000ms = 2 minutes)
+OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=300000
+export OPENCODE_DISABLE_AUTOCOMPACT=0  # Disable broken compaction
+export OPENCODE_DISABLE_PRUNE=0        # Disable potentially buggy pruning
+export OPENCODE_EXPERIMENTAL_TURN_SUMMARY=1
+export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=1
+export OPENCODE_EXPERIMENTAL_EXA=1
+
+# =============================================================================
+# MCP SERVICES (Remote APIs)
+# =============================================================================
+
+# Context7 - Up-to-date library documentation from 37.6k+ libraries
+# GitHub: https://github.com/upstash/context7
+# Get API key: https://context7.com
+CONTEXT7_API_KEY=your_context7_api_key_here
+
+# Exa - Advanced web search and code context from 3.3k repos
+# GitHub: https://github.com/exa-labs/exa-mcp-server
+# Get API key: https://exa.ai
+EXA_API_KEY=your_exa_api_key_here
+
+# GitLab Knowledge Graph (gkg) - Local codebase semantic search
+# Documentation: https://gitlab-org.gitlab.io/rust/knowledge-graph/
+# Install: https://gitlab-org.gitlab.io/rust/knowledge-graph/getting-started/install/
+# Note: Runs locally on http://localhost:27495/mcp (no API key needed)
+
+# GitHub Grep (gh_grep) - Search 1M+ public GitHub repositories
+# GitHub: https://github.com/Shachlan/grep.app-mcp
+# Note: Public service at https://mcp.grep.app (no API key needed)
+
+# =============================================================================
+# BACKLOG.MD MCP (Task Management)
+# =============================================================================
+# Markdown-native task manager with git-based project board
+# GitHub: https://github.com/MrLesk/Backlog.md (4k+ stars)
+# Install: npm install -g backlog-md
+# Note: Runs locally, no API key needed (enabled by default)
+
+# =============================================================================
+# MCP CODE-MODE (Optional - for Python code execution)
+# =============================================================================
+# GitHub: https://github.com/draphonix/mcp-code-mode
+# Enable in opencode.json: "code-mode": { "enabled": true }
+
+# OpenAI API (for code-mode LLM)
+# Get API key: https://platform.openai.com/api-keys
+# OPENAI_API_KEY=your_openai_api_key_here
+
+# Google Gemini API (alternative for code-mode)
+# Get API key: https://aistudio.google.com/apikey
+# GEMINI_API_KEY=your_gemini_api_key_here
+
+# =============================================================================
+# FIGMA MCP (Optional - for Figma integration)
+# =============================================================================
+# Framelink MCP for Figma - Extract layout info and design tokens
+# GitHub: https://github.com/GLips/Figma-Context-MCP (11.9k+ stars)
+# Enable in opencode.json: "Framelink MCP for Figma": { "enabled": true }
+# Get API key: Figma -> Settings -> Personal Access Tokens
+
+# FIGMA_API_KEY=your_figma_api_key_here
+
+# =============================================================================
+# AI MULTIMODAL SKILL (Optional - for media processing with Gemini)
+# =============================================================================
+# Used by: @.opencode/skills/stack/ai-multimodal/
+# Same as GEMINI_API_KEY above if already set
+
+# GEMINI_API_KEY=your_gemini_api_key_here
+
+# Optional: Use Vertex AI instead of AI Studio
+# GEMINI_USE_VERTEX=true
+# VERTEX_PROJECT_ID=your-gcp-project-id
+# VERTEX_LOCATION=us-central1
+
+# =============================================================================
+# DEVOPS SKILL (Optional - for cloud deployments)
+# =============================================================================
+# Used by: @.opencode/skills/core/devops/
+
+# Cloudflare (Workers, R2, D1, Pages)
+# Get from: https://dash.cloudflare.com
+# CLOUDFLARE_API_TOKEN=your_cloudflare_api_token_here
+# CLOUDFLARE_ACCOUNT_ID=your_cloudflare_account_id_here
+
+# Google Cloud Platform
+# Download service account key: IAM & Admin -> Service Accounts -> Create Key
+# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
+# GCP_PROJECT_ID=your-project-id
+# GCP_REGION=us-central1
+
+# Docker Registry (optional)
+# DOCKER_USERNAME=your_docker_username
+# DOCKER_PASSWORD=your_docker_password
+
+# =============================================================================
+# CUSTOM MCP SERVERS (Add your own)
+# =============================================================================
+# Add any environment variables your custom MCP servers need here
+# Example:
+# MY_CUSTOM_API_KEY=your_custom_api_key_here
+
+# =============================================================================
+# SECURITY NOTES
+# =============================================================================
+# 1. NEVER commit .env files to version control
+# 2. Add .env to .gitignore (already included in template)
+# 3. Use different credentials for dev/staging/production
+# 4. Rotate API keys regularly
+# 5. Use least-privilege principle for all tokens
+# 6. Keep .env.example in version control (with placeholder values only)
+
+# =============================================================================
+# PRIORITY & PRECEDENCE
+# =============================================================================
+# Environment variables are loaded in this order (first found wins):
+# 1. Project-specific: .opencode/.env (takes precedence)
+# 2. Global config: ~/.config/opencode/.env (fallback)
+# 3. System environment: export CONTEXT7_API_KEY=... (lowest priority)
+
+# =============================================================================
+# REQUIRED vs OPTIONAL
+# =============================================================================
+# REQUIRED (for core MCP functionality):
+# - CONTEXT7_API_KEY (library docs)
+# - EXA_API_KEY (web search + code context)
+
+# LOCAL MCP SERVERS (no API key needed):
+# - gkg (GitLab Knowledge Graph) - Install first, runs on localhost:27495
+# - backlog (Backlog.md) - Install via npm, runs locally
+# - gh_grep (GitHub Grep) - Public service, no install needed
+
+# OPTIONAL (enable specific features):
+# - OPENAI_API_KEY or GEMINI_API_KEY (code-mode execution)
+# - FIGMA_API_KEY (Figma integration)
+# - CLOUDFLARE_* (cloud deployments)
+# - GCP_* (Google Cloud deployments)
+
+# =============================================================================
+# GETTING STARTED (Minimal Setup)
+# =============================================================================
+# 1. Copy this file:
+#    cp .opencode/.env.example .opencode/.env
+#
+# 2. Add required keys (minimum):
+#    CONTEXT7_API_KEY=...
+#    EXA_API_KEY=...
+#
+# 3. Verify .env is in .gitignore:
+#    grep ".env" .gitignore
+#
+# 4. Test configuration:
+#    opencode # Should load without errors
+
+# =============================================================================
+# TROUBLESHOOTING
+# =============================================================================
+# "API key not found" errors:
+# - Check .env file location (.opencode/.env or ~/.config/opencode/.env)
+# - Verify no typos in variable names (case-sensitive)
+# - Ensure .env file has no quotes around values (CONTEXT7_API_KEY=abc not "abc")
+# - Restart OpenCode after adding new variables
+
+# "MCP server failed to start":
+# - Check MCP server is enabled in opencode.json
+# - Verify command path exists (e.g., python, npx)
+# - Check server-specific logs in ~/.config/opencode/logs/
+
+# =============================================================================
+# RESOURCES
+# =============================================================================
+# OpenCode Documentation: https://opencode.ai/docs
+
+# MCP Services:
+# - Context7: https://context7.com (API key) | https://github.com/upstash/context7
+# - Exa: https://exa.ai (API key) | https://github.com/exa-labs/exa-mcp-server
+# - GitLab Knowledge Graph: https://gitlab-org.gitlab.io/rust/knowledge-graph/
+# - GitHub Grep: https://github.com/Shachlan/grep.app-mcp
+# - Backlog.md: https://github.com/MrLesk/Backlog.md
+# - MCP Code Mode: https://github.com/draphonix/mcp-code-mode
+# - Figma Context MCP: https://github.com/GLips/Figma-Context-MCP
+
+# Other APIs:
+# - Gemini API: https://aistudio.google.com/apikey
+# - OpenAI API: https://platform.openai.com/api-keys
+# - Cloudflare: https://dash.cloudflare.com

package/dist/template/.opencode/AGENTS.md

@@ -0,0 +1,214 @@
+# OpenCode Global Rules
+
+## Priority Hierarchy
+
+1. Security constraints (always first)
+2. Anti-hallucination rule (overrides all except security)
+3. Delegation rules (check before tool calls)
+4. Skills check (`find_skills` → `use_skill`)
+5. User explicit requests
+6. Base prompt behaviors
+7. Global rules (this file)
+8. Project conventions (nested AGENTS.md files)
+
+## Delegation
+
+**Check before any tool call. Delegate if task involves search or research.**
+
+| Task Type         | Delegate To | Trigger Words                                        |
+| ----------------- | ----------- | ---------------------------------------------------- |
+| Code search       | @explore    | find, where is, search, how does X work, locate      |
+| External research | @scout      | research, compare, docs for, API for, best practices |
+| Code review/debug | @review     | review, audit, debug, why broken, root cause         |
+| Architecture      | @planner    | design, architect, plan, structure, phases           |
+
+**Execute directly**: Single-file edits, explicit commands, answering from loaded context.
+
+## Anti-Hallucination
+
+- **Major features**: Check task exists (`bd show <id>`)
+- **Bug fixes/edits**: Proceed directly; document clearly
+- **Before commit**: Close task with reason (`bd close <id> --reason "..."`)
+- **Find work**: Use `bd ready` for unblocked tasks
+
+## Universal Standards
+
+### Communication
+
+- Under 4 lines for typical responses
+- Brief preamble before big tool calls
+- No explanation summaries unless asked
+- Use `file:line_number` format for code references
+- No emojis unless explicitly requested
+- Keep going until query resolved; don't ask to continue
+
+### Execution
+
+- Batch independent tool calls (parallel)
+- Verify with tools; don't assume
+- Obey project AGENTS.md files (nested takes precedence)
+- Prioritize technical accuracy; disagree when necessary
+
+### Planning
+
+- TodoWrite BEFORE work; mark completed immediately
+- Verify assumptions with tools
+
+### Security
+
+- Defensive security only
+- Refuse credential harvesting
+- Allow security analysis, detection rules, vulnerability explanations
+
+## Tool Priority
+
+**GKG tools → Built-in tools**
+
+| Priority | Tools                             | Use For                          |
+| -------- | --------------------------------- | -------------------------------- |
+| 1        | `gkg_search_codebase_definitions` | Find symbols by name             |
+| 1        | `gkg_get_references`              | Find all usages                  |
+| 1        | `gkg_repo_map`                    | API-level overview               |
+| 2        | `grep`, `glob`                    | Pattern matching, file discovery |
+| 2        | `read`, `edit`, `write`           | File operations                  |
+
+**Rule**: Always `read` before `edit` to verify content.
+
+## Research Tools
+
+| Tool                                        | Use For                                                | Performance Notes                  |
+| ------------------------------------------- | ------------------------------------------------------ | ---------------------------------- |
+| `augment-context-engine_codebase-retrieval` | Codebase understanding, architecture analysis          | ~74s avg, 200K context, 67% CCEval |
+| `context7`                                  | Library docs (try first)                               | Fast, external APIs                |
+| `websearch`                                 | Docs not in Context7, recent releases, troubleshooting | General web search                 |
+| `codesearch`                                | Real implementation patterns from GitHub               | Public repo examples               |
+| `webfetch`                                  | Specific URL user provided                             | Direct URL fetch                   |
+
+**Augment Context Engine Best Practices**:
+
+- **When to use**: Complex queries like "How does authentication work?", "What's the architecture?", "Where is X implemented?"
+- **When NOT to use**: Simple lookups ("find function foo"), specific file reads, known symbol references
+
+## Error Handling
+
+- **Transient** (network, timeout): Retry 2x with backoff
+- **Rate limit**: Stop, report to user
+- **Logic error**: Change strategy, don't repeat
+
+## Memory System
+
+```
+.opencode/memory/
+  _templates/     # Task templates
+  handoffs/       # Phase transitions
+  research/       # Research findings
+```
+
+- `memory-read` - Load previous context
+- `memory-update` - Save learnings
+- Task tracking uses Beads (`bd` CLI)
+
+## Session Management
+
+**Philosophy**: Short sessions (<150k tokens) beat long bloated ones. Agents get worse with too much context. Cost is exponential.
+
+### Session Tools
+
+**`list_sessions`** - Discover available sessions before reading
+
+```
+list_sessions(limit=10, project="current")           # Current project
+list_sessions(since="today")                          # Today's sessions
+list_sessions(project="all", since="yesterday")       # Cross-project
+```
+
+**`read_session`** - Pull context from previous session
+
+```
+read_session("last")                                  # Most recent
+read_session("2 ago", project="current")              # 2nd most recent
+read_session("today")                                 # Today's first session
+read_session("ses_abc123", focus="file changes")      # Specific aspect
+```
+
+### When to Start New Session
+
+- Completing distinct task from `bd ready`
+- Token usage approaching 150k
+- Switching phases (implementation → review → testing)
+- After handoff (`/handoff <bead-id>`)
+
+### Session Workflow Pattern
+
+```
+Session 1: Implement feature X (80k tokens)
+  ↓ close, update memory
+Session 2: list_sessions() → read_session("last") → Refactor (60k tokens)
+  ↓
+Session 3: read_session("previous") → Add tests (90k tokens)
+  ↓
+Session 4: read_session refs → Final review (100k tokens)
+```
+
+**Result**: 4 fresh contexts vs 1 degraded 330k context. Better performance, lower cost.
+
+### Context Transfer
+
+Use all three:
+
+1. `read_session("last")` - Previous session work
+2. Git state - `git diff`, `git log` - Code changes
+3. Memory files - `.opencode/memory/*` - Persistent context
+4. Beads - `bd show <id>` - Task specs
+
+**Don't**: Carry everything forward. Extract what's needed, discard the rest.
+
+## Beads Usage
+
+**Session start**: `bd doctor --fix` then `bd ready`
+**Session end**: Complete one bead fully before starting next
+**Weekly**: `bd cleanup --older-than 7d` then `bd sync`
+
+**Philosophy**: Beads is execution, not planning. Plan elsewhere, track in Beads.
+
+## Skills System
+
+Use `find_skills` → `use_skill` when:
+
+| Situation                  | Skill                               |
+| -------------------------- | ----------------------------------- |
+| Creating something new     | `brainstorming`                     |
+| Bug or unexpected behavior | `systematic-debugging`              |
+| Implementing feature       | `test-driven-development`           |
+| Before commit/done         | `verification-before-completion`    |
+| Complex multi-step work    | `writing-plans` → `executing-plans` |
+| Finished implementation    | `requesting-code-review`            |
+| Building UI                | `frontend-aesthetics`               |
+| UI/UX with images          | `ui-ux-research`                    |
+| Large codebase research    | `gemini-large-context`              |
+
+Skip for simple questions, quick edits, or conversations.
+
+## Gemini CLI (Large Context)
+
+Use when analysis needs >100KB context or image analysis.
+
+```bash
+# Codebase analysis
+gemini -p "@src/ [your question]"
+
+# Image analysis (interactive)
+gemini
+@mockup.png Analyze this UI design
+```
+
+**Default**: `gemini-2.5-pro` (1M tokens)
+**Fast**: `gemini-2.5-flash` with `-m gemini-2.5-flash`
+
+## Core Constraints
+
+- No sudo
+- POSIX compatible (macOS/Linux)
+- Manual verification for config changes
+- No auto-documentation without request
+- Use absolute paths

package/dist/template/.opencode/README.md

@@ -0,0 +1,269 @@
+# 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 (5 total)
+├── command/               # Custom commands (26 workflows)
+├── superpowers/skills/    # Domain expertise (16 skills)
+├── tool/                  # Custom MCP 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
+# 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
+- Figma: https://www.figma.com/developers/api#access-tokens
+
+---
+
+## Agent System (5 Custom + 2 Built-in)
+
+**Primary Agents:**
+
+- **@build** - Main orchestrator (Claude Opus 4.5) - handles 70% of work
+- **@rush** - Fast agent (GLM-4.6) - same capabilities, faster
+
+**Subagents:**
+
+- **@planner** - Architecture, multi-phase coordination
+- **@scout** - External research (library docs + GitHub patterns)
+- **@review** - Code review + debugging + security audit
+
+**Built-in (OpenCode):**
+
+- **@explore** - Fast codebase search
+- **@general** - Simple tasks and fallback
+
+---
+
+## Custom Commands (26 workflows)
+
+**Invoke with `/` prefix:**
+
+- `/commit` - Intelligent git commits
+- `/pr` - Create pull requests
+- `/design` - Thoughtful design with brainstorming
+- `/fix` - Systematic debugging
+- `/research` - Deep documentation search
+- `/review-codebase` - Comprehensive audit
+
+**See:** `.opencode/command/` for all commands
+
+---
+
+## Skills System (16 skills)
+
+**Core:** brainstorming, writing-plans, executing-plans, verification-before-completion
+**Code:** requesting-code-review, receiving-code-review, root-cause-tracing
+**Advanced:** gemini-large-context, subagent-driven-development, dispatching-parallel-agents
+
+**Note:** Skills load via `use_skill()` in commands
+
+---
+
+## Memory System (2-Layer Architecture)
+
+```
+Memory (Permanent)     → Beads (Multi-session)    → Git (Audit Trail)
+.opencode/memory/       .beads/artifacts/          .git/
+```
+
+**Memory:** Permanent knowledge, decisions, learnings  
+**Beads:** Multi-session tasks with spec/research/plan/review artifacts  
+**Git:** Automatic execution history
+
+**See:** `INTEGRATION_OVERVIEW.md` for complete architecture
+
+---
+
+## MCP Services
+
+**Enabled by default (5 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/
+
+**Optional (disabled by default):**
+
+5. **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 → @scout (docs + GitHub patterns)
+Result: Comprehensive research doc
+```
+
+### Complex Feature
+
+```
+User: "Build auth system"
+@build → @planner (4 phases)
+@planner → @review (security audit)
+Result: Secure auth with tests
+```
+
+### Using Commands
+
+```
+User: "/design implement dashboard"
+@build: [loads brainstorming 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 with `use_skill()`
+- Use /design to load brainstorming
+- Use /fix 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 after major phases
+- Document decisions in architecture notes
+- Log blockers in research findings
+- Keep research organized (YYYY-MM-DD-topic.md)
+
+**Delegation:**
+
+- Use @build for 70% of work
+- Delegate to @planner for 3+ phases
+- Use @review before deployment (code review + security)
+- Use @scout for library docs + GitHub patterns
+- Use @explore for codebase search
+
+---
+
+## Resources
+
+- **OpenCode Docs:** https://opencode.ai/docs
+- **Context7 API:** https://context7.com
+- **Exa API:** https://exa.ai
+- **Skills Documentation:** `superpowers/skills/`
+- **Architecture Guide:** `INTEGRATION_OVERVIEW.md`
+
+---
+
+**OpenCodeKit Template v2.2**  
+**Architecture:** Two-Layer (Memory + Beads + Git)  
+**Last Updated:** December 4, 2025