ai-playbook 1.0.0

package/commands/deploy-prod.md

@@ -0,0 +1,171 @@
+# deploy-prod Command
+
+**Purpose:** Deploy to production environment with safety checks  
+**Usage:** `npm run deploy:prod`  
+**Trigger:** Release to users
+
+## CRITICAL: Safety Protocol
+
+⚠️ This command deploys to PRODUCTION  
+⚠️ Requires explicit confirmation  
+⚠️ Only run when you're certain  
+⚠️ Have rollback plan ready  
+
+## Pre-deployment Requirements
+
+✓ Tested in staging  
+✓ QA approved  
+✓ All tests passing  
+✓ On main/master branch  
+✓ Branch up to date  
+✓ No uncommitted changes  
+
+## Safety Checks
+
+```
+✓ Validate all checks pass
+✓ Check branch is main
+✓ Verify no uncommitted changes
+✓ Confirm no behind remote
+✓ Build artifacts recent
+✓ Database migrations ready
+✓ Health checks configured
+```
+
+## Deployment Confirmations
+
+```
+Confirm 1: Type 'DEPLOY TO PRODUCTION'
+Confirm 2: Type 'yes' to confirm again
+```
+
+## Deployment Process
+
+1. Final validation
+2. Confirmation (typed)
+3. Build compilation
+4. Set PRODUCTION environment
+5. Deploy to production
+6. Run migrations
+7. Health checks
+8. Monitor for errors
+
+## Success Criteria
+
+✓ Build succeeds  
+✓ Health check passes  
+✓ No error spikes  
+✓ API responds  
+✓ Database queries work  
+
+## What Gets Deployed
+
+- Compiled code
+- Static assets
+- Database migrations
+- Configuration
+- Environment variables
+
+## Health Verification
+
+```
+Check 1: Service available
+Check 2: Database connected
+Check 3: Cache working
+Check 4: External APIs responding
+```
+
+## Failure Handling
+
+| Failure | Action |
+|---|---|
+| Pre-deploy check fails | Stop, fix, retry |
+| Build fails | Fix code, rebuild, retry |
+| Migration fails | Investigate, rollback |
+| Health check fails | Investigate, rollback |
+| Error spike | Monitor, rollback if needed |
+
+## Monitoring Post-deployment
+
+After deploying:
+1. **Immediately:**
+   - Check error logs
+   - Monitor health endpoint
+   - Watch error rate
+
+2. **5 minutes:**
+   - Check performance
+   - Verify features work
+   - Monitor database
+
+3. **30 minutes:**
+   - Check error patterns
+   - Verify metrics
+   - Review customer reports
+
+## Emergency Rollback
+
+If critical issues:
+```bash
+npm run rollback
+```
+
+Restores previous version immediately.
+
+## Communication
+
+- Notify team before deploy
+- Announce in #deployments
+- Update status page
+- Document any issues
+- Post-mortem if problems
+
+## Release Notes
+
+What to include:
+- Features added
+- Bugs fixed
+- Breaking changes
+- Database migrations
+- New dependencies
+
+## Database Considerations
+
+- Migrations run first
+- Data backups created
+- Rollback tested
+- No data loss expected
+
+## Deployment Schedule
+
+Best times:
+- Weekday mornings
+- Off-peak hours
+- Never Friday afternoon
+- Never before weekend
+- Time for monitoring
+
+## Related Commands
+
+- `deploy-staging` - Staging deployment
+- `rollback` - Emergency rollback
+- `release` - Release automation
+
+## Post-deployment Checklist
+
+- [ ] Health checks passing
+- [ ] No error spike
+- [ ] Features working
+- [ ] Performance normal
+- [ ] Database responsive
+- [ ] Team notified
+- [ ] Monitoring active
+
+## Notes
+
+- Production is high stakes
+- Take your time
+- Double-check everything
+- Have team available
+- Monitor closely
+- Be ready to rollback

package/commands/deploy-staging.md

@@ -0,0 +1,147 @@
+# deploy-staging Command
+
+**Purpose:** Deploy to staging environment  
+**Usage:** `npm run deploy:staging`  
+**Trigger:** Test deployment before production
+
+## Description
+
+Deploys code to staging environment for testing before production release.
+
+## Deployment Process
+
+1. Validate all checks pass
+2. Confirm deployment
+3. Build artifacts
+4. Set environment (STAGING)
+5. Deploy to staging
+6. Run migrations (if needed)
+7. Verify health checks
+
+## Pre-deployment
+
+✓ Code committed  
+✓ Tests passing  
+✓ Lint passing  
+✓ Build successful  
+
+## Staging Environment
+
+- **Purpose:** Production-like testing
+- **Data:** Copy of prod (or test data)
+- **URL:** https://staging.example.com
+- **Reset:** Safe to reset
+
+## Deployment Targets
+
+| Platform | Method |
+|---|---|
+| Vercel | Auto-deploy on push |
+| Heroku | `git push heroku-staging` |
+| AWS | S3 sync, CloudFormation |
+| Docker | Build and push image |
+
+## Process Steps
+
+```
+1. Validate code quality
+   ↓
+2. Build artifacts
+   ↓
+3. Deploy to staging
+   ↓
+4. Run migrations
+   ↓
+5. Smoke tests
+   ↓
+6. Health checks
+```
+
+## Success Criteria
+
+✓ Deployment succeeds  
+✓ Health check passes  
+✓ No errors in logs  
+✓ App responds correctly  
+
+## Failure Recovery
+
+| Failure | Action |
+|---|---|
+| Validation fails | Fix issues, retry |
+| Deployment fails | Check logs, debug |
+| Migration fails | Rollback, fix, retry |
+| Health check fails | Investigate, rollback |
+
+## Testing in Staging
+
+After deployment:
+1. Verify app loads
+2. Test main features
+3. Check API endpoints
+4. Review logs
+5. Monitor performance
+
+## Database Management
+
+- **Migrations run:** Automatically
+- **Data reset:** Manual if needed
+- **Backup:** Before major changes
+- **Seed data:** Load test data
+
+## Environment Variables
+
+All staging secrets in:
+- `.env.staging`
+- Environment configuration
+- Secrets manager
+
+## Monitoring
+
+After deployment:
+- Check error logs
+- Monitor response times
+- Verify database queries
+- Check memory usage
+
+## Related Commands
+
+- `validate` - Pre-deployment checks
+- `build` - Build artifacts
+- `migrate` - Database migrations
+- `deploy-prod` - Production deploy
+
+## Rolling Back
+
+If issues in staging:
+```bash
+# Rollback to previous version
+npm run rollback
+```
+
+## Logs and Debugging
+
+```bash
+# View staging logs
+heroku logs -a staging-app
+
+# Check health
+curl https://staging.example.com/health
+```
+
+## Approval Process
+
+Typically:
+1. Deploy to staging
+2. Team reviews
+3. QA tests
+4. Approve for production
+5. Deploy to production
+
+## Notes
+
+- Staging should mirror production
+- Test real scenarios in staging
+- Fix issues in staging
+- Never skip staging
+- Monitor staging after deploy

package/commands/deps.md

@@ -0,0 +1,169 @@
+# deps Command
+
+**Purpose:** Check and update dependencies  
+**Usage:** `npm run deps` or `npm outdated`  
+**Trigger:** Regular maintenance, security updates
+
+## Description
+
+Audits dependencies for updates and vulnerabilities, with options to update.
+
+## Package Managers
+
+| Language | Command |
+|---|---|
+| Node.js | npm outdated, npm audit |
+| Python | pip list --outdated |
+| Go | go list -m -u all |
+| Ruby | bundle outdated |
+
+## Checks Performed
+
+- **Outdated packages** - New versions available
+- **Security vulnerabilities** - Known exploits
+- **Deprecated packages** - No longer maintained
+- **License conflicts** - Incompatible licenses
+
+## Success Criteria
+
+✓ No critical vulnerabilities  
+✓ Dependencies current  
+✓ No deprecated packages  
+✓ Licenses compatible  
+
+## Running Dependency Check
+
+```bash
+# Check for updates
+npm outdated
+
+# Security audit
+npm audit
+
+# Update check
+npm run deps
+
+# Update packages
+UPDATE=true npm run deps
+```
+
+## Update Strategies
+
+### Minor Updates (Safe)
+```bash
+npm update
+```
+- Bug fixes only
+- Backward compatible
+- Safe to do regularly
+
+### Major Updates (Risky)
+```bash
+npm install package@latest
+```
+- Breaking changes possible
+- May require code changes
+- Test thoroughly
+
+## Severity Levels
+
+| Level | Action |
+|---|---|
+| Critical | Update immediately |
+| High | Update soon |
+| Moderate | Plan update |
+| Low | Document, don't rush |
+
+## Output Example
+
+```
+Package    Current  Wanted  Latest
+express    4.17.1   4.18.2  4.18.2
+lodash     4.17.19  4.17.21 4.17.21
+```
+
+## Security Audit
+
+```bash
+npm audit
+```
+
+Fixes vulnerabilities:
+```bash
+npm audit fix
+npm audit fix --force  # Major version bumps
+```
+
+## Update Process
+
+1. Check what's outdated: `npm outdated`
+2. Review breaking changes
+3. Update: `npm update` or `npm install package@latest`
+4. Run tests: `npm test`
+5. Verify in dev: `npm run dev`
+6. Commit updates
+
+## Python Dependency Updates
+
+```bash
+# Check updates
+pip list --outdated
+
+# Upgrade package
+pip install --upgrade package
+
+# Update requirements.txt
+pip freeze > requirements.txt
+```
+
+## Go Dependencies
+
+```bash
+# Check updates
+go list -m -u all
+
+# Update module
+go get -u module
+go mod tidy
+```
+
+## npm Audit Fixes
+
+```bash
+# Automatic fixes
+npm audit fix
+
+# Review before fixing
+npm audit --json
+
+# Force major version updates
+npm audit fix --force
+```
+
+## Maintenance Schedule
+
+- **Weekly:** Check for security updates
+- **Monthly:** Check for updates
+- **Quarterly:** Plan major version upgrades
+
+## Related Commands
+
+- `test` - Verify updates work
+- `validate` - Check compatibility
+- `build` - Test production build
+
+## Risk Management
+
+✓ Update dev dependencies first  
+✓ Test after updates  
+✓ Update incrementally  
+✓ Keep main dependencies current  
+✓ Document breaking changes  
+
+## Notes
+
+- Always test after updating
+- Pin versions in production
+- Major updates need careful planning
+- Security updates should be prioritized
+- Keep dependencies lean

package/commands/dev.md

@@ -0,0 +1,132 @@
+# dev Command
+
+**Purpose:** Start development server with hot reload and debugging  
+**Usage:** `npm run dev`  
+**Trigger:** Start local development
+
+## Description
+
+Starts development server with automatic reload on file changes, debugging enabled, and dev tools active.
+
+## What It Does
+
+1. Check dependencies are installed
+2. Load `.env` configuration
+3. Start development server
+4. Watch files for changes
+5. Hot reload on file modification
+6. Show debug logs
+
+## Server Details
+
+- **Default URL:** http://localhost:3000
+- **Hot reload:** Enabled
+- **Source maps:** Enabled
+- **Debugging:** Chrome DevTools
+- **API:** http://localhost:3000/api
+
+## Prerequisites
+
+- Setup completed (`npm run setup`)
+- `.env` file configured
+- Dependencies installed
+- Port 3000 available
+
+## Configuration
+
+Set in `.env`:
+- `PORT=3000` - Server port
+- `NODE_ENV=development` - Environment
+- `DEBUG=app:*` - Debug namespaces
+- `DATABASE_URL` - Database connection
+
+## Success Criteria
+
+✓ Server starts on port 3000  
+✓ Files watched for changes  
+✓ Hot reload working  
+✓ Logs showing requests  
+✓ No errors in console  
+
+## Usage Examples
+
+```bash
+# Start server
+npm run dev
+
+# Start on different port
+PORT=3001 npm run dev
+
+# With verbose logging
+DEBUG=* npm run dev
+
+# With debugging
+node --inspect-brk [entry-file]
+```
+
+## Browser Access
+
+1. Open http://localhost:3000
+2. DevTools auto-opens (if Chrome)
+3. Sources tab shows source maps
+4. Breakpoints work normally
+5. Console shows logs
+
+## Hot Reload
+
+Changes to these files trigger reload:
+- `.js/.ts` files
+- `.css/.scss` files
+- `.html` files
+- Config files (requires restart)
+
+## Debugging
+
+### Chrome DevTools
+1. Press F12 in browser
+2. Go to Sources tab
+3. Find file in left panel
+4. Click to set breakpoints
+5. Refresh page
+
+### VS Code
+1. Open `.vscode/launch.json`
+2. Run "Debug" from Run menu
+3. Breakpoints work in editor
+
+## Stopping Server
+
+- **Mac/Linux:** Ctrl+C
+- **Windows:** Ctrl+C
+- Process cleanup: Automatic
+
+## Common Issues
+
+| Issue | Solution |
+|---|---|
+| Port 3000 in use | Change PORT in .env |
+| Module not found | Run npm install |
+| .env missing | Copy .env.example to .env |
+| Hot reload not working | Restart server |
+
+## Performance Tips
+
+- Start on needed changes only
+- Use Chrome DevTools Performance tab
+- Profile with `--inspect` flag
+- Check Network tab for slow requests
+
+## Related Commands
+
+- `setup` - Initial setup
+- `build` - Production build
+- `test` - Run tests
+- `lint` - Code quality
+
+## Notes
+
+- Development server is NOT production-ready
+- Never use dev server in production
+- Hot reload may lose state
+- Source maps slower than production
+- CPU usage higher in dev mode