baldart 3.6.2

package/framework/agents/data-model.md

@@ -0,0 +1,110 @@
+# Data Model
+
+## Purpose
+
+Define database schema documentation standards and data modeling guidelines.
+
+## Scope
+
+**In**: Schema documentation format, field types, relationships, constraints.
+**Out**: Query optimization (see agents/performance.md).
+
+## Do
+
+- Document all collections/tables in ${paths.references_dir}/data-model.md
+- Define field types and constraints
+- Document relationships between entities
+- Update docs when schema changes
+
+## Do Not
+
+- Change schema without updating documentation
+- Skip documenting new fields
+- Make breaking changes without migration plan
+
+## Schema Documentation Format
+
+Each collection/table should document:
+
+```markdown
+## [CollectionName / TableName]
+
+**Purpose**: [What this stores]
+
+**Fields**:
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| id | string | Yes | auto | Unique identifier |
+| field1 | string | Yes | - | Description |
+| field2 | number | No | 0 | Description |
+| createdAt | timestamp | Yes | now() | Creation time |
+| updatedAt | timestamp | Yes | now() | Last update time |
+
+**Indexes**:
+- Primary: `id`
+- Index: `field1`
+- Composite: `field1 + field2`
+
+**Relationships**:
+- `foreignKeyField` → References `OtherCollection.id`
+
+**Constraints**:
+- Unique: `field1`
+- Check: `field2 > 0`
+
+**Example Document/Row**:
+\`\`\`json
+{
+  "id": "123",
+  "field1": "value",
+  "field2": 42,
+  "createdAt": "2026-02-13T10:00:00Z",
+  "updatedAt": "2026-02-13T10:00:00Z"
+}
+\`\`\`
+```
+
+## Field Type Conventions
+
+- [String length limits]
+- [Number ranges]
+- [Date/timestamp formats]
+- [Boolean defaults]
+- [Array/nested object guidelines]
+- [Enum value lists]
+
+## Naming Conventions
+
+- [Collection/table naming - e.g., plural, lowercase]
+- [Field naming - e.g., camelCase, snake_case]
+- [Foreign key naming]
+- [Index naming]
+
+## Relationships
+
+- [One-to-one patterns]
+- [One-to-many patterns]
+- [Many-to-many patterns]
+- [Denormalization guidelines]
+
+## Migrations
+
+- [Migration file location]
+- [Migration naming convention]
+- [Rollback requirements]
+- [Data preservation rules]
+
+## Audit Fields
+
+Standard fields for all collections/tables:
+
+- `createdAt`: timestamp of creation
+- `updatedAt`: timestamp of last update
+- `deletedAt`: soft delete timestamp (if using soft deletes)
+
+## Data Retention
+
+- [Retention policies]
+- [Archival strategy]
+- [Deletion procedures]
+- [GDPR/privacy compliance]

package/framework/agents/deployment-protocol.md

@@ -0,0 +1,232 @@
+# Deployment Protocol
+
+## Purpose
+
+Define safe deployment procedures and rollback strategies.
+
+## Scope
+
+**In**: Deployment steps, environments, rollback procedures, pre/post checks.
+**Out**: Infrastructure details (see agents/runbook.md).
+
+## Do
+
+- Follow deployment checklist
+- Test in staging before production
+- Have rollback plan ready
+- Document deployment results
+
+## Do Not
+
+- Deploy without testing
+- Skip pre-deployment checks
+- Deploy during peak hours (unless emergency)
+
+## Environments
+
+| Environment | Purpose | Deployment Frequency | Auto-Deploy |
+|-------------|---------|---------------------|-------------|
+| Development | Local dev | Continuous | N/A |
+| Staging | Pre-production testing | On PR merge | Optional |
+| Production | Live users | Manual/Scheduled | Conditional |
+
+## Deployment Checklist
+
+### Pre-Deployment
+
+- [ ] All tests passing
+- [ ] Code review approved
+- [ ] Staging deployment successful
+- [ ] Database migrations tested
+- [ ] Rollback plan documented
+- [ ] Monitoring alerts configured
+- [ ] Team notified of deployment
+- [ ] Maintenance window scheduled (if needed)
+
+### Deployment Steps
+
+1. **Verify current state**
+   ```bash
+   [command to check current version/state]
+   ```
+
+2. **Create backup**
+   ```bash
+   [backup command]
+   ```
+
+3. **Run database migrations** (if applicable)
+   ```bash
+   [migration command]
+   ```
+
+4. **Deploy new version**
+   ```bash
+   [deploy command]
+   ```
+
+5. **Health check**
+   ```bash
+   [health check command or URL to check]
+   ```
+
+6. **Smoke tests**
+   - [ ] Homepage loads
+   - [ ] Authentication works
+   - [ ] Critical user flows work
+   - [ ] No error spikes in logs
+
+### Post-Deployment
+
+- [ ] Monitor error rates for 15 minutes
+- [ ] Check performance metrics
+- [ ] Verify database connections stable
+- [ ] Test critical user flows manually
+- [ ] Update deployment log
+- [ ] Notify team of completion
+
+## Rollback Procedure
+
+### When to Rollback
+
+- Error rate > 5% increase
+- Critical feature broken
+- Performance degradation > 50%
+- Data corruption detected
+
+### Rollback Steps
+
+1. **Announce rollback**
+   ```bash
+   # Notify team
+   ```
+
+2. **Revert to previous version**
+   ```bash
+   [rollback command]
+   ```
+
+3. **Rollback database** (if needed)
+   ```bash
+   [db rollback command]
+   ```
+
+4. **Verify health**
+   ```bash
+   [health check]
+   ```
+
+5. **Document issue**
+   - What went wrong
+   - Why it wasn't caught
+   - How to prevent in future
+
+## Deployment Strategies
+
+### Blue-Green Deployment (if applicable)
+
+1. Deploy to green environment
+2. Test green environment
+3. Switch traffic to green
+4. Keep blue as rollback option
+
+### Canary Deployment (if applicable)
+
+1. Deploy to subset of servers
+2. Monitor metrics for canary group
+3. Gradually increase percentage
+4. Rollback if issues detected
+
+### Rolling Deployment (if applicable)
+
+1. Deploy to one server at a time
+2. Verify health after each
+3. Continue to next server
+4. Rollback if issues detected
+
+## Database Migrations
+
+### Migration Checklist
+
+- [ ] Migration tested locally
+- [ ] Migration tested in staging
+- [ ] Backup created before migration
+- [ ] Migration is reversible
+- [ ] Rollback migration tested
+
+### Migration Best Practices
+
+- Make migrations backwards compatible when possible
+- Avoid locking tables during peak hours
+- Test with production-sized data
+- Have rollback SQL ready
+
+## Monitoring During Deployment
+
+Watch these metrics:
+
+- **Error rate**: Should not increase
+- **Response time**: Should remain stable
+- **CPU/Memory**: Should remain within limits
+- **Database connections**: Should remain stable
+- **Queue depth**: Should not grow
+
+## Emergency Hotfix Process
+
+1. **Identify critical issue**
+2. **Create hotfix branch** from production
+3. **Minimal fix** - only address critical issue
+4. **Fast-track review** (but still review!)
+5. **Deploy with monitoring**
+6. **Back-port to main** branch
+7. **Post-mortem** - why did this slip through?
+
+## Deployment Schedule
+
+- **Staging**: Automatic on PR merge to main
+- **Production**: [Your schedule - e.g., Mon/Wed/Fri 10am]
+- **Hotfixes**: As needed, any time
+- **Avoid**: Friday afternoons, holidays, weekends (unless emergency)
+
+## Communication
+
+### Before Deployment
+
+- Notify team in [channel]
+- Post in deployment log
+- Schedule maintenance window if needed
+
+### During Deployment
+
+- Update status in [channel]
+- Monitor alerts
+- Be ready to rollback
+
+### After Deployment
+
+- Announce completion
+- Share metrics
+- Document any issues
+
+## Deployment Log
+
+Maintain a deployment log:
+
+```markdown
+## YYYY-MM-DD HH:MM - Version X.Y.Z
+
+**Deployer**: [Name]
+**Changes**: [Brief description or link to changelog]
+**Status**: Success/Rollback
+**Issues**: [Any issues encountered]
+**Metrics**:
+- Deployment time: [duration]
+- Error rate: [before] -> [after]
+- Response time: [before] -> [after]
+```
+
+## Access Control
+
+- **Who can deploy**: [Roles/people]
+- **Approval required**: [Yes/No, by whom]
+- **Emergency access**: [Contact info]

package/framework/agents/design-review.md

@@ -0,0 +1,172 @@
+# Design Review
+
+## Purpose
+
+Define design review process and UI/UX quality standards.
+
+## Scope
+
+**In**: UI review criteria, design consistency, accessibility.
+**Out**: Implementation details (see agents/coding-standards.md).
+
+## Do
+
+- Review designs before implementation
+- Check accessibility
+- Ensure consistency with design system
+- Test across devices/browsers
+
+## Do Not
+
+- Skip design review for "small" changes
+- Ignore accessibility requirements
+- Assume designs work on all screen sizes
+
+## Design Review Checklist
+
+### Visual Design
+
+- [ ] Follows design system/style guide
+- [ ] Consistent spacing and alignment
+- [ ] Appropriate typography
+- [ ] Color contrast meets WCAG standards
+- [ ] Icons and imagery appropriate
+- [ ] Loading states designed
+- [ ] Error states designed
+- [ ] Empty states designed
+
+### Layout
+
+- [ ] Responsive across breakpoints
+- [ ] Mobile-first approach
+- [ ] Proper use of grid/flexbox
+- [ ] No horizontal scroll on mobile
+- [ ] Touch targets minimum 44x44px
+- [ ] Content hierarchy clear
+
+### Interaction Design
+
+- [ ] Clear call-to-actions
+- [ ] Feedback for user actions
+- [ ] Loading indicators where needed
+- [ ] Error messages helpful
+- [ ] Forms easy to complete
+- [ ] Navigation intuitive
+
+### Accessibility (WCAG 2.1 AA)
+
+- [ ] Color contrast ≥ 4.5:1 (text)
+- [ ] Color contrast ≥ 3:1 (UI components)
+- [ ] Keyboard navigation works
+- [ ] Focus indicators visible
+- [ ] Alt text for images
+- [ ] ARIA labels where needed
+- [ ] Form labels proper
+- [ ] Screen reader friendly
+
+### Performance
+
+- [ ] Images optimized
+- [ ] Fonts optimized
+- [ ] Animations performant
+- [ ] No layout shift
+- [ ] Fast loading
+
+### Content
+
+- [ ] Copy clear and concise
+- [ ] Tone consistent with brand
+- [ ] No jargon (unless necessary)
+- [ ] Error messages helpful
+- [ ] Microcopy thoughtful
+
+## Review Process
+
+### 1. Pre-Implementation Review
+
+- Review designs/mockups
+- Clarify requirements
+- Identify technical constraints
+- Estimate effort
+
+### 2. Implementation Review
+
+- Build matches design
+- Interactions work as specified
+- Edge cases handled
+
+### 3. Final Review
+
+- Test on multiple devices
+- Test on multiple browsers
+- Accessibility check
+- Performance check
+
+## Common Issues
+
+### Layout Issues
+
+- Inconsistent spacing
+- Misaligned elements
+- Broken responsive behavior
+- Text overflow
+
+### Interaction Issues
+
+- Missing feedback
+- Confusing navigation
+- Unclear error messages
+- Slow interactions
+
+### Accessibility Issues
+
+- Low color contrast
+- Missing alt text
+- No keyboard navigation
+- Poor focus indicators
+- Missing ARIA labels
+
+## Review Tools
+
+- **Design**: [e.g., Figma, Sketch, Adobe XD]
+- **Accessibility**: [e.g., axe DevTools, WAVE, Lighthouse]
+- **Responsive**: [e.g., Browser DevTools, BrowserStack]
+- **Performance**: [e.g., Lighthouse, WebPageTest]
+
+## Design System
+
+Reference your design system:
+
+- **Components**: [Link to component library]
+- **Colors**: [Link to color palette]
+- **Typography**: [Link to typography scale]
+- **Spacing**: [Link to spacing system]
+- **Icons**: [Link to icon set]
+
+## Browser Support
+
+Define supported browsers:
+
+| Browser | Minimum Version |
+|---------|----------------|
+| Chrome | [version] |
+| Firefox | [version] |
+| Safari | [version] |
+| Edge | [version] |
+| Mobile Safari | [version] |
+| Mobile Chrome | [version] |
+
+## Device Support
+
+Define supported devices:
+
+- **Desktop**: [min resolution]
+- **Tablet**: [resolution range]
+- **Mobile**: [resolution range]
+
+## Review Outcomes
+
+- **Approved**: Ready for implementation/deployment
+- **Approved with minor changes**: Small tweaks needed
+- **Needs revision**: Significant changes required
+- **Rejected**: Fundamental issues, needs redesign

package/framework/agents/env-reference.md

@@ -0,0 +1,171 @@
+# Environment Reference
+
+## Purpose
+
+Document all environment variables and configuration options.
+
+## Scope
+
+**In**: Environment variable definitions, configuration, secrets.
+**Out**: Operational procedures (see agents/runbook.md).
+
+## Do
+
+- Document all environment variables
+- Provide examples
+- Specify required vs optional
+- Update when adding new variables
+
+## Do Not
+
+- Commit actual secret values
+- Use production values in examples
+
+## Environment Variables
+
+### Application Configuration
+
+| Variable | Required | Default | Description | Example |
+|----------|----------|---------|-------------|---------|
+| `APP_NAME` | No | MyApp | Application name | `MyApp` |
+| `APP_ENV` | Yes | - | Environment (dev/staging/prod) | `production` |
+| `APP_PORT` | No | 3000 | Server port | `8080` |
+| `APP_URL` | Yes | - | Application base URL | `https://app.example.com` |
+
+### Database
+
+| Variable | Required | Default | Description | Example |
+|----------|----------|---------|-------------|---------|
+| `DB_HOST` | Yes | - | Database host | `localhost` |
+| `DB_PORT` | No | 5432 | Database port | `5432` |
+| `DB_NAME` | Yes | - | Database name | `myapp` |
+| `DB_USER` | Yes | - | Database username | `dbuser` |
+| `DB_PASSWORD` | Yes | - | Database password | `***` |
+| `DB_SSL` | No | false | Use SSL connection | `true` |
+
+### Authentication
+
+| Variable | Required | Default | Description | Example |
+|----------|----------|---------|-------------|---------|
+| `JWT_SECRET` | Yes | - | JWT signing secret | `***` |
+| `JWT_EXPIRY` | No | 24h | JWT expiration time | `7d` |
+| `SESSION_SECRET` | Yes | - | Session secret key | `***` |
+
+### External Services
+
+| Variable | Required | Default | Description | Example |
+|----------|----------|---------|-------------|---------|
+| `SERVICE_API_KEY` | Yes | - | External service API key | `***` |
+| `SERVICE_URL` | Yes | - | External service URL | `https://api.service.com` |
+
+### Email (if applicable)
+
+| Variable | Required | Default | Description | Example |
+|----------|----------|---------|-------------|---------|
+| `SMTP_HOST` | Yes | - | SMTP server host | `smtp.gmail.com` |
+| `SMTP_PORT` | No | 587 | SMTP server port | `587` |
+| `SMTP_USER` | Yes | - | SMTP username | `user@example.com` |
+| `SMTP_PASSWORD` | Yes | - | SMTP password | `***` |
+| `EMAIL_FROM` | Yes | - | Default sender email | `noreply@example.com` |
+
+### Storage (if applicable)
+
+| Variable | Required | Default | Description | Example |
+|----------|----------|---------|-------------|---------|
+| `STORAGE_TYPE` | No | local | Storage type (local/s3) | `s3` |
+| `S3_BUCKET` | No | - | S3 bucket name | `my-bucket` |
+| `S3_REGION` | No | - | S3 region | `us-east-1` |
+| `S3_ACCESS_KEY` | No | - | S3 access key | `***` |
+| `S3_SECRET_KEY` | No | - | S3 secret key | `***` |
+
+### Monitoring/Logging
+
+| Variable | Required | Default | Description | Example |
+|----------|----------|---------|-------------|---------|
+| `LOG_LEVEL` | No | info | Logging level | `debug` |
+| `SENTRY_DSN` | No | - | Sentry error tracking DSN | `https://***@sentry.io/***` |
+
+## Environment Files
+
+### .env.example
+
+Create a `.env.example` file with all variables (no secrets):
+
+```bash
+# Application
+APP_NAME=MyApp
+APP_ENV=development
+APP_PORT=3000
+APP_URL=http://localhost:3000
+
+# Database
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=myapp
+DB_USER=dbuser
+DB_PASSWORD=change-me-in-production
+
+# Authentication
+JWT_SECRET=change-me-to-random-string
+JWT_EXPIRY=24h
+SESSION_SECRET=change-me-to-random-string
+
+# External Services
+SERVICE_API_KEY=your-api-key-here
+SERVICE_URL=https://api.service.com
+
+# Monitoring
+LOG_LEVEL=info
+```
+
+### .env.local (Development)
+
+Copy `.env.example` to `.env.local` and fill in development values.
+
+### Environment-Specific Files
+
+- `.env.development` - Development defaults
+- `.env.staging` - Staging configuration
+- `.env.production` - Production configuration (never commit!)
+
+## Secrets Management
+
+### Development
+
+- Use `.env` files (gitignored)
+- Share example values in `.env.example`
+
+### Production
+
+- Use secrets management service (e.g., AWS Secrets Manager, HashiCorp Vault)
+- Or use platform-specific env var management (e.g., Vercel, Heroku)
+- Never commit production secrets
+
+## Configuration Validation
+
+Validate required environment variables on startup:
+
+```typescript
+// Example validation
+const required = ['DB_HOST', 'DB_NAME', 'JWT_SECRET'];
+for (const key of required) {
+  if (!process.env[key]) {
+    throw new Error(`Missing required env var: ${key}`);
+  }
+}
+```
+
+## Loading Environment
+
+Document how environment variables are loaded:
+
+- [e.g., dotenv package]
+- [e.g., Next.js built-in]
+- [e.g., platform-specific]
+
+## Feature Flags (if applicable)
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `FEATURE_FLAG_1` | boolean | false | Enable new feature |
+| `FEATURE_FLAG_2` | boolean | false | Enable experimental feature |