project-handoff

This skill generates all documentation needed to hand off a completed project to a client or their internal team. It reads the codebase, environment config, and deployment setup to produce a comprehensive handoff package.

The user provides: the project directory and optionally the client’s technical level (non-technical, developer, DevOps).

Handoff Package Contents

1. Project Overview (handoff/README.md)

# {Project Name} — Handoff Documentation

## Quick Start
git clone {repo-url}
{package-manager} install
cp .env.example .env.local  # fill in values
{package-manager} dev        # runs on localhost:3000

## Architecture
- Framework: {Next.js 16 / etc.}
- Styling: {Tailwind CSS v4 / etc.}
- Deployment: {Vercel / etc.}
- Domain: {domain.com}

## Repository
- URL: {repo-url}
- Branch strategy: main (production), develop (staging)
- CI/CD: {auto-deploy on push to main via Vercel}

2. Environment Variables (handoff/environment.md)

Auto-generated from .env.example and codebase analysis:

# Environment Variables

## Required
| Variable | Description | Where to get it | Example |
|----------|------------|-----------------|---------|
| SMTP_HOST | Email server hostname | Your email provider | smtp.gmail.com |
| SMTP_PORT | Email server port | Your email provider | 587 |
| SMTP_USER | Email account username | Your email provider | user@domain.com |
| SMTP_PASS | Email account password | Your email provider | ••••••••••• |

## Optional
| Variable | Description | Default |
|----------|------------|---------|
| NEXT_PUBLIC_GA_ID | Google Analytics ID | (none — analytics disabled) |

## Setting Variables
### Vercel
1. Go to vercel.com → Project → Settings → Environment Variables
2. Add each variable for Production, Preview, and Development
3. Redeploy after adding variables

### .env.local (local development)
Copy .env.example to .env.local and fill in values.
Never commit .env.local to git.

3. Deployment Guide (handoff/deployment.md)

# Deployment

## Production (Vercel)
- Auto-deploys when you push to `main` branch
- URL: {production-url}
- Dashboard: vercel.com/team/{team}/project/{project}

## How to Deploy
1. Make changes on a feature branch
2. Create a Pull Request to `main`
3. Vercel creates a preview deployment automatically
4. Review the preview URL
5. Merge the PR → auto-deploys to production

## Manual Deploy
npx vercel --prod

## Rollback
1. Go to Vercel Dashboard → Deployments
2. Find the last working deployment
3. Click ••• → Promote to Production

## Custom Domain
- Domain: {domain.com}
- DNS: {provider}
- Records configured: {A record / CNAME}
- SSL: Automatic via Vercel

4. Content Management (handoff/content.md)

How to update content without a developer:

# Updating Content

## Text Content
Content is stored in: src/data/*.ts

### To update text:
1. Open the relevant file in src/data/
2. Find the text you want to change
3. Edit the text between the quotes
4. Commit and push → auto-deploys

### File locations:
| Content | File |
|---------|------|
| Book list | src/data/books.ts |
| Articles | src/data/articles.ts |
| Navigation | src/data/navigation.ts |
| {etc.} | {etc.} |

## Images
- Location: public/images/
- Formats: Use .webp or .jpg (not .png for photos)
- Sizes: Keep under 500KB per image
- After adding: reference in the relevant data file

## Adding a New Page
1. Create src/app/{page-name}/page.tsx
2. Add navigation link in src/data/navigation.ts
3. Update sitemap in src/app/sitemap.ts

## Adding a New Article/Publication
1. Open src/data/{articles|books}.ts
2. Add a new entry following the existing pattern
3. Add any images to public/images/
4. Commit and push

5. Architecture Overview (handoff/architecture.md)

Auto-generated from codebase analysis:

# Architecture

## Directory Structure
src/
├── app/                    # Pages (file-based routing)
│   ├── page.tsx           # Homepage (/)
│   ├── about/page.tsx     # About page (/about)
│   ├── api/               # API routes
│   │   └── contact/route.ts  # Contact form endpoint
│   └── layout.tsx         # Root layout (header, footer)
├── components/
│   ├── layout/            # Header, footer, nav
│   ├── sections/          # Reusable page sections
│   └── ui/                # shadcn/ui components
├── data/                  # Content data files
├── lib/                   # Utility functions
└── styles/                # Global CSS

## Key Files
| File | Purpose |
|------|---------|
| src/app/layout.tsx | Root layout — wraps every page |
| src/app/globals.css | Global styles, CSS variables, fonts |
| next.config.ts | Redirects, image domains, config |
| tailwind.config.ts | Theme customization |

## Data Flow
1. Content lives in src/data/*.ts as typed TypeScript objects
2. Pages import data and render it
3. Contact form: client → /api/contact → Nodemailer → SMTP
4. No database — all content is in code

## Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| next | {version} | React framework |
| tailwindcss | {version} | Styling |
| framer-motion | {version} | Animations |
| nodemailer | {version} | Email sending |
| {etc.} | {etc.} | {etc.} |

6. Maintenance Checklist (handoff/maintenance.md)

# Maintenance

## Regular Tasks
| Task | Frequency | How |
|------|-----------|-----|
| Update dependencies | Monthly | `npm outdated` then `npm update` |
| Check for security vulns | Monthly | `npm audit` |
| Review Lighthouse scores | Quarterly | Run audit on production |
| Renew SSL certificate | Automatic | Managed by Vercel |
| Check error logs | Weekly | Vercel Dashboard → Logs |
| Backup content | Before major changes | `git tag backup-{date}` |

## Updating Dependencies
npm outdated          # see what's outdated
npm update            # update minor/patch versions
npx npm-check-updates # check for major version updates

## If Something Breaks
1. Check Vercel deployment logs: Dashboard → Deployments → latest
2. Check browser console for errors
3. Rollback to last working deployment (see deployment.md)
4. Contact: {developer contact info}

## Security
- Never commit .env files (they're in .gitignore)
- Rotate SMTP credentials periodically
- Keep dependencies updated (security patches)
- Review Vercel access permissions quarterly

7. Troubleshooting (handoff/troubleshooting.md)

# Troubleshooting

## Common Issues

### Build fails after content change
- Check for unclosed quotes or brackets in data files
- TypeScript will show the exact line with the error
- Fix: look at the Vercel build logs for the error message

### Contact form not sending emails
- Verify SMTP environment variables in Vercel
- Check Vercel Function logs for errors
- Test with a simple email first
- Common: SMTP password expired or 2FA blocking

### Images not showing
- Check file exists in public/images/
- Check filename matches exactly (case-sensitive)
- Verify image path in the data file starts with /images/

### Site looks different on mobile
- Clear browser cache (Cmd+Shift+R)
- Check if Vercel preview deployment is stale
- Verify changes are on the `main` branch

### Slow page load
- Run Lighthouse audit
- Check image sizes (should be < 500KB each)
- Look for unoptimized images (use WebP format)

Generation Process

The skill reads the actual codebase to generate accurate documentation:

1. Scan package.json — detect framework, dependencies, scripts
2. Scan .env.example — document all environment variables
3. Scan src/ directory — map file structure and data flow
4. Scan deployment config — Vercel, Netlify, Docker, etc.
5. Scan next.config.* — redirects, image domains, etc.
6. Read git remote — repository URL and branch info
7. Generate all handoff documents with accurate, project-specific content

Output

All files are saved to handoff/ directory:

handoff/
├── README.md              # Quick start and overview
├── environment.md         # Environment variables guide
├── deployment.md          # How to deploy and rollback
├── content.md             # How to update content
├── architecture.md        # Technical architecture
├── maintenance.md         # Ongoing maintenance checklist
└── troubleshooting.md     # Common issues and fixes

Customization by Audience

Agent Team Integration

In the website-refactor workflow, this skill runs in Phase 6 after deployment. The Lead generates handoff docs as the final deliverable.