ai-playbook 1.0.0

package/commands/rollback.md

@@ -0,0 +1,152 @@
+# rollback Command
+
+**Purpose:** Rollback to previous version in case of deployment issues  
+**Usage:** `npm run rollback` or `FORCE=true npm run rollback`  
+**Trigger:** EMERGENCY - Production is broken
+
+## CRITICAL SITUATION
+
+🚨 Use this only when:
+- Production is broken
+- Cannot fix immediately
+- Users are impacted
+- Rollback is safer than fix
+
+## What Rollback Does
+
+1. Finds previous version
+2. Restores application
+3. Restores database (if possible)
+4. Verifies health
+5. Notifies team
+
+## Rollback Process
+
+```
+1. Determine previous version
+   ↓
+2. Request confirmation
+   ↓
+3. Restore application code
+   ↓
+4. Restore database if possible
+   ↓
+5. Verify health checks
+   ↓
+6. Notify team
+```
+
+## Confirmation
+
+```
+⚠️ WARNING: This will rollback to the previous version
+Continue? (y/N)
+```
+
+## Success Criteria
+
+✓ Previous version restored  
+✓ Health checks pass  
+✓ Service responds  
+✓ No data loss  
+
+## What Gets Rolled Back
+
+- ✓ Application code
+- ✓ Static assets
+- ✓ Configuration (in some cases)
+- ✗ Database (if migrations ran)
+
+## Database Considerations
+
+**If migrations ran:**
+- Automatic rollback: Limited
+- Manual rollback: May be needed
+- Backup restore: May be necessary
+
+**Migration rollback:**
+1. Identify problematic migration
+2. Run rollback migration
+3. Restore previous schema
+4. Verify data integrity
+
+## Time Impact
+
+- Application: 1-5 minutes
+- Database: Depends on size
+- Verification: 2-5 minutes
+- Total: 5-15 minutes typical
+
+## After Rollback
+
+✓ Service restored  
+✓ Users can access  
+✓ Team investigates  
+✓ Root cause found  
+✓ Fix developed  
+✓ Redeploy when ready  
+
+## Post-Rollback Actions
+
+1. **Immediately:**
+   - Verify service works
+   - Check error logs
+   - Monitor metrics
+
+2. **Within 30 minutes:**
+   - Notify stakeholders
+   - Begin investigation
+   - Create incident report
+
+3. **Within 24 hours:**
+   - Root cause analysis
+   - Fix implementation
+   - Staging test
+   - Redeploy
+
+## Communication
+
+- [ ] Team notified
+- [ ] Status page updated
+- [ ] Customers informed
+- [ ] Incident created
+- [ ] Post-mortem scheduled
+
+## Related Commands
+
+- `deploy-prod` - Production deployment
+- `deploy-staging` - Staging deployment
+- `migrate` - Database migrations
+
+## Prevention
+
+Prevent rollbacks by:
+- ✓ Thorough testing
+- ✓ Stage before prod
+- ✓ Feature flags
+- ✓ Canary deployments
+- ✓ Health checks
+
+## Incident Response
+
+After rollback:
+
+```
+1. Stabilize (Done - rollback)
+2. Communicate (Notify team/users)
+3. Investigate (Root cause)
+4. Fix (Develop solution)
+5. Test (Verify fix)
+6. Deploy (Redeploy fixed version)
+7. Monitor (Watch for issues)
+8. Review (Post-mortem)
+```
+
+## Notes
+
+- Rollback is last resort
+- Always try hot fix first
+- Document what went wrong
+- Use for learning
+- Improve deployment process
+- Prevention is key

package/commands/seed.md

@@ -0,0 +1,178 @@
+# seed Command
+
+**Purpose:** Seed database with initial test data  
+**Usage:** `npm run seed`  
+**Trigger:** Initial setup, reset test data
+
+## Description
+
+Populates database with test data for development and testing.
+
+## Test Data Included
+
+- **Users:** Admin, test users
+- **Posts:** Sample posts
+- **Comments:** Sample comments
+- **Products:** Test products
+- **Orders:** Test orders
+
+## When to Seed
+
+- **Initial setup:** Fresh database
+- **Testing:** Reset to known state
+- **Demo:** Show features
+- **Development:** Populate for testing
+
+## Seeding Process
+
+1. Check database exists
+2. Run migrations first
+3. Populate tables
+4. Create relationships
+5. Verify data created
+
+## Success Criteria
+
+✓ Data inserted  
+✓ No errors  
+✓ Relationships valid  
+✓ Ready to test  
+
+## Running Seed
+
+```bash
+# Seed database
+npm run seed
+
+# Force reset
+FORCE=true npm run seed
+
+# Interactive (asks for confirmation)
+npm run seed
+
+# With specific data set
+npm run seed -- --dataset=demo
+```
+
+## Test User Credentials
+
+After seeding, login with:
+
+```
+Email: test@example.com
+Password: testpassword123
+
+Admin Email: admin@example.com
+Password: adminpassword123
+```
+
+## Data Models
+
+| Model | Count | Sample |
+|---|---|---|
+| Users | 5 | John, Jane, Admin... |
+| Posts | 20 | "Hello World", "Test"... |
+| Comments | 50 | Sample comments |
+| Products | 10 | Product A, B, C... |
+
+## Seeding Methods
+
+### Prisma
+```bash
+npx prisma db seed
+```
+
+### Django
+```bash
+python manage.py loaddata fixtures/*.json
+```
+
+### SQL
+```bash
+psql -f sql/seeds/data.sql
+```
+
+## Seed Files
+
+Located in:
+- `prisma/seed.ts` - Prisma seed
+- `scripts/seed.py` - Python seed
+- `sql/seeds/` - SQL seed files
+- `fixtures/` - Django fixtures
+
+## Reset Data
+
+To clear and reseed:
+
+```bash
+# Clear all data
+npm run db:reset
+
+# Or manually
+npm run migrate rollback
+npm run migrate
+npm run seed
+```
+
+## Development vs Testing
+
+**Development seed:**
+- More variety
+- Realistic data
+- Multiple users
+- Complex relationships
+
+**Testing seed:**
+- Minimal data
+- Known values
+- Predictable state
+- Fast to run
+
+## Verification
+
+After seeding, verify:
+
+```bash
+# Count records
+SELECT COUNT(*) FROM users;
+
+# Check data
+SELECT * FROM users LIMIT 5;
+
+# Verify relationships
+SELECT * FROM posts WHERE user_id = 1;
+```
+
+## Clearing Seed Data
+
+To remove test data:
+
+```bash
+# Delete all data (dangerous!)
+npm run db:clear
+
+# Or reset to migrations only
+npm run db:reset
+```
+
+## Related Commands
+
+- `setup` - Initial environment
+- `migrate` - Database schema
+- `dev` - Start with seeded data
+- `test` - Tests with clean data
+
+## Environment Variables
+
+- `SEED_DATA=demo` - Use demo seed
+- `SEED_DATA=test` - Use test seed
+- `FORCE=true` - Skip confirmation
+
+## Notes
+
+- Seeding is idempotent (safe to repeat)
+- Test data is not production data
+- Use realistic values for testing
+- Update seeds when schema changes
+- Keep seeds small for fast startup
+- Use transactions for consistency

package/commands/setup.md

@@ -0,0 +1,109 @@
+# setup Command
+
+**Purpose:** Initialize development environment with all dependencies and configuration  
+**Usage:** `npm run setup` or manual script invocation  
+**Trigger:** First-time setup, environment reset
+
+## Description
+
+Prepares development environment for work by installing dependencies, configuring files, and initializing database.
+
+## Steps
+
+1. Check prerequisites (git, node, npm)
+2. Install npm dependencies
+3. Install Python dependencies (if applicable)
+4. Create `.env` from template
+5. Run database migrations
+6. Seed database with test data
+7. Build project
+
+## Prerequisites
+
+- Node.js 18+
+- npm or yarn
+- Git
+- Python 3.8+ (if applicable)
+- PostgreSQL/MySQL (if applicable)
+
+## Success Criteria
+
+✓ Dependencies installed  
+✓ `.env` file created  
+✓ Database migrations run  
+✓ Database seeded  
+✓ Project builds  
+
+## What Gets Installed
+
+- npm packages from `package.json`
+- Python packages from `requirements.txt`
+- Development tools
+- Git hooks
+
+## Configuration
+
+After setup:
+1. Edit `.env` with your configuration
+2. Update database credentials
+3. Configure API keys
+4. Verify health check passes
+
+## Environment Variables
+
+No special variables needed. Uses defaults from `.env.example`.
+
+## Failure Handling
+
+| Issue | Solution |
+|---|---|
+| Missing Node.js | Install from nodejs.org |
+| npm errors | Delete node_modules, reinstall |
+| DB connection fails | Check credentials in .env |
+| Migration fails | Check database exists |
+
+## Typical Output
+
+```
+✓ Prerequisites found
+✓ npm dependencies installed
+✓ Created .env from template
+✓ Database migrated
+✓ Database seeded
+✓ Project built
+✓ Setup complete!
+```
+
+## Next Steps
+
+```bash
+# Start development server
+npm run dev
+
+# Run tests
+npm test
+
+# Check code quality
+npm run lint
+```
+
+## Troubleshooting
+
+- **Port already in use**: Change port in .env
+- **Database locked**: Kill other connections
+- **Module not found**: Run npm install again
+- **Permission denied**: Check file permissions
+
+## Related Commands
+
+- `dev` - Start development server
+- `test` - Run tests
+- `migrate` - Run migrations
+- `seed` - Seed database
+
+## Notes
+
+- Safe to run multiple times
+- Idempotent (won't duplicate data)
+- Takes 2-5 minutes typically
+- Internet required for npm install

package/commands/test.md

@@ -0,0 +1,134 @@
+# test Command
+
+**Purpose:** Run all tests with coverage reporting  
+**Usage:** `npm test`  
+**Trigger:** Validate code changes work
+
+## Description
+
+Runs complete test suite including unit tests, integration tests, and generates coverage reports.
+
+## Test Types
+
+| Type | Scope | Blocking |
+|---|---|---|
+| Unit tests | Individual functions | Yes |
+| Integration tests | Component interactions | Yes |
+| Coverage report | Test coverage % | Yes |
+
+## What Gets Tested
+
+- Business logic
+- API endpoints
+- Database operations
+- Error handling
+- Edge cases
+- User workflows
+
+## Success Criteria
+
+✓ All unit tests pass  
+✓ All integration tests pass  
+✓ Coverage >= 80%  
+✓ No regressions  
+
+## Running Tests
+
+```bash
+# All tests
+npm test
+
+# Specific test file
+npm test -- auth.test.js
+
+# Watch mode
+npm test -- --watch
+
+# With coverage
+npm test -- --coverage
+
+# Verbose output
+npm test -- --verbose
+```
+
+## Test Runners
+
+| Language | Runner | Command |
+|---|---|---|
+| JavaScript | Jest | npm test |
+| Python | pytest | pytest |
+| Go | go test | go test ./... |
+
+## Coverage Report
+
+- Located in `coverage/`
+- HTML report: `coverage/lcov-report/index.html`
+- Summary: Printed in console
+- Threshold: 80% default
+
+## Failure Handling
+
+| Scenario | Behavior |
+|---|---|
+| Test fails | Shows error, fails command |
+| Coverage low | Fails if below 80% |
+| Timeout | Test fails after 5s |
+| Module error | Shows import error |
+
+## Environment Variables
+
+- `CI=true` - Strict mode
+- `SKIP_TESTS=true` - Skip tests
+- `COVERAGE=true` - Generate coverage
+
+## Performance
+
+Typical test times:
+- Unit tests: 5-30 seconds
+- Integration: 10-60 seconds
+- Coverage: +5 seconds
+
+## Common Issues
+
+| Issue | Solution |
+|---|---|
+| Timeout | Increase timeout, optimize test |
+| Flaky test | Add retries, fix timing |
+| Import error | Install dependency |
+| Coverage low | Write more tests |
+
+## Test Patterns
+
+✓ Test happy path  
+✓ Test error cases  
+✓ Test edge cases  
+✓ Test with mocks  
+✓ Test with real data  
+
+## Debugging Tests
+
+```bash
+# Run single test
+npm test -- auth.test.js
+
+# Run matching pattern
+npm test -- --testNamePattern="auth"
+
+# Debug in Chrome
+node --inspect-brk node_modules/.bin/jest --runInBand
+```
+
+## Related Commands
+
+- `lint` - Code quality
+- `type-check` - Type validation
+- `validate` - All checks
+- `build` - Production build
+
+## Notes
+
+- Tests should be fast
+- Keep tests isolated
+- Mock external services
+- Test behavior, not implementation
+- Commit passing tests only

package/commands/validate.md

@@ -0,0 +1,147 @@
+# validate Command
+
+**Purpose:** Run all validation checks (pre-commit, pre-push)  
+**Usage:** `npm run validate`  
+**Trigger:** Before commit or push
+
+## Description
+
+Comprehensive validation suite combining linting, testing, type checking, and security checks.
+
+## Checks Performed
+
+| Check | Tool | Blocking |
+|---|---|---|
+| Linting | ESLint | Yes |
+| Testing | Jest/pytest | Yes |
+| Type checking | tsc | Yes |
+| Security | npm audit | Yes |
+| Coverage | Coverage.js | Yes |
+| Build | Webpack/tsc | Yes |
+
+## Execution Order
+
+```
+1. Lint checks
+   ↓
+2. Type checks
+   ↓
+3. Unit tests
+   ↓
+4. Integration tests
+   ↓
+5. Security audit
+   ↓
+6. Build verification
+```
+
+## Success Criteria
+
+✓ No lint errors  
+✓ No type errors  
+✓ All tests pass  
+✓ No vulnerabilities  
+✓ Coverage >= 80%  
+✓ Build succeeds  
+
+## Running Validation
+
+```bash
+# Full validation
+npm run validate
+
+# Skip tests (faster)
+SKIP_TESTS=true npm run validate
+
+# Verbose output
+VERBOSE=true npm run validate
+
+# Dry-run
+DRY_RUN=true npm run validate
+```
+
+## Typical Output
+
+```
+Running code quality checks...
+✓ Lint passed
+✓ Type check passed
+
+Running tests...
+✓ Tests passed
+
+Running security checks...
+✓ No vulnerabilities
+
+Verifying build...
+✓ Build successful
+
+✓ All validation checks passed!
+```
+
+## Failure Scenarios
+
+| Failure | Action |
+|---|---|
+| Lint fails | Fix style issues |
+| Tests fail | Debug and fix |
+| Type errors | Update types |
+| Vulnerabilities | Update packages |
+| Build fails | Check errors |
+
+## Environment Variables
+
+- `SKIP_TESTS=true` - Skip tests
+- `CI=true` - Strict mode
+- `VERBOSE=true` - Show all output
+- `DRY_RUN=true` - Preview only
+
+## Performance
+
+Typical time: 30-120 seconds
+- Lint: 2-5s
+- Tests: 10-60s
+- Type check: 1-10s
+- Security: 5-10s
+- Build: 5-30s
+
+## Pre-push Checklist
+
+✓ Validate passes locally  
+✓ All tests green  
+✓ No console errors  
+✓ Commit message clear  
+✓ Branch up to date  
+✓ No sensitive data  
+
+## Failure Recovery
+
+If validation fails:
+1. Read error message carefully
+2. Fix the issue
+3. Re-run validate
+4. Repeat until passing
+5. Then commit/push
+
+## Related Commands
+
+- `test` - Run tests only
+- `lint` - Lint only
+- `type-check` - Type check only
+- `build` - Build verification
+
+## CI/CD Integration
+
+Validation runs in CI before merge:
+- Blocks merge on failure
+- Reports all issues
+- Prevents bad code
+- Ensures quality
+
+## Notes
+
+- Run before every push
+- Faster than CI/CD
+- Catch issues early
+- Save time overall
+- Reduces deploy delays

package/context/README.md

@@ -0,0 +1,7 @@
+# Context
+
+Use this folder for shared context that shapes decisions across projects and
+roles.
+
+Load the relevant context files after role and skill routing, and prefer
+project-specific context when it conflicts with these defaults.