sandgardenhq/sgai/deployment

Deployment

Overview

Deployment of built artifacts requires mandatory safety gates. This skill reads deployment instructions from the .deploy/ directory and enforces a structured safety process around them.

Three-part model:

Core principle: No artifact leaves the build environment without passing every gate. No deployment proceeds without a rollback plan. All deployment instructions come from .deploy/.

Violating the letter of this rule is violating the spirit of this rule.

Announce at start: "I'm using the deployment skill to ensure safe artifact deployment."

Activation Rule

This skill is MANDATORY when GOAL.md contains any deployment intent. Scan GOAL.md for:

• Deployment verbs: deploy, ship, release, publish, push, distribute, deliver, roll out
• Artifact nouns: binary, container, image, package, bundle, executable, build output, artifact
• Target nouns: server, cloud, production, staging, environment, cluster, host, instance, registry

If ANY of these appear in GOAL.md in the context of deploying a built artifact, this skill must be loaded and followed. No exceptions.

Not applicable when:

• GOAL.md only mentions building (no deployment target)
• GOAL.md only mentions testing (no deployment step)
• Changes are documentation-only

Process

Step 0: Load Deployment Instructions

Before any gates, read `.deploy/` to understand the deployment procedure.

Read the contents of the .deploy/ directory at the repository root. From it, extract:

• What artifact is being deployed (name, build command, output path)
• Where it is going (target environment, host, registry)
• How to deploy it (commands, scripts, pipelines)
• How to verify it (health check endpoints, smoke test commands)
• How to roll back (rollback commands, previous version restore procedure)

If .deploy/ contains environment-specific subdirectories, identify which environment GOAL.md is targeting and read the relevant subdirectory.

If `.deploy/` does not exist:

1. Scan the project structure and GOAL.md to understand the deployment context
2. Draft a .deploy/README.md with deployment instructions based on what you can infer from the project (build system, artifact type, any deployment hints in the codebase)
3. Present the draft to the user for review
4. STOP. Do not proceed with deployment until the user confirms the `.deploy/` contents are correct.

The skill never guesses deployment commands at execution time. All deployment commands must be documented in .deploy/ and confirmed by the user before any deployment proceeds.

.deploy/ check:
  directory exists:     [YES/DRAFTING]
  instructions loaded:  [YES/NO]
  artifact identified:  [YES/NO]
  target identified:    [YES/NO]
  deploy command found: [YES/NO]
  rollback found:       [YES/NO]
  health check found:   [YES/NO]
 
ALL must show YES before proceeding to Step 1.
DRAFTING = draft .deploy/README.md, present to user, STOP until confirmed.

Step 1: Pre-Deployment Gate

No deployment proceeds until ALL gates pass.

• [ ] Tests pass - Run the full test suite. Fresh run, not cached results.
• [ ] Build succeeds - Build the artifact from clean state. Exit code 0.
• [ ] Linter clean - No lint errors or warnings in shipped code.
• [ ] completionGateScript passes - If GOAL.md defines a completionGateScript, run it and verify it passes.
• [ ] Version/tag is set - Artifact version matches intended release.
• [ ] No debug configuration - Debug flags, dev endpoints, test credentials are removed from the artifact.

Gate check:
  tests:              [PASS/FAIL]
  build:              [PASS/FAIL]
  lint:               [PASS/FAIL]
  completionGate:     [PASS/FAIL/N/A]
  version:            [SET/MISSING]
  debug config:       [CLEAN/FOUND]
 
ALL must show PASS/SET/CLEAN before proceeding.
Any FAIL/MISSING/FOUND = STOP. Fix before continuing.

Step 2: Artifact Verification

Verify the artifact at the path specified in .deploy/.

• [ ] Artifact exists - The built artifact is present at the path documented in .deploy/.
• [ ] Artifact is correct version - Version string/tag in artifact matches what was intended.
• [ ] Artifact integrity - Record checksum (SHA256) of the artifact for verification.
• [ ] Artifact size sanity - Size is within expected range (not suspiciously small or large).
• [ ] No dev/test artifacts - Only production artifacts are included in the deployment package.

Step 3: Environment Validation

Validate the target environment documented in .deploy/. Use the validation commands from .deploy/ if provided.

• [ ] Target environment is accessible - Can reach the deployment target (SSH, API, registry).
• [ ] Required services available - Dependencies (database, cache, queue) are running.
• [ ] Configuration is correct - Environment variables, secrets, and config files match the target environment.
• [ ] Sufficient resources - Disk space, memory, CPU are adequate.
• [ ] No active incidents - Target environment is not currently experiencing issues.

Environment check:
  target reachable:   [YES/NO]
  services up:        [YES/NO]
  config validated:   [YES/NO]
  resources ok:       [YES/NO]
  no incidents:       [YES/NO]
 
ALL must show YES before proceeding.

Step 4: Rollback Plan

MANDATORY. No deployment without a documented rollback.

Use the rollback procedure from .deploy/ as the basis. Verify it is complete and current.

• [ ] Current state recorded - Document what is currently deployed (version, config, state).
• [ ] Rollback procedure documented - .deploy/ contains step-by-step instructions to revert.
• [ ] Rollback tested or verified possible - Confirm the rollback mechanism works.
• [ ] Rollback trigger defined - What conditions trigger a rollback (error rate, health check failure, etc.).
• [ ] Time estimate - How long will rollback take?

If .deploy/ does not include rollback instructions, STOP. Add rollback instructions to .deploy/ and get user confirmation before proceeding.

Step 5: Deployment Execution

Execute the deployment command documented in .deploy/.

• [ ] Announce deployment - Notify stakeholders that deployment is starting.
• [ ] Execute deployment command - Run the exact command from .deploy/. Do not improvise.
• [ ] Monitor for errors - Watch deployment output for failures.
• [ ] Log deployment - Record what was deployed, when, and by whom.

Deployment log:
  artifact:    [name and version]
  target:      [environment from .deploy/]
  command:     [command from .deploy/]
  started:     [timestamp]
  completed:   [timestamp]
  status:      [SUCCESS/FAILED]
  deployed by: [agent/user]

If deployment fails: Stop. Do NOT retry blindly. Investigate the failure. If the failure is understood and fixable, fix and restart from Step 1.

Step 6: Post-Deployment Verification

Run the health checks and verification steps documented in .deploy/.

• [ ] Service is running - The deployed artifact is executing.
• [ ] Health checks pass - All health/readiness endpoints from .deploy/ return healthy.
• [ ] Key functionality works - Smoke test critical paths as documented in .deploy/.
• [ ] No error spikes - Error rates are within normal range.
• [ ] Performance acceptable - Response times and throughput are within SLA.

Post-deployment verification:
  service running:    [YES/NO]
  health checks:      [PASS/FAIL]
  smoke tests:        [PASS/FAIL]
  error rate:         [NORMAL/ELEVATED]
  performance:        [OK/DEGRADED]
 
ALL must show YES/PASS/NORMAL/OK.
Any NO/FAIL/ELEVATED/DEGRADED = Execute rollback plan from .deploy/.

The .deploy/ Directory

.deploy/ is a free-form directory at the repository root. It is the single source of truth for how deployment works for this project. The skill makes no assumptions about its internal structure beyond: the contents must be readable and must describe the deployment procedure.

Example Structures

Simple project:

.deploy/
  README.md           # all deployment instructions in one file

Multi-environment:

.deploy/
  README.md           # shared instructions, overview
  staging/
    README.md         # staging-specific commands and targets
  production/
    README.md         # production-specific commands and targets

Script-based:

.deploy/
  README.md           # overview and manual steps
  deploy.sh           # deployment script
  rollback.sh         # rollback script
  health-check.sh     # health check script

Container-based:

.deploy/
  README.md           # overview
  Dockerfile          # container build
  docker-compose.yml  # orchestration
  k8s/
    deployment.yaml
    service.yaml

Drafting .deploy/ for a New Project

When .deploy/ does not exist and this skill is activated, draft a .deploy/README.md with the following structure, filled in from project context:

# Deployment Instructions
 
## Artifact
-Name: [inferred from project]
-Build command: [inferred from build system]
-Output path: [inferred from build output]
 
## Target
-Host: [ask user if not inferable]
-Method: [scp, docker push, kubectl apply, etc.]
-Deploy command: [the actual command to run]
 
## Health Check
-URL or command: [health endpoint or verification command]
-Expected result: [HTTP 200, exit code 0, etc.]
 
## Rollback
-Procedure: [step-by-step rollback commands]
-Time estimate: [duration]
-Trigger: [conditions that require rollback]
 
## Environment Validation
-Reachability: [command to verify target is accessible]
-Services: [command to verify dependencies are running]

After drafting, present it to the user and STOP until confirmed.

Rules

1. No deployment without `.deploy/` - If .deploy/ does not exist or is empty, draft it and wait for user confirmation. Never deploy without documented instructions.
2. No deployment without passing tests - Fresh test run, not "tests passed yesterday." Run them NOW.
3. No deployment without rollback plan - If you cannot roll back, you cannot deploy. Period.
4. No deployment without environment validation - Deploying to an unreachable or unhealthy environment wastes time and risks data.
5. No debug artifacts in production - Debug builds, test credentials, dev endpoints must not reach production.
6. No skipping post-deployment verification - Deployment is not done until post-verification passes. Walking away after deploy is negligence.
7. No retry without investigation - Failed deployments must be investigated before retrying. Blind retries compound problems.
8. Rollback on any post-deployment failure - If post-deployment verification fails, execute the rollback plan from .deploy/ immediately. Do not "wait and see."
9. No improvised deployment commands - Execute what .deploy/ says. If .deploy/ is wrong, fix .deploy/ first, then redeploy.

Rationalization Table