@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/accessibility-audit/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: accessibility-audit
+description: Use when auditing UI components or pages for accessibility compliance, checking WCAG conformance, identifying keyboard navigation issues, color contrast problems, and pre-launch accessibility verification
+version: 1.0.0
+tags: [ui, code-quality]
+dependencies: []
+---
+
+# Accessibility Audit Skill
+
+## When to Use
+
+- Reviewing UI components for accessibility compliance
+- Auditing pages for WCAG conformance
+- Identifying keyboard navigation issues
+- Checking color contrast
+- Pre-launch accessibility verification
+
+## When NOT to Use
+
+- Non-UI work where accessibility isn't applicable.
+
+
+## Core Workflow
+
+### Phase 1: Visual Accessibility Analysis
+
+```
+Perform a comprehensive accessibility audit:
+
+1. COLOR CONTRAST
+   - Check text/background contrast ratios
+   - WCAG AA: 4.5:1 normal text, 3:1 large text
+   - Identify failing elements
+
+2. VISUAL HIERARCHY
+   - Heading structure (logical H1-H6)
+   - Visual grouping of related elements
+   - Touch targets (44x44px minimum)
+
+3. CONTENT ACCESSIBILITY
+   - Images needing alt text
+   - Icons without text labels
+   - Color-only information
+
+4. INTERACTIVE ELEMENTS
+   - Buttons/links with unclear purpose
+   - Form fields without labels
+   - Missing error states
+
+5. MOTION
+   - Auto-playing content
+   - Potential vestibular triggers
+
+Provide WCAG criterion references for each issue.
+```
+
+### Phase 2: Component Checklist
+
+For each interactive component:
+
+```markdown
+## Component: [Name]
+
+### Keyboard Navigation
+
+- [ ] Focusable with Tab
+- [ ] Visible focus indicator
+- [ ] Operable with Enter/Space
+- [ ] Escape closes modals
+- [ ] Arrow keys for menus
+
+### Screen Reader
+
+- [ ] Meaningful accessible name
+- [ ] Role announced correctly
+- [ ] State changes announced
+- [ ] Errors associated with inputs
+
+### Visual
+
+- [ ] 4.5:1 contrast ratio (text)
+- [ ] 3:1 contrast ratio (UI)
+- [ ] 44x44px touch targets
+- [ ] No color-only information
+
+### Motion
+
+- [ ] Respects prefers-reduced-motion
+- [ ] No auto-play >5 seconds
+```
+
+## WCAG Quick Reference
+
+### Level A (Minimum)
+
+| Criterion | Description            | Fix               |
+| --------- | ---------------------- | ----------------- |
+| 1.1.1     | Non-text Content       | Add alt text      |
+| 1.3.1     | Info and Relationships | Use semantic HTML |
+| 2.1.1     | Keyboard               | All via keyboard  |
+| 2.4.1     | Bypass Blocks          | Skip links        |
+| 4.1.2     | Name, Role, Value      | ARIA labels       |
+
+### Level AA (Recommended)
+
+| Criterion | Description   | Fix                    |
+| --------- | ------------- | ---------------------- |
+| 1.4.3     | Contrast      | 4.5:1 text, 3:1 UI     |
+| 1.4.4     | Resize Text   | Support 200% zoom      |
+| 2.4.6     | Headings      | Descriptive headings   |
+| 2.4.7     | Focus Visible | Clear focus indicators |
+
+## Common Fixes
+
+### Accessible Button
+
+```tsx
+// Bad
+<div onClick={handleClick}>Click me</div>
+
+// Good
+<button type="button" onClick={handleClick}>
+  Click me
+</button>
+```
+
+### Accessible Icon Button
+
+```tsx
+// Bad
+<button><Icon /></button>
+
+// Good
+<button aria-label="Close dialog">
+  <Icon aria-hidden="true" />
+</button>
+```
+
+### Form with Error
+
+```tsx
+<label htmlFor="email">Email</label>
+<input
+  id="email"
+  aria-describedby="email-error"
+  aria-invalid={hasError}
+/>
+{hasError && (
+  <span id="email-error" role="alert">
+    Please enter a valid email
+  </span>
+)}
+```
+
+## Report Template
+
+```markdown
+# Accessibility Audit Report
+
+**Date:** [Date]
+**Page:** [Name]
+**WCAG Level:** AA
+
+## Summary
+
+- Critical Issues: X
+- Major Issues: X
+- Minor Issues: X
+
+## Issues
+
+### [Issue Title]
+
+- **Severity:** Critical/Major/Minor
+- **WCAG:** [X.X.X]
+- **Element:** [selector]
+- **Issue:** [Description]
+- **Fix:** [Recommendation]
+```
+
+## Storage
+
+Save audit reports to `.opencode/memory/design/accessibility/`
+
+## Related Skills
+
+| Need           | Skill             |
+| -------------- | ----------------- |
+| Design quality | `frontend-design` |
+| UI research    | `ui-ux-research`  |

package/dist/template/.opencode/skill/agent-evals/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: agent-evals
+description: Use when adding/changing a skill, command, or agent prompt and you want evidence it actually helps — not just intuition. Defines bounded-task evals, no-skill baselines, deterministic verifiers, JSONL trace logs, and when to skip eval. Adapted from OpenAI eval guide, OpenHands "evaluating agent skills", Anthropic "demystifying evals".
+---
+
+# Agent Evals
+
+> Without evals, every skill ships on vibes. The harness-engineering literature is unanimous: **measured changes beat believed-changes**. This skill gives you the smallest workable eval loop.
+
+## When to Use
+
+Run an eval when:
+
+- Adding a new skill that claims to improve outcomes (`anti-ai-slop`, `prompt-leverage`, `condition-based-waiting`)
+- Changing a prompt or instruction in an agent (`build`, `plan`, `review`)
+- Comparing two approaches and you don't know which is better
+- A skill is suspected of being inert ("does this even do anything?")
+
+**Skip eval when:**
+
+- The change is mechanical (rename, refactor, lint fix)
+- The change is a one-shot fix with obvious verification (test passes / build green)
+- The skill is purely procedural with deterministic output (workspace setup)
+
+## Core Principle: Bounded + Baseline + Verifier
+
+Three ingredients. Skip any one and the eval is theatre.
+
+1. **Bounded task** — a concrete prompt with a definite finish line, runnable in <5 minutes
+2. **No-skill baseline** — the same task run **without** the skill loaded, for comparison
+3. **Deterministic verifier** — a check that returns pass/fail without human judgment
+
+If you cannot write the verifier, the skill's value is unmeasurable and you are guessing.
+
+## Eval Loop (Minimum Viable)
+
+### Step 1: Define the task
+
+Pick a real failure mode the skill targets. One paragraph, copy-pastable as a prompt.
+
+```markdown
+## Task: anti-ai-slop / no-purple-gradient
+
+**Prompt:** "Build a landing page hero for a coffee roastery brand. Single HTML file."
+
+**Verifier (deterministic):**
+
+- grep output for `linear-gradient.*purple|#[89a]\d[0-9a-f]\d{3}` → must return 0 matches
+- grep output for `Inter|Roboto` in `font-family` → must return 0 matches
+- File contains `<h1>` with content → must be true
+
+**Pass criteria:** all 3 checks pass
+```
+
+### Step 2: Run baseline (no skill)
+
+Fresh subagent, **don't load the skill**. Same prompt. Save output.
+
+```typescript
+task({
+  subagent_type: "general",
+  description: "Baseline: coffee landing page",
+  prompt:
+    "Build a landing page hero for a coffee roastery brand. Single HTML file. Output the full HTML only.",
+});
+```
+
+Save result to `.beads/artifacts/<eval-id>/baseline.html`.
+
+### Step 3: Run treatment (with skill)
+
+Fresh subagent, **load the skill explicitly** in prompt. Same task.
+
+```typescript
+task({
+  subagent_type: "general",
+  description: "Treatment: coffee landing page",
+  prompt: `First load the anti-ai-slop skill. Then: Build a landing page hero for a coffee roastery brand. Single HTML file. Output the full HTML only.`,
+});
+```
+
+Save result to `.beads/artifacts/<eval-id>/treatment.html`.
+
+### Step 4: Run verifier on both
+
+```bash
+# Baseline
+grep -cE "linear-gradient.*purple|#[89a][0-9a-f]" baseline.html
+grep -cE "(Inter|Roboto)" baseline.html
+
+# Treatment
+grep -cE "linear-gradient.*purple|#[89a][0-9a-f]" treatment.html
+grep -cE "(Inter|Roboto)" treatment.html
+```
+
+### Step 5: Record result
+
+Append one JSONL line to `.opencode/evals/log.jsonl`:
+
+```json
+{
+  "eval_id": "anti-slop-001",
+  "skill": "anti-ai-slop",
+  "date": "2026-04-21",
+  "baseline_pass": false,
+  "treatment_pass": true,
+  "delta": "+1",
+  "notes": "baseline used purple gradient + Inter; treatment used warm browns + Source Serif"
+}
+```
+
+## Multi-Run for Confidence
+
+A single run can be lucky. For a skill you're seriously evaluating:
+
+- Run baseline **3 times**, treatment **3 times** (different seeds via different prompts framings)
+- Report pass-rate not single result: `baseline 1/3, treatment 3/3`
+- If treatment ≤ baseline, the skill is **inert or harmful** — fix or delete
+
+## Verifier Patterns That Work
+
+| Skill type             | Verifier                                                          |
+| ---------------------- | ----------------------------------------------------------------- |
+| Anti-pattern avoidance | `grep` for the banned pattern → expect 0                          |
+| Required output shape  | JSON schema validation, presence of required sections             |
+| Code correctness       | run the code, run its tests, check exit code                      |
+| Behavior change        | call site count via `tilth_search`, file existence, line counts   |
+| UI / visual            | Playwright screenshot + pixel diff against expected, or DOM query |
+| Refusal / safety       | grep for forbidden phrases or correct refusal pattern             |
+
+## Verifier Anti-Patterns (Don't Use)
+
+- "Ask another LLM if this is good" — non-deterministic, expensive, judgment-laden
+- "Check if it looks right" — not a verifier, that's a vibe
+- "Pass if no errors thrown" — too weak, baseline also passes
+- "Manually inspect" — fine for one-off, useless for regression
+
+## Trace Logging Format
+
+For multi-step evals (agent ran 5 tool calls, made 3 edits), log the trace:
+
+```json
+{
+  "eval_id": "ship-flow-002",
+  "steps": [
+    { "tool": "task", "args": { "subagent_type": "explore" }, "ok": true },
+    { "tool": "edit", "args": { "path": "src/auth.ts" }, "ok": true },
+    { "tool": "bash", "args": { "command": "npm test" }, "ok": false, "exit_code": 1 }
+  ],
+  "outcome": "failed_at_step_3",
+  "verifier_pass": false
+}
+```
+
+This lets you find **which step** failed across many runs — surfaces flaky points in a workflow.
+
+## When Eval Disagrees with Intuition
+
+The skill **feels** great but the eval says baseline ≥ treatment. Trust the eval. Common causes:
+
+1. The skill is too long — the agent ignored it
+2. The skill targets a problem the model already handles
+3. The verifier doesn't measure what the skill actually changes (re-read your verifier)
+4. The baseline prompt was too easy (try a harder task)
+
+Fix in this order: verifier → task difficulty → skill content. Delete the skill if all three fail.
+
+## Eval Storage Convention
+
+```
+.opencode/evals/
+├── log.jsonl                    # append-only, one line per run
+├── tasks/                       # task definitions
+│   ├── anti-slop-001.md
+│   └── ship-flow-002.md
+└── artifacts/                   # baseline.* and treatment.* outputs
+    └── <eval_id>/
+```
+
+Keep evals in-repo. They're documentation that the skill works.
+
+## Integration with `/health` and `/curate`
+
+- `/health` should flag skills with **zero eval coverage** as IMPORTANT (not CRITICAL — many skills are simple enough not to need it)
+- `/curate` should surface eval results when proposing skill consolidation: "skill X has 0/5 passes over last 3 months, propose deletion"
+
+## Cost Discipline
+
+- Each eval run = 1 subagent call. 6 runs (3 baseline + 3 treatment) = 6 calls.
+- Don't eval every skill. Eval the ones whose **value is contested** or whose **failure would be expensive**.
+- Cache baseline runs — re-run only when the underlying model changes.
+
+## Output
+
+After running an eval, return:
+
+```markdown
+## Eval: <skill-name>
+
+- **Task:** [one line]
+- **Baseline:** N/M passes
+- **Treatment:** N/M passes
+- **Delta:** [+/-N]
+- **Verdict:** keep | iterate | delete
+- **Trace:** `.opencode/evals/log.jsonl` line <N>
+```
+
+Brief. Evidence-based. No padding.

package/dist/template/.opencode/skill/agent-teams/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: agent-teams
+description: >
+  Use when working with Claude Code-style agent teams for parallel research, review, competing hypotheses,
+  or any task that benefits from multiple agents working simultaneously under a lead coordinator.
+  Covers team configuration, task distribution, coordination patterns, and best practices.
+version: "1.0.0"
+license: MIT
+tags: [agent-coordination, workflow]
+dependencies: []
+---
+
+# Agent Teams - Multi-Agent Team Coordination
+
+> **Replaces** single-agent sequential work when tasks benefit from parallel research, review, or competing hypotheses
+
+## When to Use
+
+- Parallel research, review, or competing approaches that need coordination
+- Tasks benefit from shared findings and a lead coordinating teammates
+
+## When NOT to Use
+
+- Single-agent tasks or tightly coupled edits where coordination overhead is wasteful
+- Simple parallel work that can use fire-and-forget subagents instead
+
+## Overview
+
+**Agent Teams = Lead + Teammates + Shared Task List + Messaging**
+
+- **Lead agent**: Coordinates the team - distributes tasks, monitors progress, synthesizes results
+- **Teammates**: Execute tasks independently but can message each other and the lead
+- **Task list**: Shared work queue that the lead manages
+- **Messaging**: Bidirectional communication between lead and teammates
+
+## When to Use Agent Teams vs Subagents
+
+| Criteria              | Agent Teams                            | Subagents (Task tool)               |
+| --------------------- | -------------------------------------- | ----------------------------------- |
+| **Coordination**      | Lead coordinates, teammates message    | Fire-and-forget, results return     |
+| **Communication**     | Bidirectional messaging                | One-way (result only)               |
+| **Task reassignment** | Dynamic - lead can reassign            | Fixed - each subagent does its task |
+| **Context sharing**   | Shared through lead                    | Independent contexts                |
+| **Best for**          | Research, review, competing approaches | Independent implementation tasks    |
+| **Overhead**          | Higher - coordination cost             | Lower - no coordination             |
+
+### Decision Matrix
+
+```
+Need coordination between workers?  → Agent Teams
+Workers are fully independent?      → Subagents (Task tool)
+Need competing hypotheses?          → Agent Teams
+Need shared findings?               → Agent Teams
+Simple parallel execution?          → Subagents (Task tool)
+```
+
+### Parallel Skill Selection
+
+| Scenario                                    | Use This Skill              |
+| ------------------------------------------- | --------------------------- |
+| 3+ independent bug investigations           | dispatching-parallel-agents |
+| Coordinated team (research + review + impl) | agent-teams                 |
+| Large plan with dependency graph            | swarm-coordination          |
+| 2 independent tasks                         | Just use 2 Task() calls     |
+
+## When to Use
+
+- **Parallel research**: Multiple agents researching different aspects of a problem
+- **Code review**: Multiple reviewers examining different files/concerns
+- **Competing hypotheses**: Agents try different approaches, best one wins
+- **Large refactors**: Agents handle different subsystems with coordination
+- **Architecture exploration**: Agents explore different design options simultaneously
+
+## When NOT to Use
+
+- Single-agent tasks (overhead not worth it)
+- Tightly coupled work where agents would constantly block each other
+- Tasks under 3 independent units of work
+- Simple file edits with no research needed
+
+## Team Configuration Patterns
+
+### Pattern 1: Research Team
+
+```
+Lead: build agent
+├── Teammate 1 (explore): Search codebase for existing patterns
+├── Teammate 2 (scout): Research external docs and best practices
+└── Teammate 3 (review): Analyze current implementation for issues
+```
+
+**Use when**: Entering unfamiliar territory, evaluating new libraries, understanding complex systems.
+
+### Pattern 2: Review Team
+
+```
+Lead: build agent
+├── Teammate 1 (review): Security audit
+├── Teammate 2 (review): Performance review
+└── Teammate 3 (review): Architecture review
+```
+
+**Use when**: Pre-merge review of significant features, security-sensitive changes.
+
+### Pattern 3: Competing Approaches
+
+```
+Lead: build agent
+├── Teammate 1 (general): Implement approach A
+├── Teammate 2 (general): Implement approach B
+└── Teammate 3 (general): Implement approach C
+```
+
+**Use when**: Multiple valid solutions exist and you need to compare empirically.
+
+### Pattern 4: Subsystem Team
+
+```
+Lead: build agent
+├── Teammate 1 (general): Handle frontend changes
+├── Teammate 2 (general): Handle backend changes
+└── Teammate 3 (general): Handle database migrations
+```
+
+**Use when**: Large features spanning multiple subsystems with clear boundaries.
+
+## Best Practices
+
+### Task Distribution
+
+1. **5-6 tasks per teammate maximum** - More than this degrades quality
+2. **Clear boundaries** - Each teammate should own distinct files/modules
+3. **Avoid file conflicts** - Never assign the same file to multiple teammates
+4. **Include verification** - Each task should include its own verification step
+
+### Coordination
+
+1. **Lead synthesizes** - Don't let teammates make final decisions; lead integrates
+2. **Regular check-ins** - Lead should review intermediate results, not just final
+3. **Fail fast** - If a teammate hits a blocker, escalate to lead immediately
+4. **Shared conventions** - Establish naming, formatting, and style before dispatching
+
+### Communication
+
+1. **Task descriptions should be self-contained** - Teammate shouldn't need to ask clarifying questions
+2. **Include context** - What files to read, what patterns to follow, what constraints exist
+3. **Specify output format** - What should the teammate report back?
+4. **Include acceptance criteria** - How does the lead know the task is done?
+
+## Implementation with OpenCode
+
+### Using the Task Tool (Current)
+
+```typescript
+// Spawn research team
+const codebaseAnalysis = Task({
+  subagent_type: "explore",
+  description: "Analyze auth patterns",
+  prompt: `Research authentication patterns in this codebase:
+    1. Find all auth-related files
+    2. Map the auth flow
+    3. Identify potential security issues
+    Report back: file list, flow diagram, issues found`,
+});
+
+const externalResearch = Task({
+  subagent_type: "scout",
+  description: "Research JWT best practices",
+  prompt: `Research current JWT best practices:
+    1. Token rotation patterns
+    2. Refresh token security
+    3. Common vulnerabilities
+    Report back: recommended patterns with code examples`,
+});
+
+const codeReview = Task({
+  subagent_type: "review",
+  description: "Review auth security",
+  prompt: `Security review of auth implementation:
+    1. Check token storage
+    2. Verify CSRF protection
+    3. Audit session management
+    Report back: vulnerabilities found with severity ratings`,
+});
+
+// Lead synthesizes all results into unified recommendation
+```
+
+### Using Swarm Coordination (Advanced)
+
+For more structured parallel work, combine with the `swarm-coordination` skill:
+
+```typescript
+// Load swarm for structured coordination
+skill({ name: "swarm-coordination" });
+
+// Analyze and plan
+swarm({ op: "plan", task: "Implement auth overhaul across 3 subsystems" });
+
+// Create delegation packets
+swarm({
+  op: "delegate",
+  bead_id: "auth-frontend",
+  title: "Frontend auth components",
+  outcome: "All auth forms and guards updated",
+  must_do: "Follow existing component patterns, run component tests",
+  must_not: "Don't modify API contracts, don't add new dependencies",
+});
+```
+
+## Anti-Patterns
+
+### ❌ Too Many Teammates
+
+```
+Lead
+├── T1: Button component     ← Too granular
+├── T2: Input component      ← Too granular
+├── T3: Form component       ← Too granular
+├── T4: Modal component      ← Too granular
+├── T5: Toast component      ← Too granular
+├── T6: Dialog component     ← Too granular
+├── T7: Dropdown component   ← Too granular
+└── T8: Tabs component       ← Too granular
+```
+
+**Fix**: Group related work. 2-3 teammates handling related components each.
+
+### ❌ Overlapping File Ownership
+
+```
+T1: Refactor auth service     ← Both touch auth.ts!
+T2: Add new auth endpoint     ← Both touch auth.ts!
+```
+
+**Fix**: One teammate owns auth.ts changes. The other waits or works on different files.
+
+### ❌ Missing Context
+
+```
+Task({ prompt: "Fix the auth bug" })  ← Which bug? What file? What behavior?
+```
+
+**Fix**: Include file paths, error messages, expected vs actual behavior, and reproduction steps.
+
+### ❌ No Verification
+
+```
+Task({ prompt: "Implement feature X" })  ← No way to verify success
+```
+
+**Fix**: Include acceptance criteria: "Run `npm test auth`, ensure all pass. Run `npm run typecheck`."
+
+## Checklist
+
+Before dispatching a team:
+
+- [ ] Identified 3+ independent tasks (otherwise use single agent)
+- [ ] Each task has clear file ownership (no overlaps)
+- [ ] Each task has self-contained context (files, patterns, constraints)
+- [ ] Each task has acceptance criteria (verification commands)
+- [ ] Lead has a synthesis plan (how to integrate results)
+- [ ] Tasks are sized appropriately (5-6 per teammate max)
+
+## See Also
+
+- `dispatching-parallel-agents` — for independent debugging-focused parallel investigations
+- `swarm-coordination` — for dependency-aware large-plan execution