deployment

name	deployment
description	Produces a DEPLOY-PLAN.md (artifact, environment, health check, rollback, cutover) so the eventual ship is observable and reversible; primes the testing + security + observability gates. Use to plan a deployment before executing it.

deployment

The deployment-planning producer of the ops domain — it writes a DEPLOY-PLAN.md: the artifact, the target environment, the health check that defines post-deploy "green", the rollback, and the cutover strategy. The point is to make the eventual ship observable (a concrete health check is the Observation target) and reversible (a proven rollback). It plans the deploy; it does not execute it — ops verifies by Observation of a live resource, and a pre-execution plan has nothing live to observe, so the plan verifies by Review (sound / reversible / observable?), with the health-green Observation deferred to the execution wave that runs it. A skill never ships to production or fabricates a "healthy".

What this does / does not do

Does: resolve the deployment sub_target, write a DEPLOY-PLAN.md declaring artifact + environment + health check + rollback + cutover + the pre-go-live checklist (observability wired, change approval), and a receipt; the plan verifies by Review and names the Observation the execution wave will check. Does not: run the deploy, ship the artifact, touch production or infrastructure (the execution wave does, verified by Observation), provision infra (infrastructure) or move data (migration), or claim a deploy is healthy before it has run.

When NOT to use

• The work is executing the ship / running the rollout — that is the execution wave (Observation on the live resource), not the plan-producer.
• The work is provisioning or changing infrastructure (IaC) — that is the infrastructure sub_target; or a data/schema move — that is migration.
• A current DEPLOY-PLAN.md still fits and nothing changed — editing it beats rewriting a plan the run follows.
• The artifact does not exist yet / is not built — build it first (the software domain); a deploy plan for a nonexistent artifact is premature.

Reference Routing

Situation	Reference
The DEPLOY-PLAN.md contract template	references/deploy-plan-template.md
Per-sub_target must-declares · overlay · vocabulary	../acceptance/sub-targets.md · ../acceptance/overlay.md · ../vocabulary.md
Sibling ops sub_targets (infra / data moves)	infrastructure · migration

Inputs

• The artifact to ship (build output / release + version) and the target environment + its config.
• The existing health-check / observability context (what "green" looks like; what monitors exist).
• The ops domain pack (../vocabulary.md, ../acceptance/) + state/intake.json.

How to do it

1. Declare artifact + environment: what is shipping (name + version + provenance) and where (target environment + the config that differs from other environments).
2. Define the health check (the Observation target): the concrete, observable signal that defines post-deploy "green" — an endpoint + expected response, a metric threshold, a synthetic check. The execution wave observes this; "green" is defined here, not improvised later.
3. Specify the rollback: how to revert (previous version / down-migration / traffic shift), and the evidence it is reversible — a rollback before any production change is the ordering rule.
4. Choose the cutover: the downtime posture (zero, or a declared window) and the strategy that meets it (blue-green / canary / rolling), with the step sequence and the abort condition.
5. Wire observability + approval before go-live: confirm monitoring / alerting / logging are in place before the cutover (not after), and record the change approval + audit trail. Keep secrets out of the plan — reference a secret store, never inline a credential (the security gate).
6. State the verification handoff: the plan verifies by Review now; the live Observation (health green) runs in the execution wave — record that, do not pre-claim a healthy deploy.
7. Write DEPLOY-PLAN.md from references/deploy-plan-template.md; name the change owner.

Gate (before marking complete)

• Artifact + target environment declared, with a concrete observable health check ("green" is defined).
• A rollback is specified and shown reversible (no deploy without one).
• A downtime posture + cutover strategy (blue-green / canary / rolling) are stated.
• Monitoring / alerting / logging are wired before go-live; change approval + audit recorded.
• No credentials/secrets inline; secrets handling + least-privilege stated (security).
• The plan verifies by Review; the live Observation is deferred to the execution wave (not pre-claimed).

A gate failure is fixed before lock, not waived — these mirror the testing/security/observability gates.

Output

• DEPLOY-PLAN.md at the product root (or deploy/DEPLOY-PLAN.md if that dir exists) — persistence: Spec-Anchored. Artifact + environment · health check (Observation target) · rollback (reversible) · cutover (downtime posture + strategy) · pre-go-live checklist · change owner.
• receipt (<workspace>/receipts/deployment-receipt-<ts>.json): base schema + sub_target, artifact, environment, health_check, rollback, cutover, deploy_plan_path, observation_deferred, gate_checks. persistence: Spec-Anchored.

Proactive Triggers

• A plan with no health check: define the observable that means "green", or Observation at execution has no target — an unobservable deploy cannot be verified.
• No rollback: stop — a production change with no proven revert path fails the gate; rollback comes before the change.
• A credential inline in the plan: replace it with a secret-store reference (the security gate); creds never live in the plan or state.
• A "deployed and healthy" claim on an unexecuted plan: the plan is Review-verified; healthy is observed on the live run — do not fabricate it.

Completion Criteria

Done when: a DEPLOY-PLAN.md exists with artifact + environment + a concrete health check, a reversible rollback, a cutover strategy + downtime posture, observability + approval wired before go-live, and no inline secrets; the plan is Review-verified with the live Observation deferred; a deployment receipt records the gate checks.

Not done if: there is no observable health check; no rollback; secrets are inline; observability is deferred to after go-live; or the plan claims a healthy deploy it never ran.

Next step: the execution wave runs the plan and is verified by Observation (health check green, or the rollback fires); infrastructure/migration handle any infra or data prerequisites.

Related Skills

• infrastructure / migration: sibling ops sub_targets — provision infra / move data. deployment ships the release; it depends on those being in the expected state.
• runbook: the operational procedure (often the deploy/rollback steps as an SOP). deployment plans a specific ship; a runbook is the repeatable procedure.
• incident-response: when a deploy goes wrong — diagnose, remediate, postmortem. deployment's rollback is the first move it relies on.