@ultrakit/ultrakit 0.0.0

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

@@ -0,0 +1,224 @@
+---
+name: figma
+description: Use when implementing UI from Figma designs, extracting design tokens, or downloading assets via Framelink MCP. MUST load when user shares a Figma URL or references Figma files. Requires API token.
+mcp:
+  figma:
+    command: npx
+    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)
+
+## 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
+
+Set your Figma API key as an environment variable:
+
+```bash
+export FIGMA_API_KEY="your-figma-personal-access-token"
+```
+
+To create a Figma Personal Access Token:
+
+1. Go to Figma → Settings → Account → Personal access tokens
+2. Create a new token with read access
+3. See: https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens
+
+## Quick Start
+
+After loading this skill, use `skill_mcp` to invoke Figma tools:
+
+```
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123", "nodeId": "1234:5678"}')
+```
+
+## Available Tools
+
+### get_figma_data
+
+Fetch comprehensive Figma file data including layout, content, visuals, and component information.
+
+| Parameter | Type   | Required | Description                                                                                       |
+| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
+| `fileKey` | string | Yes      | The Figma file key (from URL: `figma.com/file/<fileKey>/...` or `figma.com/design/<fileKey>/...`) |
+| `nodeId`  | string | No       | Specific node ID (from URL param `node-id=<nodeId>`). Format: `1234:5678` or `1234-5678`          |
+| `depth`   | number | No       | Levels deep to traverse. Only use if explicitly requested by user.                                |
+
+**Returns:** YAML-formatted design data with:
+
+- `metadata` - File/node information
+- `nodes` - Simplified node tree with layout, styles, text content
+- `globalVars` - Shared styles and variables
+
+### download_figma_images
+
+Download SVG and PNG images/icons from a Figma file.
+
+| Parameter   | Type   | Required | Description                                   |
+| ----------- | ------ | -------- | --------------------------------------------- |
+| `fileKey`   | string | Yes      | The Figma file key                            |
+| `nodes`     | array  | Yes      | Array of node objects to download (see below) |
+| `localPath` | string | Yes      | Absolute path to save images                  |
+| `pngScale`  | number | No       | Export scale for PNGs (default: 2)            |
+
+**Node object structure:**
+
+```json
+{
+  "nodeId": "1234:5678",
+  "fileName": "icon-name.svg",
+  "imageRef": "optional-for-image-fills"
+}
+```
+
+## Workflow
+
+### 1. Extract File Key and Node ID from Figma URL
+
+Figma URLs follow these patterns:
+
+- `https://www.figma.com/file/<fileKey>/<fileName>?node-id=<nodeId>`
+- `https://www.figma.com/design/<fileKey>/<fileName>?node-id=<nodeId>`
+
+Example: `https://www.figma.com/design/abc123xyz/MyDesign?node-id=1234-5678`
+
+- `fileKey`: `abc123xyz`
+- `nodeId`: `1234-5678` (or `1234:5678` - both formats work)
+
+### 2. Fetch Design Data
+
+```
+# Fetch specific frame/component
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123xyz", "nodeId": "1234:5678"}')
+
+# Fetch entire file (use sparingly - can be large)
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123xyz"}')
+```
+
+### 3. Download Assets (Optional)
+
+```
+skill_mcp(skill_name="figma", tool_name="download_figma_images", arguments='{
+  "fileKey": "abc123xyz",
+  "nodes": [
+    {"nodeId": "1234:5678", "fileName": "hero-image.png"},
+    {"nodeId": "5678:9012", "fileName": "icon-arrow.svg"}
+  ],
+  "localPath": "/absolute/path/to/assets"
+}')
+```
+
+## Examples
+
+### Implement a Component from Figma
+
+```
+# User provides: https://www.figma.com/design/abc123/Dashboard?node-id=100-200
+
+# 1. Fetch the design data
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "abc123", "nodeId": "100-200"}')
+
+# 2. Review the returned YAML for:
+#    - Layout structure (flex, grid, spacing)
+#    - Typography (font, size, weight, line-height)
+#    - Colors (fills, strokes)
+#    - Dimensions and constraints
+
+# 3. Implement the component using the extracted data
+```
+
+### Extract Design Tokens
+
+```
+# Fetch a design system file
+skill_mcp(skill_name="figma", tool_name="get_figma_data", arguments='{"fileKey": "designSystemKey"}')
+
+# The globalVars section contains:
+# - Color styles
+# - Typography styles
+# - Effect styles (shadows, blurs)
+```
+
+### Download Icons
+
+```
+skill_mcp(skill_name="figma", tool_name="download_figma_images", arguments='{
+  "fileKey": "iconLibraryKey",
+  "nodes": [
+    {"nodeId": "10:20", "fileName": "icon-home.svg"},
+    {"nodeId": "10:30", "fileName": "icon-settings.svg"},
+    {"nodeId": "10:40", "fileName": "icon-user.svg"}
+  ],
+  "localPath": "/project/src/assets/icons",
+  "pngScale": 2
+}')
+```
+
+## Data Structure
+
+The `get_figma_data` tool returns simplified, AI-optimized data:
+
+```yaml
+metadata:
+  name: "Component Name"
+  lastModified: "2024-01-15T..."
+
+nodes:
+  - id: "1234:5678"
+    name: "Button"
+    type: "FRAME"
+    layout:
+      mode: "HORIZONTAL"
+      padding: { top: 12, right: 24, bottom: 12, left: 24 }
+      gap: 8
+    size: { width: 120, height: 48 }
+    fills:
+      - type: "SOLID"
+        color: { r: 0.2, g: 0.4, b: 1, a: 1 }
+    cornerRadius: 8
+    children:
+      - id: "1234:5679"
+        name: "Label"
+        type: "TEXT"
+        content: "Click me"
+        textStyle:
+          fontFamily: "Inter"
+          fontSize: 16
+          fontWeight: 600
+
+globalVars:
+  styles:
+    "S:abc123": { name: "Primary", fills: [...] }
+```
+
+## Tips
+
+- **Always use nodeId** when provided - fetching entire files is slow and context-heavy
+- **Node IDs with `-` or `:`** both work - the MCP handles conversion
+- **Check globalVars** for reusable styles before hardcoding values
+- **Use depth parameter sparingly** - only when explicitly needed
+- **For images/icons**, identify nodes with `imageRef` in the data for proper downloading
+- **SVG vs PNG**: Use `.svg` for icons/vectors, `.png` for photos/complex images
+
+## Troubleshooting
+
+**"Invalid API key"**: Ensure `FIGMA_API_KEY` environment variable is set correctly.
+
+**"File not found"**: Verify the fileKey is correct and you have access to the file.
+
+**"Node not found"**: Check the nodeId format. Try both `1234:5678` and `1234-5678`.
+
+**Large response**: Use `nodeId` to fetch specific frames instead of entire files.

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

@@ -0,0 +1,65 @@
+---
+name: figma-go
+description: Use when you need Figma read/write access WITHOUT an API token, via figma-mcp-go plugin bridge. Prefer over figma skill when no API token is available. MUST load when user needs Figma data and has the desktop plugin installed.
+mcp:
+  figma-mcp-go:
+    command: npx
+    args: ["-y", "@vkhanhqui/figma-mcp-go@latest"]
+version: 1.0.0
+tags: [design, mcp, figma]
+dependencies: []
+---
+
+# Figma MCP (figma-mcp-go)
+
+## When to Use
+
+- You need **read/write** access to live Figma documents without API rate limits.
+- You want to generate designs or modify existing Figma files via MCP.
+
+## When NOT to Use
+
+- You only need static exports (use existing asset pipeline).
+- You don’t have access to Figma Desktop or can’t install plugins.
+
+## Prerequisites (one-time setup)
+
+1. **Install the Figma plugin**
+
+- Download `plugin.zip` from: https://github.com/vkhanhqui/figma-mcp-go/releases
+- In Figma Desktop: **Plugins → Development → Import plugin from manifest**
+- Select `manifest.json` inside `plugin.zip`
+- Run the plugin inside any Figma file
+
+2. **Ensure MCP server runs via OpenCode**
+
+- This skill starts the MCP server with:
+  `npx -y @vkhanhqui/figma-mcp-go@latest`
+- No `FIGMA_API_KEY` is required.
+
+## Quick Start
+
+```bash
+skill_mcp(skill_name="figma-go", tool_name="get_metadata", arguments='{}')
+```
+
+## Common Tools
+
+- **Read**: `get_document`, `get_pages`, `get_node`, `get_nodes_info`, `get_design_context`
+- **Write**: `create_frame`, `create_text`, `set_text`, `set_fills`, `move_nodes`, `resize_nodes`, `delete_nodes`
+- **Export**: `get_screenshot`, `save_screenshots`
+
+## Example: Read a Frame
+
+```bash
+skill_mcp(skill_name="figma-go", tool_name="get_node", arguments='{"node_id":"1234:5678"}')
+```
+
+## Notes
+
+- This MCP uses a **plugin bridge**, so Figma Desktop must be running with the plugin active.
+- If tools fail, re-run the plugin inside the open Figma file.
+- If you see `Invalid schema for function 'figma-mcp-go_delete_nodes'`, keep the
+  global `mcp.figma-mcp-go` entry **disabled** in `opencode.json` and use this skill
+  (via `skill_mcp`) until upstream fixes the schema.
+- Full tool list and prompts: https://github.com/vkhanhqui/figma-mcp-go#available-tools

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

@@ -0,0 +1,357 @@
+---
+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.
+
+**Core principle:** Verify tests → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
+
+## The Process
+
+### 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
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:**
+
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Don't proceed to Step 2.
+
+**If tests pass:** Continue to Step 2.
+
+### Step 2: Determine Base Branch
+
+```bash
+# Try common base branches
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+Or ask: "This branch split from main - is that correct?"
+
+### Step 3: Present Options
+
+Use question tool to present completion options:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Complete",
+      question: "Implementation complete. What would you like to do?",
+      options: [
+        {
+          label: "Merge locally (Recommended)",
+          description: "Merge to base branch",
+        },
+        {
+          label: "Push & create PR",
+          description: "Create pull request for review",
+        },
+        { label: "Keep branch", description: "I'll handle it later" },
+        { label: "Discard work", description: "Delete this branch" },
+      ],
+    },
+  ],
+});
+```
+
+**Don't add explanation** - keep options concise.
+
+### 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
+# Switch to base branch
+git checkout <base-branch>
+
+# Pull latest
+git pull
+
+# Merge feature branch
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+
+# If tests pass
+git branch -d <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 2: Push and Create PR
+
+```bash
+# Push branch
+git push -u origin <feature-branch>
+
+# Create PR
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+<2-3 bullets of what changed>
+
+## Test Plan
+- [ ] <verification steps>
+EOF
+)"
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+
+**Don't cleanup worktree.**
+
+#### Option 4: Discard
+
+**Confirm first:**
+
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <commit-list>
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for exact confirmation.
+
+If confirmed:
+
+```bash
+git checkout <base-branch>
+git branch -D <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+### Step 5: Cleanup Worktree
+
+**For Options 1, 2, 4:**
+
+Check if in worktree:
+
+```bash
+git worktree list | grep $(git branch --show-current)
+```
+
+If yes:
+
+```bash
+git worktree remove <worktree-path>
+```
+
+**For Option 3:** Keep worktree.
+
+## Quick Reference
+
+| Option           | Merge | Push | Keep Worktree | Cleanup Branch |
+| ---------------- | ----- | ---- | ------------- | -------------- |
+| 1. Merge locally | ✓     | -    | -             | ✓              |
+| 2. Create PR     | -     | ✓    | ✓             | -              |
+| 3. Keep as-is    | -     | -    | ✓             | -              |
+| 4. Discard       | -     | -    | -             | ✓ (force)      |
+
+## Mandatory Build Gates (Longshot Pattern)
+
+**Build gates are non-optional before any merge/PR/close.** Advisory verification has failed at scale — gates must be enforced as hard blockers.
+
+### 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
+# Gate 1: Typecheck
+npm run typecheck
+# Must exit 0. If fails → STOP. Fix types first.
+
+# Gate 2: Lint
+npm run lint
+# Must exit 0. If fails → STOP. Run npm run lint:fix, then fix remaining.
+
+# Gate 3: Tests
+vitest
+# Must exit 0. If fails → STOP. Fix failing tests first.
+```
+
+### Gate Enforcement Script
+
+Run before every merge, PR creation, or bead close:
+
+```bash
+#!/bin/bash
+# Run mandatory gates — all must pass
+
+echo "Gate 1/3: Typecheck..."
+npm run typecheck || { echo "FAILED: Fix type errors before proceeding."; exit 1; }
+
+echo "Gate 2/3: Lint..."
+npm run lint || {
+  echo "Attempting auto-fix..."
+  npm run lint:fix
+  npm run lint || { echo "FAILED: Fix lint errors before proceeding."; exit 1; }
+}
+
+echo "Gate 3/3: Tests..."
+vitest || { echo "FAILED: Fix failing tests before proceeding."; exit 1; }
+
+echo "All gates passed. Safe to merge/PR/close."
+```
+
+### Gate Failure Response
+
+| Gate Failure | First Action                     | If Still Failing            |
+| ------------ | -------------------------------- | --------------------------- |
+| Typecheck    | Fix type errors at reported line | Use LSP hover for type info |
+| Lint         | Run `npm run lint:fix`           | Fix remaining manually      |
+| Tests        | Read failing test output         | Fix implementation or test  |
+
+### Hard Rules
+
+**NEVER:**
+
+- Close a bead without passing all 3 gates
+- Create a PR without passing all 3 gates
+- Merge locally without passing all 3 gates on merged result
+- Skip gates "because the change is small"
+
+**ALWAYS:**
+
+- Run gates after EVERY non-trivial file change
+- Re-run gates after fixing gate failures (to catch regressions)
+- Run gates on the merged result, not just the branch
+
+### Integration with Bead Workflow
+
+```bash
+# Before closing any bead:
+npm run typecheck && npm run lint && vitest
+
+# If all pass:
+br close <id> --reason "Implementation complete. All gates passed."
+br sync --flush-only
+
+# If any fail:
+# STOP. Fix. Re-run gates. Then close.
+```
+
+### Gate State in Delegation Packets
+
+Workers must include gate results in their completion report:
+
+```markdown
+## Completion Report
+
+### Gate Results
+
+- [ ] typecheck: PASS / FAIL (error: ...)
+- [ ] lint: PASS / FAIL (error: ...)
+- [ ] tests: PASS / FAIL (N failed, N passed)
+
+### Gate Command Used
+
+`npm run typecheck && npm run lint && vitest`
+```
+
+## Common Mistakes
+
+**Skipping test verification**
+
+- **Problem:** Merge broken code, create failing PR
+- **Fix:** Always verify tests before offering options
+
+**Open-ended questions**
+
+- **Problem:** "What should I do next?" → ambiguous
+- **Fix:** Present exactly 4 structured options
+
+**Automatic worktree cleanup**
+
+- **Problem:** Remove worktree when might need it (Option 2, 3)
+- **Fix:** Only cleanup for Options 1 and 4
+
+**No confirmation for discard**
+
+- **Problem:** Accidentally delete work
+- **Fix:** Require typed "discard" confirmation
+
+## Red Flags
+
+**Never:**
+
+- Proceed with failing tests
+- Merge without verifying tests on result
+- Delete work without confirmation
+- Force-push without explicit request
+
+**Always:**
+
+- Verify tests before offering options
+- Present exactly 4 options
+- Get typed confirmation for Option 4
+- Clean up worktree for Options 1 & 4 only
+
+## Integration
+
+**Called by:**
+
+- **subagent-driven-development** (Step 7) - After all tasks complete
+- **executing-plans** (Step 5) - After all batches complete
+
+**Pairs with:**
+
+- **using-git-worktrees** - Cleans up worktree created by that skill