@defai.digital/automatosx 5.0.13 → 5.1.2

package/examples/README.md

@@ -0,0 +1,434 @@
+# AutomatosX Examples
+
+This directory contains example agents, abilities, and usage patterns to help you get started with AutomatosX.
+
+## Directory Structure
+
+```
+examples/
+├── agents/           # Example agent profiles (YAML)
+├── abilities/        # Example ability definitions (Markdown)
+├── use-cases/        # Complete usage scenarios
+└── README.md         # This file
+```
+
+## Quick Start
+
+### 1. Using Example Agents
+
+Copy an example agent to your project:
+
+```bash
+# Copy all example agents
+cp -r examples/agents/* .automatosx/agents/
+
+# Or copy a specific agent
+cp examples/agents/backend.yaml .automatosx/agents/
+
+# Test the agent
+automatosx run backend "Hello, introduce yourself"
+```
+
+### 2. Using Example Abilities
+
+Copy example abilities to your project:
+
+```bash
+# Copy all abilities
+cp -r examples/abilities/* .automatosx/abilities/
+
+# Or copy specific abilities
+cp examples/abilities/code-review.md .automatosx/abilities/
+cp examples/abilities/debugging.md .automatosx/abilities/
+```
+
+### 3. Customizing Agents
+
+Edit agent profiles to customize behavior:
+
+```bash
+# Edit agent profile
+vim .automatosx/agents/backend.yaml
+
+# Customize:
+# - name: Unique identifier
+# - description: Agent's purpose
+# - model: AI model to use
+# - temperature: Creativity level (0.0-1.0)
+# - abilities: List of abilities to enable
+# - systemPrompt: Detailed instructions
+```
+
+## Agent Names
+
+**AutomatosX agents have human-friendly names!** 🎉
+
+Instead of remembering technical roles, you can use memorable names:
+
+- 👨‍💻 **Bob** - Backend Engineer
+- 👨‍💻 **Frank** - Frontend Developer
+- 🔒 **Steve** - Security Engineer
+- 🎨 **Debbee** - UX/UI Designer
+- 📊 **Daisy** - Data Scientist
+
+See [AGENTS_INFO.md](./AGENTS_INFO.md) for the complete directory.
+
+## Available Agents
+
+### backend.yaml - Bob
+
+**Purpose**: Backend development specialist for API and server-side tasks
+
+**Best for**:
+
+- API design and implementation
+- Database modeling
+- Server-side logic
+
+**Example**:
+
+```bash
+# Using role name
+automatosx run backend "Create a REST API endpoint for user management"
+
+# Using display name (easier to remember!)
+automatosx run Bob "Create a REST API endpoint for user management"
+```
+
+### quality.yaml - Queenie
+
+**Purpose**: Quality assurance and code review
+
+**Best for**:
+
+- Code review and analysis
+- Debugging and testing
+- Quality assurance
+
+**Example**:
+
+```bash
+automatosx run backend "Create a React component for user authentication"
+```
+
+### quality.yaml
+
+**Purpose**: Code review and quality analysis
+
+**Best for**:
+
+- Reviewing pull requests
+- Finding bugs and issues
+- Suggesting improvements
+
+**Example**:
+
+```bash
+automatosx run quality "Review the code in src/components/Auth.tsx"
+```
+
+### debugger.yaml
+
+**Purpose**: Debugging and troubleshooting
+
+**Best for**:
+
+- Analyzing error messages
+- Finding root causes
+- Suggesting fixes
+
+**Example**:
+
+```bash
+automatosx run debugger "Help me debug this error: TypeError: Cannot read property 'name' of undefined"
+```
+
+### writer.yaml
+
+**Purpose**: Technical writing and documentation
+
+**Best for**:
+
+- Writing documentation
+- Creating tutorials
+- Explaining concepts
+
+**Example**:
+
+```bash
+automatosx run writer "Write API documentation for the User authentication module"
+```
+
+## Available Abilities
+
+### Code-Related
+
+- **code-generation.md**: Generate new code from requirements
+- **code-review.md**: Review code for quality and issues
+- **refactoring.md**: Improve existing code structure
+- **debugging.md**: Debug and fix code issues
+- **testing.md**: Write and improve tests
+
+### Analysis
+
+- **error-analysis.md**: Analyze error messages and logs
+- **performance-analysis.md**: Identify performance bottlenecks
+- **security-audit.md**: Check for security vulnerabilities
+
+### Documentation
+
+- **documentation.md**: Write technical documentation
+- **technical-writing.md**: Create technical content
+- **content-creation.md**: Generate articles and guides
+
+### Problem Solving
+
+- **problem-solving.md**: Break down and solve problems
+- **task-planning.md**: Plan and organize tasks
+- **troubleshooting.md**: Diagnose and fix issues
+- **best-practices.md**: Apply industry best practices
+
+## Usage Patterns
+
+### Pattern 1: Interactive Development
+
+```bash
+# Start with planning
+automatosx chat backend
+> "I need to build a REST API for user management"
+
+# Generate code
+automatosx run backend "Create Express.js routes for user CRUD operations"
+
+# Review code
+automatosx run quality "Review the user routes I just created"
+
+# Debug issues
+automatosx run debugger "The POST /users endpoint returns 500 error"
+```
+
+### Pattern 2: Code Review Workflow
+
+```bash
+# Review specific file
+automatosx run quality "Review src/api/users.ts"
+
+# Review entire directory
+automatosx run quality "Review all files in src/api/"
+
+# Security audit
+automatosx run quality "Check src/api/auth.ts for security issues" \
+  --abilities security-audit
+```
+
+### Pattern 3: Documentation Generation
+
+```bash
+# Generate README
+automatosx run writer "Create a README.md for this project"
+
+# API documentation
+automatosx run writer "Document all API endpoints in src/routes/"
+
+# Code comments
+automatosx run backend "Add JSDoc comments to src/utils/helpers.ts"
+```
+
+### Pattern 4: Learning and Exploration
+
+```bash
+# Understand codebase
+automatosx chat backend
+> "Explain the architecture of this project"
+
+# Learn specific concepts
+automatosx run backend "How does the authentication flow work?"
+
+# Get examples
+automatosx run backend "Show me examples of using the memory system"
+```
+
+## Creating Custom Agents
+
+### Step 1: Create Profile
+
+```yaml
+# .automatosx/agents/my-agent.yaml
+name: my-agent
+description: Custom agent for specific tasks
+model: claude-3-sonnet-20240229
+temperature: 0.7
+maxTokens: 4096
+timeout: 60000
+
+abilities:
+  - code-generation
+  - debugging
+  - best-practices
+
+systemPrompt: |
+  You are a specialized assistant for [your specific domain].
+
+  Your key responsibilities:
+  1. [Responsibility 1]
+  2. [Responsibility 2]
+  3. [Responsibility 3]
+
+  Guidelines:
+  - Follow [specific style guide]
+  - Prioritize [specific aspect]
+  - Always [specific behavior]
+```
+
+### Step 2: Test Agent
+
+```bash
+automatosx run my-agent "Test prompt"
+```
+
+### Step 3: Iterate
+
+- Test with various prompts
+- Adjust temperature for creativity
+- Add/remove abilities as needed
+- Refine systemPrompt for better results
+
+## Creating Custom Abilities
+
+### Step 1: Create Ability File
+
+```markdown
+<!-- .automatosx/abilities/my-ability.md -->
+# My Custom Ability
+
+Brief description of what this ability does.
+
+## Purpose
+
+Detailed explanation of when and why to use this ability.
+
+## Usage Guidelines
+
+1. First step
+2. Second step
+3. Third step
+
+## Best Practices
+
+- Best practice 1
+- Best practice 2
+
+## Examples
+
+### Example 1: [Scenario]
+[Detailed example with input and expected output]
+
+### Example 2: [Scenario]
+[Another example]
+
+## Common Pitfalls
+
+- Pitfall 1 and how to avoid it
+- Pitfall 2 and how to avoid it
+```
+
+### Step 2: Reference in Agent
+
+```yaml
+# my-agent.yaml
+abilities:
+  - my-ability
+```
+
+### Step 3: Test
+
+```bash
+automatosx run my-agent "Use my custom ability to..."
+```
+
+## Tips and Best Practices
+
+### Agent Design
+
+1. **Single Responsibility**: Each agent should have a clear, focused purpose
+2. **Descriptive Names**: Use names that clearly indicate the agent's role
+3. **Specific System Prompts**: Provide detailed instructions for consistent behavior
+4. **Appropriate Temperature**:
+   - 0.0-0.3: Deterministic, factual tasks
+   - 0.4-0.7: Balanced creativity and accuracy
+   - 0.8-1.0: Creative, varied outputs
+
+### Ability Design
+
+1. **Clear Purpose**: Each ability should solve a specific problem
+2. **Detailed Examples**: Show concrete usage patterns
+3. **Best Practices**: Include dos and don'ts
+4. **Composable**: Abilities should work well together
+
+### Usage Tips
+
+1. **Start Simple**: Begin with example agents, customize as needed
+2. **Iterate Quickly**: Test agents with real tasks, refine based on results
+3. **Use Memory**: Let agents remember context across sessions
+4. **Combine Abilities**: Mix and match abilities for complex tasks
+5. **Debug Mode**: Use `--debug` flag to see what's happening
+
+## Troubleshooting
+
+### Agent Not Found
+
+```bash
+# List available agents
+automatosx list agents
+
+# Verify agent file exists
+ls .automatosx/agents/
+```
+
+### Abilities Not Working
+
+```bash
+# List available abilities
+automatosx list abilities
+
+# Check agent profile includes the ability
+cat .automatosx/agents/my-agent.yaml
+```
+
+### Unexpected Behavior
+
+1. Check agent's systemPrompt for clarity
+2. Adjust temperature (lower = more focused)
+3. Enable debug mode: `--debug`
+4. Review memory context: `automatosx memory list`
+
+## Real-World Use Cases
+
+See `examples/use-cases/` for complete scenarios:
+
+- Web application development
+- API design and implementation
+- Code migration and refactoring
+- Security audit workflow
+- Documentation generation
+
+## Community Examples
+
+Share your agents and abilities:
+
+1. Fork the repository
+2. Add your examples to this directory
+3. Submit a pull request
+4. Include description and usage instructions
+
+## Resources
+
+- [Main Documentation](../README.md)
+- [Configuration Guide](../docs/configuration.md)
+- [API Reference](../docs/api.md)
+- [FAQ](../FAQ.md)
+- [Troubleshooting](../TROUBLESHOOTING.md)
+
+---
+
+**Need help?** Open an issue at [GitHub Issues](https://github.com/defai-digital/automatosx/issues) - for bugs, questions, or feature requests (use "enhancement" label for wishlist items).

package/examples/abilities/accessibility.md

@@ -0,0 +1,115 @@
+# Accessibility (A11y)
+
+Build inclusive web applications following WCAG guidelines.
+
+## Core Principles (WCAG)
+
+1. **Perceivable** - Users must be able to perceive the information
+2. **Operable** - Users must be able to operate the interface
+3. **Understandable** - Users must understand the information and interface
+4. **Robust** - Content must work with current and future technologies
+
+## Essential Practices
+
+### 1. Semantic HTML
+- Use proper HTML elements (button, nav, header, main, footer, article)
+- Avoid div/span for interactive elements
+- Use headings (h1-h6) in logical order
+- Use lists (ul, ol) for groups of items
+- Use form elements with proper labels
+
+### 2. ARIA Attributes
+- Use aria-label for icons and buttons without text
+- Use aria-describedby for additional context
+- Use aria-live for dynamic content updates
+- Use aria-expanded for collapsible sections
+- Use aria-hidden="true" for decorative elements
+- Don't over-use ARIA (semantic HTML is better)
+
+### 3. Keyboard Navigation
+- All interactive elements must be keyboard accessible (Tab, Enter, Space)
+- Provide visible focus indicators (:focus-visible)
+- Implement skip links for main content
+- Use tabindex="0" to add elements to tab order
+- Use tabindex="-1" to remove from tab order (programmatically focusable)
+- Never use positive tabindex values
+
+### 4. Color and Contrast
+- Minimum contrast ratio 4.5:1 for normal text
+- Minimum contrast ratio 3:1 for large text (18pt+)
+- Don't rely on color alone to convey information
+- Provide text alternatives for color-coded information
+- Test with color blindness simulators
+
+### 5. Forms
+- Use <label> for every form input
+- Provide clear error messages
+- Use aria-invalid and aria-describedby for errors
+- Group related inputs with fieldset/legend
+- Mark required fields clearly (aria-required="true")
+- Provide autocomplete attributes where appropriate
+
+### 6. Images and Media
+- Provide alt text for all images
+- Use empty alt="" for decorative images
+- Provide captions for videos
+- Provide transcripts for audio content
+- Don't use images of text (use real text)
+
+### 7. Focus Management
+- Manage focus for modals (trap focus, restore on close)
+- Focus first interactive element when opening dialogs
+- Provide focus indicators for all interactive elements
+- Use :focus-visible to show focus only for keyboard users
+- Announce route changes for screen readers
+
+### 8. Screen Reader Support
+- Use live regions (aria-live) for dynamic updates
+- Provide meaningful page titles
+- Use aria-label when visual label isn't enough
+- Test with screen readers (NVDA, JAWS, VoiceOver)
+- Announce loading states and errors
+
+## Common Patterns
+
+### Modal Dialogs
+- Trap focus within modal
+- Close on Escape key
+- Return focus to trigger element on close
+- Use role="dialog" and aria-modal="true"
+- Provide accessible close button
+
+### Dropdown Menus
+- Use aria-expanded to indicate state
+- Navigate with arrow keys
+- Close on Escape
+- Close on click outside
+- Focus first item when opened
+
+### Form Validation
+- Associate errors with fields (aria-describedby)
+- Mark invalid fields (aria-invalid="true")
+- Announce errors to screen readers
+- Provide clear, specific error messages
+- Don't rely on color alone
+
+## Testing Tools
+
+- axe DevTools (Chrome extension)
+- Lighthouse accessibility audit
+- WAVE (Web Accessibility Evaluation Tool)
+- Keyboard navigation testing (Tab, Shift+Tab, Enter, Space, Esc, Arrow keys)
+- Screen reader testing (VoiceOver on Mac, NVDA/JAWS on Windows)
+
+## Quick Checklist
+
+- [ ] All interactive elements keyboard accessible
+- [ ] Proper semantic HTML used
+- [ ] All images have appropriate alt text
+- [ ] Color contrast meets WCAG AA (4.5:1)
+- [ ] Forms have proper labels and error handling
+- [ ] Focus management for modals/dialogs
+- [ ] ARIA attributes used correctly (when needed)
+- [ ] Tested with keyboard navigation
+- [ ] Tested with screen reader
+- [ ] No accessibility errors in axe DevTools

package/examples/abilities/api-design.md

@@ -0,0 +1,159 @@
+# API Design
+
+## Overview
+Design RESTful, GraphQL, and other API architectures following industry best practices, focusing on developer experience, performance, and maintainability.
+
+## Core Principles
+
+### 1. RESTful Design
+- Resource-oriented URL structure
+- Proper HTTP method usage (GET, POST, PUT, PATCH, DELETE)
+- Stateless communication
+- HATEOAS when appropriate
+
+### 2. GraphQL Design
+- Schema-first approach
+- Efficient resolver implementation
+- Query complexity analysis
+- Pagination and batching strategies
+
+### 3. API Versioning
+- URL versioning (`/v1/`, `/v2/`)
+- Header versioning (`Accept: application/vnd.api+json; version=1`)
+- Deprecation policies and timelines
+
+### 4. Error Handling
+- Consistent error response structure
+- Meaningful HTTP status codes
+- Detailed error messages for debugging
+- Error code cataloging
+
+### 5. Authentication & Authorization
+- Token-based authentication (JWT, OAuth 2.0)
+- API key management
+- Rate limiting per user/client
+- Scope-based permissions
+
+## Design Patterns
+
+### Request/Response Patterns
+```
+GET /api/v1/resources/{id}
+→ 200 OK with resource
+→ 404 Not Found
+→ 401 Unauthorized
+
+POST /api/v1/resources
+→ 201 Created with Location header
+→ 400 Bad Request with validation errors
+→ 409 Conflict for duplicates
+```
+
+### Pagination
+- Cursor-based for large datasets
+- Offset/limit for smaller datasets
+- Include metadata (total count, has_next, cursors)
+
+### Filtering & Sorting
+- Query parameters: `?filter[status]=active&sort=-created_at`
+- Standardized field names
+- Documentation of supported operators
+
+## Documentation Standards
+
+### OpenAPI/Swagger
+- Complete endpoint descriptions
+- Request/response schemas
+- Example payloads
+- Authentication requirements
+
+### API Documentation Must Include
+- Quick start guide
+- Authentication flow
+- Rate limits
+- Error codes reference
+- Changelog with version history
+
+## Performance Considerations
+
+### 1. Response Optimization
+- Minimal payload size
+- Field selection (`?fields=id,name`)
+- Compression (gzip, brotli)
+- Caching headers (ETag, Cache-Control)
+
+### 2. Request Optimization
+- Batch endpoints for multiple operations
+- Webhook support for async operations
+- WebSocket for real-time updates
+
+### 3. Monitoring
+- Response time percentiles (p50, p95, p99)
+- Error rates by endpoint
+- Rate limit hit metrics
+- Payload size distribution
+
+## Security Guidelines
+
+### Input Validation
+- Schema validation for all requests
+- Sanitize user input
+- Size limits on payloads
+- Content-type verification
+
+### Rate Limiting
+- Per-endpoint limits
+- User/API key throttling
+- Gradual backoff responses
+- 429 Too Many Requests with Retry-After
+
+### CORS Configuration
+- Explicit origin whitelisting
+- Credential handling
+- Preflight request caching
+
+## Contract Testing
+
+### Schema Validation
+- Request validation against OpenAPI spec
+- Response validation
+- Breaking change detection
+
+### Backward Compatibility
+- Additive changes only (new fields)
+- Deprecation warnings before removal
+- Versioning for breaking changes
+
+## Tools & Technologies
+
+### Design
+- OpenAPI 3.x specification
+- Postman/Insomnia for testing
+- GraphQL Playground
+- API Blueprint
+
+### Testing
+- Contract testing (Pact)
+- Load testing (k6, JMeter)
+- Security scanning (OWASP ZAP)
+
+### Documentation
+- Swagger UI
+- ReDoc
+- GraphQL Voyager
+- Stoplight Studio
+
+## Checklist for New API
+
+- [ ] OpenAPI spec created and validated
+- [ ] Authentication/authorization implemented
+- [ ] Rate limiting configured
+- [ ] Error responses standardized
+- [ ] CORS properly configured
+- [ ] Input validation on all endpoints
+- [ ] Response caching strategy defined
+- [ ] API documentation published
+- [ ] Monitoring/alerting set up
+- [ ] Contract tests written
+- [ ] Load testing performed
+- [ ] Security audit completed