agentsys 5.3.0 → 5.3.2

package/.kiro/steering/ship-deployment.md

@@ -0,0 +1,353 @@
+---
+inclusion: manual
+name: "ship-deployment"
+description: "Use when deploying and validating during /ship. Details Railway/Vercel deployment, smoke testing, and rollback procedures."
+---
+
+# Phases 7-10: Deploy & Validate - Reference
+
+This file contains platform-specific deployment and validation for `/ship`.
+
+**Parent document**: `ship.md`
+
+**Note**: Skip all phases if `WORKFLOW="single-branch"`.
+
+## Phase 7: Deploy to Development
+
+### Railway
+
+```bash
+if [ "$DEPLOYMENT" = "railway" ]; then
+  echo "Waiting for Railway development deployment..."
+
+  SERVICE_NAME=$(railway service list --json | jq -r '.[0].name')
+  DEPLOY_ID=$(railway deployment list --service $SERVICE_NAME --json | jq -r '.[0].id')
+
+  while true; do
+    STATUS=$(railway deployment get $DEPLOY_ID --json | jq -r '.status')
+
+    if [ "$STATUS" = "SUCCESS" ]; then
+      DEV_URL=$(railway domain list --service $SERVICE_NAME --json | jq -r '.[0].domain')
+      echo "[OK] Deployed to development: https://$DEV_URL"
+      break
+    elif [ "$STATUS" = "FAILED" ]; then
+      echo "[ERROR] Development deployment failed"
+      railway logs --deployment $DEPLOY_ID
+      exit 1
+    fi
+
+    sleep 10
+  done
+fi
+```
+
+### Vercel
+
+```bash
+if [ "$DEPLOYMENT" = "vercel" ]; then
+  echo "Waiting for Vercel development deployment..."
+
+  DEPLOY_URL=$(vercel ls --json | jq -r '.[0].url')
+
+  while true; do
+    STATUS=$(vercel inspect $DEPLOY_URL --json | jq -r '.readyState')
+
+    if [ "$STATUS" = "READY" ]; then
+      echo "[OK] Deployed to development: https://$DEPLOY_URL"
+      DEV_URL="https://$DEPLOY_URL"
+      break
+    elif [ "$STATUS" = "ERROR" ]; then
+      echo "[ERROR] Development deployment failed"
+      vercel logs $DEPLOY_URL
+      exit 1
+    fi
+
+    sleep 10
+  done
+fi
+```
+
+### Netlify
+
+```bash
+if [ "$DEPLOYMENT" = "netlify" ]; then
+  echo "Waiting for Netlify development deployment..."
+
+  SITE_ID=$(netlify status --json | jq -r '.site_id')
+  DEPLOY_ID=$(netlify api listSiteDeploys --data "{ \"site_id\": \"$SITE_ID\" }" | jq -r '.[0].id')
+
+  while true; do
+    STATUS=$(netlify api getDeploy --data "{ \"deploy_id\": \"$DEPLOY_ID\" }" | jq -r '.state')
+
+    if [ "$STATUS" = "ready" ]; then
+      DEV_URL=$(netlify api getDeploy --data "{ \"deploy_id\": \"$DEPLOY_ID\" }" | jq -r '.deploy_ssl_url')
+      echo "[OK] Deployed to development: $DEV_URL"
+      break
+    elif [ "$STATUS" = "error" ]; then
+      echo "[ERROR] Development deployment failed"
+      exit 1
+    fi
+
+    sleep 10
+  done
+fi
+```
+
+### Generic / Unknown
+
+```bash
+if [ -z "$DEPLOYMENT" ] || [ "$DEPLOYMENT" = "null" ]; then
+  echo "No deployment platform detected"
+  echo "Assuming merge to $MAIN_BRANCH means deployment"
+  DEV_URL="N/A"
+fi
+```
+
+## Phase 8: Validate Development
+
+### Health Check
+
+```bash
+echo "Running smoke tests on development..."
+
+# Wait for deployment to stabilize
+sleep 30
+
+# Basic health check
+HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" $DEV_URL/health || echo "000")
+
+if [ "$HTTP_STATUS" = "200" ] || [ "$HTTP_STATUS" = "301" ] || [ "$HTTP_STATUS" = "302" ]; then
+  echo "[OK] Health check passed: $HTTP_STATUS"
+else
+  echo "[ERROR] Health check failed: $HTTP_STATUS"
+  echo "Investigate deployment issues before proceeding to production"
+  exit 1
+fi
+```
+
+### Error Log Monitoring
+
+```bash
+echo "Checking logs for errors..."
+
+if [ "$DEPLOYMENT" = "railway" ]; then
+  ERROR_COUNT=$(railway logs --tail 100 | grep -iE "(error|exception|fatal)" | wc -l)
+elif [ "$DEPLOYMENT" = "vercel" ]; then
+  ERROR_COUNT=$(vercel logs $DEV_URL --since 5m | grep -iE "(error|exception|fatal)" | wc -l)
+elif [ "$DEPLOYMENT" = "netlify" ]; then
+  ERROR_COUNT=$(netlify logs --since 5m | grep -iE "(error|exception|fatal)" | wc -l)
+else
+  ERROR_COUNT=0
+fi
+
+if [ "$ERROR_COUNT" -gt 10 ]; then
+  echo "[ERROR] High error rate detected: $ERROR_COUNT errors in last 5 minutes"
+  echo "Review logs before proceeding to production"
+  exit 1
+else
+  echo "[OK] Error rate acceptable: $ERROR_COUNT errors"
+fi
+```
+
+### Project Smoke Tests
+
+```bash
+if jq -e '.scripts["smoke-test"]' package.json > /dev/null 2>&1; then
+  echo "Running project smoke tests..."
+
+  export SMOKE_TEST_URL=$DEV_URL
+  $PACKAGE_MGR run smoke-test
+
+  if [ $? -eq 0 ]; then
+    echo "[OK] Smoke tests passed"
+  else
+    echo "[ERROR] Smoke tests failed"
+    exit 1
+  fi
+fi
+```
+
+### Validation Summary
+
+```markdown
+## Development Validation [OK]
+
+**URL**: ${DEV_URL}
+**Health Check**: [OK] ${HTTP_STATUS}
+**Error Rate**: [OK] ${ERROR_COUNT} errors
+**Smoke Tests**: [OK] Passed
+
+Proceeding to production...
+```
+
+## Phase 9: Deploy to Production
+
+### Merge to Production Branch
+
+```bash
+# Worktree check must come first - multi-branch deployment requires branch checkout
+if [ -f "$(git rev-parse --show-toplevel 2>/dev/null)/.git" ]; then
+  MAIN_REPO=$(dirname "$(git rev-parse --git-common-dir 2>/dev/null)")
+  echo "[ERROR] Multi-branch deployment is not supported from a worktree"
+  echo "Run from the main repo: cd $MAIN_REPO"
+  exit 1
+fi
+
+echo "Merging $MAIN_BRANCH → $PROD_BRANCH..."
+
+git checkout $PROD_BRANCH
+git pull origin $PROD_BRANCH
+
+git merge $MAIN_BRANCH --no-edit
+
+if [ $? -ne 0 ]; then
+  echo "[ERROR] Merge to production failed (conflicts)"
+  git merge --abort
+  exit 1
+fi
+
+git push origin $PROD_BRANCH
+
+if [ $? -eq 0 ]; then
+  PROD_SHA=$(git rev-parse HEAD)
+  echo "[OK] Production branch at: $PROD_SHA"
+else
+  echo "[ERROR] Push to production failed"
+  exit 1
+fi
+```
+
+### Wait for Production Deployment
+
+Same platform-specific logic as Phase 7, but targeting production environment.
+
+```bash
+echo "Waiting for production deployment..."
+
+# Platform-specific deployment monitoring
+# (Similar to Phase 7)
+
+echo "[OK] Deployed to production: $PROD_URL"
+```
+
+## Phase 10: Validate Production
+
+### Conservative Validation
+
+```bash
+echo "Validating production deployment..."
+
+# Wait longer for production to stabilize
+sleep 60
+
+# Health check
+HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" $PROD_URL/health || echo "000")
+
+if [ "$HTTP_STATUS" = "200" ] || [ "$HTTP_STATUS" = "301" ] || [ "$HTTP_STATUS" = "302" ]; then
+  echo "[OK] Production health check: $HTTP_STATUS"
+else
+  echo "[ERROR] Production health check failed: $HTTP_STATUS"
+  rollback_production
+fi
+```
+
+### Production Error Monitoring
+
+```bash
+echo "Monitoring production logs..."
+
+if [ "$DEPLOYMENT" = "railway" ]; then
+  ERROR_COUNT=$(railway logs --tail 100 | grep -iE "(error|exception|fatal)" | wc -l)
+elif [ "$DEPLOYMENT" = "vercel" ]; then
+  ERROR_COUNT=$(vercel logs $PROD_URL --since 5m | grep -iE "(error|exception|fatal)" | wc -l)
+fi
+
+if [ "$ERROR_COUNT" -gt 20 ]; then
+  echo "[ERROR] CRITICAL: High error rate in production: $ERROR_COUNT errors"
+  rollback_production
+else
+  echo "[OK] Production error rate acceptable: $ERROR_COUNT errors"
+fi
+```
+
+### Production Smoke Tests
+
+```bash
+if jq -e '.scripts["smoke-test:prod"]' package.json > /dev/null 2>&1; then
+  echo "Running production smoke tests..."
+
+  export SMOKE_TEST_URL=$PROD_URL
+  $PACKAGE_MGR run smoke-test:prod
+
+  if [ $? -ne 0 ]; then
+    echo "[ERROR] Production smoke tests failed"
+    rollback_production
+  fi
+fi
+```
+
+## Rollback Mechanism
+
+**Triggered automatically on any production validation failure.**
+
+```bash
+rollback_production() {
+  # Worktree check must come first
+  if [ -f "$(git rev-parse --show-toplevel 2>/dev/null)/.git" ]; then
+    MAIN_REPO=$(dirname "$(git rev-parse --git-common-dir 2>/dev/null)")
+    echo "[ERROR] Rollback is not supported from a worktree"
+    echo "Run from the main repo: cd $MAIN_REPO"
+    exit 1
+  fi
+
+  echo "========================================"
+  echo "ROLLBACK INITIATED"
+  echo "========================================"
+
+  echo "WARNING: Force pushing to $PROD_BRANCH to revert"
+
+  git checkout $PROD_BRANCH
+  git reset --hard HEAD~1
+
+  # Use --force-with-lease for safety
+  if ! git push --force-with-lease origin $PROD_BRANCH; then
+    echo "[ERROR] Force push failed - remote may have unexpected changes"
+    echo "Manual intervention required"
+    exit 1
+  fi
+
+  echo "[OK] Rolled back production to previous deployment"
+  echo "Previous version will redeploy automatically"
+
+  # Wait for rollback deployment
+  sleep 30
+
+  # Verify rollback succeeded
+  HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" $PROD_URL/health || echo "000")
+  if [ "$HTTP_STATUS" = "200" ]; then
+    echo "[OK] Rollback successful, production is healthy"
+  else
+    echo "[WARN] Rollback deployed but health check unclear"
+    echo "Manual investigation required"
+  fi
+
+  exit 1
+}
+```
+
+## Platform Detection Reference
+
+The `detect-platform.js` script returns:
+
+```json
+{
+  "ci": "github-actions|gitlab-ci|circleci|jenkins|travis|null",
+  "deployment": "railway|vercel|netlify|heroku|null",
+  "branchStrategy": "single-branch|multi-branch",
+  "mainBranch": "main|master",
+  "projectType": "nodejs|python|rust|go",
+  "packageManager": "npm|yarn|pnpm|pip|cargo"
+}
+```
+
+Use these values to adapt deployment monitoring to your specific platform.

package/.kiro/steering/ship-error-handling.md

@@ -0,0 +1,270 @@
+---
+inclusion: manual
+name: "ship-error-handling"
+description: "Use when handling and recovering from /ship command errors."
+---
+
+# Error Handling & Recovery - Reference
+
+This file contains error handling procedures for `/ship`.
+
+**Parent document**: `ship.md`
+
+## GitHub CLI Not Available
+
+```markdown
+ERROR: GitHub CLI (gh) not found
+
+Install: https://cli.github.com
+
+Or use package manager:
+  macOS: brew install gh
+  Windows: winget install GitHub.cli
+  Linux: See https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+
+Then authenticate:
+  gh auth login
+```
+
+## CI Failure
+
+```markdown
+[ERROR] CI checks failed for PR #${PR_NUMBER}
+
+View details:
+  ${CI_URL}
+
+Fix the failing tests/checks and push again.
+The /ship command will resume from Phase 4 (CI monitoring).
+
+To retry:
+  git push
+  /ship
+```
+
+### CI Fix with ci-fixer Agent
+
+When CI fails, use the ci-fixer agent:
+
+```javascript
+Task({
+  subagent_type: "ci-fixer",
+  prompt: `Fix CI failure for PR #${PR_NUMBER}
+
+CI Output:
+${CI_OUTPUT}
+
+Failed checks:
+${FAILED_CHECKS}
+
+Requirements:
+1. Analyze the failure reason
+2. Make minimal fix to pass CI
+3. Do not introduce unrelated changes
+4. Ensure all tests pass after fix`
+});
+```
+
+## Merge Conflicts
+
+```markdown
+[ERROR] Cannot merge PR #${PR_NUMBER}: conflicts with ${MAIN_BRANCH}
+
+Resolve conflicts:
+  git fetch origin
+  git merge origin/${MAIN_BRANCH}
+  # Resolve conflicts in your editor
+  git add .
+  git commit
+  git push
+
+Then retry:
+  /ship
+```
+
+## Deployment Failure
+
+```markdown
+[ERROR] Deployment failed
+
+${WORKFLOW === 'dev-prod' ? 'Development' : 'Production'} deployment did not succeed.
+
+Check deployment logs:
+  ${DEPLOYMENT === 'railway' ? 'railway logs' : ''}
+  ${DEPLOYMENT === 'vercel' ? 'vercel logs' : ''}
+  ${DEPLOYMENT === 'netlify' ? 'netlify logs' : ''}
+
+Once fixed, deployment will retry automatically.
+```
+
+## Production Validation Failure with Rollback
+
+```markdown
+[ERROR] Production validation failed
+
+ROLLBACK INITIATED
+
+Production has been rolled back to previous version.
+Previous deployment: ${PREVIOUS_SHA}
+
+Issues detected:
+  ${VALIDATION_ISSUES}
+
+Fix the issues and try shipping again:
+  /ship
+```
+
+## Push Failure
+
+```markdown
+[ERROR] Push to remote failed
+
+Possible causes:
+1. Authentication issue: gh auth status
+2. Remote branch protected: check branch protection rules
+3. Out of date: git pull --rebase origin ${CURRENT_BRANCH}
+
+Resolve and retry:
+  /ship
+```
+
+## PR Creation Failure
+
+```markdown
+[ERROR] Failed to create PR
+
+Possible causes:
+1. Already exists: gh pr list --head ${CURRENT_BRANCH}
+2. No commits: git log ${MAIN_BRANCH}..HEAD
+3. Same branch: ensure not on ${MAIN_BRANCH}
+
+Check existing PRs:
+  gh pr list --state all --head ${CURRENT_BRANCH}
+```
+
+## Max Review Iterations Reached
+
+```markdown
+[ERROR] Max iterations (${MAX_ITERATIONS}) reached
+
+Unable to resolve all review comments automatically.
+Manual intervention required.
+
+Remaining unresolved threads: ${UNRESOLVED_COUNT}
+
+View PR: ${PR_URL}
+
+Options:
+1. Manually address remaining comments
+2. Request reviewer to close non-blocking items
+3. Continue with /ship after resolving
+```
+
+## Worktree Cleanup Failure
+
+```markdown
+[WARN] Failed to clean up worktree
+
+Worktree at: ${WORKTREE_PATH}
+
+Manual cleanup:
+  git worktree remove ${WORKTREE_PATH} --force
+  git worktree prune
+```
+
+## Force Push Safety
+
+When rollback requires force push:
+
+```bash
+# ALWAYS use --force-with-lease instead of --force
+# This prevents overwriting unexpected remote changes
+
+if ! git push --force-with-lease origin $PROD_BRANCH; then
+  echo "[ERROR] Force push failed - remote has unexpected changes"
+  echo "Someone else may have pushed to production"
+  echo "Manual investigation required"
+  exit 1
+fi
+```
+
+## Recovery Procedures
+
+### Resume After CI Fix
+
+```bash
+# After fixing CI locally
+git add .
+git commit -m "fix: address CI failures"
+git push
+
+# Resume shipping
+/ship
+```
+
+### Resume After Conflict Resolution
+
+```bash
+# After resolving merge conflicts
+git add .
+git commit
+git push
+
+# Resume shipping
+/ship
+```
+
+### Resume After Manual Review Resolution
+
+```bash
+# After manually addressing review comments
+git add .
+git commit -m "fix: address review feedback"
+git push
+
+# Resume shipping
+/ship
+```
+
+### Cancel and Cleanup
+
+```bash
+# Detect worktree
+IS_WORKTREE="false"
+if [ -f "$(git rev-parse --show-toplevel 2>/dev/null)/.git" ]; then
+  IS_WORKTREE="true"
+fi
+
+if [ "$IS_WORKTREE" = "true" ]; then
+  # In worktree: close PR and delete remote branch separately
+  gh pr close $PR_NUMBER
+  git push origin --delete "$CURRENT_BRANCH" 2>&1 || echo "[WARN] Remote branch deletion failed - may need manual cleanup"
+  echo "[OK] PR closed (worktree mode - local cleanup deferred to worktree removal)"
+else
+  gh pr close $PR_NUMBER --delete-branch
+  git checkout $MAIN_BRANCH
+  git branch -D $CURRENT_BRANCH
+fi
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success - PR merged |
+| 1 | General failure |
+| 2 | CI failure (retryable) |
+| 3 | Review timeout (manual intervention) |
+| 4 | Deployment failure |
+| 5 | Rollback triggered |
+
+## Logging for Debugging
+
+Enable verbose logging:
+
+```bash
+export SHIP_DEBUG=1
+/ship
+```
+
+This will output detailed information about each phase for troubleshooting.