ai-playbook 1.0.0

package/commands/format.md

@@ -0,0 +1,142 @@
+# format Command
+
+**Purpose:** Auto-format code to project standards  
+**Usage:** `npm run format`  
+**Trigger:** Fix code style issues
+
+## Description
+
+Automatically formats code according to project style guide using configured formatters.
+
+## Formatters
+
+| Language | Tool |
+|---|---|
+| JavaScript/TypeScript | Prettier |
+| JSON | Prettier |
+| Markdown | Prettier |
+| Python | Black, autopep8 |
+| Go | gofmt |
+| Terraform | terraform fmt |
+| YAML | yamlfmt |
+
+## Configuration Files
+
+- `.prettierrc` - Prettier config
+- `pyproject.toml` - Black config
+- `.editorconfig` - General config
+
+## What Gets Formatted
+
+- Indentation (spaces/tabs)
+- Line length and wrapping
+- Quote style
+- Semicolon usage
+- Trailing commas
+- Import sorting
+
+## Success Criteria
+
+✓ All files formatted  
+✓ Consistent style  
+✓ No syntax errors  
+✓ Ready to commit  
+
+## Running Format
+
+```bash
+# Format all files
+npm run format
+
+# Format specific file
+npm run format -- src/app.js
+
+# Dry-run (preview only)
+npm run format -- --check
+
+# Watch mode
+npm run format -- --watch
+```
+
+## Common Formatters
+
+### Prettier (JavaScript/TypeScript/JSON)
+```bash
+prettier --write "**/*.{js,ts,json,md}"
+```
+
+### Black (Python)
+```bash
+black . --quiet
+```
+
+### gofmt (Go)
+```bash
+gofmt -s -w .
+```
+
+## Before vs After
+
+**Before:**
+```js
+function hello(  name  ) {
+    console.log( 'Hello '+name )
+}
+```
+
+**After:**
+```js
+function hello(name) {
+  console.log("Hello " + name);
+}
+```
+
+## Integration
+
+- Pre-commit hook runs format
+- IDE auto-format on save
+- CI/CD checks formatting
+- GitHub actions validate
+
+## Failure Recovery
+
+If format causes issues:
+1. Review changes
+2. Verify no logic changed
+3. Run tests to confirm
+4. Commit formatted code
+
+## Editor Integration
+
+### VS Code
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode"
+}
+```
+
+### Prettier
+```bash
+npx prettier --write .
+```
+
+## Performance
+
+- Prettier: 1-5 seconds
+- Black: 2-10 seconds
+- Multiple tools: 2-10 seconds
+
+## Related Commands
+
+- `lint` - Code quality checks
+- `validate` - All checks
+- `dev` - Development server
+
+## Notes
+
+- Format before committing
+- Run in CI/CD
+- Safe to run multiple times
+- Non-destructive (only formatting)
+- Whitespace only changes

package/commands/lint.md

@@ -0,0 +1,125 @@
+# lint Command
+
+**Purpose:** Run linters and code quality checks  
+**Usage:** `npm run lint`  
+**Trigger:** Before committing code
+
+## Description
+
+Runs static analysis and linting tools to enforce code quality standards.
+
+## Linters
+
+| Language | Tool |
+|---|---|
+| JavaScript/TypeScript | ESLint |
+| Markdown | Markdownlint |
+| JSON | jsonlint |
+| Python | Pylint, Flake8 |
+| Go | golint, go vet |
+
+## Checks Performed
+
+- Code style violations
+- Unused variables
+- Missing imports
+- Undefined variables
+- Best practice violations
+- Complexity issues
+
+## Success Criteria
+
+✓ No lint errors  
+✓ All rules pass  
+✓ Code style consistent  
+✓ No warnings (if strict)  
+
+## Configuration
+
+- `.eslintrc.json` - ESLint config
+- `.pylintrc` - Pylint config
+- `.markdownlintrc` - Markdown config
+
+## Running Lint
+
+```bash
+# Check all files
+npm run lint
+
+# Check specific file
+npm run lint -- src/auth.js
+
+# Auto-fix issues
+npm run lint -- --fix
+
+# Watch mode
+npm run lint -- --watch
+```
+
+## Auto-fix
+
+```bash
+# Auto-fix JavaScript
+npm run lint -- --fix
+
+# Format with Prettier
+npm run format
+```
+
+## Failure Handling
+
+| Error Type | Blocking |
+|---|---|
+| Error | Yes |
+| Warning | No (unless strict) |
+| Style | No |
+
+## Common Issues
+
+| Error | Fix |
+|---|---|
+| Unused variable | Remove or prefix with _ |
+| Missing import | Add import statement |
+| Line too long | Break into multiple lines |
+| Inconsistent style | Run format --fix |
+
+## Rules Categories
+
+- **Best practices** - Prevent bugs
+- **Stylistic** - Code formatting
+- **ES6+** - Modern syntax
+- **Accessibility** - Accessibility rules
+- **Security** - Security issues
+
+## Severity Levels
+
+- **Error** - Must fix before commit
+- **Warning** - Should fix but not required
+- **Info** - Nice to have
+
+## Integration
+
+- Pre-commit hook runs lint
+- CI/CD fails on errors
+- IDE shows inline errors
+- GitHub shows in review
+
+## Related Commands
+
+- `format` - Auto-format code
+- `validate` - All quality checks
+- `type-check` - Type validation
+
+## Performance
+
+- ESLint: 2-5 seconds
+- Pylint: 5-10 seconds
+- Multiple tools: 5-15 seconds
+
+## Notes
+
+- Lint before pushing
+- Fix errors immediately
+- Follow team conventions
+- Customize rules per project
+- Update rules as team evolves

package/commands/migrate.md

@@ -0,0 +1,159 @@
+# migrate Command
+
+**Purpose:** Run database migrations  
+**Usage:** `npm run migrate`  
+**Trigger:** Schema changes, deployment
+
+## Description
+
+Applies pending database schema changes and updates database structure.
+
+## Migration Tools
+
+| Framework | Tool |
+|---|---|
+| Node.js | Prisma, Knex, TypeORM |
+| Python | Alembic, Django migrations |
+| Go | golang-migrate |
+| SQL | Manual migration files |
+
+## What Migrations Do
+
+- Create tables
+- Add/remove columns
+- Create indexes
+- Modify constraints
+- Update data
+
+## Success Criteria
+
+✓ No errors  
+✓ Schema updated  
+✓ Data intact  
+✓ Rollback available  
+
+## Running Migrations
+
+```bash
+# Run all pending migrations
+npm run migrate
+
+# Specific migration
+npm run migrate -- migration-name
+
+# Dry-run (preview)
+npm run migrate -- --dry-run
+
+# Rollback
+npm run migrate -- rollback
+
+# Status
+npm run migrate -- status
+```
+
+## Types of Migrations
+
+### Schema Changes
+```sql
+ALTER TABLE users ADD COLUMN age INT;
+CREATE INDEX idx_email ON users(email);
+```
+
+### Data Migrations
+```sql
+UPDATE users SET status = 'active' WHERE created_at > NOW();
+```
+
+## Migration Files
+
+Located in `migrations/` or `db/migrations/`
+
+**Naming:**
+- `001_create_users.sql`
+- `002_add_email_index.sql`
+- `003_backfill_status.sql`
+
+## Prisma Migrations
+
+```bash
+# Create migration
+prisma migrate dev --name add_email
+
+# Deploy
+prisma migrate deploy
+
+# Rollback
+prisma migrate resolve --rolled-back add_email
+```
+
+## Django Migrations
+
+```bash
+# Make migrations
+python manage.py makemigrations
+
+# Apply
+python manage.py migrate
+
+# Rollback
+python manage.py migrate app 0001
+```
+
+## Safety
+
+Migrations are:
+- Version controlled
+- Reversible (when possible)
+- Tracked in database
+- Atomic (all or nothing)
+
+## Failure Handling
+
+| Failure | Recovery |
+|---|---|
+| Syntax error | Fix migration, retry |
+| Constraint violation | Adjust migration, retry |
+| Data loss | Restore backup, fix migration |
+
+## Data Safety
+
+✓ Always backup first  
+✓ Test in staging  
+✓ Never skip migrations  
+✓ Keep migrations small  
+✓ Document complex changes  
+
+## Environment Variables
+
+- `DATABASE_URL` - Database connection
+- `SKIP_HOOKS=true` - Skip validation
+
+## Performance
+
+Migration time varies:
+- Small schema: < 1 second
+- Data migration: Seconds to minutes
+- Large tables: Can take longer
+
+## Best Practices
+
+✓ One logical change per migration  
+✓ Test migrations locally  
+✓ Migrations are one-way  
+✓ Keep migrations small  
+✓ Document complex logic  
+✓ No downtime migrations  
+
+## Related Commands
+
+- `seed` - Populate test data
+- `setup` - Initial environment
+- `deploy-staging` - Deploy with migrations
+
+## Notes
+
+- Migrations run on deploy
+- Order matters (sequential)
+- Cannot skip migrations
+- Backup before large migrations
+- Test rollback scenarios

package/commands/release.md

@@ -0,0 +1,183 @@
+# release Command
+
+**Purpose:** Create a release with version bump, changelog, and git tags  
+**Usage:** `npm run release [major|minor|patch]`  
+**Trigger:** Release to users
+
+## Description
+
+Automates release process: version bump, changelog generation, git tagging, and version commit.
+
+## Release Types
+
+| Type | Version Change | When |
+|---|---|---|
+| **patch** | 1.0.0 → 1.0.1 | Bug fixes |
+| **minor** | 1.0.0 → 1.1.0 | New features |
+| **major** | 1.0.0 → 2.0.0 | Breaking changes |
+
+## Pre-release Checklist
+
+✓ On main/master  
+✓ All tests passing  
+✓ Code committed  
+✓ No uncommitted changes  
+✓ Branch up to date  
+✓ Changelog reviewed  
+
+## Release Process
+
+1. **Validate** - Ensure all checks pass
+2. **Version bump** - Update version numbers
+3. **Changelog** - Generate from commits
+4. **Commit** - Version bump commit
+5. **Tag** - Create git tag
+6. **Push** - Push to remote
+
+## Running Release
+
+```bash
+# Patch release (bugfix)
+npm run release patch
+
+# Minor release (feature)
+npm run release minor
+
+# Major release (breaking)
+npm run release major
+
+# Custom version
+npm run release 2.1.0
+```
+
+## What Gets Updated
+
+- `package.json` - Version
+- `package-lock.json` - Lock version
+- `CHANGELOG.md` - Release notes
+- `setup.py` - Python version (if exists)
+- `Cargo.toml` - Rust version (if exists)
+
+## Changelog Generation
+
+Automatic from commit messages:
+
+```
+feat: Add new API endpoint  → Added
+fix: Resolve database issue  → Fixed
+docs: Update README          → Documentation
+refactor: Clean up code      → Changed
+```
+
+## Version Numbering
+
+Follow Semantic Versioning (semver):
+
+```
+MAJOR.MINOR.PATCH
+ 2  .  1   . 0
+
+Breaking change → MAJOR++
+New feature     → MINOR++
+Bug fix         → PATCH++
+```
+
+## Git Tags
+
+```
+Tag format: v1.2.3
+Example: v2.1.0
+
+git tag -a v2.1.0 -m "Release v2.1.0"
+git push origin v2.1.0
+```
+
+## Release Validation
+
+Before tagging:
+✓ Build succeeds  
+✓ Tests pass  
+✓ Lint passes  
+✓ Type checks pass  
+
+## After Release
+
+1. **GitHub Release**
+   - Go to Releases tab
+   - Create release from tag
+   - Copy changelog
+   - Publish release
+
+2. **Deploy**
+   - Deploy to staging
+   - Test in staging
+   - Deploy to production
+
+3. **Announce**
+   - Post release notes
+   - Update website
+   - Notify users
+   - Send email
+
+## Version Examples
+
+```
+1.0.0 - Initial release
+1.0.1 - Bugfix patch
+1.1.0 - New feature (minor)
+2.0.0 - Major breaking changes
+
+Development: 1.0.0-alpha.1
+Pre-release: 1.0.0-rc.1
+```
+
+## Release Schedule
+
+Recommended:
+- Patch: As needed (bugs)
+- Minor: Every 2-4 weeks
+- Major: Every quarter or on schedule
+
+## Rollback from Release
+
+If released version is broken:
+
+```bash
+# Revert tag
+git tag -d v1.2.3
+git push origin :refs/tags/v1.2.3
+
+# Rollback code
+git reset --hard v1.2.2
+git push --force
+```
+
+## Release Checklist
+
+- [ ] Tests passing
+- [ ] Lint passing
+- [ ] Build succeeding
+- [ ] Changelog updated
+- [ ] Version bumped
+- [ ] On main branch
+- [ ] No uncommitted changes
+- [ ] Tag created
+- [ ] Pushed to remote
+- [ ] GitHub release created
+- [ ] Deploy to staging
+- [ ] Deploy to production
+
+## Related Commands
+
+- `deploy-staging` - Test in staging
+- `deploy-prod` - Release to users
+- `validate` - Pre-release checks
+
+## Notes
+
+- Releases are permanent
+- Tags cannot be moved
+- Version numbers are forever
+- Document breaking changes
+- Plan major releases
+- Keep releases focused