# Deployment Planner

> Plan service units, runtime entry points, local startup, Docker, Kubernetes/Helm, and required deployment assets from confirmed scope. Use after devops-agent routes deployment planning.

- Skill: `neplich/deployment-planner` (Agent Skill)
- Install (CLI): `npx skillmds@latest add neplich/deployment-planner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/neplich/deployment-planner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Neplich (https://skillmd.com/u/neplich)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/neplich/deployment-planner

---


# Deployment Planner

Generate deployment configurations for the confirmed target matrix. Local
development, Docker containerization, and Kubernetes (Helm) orchestration are
available targets, not defaults.

## Reader-Facing Writing Composition

For substantial reader-facing prose, co-load `human-writing` even on direct
invocation; use the same context, not a later pass. This Skill retains evidence,
facts, required structure, paths, gates, and verification. Skip code-, config-, schema-,
lockfile-, and data-only output.

## Mandatory Deployment Matrix

For each confirmed variant, record the complete unit chain: build target,
context, static entry, image unit, Compose topology, Kubernetes/Helm resource,
values, health check, runtime entry, and disposition. Missing evidence is `blocked` or
an explicitly approved alternative, never silently omitted. Hand every
confirmed image/runtime unit and its immutable tag, architecture, registry,
trigger, and verification requirement to `cicd-bootstrap`; do not claim CI/CD
coverage until that handoff is complete.

## When to Use

- TRD or engineering docs specify deployment requirements
- User asks to set up or update deployment infrastructure
- Project is ready for production deployment
- Need to create deployment configurations from scratch
- Existing deployment config must be extended for a new service, worker, or microservice
- Existing deployment targets must be expanded or revised, such as adding Docker, Helm, staging, or production variants

## PM Handoff Entry Gate

Before planning deployment assets, require a PM/DevOps handoff packet or
equivalent confirmed operational context. Confirmed repo-wide deployment work
may use `N/A` feature scope; feature-scoped work needs the confirmed
`feature_path`. If the user directly invokes this specialist without that
context, return the request to `pm-agent` for classification.

A maintainer-supplied inventory that names the existing build variants and
their deployment coverage is equivalent confirmed operational context for a
read-only completeness assessment. Produce the requested per-variant matrix;
treat facts absent from that inventory as field-level `blocked` gaps instead
of returning the whole assessment to PM.

Use the PM-side packet definition in
the plugin-local generated `../devops-agent/_internal/_generated/shared-contracts/handoff-contract.md`.

## Context Preflight

宿主存在 `docs/site/standards/change-map.yaml` 时，项目探索先按 pm-agent 维护的 `consumption-contract.md`（the plugin-local generated `../devops-agent/_internal/_generated/shared-contracts/consumption-contract.md`）执行“任务落点 → change-map 反查 → 精准读取 → 关键判断回代码验证”；不存在时静默沿用当前代码探索。

Before generating anything, inspect:

- the current codebase shape and runtime stack
- relevant engineering docs and PM deployment requirements when they exist
- the deployment target matrix
- whether `deploy/` already exists
- whether the work is repo-wide or feature-scoped
- for feature-scoped work, the confirmed `feature_path` and the matching
  `docs/engineer/{feature_path}/TRD.md` and
  `docs/engineer/{feature_path}/IMPLEMENTATION_PLAN.md`

Determine the target matrix before generating any files. When the TRD or PM
handoff packet explicitly names deployment targets, generate only those
targets. Otherwise, infer targets only when existing deployment assets such as
`deploy/` or CI configuration provide sufficient evidence. If neither source
defines the targets clearly, ask the user which targets are required. Never
default to generating local, Docker, and Helm together.

If `deploy/` already exists, prefer extension or targeted iteration over blind regeneration.

For a documentation-site completeness handoff, enumerate Public, Internal, and
every host-specific build variant before writing. Build a per-variant matrix of
build target, context, static entry, image unit, Compose topology, Kubernetes /
Helm resources, values, health checks, and runtime entry. Do not claim completeness
until every variant has an explicit integrated, alternative-hosted, deferred,
or blocked disposition.

If the request appears feature-scoped but the `feature_path` is unclear, do not
invent a new top-level DevOps directory. Return to PM for PRD/path clarification
or to Engineer when the TRD or implementation plan is missing or inconsistent.

## Input Requirements

Read from engineering docs, PM docs, or ask the user:
- **Tech stack**: Language, framework, database
- **Scale**: Expected users, traffic volume
- **Environment needs**: staging/production split
- **Deployment targets**: Local, Docker, Kubernetes/Helm, or another confirmed target
- **Dependencies**: External services, databases

## Step 1 — Analyze Project Requirements

Read TRD to extract:
- Application type (web app, API, full-stack)
- Runtime requirements (Node.js, Python, Go, etc.)
- Database needs (PostgreSQL, MySQL, Redis, etc.)
- External dependencies (S3, email service, etc.)

When a feature scope exists, read the TRD from
`docs/engineer/{feature_path}/TRD.md` and mirror any deployment constraints into
feature-scoped notes under `docs/devops/{feature_path}/...`. Repo-wide deploy
assets still belong under `deploy/`.

If no durable deployment requirements exist, ask the user:
1. What type of application is this?
2. What runtime/language does it use?
3. Does it need a database? Which one?
4. Any external services required?
5. Which deployment targets are required?

## Step 2 — Local Development Target Reference (`deploy/local/`)

When the target matrix includes local development, generated assets must
document prerequisites and dependencies, quick start and startup behavior,
required environment variables, and database setup or migrations when needed.

Reference structure:
```
deploy/local/
├── README.md
├── .env.example
└── start.sh
```

An environment example may include:
```
DATABASE_URL=postgresql://localhost:5432/myapp_dev
REDIS_URL=redis://localhost:6379
API_KEY=your_api_key_here
```

The startup entry should:
- Checks prerequisites
- Starts database (if needed)
- Runs migrations
- Starts the application

## Step 3 — Docker Target Reference (`deploy/docker/`)

When the target matrix includes Docker, generated assets must document Docker
and Compose prerequisites, build and run commands, port mappings, volume
mounts, environment variables, and service dependencies.

Reference structure:
```
deploy/docker/
├── README.md
├── Dockerfile
├── docker-compose.yml
└── .env.example
```

The Dockerfile should:
- Use official base images
- Install dependencies
- Copy application code
- Set up non-root user
- Expose ports

The Compose setup should define:
- Application container
- Database container (if needed)
- Redis/cache (if needed)
- Network configuration
- Volume persistence

## Step 4 — Kubernetes/Helm Target Reference (`deploy/helm/`)

When the target matrix includes Kubernetes/Helm, generated assets must document
Helm prerequisites, chart installation, configuration options, scaling, and
runtime dependencies.

Reference structure:
```
deploy/helm/
├── README.md
├── Chart.yaml
├── values.yaml
└── templates/
    ├── deployment.yaml
    ├── service.yaml
    ├── ingress.yaml
    ├── configmap.yaml
    ├── secret.yaml
    └── hpa.yaml
```

Default values should cover:
- Replica count
- Image repository and tag
- Resource limits (CPU, memory)
- Service type and ports
- Ingress configuration
- Environment variables

Kubernetes resource templates should cover:
- `deployment.yaml` - Application deployment
- `service.yaml` - Service definition
- `ingress.yaml` - Ingress rules (if needed)
- `configmap.yaml` - Configuration
- `secret.yaml` - Secrets template
- `hpa.yaml` - Horizontal Pod Autoscaler (if needed)

## Step 5 — Verify Directory Structure

Verify only the targets selected in the target matrix:

```bash
tree deploy/
```

Compare the result with the selected target reference structures and confirm
that each target includes its required usage, environment, startup, and
dependency information.

## Step 6 — Summary

Output:
```
## 部署配置生成完成

目标矩阵：
- <target>: <created path and startup/install command>

未选择的目标：
- <target>: <reason omitted>

### 下一步建议
- 使用 `cicd-bootstrap` skill 搭建自动化部署流程
- 使用 `env-config-auditor` skill 检查配置完整性
```

## Edge Cases

- **No database**: Skip database-related configurations
- **Monorepo**: Generate separate configs for each service
- **Existing deploy/ directory**: Ask user before overwriting
- **Target not selected**: Do not generate Helm when Kubernetes is absent from
  the target matrix, or Docker assets when containerization is absent
- **Unsupported tech stack**: Search for official deployment guides

## Output Rules

- Primary outputs belong under `deploy/`
- Feature-scoped deployment notes, release constraints, or readiness reports
  belong under `docs/devops/{feature_path}/...`
- Prefer executable config over prose-only explanation
- Add `README.md` files only where they help someone use the generated deployment assets
- Do not automatically create CI/CD config here; hand off to `cicd-bootstrap` when needed
- Hand every confirmed documentation image unit and variant matrix to
  `cicd-bootstrap`; do not implement its CI/CD rules here