@chllming/wave-orchestration 0.5.4 → 0.6.1

package/skills/provider-docker-compose/skill.json

@@ -1,5 +1,53 @@
 {
   "id": "provider-docker-compose",
   "title": "Docker Compose",
-  "description": "Docker Compose environment and rollout norms."
+  "description": "Guides deploy verification against Docker Compose services: container health, local vs production readiness distinction, and dependency ordering.",
+  "activation": {
+    "when": "Attach when the wave deploy surface is Docker Compose and the agent must reason about service/container health ordering.",
+    "roles": [
+      "deploy",
+      "infra",
+      "integration",
+      "cont-qa"
+    ],
+    "runtimes": [],
+    "deployKinds": [
+      "docker-compose"
+    ]
+  },
+  "termination": "Stop when container health evidence and dependency ordering are explicit.",
+  "permissions": {
+    "network": [],
+    "shell": [
+      "docker",
+      "docker-compose"
+    ],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "deploy-docker-compose",
+      "role": "deploy",
+      "runtime": "opencode",
+      "deployKind": "docker-compose",
+      "expectActive": true
+    },
+    {
+      "id": "cont-qa-docker-compose",
+      "role": "cont-qa",
+      "runtime": "claude",
+      "deployKind": "docker-compose",
+      "expectActive": true
+    },
+    {
+      "id": "documentation-docker-compose",
+      "role": "documentation",
+      "runtime": "claude",
+      "deployKind": "docker-compose",
+      "expectActive": false
+    }
+  ]
 }

package/skills/provider-github-release/SKILL.md

@@ -1,6 +1,121 @@
 # GitHub Release
 
-- Keep tag names, release ids, asset names, and notes exact.
+<!-- CUSTOMIZE: Add your tag naming convention, required assets, release note template, and dependent deploys below. -->
+
+## Core Rules
+
+- Keep tag names, release IDs, asset names, and notes exact.
 - Distinguish draft, prerelease, and published release state explicitly.
 - Treat release notes, attached artifacts, and publication state as separate proof surfaces.
 - If publication depends on another deploy system, keep that dependency explicit.
+- Do not claim "released" until the release is published (not draft), all required assets are uploaded, and dependent deploys are confirmed.
+
+## Release State Model
+
+GitHub releases have three distinct states. Each is a separate proof surface:
+
+### Draft
+
+- Not visible to the public.
+- Editable: notes, assets, tag, and title can all be modified.
+- Use drafts for staging releases before all verification is complete.
+- A draft release is NOT a published release. Do not emit success markers for draft state.
+
+### Prerelease
+
+- Visible to the public but flagged as prerelease.
+- Appears in the releases list with a "Pre-release" badge.
+- Use for release candidates, beta builds, or staged rollouts.
+- A prerelease is public but carries an explicit "not stable" signal.
+
+### Published
+
+- Full release, visible to all users.
+- Appears as the "Latest release" if it has the highest semver tag (unless another release is pinned).
+- This is the only state that satisfies "release complete" in exit contracts.
+
+When reporting release state, name which of the three states the release is in. Do not use ambiguous terms like "created" or "exists."
+
+## Verification Procedures
+
+### Release Status
+
+```
+gh release view <tag> --repo <owner/repo>
+gh release view <tag> --repo <owner/repo> --json tagName,isDraft,isPrerelease,publishedAt,name
+```
+
+Confirm: release exists, state matches expectations (draft/prerelease/published), tag is correct, title and body are present.
+
+### Tag Existence
+
+```
+git tag -l <tag>
+gh api repos/<owner>/<repo>/git/refs/tags/<tag>
+```
+
+Confirm: tag exists in the repository, points to the correct commit. If the tag does not exist, the release cannot be finalized.
+
+### Asset Listing
+
+```
+gh release view <tag> --repo <owner/repo> --json assets
+```
+
+Confirm: all required assets are listed, each asset has size > 0, names match expected conventions. If checksums are required, verify checksum files are present.
+
+### Release Notes Content
+
+```
+gh release view <tag> --repo <owner/repo> --json body
+```
+
+Confirm: release notes contain required sections (changelog, breaking changes, migration notes as applicable), no placeholder text remains, links are valid.
+
+<!-- CUSTOMIZE: Add your project-specific verification commands or asset naming conventions here. -->
+
+## Asset Management
+
+Verify each asset individually:
+
+1. **Presence** -- the asset appears in the asset list with the expected name.
+2. **Size** -- the asset size is greater than zero. A zero-byte asset indicates an upload failure.
+3. **Checksum** -- if the project requires checksums (SHA256, MD5), verify the checksum file is present and its content matches the corresponding asset.
+4. **Content type** -- if specific MIME types are expected, verify them.
+
+Do not claim the release is complete until all required assets are uploaded and verified. If any asset is missing or zero-byte, the release is incomplete.
+
+Upload assets using:
+
+```
+gh release upload <tag> <file> --repo <owner/repo>
+```
+
+## Cross-System Dependencies
+
+Releases often depend on other systems being in a verified state before publication:
+
+- **Deployment dependency** -- if the release depends on a successful deploy (e.g., Railway, AWS, npm), verify the deploy is healthy before publishing the release.
+- **Registry dependency** -- if the release includes a package published to npm, PyPI, or another registry, verify the package is available in the registry before publishing the GitHub release.
+- **CI dependency** -- if the release requires CI checks to pass on the release commit, verify all required checks are green.
+
+Keep each dependency explicit:
+
+```
+Dependency: <system> must be <state> before release can be published.
+Status: <verified|pending|failed>
+Evidence: <how-verified>
+```
+
+Do not publish a release with unverified dependencies. Record the unverified dependency as a blocker.
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Tag naming convention: v<major>.<minor>.<patch>, v<major>.<minor>.<patch>-rc.<n>
+  - Required assets: <comma-separated-list-of-filenames>
+  - Checksum requirements: SHA256, MD5, none
+  - Release note template sections: Changelog, Breaking Changes, Migration Guide
+  - Dependent deploys: <system> -> <verification-command>
+  - Auto-publish conditions: all CI checks green + all assets uploaded
+-->

package/skills/provider-github-release/adapters/claude.md

@@ -0,0 +1 @@
+Prefer the `gh` CLI for release operations: `gh release view`, `gh release create`, `gh release upload`. Use `--json` flag for machine-readable output. Verify tag existence with `git tag -l` before creating releases. Use MCP GitHub tools when available for issue and PR cross-references.

package/skills/provider-github-release/adapters/codex.md

@@ -0,0 +1 @@
+Use the `gh` CLI with `--json` for release verification. If `gh` is not available in the sandbox, use `git tag -l` for tag verification and record the release verification gap. Keep all release operations deterministic and non-interactive.

package/skills/provider-github-release/skill.json

@@ -1,5 +1,55 @@
 {
   "id": "provider-github-release",
   "title": "GitHub Release",
-  "description": "GitHub release and tag publication norms."
+  "description": "Guides GitHub release verification: release state model, asset management, tag and publication proof, and cross-system dependency tracking.",
+  "activation": {
+    "when": "Attach when the wave deploy surface is a GitHub Release and the agent must verify publication state, tags, and assets.",
+    "roles": [
+      "deploy",
+      "infra",
+      "integration",
+      "cont-qa"
+    ],
+    "runtimes": [],
+    "deployKinds": [
+      "github-release"
+    ]
+  },
+  "termination": "Stop when release publication evidence is captured and cross-system dependencies are explicit.",
+  "permissions": {
+    "network": [
+      "github.com"
+    ],
+    "shell": [
+      "gh",
+      "git"
+    ],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "deploy-github-release",
+      "role": "deploy",
+      "runtime": "opencode",
+      "deployKind": "github-release",
+      "expectActive": true
+    },
+    {
+      "id": "integration-github-release",
+      "role": "integration",
+      "runtime": "claude",
+      "deployKind": "github-release",
+      "expectActive": true
+    },
+    {
+      "id": "documentation-github-release",
+      "role": "documentation",
+      "runtime": "claude",
+      "deployKind": "github-release",
+      "expectActive": false
+    }
+  ]
 }

package/skills/provider-kubernetes/SKILL.md

@@ -1,6 +1,143 @@
 # Kubernetes
 
+<!-- CUSTOMIZE: Add your cluster names, namespaces, workload names, and health probe paths below. -->
+
+## Core Rules
+
 - Name the exact cluster, namespace, workload, and rollout surface involved.
 - Prefer explicit `kubectl` state, health, and event evidence over generic rollout notes.
 - Distinguish manifest drift, admission failure, image failure, and readiness failure.
 - If rollback or restart is involved, make the operator-visible recovery posture explicit.
+- Always specify `--context` or `--kubeconfig` when multiple clusters are accessible.
+
+## Resource Identification
+
+Every Kubernetes verification must specify:
+
+- **Cluster name** -- the cluster context name as it appears in kubeconfig.
+- **Namespace** -- the Kubernetes namespace. Never omit this; do not rely on the default namespace.
+- **Workload type** -- Deployment, StatefulSet, DaemonSet, Job, CronJob, or bare Pod.
+- **Resource name** -- the exact name of the workload resource.
+
+Example: `Deployment api-server in namespace production, cluster prod-us-east-1`.
+
+## Verification Procedures
+
+### Pod State
+
+```
+kubectl get pods -n <namespace> -l app=<label> --context <cluster>
+kubectl describe pod <pod-name> -n <namespace> --context <cluster>
+```
+
+Confirm: all pods in `Running` state, restart count is zero or stable, no pods in `CrashLoopBackOff`, `ImagePullBackOff`, or `Pending`.
+
+### Deployment and Rollout
+
+```
+kubectl get deploy <name> -n <namespace> --context <cluster>
+kubectl rollout status deploy/<name> -n <namespace> --context <cluster>
+kubectl get replicasets -n <namespace> -l app=<label> --context <cluster>
+```
+
+Confirm: desired replicas match ready replicas, rollout is complete (not progressing or stalled), only one active ReplicaSet for the current revision.
+
+### Services and Endpoints
+
+```
+kubectl get svc <name> -n <namespace> --context <cluster>
+kubectl get endpoints <name> -n <namespace> --context <cluster>
+```
+
+Confirm: service exists, endpoints list is non-empty and matches expected pod count, port mappings are correct.
+
+### Events
+
+```
+kubectl get events -n <namespace> --sort-by=.lastTimestamp --context <cluster>
+kubectl describe deploy <name> -n <namespace> --context <cluster>
+```
+
+Check for: `FailedScheduling`, `FailedMount`, `Unhealthy`, `BackOff`, `FailedCreate`, or admission webhook rejection events.
+
+### Application Logs
+
+```
+kubectl logs deploy/<name> -n <namespace> --tail=100 --context <cluster>
+kubectl logs <pod-name> -n <namespace> -c <container> --tail=100 --context <cluster>
+```
+
+Confirm: no unhandled exceptions, startup completed successfully, application-level health indicators are positive.
+
+<!-- CUSTOMIZE: Add verification procedures for Ingress, HPA, PDB, ConfigMaps, or Secrets checks specific to your project here. -->
+
+## Failure Classification
+
+Classify Kubernetes failures precisely:
+
+### Manifest Drift
+
+- Desired spec does not match actual running state.
+- Symptom: `kubectl diff` shows changes, ReplicaSet count mismatch, container image tag differs from expected.
+- Fix: re-apply manifests or investigate what modified the live state.
+
+### Admission Failure
+
+- Webhook or policy controller rejected the resource creation or update.
+- Symptom: events show `admission webhook denied`, OPA/Gatekeeper/Kyverno policy violation.
+- Fix: update the manifest to comply with policy, or update the policy if the manifest is correct.
+
+### Image Failure
+
+- Container image cannot be pulled or crashes immediately on start.
+- Symptom: `ImagePullBackOff` (registry auth, image not found, tag not found) or `CrashLoopBackOff` (image starts and exits non-zero).
+- Fix: verify image exists in registry, check pull secrets, check application startup for fatal errors.
+
+### Readiness Failure
+
+- Pod is running but not passing readiness probes.
+- Symptom: pod shows `Running` but `0/1 Ready`, endpoints list is empty, service returns 503.
+- Fix: check readiness probe configuration (path, port, timeout), check application health endpoint, check dependencies the app needs at startup.
+
+Name the failure type explicitly in the `[deploy-status]` marker detail field.
+
+## Recovery Posture
+
+### Rollback
+
+```
+kubectl rollout undo deploy/<name> -n <namespace> --context <cluster>
+kubectl rollout status deploy/<name> -n <namespace> --context <cluster>
+```
+
+Use when: the current revision is unhealthy and the previous revision was known healthy. Verify the rollback completes and pods are ready.
+
+### Restart
+
+```
+kubectl rollout restart deploy/<name> -n <namespace> --context <cluster>
+```
+
+Use when: the current revision should be correct but pods are in a bad state (stale connections, resource exhaustion, transient failure). This re-creates pods with the same spec.
+
+### Scale Adjustment
+
+```
+kubectl scale deploy/<name> --replicas=<n> -n <namespace> --context <cluster>
+```
+
+Use when: the issue is capacity-related (OOM, CPU throttling, request queuing). Scale up to relieve pressure, then investigate root cause.
+
+After any recovery action, re-verify using the procedures above and emit the appropriate `[deploy-status]` marker.
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Cluster names: prod=<context>, staging=<context>
+  - Namespaces: <comma-separated-list>
+  - Workload inventory: <namespace>/<type>/<name>
+  - Health probe paths: <workload> -> <path>
+  - Ingress hostnames and TLS configuration
+  - HPA scaling thresholds
+  - PDB minimum availability requirements
+-->

package/skills/provider-kubernetes/adapters/claude.md

@@ -0,0 +1 @@
+Use kubectl with `-o json` or `-o wide` for machine-readable verification output. For complex diagnostics, use the Agent tool to run parallel kubectl commands across namespaces. Prefer `kubectl rollout status` with `--timeout` over polling pod status manually.

package/skills/provider-kubernetes/adapters/codex.md

@@ -0,0 +1 @@
+Use kubectl with `-o json` for all verification. Keep kubectl commands deterministic and non-interactive. If kubeconfig is not available in the sandbox, record the access gap as deploy risk. Capture full command output for evidence.

package/skills/provider-kubernetes/references/kubectl-patterns.md

@@ -0,0 +1,58 @@
+# Kubernetes Verification Patterns
+
+Reference for verifying Kubernetes workload state using kubectl.
+
+## Workload Health
+- Deployment status: `kubectl -n <ns> get deploy <name> -o wide`
+- Pod status: `kubectl -n <ns> get pods -l app=<label> -o wide`
+- Rollout status: `kubectl -n <ns> rollout status deploy/<name> --timeout=120s`
+- Key checks: READY count matches DESIRED, all pods Running, no restarts.
+
+## Pod Diagnostics
+- Events: `kubectl -n <ns> describe pod <name>` (check Events section)
+- Logs: `kubectl -n <ns> logs <pod> -c <container> --tail=100`
+- Previous logs (after crash): `kubectl -n <ns> logs <pod> -c <container> --previous`
+- Resource usage: `kubectl -n <ns> top pod <name>`
+
+## Service and Networking
+- Service endpoints: `kubectl -n <ns> get endpoints <svc-name>`
+- Service details: `kubectl -n <ns> describe svc <name>`
+- Key checks: Endpoints list has pod IPs, port mappings are correct.
+
+## Failure Patterns
+
+### Image Pull Failure
+- Symptom: Pod stuck in ImagePullBackOff or ErrImagePull.
+- Diagnose: `kubectl -n <ns> describe pod <name>` → Events show pull error.
+- Fix: Check image name/tag, registry credentials, network access.
+
+### Crash Loop
+- Symptom: Pod in CrashLoopBackOff, restart count increasing.
+- Diagnose: `kubectl -n <ns> logs <pod> --previous` → Check exit reason.
+- Fix: Application error, missing config, resource limits too tight.
+
+### Readiness Probe Failure
+- Symptom: Pod Running but not Ready (0/1).
+- Diagnose: `kubectl -n <ns> describe pod <name>` → Readiness probe failed.
+- Fix: Check probe path/port, application startup time, increase initialDelaySeconds.
+
+### Admission Webhook Rejection
+- Symptom: Pod creation fails immediately.
+- Diagnose: `kubectl -n <ns> get events --field-selector reason=FailedCreate`
+- Fix: Check webhook policies, pod security standards, resource quotas.
+
+## Rollback and Recovery
+- Rollback: `kubectl -n <ns> rollout undo deploy/<name>`
+- Rollback to specific revision: `kubectl -n <ns> rollout undo deploy/<name> --to-revision=<n>`
+- Restart (rolling): `kubectl -n <ns> rollout restart deploy/<name>`
+- Scale: `kubectl -n <ns> scale deploy/<name> --replicas=<n>`
+- Pause rollout: `kubectl -n <ns> rollout pause deploy/<name>`
+
+## Evidence Template
+Record for each verification:
+- Cluster: <name>
+- Namespace: <ns>
+- Resource: <type>/<name>
+- Command: <exact kubectl command>
+- Result: <key output fields>
+- Assessment: <healthy|degraded|failed>

package/skills/provider-kubernetes/skill.json

@@ -1,5 +1,52 @@
 {
   "id": "provider-kubernetes",
   "title": "Kubernetes",
-  "description": "Kubernetes cluster, workload, and rollout norms."
+  "description": "Guides deploy verification against Kubernetes clusters: workload health, failure classification across manifest, admission, image, and readiness surfaces.",
+  "activation": {
+    "when": "Attach when the wave deploy surface is Kubernetes and the agent must classify workload, admission, image, or readiness failures.",
+    "roles": [
+      "deploy",
+      "infra",
+      "integration",
+      "cont-qa"
+    ],
+    "runtimes": [],
+    "deployKinds": [
+      "kubernetes"
+    ]
+  },
+  "termination": "Stop when Kubernetes workload evidence is captured and the failure surface is classified.",
+  "permissions": {
+    "network": [],
+    "shell": [
+      "kubectl"
+    ],
+    "mcpServers": []
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "deploy-kubernetes",
+      "role": "deploy",
+      "runtime": "opencode",
+      "deployKind": "kubernetes",
+      "expectActive": true
+    },
+    {
+      "id": "infra-kubernetes",
+      "role": "infra",
+      "runtime": "claude",
+      "deployKind": "kubernetes",
+      "expectActive": true
+    },
+    {
+      "id": "documentation-kubernetes",
+      "role": "documentation",
+      "runtime": "claude",
+      "deployKind": "kubernetes",
+      "expectActive": false
+    }
+  ]
 }

package/skills/provider-railway/SKILL.md

@@ -1,6 +1,123 @@
 # Railway
 
+<!-- CUSTOMIZE: Add your Railway project ID, service names, environment names, and domain mappings below. -->
+
+## Core Rules
+
 - Prefer the Railway MCP or Railway CLI as the source of truth for deployment, environment, and service state.
-- Keep service names, environment names, domains, and deployment ids exact.
+- Keep service names, environment names, domains, and deployment IDs exact.
 - Record what was verified: build logs, deploy logs, variables, domains, or rollout state.
 - If Railway state is degraded or ambiguous, leave a concrete deploy risk instead of implying healthy rollout.
+- Do not treat a successful build as proof of a healthy deploy. Build and deploy are separate proof surfaces.
+
+## Source of Truth
+
+Use these sources in preference order:
+
+1. **Railway MCP** -- highest fidelity. Use MCP tools when available for service state, deploy status, and variable queries.
+2. **Railway CLI** -- direct CLI commands when MCP is not available. Requires `railway` CLI authenticated and linked to the correct project.
+3. **Railway Dashboard** -- lowest preference. Use only when CLI and MCP are both unavailable. Dashboard observations must be recorded with explicit timestamps.
+
+Never mix sources for a single verification claim. State which source you used.
+
+## Verification Procedures
+
+### Service List and Status
+
+```
+railway status
+railway service list
+```
+
+Confirm: service exists, is linked to the correct project and environment, current deploy state.
+
+### Deploy Status
+
+```
+railway logs --deploy
+railway logs --build
+```
+
+Confirm: latest deployment ID, build success or failure, deploy health (running, crashed, pending).
+
+### Environment Variables
+
+```
+railway variables
+railway variables --environment <env-name>
+```
+
+Confirm: required variables are set, no placeholder or empty values for critical keys, no secret leakage in logs.
+
+### Domain Bindings
+
+```
+railway domain
+```
+
+Confirm: custom domains are bound, SSL provisioned, no dangling or conflicting bindings.
+
+### Health Verification
+
+After confirming deploy status, verify the application is responding:
+
+- Check the service URL or custom domain with a health endpoint.
+- Confirm HTTP status code and response body match expectations.
+- If health check fails but deploy shows running, classify as deploy-healthy-but-app-unhealthy.
+
+<!-- CUSTOMIZE: Add your project-specific health endpoints, expected responses, and timeout thresholds here. -->
+
+## Evidence Format
+
+When recording Railway verification, use this structure:
+
+```
+Service: <exact-service-name>
+Environment: <environment-name>
+Deploy ID: <deploy-id>
+Deploy Status: <building|deploying|running|crashed|removed>
+Build Status: <success|failed|pending>
+Domains: <comma-separated-domain-list>
+Health: <healthy|unhealthy|unknown>
+Variables Confirmed: <yes|partial|no>
+Source: <MCP|CLI|Dashboard>
+Timestamp Context: <when-verified>
+```
+
+Omit fields that were not checked. Do not fill in fields with assumed values.
+
+## Failure Classification
+
+Classify Railway failures precisely:
+
+- **Build failure** -- Nixpacks or Dockerfile build step failed. Check build logs for the exact error. Common causes: missing dependency, invalid Dockerfile, incompatible runtime version.
+- **Deploy failure** -- build succeeded but the service crashed on startup. Check deploy logs for crash loop, port binding failure, or missing environment variable.
+- **Domain failure** -- service is running but the domain is not resolving, SSL is not provisioned, or the domain binding is missing.
+- **Variable drift** -- expected environment variables are missing, empty, or have unexpected values. Compare against the wave definition or config source.
+- **Region/resource failure** -- service is pending due to resource constraints or region availability.
+
+Name the failure type explicitly in the `[deploy-status]` marker detail field.
+
+## Rollback
+
+When a deploy fails and rollback is needed:
+
+1. Identify the last known healthy deployment ID from deploy logs or service history.
+2. Redeploy the previous version using `railway rollback` or by redeploying the previous commit.
+3. Verify the rollback deploy reaches running state and health checks pass.
+4. If variables were changed as part of the failed deploy, revert them explicitly.
+5. Emit `[deploy-status] state=rolled-back service=<name> detail=<reason and target deploy ID>`.
+
+Trigger rollback when: service is crash-looping, health checks fail after a reasonable timeout, or the task explicitly requests rollback.
+
+## Customization
+
+<!-- CUSTOMIZE: Override or extend any section above. Common additions:
+  - Railway project ID: <your-project-id>
+  - Service names: <comma-separated-list>
+  - Environment names: production, staging, development
+  - Domain mappings: <service> -> <domain>
+  - Health check endpoints: <service> -> <path>
+  - Required environment variables per service
+  - Build timeout thresholds
+-->

package/skills/provider-railway/references/verification-commands.md

@@ -0,0 +1,39 @@
+# Railway Verification Commands
+
+Reference for verifying Railway deployment state. Prefer MCP when available; fall back to CLI.
+
+## Service Discovery
+- MCP: Use railway_service_list to enumerate all services in the project.
+- CLI: `railway service list`
+
+## Deploy Status
+- MCP: Use railway_deployment_list with service ID to see recent deployments.
+- CLI: `railway status`
+- Key fields: deployment ID, status (SUCCESS/BUILDING/DEPLOYING/FAILED/CRASHED), created timestamp.
+
+## Build Logs
+- MCP: Use railway_deployment_logs with deployment ID.
+- CLI: `railway logs --deployment <id>`
+- Look for: build completion, Nixpacks/Dockerfile detection, dependency install success, start command.
+
+## Environment Variables
+- MCP: Use railway_variable_list with service and environment IDs.
+- CLI: `railway variables`
+- Verify: required variables are set, no stale values, no accidentally exposed secrets.
+
+## Domain Bindings
+- MCP: Use railway_custom_domain_list or railway_service_domain_list.
+- CLI: `railway domain`
+- Verify: custom domains are attached, DNS is configured, SSL certificates are active.
+
+## Service Health
+- After deploy, verify the service is actually responding:
+  - Check deploy status is SUCCESS, not BUILDING or CRASHED.
+  - If the service has a health endpoint, verify it returns 200.
+  - Check for crash loops: multiple rapid deployments with CRASHED status.
+
+## Rollback
+- Redeploy a previous known-good deployment:
+  - MCP: Use railway_deployment_redeploy with the last healthy deployment ID.
+  - CLI: `railway redeploy --deployment <id>`
+- Revert variables if the failure was config-related.