Deployment Skill v2.0

Orchestrated Deployment Workflow - From Planning Artifacts to Production

Purpose

Automated, orchestrated deployment workflow for Makerkit SaaS projects, transforming spec-planning outputs into production deployments on Vercel with full CI/CD automation.

Key Features:

• ✅ State-managed workflow (resume at any phase)
• ✅ Planning integration (consumes spec-planning artifacts)
• ✅ Automated CI/CD (GitHub Actions with MCP automation)
• ✅ Production readiness (comprehensive validation)
• ✅ Environment management (dev, staging, production)
• ✅ Rollback support (safe deployment procedures)

Foundation: Optimized for Makerkit.dev Next.js + Supabase deployed to Vercel.

---

When to Use This Skill

Activate when you need to:

• Deploy Makerkit SaaS application from spec-planning artifacts
• Set up CI/CD pipelines with GitHub Actions
• Configure production environments (Vercel, Supabase, Stripe)
• Migrate database schemas to production
• Implement staged deployment workflows

Trigger Phrases:

• "Deploy my Makerkit project from spec-planning"
• "Set up CI/CD for [project name]"
• "Configure production environment for [project]"

---

Prerequisites

See: Prerequisites Guide

Required Accounts

• ✅ GitHub repository with spec-planning artifacts
• ✅ Vercel account (team or personal)
• ✅ Supabase production project
• ✅ Domain name (for production)

Required Tools

• ✅ Vercel CLI (≥28.0.0)
• ✅ GitHub CLI (recommended)
• ✅ pnpm (≥8.0.0)
• ✅ Node.js (≥20.0.0)

Planning Artifacts

• ✅ 10 Projects/{project-name}/architecture.md
• ✅ 10 Projects/{project-name}/data-models.md
• ✅ 10 Projects/{project-name}/prd.md

---

MCP Server Requirements

Required MCP Servers

• None - This skill works without MCP servers

Optional MCP Servers

MCP Server	Purpose	Benefit	Fallback
GitHub	Deployment issues, PRs, workflows	60% faster workflow	Manual gh commands
Supabase	Database migrations, validation	Faster schema deployment	Manual pnpm supabase
Vercel	Project configuration, deployments	Automated management	Manual vercel CLI

See: MCP Integration Guide

---

Deployment Workflow Overview

6-Phase Deployment Process

Phase	Name	Duration	Outputs	Reference
0	Pre-Deployment Validation	5-10 min	Validation report	Phase 0
1	Environment Setup	30-45 min / 10-15 min (MCP)	Config files	Phase 1
2	Database Migration	30-45 min / 10-15 min (MCP)	Migrated schema	Phase 2
3	Preview Deployment	15-20 min	Preview URL	Phase 3
4	Production Deployment	45-60 min / 20-30 min (MCP)	Production URL	Phase 4
5	Post-Deployment	30-45 min / 15-20 min (MCP)	Monitoring setup	Phase 5

Total Time: 2.5-3.5 hours (manual) or 1-1.5 hours (with MCPs)

Workflow Characteristics

• Automated orchestration: Sequential phases with validation checkpoints
• State management: Resume deployment at any phase
• Progress visibility: Real-time deployment status
• Optional GitHub tracking: Track via issues and PRs

State Location: .claude/deployment/state/{project-name}/deployment_state.json

---

Quick Start

Starting New Deployment

User: "Deploy my Makerkit project from spec-planning"
Claude: [Validates prerequisites, initializes state, begins Phase 0]

Resuming Deployment

User: "Continue deployment for [project]"
Claude: [Loads state, displays progress, resumes from current phase]

---

Integration with Spec-Planning

See: Planning Integration Guide

This skill consumes outputs from spec-planning skill:

Planning Artifact	Deployment Usage
architecture.md	Extract tech stack, API patterns, integrations
data-models.md	Generate database migration scripts
prd.md	Extract environment variables, external services
development-stories.md	Create deployment milestones (optional)
product-vision.md	Configure analytics, monitoring (optional)
spec_state.json	Load project context

---

Orchestrated Workflow Instructions

Initialization: Deployment Setup

See: Initialization Workflow

Trigger: User activates skill with project name

Key Steps:

1. Check planning artifacts exist
2. Verify QA validation passed (GO decision)
3. Check/create deployment state
4. Verify prerequisites (tools installed)
5. Detect MCP server availability
6. Optional: Create GitHub deployment issue
7. Display deployment preview

Result: Deployment initialized, ready for Phase 0

---

Phase 0: Pre-Deployment Validation

Objective: Verify all prerequisites before deployment Duration: 5-10 minutes See: Phase 0 Workflow

Validates planning artifacts, implementation completion, QA results, git status, and prerequisites.

Key Checks:

• Planning artifacts exist (architecture, data-models, PRD)
• Implementation complete (all stories done, tests passing)
• QA validation passed (GO decision, score ≥90%)
• Git clean and pushed to remote
• Tools installed (Node, pnpm, Vercel CLI)

Validation Gate: Must score ≥80% to proceed

---

Phase 1: Environment Setup

Objective: Configure Vercel, Supabase, GitHub secrets Duration: 30-45 minutes (10-15 min with MCPs) See: Phase 1 Workflow

Extracts environment variables from planning docs and configures deployment infrastructure.

Key Steps:

• Extract environment variables from PRD and architecture
• Configure Vercel project (link or create)
• Configure Supabase production database
• Set GitHub secrets (VERCEL_TOKEN, etc.)
• Validate configuration completeness

Validation Gate: ≥90% configuration complete

---

Phase 2: Database Migration

Objective: Deploy database schema, RLS policies, seed data Duration: 30-45 minutes (10-15 min with MCP) See: Phase 2 Workflow

Generates migration SQL from data-models.md and applies to Supabase.

Key Steps:

• Generate SQL migration (CREATE TABLE, indexes, RLS)
• Validate SQL (conventions, constraints)
• Apply to Supabase (MCP or manual)
• Verify migration success

Validation Gate: All tables created, RLS enabled

---

Phase 3: Preview Deployment

Objective: Deploy to preview environment and validate Duration: 15-20 minutes See: Phase 3 Workflow

Builds and deploys to Vercel preview with smoke tests.

Key Steps:

• Build application (pnpm run build)
• Deploy to Vercel preview
• Run smoke tests (homepage, API, auth)
• Validate deployment

Validation Gate: ≥90% tests passing

---

Phase 4: Production Deployment

Objective: Configure domain and deploy to production Duration: 45-60 minutes (20-30 min with MCPs) See: Phase 4 Workflow

Sets up production domain, CI/CD workflows, and deploys.

Key Steps:

• Configure custom domain (DNS setup)
• Create GitHub Actions workflows (preview + production)
• Deploy to production (vercel --prod)
• Run production smoke tests

Validation Gate: All tests passing

---

Phase 5: Post-Deployment

Objective: Configure monitoring and validate readiness Duration: 30-45 minutes (15-20 min with MCPs) See: Phase 5 Workflow

Sets up monitoring, validates production readiness, creates documentation.

Key Steps:

• Configure monitoring & analytics (PostHog, Sentry, uptime)
• Run production readiness checklist (34 items, target 90%+)
• Create deployment documentation
• Display final summary

Completion: Deployment fully operational

---

State Management

See: State Management Guide

Location: .claude/deployment/state/{project-name}/deployment_state.json

Key Operations:

• Initialize: Create new state for deployment
• Load: Resume from existing state
• Update: Track progress after each phase
• Finalize: Mark deployment complete

State Schema: See State Template

Resume Capability: Load state anytime to continue from last phase

---

MCP Integration

See: MCP Integration Guide

Supports optional MCPs for 60% faster workflows:

• GitHub MCP: Automated issue tracking, workflow management
• Supabase MCP: Programmatic migrations, validation
• Vercel MCP: Automated configuration, deployments

Fallback Strategy: All MCP operations have CLI or manual fallbacks

---

Error Handling & Rollback

See: Error Handling Guide See: Rollback Procedures

Error Handling

• Phase-specific error recovery
• Clear error messages with solutions
• Retry mechanisms for transient failures
• State preservation on errors

Rollback Options

• Emergency rollback: vercel promote {previous-deployment}
• Staged rollback: Fix and retry preview
• Database rollback: DROP CASCADE + reapply (destructive)
• Configuration rollback: Update env vars, redeploy

---

Production Readiness Checklist

See: Production Readiness Checklist

7 Categories, 34 Items:

1. Legal & Content (7 items)
2. Security (5 items)
3. Email & Notifications (4 items)
4. Billing (5 items)
5. Database (4 items)
6. Monitoring & Analytics (4 items)
7. Design & UX (5 items)

Target Score: 90%+ before production launch

---

Reference Files

Core Concepts (5 files)

Location: references/core/

• Prerequisites - Detailed setup requirements
• Planning Integration - Artifact consumption
• State Management - State operations
• MCP Integration - MCP usage patterns
• Error Handling - Error recovery strategies

Phase Workflows (6 files)

Location: references/phases/

• Phase 0: Pre-Deployment Validation
• Phase 1: Environment Setup
• Phase 2: Database Migration
• Phase 3: Preview Deployment
• Phase 4: Production Deployment
• Phase 5: Post-Deployment

Additional References (3 files)

Location: references/core/ and references/workflows/

• Rollback Procedures - Safe rollback guide
• Initialization Workflow - Setup process
• Troubleshooting Guide - Common issues

Templates (4 files)

Location: templates/

• Deployment State Template - State schema
• Production Readiness Checklist - 34-item checklist
• Preview Workflow - GitHub Actions preview
• Production Workflow - GitHub Actions production

---

Success Metrics

You've successfully used this skill when:

• ✅ All 5 phases completed with passing validation (≥90%)
• ✅ Application deployed to production and accessible
• ✅ Database schema migrated successfully
• ✅ GitHub Actions workflows active
• ✅ Production readiness score ≥90%
• ✅ Monitoring and analytics configured
• ✅ Deployment documentation created
• ✅ State file shows "completed" status

---

Workflow Time Estimates

Workflow	Without MCPs	With MCPs	Savings
Phase 1: Environment Setup	30-45 min	10-15 min	67%
Phase 2: Database Migration	30-45 min	10-15 min	67%
Phase 3: Preview Deployment	15-20 min	10-15 min	25%
Phase 4: Production Deployment	45-60 min	20-30 min	56%
Phase 5: Post-Deployment	30-45 min	15-20 min	50%
Total	2.5-3.5 hours	1-1.5 hours	60%

---

Version History

v2.0.0 (2025-10-29):

• Refactored to <500 lines with progressive disclosure
• Organized 14 reference files + 4 templates
• Enhanced GitHub integration via github-issue-manager skill
• Improved MCP fallback strategies
• Comprehensive error handling and rollback procedures
• Production readiness validation

v1.0.0 (2025-10-28):

• Initial release with orchestrated workflow
• Integration with spec-planning outputs
• State management and resume capability
• GitHub MCP integration for automation
• Makerkit + Vercel deployment focus
• Production readiness validation
• Rollback procedures and error handling

---

Version: 2.0.0 Last Updated: 2025-10-29 Maintained by: Personal Workflow Workflow Mode: Orchestrated Integrates With: spec-planning, implementation, qa-validation