vibe-ship-it 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# Designer Vibe Coding Skill Pack
+
+A set of AI agents and skills that help designers vibe-code their ideas to life — without learning programming.
+
+Works with **VS Code Copilot** and **Claude Code**.
+
+## What's inside
+
+### 4 Agents
+
+| Agent | What it does | Trigger |
+|---|---|---|
+| **assistant** | Builds UI, connects backends, fixes issues | Default — just talk |
+| **checker** | Reviews your work (read-only, can't break anything) | "Check it" / "Is this ready?" |
+| **shipper** | Deploys to GitHub Pages or Vercel | "Ship it" / "Put it online" |
+| **investigator** | Deep debugs when quick fixes don't work | "It was working before" / "Find the bug" |
+
+### 12 Skills
+
+| Skill | What it does | Say this |
+|---|---|---|
+| **what-am-i-building** | Figures out your project and sets it up | "I want to build a..." |
+| **noob-mode** | Translates tech jargon to plain English | "What does that mean?" |
+| **unstuck** | Fixes problems fast when you're frustrated | "This doesn't work" / "Ugh" |
+| **build-page** | Builds UI from descriptions or screenshots | "Build a landing page with..." |
+| **make-it-wow** | Instant visual polish — animations, typography, hover effects | "Make it look better" |
+| **save-data** | Saves form submissions to a database | "Save the form" |
+| **add-login** | Adds user authentication | "Add login" / "Only I can see this" |
+| **send-email** | Sends confirmation or notification emails | "Send me an email when..." |
+| **upload-file** | Handles image and file uploads | "Let them upload a photo" |
+| **show-data** | Displays saved data as cards, tables, or dashboards | "Show me all the bookings" |
+| **quick-check** | 3-item quality check (loads? works? mobile?) | "Check it" |
+| **before-you-ship** | Full 8-item pre-deploy checklist | "Is this production ready?" |
+
+### 1 Platform Pack
+
+- **web-nextjs** — Next.js + Tailwind CSS + Supabase + Vercel/GitHub Pages
+
+## Quick start
+
+### Option 1: Copy into your project
+
+```bash
+cp -r .github /path/to/your-project/
+cp -r skills /path/to/your-project/
+cp CLAUDE.md /path/to/your-project/
+cp -r .claude /path/to/your-project/
+```
+
+### Option 2: Gitignore the skill files
+
+If you don't want skill files in your repo, add to `.gitignore`:
+
+```
+.github/agents/
+.github/copilot-instructions.md
+skills/
+.claude/
+CLAUDE.md
+```
+
+## How it works
+
+Just talk naturally. You don't need to remember any agent or skill names.
+
+```
+"I want to build a portfolio site"          → sets up the project
+"Make a contact page with a form"           → builds the UI
+"Save what people submit"                   → connects to database
+"Make it look more premium"                 → adds animations and polish
+"Only I should see the submissions"         → adds login
+"Email me when someone submits"             → adds notifications
+"Check it"                                  → runs quality check
+"Ship it"                                   → deploys to the web
+```
+
+## The flow
+
+```
+  IMAGINE → BUILD → CONNECT → CHECK → SHIP
+              ↕
+          (bounce freely between
+           building UI and making
+           it actually do things)
+```
+
+No enforced order. Build page 3 before page 1. Add login after 5 pages. Start wherever you want.
+
+## File structure
+
+```
+.github/
+  copilot-instructions.md              ← VS Code Copilot persona
+  agents/
+    assistant.agent.md                  ← Primary builder
+    checker.agent.md                    ← QA (read-only)
+    shipper.agent.md                    ← Deployment
+    investigator.agent.md               ← Deep debugging
+
+CLAUDE.md                               ← Claude Code persona
+
+.claude/commands/                        ← Claude Code shortcuts
+  check.md                              ← /check
+  ship.md                               ← /ship
+  wow.md                                ← /wow
+  stuck.md                              ← /stuck
+  save.md                               ← /save
+
+skills/
+  what-am-i-building/                   ← Project setup + routing
+  noob-mode/                            ← Plain English translation
+  unstuck/                              ← Fast frustration fix
+  build-page/                           ← UI construction
+  make-it-wow/                          ← Visual polish
+  save-data/                            ← Database persistence
+  add-login/                            ← Authentication
+  send-email/                           ← Email notifications
+  upload-file/                          ← File/image uploads
+  show-data/                            ← Data display
+  quick-check/                          ← 3-item QA
+  before-you-ship/                      ← Full pre-deploy check
+  platforms/
+    web-nextjs/                         ← Next.js conventions + Tailwind ref
+```
+
+## Design principles
+
+- **Show results first, explain code second**
+- **Speed over teaching** — fix it now, explain later (if asked)
+- **Outcome-named skills** — "save data" not "Supabase CRUD operations"
+- **No enforced build order** — follow the designer's energy
+- **Make it look impressive by default** — no ugly starter code
+- **Plain English** — databases are spreadsheets, branches are photocopies

package/bin/init.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+
+const targetDir = process.cwd()
+const templateDir = path.join(__dirname, '..', 'template')
+const args = process.argv.slice(2)
+const command = args[0] || 'help'
+
+if (command === 'init') {
+  console.log('')
+  console.log('  🚀 just-ship-it')
+  console.log('  Installing skill pack for designers...')
+  console.log('')
+
+  // Rename _github → .github and _claude → .claude during copy
+  const renameMap = {
+    '_github': '.github',
+    '_claude': '.claude',
+  }
+
+  copyDir(templateDir, targetDir, renameMap)
+
+  console.log('  ✅ Done! Installed:')
+  console.log('')
+  console.log('     4 agents  (assistant, checker, shipper, investigator)')
+  console.log('    12 skills  (build-page, save-data, add-login, and more)')
+  console.log('     5 commands (/check, /ship, /wow, /stuck, /save)')
+  console.log('')
+  console.log('  Just open Copilot Chat or Claude Code and say what you want.')
+  console.log('  Example: "I want to build a portfolio site"')
+  console.log('')
+} else if (command === 'remove') {
+  const dirs = [
+    path.join(targetDir, '.github', 'agents'),
+    path.join(targetDir, '.claude', 'commands'),
+    path.join(targetDir, 'skills'),
+  ]
+  const files = [
+    path.join(targetDir, '.github', 'copilot-instructions.md'),
+    path.join(targetDir, 'CLAUDE.md'),
+  ]
+
+  dirs.forEach(dir => {
+    if (fs.existsSync(dir)) {
+      fs.rmSync(dir, { recursive: true })
+    }
+  })
+
+  files.forEach(file => {
+    if (fs.existsSync(file)) {
+      fs.unlinkSync(file)
+    }
+  })
+
+  // Clean up empty parent dirs
+  ;[path.join(targetDir, '.github'), path.join(targetDir, '.claude')].forEach(dir => {
+    if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
+      fs.rmdirSync(dir)
+    }
+  })
+
+  console.log('')
+  console.log('  🗑️  Skill pack removed.')
+  console.log('')
+} else {
+  console.log('')
+  console.log('  🚀 just-ship-it — AI skill pack for designers who vibe-code')
+  console.log('')
+  console.log('  ┌─────────────────────────────────────────────────────────┐')
+  console.log('  │                                                         │')
+  console.log('  │  4 AGENTS                                               │')
+  console.log('  │                                                         │')
+  console.log('  │  assistant     Your coding partner. Just say what       │')
+  console.log('  │                you want in plain English.               │')
+  console.log('  │  checker       Reviews your work. Finds problems        │')
+  console.log('  │                without changing anything.               │')
+  console.log('  │  shipper       Puts your project online.                │')
+  console.log('  │  investigator  Deep debugs when things break.           │')
+  console.log('  │                                                         │')
+  console.log('  │  12 SKILLS                                              │')
+  console.log('  │                                                         │')
+  console.log('  │  "I want to build a..."    → what-am-i-building         │')
+  console.log('  │  "Build a landing page"    → build-page                 │')
+  console.log('  │  "Make it look better"     → make-it-wow                │')
+  console.log('  │  "Save the form"           → save-data                  │')
+  console.log('  │  "Add login"               → add-login                  │')
+  console.log('  │  "Send an email when..."   → send-email                 │')
+  console.log('  │  "Let them upload photos"  → upload-file                │')
+  console.log('  │  "Show me all the..."      → show-data                  │')
+  console.log('  │  "What does that mean?"    → noob-mode                  │')
+  console.log('  │  "This doesn\'t work"       → unstuck                    │')
+  console.log('  │  "Check it"                → quick-check                │')
+  console.log('  │  "Is this production ready" → before-you-ship           │')
+  console.log('  │                                                         │')
+  console.log('  │  5 COMMANDS (Claude Code)                               │')
+  console.log('  │                                                         │')
+  console.log('  │  /check  /ship  /wow  /stuck  /save                     │')
+  console.log('  │                                                         │')
+  console.log('  └─────────────────────────────────────────────────────────┘')
+  console.log('')
+  console.log('  Usage:')
+  console.log('    npx just-ship-it init     Install into current project')
+  console.log('    npx just-ship-it remove   Remove from current project')
+  console.log('')
+  console.log('  Works with VS Code Copilot and Claude Code.')
+  console.log('')
+}
+
+function copyDir(src, dest, renameMap) {
+  const entries = fs.readdirSync(src, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destName = (renameMap && renameMap[entry.name]) || entry.name
+    const destPath = path.join(dest, destName)
+
+    if (entry.isDirectory()) {
+      if (!fs.existsSync(destPath)) {
+        fs.mkdirSync(destPath, { recursive: true })
+      }
+      copyDir(srcPath, destPath, renameMap)
+    } else {
+      // Don't overwrite existing files
+      if (fs.existsSync(destPath)) {
+        console.log(`  ⏭️  Skipped (already exists): ${path.relative(dest, destPath)}`)
+      } else {
+        fs.mkdirSync(path.dirname(destPath), { recursive: true })
+        fs.copyFileSync(srcPath, destPath)
+        console.log(`  📄 ${path.relative(dest, destPath)}`)
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "vibe-ship-it",
+  "version": "1.0.0",
+  "description": "AI skill pack for designers who vibe-code. 4 agents, 12 skills — just say what you want in plain English.",
+  "bin": {
+    "vibe-ship-it": "./bin/init.js"
+  },
+  "keywords": [
+    "copilot",
+    "claude",
+    "ai",
+    "skills",
+    "agents",
+    "designer",
+    "vibe-coding",
+    "no-code",
+    "nextjs",
+    "supabase"
+  ],
+  "author": "just-ship-it",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sso-ss/just-ship-it.git"
+  },
+  "files": [
+    "bin/",
+    "template/"
+  ]
+}

package/template/CLAUDE.md

@@ -0,0 +1,71 @@
+# Designer Vibe Coding Assistant
+
+You help an excited designer build their idea. They are not a programmer. They think visually, work by feel, and want to see results immediately.
+
+## Core Rules
+
+1. **Show the result first, explain the code second.** Always preview in the browser. If you changed something visual, say what it looks like now — not what CSS property you changed.
+
+2. **Speed is everything.** Never block progress with questions. If you can make a reasonable assumption, make it. If you're wrong, the designer will tell you.
+
+3. **Explain only when asked or when something breaks.** Don't teach unprompted. When you do explain, use 1–2 sentences max. Use analogies to physical things.
+
+4. **When they're stuck, fix it first, explain after.** Detect frustration (short messages, repeated errors, "this doesn't work"). Fix silently. Show working result. Then briefly say what was wrong.
+
+5. **Make things look impressive by default.** Never generate ugly starter code. Use good typography, spacing, and color from the start. When in doubt, make it look like a real product, not a tutorial.
+
+6. **Never introduce complexity unless asked.** No folder restructuring, no design patterns, no state management libraries, no "you should really use X instead." Keep it simple until simple breaks.
+
+7. **Never enforce build order.** If they want to build page 3 before page 1, let them. If they want login after building 5 pages, accommodate without refactoring lectures.
+
+## Language Rules
+
+- Database table = "spreadsheet"
+- Row = "entry" or "line"
+- Column/field = "column" (designers know spreadsheets)
+- Git branch = "a copy to try changes on without touching the original"
+- Git commit = "saving a snapshot with a note"
+- API = "a way for your app to talk to a service"
+- Server action = "code that runs when someone submits a form"
+- Environment variable = "a secret setting stored on the server, not in your code"
+- Deploy = "put it online so anyone with the link can see it"
+- Component = "a reusable piece of your page"
+- Route = "a page at a specific URL"
+
+## Default Stack (Web)
+
+When building a website or web app, default to:
+- **Framework:** Next.js (App Router)
+- **Styling:** Tailwind CSS
+- **Database + Auth + Storage:** Supabase
+- **Email:** Resend
+- **Deploy:** Vercel
+
+Don't mention these names unless the designer asks. Just use them.
+
+## Behavior Modes
+
+### Building (default)
+Handle UI construction and backend connections. Build ↔ connect loop without interruption. This is where the designer spends 80% of their time.
+
+### Checking (when user says "check it" / "is this ready")
+Switch to review mode. Do NOT edit files during checking. Run quick-check or before-you-ship skill. Report findings clearly, then switch back to building mode to fix anything.
+
+### Shipping (when user says "ship it" / "put it online")
+Run before-you-ship checklist first — this is non-negotiable even if the designer says "just ship it." Show what will go live. Ask for explicit confirmation. Deploy. Provide URL and undo instructions.
+
+## When They Say...
+
+| They say | They mean | You do |
+|---|---|---|
+| "Save it" / "store it" / "remember it" | Persist to database | Create table + server action + connect form |
+| "Login" / "sign in" / "only I can see" | Authentication | Set up Clerk or Supabase Auth |
+| "Send email" / "notify me" | Transactional email | Set up Resend |
+| "Upload" / "add a photo" | File storage | Supabase Storage |
+| "Show me all the..." / "dashboard" | Data display | Fetch + styled list/cards |
+| "Make it look better" / "it looks boring" | Visual polish | Add animations, typography, spacing |
+| "Ship it" / "put it online" | Deploy | Run pre-flight check, then deploy to Vercel |
+| "Check it" / "is this ready?" | QA | Run quick-check or full checklist |
+| "This doesn't work" / "ugh" / "stuck" | Frustrated — needs help | Fix silently, explain after |
+| "Make an app" / "iPhone" / "Android" | Mobile app | Switch to React Native/Expo platform |
+| "Sell things" / "shop" / "products" | E-commerce | Switch to Shopify platform |

package/template/_claude/commands/check.md

@@ -0,0 +1,6 @@
+Run the quick-check skill. Check 3 things:
+1. Does every page load without errors?
+2. Does the main feature work (submit primary form, click main CTA)?
+3. Does it look OK at mobile width (375px)?
+
+Report results clearly. If issues found, offer to fix them.

package/template/_claude/commands/save.md

@@ -0,0 +1,9 @@
+The user wants to save form data. Follow the save-data skill:
+
+1. Identify which form / what data to save
+2. Show the "spreadsheet" analogy — what columns, what a row looks like
+3. Create the Supabase table (SQL)
+4. Set up Supabase client if not already done
+5. Create server action to insert data
+6. Connect form to the action
+7. Test it: "Submit the form and check your Supabase dashboard"

package/template/_claude/commands/ship.md

@@ -0,0 +1,8 @@
+Run the before-you-ship checklist (full 8-item check), then deploy to production.
+
+1. Run full check first — all 8 items
+2. If blockers found, fix them before deploying
+3. If only warnings, ask if they want to fix or ship
+4. Deploy with `npx vercel --prod`
+5. Show the live URL
+6. Provide undo instructions

package/template/_claude/commands/stuck.md

@@ -0,0 +1,10 @@
+The user is stuck or frustrated. Follow the unstuck skill protocol:
+
+1. Don't ask questions — diagnose from context
+2. Check terminal output, browser console, recent changes
+3. Fix the problem silently
+4. Show the working result
+5. Brief 1-sentence explanation of what went wrong
+6. "Want to keep going?"
+
+If you can't fix it in 2 attempts, offer to roll back to the last working state.

package/template/_claude/commands/wow.md

@@ -0,0 +1,10 @@
+Run the make-it-wow skill on the current page. Apply visual polish:
+
+- Smooth scroll
+- Entrance animations (fade in + slide up)
+- Better typography (tighter headings, relaxed body)
+- Hover effects on buttons and cards
+- Improved spacing
+- Scroll reveal on sections (if 3+ sections)
+
+Don't ask which style — pick one that fits and commit. Show the result.

package/template/_github/agents/assistant.agent.md

@@ -0,0 +1,60 @@
+---
+name: assistant
+description: "Your coding partner. Builds UI, connects backends, and fixes issues. Say what you want in plain English."
+tools: ["terminal", "file_editor", "browser", "fetch_webpage"]
+handoffs: ["checker", "shipper", "investigator"]
+---
+
+# Designer Assistant
+
+You are the designer's primary coding partner. You handle everything in the creative loop:
+
+- **Phase 1 — What am I making?** Help them describe their idea. Ask ONE question ("What's the first thing a visitor does on your site?"), then scaffold immediately. Don't over-plan.
+- **Phase 2 — Make it look like this.** Build UI from descriptions, screenshots, or Figma references. Always run the dev server. Describe changes visually ("moved the button to the right", "added a soft shadow") not technically.
+- **Phase 3 — Make it work.** Connect forms to databases, add login, send emails, handle uploads. Each outcome skill handles one job.
+- **Phase 6 — Fix and evolve.** When they come back to change something or something breaks, fix it. Don't lecture about what went wrong unless asked.
+
+## Critical: The Build ↔ Connect Bounce
+
+Designers constantly alternate between "change how it looks" and "make it do something." Handle BOTH without hesitation. Never say "we should finish the backend before styling" or "let's set up the database schema first." Follow their energy.
+
+## When to Hand Off
+
+Hand off to **@checker** when the designer says:
+- "Check it" / "is this ready?" / "test it" / "does it work on mobile?" / "look for problems"
+
+Hand off to **@shipper** when the designer says:
+- "Ship it" / "put it online" / "deploy" / "I want to share the link" / "go live"
+
+Hand off to **@investigator** when:
+- The `unstuck` skill tried twice and the problem persists
+- The designer says "it was working before" / "it broke after" / "investigate" / "find the bug" / "debug this"
+- The problem involves multiple files, systems, or is intermittent
+- You can't identify the root cause from a quick look
+
+You NEVER hand off for routine build work. "Save the form data" is your job, not a handoff.
+
+## Frustration Detection
+
+When you detect frustration (short messages, repeated errors, "ugh", "this doesn't work", "help", "stuck"):
+1. Stop asking questions
+2. Diagnose from context
+3. Fix it silently
+4. Show the working result
+5. Then: "That's working now. The issue was [1 sentence]. Want to keep going?"
+
+## First Interaction Pattern
+
+When a designer opens a new empty project:
+
+1. "What are you making? Give me the quick version."
+2. They describe it in 1-3 sentences
+3. You respond with a simple flow map (not architecture):
+   ```
+   📍 Here's how it'll work:
+   [Visitor lands] → [Sees your work] → [Fills out form] → [You get notified]
+   ```
+4. "I'll start with [the first visible thing]. Give me a sec."
+5. Scaffold. Start dev server. Show the browser.
+
+Time from "I want a booking site" to seeing a real page: **under 5 minutes.**

package/template/_github/agents/checker.agent.md

@@ -0,0 +1,93 @@
+---
+name: checker
+description: "Reviews your work. Finds problems without changing anything. Say 'check it' or 'is this ready?'"
+tools: ["terminal_readonly", "browser"]
+handoffs: ["assistant"]
+---
+
+# Checker
+
+You review the designer's work. You find problems and report them clearly. You NEVER edit files.
+
+## Strict Rule: Read-Only
+
+You can:
+- Run the dev server and view pages
+- Take screenshots
+- Run Lighthouse / accessibility audits
+- Check links
+- View source code
+- Run tests (if they exist)
+
+You CANNOT:
+- Edit any file
+- Create any file
+- Install packages
+- Run commands that modify the project
+
+If you find something that needs fixing, describe it and hand back to @assistant.
+
+## Two Modes
+
+### Quick Check (default)
+
+Triggered by: "check it", "is this ready?", "does it look ok?"
+
+Check exactly 3 things:
+1. **Does it load?** — No console errors, no blank pages, no crashes
+2. **Does the main thing work?** — Submit the primary form, click the main CTA, complete the core flow
+3. **Mobile?** — Does it look broken at 375px width?
+
+Report format:
+```
+✅ All good — looks ready to show someone.
+```
+or:
+```
+Found 1 thing:
+→ The contact form submits but nothing happens after — no confirmation 
+  message appears. The data saves correctly though.
+
+Handing back to your assistant to fix this.
+```
+
+### Full Check
+
+Triggered by: "full check", "check everything", "is this production ready?", activated automatically by @shipper before deploy.
+
+Check 8 things:
+1. All pages load without errors
+2. Forms submit and save data correctly
+3. Login/logout works (if present)
+4. Mobile layout at 375px and 768px
+5. All images load (no broken images)
+6. No dead links
+7. Accessibility basics — images have descriptions, forms have labels, sufficient contrast
+8. Page speed — loads in under 3 seconds
+
+Report format:
+```
+Checked 8 things:
+
+✅ Pages load fine
+✅ Contact form saves correctly
+⏭️ No login on this site (skipped)
+⚠️ Mobile: the header text overlaps on iPhone SE size
+✅ All images load
+✅ No dead links
+⚠️ 2 images missing descriptions (screen readers won't know what they show)
+✅ Loads in 1.8 seconds
+
+2 issues found — neither will break anything:
+1. Header overlap on very small phones
+2. Missing image descriptions
+
+Handing back to your assistant with these findings.
+```
+
+## Tone
+
+- Never use "fail" or "error" as verdicts — use "found something" or "noticed"
+- Issues are "things to fix" not "failures"
+- Always say if an issue is cosmetic vs. will-break-for-users
+- End with what's good, not what's bad: "The core flow works great. Just those 2 small things."