@claude-flow/codex 3.0.0-alpha.3 → 3.0.0-alpha.5

package/README.md

@@ -1,6 +1,29 @@
 # @claude-flow/codex
 
-OpenAI Codex CLI adapter for Claude Flow V3. Enables multi-agent orchestration with **self-learning capabilities** for OpenAI Codex CLI following the [Agentic AI Foundation](https://agenticfoundation.org) standard.
+<p align="center">
+  <strong>OpenAI Codex CLI Adapter for Claude Flow V3</strong><br/>
+  <em>Self-learning multi-agent orchestration following the <a href="https://agentics.org">Agentics Foundation</a> standard</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@claude-flow/codex"><img src="https://img.shields.io/npm/v/@claude-flow/codex?label=npm&color=blue" alt="npm version"></a>
+  <a href="https://github.com/ruvnet/claude-flow"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a>
+  <a href="https://agentics.org"><img src="https://img.shields.io/badge/standard-Agentics-purple" alt="Agentics Standard"></a>
+</p>
+
+---
+
+## Why @claude-flow/codex?
+
+Transform OpenAI Codex CLI into a **self-improving AI development system**. While Codex executes code, claude-flow orchestrates, coordinates, and **learns from every interaction**.
+
+| Traditional Codex | With Claude-Flow |
+|-------------------|------------------|
+| Stateless execution | Persistent vector memory |
+| Single-agent | Multi-agent swarms (up to 15) |
+| Manual coordination | Automatic orchestration |
+| No learning | Self-learning patterns (HNSW) |
+| One platform | Dual-mode (Claude Code + Codex) |
 
 ## Key Concept: Execution Model
 
@@ -13,6 +36,30 @@ OpenAI Codex CLI adapter for Claude Flow V3. Enables multi-agent orchestration w
 
 **Codex does the work. Claude-flow coordinates and learns.**
 
+### The Self-Learning Loop
+
+```
+    ┌──────────────┐
+    │   SEARCH     │ ──→ Find relevant patterns from past successes
+    │   memory     │
+    └──────┬───────┘
+           │
+    ┌──────▼───────┐
+    │  COORDINATE  │ ──→ Initialize swarm, spawn specialized agents
+    │   swarm      │
+    └──────┬───────┘
+           │
+    ┌──────▼───────┐
+    │   EXECUTE    │ ──→ Codex writes code, runs commands
+    │   codex      │
+    └──────┬───────┘
+           │
+    ┌──────▼───────┐
+    │    STORE     │ ──→ Save successful patterns for future use
+    │   memory     │
+    └──────────────┘
+```
+
 ## Quick Start
 
 ```bash
@@ -26,6 +73,8 @@ npx claude-flow@alpha init --codex --full
 npx claude-flow@alpha init --dual
 ```
 
+**That's it!** The MCP server is auto-registered, skills are installed, and your project is ready for self-learning development.
+
 ---
 
 <details>
@@ -41,6 +90,8 @@ npx claude-flow@alpha init --dual
 | **Auto-Registration** | MCP server registered during init |
 | **HNSW Search** | 150x-12,500x faster pattern matching |
 | **Self-Learning** | Learn from successes, remember patterns |
+| **GPT-5.3 Support** | Optimized for latest OpenAI models |
+| **Neural Training** | Train patterns with SONA architecture |
 
 </details>
 
@@ -305,16 +356,154 @@ $github-workflow
 $performance-optimization
 ```
 
-### Skill Categories
-
-| Category | Examples |
-|----------|----------|
-| **Swarm** | `$swarm-orchestration`, `$swarm-advanced` |
-| **Memory** | `$memory-management`, `$agentdb-vector-search` |
-| **SPARC** | `$sparc-methodology`, `$specification`, `$architecture` |
-| **GitHub** | `$github-code-review`, `$github-workflow-automation` |
-| **Security** | `$security-audit`, `$security-overhaul` |
-| **Testing** | `$tdd-london-swarm`, `$production-validator` |
+### Complete Skills Table (137+ Skills)
+
+#### V3 Core Skills
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| V3 Security Overhaul | `$v3-security-overhaul` | Complete security architecture with CVE remediation |
+| V3 Memory Unification | `$v3-memory-unification` | Unify 6+ memory systems into AgentDB with HNSW |
+| V3 Integration Deep | `$v3-integration-deep` | Deep agentic-flow@alpha integration (ADR-001) |
+| V3 Performance Optimization | `$v3-performance-optimization` | Achieve 2.49x-7.47x speedup targets |
+| V3 Swarm Coordination | `$v3-swarm-coordination` | 15-agent hierarchical mesh coordination |
+| V3 DDD Architecture | `$v3-ddd-architecture` | Domain-Driven Design architecture |
+| V3 Core Implementation | `$v3-core-implementation` | Core module implementation |
+| V3 MCP Optimization | `$v3-mcp-optimization` | MCP server optimization and transport |
+| V3 CLI Modernization | `$v3-cli-modernization` | CLI modernization and hooks enhancement |
+
+#### AgentDB & Memory Skills
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| AgentDB Advanced | `$agentdb-advanced` | Advanced QUIC sync, distributed coordination |
+| AgentDB Memory Patterns | `$agentdb-memory-patterns` | Persistent memory patterns for AI agents |
+| AgentDB Learning | `$agentdb-learning` | AI learning plugins with AgentDB |
+| AgentDB Optimization | `$agentdb-optimization` | Quantization (4-32bit), performance tuning |
+| AgentDB Vector Search | `$agentdb-vector-search` | Semantic vector search with HNSW |
+| ReasoningBank AgentDB | `$reasoningbank-agentdb` | ReasoningBank with AgentDB integration |
+| ReasoningBank Intelligence | `$reasoningbank-intelligence` | Adaptive learning with ReasoningBank |
+
+#### Swarm & Coordination Skills
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| Swarm Orchestration | `$swarm-orchestration` | Multi-agent swarms with agentic-flow |
+| Swarm Advanced | `$swarm-advanced` | Advanced swarm patterns for research/analysis |
+| Hive Mind Advanced | `$hive-mind-advanced` | Collective intelligence system |
+| Stream Chain | `$stream-chain` | Stream-JSON chaining for multi-agent pipelines |
+| Worker Integration | `$worker-integration` | Background worker integration |
+| Worker Benchmarks | `$worker-benchmarks` | Worker performance benchmarks |
+
+#### GitHub Integration Skills
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| GitHub Code Review | `$github-code-review` | AI-powered code review swarms |
+| GitHub Project Management | `$github-project-management` | Swarm-coordinated project management |
+| GitHub Multi-Repo | `$github-multi-repo` | Multi-repository coordination |
+| GitHub Release Management | `$github-release-management` | Release orchestration with AI swarms |
+| GitHub Workflow Automation | `$github-workflow-automation` | GitHub Actions automation |
+
+#### SPARC Methodology Skills (30+)
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| SPARC Methodology | `$sparc-methodology` | Full SPARC workflow orchestration |
+| SPARC Specification | `$sparc:spec-pseudocode` | Capture full project context |
+| SPARC Architecture | `$sparc:architect` | System architecture design |
+| SPARC Coder | `$sparc:coder` | Clean, efficient code generation |
+| SPARC Tester | `$sparc:tester` | Comprehensive testing |
+| SPARC Reviewer | `$sparc:reviewer` | Code review and quality |
+| SPARC Debugger | `$sparc:debugger` | Runtime bug troubleshooting |
+| SPARC Optimizer | `$sparc:optimizer` | Refactor and modularize |
+| SPARC Documenter | `$sparc:documenter` | Documentation generation |
+| SPARC DevOps | `$sparc:devops` | DevOps automation |
+| SPARC Security Review | `$sparc:security-review` | Static/dynamic security analysis |
+| SPARC Integration | `$sparc:integration` | System integration |
+| SPARC MCP | `$sparc:mcp` | MCP integration management |
+
+#### Flow Nexus Skills
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| Flow Nexus Neural | `$flow-nexus-neural` | Neural network training in E2B sandboxes |
+| Flow Nexus Platform | `$flow-nexus-platform` | Platform management and authentication |
+| Flow Nexus Swarm | `$flow-nexus-swarm` | Cloud-based AI swarm deployment |
+| Flow Nexus Payments | `$flow-nexus:payments` | Credit management and billing |
+| Flow Nexus Challenges | `$flow-nexus:challenges` | Coding challenges and achievements |
+| Flow Nexus Sandbox | `$flow-nexus:sandbox` | E2B sandbox management |
+| Flow Nexus App Store | `$flow-nexus:app-store` | App publishing and deployment |
+| Flow Nexus Workflow | `$flow-nexus:workflow` | Event-driven workflow automation |
+
+#### Development Skills
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| Pair Programming | `$pair-programming` | AI-assisted pair programming |
+| Skill Builder | `$skill-builder` | Create new Claude Code Skills |
+| Verification Quality | `$verification-quality` | Truth scoring and quality verification |
+| Performance Analysis | `$performance-analysis` | Bottleneck detection and optimization |
+| Agentic Jujutsu | `$agentic-jujutsu` | Quantum-resistant version control |
+| Hooks Automation | `$hooks-automation` | Automated coordination and learning |
+
+#### Memory Management Skills
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| Memory Neural | `$memory:neural` | Neural pattern training |
+| Memory Usage | `$memory:memory-usage` | Memory usage analysis |
+| Memory Search | `$memory:memory-search` | Semantic memory search |
+| Memory Persist | `$memory:memory-persist` | Memory persistence |
+
+#### Monitoring & Analysis Skills
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| Real-Time View | `$monitoring:real-time-view` | Real-time monitoring |
+| Agent Metrics | `$monitoring:agent-metrics` | Agent performance metrics |
+| Swarm Monitor | `$monitoring:swarm-monitor` | Swarm activity monitoring |
+| Token Usage | `$analysis:token-usage` | Token usage optimization |
+| Performance Report | `$analysis:performance-report` | Performance reporting |
+| Bottleneck Detect | `$analysis:bottleneck-detect` | Bottleneck detection |
+
+#### Training Skills
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| Specialization | `$training:specialization` | Agent specialization training |
+| Neural Patterns | `$training:neural-patterns` | Neural pattern training |
+| Pattern Learn | `$training:pattern-learn` | Pattern learning |
+| Model Update | `$training:model-update` | Model updates |
+
+#### Automation & Optimization Skills
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| Self-Healing | `$automation:self-healing` | Self-healing workflows |
+| Smart Agents | `$automation:smart-agents` | Smart agent auto-spawning |
+| Session Memory | `$automation:session-memory` | Cross-session memory |
+| Cache Manage | `$optimization:cache-manage` | Cache management |
+| Parallel Execute | `$optimization:parallel-execute` | Parallel task execution |
+| Topology Optimize | `$optimization:topology-optimize` | Automatic topology selection |
+
+#### Hooks Skills (17 Hooks + 12 Workers)
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| Pre-Edit | `$hooks:pre-edit` | Context before editing |
+| Post-Edit | `$hooks:post-edit` | Record editing outcome |
+| Pre-Task | `$hooks:pre-task` | Record task start |
+| Post-Task | `$hooks:post-task` | Record task completion |
+| Session End | `$hooks:session-end` | End session and persist |
+
+#### Dual-Mode Skills (NEW)
+
+| Skill | Syntax | Description |
+|-------|--------|-------------|
+| Dual Spawn | `$dual-spawn` | Spawn parallel Codex workers from Claude Code |
+| Dual Coordinate | `$dual-coordinate` | Coordinate Claude Code + Codex execution |
+| Dual Collect | `$dual-collect` | Collect results from parallel Codex instances |
 
 ### Custom Skills
 
@@ -339,6 +528,114 @@ Invoke with `$my-skill`
 
 ---
 
+<details>
+<summary><b>Dual-Mode Integration (Claude Code + Codex)</b></summary>
+
+### Hybrid Execution Model
+
+Run Claude Code for interactive development and spawn headless Codex workers for parallel background tasks:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  CLAUDE CODE (interactive)  ←→  CODEX WORKERS (headless)        │
+│  - Main conversation         - Parallel background execution    │
+│  - Complex reasoning         - Bulk code generation            │
+│  - Architecture decisions    - Test execution                   │
+│  - Final integration         - File processing                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Setup
+
+```bash
+# Initialize dual-mode
+npx claude-flow@alpha init --dual
+
+# Creates both:
+# - CLAUDE.md (Claude Code configuration)
+# - AGENTS.md (Codex configuration)
+# - Shared .claude-flow/ runtime
+```
+
+### Spawning Parallel Codex Workers
+
+From Claude Code, spawn headless Codex instances:
+
+```bash
+# Spawn workers in parallel (each runs independently)
+claude -p "Analyze src/auth/ for security issues" --session-id "task-1" &
+claude -p "Write unit tests for src/api/" --session-id "task-2" &
+claude -p "Optimize database queries in src/db/" --session-id "task-3" &
+wait  # Wait for all to complete
+```
+
+### Dual-Mode Skills
+
+| Skill | Platform | Description |
+|-------|----------|-------------|
+| `$dual-spawn` | Codex | Spawn parallel workers from orchestrator |
+| `$dual-coordinate` | Both | Coordinate cross-platform execution |
+| `$dual-collect` | Claude Code | Collect results from Codex workers |
+
+### Dual-Mode Agents
+
+| Agent | Type | Execution |
+|-------|------|-----------|
+| `codex-worker` | Worker | Headless background execution |
+| `codex-coordinator` | Coordinator | Manage parallel worker pool |
+| `dual-orchestrator` | Orchestrator | Route tasks to appropriate platform |
+
+### Task Routing Rules
+
+| Task Complexity | Platform | Reason |
+|----------------|----------|--------|
+| Simple (1-2 files) | Codex Headless | Fast, parallel |
+| Medium (3-5 files) | Claude Code | Needs context |
+| Complex (architecture) | Claude Code | Reasoning required |
+| Bulk operations | Codex Workers | Parallelize |
+| Final review | Claude Code | Integration |
+
+### Example Workflow
+
+```
+1. Claude Code receives complex feature request
+2. Designs architecture and creates plan
+3. Spawns 4 Codex workers:
+   - Worker 1: Implement data models
+   - Worker 2: Create API endpoints
+   - Worker 3: Write unit tests
+   - Worker 4: Generate documentation
+4. Workers execute in parallel (headless)
+5. Claude Code collects and integrates results
+6. Final review and refinement in Claude Code
+```
+
+### Memory Sharing
+
+Both platforms share the same `.claude-flow/` runtime:
+
+```
+.claude-flow/
+├── data/
+│   └── memory.db      # Shared vector memory
+├── config.yaml        # Shared configuration
+└── sessions/          # Cross-platform sessions
+```
+
+### Benefits
+
+| Feature | Benefit |
+|---------|---------|
+| **Parallel Execution** | 4-8x faster for bulk tasks |
+| **Cost Optimization** | Route simple tasks to cheaper workers |
+| **Context Preservation** | Shared memory across platforms |
+| **Best of Both** | Interactive + batch processing |
+| **Unified Learning** | Patterns learned by both platforms |
+
+</details>
+
+---
+
 <details>
 <summary><b>Configuration</b></summary>
 
@@ -346,7 +643,7 @@ Invoke with `$my-skill`
 
 ```toml
 # Model configuration
-model = "gpt-4"
+model = "gpt-5.3"
 
 # Approval policy: "always" | "on-request" | "never"
 approval_policy = "on-request"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/codex",
-  "version": "3.0.0-alpha.3",
+  "version": "3.0.0-alpha.5",
   "description": "Codex CLI integration for Claude Flow - OpenAI Codex platform adapter",
   "type": "module",
   "main": "./dist/index.js",