@defai.digital/automatosx 5.6.35 → 5.7.2

package/examples/agents/.automatosx/abilities/clean-code.md

@@ -0,0 +1,398 @@
+# Clean Code Ability
+
+Expert knowledge and application of clean code principles for writing maintainable, readable, and high-quality software.
+
+## Overview
+
+Clean code is code that is easy to read, understand, and modify. It communicates intent clearly and minimizes cognitive load for future developers (including yourself).
+
+## Fundamental Principles
+
+### 1. Meaningful Names
+
+**Rule**: Names should reveal intent without requiring comments
+
+**Guidelines**:
+- Use intention-revealing names
+- Avoid disinformation and encodings
+- Make meaningful distinctions
+- Use pronounceable and searchable names
+- Avoid mental mapping
+
+**Examples**:
+```typescript
+// ❌ BAD: Cryptic names
+const d = new Date(); // elapsed time in days
+const arr = ['Bob', 'Alice'];
+
+// ✅ GOOD: Intention-revealing
+const elapsedTimeInDays = new Date();
+const userNames = ['Bob', 'Alice'];
+
+// ❌ BAD: Hungarian notation, noise words
+const strName = 'Bob';
+const userData = { name: 'Bob' };
+const userInfo = { name: 'Bob' }; // What's the difference?
+
+// ✅ GOOD: Clean, semantic names
+const userName = 'Bob';
+const user = { name: 'Bob' };
+const userProfile = { name: 'Bob', bio: '...' };
+```
+
+**Variable Naming**:
+- Use nouns or noun phrases
+- Boolean: `isActive`, `hasPermission`, `canEdit`
+- Collections: Use plural (`users`, `orders`, `products`)
+
+**Function Naming**:
+- Use verbs or verb phrases
+- `getUser()`, `calculateTotal()`, `validateInput()`
+- Boolean returning: `isValid()`, `hasErrors()`, `canProceed()`
+
+**Class Naming**:
+- Use nouns
+- Avoid "Manager", "Processor", "Data" suffixes
+- `UserRepository`, `EmailService`, `OrderValidator`
+
+### 2. Functions
+
+**Rule**: Functions should do one thing, do it well, and do it only
+
+**Small Functions**:
+- Keep functions small (< 20 lines ideal)
+- Each function should be one level of abstraction
+- Functions should not have side effects
+
+**Single Responsibility**:
+```typescript
+// ❌ BAD: Multiple responsibilities
+function processUser(user: User) {
+  validateUser(user);
+  saveToDatabase(user);
+  sendEmail(user);
+  logAudit(user);
+  updateCache(user);
+}
+
+// ✅ GOOD: Single responsibility
+function registerUser(user: User) {
+  const validated = validateUser(user);
+  return userRepository.save(validated);
+}
+
+function notifyUserRegistered(user: User) {
+  emailService.sendWelcome(user);
+  auditLogger.log('USER_REGISTERED', user.id);
+}
+```
+
+**Function Arguments**:
+- Zero arguments (niladic) is ideal
+- One argument (monadic) is good
+- Two arguments (dyadic) are okay
+- Three+ arguments (triadic+) require justification
+- Avoid flag arguments (split into two functions)
+
+**Examples**:
+```typescript
+// ❌ BAD: Too many arguments
+function createUser(name: string, email: string, age: number, role: string, active: boolean) {}
+
+// ✅ GOOD: Use object parameter
+function createUser(userData: UserData) {}
+
+// ❌ BAD: Flag argument
+function saveUser(user: User, validate: boolean) {}
+
+// ✅ GOOD: Separate functions
+function saveUser(user: User) {}
+function saveUserWithoutValidation(user: User) {}
+```
+
+**Command Query Separation**:
+- Functions should either DO something or ANSWER something, not both
+- Commands modify state, queries return values
+
+```typescript
+// ❌ BAD: Does both
+function setAndReturn(value: string): boolean {
+  this.value = value; // Command
+  return this.value === value; // Query
+}
+
+// ✅ GOOD: Separated
+function setValue(value: string): void {
+  this.value = value;
+}
+
+function getValue(): string {
+  return this.value;
+}
+```
+
+### 3. Comments
+
+**Rule**: Good code mostly documents itself; use comments wisely
+
+**When to Comment**:
+- Explain WHY, not WHAT
+- Clarify complex business rules
+- Warn of consequences
+- TODO/FIXME notes (with tickets)
+- Legal comments (copyright, license)
+- API documentation (JSDoc, docstrings)
+
+**When NOT to Comment**:
+- Don't comment bad code, rewrite it
+- Avoid redundant comments
+- Don't comment out code (use version control)
+- Avoid journal comments
+- Avoid position markers
+
+**Examples**:
+```typescript
+// ❌ BAD: Redundant comments
+// Get the user by ID
+function getUserById(id: string): User {
+  // Return the user
+  return users.find(u => u.id === id);
+}
+
+// ✅ GOOD: Self-documenting code
+function getUserById(id: string): User {
+  return users.find(u => u.id === id);
+}
+
+// ❌ BAD: Commented-out code
+function processOrder(order: Order) {
+  // validateOrder(order);
+  // checkInventory(order);
+  saveOrder(order);
+}
+
+// ✅ GOOD: Clear intent without noise
+/**
+ * Processes order for payment and fulfillment.
+ * NOTE: Validation and inventory check are handled upstream.
+ */
+function processOrder(order: Order) {
+  saveOrder(order);
+}
+```
+
+### 4. Formatting
+
+**Rule**: Code formatting is about communication
+
+**Vertical Formatting**:
+- Small files are better (< 500 lines)
+- Blank lines separate concepts
+- Related code should be close together
+- Declare variables close to usage
+- Dependent functions should be close
+
+**Horizontal Formatting**:
+- Keep lines short (< 120 characters)
+- Use whitespace to associate related things
+- Indent to show hierarchy
+
+**Example**:
+```typescript
+// ✅ GOOD: Well-formatted
+class UserService {
+  constructor(
+    private userRepository: UserRepository,
+    private emailService: EmailService
+  ) {}
+
+  async registerUser(userData: UserData): Promise<User> {
+    const validated = this.validateUserData(userData);
+    const user = await this.userRepository.create(validated);
+    await this.sendWelcomeEmail(user);
+    return user;
+  }
+
+  private validateUserData(userData: UserData): UserData {
+    if (!userData.email) throw new Error('Email required');
+    if (!userData.name) throw new Error('Name required');
+    return userData;
+  }
+
+  private async sendWelcomeEmail(user: User): Promise<void> {
+    await this.emailService.send(user.email, 'Welcome!');
+  }
+}
+```
+
+### 5. Objects and Data Structures
+
+**Rule**: Objects hide data, expose behavior. Data structures expose data, have no behavior.
+
+**Law of Demeter**:
+- Don't talk to strangers
+- Method should only call methods on:
+  - Itself
+  - Its parameters
+  - Objects it creates
+  - Its direct dependencies
+
+```typescript
+// ❌ BAD: Violates Law of Demeter (train wreck)
+const street = user.getAddress().getStreet().getName();
+
+// ✅ GOOD: Tell, don't ask
+const street = user.getStreetName();
+
+// Inside User class:
+getStreetName(): string {
+  return this.address.street.name;
+}
+```
+
+### 6. Error Handling
+
+**Rule**: Error handling is important, but it shouldn't obscure logic
+
+**Use Exceptions**:
+```typescript
+// ❌ BAD: Error codes
+function processPayment(amount: number): number {
+  if (amount <= 0) return -1;
+  if (insufficientFunds()) return -2;
+  return 0; // success
+}
+
+// ✅ GOOD: Exceptions
+function processPayment(amount: number): void {
+  if (amount <= 0) {
+    throw new InvalidAmountError('Amount must be positive');
+  }
+  if (insufficientFunds()) {
+    throw new InsufficientFundsError('Not enough balance');
+  }
+  // Process payment
+}
+```
+
+**Don't Return Null**:
+```typescript
+// ❌ BAD: Null checks everywhere
+const users = getUsers();
+if (users !== null) {
+  for (const user of users) {
+    if (user !== null) {
+      // ...
+    }
+  }
+}
+
+// ✅ GOOD: Return empty collection
+function getUsers(): User[] {
+  return users ?? [];
+}
+
+// Or use Optional/Maybe pattern
+function getUserById(id: string): User | undefined {
+  return users.find(u => u.id === id);
+}
+```
+
+### 7. DRY (Don't Repeat Yourself)
+
+**Rule**: Every piece of knowledge should have a single representation in the system
+
+```typescript
+// ❌ BAD: Duplication
+function calculateOrderTotal(order: Order): number {
+  let total = 0;
+  for (const item of order.items) {
+    total += item.price * item.quantity;
+  }
+  total += total * 0.1; // Tax
+  total += 5; // Shipping
+  return total;
+}
+
+function calculateInvoiceTotal(invoice: Invoice): number {
+  let total = 0;
+  for (const item of invoice.items) {
+    total += item.price * item.quantity;
+  }
+  total += total * 0.1; // Tax
+  total += 5; // Shipping
+  return total;
+}
+
+// ✅ GOOD: Extract common logic
+function calculateSubtotal(items: Item[]): number {
+  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+}
+
+function addTaxAndShipping(subtotal: number): number {
+  const tax = subtotal * 0.1;
+  const shipping = 5;
+  return subtotal + tax + shipping;
+}
+
+function calculateTotal(items: Item[]): number {
+  const subtotal = calculateSubtotal(items);
+  return addTaxAndShipping(subtotal);
+}
+```
+
+## Code Quality Checklist
+
+**Naming**:
+- [ ] All names reveal intent
+- [ ] No abbreviations or encodings
+- [ ] Boolean names start with is/has/can
+- [ ] Collections are plural
+- [ ] Functions are verbs, classes are nouns
+
+**Functions**:
+- [ ] Functions are small (< 20 lines)
+- [ ] Functions do one thing
+- [ ] One level of abstraction per function
+- [ ] Few arguments (prefer 0-2)
+- [ ] No flag arguments
+- [ ] No side effects
+
+**Comments**:
+- [ ] Comments explain WHY, not WHAT
+- [ ] No commented-out code
+- [ ] No redundant comments
+- [ ] API documentation present where needed
+
+**Formatting**:
+- [ ] Consistent indentation
+- [ ] Lines < 120 characters
+- [ ] Blank lines separate concepts
+- [ ] Related code is together
+
+**Error Handling**:
+- [ ] Use exceptions, not error codes
+- [ ] Don't return null (use empty collections or Optional)
+- [ ] Exceptions are specific and meaningful
+
+**General**:
+- [ ] No duplication (DRY)
+- [ ] Code is self-documenting
+- [ ] Tests exist and pass
+- [ ] No dead code
+
+## The Boy Scout Rule
+
+**"Leave the code better than you found it."**
+
+- Clean up small messes when you see them
+- Improve names, extract functions, add tests
+- Continuous improvement over time
+- Don't need permission for small improvements
+
+## Further Reading
+
+- "Clean Code" by Robert C. Martin
+- "Code Complete" by Steve McConnell
+- "The Pragmatic Programmer" by Hunt and Thomas
+- "Refactoring" by Martin Fowler

package/examples/agents/.automatosx/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/agents/.automatosx/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/agents/.automatosx/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)