opencodekit 0.18.1 → 0.18.3

package/dist/template/.opencode/skill/verification-before-completion/SKILL.md

@@ -1,10 +1,23 @@
 ---
 name: verification-before-completion
 description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+version: 1.0.0
+tags: [workflow, code-quality]
+dependencies: []
 ---
 
 # Verification Before Completion
 
+## When to Use
+
+- Before claiming tests/lint/build pass or a bug is fixed
+- Before committing, opening PRs, or stating completion in a status update
+
+## When NOT to Use
+
+- While still actively coding without a completion claim
+- When you cannot run verification commands yet (e.g., missing dependencies) — resolve first
+
 ## Overview
 
 Claiming work is complete without verification is dishonesty, not efficiency.
@@ -35,8 +48,17 @@ BEFORE claiming any status or expressing satisfaction:
 5. ONLY THEN: Make the claim
 
 Skip any step = lying, not verifying
+
 ```
 
+## Verification Checklist
+
+- [ ] Identify the exact command that proves the claim
+- [ ] Run the full command (fresh)
+- [ ] Read the full output and exit code
+- [ ] Confirm the output matches the claim
+- [ ] Only then state the completion claim with evidence
+
 ## Common Failures
 
 | Claim                 | Requires                        | Not Sufficient                 |

package/dist/template/.opencode/skill/verification-before-completion/references/VERIFICATION_PROTOCOL.md

@@ -0,0 +1,67 @@
+# Verification Protocol
+
+## Standard Gates
+
+Run these gates in parallel where possible:
+
+### Parallel Group (independent — run simultaneously)
+
+```bash
+# Gate 1: Typecheck
+npm run typecheck 2>&1 &
+PID_TC=$!
+
+# Gate 2: Lint (incremental when possible)
+# Full codebase:
+npm run lint 2>&1 &
+# Or incremental (changed files only):
+# npx oxlint $(git diff --name-only --diff-filter=d HEAD | grep -E '\.(ts|tsx|js|jsx)$')
+PID_LINT=$!
+
+wait $PID_TC $PID_LINT
+```
+
+### Sequential Group (depends on parallel group passing)
+
+```bash
+# Gate 3: Tests (incremental when possible)
+# Full: npm test
+# Incremental: npx vitest --changed
+npm test
+
+# Gate 4: Build (only if shipping)
+npm run build
+```
+
+## Incremental Mode
+
+Use incremental mode when:
+
+- Only a few files changed (< 20 files)
+- Not shipping/releasing (pre-commit, mid-development)
+
+| Gate      | Full Command        | Incremental Command                        |
+| --------- | ------------------- | ------------------------------------------ |
+| Typecheck | `npm run typecheck` | `npm run typecheck` (always full — needed) |
+| Lint      | `npm run lint`      | `npx oxlint $(git diff --name-only HEAD)`  |
+| Test      | `npm test`          | `npx vitest --changed`                     |
+| Build     | `npm run build`     | Skip (only needed for ship/release)        |
+
+## Gate Results Format
+
+Report results as:
+
+```text
+| Gate      | Status | Time   |
+|-----------|--------|--------|
+| Typecheck | PASS   | 2.1s   |
+| Lint      | PASS   | 0.8s   |
+| Test      | PASS   | 5.3s   |
+| Build     | SKIP   | —      |
+```
+
+## Failure Handling
+
+- If any gate fails, stop and fix before proceeding
+- Show the FULL error output for failed gates
+- After fixing, re-run ONLY the failed gate(s) + any downstream gates

package/dist/template/.opencode/skill/visual-analysis/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: visual-analysis
 description: Use when analyzing images, screenshots, UI mockups, or visual content for extracting information, comparing designs, or assessing visual properties like colors, typography, and layout
+version: 1.0.0
+tags: [design, research]
+dependencies: []
 ---
 
 # Visual Analysis Skill
 
-Analyze images, screenshots, and visual content.
-
 ## When to Use
 
 - Analyzing UI mockups or screenshots
@@ -14,6 +15,11 @@ Analyze images, screenshots, and visual content.
 - Comparing visual designs
 - Quick visual assessments
 
+## When NOT to Use
+
+- Pure text/code review without any visual assets.
+
+
 ## Quick Mode
 
 Fast, focused analysis for specific questions.
@@ -132,4 +138,4 @@ Save findings to `.opencode/memory/design/analysis/`
 | Found accessibility issues  | `accessibility-audit` |
 | Need to implement design    | `mockup-to-code`      |
 | Want design tokens          | `design-system-audit` |
-| Need aesthetic improvements | `frontend-design` |
+| Need aesthetic improvements | `frontend-design`     |

package/dist/template/.opencode/skill/web-design-guidelines/SKILL.md

@@ -1,15 +1,21 @@
 ---
 name: web-design-guidelines
 description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
-metadata:
-  author: vercel
-  version: "1.0.0"
-  argument-hint: <file-or-pattern>
+version: 1.0.0
+tags: [ui, design]
+dependencies: []
 ---
 
 # Web Interface Guidelines
 
-Review files for compliance with Web Interface Guidelines.
+## When to Use
+
+- Reviewing UI files against Web Interface Guidelines for UX/design compliance.
+
+## When NOT to Use
+
+- Non-UI code reviews or when no files/pattern are provided.
+
 
 ## How It Works
 
@@ -31,6 +37,7 @@ Use WebFetch to retrieve the latest rules. The fetched content contains all the
 ## Usage
 
 When a user provides a file or pattern argument:
+
 1. Fetch guidelines from the source URL above
 2. Read the specified files
 3. Apply all rules from the fetched guidelines

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

@@ -1,10 +1,23 @@
 ---
 name: writing-plans
 description: Use when design is complete and you need detailed implementation tasks for engineers with zero codebase context - creates comprehensive implementation plans with exact file paths, complete code examples, and verification steps assuming engineer has minimal domain knowledge
+version: 1.0.0
+tags: [planning, documentation]
+dependencies: []
 ---
 
 # Writing Plans
 
+## When to Use
+
+- Design/PRD is complete and you need a detailed, step-by-step implementation plan
+- You need a plan for engineers with minimal codebase context and explicit file paths
+
+## When NOT to Use
+
+- Requirements are still being defined (use brainstorming or prd)
+- You already have a vetted plan and only need execution (use executing-plans)
+
 ## Overview
 
 Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

package/dist/template/.opencode/skill/writing-skills/SKILL.md

@@ -1,10 +1,26 @@
 ---
 name: writing-skills
-description: Use when creating new skills, editing existing skills, or verifying skills work before deployment - applies TDD to process documentation by testing with subagents before writing, iterating until bulletproof against rationalization
+description: "Use when creating new skills, editing existing skills, or verifying skills work before deployment - applies TDD to process documentation by testing with subagents before writing, iterating until bulletproof against rationalization"
+version: 1.0.0
+tags: [documentation, workflow]
+dependencies: []
 ---
 
 # Writing Skills
 
+## When to Use
+
+- Creating a new skill from scratch
+- Editing or improving an existing skill
+- Verifying a skill works correctly before deployment
+- Applying TDD methodology to process documentation
+
+## When NOT to Use
+
+- Routine code implementation (use executing-plans instead)
+- One-off instructions that don't need to be reusable
+- Quick configuration changes that don't warrant a skill
+
 ## Overview
 
 **Writing skills IS Test-Driven Development applied to process documentation.**
@@ -148,236 +164,6 @@ What goes wrong + fixes
 Concrete results
 ```
 
-## Claude Search Optimization (CSO)
-
-**Critical for discovery:** Future Claude needs to FIND your skill
-
-### 1. Rich Description Field
-
-**Purpose:** Claude reads description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
-
-**Format:** Start with "Use when..." to focus on triggering conditions, then explain what it does
-
-**Content:**
-
-- Use concrete triggers, symptoms, and situations that signal this skill applies
-- Describe the _problem_ (race conditions, inconsistent behavior) not _language-specific symptoms_ (setTimeout, sleep)
-- Keep triggers technology-agnostic unless the skill itself is technology-specific
-- If skill is technology-specific, make that explicit in the trigger
-- Write in third person (injected into system prompt)
-
-```yaml
-# ❌ BAD: Too abstract, vague, doesn't include when to use
-description: For async testing
-
-# ❌ BAD: First person
-description: I can help you with async tests when they're flaky
-
-# ❌ BAD: Mentions technology but skill isn't specific to it
-description: Use when tests use setTimeout/sleep and are flaky
-
-# ✅ GOOD: Starts with "Use when", describes problem, then what it does
-description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently - replaces arbitrary timeouts with condition polling for reliable async tests
-
-# ✅ GOOD: Technology-specific skill with explicit trigger
-description: Use when using React Router and handling authentication redirects - provides patterns for protected routes and auth state management
-```
-
-### 2. Keyword Coverage
-
-Use words Claude would search for:
-
-- Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
-- Symptoms: "flaky", "hanging", "zombie", "pollution"
-- Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
-- Tools: Actual commands, library names, file types
-
-### 3. Descriptive Naming
-
-**Use active voice, verb-first:**
-
-- ✅ `creating-skills` not `skill-creation`
-- ✅ `testing-skills-with-subagents` not `subagent-skill-testing`
-
-### 4. Token Efficiency (Critical)
-
-**Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts.
-
-**Target word counts:**
-
-- getting-started workflows: <150 words each
-- Frequently-loaded skills: <200 words total
-- Other skills: <500 words (still be concise)
-
-**Techniques:**
-
-**Move details to tool help:**
-
-```bash
-# ❌ BAD: Document all flags in SKILL.md
-search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
-
-# ✅ GOOD: Reference --help
-search-conversations supports multiple modes and filters. Run --help for details.
-```
-
-**Use cross-references:**
-
-```markdown
-# ❌ BAD: Repeat workflow details
-
-When searching, dispatch subagent with template...
-[20 lines of repeated instructions]
-
-# ✅ GOOD: Reference other skill
-
-Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
-```
-
-**Compress examples:**
-
-```markdown
-# ❌ BAD: Verbose example (42 words)
-
-your human partner: "How did we handle authentication errors in React Router before?"
-You: I'll search past conversations for React Router authentication patterns.
-[Dispatch subagent with search query: "React Router authentication error handling 401"]
-
-# ✅ GOOD: Minimal example (20 words)
-
-Partner: "How did we handle auth errors in React Router?"
-You: Searching...
-[Dispatch subagent → synthesis]
-```
-
-**Eliminate redundancy:**
-
-- Don't repeat what's in cross-referenced skills
-- Don't explain what's obvious from command
-- Don't include multiple examples of same pattern
-
-**Verification:**
-
-```bash
-wc -w skills/path/SKILL.md
-# getting-started workflows: aim for <150 each
-# Other frequently-loaded: aim for <200 total
-```
-
-**Name by what you DO or core insight:**
-
-- ✅ `condition-based-waiting` > `async-test-helpers`
-- ✅ `using-skills` not `skill-usage`
-- ✅ `flatten-with-flags` > `data-structure-refactoring`
-- ✅ `root-cause-tracing` > `debugging-techniques`
-
-**Gerunds (-ing) work well for processes:**
-
-- `creating-skills`, `testing-skills`, `debugging-with-logs`
-- Active, describes the action you're taking
-
-### 4. Cross-Referencing Other Skills
-
-**When writing documentation that references other skills:**
-
-Use skill name only, with explicit requirement markers:
-
-- ✅ Good: `**REQUIRED SUB-SKILL:** Use skill({ name: "test-driven-development" })`
-- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand systematic-debugging`
-- ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)
-- ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
-
-**Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them.
-
-## Flowchart Usage
-
-```dot
-digraph when_flowchart {
-    "Need to show information?" [shape=diamond];
-    "Decision where I might go wrong?" [shape=diamond];
-    "Use markdown" [shape=box];
-    "Small inline flowchart" [shape=box];
-
-    "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
-    "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
-    "Decision where I might go wrong?" -> "Use markdown" [label="no"];
-}
-```
-
-**Use flowcharts ONLY for:**
-
-- Non-obvious decision points
-- Process loops where you might stop too early
-- "When to use A vs B" decisions
-
-**Never use flowcharts for:**
-
-- Reference material → Tables, lists
-- Code examples → Markdown blocks
-- Linear instructions → Numbered lists
-- Labels without semantic meaning (step1, helper2)
-
-See @graphviz-conventions.dot for graphviz style rules.
-
-## Code Examples
-
-**One excellent example beats many mediocre ones**
-
-Choose most relevant language:
-
-- Testing techniques → TypeScript/JavaScript
-- System debugging → Shell/Python
-- Data processing → Python
-
-**Good example:**
-
-- Complete and runnable
-- Well-commented explaining WHY
-- From real scenario
-- Shows pattern clearly
-- Ready to adapt (not generic template)
-
-**Don't:**
-
-- Implement in 5+ languages
-- Create fill-in-the-blank templates
-- Write contrived examples
-
-You're good at porting - one great example is enough.
-
-## File Organization
-
-### Self-Contained Skill
-
-```
-defense-in-depth/
-  SKILL.md    # Everything inline
-```
-
-When: All content fits, no heavy reference needed
-
-### Skill with Reusable Tool
-
-```
-condition-based-waiting/
-  SKILL.md    # Overview + patterns
-  example.ts  # Working helpers to adapt
-```
-
-When: Tool is reusable code, not just narrative
-
-### Skill with Heavy Reference
-
-```
-pptx/
-  SKILL.md       # Overview + workflows
-  pptxgenjs.md   # 600 lines API reference
-  ooxml.md       # 500 lines XML structure
-  scripts/       # Executable tools
-```
-
-When: Reference material too large for inline
-
 ## The Iron Law (Same as TDD)
 
 ```
@@ -396,153 +182,10 @@ Edit skill without testing? Same violation.
 - Not for "documentation updates"
 - Don't keep untested changes as "reference"
 - Don't "adapt" while running tests
-- Delete means delete
-
-**REQUIRED BACKGROUND:** The test-driven-development skill explains why this matters. Same principles apply to documentation.
-
-## Testing All Skill Types
-
-Different skill types need different test approaches:
-
-### Discipline-Enforcing Skills (rules/requirements)
-
-**Examples:** TDD, verification-before-completion, designing-before-coding
-
-**Test with:**
-
-- Academic questions: Do they understand the rules?
-- Pressure scenarios: Do they comply under stress?
-- Multiple pressures combined: time + sunk cost + exhaustion
-- Identify rationalizations and add explicit counters
-
-**Success criteria:** Agent follows rule under maximum pressure
-
-### Technique Skills (how-to guides)
-
-**Examples:** condition-based-waiting, root-cause-tracing, defensive-programming
-
-**Test with:**
-
-- Application scenarios: Can they apply the technique correctly?
-- Variation scenarios: Do they handle edge cases?
-- Missing information tests: Do instructions have gaps?
-
-**Success criteria:** Agent successfully applies technique to new scenario
-
-### Pattern Skills (mental models)
-
-**Examples:** reducing-complexity, information-hiding concepts
-
-**Test with:**
-
-- Recognition scenarios: Do they recognize when pattern applies?
-- Application scenarios: Can they use the mental model?
-- Counter-examples: Do they know when NOT to apply?
-
-**Success criteria:** Agent correctly identifies when/how to apply pattern
-
-### Reference Skills (documentation/APIs)
-
-**Examples:** API documentation, command references, library guides
-
-**Test with:**
-
-- Retrieval scenarios: Can they find the right information?
-- Application scenarios: Can they use what they found correctly?
-- Gap testing: Are common use cases covered?
-
-**Success criteria:** Agent finds and correctly applies reference information
-
-## Common Rationalizations for Skipping Testing
-
-| Excuse                         | Reality                                                          |
-| ------------------------------ | ---------------------------------------------------------------- |
-| "Skill is obviously clear"     | Clear to you ≠ clear to other agents. Test it.                   |
-| "It's just a reference"        | References can have gaps, unclear sections. Test retrieval.      |
-| "Testing is overkill"          | Untested skills have issues. Always. 15 min testing saves hours. |
-| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying.        |
-| "Too tedious to test"          | Testing is less tedious than debugging bad skill in production.  |
-| "I'm confident it's good"      | Overconfidence guarantees issues. Test anyway.                   |
-| "Academic review is enough"    | Reading ≠ using. Test application scenarios.                     |
-| "No time to test"              | Deploying untested skill wastes more time fixing it later.       |
-
-**All of these mean: Test before deploying. No exceptions.**
-
-## Bulletproofing Skills Against Rationalization
-
-Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.
-
-**Psychology note:** Understanding WHY persuasion techniques work helps you apply them systematically. See persuasion-principles.md for research foundation (Cialdini, 2021; Meincke et al., 2025) on authority, commitment, scarcity, social proof, and unity principles.
-
-### Close Every Loophole Explicitly
-
-Don't just state the rule - forbid specific workarounds:
-
-<Bad>
-```markdown
-Write code before test? Delete it.
-```
-</Bad>
-
-<Good>
-```markdown
-Write code before test? Delete it. Start over.
-
-**No exceptions:**
-
-- Don't keep it as "reference"
-- Don't "adapt" it while writing tests
 - Don't look at it
 - Delete means delete
 
-````
-</Good>
-
-### Address "Spirit vs Letter" Arguments
-
-Add foundational principle early:
-
-```markdown
-**Violating the letter of the rules is violating the spirit of the rules.**
-````
-
-This cuts off entire class of "I'm following the spirit" rationalizations.
-
-### Build Rationalization Table
-
-Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table:
-
-```markdown
-| Excuse                           | Reality                                                                 |
-| -------------------------------- | ----------------------------------------------------------------------- |
-| "Too simple to test"             | Simple code breaks. Test takes 30 seconds.                              |
-| "I'll test after"                | Tests passing immediately prove nothing.                                |
-| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
-```
-
-### Create Red Flags List
-
-Make it easy for agents to self-check when rationalizing:
-
-```markdown
-## Red Flags - STOP and Start Over
-
-- Code before test
-- "I already manually tested it"
-- "Tests after achieve the same purpose"
-- "It's about spirit not ritual"
-- "This is different because..."
-
-**All of these mean: Delete code. Start over with TDD.**
-```
-
-### Update CSO for Violation Symptoms
-
-Add to description: symptoms of when you're ABOUT to violate the rule:
-
-```yaml
-description: use when implementing any feature or bugfix, before writing implementation code
-```
+**REQUIRED BACKGROUND:** The test-driven-development skill explains why this matters. Same principles apply to documentation.
 
 ## RED-GREEN-REFACTOR for Skills
 
@@ -575,32 +218,6 @@ Agent found new rationalization? Add explicit counter. Re-test until bulletproof
 - Plugging holes systematically
 - Meta-testing techniques
 
-## Anti-Patterns
-
-### ❌ Narrative Example
-
-"In session 2025-10-03, we found empty projectDir caused..."
-**Why bad:** Too specific, not reusable
-
-### ❌ Multi-Language Dilution
-
-example-js.js, example-py.py, example-go.go
-**Why bad:** Mediocre quality, maintenance burden
-
-### ❌ Code in Flowcharts
-
-```dot
-step1 [label="import fs"];
-step2 [label="read file"];
-```
-
-**Why bad:** Can't copy-paste, hard to read
-
-### ❌ Generic Labels
-
-helper1, helper2, step3, pattern4
-**Why bad:** Labels should have semantic meaning
-
 ## STOP: Before Moving to Next Skill
 
 **After writing ANY skill, you MUST STOP and complete the deployment process.**
@@ -659,24 +276,12 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 - [ ] Commit skill to git and push to your fork (if configured)
 - [ ] Consider contributing back via PR (if broadly useful)
 
-## Discovery Workflow
-
-How future Claude finds your skill:
-
-1. **Encounters problem** ("tests are flaky")
-2. **Finds SKILL** (description matches)
-3. **Scans overview** (is this relevant?)
-4. **Reads patterns** (quick reference table)
-5. **Loads example** (only when implementing)
-
-**Optimize for this flow** - put searchable terms early and often.
-
-## The Bottom Line
-
-**Creating skills IS TDD for process documentation.**
-
-Same Iron Law: No skill without failing test first.
-Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).
-Same benefits: Better quality, fewer surprises, bulletproof results.
+## References
 
-If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation.
+- `references/claude-search-optimization.md` - CSO guidance: descriptions, keywords, token efficiency, cross-references
+- `references/flowcharts-and-examples.md` - Flowchart usage rules and code example guidance
+- `references/file-organization.md` - Patterns for self-contained vs heavy-reference skills
+- `references/testing-skill-types.md` - How to test discipline, technique, pattern, and reference skills
+- `references/rationalization-hardening.md` - Loophole closure, rationalization tables, red flags
+- `references/anti-patterns.md` - Anti-patterns to avoid
+- `references/discovery-workflow.md` - How future agents find and use skills