deployment

name	deployment
description	This skill should be used when configuring deployment pipelines and infrastructure for web applications. It covers environment setup, CI/CD workflows, database operations, monitoring, and rollback strategies.
depends	["real.md","cog.md"]
generates	["spec-deployment.md"]

Note for AI Agents: This skill generates specification documents for AI/Agent consumption (especially Claude Code). Before generating specs, you MUST load context from real.md and cog.md. If these files don't exist, invoke the 00-meta skill first to create them.

Prerequisites

Pre-execution Checklist

Before using this skill, verify:

1. real.md exists - Contains reality constraints (max 4 required + 3 optional)
2. cog.md exists - Contains cognitive model (Agents + Information + Context)

If either file is missing, execute:

Invoke skill: 00-meta

Context Loading

From cog.md, extract:

• Context environment: Deployment targets (Vercel, EdgeOne, etc.)
• External integrations: Third-party services requiring configuration
• Agent access patterns: Traffic patterns affecting scaling decisions

From real.md, extract:

• Security constraints: Secrets management, encryption key requirements
• Infrastructure constraints: Region requirements, compliance needs
• Operational constraints: Backup frequency, monitoring requirements

Deployment & Operations

Overview

This skill guides the deployment and operation of web applications. To deploy successfully, configure environments, set up CI/CD pipelines, manage databases, implement monitoring, and plan rollback strategies.

When to Use This Skill

• Setting up deployment infrastructure
• Configuring CI/CD pipelines
• Managing environment variables
• Planning database migrations
• Implementing monitoring and alerting

Process

Phase 1: Environment Configuration

Environment Types:

Environment	Purpose	Branch	URL
Development	Local development	feature/*	localhost:3000
Preview	PR previews	PR branches	*.vercel.app
Staging	Pre-production testing	develop	staging.domain.com
Production	Live application	main	domain.com

Environment Variables:

# .env.example

# Database
DATABASE_URL="postgresql://user:pass@host/db?sslmode=require"

# Authentication
JWT_SECRET="min-32-character-secret-key-here"
SESSION_SECRET="another-secure-secret-key"

# Encryption (for API keys)
ENCRYPTION_KEY="64-character-hex-key-for-aes-256"

# Application
NEXT_PUBLIC_APP_URL="https://domain.com"
NODE_ENV="production"

# Optional: External Services
SEARCH_API_KEY="search-service-api-key"

Security Guidelines:

Rule	Description
Never commit secrets	Use .gitignore for .env
Use unique keys per env	Different secrets for staging/prod
Rotate regularly	Change secrets every 90 days
Audit access	Log who accesses secrets

Phase 2: Configure Vercel Deployment

vercel.json Configuration:

{
  "framework": "nextjs",
  "buildCommand": "bun run build",
  "installCommand": "bun install",
  "regions": ["hkg1", "sin1"],
  "functions": {
    "app/api/**/*.ts": {
      "maxDuration": 30
    }
  },
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options"   
             
             
      
    
  

Vercel Environment Setup:

1. Connect repository (GitHub/GitLab)
2. Configure build settings
3. Add environment variables
4. Set up preview deployments
5. Configure production domain

Phase 3: CI/CD Pipeline

GitHub Actions Workflow:

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      
      - name: Install dependencies
        run: bun install
      
      - name: Lint
        run: bun run lint
      
      - name: Type check
        run: bun run type-check
      
      - name: Unit tests
        run: bun test

  e2e:
    runs-on: ubuntu-latest
    needs: quality
    steps:
        
        
      
         
          
      
         
            
      
          
           
        
             

  
     
     
       
    
        
        
        
             
             
             

  
     
     [, ]
       
    
        
        
        
             
             
             
           

Deployment Flow:

1. Developer pushes to feature branch
2. Create PR to develop
3. CI runs lint, type-check, tests
4. Vercel deploys preview
5. Code review and approval
6. Merge to develop → staging deploy
7. Merge to main → production deploy

Phase 4: Database Operations

Neon Setup:

// lib/db/index.ts
import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';
import * as schema from './schema';

const sql = neon(process.env.DATABASE_URL!);
export const db = drizzle(sql, { schema });

Migration Commands:

# Generate migration from schema changes
bunx drizzle-kit generate

# Apply migrations
bunx drizzle-kit migrate

# Open Drizzle Studio (local DB viewer)
bunx drizzle-kit studio

# Push schema directly (dev only)
bunx drizzle-kit push

Migration Strategy:

Change Type	Risk	Strategy
Add table	Low	Direct migration
Add column	Low	Add with DEFAULT or NULL
Remove column	High	Deprecate → Remove later
Rename column	High	Add new → Copy → Drop old
Change type	High	Create new → Migrate data

Backup Strategy:

## Neon Automatic Backups

- Point-in-time recovery (PITR)
- 7-day history retention
- Branch-based recovery

## Manual Backup

# Export
pg_dump $DATABASE_URL > backup_$(date +%Y%m%d).sql

# Restore
psql $DATABASE_URL < backup_20231205.sql

Phase 5: Health Monitoring

Health Check Endpoint:

// app/api/health/route.ts
import { NextResponse } from 'next/server';
import { db } from '@/lib/db';
import { sql } from 'drizzle-orm';

export async function GET() {
  const startTime = Date.now();
  
  try {
    // Check database
    await db.execute(sql`SELECT 1`);
    
    const responseTime = Date.now() - startTime;
    
    return NextResponse.json({
      status: 'healthy',
      timestamp: new Date().toISOString(),
      version: process.env.VERCEL_GIT_COMMIT_SHA?.slice(0, 7),
      checks: {
        database: 'ok',
      },
      responseTime: `${responseTime}ms`,
    });
  } catch (error) {
    return NextResponse.json(
      {
        : ,
        :  ().(),
        : ,
      },
      { :  }
    );
  }
}

Monitoring Checklist:

Metric	Alert Threshold	Action
Response time	> 3s	Investigate slow queries
Error rate	> 1%	Check logs
DB connections	> 80% pool	Scale or optimize
Memory usage	> 90%	Investigate leaks

Vercel Analytics:

• Real User Monitoring (RUM)
• Web Vitals tracking
• Error tracking
• Usage analytics

Phase 6: Rollback Strategy

Vercel Rollback:

1. Go to Vercel Dashboard
2. Navigate to Deployments
3. Find last working deployment
4. Click "Promote to Production"

Database Rollback:

## Using Neon Branches

1. Create branch from production
2. Test rollback on branch
3. Apply to production

## Using Point-in-Time Recovery

1. Identify target timestamp
2. Create new branch at timestamp
3. Verify data integrity
4. Switch application to new branch

Rollback Checklist:

• Identify the issue
• Determine if code or data issue
• For code: Rollback deployment
• For data: Use database recovery
• Verify fix in production
• Document incident

Output Template

# Deployment Configuration

## 1. Environments
- Environment list and configuration

## 2. Environment Variables
- Required variables list

## 3. CI/CD Pipeline
- Workflow configuration

## 4. Database Operations
- Migration strategy
- Backup configuration

## 5. Monitoring
- Health endpoints
- Alert configuration

## 6. Rollback Plan
- Procedure documentation

Quality Checklist

• All environments configured
• Secrets managed securely
• CI/CD pipeline working
• Database migrations tested
• Health endpoint implemented
• Monitoring configured
• Rollback procedure documented

Integration with Other Skills

Skill	Relationship
system-architecture	Input: architecture defines infra
quality-assurance	Input: tests run in CI
coding	Input: code to be deployed