@defai.digital/automatosx 5.0.13 → 5.1.2

package/examples/abilities/data-modeling.md

@@ -0,0 +1,171 @@
+# Data Modeling
+
+## Overview
+Design efficient, scalable data models for relational and NoSQL databases. Focus on normalization, relationships, and schema design that supports business requirements while maintaining data integrity.
+
+## Core Principles
+
+### 1. Normalization (Relational)
+Eliminate data redundancy through normal forms (1NF, 2NF, 3NF, BCNF).
+
+### 2. Denormalization (When Needed)
+Strategic denormalization for read-heavy workloads and performance optimization.
+
+### 3. Schema Design Patterns
+- **Star Schema**: Dimensional modeling for analytics (fact + dimension tables)
+- **Snowflake Schema**: Normalized dimensional model
+- **Data Vault**: Flexible, auditable data warehouse modeling
+
+## Do's ✅
+
+### Relational Data Model
+```sql
+-- ✅ Good: Normalized design
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE orders (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER REFERENCES users(id),
+  total_amount DECIMAL(10,2),
+  status VARCHAR(50),
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE order_items (
+  id SERIAL PRIMARY KEY,
+  order_id INTEGER REFERENCES orders(id),
+  product_id INTEGER REFERENCES products(id),
+  quantity INTEGER,
+  price DECIMAL(10,2)
+);
+```
+
+### Indexes
+```sql
+-- ✅ Good: Index frequently queried columns
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_orders_created_at ON orders(created_at);
+CREATE INDEX idx_order_items_order_id ON order_items(order_id);
+
+-- ✅ Good: Composite index for multi-column queries
+CREATE INDEX idx_orders_user_status ON orders(user_id, status);
+```
+
+### NoSQL Data Model (MongoDB)
+```javascript
+// ✅ Good: Embedded documents for one-to-few
+{
+  _id: ObjectId("..."),
+  user_email: "user@example.com",
+  addresses: [
+    { type: "home", street: "123 Main St", city: "NYC" },
+    { type: "work", street: "456 Office Ave", city: "LA" }
+  ]
+}
+
+// ✅ Good: References for one-to-many
+// User document
+{
+  _id: ObjectId("user123"),
+  email: "user@example.com"
+}
+
+// Order documents (separate collection)
+{
+  _id: ObjectId("order456"),
+  user_id: ObjectId("user123"),
+  items: [...],
+  total: 99.99
+}
+```
+
+## Don'ts ❌
+
+### Over-Normalization
+```sql
+-- ❌ Bad: Excessive normalization
+CREATE TABLE user_first_names (
+  user_id INTEGER REFERENCES users(id),
+  first_name VARCHAR(100)
+);
+
+CREATE TABLE user_last_names (
+  user_id INTEGER REFERENCES users(id),
+  last_name VARCHAR(100)
+);
+
+-- ✅ Good: Appropriate normalization
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  first_name VARCHAR(100),
+  last_name VARCHAR(100),
+  email VARCHAR(255) UNIQUE
+);
+```
+
+### Missing Constraints
+```sql
+-- ❌ Bad: No constraints
+CREATE TABLE orders (
+  id INTEGER,
+  user_id INTEGER,
+  total DECIMAL
+);
+
+-- ✅ Good: Proper constraints
+CREATE TABLE orders (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  total DECIMAL(10,2) CHECK (total >= 0),
+  status VARCHAR(50) DEFAULT 'pending',
+  created_at TIMESTAMP NOT NULL DEFAULT NOW()
+);
+```
+
+### Embedding Large Arrays (NoSQL)
+```javascript
+// ❌ Bad: Unbounded array growth
+{
+  user_id: "user123",
+  orders: [ /* Could grow to thousands */ ]
+}
+
+// ✅ Good: Reference pattern
+{
+  user_id: "user123",
+  recent_orders: [ /* Last 5 orders */ ],
+  total_order_count: 1247
+}
+// Store full orders in separate collection
+```
+
+## Best Practices
+
+### 1. Use Appropriate Data Types
+- `TIMESTAMP` for dates (not VARCHAR)
+- `DECIMAL` for money (not FLOAT)
+- `ENUM` or `CHECK` constraints for fixed options
+- `UUID` for distributed primary keys
+
+### 2. Plan for Growth
+- Partition large tables by date/region
+- Use sharding for horizontal scalability
+- Implement archival strategy for old data
+
+### 3. Document Relationships
+```
+Users (1) ← (M) Orders (1) ← (M) OrderItems (M) → (1) Products
+```
+
+### 4. Version Schema Changes
+Use migration tools (Flyway, Liquibase, Alembic) for schema versioning.
+
+## Resources
+
+- [Database Normalization](https://en.wikipedia.org/wiki/Database_normalization)
+- [MongoDB Schema Design Patterns](https://www.mongodb.com/blog/post/building-with-patterns-a-summary)
+- [PostgreSQL Documentation](https://www.postgresql.org/docs/)

package/examples/abilities/data-validation.md

@@ -0,0 +1,50 @@
+# Data Validation
+
+Implement comprehensive data quality checks to ensure accuracy, completeness, and consistency. Catch data issues early before they impact downstream systems.
+
+## Do's ✅
+
+```python
+# ✅ Good: Schema validation with Pydantic
+from pydantic import BaseModel, validator
+
+class UserRecord(BaseModel):
+    id: int
+    email: str
+    age: int
+
+    @validator('email')
+    def email_must_be_valid(cls, v):
+        if '@' not in v:
+            raise ValueError('Invalid email')
+        return v
+
+# ✅ Good: Data quality checks
+def validate_data(df):
+    checks = [
+        ('No nulls', df[['id', 'email']].notnull().all().all()),
+        ('Unique IDs', df['id'].is_unique),
+        ('Valid ages', df['age'].between(0, 150).all()),
+    ]
+    failed = [check for check, passed in checks if not passed]
+    if failed:
+        raise ValueError(f"Validation failed: {failed}")
+```
+
+## Don'ts ❌
+
+```python
+# ❌ Bad: No validation
+df = pd.read_csv('data.csv')
+df.to_sql('users', engine)  # Hope for the best!
+
+# ❌ Bad: Silent failures
+df = df.dropna()  # What was dropped? Why?
+```
+
+## Best Practices
+- Define data quality SLAs
+- Implement continuous monitoring
+- Document validation rules
+- Use validation frameworks (Great Expectations, Pandera)
+- Create data quality dashboards

package/examples/abilities/db-modeling.md

@@ -0,0 +1,158 @@
+# Database Modeling
+
+## Overview
+Design efficient, scalable, and maintainable database schemas for relational and NoSQL databases, focusing on data integrity, performance, and evolution.
+
+## Core Principles
+
+### 1. Normalization & Denormalization
+- 3NF for transactional systems
+- Strategic denormalization for read-heavy workloads
+- Balance between data integrity and query performance
+
+### 2. Data Integrity
+- Primary keys on all tables
+- Foreign key constraints
+- Check constraints for data validation
+- Unique constraints for business rules
+
+### 3. Indexing Strategy
+- Primary key indexes (clustered)
+- Secondary indexes for frequent queries
+- Composite indexes for multi-column filters
+- Index maintenance and statistics
+
+### 4. Schema Evolution
+- Migration strategy (forward-only)
+- Backward compatibility during deploys
+- Column additions vs. breaking changes
+- Versioning for schema changes
+
+## Relational Database Design
+
+### Table Design Essentials
+- Primary key (BIGSERIAL, UUID)
+- Timestamps (created_at, updated_at)
+- Soft delete (deleted_at)
+- Proper data types
+
+### Relationship Patterns
+- One-to-Many: Foreign key in child table
+- Many-to-Many: Junction table with composite primary key
+- One-to-One: Rare; consider column addition instead
+
+### Partitioning Strategies
+- Range partitioning (dates, IDs)
+- List partitioning (regions, categories)
+- Hash partitioning (even distribution)
+- When to partition: >10M rows, predictable access patterns
+
+## NoSQL Design Patterns
+
+### Document Stores (MongoDB, DynamoDB)
+- Embed vs. reference decision tree
+- Avoid unbounded arrays
+- Duplicate data strategically
+- Query pattern drives schema
+
+### Key-Value Stores (Redis, DynamoDB)
+- Compound key design
+- TTL for expiring data
+- Secondary indexes trade-offs
+
+### Graph Databases (Neo4j)
+- Node and relationship properties
+- Index on frequently queried properties
+- Cypher query optimization
+
+## Performance Optimization
+
+### Query Performance
+- EXPLAIN ANALYZE for execution plans
+- Index usage verification
+- Avoid N+1 queries (eager loading)
+- Connection pooling configuration
+
+### Write Optimization
+- Batch inserts for bulk data
+- Async writes for non-critical data
+- Write-ahead logging (WAL) tuning
+
+### Read Optimization
+- Read replicas for scaling
+- Query result caching
+- Materialized views for complex aggregations
+
+## Data Types Best Practices
+
+### Choosing Types
+- VARCHAR vs. TEXT vs. CHAR
+- INTEGER vs. BIGINT (consider growth)
+- DECIMAL for money (never FLOAT)
+- TIMESTAMPTZ for dates (always use timezone)
+- JSON/JSONB for semi-structured data
+
+### Type Performance
+- Smaller types = better performance
+- Fixed-length types for indexes
+- Avoid TEXT in WHERE clauses without indexes
+
+## Migration Strategies
+
+### Safe Migration Patterns
+1. Add nullable column → Backfill → Add NOT NULL
+2. Create new table → Dual write → Swap → Drop old
+3. Add index CONCURRENTLY (PostgreSQL)
+4. Rename via view (zero-downtime)
+
+### Rollback Strategies
+- Idempotent migrations
+- Reversible changes
+- Feature flags for data migrations
+- Separate schema and data migrations
+
+## Security & Compliance
+
+### Access Control
+- Principle of least privilege
+- Row-level security (RLS)
+- Column-level permissions
+- Audit logging for sensitive data
+
+### Data Encryption
+- Encryption at rest
+- Encryption in transit (SSL/TLS)
+- Column-level encryption for PII
+- Key rotation policies
+
+### GDPR/Privacy
+- Soft delete vs. hard delete
+- Data retention policies
+- PII identification and protection
+- Right to be forgotten implementation
+
+## Common Patterns
+
+### Soft Delete
+Use `deleted_at` timestamp with partial index
+
+### Audit Trails
+Track created_at, created_by, updated_at, updated_by
+
+### Status/State Machine
+Use CHECK constraints for valid states
+
+## Design Checklist
+
+- [ ] All tables have primary keys
+- [ ] Foreign key constraints defined
+- [ ] Indexes cover frequent query patterns
+- [ ] Data types appropriately sized
+- [ ] Nullable columns justified
+- [ ] Constraints enforce business rules
+- [ ] Migration scripts tested
+- [ ] Rollback plan documented
+- [ ] Performance testing completed
+- [ ] Schema documented
+- [ ] Backup/restore verified
+- [ ] Security audit completed

package/examples/abilities/debugging.md

@@ -0,0 +1,43 @@
+# Debugging Ability
+
+Systematically identify and fix bugs in code.
+
+## Debugging Process
+
+1. **Reproduce** the issue
+   - Understand error messages
+   - Identify conditions that trigger the bug
+   - Create minimal reproduction case
+
+2. **Investigate** the problem
+   - Read stack traces carefully
+   - Add logging and breakpoints
+   - Check recent changes (git diff)
+   - Verify assumptions
+
+3. **Isolate** the root cause
+   - Use binary search (comment out code blocks)
+   - Test components individually
+   - Check inputs and outputs
+   - Trace execution flow
+
+4. **Fix** the bug
+   - Implement targeted fix
+   - Avoid introducing new bugs
+   - Update related code if needed
+   - Add regression test
+
+5. **Verify** the solution
+   - Test the fix thoroughly
+   - Check for side effects
+   - Run full test suite
+   - Document the fix
+
+## Common Bug Types
+
+- Off-by-one errors
+- Null/undefined reference errors
+- Race conditions and timing issues
+- Type mismatches
+- Resource leaks (memory, file handles)
+- Logic errors in conditionals

package/examples/abilities/dependency-audit.md

@@ -0,0 +1,60 @@
+# Dependency Audit
+
+Scan and manage third-party dependencies for known vulnerabilities. Keep dependencies updated and minimize supply chain risks.
+
+## Do's ✅
+
+```bash
+# ✅ Good: Regular scanning
+npm audit
+npm audit fix
+
+npx snyk test
+npx snyk monitor
+```
+
+```yaml
+# ✅ Good: Automated CI scanning
+name: Security
+on: [push, pull_request]
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Run Snyk
+        uses: snyk/actions/node@master
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+```
+
+```json
+// ✅ Good: Pin versions
+{
+  "dependencies": {
+    "express": "4.18.2"
+  }
+}
+```
+
+## Don'ts ❌
+
+```bash
+# ❌ Bad: Ignoring warnings
+npm audit
+# 15 vulnerabilities found
+# (deploys anyway)
+```
+
+```javascript
+// ❌ Bad: Unmaintained packages
+const pkg = require('abandoned-library');  // Last update 5 years ago
+```
+
+## Best Practices
+- Run `npm audit` in CI pipeline
+- Use Dependabot/Renovate for auto-updates
+- Review changelogs before updating
+- Have rollback plan
+- Monitor security advisories
+- Use minimal dependencies

package/examples/abilities/design-system-implementation.md

@@ -0,0 +1,126 @@
+# Design System Implementation
+
+## Overview
+Implement and maintain consistent design systems using tokens, components, and documentation. Ensure brand consistency and developer efficiency across the application.
+
+## Core Concepts
+
+### Design Tokens
+Centralized design decisions (colors, typography, spacing) as code.
+
+**Token Categories**:
+- Colors (primary, secondary, success, danger)
+- Spacing (xs, sm, md, lg, xl)
+- Typography (font families, sizes)
+- Breakpoints (mobile, tablet, desktop)
+
+### Theme System
+- Light/Dark theme support
+- Consistent color schemes
+- Themeable components
+- Runtime theme switching
+
+## Component Library Structure
+
+```
+/design-system
+  /tokens
+    colors.ts
+    spacing.ts
+    typography.ts
+  /components
+    /Button
+      Button.tsx
+      Button.test.tsx
+      Button.stories.tsx
+    /Input
+    /Card
+  /hooks
+    useTheme.ts
+  /utils
+    themed.ts
+```
+
+## Best Practices
+
+### 1. Use Design Tokens
+- Reference tokens, not magic values
+- Maintain consistency across app
+- Single source of truth
+
+### 2. Variant System
+- Consistent variants (primary, secondary, ghost)
+- Size variants (sm, md, lg)
+- Type-safe props
+
+### 3. Component Composition
+- Build complex components from simpler ones
+- Reusable building blocks
+- Clear component hierarchy
+
+### 4. Accessibility First
+- Include ARIA attributes
+- Keyboard navigation
+- Screen reader support
+- Color contrast compliance
+
+### 5. Responsive Design
+- Use responsive tokens
+- Breakpoint consistency
+- Mobile-first approach
+
+### 6. Documentation
+- Storybook for components
+- Usage examples
+- Props documentation
+- Visual regression tests
+
+## Do's ✅
+
+- Use design tokens consistently
+- Create variant systems for flexibility
+- Document all components in Storybook
+- Test accessibility requirements
+- Maintain component library structure
+- Version components properly
+
+## Don'ts ❌
+
+### Inconsistent Spacing
+Avoid random spacing values—use spacing scale
+
+### Hardcoded Colors
+Use semantic color names from tokens
+
+### Component Duplication
+Single component with variants > multiple implementations
+
+### Missing Documentation
+Every component needs Storybook stories
+
+## Component Checklist
+
+- [ ] Uses design tokens
+- [ ] Has variant system
+- [ ] TypeScript interfaces defined
+- [ ] Accessibility attributes included
+- [ ] Responsive design implemented
+- [ ] Storybook stories created
+- [ ] Unit tests written
+- [ ] Visual regression tests
+- [ ] Documentation complete
+- [ ] Breaking changes versioned
+
+## Tools
+
+- **Storybook**: Component documentation and testing
+- **Styled Components / Tailwind**: Styling solutions
+- **Figma**: Design source of truth
+- **Chromatic**: Visual regression testing
+
+## Resources
+
+- [Material Design System](https://m3.material.io/)
+- [Ant Design](https://ant.design/)
+- [Chakra UI](https://chakra-ui.com/)
+- [Radix UI](https://www.radix-ui.com/)

package/examples/abilities/documentation.md

@@ -0,0 +1,54 @@
+# Documentation Ability
+
+Create clear, comprehensive, and useful documentation.
+
+## Documentation Types
+
+1. **API Documentation**
+   - Function/method signatures
+   - Parameters and return values
+   - Usage examples
+   - Error conditions
+
+2. **README Files**
+   - Project overview
+   - Installation instructions
+   - Quick start guide
+   - Links to detailed docs
+
+3. **User Guides**
+   - Feature explanations
+   - Step-by-step tutorials
+   - Screenshots and diagrams
+   - Troubleshooting section
+
+4. **Technical Specifications**
+   - Architecture overview
+   - Design decisions
+   - System requirements
+   - API contracts
+
+5. **Code Comments**
+   - Explain why (not what)
+   - Document complex logic
+   - Add TODOs and FIXMEs
+   - Use JSDoc/docstrings
+
+## Writing Principles
+
+- **Clarity**: Use simple, direct language
+- **Completeness**: Cover all necessary information
+- **Accuracy**: Keep docs up to date
+- **Usability**: Structure for easy navigation
+- **Examples**: Show, don't just tell
+
+## Documentation Checklist
+
+- [ ] Project purpose clear
+- [ ] Installation steps complete
+- [ ] Usage examples included
+- [ ] API documented
+- [ ] Configuration options explained
+- [ ] Troubleshooting guide provided
+- [ ] Links to related resources
+- [ ] Version/changelog maintained