@defai.digital/automatosx 5.0.13 → 5.1.2

package/examples/abilities/best-practices.md

@@ -0,0 +1,102 @@
+# Best Practices Ability
+
+Apply industry-standard best practices across development.
+
+## Code Quality
+
+1. **Readability**
+   - Clear, descriptive names
+   - Consistent formatting
+   - Meaningful comments
+   - Self-documenting code
+
+2. **Simplicity**
+   - KISS (Keep It Simple, Stupid)
+   - Avoid over-engineering
+   - Solve today's problem
+   - Refactor when needed
+
+3. **Maintainability**
+   - DRY (Don't Repeat Yourself)
+   - SOLID principles
+   - Low coupling, high cohesion
+   - Modular design
+
+4. **Reliability**
+   - Error handling
+   - Input validation
+   - Defensive programming
+   - Comprehensive testing
+
+## Development Practices
+
+### Version Control (Git)
+
+- Commit often, push daily
+- Write meaningful commit messages
+- Use feature branches
+- Review before merging
+- Keep main/master deployable
+
+### Code Review
+
+- Review all changes
+- Be constructive and respectful
+- Check for bugs, style, design
+- Suggest alternatives
+- Approve only when ready
+
+### Testing
+
+- Write tests first (TDD)
+- Test behavior, not implementation
+- Aim for 80%+ coverage
+- Fast test execution
+- Fix failing tests immediately
+
+### Security
+
+- Never commit secrets
+- Validate all inputs
+- Use parameterized queries
+- Keep dependencies updated
+- Follow OWASP guidelines
+
+## Architecture Principles
+
+1. **Separation of Concerns**
+   - Each module has one responsibility
+   - Clear boundaries
+   - Minimal dependencies
+
+2. **Dependency Injection**
+   - Don't create dependencies internally
+   - Inject through constructor/parameters
+   - Easier testing and flexibility
+
+3. **Interface-Based Design**
+   - Program to interfaces, not implementations
+   - Enables polymorphism
+   - Facilitates testing (mocking)
+
+4. **Configuration Over Hardcoding**
+   - Use config files/environment variables
+   - Don't hardcode URLs, paths, credentials
+   - Environment-specific configs
+
+## Performance
+
+- Profile before optimizing
+- Optimize bottlenecks only
+- Use caching strategically
+- Minimize database queries
+- Lazy load when possible
+- Consider asynchronous operations
+
+## Documentation
+
+- README for every project
+- API documentation (JSDoc, OpenAPI)
+- Code comments for "why"
+- Architecture diagrams
+- Changelog/release notes

package/examples/abilities/caching-strategy.md

@@ -0,0 +1,165 @@
+# Caching Strategy
+
+## Overview
+Design and implement multi-layer caching strategies to optimize application performance, reduce database load, and improve user experience.
+
+## Caching Layers
+
+### 1. Client-Side Caching
+- Browser cache (Cache-Control, ETag)
+- Service Worker caching
+- Local Storage / IndexedDB
+- CDN edge caching
+
+### 2. Application-Level Caching
+- In-memory cache (Redis, Memcached)
+- Application process cache
+- Query result caching
+- Computed value caching
+
+### 3. Database Caching
+- Query result cache
+- Prepared statement cache
+- Connection pool
+- Buffer pool (InnoDB)
+
+## Cache Patterns
+
+### Cache-Aside (Lazy Loading)
+1. Check cache
+2. If miss → Query database
+3. Store in cache
+4. Return data
+
+**Use when**: Read-heavy, acceptable stale data
+
+### Write-Through
+1. Write to cache
+2. Write to database (synchronous)
+3. Return success
+
+**Use when**: Data consistency critical
+
+### Write-Behind (Write-Back)
+1. Write to cache
+2. Queue database write (async)
+3. Return success
+
+**Use when**: High write throughput needed
+
+### Read-Through
+Cache handles database reads automatically
+
+**Use when**: Simplify application logic
+
+### Refresh-Ahead
+Proactively refresh before expiration
+
+**Use when**: Predictable access patterns
+
+## Cache Invalidation
+
+### Time-Based (TTL)
+**Pros**: Simple, predictable
+**Cons**: May serve stale data
+
+### Event-Based
+**Pros**: Always fresh
+**Cons**: Complex invalidation logic
+
+### Tag-Based
+**Pros**: Flexible, bulk invalidation
+**Cons**: Overhead in management
+
+## Cache Key Design
+
+### Naming Conventions
+`<namespace>:<entity>:<id>:<attribute>`
+
+Examples:
+- `user:123:profile`
+- `product:456:inventory`
+- `session:abc123:cart`
+
+### Hierarchical Keys
+`app:v1:user:123:settings`
+
+### Composite Keys
+- `search:query:<hash>:page:1`
+- `filter:category:electronics:brand:apple`
+
+## Performance Optimization
+
+### Connection Pooling
+- Min/max pool size tuning
+- Connection timeout configuration
+- Health checks for stale connections
+
+### Compression
+- Compress large values (>1KB)
+- Trade CPU for memory savings
+- Use MessagePack or Snappy
+
+### Batch Operations
+- Pipeline multiple commands
+- Reduce network round trips
+
+### Read Replicas
+- Separate read/write connections
+- Route heavy reads to replicas
+- Monitor replication lag
+
+## Monitoring & Metrics
+
+### Key Metrics
+- Hit rate (hits / (hits + misses))
+- Miss rate
+- Eviction rate
+- Memory usage
+- Latency (p50, p95, p99)
+
+### Alerts
+- Hit rate < 80%
+- Memory usage > 85%
+- Eviction rate spike
+- Replication lag > 1s
+
+## Eviction Policies
+- **noeviction**: Return error when full
+- **allkeys-lru**: Evict least recently used
+- **volatile-lru**: Evict LRU with TTL set
+- **allkeys-random**: Random eviction
+- **volatile-ttl**: Evict soonest expiring
+
+## Common Pitfalls
+
+### Cache Stampede
+**Problem**: Many requests hit DB on cache miss
+**Solution**: Probabilistic early expiration, lock-based refresh, always return stale data while refreshing
+
+### Cache Penetration
+**Problem**: Queries for non-existent data bypass cache
+**Solution**: Cache null results with short TTL
+
+### Hot Key Problem
+**Problem**: Single key gets massive traffic
+**Solution**: Key sharding, local cache, load balancing
+
+### Cache Avalanche
+**Problem**: Many keys expire simultaneously
+**Solution**: Add jitter to TTL (TTL ± random)
+
+## Design Checklist
+
+- [ ] Cache layers identified (client, app, DB)
+- [ ] Cache pattern selected (cache-aside, write-through, etc.)
+- [ ] Invalidation strategy defined
+- [ ] Key naming convention established
+- [ ] TTL values justified
+- [ ] Eviction policy configured
+- [ ] Connection pooling set up
+- [ ] Monitoring/alerting configured
+- [ ] Security measures implemented
+- [ ] Cache stampede prevention
+- [ ] Performance testing completed
+- [ ] Documentation updated

package/examples/abilities/ci-cd.md

@@ -0,0 +1,61 @@
+# CI/CD Pipelines
+
+Automate build, test, and deployment processes. Implement continuous integration and continuous delivery for reliable, fast releases.
+
+## Do's ✅
+
+```yaml
+# ✅ Good: Comprehensive pipeline (GitHub Actions)
+name: CI/CD
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build
+
+  deploy:
+    needs: test
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy
+        run: ./deploy.sh production
+        env:
+          AWS_KEY: ${{ secrets.AWS_KEY }}
+```
+
+## Don'ts ❌
+
+```yaml
+# ❌ Bad: Deploy without testing
+on: push
+jobs:
+  deploy:
+    steps:
+      - run: ./deploy.sh  # YOLO!
+
+# ❌ Bad: Secrets in code
+env:
+  API_KEY: "sk_live_abc123"  # Never!
+```
+
+## Best Practices
+- Run tests on every commit
+- Use secrets management
+- Implement rollback strategies
+- Use artifact caching
+- Implement deployment gates for production
+- Monitor deployment health

package/examples/abilities/code-generation.md

@@ -0,0 +1,95 @@
+# Code Generation
+
+Generate high-quality, production-ready code following best practices and patterns.
+
+## Core Principles
+
+### 1. Type Safety & Validation
+- Use strong typing (TypeScript interfaces, Python type hints)
+- Validate inputs before processing
+- Define clear return types
+- Use enums for fixed value sets
+
+### 2. Error Handling
+- Use try-catch for I/O operations
+- Provide specific error messages with context
+- Log errors appropriately
+- Never swallow errors silently
+- Return typed error objects or throw typed exceptions
+
+### 3. Function Design
+- Single responsibility per function
+- Clear, descriptive names
+- Document complex logic with comments
+- Keep functions small (<50 lines)
+- Minimize side effects
+
+### 4. API Design
+- RESTful conventions (GET/POST/PUT/DELETE)
+- Consistent response formats
+- Proper HTTP status codes
+- Request/response validation
+- API versioning when needed
+
+### 5. Testing
+- Write unit tests for business logic
+- Test error cases and edge conditions
+- Use descriptive test names
+- Aim for >80% coverage on critical paths
+- Mock external dependencies
+
+### 6. Code Quality
+- Follow project coding standards
+- Use linting and formatting tools
+- Write self-documenting code
+- Keep complexity low (cyclomatic complexity <10)
+- Remove dead code and TODOs
+
+### 7. Security
+- Validate and sanitize all inputs
+- Use parameterized queries (prevent SQL injection)
+- Never log sensitive data
+- Follow principle of least privilege
+- Keep dependencies updated
+
+### 8. Performance
+- Avoid N+1 queries
+- Use appropriate data structures
+- Cache when beneficial
+- Lazy load when possible
+- Profile before optimizing
+
+## Language-Specific Patterns
+
+### TypeScript/JavaScript
+- Async/await for promises
+- Optional chaining (?.) and nullish coalescing (??)
+- Destructuring for cleaner code
+- Use const by default, let when needed
+- Avoid var
+
+### Python
+- Type hints for function signatures
+- List/dict comprehensions for data transformation
+- Context managers (with statement) for resources
+- Follow PEP 8 style guide
+- Use dataclasses for data models
+
+### SQL
+- Use indexes on frequently queried columns
+- Avoid SELECT *
+- Use JOINs efficiently
+- Parameterize queries
+- Use transactions for multi-step operations
+
+## Quick Checklist
+
+Before submitting code:
+- [ ] Types and interfaces defined
+- [ ] Error handling implemented
+- [ ] Input validation added
+- [ ] Tests written and passing
+- [ ] Code formatted and linted
+- [ ] No console.log/print in production code
+- [ ] Security considerations addressed
+- [ ] Performance optimized where needed

package/examples/abilities/code-review.md

@@ -0,0 +1,42 @@
+# Code Review Ability
+
+Perform thorough code reviews focusing on quality, security, and maintainability.
+
+## Review Areas
+
+1. **Correctness**
+   - Logic errors and bugs
+   - Edge case handling
+   - Error handling and validation
+
+2. **Security**
+   - Input validation
+   - SQL injection, XSS vulnerabilities
+   - Secrets and credentials exposure
+   - Authentication and authorization
+
+3. **Performance**
+   - Algorithm complexity (Big O)
+   - Resource usage (memory, CPU)
+   - Database query optimization
+   - Caching opportunities
+
+4. **Maintainability**
+   - Code clarity and readability
+   - Documentation quality
+   - Test coverage
+   - Modularity and coupling
+
+5. **Style**
+   - Coding standards compliance
+   - Naming conventions
+   - Code organization
+   - Consistent formatting
+
+## Review Process
+
+1. Understand the context and requirements
+2. Review code systematically (file by file)
+3. Identify issues and improvements
+4. Prioritize findings (critical/major/minor)
+5. Provide actionable, constructive feedback

package/examples/abilities/component-architecture.md

@@ -0,0 +1,112 @@
+# Component Architecture
+
+## Overview
+Design and implement reusable, maintainable component structures following modern frontend architecture patterns. Focus on composition, separation of concerns, and clear component hierarchies.
+
+## Core Principles
+
+### 1. Single Responsibility
+Each component should have one clear purpose. Avoid components that try to do too much.
+
+### 2. Composition Over Inheritance
+Build complex UIs by composing smaller, focused components rather than creating deep inheritance chains.
+
+### 3. Container/Presentational Pattern
+- **Container components**: Handle logic, state, and side effects
+- **Presentational components**: Focus purely on rendering UI based on props
+
+### 4. Props Design
+- Keep props interfaces simple and explicit
+- Use TypeScript for type safety
+- Avoid prop drilling—use context or state management for deep data
+
+## Component Structure
+
+```
+/components
+  /Button
+    Button.tsx          # Component implementation
+    Button.test.tsx     # Tests
+    Button.stories.tsx  # Storybook stories
+    index.ts            # Public exports
+```
+
+## Atomic Design
+
+Organize components by complexity:
+- **Atoms**: Button, Input, Label
+- **Molecules**: FormField (Input + Label), SearchBar
+- **Organisms**: LoginForm, Header, Card
+- **Templates**: Page layouts
+- **Pages**: Complete pages
+
+## Best Practices
+
+### Component Design
+- Single responsibility principle
+- TypeScript interfaces for props
+- Proper error boundaries
+- Clear naming conventions
+
+### Performance
+- Memoization where appropriate (React.memo, useMemo)
+- Callback memoization (useCallback)
+- Code splitting for heavy components
+- Lazy loading with Suspense
+
+### Testing
+- Unit tests for component logic
+- Integration tests for user interactions
+- Accessibility testing
+- Visual regression tests
+
+## Anti-Patterns to Avoid
+
+### 1. God Components
+Components that handle too many responsibilities
+
+### 2. Prop Drilling
+Passing props through many levels—use Context API or state management
+
+### 3. Tight Coupling
+Components depending on specific parent or child implementations
+
+### 4. Mixed Concerns
+Mixing business logic, API calls, and rendering in one component
+
+## Component Checklist
+
+- [ ] Single responsibility
+- [ ] TypeScript interfaces for props
+- [ ] Proper error boundaries
+- [ ] Memoization where appropriate
+- [ ] Accessibility attributes (ARIA)
+- [ ] Unit tests for logic
+- [ ] Integration tests for interactions
+- [ ] Storybook documentation
+- [ ] Performance optimized
+- [ ] Code split if heavy
+
+## Performance Considerations
+
+### Memoization
+- Memoize expensive computations (useMemo)
+- Memoize callback functions (useCallback)
+- Memoize components that render often (React.memo)
+
+### Code Splitting
+- Lazy load heavy components
+- Use Suspense for loading states
+- Route-based code splitting
+
+### Optimization Techniques
+- Virtual scrolling for long lists
+- Debounce/throttle for frequent events
+- Avoid unnecessary re-renders
+- Use production builds
+
+## Resources
+
+- [React Component Patterns](https://reactpatterns.com/)
+- [Atomic Design Methodology](https://atomicdesign.bradfrost.com/)
+- [Testing Library Best Practices](https://testing-library.com/docs/react-testing-library/intro)

package/examples/abilities/content-creation.md

@@ -0,0 +1,97 @@
+# Content Creation Ability
+
+Create engaging, informative content for various audiences.
+
+## Content Types
+
+1. **Blog Posts**
+   - Catchy title
+   - Hook in first paragraph
+   - Clear structure (intro, body, conclusion)
+   - Scannable (headings, bullets, short paragraphs)
+   - Call to action
+
+2. **Tutorials**
+   - Clear learning objectives
+   - Prerequisites listed
+   - Step-by-step instructions
+   - Code examples
+   - Screenshots/diagrams
+   - What you learned / next steps
+
+3. **Documentation**
+   - Purpose and overview
+   - Installation/setup
+   - Usage examples
+   - API reference
+   - Troubleshooting
+   - FAQ
+
+4. **Presentations**
+   - One idea per slide
+   - Visual > text
+   - Tell a story
+   - Practice delivery
+   - End with key takeaways
+
+## Writing Process
+
+1. **Research**
+   - Understand the topic
+   - Know your audience
+   - Check existing content
+   - Gather examples
+
+2. **Outline**
+   - Main points
+   - Logical flow
+   - Supporting details
+   - Conclusion
+
+3. **Draft**
+   - Get ideas down
+   - Don't self-edit yet
+   - Write more than needed
+   - Focus on clarity
+
+4. **Edit**
+   - Cut unnecessary content
+   - Improve clarity
+   - Fix grammar/spelling
+   - Check flow and structure
+
+5. **Review**
+   - Read aloud
+   - Get feedback
+   - Check accuracy
+   - Final polish
+
+## Writing Tips
+
+**Clarity:**
+
+- Use simple words
+- Short sentences
+- Active voice
+- Concrete examples
+
+**Engagement:**
+
+- Hook readers early
+- Use stories and examples
+- Ask questions
+- Vary sentence length
+
+**Structure:**
+
+- Clear headings
+- Logical progression
+- Bullet points for lists
+- White space for readability
+
+**Credibility:**
+
+- Cite sources
+- Use data and statistics
+- Show expertise
+- Acknowledge limitations