@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/redesign-existing-projects/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: redesign-existing-projects
+description: Use when upgrading an existing website or app's visual design to premium quality. Audits current design, identifies generic AI patterns, applies high-end standards without breaking functionality. MUST load before any design overhaul of existing projects.
+---
+
+## When to Use
+
+- When upgrading an existing website or app's visual design to premium quality
+- Before any design overhaul of existing projects
+- When the current design has been identified as generic, template-looking, or AI-default
+
+## When NOT to Use
+
+- For greenfield projects (use frontend-design with an aesthetic overlay instead)
+- When the design is already polished and only minor tweaks are needed
+- For non-visual changes (performance, accessibility-only fixes)
+
+
+# Redesign Skill
+
+## How This Works
+
+When applied to an existing project, follow this sequence:
+
+1. **Scan** — Read the codebase. Identify the framework, styling method (Tailwind, vanilla CSS, styled-components, etc.), and current design patterns.
+2. **Diagnose** — Run through the audit below. List every generic pattern, weak point, and missing state you find.
+3. **Fix** — Apply targeted upgrades working with the existing stack. Do not rewrite from scratch. Improve what's there.
+
+## Design Audit
+
+### Typography
+
+Check for these problems and fix them:
+
+- **Browser default fonts or Inter everywhere.** Replace with a font that has character. Good options: `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`. For editorial/creative projects, pair a serif header with a sans-serif body.
+- **Headlines lack presence.** Increase size for display text, tighten letter-spacing, reduce line-height. Headlines should feel heavy and intentional.
+- **Body text too wide.** Limit paragraph width to roughly 65 characters. Increase line-height for readability.
+- **Only Regular (400) and Bold (700) weights used.** Introduce Medium (500) and SemiBold (600) for more subtle hierarchy.
+- **Numbers in proportional font.** Use a monospace font or enable tabular figures (`font-variant-numeric: tabular-nums`) for data-heavy interfaces.
+- **Missing letter-spacing adjustments.** Use negative tracking for large headers, positive tracking for small caps or labels.
+- **All-caps subheaders everywhere.** Try lowercase italics, sentence case, or small-caps instead.
+- **Orphaned words.** Single words sitting alone on the last line. Fix with `text-wrap: balance` or `text-wrap: pretty`.
+
+### Color and Surfaces
+
+- **Pure `#000000` background.** Replace with off-black, dark charcoal, or tinted dark (`#0a0a0a`, `#121212`, or a dark navy).
+- **Oversaturated accent colors.** Keep saturation below 80%. Desaturate accents so they blend with neutrals instead of screaming.
+- **More than one accent color.** Pick one. Remove the rest. Consistency beats variety.
+- **Mixing warm and cool grays.** Stick to one gray family. Tint all grays with a consistent hue (warm or cool, not both).
+- **Purple/blue "AI gradient" aesthetic.** This is the most common AI design fingerprint. Replace with neutral bases and a single, considered accent.
+- **Generic `box-shadow`.** Tint shadows to match the background hue. Use colored shadows (e.g., dark blue shadow on a blue background) instead of pure black at low opacity.
+- **Flat design with zero texture.** Add subtle noise, grain, or micro-patterns to backgrounds. Pure flat vectors feel sterile.
+- **Perfectly even gradients.** Break the uniformity with radial gradients, noise overlays, or mesh gradients instead of standard linear 45-degree fades.
+- **Inconsistent lighting direction.** Audit all shadows to ensure they suggest a single, consistent light source.
+- **Random dark sections in a light mode page (or vice versa).** A single dark-background section breaking an otherwise light page looks like a copy-paste accident. Either commit to a full dark mode or keep a consistent background tone throughout. If contrast is needed, use a slightly darker shade of the same palette — not a sudden jump to `#111` in the middle of a cream page.
+- **Empty, flat sections with no visual depth.** Sections that are just text on a plain background feel unfinished. Add high-quality background imagery (blurred, overlaid, or masked), subtle patterns, or ambient gradients. Use reliable placeholder sources like `https://picsum.photos/seed/{name}/1920/1080` when real assets are not available. Experiment with background images behind hero sections, feature blocks, or CTAs — even a subtle full-width photo at low opacity adds presence.
+
+### Layout
+
+- **Everything centered and symmetrical.** Break symmetry with offset margins, mixed aspect ratios, or left-aligned headers over centered content.
+- **Three equal card columns as feature row.** This is the most generic AI layout. Replace with a 2-column zig-zag, asymmetric grid, horizontal scroll, or masonry layout.
+- **Using `height: 100vh` for full-screen sections.** Replace with `min-height: 100dvh` to prevent layout jumping on mobile browsers (iOS Safari viewport bug).
+- **Complex flexbox percentage math.** Replace with CSS Grid for reliable multi-column structures.
+- **No max-width container.** Add a container constraint (around 1200-1440px) with auto margins so content doesn't stretch edge-to-edge on wide screens.
+- **Cards of equal height forced by flexbox.** Allow variable heights or use masonry when content varies in length.
+- **Uniform border-radius on everything.** Vary the radius: tighter on inner elements, softer on containers.
+- **No overlap or depth.** Elements sit flat next to each other. Use negative margins to create layering and visual depth.
+- **Symmetrical vertical padding.** Top and bottom padding are always identical. Adjust optically — bottom padding often needs to be slightly larger.
+- **Dashboard always has a left sidebar.** Try top navigation, a floating command menu, or a collapsible panel instead.
+- **Missing whitespace.** Double the spacing. Let the design breathe. Dense layouts work for data dashboards, not for marketing pages.
+- **Buttons not bottom-aligned in card groups.** When cards have different content lengths, CTAs end up at random heights. Pin buttons to the bottom of each card so they form a clean horizontal line regardless of content above.
+- **Feature lists starting at different vertical positions.** In pricing tables or comparison cards, the list of features should start at the same Y position across all columns. Use consistent spacing above the list or fixed-height title/price blocks.
+- **Inconsistent vertical rhythm in side-by-side elements.** When placing cards, columns, or panels next to each other, align shared elements (titles, descriptions, prices, buttons) across all items. Misaligned baselines make the layout look broken.
+- **Mathematical alignment that looks optically wrong.** Centering by the math doesn't always look centered to the eye. Icons next to text, play buttons in circles, or text in buttons often need 1-2px optical adjustments to feel right.
+
+### Interactivity and States
+
+- **No hover states on buttons.** Add background shift, slight scale, or translate on hover.
+- **No active/pressed feedback.** Add a subtle `scale(0.98)` or `translateY(1px)` on press to simulate a physical click.
+- **Instant transitions with zero duration.** Add smooth transitions (200-300ms) to all interactive elements.
+- **Missing focus ring.** Ensure visible focus indicators for keyboard navigation. This is an accessibility requirement, not optional.
+- **No loading states.** Replace generic circular spinners with skeleton loaders that match the layout shape.
+- **No empty states.** An empty dashboard showing nothing is a missed opportunity. Design a composed "getting started" view.
+- **No error states.** Add clear, inline error messages for forms. Do not use `window.alert()`.
+- **Dead links.** Buttons that link to `#`. Either link to real destinations or visually disable them.
+- **No indication of current page in navigation.** Style the active nav link differently so users know where they are.
+- **Scroll jumping.** Anchor clicks jump instantly. Add `scroll-behavior: smooth`.
+- **Animations using `top`, `left`, `width`, `height`.** Switch to `transform` and `opacity` for GPU-accelerated, smooth animation.
+
+### Content
+
+- **Generic names like "John Doe" or "Jane Smith".** Use diverse, realistic-sounding names.
+- **Fake round numbers like `99.99%`, `50%`, `$100.00`.** Use organic, messy data: `47.2%`, `$99.00`, `+1 (312) 847-1928`.
+- **Placeholder company names like "Acme Corp", "Nexus", "SmartFlow".** Invent contextual, believable brand names.
+- **AI copywriting cliches.** Never use "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve", "Tapestry", or "In the world of...". Write plain, specific language.
+- **Exclamation marks in success messages.** Remove them. Be confident, not loud.
+- **"Oops!" error messages.** Be direct: "Connection failed. Please try again."
+- **Passive voice.** Use active voice: "We couldn't save your changes" instead of "Mistakes were made."
+- **All blog post dates identical.** Randomize dates to appear real.
+- **Same avatar image for multiple users.** Use unique assets for every distinct person.
+- **Lorem Ipsum.** Never use placeholder latin text. Write real draft copy.
+- **Title Case On Every Header.** Use sentence case instead.
+
+### Component Patterns
+
+- **Generic card look (border + shadow + white background).** Remove the border, or use only background color, or use only spacing. Cards should exist only when elevation communicates hierarchy.
+- **Always one filled button + one ghost button.** Add text links or tertiary styles to reduce visual noise.
+- **Pill-shaped "New" and "Beta" badges.** Try square badges, flags, or plain text labels.
+- **Accordion FAQ sections.** Use a side-by-side list, searchable help, or inline progressive disclosure.
+- **3-card carousel testimonials with dots.** Replace with a masonry wall, embedded social posts, or a single rotating quote.
+- **Pricing table with 3 towers.** Highlight the recommended tier with color and emphasis, not just extra height.
+- **Modals for everything.** Use inline editing, slide-over panels, or expandable sections instead of popups for simple actions.
+- **Avatar circles exclusively.** Try squircles or rounded squares for a less generic look.
+- **Light/dark toggle always a sun/moon switch.** Use a dropdown, system preference detection, or integrate it into settings.
+- **Footer link farm with 4 columns.** Simplify. Focus on main navigational paths and legally required links.
+
+### Iconography
+
+- **Lucide or Feather icons exclusively.** These are the "default" AI icon choice. Use Phosphor, Heroicons, or a custom set for differentiation.
+- **Rocketship for "Launch", shield for "Security".** Replace cliche metaphors with less obvious icons (bolt, fingerprint, spark, vault).
+- **Inconsistent stroke widths across icons.** Audit all icons and standardize to one stroke weight.
+- **Missing favicon.** Always include a branded favicon.
+- **Stock "diverse team" photos.** Use real team photos, candid shots, or a consistent illustration style instead of uncanny stock imagery.
+
+### Code Quality
+
+- **Div soup.** Use semantic HTML: `<nav>`, `<main>`, `<article>`, `<aside>`, `<section>`.
+- **Inline styles mixed with CSS classes.** Move all styling to the project's styling system.
+- **Hardcoded pixel widths.** Use relative units (`%`, `rem`, `em`, `max-width`) for flexible layouts.
+- **Missing alt text on images.** Describe image content for screen readers. Never leave `alt=""` or `alt="image"` on meaningful images.
+- **Arbitrary z-index values like `9999`.** Establish a clean z-index scale in the theme/variables.
+- **Commented-out dead code.** Remove all debug artifacts before shipping.
+- **Import hallucinations.** Check that every import actually exists in `package.json` or the project dependencies.
+- **Missing meta tags.** Add proper `<title>`, `description`, `og:image`, and social sharing meta tags.
+
+### Strategic Omissions (What AI Typically Forgets)
+
+- **No legal links.** Add privacy policy and terms of service links in the footer.
+- **No "back" navigation.** Dead ends in user flows. Every page needs a way back.
+- **No custom 404 page.** Design a helpful, branded "page not found" experience.
+- **No form validation.** Add client-side validation for emails, required fields, and format checks.
+- **No "skip to content" link.** Essential for keyboard users. Add a hidden skip-link.
+- **No cookie consent.** If required by jurisdiction, add a compliant consent banner.
+
+## Upgrade Techniques
+
+When upgrading a project, pull from these high-impact techniques to replace generic patterns:
+
+### Typography Upgrades
+- **Variable font animation.** Interpolate weight or width on scroll or hover for text that feels alive.
+- **Outlined-to-fill transitions.** Text starts as a stroke outline and fills with color on scroll entry or interaction.
+- **Text mask reveals.** Large typography acting as a window to video or animated imagery behind it.
+
+### Layout Upgrades
+- **Broken grid / asymmetry.** Elements that deliberately ignore column structure — overlapping, bleeding off-screen, or offset with calculated randomness.
+- **Whitespace maximization.** Aggressive use of negative space to force focus on a single element.
+- **Parallax card stacks.** Sections that stick and physically stack over each other during scroll.
+- **Split-screen scroll.** Two halves of the screen sliding in opposite directions.
+
+### Motion Upgrades
+- **Smooth scroll with inertia.** Decouple scrolling from browser defaults for a heavier, cinematic feel.
+- **Staggered entry.** Elements cascade in with slight delays, combining Y-axis translation with opacity fade. Never mount everything at once.
+- **Spring physics.** Replace linear easing with spring-based motion for a natural, weighty feel on all interactive elements.
+- **Scroll-driven reveals.** Content entering through expanding masks, wipes, or draw-on SVG paths tied to scroll progress.
+
+### Surface Upgrades
+- **True glassmorphism.** Go beyond `backdrop-filter: blur`. Add a 1px inner border and a subtle inner shadow to simulate edge refraction.
+- **Spotlight borders.** Card borders that illuminate dynamically under the cursor.
+- **Grain and noise overlays.** A fixed, pointer-events-none overlay with subtle noise to break digital flatness.
+- **Colored, tinted shadows.** Shadows that carry the hue of the background rather than using generic black.
+
+## Fix Priority
+
+Apply changes in this order for maximum visual impact with minimum risk:
+
+1. **Font swap** — biggest instant improvement, lowest risk
+2. **Color palette cleanup** — remove clashing or oversaturated colors
+3. **Hover and active states** — makes the interface feel alive
+4. **Layout and spacing** — proper grid, max-width, consistent padding
+5. **Replace generic components** — swap cliche patterns for modern alternatives
+6. **Add loading, empty, and error states** — makes it feel finished
+7. **Polish typography scale and spacing** — the premium final touch
+
+## Rules
+
+- Work with the existing tech stack. Do not migrate frameworks or styling libraries.
+- Do not break existing functionality. Test after every change.
+- Before importing any new library, check the project's dependency file first.
+- If the project uses Tailwind, check the version (v3 vs v4) before modifying config.
+- If the project has no framework, use vanilla CSS.
+- Keep changes reviewable and focused. Small, targeted improvements over big rewrites.

package/dist/template/.opencode/skill/reflection-checkpoints/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: reflection-checkpoints
+description: >
+  Use when executing long-running commands (/ship, /lfg) to add self-assessment
+  checkpoints that detect scope drift, stalled progress, and premature completion claims.
+  Inspired by ByteRover's reflection prompt architecture.
+version: 1.0.0
+tags: [workflow, quality, autonomous]
+dependencies: [verification-before-completion]
+---
+
+# Reflection Checkpoints
+
+## When to Use
+
+- During `/ship` execution after completing 50%+ of tasks
+- During `/lfg` at each phase transition (Plan→Work→Review→Compound)
+- When a task takes significantly longer than estimated
+- When context usage exceeds 60% of budget
+
+## When NOT to Use
+
+- Simple, single-task work (< 3 tasks)
+- Pure research or exploration commands
+- When user explicitly requests fast execution without checkpoints
+
+## Overview
+
+Long-running autonomous execution drifts silently. By the time you notice, you've burned context on the wrong thing. Reflection checkpoints force self-assessment at critical moments — catching drift before it compounds.
+
+**Core principle:** Pause to assess, don't just assess to pause.
+
+## The Four Reflection Types
+
+### 1. Mid-Point Check
+
+**Trigger:** After completing ~50% of planned tasks (e.g., 3 of 6 tasks done)
+
+```
+## 🔍 Mid-Point Reflection
+
+**Progress:** [N/M] tasks complete
+**Context used:** ~[X]% estimated
+
+### Scope Check
+- [ ] Am I still solving the original problem?
+- [ ] Have I introduced any unplanned work?
+- [ ] Are remaining tasks still correctly scoped?
+
+### Quality Check
+- [ ] Do completed tasks actually work (not just "done")?
+- [ ] Any verification steps I deferred?
+- [ ] Any TODO/FIXME I left that needs addressing?
+
+### Efficiency Check
+- [ ] Am I spending context on the right things?
+- [ ] Should remaining tasks be parallelized?
+- [ ] Any tasks that should be deferred to a follow-up bead?
+
+**Assessment:** [On track / Drifting / Blocked]
+**Adjustment:** [None needed / Describe change]
+```
+
+### 2. Completion Check
+
+**Trigger:** Before claiming any task or phase is complete
+
+```
+## ✅ Completion Check
+
+**Claiming complete:** [task/phase name]
+
+### Evidence Audit
+- [ ] Verification command was run (not assumed)
+- [ ] Output confirms the claim (not inferred)
+- [ ] No stub patterns in modified files
+- [ ] Imports/exports are wired (not just declared)
+
+### Goal-Backward Check
+- [ ] Does this task achieve its stated end-state?
+- [ ] Would a user see the expected behavior?
+- [ ] If tested manually, would it work?
+
+**Verdict:** [Complete / Needs work: describe what]
+```
+
+### 3. Near-Limit Warning
+
+**Trigger:** When context usage exceeds ~70% or step count approaches limit
+
+```
+## ⚠️ Near-Limit Warning
+
+**Context pressure:** [High / Critical]
+**Remaining tasks:** [N]
+
+### Triage
+1. What MUST be done before stopping? [list critical tasks]
+2. What CAN be deferred? [list deferrable tasks]
+3. What should be handed off? [list with context needed]
+
+### Action
+- [ ] Compress completed work
+- [ ] Prioritize remaining tasks ruthlessly
+- [ ] Prepare handoff if needed
+
+**Decision:** [Continue (enough budget) / Compress and continue / Handoff now]
+```
+
+### 4. Phase Transition Check
+
+**Trigger:** At `/lfg` phase boundaries (Plan→Work, Work→Review, Review→Compound)
+
+```
+## 🔄 Phase Transition: [Previous] → [Next]
+
+### Previous Phase Assessment
+- **Objective met?** [Yes / Partially / No]
+- **Artifacts produced:** [list]
+- **Open issues carried forward:** [list or "none"]
+
+### Next Phase Readiness
+- [ ] Prerequisites satisfied
+- [ ] Context is clean (no stale noise)
+- [ ] Correct skills loaded for next phase
+
+**Proceed:** [Yes / Need to resolve: describe]
+```
+
+## Integration Points
+
+### In `/ship` (Phase 3 task loop)
+
+After every ceil(totalTasks / 2) tasks, run **Mid-Point Check**:
+
+```typescript
+const midpoint = Math.ceil(totalTasks / 2);
+if (completedTasks === midpoint) {
+  // Run mid-point reflection
+  // Log assessment to .beads/artifacts/$BEAD_ID/reflections.md
+}
+```
+
+Before each task completion claim, run **Completion Check** (lightweight — just the evidence audit).
+
+### In `/lfg` (phase transitions)
+
+At each step boundary (Plan→Work, Work→Review, Review→Compound), run **Phase Transition Check**.
+
+### Context pressure monitoring
+
+When context usage estimate exceeds 70%, run **Near-Limit Warning** regardless of task position.
+
+## Reflection Log
+
+Append all reflections to `.beads/artifacts/$BEAD_ID/reflections.md` (or session-level if no bead):
+
+```markdown
+## Reflection Log
+
+### [timestamp] Mid-Point Check
+
+Assessment: On track
+Context: ~45% used
+Adjustment: None
+
+### [timestamp] Completion Check — Task 3
+
+Verdict: Complete
+Evidence: typecheck pass, test pass (12/12)
+
+### [timestamp] Near-Limit Warning
+
+Decision: Compress and continue
+Deferred: Task 6 (cosmetic cleanup) → follow-up bead
+```
+
+## Gotchas
+
+- **Don't over-reflect** — these are quick self-checks, not long analyses. Each should take < 30 seconds of reasoning.
+- **Don't block on minor drift** — if drift is cosmetic (variable naming, style), note it and continue. Only pause for scope drift.
+- **Context cost** — each reflection adds ~200-400 tokens. Budget accordingly. Skip mid-point check for < 4 tasks.
+- **Not a replacement for verification** — reflections assess trajectory, not correctness. Always run actual verification commands.