@defai.digital/automatosx 5.0.13 → 5.1.2

package/examples/abilities/our-code-review-checklist.md

@@ -0,0 +1,149 @@
+# Our Code Review Checklist - AutomatosX v5
+
+> Code review checklist for AutomatosX team
+
+## Before Submitting PR
+
+### Code Quality
+
+- [ ] **No `any` types** - All types explicit, use `unknown` if truly unknown
+- [ ] **ESM imports** - All imports have `.js` extension
+- [ ] **Function size** - Functions <50 lines, extract helpers if needed
+- [ ] **Naming** - Clear, descriptive names (no abbreviations)
+- [ ] **Comments** - JSDoc for public APIs, inline for complex logic
+
+### Error Handling
+
+- [ ] **Custom errors** - Use AgentValidationError, PathError, etc.
+- [ ] **Error context** - Include relevant context in error messages
+- [ ] **Try-catch blocks** - Catch and re-throw with context
+- [ ] **No silent failures** - All errors logged or thrown
+
+### Security
+
+- [ ] **Path validation** - All file access through PathResolver
+- [ ] **Input sanitization** - User inputs sanitized before use
+- [ ] **Workspace isolation** - Writes only to agent workspace
+- [ ] **File size limits** - Check file sizes to prevent DoS
+- [ ] **No hardcoded secrets** - Use environment variables
+
+### Testing
+
+- [ ] **Tests added** - New features have tests (unit + integration)
+- [ ] **Coverage maintained** - Overall ≥70%, core modules ≥85%
+- [ ] **Tests pass** - All 1,149 tests passing
+- [ ] **Edge cases** - Test edge cases and error scenarios
+
+### Performance
+
+- [ ] **No bottlenecks** - Profile if adding expensive operations
+- [ ] **Lazy loading** - Heavy deps use dynamic import
+- [ ] **Caching** - Use TTLCache for expensive operations
+- [ ] **Bundle size** - Check `dist/index.js` stays <250KB
+
+### Logging
+
+- [ ] **Structured logging** - Use `logger.info/warn/error` with context
+- [ ] **Log levels** - Appropriate log levels (debug/info/warn/error)
+- [ ] **No console.log** - Use logger, not console.log
+
+### Git
+
+- [ ] **Conventional commits** - Format: `type(scope): message`
+- [ ] **Descriptive message** - Clear what and why
+- [ ] **No large files** - No binaries or large files
+- [ ] **No sensitive data** - No API keys, passwords, etc.
+
+## Reviewer Checklist
+
+### Code Review
+
+- [ ] **Logic correctness** - Does the code do what it's supposed to?
+- [ ] **Type safety** - Are all types correct and complete?
+- [ ] **Error handling** - Are errors handled appropriately?
+- [ ] **Security** - No security vulnerabilities introduced?
+
+### Architecture
+
+- [ ] **Import hierarchy** - Follows layer architecture (types → utils → core → agents → cli)
+- [ ] **Module boundaries** - No circular dependencies
+- [ ] **Separation of concerns** - Each module has single responsibility
+
+### Testing
+
+- [ ] **Test quality** - Tests are meaningful and comprehensive
+- [ ] **Test coverage** - Coverage meets targets
+- [ ] **Mock providers** - Tests use AUTOMATOSX_MOCK_PROVIDERS=true
+
+### Documentation
+
+- [ ] **JSDoc complete** - Public APIs have JSDoc
+- [ ] **README updated** - If adding features, update README
+- [ ] **CHANGELOG updated** - Add entry to CHANGELOG.md
+
+### Performance & Size
+
+- [ ] **No new large deps** - Check package.json for new dependencies
+- [ ] **Bundle size** - Run `npm run build` and check dist/index.js size
+- [ ] **Startup time** - CLI startup time reasonable
+
+## Common Patterns
+
+### Type Safety
+
+```typescript
+// ❌ Avoid
+const data: any = loadData();
+
+// ✅ Prefer
+const data: ProfileData = loadProfile(name);
+```
+
+### Error Handling
+
+```typescript
+// ❌ Avoid: Silent failure
+try {
+  await task();
+} catch (e) { }
+
+// ✅ Prefer: Log and re-throw
+try {
+  await task();
+} catch (error) {
+  logger.error('Task failed', {
+    task: taskName,
+    error: (error as Error).message
+  });
+  throw error;
+}
+```
+
+### Security
+
+```typescript
+// ❌ Avoid: Path traversal risk
+const path = join(root, userInput);
+
+// ✅ Prefer: Validated path
+const resolver = new PathResolver({ projectRoot: root });
+const path = await resolver.resolve(userInput);
+```
+
+### Logging
+
+```typescript
+// ❌ Avoid
+console.log('Profile loaded');
+
+// ✅ Prefer
+logger.info('Profile loaded', {
+  name: profileName,
+  path: profilePath
+});
+```
+
+---
+
+**Last Updated:** 2025-10-10
+**For:** AutomatosX v5.0+

package/examples/abilities/our-coding-standards.md

@@ -0,0 +1,270 @@
+# Our Coding Standards - AutomatosX v5
+
+> Project-specific coding standards for AutomatosX
+
+## TypeScript Standards
+
+**Strict mode enabled:**
+
+```json
+{
+  "strict": true,
+  "noUncheckedIndexedAccess": true,
+  "noImplicitOverride": true,
+  "noFallthroughCasesInSwitch": true
+}
+```
+
+**Type annotations:**
+
+```typescript
+// ✅ Good: Explicit types for public APIs
+export function loadProfile(name: string): Promise<AgentProfile> { }
+
+// ❌ Bad: Any types
+function process(data: any) { }  // Never use any!
+```
+
+**Error handling:**
+
+```typescript
+// ✅ Good: Typed errors from utils/errors.ts
+import { AgentValidationError, PathError } from '../utils/errors.js';
+
+if (!profile.name) {
+  throw new AgentValidationError('Missing required field: name');
+}
+
+// Include error context
+try {
+  await executeTask();
+} catch (error) {
+  logger.error('Task execution failed', {
+    task: taskName,
+    agent: agentName,
+    error: (error as Error).message
+  });
+  throw error;
+}
+```
+
+**Module system (ESM with .js extensions):**
+
+```typescript
+// ✅ Good: .js extension in imports (required for ESM)
+import { PathResolver } from '../core/path-resolver.js';
+import type { AgentProfile } from '../types/agent.js';
+
+// ❌ Bad: No extension
+import { PathResolver } from '../core/path-resolver';
+```
+
+## Code Quality Standards
+
+**Function size (<50 lines):**
+
+```typescript
+// ✅ Good: Small, focused function
+private buildPrompt(context: ExecutionContext): string {
+  let prompt = '';
+  if (context.abilities) {
+    prompt += `# Your Abilities\n\n${context.abilities}\n\n`;
+  }
+  if (context.agent.stages) {
+    prompt += this.buildStagesSection(context.agent.stages);
+  }
+  prompt += `# Task\n\n${context.task}`;
+  return prompt;
+}
+```
+
+**Naming conventions:**
+
+```typescript
+// ✅ Good: Descriptive names
+const profilePath = join(profilesDir, `${name}.yaml`);
+async function resolveAgentName(input: string): Promise<string> { }
+
+// ✅ Good: PascalCase for classes
+export class PathResolver { }
+export class MemoryManager { }
+
+// ❌ Bad: Abbreviations or vague names
+const p = join(dir, `${n}.yaml`);
+export class PM { }
+```
+
+**JSDoc for public APIs:**
+
+```typescript
+/**
+ * Load agent profile from YAML file
+ *
+ * @param name - Agent name (e.g., "backend", "quality")
+ * @returns Validated AgentProfile
+ * @throws AgentNotFoundError if profile doesn't exist
+ * @throws AgentValidationError if profile is invalid
+ */
+async loadProfile(name: string): Promise<AgentProfile> { }
+```
+
+## Security Standards
+
+**Always use PathResolver:**
+
+```typescript
+// ✅ Good: Use PathResolver for all file access
+import { PathResolver } from '../core/path-resolver.js';
+
+const resolver = new PathResolver({ projectRoot });
+const safePath = await resolver.resolve(userInput);
+
+// ❌ Bad: Direct path manipulation
+const path = join(projectRoot, userInput);  // Unsafe!
+```
+
+**Input sanitization:**
+
+```typescript
+// ✅ Good: Sanitize before using in file system
+const agentDirName = agentName
+  .replace(/[^a-zA-Z0-9-]/g, '-')
+  .toLowerCase();
+
+// ✅ Good: File size limits to prevent DoS
+if (content.length > 100 * 1024) {
+  throw new AgentValidationError('Profile file too large (max 100KB)');
+}
+```
+
+**Restrictive permissions:**
+
+```typescript
+// ✅ Good: Restrict workspace permissions (Unix)
+if (process.platform !== 'win32') {
+  await chmod(agentWorkspace, 0o700);  // Owner only
+}
+```
+
+## Testing Standards
+
+**Structure with Vitest:**
+
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest';
+
+describe('PathResolver', () => {
+  let resolver: PathResolver;
+
+  beforeEach(() => {
+    resolver = new PathResolver({ projectRoot: '/test' });
+  });
+
+  it('should resolve relative paths', async () => {
+    const result = await resolver.resolve('./file.txt');
+    expect(result).toBe('/test/file.txt');
+  });
+
+  it('should reject path traversal', async () => {
+    await expect(
+      resolver.resolve('../../../etc/passwd')
+    ).rejects.toThrow(PathError);
+  });
+});
+```
+
+**Coverage targets:**
+
+- Overall: 70%+ (currently 85%)
+- Core modules: 85%+
+- CLI commands: 70%+
+- Utils: 90%+
+
+## Logging Standards
+
+**Use structured logging:**
+
+```typescript
+import { logger } from '../utils/logger.js';
+
+// ✅ Good: Structured logging with context
+logger.info('Profile loaded', {
+  name: profileName,
+  path: profilePath
+});
+
+logger.error('Execution failed', {
+  agent: agentName,
+  task: taskSummary,
+  error: (error as Error).message
+});
+
+// ❌ Bad: Console.log
+console.log('Profile loaded');
+```
+
+**Log levels:**
+
+- **debug:** Development details
+- **info:** Normal operations
+- **warn:** Recoverable issues
+- **error:** Failures requiring attention
+
+## Performance Standards
+
+**Lazy loading:**
+
+```typescript
+// ✅ Good: Lazy load heavy dependencies
+async executeTask() {
+  const { spawn } = await import('child_process');
+  // ...
+}
+```
+
+**Caching:**
+
+```typescript
+// ✅ Good: Cache profiles with TTL
+this.cache = new TTLCache<AgentProfile>({
+  maxEntries: 20,
+  ttl: 300000,        // 5 minutes
+  cleanupInterval: 60000
+});
+```
+
+**Bundle size target:** <250KB (currently 381KB)
+
+## Git Commit Standards
+
+**Conventional Commits format:** `type(scope): message`
+
+```bash
+# Types
+feat(agents): add stage injection to executor
+fix(memory): resolve vector search timeout
+docs(readme): update installation instructions
+test(router): add retry logic tests
+refactor(cli): simplify command parsing
+perf(cache): optimize TTL cleanup interval
+```
+
+**Commit message structure:**
+
+```bash
+# ✅ Good: Clear, specific
+feat(stages): inject workflow stages into prompt
+
+- Add Stage and Personality interfaces to types
+- Update ProfileLoader to parse stages from YAML
+- Modify Executor to include stages in prompt
+
+# ❌ Bad: Vague
+fix: bug fix
+update: changes
+```
+
+---
+
+**Last Updated:** 2025-10-10
+**For:** AutomatosX v5.0+

package/examples/abilities/our-project-structure.md

@@ -0,0 +1,175 @@
+# Our Project Structure - AutomatosX v5
+
+> AutomatosX project organization and file structure conventions
+
+## Directory Structure
+
+```
+automatosx/
+├── src/                      # TypeScript source code
+│   ├── core/                 # Router, PathResolver, MemoryManager, SessionManager
+│   ├── agents/               # ProfileLoader, AbilitiesManager, ContextManager, Executor
+│   ├── providers/            # Claude, Gemini, OpenAI implementations
+│   ├── cli/                  # CLI entry point and commands/
+│   ├── types/                # TypeScript type definitions
+│   └── utils/                # Logger, errors, formatters
+│
+├── tests/                    # 1,149 tests (100% pass)
+│   ├── unit/                 # Core modules, utilities
+│   ├── integration/          # CLI command flows
+│   ├── e2e/                  # Complete workflows
+│   └── fixtures/             # Test helpers, mock providers
+│
+├── examples/
+│   ├── agents/               # Example agent profiles (YAML)
+│   ├── abilities/            # Example abilities (Markdown)
+│   └── templates/            # Agent templates (v5.0.0+)
+│
+├── dist/                     # Build output (381KB, gitignored)
+│   ├── index.js              # Bundled CLI (ESM)
+│   ├── index.js.map
+│   └── index.d.ts
+│
+├── .automatosx/              # User project directory (created by init)
+│   ├── config.json           # User configuration
+│   ├── agents/               # User's custom agents
+│   ├── abilities/            # User's custom abilities
+│   ├── memory/               # SQLite database (memory.db)
+│   ├── sessions/             # Session persistence
+│   └── workspaces/           # Agent workspaces (isolated)
+│
+└── tmp/                      # Temporary files (gitignored)
+```
+
+## Module Import Hierarchy
+
+**Dependency flow (imports only from lower layers):**
+
+```
+Layer 1: types/              → No dependencies
+Layer 2: utils/              → types/
+Layer 3: core/               → types/, utils/
+Layer 4: providers/          → types/, core/
+Layer 5: agents/             → types/, utils/, core/
+Layer 6: cli/                → All of the above
+```
+
+**Rule:** Higher layers can import from lower layers, never vice versa.
+
+## File Naming Conventions
+
+**TypeScript files:** `kebab-case.ts`
+
+```
+✅ path-resolver.ts, memory-manager.ts, claude-provider.ts
+❌ PathResolver.ts, path_resolver.ts, pathResolver.ts
+```
+
+**Test files:** `{module-name}.test.ts`
+
+```
+✅ path-resolver.test.ts, memory-manager.test.ts
+❌ path-resolver.spec.ts, test-path-resolver.ts
+```
+
+**Type files:** `{concept}.ts` (no -types suffix)
+
+```
+✅ types/agent.ts, types/provider.ts
+❌ types/agent-types.ts, types/AgentTypes.ts
+```
+
+**Configuration files:**
+
+- YAML for agents: `examples/agents/backend.yaml`
+- Markdown for abilities: `examples/abilities/code-generation.md`
+- JSON for config: `.automatosx/config.json`
+
+## Import Patterns
+
+**ESM imports (always use .js extension):**
+
+```typescript
+// ✅ Good: Full path with .js
+import { PathResolver } from '../core/path-resolver.js';
+import type { AgentProfile } from '../types/agent.js';
+
+// ❌ Bad: Missing .js extension
+import { PathResolver } from '../core/path-resolver';
+```
+
+**Type-only imports:**
+
+```typescript
+// ✅ Good: type-only imports (better tree-shaking)
+import type { AgentProfile } from '../types/agent.js';
+import type { Provider } from '../types/provider.js';
+```
+
+## Configuration Hierarchy
+
+**Priority order:**
+
+1. `.automatosx/config.json` (project-specific, created by `ax init`)
+2. `automatosx.config.json` (project root, manually created)
+3. `~/.automatosx/config.json` (user global)
+4. `DEFAULT_CONFIG` (defaults in `src/types/config.ts`)
+
+**Agent profiles search order:**
+
+1. `.automatosx/agents/{name}.yaml` (user custom)
+2. `examples/agents/{name}.yaml` (built-in)
+
+**Abilities search order:**
+
+1. `.automatosx/abilities/{name}.md` (user custom)
+2. `examples/abilities/{name}.md` (built-in)
+
+## Build Output
+
+**Location:** `dist/`
+
+- `index.js` - Bundled CLI (ESM, 381KB)
+- `index.js.map` - Source map
+- `index.d.ts` - Type definitions
+
+**Bundle target:** ESM, Node 20+, <250KB target
+
+## Workspace Structure
+
+**Agent workspaces:** `.automatosx/workspaces/{agent-name}/`
+
+- Isolated workspace for file operations
+- Permissions: 700 (owner only on Unix)
+
+**Memory storage:** `.automatosx/memory/memory.db`
+
+- SQLite database with FTS5 full-text search
+- < 1ms search performance
+
+**Session storage:** `.automatosx/sessions/sessions.json`
+
+- JSON-based persistence
+- 100ms debounced saves
+- Automatic cleanup (7+ days old)
+
+## Security Boundaries
+
+**Allowed reads:**
+
+- `{projectRoot}/**/*` (validated by PathResolver)
+
+**Allowed writes:**
+
+- `.automatosx/workspaces/{agent-name}/**/*` only
+
+**Forbidden:**
+
+- Path traversal (`../../../etc/passwd`)
+- Symbolic links outside project
+- Writing outside workspace
+
+---
+
+**Last Updated:** 2025-10-10
+**For:** AutomatosX v5.0+

package/examples/abilities/performance-analysis.md

@@ -0,0 +1,56 @@
+# Performance Analysis Ability
+
+Identify and fix performance bottlenecks.
+
+## Performance Metrics
+
+1. **Response Time**
+   - Target: <100ms for API calls
+   - Target: <1s for page loads
+   - Measure: p50, p95, p99 latencies
+
+2. **Throughput**
+   - Requests per second
+   - Concurrent users supported
+   - Resource utilization
+
+3. **Resource Usage**
+   - CPU: Target <70% average
+   - Memory: No leaks, stable usage
+   - Disk I/O: Minimize random access
+   - Network: Bandwidth optimization
+
+## Analysis Process
+
+1. **Measure** (establish baseline)
+   - Use profilers (Chrome DevTools, Python cProfile)
+   - Monitor production metrics
+   - Identify slow operations
+
+2. **Analyze** (find bottlenecks)
+   - Check database queries (N+1 problem)
+   - Review algorithm complexity
+   - Identify network round trips
+   - Check memory allocations
+
+3. **Optimize** (targeted improvements)
+   - Add caching (Redis, CDN)
+   - Optimize database queries (indexes, query optimization)
+   - Use async/parallel processing
+   - Reduce payload sizes
+
+4. **Verify** (measure improvements)
+   - Re-run benchmarks
+   - Compare before/after
+   - Check for regressions
+   - Monitor in production
+
+## Common Performance Issues
+
+- N+1 query problem (ORM)
+- Missing database indexes
+- Synchronous I/O blocking
+- Large payload sizes
+- No caching strategy
+- Memory leaks
+- Inefficient algorithms (O(n²) when O(n) possible)