opencodekit 0.20.7 → 0.21.0

package/dist/template/.opencode/skill/performance-optimization/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: performance-optimization
+description: Use when profiling, optimizing, or adding performance budgets to applications — covers measure-first workflow, Core Web Vitals, common anti-patterns, and performance regression prevention
+version: 1.0.0
+tags: [performance, code-quality]
+dependencies: []
+---
+
+# Performance Optimization
+
+> **Replaces** premature optimization and gut-feeling tuning with measurement-driven improvements that target actual bottlenecks
+
+## When to Use
+
+- Application is measurably slow (user reports, metrics, profiler data)
+- Setting up performance budgets for a new project
+- Reviewing code for common performance anti-patterns
+- Performance regression detected in CI or monitoring
+
+## When NOT to Use
+
+- No evidence of a performance problem — premature optimization wastes time
+- Micro-optimizations that save nanoseconds in non-hot paths
+- Choosing "fast" over "correct" — correctness first, always
+
+## Overview
+
+Performance optimization is an empirical process. Measure, identify, fix, verify. Never optimize without profiling first.
+
+**Core principle:** Measure before optimizing. Optimize the bottleneck, not the code you happen to be reading. Verify the improvement with numbers.
+
+## Measure-First Workflow
+
+```
+1. MEASURE   — Profile to identify actual bottlenecks (not guessed ones)
+2. IDENTIFY  — Find the specific hot path or resource constraint
+3. FIX       — Apply targeted optimization to the bottleneck
+4. VERIFY    — Measure again to confirm improvement
+5. GUARD     — Add budget/benchmark to prevent regression
+```
+
+**Rule:** Skip to step 3 only if you have measurement data that justifies the optimization.
+
+## Performance Targets
+
+### Core Web Vitals (Web)
+
+| Metric                          | Good    | Needs Improvement | Poor    |
+| ------------------------------- | ------- | ----------------- | ------- |
+| LCP (Largest Contentful Paint)  | ≤ 2.5s  | ≤ 4.0s            | > 4.0s  |
+| INP (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms           | > 500ms |
+| CLS (Cumulative Layout Shift)   | ≤ 0.1   | ≤ 0.25            | > 0.25  |
+
+### General Targets
+
+| Context             | Target       | Measure                |
+| ------------------- | ------------ | ---------------------- |
+| API response (p95)  | < 200ms      | Server-side timing     |
+| CLI command startup | < 500ms      | `time` or `perf_hooks` |
+| Build time          | < 60s        | CI pipeline metrics    |
+| Bundle size (JS)    | < 200KB gzip | Bundler output         |
+| Database query      | < 50ms       | Query EXPLAIN + timing |
+
+## Common Anti-Patterns & Fixes
+
+### N+1 Queries
+
+```typescript
+// ❌ N+1: One query per user
+const users = await db.query("SELECT * FROM users");
+for (const user of users) {
+  user.posts = await db.query("SELECT * FROM posts WHERE user_id = ?", [user.id]);
+}
+
+// ✅ Batch: Two queries total
+const users = await db.query("SELECT * FROM users");
+const userIds = users.map((u) => u.id);
+const posts = await db.query("SELECT * FROM posts WHERE user_id IN (?)", [userIds]);
+// Group posts by user_id in application code
+```
+
+### Unbounded Fetching
+
+```typescript
+// ❌ Fetch everything
+const allItems = await db.query("SELECT * FROM items");
+
+// ✅ Paginate
+const items = await db.query("SELECT * FROM items LIMIT ? OFFSET ?", [pageSize, offset]);
+```
+
+### Missing Memoization
+
+```typescript
+// ❌ Recompute on every render
+function ExpensiveList({ items }) {
+  const sorted = items.sort((a, b) => complexSort(a, b)); // sorts on every render
+  return <List items={sorted} />;
+}
+
+// ✅ Memoize expensive computation
+function ExpensiveList({ items }) {
+  const sorted = useMemo(
+    () => [...items].sort((a, b) => complexSort(a, b)),
+    [items]
+  );
+  return <List items={sorted} />;
+}
+```
+
+### Large Bundle Size
+
+```typescript
+// ❌ Import entire library
+import _ from "lodash";
+const result = _.debounce(fn, 300);
+
+// ✅ Import only what you need
+import debounce from "lodash/debounce";
+const result = debounce(fn, 300);
+
+// ✅✅ Use native (no dependency)
+function debounce(fn, ms) {
+  /* ... */
+}
+```
+
+### Missing Image Optimization
+
+```html
+<!-- ❌ Unoptimized -->
+<img src="hero.png" />
+
+<!-- ✅ Optimized -->
+<img
+  src="hero.webp"
+  srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w"
+  sizes="(max-width: 600px) 400px, (max-width: 1024px) 800px, 1200px"
+  loading="lazy"
+  decoding="async"
+  width="1200"
+  height="630"
+  alt="Hero image"
+/>
+```
+
+### Unnecessary Re-renders (React)
+
+```typescript
+// ❌ New object every render causes child re-render
+function Parent() {
+  return <Child style={{ color: 'red' }} onClick={() => doThing()} />;
+}
+
+// ✅ Stable references
+const style = { color: 'red' };
+function Parent() {
+  const handleClick = useCallback(() => doThing(), []);
+  return <Child style={style} onClick={handleClick} />;
+}
+```
+
+## Profiling Tools
+
+| Context          | Tool                             | What It Shows                     |
+| ---------------- | -------------------------------- | --------------------------------- |
+| Web (browser)    | Chrome DevTools Performance      | Paint, scripting, layout, network |
+| Web (field data) | CrUX, PageSpeed Insights         | Real-user Core Web Vitals         |
+| Node.js          | `node --prof` + `--prof-process` | V8 profiling ticks per function   |
+| Node.js          | `clinic.js`                      | Flamegraphs, event loop delays    |
+| React            | React DevTools Profiler          | Component render times            |
+| SQL              | `EXPLAIN ANALYZE`                | Query execution plan              |
+| Bundle           | `source-map-explorer`            | Module size breakdown             |
+| Network          | `lighthouse`                     | Loading performance audit         |
+
+## Performance Budget
+
+### Setting Budgets
+
+```json
+{
+  "budgets": [
+    { "metric": "js-bundle", "max": "200KB", "warn": "150KB" },
+    { "metric": "css-bundle", "max": "50KB", "warn": "40KB" },
+    { "metric": "lcp", "max": "2500ms", "warn": "2000ms" },
+    { "metric": "api-p95", "max": "200ms", "warn": "150ms" }
+  ]
+}
+```
+
+### Enforcing Budgets in CI
+
+```yaml
+- name: Check bundle size
+  run: |
+    npx bundlesize --config .bundlesizerc.json
+
+- name: Lighthouse audit
+  run: |
+    npx lighthouse $URL --output json --chrome-flags="--headless"
+    # Parse and assert against budgets
+```
+
+## Common Rationalizations
+
+| Excuse                            | Rebuttal                                                                           |
+| --------------------------------- | ---------------------------------------------------------------------------------- |
+| "It's fast enough on my machine"  | Test on low-end devices and slow networks. Your machine isn't representative.      |
+| "We'll optimize later"            | Performance debt compounds. Set budgets now, optimize when they're breached.       |
+| "This micro-optimization matters" | Profile first. If it's not in the hot path, it doesn't matter.                     |
+| "Users won't notice 200ms"        | Studies show 100ms delays reduce conversions. Users notice more than you think.    |
+| "Adding metrics is overhead"      | The overhead of measurement is trivial compared to the cost of blind optimization. |
+| "Caching will fix it"             | Caching masks problems. Fix the root cause, then add caching as defense.           |
+
+## Red Flags — STOP
+
+- Optimizing without profiling data
+- Adding caching to mask a fundamentally slow operation
+- Micro-optimizing code that runs once per request
+- Bundle size growing without review
+- No performance budget or monitoring in place
+- Using `SELECT *` in production queries
+
+## Verification
+
+- [ ] Bottleneck identified with profiling data (not intuition)
+- [ ] Optimization shows measurable improvement in profiler
+- [ ] Performance budget is set and enforced in CI
+- [ ] No regressions in existing benchmarks
+- [ ] Optimization doesn't sacrifice correctness or readability
+
+## See Also
+
+- **react-best-practices** — React-specific performance patterns (server components, bundle optimization)
+- **ci-cd-and-automation** — Enforcing performance budgets in CI
+- **code-simplification** — Simplifying code often improves performance as a side effect

package/dist/template/.opencode/skill/prompt-leverage/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: prompt-leverage
+description: >-
+  Strengthen raw user prompts into execution-ready instruction sets. Use when processing
+  user input to upgrade it with clear objective, context, work style, tool rules, output
+  contract, verification, and done criteria before planning or execution.
+metadata:
+  dependencies: []
+---
+
+# Prompt Leverage
+
+Strengthen the user's current prompt into a stronger working instruction set without changing the underlying intent. Preserve the task, fill in missing execution structure, and add only enough scaffolding to improve reliability.
+
+This skill acts as a **pre-processing layer** — it runs on user input BEFORE planning/execution to ensure every prompt is execution-ready.
+
+## Workflow
+
+1. Read the raw prompt and identify the real job to be done.
+2. Infer the task type: coding, research, writing, analysis, planning, or review.
+3. Rebuild the prompt with the framework blocks in `references/framework.md`.
+4. Keep the result proportional: do not over-specify a simple task.
+5. Return both the improved prompt and a short explanation of what changed when useful.
+
+## Transformation Rules
+
+- Preserve the user's objective, constraints, and tone unless they conflict.
+- Prefer adding missing structure over rewriting everything stylistically.
+- Add context requirements only when they improve correctness.
+- Add tool rules only when tool use materially affects correctness.
+- Add verification and completion criteria for non-trivial tasks.
+- Keep prompts compact enough to be practical in repeated use.
+
+## Framework Blocks
+
+Use these blocks selectively.
+
+- `Objective`: state the task and what success looks like.
+- `Context`: list sources, files, constraints, and unknowns.
+- `Work Style`: set depth, breadth, care, and first-principles expectations.
+- `Tool Rules`: state when tools, browsing, or file inspection are required.
+- `Output Contract`: define structure, formatting, and level of detail.
+- `Verification`: require checks for correctness, edge cases, and better alternatives.
+- `Done Criteria`: define when the agent should stop.
+
+## Output Modes
+
+Choose one mode based on the user request.
+
+- `Inline upgrade`: provide the upgraded prompt only.
+- `Upgrade + rationale`: provide the prompt plus a brief list of improvements.
+- `Template extraction`: convert the prompt into a reusable fill-in-the-blank template.
+- `Hook spec`: explain how to apply the framework automatically before execution.
+
+## Quality Bar
+
+Before finalizing, check the upgraded prompt:
+
+- still matches the original intent
+- does not add unnecessary ceremony
+- includes the right verification level for the task
+- gives the agent a clear definition of done
+
+If the prompt is already strong, say so and make only minimal edits.
+
+## Intensity Levels
+
+Use the minimum level that matches the task.
+
+- `Light`: simple edits, formatting, quick rewrites.
+- `Standard`: typical coding, research, and drafting tasks.
+- `Deep`: debugging, architecture, complex research, or high-stakes outputs.
+
+## Task-Type Adjustments
+
+### Coding
+
+- Emphasize repo context, file inspection, smallest correct change, validation, and edge cases.
+
+### Research
+
+- Emphasize source quality, evidence gathering, synthesis, uncertainty, and citations.
+
+### Writing
+
+- Emphasize audience, tone, structure, constraints, and revision criteria.
+
+### Review
+
+- Emphasize fresh-eyes critique, failure modes, alternatives, and explicit severity.

package/dist/template/.opencode/skill/prompt-leverage/references/framework.md

@@ -0,0 +1,91 @@
+# Prompt Leverage Framework
+
+Reference for combining source ideas into a practical execution framework.
+
+## Source Synthesis
+
+- **Agent Flywheel** contributes behavior controls: intensity, wider search, deeper analysis, fresh eyes, first-principles thinking, and future-self clarity.
+- **OpenAI prompt guidance** contributes execution controls: clear objectives, explicit output contracts, tool persistence, dependency checks, verification loops, and completion criteria.
+
+Treat the final framework as:
+
+`Objective -> Context -> Work Style -> Tool Rules -> Output Contract -> Verification -> Done`
+
+## Block Definitions
+
+### Objective
+
+State the task in one or two lines. Define success in observable terms.
+
+### Context
+
+Specify relevant files, URLs, constraints, assumptions, and information boundaries. Say when the agent must retrieve facts instead of guessing.
+
+### Work Style
+
+Control how the agent approaches the task.
+
+- Go broad first when system understanding matters.
+- Go deep where risk or complexity is highest.
+- Use first-principles reasoning before changing things.
+- Re-check with fresh eyes for non-trivial tasks.
+
+### Tool Rules
+
+Define when browsing, file inspection, tests, or external tools are required. Prevent skipping prerequisite checks.
+
+### Output Contract
+
+Define exact structure, tone, formatting, depth, and any required sections or schemas.
+
+### Verification
+
+Require checks for correctness, grounding, completeness, side effects, and better alternatives.
+
+### Done Criteria
+
+Define what must be true before the agent stops.
+
+## Intensity Levels
+
+Use the minimum level that matches the task.
+
+- `Light`: simple edits, formatting, quick rewrites.
+- `Standard`: typical coding, research, and drafting tasks.
+- `Deep`: debugging, architecture, complex research, or high-stakes outputs.
+
+## Task-Type Adjustments
+
+### Coding
+
+- Emphasize repo context, file inspection, smallest correct change, validation, and edge cases.
+
+### Research
+
+- Emphasize source quality, evidence gathering, synthesis, uncertainty, and citations.
+
+### Writing
+
+- Emphasize audience, tone, structure, constraints, and revision criteria.
+
+### Review
+
+- Emphasize fresh-eyes critique, failure modes, alternatives, and explicit severity.
+
+## Prompt Upgrade Heuristics
+
+- Add missing blocks only when they materially improve execution.
+- Do not turn a one-line request into a giant spec unless the task is genuinely complex.
+- Preserve user language where possible so the upgraded prompt still feels native.
+- Prefer concrete completion criteria over vague quality adjectives.
+
+## Upgrade Rubric
+
+An upgraded prompt is good when it:
+
+1. preserves original intent
+2. reduces ambiguity
+3. sets the right depth and care level
+4. defines the expected output clearly
+5. includes an appropriate verification step
+6. tells the agent when to stop

package/dist/template/.opencode/skill/prompt-leverage/scripts/augment_prompt.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Automated prompt upgrader using the Prompt Leverage Framework."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from textwrap import dedent
+
+
+TASK_KEYWORDS = {
+    "coding": [
+        "code",
+        "bug",
+        "repo",
+        "refactor",
+        "test",
+        "implement",
+        "fix",
+        "function",
+        "api",
+    ],
+    "research": [
+        "research",
+        "compare",
+        "find",
+        "latest",
+        "sources",
+        "analyze market",
+        "look up",
+    ],
+    "writing": ["write", "rewrite", "draft", "email", "memo", "blog", "copy", "tone"],
+    "review": ["review", "audit", "critique", "inspect", "evaluate", "assess"],
+    "planning": ["plan", "roadmap", "strategy", "framework", "outline"],
+    "analysis": ["analyze", "explain", "break down", "diagnose", "root cause"],
+}
+
+
+def detect_task(prompt: str) -> str:
+    """Detect task type by keyword matching."""
+    lowered = prompt.lower()
+    scores = {
+        task: sum(1 for keyword in keywords if keyword in lowered)
+        for task, keywords in TASK_KEYWORDS.items()
+    }
+    best_task, best_score = max(scores.items(), key=lambda item: item[1])
+    return best_task if best_score > 0 else "analysis"
+
+
+def infer_intensity(prompt: str, task: str) -> str:
+    """Infer intensity level from prompt content."""
+    lowered = prompt.lower()
+    if any(
+        token in lowered
+        for token in [
+            "careful",
+            "deep",
+            "thorough",
+            "high stakes",
+            "production",
+            "critical",
+        ]
+    ):
+        return "Deep"
+    if task in {"coding", "research", "review"}:
+        return "Standard"
+    return "Light"
+
+
+def build_tool_rules(task: str) -> str:
+    """Build task-specific tool rules."""
+    rules = {
+        "coding": "Inspect the relevant files and dependencies first. Validate the final change with the narrowest useful checks before broadening scope.",
+        "research": "Retrieve evidence from reliable sources before concluding. Do not guess facts that can be checked.",
+        "review": "Read enough surrounding context to understand intent before critiquing. Distinguish confirmed issues from plausible risks.",
+    }
+    return rules.get(
+        task,
+        "Use tools or extra context only when they materially improve correctness or completeness.",
+    )
+
+
+def build_output_contract(task: str) -> str:
+    """Build task-specific output contract."""
+    contracts = {
+        "coding": "Return the result in a practical execution format: concise summary, concrete changes or code, validation notes, and any remaining risks.",
+        "research": "Return a structured synthesis with key findings, supporting evidence, uncertainty where relevant, and a concise bottom line.",
+        "writing": "Return polished final copy in the requested tone and format. If useful, include a short rationale for major editorial choices.",
+        "review": "Return findings grouped by severity or importance, explain why each matters, and suggest the smallest credible next step.",
+    }
+    return contracts.get(
+        task,
+        "Return a clear, well-structured response matched to the task, with no unnecessary verbosity.",
+    )
+
+
+def upgrade_prompt(raw_prompt: str, task: str | None) -> str:
+    """Upgrade a raw prompt using the framework."""
+    normalized = re.sub(r"\s+", " ", raw_prompt).strip()
+    detected_task = task or detect_task(normalized)
+    intensity = infer_intensity(normalized, detected_task)
+    tool_rules = build_tool_rules(detected_task)
+    output_contract = build_output_contract(detected_task)
+
+    return dedent(
+        f"""
+        Objective:
+        - Complete this task: {normalized}
+        - Optimize for a correct, useful result rather than a merely plausible one.
+
+        Context:
+        - Preserve the user's original intent and constraints.
+        - Surface any key assumptions if required information is missing.
+
+        Work Style:
+        - Task type: {detected_task}
+        - Effort level: {intensity}
+        - Understand the problem broadly enough to avoid narrow mistakes, then go deep where the risk or complexity is highest.
+        - Use first-principles reasoning before proposing changes.
+        - For non-trivial work, review the result once with fresh eyes before finalizing.
+
+        Tool Rules:
+        - {tool_rules}
+
+        Output Contract:
+        - {output_contract}
+
+        Verification:
+        - Check correctness, completeness, and edge cases.
+        - Improve obvious weaknesses if a better approach is available within scope.
+
+        Done Criteria:
+        - Stop only when the response satisfies the task, matches the requested format, and passes the verification step.
+        """
+    ).strip()
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Upgrade a raw prompt into a framework-backed execution prompt."
+    )
+    parser.add_argument("prompt", help="Raw prompt text to upgrade.")
+    parser.add_argument(
+        "--task",
+        choices=sorted(TASK_KEYWORDS.keys()),
+        help="Optional explicit task type (auto-detected if not provided).",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    print(upgrade_prompt(args.prompt, args.task))
+
+
+if __name__ == "__main__":
+    main()

package/dist/template/.opencode/skill/receiving-code-review/SKILL.md

@@ -20,6 +20,17 @@ dependencies: []
 - You already verified and accepted the feedback and are ready to implement
 - You need to request a review (use requesting-code-review)
 
+## Common Rationalizations
+
+| Rationalization                                   | Rebuttal                                                                               |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| "The reviewer is experienced, they must be right" | Experience doesn't mean they have YOUR codebase context. Verify against reality        |
+| "It's faster to just implement it than to verify" | A wrong implementation costs more than the 2 minutes to check                          |
+| "Pushing back will create conflict"               | Technical correctness > social comfort. Shipping wrong code creates bigger conflict    |
+| "I'll fix it and verify later"                    | "Later" means after the wrong change is merged and depended upon                       |
+| "The suggestion is small, no need to verify"      | Small changes break things too. One wrong import can crash a module                    |
+| "I understood the feedback, no need to restate"   | Restating catches misunderstandings BEFORE you waste time implementing the wrong thing |
+
 ## Overview
 
 Code review requires technical evaluation, not emotional performance.

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

@@ -0,0 +1,48 @@
+---
+name: screenshot
+description: Use when the user explicitly asks for desktop/system screenshots or when browser/tool-specific capture is unavailable.
+version: 1.0.0
+tags: [debugging, ui, automation]
+dependencies: []
+---
+
+# screenshot
+
+Capture screenshots at OS level for desktop apps, windows, regions, or full screen.
+
+## When to Use
+
+- User asks for screenshot of desktop/app/window/region
+- You need non-browser captures (native app, OS UI, Electron shell)
+- Browser capture tools are unavailable or insufficient
+
+## When NOT to Use
+
+- Browser-only capture where Playwright/DevTools is enough
+- Design-file capture where Figma skills are available
+
+## Save Location Rules
+
+1. If user gives a path, save there.
+2. If user asks generally for a screenshot, use OS default screenshot location.
+3. If screenshot is for agent inspection, save to temp location.
+
+## Scripts
+
+- `scripts/take_screenshot.py` (macOS/Linux)
+- `scripts/take_screenshot.ps1` (Windows)
+- `scripts/ensure_macos_permissions.sh` (macOS preflight)
+
+## Quick Start
+
+```bash
+# macOS/Linux default capture
+python3 .opencode/skill/screenshot/scripts/take_screenshot.py
+
+# capture app window(s) on macOS to temp
+bash .opencode/skill/screenshot/scripts/ensure_macos_permissions.sh && \
+python3 .opencode/skill/screenshot/scripts/take_screenshot.py --app "Codex" --mode temp
+
+# region capture
+python3 .opencode/skill/screenshot/scripts/take_screenshot.py --mode temp --region 100,200,800,600
+```