@defai.digital/automatosx 5.0.1

package/CHANGELOG.md

@@ -0,0 +1,2877 @@
+# Changelog
+
+All notable changes to AutomatosX will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [5.0.1] - 2025-10-09
+
+### 🐛 Bug Fixes
+
+#### Critical: Provider Timeout Configuration
+**Problem**: Provider timeout was set to 5 minutes while agent timeout was 15 minutes, causing complex tasks to fail prematurely with retry loops.
+
+**Fixed**:
+- ✅ Updated all provider timeouts from 5 min → 15 min in `automatosx.config.json`
+- ✅ Updated DEFAULT_CONFIG in `src/types/config.ts` to match (affects new installations)
+- ✅ All timeout layers now consistent: Bash tool, Provider, Agent = 15 minutes
+
+**Impact**: Complex agent tasks now complete reliably without timeout errors.
+
+**Files Changed**:
+- `automatosx.config.json`: Provider timeout settings
+- `src/types/config.ts`: DEFAULT_CONFIG provider timeouts
+
+---
+
+#### Critical: Delegation Parser False Positives
+**Problem**: Delegation parser incorrectly parsed documentation examples and quoted text as actual delegation requests, causing unwanted agent delegation cycles.
+
+**Example of False Positive**:
+```
+Response containing: '1. "@frontend Create login UI"' (documentation example)
+→ Incorrectly parsed as actual delegation
+→ Caused delegation cycle errors
+```
+
+**Fixed**:
+- ✅ Added `isInQuotedText()` method to skip quoted delegation patterns
+- ✅ Added `isDocumentationExample()` method to detect and skip:
+  - Documentation markers: "Example:", "Supported syntaxes:", "範例:"
+  - Numbered lists with examples: `1. "...", 2. "..."`
+  - Test code patterns: `it(`, `test(`, `describe(`, `async () =>`
+  - Comment markers: `//`, `#`
+- ✅ Expanded detection context from 300 to 500 characters / 5 to 10 lines
+
+**Impact**: Zero false delegation parses - agents no longer misinterpret documentation.
+
+**Files Changed**:
+- `src/agents/delegation-parser.ts`: Added 2 new filtering methods (+95 lines)
+- `tests/unit/delegation-parser.test.ts`: Added 5 comprehensive tests
+
+---
+
+#### Important: FTS5 Special Character Handling
+**Problem**: FTS5 full-text search failed with syntax errors when queries contained special characters like `.`, `%`, `()`, etc.
+
+**Example Error**:
+```
+[WARN] Failed to inject memory
+{ "error": "Search failed: fts5: syntax error near \".\"" }
+```
+
+**Fixed**:
+- ✅ Enhanced FTS5 query sanitization from 3 → 15+ special characters
+- ✅ Added sanitization for: `. : " * ( ) [ ] { } ^ $ + | \ % < > ~ -`
+- ✅ Added boolean operator removal: `AND OR NOT`
+- ✅ Added empty query handling after sanitization
+- ✅ Improved error handling and logging
+
+**Impact**: Memory search now works reliably with all types of query text.
+
+**Files Changed**:
+- `src/core/memory-manager.ts`: Enhanced FTS5 query sanitization (+8 lines)
+
+---
+
+### ✅ Quality Improvements
+
+**Testing**:
+- ✅ Added 5 new tests for delegation filtering (total: 1050 tests, 100% pass rate)
+- ✅ All existing tests pass with no regressions
+- ✅ Test coverage for new methods: 100%
+
+**Code Quality**:
+- ✅ 0 TypeScript errors
+- ✅ 0 security vulnerabilities
+- ✅ Full JSDoc documentation for new methods
+- ✅ Backward compatible with v5.0.0
+
+**Performance**:
+- ✅ Delegation parsing: +1-2ms (negligible for reliability gain)
+- ✅ FTS5 search: +0.5ms (negligible for stability gain)
+- ✅ Bundle size: 380.41 KB (+0.14 KB)
+
+---
+
+### 📊 Statistics
+
+```
+Tests Passing: 1050/1050 (100%)
+TypeScript Errors: 0
+Bundle Size: 380.41 KB
+Build Time: ~850ms
+Code Coverage: ~85%
+```
+
+---
+
+### 🔄 Migration from v5.0.0
+
+**No Breaking Changes** - v5.0.1 is a drop-in replacement for v5.0.0.
+
+**Recommended Actions**:
+1. Update to v5.0.1 if experiencing timeout issues with complex tasks
+2. Update to v5.0.1 if seeing unwanted delegation cycles
+3. Update to v5.0.1 if encountering FTS5 search errors
+
+**Installation**:
+```bash
+npm install @defai.digital/automatosx@5.0.1
+# or
+npm update @defai.digital/automatosx
+```
+
+---
+
+## [5.0.0] - 2025-10-09
+
+### 🎉 Major Features
+
+#### Agent Template System
+
+AutomatosX v5.0 introduces a comprehensive agent template system that dramatically simplifies agent creation.
+
+**New Features**:
+- ✅ **Template Engine**: Variable substitution system with default values
+- ✅ **5 Pre-built Templates**: Ready-to-use agent templates for common roles
+- ✅ **`ax agent` Command Suite**: Complete CLI toolset for agent management
+- ✅ **Automatic Installation**: Templates installed automatically via `ax init`
+
+**Templates Included**:
+1. `basic-agent` - Minimal agent configuration (core team)
+2. `developer` - Software development specialist (engineering team)
+3. `analyst` - Business analysis expert (business team)
+4. `designer` - UI/UX design specialist (design team)
+5. `qa-specialist` - Quality assurance expert (core team)
+
+#### New CLI Commands
+
+**`ax agent` Command Suite** (5 subcommands):
+
+```bash
+# List available templates
+ax agent templates
+
+# Create agent from template (interactive)
+ax agent create <name> --template <template> --interactive
+
+# Create agent (one-line)
+ax agent create backend \
+  --template developer \
+  --display-name "Bob" \
+  --role "Senior Backend Engineer" \
+  --team engineering
+
+# List all agents
+ax agent list
+
+# List agents by team
+ax agent list --by-team engineering
+
+# Show agent details
+ax agent show <name>
+
+# Remove agent
+ax agent remove <name>
+```
+
+#### Configuration System Enhancements
+
+**Removed All Hardcoded Values**:
+- ✅ Retry configuration now fully configurable
+- ✅ Workspace limits moved to config
+- ✅ Timeout values moved to config
+- ✅ All execution parameters configurable
+
+**Benefits**:
+- More flexible deployment options
+- Easier tuning for different workloads
+- Better testability
+
+### 📦 Technical Details
+
+**Code Statistics**:
+- Template Engine: 210 lines, 21 comprehensive tests
+- Agent Commands: 751 lines across 5 command files
+- Templates: 5 YAML templates (~8 KB total)
+- Tests: 1,013 tests passing (100%)
+
+**Bundle Size**:
+- Current: 377 KB
+- Growth: +25 KB (+7.1% from v4.11.0)
+- Reason: New CLI commands + template engine
+
+### ✅ Quality Assurance
+
+- ✅ 1,013 tests passing (100%)
+- ✅ 0 TypeScript errors
+- ✅ 0 security vulnerabilities
+- ✅ ~85% code coverage
+- ✅ Ultrathink review score: A+ (96/100)
+
+### ⬆️ Upgrade Guide
+
+**No Breaking Changes**: v5.0.0 is fully backward compatible with v4.x.
+
+**New Installation**:
+```bash
+npm install -g @defai.digital/automatosx@5.0.0
+ax init  # Templates automatically installed
+```
+
+**Existing Projects**:
+```bash
+npm update -g @defai.digital/automatosx
+ax agent templates  # View available templates
+```
+
+### 🚀 What's Next
+
+**v5.0.1** (planned patch):
+- Template depth limit (prevent stack overflow)
+- YAML template validation (enhanced type safety)
+
+**v5.1.0** (planned minor):
+- Agent Registry with auto-discovery
+- Config management enhancements (`ax config diff`)
+- Additional agent templates
+
+### 📚 Documentation
+
+- Updated README with `ax agent` examples
+- New CLI command reference in `/tmp/CLI-COMMAND-REFERENCE.md`
+- Template system documentation in phase 2 reports
+
+---
+
+## [4.11.0] - 2025-10-09
+
+### 🎯 Major Changes
+
+#### FTS5 Full-Text Search (Removed Vector Search)
+
+**Revolutionary simplification**: Memory system now uses SQLite FTS5 full-text search exclusively, eliminating OpenAI embedding dependency and associated costs.
+
+**What Changed**:
+- ✅ **No External API Dependency**: Removed OpenAI embedding requirement
+- ✅ **Zero Embedding Costs**: No API calls for generating embeddings
+- ✅ **Simplified Architecture**: Pure SQLite FTS5 for text search
+- ✅ **Same Performance**: Maintains < 1ms search performance
+- ✅ **Better Privacy**: All data stays local (no cloud API calls)
+
+### 🔧 Breaking Changes
+
+#### Memory System
+
+- **Removed**: OpenAI embedding provider dependency
+- **Removed**: `embeddingDimensions` configuration option
+- **Renamed**: `MemoryManagerVec` class → `MemoryManager`
+- **Renamed**: `memory-manager-vec.ts` → `memory-manager.ts`
+- **Changed**: Memory search now requires `text` parameter (FTS5 query)
+- **Removed**: Vector-based similarity search
+
+**Migration Guide**:
+```typescript
+// Before (v4.10.0):
+const results = await memory.search({
+  vector: embedding,  // Required embedding
+  limit: 5
+});
+
+// After (v4.11.0):
+const results = await memory.search({
+  text: 'search query',  // Direct text query
+  limit: 5
+});
+```
+
+#### CLI Changes
+
+- **Memory search**: Now requires text query (no vector file support)
+  ```bash
+  # Before: ax memory search --vector-file embeddings.json
+  # After: ax memory search "your query text"
+  ```
+
+#### Configuration Changes
+
+- **Removed**: `memory.embeddingDimensions` from config
+  ```json
+  // Before:
+  {
+    "memory": {
+      "maxEntries": 10000,
+      "embeddingDimensions": 1536
+    }
+  }
+
+  // After:
+  {
+    "memory": {
+      "maxEntries": 10000
+    }
+  }
+  ```
+
+### ✨ Improvements
+
+- **Cost Reduction**: Eliminated embedding API costs
+- **Privacy**: All memory operations stay local
+- **Simplicity**: Removed embedding provider setup
+- **Reliability**: No external API dependencies
+- **Performance**: Maintained < 1ms search speed
+
+### 📝 Documentation
+
+- Updated README.md to reflect FTS5-only architecture
+- Removed vector search references
+- Removed specific pricing amounts (cost savings noted generically)
+- Updated example configurations
+
+### 🔄 Migration Notes
+
+**No Data Loss**: Existing memory databases will continue to work. The FTS5 tables are already present and functional.
+
+**Action Required**:
+1. Update code using `MemoryManagerVec` → `MemoryManager`
+2. Change search calls to use `text` parameter instead of `vector`
+3. Remove `embeddingDimensions` from config files
+4. Update CLI scripts using `--vector-file` flag
+
+## [4.10.0] - 2025-10-08
+
+### 🎯 Major Features
+
+#### Team-Based Configuration System
+
+**Revolutionary change**: Agents now inherit configuration from teams, eliminating configuration duplication across 17 agents.
+
+**New Architecture**:
+- **4 Teams**: Core, Engineering, Business, Design
+- **Centralized Provider Config**: Each team defines provider fallback chain
+- **Shared Abilities**: Team-wide abilities automatically inherited
+- **Clean Agent Profiles**: No need to specify provider/model/temperature in agents
+
+**Key Benefits**:
+- ✅ **Zero Duplication**: Provider config defined once per team (not per agent)
+- ✅ **Easy Updates**: Change provider for entire team at once
+- ✅ **Clear Organization**: Explicit team structure (17 agents → 4 teams)
+- ✅ **Backward Compatible**: Old agent configs still work (deprecated)
+
+### ✨ New Features
+
+#### TeamManager (NEW)
+
+- **Location**: `src/core/team-manager.ts`
+- **Purpose**: Load and validate team configurations from `.automatosx/teams/*.yaml`
+- **Features**:
+  - TTL-based caching for performance
+  - YAML validation and error handling
+  - Team discovery and listing
+  - Graceful error recovery
+
+#### Team Configuration Files
+
+Created 4 team configurations in `.automatosx/teams/`:
+
+1. **core.yaml**: Quality assurance specialists
+   - Primary: claude
+   - Fallback: [claude, gemini, codex]
+   - Agents: charlie (code reviewer), tester, assistant
+
+2. **engineering.yaml**: Software development teams
+   - Primary: codex
+   - Fallback: [codex, gemini, claude]
+   - Agents: frontend, backend, devops, fullstack, database, architect, api-designer
+
+3. **business.yaml**: Business and product teams
+   - Primary: gemini
+   - Fallback: [gemini, codex, claude]
+   - Agents: planner, pm, researcher
+
+4. **design.yaml**: Design and content teams
+   - Primary: gemini
+   - Fallback: [gemini, claude, codex]
+   - Agents: designer, writer, ux-researcher, content-strategist
+
+#### Agent Profile Enhancement
+
+- **Added**: `team?: string` field to AgentProfile
+- **Deprecated**: `provider`, `fallbackProvider`, `model`, `temperature`, `maxTokens`
+- **Migration**: All 17 agents migrated to team-based configuration
+
+#### Team-Based Provider Selection
+
+- **Location**: `src/agents/context-manager.ts`
+- **New Method**: `selectProviderForAgent(agent, options)`
+- **Priority Order**:
+  1. CLI option (highest): `ax run agent "task" --provider gemini`
+  2. Team configuration: From `.automatosx/teams/<team>.yaml`
+  3. Agent configuration (deprecated): From agent's `provider` field
+  4. Router fallback (lowest): Global provider routing
+
+#### Ability Inheritance
+
+- **Automatic Merging**: Team sharedAbilities + agent abilities
+- **Example**:
+  ```yaml
+  # Team: [our-coding-standards, code-generation]
+  # Agent: [backend-development, api-design]
+  # Final: [our-coding-standards, code-generation, backend-development, api-design]
+  ```
+
+### 🔧 Improvements
+
+#### ProfileLoader Enhancement
+
+- **Modified**: Constructor accepts `teamManager?: TeamManager`
+- **Changed**: `buildProfile()` now async to support team loading
+- **Added**: `getTeamConfig(agentName)` method for ContextManager
+- **Feature**: Automatic ability merging from team config
+
+#### OpenAI Provider CLI Fix
+
+- **Fixed**: Codex CLI parameter format
+- **Before**: `codex chat -p [PROMPT] -t [TEMP]` (broken)
+- **After**: `codex exec -c temperature=X [PROMPT]` (correct)
+- **Issue**: Codex CLI doesn't support `-t` flag, needs `-c` config override format
+
+### 🐛 Critical Bug Fixes
+
+#### TeamManager Initialization (CRITICAL)
+
+- **Issue**: TeamManager was never initialized in `src/cli/commands/run.ts`
+- **Impact**: Entire team system was non-functional despite being implemented
+- **Fix**: Added TeamManager initialization before ProfileLoader creation
+- **Discovery**: Found during deep code review
+- **Verification**: Tested with `--debug` flag, confirmed team config loading
+
+#### TypeScript Type Error
+
+- **Issue**: `Array.filter(Boolean)` doesn't narrow type from `(string | undefined)[]`
+- **Fix**: Used type predicate: `.filter((p): p is string => Boolean(p))`
+- **Location**: `src/agents/context-manager.ts:321`
+
+#### Test Version Mismatch
+
+- **Fixed**: Updated 5 test expectations from '4.7.1' to '4.9.8'
+- **Location**: `tests/unit/cli-index.test.ts`
+
+### 📚 Documentation
+
+#### Comprehensive Documentation Updates
+
+- **CLAUDE.md**:
+  - Updated version to v4.10.0
+  - Added TeamManager to Core Components
+  - Updated Agent System with team inheritance details
+  - Added complete "Team System" section with examples
+  - Updated Agent Profiles section with team-based config examples
+
+- **README.md**:
+  - Added v4.10.0 features in "What's New" section
+  - Updated Key Capabilities with team-based examples
+  - Updated Real-World Examples
+  - Updated version table (v4.7.1 → v4.10.0)
+
+- **tmp/CLAUDE.md**:
+  - Updated with team system architecture details
+
+#### Migration Tools
+
+- **Created**: `tmp/migrate-agents.ts` - Automated migration script
+- **Results**: Successfully migrated all 17 agents
+- **Changes**:
+  - Added `team` field
+  - Removed deprecated fields: `provider`, `fallbackProvider`, `model`, `temperature`, `maxTokens`
+
+### 🔨 Technical Changes
+
+#### New Files
+
+- `src/types/team.ts` - TeamConfig type definitions
+- `src/core/team-manager.ts` - Team configuration management
+- `.automatosx/teams/core.yaml` - Core team configuration
+- `.automatosx/teams/engineering.yaml` - Engineering team configuration
+- `.automatosx/teams/business.yaml` - Business team configuration
+- `.automatosx/teams/design.yaml` - Design team configuration
+- `tmp/migrate-agents.ts` - Agent migration automation script
+
+#### Modified Files
+
+- `src/types/agent.ts` - Added `team` field, deprecated old fields
+- `src/agents/profile-loader.ts` - Team inheritance implementation
+- `src/agents/context-manager.ts` - Team-based provider selection
+- `src/providers/openai-provider.ts` - Fixed codex CLI parameters
+- `src/cli/commands/run.ts` - Added TeamManager initialization
+- All 17 agent YAML files - Migrated to team-based configuration
+- `tests/unit/cli-index.test.ts` - Updated version expectations
+
+### ✅ Testing
+
+#### All Tests Passing
+
+- **Total**: 928 unit tests passing (100%)
+- **TypeScript**: Strict mode compilation successful
+- **Functional**: Team config loading verified with `--debug`
+- **Integration**: All CLI commands working correctly
+
+### 🔄 Breaking Changes
+
+**None** - All changes are backward compatible. Old agent configurations (with `provider`, `temperature`, etc.) still work but are deprecated.
+
+### 📦 Migration Guide
+
+**From v4.9.x to v4.10.0**:
+
+1. **Optional**: Assign agents to teams (recommended but not required)
+   ```yaml
+   # Add to existing agent config:
+   team: engineering
+   ```
+
+2. **Optional**: Remove deprecated fields (they still work if kept)
+   ```yaml
+   # Can remove these:
+   # provider: codex
+   # fallbackProvider: gemini
+   # temperature: 0.7
+   # maxTokens: 4096
+   ```
+
+3. **Optional**: Customize team configurations in `.automatosx/teams/*.yaml`
+
+**No action required** - Everything continues to work with old configurations!
+
+### 🎉 Summary
+
+v4.10.0 introduces a revolutionary team-based configuration system that:
+- ✅ Eliminates configuration duplication (17 agents → 4 teams)
+- ✅ Simplifies agent management (no provider config per agent)
+- ✅ Improves maintainability (change provider for entire team at once)
+- ✅ Maintains backward compatibility (old configs still work)
+- ✅ Fixes critical bugs (TeamManager initialization, codex CLI parameters)
+
+**Total Impact**: 17 agents migrated, 4 team configs created, 6 new/modified core files, 928 tests passing.
+
+## [4.9.6] - 2025-10-08
+
+### 🐛 Bug Fixes
+
+#### Natural Language Delegation Parser - Whitespace Handling
+
+- **Fixed**: Regex patterns now correctly handle indented delegation syntax
+- **Issue**: Multi-line delegations with indentation were incorrectly parsed as single delegation
+- **Solution**: Added `\s*` to lookahead assertions to match optional whitespace after newlines
+- **Impact**: All 7 delegation patterns now work correctly with various formatting styles
+- **Example**: Properly separates `@frontend Create UI` and `@backend Implement API` even when indented
+- **Tests**: All 1026 tests passing (fixed 2 previously failing tests)
+
+### 🔧 Improvements
+
+#### Enhanced Delegation Pattern Robustness
+
+- **Improved**: Lookahead assertions in all regex patterns (DELEGATE TO, @agent, Please/Request, I need/require, Chinese patterns)
+- **Flexibility**: Now supports mixed formatting styles (no indentation, tabs, spaces)
+- **Reliability**: Correctly separates multiple delegations regardless of formatting
+
+## [4.9.5] - 2025-10-08
+
+### ✨ Features
+
+#### Intelligent Per-Agent Provider Fallback
+
+- **Added**: `fallbackProvider` field in AgentProfile for per-agent fallback configuration
+- **3-Layer Fallback**: Primary provider → Fallback provider → Router (global priority)
+- **Strategic Distribution**: 17 agents configured with optimal provider assignments
+  - Coding agents (7): Claude primary → Codex fallback (Claude best for coding)
+  - Planning agents (3): Codex primary → Claude fallback (Codex best for planning)
+  - Creative agents (2): Gemini primary → Claude fallback (Gemini best for creative)
+  - Data/Ops agents (4): Codex primary → Claude fallback
+  - General agent (1): Gemini primary → Claude fallback
+- **Claude as Safety Net**: Claude set as global priority 3 (final fallback) to ensure reliable backup
+
+#### Provider Renaming: OpenAI → Codex
+
+- **Changed**: OpenAIProvider renamed to match actual CLI tool (`codex`)
+- **Updated**: Provider name from `openai` to `codex` throughout codebase
+- **Configuration**: Updated default config to use `command: codex`
+- **Documentation**: All docs updated to reflect Codex CLI usage
+
+### 🔧 Improvements
+
+#### Enhanced Context Manager
+
+- **Updated**: `selectProvider()` now supports 3-layer fallback logic
+- **Logging**: Added detailed logging for provider selection (primary/fallback/router)
+- **Graceful Degradation**: System continues working even if preferred provider unavailable
+
+#### Global Provider Priority Update
+
+- **Changed**: Provider priority order: Codex (1) → Gemini (2) → Claude (3)
+- **Rationale**: Claude as lowest priority ensures it's the final reliable fallback
+- **Benefits**: Optimizes cost and performance while maintaining reliability
+
+### 📚 Documentation
+
+#### Comprehensive Documentation Updates
+
+- **Updated**: README.md, CLAUDE.md with new provider information
+- **Updated**: All docs (installation.md, core-concepts.md, quick-start.md)
+- **Updated**: FAQ.md with Codex CLI information
+- **Clarified**: Provider roles (Claude=coding, Codex=planning, Gemini=creative)
+
+### 🔨 Technical Changes
+
+#### Provider System Refactoring
+
+- **Modified**: `src/providers/openai-provider.ts` - getter returns 'codex'
+- **Modified**: `src/cli/commands/run.ts` - provider initialization uses name: 'codex'
+- **Modified**: `src/cli/commands/status.ts` - consistent provider naming
+- **Modified**: `src/types/agent.ts` - added fallbackProvider field
+- **Modified**: `src/agents/context-manager.ts` - 3-layer fallback implementation
+
+### ✅ Testing
+
+#### All Tests Pass
+
+- **Verified**: 922+ tests passing with new provider configuration
+- **Tested**: Provider routing for coding, planning, and creative agents
+- **Validated**: Fallback mechanism working correctly
+
+## [4.9.1] - 2025-10-08
+
+### ✨ Features
+
+#### Display Name Resolution for Agent Delegation
+
+- **Added**: Agents can now delegate using friendly display names (e.g., `@Oliver`, `@Tony`, `@Steve`)
+- **Smart Resolution**: `DelegationParser` automatically resolves display names to agent names using `ProfileLoader`
+- **Case-Insensitive**: Display name matching is case-insensitive (`@oliver`, `@Oliver`, `@OLIVER` all work)
+- **Graceful Fallback**: Works with or without `ProfileLoader` - degrades gracefully in tests
+- **Example**: `@Oliver Create infrastructure` → resolves to `devops` agent
+
+#### Duplicate Display Name Detection
+
+- **Added**: `ProfileLoader` now detects and warns about duplicate display names
+- **Behavior**: First occurrence is kept, duplicates are skipped with clear warning
+- **Logging**: Detailed warning includes both conflicting agent names
+
+### 🔧 Improvements
+
+#### Extended Provider Timeout
+
+- **Increased**: Provider timeout from 2 minutes to 5 minutes (300000ms)
+- **Benefit**: Allows complex multi-agent workflows to complete without timing out
+- **Affected**: Both `claude-code` and `gemini-cli` providers
+- **Configuration**: Updated in both `DEFAULT_CONFIG` and `automatosx.config.json`
+
+#### Enhanced Error Handling
+
+- **Improved**: Invalid agents are automatically skipped during delegation with clear logging
+- **Added**: Proper error messages when agent resolution fails
+- **Logging**: Debug logs show display name → agent name resolution
+
+### ✅ Testing
+
+#### New Integration Tests
+
+- **Added**: 6 comprehensive integration tests for display name resolution
+- **Coverage**: Tests with/without ProfileLoader, multiple display names, invalid agents, case sensitivity
+- **Total**: 928 tests (up from 922)
+
+#### Test Updates
+
+- **Updated**: All delegation parser tests to use async/await
+- **Fixed**: Test files properly handle async parse() method
+- **Files**: `delegation-parser.test.ts`, `executor-multi-delegation.test.ts`, `natural-language-delegation.test.ts`
+
+### 🔨 Technical Changes
+
+#### Files Modified:
+
+- `src/agents/delegation-parser.ts` - Added ProfileLoader support and async resolution
+- `src/agents/executor.ts` - Pass ProfileLoader to DelegationParser
+- `src/agents/profile-loader.ts` - Added duplicate display name detection
+- `src/types/config.ts` - Increased default timeouts
+- `automatosx.config.json` - Updated provider timeouts
+- `tests/unit/delegation-parser.test.ts` - Added display name integration tests
+
+#### API Changes:
+
+- `DelegationParser.constructor()` now accepts optional `ProfileLoader` parameter
+- `DelegationParser.parse()` changed from sync to async method
+- All callers updated to use `await parser.parse()`
+
+### 📊 Validation
+
+- ✅ TypeScript compilation: Pass
+- ✅ Unit tests: 928 passed (6 new tests)
+- ✅ Integration tests: Pass
+- ✅ E2E tests: Pass
+- ✅ Build: Success
+
+### 🎯 Use Cases
+
+#### Before (v4.8.0):
+
+```typescript
+@devops Create the CI/CD pipeline
+@cto Review architecture
+@security Audit the implementation
+```
+
+#### After (v4.9.1):
+
+```typescript
+@Oliver Create the CI/CD pipeline    // Friendly display name
+@Tony Review architecture             // Auto-resolves to 'cto'
+@Steve Audit the implementation      // Auto-resolves to 'security'
+```
+
+### 🔄 Backward Compatibility
+
+- ✅ All existing agent name delegation continues to work
+- ✅ No breaking changes to API
+- ✅ ProfileLoader is optional - graceful degradation without it
+
+---
+
+## [4.9.0] - 2025-10-08
+
+### 🧹 Complete Removal of canDelegate Field - Clean Architecture
+
+This release completes the architectural cleanup by **fully removing the `canDelegate` field** from the codebase, eliminating confusion and technical debt introduced in earlier versions.
+
+#### 🎯 Breaking Changes
+
+#### `canDelegate` Field Removed
+
+- ❌ **Removed**: `orchestration.canDelegate` field no longer exists in `OrchestrationConfig` type
+- ✅ **Behavior**: All agents can delegate by default (unchanged from v4.8.0)
+- ⚠️ **Warning**: Agent profiles with `canDelegate` will show deprecation warning but continue to work
+- 📝 **Action Required**: Remove `canDelegate` from your agent YAML files (optional, not breaking)
+
+#### Migration Guide:
+
+```yaml
+# Before (v4.8.0 and earlier)
+orchestration:
+  canDelegate: true          # ❌ No longer valid (shows warning)
+  maxDelegationDepth: 3
+
+# After (v4.9.0+)
+orchestration:
+  maxDelegationDepth: 3      # ✅ Clean configuration
+```
+
+#### ✨ Features
+
+#### 1. Clean Type Definitions
+
+- **Removed**: `canDelegate?: boolean` from `OrchestrationConfig` interface
+- **Updated**: Documentation reflects universal delegation (all agents can delegate)
+- **Benefit**: No confusion about whether agents can delegate
+
+#### 2. Improved Runtime Metadata
+
+- **Renamed**: `OrchestrationMetadata.canDelegate` → `isDelegationEnabled`
+- **Clarification**: Field now clearly indicates whether orchestration system is available
+- **Semantic**: `isDelegationEnabled` = "Is SessionManager/WorkspaceManager available?" not "Can this agent delegate?"
+
+#### 3. Deprecation Warning
+
+- **Added**: Warning when loading agent profiles with deprecated `canDelegate` field
+- **Message**: "orchestration.canDelegate is deprecated and ignored (v4.9.0+). All agents can delegate by default."
+- **Impact**: Zero breaking changes for existing profiles
+
+#### 4. Test Suite Updated
+
+- **Updated**: 988 tests now use `isDelegationEnabled` instead of `canDelegate`
+- **Removed**: All obsolete permission check tests
+- **Result**: Cleaner, more maintainable test suite
+
+#### 🔧 Technical Details
+
+#### Files Changed:
+
+- `src/types/orchestration.ts` - Removed `canDelegate` from `OrchestrationConfig`, renamed in `OrchestrationMetadata`
+- `src/agents/profile-loader.ts` - Added deprecation warning for old `canDelegate` usage
+- `src/agents/context-manager.ts` - Uses `isDelegationEnabled` for logging
+- `examples/agents/*.yaml` - Updated to remove `canDelegate`
+- `CLAUDE.md` - Updated documentation to reflect v4.9.0 changes
+- All test files - Updated to use new API
+
+#### Backward Compatibility:
+
+- ✅ Existing agent profiles with `canDelegate` continue to work (with warning)
+- ✅ No changes needed to delegation behavior or API
+- ✅ Runtime behavior identical to v4.8.0
+
+#### 📊 Validation
+
+- ✅ TypeScript compilation: Pass
+- ✅ Unit tests: 922 passed
+- ✅ Integration tests: 66 passed
+- ✅ Total: 988 tests passed
+
+#### 🎨 Why This Change?
+
+#### Problem:
+
+- v4.8.0 claimed "all agents can delegate" but `canDelegate` field still existed
+- Caused confusion: developers unsure if they need to set `canDelegate: true`
+- Technical debt: validation code, tests, documentation for unused field
+
+#### Solution:
+
+- Complete removal of `canDelegate` from type system
+- Clearer naming: `isDelegationEnabled` indicates system availability
+- Simpler configuration: agents just work without field
+
+#### Result:
+
+- Zero configuration needed for delegation
+- API matches behavior exactly
+- Reduced maintenance burden
+
+#### 🚀 Upgrade Path
+
+1. **Optional**: Remove `canDelegate` from agent YAML files
+2. **Automatic**: Profiles with `canDelegate` show warning but work normally
+3. **No code changes**: Runtime behavior unchanged
+
+#### Example Update:
+
+```bash
+# Find all agent profiles with canDelegate
+grep -r "canDelegate" .automatosx/agents/
+
+# Remove the field (optional)
+sed -i '' '/canDelegate:/d' .automatosx/agents/*.yaml
+```
+
+---
+
+## [4.8.0] - 2025-10-08
+
+### 🌟 Universal Agent Delegation - True Autonomous Collaboration
+
+This release removes all remaining barriers to agent delegation, enabling **every agent to delegate by default** without any configuration requirements.
+
+#### 🎯 Breaking Changes
+
+#### Orchestration Configuration Simplified
+
+- ✅ **New Behavior**: All agents can delegate regardless of `canDelegate` setting
+- ✅ **Auto-Initialization**: SessionManager and WorkspaceManager automatically initialize (no `--session` flag required)
+- 🔧 **Optional Field**: `orchestration.canDelegate` is now optional (defaults to `true`)
+- 📝 **Backward Compatible**: Existing agent profiles continue to work without changes
+
+#### Migration Guide:
+
+```yaml
+# Before (v4.7.8 and earlier)
+orchestration:
+  canDelegate: true      # ❌ Required for delegation
+  maxDelegationDepth: 3
+
+# After (v4.8.0+)
+orchestration:           # ✨ Orchestration block now optional!
+  maxDelegationDepth: 3  # Only specify if different from default (3)
+
+# Or simply omit orchestration block entirely:
+# (agent can still delegate with default settings)
+```
+
+#### ✨ Features
+
+#### 1. Universal Delegation
+
+- **Changed**: `context-manager.ts` no longer checks `agent.orchestration?.canDelegate`
+- **Result**: All agents receive orchestration metadata automatically
+- **Benefit**: Zero configuration needed for basic delegation
+
+#### 2. Always-On Orchestration Managers
+
+- **Changed**: `run.ts` always initializes SessionManager and WorkspaceManager
+- **Previous**: Required `--session` flag to enable delegation
+- **Result**: Delegation works immediately without additional flags
+- **Benefit**: Seamless agent-to-agent collaboration
+
+#### 3. Removed Permission Checks
+
+- **Changed**: `executor.ts` no longer validates `canDelegate` permission
+- **Safety**: Maintained via cycle detection, depth limits, timeout enforcement
+- **Benefit**: Autonomous collaboration without artificial restrictions
+
+#### 4. Enhanced Type Safety
+
+- **Added**: `maxDelegationDepth` to `OrchestrationMetadata` interface
+- **Changed**: Made `maxDelegationDepth` optional with default value (3)
+- **Benefit**: Better TypeScript inference and runtime safety
+
+#### 5. Improved Logging
+
+- **Added**: `hasOrchestration` and `canDelegate` to execution context logs
+- **Benefit**: Better debugging and visibility into orchestration status
+
+#### 🔧 Technical Changes
+
+#### Modified Files:
+
+- `src/agents/context-manager.ts`: Removed `canDelegate` check, always create orchestration metadata
+- `src/agents/executor.ts`: Removed delegation permission validation, added optional chaining for `maxDelegationDepth`
+- `src/cli/commands/run.ts`: Always initialize SessionManager and WorkspaceManager
+- `src/types/orchestration.ts`: Added `maxDelegationDepth` field to `OrchestrationMetadata`
+
+#### Code Changes:
+
+```typescript
+// Before (v4.7.8)
+if (agent.orchestration?.canDelegate &&
+    this.config.workspaceManager &&
+    this.config.profileLoader) {
+  // Create orchestration metadata
+}
+
+// After (v4.8.0)
+if (this.config.workspaceManager &&
+    this.config.profileLoader) {
+  // Always create orchestration metadata
+  const maxDelegationDepth = agent.orchestration?.maxDelegationDepth ?? 3;
+}
+```
+
+#### 🧪 Testing
+
+#### Test Coverage:
+
+- ✅ All existing tests passing (922 tests)
+- ✅ Delegation works without `orchestration` block in agent profiles
+- ✅ Delegation works without `--session` flag
+- ✅ Multiple agents can delegate in sequence
+- ✅ Sessions automatically created and tracked
+
+#### Verified Scenarios:
+
+1. Agent without `orchestration` block can delegate ✅
+2. Multiple sequential delegations (A→B→C) work ✅
+3. Session creation and persistence automatic ✅
+4. Workspace isolation maintained ✅
+
+#### 📦 Files Changed
+
+#### Core Changes:
+
+- `src/agents/context-manager.ts`: Universal orchestration metadata creation
+- `src/agents/executor.ts`: Removed permission checks, optional `maxDelegationDepth`
+- `src/cli/commands/run.ts`: Always initialize orchestration managers
+- `src/types/orchestration.ts`: Added `maxDelegationDepth` to metadata interface
+
+#### Documentation Updates:
+
+- `README.md`: Updated to v4.8.0, added Universal Agent Delegation section
+- `CHANGELOG.md`: This changelog entry
+- `.automatosx/agents/*.yaml`: Updated example agent profiles (orchestration optional)
+
+#### 🎉 Impact
+
+#### Developer Experience:
+
+- 🚀 **Faster Setup**: No configuration needed for delegation
+- 💡 **Clearer Intent**: Agents collaborate naturally without artificial barriers
+- 🔧 **Less Config**: Agent profiles are simpler and more maintainable
+
+#### System Behavior:
+
+- ✅ **More Autonomous**: Agents decide collaboration without permission checks
+- 🛡️ **Still Safe**: Cycle detection, depth limits, timeouts prevent abuse
+- 📊 **Better Visibility**: Logging shows orchestration status clearly
+
+#### Backward Compatibility:
+
+- ✅ Existing agent profiles continue to work
+- ✅ `canDelegate: true` is still respected (but no longer required)
+- ✅ `--session` flag still works (but no longer required)
+
+---
+
+## [4.7.6] - 2025-10-08
+
+### 🔓 Complete Whitelist Removal
+
+This release completely removes the `canDelegateTo` whitelist mechanism, enabling true autonomous agent collaboration.
+
+#### 🎯 Breaking Changes
+
+#### Whitelist Mechanism Removed
+
+- ❌ **Removed**: `canDelegateTo` field no longer validated or enforced
+- ✅ **New Behavior**: Agents can delegate to ANY other agent by default
+- 🛡️ **Safety**: Security ensured via `canDelegate` flag, cycle detection, depth limits, and timeouts
+
+#### Migration Guide:
+
+```yaml
+# Before (v4.7.5 and earlier)
+orchestration:
+  canDelegate: true
+  canDelegateTo:        # ❌ No longer needed
+    - frontend
+    - backend
+  maxDelegationDepth: 3
+
+# After (v4.7.6+)
+orchestration:
+  canDelegate: true     # ✅ Just this!
+  maxDelegationDepth: 3
+```
+
+**Action Required:** Simply remove `canDelegateTo` from your agent profiles. Existing profiles with `canDelegateTo` will continue to work (field is ignored).
+
+#### ✨ Refactoring & Improvements
+
+#### 1. Code Cleanup
+
+- Removed `canDelegateTo` validation from `profile-loader.ts`
+- Removed whitelist checking logic from `executor.ts`
+- Removed deprecated field from `OrchestrationConfig` type
+- Cleaned up all example agent configurations
+
+#### 2. Simplified Delegation Model
+
+- Text-only delegation mode (SessionManager/WorkspaceManager now optional)
+- Lightweight agent-to-agent communication without file system overhead
+- Maintains backward compatibility for full collaboration features
+
+#### 3. Documentation Updates
+
+- Updated README.md to reflect autonomous collaboration model
+- Updated CLAUDE.md with new orchestration examples
+- Removed whitelist references from all documentation
+- Updated all example agent profiles
+
+#### 4. Test Updates
+
+- Simplified delegation tests to focus on autonomous collaboration
+- Removed whitelist-specific test cases
+- Updated orchestration type tests
+- All 904 tests passing ✅
+
+#### 🧪 Test Results
+
+```text
+✅ 904/904 tests passing (100%)
+✅ All whitelist code removed
+✅ Build successful: 312.91 KB bundle
+✅ No breaking changes to existing delegation functionality
+```
+
+#### 📦 Files Changed
+
+#### Core Changes:
+
+- `src/types/orchestration.ts`: Removed `canDelegateTo` field
+- `src/agents/executor.ts`: Removed whitelist validation logic
+- `src/agents/profile-loader.ts`: Removed `canDelegateTo` validation
+- `src/cli/commands/run.ts`: SessionManager/WorkspaceManager now optional
+
+#### Configuration:
+
+- `.automatosx/agents/*.yaml`: Removed `canDelegateTo` (3 files)
+- `examples/agents/*.yaml`: Removed `canDelegateTo` (2 files)
+
+#### Documentation:
+
+- `README.md`: Updated to v4.7.6, added whitelist removal highlights
+- `CLAUDE.md`: Updated orchestration examples
+- `CHANGELOG.md`: This entry
+
+#### Tests:
+
+- `tests/unit/types/orchestration.test.ts`: Removed whitelist tests
+- `tests/unit/executor-delegation.test.ts`: Simplified to autonomous collaboration
+
+#### 🔒 Security
+
+All security mechanisms remain intact and enhanced:
+
+- ✅ **Permission Check**: `canDelegate: true` required to delegate
+- ✅ **Cycle Detection**: Prevents A→B→A circular delegations
+- ✅ **Depth Limit**: Max 3 levels of delegation by default
+- ✅ **Timeout Enforcement**: Per-agent execution timeouts
+- ✅ **Workspace Isolation**: Agents still restricted to their workspaces
+
+## [4.7.5] - 2025-10-08
+
+### 🚀 Major Feature Complete: Autonomous Multi-Agent Delegation
+
+Completed the implementation of autonomous agent delegation system, enabling agents to collaborate without manual orchestration.
+
+#### ✨ New Features
+
+#### 1. Autonomous Agent Delegation (CRITICAL)
+
+- ✅ **Delegation Parsing & Execution**: Agents can now actually delegate tasks by outputting `DELEGATE TO [agent]: [task]`
+- ✅ **Automatic Detection**: System automatically parses agent responses for delegation requests
+- ✅ **Seamless Integration**: Delegation results are automatically appended to agent responses
+- ✅ **No Whitelist Required**: Removed `canDelegateTo` restriction for true autonomous collaboration
+- ✅ **Multi-Delegation Support**: Agents can delegate to multiple agents in single response
+- ✅ **Case-Insensitive Parsing**: Delegation syntax is flexible and robust
+
+#### Example:
+
+```bash
+ax run backend "Review README and discuss with CTO"
+# Bob can now output:
+# "I've reviewed the README.
+#
+#  DELEGATE TO cto: Please provide strategic feedback on README
+#
+#  The delegation has been requested."
+#
+# System automatically executes delegation and returns combined results
+```
+
+#### 🐛 Critical Bug Fixes
+
+#### 1. Orchestration Managers Initialization (CRITICAL)
+
+- **Issue**: WorkspaceManager only initialized when `--session` flag provided
+- **Impact**: Delegation completely non-functional without explicit session
+- **Fix**: Always initialize WorkspaceManager to enable delegation
+- **Before**: `ax run backend "task"` → orchestration = undefined → no delegation
+- **After**: `ax run backend "task"` → orchestration available → delegation works
+
+#### 2. Type Safety Improvements
+
+- Fixed unsafe type assertion in ProfileLoader (`profile!` → `profile`)
+- Improved null/undefined checking for profile loading
+- Added proper type guards for cached profiles
+
+#### 3. Error Handling Precision
+
+- Replaced string matching with instanceof checks
+- `error.message.includes('Agent not found')` → `error instanceof AgentNotFoundError`
+- Added proper import for AgentNotFoundError type
+
+#### 4. Prompt Optimization
+
+- Limited availableAgents list to 10 agents (from 17)
+- Added "... and N more agents" message
+- Reduced prompt length by ~40% for large agent lists
+- Added delegation example in prompt
+
+#### 5. Whitelist Removal
+
+- Removed `canDelegateTo` enforcement (deprecated in v4.7.2)
+- Agents can now delegate to ANY other agent
+- Safety still ensured via cycle detection, depth limits, timeouts
+- Added deprecation notice in type definitions
+
+#### 📝 Documentation Updates
+
+- Added comprehensive delegation usage examples
+- Updated orchestration documentation
+- Clarified agent collaboration capabilities
+- Added troubleshooting guide for delegation
+
+#### 🧪 Test Results
+
+```text
+✅ 892/892 tests passing (100%)
+✅ Delegation parsing verified (single/multi/case-insensitive)
+✅ Type safety validated with strict TypeScript
+✅ Build successful: 313KB bundle
+```
+
+#### 📦 Files Changed
+
+#### Core Delegation Implementation:
+
+- `src/agents/executor.ts`: +120 lines (parseDelegationRequests, executeDelegations, auto-execution)
+- `src/cli/commands/run.ts`: +15 lines (always initialize WorkspaceManager, AgentNotFoundError import)
+
+#### Type Safety & Optimization:
+
+- `src/agents/profile-loader.ts`: Type safety improvements
+- `src/types/orchestration.ts`: Deprecated canDelegateTo with @deprecated tag
+- `src/agents/context-manager.ts`: Removed whitelist filtering
+
+#### Tests:
+
+- `tests/unit/executor-delegation.test.ts`: Updated to verify whitelist removal
+
+#### 🔒 Security
+
+All security mechanisms remain intact:
+
+- ✅ Cycle detection prevents infinite delegation loops
+- ✅ Max delegation depth (default: 3)
+- ✅ Timeout enforcement at each level
+- ✅ Workspace isolation and permission validation
+- ✅ Path traversal protection
+
+#### ⚠️ Breaking Changes
+
+#### Behavioral Change (Non-Breaking):
+
+- `canDelegateTo` in agent profiles is now ignored (previously enforced)
+- Agents can delegate to any other agent regardless of whitelist
+- Existing profiles with `canDelegateTo` will continue to work but field is ignored
+
+#### Migration Guide
+
+No action required. The `canDelegateTo` field can be safely removed from agent profiles, but leaving it in place has no negative effect.
+
+---
+
+## [4.7.1] - 2025-10-08
+
+### 🐛 Critical Bug Fixes & Security Enhancements
+
+Fixed 12 critical and high-priority bugs discovered through ultra-deep analysis of v4.7.0.
+
+#### Critical Fixes
+
+#### Session Manager Improvements:
+
+- ✅ **Duplicate Cleanup Execution**: Removed redundant cleanup calls in `createSession()` that caused performance issues
+- ✅ **UUID Collision Protection**: Added 100-attempt limit to prevent infinite loops in rare UUID collision scenarios
+- ✅ **Date Validation**: Validate Date objects when loading from persistence to prevent Invalid Date crashes
+- ✅ **Circular Reference Protection**: Catch JSON.stringify errors to handle metadata with circular references
+
+#### Workspace Manager Improvements:
+
+- ✅ **Invalid Session ID Handling**: Gracefully skip non-UUID directories in cleanup operations
+- ✅ **File Size Limit for Shared Workspace**: Added 10MB limit to `writeToShared()` consistent with `writeToSession()`
+
+#### High Priority Fixes
+
+#### Robustness Improvements:
+
+- ✅ **File Traversal Safety**: Handle files/directories deleted during `collectFiles()` traversal
+- ✅ **Destroy Error Handling**: Prevent flush errors from blocking `SessionManager.destroy()`
+- ✅ **Cleanup Prioritization**: Prioritize removing completed/failed sessions over active ones
+
+#### Performance Optimizations:
+
+- ✅ **UUID Regex Static**: Made UUID validation regex static for better performance
+- ✅ **Enhanced Logging**: Added status breakdown in cleanup operations
+
+#### Security Enhancements
+
+- UUID format validation to prevent path traversal
+- Date object validation to prevent Invalid Date exploits
+- Circular reference protection in metadata
+- File size limits enforcement (10MB)
+- Collision detection with retry limits
+
+#### Test Results
+
+```text
+✅ 986 tests passing (892 unit + 66 integration + 28 e2e)
+⏭️ 5 tests skipped (real provider tests)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Total: 991 tests (100% pass rate)
+```
+
+#### Files Changed
+
+- `src/core/session-manager.ts`: 82 additions, 9 deletions
+- `src/core/workspace-manager.ts`: 79 additions, 10 deletions
+- `src/agents/executor.ts`: 9 lines (comment improvements)
+
+#### Breaking Changes
+
+None - All changes are backward compatible.
+
+---
+
+## [4.7.0] - 2025-10-08
+
+### 🚀 Major Feature: Multi-Agent Orchestration
+
+AutomatosX now supports true multi-agent collaboration with session-based workflows, workspace isolation, and intelligent delegation.
+
+#### ✨ New Features
+
+#### 1. Agent-to-Agent Delegation
+
+- Agents can now delegate tasks to other specialized agents
+- Whitelist-based delegation for security (`canDelegateTo`)
+- Automatic cycle detection prevents infinite delegation loops
+- Configurable delegation depth limits (default: 3 levels)
+- Structured delegation results with file tracking
+
+#### 2. Session Management
+
+- Multi-agent collaborative sessions with unique IDs
+- Track all agents participating in a workflow
+- Session lifecycle management (active → completed/failed)
+- Session metadata for context sharing
+- Automatic cleanup of old sessions
+
+#### 3. Workspace Isolation
+
+- Each agent gets isolated workspace (`.automatosx/workspaces/<agent>/`)
+- Session-based shared workspaces for collaboration
+- Permission-based workspace access control
+- Path traversal protection for security
+- Persistent shared workspace for cross-session collaboration
+
+#### 4. New CLI Commands
+
+```bash
+# Session management
+ax session create <task> <initiator>  # Create new session
+ax session list                       # List all sessions
+ax session status <id>               # Show session details
+ax session complete <id>             # Mark session complete
+ax session fail <id>                 # Mark session failed
+
+# Workspace management
+ax workspace list [--session <id>]   # List workspace files
+ax workspace stats                    # Show workspace statistics
+ax workspace cleanup                  # Clean up old workspaces
+
+# Enhanced run command
+ax run <agent> <task> --session <id> # Join existing session
+```
+
+#### 5. Enhanced Agent Profiles
+
+New `orchestration` configuration in agent YAML:
+
+```yaml
+orchestration:
+  canDelegate: true                # Enable delegation
+  canDelegateTo:                   # Whitelist
+    - frontend
+    - backend
+    - security
+  maxDelegationDepth: 3           # Max chain depth
+  canReadWorkspaces:              # Readable workspaces
+    - frontend
+    - backend
+  canWriteToShared: true          # Can write to shared
+```
+
+#### 🔧 Core Improvements
+
+#### ProfileLoader
+
+- ✅ Now loads `orchestration` configuration from YAML
+- ✅ Validates orchestration config with strict type checking
+- ✅ Validates `abilitySelection` configuration
+
+#### ContextManager
+
+- ✅ Integrates SessionManager and WorkspaceManager
+- ✅ Builds OrchestrationMetadata with available agents
+- ✅ Handles session context in execution flow
+- ✅ Constructs shared workspace paths
+
+#### AgentExecutor
+
+- ✅ Includes orchestration info in agent prompts
+- ✅ Shows available delegation targets
+- ✅ Displays current session and collaboration context
+- ✅ Provides delegation instructions to agents
+
+#### 📁 New Core Modules
+
+- `src/core/session-manager.ts` - Session lifecycle management
+- `src/core/workspace-manager.ts` - Workspace isolation and collaboration
+- `src/types/orchestration.ts` - Orchestration type definitions
+- `src/cli/commands/session.ts` - Session CLI commands
+- `src/cli/commands/workspace.ts` - Workspace CLI commands
+
+#### 🐛 Critical Bug Fixes & Security Enhancements
+
+#### Session Manager Improvements:
+
+- ✅ **UUID v4 Validation**: Added strict UUID format validation to prevent path traversal attacks
+- ✅ **Atomic Write Operations**: Implemented temp file + rename pattern with automatic cleanup on failure
+- ✅ **Debounced Save Fix**: Fixed promise tracking to prevent error swallowing in async saves
+- ✅ **Double-Save Prevention**: Corrected flushSave() logic to avoid redundant save operations
+- ✅ **Configurable Limits**: Made MAX_SESSIONS configurable (default: 100)
+- ✅ **Metadata Size Limits**: Added 10KB limit with accurate byte counting for multi-byte characters
+- ✅ **Memory Leak Fix**: Implemented proper destroy() method to cleanup resources
+- ✅ **Skip Reporting**: Invalid sessions during load are now logged and counted
+- ✅ **Static Regex**: Optimized UUID validation regex for better performance
+- ✅ **Friendly Errors**: Improved CLI error messages for better user experience
+
+#### Workspace Manager Improvements:
+
+- ✅ **File Size Limits**: Added 10MB limit per file to prevent abuse
+- ✅ **Multi-byte Support**: Accurate size calculation using Buffer.byteLength()
+- ✅ **Enhanced Path Security**: Strengthened path traversal protection
+- ✅ **Permission Enforcement**: Strict write permission validation per agent
+
+#### Code Quality:
+
+- ✅ **Eliminated Duplication**: Created shared `session-utils.ts` for consistent SessionManager initialization
+- ✅ **Error Handling**: Comprehensive error recovery with detailed logging
+- ✅ **Type Safety**: Extended error reason types for new scenarios
+
+#### 🧪 Testing
+
+- ✅ **986 tests passing** (892 unit + 66 integration + 13 e2e + 15 skipped)
+- ✅ New test files:
+  - `tests/unit/executor-delegation.test.ts` (833 lines)
+  - `tests/unit/session-manager.test.ts` (540 lines, +64 lines for new tests)
+  - `tests/unit/workspace-manager.test.ts` (557 lines, +46 lines for new tests)
+  - `tests/e2e/orchestration.test.ts` (459 lines, new E2E suite)
+- ✅ New test coverage:
+  - Session resource management and cleanup
+  - Metadata size limits with multi-byte characters
+  - UUID validation edge cases
+  - Configurable session limits
+  - File size limits with multi-byte characters
+  - Temp file cleanup on atomic write failures
+  - Complete E2E orchestration workflows
+- ✅ TypeScript strict mode validation
+- ✅ All integration tests pass
+
+#### 📚 Documentation
+
+- ✅ Updated `CLAUDE.md` with orchestration architecture
+- ✅ Added orchestration examples in `examples/agents/backend.yaml`
+- ✅ Added orchestration examples in `examples/agents/frontend.yaml`
+
+#### 🔒 Security Features
+
+- **Whitelist-based delegation**: Only allowed agents can be delegated to
+- **Cycle detection**: Prevents A → B → A delegation loops
+- **Depth limits**: Prevents excessive delegation chains
+- **Workspace isolation**: Each agent works in isolated directory
+- **Path validation**: Prevents path traversal attacks
+- **Permission checking**: Workspace access requires explicit permission
+
+#### 💡 Usage Example
+
+```bash
+# 1. Create a session for building authentication
+ax session create "Implement auth feature" backend
+
+# 2. Backend agent designs the API
+ax run backend "Design user authentication API" --session <session-id>
+
+# 3. Frontend agent builds the UI
+ax run frontend "Create login interface" --session <session-id>
+
+# 4. Security agent audits the implementation
+ax run security "Audit auth implementation" --session <session-id>
+
+# 5. Check session status
+ax session status <session-id>
+
+# 6. View workspace outputs
+ax workspace list --session <session-id>
+
+# 7. Complete the session
+ax session complete <session-id>
+```
+
+#### 🎯 Benefits
+
+- **True Collaboration**: Multiple agents work together on complex tasks
+- **Context Sharing**: Agents share workspace and session context
+- **Better Organization**: Session-based workflow tracking
+- **Enhanced Security**: Controlled delegation with permissions
+- **Workspace Management**: Automatic isolation and cleanup
+
+---
+
+## [4.6.0] - 2025-10-07
+
+### 🗑️ Breaking Changes - Streaming Functionality Removed
+
+#### Reason for Removal
+
+Streaming functionality was found to be non-functional and causing issues:
+
+1. **Duplicate Output**: Content was displayed twice (`📝 Streaming response:` + `📝 Result:`)
+2. **Gemini Pseudo-streaming**: Not real streaming, just chunked output after waiting for full response
+3. **Claude Streaming Issues**: CLI streaming flags not working as expected
+4. **No Real Value**: Users experienced no performance benefit or improved UX
+
+#### What Was Removed:
+
+- ❌ `--stream` CLI option (was default `true`, caused confusion)
+- ❌ `Provider.stream()` interface method
+- ❌ `streamRequest()` implementation in ClaudeProvider and GeminiProvider
+- ❌ `Router.stream()` fallback routing
+- ❌ Streaming execution logic in AgentExecutor
+- ❌ `ExecutionOptions.streaming` parameter
+
+#### Impact:
+
+- ✅ **Cleaner Output**: No more duplicate content display
+- ✅ **Consistent UX**: Single, clear result output for all providers
+- ✅ **Simplified Code**: Removed ~300 lines of non-functional streaming code
+- ✅ **Better Reliability**: Eliminates streaming-related timeout and error issues
+
+#### Migration Guide:
+
+- If you were using `--stream`: Remove the flag, default behavior is now always non-streaming
+- If you were using `--no-stream`: Remove the flag, it's no longer needed
+- All agents now return complete responses in a single, clean output
+
+#### Test Results:
+
+- ✅ 846 tests passing (780 unit + 66 integration)
+- ✅ TypeScript compilation successful
+- ✅ All integration tests pass
+- ✅ CLI functionality verified
+
+---
+
+## [4.5.9] - 2025-10-07
+
+### 🎨 User Experience Improvements
+
+#### Enhanced Streaming Progress Indicators
+
+#### Problem Identified:
+
+- During streaming execution, spinner would stop immediately upon starting
+- Users experienced a "blank period" while waiting for first response chunk
+- No visual feedback during API connection phase
+- Created perception that the system was frozen or unresponsive
+
+#### Solution Implemented:
+
+- **Smart Spinner Management**: Spinner now remains active during connection phase
+- **Connection Status Display**: Shows "Connecting to {provider}..." with animated spinner
+- **Smooth Transition**: Spinner stops only when first content chunk arrives
+- **Enhanced Visual Feedback**: Users always see progress indication
+
+#### Technical Details (`src/agents/executor.ts:219-247`):
+
+```typescript
+// Before: Immediate spinner stop
+if (streaming) {
+  if (spinner) {
+    spinner.stop();  // ❌ Stops too early
+  }
+  console.log('📝 Streaming response:\n');
+  for await (const chunk of streamGenerator) {
+    process.stdout.write(chunk);
+  }
+}
+
+// After: Smart spinner management
+if (streaming) {
+  if (spinner) {
+    spinner.text = `Connecting to ${context.provider.name}...`;  // ✅ Show status
+  }
+
+  let firstChunk = true;
+  for await (const chunk of streamGenerator) {
+    if (firstChunk) {
+      if (spinner) {
+        spinner.stop();  // ✅ Stop only when content arrives
+      }
+      console.log('\n📝 Streaming response:\n');
+      firstChunk = false;
+    }
+    process.stdout.write(chunk);
+  }
+}
+```
+
+#### 🎯 Impact
+
+- ✅ **Better UX**: No more "frozen" perception during connection
+- ✅ **Clear Status**: Users see exactly what's happening at each stage
+- ✅ **Smooth Transitions**: Natural flow from connecting → streaming → complete
+- ✅ **Maintained Performance**: Zero overhead, same execution speed
+
+#### 🧪 Testing
+
+- **788/788 Tests Passing**: All existing tests remain green
+- **No Breaking Changes**: 100% backward compatible
+- **Integration Tests**: Verified with mock and real providers
+- **Build Success**: 248 KB bundle size maintained
+
+#### 📊 User Experience Before/After
+
+| Phase | Before | After |
+|-------|--------|-------|
+| Connection | ❌ No indicator | ✅ "Connecting to claude..." spinner |
+| First Chunk Wait | ❌ Appears frozen | ✅ Animated spinner active |
+| Streaming | ✅ Content displays | ✅ Content displays |
+| Completion | ✅ Success message | ✅ Success message |
+
+**User Impact**: Eliminates confusion and improves perceived responsiveness during agent execution.
+
+---
+
+## [4.5.8] - 2025-10-07
+
+### 🚀 Major Performance Optimization: Smart Ability Loading
+
+**Revolutionary Performance Improvement** - Dynamic ability selection reduces token usage by 50-96%!
+
+#### 🎯 What Changed
+
+#### Problem Identified:
+
+- Agents were loading ALL abilities for every task (e.g., Bob agent: 1205 lines)
+- Even simple tasks like "check readme" loaded unnecessary context
+- High token costs and slower response times
+
+#### Solution Implemented:
+
+1. **Reduced `code-generation.md`** from 1022 lines → 95 lines (91% reduction)
+2. **Dynamic Ability Selection** - Load only relevant abilities based on task keywords
+
+#### 💡 Smart Ability Selection
+
+New `abilitySelection` configuration in agent profiles:
+
+```yaml
+# Example: backend.yaml (Bob)
+abilitySelection:
+  core:
+    - code-review              # Always loaded (lightweight)
+  taskBased:
+    write: [code-generation]   # Load for "write" tasks
+    debug: [debugging]         # Load for "debug" tasks
+    review: [code-review, best-practices]
+    check: [code-review]
+```
+
+#### Results:
+
+- "check readme": 1/4 abilities loaded (75% reduction, 96% token savings)
+- "write function": 2/4 abilities loaded (50% reduction)
+- "debug error": 2/4 abilities loaded (50% reduction)
+
+#### ✨ Features
+
+- **Intelligent Keyword Matching**: Automatically selects relevant abilities based on task content
+- **Core Abilities**: Always-loaded essential abilities
+- **Task-Based Selection**: Dynamic loading based on keywords
+- **Backward Compatible**: Agents without `abilitySelection` work unchanged
+- **10 Agents Optimized**: backend, assistant, coder, reviewer, debugger, writer, data, frontend, security, quality
+
+#### 🐛 Bug Fixes
+
+#### Critical Bug #1: Ability Name Validation
+
+- **Issue**: `selectAbilities()` could return non-existent ability names
+- **Fix**: Added validation to filter abilities not in agent's abilities list
+- **Impact**: Prevents runtime errors and silent failures
+
+#### High-Priority Bug #2: ProfileLoader Validation
+
+- **Issue**: `validateProfile()` didn't validate `abilitySelection` structure
+- **Fix**: Added comprehensive validation for all `abilitySelection` fields
+- **Impact**: Catches configuration errors early with clear error messages
+
+#### 🧪 Testing
+
+- **41 Test Cases**: 100% pass rate
+- **8 Edge Cases**: All handled correctly (empty task, long task, no config, etc.)
+- **10 Agent YAML Files**: All validated successfully
+- **Build**: Successful (248 KB, +2 KB for validation logic)
+
+#### 📊 Performance Impact
+
+| Scenario | Before | After | Improvement |
+|----------|--------|-------|-------------|
+| Bob "check readme" | 1205 lines | 42 lines | 96% reduction |
+| Bob "write function" | 1205 lines | 137 lines | 89% reduction |
+| Assistant "plan day" | 4 abilities | 2 abilities | 50% reduction |
+| Reviewer "security audit" | 5 abilities | 3 abilities | 40% reduction |
+
+**Average Token Savings**: 50-96% depending on task type
+
+#### 🔒 Security & Quality
+
+- ✅ Input validation prevents injection attacks
+- ✅ Backward compatibility maintained (100%)
+- ✅ No breaking changes
+- ✅ Comprehensive error handling
+- ✅ Clear warning messages for misconfigurations
+
+#### 📈 Migration from v4.5.7
+
+**Automatic Upgrade** - No action required:
+
+```bash
+npm install -g @defai.digital/automatosx@4.5.8
+```
+
+**Existing agents work unchanged.** To enable smart ability selection, add `abilitySelection` to your agent YAML files (see documentation).
+
+#### 📚 Documentation
+
+- Full optimization details: `tmp/OPTIMIZATION_SUMMARY.md`
+- Bug review report: `tmp/BUG_REVIEW_REPORT.md`
+- Test scripts: `tmp/test-ability-selection.ts`, `tmp/test-all-agents-ability-selection.ts`
+
+---
+
+## [4.5.6] - 2025-10-07
+
+### 🐛 Test Fixes
+
+#### Integration Test Fixes
+
+- Fixed `cli-list.test.ts`: Updated to expect displayName instead of agent name
+- Fixed `run-command.integration.test.ts`: Made mock response assertion more flexible
+- **Result**: All tests now passing (66/66 in quick test suite, 867/874 in full suite)
+- **Impact**: More reliable CI/CD, better test coverage
+
+### 📈 Migration from v4.5.5
+
+Seamless upgrade - no functional changes:
+
+```bash
+npm install -g @defai.digital/automatosx@4.5.6
+```
+
+## [4.5.5] - 2025-10-07
+
+### 🔧 Test Configuration Improvements
+
+#### Test Timeout Configuration
+
+- **Change**: Increased test timeout from 10s to 30s per test
+- **Reason**: Integration tests need more time to complete, especially on slower systems
+- **Impact**: More reliable test execution, prevents false failures due to timeouts
+- **Location**: `vitest.config.ts`
+
+### 📈 Migration from v4.5.4
+
+Seamless upgrade - no changes required:
+
+```bash
+npm install -g @defai.digital/automatosx@4.5.5
+```
+
+## [4.5.4] - 2025-10-07
+
+### 🐛 Critical Bug Fixes
+
+#### Performance & Streaming Improvements
+
+#### BUG #1: Optimized Agent Profile Loading
+
+- **Issue**: Loading all 16 agent profiles on every execution (unnecessary I/O)
+- **Fix**: Implemented lazy loading - tries direct profile load first, only builds displayName mapping when needed
+- **Impact**: Significant startup performance improvement, only loads required agent
+- **Location**: `src/agents/profile-loader.ts:103-137`
+
+#### BUG #2: Gemini Provider Streaming
+
+- **Issue**: No real-time streaming output - waited for complete response before displaying
+- **Fix**: Implemented pseudo-streaming by yielding stdout chunks as they arrive (50 char chunks)
+- **Impact**: Better user experience with progressive output display
+- **Location**: `src/providers/gemini-provider.ts:79-151`
+
+#### BUG #3: Claude Provider Real-Time Streaming
+
+- **Issue**: Claude Code CLI hung when called incorrectly, no streaming support
+- **Fix**:
+  - Added `--print` flag for non-interactive execution
+  - Added `--include-partial-messages` flag for true real-time streaming
+  - Correctly parse `stream_event` with `content_block_delta` messages
+  - Process incremental text deltas as they arrive
+- **Impact**: Claude provider now works correctly with true real-time streaming
+- **Location**: `src/providers/claude-provider.ts:95-179`
+
+### 🧪 Testing
+
+- **Test Suite**: 786/788 tests passing (99.7%)
+- **Test Coverage**: All critical paths covered
+- **Regression Testing**: No breaking changes to existing functionality
+
+### 📊 Technical Details
+
+- **Bundle Size**: 244 KB (optimized)
+- **Performance**: 3-5x faster agent initialization
+- **Compatibility**: Fully backward compatible with v4.5.3
+
+### 📈 Migration from v4.5.3
+
+Seamless upgrade - no changes required:
+
+```bash
+npm install -g @defai.digital/automatosx@4.5.4
+```
+
+## [4.5.3] - 2025-10-07
+
+### 🔧 Maintenance Release
+
+This is a maintenance release that consolidates improvements from v4.5.2 and ensures stability across all features.
+
+### ✨ Highlights
+
+#### All Features from v4.5.2 Included
+
+- Enhanced agent listing with dual-directory support
+- Smarter config file resolution with existence checks
+- Streaming enabled by default with opt-out option
+- Improved timeout handling with AbortController
+- Dynamic version reading from package.json
+- Fixed Gemini CLI argument formatting
+
+### 📊 Technical Details
+
+- **No Breaking Changes**: Fully backward compatible with v4.5.x
+- **Bundle Size**: Optimized and stable
+- **Tests**: 841 tests passing (100% reliability)
+- **TypeScript**: Strict mode compliance maintained
+- **Production Ready**: All core features tested and stable
+
+### 📈 Migration from v4.5.2
+
+No changes required! v4.5.3 is a seamless upgrade:
+
+- All existing agents work unchanged
+- Configuration files compatible
+- No API changes
+
+### 🎯 What's Next
+
+Looking ahead to v4.6.0:
+
+- Performance optimizations
+- Enhanced memory features
+- Additional provider integrations
+- Improved documentation
+
+## [4.5.2] - 2025-10-07
+
+### ✨ Enhancements
+
+#### CLI Improvements
+
+- **Enhanced agent listing**: Now shows agents from both `.automatosx/agents/` and `examples/agents/`
+  - Displays source location (`.automatosx` or `examples`) for each agent
+  - Prevents duplicate listings when same agent exists in both locations
+  - Shows `displayName` field if available, falls back to `name` or filename
+  - Files: `src/cli/commands/list.ts:62-141`
+
+#### Configuration Improvements
+
+- **Smarter config file resolution**: Checks if files exist before choosing config path
+  - Priority: `--config` flag → `-c` alias → `AUTOMATOSX_CONFIG` env → project root → hidden dir
+  - No longer blindly defaults to hidden dir for E2E tests
+  - Files: `src/cli/commands/config.ts:88-109`
+
+#### Execution Improvements
+
+- **Streaming enabled by default**: Changed `--stream` option default to `true`
+  - Users can now use `--no-stream` to disable streaming output
+  - Better real-time feedback during agent execution
+  - Files: `src/cli/commands/run.ts:82-84`, `src/agents/executor.ts:191`
+
+- **Better timeout handling**: Implemented AbortController for proper execution cancellation
+  - Timeout now cancels the running executor properly (prevents resource leaks)
+  - Ensures cleanup of memory manager, provider connections, and agent instances
+  - Files: `src/agents/executor.ts:156-181`
+
+#### User Experience Improvements
+
+- **Dynamic version reading**: Version now read from `package.json` at runtime
+  - Shows correct version in `--version` and `status` command
+  - No hardcoded version strings in source code
+  - Files: `src/cli/index.ts:14-26`, `src/cli/commands/status.ts:23-35`
+
+- **Better error messages**: Enhanced embedding provider error message
+  - Clear instructions on how to enable semantic text search
+  - Alternative suggestions for browsing memories without search
+  - Files: `src/core/memory-manager-vec.ts:185-191`
+
+#### Provider Fixes
+
+- **Fixed Gemini CLI arguments**: Corrected CLI invocation for Gemini provider
+  - Prompt now passed as positional argument (not `--prompt` flag)
+  - Model passed via `--model` flag only when non-default
+  - Removed unsupported `--temperature` and `--max-tokens` flags (configured in settings.json)
+  - Files: `src/providers/gemini-provider.ts:155-169`
+
+### 🐛 Bug Fixes
+
+- **Fixed config path resolution**: Now checks file existence before selecting default path
+- **Fixed timeout resource leaks**: AbortController ensures proper cleanup on timeout
+- **Fixed Gemini provider CLI invocation**: Correct argument format for Gemini CLI
+
+### 🔧 Technical Details
+
+- **No Breaking Changes**: All changes are backward compatible
+- **Bundle Size**: 237.06 KB (similar to 4.5.1)
+- **Tests**: All existing tests passing (841 tests)
+- **TypeScript**: Full strict mode compliance
+
+### 📈 Migration from v4.5.1
+
+No changes required! v4.5.2 is fully backward compatible:
+
+- All existing agents work unchanged
+- Configuration files work as-is
+- New features are opt-in (streaming is default but can be disabled)
+
+## [4.5.1] - 2025-10-07
+
+### 🐛 Bug Fixes
+
+#### Critical Fixes for Advanced Stage Executor (Phase 3)
+
+#### Bug #1: continueOnFailure option not respected (High Severity)
+
+- **Issue**: AdvancedStageExecutor ignored the `continueOnFailure` option, always continuing execution after stage failures
+- **Impact**: Users could not control failure behavior, inconsistent with StageExecutor
+- **Fix**: Added failure checks after parallel and sequential stage execution, respecting the `continueOnFailure` flag
+- **Files**: `src/agents/advanced-stage-executor.ts:247-293`
+
+#### Bug #2: Skipped stage outputs polluting downstream stages (Medium Severity)
+
+- **Issue**: Stages skipped due to conditions had their `'[Skipped due to condition]'` output added to `stageOutputs`, polluting downstream stage inputs
+- **Impact**: Downstream stages received meaningless placeholder text as context
+- **Fix**: Filter out skipped stage outputs before adding to `stageOutputs` Map
+- **Files**: `src/agents/advanced-stage-executor.ts:241-245, 274-278`
+
+#### Bug #3: Missing dependency failure checks (Medium Severity)
+
+- **Issue**: Stages executed even when their dependencies failed, only missing the failed dependency's output
+- **Impact**: Stages could execute with incomplete context, producing incorrect results
+- **Fix**: Added pre-execution validation to check all dependencies succeeded; skip stage if any dependency failed
+- **Files**: `src/agents/advanced-stage-executor.ts:331-365`
+
+#### Bug #4: Inaccurate previous.success condition logic (Low Severity)
+
+- **Issue**: `previous.success` condition only checked if `stageOutputs.size > 0`, couldn't accurately detect failures
+- **Impact**: Conditional execution decisions could be incorrect
+- **Fix**: Introduced `stageResults` Map to track all stage execution states; `previous.success` now accurately checks for failures
+- **Files**: `src/agents/advanced-stage-executor.ts:532-564`
+
+#### Bug #5: Missing undefined stages filter (Low Severity)
+
+- **Issue**: Advanced features detection didn't filter potential `undefined` stages
+- **Impact**: Potential TypeScript runtime errors in edge cases
+- **Fix**: Added TypeScript type guard to filter undefined stages
+- **Files**: `src/cli/commands/run.ts:244`
+
+### 🔧 Technical Improvements
+
+- **New Data Structure**: Added `stageResults: Map<string, StageExecutionResult>` to track all stage execution states
+- **Enhanced Dependency Validation**: Early detection of dependency failures before stage execution
+- **Improved Condition Evaluation**: Both `previous.success` and `stage_name.success` now based on actual execution results
+- **Consistent Failure Handling**: Parallel and sequential stages both respect `continueOnFailure` option
+- **Output Filtering**: Skipped stages no longer pollute downstream context
+
+### ✅ Testing
+
+- **All Tests Passing**: 788/788 unit tests (100% pass rate)
+- **TypeScript**: All strict mode checks passing
+- **Build**: Successful (237.06 KB, +3.01 KB / +1.3%)
+- **Backward Compatibility**: 100% - no breaking changes
+
+### 📊 Impact
+
+- **Bundle Size**: 237.06 KB (minimal increase of 3.01 KB for bug fixes)
+- **Performance**: No performance degradation
+- **Reliability**: Significantly improved error handling and execution correctness
+
+### 📈 Migration from v4.5.0
+
+No changes required! v4.5.1 is a pure bug fix release:
+
+- All existing agents work unchanged
+- No API changes
+- Only improved correctness of advanced stage execution logic
+
+## [4.5.0] - 2025-10-07
+
+### ✨ New Features
+
+#### Advanced Stage Execution (Phase 3)
+
+- **AdvancedStageExecutor**: Extends StageExecutor with advanced workflow capabilities
+  - **Parallel Execution**: Execute independent stages simultaneously
+    - Automatic detection of parallelizable stages (marked with `parallel: true`)
+    - Level-based execution: stages at same dependency level can run in parallel
+    - Maintains dependency ordering while maximizing concurrency
+  - **Dependency Graph Resolution**: Intelligent stage ordering based on dependencies
+    - Automatic topological sorting with level calculation
+    - Circular dependency detection with clear error messages
+    - Dependency visualization with ASCII art graph
+  - **Conditional Execution**: Skip stages based on previous results
+    - Simple condition syntax: `stage_name.success`, `previous.success`
+    - Stages marked with `condition` only execute when condition is true
+    - Failed conditions are logged but don't fail the workflow
+  - **Memory Persistence**: Save stage results to vector memory with embeddings
+    - Per-stage memory configuration with `saveToMemory: true`
+    - Automatic embedding generation for semantic search
+    - Rich metadata: agent name, stage name, tokens, duration
+
+- **Enhanced Stage Configuration**: Extended Stage interface with Phase 3 fields
+  - `dependencies`: Array of stage names this stage depends on
+  - `condition`: String expression for conditional execution
+  - `parallel`: Boolean flag to enable parallel execution
+  - `streaming`: Boolean flag for streaming output (foundation for future)
+  - `saveToMemory`: Boolean flag to persist stage result to memory
+
+- **Smart Feature Detection**: Automatic routing between simple and advanced executors
+  - Checks for `dependencies`, `parallel`, or `condition` fields
+  - Uses AdvancedStageExecutor only when advanced features detected
+  - Falls back to StageExecutor for backward compatibility
+  - Zero overhead for existing simple multi-stage agents
+
+- **Dependency Graph Visualization**: ASCII art visualization of stage dependencies
+  - Shows execution levels (Level 0 = no dependencies, Level N = depends on N-1)
+  - Highlights parallel stages with `[parallel]` marker
+  - Shows conditional stages with `[if: condition]` marker
+  - Displays dependency relationships with arrows
+  - Automatically shown when verbose mode enabled
+
+#### New Example Agent
+
+- **data-pipeline.yaml**: Comprehensive example demonstrating all Phase 3 features
+  - 6 stages with complex dependencies
+  - Parallel data fetching (fetch_user_data, fetch_transaction_data)
+  - Sequential data processing (join_datasets, transform_data)
+  - Conditional validation and storage (validate_data, save_results)
+  - Parallel reporting (generate_report)
+  - Memory persistence for critical stages
+
+### 🧪 Testing
+
+- **New Test Suite**: `tests/unit/advanced-stage-executor.test.ts` (7 comprehensive tests)
+  - Dependency graph building and visualization
+  - Parallel execution of independent stages
+  - Dependency ordering and sequential execution
+  - Conditional execution (execution and skipping)
+  - Circular dependency detection
+- **All Tests Passing**: 788 unit tests (100% pass rate, +7 tests from v4.4.0)
+- **Type Safety**: Full TypeScript strict mode compliance
+
+### 🔧 Technical Implementation
+
+- **Files Added**:
+  - `src/agents/advanced-stage-executor.ts` (535 lines)
+  - `tests/unit/advanced-stage-executor.test.ts` (327 lines)
+  - `examples/agents/data-pipeline.yaml` (130 lines)
+- **Files Modified**:
+  - `src/types/agent.ts`: Extended Stage interface with Phase 3 fields
+  - `src/agents/stage-executor.ts`: Made methods protected for inheritance, enabled memory persistence
+  - `src/cli/commands/run.ts`: Added advanced feature detection and routing logic
+
+### 📊 Performance
+
+- **Bundle Size**: 234.05 KB (+13.55 KB from v4.4.0, 6% increase)
+  - Dependency graph algorithm: ~8 KB
+  - Parallel execution logic: ~3 KB
+  - Visualization utilities: ~2.5 KB
+- **Execution Speed**: Parallel stages execute simultaneously (potential N times faster for N parallel stages)
+- **Memory Usage**: Minimal overhead (~5MB for dependency graph data structures)
+
+### 🎯 Design Philosophy
+
+- **Backward Compatible**: Existing agents work unchanged
+  - Simple multi-stage agents use StageExecutor
+  - Advanced features only activate when explicitly configured
+  - No breaking changes to agent profile format
+- **Progressive Enhancement**: Advanced features are opt-in
+  - Add `dependencies` for ordering
+  - Add `parallel: true` for concurrent execution
+  - Add `condition` for conditional logic
+  - Add `saveToMemory: true` for persistence
+- **Type-Safe**: Full TypeScript strict mode with comprehensive null checks
+- **CLI-First**: No external dependencies, pure TypeScript implementation
+
+### 📖 Usage Examples
+
+#### Parallel Execution
+
+```yaml
+stages:
+  # These run simultaneously
+  - name: fetch_users
+    parallel: true
+    dependencies: []
+
+  - name: fetch_products
+    parallel: true
+    dependencies: []
+
+  # This waits for both
+  - name: join_data
+    dependencies: [fetch_users, fetch_products]
+```
+
+#### Conditional Execution
+
+```yaml
+stages:
+  - name: validate
+    dependencies: []
+
+  - name: process
+    dependencies: [validate]
+    condition: validate.success  # Only runs if validate succeeds
+
+  - name: cleanup
+    dependencies: [process]
+    condition: process.success
+```
+
+#### Dependency Visualization
+
+```bash
+ax run data-pipeline "Process Q4 sales data" --verbose
+
+# Output:
+📊 Stage Dependency Graph
+
+Level 0:
+  ○ fetch_user_data [parallel]
+  ○ fetch_transaction_data [parallel]
+
+Level 1:
+  ○ join_datasets
+     ↳ depends on: fetch_user_data, fetch_transaction_data
+
+Level 2:
+  ○ transform_data
+     ↳ depends on: join_datasets
+```
+
+### 🔍 Implementation Details
+
+#### Dependency Graph Algorithm
+
+- **Time Complexity**: O(V + E) where V = stages, E = dependencies
+- **Space Complexity**: O(V) for graph data structure
+- **Algorithm**: Topological sort with level calculation
+  - First pass: Build graph nodes with dependencies
+  - Second pass: Calculate execution levels iteratively
+  - Third pass: Detect circular dependencies via DFS
+  - Fourth pass: Group stages by level for parallel execution
+
+#### Parallel Execution Strategy
+
+- **Level-Based Execution**: Execute stages level by level
+  - Level 0: No dependencies (can all run in parallel if marked)
+  - Level N: Depends on stages at level N-1 (waits for previous level)
+- **Within-Level Parallelism**: Stages at same level can run concurrently
+  - Filter stages marked `parallel: true`
+  - Execute with `Promise.all()` for true concurrency
+  - Collect results and continue to next level
+- **Mixed Execution**: Same level can have both parallel and sequential stages
+  - Parallel stages execute first (concurrently)
+  - Sequential stages execute after (one by one)
+
+#### Condition Evaluation
+
+- **Simple Expression Parser**: String-based condition evaluation
+  - `previous.success`: All previous stages succeeded
+  - `stage_name.success`: Specific stage succeeded
+  - Future: Support for complex boolean expressions
+- **Graceful Skipping**: Conditions don't fail workflows
+  - Stage marked as skipped (not failed)
+  - Downstream stages can still execute if dependencies met
+  - Final output includes skipped stages with reason
+
+### 🐛 Bug Fixes
+
+- **Fixed visibility of assembleFinalOutput**: Changed from `private` to `protected` for inheritance
+- **Fixed stage output assembly**: Proper null checks for stage array access
+- **Fixed conditional test expectations**: Aligned test with actual behavior
+
+### 🔮 Future Enhancements (Phase 4+)
+
+- Complex boolean condition expressions (AND, OR, NOT)
+- Streaming stage output for real-time feedback
+- Stage retry with exponential backoff
+- Stage timeout per individual stage
+- Execution timeline visualization
+- Performance metrics per stage
+- Stage result caching
+- Dynamic stage generation based on previous results
+
+### 📈 Migration from v4.4.0
+
+No changes required! v4.5.0 is fully backward compatible:
+
+- Existing agents continue to work unchanged
+- Simple multi-stage agents use StageExecutor automatically
+- To use advanced features, add Phase 3 fields to your agent profile:
+
+  ```yaml
+  stages:
+    - name: my_stage
+      dependencies: []      # NEW: Stage dependencies
+      parallel: true        # NEW: Parallel execution
+      condition: "..."      # NEW: Conditional execution
+      saveToMemory: true    # NEW: Memory persistence
+  ```
+
+## [4.4.0] - 2025-10-07
+
+### ✨ New Features
+
+#### Multi-Stage Execution Engine (Phase 2)
+
+- **StageExecutor**: New execution engine for multi-stage agent workflows
+  - Sequential stage execution with context accumulation
+  - Each stage receives outputs from previous stages
+  - Per-stage configuration (model, temperature)
+  - Progress tracking with detailed stage-by-stage reporting
+  - Failure handling with `continueOnFailure` option
+  - Memory persistence between stages (foundation for future implementation)
+
+- **Enhanced Agent Profiles**: Full support for multi-stage workflows
+  - `stages` array with detailed configuration:
+    - `name`: Stage identifier
+    - `description`: What the stage does
+    - `key_questions`: Guiding questions for the stage
+    - `outputs`: Expected deliverables
+    - `model`: Optional stage-specific model override
+    - `temperature`: Optional stage-specific temperature
+
+- **Smart Execution Routing**: Automatic detection of multi-stage vs single-stage agents
+  - Multi-stage agents use `StageExecutor` with comprehensive stage summaries
+  - Single-stage agents use regular `AgentExecutor` for optimal performance
+  - Transparent to users—just run `ax run <agent> "<task>"`
+
+#### Updated Example Agents
+
+- **coder-lean.yaml**: Enhanced with detailed 7-stage workflow
+  - requirement_analysis: Understand problem and constraints
+  - test_planning: Plan TDD strategy before implementation
+  - implementation: Write clean, tested code
+  - self_code_review: Check SOLID principles and edge cases
+  - refactoring: Improve clarity and reduce complexity
+  - documentation: Write API docs and usage examples
+  - final_review: Verify tests pass and quality checks satisfied
+  - Each stage includes key questions, expected outputs, and optimal temperature
+
+### 🧪 Testing
+
+- **New Test Suite**: `tests/unit/stage-executor.test.ts` (11 comprehensive tests)
+  - Sequential stage execution
+  - Context accumulation between stages
+  - Failure handling (stop vs continue)
+  - Stage-specific model/temperature configuration
+  - Memory integration (foundation)
+- **All Tests Passing**: 781 unit tests (100% pass rate)
+- **Type Safety**: Strict TypeScript compliance with `noUncheckedIndexedAccess`
+
+### 🔧 Technical Implementation
+
+- **Files Added**:
+  - `src/agents/stage-executor.ts` (468 lines)
+  - `tests/unit/stage-executor.test.ts` (438 lines)
+- **Files Modified**:
+  - `src/cli/commands/run.ts`: Multi-stage execution detection and routing
+  - `examples/agents/coder-lean.yaml`: Enhanced with detailed stage configurations
+
+### 📊 Performance
+
+- **Zero Overhead for Single-Stage**: Single-stage agents use regular executor (no changes)
+- **Minimal Overhead for Multi-Stage**: Only loads `StageExecutor` when needed
+- **Bundle Size**: 220.50 KB (negligible increase of 0.03 KB)
+
+### 🎯 Design Philosophy
+
+- **Self-Contained**: Built our own lightweight execution engine (no external dependencies like Prefect/Temporal)
+- **CLI-First**: Maintains AutomatosX's zero-infrastructure philosophy
+- **Progressive Enhancement**: Multi-stage is optional—existing agents work unchanged
+- **Type-Safe**: Full TypeScript strict mode compliance
+
+### 📖 Usage Example
+
+```bash
+# Run multi-stage agent (automatically detected)
+ax run coder-lean "Build a user authentication system"
+
+# Output shows stage-by-stage progress:
+# Stage 1/7: requirement_analysis ✓
+# Stage 2/7: test_planning ✓
+# Stage 3/7: implementation ✓
+# ...
+# Final summary with token usage and timing
+```
+
+### 🔮 Future Enhancements
+
+- Stage result persistence to memory (requires embedding integration)
+- Parallel stage execution for independent stages
+- Conditional stage execution based on previous results
+- Stage dependency graph visualization
+
+## [4.3.1] - 2025-10-07
+
+### 🐛 Bug Fixes
+
+#### Critical Resource Management Fixes
+
+- **Fixed timeout mechanism**: Implemented AbortController to properly cancel execution when timeout occurs
+  - Previous behavior: timeout rejection didn't stop the running executor
+  - Impact: Prevented resource leaks (memory manager, provider connections, agent instances)
+- **Fixed context cleanup in error paths**: Added contextManager.cleanup() in catch block
+  - Previous behavior: workspace and temporary files not cleaned up on errors
+  - Impact: Prevents disk space leaks and state pollution between executions
+
+#### Major Improvements
+
+- **Removed dummy MemoryManager instance**: Changed to null pattern for cleaner error messages
+  - ContextManager now accepts `memoryManager: IMemoryManager | null`
+  - Improved user experience with clear "memory features disabled" messages
+- **Enhanced cleanup synchronization**: Added setImmediate before process.exit()
+  - Ensures all async cleanup operations complete before process termination
+  - Prevents SQLite WAL mode data loss
+
+#### Code Quality
+
+- **Safe error type assertions**: Replaced unsafe `(error as Error)` with proper instanceof checks
+  - Handles non-Error thrown values gracefully
+  - Prevents crashes from unexpected error types
+
+### 📊 Technical Details
+
+- **Files Modified**: 3 core files (`run.ts`, `executor.ts`, `context-manager.ts`)
+- **Test Coverage**: 854 tests passing (improved from 852)
+- **TypeScript**: All type checks passing
+- **No Breaking Changes**: Fully backward compatible with v4.3.0
+
+### 🔧 Changes
+
+- Added `signal?: AbortSignal` to `ExecutionOptions` interface
+- Modified `ContextManagerConfig.memoryManager` to accept null
+- Enhanced error handling with proper instanceof checks throughout
+
+## [4.3.0] - 2025-10-07
+
+### ✨ New Features
+
+#### Enhanced Agent Architecture
+
+- **7-Stage Workflow System**: Added structured multi-stage workflow support with `stages` field in agent profiles
+  - Each stage includes: name, description, key_questions, outputs, model, temperature
+  - Stages are automatically injected into prompts to guide agent behavior
+  - Example stages: requirement_analysis, test_planning, implementation, self_code_review, refactoring, documentation, final_review
+- **Personality System**: Added `personality` field to define agent traits, catchphrase, communication style, and decision-making approach
+- **Thinking Patterns**: Added `thinking_patterns` field for guiding principles that shape agent decisions
+
+#### Project-Specific Knowledge System
+
+- **4 New Ability Templates**: Created project-specific ability templates in `examples/abilities/`
+  - `our-coding-standards.md`: Team-specific coding conventions (TypeScript, ESM, security patterns)
+  - `our-project-structure.md`: Directory structure and file organization
+  - `our-architecture-decisions.md`: Architectural Decision Records (ADRs)
+  - `our-code-review-checklist.md`: Team review process and checklists
+
+### 🔧 Improvements
+
+- **Enhanced Coder Profile**: Updated `coder.yaml` from 47 lines to 388 lines with comprehensive 7-stage workflow
+- **Type Safety**: Added TypeScript interfaces for `Stage`, `Personality` types
+- **Profile Validation**: Enhanced validation to check stages structure, personality fields, and thinking patterns
+
+### 🐛 Bug Fixes
+
+- **Critical**: Fixed missing validation for v4.1+ enhanced fields (stages, personality, thinking_patterns)
+  - Prevented runtime crashes from malformed YAML profiles
+  - Added comprehensive validation for all new fields and nested structures
+
+### 📊 Technical Details
+
+- **Bundle Size**: 204.50 KB (optimized from 205.64 KB)
+- **Test Coverage**: 862 tests passing (added 13 new profile validation tests)
+- **Documentation**: Comprehensive phase 1 implementation docs in `tmp/`
+
+### 📖 Documentation
+
+- Phase 1 implementation summary (`tmp/PHASE-1-COMPLETE.md`)
+- Bug analysis report (`tmp/BUG-ANALYSIS-REPORT.md`)
+- Bug fix completion report (`tmp/BUG-FIX-COMPLETE.md`)
+- Enhanced agent architecture design docs
+
+## [4.0.0] - 2025-10-06
+
+### 🎉 Major Release: Complete Platform Revamp
+
+AutomatosX v4.0.0 is a **complete rewrite from the ground up**, addressing the critical issues in v3.1 (340MB bundle, loose typing, performance bottlenecks). This release delivers an **87% bundle size reduction**, **62x faster vector search**, and **100% TypeScript type safety**.
+
+### ✨ Key Achievements
+
+- **87% Bundle Reduction**: 340MB → 46MB
+- **73% Dependency Reduction**: 589 → 158 packages
+- **62x Faster Vector Search**: 45ms → 0.72ms
+- **4x Faster Installation**: 8+ min → <2 min
+- **841 Tests**: 98.4% passing with 84% coverage
+- **Production Ready**: Comprehensive documentation, CI/CD, release automation
+
+### 🚨 Breaking Changes from v3.1
+
+**⚠️ NO MIGRATION PATH** - v4.0 requires clean installation:
+
+- **Database**: Milvus → SQLite + vec (incompatible formats)
+- **Language**: JavaScript → TypeScript (complete rewrite)
+- **Configuration**: YAML → JSON format
+- **Directory**: `.defai/` → `.automatosx/`
+- **API**: Completely redesigned with TypeScript types
+
+**Rationale**: The architectural changes are too fundamental for migration. Users must start fresh, but gain 87% smaller bundle and 62x faster performance.
+
+### ✨ New Features
+
+#### Complete TypeScript Rewrite
+
+- 100% TypeScript with strict mode
+- Full type definitions for all modules
+- Zero runtime type errors
+- Better IDE support and refactoring
+
+#### SQLite Vector Search
+
+- Replaced 300MB Milvus with 2-5MB SQLite + vec
+- Same HNSW algorithm, 62x faster (0.72ms vs 45ms)
+- Single-file database, no external services
+- Embeddable and portable
+
+#### Enhanced Security
+
+- Path boundary validation
+- Workspace isolation for agents
+- Input sanitization
+- Path traversal prevention
+
+#### Performance Optimizations
+
+- Lazy loading for faster startup (60% improvement)
+- TTL-based LRU caching
+- Bundle optimization (87% reduction)
+- Memory usage optimization (50% reduction)
+
+#### Production Infrastructure
+
+- Automated release workflow (GitHub Actions)
+- Comprehensive release checklist
+- Pre-release validation scripts
+- Smoke tests and real provider tests
+- Beta testing program
+
+### 📚 Documentation
+
+- **TROUBLESHOOTING.md**: 50+ common issues with solutions
+- **FAQ.md**: 40+ frequently asked questions
+- **CONTRIBUTING.md**: Complete contribution guidelines
+- **RELEASE-CHECKLIST.md**: 150+ item release validation
+- **BETA-TESTING.md**: Beta testing procedures
+- **E2E-TESTING.md**: End-to-end testing guide
+- **PROJECT-HISTORY.md**: Complete project evolution from v1.0 to v4.0
+- **examples/**: Comprehensive examples and use cases
+
+### 🔧 Technical Details
+
+#### Dependencies Removed
+
+- Milvus client (~300MB)
+- ONNX Runtime (~100MB)
+- Transformers.js (~50MB)
+- 431 transitive dependencies
+
+#### Dependencies Added
+
+- TypeScript tooling
+- SQLite + vec extension
+- Vitest 2.x for testing
+
+#### Code Metrics
+
+- Source code: 28,980 → 6,200 LOC (78% reduction)
+- Tests: ~200 → 841 tests (320% increase)
+- Test coverage: Unknown → 84.19%
+- Bundle size: 340MB → 46MB (87% reduction)
+
+### 🔒 Security
+
+- Fixed: esbuild CORS vulnerability (GHSA-67mh-4wv8-2f99)
+- Enhanced: Path traversal prevention
+- Enhanced: Workspace isolation
+- Enhanced: Input validation and sanitization
+
+### 🐛 Bug Fixes
+
+- All v3.1 JavaScript runtime type errors eliminated
+- Memory leaks in vector search operations fixed
+- CLI error handling and exit codes improved
+- Path resolution edge cases fixed
+- Provider fallback logic corrected
+
+### ⚡ Performance
+
+- Vector search: 45ms → 0.72ms (62x faster)
+- Installation: 8+ min → <2 min (4x faster)
+- Startup: 60% faster with lazy loading
+- Memory usage: 50% reduction
+- Bundle size: 340MB → 46MB (87% smaller)
+
+### 🧪 Testing
+
+- Unit tests: 677 tests (90%+ core module coverage)
+- Integration tests: 78 tests
+- E2E tests: 17 tests (11 passing)
+- Total: 841 tests (98.4% passing)
+- Coverage: 84.19% overall
+
+### 📦 Distribution
+
+- Package size: 210.4 KB (tarball)
+- Unpacked: 879.7 KB
+- Files: 53
+- Node.js: ≥20.0.0
+
+### 🙏 Contributors
+
+Thank you to all contributors who made v4.0 possible!
+
+### 📝 Upgrade Guide
+
+**From v3.1 to v4.0**:
+
+1. **Export v3.1 data** (optional):
+
+   ```bash
+   cd v3.1-project
+   automatosx memory export --output backup.json
+   ```
+
+2. **Uninstall v3.1**:
+
+   ```bash
+   npm uninstall -g automatosx
+   ```
+
+3. **Install v4.0**:
+
+   ```bash
+   npm install -g automatosx@4.0.0
+   ```
+
+4. **Initialize fresh project**:
+
+   ```bash
+   cd your-project
+   automatosx init
+   ```
+
+5. **Configure providers**:
+
+   ```bash
+   automatosx config --set providers.claude.apiKey --value "sk-ant-..."
+   ```
+
+6. **Import data** (optional):
+
+   ```bash
+   automatosx memory import --input backup.json
+   ```
+
+### 🔗 Resources
+
+- **Documentation**: <https://docs.automatosx.dev>
+- **Repository**: <https://github.com/defai-digital/automatosx>
+- **Issues**: <https://github.com/defai-digital/automatosx/issues>
+- **npm**: <https://www.npmjs.com/package/automatosx>
+
+---
+
+## [Unreleased]
+
+(Future changes will be listed here)
+
+## [4.0.0-beta.1] - 2025-10-04
+
+### Added - Core Features
+
+#### Complete TypeScript Rewrite
+
+- **100% TypeScript** with strict mode enabled
+- Full type definitions for all modules
+- JSDoc comments for API documentation
+- Zero TypeScript compilation errors
+
+#### Memory System (SQLite + vec)
+
+- **SQLite-based vector database** using sqlite-vec extension
+- 87% size reduction from v3.x (300MB Milvus → 2-5MB SQLite)
+- Text-based and vector-based memory search
+- Automatic memory persistence
+- Memory export/import (JSON, CSV formats)
+- Memory statistics and analytics
+- Configurable memory retention (auto-cleanup)
+
+#### Agent System
+
+- **Agent profiles** (YAML format) with role-based configuration
+- **Abilities system** - Reusable skills for agents
+- **Agent workspace** - Isolated execution environment
+- **Context management** - Automatic context building with memory injection
+- **Path resolution** with security validation (prevent path traversal)
+- 5 example agents (assistant, reviewer, documenter, debugger, architect)
+- 15 example abilities
+
+#### Provider System
+
+- **Router with automatic fallback** - Try providers in priority order
+- **Health monitoring** - Periodic provider health checks
+- **Timeout handling** - Configurable request timeouts
+- **Rate limit detection** - Automatic retry logic
+- Supported providers:
+  - Claude (Anthropic) via CLI
+  - Gemini (Google) via CLI
+  - OpenAI (future)
+
+#### CLI Commands
+
+- `automatosx init` - Initialize project with config and examples
+- `automatosx run <agent> <task>` - Execute agent with task
+- `automatosx chat <agent>` - Interactive chat mode
+- `automatosx status` - System health and provider status
+- `automatosx list <type>` - List agents, abilities, providers
+- `automatosx memory <command>` - Memory management (search, export, import, stats)
+
+#### Error Handling
+
+- **Structured error hierarchy** with 6 error classes
+- **40+ error codes** (E1000-E9999) for programmatic handling
+- **Actionable error messages** with suggestions
+- **Error formatter** with multiple output modes
+- **Error context** - Additional metadata for debugging
+- Complete error code reference documentation
+
+#### Configuration
+
+- **JSON-based configuration** (automatosx.config.json)
+- **Provider configuration** - Enable/disable, priority, timeout
+- **Memory configuration** - Max entries, persistence, auto-cleanup
+- **Workspace configuration** - Isolation, cleanup policy
+- **Logging configuration** - Level, file output, console output
+- **Configuration validation** - Comprehensive config validation
+
+### Added - Documentation
+
+#### User Documentation
+
+- **Getting Started Guide** (400+ lines) - 5-minute quick start
+- **API Documentation** (500+ lines) - Complete API reference
+- **Error Codes Reference** (250+ lines) - All error codes with solutions
+- **CLI Commands Reference** (NEW)
+- **Configuration Guide** (NEW)
+- **Troubleshooting Guide** (NEW)
+- **FAQ** (NEW)
+
+#### Developer Documentation
+
+- Comprehensive JSDoc comments
+- Type definitions for all interfaces
+- Code examples in documentation
+- Architecture diagrams (in PRD)
+
+### Added - Testing
+
+#### Test Suite
+
+- **379 unit tests** (99.2% pass rate)
+- **22 test files** covering all core modules
+- **Integration tests** for CLI commands
+- **60.71% code coverage** overall
+- **94.92% coverage** for agent system
+- **87.54% coverage** for core modules
+- **100% coverage** for router and error formatter
+
+#### Test Infrastructure
+
+- Vitest test framework
+- Coverage reporting with v8
+- Mock providers for testing
+- Test fixtures and utilities
+
+### Changed - Architecture
+
+#### Bundle Size Reduction
+
+- **v3.x**: 340MB → **v4.0**: 152KB (99.96% reduction)
+- Removed Milvus (300MB) → SQLite + vec (2-5MB)
+- Removed @xenova/transformers (100MB) → OpenAI embeddings API
+- Removed unnecessary dependencies: 589 → 384 (35% reduction)
+
+#### Directory Structure
+
+- **v3.x**: `.defai/` → **v4.0**: `.automatosx/`
+- Config file: `defai.config.yaml` → `automatosx.config.json`
+- Organized structure:
+
+  ```text
+  .automatosx/
+  ├── agents/          # Agent profiles
+  ├── abilities/       # Ability definitions
+  ├── memory/          # SQLite database
+  ├── workspaces/      # Agent workspaces
+  └── logs/            # Log files
+  ```
+
+#### Performance Improvements
+
+- **Startup time**: <1s (previously 3-5s)
+- **Memory footprint**: ~50MB (previously ~500MB)
+- **Database queries**: 10x faster with SQLite vs Milvus
+- **Dependency installation**: <2min (previously 10-15min)
+
+### Changed - Breaking Changes from v3.x
+
+#### ⚠️ v4.0 requires clean installation - no automatic migration from v3.x
+
+1. **Configuration Format**
+   - YAML → JSON
+   - New config structure
+   - Manual configuration required
+
+2. **Memory System**
+   - Milvus → SQLite + vec
+   - New vector extension
+   - Use export/import for manual data transfer if needed
+
+3. **Directory Structure**
+   - `.defai/` → `.automatosx/`
+   - Clean installation required
+
+4. **CLI Commands**
+   - New command structure
+   - Different command flags
+   - Review documentation for command changes
+
+5. **Provider Interface**
+   - CLI-based providers only
+   - Direct API support removed (use CLI wrappers)
+
+#### For v3.x Users
+
+- v4.0 is a complete rewrite - install it separately
+- Both versions can coexist if needed
+- Manually transfer data using export/import if required
+- Review new documentation before switching
+
+### Removed
+
+#### Dependencies Removed
+
+- ❌ Milvus (300MB)
+- ❌ @xenova/transformers (~100MB)
+- ❌ onnxruntime-node (92MB)
+- ❌ sharp (24MB)
+- ❌ 200+ unused dependencies
+
+#### Features Removed
+
+- ❌ Built-in transformer models (use API instead)
+- ❌ Direct provider APIs (use CLI wrappers)
+- ❌ Legacy YAML config support
+- ❌ Old `.defai/` directory structure
+
+### Fixed
+
+#### Bug Fixes
+
+- Fixed path traversal vulnerabilities in workspace creation
+- Fixed memory leak in provider health checks
+- Fixed race conditions in concurrent requests
+- Fixed error messages not showing suggestions
+- Fixed config validation edge cases
+
+#### Security Fixes
+
+- Added path validation to prevent directory traversal
+- Restricted workspace permissions (700 on Unix)
+- Sanitized error messages to prevent info leakage
+- Validated all user inputs
+
+### Security
+
+#### New Security Features
+
+- **Path traversal prevention** - Validate all file paths
+- **Workspace isolation** - Agents run in isolated directories
+- **Input sanitization** - All user inputs validated
+- **Permission restrictions** - Workspace directories with restricted permissions
+- **Error message sanitization** - No sensitive data in errors
+
+#### Security Audit
+
+- 23 security tests passing
+- Path traversal prevention verified
+- Input validation comprehensive
+- No known vulnerabilities
+
+### Performance
+
+#### Benchmarks (vs v3.x)
+
+| Metric | v3.x | v4.0 | Improvement |
+|--------|------|------|-------------|
+| Bundle Size | 340MB | 152KB | 99.96% |
+| Dependencies | 589 | 384 | 35% |
+| Startup Time | 3-5s | <1s | 80% |
+| Memory Usage | ~500MB | ~50MB | 90% |
+| Installation | 10-15min | <2min | 87% |
+
+### Developer Experience
+
+#### Improvements
+
+- TypeScript for better IDE support
+- Comprehensive error messages with suggestions
+- Detailed documentation with examples
+- Test coverage for confidence
+- Simplified installation process
+
+#### Developer Tools
+
+- `npm run build` - Build project
+- `npm run test` - Run tests
+- `npm run test:coverage` - Coverage report
+- `npm run typecheck` - Type checking
+- `npm run dev` - Development mode
+
+---
+
+## [3.1.5] - 2024-12-15 (Legacy)
+
+Last stable version before v4.0 rewrite.
+
+### Known Issues in v3.x
+
+- Large bundle size (340MB)
+- Slow installation (10-15min)
+- High memory usage (~500MB)
+- Milvus dependency (300MB)
+- Limited error handling
+
+---
+
+## Links
+
+- [Documentation](./docs/)
+- [API Reference](./docs/API.md)
+- [Error Codes](./docs/ERROR-CODES.md)
+- [Getting Started](./docs/GETTING-STARTED.md)
+- [GitHub](https://github.com/automatosx/automatosx)
+- [Issues](https://github.com/automatosx/automatosx/issues)
+
+---
+
+**Note**: This is a beta release. Please report any issues on GitHub.