@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/anti-ai-slop/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: anti-ai-slop
+description: Use when generating any visual design output (web UI, slides, animations, mockups, infographics) to actively prevent the AI default aesthetic that strips brand identity. Bans purple gradients, emoji-as-icons, rounded-card+left-accent, AI-drawn human SVGs, GitHub-dark `#0D1117`, Inter/Roboto-as-display. Adapted from huashu-design.
+---
+
+# Anti AI Slop
+
+> The AI default aesthetic is the **visual common denominator** of all training data. Using it makes every brand look identical. Avoiding it is **brand protection**, not aesthetic snobbery.
+
+## Why This Matters
+
+The reasoning chain:
+
+1. The user wants their brand to be recognizable.
+2. AI default output = average of training corpus = all brands blended = **no brand recognized**.
+3. So AI defaults dilute the user's brand into "another AI-generated page."
+4. Avoiding AI slop is replacing default-mode output with **brand-specific intent**.
+
+Anti-slop is the **defensive** half of design discipline. The **offensive** half is `brand-asset-protocol` (use real logos, real product images, real colors). Both required.
+
+## The Slop Lookup Table
+
+| Pattern                                                | Why it's slop                                                                               | Allowed when                                                                               |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| **Aggressive purple gradient**                         | The "tech feel" formula in every SaaS/AI/web3 landing page in training data                 | Brand actually uses purple gradient (some Linear contexts), or task is satire of slop      |
+| **Emoji as icon** (`🚀 Fast`, `✨ Magic`)              | "Not professional enough? Add an emoji" disease — symptom of training data                  | Brand uses them (Notion), or audience is kids / casual                                     |
+| **Rounded card + left colored border accent**          | 2020-2024 Material/Tailwind cliche, now visual noise                                        | User explicitly asks, or it's in the brand spec                                            |
+| **SVG-drawn imagery** (humans, faces, scenes)          | AI-drawn SVG humans always have warped faces, weird proportions                             | **Almost never** — use real images (Wikimedia/Unsplash/AI-generated) or honest placeholder |
+| **CSS silhouettes for product photos**                 | Generates "generic tech animation" — black bg + orange accent + rounded bars. Zero brand ID | Almost never — fetch real product photo first (see `brand-asset-protocol`)                 |
+| **Inter / Roboto / Arial / system as display font**    | Too common — reader can't tell "designed product" from "demo page"                          | Brand spec uses them (Stripe uses tuned Inter variant)                                     |
+| **Cyber neon / GitHub dark `#0D1117`**                 | Copy of GitHub dark mode aesthetic, used everywhere                                         | Developer tools brand that genuinely uses this direction                                   |
+| **Generic stock photo "lifestyle" hero on text essay** | Adds no information; pure decoration = slop                                                 | Image is the content (museum portrait, product detail, location card)                      |
+| **3+ accent colors**                                   | Multi-color clustering reads as "I couldn't decide"                                         | Data legitimately has ≥3 categorical dimensions                                            |
+| **Decorative-icon-on-every-line**                      | "Iconography slop" — pads visual density without information                                | Icon carries differentiating product information (status, type, action)                    |
+| **Fabricated stats / fake quotes / lorem ipsum**       | "Data slop" — fills space with meaningless numbers                                          | Never. Ask user for real content or leave honest blank space                               |
+| **One generic "page load" animation everywhere**       | Scattered micro-interactions feel cheap                                                     | One well-orchestrated, intentional animation per page                                      |
+
+**Single criterion for allowing any of these**: "the brand spec uses it" or "the task is intentionally about showing slop." Without that explicit reason, default to avoiding.
+
+## What to Do Instead (Positive Patterns)
+
+- ✅ **`text-wrap: pretty`, CSS Grid, advanced CSS** — typography details an AI usually skips. Signals "real designer."
+- ✅ **Use `oklch()` or colors from the brand spec.** Never invent new colors mid-design — every invented color erodes brand consistency.
+- ✅ **Real images > AI-drawn SVG > HTML/CSS-faked imagery.** Photo first; AI generation second; CSS shapes only when imagery isn't the point.
+- ✅ **Typographic curly quotes** ("smart" not "straight") — signal of "this was reviewed."
+- ✅ **120% on one detail, 80% on the rest.** Taste = picking the right place to be precise. Even attention everywhere = uniformly bland.
+- ✅ **Honest blank > clumsy fill.** A gray block labeled "user avatar" beats an AI-drawn portrait.
+
+## "But the task IS about slop" — Negative Examples Done Right
+
+When the work is showing what _not_ to do (a critique post, a slop-vs-good comparison):
+
+- **Don't fill the whole page with slop.** Containerize the bad sample.
+- Use a **dashed border + corner label** "Anti-pattern · do not copy" so the reader can tell intent.
+- The negative example serves the narrative; it doesn't pollute the page's primary visual register.
+
+## Self-Check Questions (run before delivery)
+
+For every visual element on the page, ask:
+
+1. **Why is this here?** "It looks nice" is not enough. Each element must earn its place.
+2. **Could a different brand use this exact element?** If yes → it's not specific enough.
+3. **Did I invent this color/font/shape, or did it come from the brand spec or a real source?**
+4. **Is there an icon that adds no information?** Remove it.
+5. **Is there a number/stat I made up?** Remove it or get real data.
+6. **Is there a gradient that has no brand basis?** Remove it.
+7. **Is there an SVG of a human/face I drew?** Replace with real image or honest placeholder.
+
+If any answer fails the test, fix before claiming done.
+
+## Pairs Well With
+
+- `brand-asset-protocol` — the positive counterpart (real assets, brand spec)
+- `design-direction-advisor` — when no brand context exists, recommends differentiated directions instead of falling into AI default
+- `design-taste-frontend` — base aesthetic discipline for web UI (more prescriptive; this skill is more prohibitive)
+- `high-end-visual-design` — premium aesthetic overlay

package/dist/template/.opencode/skill/api-and-interface-design/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: api-and-interface-design
+description: Use when designing REST/GraphQL APIs, SDK interfaces, or public module boundaries — covers contract-first design, versioning, error shapes, and backward compatibility
+version: 1.0.0
+tags: [architecture, code-quality]
+dependencies: []
+---
+
+# API & Interface Design
+
+> **Replaces** ad-hoc API creation where endpoints, error shapes, and versioning are afterthoughts
+
+## When to Use
+
+- Designing a new API endpoint, SDK method, or public module interface
+- Reviewing or extending an existing API for backward compatibility
+- Defining error responses, pagination, or authentication contracts
+
+## When NOT to Use
+
+- Internal-only helper functions that no external code calls
+- Prototyping where the API shape will change frequently (use after stabilization)
+
+## Overview
+
+APIs are contracts. Once published, they're hard to change without breaking consumers. Design the contract first, implement second.
+
+**Core principle:** Define the contract (types, errors, versioning) before writing implementation. Make breaking changes impossible through careful interface design.
+
+## Contract-First Process
+
+```
+1. DEFINE  — Write TypeScript types / OpenAPI schema for request & response
+2. REVIEW  — Check backward compatibility, error coverage, naming consistency
+3. IMPLEMENT — Code against the contract, not the other way around
+4. VERIFY  — Validate implementation matches contract exactly
+```
+
+## API Design Checklist
+
+### Naming
+
+- [ ] Resource-oriented URLs (nouns, not verbs): `/users/{id}` not `/getUser`
+- [ ] Consistent casing (camelCase for JSON fields, kebab-case for URLs)
+- [ ] Plural collection names: `/users` not `/user`
+- [ ] Avoid abbreviations — `configuration` not `config` in public APIs
+
+### Request Design
+
+- [ ] Use appropriate HTTP methods (GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes)
+- [ ] Validate all input with schemas (zod, JSON Schema) at the boundary
+- [ ] Accept only what you need — reject unknown fields
+- [ ] Use query params for filtering/pagination, body for creation/mutation
+
+### Response Design
+
+- [ ] Consistent envelope: `{ data, error, meta }` or flat depending on convention
+- [ ] Include pagination metadata: `{ total, page, pageSize, hasMore }`
+- [ ] Return created/updated resource in mutation responses
+- [ ] Use ISO 8601 for dates, UTC always
+
+### Error Design
+
+```typescript
+// Consistent error shape
+interface ApiError {
+  code: string; // machine-readable: "VALIDATION_ERROR", "NOT_FOUND"
+  message: string; // human-readable description
+  details?: unknown; // field-level errors, context
+  requestId?: string; // correlation ID for debugging
+}
+```
+
+- [ ] Use standard HTTP status codes correctly (400 vs 422 vs 500)
+- [ ] Never expose stack traces or internal errors to clients
+- [ ] Include actionable error messages
+- [ ] Document all possible error codes per endpoint
+
+### Versioning
+
+| Strategy      | When                               | Example                               |
+| ------------- | ---------------------------------- | ------------------------------------- |
+| URL prefix    | Breaking changes to resources      | `/v1/users`, `/v2/users`              |
+| Header        | Breaking changes, same URL desired | `Accept: application/vnd.api.v2+json` |
+| Query param   | Simple, low-ceremony               | `/users?version=2`                    |
+| No versioning | Internal APIs, single consumer     | Direct updates                        |
+
+**Default:** URL prefix versioning for public APIs, no versioning for internal.
+
+### Backward Compatibility Rules
+
+| Safe (Non-Breaking)       | Unsafe (Breaking)        |
+| ------------------------- | ------------------------ |
+| Add optional fields       | Remove or rename fields  |
+| Add new endpoints         | Change field types       |
+| Add new enum values       | Remove enum values       |
+| Widen input validation    | Tighten input validation |
+| Add optional query params | Change URL structure     |
+
+## Common Rationalizations
+
+| Excuse                           | Rebuttal                                                                 |
+| -------------------------------- | ------------------------------------------------------------------------ |
+| "It's just an internal API"      | Internal APIs become external. Design the contract now.                  |
+| "We can change it later"         | Every consumer you add makes changes harder. Get it right early.         |
+| "The frontend team will adapt"   | Consumers shouldn't break because you didn't plan the interface.         |
+| "Error handling is boilerplate"  | Inconsistent errors cause more debugging than any boilerplate saves.     |
+| "Versioning is overkill for now" | Adding versioning later requires migrating all consumers simultaneously. |
+
+## TypeScript Patterns
+
+### Strict Input/Output Types
+
+```typescript
+// ✅ Separate input and output types
+interface CreateUserInput {
+  name: string;
+  email: string;
+}
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: string; // ISO 8601
+}
+
+// ✅ Validate at boundary
+const createUserSchema = z.object({
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+});
+```
+
+### Discriminated Unions for Results
+
+```typescript
+type ApiResult<T> = { success: true; data: T } | { success: false; error: ApiError };
+```
+
+## Red Flags — STOP
+
+- Endpoint returns different shapes depending on internal state
+- Error responses have no consistent structure
+- URL contains verbs (`/createUser`, `/deleteItem`)
+- No input validation at the API boundary
+- Response includes internal database IDs or implementation details
+- Breaking change deployed without version bump
+
+## Verification
+
+- [ ] All endpoints have typed request/response schemas
+- [ ] Error responses follow the consistent error shape
+- [ ] Breaking changes increment the API version
+- [ ] Input validation rejects invalid/extra fields
+- [ ] Response matches documented contract exactly
+
+## See Also
+
+- **defense-in-depth** — Validation at every layer, not just the API boundary
+- **incremental-implementation** — Build API endpoints as thin vertical slices
+- **test-driven-development** — Write API contract tests before implementation

package/dist/template/.opencode/skill/augment-context-engine/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: augment-context-engine
+description: Semantic codebase search via Augment Context Engine MCP. Use when you need to understand code relationships, find relevant implementations, or explore unfamiliar codebases beyond keyword matching.
+version: 1.0.0
+tags: [research, context]
+dependencies: []
+---
+
+# Augment Context Engine (MCP)
+
+## When to Use
+
+- When you need semantic search to understand code relationships or find implementations beyond keyword matching.
+
+## When NOT to Use
+
+- When exact string matching or known file paths can be handled by grep/read/LSP locally.
+
+
+## Available Tools
+
+- `augment_code_search` - Semantic search across indexed GitHub repositories
+
+**Parameters:**
+
+- `repo_owner` (string, required) - GitHub org or username (e.g. `"augmentcode"`)
+- `repo_name` (string, required) - Repository name (e.g. `"test-repo"`)
+- `query` (string, required) - Natural language description of what you're looking for
+- `branch` (string, optional) - Branch to search (defaults to `"main"`)
+- `max_results` (integer, optional) - Max code snippets to return (defaults to 5)
+
+## Quick Start
+
+```
+# Search a GitHub repo for authentication code
+skill_mcp(skill_name="augment-context-engine", tool_name="augment_code_search", arguments='{"repo_owner": "myorg", "repo_name": "myapp", "query": "authentication middleware that validates JWT tokens"}')
+
+# Search a specific branch with more results
+skill_mcp(skill_name="augment-context-engine", tool_name="augment_code_search", arguments='{"repo_owner": "myorg", "repo_name": "myapp", "query": "error handling patterns", "branch": "develop", "max_results": 10}')
+```
+
+> **Tip:** Get `repo_owner` and `repo_name` from git: `git remote get-url origin`
+
+## Setup
+
+### 1. Install the Augment GitHub App
+
+Install at [github.com/apps/augmentcode](https://github.com/apps/augmentcode/installations/new) and grant access to the repos you want to index.
+
+### 2. Add the remote server
+
+The skill's `mcp.json` uses `mcp-remote` to bridge the remote API via stdio.
+
+For global access, add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "auggie": {
+      "type": "remote",
+      "url": "https://api.augmentcode.com/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+### 3. Authenticate
+
+Sign in at [app.augmentcode.com](https://app.augmentcode.com) when prompted by `mcp-remote` on first use.
+
+## Query Tips
+
+Good queries (natural language, conceptual):
+
+- `"function that handles user authentication"`
+- `"database connection setup code"`
+- `"tests for the payment processing module"`
+
+Bad queries (use grep instead):
+
+- `"foo_bar"` — exact symbol search
+- `"TODO"` — keyword search
+- `"code that deals with everything"` — too vague
+
+## When to Use
+
+| Scenario                 | Use This              | Instead Of                 |
+| ------------------------ | --------------------- | -------------------------- |
+| Find code by meaning     | `augment_code_search` | `grep` (text only)         |
+| Understand relationships | `augment_code_search` | `@explore` agent (heavier) |
+| Unfamiliar codebase      | `augment_code_search` | Manual file exploration    |
+| Cross-repo dependencies  | `augment_code_search` | LSP references (narrower)  |
+
+## When NOT to Use
+
+- **Exact string matching** — Use `grep` instead (faster, free)
+- **Known file paths** — Use `read` directly
+- **Symbol definitions** — Use LSP `goToDefinition` (precise)
+- **Local-only work** — This searches GitHub-indexed repos, not local files
+
+## Tool Priority Integration
+
+```
+grep (text) → semantic search (meaning) → read (full file) → LSP (symbols) → edit
+```
+
+Use grep first for exact matches. Escalate to semantic search when grep results are noisy or you need conceptual understanding.
+
+## Cost
+
+- ~40-70 credits per query
+- Not free — use judiciously
+- Prefer grep for simple lookups
+
+## Resources
+
+- Docs: https://docs.augmentcode.com/context-services/mcp/overview
+- OpenCode Quickstart: https://docs.augmentcode.com/context-services/mcp/quickstart-open-code
+- GitHub App: https://github.com/apps/augmentcode/installations/new
+- Product: https://www.augmentcode.com/product/context-engine-mcp

package/dist/template/.opencode/skill/augment-context-engine/mcp.json

@@ -0,0 +1,6 @@
+{
+	"augment-context-engine": {
+		"command": "npx",
+		"args": ["-y", "mcp-remote", "https://api.augmentcode.com/mcp"]
+	}
+}

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

@@ -0,0 +1,182 @@
+---
+name: beads
+description: >
+  Multi-agent task coordination using br (beads_rust) CLI. Use when work spans multiple
+  sessions, has dependencies, needs file locking, or requires agent coordination. Covers
+  claim/reserve/done cycle, dependency management, hierarchical decomposition, and session protocols.
+version: "2.0.0"
+license: MIT
+tags: [workflow, agent-coordination]
+dependencies: []
+---
+
+# Beads Workflow - Multi-Agent Task Coordination
+
+> **Replaces** ad-hoc task tracking with sticky notes, TODO comments, or mental checklists that lose state between sessions
+
+## When to Use
+
+- Coordinating multi-session work with dependencies, blockers, or file locking needs
+- Running multi-agent work where tasks must persist across sessions and handoffs
+
+## When NOT to Use
+
+- Single-session, linear tasks tracked via TodoWrite
+- Quick changes with no dependencies or handoff needs
+
+## Overview
+
+**br (beads_rust) CLI** replaces the old `bd` (beads) CLI with a faster Rust implementation.
+
+**Key Distinction**:
+
+- **br CLI**: Multi-session work, dependencies, file locking, agent coordination
+- **TodoWrite**: Single-session tasks, linear execution, conversation-scoped
+
+**When to Use br vs TodoWrite**:
+
+- "Will I need this context in 2 weeks?" → **YES** = br
+- "Does this have blockers/dependencies?" → **YES** = br
+- "Multiple agents editing same codebase?" → **YES** = br
+- "Will this be done in this session?" → **YES** = TodoWrite
+
+**Decision Rule**: If resuming in 2 weeks would be hard without beads, use beads.
+
+## Essential Commands
+
+```bash
+br ready              # Show issues ready to work (no blockers)
+br list --status open # All open issues
+br show <id>          # Full issue details with dependencies
+br create --title "Fix bug" --type bug --priority 2 --description "Details here"
+br update <id> --status in_progress
+br close <id> --reason "Completed"
+br sync --flush-only  # Export to JSONL (then git add/commit manually)
+```
+
+## Hierarchy & Dependencies (Summary)
+
+- Beads supports up to 3 levels of hierarchy: Epic → Task → Subtask
+- Use hierarchy for multi-day, cross-domain, or multi-agent work
+- Dependencies unblock parallel work when parents close
+
+See: `references/HIERARCHY.md` and `references/DEPENDENCIES.md` for full details.
+
+## Session Protocol (Summary)
+
+**Start:** `br ready` → `br update <id> --status in_progress` → `br show <id>`
+
+**End:** `br close <id> --reason "..."` → `br sync --flush-only` → commit `.beads/` → restart session
+
+See: `references/SESSION_PROTOCOL.md` and `references/WORKFLOWS.md` for detailed steps and checklists.
+
+## Task Creation (Summary)
+
+Create tasks when work spans sessions, has dependencies, or is discovered mid-implementation (>2 min).
+
+```bash
+br create --title "Fix authentication bug" --priority 0 --type bug
+```
+
+See: `references/TASK_CREATION.md` for full examples and patterns.
+
+## Git Sync (Summary)
+
+`br` never runs git commands. Always `br sync --flush-only` and commit `.beads/` manually.
+
+See: `references/GIT_SYNC.md` for detailed flow and cleanup guidance.
+
+## Troubleshooting (Summary)
+
+- No ready tasks → `br list --status open`, check blockers via `br show <id>`
+- Sync failures → `br doctor`
+
+See: `references/TROUBLESHOOTING.md` for common issues and fixes.
+
+## Examples
+
+See: `references/EXAMPLES.md` for complete usage examples.
+
+## Multi-Agent Coordination (Summary)
+
+For parallel execution with multiple subagents, use the **swarm-coordination** skill.
+
+See: `references/MULTI_AGENT.md` for swarm tool usage and examples.
+
+## Rules
+
+1. **Check `br ready` first** - Find unblocked work before starting
+2. **Claim before editing** - `br update <id> --status in_progress`
+3. **One task per session** - Restart after `br close`
+4. **Always sync and commit** - `br sync --flush-only` then `git add .beads/ && git commit`
+5. **Write notes for future agents** - Assume zero conversation context
+6. **Claim file paths before editing** - Use reserve to declare ownership (multi-agent only)
+
+## Anti-Patterns
+
+| Anti-Pattern                                                        | Why It Fails                                                  | Instead                                                          |
+| ------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Claiming a bead without reading its current state first (`br show`) | Misses dependencies, blockers, and prior context              | Run `br show <id>` before `br update <id> --status in_progress`  |
+| Closing a bead without verification evidence                        | Marks incomplete or broken work as done                       | Run verification commands and capture output before `br close`   |
+| Working on blocked beads (dependencies not met)                     | Wastes time and causes out-of-order delivery                  | Use `br ready` and confirm dependencies in `br show <id>`        |
+| Modifying bead state without user confirmation                      | Violates workflow expectations and can surprise collaborators | Ask before changing bead status, especially close/sync actions   |
+| Using `br sync` without `--flush-only` (can cause conflicts)        | May write unexpected state and increase sync conflict risk    | Always use `br sync --flush-only` then commit `.beads/` manually |
+
+## Verification
+
+- **Before closing:** run verification commands, paste output as evidence
+- **After close:** `br show <id>` confirms `status=closed`
+- **After sync:** `git status` shows clean working tree
+
+## File Path Claiming (Summary)
+
+Claim files before editing in multi-agent work using `br reserve <id> --files "..."`.
+
+See: `references/FILE_CLAIMING.md` for the full protocol and examples.
+
+## Best Practices (Summary)
+
+- One task per session, then restart
+- File issues for work >2 minutes
+- Weekly `br doctor`, periodic `br cleanup --days 7`
+
+See: `references/BEST_PRACTICES.md` for maintenance and database health guidance.
+
+## Quick Reference
+
+```
+SESSION START:
+  br ready → br update <id> --status in_progress → br show <id>
+
+DURING WORK:
+  br create for discovered work (>2min)
+  br show <id> for context
+
+SESSION END:
+  br close <id> --reason "..." → br sync --flush-only → git add .beads/ && git commit → RESTART SESSION
+
+MAINTENANCE:
+  br doctor - weekly health check
+  br cleanup --days 7 - remove old issues
+```
+
+## References
+
+- `references/BOUNDARIES.md`
+- `references/RESUMABILITY.md`
+- `references/DEPENDENCIES.md`
+- `references/WORKFLOWS.md`
+- `references/HIERARCHY.md`
+- `references/SESSION_PROTOCOL.md`
+- `references/TASK_CREATION.md`
+- `references/GIT_SYNC.md`
+- `references/TROUBLESHOOTING.md`
+- `references/EXAMPLES.md`
+- `references/MULTI_AGENT.md`
+- `references/FILE_CLAIMING.md`
+- `references/BEST_PRACTICES.md`
+
+## See Also
+
+- `verification-before-completion`
+- `swarm-coordination`

package/dist/template/.opencode/skill/beads/references/BEST_PRACTICES.md

@@ -0,0 +1,27 @@
+# Best Practices
+
+## Daily/Weekly Maintenance
+
+| Task         | Frequency      | Command               | Why                                            |
+| ------------ | -------------- | --------------------- | ---------------------------------------------- |
+| Health check | Weekly         | `br doctor`           | Repairs database issues, detects orphaned work |
+| Cleanup      | Every few days | `br cleanup --days 7` | Keep DB under 200-500 issues for performance   |
+
+## Key Principles
+
+1. **Plan outside Beads first** - Use planning tools, then import tasks to beads
+2. **One task per session, then restart** - Fresh context prevents confusion
+3. **File lots of issues** - Any work >2 minutes should be tracked
+4. **"Land the plane" = PUSH** - `br sync --flush-only` + git commit/push, not "ready when you are"
+5. **Include issue ID in commits** - `git commit -m "Fix bug (br-abc)"`
+
+## Database Health
+
+```bash
+# Check database size
+br list --status all --json | wc -l
+
+# Target: under 200-500 issues
+# If over, run cleanup more aggressively:
+br cleanup --days 3
+```