vibe-ship-it 1.0.0

package/template/skills/before-you-ship/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: before-you-ship
+description: "Full pre-deploy checklist. Runs automatically before deployment. Triggers: 'full check', 'check everything', 'production ready', 'is this ready to deploy', 'pre-deploy', 'ship check', 'before deploy'."
+---
+
+# Before You Ship
+
+The full 8-item checklist that runs before deployment. Called automatically by the shipper agent. Can also be triggered manually.
+
+## The 8 Checks
+
+### 1. All Pages Load
+Visit every route in the app. Each must render without:
+- Console errors
+- Blank pages
+- Uncaught exceptions
+- Missing components
+
+### 2. Forms Save Correctly
+Submit every form with test data. Verify:
+- Data appears in Supabase (or whatever storage is used)
+- Success confirmation shows
+- Form clears or redirects after submit
+- Submit button shows loading state (prevents double-submit)
+
+### 3. Auth Works (if present)
+If the project has login:
+- Visit a protected page while logged out → should redirect to login
+- Log in with valid credentials → should reach the protected page
+- Sign out → should return to public page
+- Visit login while already logged in → should redirect to dashboard
+
+Skip if no auth is set up.
+
+### 4. Mobile Layout
+Check at 375px (phone) and 768px (tablet):
+- No horizontal overflow
+- Text readable without zooming
+- Navigation usable (hamburger, bottom nav, or responsive links)
+- Forms fillable (inputs not cut off, keyboard doesn't hide submit button)
+- Images scale properly
+
+### 5. Images Load
+- No broken image icons
+- All images have reasonable file sizes (warn if any > 1MB)
+- All `<img>` tags have `alt` attributes (even if empty string for decorative images)
+
+### 6. No Dead Links
+- Click every link on every page
+- No 404 pages
+- No links that go nowhere or point to `#`
+- External links open in new tab
+
+### 7. Accessibility Basics
+Not a full WCAG audit — just the essentials:
+- Images have `alt` text
+- Form inputs have labels (visible or `aria-label`)
+- Color contrast is sufficient (text is readable against background)
+- Focus indicators visible when tabbing
+- Page has a `<title>` tag
+
+### 8. Page Speed
+Run a basic performance check:
+- Page loads in under 3 seconds
+- No massive unoptimized images
+- No blocking scripts
+- Fonts load without visible flash
+
+## Report Format
+
+```
+🔍 Full check — 8 items:
+
+1. ✅ All pages load without errors
+2. ✅ Contact form saves correctly
+3. ⏭️ No login (skipped)
+4. ⚠️ Mobile: nav menu overlaps logo on small phones
+5. ✅ All images load
+6. ✅ All links work
+7. ⚠️ 2 images missing alt text
+8. ✅ Loads in 1.6 seconds
+
+6 passed · 2 warnings · 0 blockers
+
+The 2 warnings won't break anything for visitors:
+  1. Nav overlap — only on very small phones (iPhone SE)
+  2. Missing alt text — screen reader users won't know 
+     what those images show
+
+👍 Safe to ship. Fix the warnings after if you want.
+```
+
+## Severity Levels
+
+| Level | Icon | Meaning | Action |
+|---|---|---|---|
+| Pass | ✅ | Works correctly | None |
+| Skipped | ⏭️ | Not applicable (e.g., no auth) | None |
+| Warning | ⚠️ | Minor issue, won't break for users | Report, don't block |
+| Blocker | ❌ | Will break for visitors | Must fix before deploy |
+
+### Blockers (must fix)
+- A page crashes or shows an error
+- Main form doesn't save data
+- Login doesn't work (if auth exists)
+- Page takes over 10 seconds to load
+
+### Warnings (can ship, fix later)
+- Minor layout issues on edge screen sizes
+- Missing alt text
+- Slight performance issues
+- Minor visual inconsistencies
+
+## After the Check
+
+If **no blockers**:
+> "All good — safe to ship. There are [N] minor things you could fix later, but nothing that'll break for visitors. Ready to deploy?"
+
+If **blockers found**:
+> "Found [N] things that should be fixed first — they'd cause problems for visitors:
+> 1. [Blocker description]
+> 2. [Blocker description]
+> 
+> Want me to fix these? Should take [rough time estimate]."
+
+## Rules
+
+- This check is NON-NEGOTIABLE before deploy — the shipper agent always runs it
+- Be honest about blockers — don't let broken things ship
+- Be relaxed about warnings — perfection is not required for launch
+- Always frame warnings as "you can fix this later" — don't make the designer feel the site isn't ready
+- Celebrate when it passes: "Looking great! Ready for the world to see it."

package/template/skills/build-page/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: build-page
+description: "Builds UI from descriptions, screenshots, or Figma designs. Triggers: 'build a page', 'create a page', 'make a page', 'build the UI', 'make it look like', 'design this page', 'add a page', 'new page', 'home page', 'landing page', 'about page', 'contact page', 'hero section', 'add a section', 'layout', 'header', 'footer', 'navigation', 'sidebar', 'form', 'card', 'modal', 'build this'."
+---
+
+# Build Page
+
+Turns descriptions, screenshots, or Figma designs into working UI. The designer's primary creative tool.
+
+## Input Types
+
+### 1. Text Description
+> "I want a landing page with a big headline, some portfolio images in a grid, and a contact form at the bottom"
+
+→ Decompose into sections, generate each, preview immediately.
+
+### 2. Screenshot / Image
+> *pastes or uploads an image*
+
+→ Analyze the layout, colors, typography, and spacing. Reproduce as closely as possible. Ask: "Does this match? What should change?"
+
+### 3. Figma Reference
+> "Here's my Figma design" / provides a Figma link
+
+→ If Figma MCP is available, pull design data directly. Otherwise, ask them to screenshot the specific frame.
+
+### 4. Vague Request
+> "make me a website"
+
+→ Don't ask 10 questions. Pick a sensible default (clean landing page with hero, features section, CTA), build it, show it. They'll tell you what to change.
+
+## Build Process
+
+### Step 1: Decompose
+Break the page into sections mentally. Don't show the decomposition to the designer — just build.
+
+Typical page anatomy:
+- Navigation (header)
+- Hero section (headline + CTA)
+- Content sections (features, portfolio, testimonials, etc.)
+- Forms (contact, signup, booking)
+- Footer
+
+### Step 2: Generate
+Build the full page in one go. Use:
+- Tailwind CSS for all styling
+- Semantic HTML
+- Good defaults: comfortable spacing, readable typography, balanced proportions
+- Real-looking placeholder content (not "Lorem ipsum" — use realistic copy)
+
+### Step 3: Preview
+Ensure dev server is running. Tell the designer:
+> "Check your browser — here's what it looks like."
+
+### Step 4: Iterate
+Wait for feedback. Common responses and what to do:
+
+| They say | They mean | Do |
+|---|---|---|
+| "Perfect!" | Done | Move on |
+| "Close but..." | Needs tweaks | Ask what specifically |
+| "The spacing feels off" | Padding/margin/gap issue | Adjust spacing, show again |
+| "Too much text" | Content is overwhelming | Reduce copy, increase white space |
+| "Make it more [adjective]" | Aesthetic change | Apply the vibe (see adjective table below) |
+| "Like [reference site]" | Match an external reference | Analyze the reference, adapt to their content |
+
+### Adjective Translation Table
+
+| They say | They mean | You do |
+|---|---|---|
+| "Modern" | Clean lines, lots of white space, sans-serif | Inter/system font, minimal borders, generous padding |
+| "Bold" | Strong colors, large typography | Increase heading size, use black/bright accent |
+| "Minimal" | Less is more, lots of breathing room | Remove visual noise, increase white space, fewer elements |
+| "Fun" | Playful colors, rounded corners, casual | Rounded-xl, bright palette, informal copy |
+| "Professional" | Corporate, trustworthy, serious | Neutral palette, geometric, structured grid |
+| "Luxury" / "Premium" | Elegant, expensive-feeling | Dark background, gold/muted accents, serif headings, generous spacing |
+| "Warm" | Inviting, comfortable | Warm color palette (amber, terracotta), organic shapes, soft shadows |
+| "Techy" | Developer/startup vibe | Dark mode, monospace accents, neon accents, code-like elements |
+| "Friendly" | Approachable, human | Rounded shapes, illustrations, conversational copy |
+
+## Component Library
+
+When building, prefer these patterns:
+
+### Navigation
+```
+Sticky header, logo left, links right, mobile hamburger menu.
+Simple — no mega-menus unless asked.
+```
+
+### Hero Section
+```
+Full-width, large headline (text-5xl to text-7xl), 
+subtitle underneath, one prominent CTA button.
+Optional: background image or gradient.
+```
+
+### Feature Grid
+```
+3-column grid (responsive to single column on mobile).
+Icon or image + heading + short description per card.
+```
+
+### Contact Form
+```
+Name, email, message fields. 
+Single "Send" button.
+Clean layout, clear labels.
+Connect to save-data skill when they say "make it work."
+```
+
+### Footer
+```
+Logo, key links, copyright.
+Keep it simple — designers rarely care about the footer first.
+```
+
+## Visual Defaults
+
+Always apply these unless told otherwise:
+- Font: system font stack or Inter
+- Heading sizes: responsive using `text-3xl md:text-5xl lg:text-7xl`
+- Body text: `text-base` or `text-lg`, line-height relaxed
+- Spacing: generous (`py-16 md:py-24` between sections)
+- Colors: start with neutral palette + one accent color
+- Border radius: `rounded-lg` or `rounded-xl` (not square, not full circle)
+- Shadows: subtle (`shadow-sm` or `shadow-md`), never harsh
+- Max width: content constrained with `max-w-7xl mx-auto`
+- Padding: `px-4 md:px-8` for horizontal padding
+
+## Critical Rules
+
+1. **Never generate ugly starter code.** Every page should look like a real product from the first render.
+2. **Use realistic placeholder content.** "Sarah Chen, UX Designer" not "John Doe, Lorem Ipsum."
+3. **Mobile-first.** Build for phone first, then make it nice on desktop.
+4. **Show, don't tell.** After building, say "Check your browser" — don't describe what the CSS does.
+5. **One page at a time.** Don't scaffold 5 empty pages. Build the one they're talking about fully, then move to the next.

package/template/skills/make-it-wow/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: make-it-wow
+description: "Instant visual polish. Makes your site look premium with animations, better typography, and modern effects. Triggers: 'make it look better', 'make it wow', 'polish', 'make it premium', 'it looks boring', 'more animation', 'make it pop', 'spice it up', 'make it cool', 'fancy', 'sleek', 'modern', 'upgrade the design', 'too plain', 'needs more life'."
+---
+
+# Make It Wow
+
+Applies opinionated visual upgrades to make the site look premium. No configuration, no questions. Just make it look better, immediately.
+
+## How It Works
+
+When triggered, scan the current page and apply upgrades from these categories. Don't ask which ones — apply all that make sense for the current content.
+
+## Upgrade Categories
+
+### 1. Smooth Scroll
+Add document-level smooth scrolling:
+```css
+html { scroll-behavior: smooth; }
+```
+
+### 2. Page Entrance Animation
+Add fade-in + slide-up to main content sections on page load:
+
+For Next.js with Tailwind — use CSS animations:
+```css
+@keyframes fadeInUp {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.animate-fade-in-up {
+  animation: fadeInUp 0.6s ease-out forwards;
+}
+```
+
+Apply staggered delays to sections for a cascading reveal effect.
+
+If Framer Motion is available or appropriate to install:
+```tsx
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.6 }}
+>
+```
+
+### 3. Typography Upgrade
+- Headlines: increase contrast between heading and body sizes
+- Use `font-semibold` or `font-bold` on headings, `font-normal` on body
+- Add `tracking-tight` to large headings
+- Ensure line-height is relaxed on body text (`leading-relaxed`)
+- If the site uses only system font, consider adding Inter or a personality font
+
+### 4. Hover States
+Add hover effects to all interactive elements:
+- Buttons: subtle scale + shadow lift
+  ```
+  hover:scale-[1.02] hover:shadow-lg transition-all duration-200
+  ```
+- Cards: lift effect
+  ```
+  hover:-translate-y-1 hover:shadow-xl transition-all duration-300
+  ```
+- Links: color transition
+  ```
+  hover:text-[accent-color] transition-colors duration-200
+  ```
+- Images: subtle zoom
+  ```
+  hover:scale-105 transition-transform duration-500 overflow-hidden
+  ```
+
+### 5. Gradient & Color Depth
+- Replace flat backgrounds with subtle gradients
+- Add depth with layered backgrounds
+- Use accent color consistently across CTAs, links, and highlights
+- Dark sections alternating with light sections for visual rhythm
+
+### 6. Spacing & White Space
+- Increase section padding if too tight
+- Add more vertical space between sections (`py-20 md:py-32`)
+- Ensure content doesn't touch edges on any screen size
+- Use `max-w` constraints to keep text readable
+
+### 7. Scroll Reveal (Optional)
+For longer pages, add intersection observer to fade in sections as user scrolls. Only if the page has 3+ sections.
+
+CSS + JS approach (no library needed):
+```css
+.reveal {
+  opacity: 0;
+  transform: translateY(30px);
+  transition: opacity 0.6s ease, transform 0.6s ease;
+}
+.reveal.visible {
+  opacity: 1;
+  transform: translateY(0);
+}
+```
+
+### 8. Micro-Details
+- Add `rounded-2xl` to cards (softer than `rounded-lg`)
+- Subtle border: `border border-gray-100` on light cards
+- Background texture: very subtle noise or gradient overlay
+- Focus states: visible and styled, not default browser outline
+- Selection color: match accent color
+
+## Performance Rules
+
+NEVER violate these:
+- Only animate `transform` and `opacity` (never `width`, `height`, `margin`, `top`)
+- Wrap continuous animations in `@media (prefers-reduced-motion: no-preference)`
+- Add `will-change: transform` only during animation, remove after
+- Wrap hover animations in `@media (hover: hover)` to skip touch devices
+- Keep total animation CSS under 5KB
+
+## Application Process
+
+1. Scan current page
+2. Identify which upgrades apply (don't add scroll reveal to a single-section page)
+3. Apply all applicable upgrades
+4. Show the result: "Check your browser — added smooth animations, hover effects, and better typography."
+5. Don't list every CSS change. Just show the before/after feeling.
+
+## What NOT To Do
+
+- Don't ask "which style would you prefer?" — just pick one and commit
+- Don't add 3D effects, parallax, or WebGL unless specifically asked
+- Don't change the layout — only enhance the existing design
+- Don't change colors dramatically — enhance what's there
+- Don't add sound effects (ever)
+- Don't add loading spinners where none are needed

package/template/skills/noob-mode/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: noob-mode
+description: "Plain-English translation layer. Explains technical things in simple language. Triggers: 'what does that mean', 'explain', 'I don't understand', 'what happened', 'what is', 'confused', 'explain everything', 'noob mode', 'beginner mode', 'speak simply'."
+---
+
+# Noob Mode
+
+Translates everything technical into clear, jargon-free language. Three intensity levels — start light, adjust based on the designer's needs.
+
+## Intensity Levels
+
+### Light Mode (Default)
+
+- Define technical terms only on FIRST use, as brief parentheticals
+- Explain only risky or destructive actions (file deletion, deployment, database changes)
+- Skip explanation for routine actions (creating files, reading code, running dev server)
+- Keep definitions to one sentence max
+
+Example:
+> "I'll create a server action (code that runs when someone submits a form) to save the contact info."
+
+After the first use, just say "server action" without re-explaining.
+
+### Full Mode
+
+Activated when the designer says: "explain everything", "noob mode", "I'm confused about everything", or during their very first session.
+
+- Explain every action before taking it
+- Define every technical term
+- Show risk level for every operation
+- Narrate multi-step tasks with a roadmap
+- Translate all command output
+
+Risk indicators:
+| Action | Risk | Icon |
+|---|---|---|
+| Reading/viewing files | Low | 🟢 |
+| Creating a new file | Moderate | 🟡 |
+| Editing an existing file | Moderate | 🟡 |
+| Installing packages | Moderate | 🟡 |
+| Running shell commands | High | 🔴 |
+| Deleting files | High | 🔴 |
+| Deploying | Critical | ⛔ |
+
+Format for full-mode actions:
+```
+📋 WHAT I'M DOING: [One plain sentence]
+🎯 WHY: [Connection to what you asked for]
+⚠️ RISK: [icon] [level] — [one sentence in everyday terms]
+```
+
+### Silent Mode
+
+Activated when the designer says: "just do it", "stop explaining", "I trust you", or after many sessions with no questions.
+
+- Do the work without narration
+- Summarize at the end: "Done — created 2 files and updated your form"
+- Only speak up for destructive or irreversible actions
+
+## Intensity Auto-Detection
+
+- First session ever → Full mode for first 10 minutes, then Light
+- Designer asks "what does X mean?" → Stay in current mode but explain that term
+- Designer says "just do it" or "skip the explanation" → Switch to Silent
+- Designer says "what's happening?" or "explain" → Switch to Full for this task, then back to Light
+
+## Analogies Reference
+
+Use these consistently. Don't invent new ones each time — consistency builds familiarity.
+
+| Technical concept | Analogy |
+|---|---|
+| Database | A spreadsheet in the cloud |
+| Database table | A tab in a spreadsheet |
+| Row | One line/entry in the spreadsheet |
+| Column/field | A column in the spreadsheet |
+| Query | Looking something up in the spreadsheet |
+| Foreign key | A cell that says "see row 5 in the other spreadsheet tab" |
+| API | A waiter — takes your order to the kitchen and brings back food |
+| Server | A computer that's always on, waiting for visitors |
+| Client | The visitor's browser — what they see on their screen |
+| Server action | Code that runs when someone submits a form |
+| Environment variable | A secret sticky note on the server — programs can read it but visitors can't |
+| Git repository | A project folder with a built-in time machine |
+| Git branch | A photocopy of your project to try changes without touching the original |
+| Git commit | Saving a snapshot with a note about what you changed |
+| Git merge | Combining the edits from your photocopy back into the original |
+| Pull request | "I made changes — can someone review before we make them official?" |
+| npm install | Downloading tools this project needs, like getting supplies before a craft project |
+| Package/dependency | A pre-built tool the project uses, like a reference book for your work |
+| Build | Converting the code into something that can actually run — like exporting a PDF from your design file |
+| Deploy | Putting it online so anyone with the link can see it |
+| Terminal/shell | A text-based control panel — you type commands instead of clicking buttons |
+| Component | A reusable piece of your page — like a symbol in Figma |
+| Props | Settings you pass to a component — like overrides on a Figma instance |
+| State | Information the page remembers while someone's using it — like a form field that knows what you typed |
+| Route | A page at a specific URL — /about goes to your About page |
+| Middleware | A security checkpoint between the visitor and your page |
+| Webhook | An automatic notification — "when X happens, tell Y" |
+| Cache | Remembering an answer so you don't have to look it up again |
+| SSL/HTTPS | The padlock in the browser — means the connection is encrypted |
+| DNS | The phone book of the internet — converts yoursite.com to a server address |
+| CDN | Copies of your site stored around the world so it loads fast everywhere |
+
+## Error Translation
+
+When a command or process produces an error, always translate:
+
+```
+❌ WHAT WENT WRONG: [Plain English]
+💡 WHY: [Why it happened, in non-technical terms]
+🔧 FIX: [What to do about it]
+```
+
+Common translations:
+
+| Error | Translation |
+|---|---|
+| `ECONNREFUSED` | "Can't connect to the server. It might not be running." |
+| `MODULE_NOT_FOUND` | "A tool this project needs isn't installed. I'll install it." |
+| `EACCES` / permission denied | "Your computer won't let me do this. Usually means we need to run it differently." |
+| `404` | "That page doesn't exist. Might be a typo in the URL or the page hasn't been created yet." |
+| `500` | "Something went wrong on the server side. Let me check the code." |
+| `CORS` | "The browser is blocking this request for security reasons. I'll fix the server settings." |
+| `hydration mismatch` | "The page looks different on the server vs the browser. Usually a small code fix." |
+| `type error` | "The code expected one type of data but got another. Like putting text where a number should go." |
+| Build failed | "The code can't be converted to a working site. Usually a typo or missing piece. Let me find it." |
+
+## Tone
+
+- Never make the designer feel bad for not knowing something
+- "Here's how this works" not "you should know that..."
+- If they ask what something means, answer warmly and completely
+- End complex explanations with "Does that make sense?" or "Want me to explain differently?"
+- Celebrate completions: "That's live!" / "Working!" / "Looks great!"