opencode-starterkit 1.0.1

package/baseline/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

package/baseline/skill/frontend-design/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces. Use when building web components, pages, or applications with React-based frameworks. Includes Tailwind CSS v4, shadcn/ui components, Motion animations, and visual design philosophy for avoiding generic AI aesthetics.
+version: 1.1.0
+tags: [ui, design]
+dependencies: []
+---
+
+# Frontend Design
+
+## When to Use
+
+- Building UI with React frameworks (Next.js, Vite, Remix)
+- Creating visually distinctive, memorable interfaces
+- Implementing accessible components with shadcn/ui
+- Styling with Tailwind CSS v4
+- Adding animations and micro-interactions
+- Creating visual designs, posters, brand materials
+
+## When NOT to Use
+
+- Backend-only tasks or minimal UI with no visual design requirements.
+
+## Reference Documentation
+
+### Tailwind CSS v4.1
+
+- `./references/tailwind/v4-config.md` - Installation, @theme, CSS-first config
+- `./references/tailwind/v4-features.md` - Container queries, gradients, masks, text shadows
+- `./references/tailwind/utilities-layout.md` - Display, flex, grid, position
+- `./references/tailwind/utilities-styling.md` - Spacing, typography, colors, borders
+- `./references/tailwind/responsive.md` - Breakpoints, mobile-first, container queries
+
+Search: `@theme`, `@container`, `OKLCH`, `mask-`, `text-shadow`
+
+### shadcn/ui (CLI v3.6)
+
+- `./references/shadcn/setup.md` - Installation, visual styles, component list
+- `./references/shadcn/core-components.md` - Button, Card, Dialog, Select, Tabs, Toast
+- `./references/shadcn/form-components.md` - Form, Field, Input Group, 2026 components
+- `./references/shadcn/theming.md` - CSS variables, OKLCH, dark mode
+- `./references/shadcn/accessibility.md` - ARIA, keyboard, screen reader
+
+Search: `Field`, `InputGroup`, `Spinner`, `ButtonGroup`, `next-themes`
+
+### Animation (Motion + Tailwind)
+
+- `./references/animation/motion-core.md` - Timing system, easing constants, performance rules, reduced motion, core patterns
+- `./references/animation/motion-advanced.md` - AnimatePresence, scroll, orchestration, TypeScript
+
+**Stack**:
+| Animation Type | Tool |
+|----------------|------|
+| Hover/transitions | Tailwind CSS (`transition-*`) |
+| shadcn states | `tailwindcss-animate` (built-in) |
+| Gestures/layout/exit | Motion (`motion/react`) |
+| Complex SVG morphing | anime.js v4 (niche only) |
+
+### Visual Design
+
+- `./references/canvas/philosophy.md` - Design movements, core principles
+- `./references/canvas/execution.md` - Multi-page systems, quality standards
+
+For sophisticated compositions: posters, brand materials, design systems.
+
+### Design Systems (Deep Guides)
+
+- `./references/design/color-system.md` - OKLCH, semantic tokens, dark mode architecture
+- `./references/design/typography-rules.md` - Fluid type, modular scale, OpenType features
+- `./references/design/interaction.md` - State models, focus, dialogs/popovers, loading patterns
+- `./references/design/ux-writing.md` - Button copy, error structure, empty states, i18n
+
+Search: `AI Slop Test`, `tinted neutrals`, `focus-visible`, `verb + object`, `65ch`
+
+## Design Thinking
+
+Before coding, commit to BOLD aesthetic direction:
+
+- **Purpose**: What problem? Who uses it?
+- **Tone**: Pick extreme - brutally minimal, maximalist chaos, retro-futuristic, organic, luxury, playful, editorial, brutalist, art deco, soft/pastel, industrial
+- **Differentiation**: What makes this UNFORGETTABLE?
+
+Bold maximalism and refined minimalism both work. Key is intentionality.
+
+## Anti-Patterns (AI Fingerprints — NEVER)
+
+These patterns immediately signal "AI made this." Avoid them all.
+
+### Typography
+
+- **Banned fonts**: Inter, Roboto, Arial, Open Sans, Lato, Montserrat, Space Grotesk, system-ui as display font
+- Monospace used as "developer aesthetic" shorthand
+- Big icons centered above every heading
+- Using `px` for body text (use `rem`/`em` to respect user settings)
+
+### Color
+
+- **AI palette**: Cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds
+- Gray text on colored backgrounds (use darker shade of background color instead)
+- Pure `#000` or `#fff` (always tint — pure black/white don't exist in nature)
+- Gradient text on headings or metrics
+- `rgba()` / heavy alpha transparency as primary palette (design smell — define explicit colors)
+
+### Layout
+
+- Cards nested inside cards (use typography, spacing, dividers for hierarchy within a card)
+- Identical card grids (icon + heading + text repeated 3-6 times)
+- Hero metric template (big number + small label + gradient accent)
+- Center-aligning everything
+- Same spacing everywhere (no visual rhythm)
+
+### Visual
+
+- Glassmorphism used decoratively (blur cards, glow borders)
+- Thick colored border on one side of rounded rectangles
+- Sparklines as decoration (not connected to real data)
+- Generic drop shadows on everything
+- Rounded rectangles as the only shape language
+
+### Motion
+
+- Bounce or elastic easing (real objects decelerate smoothly)
+- Animating `height`, `width`, `padding`, `margin` (causes layout recalculation)
+- Default `ease` (compromise that's rarely optimal — use exponential easing)
+- Missing `prefers-reduced-motion` handling
+
+> **The AI Slop Test**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.
+
+## Best Practices
+
+1. **Accessibility First**: Radix primitives, `:focus-visible` (not `:focus`), semantic HTML, 44px touch targets
+2. **Mobile-First**: Start mobile, layer responsive variants with `min-width` queries
+3. **Design Tokens**: Two-layer system — primitives (`--blue-500`) + semantic (`--color-primary: var(--blue-500)`); dark mode redefines semantic layer only
+4. **Dark Mode**: Not inverted light mode — lighter surfaces create depth (no shadows); desaturate accents; base at `oklch(15-18% …)`
+5. **Container Queries**: Use `@container` for component layout, viewport queries for page layout
+6. **Performance**: `transform` + `opacity` only for animations; CSS purging; avoid dynamic class names
+7. **TypeScript**: Full type safety
+8. **Expert Craftsmanship**: Every detail matters — squint test for hierarchy validation
+
+## Core Stack Summary
+
+**Tailwind v4.1**: CSS-first config via `@theme`. Single `@import "tailwindcss"`. OKLCH colors. Container queries built-in.
+
+**shadcn/ui v3.6**: Copy-paste Radix components. Visual styles: Vega/Nova/Maia/Lyra/Mira. New: Field, InputGroup, Spinner, ButtonGroup.
+
+**Motion**: `import { motion, AnimatePresence } from 'motion/react'`. Declarative React animations. Use `tailwindcss-animate` for shadcn states.
+
+## Typography
+
+→ Consult `./references/design/typography-rules.md` for full fluid type system
+
+Choose distinctive fonts. Pair display with body:
+
+- **Preferred**: Instrument Sans, Plus Jakarta Sans, Outfit, Onest, Figtree, Urbanist (sans); Fraunces, Newsreader (editorial)
+- **Fluid sizing**: `clamp(1rem, 0.5rem + 2vw, 1.5rem)` — never fixed `px` for body
+- **Modular scale**: Pick one ratio (1.25 major third, 1.333 perfect fourth) — 5 sizes max
+- **Measure**: `max-width: 65ch` for body text
+- **OpenType**: `tabular-nums` for data, `diagonal-fractions` for recipes, `all-small-caps` for abbreviations
+
+```css
+@theme {
+  --font-display: "Fraunces", serif;
+  --font-body: "Instrument Sans", sans-serif;
+}
+```
+
+## Color
+
+→ Consult `./references/design/color-system.md` for OKLCH deep guide
+
+Use OKLCH for perceptually uniform colors. Two-layer token system:
+
+```css
+@theme {
+  /* Primitives */
+  --blue-500: oklch(0.55 0.22 264);
+  --amber-400: oklch(0.75 0.18 80);
+  /* Semantic (redefine these for dark mode) */
+  --color-primary: var(--blue-500);
+  --color-accent: var(--amber-400);
+  /* Tinted neutrals — chroma 0.01 for subconscious brand cohesion */
+  --color-surface: oklch(0.97 0.01 264);
+  --color-surface-dark: oklch(0.16 0.01 264);
+}
+```
+
+## Motion
+
+→ Consult `./references/animation/motion-core.md` for Motion API
+
+**Timing**: 100-150ms instant feedback | 200-300ms state changes | 300-500ms layout | exit = 75% of enter
+
+**Easing**: Exponential only — `cubic-bezier(0.16, 1, 0.3, 1)` for entrances. Never `ease`, never bounce/elastic.
+
+**Performance**: Only animate `transform` and `opacity`. Height expand → `grid-template-rows: 0fr → 1fr`.
+
+**Accessibility**: `prefers-reduced-motion` is mandatory (affects ~35% of adults over 40). Swap spatial animations for crossfades.
+
+```tsx
+import { motion, AnimatePresence } from 'motion/react';
+
+<motion.div initial={{ opacity: 0, y: 12 }} animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.3, ease: [0.16, 1, 0.3, 1] }} />
+
+<AnimatePresence>
+  {show && <motion.div exit={{ opacity: 0 }} transition={{ duration: 0.2 }} />}
+</AnimatePresence>
+```
+
+CSS stagger: `animation-delay: calc(var(--i, 0) * 50ms)` — cap total at 500ms.
+
+## Spatial Composition
+
+- **4pt spacing system**: 4, 8, 12, 16, 24, 32, 48, 64, 96px — not 8pt (too coarse at small gaps)
+- **`gap` over margins** for sibling spacing (eliminates margin collapse)
+- **Self-adjusting grids**: `repeat(auto-fit, minmax(280px, 1fr))` — responsive without breakpoints
+- **Container queries** for components: `container-type: inline-size` on wrapper, `@container` on children
+- **Optical text alignment**: `margin-left: -0.05em` for text that appears indented due to letterform whitespace
+- Asymmetry, overlap, diagonal flow, grid-breaking elements. Generous negative space OR controlled density.
+
+## Interaction
+
+→ Consult `./references/design/interaction.md`
+
+Design all 8 states: Default, Hover, Focus, Active, Disabled, Loading, Error, Success. Use `:focus-visible` not `:focus`. Native `<dialog>` + `inert` for modals. Popover API for tooltips/dropdowns. Skeleton screens over spinners. Undo over confirmation dialogs.
+
+## UX Writing
+
+→ Consult `./references/design/ux-writing.md`
+
+Button labels: specific verb + object ("Save changes" not "OK"). Error formula: What happened + Why + How to fix. Empty states are onboarding opportunities. Plan for 30% text expansion (i18n).
+
+## Backgrounds
+
+Create atmosphere: gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, grain overlays.