@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/using-git-worktrees/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: using-git-worktrees
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
+version: 1.0.0
+tags: [git, workflow]
+dependencies: []
+---
+
+# Using Git Worktrees
+
+## When to Use
+
+- When starting feature work that needs an isolated workspace or before executing an implementation plan.
+
+## When NOT to Use
+
+- When a simple change can safely be done in the current working tree or the repo does not allow worktrees.
+
+## Overview
+
+Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
+
+**Core principle:** Systematic directory selection + safety verification = reliable isolation.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Directory Selection Process
+
+Follow this priority order:
+
+### 1. Check Existing Directories
+
+```bash
+# Check in priority order
+ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+ls -d worktrees 2>/dev/null      # Alternative
+```
+
+**If found:** Use that directory. If both exist, `.worktrees` wins.
+
+### 2. Check AGENTS.md
+
+```bash
+grep -i "worktree.*director" AGENTS.md 2>/dev/null
+```
+
+**If preference specified:** Use it without asking.
+
+### 3. Ask User
+
+If no directory exists and no AGENTS.md preference:
+
+```
+No worktree directory found. Where should I create worktrees?
+
+1. .worktrees/ (project-local, hidden)
+2. ~/.opencode/worktrees/<project-name>/ (global location)
+
+Which would you prefer?
+```
+
+## Safety Verification
+
+### For Project-Local Directories (.worktrees or worktrees)
+
+**MUST verify .gitignore before creating worktree:**
+
+```bash
+# Check if directory pattern in .gitignore
+grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore
+```
+
+**If NOT in .gitignore:**
+
+Per Jesse's rule "Fix broken things immediately":
+
+1. Add appropriate line to .gitignore
+2. Commit the change
+3. Proceed with worktree creation
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+### For Global Directory (~/.opencode/worktrees)
+
+No .gitignore verification needed - outside project entirely.
+
+## Creation Steps
+
+### 1. Detect Project Name
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### 2. Create Worktree
+
+```bash
+# Determine full path
+case $LOCATION in
+  .worktrees|worktrees)
+    path="$LOCATION/$BRANCH_NAME"
+    ;;
+  ~/.opencode/worktrees/*)
+    path="~/.opencode/worktrees/$project/$BRANCH_NAME"
+    ;;
+esac
+
+# Create worktree with new branch
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+## Worktree Tracking
+
+After creating a worktree, persist its absolute path for session resume:
+
+```bash
+# After creating worktree
+mkdir -p .beads/artifacts/$BEAD_ID
+echo "/absolute/path/to/worktree" > .beads/artifacts/$BEAD_ID/worktree.txt
+```
+
+On session resume, restore the active worktree if tracking exists:
+
+```bash
+# Check if worktree exists for active bead
+if [ -f .beads/artifacts/$BEAD_ID/worktree.txt ]; then
+  WORKTREE_PATH=$(cat .beads/artifacts/$BEAD_ID/worktree.txt)
+  cd "$WORKTREE_PATH"
+fi
+```
+
+On worktree cleanup (after merge), remove the tracking file:
+
+```bash
+rm -f .beads/artifacts/$BEAD_ID/worktree.txt
+```
+
+### 3. Run Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### 4. Verify Clean Baseline
+
+Run tests to ensure worktree starts clean:
+
+```bash
+# Examples - use project-appropriate command
+npm test
+cargo test
+pytest
+go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### 5. Report Location
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation                   | Action                      |
+| --------------------------- | --------------------------- |
+| `.worktrees/` exists        | Use it (verify .gitignore)  |
+| `worktrees/` exists         | Use it (verify .gitignore)  |
+| Both exist                  | Use `.worktrees/`           |
+| Neither exists              | Check AGENTS.md → Ask user  |
+| Directory not in .gitignore | Add it immediately + commit |
+| Tests fail during baseline  | Report failures + ask       |
+| No package.json/Cargo.toml  | Skip dependency install     |
+
+## Common Mistakes
+
+**Skipping .gitignore verification**
+
+- **Problem:** Worktree contents get tracked, pollute git status
+- **Fix:** Always grep .gitignore before creating project-local worktree
+
+**Assuming directory location**
+
+- **Problem:** Creates inconsistency, violates project conventions
+- **Fix:** Follow priority: existing > AGENTS.md > ask
+
+**Proceeding with failing tests**
+
+- **Problem:** Can't distinguish new bugs from pre-existing issues
+- **Fix:** Report failures, get explicit permission to proceed
+
+**Hardcoding setup commands**
+
+- **Problem:** Breaks on projects using different tools
+- **Fix:** Auto-detect from project files (package.json, etc.)
+
+## Example Workflow
+
+```
+You: I'm using the using-git-worktrees skill to set up an isolated workspace.
+
+[Check .worktrees/ - exists]
+[Verify .gitignore - contains .worktrees/]
+[Create worktree: git worktree add .worktrees/auth -b feature/auth]
+[Run npm install]
+[Run npm test - 47 passing]
+
+Worktree ready at /Users/jesse/myproject/.worktrees/auth
+Tests passing (47 tests, 0 failures)
+Ready to implement auth feature
+```
+
+## Red Flags
+
+**Never:**
+
+- Create worktree without .gitignore verification (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without asking
+- Assume directory location when ambiguous
+- Skip AGENTS.md check
+
+**Always:**
+
+- Follow directory priority: existing > AGENTS.md > ask
+- Verify .gitignore for project-local
+- Auto-detect and run project setup
+- Verify clean test baseline
+
+## Integration
+
+**Called by:**
+
+- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
+- Any skill needing isolated workspace
+
+**Pairs with:**
+
+- **finishing-a-development-branch** - REQUIRED for cleanup after work complete
+- **executing-plans** or **subagent-driven-development** - Work happens in this worktree

package/dist/template/.opencode/skill/ux-quality-gates/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: ux-quality-gates
+description: Use when designing, reviewing, planning, or shipping user-facing UI where UX correctness matters — applies information architecture, usability heuristics, forms, recovery, loading states, semantic HTML, and component consistency checks.
+version: 1.0.0
+tags: [ui, design, code-quality]
+dependencies: []
+---
+
+# UX Quality Gates
+
+## Overview
+
+UX quality is not visual polish. A screen passes only when users can understand scope, complete the primary task, recover from errors, and use it with keyboard/screen reader support.
+
+This skill consolidates high-signal UX review patterns into gates for `/design`, `/ui-review`, `/ui-slop-check`, `/plan`, and `/ship`.
+
+## When to Use
+
+- Designing or reviewing user-facing components, pages, dashboards, forms, or flows.
+- Planning UI PRDs that include loading, error, empty, success, destructive, or async states.
+- Auditing changed UI files before shipping.
+- Checking enterprise/data-heavy UIs with selection, bulk actions, filters, or tables.
+
+## When NOT to Use
+
+- Backend-only work.
+- Pure visual asset generation with no interaction or user flow.
+- Trivial copy/color tweaks where no behavior, state, or structure changes.
+
+## Core Gates
+
+| Gate                     | Pass Condition                                                              | Failure Signals                                                                  |
+| ------------------------ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Information architecture | UI names match user vocabulary; scope and relationships are visible         | Engineer terms, mixed synonyms, hidden side effects                              |
+| Primary action           | One dominant action per view/section                                        | Multiple filled buttons, equal cancel/confirm, destructive action beside primary |
+| Forms                    | Label, helper, validation, and error wiring are explicit                    | Placeholder-as-label, errors not associated, disabled submit hiding issues       |
+| Recovery                 | Every failure path offers retry, undo, fallback, or support                 | Dead-end errors, disappearing error toasts, no rollback for optimistic UI        |
+| State coverage           | Empty/loading/error/success states exist and match final layout             | Global spinner, mismatched skeleton, no no-results state                         |
+| Accessibility            | WCAG 2.2 AA baseline, keyboard path, focus, semantic HTML                   | No skip path, focus trap, unlabeled controls, ARIA replacing native HTML         |
+| Semantic web             | Correct landmarks/headings/native controls; SEO only when page is indexable | Div buttons, multiple h1s, missing route focus/scroll handling                   |
+| Component family         | Shared token DNA across related components                                  | One-off radius/color/height/shadow, inconsistent focus/error states              |
+
+## Usability Heuristic Pass
+
+Check every UI against these ten questions:
+
+1. **System status** — Does the UI show what is happening now?
+2. **Real-world language** — Does copy use user vocabulary, not implementation terms?
+3. **User control** — Can users cancel, undo, go back, or recover?
+4. **Consistency** — Are names, controls, and patterns reused consistently?
+5. **Error prevention** — Are dangerous or invalid actions prevented before they happen?
+6. **Recognition over recall** — Are options, context, and relationships visible?
+7. **Efficiency** — Are shortcuts or bulk actions available where volume requires them?
+8. **Minimalism** — Is each visible element serving the current task?
+9. **Error recovery** — Does error copy say what happened, why, and how to fix it?
+10. **Help** — Is guidance present where users may be stuck?
+
+## Pattern Rules
+
+### Destructive Actions
+
+Require confirmation for permanent deletion, bulk destructive actions, permission/security changes, billing/account scope changes, and irreversible workflow transitions.
+
+Confirmation anatomy:
+
+- Title names the entity/action specifically.
+- Body lists concrete consequences.
+- Primary label is explicit, e.g. `Delete project`, not `OK` or `Yes`.
+- Cancel is easy and default-focused.
+- Highest-risk actions require typing the entity name.
+
+Prefer undo for low-stakes reversible actions.
+
+### Forms
+
+- Labels are always visible; placeholders are examples only.
+- Helper text explains expected input or consequences.
+- Validate on blur by default; use debounced real-time validation for complex fields.
+- Submit catches all errors and moves focus/scroll to the first error.
+- Use `aria-describedby`, `aria-invalid`, and `role="alert"` for errors.
+- Required/optional marker shows the minority case.
+- Use correct `type`, `autocomplete`, `fieldset`, and `legend`.
+- Disable submit only for short forms where all validity is visible; otherwise allow submit and show errors.
+
+### Loading and Async States
+
+| Wait | Pattern                                      |
+| ---- | -------------------------------------------- |
+| <1s  | Inline spinner or optimistic update          |
+| 1-3s | Skeleton matching final layout               |
+| >3s  | Determinate/progressive status when possible |
+
+- Button loading prevents duplicate submit without shifting layout.
+- Skeletons are recessive and match final dimensions.
+- Optimistic updates must have rollback.
+- Error toasts persist until dismissed or replaced by a visible recovery path.
+
+### Notifications and Recovery
+
+- Success toast: auto-dismiss after 4-6s unless action is needed.
+- Error toast/banner: persists until resolved or dismissed.
+- Toasts have at most one action.
+- Inline errors live beside the affected control.
+- Failed sections degrade locally instead of blanking the whole app.
+- Transient failures get retry; repeated failures escalate to support or alternative path.
+
+### Data Display and Selection
+
+Use for data-heavy UIs only:
+
+- Offer grid/list/table only when each view changes task value.
+- Persist view choice when useful.
+- Selection supports row/card click, checkbox indicator, keyboard Space, and range selection where expected.
+- Bulk action toolbar shows selected count.
+- Destructive bulk actions name the count and scope.
+- Distinguish filtered no-results from genuinely empty state.
+- Tables may need sticky headers/first column, row actions, and resize/reorder for enterprise density.
+
+## Review Output
+
+When reporting findings, include:
+
+- Gate name.
+- Severity: Critical, Warning, or Info.
+- Location with `file:line` when reviewing code.
+- User impact.
+- Concrete fix.
+
+## Common Mistakes
+
+| Mistake                                 | Fix                                                              |
+| --------------------------------------- | ---------------------------------------------------------------- |
+| Treating UX as aesthetics               | Check task completion, recovery, and state coverage first        |
+| Adding every UX rule to every task      | Apply data/table/SEO rules only when relevant                    |
+| Using ARIA to patch non-semantic markup | Prefer native elements, add ARIA only when semantics are missing |
+| Making errors transient                 | Persistent errors need persistent recovery                       |
+| Importing many overlapping skills       | Use this consolidated gate and existing design/a11y skills       |

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

@@ -0,0 +1,158 @@
+---
+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.