opencodekit 0.23.2 → 0.23.4

package/dist/template/.opencode/skill/structured-edit/SKILL.md

@@ -1,191 +0,0 @@
----
-name: structured-edit
-description: Use when editing files to reduce str_replace failures - combines LSP location with read-verify-edit pattern for reliable edits
-version: 1.0.0
-tags: [code-quality, workflow]
-dependencies: []
----
-
-# Structured Edit Protocol
-
-## When to Use
-
-- Editing files where exact string matches are error-prone (e.g., str_replace failures)
-- Making targeted changes that require precise location and verification
-
-## When NOT to Use
-
-- One-line edits where a direct edit is safe and unambiguous
-- Large refactors better served by full rewrites or file splits
-
-## Common Rationalizations
-
-| Rationalization                                   | Rebuttal                                                                                    |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| "I remember what the file looks like"             | You remember what it looked like 5 edits ago. Read it fresh                                 |
-| "The edit is simple, I don't need to verify"      | Simple edits fail most often — whitespace, encoding, duplicate matches                      |
-| "LSP lookup is an extra step I can skip"          | LSP takes 1 call. Retrying a failed edit takes 3-5 calls                                    |
-| "I'll just use a larger context block to be safe" | Larger blocks = more chances for invisible character mismatches. Use minimal unique context |
-| "The file hasn't changed since I last read it"    | Other edits, formatters, and git operations can modify files between your reads             |
-
-## Overview
-
-The `str_replace` edit tool is the #1 source of failures in LLM coding. Models reproduce content with subtle differences (whitespace, encoding, line endings) causing "string not found" errors.
-
-**Core principle:** Don't guess content — locate, read, verify, then edit.
-
-## Why This Exists
-
-`str_replace` failures happen when:
-
-| Cause                | Example                                    |
-| -------------------- | ------------------------------------------ |
-| Whitespace mismatch  | Tabs vs spaces, trailing spaces            |
-| Content changed      | File modified since last read              |
-| Multiple matches     | Same string appears twice in file          |
-| Encoding differences | Line endings (CRLF vs LF), invisible chars |
-| Stale context        | Editing from memory instead of fresh read  |
-
-**Result:** Wasted tokens on retries, frustrated developers, broken workflows.
-
-## The Protocol
-
-### Step 1: LOCATE
-
-Use LSP to find exact positions instead of guessing:
-
-```typescript
-// Find where a function is defined
-lsp({ operation: "goToDefinition", filePath, line, character });
-
-// Find all references to a symbol
-lsp({ operation: "findReferences", filePath, line, character });
-
-// Get all symbols in a file
-lsp({ operation: "documentSymbol", filePath, line: 1, character: 1 });
-
-// Search for symbol across workspace
-lsp({ operation: "workspaceSymbol", filePath, line: 1, character: 1 });
-```
-
-### Step 2: READ
-
-Get fresh file content at the located position:
-
-```typescript
-// Read context around target line
-read({ filePath, offset: line - 10, limit: 30 });
-```
-
-**Always include context** — don't just read the target line.
-
-### Step 3: VERIFY
-
-Confirm expected content exists at the location:
-
-```typescript
-// Check that what you expect is actually there
-if (!content.includes(expectedSubstring)) {
-  // STOP — investigate before proceeding
-}
-```
-
-### Step 4: EDIT
-
-Apply minimal, scoped change with unique context:
-
-```typescript
-// Include enough surrounding lines for uniqueness
-edit({
-  filePath,
-  oldString: "  // unique context before\n  targetLine\n  // unique context after",
-  newString: "  // unique context before\n  modifiedLine\n  // unique context after",
-});
-```
-
-**Guidelines:**
-
-- Include 2-3 lines before/after for uniqueness
-- Never use just the target line
-- Keep oldString minimal but unique
-
-### Step 5: CONFIRM
-
-Verify the edit succeeded:
-
-```typescript
-// Read back the modified section
-read({ filePath, offset: line - 5, limit: 15 });
-
-// Confirm content matches intent
-```
-
-## Red Flags — STOP
-
-If you catch yourself:
-
-- Editing without reading first
-- Assuming content hasn't changed
-- Using large multi-line oldString values
-- Skipping the verify step
-- Guessing line numbers without LSP
-
-**STOP.** Return to Step 1.
-
-## Best Practices
-
-### File Size Matters
-
-From research on the "harness problem":
-
-| File Size     | Strategy                                   |
-| ------------- | ------------------------------------------ |
-| < 100 lines   | Full rewrite often easier than str_replace |
-| 100-400 lines | Structured edit with good context          |
-| > 400 lines   | Strongly prefer structured edits           |
-
-**Prefer smaller files** — composition over monoliths.
-
-### Unique Context Selection
-
-```typescript
-// BAD: Non-unique, whitespace-sensitive
-oldString: "return result;";
-
-// GOOD: Unique with surrounding context
-oldString: "  // Calculate final value\n  const result = compute(input);\n  return result;";
-```
-
-### When to Use LSP vs Direct
-
-| Scenario                  | Approach              |
-| ------------------------- | --------------------- |
-| Finding function/class    | LSP goToDefinition    |
-| Finding all usages        | LSP findReferences    |
-| Modifying specific symbol | LSP + structured edit |
-| Large refactoring         | Consider full rewrite |
-| Simple one-line change    | Direct edit OK        |
-
-## Integration with Other Skills
-
-**Use with:**
-
-- `verification-before-completion` — Always verify edits succeeded
-- `systematic-debugging` — When edit failures indicate deeper issues
-- `defense-in-depth` — Add validation after structural changes
-
-## Quick Reference
-
-```
-LOCATE  → lsp({ operation: "goToDefinition" | "findReferences", ... })
-READ    → read({ filePath, offset: line-10, limit: 30 })
-VERIFY  → Check expected content exists
-EDIT    → edit({ oldString: "...unique context...", newString: "..." })
-CONFIRM → read() again to verify success
-```
-
-## The Bottom Line
-
-**Don't trust your memory. Don't guess content. Locate, read, verify, edit, confirm.**
-
-This protocol eliminates the #1 source of LLM coding failures.

package/dist/template/.opencode/skill/ubiquitous-language/SKILL.md

@@ -1,184 +0,0 @@
----
-name: ubiquitous-language
-description: Establishes and maintains shared vocabulary across codebase, context files, and team conversation — inspired by Evans' Domain-Driven Design and Pocock's AI agent glossary technique. Use when terms are ambiguous, the AI does the wrong thing, or you need to align code with domain concepts.
-version: 1.0.0
-tags: [architecture, domain-driven-design, ai-workflow]
-dependencies: []
-agent_types: [planner, scout]
-tools: [srcwalk_search, grep, memory]
----
-
-# Ubiquitous Language
-
-> Based on Eric Evans' *Domain-Driven Design* and Matt Pocock's AI-agent glossary technique
-
-## Overview
-
-A ubiquitous language is a **shared vocabulary** that is used consistently across:
-
-- **Code** — types, classes, functions, modules, files
-- **Conversation** — how developers and domain experts talk about the system
-- **AI context** — AGENTS.md, CLAUDE.md, and other files that guide AI agents
-- **Specs and docs** — PRDs, design docs, specifications
-
-When these four use the same words for the same concepts, communication is precise, AI agents produce correct code more often, and the "wrong thing" failure mode is dramatically reduced.
-
-When they diverge, every translation gap is a bug waiting to happen.
-
-> *"Conversations among developers and expressions of the code are all derived from the same domain model."* — Eric Evans
-
-**Why this matters for AI agents:** Matt Pocock demonstrated that feeding a structured glossary (extracted from the codebase) as persistent context to an LLM reduces verbose reasoning and aligns implementation more closely with intent. Ubiquitous language isn't a documentation luxury — it's a direct input into AI correctness.
-
-## When to Use
-
-- Terms are used interchangeably that shouldn't be ("User" vs "Account" vs "Profile")
-- AI agents consistently implement the wrong concept
-- Specs use different vocabulary than the codebase
-- Starting a new domain module that needs clear boundaries
-- Onboarding new developers or agents who need to learn the vocabulary
-- The codebase has multiple ways to refer to the same domain concept
-
-## When NOT to Use
-
-- Trivial utilities with no domain concept at stake
-- Short-lived spike code
-- Already consistent codebases with clear terminology (maintain, don't re-engineer)
-
-## Core Principle
-
-> **Every concept in the domain should have exactly one name in the codebase.**
-
-If two terms mean the same thing, consolidate. If one term means two different things, split them into separate concepts with separate names.
-
-## Technique 1: Glossary Extraction
-
-### From Codebase
-
-Scan the codebase for key terms and build a glossary:
-
-```
-src/
-  types/          → Extract type/interface names
-  models/         → Extract model/entity names  
-  routes/         → Extract resource names from URL patterns
-  services/       → Extract domain operation names
-  commands/       → Extract command/mutation names
-```
-
-**Automated approach:**
-```bash
-# Extract type definitions (TypeScript example)
-grep -rn "^export (type|interface|class|enum) " src/ --include='*.ts' | 
-  cut -d' ' -f3- | sort -u
-
-# Extract module/file names that correspond to domain concepts
-ls -d src/models/*/ | xargs -I{} basename {} | sort -u
-```
-
-### From AGENTS.md / Context Files
-
-Every term used in your AGENTS.md or CLAUDE.md should map to a code symbol. Cross-reference:
-
-1. List every capitalized noun phrase in AGENTS.md
-2. Search the codebase for each phrase
-3. For mismatches: either rename the code symbol or update the context file
-
-### Glossary Table Format
-
-```markdown
-## Glossary
-
-| Term | Definition | Code Symbol | Context |
-|------|------------|-------------|---------|
-| Order | A customer's purchase request in PENDING state | `Order` class, `orders` table | Checkout context |
-| OrderFulfillment | The shipping/delivery of items for an Order | `Fulfillment` class, `fulfillments` table | Fulfillment context |
-| User | An authenticated person using the system | `User` model, `users` table | Auth context |
-| Account | A User's billing/subscription profile | `Account` model, `accounts` table | Billing context |
-```
-
-## Technique 2: Bounded Context Mapping
-
-In DDD, the same term can mean different things in different contexts. The "Ubiquitous" in "Ubiquitous Language" is bounded — it applies *within* one context, not globally.
-
-**Example:** An "Order" in the **Checkout** context means "pending payment." An "Order" in the **Fulfillment** context means "packed and shipped." These are different concepts that happen to share a name.
-
-### When Contexts Conflict
-
-| Option | When | Tradeoff |
-|---|---|---|
-| **Split the term** | Different behaviors, data, lifecycle | Clearer but more types to manage |
-| **Keep one term, document the phases** | Same entity, different states | Simpler but confusion at boundaries |
-| **Use sub-types** | Shared core with context-specific properties | Precise but more complex |
-
-**Default:** Split the term if the two contexts never share code. Keep one term if they share a code path.
-
-## Technique 3: Glossary as AI Context
-
-This technique — from Matt Pocock's AI Engineer Summit talk — directly improves AI agent output:
-
-1. **Extract** your glossary from the codebase (Technique 1)
-2. **Format** it as a markdown table in your AGENTS.md or a dedicated `.md` file
-3. **Persist** it — include it in every prompt or reference it from context files
-4. **Read thinking traces** — when the LLM uses a term incorrectly, update the glossary
-
-### Example: Glossary Section in AGENTS.md
-
-```markdown
-## Glossary
-
-- **Order** = `src/orders/Order.ts` — purchase request in PENDING state
-- **Invoice** = `src/billing/Invoice.ts` — billing record generated from Order
-- **Shipment** = `src/fulfillment/Shipment.ts` — physical delivery of items
-```
-
-### Why This Works
-
-Pocock observed that reading the model's thinking traces confirmed this technique:
-
-- **Reduces verbose reasoning** — the AI doesn't have to infer what a term means from context
-- **Aligns implementation with intent** — the AI uses the correct code symbols from the start
-- **Prevents drift** — the glossary is extracted from truth (the codebase), not from conversation
-
-## Technique 4: Detecting Language Drift
-
-Over time, vocabulary naturally diverges. Watch for:
-
-| Signal | What to do |
-|---|---|
-| AI generates a new term the codebase doesn't use | Update the glossary or rename the generated code |
-| Two developers use different names for the same concept | Align on one name, update code and context |
-| AGENTS.md mentions a term not found in code | Add the code symbol or remove the stale term |
-| Same term used for different concepts in code | Refactor or split the type |
-| PR review consistently corrects naming | Create a glossary entry and enforce it |
-
-### Drift Check Frequency
-
-- **Per sprint** — scan for new terms in code vs AGENTS.md
-- **Per AI session** — check that AGENTS.md terms match the module you're working in
-- **Per refactor** — regenerate the glossary when domain types change
-
-## Output Checklist
-
-- [ ] Glossary extracted from codebase: types, modules, routes, domain operations
-- [ ] AGENTS.md vocabulary cross-referenced against code symbols
-- [ ] Bounded contexts identified where same term has different meanings
-- [ ] Glossary formatted and persisted for AI context
-- [ ] Language drift signals documented for ongoing maintenance
-
-## See Also
-
-- **spec-driven-development** — Define vocabulary in the spec before implementation
-- **deep-module-design** — Module boundaries align with bounded contexts
-- **memory-system** — Persist glossary for cross-session AI context
-
-## Skill Result Contract
-
-```xml
-<skill_result>
-  <skill>ubiquitous-language</skill>
-  <status>success|partial|blocked|failure</status>
-  <evidence>Glossary generated, cross-references checked, bounded contexts mapped</evidence>
-  <artifacts>Glossary file, AGENTS.md updates, detected drifts</artifacts>
-  <risks>Unaligned terms deferred, contexts not fully mapped, or none</risks>
-</skill_result>
-```

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

@@ -1,158 +0,0 @@
----
-name: v0
-description: Use when you need AI-powered UI generation for React components, dashboards, or quick prototypes via v0. MUST load before creating v0 chats or generating components via v0 MCP.
-mcp:
-  v0:
-    command: npx
-    args: ["mcp-remote", "https://mcp.v0.dev", "--header", "Authorization: Bearer ${V0_API_KEY}"]
-    env:
-      V0_API_KEY: "${V0_API_KEY}"
-version: 1.0.0
-tags: [ui, mcp, design]
-dependencies: []
----
-
-# v0 AI Code Generation (MCP)
-
-## When to Use
-
-- When you need AI-generated UI components or chat-based design iteration via v0.
-
-## When NOT to Use
-
-- When you need to implement UI from a fixed design system without AI generation.
-
-
-## Prerequisites
-
-Set your v0 API key as an environment variable:
-
-```bash
-export V0_API_KEY="your-v0-api-key"
-```
-
-To get your v0 API key:
-
-1. Go to [v0 account settings](https://v0.app/chat/settings/keys)
-2. Create a new API key
-3. Copy and set as environment variable
-
-## Quick Start
-
-After loading this skill, list available tools:
-
-```
-skill_mcp(skill_name="v0", list_tools=true)
-```
-
-Then invoke tools:
-
-```
-skill_mcp(skill_name="v0", tool_name="create_chat", arguments='{"prompt": "Create a React dashboard component with a sidebar"}')
-```
-
-## Available Tools
-
-### create_chat
-
-Create a new v0 chat with a prompt.
-
-| Parameter | Type   | Required | Description                        |
-| --------- | ------ | -------- | ---------------------------------- |
-| `prompt`  | string | Yes      | The prompt for v0 to generate code |
-
-**Example:**
-
-```
-skill_mcp(skill_name="v0", tool_name="create_chat", arguments='{"prompt": "Build a responsive navbar with dark mode toggle"}')
-```
-
-### get_chat
-
-Get details about an existing chat.
-
-| Parameter | Type   | Required | Description    |
-| --------- | ------ | -------- | -------------- |
-| `chatId`  | string | Yes      | The v0 chat ID |
-
-**Example:**
-
-```
-skill_mcp(skill_name="v0", tool_name="get_chat", arguments='{"chatId": "abc123"}')
-```
-
-### find_chats
-
-Search through your v0 chats.
-
-| Parameter | Type   | Required | Description  |
-| --------- | ------ | -------- | ------------ |
-| `query`   | string | No       | Search query |
-
-**Example:**
-
-```
-skill_mcp(skill_name="v0", tool_name="find_chats", arguments='{"query": "React components"}')
-```
-
-### send_message
-
-Continue a conversation in an existing chat.
-
-| Parameter | Type   | Required | Description     |
-| --------- | ------ | -------- | --------------- |
-| `chatId`  | string | Yes      | The v0 chat ID  |
-| `message` | string | Yes      | Message to send |
-
-**Example:**
-
-```
-skill_mcp(skill_name="v0", tool_name="send_message", arguments='{"chatId": "abc123", "message": "Add dark mode support"}')
-```
-
-## Workflow
-
-### 1. Generate a New Component
-
-```
-# Create a new chat with your requirements
-skill_mcp(skill_name="v0", tool_name="create_chat", arguments='{"prompt": "Create a modern pricing table with 3 tiers using Tailwind CSS"}')
-
-# The response includes a chat ID and generated code
-```
-
-### 2. Iterate on Design
-
-```
-# Send follow-up messages to refine
-skill_mcp(skill_name="v0", tool_name="send_message", arguments='{"chatId": "chat-id-here", "message": "Make the recommended tier more prominent with a gradient border"}')
-```
-
-### 3. Search Previous Work
-
-```
-# Find relevant previous chats
-skill_mcp(skill_name="v0", tool_name="find_chats", arguments='{"query": "dashboard"}')
-```
-
-## Use Cases
-
-- **Component Generation**: Create React/Next.js components from descriptions
-- **UI Prototyping**: Rapidly prototype UI ideas
-- **Design Iteration**: Refine designs through conversation
-- **Code Assistance**: Get help with Tailwind CSS, responsive design, etc.
-
-## Tips
-
-- **Be specific** in prompts - include framework (React, Next.js), styling (Tailwind, CSS), and functionality details
-- **Iterate** using `send_message` rather than creating new chats for refinements
-- **Search first** with `find_chats` to reuse previous work
-- **Include context** about your existing design system or component patterns
-
-## Troubleshooting
-
-**"Invalid API key"**: Ensure `V0_API_KEY` environment variable is set correctly.
-
-**"Rate limit exceeded"**: v0 has usage limits. Wait a few minutes or check your plan.
-
-**"Chat not found"**: Verify the chat ID is correct. Use `find_chats` to list available chats.