setup-deploy— agent skill

When to invoke

Use when: "setup deploy", "configure deployment", "set up land-and-deploy", "how do I configure deploys".

Preamble

eval "$(~/.vibestack/bin/vibe-slug 2>/dev/null)" 2>/dev/null || SLUG="unknown"
_LEARN_FILE="${VIBESTACK_HOME:-$HOME/.vibestack}/projects/${SLUG:-unknown}/learnings.jsonl"
if [ -f "$_LEARN_FILE" ]; then
  _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ')
  echo "LEARNINGS: $_LEARN_COUNT entries loaded"
  if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then
    ~/.vibestack/bin/vibe-learnings-search --limit 5 2>/dev/null || true
  fi
else
  echo "LEARNINGS: none yet"
fi

{{include lib/snippets/session-host.md}}

{{include lib/snippets/decision-brief.md}}

{{include lib/snippets/working-protocols.md}}

{{include lib/snippets/state-protocols.md}}

User-invocable

When the user types /setup-deploy, run this skill.

Instructions

Step 1: Check existing configuration

grep -A 20 "## Deploy Configuration" CLAUDE.md 2>/dev/null || echo "NO_CONFIG"

If configuration already exists, show it and ask:

• Context: Deploy configuration already exists in CLAUDE.md.
• RECOMMENDATION: Choose A to update if your setup changed.
• A) Reconfigure from scratch (overwrite existing)
• B) Edit specific fields (show current config, let me change one thing)
• C) Done — configuration looks correct

If the user picks C, stop.

Step 2: Detect platform

Run the platform detection from the deploy bootstrap:

# Platform config files
[ -f fly.toml ] && echo "PLATFORM:fly" && cat fly.toml
[ -f render.yaml ] && echo "PLATFORM:render" && cat render.yaml
[ -f vercel.json ] || [ -d .vercel ] && echo "PLATFORM:vercel"
[ -f netlify.toml ] && echo "PLATFORM:netlify" && cat netlify.toml
[ -f Procfile ] && echo "PLATFORM:heroku"
[ -f railway.json ] || [ -f railway.toml ] && echo "PLATFORM:railway"

# GitHub Actions deploy workflows
for f in $(find .github/workflows -maxdepth 1 \( -name '*.yml' -o -name '*.yaml' \) 2>/dev/null); do
  [ -f "$f" ] && grep -qiE "deploy|release|production|staging|cd" "$f" 2>/dev/null && echo "DEPLOY_WORKFLOW:$f"
done

# Project type
[ -f package.json ] && grep -q '"bin"' package.json 2>/dev/null && echo "PROJECT_TYPE:cli"
find . -maxdepth 1 -name '*.gemspec' 2>/dev/null | grep -q . && echo "PROJECT_TYPE:library"

Step 3: Platform-specific setup

Based on what was detected, guide the user through platform-specific configuration.

#### Fly.io

If fly.toml detected:

1. Extract app name: grep -m1 "^app" fly.toml | sed 's/app = "\(.*\)"/\1/'
2. Check if fly CLI is installed: which fly 2>/dev/null
3. If installed, verify: fly status --app {app} 2>/dev/null
4. Infer URL: https://{app}.fly.dev
5. Set deploy status command: fly status --app {app}
6. Set health check: https://{app}.fly.dev (or /health if the app has one)

Ask the user to confirm the production URL. Some Fly apps use custom domains.

#### Render

If render.yaml detected:

1. Extract service name and type from render.yaml
2. Check for Render API key: echo $RENDER_API_KEY | head -c 4 (don't expose the full key)
3. Infer URL: https://{service-name}.onrender.com
4. Render deploys automatically on push to the connected branch — no deploy workflow needed
5. Set health check: the inferred URL

Ask the user to confirm. Render uses auto-deploy from the connected git branch — after merge to main, Render picks it up automatically. The "deploy wait" in /land-and-deploy should poll the Render URL until it responds with the new version.

#### Vercel

If vercel.json or .vercel detected:

1. Check for vercel CLI: which vercel 2>/dev/null
2. If installed: vercel ls --prod 2>/dev/null | head -3
3. Vercel deploys automatically on push — preview on PR, production on merge to main
4. Set health check: the production URL from vercel project settings

#### Netlify

If netlify.toml detected:

1. Extract site info from netlify.toml
2. Netlify deploys automatically on push
3. Set health check: the production URL

#### GitHub Actions only

If deploy workflows detected but no platform config:

1. Read the workflow file to understand what it does
2. Extract the deploy target (if mentioned)
3. Ask the user for the production URL

#### Custom / Manual

If nothing detected, use AskUserQuestion to gather the information:

1. How are deploys triggered?

• A) Automatically on push to main (Fly, Render, Vercel, Netlify, etc.)
• B) Via GitHub Actions workflow
• C) Via a deploy script or CLI command (describe it)
• D) Manually (SSH, dashboard, etc.)
• E) This project doesn't deploy (library, CLI, tool)

1. What's the production URL? (Free text — the URL where the app runs)

1. How can /land-and-deploy check if a deploy succeeded?

• A) HTTP health check at a specific URL (e.g., /health, /api/status)
• B) CLI command (e.g., fly status, kubectl rollout status)
• C) Check the GitHub Actions workflow status
• D) No automated way — just check the URL loads

1. Any pre-merge or post-merge hooks?

• Commands to run before merging (e.g., bun run build)
• Commands to run after merge but before deploy verification

Step 4: Write configuration

Read CLAUDE.md (or create it). Find and replace the ## Deploy Configuration section if it exists, or append it at the end.

## Deploy Configuration (configured by /setup-deploy)
- Platform: {platform}
- Production URL: {url}
- Deploy workflow: {workflow file or "auto-deploy on push"}
- Deploy status command: {command or "HTTP health check"}
- Merge method: {squash/merge/rebase}
- Project type: {web app / API / CLI / library}
- Post-deploy health check: {health check URL or command}

### Custom deploy hooks
- Pre-merge: {command or "none"}
- Deploy trigger: {command or "automatic on push to main"}
- Deploy status: {command or "poll production URL"}
- Health check: {URL or command}

Step 5: Verify

After writing, verify the configuration works:

1. If a health check URL was configured, try it:

curl -sf "{health-check-url}" -o /dev/null -w "%{http_code}" 2>/dev/null || echo "UNREACHABLE"

1. If a deploy status command was configured, try it:

{deploy-status-command} 2>/dev/null | head -5 || echo "COMMAND_FAILED"

Report results. If anything failed, note it but don't block — the config is still useful even if the health check is temporarily unreachable.

Step 6: Summary

DEPLOY CONFIGURATION — COMPLETE
════════════════════════════════
Platform:      {platform}
URL:           {url}
Health check:  {health check}
Status cmd:    {status command}
Merge method:  {merge method}

Saved to CLAUDE.md. /land-and-deploy will use these settings automatically.

Next steps:
- Run /land-and-deploy to merge and deploy your current PR
- Edit the "## Deploy Configuration" section in CLAUDE.md to change settings
- Run /setup-deploy again to reconfigure

Important Rules

• Never expose secrets. Don't print full API keys, tokens, or passwords.
• Confirm with the user. Always show the detected config and ask for confirmation before writing.
• CLAUDE.md is the source of truth. All configuration lives there — not in a separate config file.
• Idempotent. Running /setup-deploy multiple times overwrites the previous config cleanly.
• Platform CLIs are optional. If fly or vercel CLI isn't installed, fall back to URL-based health checks.

Capture Learnings

If you discovered a non-obvious platform quirk, deployment pattern, or configuration gotcha during this session, log it for future sessions:

~/.vibestack/bin/vibe-learnings-log '{"skill":"setup-deploy","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'

Types: pattern (reusable approach), pitfall (what NOT to do), preference (user stated), architecture (structural decision), operational (environment/CLI/workflow).

Only log genuine discoveries. Don't log obvious things. A good test: would this insight save time in a future session?