@defai.digital/automatosx 5.0.13 → 5.1.2

package/examples/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

package/examples/abilities/etl-pipelines.md

@@ -0,0 +1,44 @@
+# ETL Pipelines
+
+Build robust Extract, Transform, Load pipelines for data integration. Handle incremental loading, error recovery, and monitoring.
+
+## Do's ✅
+
+```python
+# ✅ Good: Incremental loading
+last_sync = get_last_sync_timestamp()
+new_data = source.extract(where=f"updated_at > '{last_sync}'")
+transformed = transform(new_data)
+warehouse.upsert(transformed, key_columns=['id'])
+
+# ✅ Good: Idempotent operations
+warehouse.upsert(data, key_columns=['id'], update_columns=['name', 'updated_at'])
+
+# ✅ Good: Error handling with retry
+try:
+    data = extract_from_api()
+    load_to_warehouse(transform(data))
+except APIError as e:
+    log_error(e)
+    save_failed_batch(data)  # Retry later
+```
+
+## Don'ts ❌
+
+```python
+# ❌ Bad: Full table reload every time
+data = source.extract_all()  # Millions of rows!
+warehouse.truncate()
+warehouse.insert(data)
+
+# ❌ Bad: No schema validation
+for row in data:
+    warehouse.insert(row['id'], row['name'])  # What if fields missing?
+```
+
+## Best Practices
+- Use orchestration tools (Airflow, Prefect, Dagster)
+- Implement data quality checks
+- Monitor pipeline SLAs
+- Version control transformation logic
+- Document data lineage

package/examples/abilities/feasibility-study.md

@@ -0,0 +1,20 @@
+Goal
+- Assess technical, operational, and economic feasibility with timelines and costs.
+
+How to do it
+- Define scope, constraints, and success criteria.
+- Technical: stack fit, complexity, integration risks.
+- Operational: processes, skills, SLAs, compliance.
+- Economic: cost drivers (build/run), ROI windows, sensitivities.
+
+Do
+- Provide a small matrix (dimension × 1–5 score) and rationale.
+- Add timeline bands (e.g., 2–4 weeks, 1–2 quarters) with key assumptions.
+
+Don’t
+- Don’t present estimates without assumptions.
+- Don’t ignore maintenance/operational costs.
+
+Output
+- A feasibility summary with scores, assumptions, timeline bands, and go/no‑go recommendation.
+

package/examples/abilities/general-assistance.md

@@ -0,0 +1,26 @@
+# General Assistance
+
+## Description
+
+Provide helpful assistance for general tasks and inquiries.
+
+## Capabilities
+
+- Answer questions on various topics
+- Provide explanations and clarifications
+- Offer suggestions and recommendations
+- Break down complex problems into manageable steps
+
+## Usage Guidelines
+
+- Be clear and concise in responses
+- Ask clarifying questions when needed
+- Provide examples to illustrate concepts
+- Adapt communication style to user needs
+
+## Best Practices
+
+- Listen carefully to user requests
+- Provide accurate and reliable information
+- Be patient and understanding
+- Follow up to ensure user satisfaction

package/examples/abilities/idea-evaluation.md

@@ -0,0 +1,21 @@
+Goal
+- Evaluate ideas against objectives, constraints, user value, and alternatives.
+
+How to do it
+- Clarify the objective, target users, and measurable outcomes.
+- Identify assumptions; label each as validated, unvalidated, or unknown.
+- Compare at least two alternatives; state trade‑offs.
+- Use simple scoring (e.g., 1–5) for value, cost, risk, and time.
+
+Do
+- Show a short decision table with criteria and scores.
+- Call out unknowns and how to validate them.
+- Provide an executive summary before details.
+
+Don’t
+- Don’t assume feasibility without evidence.
+- Don’t hide uncertainties; surface them with next steps.
+
+Output
+- A concise evaluation with assumptions, alternatives, scores, and a clear recommendation.
+

package/examples/abilities/infra-as-code.md

@@ -0,0 +1,57 @@
+# Infrastructure as Code
+
+Define and manage infrastructure through code using Terraform, Pulumi, or AWS CDK. Enable version control, reproducibility, and automation.
+
+## Do's ✅
+
+```hcl
+# ✅ Good: Modular Terraform
+resource "aws_vpc" "main" {
+  cidr_block = var.vpc_cidr
+  enable_dns_hostnames = true
+
+  tags = {
+    Name = "${var.project}-vpc"
+    Environment = var.environment
+  }
+}
+
+# ✅ Good: Remote state with locking
+terraform {
+  backend "s3" {
+    bucket         = "terraform-state"
+    key            = "prod/terraform.tfstate"
+    region         = "us-east-1"
+    encrypt        = true
+    dynamodb_table = "terraform-locks"
+  }
+}
+
+# ✅ Good: Use modules
+module "vpc" {
+  source  = "terraform-aws-modules/vpc/aws"
+  version = "~> 3.0"
+  name    = "${var.project}-vpc"
+  cidr    = var.vpc_cidr
+}
+```
+
+## Don'ts ❌
+
+```hcl
+# ❌ Bad: Hardcoded values
+resource "aws_instance" "web" {
+  ami           = "ami-0c55b159cbfafe1f0"  # Region-specific!
+  subnet_id     = "subnet-12345"  # Hardcoded
+}
+
+# ❌ Bad: Manual changes
+# Never modify infrastructure manually in console
+```
+
+## Best Practices
+- Use workspaces for environments (dev/staging/prod)
+- Enable state locking
+- Always run `terraform plan` before apply
+- Version pin modules and providers
+- Implement automated testing (Terratest)

package/examples/abilities/job-orchestration.md

@@ -0,0 +1,44 @@
+# Job Orchestration
+
+Schedule and orchestrate data jobs, pipelines, and workflows. Manage dependencies, retries, and monitoring using orchestration tools.
+
+## Do's ✅
+
+```python
+# ✅ Good: Clear task dependencies (Airflow)
+from airflow import DAG
+from airflow.operators.python import PythonOperator
+
+with DAG('user_pipeline', schedule='0 2 * * *') as dag:
+    extract = PythonOperator(task_id='extract', python_callable=extract_users)
+    transform = PythonOperator(task_id='transform', python_callable=transform_users)
+    load = PythonOperator(task_id='load', python_callable=load_users)
+
+    extract >> transform >> load
+
+# ✅ Good: Retry configuration
+PythonOperator(
+    task_id='api_call',
+    python_callable=call_api,
+    retries=3,
+    retry_delay=timedelta(minutes=5),
+    retry_exponential_backoff=True
+)
+```
+
+## Don'ts ❌
+
+```python
+# ❌ Bad: Complex dependencies
+task1 >> [task2, task3, task4] >> task5 >> [task6, task7] >> task8
+
+# ✅ Good: Logical groupings
+extract_tasks >> transform_task >> load_tasks
+```
+
+## Best Practices
+- Use task groups for related operations
+- Implement SLA monitoring
+- Configure alerting for failures
+- Version control DAG definitions
+- Use dynamic task generation when appropriate

package/examples/abilities/literature-review.md

@@ -0,0 +1,19 @@
+Goal
+- Summarize prior work and credible sources; extract insights and gaps.
+
+How to do it
+- Collect 5–10 relevant sources; prefer primary research or official docs.
+- For each source: key claim, method, limits, and applicability.
+- Synthesize themes; identify contradictions and open questions.
+
+Do
+- Provide inline citations (Author/Org, Year or URL).
+- Group findings by theme; call out where evidence is weak.
+
+Don’t
+- Don’t copy long quotes; summarize.
+- Don’t mix citation and commentary without clearly separating them.
+
+Output
+- A thematic summary with citations and a short “Implications for this project” section.
+

package/examples/abilities/logical-analysis.md

@@ -0,0 +1,21 @@
+Goal
+- Analyze arguments for validity, completeness, and hidden assumptions.
+
+How to do it
+- List premises and assumptions explicitly.
+- Check inference steps; note logical fallacies or gaps.
+- Consider counter‑examples and edge cases.
+- Separate facts (with citations) from opinions (qualified language).
+
+Do
+- Use bullet points for premises → conclusion.
+- Mark each step as sound/unsound with a brief note.
+- Provide a short “What would change my conclusion?” section.
+
+Don’t
+- Don’t conflate correlation with causation.
+- Don’t bury key assumptions.
+
+Output
+- A compact reasoning audit: premises, inferences, counter‑points, and a confidence rating.
+

package/examples/abilities/longform-report.md

@@ -0,0 +1,25 @@
+Goal
+- Produce a structured, long‑form report suitable for stakeholders.
+
+Structure
+- Title, Author, Date
+- Executive Summary (bullets)
+- Background & Objectives
+- Methodology (how you reasoned / sources)
+- Findings (thematic)
+- Analysis (logic, feasibility, risks)
+- Options & Recommendations (w/ criteria)
+- Citations & Appendices
+
+Do
+- Use clear headings, short paragraphs, and lists.
+- Call out assumptions and uncertainties.
+- Add tables where helpful (scores, risks, timelines).
+
+Don’t
+- Don’t bury the lede—start with the summary.
+- Don’t omit sources when making claims.
+
+Output
+- A polished document following the above structure; aim for clarity over length.
+

package/examples/abilities/observability.md

@@ -0,0 +1,61 @@
+# Observability
+
+Implement logging, metrics, and tracing to understand system behavior. Monitor health, troubleshoot issues, and optimize performance.
+
+## Three Pillars
+
+### 1. Logs
+```javascript
+// ✅ Good: Structured logging
+logger.info('User login', {
+  user_id: user.id,
+  ip: req.ip,
+  timestamp: new Date().toISOString()
+});
+```
+
+### 2. Metrics
+```javascript
+// ✅ Good: Application metrics (Prometheus)
+const counter = new promClient.Counter({
+  name: 'http_requests_total',
+  help: 'Total HTTP requests',
+  labelNames: ['method', 'route', 'status']
+});
+
+app.use((req, res, next) => {
+  res.on('finish', () => {
+    counter.inc({ method: req.method, route: req.route, status: res.statusCode });
+  });
+});
+```
+
+### 3. Traces
+```javascript
+// ✅ Good: Distributed tracing
+const span = tracer.startSpan('get_user');
+try {
+  const user = await db.getUser(id);
+  res.json(user);
+} finally {
+  span.finish();
+}
+```
+
+## Don'ts ❌
+
+```javascript
+// ❌ Bad: Log sensitive data
+logger.info('Login', { username, password });  // Never!
+
+// ❌ Bad: Unstructured logs
+console.log('User ' + user.id + ' logged in');
+```
+
+## Best Practices
+- Use log levels appropriately
+- Implement correlation IDs for tracing
+- Set up dashboards for key metrics
+- Configure alerts with thresholds
+- Use APM tools (Datadog, New Relic)
+- Implement SLOs and error budgets

package/examples/abilities/our-architecture-decisions.md

@@ -0,0 +1,180 @@
+# Our Architecture Decisions - AutomatosX v5
+
+> Key architectural decisions and rationale for AutomatosX
+
+## ADR-001: SQLite FTS5 Over Milvus
+
+**Decision:** Use SQLite with FTS5 full-text search instead of Milvus
+
+**Rationale:**
+
+- v3.1 used Milvus (340MB bundle, complex setup)
+- SQLite FTS5 offers < 1ms search performance
+- Simple setup, no external services
+
+**Impact:**
+
+- ✅ Bundle: 340MB → 381KB (99.9% reduction)
+- ✅ Fast text search (45ms → <1ms, 45x faster)
+- ✅ No embedding costs (v4.11.0: removed vector search)
+- ❌ Limited to single-node (acceptable for CLI tool)
+
+## ADR-002: ESM Over CommonJS
+
+**Decision:** Use ES Modules (ESM) for entire codebase
+
+**Rationale:**
+
+- Node.js 20+ has first-class ESM support
+- Better tree-shaking and bundle optimization
+- Modern standards compliance
+
+**Impact:**
+
+- ✅ Better tree-shaking (smaller bundle)
+- ✅ Future-proof
+- ⚠️ Requires `.js` in imports (minor inconvenience)
+
+## ADR-003: TypeScript Strict Mode
+
+**Decision:** Enable all strict TypeScript checks
+
+**Configuration:**
+
+```json
+{
+  "strict": true,
+  "noUncheckedIndexedAccess": true,
+  "noImplicitOverride": true,
+  "noFallthroughCasesInSwitch": true
+}
+```
+
+**Impact:**
+
+- ✅ Fewer runtime errors
+- ✅ Better IDE support
+- ✅ Safer refactoring
+- ⚠️ More initial development time (worth it)
+
+## ADR-004: Three-Layer Security Model
+
+**Decision:** Implement path validation, workspace isolation, and input sanitization
+
+**Layers:**
+
+1. **Path Resolution:** All file access through PathResolver
+2. **Workspace Isolation:** Agent-specific workspaces with restricted permissions (700)
+3. **Input Validation:** Sanitize all user inputs
+
+**Impact:**
+
+- ✅ Prevents path traversal attacks
+- ✅ Agent isolation
+- ✅ No privilege escalation
+- ⚠️ Slightly more complex file operations
+
+## ADR-005: Profile + Abilities = Agent
+
+**Decision:** Separate agent profile (YAML) from abilities (Markdown)
+
+**Structure:**
+
+- Profile: YAML with metadata, systemPrompt, abilities references
+- Abilities: Markdown files with domain knowledge
+- Agent = Profile + loaded Abilities
+
+**Impact:**
+
+- ✅ Reusable abilities across agents
+- ✅ Easy to add new knowledge
+- ✅ Clear separation of concerns
+- ✅ User can customize both independently
+
+## ADR-006: Team-Based Configuration (v4.10.0+)
+
+**Decision:** Agents inherit configuration from their team
+
+**4 Built-in Teams:**
+
+- **core:** Quality assurance (primary: claude)
+- **engineering:** Software development (primary: codex)
+- **business:** Product & planning (primary: gemini)
+- **design:** Design & content (primary: gemini)
+
+**Impact:**
+
+- ✅ No configuration duplication
+- ✅ Change provider for entire team at once
+- ✅ Shared abilities automatically included
+- ✅ Centralized orchestration settings
+
+## ADR-007: Lazy Loading for Performance
+
+**Decision:** Defer expensive imports until needed
+
+**Implementation:**
+
+- Heavy modules use dynamic import: `await import('module')`
+- Core modules use static imports
+- LazyLoader utility for caching
+
+**Impact:**
+
+- ✅ Faster CLI startup (~200ms)
+- ✅ Smaller initial memory footprint
+- ✅ Pay for what you use
+
+## ADR-008: Vitest Over Jest
+
+**Decision:** Use Vitest as testing framework
+
+**Rationale:**
+
+- Modern test runner with native ESM support
+- Fast execution with watch mode
+- Compatible with Vite ecosystem
+
+**Impact:**
+
+- ✅ Fast test execution (1,149 tests in ~10s)
+- ✅ Native ESM support (no transform)
+- ✅ Great developer experience
+
+## ADR-009: TTL Cache for Profiles
+
+**Decision:** Cache loaded profiles with 5-minute TTL
+
+**Configuration:**
+
+- TTLCache with 5-minute TTL
+- Max 20 entries (LRU eviction)
+- Cleanup every 60 seconds
+
+**Impact:**
+
+- ✅ Faster repeated executions
+- ✅ Reduced file I/O
+- ✅ Automatic cache invalidation
+- ⚠️ 5-minute delay for profile updates (acceptable)
+
+## ADR-010: Provider Router Pattern
+
+**Decision:** Use Router to abstract provider selection
+
+**Features:**
+
+- Router manages provider selection
+- Retry with exponential backoff
+- Fallback to alternative providers
+
+**Impact:**
+
+- ✅ Provider flexibility
+- ✅ Resilience to provider failures
+- ✅ Easy to add new providers
+
+---
+
+**Last Updated:** 2025-10-10
+**For:** AutomatosX v5.0+