codingbuddy-rules 4.2.0 → 4.4.0

package/.ai-rules/skills/deployment-checklist/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: deployment-checklist
+description: Use before deploying to staging or production. Covers pre-deploy validation, environment verification, rollback planning, health checks, and post-deploy monitoring.
+---
+
+# Deployment Checklist
+
+## Overview
+
+Deployments fail in predictable ways. This checklist prevents the most common causes.
+
+**Core principle:** Never deploy what you haven't tested. Never deploy without a rollback plan.
+
+**Iron Law:**
+```
+NO DEPLOY WITHOUT ROLLBACK PLAN
+If you can't roll back in < 5 minutes, don't deploy.
+```
+
+## When to Use
+
+- Before every production deployment
+- Before staging deployments of critical features
+- When deploying database migrations with code
+- When changing environment configuration
+- When deploying infrastructure changes
+
+## Phase 1: Pre-Deploy Validation
+
+### Code Readiness
+```
+- [ ] All tests passing (zero failures)
+- [ ] Test coverage meets threshold (≥ 80% for new code)
+- [ ] No TypeScript errors (tsc --noEmit passes)
+- [ ] Linting passes (eslint/prettier)
+- [ ] No TODO/FIXME in production code paths
+- [ ] Security audit passed (npm audit --audit-level=high)
+- [ ] PR reviewed and approved
+- [ ] Branch up-to-date with main
+```
+
+### Build Verification
+```bash
+# Verify build succeeds from clean state
+rm -rf dist/ node_modules/.cache
+npm run build
+
+# Verify the build output
+ls dist/
+node dist/main.js --version
+```
+
+### Environment Configuration
+```
+- [ ] All required env vars documented in .env.example
+- [ ] Production env vars set in deployment system
+- [ ] No secrets committed to git
+- [ ] Config differences between environments documented
+- [ ] Feature flags configured correctly
+```
+
+## Phase 2: Database Migration (if applicable)
+
+```
+- [ ] Migration files reviewed and approved
+- [ ] Migration tested on staging with production data snapshot
+- [ ] Rollback migration written and tested
+- [ ] Migration is backward-compatible (expand-contract pattern)
+- [ ] Estimated migration duration known
+- [ ] Maintenance window scheduled if migration > 30s
+
+Migration order: deploy migration → verify → deploy code
+```
+
+```bash
+# Test migration on staging first
+npm run migration:run --env=staging
+
+# Verify migration applied correctly
+npm run migration:status
+
+# Verify rollback works
+npm run migration:revert --dry-run
+```
+
+## Phase 3: Deployment Execution
+
+### Staging First
+```
+1. Deploy to staging
+2. Run smoke tests on staging
+3. Verify critical paths work
+4. Check error rates in monitoring
+5. Get sign-off before promoting to production
+```
+
+### Production Deploy
+```bash
+# Tag the release
+git tag v$(npm run version --silent)
+git push origin --tags
+
+# Deploy (method varies by platform)
+# Heroku:    git push heroku main
+# Railway:   railway deploy
+# Docker:    docker push && kubectl apply
+# PM2:       pm2 deploy ecosystem.config.js production
+
+# Monitor during deploy
+watch -n 5 'curl -s https://api.example.com/health | jq .status'
+```
+
+## Phase 4: Health Checks
+
+### Immediate (within 2 minutes of deploy)
+```bash
+# Health endpoint
+curl https://api.example.com/health
+# Expected: { "status": "ok", "version": "1.2.3" }
+
+# MCP server health
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
+  node dist/main.js 2>/dev/null | jq '.result.tools | length'
+# Expected: > 0
+
+# Check for error spikes
+# (in your monitoring tool: Datadog, CloudWatch, etc.)
+```
+
+### Extended (within 10 minutes)
+```
+- [ ] Error rate < baseline (< 0.1% for APIs)
+- [ ] Response times < baseline (p95 < 500ms)
+- [ ] Memory usage stable (not growing)
+- [ ] No unexpected log errors
+- [ ] Database connections healthy
+- [ ] External integrations responding
+```
+
+## Phase 5: Rollback Plan
+
+**Document before deploying:**
+
+```markdown
+## Rollback Plan for v1.2.3
+
+**Trigger conditions:**
+- Error rate > 1% for 5 minutes
+- P95 latency > 2s for 5 minutes
+- Any data corruption detected
+
+**Rollback steps:**
+1. git revert [commit] → push
+   OR
+   kubectl rollout undo deployment/mcp-server
+   (estimated time: 2 minutes)
+
+2. If database migration was run:
+   npm run migration:revert (estimated time: 30 seconds)
+
+3. Verify rollback:
+   curl https://api.example.com/health
+
+**Decision maker:** [Name/role]
+**Rollback time limit:** 5 minutes from trigger detection
+```
+
+## Phase 6: Post-Deploy Monitoring
+
+### First 30 minutes
+```
+- [ ] Monitor error rates every 5 minutes
+- [ ] Check application logs for unexpected errors
+- [ ] Verify key business metrics unchanged
+- [ ] Test critical user paths manually
+- [ ] Watch memory and CPU trends
+```
+
+### First 24 hours
+```
+- [ ] Review full day's error logs
+- [ ] Check performance percentiles (p50, p95, p99)
+- [ ] Verify no data anomalies
+- [ ] Team on standby for issues
+```
+
+## Platform-Specific Checklists
+
+### Docker / Kubernetes
+```
+- [ ] Image built and pushed to registry
+- [ ] Deployment manifest updated with new image tag
+- [ ] Resource limits set (CPU, memory)
+- [ ] Liveness and readiness probes configured
+- [ ] Rolling update strategy (not Recreate)
+- [ ] kubectl rollout status deployment/name watched
+```
+
+### NestJS / Node.js
+```
+- [ ] NODE_ENV=production set
+- [ ] PM2 cluster mode for multi-core usage
+- [ ] Graceful shutdown handler (SIGTERM)
+- [ ] Memory limits configured
+- [ ] Log rotation configured
+```
+
+## Quick Reference
+
+| Environment | Approach |
+|-------------|----------|
+| Development | Deploy freely, no checklist needed |
+| Staging | Run pre-deploy + health check phases |
+| Production | Full checklist, no exceptions |
+
+| Severity | Rollback Trigger |
+|----------|-----------------|
+| P0 Critical | Immediate rollback |
+| P1 High | Rollback if > 5 min to fix |
+| P2 Medium | Fix forward or rollback (team decision) |
+| P3 Low | Fix forward in next deploy |
+
+## Red Flags — Do Not Deploy
+
+```
+❌ Tests failing
+❌ Build failing
+❌ npm audit shows HIGH or CRITICAL vulnerabilities
+❌ No rollback plan documented
+❌ Migration not tested on staging
+❌ Team members unavailable for 2h post-deploy
+❌ Deploying Friday after 3pm
+```

package/.ai-rules/skills/documentation-generation/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: documentation-generation
+description: Use when creating or updating README, API docs, architecture docs, or CHANGELOG. Generates clear, accurate documentation from code structure and context.
+---
+
+# Documentation Generation
+
+## Overview
+
+Good documentation is the gift you give your future self and your team. It is NOT optional.
+
+**Core principle:** Documentation describes behavior, not code. If the code changes, update the docs.
+
+**Iron Law:**
+```
+DOCS ARE OUTDATED THE MOMENT THEY ARE WRITTEN — AUTOMATE OR ACCEPT THE DEBT
+```
+
+## When to Use
+
+- Creating a new project README
+- Documenting new API endpoints
+- Generating CHANGELOG entries
+- Writing architecture decision records (ADRs)
+- Creating onboarding guides for new team members
+- Documenting AI rules for multi-tool projects
+
+## Document Types & Templates
+
+### 1. README.md
+
+A good README answers: What is this? How do I run it? How do I use it?
+
+```markdown
+# Project Name
+
+One-sentence description of what this does and who it's for.
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+## Features
+
+- Feature 1: Brief description
+- Feature 2: Brief description
+
+## Installation
+
+\`\`\`bash
+# Prerequisites
+node >= 18
+npm >= 9
+
+# Install
+npm install
+
+# Configure
+cp .env.example .env
+# Edit .env with your values
+
+# Run
+npm start
+\`\`\`
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PORT` | No | `3000` | Server port |
+| `DATABASE_URL` | Yes | — | PostgreSQL connection string |
+
+## API Reference
+
+See [API Documentation](./docs/api.md) for full reference.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT
+```
+
+### 2. API Documentation
+
+````markdown
+# API Reference
+
+## Authentication
+
+All endpoints require Bearer token:
+\`\`\`
+Authorization: Bearer <token>
+\`\`\`
+
+## Endpoints
+
+### GET /users
+
+List all users.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `page` | integer | No | Page number (default: 1) |
+| `limit` | integer | No | Per-page count (default: 20, max: 100) |
+
+**Response:**
+\`\`\`json
+{
+  "data": [{ "id": "123", "email": "user@example.com" }],
+  "meta": { "total": 42, "page": 1 }
+}
+\`\`\`
+
+**Errors:**
+| Code | Status | Description |
+|------|--------|-------------|
+| `UNAUTHORIZED` | 401 | Missing or invalid token |
+| `FORBIDDEN` | 403 | Insufficient permissions |
+````
+
+### 3. Architecture Decision Record (ADR)
+
+```markdown
+# ADR-001: Use NestJS for MCP Server
+
+**Date:** 2024-01-15
+**Status:** Accepted
+
+## Context
+
+We need a Node.js framework for the MCP server with dependency injection and testability.
+
+## Decision
+
+Use NestJS with TypeScript.
+
+## Rationale
+
+- Built-in dependency injection for testable code
+- Decorator-based approach matches MCP patterns
+- Strong TypeScript support
+- Module system aligns with MCP's separation of concerns
+
+## Consequences
+
+- Higher initial complexity than Express
+- Requires understanding of NestJS modules
+- Excellent testing support out of the box
+```
+
+### 4. CHANGELOG
+
+Follow [Keep a Changelog](https://keepachangelog.com) format:
+
+```markdown
+# Changelog
+
+## [Unreleased]
+
+### Added
+- New feature X
+
+## [1.2.0] - 2024-01-15
+
+### Added
+- Support for SSE transport mode
+- Bearer token authentication for SSE
+
+### Changed
+- Improved error messages for invalid rules
+
+### Fixed
+- Memory leak in rule file watcher
+
+### Security
+- Fixed token exposure in debug logs
+
+## [1.1.0] - 2024-01-01
+...
+```
+
+## Generation Process
+
+### Step 1: Gather Context
+
+```bash
+# Understand the project structure
+ls -la
+cat package.json
+git log --oneline -20   # Recent changes for CHANGELOG
+
+# Find existing documentation
+find . -name "*.md" -not -path "*/node_modules/*"
+```
+
+### Step 2: Extract Information from Code
+
+For TypeScript projects, extract JSDoc/TSDoc:
+```typescript
+/**
+ * Search rules by query string.
+ * @param query - Search term to match against rule content
+ * @param options - Optional filters
+ * @returns Matching rules sorted by relevance
+ */
+async searchRules(query: string, options?: SearchOptions): Promise<Rule[]>
+```
+
+For configuration:
+```typescript
+// Extract environment variables
+grep -rn "process.env\." src/ | grep -o "process\.env\.[A-Z_]*" | sort -u
+```
+
+### Step 3: Write Documentation
+
+**Principles:**
+- **Show, don't just tell** — Include working examples for every major feature
+- **Start with Why** — First sentence explains purpose, not mechanism
+- **One job per section** — Each section answers one question
+- **Concrete over abstract** — Specific examples beat generic descriptions
+
+### Step 4: Verify Accuracy
+
+```
+- [ ] All code examples are runnable
+- [ ] Environment variables list matches .env.example
+- [ ] API endpoints match actual routes
+- [ ] Prerequisites match actual requirements
+- [ ] Links are not broken
+```
+
+## Documentation Checklist by Type
+
+### README
+- [ ] One-line description at top
+- [ ] Quick Start (< 5 steps to run)
+- [ ] Configuration table (all env vars)
+- [ ] At least one working code example
+- [ ] Link to full docs / contributing guide
+
+### API Docs
+- [ ] Authentication documented
+- [ ] All endpoints listed
+- [ ] Request/response examples for each
+- [ ] Error codes documented
+- [ ] Rate limits documented
+
+### CHANGELOG
+- [ ] Follows semver (MAJOR.MINOR.PATCH)
+- [ ] Added / Changed / Deprecated / Removed / Fixed / Security sections
+- [ ] Each entry links to issue/PR
+- [ ] Unreleased section at top
+
+### ADR
+- [ ] Context explains why decision was needed
+- [ ] Alternatives considered
+- [ ] Decision and rationale clear
+- [ ] Consequences (positive and negative) listed
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Documenting code, not behavior | Describe what it does, not how |
+| Outdated examples | Add docs to definition of done |
+| No quick start | First 5 minutes → working system |
+| Wall of text | Use tables, code blocks, lists |
+| Missing error docs | Document failure modes |
+| Internal jargon | Write for a new team member |
+
+## Tools to Accelerate
+
+```bash
+# TypeScript → API docs
+npx typedoc --out docs/api src/
+
+# Markdown linting
+npx markdownlint-cli "**/*.md"
+
+# Link checking
+npx markdown-link-check README.md
+
+# CHANGELOG generation from git log
+npx conventional-changelog-cli -p angular
+```