@defai.digital/automatosx 12.8.7 → 13.1.3

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

@@ -1,149 +0,0 @@
-# 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 AX_MOCK_PROVIDERS=true
-
-### Documentation
-
-- [ ] **JSDoc complete** - Public APIs have JSDoc
-- [ ] **README updated** - If adding features, update README
-- [ ] **CHANGELOG updated** - Add entry to GitHub Releases (https://github.com/defai-digital/automatosx/releases)
-
-### 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/abilities/our-coding-standards.md

@@ -1,369 +0,0 @@
-# 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';
-```
-
-**Runtime validation with Zod (REQUIRED for all scripts):**
-
-```typescript
-// ✅ Good: Use Zod for all external data validation
-import { z } from 'zod';
-
-const ConfigSchema = z.object({
-  workspaceRoot: z.string().min(1),
-  timeout: z.number().int().positive().default(30000),
-  maxRetries: z.number().int().min(0).max(5).default(3),
-  providers: z.array(z.string()).min(1),
-});
-
-type Config = z.infer<typeof ConfigSchema>;
-
-function loadConfig(data: unknown): Config {
-  return ConfigSchema.parse(data);
-}
-
-// ❌ Bad: No runtime validation (TypeScript types don't catch runtime errors)
-interface Config {
-  workspaceRoot: string;
-  timeout: number;
-  // ...
-}
-
-function loadConfig(data: any): Config {
-  return data as Config; // Unsafe!
-}
-```
-
-**When to use Zod in AutomatosX:**
-
-- ✅ **CLI argument parsing** - Validate all user input
-- ✅ **Configuration files** - Validate YAML/JSON configs
-- ✅ **API requests/responses** - Validate provider responses
-- ✅ **File I/O** - Validate file contents before processing
-- ✅ **Environment variables** - Validate at startup
-- ✅ **External scripts** - Always validate external data
-
-**Example: CLI argument validation**
-
-```typescript
-import { z } from 'zod';
-
-const RunCommandArgsSchema = z.object({
-  agent: z.string().min(1).max(50),
-  task: z.string().min(1),
-  timeout: z.number().int().positive().optional(),
-  verbose: z.boolean().default(false),
-  provider: z.enum(['claude', 'gemini', 'openai']).optional(),
-});
-
-export function validateRunArgs(argv: unknown) {
-  try {
-    return RunCommandArgsSchema.parse(argv);
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      const messages = error.issues.map(
-        (issue) => `${issue.path.join('.')}: ${issue.message}`
-      );
-      throw new Error(`Invalid arguments:\n${messages.join('\n')}`);
-    }
-    throw error;
-  }
-}
-```
-
-**Example: Agent profile validation**
-
-```typescript
-import { z } from 'zod';
-
-const AgentProfileSchema = z.object({
-  name: z.string().min(1).max(50),
-  displayName: z.string().min(1).max(100),
-  description: z.string().min(1),
-  systemPrompt: z.string().min(1),
-  defaultProvider: z.enum(['claude', 'gemini', 'openai']).optional(),
-  timeout: z.number().int().positive().optional(),
-  abilities: z.array(z.string()).default([]),
-  stages: z.array(z.object({
-    name: z.string(),
-    prompt: z.string(),
-    checkpoints: z.array(z.string()).optional(),
-  })).optional(),
-});
-
-type AgentProfile = z.infer<typeof AgentProfileSchema>;
-
-export async function loadAgentProfile(path: string): Promise<AgentProfile> {
-  const raw = await readFile(path, 'utf-8');
-  const yaml = YAML.parse(raw);
-
-  // Validate and return typed profile
-  return AgentProfileSchema.parse(yaml);
-}
-```
-
-## 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

@@ -1,183 +0,0 @@
-# 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
-│
-├── 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
-│   └── logs/                 # Application logs
-│
-├── automatosx/               # Workspace directory
-│   ├── PRD/                  # Planning documents (permanent)
-│   └── tmp/                  # Temporary files (auto-cleanup)
-│
-└── 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 setup`)
-2. `ax.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 24+, <250KB target
-
-## Workspace Structure
-
-**Shared workspaces:**
-
-- `automatosx/PRD/` - Planning documents, feature designs, proposals (permanent)
-- `automatosx/tmp/` - Test scripts, analysis tools, temporary reports (auto-cleanup)
-
-**All agents** have equal read/write access to both directories.
-
-**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/PRD/**/*` - Planning documents
-- `automatosx/tmp/**/*` - Temporary files
-
-**Forbidden:**
-
-- Empty paths or current directory (`''`, `'.'`)
-- Path traversal (`../../../etc/passwd`)
-- Symbolic links outside project
-- Absolute paths
-
----
-
-**Last Updated:** 2025-10-11
-**For:** AutomatosX v5.2+