opencodekit 0.18.0 → 0.18.2

package/dist/template/.opencode/skill/context-initialization/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: context-initialization
 description: Initialize GSD-style project context files from templates
+version: 1.0.0
+tags: [context, workflow]
+dependencies: []
 ---
 
 # Context Initialization
 
-Create project.md, roadmap.md, and state.md from templates with user input.
+## When to Use
+
+- When initializing project context files (project.md, roadmap.md, state.md) from templates.
+
+## When NOT to Use
+
+- When context files already exist and only need minor manual edits.
+
 
 ## Process
 

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

@@ -1,11 +1,23 @@
 ---
 name: context-management
 description: Use when context is growing large, needing to prune/distill tool outputs, or managing conversation size - covers DCP slash commands and context budgets
+version: 1.0.0
+tags: [context, workflow]
+dependencies: []
 ---
 
 # Context Management
 
-Manage conversation context to prevent degradation. Uses DCP plugin (`@tarquinen/opencode-dcp@latest`).
+## When to Use
+
+- Context is growing large and you need to compress/distill/prune tool outputs
+- You are finishing a phase and want to preserve signal while freeing tokens
+
+## When NOT to Use
+
+- You still need active file contents for upcoming edits
+- The output is protected or required for immediate modifications
+
 
 ## Tool Hierarchy (v2.2+ Philosophy)
 

package/dist/template/.opencode/skill/core-data-expert/SKILL.md

@@ -1,10 +1,21 @@
 ---
 name: core-data-expert
-description: 'Expert Core Data guidance (iOS/macOS): stack setup, fetch requests & NSFetchedResultsController, saving/merge conflicts, threading & Swift Concurrency, batch operations & persistent history, migrations, performance, and NSPersistentCloudKitContainer/CloudKit sync.'
+description: "Expert Core Data guidance (iOS/macOS): stack setup, fetch requests & NSFetchedResultsController, saving/merge conflicts, threading & Swift Concurrency, batch operations & persistent history, migrations, performance, and NSPersistentCloudKitContainer/CloudKit sync."
+version: 1.0.0
+tags: [apple, integration]
+dependencies: []
 ---
+
 # Core Data Expert
 
-Fast, production-oriented guidance for building **correct**, **performant** Core Data stacks and fixing common crashes.
+## When to Use
+
+- When working with Core Data stack setup, threading/concurrency, migrations, or performance issues.
+
+## When NOT to Use
+
+- When the app does not use Core Data (e.g., alternative persistence layers).
+
 
 ## Agent behavior contract (follow these rules)
 

package/dist/template/.opencode/skill/deep-research/SKILL.md

@@ -4,17 +4,14 @@ description: >
   Use when analyzing unfamiliar code, implementing complex features, or entering thorough research mode.
   Provides structured LSP exploration (all 9 operations), memory-first protocol, and confidence-scored findings.
   Integrates with scout agent deep mode and research command --thorough flag.
-version: "1.0.0"
-license: MIT
+version: 1.0.0
+tags: [research, workflow]
+dependencies: []
 ---
 
 # Deep Research - Comprehensive Code Understanding
 
-Systematic methodology for thorough codebase exploration before implementation.
-
-## When to Use This Skill
-
-Use deep research when:
+## When to Use
 
 - **Complex implementation**: Feature touches 3+ files or unfamiliar modules
 - **Thorough mode**: `/research <topic> --thorough` or scout deep mode
@@ -22,7 +19,7 @@ Use deep research when:
 - **Architecture exploration**: Understanding how systems connect
 - **Debugging**: Tracing behavior through multiple layers
 
-**Don't use when:**
+## When NOT to Use
 
 - Quick syntax lookup (use quick mode instead)
 - Well-understood code with obvious changes

package/dist/template/.opencode/skill/defense-in-depth/SKILL.md

@@ -1,10 +1,23 @@
 ---
 name: defense-in-depth
 description: Use when invalid data causes failures deep in execution, requiring validation at multiple system layers - validates at every layer data passes through to make bugs structurally impossible
+version: 1.0.0
+tags: [code-quality, debugging]
+dependencies: []
 ---
 
 # Defense-in-Depth Validation
 
+## When to Use
+
+- A bug is caused by invalid data flowing through multiple layers
+- One validation check is insufficient because data crosses boundaries
+
+## When NOT to Use
+
+- Simple, single-layer validation at an obvious entry point is enough
+- The issue is unrelated to invalid data or boundary checks
+
 ## Overview
 
 When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.

package/dist/template/.opencode/skill/design-system-audit/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: design-system-audit
 description: Use when auditing existing design systems for consistency, documenting undocumented design tokens, identifying design debt, preparing for design system refactoring, or comparing implementation vs design specs
+version: 1.0.0
+tags: [design, code-quality]
+dependencies: []
 ---
 
 # Design System Audit Skill
 
-Audit, document, and improve design systems.
-
 ## When to Use
 
 - Auditing existing design systems for consistency
@@ -15,6 +16,11 @@ Audit, document, and improve design systems.
 - Preparing for design system refactoring
 - Comparing implementation vs design specs
 
+## When NOT to Use
+
+- No design system or token set to analyze.
+
+
 ## Core Workflow
 
 ### Phase 1: Visual Inventory
@@ -141,6 +147,6 @@ Save design tokens to `.opencode/memory/design/tokens/`
 
 | Need                 | Skill                 |
 | -------------------- | --------------------- |
-| Aesthetic principles | `frontend-design` |
+| Aesthetic principles | `frontend-design`     |
 | Implement components | `mockup-to-code`      |
 | Accessibility        | `accessibility-audit` |

package/dist/template/.opencode/skill/development-lifecycle/SKILL.md

@@ -1,10 +1,25 @@
 ---
 name: development-lifecycle
 description: Orchestrates the full feature development lifecycle from ideation through verification. Guides through phases (brainstorm → design → specify → plan → implement → verify) and loads appropriate sub-skills at each stage.
+version: 1.0.0
+tags: [workflow, planning]
+dependencies: [brainstorming, prd, writing-plans, executing-plans, verification-before-completion, requesting-code-review, finishing-a-development-branch]
+---
+
 ---
 
 # Development Lifecycle Orchestration
 
+## When to Use
+
+- Starting a new feature, migration, or refactor and need the full end-to-end workflow
+- You want phase-by-phase guidance with the correct sub-skill at each stage
+
+## When NOT to Use
+
+- You are already mid-phase and only need a specific sub-skill
+- The change is trivial and can skip the full lifecycle
+
 ## Overview
 
 This skill orchestrates the complete feature development workflow, guiding you through each phase and loading the appropriate sub-skills automatically.
@@ -35,6 +50,12 @@ This skill orchestrates the complete feature development workflow, guiding you t
 
 ## Phase 1: Ideation (brainstorming)
 
+### Phase 1 Checklist
+
+- [ ] Load `brainstorming`
+- [ ] Validate design with user
+- [ ] Write `.beads/artifacts/<bead-id>/design.md`
+
 **When:** You have a rough idea but need to explore and refine it.
 
 **Load skill:**
@@ -63,6 +84,12 @@ skill({ name: "brainstorming" });
 
 ## Phase 2: Specification (prd)
 
+### Phase 2 Checklist
+
+- [ ] Confirm or create bead id
+- [ ] Ask clarifying questions
+- [ ] Write `.beads/artifacts/<bead-id>/prd.md`
+
 **When:** Design is validated, need formal requirements and task breakdown.
 
 **Load skill:**
@@ -91,6 +118,12 @@ skill({ name: "prd" });
 
 ## Phase 3: Task Conversion (prd-task)
 
+### Phase 3 Checklist
+
+- [ ] Read PRD from `.beads/artifacts/<bead-id>/prd.md`
+- [ ] Generate `.beads/artifacts/<bead-id>/prd.json`
+- [ ] Ensure `progress.txt` exists
+
 **When:** PRD is complete, need executable task list.
 
 **Load skill:**
@@ -117,6 +150,12 @@ skill({ name: "prd-task" });
 
 ## Phase 4: Planning (writing-plans)
 
+### Phase 4 Checklist
+
+- [ ] Create bite-sized tasks with exact file paths
+- [ ] Include TDD steps and verification commands
+- [ ] Write `.beads/artifacts/<bead-id>/plan.md`
+
 **When:** Tasks defined, need detailed implementation instructions.
 
 **Load skill:**
@@ -145,6 +184,12 @@ skill({ name: "writing-plans" });
 
 ## Phase 5: Implementation (executing-plans)
 
+### Phase 5 Checklist
+
+- [ ] Load and review plan
+- [ ] Execute in batches with verification
+- [ ] Report for feedback between batches
+
 **When:** Plan is ready, time to build.
 
 **Load skill:**
@@ -172,6 +217,12 @@ skill({ name: "executing-plans" });
 
 ## Phase 6: Verification (verification-before-completion)
 
+### Phase 6 Checklist
+
+- [ ] Identify verification commands
+- [ ] Run full verification suite
+- [ ] Only then claim completion and close bead
+
 **When:** Implementation complete, before claiming done.
 
 **Load skill:**

package/dist/template/.opencode/skill/dispatching-parallel-agents/SKILL.md

@@ -1,48 +1,37 @@
 ---
 name: dispatching-parallel-agents
 description: Use when facing 3+ independent failures that can be investigated without shared state or dependencies - dispatches multiple Claude agents to investigate and fix independent problems concurrently
+version: 1.0.0
+tags: [agent-coordination, workflow]
+dependencies: []
 ---
 
 # Dispatching Parallel Agents
 
-## Overview
+## When to Use
 
-When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
+- 3+ independent failures across different subsystems or test files
+- Each investigation can proceed without shared state or coordination
 
-**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
+## When NOT to Use
 
-## When to Use
+- Failures are related or likely share a root cause
+- Work requires sequential understanding of the same code paths
 
-```dot
-digraph when_to_use {
-    "Multiple failures?" [shape=diamond];
-    "Are they independent?" [shape=diamond];
-    "Single agent investigates all" [shape=box];
-    "One agent per problem domain" [shape=box];
-    "Can they work in parallel?" [shape=diamond];
-    "Sequential agents" [shape=box];
-    "Parallel dispatch" [shape=box];
-
-    "Multiple failures?" -> "Are they independent?" [label="yes"];
-    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
-    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
-    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
-    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
-}
-```
+## Parallel Dispatch Checklist
 
-**Use when:**
+- [ ] Confirm 3+ independent failures or domains
+- [ ] Group failures by domain and define clear ownership
+- [ ] Write focused prompts with scope, constraints, and expected output
+- [ ] Dispatch one agent per domain in parallel
+- [ ] Review each agent’s summary and check for conflicts
+- [ ] Run full verification after integrating changes
 
-- 3+ test files failing with different root causes
-- Multiple subsystems broken independently
-- Each problem can be understood without context from others
-- No shared state between investigations
+## Overview
 
-**Don't use when:**
+When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
 
-- Failures are related (fix one might fix others)
-- Need to understand full system state
-- Agents would interfere with each other
+**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
 
 ## The Pattern
 

package/dist/template/.opencode/skill/executing-plans/SKILL.md

@@ -1,10 +1,23 @@
 ---
 name: executing-plans
 description: Use when partner provides a complete implementation plan to execute in controlled batches with review checkpoints - loads plan, reviews critically, executes tasks in batches, reports for review between batches
+version: 1.0.0
+tags: [workflow, planning]
+dependencies: [writing-plans]
 ---
 
 # Executing Plans
 
+## When to Use
+
+- A complete implementation plan exists and you need to execute it in batches with checkpoints
+- You must follow a plan precisely and report between waves for feedback
+
+## When NOT to Use
+
+- There is no plan yet or requirements are still unclear
+- You need to create the plan or tasks first (use writing-plans or prd)
+
 ## Overview
 
 Load plan, review critically, execute tasks in batches, report for review between batches.
@@ -17,6 +30,13 @@ Load plan, review critically, execute tasks in batches, report for review betwee
 
 ### Step 1: Load and Review Plan
 
+#### Plan Review Checklist
+
+- [ ] Read the plan file end-to-end
+- [ ] Identify goal, deliverables, risks, and missing pieces
+- [ ] If concerns, ask via `question()` and wait for decision
+- [ ] If no concerns, create TodoWrite and proceed
+
 1. Read plan file
 2. Review critically - identify any questions or concerns about the plan
 3. If concerns: Use question tool to raise them:
@@ -63,6 +83,15 @@ If concerns: Wait for human to decide and resubmit
 git tag wave-${BATCH_NUMBER}-start
 ```
 
+#### Batch Execution Checklist
+
+- [ ] Create wave start tag: `git tag wave-${BATCH_NUMBER}-start`
+- [ ] Mark each task in_progress
+- [ ] Follow each step exactly as written
+- [ ] Run all specified verifications
+- [ ] Mark tasks completed
+- [ ] Create wave complete tag: `git tag wave-${BATCH_NUMBER}-complete`
+
 For each task:
 
 1. Mark as in_progress
@@ -79,6 +108,13 @@ git tag wave-${BATCH_NUMBER}-complete
 
 ### Step 3: Report
 
+#### Batch Report Checklist
+
+- [ ] Summarize what was implemented
+- [ ] Include verification output
+- [ ] Confirm wave tag created (e.g., `wave-1-complete`)
+- [ ] Ask for feedback before continuing
+
 When batch complete:
 
 - Show what was implemented

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

@@ -7,11 +7,21 @@ mcp:
     args: ["-y", "figma-developer-mcp", "--stdio"]
     env:
       FIGMA_API_KEY: "${FIGMA_API_KEY}"
+version: 1.0.0
+tags: [design, mcp, integration]
+dependencies: []
 ---
 
 # Figma Design Data (MCP)
 
-Access Figma design data via the Framelink MCP server. When this skill is loaded, the `figma` MCP server auto-starts and exposes tools to fetch design data and download images.
+## When to Use
+
+- When you need to fetch layout, styles, or assets from a Figma file via MCP.
+
+## When NOT to Use
+
+- When no Figma file key/node ID is available or design data isn't required.
+
 
 ## Prerequisites
 

package/dist/template/.opencode/skill/finishing-a-development-branch/SKILL.md

@@ -1,10 +1,23 @@
 ---
 name: finishing-a-development-branch
 description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
+version: 1.0.0
+tags: [workflow, git]
+dependencies: []
 ---
 
 # Finishing a Development Branch
 
+## When to Use
+
+- Implementation is complete and tests pass, and you need to merge/PR/cleanup
+- You must present structured end-of-work options and execute the chosen path
+
+## When NOT to Use
+
+- Tests or mandatory gates are failing
+- Work is still in progress and not ready for integration
+
 ## Overview
 
 Guide completion of development work by presenting clear options and handling chosen workflow.
@@ -17,6 +30,11 @@ Guide completion of development work by presenting clear options and handling ch
 
 ### Step 1: Verify Tests
 
+#### Completion Prep Checklist
+
+- [ ] Run the project's test suite
+- [ ] Stop if any tests fail and report failures
+
 **Before presenting options, verify tests pass:**
 
 ```bash
@@ -78,6 +96,12 @@ question({
 
 ### Step 4: Execute Choice
 
+#### Execute Choice Checklist
+
+- [ ] Follow the selected option's steps exactly
+- [ ] Re-run tests on merged result when applicable
+- [ ] Only cleanup worktree for Options 1, 2, or 4
+
 #### Option 1: Merge Locally
 
 ```bash
@@ -181,6 +205,13 @@ git worktree remove <worktree-path>
 
 ### Gate Sequence
 
+#### Gate Checklist
+
+- [ ] Gate 1: `npm run typecheck`
+- [ ] Gate 2: `npm run lint` (run `npm run lint:fix` if needed)
+- [ ] Gate 3: `vitest`
+- [ ] Stop and fix if any gate fails
+
 Every bead MUST pass all three gates in order. No exceptions.
 
 ```bash

package/dist/template/.opencode/skill/frontend-design/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: frontend-design
 description: Create distinctive, production-grade frontend interfaces. Use when building web components, pages, or applications with React-based frameworks. Includes Tailwind CSS v4, shadcn/ui components, Motion animations, and visual design philosophy for avoiding generic AI aesthetics.
+version: 1.0.0
+tags: [ui, design]
+dependencies: []
 ---
 
 # Frontend Design
 
-Create distinctive, production-grade interfaces avoiding generic "AI slop" aesthetics.
-
 ## When to Use
 
 - Building UI with React frameworks (Next.js, Vite, Remix)
@@ -16,6 +17,11 @@ Create distinctive, production-grade interfaces avoiding generic "AI slop" aesth
 - Adding animations and micro-interactions
 - Creating visual designs, posters, brand materials
 
+## When NOT to Use
+
+- Backend-only tasks or minimal UI with no visual design requirements.
+
+
 ## Reference Documentation
 
 ### Tailwind CSS v4.1
@@ -139,10 +145,14 @@ import { motion, AnimatePresence } from 'motion/react';
 ```
 
 CSS fallback (no JS):
+
 ```css
 dialog[open] {
   opacity: 1;
-  @starting-style { opacity: 0; transform: scale(0.95); }
+  @starting-style {
+    opacity: 0;
+    transform: scale(0.95);
+  }
 }
 ```
 

package/dist/template/.opencode/skill/gemini-large-context/SKILL.md

@@ -1,10 +1,21 @@
 ---
 name: gemini-large-context
 description: Use when analyzing large codebases, comparing multiple files, or researching project-wide patterns that exceed typical context limits - leverages Gemini CLI's 1M token context window for comprehensive analysis
+version: 1.0.0
+tags: [research, context]
+dependencies: []
 ---
 
 # Gemini CLI Large Context Analysis
 
+## When to Use
+
+- Large, multi-file or project-wide analysis that exceeds local context limits.
+
+## When NOT to Use
+
+- Small, focused tasks that fit within normal context or require edits.
+
 ## Overview
 
 Use Gemini CLI's massive context window (1M tokens) when analysis requires more context than available in current session. Ideal for codebase-wide searches, multi-file comparisons, and pattern discovery across large projects.

package/dist/template/.opencode/skill/index-knowledge/SKILL.md

@@ -1,11 +1,21 @@
 ---
 name: index-knowledge
 description: Generate hierarchical AGENTS.md knowledge base for a codebase. Creates root + complexity-scored subdirectory documentation.
+version: 1.0.0
+tags: [documentation, workflow]
+dependencies: []
 ---
 
 # index-knowledge
 
-Generate hierarchical AGENTS.md files. Root + complexity-scored subdirectories.
+## When to Use
+
+- When you need to generate or update hierarchical AGENTS.md documentation for a codebase.
+
+## When NOT to Use
+
+- When only a single small directory needs a manual note instead of a full knowledge hierarchy.
+
 
 ## Usage
 

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

@@ -1,11 +1,21 @@
 ---
 name: jira
 description: Jira and Confluence integration via official Atlassian MCP. Search issues, create tickets, update status, and access Confluence docs. Uses OAuth 2.1 authorization with Rovo Search.
+version: 1.0.0
+tags: [integration, mcp, workflow]
+dependencies: []
 ---
 
 # Jira & Confluence Integration (MCP)
 
-Official Atlassian MCP Server integration via `atlassian/atlassian-mcp-server`.
+## When to Use
+
+- When you need to search or update Jira/Confluence content via Atlassian MCP.
+
+## When NOT to Use
+
+- When the project does not use Atlassian Cloud or MCP access is unavailable.
+
 
 ## Key Features