Update deployment skill documentation to reflect new 7-step workflow and directory structure. Enhance README with detailed usage instructions for the autopilot feature and clarify skill descriptions. Adjust paths for deployment templates to align with the updated documentation structure.

2026-04-22 09:16:38 +00:00 · 2026-03-19 17:05:59 +02:00
parent 05411d19b8
commit f70d701979
10 changed files with 921 additions and 50 deletions
@@ -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 complete | `observability.md` |
-| Step 5 | Deployment procedures documented | `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 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

@@ -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–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 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              │
 └────────────────────────────────────────────────────────────────┘
 ```