npm - @defai.digital/automatosx - Versions diffs - 5.0.5 → 5.0.6 - Mend

@defai.digital/automatosx 5.0.5 → 5.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,644 +1,412 @@
 # AutomatosX
-> **The control tower for shipping customer-facing ideas—without the chaos**
-> Orchestrate specialized AI agents to move work from slide decks to production, keeping product, engineering, and stakeholders in sync.
+> **AI Agent Orchestration for Claude Code**
+>
+> Transform Claude Code into a multi-agent powerhouse with persistent memory, intelligent delegation, and zero-cost knowledge management.
 [![npm version](https://img.shields.io/npm/v/@defai.digital/automatosx.svg)](https://www.npmjs.com/package/@defai.digital/automatosx)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue.svg)](https://www.typescriptlang.org/)
-[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](#production-ready-toolkit)
+[![Tests](https://img.shields.io/badge/tests-1,149%20passing-brightgreen.svg)](#)
-**Teams and solo builders choose AutomatosX because:**
+**Status**: ✅ Production Ready · v5.0.6 · October 2025
-- 🎯 **Keeps people aligned, not just code moving** – track roadmaps, builds, and launch tasks in one place
-- 🛡️ **Protects quality across the whole release** – built-in guardrails for tests, docs, compliance, approvals
-- ⚡ **Shortens idea-to-impact gap** – organized workflows mean faster onboarding, tighter handoffs, confident timelines
-- 💰 **10× more cost-effective** – CLI-based orchestration beats expensive assistants APIs
-**🤖 4 Specialized Teams**: AutomatosX agents are [organized into 4 professional teams](https://github.com/defai-digital/automatosx/blob/main/examples/AGENTS_INFO.md), each optimized with the best AI provider for their domain:
-- **👥 Core Team** (OpenAI): General assistance, code generation, planning - Alex, Sofia, Ryan, Danny, Wendy
-- **💻 Engineering Team** (Claude): Deep reasoning for backend, frontend, security, DevOps, QA - Bob, Frank, Oliver, Steve, Queenie
-- **📊 Business Team** (Gemini): Strategic thinking for executive leadership and product - Eric, Tony, Paris, Daisy
-- **🎨 Design Team** (Gemini): Creative work for UX/UI and technical writing - Debbee
+---
-Every team uses intelligent fallback strategies to ensure maximum reliability across all your workflows.
+## 🎯 Built for Claude Code
-**Status**: ✅ Production Release · **Latest**: October 2025
-📖 **[Project History](docs/PROJECT-HISTORY.md)**: From Tokyo AI Expo (Nov 2024) to v5.0.1 - The complete journey
+**AutomatosX extends Claude Code with specialized AI agents that remember context, delegate tasks, and collaborate autonomously.**
----
-## 📣 What's New
-**v5.0.5 (October 2025)**: Provider Parameters Simplified & Version Management
-- 🎯 **Simplified provider parameters** - Removed artificial limits to let provider CLIs use their optimal defaults
-- 📦 **Unified version management** - Single source of truth (version.json) prevents version inconsistencies
-- 🔧 **Enhanced parameter validation** - Smart parameter filtering based on provider capabilities
-- ✅ **Critical bug fixes** - Fixed 3 bugs in version sync and error handling
-- 📊 **Better defaults** - No maxTokens limits (Claude: 200K, Gemini: 2M tokens available)
-**v5.0.4 (October 2025)**: Memory Saving Fix
-- 🐛 **Memory saving now works** - Agent conversations automatically saved to memory (--save-memory flag)
-- 🔧 **Fixed initialization logic** - Memory manager properly initialized for all flag combinations
-- ✅ **All edge cases tested** - 4/4 scenarios verified (inject-only, save-only, both, neither)
-- 🚀 **FTS5 search working** - Search your agent conversation history instantly
-- 🎯 **Zero regressions** - All existing features continue to work perfectly
-**v5.0.3 (October 2025)**: FTS5 Special Character Support
-- 🐛 **Memory search fixed** - File paths, URLs, dates, and emails now work correctly
-- 🔍 **Extended sanitization** - Handles 26 special characters (up from 15)
-- ✅ **Comprehensive testing** - Added 29 new tests covering all real-world scenarios
-- 🚀 **Zero regressions** - All 1,079 tests passing with complete backward compatibility
-**v5.0.2 (October 2025)**: Documentation & Schema Improvements
-- 📚 **Comprehensive documentation** - Added multi-agent orchestration guide (600+ lines)
-- 🎯 **Self-contained JSON Schema** - Configuration validation now built into repository
-- 🔗 **GitHub-based schema** - No external dependencies, works offline with caching
-- 📖 **Enhanced guides** - Team configuration and agent templates fully documented
-- 🗂️ **Organized docs** - Beta testing guide archived, outdated content cleaned
-**v5.0.1 (October 2025)**: Critical Bug Fixes
-- 🐛 **Provider timeout fixed** - Complex tasks no longer timeout (15 min timeout now consistent)
-- 🐛 **Delegation parser improved** - Zero false positives from documentation examples
-- 🐛 **FTS5 search stabilized** - Handles all special characters reliably
-- ✅ **1050 tests passing** - 100% pass rate with comprehensive test coverage
-**v5.0.0 (October 2025)**: Agent Template System
-- 🎉 **Quick agent creation** - Create agents from templates in seconds with `ax agent create`
-- 📋 **5 pre-built templates** - Ready-to-use templates for common roles (developer, analyst, designer, qa, basic)
-- 🛠️ **Complete CLI toolset** - `ax agent templates`, `list`, `show`, `create`, `remove`
-- 🔄 **Interactive mode** - Guided creation with prompts for all values
-- ⚡ **One-line creation** - Fast creation with all parameters in command line
-- 📦 **Auto-installation** - Templates automatically installed on `ax init`
-**New Commands**:
 ```bash
-# Quick agent creation from template
-ax agent create backend --template developer --interactive
+# In Claude Code, simply use /ax
+/ax run paris "Design authentication system with JWT"
+/ax run sofia "Implement the auth design"  # Sofia auto-receives Paris's design from memory
+/ax memory search "authentication"          # Instant search of all past decisions
+```
-# List all agents by team
-ax agent list --by-team engineering
+**The result**: Claude Code becomes a **learning, coordinated team** instead of a stateless assistant.
-# Show agent details
-ax agent show backend
-```
+---
-**v4.11.0 (October 2025)**: FTS5 Full-Text Search
-- 🎯 **No embedding costs** - Removed OpenAI embedding dependency
-- ⚡ **< 1ms search** - Pure SQLite FTS5 for blazing fast text search
-- 🔒 **Better privacy** - All data stays local (no cloud API calls)
+## 💡 Why AutomatosX?
-**v4.10.0 (October 2025)**: Team-Based Configuration
-- 🎯 **No configuration duplication** - Agents inherit settings from team
-- 👥 **4 built-in teams** - Core Team (OpenAI), Engineering Team (Claude), Business Team (Gemini), Design Team (Gemini)
-- ♻️ **Shared abilities** - Team-wide abilities automatically included
+### The Problem with Stateless AI
-For detailed release notes, new features, and upgrade instructions, see:
+**Traditional AI assistants** (ChatGPT, vanilla Claude):
+- ❌ No memory between conversations
+- ❌ You repeat context every time
+- ❌ No coordination between tasks
+- ❌ Knowledge disappears after each session
-- 📋 **[Release Notes](https://github.com/defai-digital/automatosx/releases)** - Latest updates and changes
-- 📝 **[Changelog](CHANGELOG.md)** - Complete version history
+**AutomatosX changes this**:
+- ✅ **Persistent memory**: < 1ms search, zero cost, 100% local
+- ✅ **Multi-agent delegation**: Agents coordinate automatically
+- ✅ **Context retention**: Never explain the same thing twice
+- ✅ **Knowledge accumulation**: Your team gets smarter over time
-**Quick Install:**
+### Real-World Impact
-```bash
-npm install -g @defai.digital/automatosx
+**Without AutomatosX**:
+```
+Day 1: You explain architecture to Claude → Response lost
+Day 2: You ask to implement → You re-explain architecture
+Day 3: Different task → You re-explain everything again
 ```
----
+**With AutomatosX**:
+```
+Day 1: Paris designs architecture → Saved to memory
+Day 2: /ax run sofia "implement auth" → Sofia finds Paris's design automatically
+Day 3: /ax run steve "security audit" → Steve has full context from Day 1-2
+```
-## Why AutomatosX?
+**Time saved**: Hours per week. **Quality**: Consistent. **Cost**: $0.
-### The Real Problem: Coordination, Not Code
+---
-Building software is easy. **Shipping it reliably is hard.**
+## 🚀 What's New
-Your team faces:
+**v5.0.6** (October 2025): File Operation Tools Enabled
+- Claude Provider: Enable file operations (Read, Write, Edit, Bash, Glob, Grep)
+- Gemini Provider: Enable automated file edits (--approval-mode auto_edit)
+- Fixed issue where agents couldn't perform file operations through CLIs
+- Updated provider CLI args tests for comprehensive coverage
-- **Context chaos**: Marketing doesn't know what's shipping next week. Sales asks "who owns this?" Nobody remembers what was decided.
-- **Quality gaps**: Deadlines loom. Release notes go stale. Compliance updates get skipped. Tests aren't run.
-- **Handoff friction**: New contributors ask the same questions. Cross-team work stalls. Executives lose confidence in timelines.
+**v5.0.5**: Provider Parameters & Version Management
+**v5.0.4**: Memory saving now works automatically
+**v5.0.3**: Special character support in memory search
+**v5.0.0**: Agent template system for quick agent creation
-**Claude or ChatGPT can write code fast—but they can't tell your team what to ship, in what order, or who's responsible.**
+[📋 Full Changelog](CHANGELOG.md) | [🎉 Release Notes](https://github.com/defai-digital/automatosx/releases)
-### The AutomatosX Solution
+---
-**Think of AutomatosX as your operating system for launches.** Every plan, checklist, test result, and approval lives in one orchestrated workflow—so your team stays in sync from kickoff to post-launch.
+## 🧠 Core Value: Persistent Memory
-```bash
-# PRD: Kickoff sprint
-automatosx run planner "Draft Q1 roadmap with marketing milestones"
+**AutomatosX remembers everything**. Every agent conversation is automatically saved and searchable.
-# Engineer: Build with guardrails
-automatosx run coder "Scaffold auth with Supabase"
-automatosx run reviewer "Audit API security before launch"
+### How It Works
-# QA: Run pre-launch checks
-automatosx run tester "Execute integration test suite"
+```typescript
+// Automatic memory saving
+/ax run paris "Design calculator with add/subtract"
+→ Task + Response saved to SQLite FTS5
-# Marketing: Coordinate launch
-automatosx run writer "Draft release notes and changelog"
-automatosx memory search "What did sales promise Customer #1234?"
+// Automatic memory retrieval
+/ax run sofia "Implement the calculator"
+→ Memory searches "calculator" automatically
+→ Sofia receives: "# Relevant Context from Memory: Paris's design..."
+→ Sofia implements WITHOUT you repeating the spec
 ```
-**Every agent has:**
-- 🧠 **Persistent memory** – recalls every decision, deadline, and dependency
-- 🎭 **Defined roles** – researcher, coder, reviewer, tester, writer (no context-switching)
-- 🔒 **Workspace isolation** – agents work independently without colliding
-- 💸 **Cost controls** – pay per CLI call, not expensive subscription seats
-### Real Impact: Before vs After
-| Without AutomatosX | With AutomatosX |
-|-------------------|-----------------|
-| 📋 Scattered docs, Slack threads, "who owns this?" | 🎯 Single source of truth—everyone works from the same playbook |
-| 🐌 New hires take weeks to ramp | ⚡ Organized workflows = onboarding in days |
-| 💸 Expensive subscription plans per seat | 💰 Pay-per-use CLI pricing = significant cost savings |
-| 🤯 Release notes forgotten, compliance skipped | 🛡️ Built-in guardrails catch gaps before launch |
-| ⏳ 3 weeks from plan to production | 🚀 3 days—agents handle research, build, review, docs in parallel |
-### "Why not just use Claude Code or ChatGPT?"
+### The Technology
-**Claude Code / ChatGPT**: Brilliant for answering quick questions or generating snippets. But they can't:
+- **SQLite FTS5**: Built-in full-text search
+- **< 1ms search**: 62x faster than v3.x vector search
+- **$0 cost**: No embedding APIs, no cloud calls
+- **100% local**: Your data never leaves your machine
+- **Automatic injection**: Relevant context added to every agent
-- Track who approved the launch plan
-- Remind you the release checklist is incomplete
-- Coordinate work across product, engineering, and marketing
-- Remember context from last quarter's sprint
+### Benefits
-**AutomatosX**: Built for **shipping outcomes, not just code**. It's the glue that:
+✅ **Cross-day continuity**: Pick up where you left off
+✅ **Cross-agent knowledge**: All agents share the same knowledge base
+✅ **Learning from history**: Agents avoid past mistakes
+✅ **Zero cost scaling**: 10,000 entries = ~10MB, still < 1ms search
-- Keeps teams aligned on what's shipping and when
-- Enforces quality gates (tests, docs, compliance) automatically
-- Turns scattered tribal knowledge into dependable workflows
-- Runs unattended in CI/CD while remembering every conversation
-**In plain terms**: Claude is a smart assistant. AutomatosX is your launch control center. Use both—but only AutomatosX ensures the right work happens, in the right order, by the right people.
+**Learn more**: [Memory System Guide](docs/guide/agent-communication.md) | [Memory Tutorial](docs/tutorials/memory-management.md)
 ---
-## What You Can Build in Minutes
+## 🤝 Core Value: Multi-Agent Orchestration
-### 🔍 Research Assistant
+**Agents coordinate automatically**. Natural language delegation creates complex workflows without manual orchestration.
-```bash
-automatosx run researcher "Analyze the top 5 TypeScript frameworks in 2025"
-# → Searches web, summarizes findings, cites sources
-```
+### How It Works
-### 🚨 On-Call Incident Bot
+```typescript
+// Product Manager analyzes and delegates
+/ax run paris "Build authentication feature"
-```bash
-automatosx run oncall "Check error logs from the last hour"
-# → Scans logs, identifies critical errors, auto-creates tickets
-```
+Paris response:
+  "I'll design the auth system with JWT + OAuth2.
-### 💬 Customer Support Copilot
+   @sofia Please implement the JWT authentication API based on this design.
+   @steve Please audit the implementation for security issues."
-```bash
-automatosx chat support
-> "What did Customer #1234 ask about last week?"
-# → Searches memory, recalls context, suggests responses
+// AutomatosX automatically:
+// 1. Sofia receives full spec, implements code
+// 2. Steve receives spec + code, performs audit
+// 3. Results aggregated back to Paris
 ```
-### 🔄 Batch Processing with Fallbacks
+### The Technology
-```bash
-automatosx run batch-analyzer "Process all user feedback from Q3"
-# → Tries Claude → falls back to Gemini if rate-limited → exports results
-```
+- **7 delegation syntaxes**: `@mention`, `DELEGATE TO`, `Please ask`, etc.
+- **Cycle detection**: Prevents infinite loops
+- **Depth limits**: Default 2 levels (configurable)
+- **Session tracking**: Who did what, when
+- **Workspace isolation**: No file collisions
-See `examples/` for ready-to-run agent profiles.
----
+### Benefits
-## Quick Start (< 2 minutes)
+✅ **Automatic coordination**: No manual task switching
+✅ **Parallel execution**: Multiple agents work simultaneously
+✅ **Transparent workflows**: Full delegation chain visible
+✅ **Context preservation**: Every agent has complete context
-### 1. Install
+**Learn more**: [Multi-Agent Orchestration Guide](docs/guide/multi-agent-orchestration.md)
-```bash
-npm install -g @defai.digital/automatosx
-# or run without installing
-npx @defai.digital/automatosx --help
-```
+---
-### 2. Setup Provider CLI (one-time)
+## 🎭 15 Specialized Agents, 4 Professional Teams
-AutomatosX uses your installed CLI tools—**no API keys needed**:
+**Every agent optimized for their domain with the best AI provider**:
-```bash
-# Install Claude Code CLI (if you use Claude)
-npm install -g @anthropic-ai/claude-code
-# Or via native installer: curl -fsSL https://claude.ai/install.sh | bash
-# Or via Homebrew: brew install --cask claude-code
-# Or install Gemini CLI (if you use Gemini)
-npm install -g @google/gemini-cli
-# Or install Codex CLI (if you use OpenAI)
-npm install -g @openai/codex
-# Or via Homebrew: brew install codex
-# Docs: https://github.com/openai/codex
-```
+### 👥 Core Team (OpenAI)
+General assistance and code generation
+- **Alex** - Versatile assistant for general tasks
+- **Sofia** - Senior software engineer (clean code, TDD, pragmatic)
+- **Ryan** - Code reviewer (quality, security, performance)
+- **Danny** - Debugger specialist
+- **Wendy** - Technical writer
-AutomatosX will automatically detect and use your installed CLIs.
+### 💻 Engineering Team (Claude)
+Deep reasoning for technical work
+- **Bob** - Backend expert (API design, databases, microservices)
+- **Frank** - Frontend specialist (React, UX, accessibility)
+- **Oliver** - DevOps engineer (infrastructure, CI/CD, cloud)
+- **Steve** - Security expert (threat modeling, security audit)
+- **Queenie** - QA specialist (testing strategies, test automation)
-### 3. Run your first agent
+### 📊 Business Team (Gemini)
+Strategic thinking and analysis
+- **Eric** - CEO (business strategy, organizational leadership)
+- **Tony** - CTO (technology strategy, technical leadership)
+- **Daisy** - Data Analyst (data analysis, ML, statistical modeling)
-```bash
-automatosx run assistant "Explain quantum computing in 3 sentences"
-# AutomatosX calls your installed claude/gemini/codex CLI under the hood
-```
+### 🎨 Design Team (Gemini)
+Creative and design work
+- **Paris** - Product Manager (product strategy, user research)
+- **Debbee** - UX/UI Designer (user experience, visual design)
-**That's it!** Now explore:
-```bash
-automatosx list agents              # See available agents
-automatosx chat assistant           # Interactive mode
-automatosx memory search "quantum"  # Recall past conversations
-```
+[📖 Complete Agent Directory](examples/AGENTS_INFO.md)
 ---
-## Key Capabilities
-**Composable Agents** *(v4.10.0+: Team-Based Configuration)*
-Define roles, abilities, and guardrails in `.automatosx/agents/*.yaml`. Agents inherit provider configuration from their team—no duplication needed.
-```yaml
-# .automatosx/agents/researcher.yaml (v4.10.0+)
-name: researcher
-team: core                      # 🆕 Inherits provider from team config
-displayName: "Ryan"             # Optional memorable name
-description: Research specialist with web search and citation abilities
-abilities:
-  - web_search
-  - summarize
-  - cite_sources
-  # Note: Team sharedAbilities automatically included
-```
-**Team Configuration** (`.automatosx/teams/core.yaml`):
-```yaml
-name: core
-displayName: "Core Team"
-provider:
-  primary: claude
-  fallbackChain: [claude, gemini, codex]
-sharedAbilities:
-  - our-code-review-checklist
-  - testing
-```
-**Benefits**: No need to specify `provider`, `model`, `temperature` in each agent—just assign a team!
+## ⚡ Quick Start
-**Intelligent Memory**
-SQLite FTS5 full-text search delivers millisecond recall with export/import, quotas, and deterministic search.
+### Installation
 ```bash
-# Store information
-automatosx run assistant "Remember: Project Alpha launches Q1 2025"
-# Search later (even in different sessions)
-automatosx memory search "when does Alpha launch"
-# → Returns: "Project Alpha launches Q1 2025" (0.72ms)
+npm install -g @defai.digital/automatosx
 ```
-**Multi-Agent Orchestration** *(v4.7.0+)*
-Agents collaborate autonomously through natural language delegation—no complex APIs needed.
+### In Claude Code
 ```bash
-# Coordinator agent automatically delegates to specialists:
-automatosx run coordinator "Build authentication feature"
-# Agent response includes natural language delegations:
-# "@agent-a Create login UI with email/password fields."
-# "@agent-b Implement JWT auth API."
-#
-# System automatically:
-# 1. Detects delegation requests (@agent-a, @agent-b)
-# 2. Executes delegated tasks in parallel
-# 3. Collects and returns all results
-```
-**Supported delegation syntaxes:**
-- `@[agent-name] Create login UI` - Concise mention
-- `DELEGATE TO [agent]: Implement API` - Explicit command
-- `Please ask [agent] to design schema` - Natural request
-- `I need [agent] to handle the UI` - Need expression
-- `請 [agent] 建立 UI` - Chinese support
+# Initialize (first time only)
+/ax init
-**Safety features:**
+# Run agents
+/ax run paris "Design REST API for users"
+/ax run sofia "Implement the API"           # Auto-receives Paris's design
+/ax run queenie "Write tests for the API"    # Auto-receives design + implementation
-- ✅ Autonomous collaboration (no whitelists needed)
-- ✅ Cycle detection prevents infinite loops
-- ✅ Depth limits control delegation chains (default: 3)
-- ✅ Self-delegation automatically blocked
-- ✅ Session tracking for multi-agent workflows
+# Search memory
+/ax memory search "API design"
+/ax memory list --agent paris
-**Secure Execution**
-Path boundary validation, workspace sandboxes, and deterministic config precedence keep agents in safe lanes.
-- ✅ Agents read user files (validated paths only)
-- ✅ Agents write to isolated workspaces (`.automatosx/workspaces/<agent>/`)
-- ✅ Input sanitization prevents path traversal attacks
+# Manage agents
+/ax agent list
+/ax agent show sofia
+/ax agent create backend --template developer
+```
-**Developer Experience**
-Strict TypeScript, CLI ergonomics, and rich docs unblock contributors quickly.
+**That's it!** Agents now remember everything and coordinate automatically.
-```bash
-npm run dev -- run assistant "test"  # Dev mode with hot reload
-npm test                              # 994 tests with Vitest
-npm run typecheck                     # Strict TS validation
-```
+📖 **[Full Installation Guide](docs/guide/installation.md)** | **[Quick Start Tutorial](docs/guide/quick-start.md)**
 ---
-## Architecture at a Glance
-```text
-automatosx/
-├── src/
-│   ├── core/        # config, routing, memory, path resolution, team-manager (v4.10.0+)
-│   ├── cli/         # command definitions (run, chat, memory, etc.)
-│   ├── agents/      # profile-loader, abilities-manager, context-manager
-│   ├── providers/   # Claude, Gemini, Codex adapters
-│   ├── types/       # TypeScript type definitions (agent, team, provider, etc.)
-│   └── utils/       # logger, performance tracking
-├── .automatosx/
-│   ├── agents/      # Agent YAML profiles (17 agents)
-│   ├── teams/       # 🆕 Team YAML configs (4 teams) - v4.10.0+
-│   ├── abilities/   # Markdown knowledge bases
-│   ├── memory/      # SQLite FTS5 database
-│   └── workspaces/  # Agent isolated workspaces
-├── tests/
-│   ├── unit/        # 928 tests (core modules)
-│   ├── integration/ # 66 tests (CLI commands)
-│   └── e2e/         # Complete workflows
-├── docs/            # guides, references, troubleshooting
-└── examples/        # agent profiles and abilities
-```
+## 📚 Documentation
-**v4.10.0 Highlights:**
-- 🆕 `.automatosx/teams/` - Team-based configuration (4 teams)
-- 🆕 `src/core/team-manager.ts` - Team configuration management
-- 🆕 `src/types/team.ts` - TeamConfig type definitions
+### Getting Started
+- **[Quick Start Guide](docs/guide/quick-start.md)** - Get up and running in 5 minutes
+- **[Core Concepts](docs/guide/core-concepts.md)** - Understand agents, memory, providers
+- **[Installation Guide](docs/guide/installation.md)** - Detailed setup instructions
-Strict mode TypeScript + Vitest ensures every module is covered before it ships.
+### Core Features
+- **[Agent Communication & Memory](docs/guide/agent-communication.md)** - How agents communicate and remember
+- **[Multi-Agent Orchestration](docs/guide/multi-agent-orchestration.md)** - Natural language delegation
+- **[Team Configuration](docs/guide/team-configuration.md)** - Team-based agent organization
+- **[Agent Templates](docs/guide/agent-templates.md)** - Quick agent creation
----
+### Tutorials
+- **[Memory Management](docs/tutorials/memory-management.md)** - Hands-on memory system guide
+- **[Creating Your First Agent](docs/tutorials/first-agent.md)** - Build custom agents
-## Production-Ready Toolkit
+### Reference
+- **[CLI Commands](docs/reference/cli-commands.md)** - Complete command reference
+- **[Agent Directory](examples/AGENTS_INFO.md)** - All available agents
-| Metric | v3.1 | v4.10.0 | v5.0.1 |
-|--------|------|---------|--------|
-| Bundle size | 340 MB | 46 MB | **381 KB** |
-| Text search (FTS5) | 45 ms | 0.72 ms | **< 1 ms** |
-| Dependencies | 589 | 158 | **19** |
-| Tests passing | 512 | 994 | **1,050** |
+---
-**Run the essentials:**
+## 🔬 The Technical Advantage
-```bash
-npm run build          # Bundle via tsup into dist/
-npm test               # All test suites
-npm run typecheck      # Strict TS validation
-npm run test:coverage  # Generate coverage report
-```
+| Feature | Traditional AI Chat | Claude Code | Claude Code + AutomatosX |
+|---------|---------------------|-------------|--------------------------|
+| **Memory** | No | No | ✅ SQLite FTS5 (< 1ms) |
+| **Cost** | $20/month | Included | ✅ $0 (100% local) |
+| **Multi-Agent** | No | No | ✅ 15 specialized agents |
+| **Coordination** | Manual | Manual | ✅ Automatic delegation |
+| **Context Retention** | Copy-paste | Session only | ✅ Persistent (days/weeks) |
+| **Knowledge Sharing** | No | No | ✅ Cross-agent memory |
+| **Privacy** | Cloud | Claude servers | ✅ 100% local data |
+| **Speed** | Web UI | Terminal | ✅ Instant CLI |
 ---
-## Commands You'll Use Daily
+## 💼 Real-World Use Cases
+### 🏗️ Feature Development
 ```bash
-# Execute agents
-automatosx run <agent> "<task>"      # One-time execution
-automatosx chat <agent>               # Interactive session
+/ax run paris "Design user authentication feature"
+# Paris creates spec → Saved to memory
-# Agents have memorable names! 🎉
-automatosx run Bob "Design a RESTful API"      # Bob = Backend Engineer
-automatosx run Frank "Create login component"  # Frank = Frontend Developer
-automatosx run Steve "Review auth code"        # Steve = Security Engineer
+/ax run sofia "Implement auth based on spec"
+# Sofia auto-receives spec → Implements code
-# See all agents with their memorable names
-# 📖 Full agent directory: examples/AGENTS_INFO.md
+/ax run steve "Security audit the auth implementation"
+# Steve auto-receives spec + code → Performs audit
-# Manage agents
-automatosx list agents                # Show available agents
-automatosx list abilities             # Show available abilities
-# Memory operations
-automatosx memory search "<query>"   # Semantic search
-automatosx memory export --output memories.json
-automatosx memory import --input memories.json
-automatosx memory clear               # Clear all memories
-# Configuration
-automatosx init [path]                # Initialize project
-automatosx config --list              # View settings
-automatosx config --set <key> --value <val>
-automatosx status                     # System status
+/ax run wendy "Document the auth system"
+# Wendy auto-receives everything → Creates docs
 ```
-Full CLI reference: `docs/reference/cli-commands.md`
----
-## Real-World Examples
-### Research Pipeline
+**Result**: 4-step workflow, zero context re-explanation, complete audit trail
+### 🐛 Bug Investigation
 ```bash
-# 1. Define researcher agent (v4.10.0+ team-based config)
-cat > .automatosx/agents/researcher.yaml <<EOF
-name: researcher
-team: core                      # Inherits provider from team
-displayName: "Ryan"
-abilities: [web_search, summarize, cite_sources]
-EOF
-# 2. Run research task
-automatosx run researcher "Compare Redis vs PostgreSQL for session storage"
-# Or use display name: automatosx run Ryan "..."
-# 3. Search results later
-automatosx memory search "session storage comparison"
-```
+/ax run danny "Debug the payment timeout issue"
+# Danny analyzes, saves findings to memory
-### CI/CD Integration
+/ax run sofia "Fix the issue Danny found"
+# Sofia reads Danny's analysis → Implements fix
-```yaml
-# .github/workflows/code-review.yml
-- name: AI Code Review
-  run: |
-    automatosx run reviewer "Review changes in PR #${{ github.event.number }}"
+/ax run queenie "Test the payment fix"
+# Queenie knows the bug + fix → Comprehensive testing
 ```
-### Cron Job Monitoring
+**Result**: Coordinated debugging with full context preservation
+### 📊 Research & Analysis
 ```bash
-# Monitor logs every hour
-0 * * * * automatosx run oncall "Check last hour logs for errors" | mail -s "Hourly Report" team@company.com
-```
+/ax run daisy "Analyze user behavior patterns"
+# Daisy analyzes data → Findings in memory
----
+/ax run paris "Design features based on Daisy's analysis"
+# Paris reads analysis → Creates product spec
-## Configuration
-### Global Configuration
-AutomatosX uses JSON configuration with priority order:
-1. `.automatosx/config.json` (project-specific)
-2. `automatosx.config.json` (project root)
-3. `~/.automatosx/config.json` (user global)
-**Example configuration:**
-```json
-{
-  "$schema": "https://automatosx.com/schema/config.json",
-  "version": "4.10.0",
-  "providers": {
-    "preferred": "claude",
-    "claude": {
-      "command": "claude"
-    },
-    "gemini": {
-      "command": "gemini"
-    },
-    "openai": {
-      "command": "codex"
-    }
-  },
-  "memory": {
-    "maxEntries": 10000
-  }
-}
+/ax run eric "Business case for Paris's proposal"
+# Eric has analysis + spec → Strategic evaluation
 ```
-### Team Configuration (v4.10.0+)
+**Result**: Data-driven decision making with complete context
-**NEW**: Organize agents into teams with shared provider configurations:
+---
-```yaml
-# .automatosx/teams/engineering.yaml
-name: engineering
-displayName: "Engineering Team"
-description: Software development specialists
+## 🎯 Why Teams Choose AutomatosX
-# Provider configuration (inherited by all team members)
-provider:
-  primary: codex
-  fallbackChain: [codex, gemini, claude]
+### For Solo Developers
+- **Extend Claude Code** with persistent memory
+- **Never repeat context** - agents remember everything
+- **Coordinate complex tasks** with multi-agent workflows
+- **100% local** - your data stays private
-# Shared abilities (automatically added to all team agents)
-sharedAbilities:
-  - our-coding-standards
-  - code-generation
-  - refactoring
-  - testing
+### For Teams
+- **Shared knowledge base** - export/import memory across team
+- **Consistent quality** - agents learn from past work
+- **Faster onboarding** - new members inherit team knowledge
+- **Audit trail** - complete history of all decisions
-# Team-level orchestration defaults
-orchestration:
-  maxDelegationDepth: 2  # Default: 2 (v4.11.0+)
+### For Claude Code Power Users
+- **Slash command integration** - `/ax` for instant access
+- **Terminal-native** - no context switching
+- **CLI-based** - scriptable and automatable
+- **Zero latency** - local memory = instant search
-metadata:
-  owner: "Engineering Lead"
-  created: "2025-10-08"
-```
+---
-**Built-in Teams:**
-- **core**: Quality assurance (primary: claude)
-- **engineering**: Software development (primary: codex)
-- **business**: Product & planning (primary: gemini)
-- **design**: Design & content (primary: gemini)
+## 🛠️ Production-Ready
-**Benefits:**
-- ✅ Agents inherit provider settings from their team
-- ✅ Change provider for entire team at once
-- ✅ Shared abilities automatically included
-- ✅ No duplication across agent configs
+✅ **1,149 tests passing** (100% pass rate)
+✅ **TypeScript strict mode** (zero errors)
+✅ **84% test coverage** (comprehensive testing)
+✅ **46MB bundle** (87% smaller than v3.x)
+✅ **< 1ms memory search** (62x faster than v3.x)
-### Provider Configuration
+### Performance Metrics
-**How it works:**
+```
+Memory Search: < 1ms (10,000 entries)
+Bundle Size:   46MB (down from 340MB in v3.x)
+Dependencies:  158 packages (down from 589 in v3.x)
+Test Coverage: 84.19% (1,149 tests)
+Memory Cost:   $0 (no API calls)
+```
-- AutomatosX calls your installed CLI commands (`claude`, `gemini`, `codex`)
-- Each CLI uses its own default model (you can override via CLI config if needed)
-- No need to specify model versions—CLIs auto-update to latest models
-- You manage your own subscription/plan directly with the provider
-- No API keys stored in AutomatosX—your CLI handles authentication
-- Pay only for what you use via your existing CLI plan
+### Technology Stack
-**Provider Selection Priority** (v4.10.0+):
-1. **CLI option** (highest): `ax run agent "task" --provider gemini`
-2. **Team config**: From `.automatosx/teams/<team>.yaml`
-3. **Agent config** (deprecated): From agent's `provider` field
-4. **Router fallback** (lowest): Global provider routing
+- **Runtime**: Node.js 20+
+- **Language**: TypeScript 5.3 (strict mode)
+- **Memory**: SQLite + FTS5 (built-in full-text search)
+- **Testing**: Vitest 2.x (1,149 tests)
+- **Build**: tsup/esbuild
+- **Providers**: Claude CLI, Gemini CLI, OpenAI Codex
 ---
-## Documentation & Support
+## 🚧 Coming Soon
-- **Agent Directory**: `examples/AGENTS_INFO.md` (complete list of agents with memorable names)
-- **Guides**: `docs/guide/` (installation, quick start, core concepts)
-- **FAQ**: `FAQ.md`
-- **Troubleshooting**: `TROUBLESHOOTING.md`
-- **Issues & Support**: [GitHub Issues](https://github.com/defai-digital/automatosx/issues)
-  - 🐛 Bug reports
-  - ✨ Feature requests (use "enhancement" label)
-  - ❓ Questions
-  - 💡 Wishlist & Ideas
-- **npm**: <https://www.npmjs.com/package/@defai.digital/automatosx>
-- **Website**: <https://automatosx.com>
+- Enhanced Claude Code integration
+- Visual workflow builder
+- Advanced memory analytics
+- Cross-project knowledge sharing
+- Plugin system for custom providers
 ---
-## Migration from v3.1
+## 🤝 Contributing
-⚠️ **No automatic migration path** – v4.0 requires clean installation due to fundamental architectural changes.
+We welcome contributions! AutomatosX is built in the open.
-**Key changes:**
+- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute
+- **[Development Setup](CONTRIBUTING.md#development-setup)** - Local setup
+- **[Architecture Guide](docs/guide/core-concepts.md)** - Understand the codebase
-- Memory: Milvus vector DB → SQLite FTS5 full-text search
-- Language: JavaScript → TypeScript
-- Config: `.defai/` → `.automatosx/`, YAML → JSON
-- Bundle: 340MB → 46MB (87% reduction)
-See [CHANGELOG.md](CHANGELOG.md#400---2025-10-06) for detailed upgrade instructions.
+**Join the community**:
+- 🐛 [Report Issues](https://github.com/defai-digital/automatosx/issues)
+- 💡 [Feature Requests](https://github.com/defai-digital/automatosx/issues/new)
 ---
-## Contributing
-We welcome contributions! Please:
+## 📄 License
-1. Read [CONTRIBUTING.md](CONTRIBUTING.md)
-2. Follow [Conventional Commits](https://www.conventionalcommits.org/)
-3. Run tests before submitting: `npm test -- --coverage`
-4. Update docs when changing architecture or APIs
-**Development setup:**
-```bash
-git clone https://github.com/defai-digital/automatosx.git
-cd automatosx
-npm install
-npm test
-npm run build
-```
+AutomatosX is [Apache 2.0 licensed](LICENSE).
 ---
-## License
+## 🔗 Links
-Apache License 2.0 — see [LICENSE](LICENSE) for details.
+- **📦 npm**: [@defai.digital/automatosx](https://www.npmjs.com/package/@defai.digital/automatosx)
+- **🐙 GitHub**: [defai-digital/automatosx](https://github.com/defai-digital/automatosx)
+- **📖 Documentation**: [docs/](docs/)
+- **🎉 Releases**: [GitHub Releases](https://github.com/defai-digital/automatosx/releases)
+- **📋 Changelog**: [CHANGELOG.md](CHANGELOG.md)
 ---
-**Built by the DEFAI team for practitioners who ship agents, not demos.**
+**Transform Claude Code into an intelligent, coordinated team with AutomatosX.** 🚀
-*Need enterprise support, custom integrations, or SLA guarantees? Contact us at <support@defai.digital>*
+**Built with ❤️ by the AutomatosX team**