@defai.digital/automatosx 5.0.1

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

@@ -0,0 +1,217 @@
+# Our Code Review Checklist - AutomatosX v4
+
+> 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. from `utils/errors.ts`
+- [ ] **Error context** - Include relevant context in error messages
+- [ ] **Try-catch blocks** - Catch and re-throw with context where appropriate
+- [ ] **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 coverage ≥70%, core modules ≥85%
+- [ ] **Tests pass** - All 841 tests passing
+- [ ] **Edge cases** - Test edge cases and error scenarios
+
+### Performance
+
+- [ ] **No obvious 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 committed
+- [ ] **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 Issues to Watch For
+
+### Type Safety
+
+❌ **Avoid:**
+
+```typescript
+const data: any = loadData();  // Any type
+function process(x) { }        // Implicit any
+```
+
+✅ **Prefer:**
+
+```typescript
+const data: ProfileData = loadProfile(name);
+function process(x: string): void { }
+```
+
+### Error Handling
+
+❌ **Avoid:**
+
+```typescript
+try {
+  await task();
+} catch (e) {
+  // Silent failure
+}
+```
+
+✅ **Prefer:**
+
+```typescript
+try {
+  await task();
+} catch (error) {
+  logger.error('Task failed', {
+    task: taskName,
+    error: (error as Error).message
+  });
+  throw error;
+}
+```
+
+### Security
+
+❌ **Avoid:**
+
+```typescript
+const path = join(root, userInput);  // Path traversal risk
+```
+
+✅ **Prefer:**
+
+```typescript
+const resolver = new PathResolver({ projectRoot: root });
+const path = await resolver.resolve(userInput);  // Validated
+```
+
+### Logging
+
+❌ **Avoid:**
+
+```typescript
+console.log('Profile loaded');  // No structure
+```
+
+✅ **Prefer:**
+
+```typescript
+logger.info('Profile loaded', {
+  name: profileName,
+  path: profilePath
+});
+```
+
+## Testing Checklist
+
+### Unit Tests
+
+- [ ] Test happy path
+- [ ] Test edge cases
+- [ ] Test error cases
+- [ ] Mock external dependencies
+- [ ] Fast execution (<1s per suite)
+
+### Integration Tests
+
+- [ ] Test CLI command integration
+- [ ] Use temp directory for file operations
+- [ ] Mock providers (AUTOMATOSX_MOCK_PROVIDERS=true)
+- [ ] Clean up after tests
+
+### E2E Tests
+
+- [ ] Test complete user workflows
+- [ ] Use real config, real file system
+- [ ] Mock providers
+- [ ] Verify final state
+
+## Performance Checklist
+
+- [ ] **Lazy load** - Heavy modules use `await import()`
+- [ ] **Cache** - Expensive operations cached with TTL
+- [ ] **Batch** - Batch file operations where possible
+- [ ] **Async** - Use async/await for I/O operations
+- [ ] **Profile** - Profile if performance-critical code
+
+## Security Checklist
+
+- [ ] **Path traversal** - No `../` in paths without validation
+- [ ] **Input validation** - All user inputs validated/sanitized
+- [ ] **File permissions** - Workspaces have restrictive permissions (700)
+- [ ] **Size limits** - File size limits to prevent DoS
+- [ ] **Safe YAML** - Use safe YAML parsing (no unsafe schemas)
+
+## Documentation Checklist
+
+- [ ] **JSDoc** - Public functions have JSDoc
+- [ ] **Comments** - Complex logic explained
+- [ ] **Examples** - Usage examples for complex features
+- [ ] **README** - Updated if adding user-facing features
+- [ ] **CHANGELOG** - Entry added for changes
+
+---
+
+**Last Updated:** 2025-10-07
+**For:** AutomatosX v4.0+

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

@@ -0,0 +1,389 @@
+# Our Coding Standards - AutomatosX v4
+
+> Project-specific coding standards for AutomatosX
+
+## TypeScript Standards
+
+### Type Safety (Strict Mode)
+
+**Always use strict TypeScript:**
+
+```typescript
+// tsconfig.json enforces:
+// - strict: true
+// - noUncheckedIndexedAccess: true
+// - noImplicitOverride: true
+// - noFallthroughCasesInSwitch: true
+```
+
+**Type annotations:**
+
+```typescript
+// ✅ Good: Explicit types for public APIs
+export function loadProfile(name: string): Promise<AgentProfile> {
+  // ...
+}
+
+// ✅ Good: Type parameters
+export class TTLCache<T> {
+  get(key: string): T | undefined { }
+}
+
+// ❌ Bad: Any types
+function process(data: any) { } // Never use any!
+```
+
+### Error Handling
+
+**Use custom error classes:**
+
+```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');
+}
+
+if (path.includes('..')) {
+  throw PathError.traversal(path);
+}
+
+// ❌ Bad: Generic Error
+throw new Error('Something went wrong'); // Too vague
+```
+
+**Error context:**
+
+```typescript
+// ✅ Good: Include 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'; // Won't work
+```
+
+### File Organization
+
+**Directory structure:**
+
+```
+src/
+├── core/           # Core modules (Router, PathResolver, MemoryManager)
+├── agents/         # Agent system (ProfileLoader, AbilitiesManager, ContextManager)
+├── providers/      # Provider implementations (Claude, Gemini, OpenAI)
+├── cli/            # CLI commands
+├── types/          # TypeScript type definitions
+└── utils/          # Utilities (logger, errors, formatters)
+```
+
+**File naming:**
+
+- Use kebab-case: `path-resolver.ts`, `memory-manager.ts`
+- Types: `agent.ts`, `provider.ts` (no -types suffix)
+- Tests: `path-resolver.test.ts` (co-located with source)
+
+## Code Quality Standards
+
+### Function Size
+
+**Keep functions small (<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;
+}
+
+// Break down large functions into smaller helpers
+private buildStagesSection(stages: Stage[]): string {
+  // ...
+}
+```
+
+### Naming Conventions
+
+**Variables and functions:**
+
+```typescript
+// ✅ Good: Descriptive names
+const profilePath = join(profilesDir, `${name}.yaml`);
+async function resolveAgentName(input: string): Promise<string> { }
+
+// ❌ Bad: Vague names
+const p = join(dir, `${n}.yaml`);
+async function resolve(x: string): Promise<string> { }
+```
+
+**Classes:**
+
+```typescript
+// ✅ Good: PascalCase, descriptive
+export class PathResolver { }
+export class MemoryManager { }
+
+// ❌ Bad: Abbreviations
+export class PathRes { }  // Too short
+export class PM { }      // Unclear
+```
+
+### Comments and Documentation
+
+**JSDoc for public APIs:**
+
+```typescript
+/**
+ * Load agent profile from YAML file
+ *
+ * @param name - Agent name (e.g., "coder", "reviewer")
+ * @returns Validated AgentProfile
+ * @throws AgentNotFoundError if profile doesn't exist
+ * @throws AgentValidationError if profile is invalid
+ */
+async loadProfile(name: string): Promise<AgentProfile> {
+  // ...
+}
+```
+
+**Inline comments for complex logic:**
+
+```typescript
+// Security: Validate path to prevent traversal attacks
+const resolvedPath = resolve(userPath);
+if (!resolvedPath.startsWith(projectRoot)) {
+  throw PathError.traversal(userPath);
+}
+```
+
+## Security Standards
+
+### Path Validation
+
+**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
+
+**Sanitize user inputs:**
+
+```typescript
+// ✅ Good: Sanitize before using in file system
+const agentDirName = agentName
+  .replace(/[^a-zA-Z0-9-]/g, '-')
+  .toLowerCase();
+
+const workspace = join(projectRoot, '.automatosx', 'workspaces', agentDirName);
+```
+
+**File size limits:**
+
+```typescript
+// ✅ Good: Prevent DoS with size limits
+if (content.length > 100 * 1024) {
+  throw new AgentValidationError('Profile file too large (max 100KB)');
+}
+```
+
+### Permissions
+
+**Restrictive permissions on Unix:**
+
+```typescript
+// ✅ Good: Restrict workspace permissions
+if (process.platform !== 'win32') {
+  await chmod(agentWorkspace, 0o700); // Owner only
+}
+```
+
+## Testing Standards
+
+### Test Structure
+
+**Use Vitest with describe/it:**
+
+```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 84%)
+- **Core modules:** 85%+
+- **CLI commands:** 70%+
+- **Utils:** 90%+
+
+## Logging Standards
+
+### Use Structured Logging
+
+**Always use logger from utils/logger:**
+
+```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'); // No structure, no context
+```
+
+### Log Levels
+
+- **debug:** Development details
+- **info:** Normal operations
+- **warn:** Recoverable issues
+- **error:** Failures requiring attention
+
+## Performance Standards
+
+### Lazy Loading
+
+**Defer expensive operations:**
+
+```typescript
+// ✅ Good: Lazy load heavy dependencies
+async executeTask() {
+  const { spawn } = await import('child_process'); // Load when needed
+  // ...
+}
+```
+
+### Caching
+
+**Use TTLCache for expensive operations:**
+
+```typescript
+// ✅ Good: Cache profiles with TTL
+this.cache = new TTLCache<AgentProfile>({
+  maxEntries: 20,
+  ttl: 300000, // 5 minutes
+  cleanupInterval: 60000
+});
+```
+
+### Bundle Size
+
+**Target: <250KB**
+
+- Current: 205KB ✅
+- Avoid large dependencies
+- Use tree-shaking friendly imports
+
+## 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 Messages
+
+```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
+- Add ~560 tokens per request for structured workflow
+
+# ❌ Bad: Vague
+fix: bug fix
+update: changes
+```
+
+## Code Review Checklist
+
+When reviewing code:
+
+- [ ] Type safety: No `any` types, all public APIs typed
+- [ ] Error handling: Custom errors with context
+- [ ] Security: Path validation, input sanitization
+- [ ] Testing: Tests added, coverage maintained
+- [ ] Performance: No obvious bottlenecks
+- [ ] Logging: Structured logs with context
+- [ ] Documentation: JSDoc for public APIs
+- [ ] Bundle size: No large dependencies added
+
+---
+
+**Last Updated:** 2025-10-07
+**For:** AutomatosX v4.0+