@defai.digital/automatosx 5.6.35 → 5.7.2

package/examples/agents/.automatosx/abilities/design-patterns.md

@@ -0,0 +1,437 @@
+# Design Patterns Ability
+
+Expert knowledge and application of software design patterns from the Gang of Four and beyond.
+
+## Overview
+
+Design patterns are proven solutions to common software design problems. They provide a shared vocabulary and best practices for object-oriented design.
+
+## Creational Patterns
+
+Patterns for object creation mechanisms.
+
+### Factory Method
+
+**Problem**: Need to create objects without specifying exact class
+**Solution**: Define interface for creating objects, let subclasses decide which class to instantiate
+
+**When to use**:
+- Class can't anticipate the type of objects it needs to create
+- Subclasses specify the objects to create
+- Delegate creation responsibility to helper subclasses
+
+**Example**:
+```typescript
+interface Logger {
+  log(message: string): void;
+}
+
+abstract class LoggerFactory {
+  abstract createLogger(): Logger;
+
+  logMessage(message: string) {
+    const logger = this.createLogger();
+    logger.log(message);
+  }
+}
+
+class ConsoleLoggerFactory extends LoggerFactory {
+  createLogger(): Logger {
+    return new ConsoleLogger();
+  }
+}
+
+class FileLoggerFactory extends LoggerFactory {
+  createLogger(): Logger {
+    return new FileLogger();
+  }
+}
+```
+
+### Abstract Factory
+
+**Problem**: Create families of related objects without specifying concrete classes
+**Solution**: Provide interface for creating families of related objects
+
+**When to use**:
+- System should be independent of how products are created
+- System should be configured with one of multiple families of products
+- Family of related products should be used together
+
+### Singleton
+
+**Problem**: Ensure a class has only one instance with global access point
+**Solution**: Private constructor, static instance method
+
+**When to use**:
+- Exactly one instance needed (configuration, connection pool)
+- Controlled access to sole instance required
+- Instance should be extensible by subclassing
+
+**Caution**: Often considered anti-pattern; prefer dependency injection
+
+**Example**:
+```typescript
+class DatabaseConnection {
+  private static instance: DatabaseConnection;
+  private constructor() { }
+
+  static getInstance(): DatabaseConnection {
+    if (!DatabaseConnection.instance) {
+      DatabaseConnection.instance = new DatabaseConnection();
+    }
+    return DatabaseConnection.instance;
+  }
+}
+```
+
+### Builder
+
+**Problem**: Construct complex objects step by step
+**Solution**: Separate construction from representation
+
+**When to use**:
+- Object creation involves many steps
+- Same construction process should create different representations
+- Avoid telescoping constructors
+
+**Example**:
+```typescript
+class QueryBuilder {
+  private query = '';
+
+  select(fields: string[]): this {
+    this.query = `SELECT ${fields.join(', ')}`;
+    return this;
+  }
+
+  from(table: string): this {
+    this.query += ` FROM ${table}`;
+    return this;
+  }
+
+  where(condition: string): this {
+    this.query += ` WHERE ${condition}`;
+    return this;
+  }
+
+  build(): string {
+    return this.query;
+  }
+}
+
+const query = new QueryBuilder()
+  .select(['name', 'email'])
+  .from('users')
+  .where('age > 18')
+  .build();
+```
+
+### Prototype
+
+**Problem**: Create new objects by copying existing ones
+**Solution**: Specify kinds of objects using prototypical instance
+
+## Structural Patterns
+
+Patterns for composing classes and objects.
+
+### Adapter
+
+**Problem**: Make incompatible interfaces work together
+**Solution**: Convert interface of class into another interface clients expect
+
+**When to use**:
+- Use existing class with incompatible interface
+- Create reusable class cooperating with unrelated classes
+- Need to use several existing subclasses with incompatible interfaces
+
+**Example**:
+```typescript
+// Legacy API
+class LegacyLogger {
+  logMessage(msg: string) { console.log(msg); }
+}
+
+// New interface
+interface ModernLogger {
+  log(level: string, message: string): void;
+}
+
+// Adapter
+class LoggerAdapter implements ModernLogger {
+  constructor(private legacy: LegacyLogger) {}
+
+  log(level: string, message: string) {
+    this.legacy.logMessage(`[${level}] ${message}`);
+  }
+}
+```
+
+### Decorator
+
+**Problem**: Add responsibilities to objects dynamically
+**Solution**: Wrap object in decorator that adds behavior
+
+**When to use**:
+- Add responsibilities to individual objects dynamically
+- Responsibilities can be withdrawn
+- Extension by subclassing is impractical
+
+**Example**:
+```typescript
+interface Coffee {
+  cost(): number;
+  description(): string;
+}
+
+class SimpleCoffee implements Coffee {
+  cost() { return 5; }
+  description() { return 'Simple coffee'; }
+}
+
+class MilkDecorator implements Coffee {
+  constructor(private coffee: Coffee) {}
+  cost() { return this.coffee.cost() + 2; }
+  description() { return this.coffee.description() + ', milk'; }
+}
+
+class SugarDecorator implements Coffee {
+  constructor(private coffee: Coffee) {}
+  cost() { return this.coffee.cost() + 1; }
+  description() { return this.coffee.description() + ', sugar'; }
+}
+
+const coffee = new SugarDecorator(new MilkDecorator(new SimpleCoffee()));
+// Cost: 8, Description: "Simple coffee, milk, sugar"
+```
+
+### Facade
+
+**Problem**: Provide simplified interface to complex subsystem
+**Solution**: Higher-level interface that makes subsystem easier to use
+
+**When to use**:
+- Simplify complex subsystem
+- Layer your subsystems
+- Reduce coupling between subsystems
+
+### Proxy
+
+**Problem**: Provide surrogate or placeholder for another object
+**Solution**: Control access to the original object
+
+**When to use**:
+- Lazy initialization (virtual proxy)
+- Access control (protection proxy)
+- Remote object access (remote proxy)
+- Caching (cache proxy)
+
+### Composite
+
+**Problem**: Treat individual objects and compositions uniformly
+**Solution**: Compose objects into tree structures
+
+## Behavioral Patterns
+
+Patterns for communication between objects.
+
+### Strategy
+
+**Problem**: Define family of algorithms, make them interchangeable
+**Solution**: Encapsulate each algorithm, make them interchangeable
+
+**When to use**:
+- Many related classes differ only in behavior
+- Need different variants of algorithm
+- Algorithm uses data clients shouldn't know about
+- Class defines many behaviors as conditional statements
+
+**Example**:
+```typescript
+interface PaymentStrategy {
+  pay(amount: number): void;
+}
+
+class CreditCardPayment implements PaymentStrategy {
+  pay(amount: number) {
+    console.log(`Paid ${amount} with credit card`);
+  }
+}
+
+class PayPalPayment implements PaymentStrategy {
+  pay(amount: number) {
+    console.log(`Paid ${amount} with PayPal`);
+  }
+}
+
+class ShoppingCart {
+  constructor(private paymentStrategy: PaymentStrategy) {}
+
+  checkout(amount: number) {
+    this.paymentStrategy.pay(amount);
+  }
+}
+```
+
+### Observer
+
+**Problem**: Define one-to-many dependency between objects
+**Solution**: When one object changes state, all dependents are notified
+
+**When to use**:
+- Change to one object requires changing others
+- Object should notify others without assumptions about who they are
+- Abstraction has two aspects, one dependent on the other
+
+**Example**:
+```typescript
+interface Observer {
+  update(data: any): void;
+}
+
+class Subject {
+  private observers: Observer[] = [];
+
+  attach(observer: Observer) {
+    this.observers.push(observer);
+  }
+
+  notify(data: any) {
+    this.observers.forEach(obs => obs.update(data));
+  }
+}
+
+class DataLogger implements Observer {
+  update(data: any) {
+    console.log('Data logged:', data);
+  }
+}
+
+class DataDisplay implements Observer {
+  update(data: any) {
+    console.log('Data displayed:', data);
+  }
+}
+```
+
+### Command
+
+**Problem**: Encapsulate request as object
+**Solution**: Parameterize clients with different requests, queue/log requests
+
+**When to use**:
+- Parameterize objects with actions
+- Specify, queue, and execute requests at different times
+- Support undo
+- Support logging changes
+
+### Template Method
+
+**Problem**: Define skeleton of algorithm, let subclasses override steps
+**Solution**: Define algorithm structure, defer some steps to subclasses
+
+**When to use**:
+- Implement invariant parts of algorithm once
+- Common behavior among subclasses should be factored
+- Control subclass extensions
+
+### Iterator
+
+**Problem**: Access elements of aggregate object sequentially without exposing representation
+**Solution**: Provide way to access elements without exposing structure
+
+### State
+
+**Problem**: Allow object to alter behavior when internal state changes
+**Solution**: Object appears to change its class
+
+### Chain of Responsibility
+
+**Problem**: Avoid coupling sender to receiver
+**Solution**: Give more than one object chance to handle request
+
+## Pattern Selection Guide
+
+### Choosing the Right Pattern
+
+**Creating Objects:**
+- Simple object creation → Factory Method
+- Family of related objects → Abstract Factory
+- Complex construction → Builder
+- Copy existing object → Prototype
+- Single instance → Singleton
+
+**Structuring Code:**
+- Incompatible interfaces → Adapter
+- Add behavior dynamically → Decorator
+- Simplify complex system → Facade
+- Control access → Proxy
+- Tree structure → Composite
+
+**Defining Behavior:**
+- Interchangeable algorithms → Strategy
+- Notify multiple objects → Observer
+- Encapsulate requests → Command
+- Algorithm skeleton → Template Method
+- Sequential access → Iterator
+- State-based behavior → State
+- Chain of handlers → Chain of Responsibility
+
+## Anti-patterns to Avoid
+
+### Pattern Overuse
+- Don't force patterns where they don't fit
+- Simpler solutions often better
+- Patterns add complexity and abstraction
+
+### Singleton Abuse
+- Global state is problematic
+- Tight coupling
+- Difficult to test
+- Consider dependency injection instead
+
+### God Object
+- Object that knows/does too much
+- Violates Single Responsibility Principle
+- Hard to maintain and test
+
+### Premature Optimization
+- Don't optimize before measuring
+- Pattern complexity should solve real problems
+- YAGNI (You Aren't Gonna Need It)
+
+## Best Practices
+
+1. **Understand the Problem First**
+   - Identify the actual problem
+   - Consider simpler solutions
+   - Pattern should solve real need
+
+2. **Know the Trade-offs**
+   - Every pattern adds complexity
+   - Balance flexibility vs. simplicity
+   - Consider maintainability
+
+3. **Use Patterns as Communication**
+   - Shared vocabulary
+   - Document intent
+   - Aid team understanding
+
+4. **Refactor to Patterns**
+   - Don't design patterns upfront
+   - Let patterns emerge
+   - Refactor when pattern becomes clear
+
+5. **Combine Patterns**
+   - Patterns often work together
+   - Strategy + Factory Method
+   - Decorator + Composite
+   - Observer + Mediator
+
+## Further Reading
+
+- "Design Patterns: Elements of Reusable Object-Oriented Software" by Gang of Four
+- "Head First Design Patterns" by Freeman et al.
+- "Patterns of Enterprise Application Architecture" by Martin Fowler
+- "Refactoring to Patterns" by Joshua Kerievsky

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

package/examples/agents/.automatosx/abilities/error-analysis.md

@@ -0,0 +1,107 @@
+# Error Analysis Ability
+
+Analyze and understand error messages to find solutions.
+
+## Error Analysis Process
+
+1. **Read the Error Carefully**
+   - Full error message
+   - Error code/type
+   - Stack trace
+   - Context information
+
+2. **Identify Error Type**
+   - Syntax error (typo, missing character)
+   - Runtime error (execution failure)
+   - Logic error (wrong output)
+   - Configuration error (missing setup)
+
+3. **Locate the Source**
+   - File name and line number
+   - Stack trace (call chain)
+   - Relevant code section
+   - Recent changes
+
+4. **Understand the Cause**
+   - What was the code trying to do?
+   - Why did it fail?
+   - What assumption was wrong?
+   - What conditions triggered it?
+
+5. **Research if Needed**
+   - Search error message
+   - Check documentation
+   - Review similar issues
+   - Ask for help (with context)
+
+## Common Error Patterns
+
+### Null/Undefined Errors
+
+```
+TypeError: Cannot read property 'x' of undefined
+```
+
+- Cause: Accessing property on null/undefined
+- Fix: Check if object exists first
+- Prevention: Use optional chaining (?.)
+
+### Type Errors
+
+```
+TypeError: 'int' object is not callable
+```
+
+- Cause: Using wrong type for operation
+- Fix: Convert type or use correct type
+- Prevention: Type annotations, validation
+
+### Import/Module Errors
+
+```
+ModuleNotFoundError: No module named 'x'
+```
+
+- Cause: Missing dependency or wrong path
+- Fix: Install dependency or fix import path
+- Prevention: Requirements file, path checks
+
+### Network Errors
+
+```
+ConnectionError: Connection refused
+```
+
+- Cause: Service not running, wrong address, firewall
+- Fix: Start service, check URL, check network
+- Prevention: Health checks, retry logic
+
+### Permission Errors
+
+```
+PermissionError: Permission denied
+```
+
+- Cause: Insufficient file/resource permissions
+- Fix: Grant permissions or run as correct user
+- Prevention: Check permissions, use appropriate user
+
+## Error Message Anatomy
+
+```
+TypeError: Cannot read property 'name' of undefined
+    at getUserName (app.js:42:18)
+    at handleRequest (app.js:15:10)
+    at Server.<anonymous> (app.js:8:5)
+```
+
+Parts:
+
+1. **Error Type**: TypeError
+2. **Error Message**: Cannot read property 'name' of undefined
+3. **Stack Trace**: Call chain showing where error occurred
+4. **Location**: app.js:42:18 (file:line:column)
+
+## Debugging Workflow
+
+1. Read error → 2. Identify location → 3. Examine code → 4. Form hypothesis → 5. Add logging → 6. Test fix → 7. Verify solution