@@ -1,22 +1,22 @@
---
name: deploy
description: |
Comprehensive deployment skill covering containerization, CI/CD pipeline, environment strategy, observability, and deployment procedures.
5 -step workflow: Docker containerization, CI/CD pipeline definition, environment strategy, observability planning, deployment procedures.
Uses _docs/02_plans/ deployment / structure.
Comprehensive deployment skill covering status check, env setup, containerization, CI/CD pipeline, environment strategy, observability, deployment procedures, and deployment scripts .
7 -step workflow: Status & env check, Docker containerization, CI/CD pipeline definition, environment strategy, observability planning, deployment procedures, deployment scripts .
Uses _docs/04_ deploy/ structure.
Trigger phrases:
- "deploy", "deployment", "deployment strategy"
- "CI/CD", "pipeline", "containerize"
- "observability", "monitoring", "logging"
- "dockerize", "docker compose"
category: ship
tags: [deployment, docker, ci-cd, observability, monitoring, containerization]
tags: [deployment, docker, ci-cd, observability, monitoring, containerization, scripts ]
disable-model-invocation: true
---
# Deployment Planning
Plan and document the full deployment lifecycle: containerize the application, define CI/CD pipelines, configure environments, set up observability, and document deployment procedures.
Plan and document the full deployment lifecycle: check deployment status and environment requirements, containerize the application, define CI/CD pipelines, configure environments, set up observability, document deployment procedures, and generate deployment scripts .
## Core Principles
@@ -26,14 +26,16 @@ Plan and document the full deployment lifecycle: containerize the application, d
- **Environment parity**: dev, staging, and production environments mirror each other as closely as possible
- **Save immediately**: write artifacts to disk after each step; never accumulate unsaved work
- **Ask, don't assume**: when infrastructure constraints or preferences are unclear, ask the user
- **Plan, don't code**: this workflow produces deployment documents and specifications, not implementation code
- **Plan, don't code**: this workflow produces deployment documents and specifications, not implementation code (except deployment scripts in Step 7)
## Context Resolution
Fixed paths:
- PLANS_DIR: `_docs/02_plans/`
- DEPLOY_DIR: `_docs/02_plans/ deployment /`
- DEPLOY_DIR: `_docs/04_ deploy/`
- REPORTS_DIR: `_docs/04_deploy/reports/`
- SCRIPTS_DIR: `scripts/`
- ARCHITECTURE: `_docs/02_plans/architecture.md`
- COMPONENTS_DIR: `_docs/02_plans/components/`
@@ -55,7 +57,7 @@ Announce the resolved paths to the user before proceeding.
1. `architecture.md` exists — **STOP if missing ** , run `/plan` first
2. At least one component spec exists in `PLANS_DIR/components/` — **STOP if missing **
3. Create DEPLOY_DIR if it does not exist
3. Create DEPLOY_DIR, REPORTS_DIR, and SCRIPTS_DIR if they do not exist
4. If DEPLOY_DIR already contains artifacts, ask user: **resume from last checkpoint or start fresh? **
## Artifact Management
@@ -68,18 +70,33 @@ DEPLOY_DIR/
├── ci_cd_pipeline.md
├── environment_strategy.md
├── observability.md
└ ── deployment_procedures.md
├ ── deployment_procedures.md
├── deploy_scripts.md
└── reports/
└── deploy_status_report.md
SCRIPTS_DIR/ (project root)
├── deploy.sh
├── pull-images.sh
├── start-services.sh
├── stop-services.sh
└── health-check.sh
.env (project root, git-ignored)
.env.example (project root, committed)
```
### Save Timing
| Step | Save immediately after | Filename |
|------|------------------------|----------|
| Step 1 | Containerization plan complete | `containerization.md `
| Step 2 | CI/CD pipeline defined | `ci_cd_pipeline .md`
| Step 3 | Environment strategy documented | `environment_strategy .md`
| Step 4 | Observability plan comple te | `observabilit y.md` |
| Step 5 | Deployment procedures documen ted | `deployment_procedures .md` |
| Step 1 | Status check & env setup complete | `reports/deploy_status_report.md` + `.env` + `.env.example `
| Step 2 | Containerization plan complete | `containerization .md`
| Step 3 | CI/CD pipeline defined | `ci_cd_pipeline .md`
| Step 4 | Environment strategy documen ted | `environment_strateg y.md` |
| Step 5 | Observability plan comple te | `observability .md` |
| Step 6 | Deployment procedures documented | `deployment_procedures.md` |
| Step 7 | Deployment scripts created | `deploy_scripts.md` + scripts in `SCRIPTS_DIR/` |
### Resumability
@@ -92,11 +109,52 @@ If DEPLOY_DIR already contains artifacts:
## Progress Tracking
At the start of execution, create a TodoWrite with all steps (1 through 5 ). Update status as each step completes.
At the start of execution, create a TodoWrite with all steps (1 through 7 ). Update status as each step completes.
## Workflow
### Step 1: Containerization
### Step 1: Deployment Status & Environment Setup
**Role ** : DevOps / Platform engineer
**Goal ** : Assess current deployment readiness, identify all required environment variables, and create `.env` files
**Constraints ** : Must complete before any other step
1. Read architecture.md, all component specs, and restrictions.md
2. Assess deployment readiness:
- List all components and their current state (planned / implemented / tested)
- Identify external dependencies (databases, APIs, message queues, cloud services)
- Identify infrastructure prerequisites (container registry, cloud accounts, DNS, SSL certificates)
- Check if any deployment blockers exist
3. Identify all required environment variables by scanning:
- Component specs for configuration needs
- Database connection requirements
- External API endpoints and credentials
- Feature flags and runtime configuration
- Container registry credentials
- Cloud provider credentials
- Monitoring/logging service endpoints
4. Generate `.env.example` in project root with all variables and placeholder values (committed to VCS)
5. Generate `.env` in project root with development defaults filled in where safe (git-ignored)
6. Ensure `.gitignore` includes `.env` (but NOT `.env.example` )
7. Produce a deployment status report summarizing readiness, blockers, and required setup
**Self-verification ** :
- [ ] All components assessed for deployment readiness
- [ ] External dependencies catalogued
- [ ] Infrastructure prerequisites identified
- [ ] All required environment variables discovered
- [ ] `.env.example` created with placeholder values
- [ ] `.env` created with safe development defaults
- [ ] `.gitignore` updated to exclude `.env`
- [ ] Status report written to `reports/deploy_status_report.md`
**Save action ** : Write `reports/deploy_status_report.md` using `templates/deploy_status_report.md` , create `.env` and `.env.example` in project root
**BLOCKING ** : Present status report and environment variables to user. Do NOT proceed until confirmed.
---
### Step 2: Containerization
**Role ** : DevOps / Platform engineer
**Goal ** : Define Docker configuration for every component, local development, and integration test environments
@@ -117,7 +175,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda
- Database (Postgres) with named volume
- Any message queues, caches, or external service mocks
- Shared network
- Environment variable files (`.env.dev ` )
- Environment variable files (`.env` )
6. Define `docker-compose.test.yml` for integration tests:
- Application components under test
- Test runner container (black-box, no internal imports)
@@ -140,7 +198,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda
---
### Step 2 : CI/CD Pipeline
### Step 3 : CI/CD Pipeline
**Role ** : DevOps engineer
**Goal ** : Define the CI/CD pipeline with quality gates, security scanning, and multi-environment deployment
@@ -179,7 +237,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda
---
### Step 3 : Environment Strategy
### Step 4 : Environment Strategy
**Role ** : Platform engineer
**Goal ** : Define environment configuration, secrets management, and environment parity
@@ -194,7 +252,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda
| **Production ** | Live system | Full infrastructure | Real data |
2. Define environment variable management:
- `.env.example` with all required variables (no real values)
- Reference `.env.example` created in Step 1
- Per-environment variable sources (`.env` for dev, secret manager for staging/prod)
- Validation: fail fast on missing required variables at startup
3. Define secrets management:
@@ -209,7 +267,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda
**Self-verification ** :
- [ ] All three environments defined with clear purpose
- [ ] Environment variable documentation complete (`.env.example` )
- [ ] Environment variable documentation complete (references `.env.example` from Step 1 )
- [ ] No secrets in any output document
- [ ] Secret manager specified for staging/production
- [ ] Database strategy per environment
@@ -218,7 +276,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda
---
### Step 4 : Observability
### Step 5 : Observability
**Role ** : Site Reliability Engineer (SRE)
**Goal ** : Define logging, metrics, tracing, and alerting strategy
@@ -272,7 +330,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda
---
### Step 5 : Deployment Procedures
### Step 6 : Deployment Procedures
**Role ** : DevOps / Platform engineer
**Goal ** : Define deployment strategy, rollback procedures, health checks, and deployment checklist
@@ -321,6 +379,69 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda
---
### Step 7: Deployment Scripts
**Role ** : DevOps / Platform engineer
**Goal ** : Create executable deployment scripts for pulling Docker images and running services on the remote target machine
**Constraints ** : Produce real, executable shell scripts. This is the ONLY step that creates implementation artifacts.
1. Read containerization.md and deployment_procedures.md from previous steps
2. Read `.env.example` for required variables
3. Create the following scripts in `SCRIPTS_DIR/` :
* * `deploy.sh` ** — Main deployment orchestrator:
- Validates that required environment variables are set (sources `.env` if present)
- Calls `pull-images.sh` , then `stop-services.sh` , then `start-services.sh` , then `health-check.sh`
- Exits with non-zero code on any failure
- Supports `--rollback` flag to redeploy previous image tags
* * `pull-images.sh` ** — Pull Docker images to target machine:
- Reads image list and tags from environment or config
- Authenticates with container registry
- Pulls all required images
- Verifies image integrity (digest check)
* * `start-services.sh` ** — Start services on target machine:
- Runs `docker compose up -d` or individual `docker run` commands
- Applies environment variables from `.env`
- Configures networks and volumes
- Waits for containers to reach healthy state
* * `stop-services.sh` ** — Graceful shutdown:
- Stops services with graceful shutdown period
- Saves current image tags for rollback reference
- Cleans up orphaned containers/networks
* * `health-check.sh` ** — Verify deployment health:
- Checks all health endpoints
- Reports status per service
- Returns non-zero if any service is unhealthy
4. All scripts must:
- Be POSIX-compatible (#!/bin/bash with set -euo pipefail)
- Source `.env` from project root or accept env vars from the environment
- Include usage/help output (`--help` flag)
- Be idempotent where possible
- Handle SSH connection to remote target (configurable via `DEPLOY_HOST` env var)
5. Document all scripts in `deploy_scripts.md`
**Self-verification ** :
- [ ] All five scripts created and executable
- [ ] Scripts source environment variables correctly
- [ ] `deploy.sh` orchestrates the full flow
- [ ] `pull-images.sh` handles registry auth and image pull
- [ ] `start-services.sh` starts containers with correct config
- [ ] `stop-services.sh` handles graceful shutdown
- [ ] `health-check.sh` validates all endpoints
- [ ] Rollback supported via `deploy.sh --rollback`
- [ ] Scripts work for remote deployment via SSH (DEPLOY_HOST)
- [ ] `deploy_scripts.md` documents all scripts
**Save action ** : Write scripts to `SCRIPTS_DIR/` , write `deploy_scripts.md` using `templates/deploy_scripts.md`
---
## Escalation Rules
| Situation | Action |
@@ -331,33 +452,40 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda
| Secret manager not chosen | **ASK user ** |
| Deployment pattern trade-offs | **ASK user ** with recommendation |
| Missing architecture.md | **STOP ** — run `/plan` first |
| Remote target machine details unknown | **ASK user ** for SSH access, OS, and specs |
## Common Mistakes
- **Implementing during planning**: this workflow produces documents, not Dockerfiles or pipeline YAML
- **Hardcoding secrets**: never include real credentials in deployment documents
- **Implementing during planning**: Steps 1– produce documents, not code (Step 7 is the exception — it creates scripts)
- **Hardcoding secrets**: never include real credentials in deployment documents or scripts
- **Ignoring integration test containerization**: the test environment must be containerized alongside the app
- **Skipping BLOCKING gates**: never proceed past a BLOCKING marker without user confirmation
- **Using `:latest` tags**: always pin base image versions
- **Forgetting observability**: logging, metrics, and tracing are deployment concerns, not post-deployment additions
- **Committing `.env` **: only `.env.example` goes to version control; `.env` must be in `.gitignore`
- **Non-portable scripts**: deployment scripts must work across environments; avoid hardcoded paths
## Methodology Quick Reference
```
┌────────────────────────────────────────────────────────────────┐
│ Deployment Planning (5 -Step Method) │
│ Deployment Planning (7 -Step Method) │
├────────────────────────────────────────────────────────────────┤
│ PREREQ: architecture.md + component specs exist │
│ PREREQ: architecture.md + component specs exist │
│ │
│ 1. Containerization → containerization.md │
│ [BLOCKING: user confirms Docker plan] │
│ 2. CI/CD Pipeline → ci_cd_pipeline.md │
│ 3 . Environment → environment_strategy.md │
│ 4. Observability → observability.md │
│ 5 . Procedures → deployment_procedures.md │
│ [BLOCKING: user confirms deployment plan] │
│ 1. Status & Env → reports/deploy_status_report.md │
│ + .env + .env.example │
│ [BLOCKING: user confirms status & env vars] │
│ 2 . Containerization → containerization.md │
│ [BLOCKING: user confirms Docker plan] │
│ 3 . CI/CD Pipeline → ci_cd_pipeline.md │
│ 4. Environment → environment_strategy.md │
│ 5. Observability → observability.md │
│ 6. Procedures → deployment_procedures.md │
│ [BLOCKING: user confirms deployment plan] │
│ 7. Scripts → deploy_scripts.md + scripts/ │
├────────────────────────────────────────────────────────────────┤
│ Principles: Docker-first · IaC · Observability built-in │
│ Environment parity · Save immediately │
│ Principles: Docker-first · IaC · Observability built-in │
│ Environment parity · Save immediately │
└────────────────────────────────────────────────────────────────┘
```
Oleksandr Bezdieniezhnykh