opencodekit 0.19.6 → 0.20.1

package/dist/template/.opencode/skill/compaction/SKILL.md

@@ -1,384 +0,0 @@
----
-name: compaction
-description: >
-  Use when context is growing large during long-running tasks and needs server-side or client-side
-  summarization to continue effectively. Covers compaction triggers, custom summarization patterns,
-  session handoff, and context preservation strategies.
-version: 1.0.0
-tags: [context, workflow]
-dependencies: []
----
-
-# Context Compaction - Managing Long-Running Sessions
-
-## When to Use
-
-- Context is growing large and needs compression/cleanup to continue.
-
-## When NOT to Use
-
-- Short sessions with low context usage where no compaction is needed.
-
-## Overview
-
-**Compaction = Summarization + Preservation + Continuity**
-
-Long-running sessions accumulate context (tool outputs, code reads, exploration results). When context approaches limits, compaction reduces it to essential information while preserving decision history and work state.
-
-## Context Budget Awareness
-
-### Token Thresholds
-
-| Context Usage | Status      | Action                                        |
-| ------------- | ----------- | --------------------------------------------- |
-| 0-50%         | 🟢 Normal   | Work freely                                   |
-| 50-70%        | 🟡 Watch    | Start compressing completed explorations      |
-| 70-85%        | 🟠 Compact  | Actively compress and sweep stale noise       |
-| 85-95%        | 🔴 Critical | Emergency compaction, prepare session handoff |
-| 95%+          | ⛔ Limit    | Session handoff required                      |
-
-### Monitoring
-
-Pay attention to these signals:
-
-- Completed phases accumulating without being compressed
-- Repeated file reads of the same content
-- Large bash outputs from builds/tests
-- Multiple exploration rounds without synthesis
-
-## Compaction Strategies
-
-### Strategy 1: Phase Compression (Preferred)
-
-Compress completed conversation phases into dense summaries. This is the primary DCP instrument in the installed beta.
-
-Compress completed conversation phases into dense summaries.
-
-```
-WHEN: A research phase is complete and findings are clear
-DO: compress({
-  topic: "Auth Research Complete",
-  content: {
-    startString: "unique text at phase start",
-    endString: "unique text at phase end",
-    summary: "Complete technical summary of findings..."
-  }
-})
-```
-
-**Key principle**: Only compress CLOSED chapters. Never compress active work.
-
-### Strategy 2: Sweep Stale Noise
-
-Use `/dcp sweep` after a phase is complete to remove stale/noisy content automatically.
-
-```
-WHEN: Wrong-target searches or superseded outputs are no longer needed
-DO: /dcp sweep
-```
-
-**Key principle**: Sweep only after the relevant phase is closed. If in doubt, keep it.
-
-### Strategy 3: Session Handoff
-
-When context is too large to compact further, hand off to a new session.
-
-```
-WHEN: Context > 85% and significant work remains
-DO:
-  1. Create handoff document with memory-update
-  2. Save all decisions with observation tool
-  3. Document current state and remaining work
-  4. Start new session with handoff reference
-```
-
-## Compaction Decision Tree
-
-```
-Is context growing large?
-├── NO → Continue working normally
-└── YES → What type of content is consuming space?
-    ├── Completed conversation phases → COMPRESS
-    ├── Stale/noisy closed-phase outputs → SWEEP
-    └── Everything is still relevant → SESSION HANDOFF
-```
-
-## Custom Summarization Patterns
-
-### For Code Exploration
-
-```markdown
-## Exploration Summary: [Component/Module]
-
-### Architecture
-
-- Entry point: `src/auth/index.ts`
-- Key classes: AuthService, TokenManager, SessionStore
-- Dependencies: jwt, bcrypt, redis
-
-### Key Findings
-
-- Auth flow: login → validate → issue JWT → store session
-- Token rotation: every 15 minutes via refresh endpoint
-- Session storage: Redis with 24h TTL
-
-### Decisions Made
-
-- Use existing TokenManager (don't replace)
-- Add rate limiting to login endpoint
-- Migrate session store from memory to Redis
-
-### Files to Modify
-
-- src/auth/service.ts (add rate limiting)
-- src/auth/session.ts (Redis integration)
-- src/config/redis.ts (new file)
-```
-
-### For Implementation Phase
-
-```markdown
-## Implementation Summary: [Feature]
-
-### Completed
-
-- [x] Database schema migration (src/db/migrations/004_auth.ts)
-- [x] API endpoints (src/routes/auth.ts) - 3 new routes
-- [x] Frontend forms (src/components/auth/) - Login, Register, Reset
-
-### Verification
-
-- TypeScript: ✅ passing
-- Tests: ✅ 12/12 passing
-- Lint: ✅ no issues
-
-### Remaining
-
-- [ ] Email verification flow
-- [ ] Rate limiting middleware
-
-### Key Decisions
-
-- JWT expiry: 15 minutes (refresh: 7 days)
-- Password hashing: bcrypt with 12 rounds
-- Session storage: Redis (not in-memory)
-```
-
-### For Debugging
-
-```markdown
-## Debug Summary: [Issue]
-
-### Symptoms
-
-- Error: "TypeError: Cannot read property 'id' of undefined"
-- Location: src/auth/middleware.ts:42
-- Trigger: POST /api/protected when token is expired
-
-### Root Cause
-
-- Token validation returns null on expired tokens
-- Middleware assumes valid token object, no null check
-- Race condition: token expires between validation and use
-
-### Fix Applied
-
-- Added null check in middleware (src/auth/middleware.ts:42)
-- Added token refresh attempt before rejecting (src/auth/refresh.ts)
-- Added test for expired token scenario (src/auth/**tests**/middleware.test.ts)
-
-### Verification
-
-- Tests: ✅ all passing including new test
-- Manual: ✅ expired token now triggers refresh
-```
-
-## Session Handoff Protocol
-
-When you must hand off to a new session:
-
-### 1. Create Handoff Document
-
-```typescript
-memory -
-  update({
-    file: "handoffs/YYYY-MM-DD-feature-name",
-    content: `# Session Handoff: [Feature Name]
-
-## Context
-[Why this session started, what was the goal]
-
-## Completed Work
-[What was done, files changed, decisions made]
-
-## Current State
-[Where things stand right now]
-
-## Remaining Work
-[What still needs to be done]
-
-## Key Decisions
-[Important choices made and why]
-
-## Files Modified
-[List of all files changed with brief description]
-
-## Gotchas
-[Things the next session should know]
-  `,
-    mode: "replace",
-  });
-```
-
-### 2. Save Key Observations
-
-```typescript
-observation({
-  type: "decision",
-  title: "Auth implementation approach",
-  narrative: "Chose JWT with Redis sessions because...",
-  facts: "JWT 15min expiry, Redis 24h TTL, bcrypt 12 rounds",
-  concepts: "authentication, sessions, tokens",
-  confidence: "high",
-});
-```
-
-### 3. Resume in New Session
-
-```typescript
-// In new session:
-memory - read({ file: "handoffs/YYYY-MM-DD-feature-name" });
-memory - search({ query: "auth implementation" });
-```
-
-## Integration with DCP Plugin
-
-This project uses `@tarquinen/opencode-dcp` for always-on context management (injected via `experimental.chat.system.transform`):
-
-- **compress**: Phase-level conversation compression (primary DCP tool in the installed beta)
-- **/dcp sweep**: Cleanup command for stale/noisy content after a phase is complete
-- **Prunable-tools list**: Auto-injected into messages with token estimates
-- **Nudge system**: Reminders every N tool calls + critical limit warnings
-
-**Division of responsibility:**
-
-- **DCP plugin**: Context budget rules, tool guidance, prunable-tools list, nudges (always present via system prompt)
-- **Compaction plugin** (`.opencode/plugin/compaction.ts`): Session continuity, beads state, handoff recovery, post-compaction protocol (fires during compaction events only)
-
-**Custom prompts (enabled):**
-
-DCP custom prompts are enabled (`experimental.customPrompts: true`). Override files live at `.opencode/dcp-prompts/overrides/`:
-
-- `compress-message.md` — 9-section structured summary format (Primary Request, Key Technical Concepts, Files/Code, Errors/Fixes, Problem Solving, User Messages, Pending Tasks, Current Work, Next Step)
-
-Override precedence: project (`.opencode/dcp-prompts/overrides/`) > config dir > global (`~/.config/opencode/dcp-prompts/overrides/`).
-
-## Post-Compaction Restoration Protocol
-
-**Critical:** After any compaction (server-side or DCP compress), you lose raw file content and active context. Immediately restore:
-
-### Step 1: Re-read Active Files (max 5)
-
-Re-read the files you were actively editing before compaction. Prioritize by recency — most recently modified first. Cap at 5 files, use offset/limit to read only the sections you need (~200 lines each).
-
-```
-After compaction, if you were editing src/auth.ts:
-read({ filePath: "src/auth.ts", offset: 30, limit: 50 })
-```
-
-**Why:** The Write/Edit tool requires a prior Read in the same session (`FileTime.assert()`). Without re-reading, your next edit attempt will fail.
-
-### Step 2: Restore Active Skill Context
-
-If you were using a skill before compaction, re-load it:
-
-```typescript
-skill({ name: "<active-skill>" });
-```
-
-Skills are prompt-injected — compaction drops them. Re-load to restore the workflow.
-
-### Step 3: Check Todo State
-
-Review your TodoWrite list to re-establish task tracking:
-
-```
-- What was in_progress?
-- What was pending?
-- What was completed?
-```
-
-### Step 4: Verify Git Position
-
-```bash
-git branch --show-current
-git status --short
-```
-
-Confirms you're on the right branch and shows any uncommitted changes.
-
-### Step 5: Scan Memory for Context
-
-If the compaction was heavy (>50% reduction), check memory for recent observations:
-
-```typescript
-memory - search({ query: "<current task keywords>", limit: 3 });
-```
-
-### Why This Protocol Exists
-
-Compaction strips raw file content, tool outputs, and skill prompts. Without restoration:
-
-- File edits fail (`FileTime.assert` — no prior read)
-- Line-number precision is lost (you're guessing, not citing)
-- Skill workflows are inactive (no prompt injection)
-- Task tracking is disconnected (todos lost in compressed summary)
-
-## Anti-Patterns
-
-### ❌ Premature Compaction
-
-```
-// DON'T compress a file you're about to edit
-compress({ ... })  // Loses exact line numbers you need
-edit({ ... })      // Now you can't find the right location
-```
-
-**Fix**: Keep raw content while actively editing. Compress AFTER the edit phase.
-
-### ❌ Compressing Active Work
-
-```
-// DON'T compress a conversation phase you might return to
-compress({ summary: "Explored auth options" })
-// Later: "Wait, which options did we consider?"
-```
-
-**Fix**: Only compress CLOSED chapters where findings are crystallized.
-
-### ❌ Ignoring Context Growth
-
-```
-// DON'T let context grow unchecked until hitting limits
-// By the time you notice, emergency compaction loses information
-```
-
-**Fix**: Monitor regularly. Compress at natural breakpoints and use `/dcp sweep` after closed phases.
-
-## Checklist
-
-Before compacting:
-
-- [ ] Identified what type of content is consuming context
-- [ ] Chosen appropriate strategy (compress/sweep/handoff)
-- [ ] Verified raw content is no longer needed for active work
-- [ ] Captured all key details in the compression summary or handoff
-- [ ] Saved important decisions as observations
-- [ ] Created handoff document if switching sessions
-
-During long sessions:
-
-- [ ] Compressing completed phases at natural breakpoints
-- [ ] Sweeping stale/noisy outputs after phase completion
-- [ ] Monitoring context usage trends
-- [ ] Planning session handoff if approaching limits

package/dist/template/.opencode/skill/session-management/SKILL.md

@@ -1,9 +0,0 @@
----
-description: "Merged into context-management. Load that skill instead."
----
-
-# Session Management
-
-> This skill has been merged into `context-management` which now covers both context and session lifecycle management.
-> 
-> Load `context-management` instead.

package/dist/template/.opencode/skill/source-code-research/SKILL.md

@@ -1,293 +0,0 @@
----
-name: source-code-research
-description: "Use when researching library implementation details beyond API docs. Fetches package source code using opensrc to understand internals, edge cases, and implementation patterns. Complements documentation-based research with actual code inspection."
-version: 1.0.0
-tags: [research, code-quality]
-dependencies: [opensrc]
----
-
-# Source Code Research - Deep Library Investigation
-
-Fetch and analyze package source code when documentation is insufficient.
-
-## When to Use
-
-- Documentation gaps — API docs don't explain behavior clearly
-- Edge cases — need to understand how library handles corner cases
-- Implementation details — need to see actual code, not just interfaces
-- Debugging — library behaving unexpectedly, need to trace internals
-- Evaluation — deciding if library fits requirements, need to assess quality
-- Type definitions — TypeScript types exist but implementation unclear
-
-## When NOT to Use
-
-- Official docs answer your question (check Context7 first)
-- You only need API syntax (codesearch is faster)
-- Library is too large to analyze in session (>50k LOC)
-
-## Prerequisites
-
-OpenSrc must be available:
-
-```bash
-npx opensrc --help
-```
-
-If not installed, it will be fetched via npx automatically.
-
-## Workflow
-
-### Step 1: Identify What to Fetch
-
-Determine the minimal package/repo needed:
-
-```typescript
-// If researching a specific npm package
-const target = "zod"; // Just the package name
-
-// If researching Python library
-const target = "pypi:requests";
-
-// If researching Rust crate
-const target = "crates:serde";
-
-// If researching GitHub repo directly
-const target = "vercel/ai"; // or "github:vercel/ai@v3.0.0"
-```
-
-### Step 2: Fetch Source Code
-
-Run opensrc to clone the repository:
-
-```bash
-npx opensrc <package>
-```
-
-**Examples:**
-
-```bash
-npx opensrc zod                    # Fetch latest zod from npm
-npx opensrc zod@3.22.0             # Fetch specific version
-npx opensrc pypi:requests          # Fetch Python package
-npx opensrc vercel/ai              # Fetch GitHub repo
-npx opensrc vercel/ai@v3.0.0       # Fetch specific tag
-```
-
-**What happens:**
-
-- Clones source to `opensrc/repos/<host>/<owner>/<repo>/`
-- Auto-detects version from lockfiles if no version specified
-- Updates `opensrc/sources.json` with metadata
-- Adds `opensrc/` to `.gitignore` automatically (asks once)
-
-### Step 3: Locate Relevant Code
-
-Use search tools to find code you need:
-
-```typescript
-// Find all TypeScript source files
-glob({ pattern: "opensrc/**/src/**/*.ts" });
-
-// Search for specific function/class
-grep({
-  pattern: "class ValidationError",
-  path: "opensrc/",
-  include: "*.ts",
-});
-
-// Search for function pattern
-grep({
-  pattern: "export function parse",
-  path: "opensrc/",
-  include: "*.ts",
-});
-```
-
-### Step 4: Read and Analyze
-
-Read the implementation:
-
-```typescript
-// Read the file
-read({ filePath: "opensrc/repos/github.com/colinhacks/zod/src/types.ts" });
-
-// Use LSP for navigation (if available)
-lsp_lsp_goto_definition({
-  filePath: "opensrc/.../file.ts",
-  line: 42,
-  character: 10,
-});
-
-// Find all references
-lsp_lsp_find_references({
-  filePath: "opensrc/.../file.ts",
-  line: 42,
-  character: 10,
-});
-```
-
-### Step 5: Document Findings
-
-Write research findings to bead artifact:
-
-````markdown
-# Research: [Library Name] Implementation
-
-**Package:** [name@version]
-**Source:** opensrc/repos/[path]
-**Focus:** [What you were investigating]
-
-## Key Findings
-
-### [Topic 1]: [Function/Pattern Name]
-
-**Location:** `opensrc/repos/.../file.ts:42`
-
-**Implementation:**
-
-```typescript
-// Paste relevant code snippet
-```
-````
-
-**Insights:**
-
-- [What you learned]
-- [Edge cases discovered]
-- [Performance implications]
-
-**Confidence:** High (direct source code)
-
----
-
-### [Topic 2]: [Another Discovery]
-
-[Same structure]
-
-## Answers to Original Questions
-
-1. **Q:** [Original question]
-   **A:** [Answer based on source code]
-   **Evidence:** `file.ts:123-145`
-
-2. **Q:** [Another question]
-   **A:** [Answer]
-
-## Recommendations
-
-Based on source analysis:
-
-- [Recommendation 1]
-- [Recommendation 2]
-
-## Caveats
-
-- Version analyzed: [version]
-- Code may have changed in newer versions
-- Private APIs discovered may change without notice
-
-````
-
-## Limitations
-
-### When Source Code Won't Help
-
-- **Build-time transforms**: Source may differ from runtime (Babel, webpack)
-- **Native modules**: C/C++ code requires different analysis
-- **Minified code**: Some packages don't publish source
-- **Monorepos**: May need to navigate complex structure
-
-### Alternatives
-
-If opensrc doesn't work:
-
-1. **GitHub web interface**: Browse online at github.com/owner/repo
-2. **npm unpacked**: `npm pack <package>` then extract
-3. **node_modules**: If already installed, check `node_modules/<package>/`
-4. **Source maps**: If debugging, browser DevTools may show original source
-
-## Integration with Other Research Methods
-
-Source code research complements other tools:
-
-| Method         | Best For                   | Source Code Adds               |
-| -------------- | -------------------------- | ------------------------------ |
-| **Context7**   | API docs, official guides  | Implementation details         |
-| **codesearch** | Usage patterns in the wild | Canonical implementation       |
-| **grepsearch** | Real-world examples        | How library itself works       |
-| **Web search** | Tutorials, blog posts      | Ground truth from source       |
-| **Codebase**   | Project-specific patterns  | How dependencies actually work |
-
-**Recommended flow:**
-
-1. Context7 - Check official docs
-2. Codebase - Check existing usage
-3. **Source code** - If still unclear, fetch source
-4. codesearch/grepsearch - See how others use it
-5. Web search - Last resort for context
-
-## Cleanup
-
-After research is complete:
-
-```bash
-# Remove specific package
-npx opensrc remove <package>
-
-# Remove all sources
-npx opensrc clean
-
-# Remove just npm packages
-npx opensrc clean --npm
-
-# Keep sources for documentation
-# (opensrc/ is gitignored, won't be committed)
-```
-
-## Success Criteria
-
-You've successfully used this skill when:
-
-- [ ] Fetched correct package/version source
-- [ ] Located relevant implementation code
-- [ ] Understood behavior from reading source
-- [ ] Documented findings with file:line references
-- [ ] Answered original research question with high confidence
-- [ ] Provided code evidence for claims
-
-## Quick Reference
-
-```bash
-# Fetch package source
-npx opensrc <package>                    # npm (auto-detect version)
-npx opensrc <package>@<version>          # npm (specific version)
-npx opensrc pypi:<package>               # Python
-npx opensrc crates:<package>             # Rust
-npx opensrc <owner>/<repo>               # GitHub
-npx opensrc <owner>/<repo>@<tag>         # GitHub (specific tag)
-
-# List fetched sources
-npx opensrc list
-npx opensrc list --json
-
-# Remove sources
-npx opensrc remove <package>
-npx opensrc clean
-npx opensrc clean --npm --pypi --crates
-
-# Source location
-opensrc/repos/<host>/<owner>/<repo>/
-
-# Metadata
-opensrc/sources.json
-```
-
-## References
-
-- `references/common-patterns.md` - Error handling, tracing behavior, quality evaluation patterns
-- `references/source-structure.md` - npm/PyPI/Rust source layouts
-- `references/analysis-tips.md` - Tests, examples, changelog, types, blame
-- `references/example-workflow.md` - Full zod async refinement workflow
-- `references/anti-patterns.md` - What not to do when researching
-- `references/further-reading.md` - External links
-````

package/dist/template/.opencode/skill/ui-ux-research/SKILL.md

@@ -1,9 +0,0 @@
----
-description: "Merged into design-system-audit. Load that skill instead."
----
-
-# UI/UX Research
-
-> This skill has been merged into `design-system-audit` which now covers UI pattern analysis, design token auditing, and visual comparison.
-> 
-> Load `design-system-audit` instead.