add-deploy

name	add-deploy
description	[ADD v0.11.0] Environment-aware commit, push, and deploy workflow
argument-hint	[--env local|dev|staging|production] [--skip-verify]

ADD Deploy Skill v0.11.0

Execute environment-aware deployment: commit changes, push to remote, trigger CI/CD, and verify successful deployment.

Overview

The Deploy skill orchestrates the final step of the development workflow:

1. Commit — Stage and commit code changes with traceability
2. Push — Push to remote repository and branch
3. CI/CD — Trigger or monitor CI pipeline
4. Verify — Confirm deployment success and run smoke tests

The skill is environment-aware: deployment to production is gated with additional safety checks and requires human approval.

Deployment flows:

• Local: Commit only (no push)
• Dev: Commit → Push → Optional CI
• Staging: Commit → Push → CI required → Verify
• Production: Commit → Push → CI required → Gated approval → Verify smoke tests

Pre-Flight Checks

1. Verify code quality

   • Run /add-verify --level deploy (unless --skip-verify)
   • Halt if quality gates fail
   • Ensure all tests passing

2. Load configuration

   • Read .add/config.json
   • Extract deployment settings:
     • ci.enabled (true/false)
     • ci.provider (github, gitlab, circleci, etc.)
     • environments: dev, staging, production configs
     • deployment.strategy (direct, blue-green, canary)
   • Load credential/auth settings

3. Verify git repository

   • Confirm working directory is a git repo
   • Check git is configured (user.name, user.email)
   • Verify branch protection rules won't block merge

4. Determine environment

   • Use --env flag or prompt user
   • Default: staging (safe default)
   • Validate environment exists in config

5. Check for uncommitted changes

   • Run git status
   • Verify all relevant changes are staged
   • Halt if unintended changes exist
   • Ask user to review staged changes

6. Verify feature branch

   • Confirm on feature branch (not main/master)
   • For production, branch should be up-to-date with main
   • For dev, any branch acceptable

7. Check for session handoff

   • Read .add/handoff.md if it exists
   • Note any in-progress work or decisions relevant to this operation
   • If handoff mentions blockers for this skill's scope, warn before proceeding

Execution Steps

Step 1: Pre-Deployment Verification

Unless --skip-verify:

# Run full quality gates
npm test            # all tests pass
npm run lint        # no lint errors
npm run build       # builds successfully
# or Python equivalent
python -m pytest    # all tests pass
python -m flake8    # no lint errors
# or other language equivalents

Capture results:

• Exit code (0 = success)
• Test count and results
• Coverage percentage
• Build artifacts created

If any verification fails:

• Report which gate failed
• Do NOT proceed with deployment
• Ask user to fix issues and re-run

Step 1.5: Pre-commit secrets gate

Before composing the commit message, run the shared secrets gate per ~/.codex/add/references/secrets-gate.md — the same gate as /add-verify Gate 4.6. The executable scanner (~/.codex/add/lib/scan-secrets.sh against the staged diff) is the single point of truth — do NOT re-implement the catalog inline. Scanner invocation, exit codes, finding format, --allow-secret confirm-phrase matching rules, .secretsignore handling, and edge cases are all in the reference.

Deploy-specific behavior:

• Blocking vs advisory by maturity: at POC maturity the gate is advisory — report findings and continue only with explicit user acknowledgment. At Alpha and above, any unsuppressed finding aborts the commit: no commit is created, and staged changes are preserved so the user can fix and retry.

• Overrides: interactive override via /add-deploy --allow-secret (exact confirm phrase, matched literally per the reference), or the automation-friendly commit-message trailer [ADD-SECRET-OVERRIDE: {SEC-NNN} (reason)] — the scanner accepts the trailer when --commit-msg-file points at the message and the trailer enumerates the SEC codes being overridden.

• On a successful override, before proceeding to Step 2, append to .add/observations.md:

  {YYYY-MM-DD HH:MM} | deploy | secrets-gate override: {file}:{line} {PATTERN_NAME} | reason: {user's stated reason}
  

  and append the override record to .add/redaction-log.json under { "artifact": "deploy-gate-override", ... } if the log exists.

• .secretsignore-listed files staged anyway (SEC-998 findings) are treated the same as catalog matches — abort unless overridden; the file should not be committed at all.

Step 2: Prepare Commit Message

Compose a detailed commit message following conventions:

• First line: {type}: {short description under 50 chars} — types are feat, fix, refactor, test, docs, perf, ci, chore.
• Body: a longer description explaining the change.
• Then structured sections: Acceptance Criteria (per-AC ✓ status), Test Coverage (test count + coverage %), Quality Gates (lint / types / tests / spec compliance).
• Footer: Closes: #{issue-number} if applicable.

Full format specification and a worked example: ~/.codex/add/templates/commit-message.md.

Step 3: Stage and Commit Changes

Stage relevant files (not sensitive files):

# Stage implementation files
git add src/
git add tests/
git add docs/

# Verify staging
git status
git diff --cached

# Do NOT stage:
# - .env files
# - Secrets or credentials
# - node_modules/
# - Build artifacts (unless necessary)
# - .DS_Store, IDE files

Ask user to verify staged changes:

Staged files:
- src/form.ts
- src/api/submit.ts
- tests/form.test.ts
- tests/api.test.ts
- docs/performance.md

Proceed with commit? [yes/no]

Wait for explicit confirmation before committing.

Create commit:

git commit -m "$(cat <<'EOF'
feat: Add form submission with email validation

[full message as prepared in Step 2]
EOF
)"

Verify commit:

git log -1 --oneline
# Output: abc1234 feat: Add form submission with email validation

Step 4: Push to Remote

For Dev/Staging Environments:

Determine target branch:

• Default: same name as feature branch
• Or specified via config

Push to remote:

git push origin {feature-branch}
# or
git push -u origin {feature-branch}

Verify push succeeded:

• Check exit code (0 = success)
• Confirm remote shows new commit

For Production Environment:

Production requires PR/merge request workflow:

1. Create PR/MR with:

   • Title from commit message
   • Description with AC list
   • Link to spec and plan
   • Risk assessment

2. Request reviews:

   • At least 2 approvals required (per config)
   • Assign to code owners
   • Wait for approval

3. Merge to main:

   # After PR approved and CI passes
   git checkout main
   git pull origin main
   git merge {feature-branch}
   # or use GitHub/GitLab merge button
   

4. Tag release:

   git tag -a v{version} -m "Release {feature-name} v{version}"
   git push origin v{version}
   

Step 5: Trigger or Monitor CI/CD

CI/CD Pipeline:

Check if CI is enabled in config (ci.enabled):

If enabled:

1. Trigger CI (if not automatic)

   • GitHub: automatic on push/PR
   • GitLab: automatic on push/MR
   • CircleCI: may require manual trigger
   • Jenkins: may require webhook/API call

2. Monitor pipeline progress

   • Fetch build status from CI provider
   • Poll until complete (timeout: 30min)
   • Stream logs if available

3. Check gate results

   CI Pipeline Status: 🟡 In Progress
   
   Jobs:
   - Lint: ✓ PASSED (2 min)
   - Type Check: ✓ PASSED (3 min)
   - Unit Tests: 🟡 IN PROGRESS (4/32 tests)
   - Integration Tests: ⊘ PENDING
   - Deploy to Staging: ⊘ PENDING
   
   Elapsed: 5 minutes
   ETA: 8 minutes
   

4. Wait for completion

   • All jobs must pass
   • No failures allowed
   • Report if any job fails

If CI disabled:

• Document that CI is skipped
• Warn user: "CI verification skipped - consider enabling"
• Continue to deployment

Step 6: Production Approval Gate — Confirm-Phrase (Production Only)

This gate is a runtime check, not a behavioral rule. The skill MUST NOT proceed to any production deployment action without capturing the exact confirmation phrase below. This applies regardless of --promote, away mode, or any other autonomy granting — production is the one boundary that remains human-gated at all maturities.

Also required: .add/config.json → environments.production.autoPromote must be false. If it is true, halt with: "autoPromote: true on production is not permitted — ADD refuses to proceed. Edit .add/config.json to set autoPromote: false."

6.1 Present deployment plan

⚠️  PRODUCTION DEPLOYMENT

Feature: Form submission with email validation
Commit: abc1234
Branch: feature/form-submission
Target: main

Changes:
- 3 files modified
- 450 lines added, 20 lines removed

Testing:
- ✓ All 32 tests passing
- ✓ 87% code coverage
- ✓ Lint and type checks passing

Acceptance Criteria Verified:
- AC-001: ✓ User can submit valid form
- AC-002: ✓ Validation errors shown
- AC-003: ✓ Network errors handled

Risk Assessment:
- Integration Points: 1 (Email service)
- Database Changes: None
- Breaking Changes: None
- Rollback Plan: Revert commit + redeploy previous tag

6.2 Require the confirm-phrase

Ask the user:

"To proceed with production deployment, type DEPLOY TO PRODUCTION (all caps, exactly) and press enter. Any other response — including 'yes', 'y', 'ok', or silence — will cancel."

Matching rules — implemented literally in the skill, not left to agent judgment:

• The response MUST equal the string DEPLOY TO PRODUCTION (no quotes, no leading/trailing whitespace other than a trailing newline).
• Case-sensitive match. deploy to production does NOT pass. Deploy to Production does NOT pass.
• The match is on the ENTIRE user response. DEPLOY TO PRODUCTION please does NOT pass.
• The match must be the IMMEDIATELY NEXT user message. If the user sends any intervening message (clarification, question), the gate resets and must be re-asked.

If the match succeeds: proceed to Step 7. If the match fails for any reason: halt and output:

Production deployment CANCELLED. No changes made.

Re-run /add-deploy --env production when ready to deploy.
The confirm-phrase gate exists to prevent automation, rushed approvals,
and ambiguous consent from deploying to production.

Why this gate exists: ADD's autonomous-execution model is powerful enough that "please approve" prompts during away mode get fuzzy. Requiring a specific literal string means no agent, no script, no accidental enter-key can trigger a production deploy without the human actively typing the phrase. This is a technical gate, not a behavioral rule.

6.3 Record and proceed

• Timestamp the approval
• Record in .add/deploy-log.md with commit hash, branch, and confirm-phrase timestamp
• Include in the commit message body: Approved via DEPLOY TO PRODUCTION phrase at {UTC timestamp}
• Continue to Step 7

6.4 Timeout and boundary behavior

• If the user does not respond within 15 minutes: halt and cancel (same as a non-matching response)
• During away mode: the gate still requires the phrase. If away mode is active and the user is unreachable, the production deploy MUST wait for the user's return. Log to .add/away-log.md and move to the next task.

Step 7: Execute Deployment

For Dev Environment:

# Direct deploy (no CI required)
npm run deploy:dev
# or
./scripts/deploy-dev.sh

For Staging Environment:

# After CI passes
npm run deploy:staging
# or
./scripts/deploy-staging.sh

For Production Environment:

# After approval, merge to main, and CI passes
npm run deploy:production
# or
./scripts/deploy-production.sh

# This typically:
# - Pulls latest from main
# - Builds production bundle
# - Uploads to production servers
# - Runs database migrations if needed
# - Restarts services
# - Runs health checks

Monitor deployment:

• Watch deployment logs
• Check for errors or failures
• Verify services are coming online
• Confirm no data loss

Step 8: Verify Deployment Success

After deployment completes:

1. Run smoke tests

   npm run test:smoke -- --environment production
   # or equivalent
   

   Smoke tests check:

   • API endpoints responding
   • Database connectivity
   • Cache working
   • Email service working
   • No obvious breakage

2. Verify application health

   curl https://api.example.com/health
   # Response should indicate health: 200 OK
   

3. Check user-facing changes

   • Navigate to deployed application
   • Test happy path for new feature
   • Verify no visual regressions
   • Check mobile responsiveness

4. Monitor error logs

   • Check application logs for errors
   • Check infrastructure logs
   • Alert on unexpected errors

5. Verify metrics

   • Response time within targets
   • Error rate normal
   • Resource usage normal
   • User activity patterns normal

Success Criteria:

• All smoke tests pass
• No critical errors in logs
• Metrics within normal ranges
• Feature working as designed

Failure Response:

• If any smoke test fails, escalate
• For production, implement rollback plan
• Document the failure
• Root cause analysis

Output Format

Upon successful deployment, output a "Deployment Complete" report covering: deployment summary (environment, feature, commit, branch, timestamp, duration), code changes, pre-deploy quality gates, CI/CD job results, post-deployment verification (smoke tests, health check, error rate, response time), deployment details (strategy + rollback plan), deployed files, notifications, and next steps. Render per the sample report in ~/.codex/add/templates/deploy-reference.md.

Error Handling

Quality gates fail (--skip-verify not set)

• Report which gates fail
• Do NOT proceed with deployment
• Ask user to fix issues
• Run /add-verify to see detailed failures

Uncommitted changes detected

• List uncommitted changes
• Ask user: commit or discard?
• Halt until resolved

Branch protection rules block push

• Report which rule is blocking
• For production, this is expected (PR required)
• Guide user through PR process

CI pipeline fails

• Report which job failed
• Show job logs
• Do NOT proceed with deployment
• Ask user to fix and retry

Smoke tests fail after deployment

• Immediate escalation for production
• For prod, recommend rollback
• For staging, document and investigate
• Run root cause analysis

Production deployment approval timeout

• Halt after 15 minutes of no response
• Preserve staged changes for retry
• Notify user to re-run when ready

Deployment script fails

• Report error from deployment command
• Show relevant logs
• Suggest manual investigation
• For production, initiate rollback procedure

Environment Promotion Ladder

When deploying to a multi-environment project (Tier 2+), the deploy skill supports automatic promotion through environments:

Promotion Mode (--promote)

When invoked with --promote (or during away mode), the skill climbs the promotion ladder:

1. Deploy to current environment → run verifyCommand for that environment
2. If verification passes AND next environment has autoPromote: true → deploy to next environment
3. Repeat until ladder ends, verification fails, or autoPromote: false is reached
4. If verification fails at any level → rollback that environment to last known good, log failure, stop

/add-deploy --promote --env dev
  → deploys to dev
  → runs dev verifyCommand (integration tests)
  → PASS → auto-promotes to staging
  → runs staging verifyCommand (e2e + perf)
  → PASS → stops (production requires human approval)
  → logs: "Verified through staging. Production queued for human approval."

Rollback on Failure

If verification fails after deploying to an environment:

1. Read rollbackStrategy from config for that environment:
   • revert-commit: git revert {commit} && git push → redeploy
   • redeploy-previous-tag: find last stable tag → checkout → redeploy
2. Run smoke test against the rolled-back environment to confirm it's healthy
3. Log the failure with: what was deployed, what failed, what was rolled back
4. Stop the ladder — do not promote further

Away Mode Behavior

During away mode, the deploy skill automatically uses --promote behavior:

• Climb the ladder through all autoPromote: true environments
• Stop before any autoPromote: false environment (always production)
• On failure: rollback, log, move to next task in the away plan

Integration with Other Skills

• Called after /add-tdd-cycle and /add-verify succeed
• Triggers /add-verify --level smoke after deployment
• Supports --promote for automatic environment ladder climbing
• Final step in development workflow
• Completes the cycle: Spec → Plan → Code → Deploy

Configuration in .add/config.json

Deploy reads: git.* (defaultBranch, requirePR, requireReviews), ci.* (enabled, provider, timeout), deployment.* (strategy, rollbackEnabled, smokeTestScript), and per-environment environments.{env} settings (branch, requireApproval, requireReviews, targetHost). Full annotated example: ~/.codex/add/templates/deploy-reference.md.

Deployment Checklist

Before deploying to production, walk the 15-item pre-production checklist in ~/.codex/add/templates/deploy-reference.md (ACs implemented, tests + coverage, reviews, spec compliance, performance, migrations, docs, release notes, rollback plan, notifications, monitoring, smoke tests).

Rollback Procedure

If production deployment fails: revert the problematic commit (or check out the previous stable tag), push, redeploy the previous version, then verify health with smoke tests against production. Commands: ~/.codex/add/templates/deploy-reference.md.

Document: what broke, why it broke, how to prevent it in future, and the incident timeline.

Post-Deployment Monitoring

After production deployment:

• Monitor error rates for 1 hour
• Check user feedback channels
• Verify feature adoption
• Monitor performance metrics
• Be ready to rollback if issues arise

Epilogue

End-of-skill epilogue: follow ~/.codex/add/references/skill-epilogue.md (observation + learning checkpoint + progress tracking).

Deploy specifics: progress-task phases are pre-deploy checks → prepare → deploy → smoke tests; the observation line uses skill name deploy; the learning checkpoint uses the "After Deployment" trigger in ~/.codex/add/references/learning-reference.md.