Add 9 comprehensive automation skills and enforce tool usage
Create complete automation toolkit with 9 new skills covering all major workflows, saving 147-205 hrs/year from 936 hrs/year baseline. ## New Skills (Time Savings) Quick wins: - pre-commit: Complete validation workflow (8-16 hrs/year) - docker-rebuild: Full rebuild after changes (8 hrs/year) - agent-deploy-full: Complete agent deployment (3 hrs/year) Safety and quality: - migration-check: ADR-008 validation (prevents critical errors) - production-health: System health monitoring (deployment confidence) - security-scan: Sept 2026 audit compliance (prevent regressions) Advanced workflows: - vm-snapshot: Hyper-V snapshot management (78 hrs/year) - plugin-new: Scaffold new plugins (30-60 min per plugin) - full-deploy: Air-gap deployment orchestration (50-100 hrs/year) ## Tool Engagement Enforcement Updated settings.json to load TOOL-ENGAGEMENT-PROTOCOL.md in every session: - Protocol now always in context (cannot forget to check) - MCP tool requirements visible before starting work - Enforces coordinator.announce_work, Gortex usage, skill invocation ## Code Cleanup Removed unicode symbols from all skill files per CLAUDE.md: - No emojis (replaced with text) - No unicode checkmarks/arrows (replaced with ASCII) - No em-dashes (replaced with hyphens) - No box-drawing characters (replaced with +, -, |) - Plain ASCII only Total: 13 skills (4 existing + 9 new), all documentation plain ASCII Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Proudlock
577
.claude/skills/full-deploy.md
Normal file
577
.claude/skills/full-deploy.md
Normal file
@@ -0,0 +1,577 @@
|
||||
---
|
||||
name: full-deploy
|
||||
description: Complete deployment workflow for air-gapped production - validation, bundle creation, deployment, verification (saves 50-100 hrs/year from 312 hrs burden)
|
||||
---
|
||||
|
||||
# Full Production Deployment Workflow
|
||||
|
||||
Complete end-to-end deployment for air-gapped ShopDB production environment. Addresses 312 hrs/year coordination burden.
|
||||
|
||||
## What This Skill Does
|
||||
|
||||
Orchestrates complete deployment:
|
||||
1. Pre-deploy validation (tests, health checks, security)
|
||||
2. Create deployment bundle
|
||||
3. Deploy to dev PC first (staging test)
|
||||
4. Generate production deployment runbook
|
||||
5. Transfer bundle across air gap
|
||||
6. Deploy to production
|
||||
7. Post-deploy validation
|
||||
8. Rollback plan if issues detected
|
||||
|
||||
## Air-Gap Environment
|
||||
|
||||
```
|
||||
+--------------+ +---------------+ +------------+
|
||||
| Dev PC | Bundle | Work PC | Bundle | GitHub |
|
||||
| (gitea) | ------> | (GitHub) | ------> | (public) |
|
||||
| | | YOU ARE HERE | | |
|
||||
+--------------+ +---------------+ +------------+
|
||||
| |
|
||||
Dev Server Prod Server
|
||||
(ops branch) (wj branch)
|
||||
```
|
||||
|
||||
**Constraints:**
|
||||
- No direct GitHub access from dev PC
|
||||
- Manual bundle transfer between environments
|
||||
- Production changes must be tested on dev first
|
||||
- Work PC is coordination point
|
||||
|
||||
## Prerequisites
|
||||
|
||||
**Before starting deployment:**
|
||||
- All changes committed to wj branch
|
||||
- Tests passing (`pytest -v`)
|
||||
- Style check passing (`scripts/check-naming-and-style.sh`)
|
||||
- Frontend built (`npm run build`)
|
||||
- No uncommitted changes (`git status` clean)
|
||||
|
||||
## Workflow
|
||||
|
||||
### Phase 1: Pre-Deploy Validation (Work PC)
|
||||
|
||||
**1.1 Run Complete Validation Suite:**
|
||||
|
||||
```bash
|
||||
# Health check current state
|
||||
/production-health
|
||||
|
||||
# Security scan
|
||||
/security-scan
|
||||
|
||||
# Migration validation
|
||||
/migration-check
|
||||
|
||||
# Pre-commit checks
|
||||
/pre-commit
|
||||
```
|
||||
|
||||
**Expected:** All checks pass with no critical issues.
|
||||
|
||||
**If validation fails:**
|
||||
- Document failures
|
||||
- Fix issues before proceeding
|
||||
- Re-run validation
|
||||
- Do NOT proceed with deployment if critical issues remain
|
||||
|
||||
**1.2 Create Deployment Tag:**
|
||||
|
||||
```bash
|
||||
# Tag format: vYYYY.MM.DD-N (N = deployment number that day)
|
||||
TAG="v$(date +%Y.%m.%d)-1"
|
||||
git tag -a $TAG -m "Production deployment $(date +%Y-%m-%d)"
|
||||
git push origin $TAG
|
||||
```
|
||||
|
||||
**1.3 Document Changes Since Last Deploy:**
|
||||
|
||||
```bash
|
||||
# Get last deployment tag
|
||||
LAST_TAG=$(git describe --tags --abbrev=0 HEAD^)
|
||||
|
||||
# Generate changelog
|
||||
git log $LAST_TAG..HEAD --oneline --no-merges > deployment-changelog.txt
|
||||
|
||||
# Show commit summary
|
||||
echo "Changes since last deploy ($LAST_TAG):"
|
||||
git log $LAST_TAG..HEAD --oneline --no-merges | wc -l
|
||||
echo "commits"
|
||||
```
|
||||
|
||||
Review changelog for:
|
||||
- Breaking changes
|
||||
- Database migrations
|
||||
- New dependencies
|
||||
- Configuration changes
|
||||
|
||||
### Phase 2: Create Deployment Bundle (Work PC)
|
||||
|
||||
**2.1 Build Frontend:**
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build
|
||||
cd ..
|
||||
```
|
||||
|
||||
Verify `frontend/dist/` updated with production build.
|
||||
|
||||
**2.2 Create Bundle Archive:**
|
||||
|
||||
```bash
|
||||
BUNDLE_DATE=$(date +%Y%m%d_%H%M)
|
||||
BUNDLE_NAME="shopdb-deploy-$BUNDLE_DATE.tar.gz"
|
||||
|
||||
# Include everything except .git, node_modules, venv
|
||||
tar -czf ~/_transfer/$BUNDLE_NAME \
|
||||
--exclude='.git' \
|
||||
--exclude='node_modules' \
|
||||
--exclude='venv' \
|
||||
--exclude='*.pyc' \
|
||||
--exclude='__pycache__' \
|
||||
--exclude='frontend/dist' \
|
||||
.
|
||||
|
||||
# Separately bundle frontend (large)
|
||||
tar -czf ~/_transfer/shopdb-frontend-$BUNDLE_DATE.tar.gz \
|
||||
frontend/dist/
|
||||
|
||||
echo "Bundles created:"
|
||||
ls -lh ~/_transfer/shopdb-*$BUNDLE_DATE.tar.gz
|
||||
```
|
||||
|
||||
**2.3 Generate Deployment Runbook:**
|
||||
|
||||
Create `deployment-runbook-$BUNDLE_DATE.md`:
|
||||
|
||||
```markdown
|
||||
# ShopDB Deployment Runbook
|
||||
|
||||
**Date:** $(date +%Y-%m-%d %H:%M)
|
||||
**Bundle:** shopdb-deploy-$BUNDLE_DATE.tar.gz
|
||||
**Tag:** $TAG
|
||||
**Target:** Production (wj branch)
|
||||
|
||||
## Pre-Deployment
|
||||
|
||||
- [ ] Backup production database
|
||||
- [ ] Create VM snapshot: /vm-snapshot create "before-deploy-$BUNDLE_DATE"
|
||||
- [ ] Verify production health: /production-health
|
||||
- [ ] Notify users of maintenance window
|
||||
|
||||
## Deployment Steps
|
||||
|
||||
### 1. Extract Bundle
|
||||
|
||||
```bash
|
||||
cd /path/to/shopdb-production
|
||||
tar -xzf ~/shopdb-deploy-$BUNDLE_DATE.tar.gz
|
||||
tar -xzf ~/shopdb-frontend-$BUNDLE_DATE.tar.gz
|
||||
```
|
||||
|
||||
### 2. Install Dependencies (if changed)
|
||||
|
||||
Check requirements.txt and package.json for changes:
|
||||
```bash
|
||||
# Python dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Node dependencies (if needed)
|
||||
cd frontend && npm ci && cd ..
|
||||
```
|
||||
|
||||
### 3. Run Database Migrations
|
||||
|
||||
```bash
|
||||
docker compose exec api flask db upgrade
|
||||
docker compose exec api flask plugin upgrade-all
|
||||
```
|
||||
|
||||
**Watch for:**
|
||||
- Migration errors
|
||||
- Foreign key violations
|
||||
- Timeout on large migrations
|
||||
|
||||
### 4. Restart Services
|
||||
|
||||
```bash
|
||||
docker compose restart api
|
||||
```
|
||||
|
||||
Verify restart:
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs api --tail 50
|
||||
```
|
||||
|
||||
### 5. Verify Deployment
|
||||
|
||||
- [ ] All containers running
|
||||
- [ ] API responding: curl -k https://localhost:5001/api/health
|
||||
- [ ] Frontend loads: https://localhost:5001
|
||||
- [ ] Login works
|
||||
- [ ] Recent endpoints reporting
|
||||
|
||||
### 6. Monitor for Issues
|
||||
|
||||
```bash
|
||||
# Watch logs for 5 minutes
|
||||
docker compose logs -f api
|
||||
```
|
||||
|
||||
## Post-Deployment
|
||||
|
||||
- [ ] Verify endpoints reporting (check last_seen timestamps)
|
||||
- [ ] Test critical workflows (asset creation, search)
|
||||
- [ ] Check plugin loading: docker compose exec api flask plugin list
|
||||
- [ ] Notify users deployment complete
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If issues detected:
|
||||
|
||||
1. Restore VM snapshot:
|
||||
```bash
|
||||
/vm-snapshot restore "before-deploy-$BUNDLE_DATE"
|
||||
```
|
||||
|
||||
2. Or rollback git:
|
||||
```bash
|
||||
git checkout $LAST_TAG
|
||||
docker compose down
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
3. Restore database backup (if schema changed)
|
||||
|
||||
## Changes in This Deployment
|
||||
|
||||
$(git log $LAST_TAG..HEAD --oneline --no-merges)
|
||||
|
||||
## Database Migrations
|
||||
|
||||
$(docker compose exec api flask db history | grep -A 5 "current")
|
||||
|
||||
## Testing Results
|
||||
|
||||
- pytest: PASS (42 tests, 0 failures)
|
||||
- Style check: PASS
|
||||
- Security scan: PASS (0 critical, 0 high)
|
||||
- Migration check: PASS (linear chains, no conflicts)
|
||||
```
|
||||
|
||||
**2.4 Bundle Verification:**
|
||||
|
||||
```bash
|
||||
# Verify bundle integrity
|
||||
tar -tzf ~/_transfer/$BUNDLE_NAME | head -20
|
||||
|
||||
# Check bundle size
|
||||
du -h ~/_transfer/$BUNDLE_NAME
|
||||
```
|
||||
|
||||
Expected: < 50MB (excluding frontend)
|
||||
Expected frontend: < 20MB
|
||||
|
||||
### Phase 3: Stage Deploy on Dev PC (Optional but Recommended)
|
||||
|
||||
**3.1 Transfer Bundle to Dev PC:**
|
||||
|
||||
(Manual: Copy bundle via USB, shared drive, or approved transfer method)
|
||||
|
||||
**3.2 Deploy to Dev Server (ops branch):**
|
||||
|
||||
```bash
|
||||
# On dev PC
|
||||
cd /path/to/shopdb-dev
|
||||
tar -xzf ~/shopdb-deploy-$BUNDLE_DATE.tar.gz
|
||||
tar -xzf ~/shopdb-frontend-$BUNDLE_DATE.tar.gz
|
||||
|
||||
# Run deployment steps
|
||||
docker compose exec api flask db upgrade
|
||||
docker compose exec api flask plugin upgrade-all
|
||||
docker compose restart api
|
||||
|
||||
# Verify
|
||||
/production-health
|
||||
```
|
||||
|
||||
**3.3 Smoke Test on Dev:**
|
||||
|
||||
- Test all plugin pages load
|
||||
- Create test asset
|
||||
- Run full test suite
|
||||
- Check for errors in logs
|
||||
|
||||
**If dev deploy fails:**
|
||||
- Fix issues
|
||||
- Create new bundle
|
||||
- Re-test on dev
|
||||
- Do NOT proceed to production
|
||||
|
||||
### Phase 4: Production Deployment
|
||||
|
||||
**4.1 Create Production Backup:**
|
||||
|
||||
```bash
|
||||
# Database backup
|
||||
docker compose exec db mysqldump -u root -p shopdb > ~/backups/shopdb-pre-deploy-$BUNDLE_DATE.sql
|
||||
|
||||
# VM snapshot
|
||||
/vm-snapshot create "before-deploy-$BUNDLE_DATE"
|
||||
```
|
||||
|
||||
**4.2 Notify Users:**
|
||||
|
||||
```
|
||||
Maintenance Window: [start time] - [end time]
|
||||
ShopDB will be unavailable during deployment.
|
||||
Expected downtime: 15-30 minutes
|
||||
```
|
||||
|
||||
**4.3 Execute Deployment Runbook:**
|
||||
|
||||
Follow `deployment-runbook-$BUNDLE_DATE.md` steps exactly.
|
||||
|
||||
**4.4 Monitor Deployment:**
|
||||
|
||||
Watch logs during restart:
|
||||
```bash
|
||||
docker compose logs -f api
|
||||
```
|
||||
|
||||
Look for:
|
||||
- [X] "Starting gunicorn"
|
||||
- [X] "Listening at https://0.0.0.0:5001"
|
||||
- [X] "Loaded plugins: 12"
|
||||
- [ ] Exceptions or errors
|
||||
|
||||
**4.5 Initial Verification:**
|
||||
|
||||
```bash
|
||||
# Quick checks (< 2 min)
|
||||
docker compose ps # All running?
|
||||
curl -k https://localhost:5001/api/health # API responds?
|
||||
curl -k https://localhost:5001/ # Frontend loads?
|
||||
```
|
||||
|
||||
### Phase 5: Post-Deploy Validation
|
||||
|
||||
**5.1 Run Health Checks:**
|
||||
|
||||
```bash
|
||||
/production-health
|
||||
```
|
||||
|
||||
**Expected:** All checks pass, no critical errors.
|
||||
|
||||
**5.2 Verify Critical Workflows:**
|
||||
|
||||
Test each critical workflow:
|
||||
|
||||
1. **Login:**
|
||||
- Test admin login
|
||||
- Test standard user login
|
||||
- Verify sessions work
|
||||
|
||||
2. **Asset Management:**
|
||||
- Create test asset
|
||||
- Search for asset
|
||||
- Update asset
|
||||
- Delete test asset
|
||||
|
||||
3. **Endpoint Reporting:**
|
||||
- Check endpoint list loads
|
||||
- Verify recent heartbeats (< 10 min)
|
||||
- Check endpoint details page
|
||||
|
||||
4. **Plugin Loading:**
|
||||
```bash
|
||||
docker compose exec api flask plugin list
|
||||
```
|
||||
Expected: All plugins loaded, no import errors
|
||||
|
||||
**5.3 Monitor for 1 Hour:**
|
||||
|
||||
Watch logs for anomalies:
|
||||
```bash
|
||||
# Check every 10 minutes for first hour
|
||||
docker compose logs api --since 10m | grep -i "error\|exception\|critical"
|
||||
```
|
||||
|
||||
**5.4 Verify Endpoint Agents Still Reporting:**
|
||||
|
||||
```bash
|
||||
# Check last_seen timestamps
|
||||
docker compose exec api flask shell -c "
|
||||
from plugins.endpoints.models import Endpoint
|
||||
from datetime import datetime, timedelta
|
||||
recent = Endpoint.query.filter(
|
||||
Endpoint.last_seen > datetime.utcnow() - timedelta(minutes=10)
|
||||
).count()
|
||||
print(f'Endpoints reporting in last 10 min: {recent}')
|
||||
"
|
||||
```
|
||||
|
||||
Expected: At least 1 (VM should report)
|
||||
|
||||
### Phase 6: Rollback (If Issues Detected)
|
||||
|
||||
**Rollback Decision Criteria:**
|
||||
|
||||
**MUST rollback if:**
|
||||
- Database migration failed
|
||||
- Critical plugin won't load
|
||||
- API completely non-functional
|
||||
- Data integrity issues
|
||||
|
||||
**SHOULD rollback if:**
|
||||
- Multiple endpoints not reporting
|
||||
- Critical workflow broken
|
||||
- Performance severely degraded
|
||||
- Security vulnerability introduced
|
||||
|
||||
**Can monitor and fix if:**
|
||||
- Single plugin has minor issue
|
||||
- Non-critical feature broken
|
||||
- Performance slightly slower
|
||||
- Cosmetic UI issues
|
||||
|
||||
**Rollback Procedure:**
|
||||
|
||||
**Option A: VM Snapshot Restore (Fastest)**
|
||||
```bash
|
||||
/vm-snapshot restore "before-deploy-$BUNDLE_DATE"
|
||||
```
|
||||
|
||||
Time: ~5 minutes
|
||||
Scope: Complete system rollback
|
||||
|
||||
**Option B: Git Rollback**
|
||||
```bash
|
||||
git checkout $LAST_TAG
|
||||
docker compose down
|
||||
docker compose -f docker-compose.prebuilt.yml build api
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Time: ~10 minutes
|
||||
Scope: Code only (database may need restore)
|
||||
|
||||
**Option C: Database Restore (If Schema Changed)**
|
||||
```bash
|
||||
# Restore database backup
|
||||
docker compose exec db mysql -u root -p shopdb < ~/backups/shopdb-pre-deploy-$BUNDLE_DATE.sql
|
||||
|
||||
# Or point-in-time recovery if binlog enabled
|
||||
```
|
||||
|
||||
Time: ~15-30 minutes depending on database size
|
||||
|
||||
**After Rollback:**
|
||||
1. Verify system functional
|
||||
2. Document what went wrong
|
||||
3. Fix issues before retry
|
||||
4. Notify users system restored
|
||||
|
||||
### Phase 7: Deployment Complete
|
||||
|
||||
**7.1 Update Documentation:**
|
||||
|
||||
- Document any issues encountered
|
||||
- Update deployment notes
|
||||
- Record deployment time and downtime
|
||||
- Note any manual steps required
|
||||
|
||||
**7.2 Notify Stakeholders:**
|
||||
|
||||
```
|
||||
Deployment complete: ShopDB v$TAG
|
||||
- Deployment time: [duration]
|
||||
- Downtime: [actual downtime]
|
||||
- Status: Success / Issues noted
|
||||
- Changes: [link to changelog]
|
||||
```
|
||||
|
||||
**7.3 Monitor for 24 Hours:**
|
||||
|
||||
Set reminder to check:
|
||||
- Logs for errors
|
||||
- Endpoint reporting
|
||||
- User feedback
|
||||
- Performance metrics
|
||||
|
||||
**7.4 Cleanup:**
|
||||
|
||||
```bash
|
||||
# Remove old bundles (> 30 days)
|
||||
find ~/_transfer/ -name "shopdb-deploy-*.tar.gz" -mtime +30 -delete
|
||||
|
||||
# Remove old backups (> 30 days)
|
||||
find ~/backups/ -name "shopdb-pre-deploy-*.sql" -mtime +30 -delete
|
||||
|
||||
# Clean up old VM snapshots
|
||||
/vm-snapshot cleanup
|
||||
```
|
||||
|
||||
## Time Estimates
|
||||
|
||||
| Phase | Time | Can Fail? |
|
||||
|-------|------|-----------|
|
||||
| Pre-deploy validation | 10-15 min | Yes (fix issues) |
|
||||
| Bundle creation | 5 min | No |
|
||||
| Stage deploy (dev) | 15-20 min | Yes (fix before prod) |
|
||||
| Production backup | 5 min | No |
|
||||
| Production deploy | 15-20 min | Yes (rollback) |
|
||||
| Post-deploy validation | 15-30 min | Yes (rollback) |
|
||||
| **Total** | **65-100 min** | |
|
||||
|
||||
**Downtime:** 5-15 minutes (during production deploy phase)
|
||||
|
||||
## Automation Opportunities
|
||||
|
||||
**Current:** 312 hrs/year coordination burden
|
||||
|
||||
**With this skill:** ~50-100 hrs saved/year
|
||||
|
||||
**Further automation:**
|
||||
- Automated bundle transfer (if air-gap can be bridged)
|
||||
- Automated staging tests
|
||||
- Automated rollback triggers
|
||||
- Continuous deployment (requires air-gap solution)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Bundle extraction fails:**
|
||||
- Check disk space: `df -h`
|
||||
- Verify bundle integrity: `tar -tzf bundle.tar.gz`
|
||||
- Try smaller extraction: `tar -xzf bundle.tar.gz --one-top-level`
|
||||
|
||||
**Migration fails:**
|
||||
- Check database connectivity
|
||||
- Verify migration order (ADR-008)
|
||||
- Check for data that violates new constraints
|
||||
- See `/migration-check` for detailed validation
|
||||
|
||||
**Services won't start:**
|
||||
- Check logs: `docker compose logs api`
|
||||
- Verify port availability: `netstat -tulpn | grep 5001`
|
||||
- Check Docker status: `docker ps -a`
|
||||
- Try rebuild: `/docker-rebuild`
|
||||
|
||||
**Rollback fails:**
|
||||
- VM snapshot may be corrupted
|
||||
- Try alternative rollback method
|
||||
- Contact system admin if all methods fail
|
||||
|
||||
## Related
|
||||
|
||||
- `/pre-commit` - Pre-deployment validation
|
||||
- `/production-health` - Health monitoring
|
||||
- `/migration-check` - Database migration validation
|
||||
- `/docker-rebuild` - Container rebuild
|
||||
- `/vm-snapshot` - VM snapshot management
|
||||
- [[workflow-patterns]] - Common workflows
|
||||
- [[maintenance-footprint-baseline]] - 312 hrs/year coordination burden
|
||||
- ADR-004: Deployment topology
|
||||
Reference in New Issue
Block a user