opencodekit 0.16.17 → 0.16.18

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

@@ -1,512 +1,79 @@
-# OpenCodeKit Template - Configuration Guide
+# OpenCodeKit Template Configuration
 
-**Project-specific OpenCode configuration and custom extensions.**
+This directory contains project-specific OpenCode configuration: agents, commands, skills, tools, plugins, and memory conventions.
 
----
+## Layout
 
-## 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
-
-```
+```text
 .opencode/
-├── .env.example           # Environment variables template (COPY TO .env)
-├── README.md              # This file
-├── opencode.json          # OpenCode configuration
-├── dcp.jsonc              # DCP plugin configuration (context pruning)
-├── AGENTS.md              # Global agent rules
-│
-├── agent/                 # Custom agents (9 total)
-├── command/               # Custom commands (14 workflows)
-├── skill/                 # Domain expertise (10 skills)
-├── tool/                  # Custom MCP tools (memory-*, observation, swarm-*)
-├── plugin/                # Background plugins (memory, sessions, lsp, truncator)
-└── memory/                # Persistent context
-```
-
----
-
-## Context Management: DCP Plugin (Beta)
-
-This kit uses **Dynamic Context Pruning (DCP)** plugin for intelligent context management.
-
-### Why DCP?
-
-- **AI-driven pruning**: `prune`, `distill`, and `compress` tools let the AI decide what to remove
-- **Zero-cost strategies**: Deduplication, supersede writes, and error purging run automatically
-- **Turn protection**: Prevents premature pruning of recent tool outputs
-- **File protection**: Critical config files are never auto-pruned
-
-### Configuration
-
-DCP is configured via `.opencode/dcp.jsonc`:
-
-```jsonc
-{
-  "enabled": true,
-  "pruneNotification": "off", // "minimal" or "detailed" for visibility
-  "turnProtection": {
-    "enabled": true,
-    "turns": 4, // Protect tool outputs for 4 turns
-  },
-  "tools": {
-    "prune": { "enabled": true }, // Remove noise without preservation
-    "distill": { "enabled": true }, // Extract key findings before removing
-    "compress": { "enabled": true }, // Collapse message ranges into summaries
-  },
-  "strategies": {
-    "deduplication": { "enabled": true }, // Remove duplicate reads
-    "supersedeWrites": { "enabled": true }, // Prune write inputs after read
-    "purgeErrors": { "enabled": true, "turns": 4 }, // Remove error inputs
-  },
-}
-```
-
-### DCP Commands
-
-- `/dcp` - Show available DCP commands
-- `/dcp context` - Token usage breakdown by category
-- `/dcp stats` - Cumulative pruning statistics
-- `/dcp sweep` - Prune all tools since last user message
-- `/dcp sweep 10` - Prune last 10 tools
-
-### How It Works With OpenCode's Built-in Compaction
-
-OpenCode has internal compaction (not user-configurable via `opencode.json`):
-
-- **Built-in prune**: FIFO removal when context exceeds thresholds
-- **PRUNE_PROTECT = 40,000** tokens - Always keeps last 40K of tool outputs
-- **PRUNE_MINIMUM = 20,000** tokens - Only prunes if >20K tokens can be saved
-- **Protected tools**: `skill` outputs are never pruned
-
-**DCP complements this** by adding AI-driven, strategic pruning on top:
-
-| System                | Role                                     |
-| --------------------- | ---------------------------------------- |
-| **DCP tools**         | Active management (AI decides what/when) |
-| **OpenCode built-in** | Passive safety net (automatic FIFO)      |
-
-> **Note**: The `compaction` key is NOT in the official OpenCode config schema.
-> Built-in compaction behavior is controlled internally, not via user config.
-
-### Protected Files
-
-These patterns are never auto-pruned (configured in `dcp.jsonc`):
-
-- `**/.env*` - Environment files
-- `**/AGENTS.md` - Agent rules
-- `**/.opencode/**` - OpenCode config
-- `**/.beads/**` - Task tracking
-- `**/package.json`, `**/tsconfig.json`, `**/biome.json` - Project config
-
-### Cache Hit Trade-off
-
-DCP modifies message content before sending to LLMs, which affects prompt caching:
-
-- ~65% cache hit rate with DCP vs ~85% without
-- Token savings typically outweigh cache miss cost in long sessions
-- **Best for**: GitHub Copilot, Google Antigravity (request-based pricing)
-
----
-
-## 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
+├── AGENTS.md                # Global operating rules for agents
+├── opencode.json            # OpenCode runtime configuration
+├── dcp.jsonc                # Dynamic context pruning settings
+├── agent/                   # Agent definitions (9)
+├── command/                 # Slash commands (14)
+├── skill/                   # Skill library used by agents/commands
+├── tool/                    # Custom tools (memory, swarm, research, etc.)
+├── plugin/                  # OpenCode plugins and plugin-local SDK code
+├── memory/                  # Memory templates + project memory files
+└── .env.example             # Environment variable template
 ```
 
-**Optional (enable specific features):**
+## Quick Setup
 
 ```bash
-# Figma integration
-FIGMA_API_KEY=your_figma_api_key_here
-
-# Google Stitch (AI UI design)
-GOOGLE_CLOUD_PROJECT=your_gcp_project_id
-STITCH_ACCESS_TOKEN=$(gcloud auth print-access-token)
-
-# Cloud deployments (devops skill)
-CLOUDFLARE_API_TOKEN=your_token_here
-CLOUDFLARE_ACCOUNT_ID=your_account_id_here
-GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
+cp .opencode/.env.example .opencode/.env
 ```
 
-**Get API keys:**
-
-- Context7: https://context7.com
-- Exa: https://exa.ai
-- Figma: https://www.figma.com/developers/api#access-tokens
-- Google Cloud: https://console.cloud.google.com (for Stitch)
-
----
-
-## Agent System (9 Custom Agents)
-
-**Primary Agents:**
-
-- **@build** - Main orchestrator (Kimi K2.5) - handles 70% of work
-- **@plan** - Architecture, multi-phase coordination
-
-**Specialist Subagents:**
-
-- **@general** - Fast subagent for small, well-defined tasks
-- **@explore** - Fast codebase search specialist
-- **@scout** - External research (library docs + GitHub patterns)
-- **@review** - Code review + debugging + security audit
-- **@vision** - UI/UX design: mockup, UI review, accessibility, aesthetics
-- **@looker** - Media extraction (images, PDFs, diagrams via OCR)
-- **@painter** - Image generation and editing (mockups, icons, assets)
-
----
-
-## Custom Commands (14 workflows)
-
-**Invoke with `/` prefix:**
-
-- `/ship` - Ship code with verification
-- `/plan` - Create execution plan
-- `/start` - Start new work session
-- `/resume` - Resume from handoff
-- `/handoff` - Create session handoff
-- `/status` - Check project status
-- `/pr` - Create pull requests
-- `/review-codebase` - Full codebase review
-- `/research` - External research task
-- `/design` - Thoughtful design with brainstorming
-- `/ui-review` - UI/UX review
-- `/create` - Create new component/feature
-- `/init` - Initialize project
-- `/verify` - Verify changes
-
-**See:** `.opencode/command/` for all commands
+Add the keys you actually need for enabled services.
 
----
+## Agent and Command Workflow
 
-## Skills System (10 skills)
+- Spec-first flow: `/create` -> `/start <id>` -> `/ship <id>`
+- Use `/plan <id>` optionally for deeper implementation planning
+- Use `/status` and `/resume` for continuity
 
-**Core:** beads-bridge, defense-in-depth, mockup-to-code, playwriter, resend, session-management, subagent-driven-development, vercel-deploy-claimable, verification-before-completion, writing-skills
+## Skills
 
-**Note:** Skills load via native `skill()` tool. Commands auto-load relevant expertise.
+Skills live in `.opencode/skill/` and are loaded on demand with `skill({ name: "..." })`.
 
----
-
-## Memory System (2-Layer Architecture)
-
-```
-Memory (Permanent)     → Beads (Multi-session)    → Git (Audit Trail)
-.opencode/memory/       .beads/artifacts/          .git/
-```
-
-**Memory:** Permanent knowledge, decisions, learnings (SQLite + FTS5)
-**Beads:** Multi-session tasks with spec/research/plan/review artifacts
-**Git:** Automatic execution history
-
-**See:** `AGENTS.md` for global rules and tool priority
-
----
+- Core workflow examples: `beads`, `verification-before-completion`, `writing-plans`, `executing-plans`
+- Debug/reliability examples: `systematic-debugging`, `root-cause-tracing`, `defense-in-depth`
+- UI/design examples: `frontend-design`, `visual-analysis`, `accessibility-audit`
 
 ## Custom Tools
 
-### Memory Tools
-
-- **memory-read** - Load previous context, templates
-- **memory-update** - Save learnings, handoffs
-- **memory-search** - FTS5 full-text search across observations
-- **memory-get** - Get full observation details by ID
-- **memory-timeline** - Chronological context around anchor
-- **memory-admin** - Database administration (maintenance, migration)
-- **observation** - Create structured observations (decision, bugfix, feature, etc.)
-
-### Swarm Tool
-
-- **swarm** - Unified swarm coordination with operations:
-  - `plan`: Task analysis with Kimi K2.5 PARL patterns
-  - `delegate`: Create delegation packets for workers
-  - `monitor`: Progress tracking for parallel tasks
-  - `sync`: Beads ↔ OpenCode todos synchronization
-
-### External Tools
-
-- **context7** - Library documentation lookup (resolve + query operations)
-- **grepsearch** - Search GitHub repos via grep.app
-
----
-
-## MCP Services
-
-**Enabled by default:**
-
-1. **context7** - Up-to-date library documentation (37.6k+ libraries)
-   - Native tool: `context7({ operation: "resolve"|"query" })`
-   - Step 1: Resolve library name → libraryId
-   - Step 2: Query docs with the libraryId
-
-2. **grepsearch** - Search 1M+ public GitHub repositories via grep.app
-   - Native tool: `grepsearch({ query: "...", language: [...] })`
-   - No API key needed (public service)
-
-**Skill-Embedded MCP (load on-demand):**
-
-3. **figma** - Extract Figma layouts and design tokens
-   - Requires: FIGMA_API_KEY
-   - Use: `skill({ name: "figma" })` then `skill_mcp()`
+Tools in `.opencode/tool/` are loaded by OpenCode and available to agents.
 
-4. **playwright** - Browser automation for testing
-   - No API key needed
-   - Use: `skill({ name: "playwright" })` then `skill_mcp()`
+- Memory: `memory-search`, `memory-get`, `memory-read`, `memory-update`, `memory-admin`, `memory-timeline`
+- Observability/orchestration: `observation`, `swarm`, `action-queue`
+- External research/docs: `context7`, `grepsearch`
 
-5. **stitch** - Google Stitch AI-powered UI design generation
-   - Requires: Google Cloud project with Stitch API enabled
-   - Currently disabled in config (set `enabled: true` to activate)
+## Plugins
 
----
+Current plugin source files in `.opencode/plugin/`:
 
-## Stitch MCP Setup
+- `memory.ts` - memory DB maintenance hooks + toast notifications
+- `sessions.ts` - session browsing/search/summarization tools
+- `compaction.ts` - compaction-time context injection and recovery protocol
+- `swarm-enforcer.ts` - `/create` -> `/start` -> `/ship` workflow enforcement
+- `skill-mcp.ts` - bridge for skill-scoped MCP servers/tools
+- `copilot-auth.ts` - GitHub Copilot auth/provider integration
 
-Google Stitch MCP enables AI-powered UI design generation directly from OpenCode.
+See `.opencode/plugin/README.md` for plugin details.
 
-### Prerequisites
+## Guardrails
 
-1. **Google Cloud CLI** installed: https://cloud.google.com/sdk/docs/install
-2. **Google Cloud Project** with billing enabled
+- Keep edits focused; avoid changing generated output under `dist/`.
+- Never commit `.env` values or credentials.
+- Prefer tool-based file operations over shell text manipulation in agent workflows.
+- Use `br` commands to track multi-session work and keep bead state accurate.
 
-### Setup Steps
-
-**Step 1: Authenticate with Google Cloud**
-
-```bash
-# Login to Google Cloud
-gcloud auth login
-
-# Set your project
-gcloud config set project YOUR_PROJECT_ID
-
-# Set up Application Default Credentials
-gcloud auth application-default login
-```
-
-**Step 2: Enable Stitch MCP**
-
-```bash
-# Enable the Stitch API
-gcloud services enable stitch.googleapis.com --project=YOUR_PROJECT_ID
-
-# Enable Stitch for MCP access (required!)
-gcloud beta services mcp enable stitch.googleapis.com --project=YOUR_PROJECT_ID
-```
-
-**Step 3: Set Environment Variables**
-
-Add to your `.opencode/.env` or export before starting OpenCode:
-
-```bash
-# Google Cloud Project ID
-GOOGLE_CLOUD_PROJECT=your-project-id
-
-# Access token (refresh when expired - tokens last ~1 hour)
-STITCH_ACCESS_TOKEN=$(gcloud auth print-access-token)
-```
-
-**Step 4: Enable in Config**
-
-Set `enabled: true` for stitch in `opencode.json`:
-
-```jsonc
-"mcp": {
-  "stitch": {
-    "enabled": true,
-    ...
-  }
-}
-```
-
-### Available Stitch Tools
-
-| Tool                               | Description                       |
-| ---------------------------------- | --------------------------------- |
-| `stitch_list_projects`             | List all your Stitch projects     |
-| `stitch_create_project`            | Create a new UI design project    |
-| `stitch_get_project`               | Get project details               |
-| `stitch_list_screens`              | List screens in a project         |
-| `stitch_get_screen`                | Get screen details with HTML code |
-| `stitch_generate_screen_from_text` | Generate UI from text prompt      |
-
-### Troubleshooting
-
-**"Stitch API not enabled":**
-
-```bash
-gcloud beta services mcp enable stitch.googleapis.com --project=YOUR_PROJECT_ID
-```
-
-**"Authentication failed":**
-
-```bash
-# Refresh your access token (expires after ~1 hour)
-export STITCH_ACCESS_TOKEN=$(gcloud auth print-access-token)
-# Restart OpenCode
-```
-
----
-
-## 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 → @plan (4 phases)
-@plan → @review (security audit)
-Result: Secure auth with tests
-```
-
-### Using Commands
-
-```
-User: "/design implement dashboard"
-@build: [loads brainstorming skill]
-Result: Dashboard with shadcn/ui
-```
-
----
-
-## Troubleshooting
-
-**"Notifications not working" (WSL/Windows):**
-
-If running OpenCode in WSL, notifications require additional setup:
+## Verification Baseline
 
 ```bash
-# 1. Install dependencies
-sudo apt install -y libnotify-bin dunst
-
-# 2. Start dunst (run each time you open WSL terminal)
-dunst >/dev/null 2>&1 &
-
-# 3. Or add to ~/.bashrc for auto-start:
-if ! pgrep -x dunst >/dev/null; then
-  dunst >/dev/null 2>&1 &
-fi
+npm run typecheck
+npm run lint
+npm run test
 ```
 
-**"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 native `skill()` tool (auto-discovered)
-- Use /design to load brainstorming
-- Use /fix to load systematic-debugging
-- Check `.opencode/skill/` directory exists
-
-**"Context growing too fast":**
-
-- Run `/dcp context` to see token breakdown
-- Run `/dcp sweep` to prune recent tool outputs
-- Use `distill` tool to preserve key info while removing raw outputs
-- DCP handles active pruning; OpenCode's built-in handles passive FIFO
-
----
-
-## Best Practices
-
-**Environment:**
-
-- Use .opencode/.env for project keys
-- Use ~/.config/opencode/.env for global keys
-- Never commit .env files
-- Rotate API keys regularly
-
-**Context Management (DCP):**
-
-- Use `/dcp context` to monitor token usage
-- Use `/dcp sweep` before starting new phases
-- Let DCP handle active pruning (turn protection prevents premature removal)
-- OpenCode's built-in compaction runs automatically as a safety net
-
-**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 @plan 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
-- **DCP Plugin:** https://github.com/Opencode-DCP/opencode-dynamic-context-pruning
-- **Context7 API:** https://context7.com
-- **Exa API:** https://exa.ai
-- **Skills Documentation:** `.opencode/skill/`
-- **Architecture Guide:** `AGENTS.md`
-
----
-
-**OpenCodeKit v0.15.7**
-**Architecture:** Two-Layer (Memory + Beads + Git)
-**Context Management:** DCP Plugin (Beta) - AI-driven pruning
-**Package:** `npx opencodekit` to scaffold new projects
-**Last Updated:** February 4, 2026
+For docs/config governance, run the validation scripts defined in `package.json`.