codingbuddy-rules 4.3.0 → 4.4.0

package/.ai-rules/skills/context-management/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: context-management
+description: Use when working on long tasks that span multiple sessions, when context compaction is a concern, or when decisions from PLAN mode need to persist through ACT and EVAL modes.
+---
+
+# Context Management
+
+## Overview
+
+AI assistant context windows are finite. Long tasks get compacted, earlier decisions are forgotten, and continuity breaks. Context management is the practice of preserving critical information so work survives compaction.
+
+**Core principle:** If it matters after the current conversation, write it down. Memory is the enemy of continuity.
+
+**Iron Law:**
+```
+EXTERNAL STATE > INTERNAL MEMORY
+Write decisions to files. Files survive compaction; conversation memory does not.
+```
+
+## When to Use
+
+- Starting a task that will span multiple sessions
+- Beginning PLAN mode (decisions must survive to ACT)
+- Completing ACT mode (progress must survive to EVAL)
+- When conversation is approaching context limits
+- Before any context compaction event
+- When resuming work after a break
+
+## The Context Document (codingbuddy)
+
+The primary context persistence mechanism is `docs/codingbuddy/context.md`.
+
+```
+docs/codingbuddy/context.md
+─────────────────────────────
+This file is:
+- Created/reset by PLAN mode
+- Appended by ACT mode
+- Appended by EVAL mode
+- Always at a fixed, predictable path
+- Safe to read at any point
+```
+
+### What Goes in Context
+
+**PLAN mode writes:**
+- Task description
+- Key design decisions and their rationale
+- Architecture choices
+- Dependencies and constraints
+- Recommended ACT agent
+
+**ACT mode writes:**
+- Progress milestones completed
+- Files created/modified
+- Implementation decisions made
+- Issues encountered and resolved
+- Next steps
+
+**EVAL mode writes:**
+- Quality findings (with severity)
+- Security issues found
+- Performance observations
+- Recommendations for next iteration
+
+### Context Document Format
+
+```markdown
+# Context: [Task Title]
+
+## PLAN — [timestamp]
+**Task:** [Original task description]
+**Primary Agent:** solution-architect
+**Recommended ACT Agent:** agent-architect
+
+### Decisions
+- Decision 1: [What was decided and why]
+- Decision 2: [What was decided and why]
+
+### Notes
+- Implementation note 1
+- Constraint or dependency to remember
+
+---
+
+## ACT — [timestamp]
+**Primary Agent:** agent-architect
+
+### Progress
+- [x] Created RulesService with search capability
+- [x] Added Tests: 12 passing
+- [ ] SSE transport implementation pending
+
+### Notes
+- Used glob for file discovery (faster than readdir recursion)
+- NestJS module structure: McpModule → RulesModule
+
+---
+
+## EVAL — [timestamp]
+
+### Findings
+- [HIGH] Missing rate limiting on /sse endpoint
+- [MEDIUM] Test coverage at 72%, below 80% target
+
+### Recommendations
+- Add rate limiting middleware
+- Add tests for error cases in RulesService
+```
+
+## Context Strategy by Task Duration
+
+### Short Tasks (< 1 hour, single session)
+
+No special context management needed. Conversation memory is sufficient.
+
+### Medium Tasks (1-4 hours, 1-2 sessions)
+
+```
+1. Write task summary to context.md at start
+2. Update progress at each major milestone
+3. Write completion summary before ending session
+```
+
+### Long Tasks (multi-day, multiple sessions)
+
+```
+1. Create context.md with full plan (PLAN mode)
+2. Create task breakdown in docs/codingbuddy/plan/
+3. Update context.md after each working session
+4. Begin each session by reading context.md
+5. Use git commits as progress markers
+```
+
+## Session Start Protocol
+
+When resuming a task:
+
+```markdown
+## Session Resume Checklist
+
+1. Read context document:
+   - docs/codingbuddy/context.md
+
+2. Check git status:
+   - What was last committed?
+   - Any uncommitted changes?
+
+3. Check task list:
+   - What was pending at last session?
+
+4. Verify environment:
+   - Tests still passing?
+   - Build still working?
+
+5. Update context with session start note
+```
+
+## Session End Protocol
+
+Before ending a session:
+
+```markdown
+## Session End Checklist
+
+1. Commit all completed work with descriptive message
+
+2. Update context document:
+   - Mark completed items
+   - Note pending items
+   - Capture any decisions made
+
+3. Note exact stopping point:
+   - What file/function was being edited?
+   - What was the next intended step?
+
+4. If blocked: note the blocker clearly
+
+5. Push to remote if collaborating
+```
+
+## Information Priority
+
+When deciding what to preserve, use this priority:
+
+```
+MUST preserve:
+- Architecture decisions (hard to reconstruct)
+- Why (not what) was done — rationale survives code changes
+- Open questions and blockers
+- External dependencies and constraints
+
+SHOULD preserve:
+- Files created and their purpose
+- Test coverage status
+- Performance baseline numbers
+
+CAN skip:
+- Step-by-step implementation details (read the code)
+- Obvious decisions (no need to record "used async/await")
+- Information available in git history
+```
+
+## Context Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| Relying on conversation memory | Compaction erases it | Write to file |
+| Writing everything verbatim | Context file becomes noise | Summarize decisions, not steps |
+| Never reading context file | Repeating work already done | Read at session start |
+| Single monolithic context file | Hard to navigate | Split by phase (PLAN/ACT/EVAL) |
+| Context file not in git | Lost if repo changes machines | Always commit context docs |
+
+## notepad.md (OMC Alternative)
+
+For sessions not using codingbuddy's parse_mode, use OMC's notepad:
+
+```
+notepad_write_priority: Critical info always loaded at session start
+notepad_write_working:  Session-specific notes (auto-pruned after 7 days)
+notepad_write_manual:   Permanent notes that must survive
+```
+
+**When to use notepad vs context.md:**
+- `context.md` → For codingbuddy PLAN/ACT/EVAL workflow
+- notepad → For ad-hoc sessions without formal workflow
+
+## Quick Reference
+
+```
+Context File Locations:
+──────────────────────
+docs/codingbuddy/context.md    → Primary context (PLAN/ACT/EVAL)
+docs/codingbuddy/plan/         → Detailed plan documents
+~/.claude/notepad.md            → Global session notes (OMC)
+
+Update Context via MCP:
+──────────────────────
+update_context(mode, decisions[], notes[], progress[], status)
+
+Read Context via MCP:
+──────────────────────
+read_context(verbosity: minimal|standard|full)
+```

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
+```