googlarz/vibe-coder-kit/vibe-handoff

# Stack
cat package.json 2>/dev/null | grep -E '"name"|"dependencies"' | head -20
cat requirements.txt 2>/dev/null | head -20
 
# Project structure (top-level only)
ls -1 . | grep -v node_modules | grep -v ".git"
 
# Entry points
ls src/ app/ pages/ api/ 2>/dev/null

# EMERGENCY HANDOFF — [Project name or "Unnamed Project"]
Generated: [today's date]
 
---
 
## What We Built
[2-3 sentences. What the project does, who uses it, approximate current state. Plain English.]
 
## What Broke
[Exactly what stopped working. Be specific: which page, which action, which API call.
When it was last working. What changed right before it broke, if known.]
 
## What We Tried
[Bullet list of every fix attempted. Be honest — include things that made it worse.]
 
## The Error
[Exact error message, copied verbatim. If there's no error message, describe the symptom
as specifically as possible: "the page loads but the submit button does nothing",
"the app crashes with a white screen", etc.]
 
## What a Developer Should Look at First
[Your best guess at root cause. Be direct even if uncertain:
"Most likely X because of Y. Could also be Z."
Point to specific files or functions if you know them.]
 
## Environment
[From .vibe/project.md if available:]
- Platform: [Vercel / Replit / Railway / local / etc.]
- Database: [Supabase / PlanetScale / SQLite / etc.]
- Auth: [NextAuth / Clerk / custom / none]
- Deployment: [how it gets pushed to production]
- Stack: [main language/framework]
 
## Urgency
[Answer these directly:]
- Real users affected: [yes / no / unknown]
- Data at risk: [yes / no / unknown]
- Revenue affected: [yes / no / unknown]
 
---
 
## Where to Get Help
 
[One of the following, based on what's broken and how serious:]
 
**If it's a platform issue** (Vercel, Supabase, etc.):
→ [Platform name] Discord: [link if known] or their support docs.
   For common platforms, use these: Vercel: vercel.com/support | Supabase: supabase.com/support | Railway: railway.app/help | Fly.io: community.fly.io | Stripe: support.stripe.com. If the platform isn't in the list above, write: "Search for [actual platform name, e.g. Railway] support or community Discord" — substitute the actual platform name, not a placeholder.
 
**If it's a framework issue** (Next.js, Rails, etc.):
→ Stack Overflow tag: [tag name] — paste the exact error message.
 
**If this needs a professional developer:**
→ This is beyond vibe-coding territory. Post on Upwork (upwork.com) or Toptal (toptal.com)
   and share this document. A developer should be able to diagnose within an hour.

# PROJECT HANDOFF — [Project name]
Generated: [today's date]
 
---
 
## What This Is
[One paragraph. What the project does, who the users are, current state
(prototype / MVP / in production with X users). Be honest about maturity.]
 
## Stack
[From .vibe/project.md if available; otherwise inferred from codebase — note "[inferred from codebase, not from project log]" if project.md was missing.]
- Language/Framework: [e.g. Next.js 14, Rails 7, Django 4]
- Database: [e.g. PostgreSQL via Supabase, SQLite]
- Auth: [e.g. NextAuth with Google, Clerk, custom JWT]
- Hosting: [e.g. Vercel, Railway, Fly.io, self-hosted]
- Key third-party services: [Stripe, Resend, Cloudinary, etc.]
 
## Architecture
[From .vibe/decisions.md if available. Key decisions and why they were made.
If the decisions file doesn't exist, describe the structure you can see:
- How the codebase is organized
- Where the main entry points are
- How data flows through the system
Note: "[inferred from codebase, not from decision log]" if the file was missing.]
 
## Known Debt
[From .vibe/debt.md if available. Format each item as:]
 
| Area | What the shortcut is | Risk if not fixed |
|------|----------------------|-------------------|
| [file or feature] | [plain description] | [LOW / MEDIUM / HIGH] |
 
[If no debt file exists: "No formal debt log. See 'What Needs Professional Attention' below."]
 
## Recent History
[From .vibe/sessions.md — last 5 sessions summarized as bullet points.
Format: "[Date] — [what was done] / [what was left fragile]]
If sessions file doesn't exist: "No session log available."]
 
## What Needs Professional Attention
[Honest assessment. Flag these areas if they apply:]
 
- [ ] **Auth** — [describe what's there and what the concern is]
- [ ] **Data model** — [describe schema and any obvious issues]
- [ ] **Security** — [note if a security scan was run (vibe-check — the security scan tool in this pack); list known findings]
- [ ] **Payments** — [describe Stripe setup and any gaps]
- [ ] **Performance** — [describe any known slow paths]
- [ ] **Deployment** — [describe how deploys work; note if it's manual/fragile]
 
## How to Run Locally
[If a README exists with setup instructions, summarize them here. If not, infer from the codebase and note "[inferred from codebase, not from README]".]
 
1. Clone the repo
2. Copy `.env.example` to `.env` and fill in: [list required env vars]
3. Install dependencies: `[npm install / pip install -r requirements.txt / etc.]`
4. [Any database setup steps]
5. Run: `[npm run dev / python manage.py runserver / etc.]`
6. Open: [http://localhost:3000 or equivalent]
 
[If this can't be inferred: "Setup instructions not documented. Ask the original developer."]
 
## About This Project's Setup
This project uses [vibe-coder-kit](https://github.com/googlarz/vibe-coder-kit) — a set of
behavioral contracts and hooks for AI-assisted development. Key things to know:
 
- `.vibe/` folder contains project context, decision log, debt log, and session history
- The AI assistant follows behavioral contracts defined in `CLAUDE.md` at the project root
- Checkpoints are saved as git commits before significant changes
 
When working with AI tools on this project, the behavioral baseline is active by default.