ai-training/.cursor/skills/deploy/SKILL.md

name, description, category, tags, disable-model-invocation

name	description	category	tags	disable-model-invocation
deploy	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"	ship	deployment docker ci-cd observability monitoring containerization scripts	true

Deployment Planning

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

• Docker-first: every component runs in a container; local dev, blackbox tests, and production all use Docker
• Infrastructure as code: all deployment configuration is version-controlled
• Observability built-in: logging, metrics, and tracing are part of the deployment plan, not afterthoughts
• 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 (except deployment scripts in Step 7)

Context Resolution

Fixed paths:

• DOCUMENT_DIR: _docs/02_document/
• DEPLOY_DIR: _docs/04_deploy/
• REPORTS_DIR: _docs/04_deploy/reports/
• SCRIPTS_DIR: scripts/
• ARCHITECTURE: _docs/02_document/architecture.md
• COMPONENTS_DIR: _docs/02_document/components/

Announce the resolved paths to the user before proceeding.

Input Specification

Required Files

File	Purpose	Required
_docs/00_problem/problem.md	Problem description and context	Greenfield only
_docs/00_problem/restrictions.md	Constraints and limitations	Greenfield only
_docs/01_solution/solution.md	Finalized solution	Greenfield only
DOCUMENT_DIR/architecture.md	Architecture (from plan or document skill)	Always
DOCUMENT_DIR/components/	Component specs	Always

Prerequisite Checks (BLOCKING)

1. architecture.md exists — STOP if missing, run /plan first
2. At least one component spec exists in DOCUMENT_DIR/components/ — STOP if missing
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

Directory Structure

DEPLOY_DIR/
├── containerization.md
├── ci_cd_pipeline.md
├── environment_strategy.md
├── observability.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	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 documented	environment_strategy.md
Step 5	Observability plan complete	observability.md
Step 6	Deployment procedures documented	deployment_procedures.md
Step 7	Deployment scripts created	deploy_scripts.md + scripts in SCRIPTS_DIR/

Resumability

If DEPLOY_DIR already contains artifacts:

1. List existing files and match to the save timing table
2. Identify the last completed step
3. Resume from the next incomplete step
4. Inform the user which steps are being skipped

Progress Tracking

At the start of execution, create a TodoWrite with all steps (1 through 7). Update status as each step completes.

Workflow

Step 1: Deployment Status & Environment Setup

Read and follow steps/01_status-env.md.

---

Step 2: Containerization

Read and follow steps/02_containerization.md.

---

Step 3: CI/CD Pipeline

Read and follow steps/03_ci-cd-pipeline.md.

---

Step 4: Environment Strategy

Read and follow steps/04_environment-strategy.md.

---

Step 5: Observability

Read and follow steps/05_observability.md.

---

Step 6: Deployment Procedures

Read and follow steps/06_procedures.md.

---

Step 7: Deployment Scripts

Read and follow steps/07_scripts.md.

Escalation Rules

Situation	Action
Unknown cloud provider or hosting	ASK user
Container registry not specified	ASK user
CI/CD platform preference unclear	ASK user — default to GitHub Actions
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: Steps 1–6 produce documents, not code (Step 7 is the exception — it creates scripts)
• Hardcoding secrets: never include real credentials in deployment documents or scripts
• Ignoring blackbox 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 (7-Step Method)                  │
├────────────────────────────────────────────────────────────────┤
│ PREREQ: architecture.md + component specs exist                │
│                                                                │
│ 1. Status & Env     → steps/01_status-env.md                   │
│                       → reports/deploy_status_report.md         │
│                       + .env + .env.example                    │
│    [BLOCKING: user confirms status & env vars]                 │
│ 2. Containerization → steps/02_containerization.md             │
│                       → containerization.md                    │
│    [BLOCKING: user confirms Docker plan]                       │
│ 3. CI/CD Pipeline   → steps/03_ci-cd-pipeline.md               │
│                       → ci_cd_pipeline.md                      │
│ 4. Environment      → steps/04_environment-strategy.md         │
│                       → environment_strategy.md                │
│ 5. Observability    → steps/05_observability.md                │
│                       → observability.md                       │
│ 6. Procedures       → steps/06_procedures.md                   │
│                       → deployment_procedures.md               │
│    [BLOCKING: user confirms deployment plan]                   │
│ 7. Scripts          → steps/07_scripts.md                      │
│                       → deploy_scripts.md + scripts/           │
├────────────────────────────────────────────────────────────────┤
│ Principles: Docker-first · IaC · Observability built-in        │
│             Environment parity · Save immediately              │
└────────────────────────────────────────────────────────────────┘