@defai.digital/automatosx 5.6.35 → 5.7.2

package/examples/agents/.automatosx/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 access control, and input sanitization
+
+**Layers:**
+
+1. **Path Resolution:** All file access through PathResolver
+2. **Workspace Access Control:** Shared workspaces with path validation (v5.2+)
+3. **Input Validation:** Sanitize all user inputs
+
+**Impact:**
+
+- ✅ Prevents path traversal attacks
+- ✅ Controlled workspace access with validation
+- ✅ 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+

package/examples/agents/.automatosx/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 or WorkspaceManager
+- [ ] **Input sanitization** - User inputs sanitized before use
+- [ ] **Workspace boundaries** - Writes only to automatosx/PRD or automatosx/tmp (v5.2+)
+- [ ] **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-11
+**For:** AutomatosX v5.2+

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