From 5795367455880ef9bfeb45d4e5fd580366f27bee Mon Sep 17 00:00:00 2001 From: rUv Date: Sat, 7 Feb 2026 17:49:15 +0000 Subject: [PATCH] Checkpoint: File edits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Automatic checkpoint created by Claude Code - Branch: feature/codex-integration - Timestamp: 2026-02-07T17:49:15Z - Changes: 2 file(s) πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- AGENTS.md | 719 ++++++++++++-------------------- v3/@claude-flow/codex/README.md | 218 ++++++++++ 2 files changed, 486 insertions(+), 451 deletions(-) create mode 100644 v3/@claude-flow/codex/README.md diff --git a/AGENTS.md b/AGENTS.md index c0139880ae..598c736abd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,481 +1,298 @@ # Claude Flow V3 - Agent Guide -> **For OpenAI Codex CLI** - This file follows the [Agentic AI Foundation](https://agenticfoundation.org) standard -> Use `$skill-name` syntax to invoke skills -> Configuration: `.agents/config.toml` -> Skills: `.agents/skills/` - -## Behavioral Rules (Always Enforced) - -- Do what has been asked; nothing more, nothing less -- NEVER create files unless they're absolutely necessary for achieving your goal -- ALWAYS prefer editing an existing file to creating a new one -- NEVER proactively create documentation files (*.md) or README files unless explicitly requested -- NEVER save working files, text/mds, or tests to the root folder -- Never continuously check status after spawning a swarm β€” wait for results -- ALWAYS read a file before editing it -- NEVER commit secrets, credentials, or .env files - -## File Organization - -- NEVER save to root folder β€” use the directories below -- Use `/src` for source code files -- Use `/tests` for test files -- Use `/docs` for documentation and markdown files -- Use `/config` for configuration files -- Use `/scripts` for utility scripts -- Use `/examples` for example code - -## Project Architecture - -- Follow Domain-Driven Design with bounded contexts -- Keep files under 500 lines -- Use typed interfaces for all public APIs -- Prefer TDD London School (mock-first) for new code -- Use event sourcing for state changes -- Ensure input validation at system boundaries - -### Key Packages - -| Package | Path | Purpose | -|---------|------|---------| -| `@claude-flow/cli` | `v3/@claude-flow/cli/` | CLI entry point (26 commands) | -| `@claude-flow/guidance` | `v3/@claude-flow/guidance/` | Governance control plane | -| `@claude-flow/hooks` | `v3/@claude-flow/hooks/` | 17 hooks + 12 workers | -| `@claude-flow/memory` | `v3/@claude-flow/memory/` | AgentDB + HNSW search | -| `@claude-flow/security` | `v3/@claude-flow/security/` | Input validation, CVE remediation | -| `@claude-flow/codex` | `v3/@claude-flow/codex/` | OpenAI Codex integration | - -## Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS - -- All operations MUST be concurrent/parallel when possible -- Use CLI commands for spawning agents - -**Mandatory patterns:** -- ALWAYS batch related operations together -- Use `npx claude-flow agent spawn` for agent creation -- ALWAYS batch file reads/writes/edits together -- ALWAYS batch terminal operations together -- ALWAYS batch memory store/retrieve operations together +> **For OpenAI Codex CLI** - Agentic AI Foundation standard +> Skills: `$skill-name` | Config: `.agents/config.toml` --- -## Swarm Orchestration +## ⚑ QUICK COMMANDS (NO DISCOVERY NEEDED) -- Initialize swarm using CLI when starting complex tasks -- Spawn agents using `npx claude-flow agent spawn` -- Start swarm execution using `npx claude-flow swarm start` - -### Swarm Initialization Pattern +### Spawn N-Agent Swarm (Copy-Paste Ready) ```bash -# Initialize swarm first -npx claude-flow swarm init --topology hierarchical --max-agents 8 --strategy specialized - -# Spawn required agents -npx claude-flow agent spawn --type coordinator --name swarm-coord -npx claude-flow agent spawn --type coder --name coder-1 -npx claude-flow agent spawn --type tester --name tester-1 - -# Start swarm execution with an objective -npx claude-flow swarm start --objective "Build REST API" --strategy development -``` - -### Task Management - -```bash -# Create a task -npx claude-flow task create --type implementation --description "Add user auth" - -# List tasks -npx claude-flow task list - -# Assign task to agent -npx claude-flow task assign task-123 --agent coder-1 -``` - -### 3-Tier Model Routing (ADR-026) - -| Tier | Handler | Latency | Cost | Use Cases | -|------|---------|---------|------|-----------| -| **1** | Agent Booster (WASM) | <1ms | $0 | Simple transforms (varβ†’const, add types, etc.) β€” **Skip LLM entirely** | -| **2** | Haiku/GPT-4o-mini | ~500ms | $0.0002 | Simple tasks, low complexity (<30%) | -| **3** | Sonnet/Opus/GPT-5 | 2-5s | $0.003-0.015 | Complex reasoning, architecture, security (>30%) | - -## Swarm Configuration & Anti-Drift - -### Anti-Drift Coding Swarm (PREFERRED DEFAULT) - -- ALWAYS use hierarchical topology for coding swarms -- Keep maxAgents at 6-8 for tight coordination -- Use specialized strategy for clear role boundaries -- Use `raft` consensus for hive-mind (leader maintains authoritative state) -- Run frequent checkpoints via `post-task` hooks -- Keep shared memory namespace for all agents -- Keep task cycles short with verification gates - -```javascript -swarm_init({ - topology: "hierarchical", - maxAgents: 8, - strategy: "specialized" -}) -``` - -## Swarm Protocols & Routing - -### Auto-Start Swarm Protocol - -When the user requests a complex task (multi-file changes, feature implementation, refactoring), **immediately execute this pattern in a SINGLE message:** - -```bash -# STEP 1: Initialize swarm coordination -npx claude-flow swarm init --topology hierarchical --max-agents 8 --strategy specialized - -# STEP 2: Spawn agents via CLI -npx claude-flow agent spawn --type coordinator --name swarm-coord -npx claude-flow agent spawn --type researcher --name researcher-1 -npx claude-flow agent spawn --type architect --name architect-1 +# 5-AGENT SWARM - Run these commands in sequence: +npx claude-flow swarm init --topology hierarchical --max-agents 8 +npx claude-flow agent spawn --type coordinator --name coord-1 npx claude-flow agent spawn --type coder --name coder-1 +npx claude-flow agent spawn --type coder --name coder-2 npx claude-flow agent spawn --type tester --name tester-1 npx claude-flow agent spawn --type reviewer --name reviewer-1 - -# STEP 3: Orchestrate task -npx claude-flow task orchestrate --task "Your task description" --strategy adaptive +npx claude-flow swarm start --objective "Your task here" --strategy development ``` -### Agent Routing (Anti-Drift) +### Common Swarm Patterns -| Code | Task | Agents | -|------|------|--------| -| 1 | Bug Fix | coordinator, researcher, coder, tester | -| 3 | Feature | coordinator, architect, coder, tester, reviewer | -| 5 | Refactor | coordinator, architect, coder, reviewer | -| 7 | Performance | coordinator, perf-engineer, coder | -| 9 | Security | coordinator, security-architect, auditor | -| 11 | Memory | coordinator, memory-specialist, perf-engineer | -| 13 | Docs | researcher, api-docs | +| Task | Exact Command | +|------|---------------| +| Init hierarchical swarm | `npx claude-flow swarm init --topology hierarchical --max-agents 8` | +| Init mesh swarm | `npx claude-flow swarm init --topology mesh --max-agents 5` | +| Init V3 mode (15 agents) | `npx claude-flow swarm init --v3-mode` | +| Spawn coder | `npx claude-flow agent spawn --type coder --name coder-1` | +| Spawn tester | `npx claude-flow agent spawn --type tester --name tester-1` | +| Spawn coordinator | `npx claude-flow agent spawn --type coordinator --name coord-1` | +| Spawn architect | `npx claude-flow agent spawn --type architect --name arch-1` | +| Spawn reviewer | `npx claude-flow agent spawn --type reviewer --name rev-1` | +| Spawn researcher | `npx claude-flow agent spawn --type researcher --name res-1` | +| Start swarm | `npx claude-flow swarm start --objective "task" --strategy development` | +| Check swarm status | `npx claude-flow swarm status` | +| List agents | `npx claude-flow agent list` | +| Stop swarm | `npx claude-flow swarm stop` | -**Codes 1-11: hierarchical/specialized (anti-drift). Code 13: mesh/balanced** +### Agent Types (Use with `--type`) -### Task Complexity Detection +| Type | Purpose | +|------|---------| +| `coordinator` | Orchestrates other agents | +| `coder` | Writes code | +| `tester` | Writes tests | +| `reviewer` | Reviews code | +| `architect` | Designs systems | +| `researcher` | Analyzes requirements | +| `security-architect` | Security design | +| `performance-engineer` | Optimization | -**AUTO-INVOKE SWARM when task involves:** +### Task Commands + +| Action | Command | +|--------|---------| +| Create task | `npx claude-flow task create --type implementation --description "desc"` | +| List tasks | `npx claude-flow task list` | +| Assign task | `npx claude-flow task assign TASK_ID --agent AGENT_NAME` | +| Task status | `npx claude-flow task status TASK_ID` | +| Cancel task | `npx claude-flow task cancel TASK_ID` | + +### Memory Commands + +| Action | Command | +|--------|---------| +| Store | `npx claude-flow memory store --key "key" --value "value" --namespace patterns` | +| Search | `npx claude-flow memory search --query "search terms"` | +| List | `npx claude-flow memory list --namespace patterns` | +| Retrieve | `npx claude-flow memory retrieve --key "key"` | + +--- + +## πŸš€ SWARM RECIPES + +### Recipe 1: Hello World Test (5 Agents) +```bash +npx claude-flow swarm init --topology mesh --max-agents 5 +npx claude-flow agent spawn --type coder --name hello-1 +npx claude-flow agent spawn --type coder --name hello-2 +npx claude-flow agent spawn --type coder --name hello-3 +npx claude-flow agent spawn --type coder --name hello-4 +npx claude-flow agent spawn --type coder --name hello-5 +npx claude-flow swarm start --objective "Print hello world" --strategy development +``` + +### Recipe 2: Feature Implementation (6 Agents) +```bash +npx claude-flow swarm init --topology hierarchical --max-agents 8 +npx claude-flow agent spawn --type coordinator --name lead +npx claude-flow agent spawn --type architect --name arch +npx claude-flow agent spawn --type coder --name impl-1 +npx claude-flow agent spawn --type coder --name impl-2 +npx claude-flow agent spawn --type tester --name test +npx claude-flow agent spawn --type reviewer --name review +npx claude-flow swarm start --objective "Implement [feature]" --strategy development +``` + +### Recipe 3: Bug Fix (4 Agents) +```bash +npx claude-flow swarm init --topology hierarchical --max-agents 4 +npx claude-flow agent spawn --type coordinator --name lead +npx claude-flow agent spawn --type researcher --name debug +npx claude-flow agent spawn --type coder --name fix +npx claude-flow agent spawn --type tester --name verify +npx claude-flow swarm start --objective "Fix [bug]" --strategy development +``` + +### Recipe 4: Security Audit (3 Agents) +```bash +npx claude-flow swarm init --topology hierarchical --max-agents 4 +npx claude-flow agent spawn --type coordinator --name lead +npx claude-flow agent spawn --type security-architect --name audit +npx claude-flow agent spawn --type reviewer --name review +npx claude-flow swarm start --objective "Security audit" --strategy development +``` + +### Recipe 5: V3 Full Coordination (15 Agents) +```bash +npx claude-flow swarm init --v3-mode +npx claude-flow swarm coordinate --agents 15 +``` + +--- + +## πŸ“‹ BEHAVIORAL RULES + +- Do what is asked; nothing more, nothing less +- NEVER create files unless absolutely necessary +- ALWAYS prefer editing existing files +- NEVER save to root folder +- NEVER commit secrets or .env files +- ALWAYS read a file before editing it +- NEVER check swarm status repeatedly - wait for results + +## πŸ“ FILE ORGANIZATION + +| Directory | Purpose | +|-----------|---------| +| `/src` | Source code | +| `/tests` | Test files | +| `/docs` | Documentation | +| `/config` | Configuration | +| `/scripts` | Utility scripts | + +## 🎯 WHEN TO USE SWARMS + +**USE SWARM:** - Multiple files (3+) - New feature implementation -- Refactoring across modules +- Cross-module refactoring - API changes with tests - Security-related changes - Performance optimization -- Database schema changes -**SKIP SWARM for:** +**SKIP SWARM:** - Single file edits - Simple bug fixes (1-2 lines) - Documentation updates - Configuration changes -- Quick questions/exploration - -## Project Configuration - -This project is configured with Claude Flow V3 (Anti-Drift Defaults): -- **Topology**: hierarchical (prevents drift via central coordination) -- **Max Agents**: 8 (smaller team = less drift) -- **Strategy**: specialized (clear roles, no overlap) -- **Consensus**: raft (leader maintains authoritative state) -- **Memory Backend**: hybrid (SQLite + AgentDB) -- **HNSW Indexing**: Enabled (150x-12,500x faster) -- **Neural Learning**: Enabled (SONA) - -## Available Skills - -Use `$skill-name` syntax to invoke: - -| Skill | Use Case | -|-------|----------| -| `$swarm-orchestration` | Multi-agent task coordination | -| `$memory-management` | Pattern storage and retrieval | -| `$sparc-methodology` | Structured development workflow | -| `$security-audit` | Security scanning and CVE detection | -| `$performance-analysis` | Performance profiling and benchmarking | -| `$github-automation` | GitHub workflow and PR management | -| `$hive-mind` | Byzantine fault-tolerant consensus | -| `$neural-training` | Neural pattern training (SONA, MoE) | -| `$hooks-automation` | Hook lifecycle management | -| `$workflow-automation` | Workflow creation and execution | -| `$agent-coordination` | Agent spawning and coordination | -| `$embeddings` | Vector embeddings and search | -| `$claims` | Claims-based authorization | - -## V3 CLI Commands (26 Commands, 140+ Subcommands) - -### Core Commands - -| Command | Subcommands | Description | -|---------|-------------|-------------| -| `init` | 4 | Project initialization with wizard, presets, skills, hooks | -| `agent` | 8 | Agent lifecycle (spawn, list, status, stop, metrics, pool, health, logs) | -| `swarm` | 6 | Multi-agent swarm coordination and orchestration | -| `memory` | 11 | AgentDB memory with vector search (150x-12,500x faster) | -| `mcp` | 9 | MCP server management and tool execution | -| `task` | 6 | Task creation, assignment, and lifecycle | -| `session` | 7 | Session state management and persistence | -| `config` | 7 | Configuration management and provider setup | -| `status` | 3 | System status monitoring with watch mode | -| `start` | 3 | Service startup and quick launch | -| `workflow` | 6 | Workflow execution and template management | -| `hooks` | 17 | Self-learning hooks + 12 background workers | -| `hive-mind` | 6 | Queen-led Byzantine fault-tolerant consensus | - -### Advanced Commands - -| Command | Subcommands | Description | -|---------|-------------|-------------| -| `daemon` | 5 | Background worker daemon (start, stop, status, trigger, enable) | -| `neural` | 5 | Neural pattern training (train, status, patterns, predict, optimize) | -| `security` | 6 | Security scanning (scan, audit, cve, threats, validate, report) | -| `performance` | 5 | Performance profiling (benchmark, profile, metrics, optimize, report) | -| `providers` | 5 | AI providers (list, add, remove, test, configure) | -| `plugins` | 5 | Plugin management (list, install, uninstall, enable, disable) | -| `deployment` | 5 | Deployment management (deploy, rollback, status, environments, release) | -| `embeddings` | 4 | Vector embeddings (embed, batch, search, init) - 75x faster | -| `claims` | 4 | Claims-based authorization (check, grant, revoke, list) | -| `migrate` | 5 | V2 to V3 migration with rollback support | -| `process` | 4 | Background process management | -| `doctor` | 1 | System diagnostics with health checks | -| `completions` | 4 | Shell completions (bash, zsh, fish, powershell) | - -### Quick CLI Examples - -```bash -# Initialize project -npx claude-flow init --wizard - -# Start daemon with background workers -npx claude-flow daemon start - -# Spawn an agent -npx claude-flow agent spawn -t coder --name my-coder - -# Initialize swarm -npx claude-flow swarm init --v3-mode - -# Search memory (HNSW-indexed) -npx claude-flow memory search -q "authentication patterns" - -# System diagnostics -npx claude-flow doctor --fix - -# Security scan -npx claude-flow security scan --depth full - -# Performance benchmark -npx claude-flow performance benchmark --suite all -``` - -## Available Agents (60+ Types) - -### Core Development -`coder`, `reviewer`, `tester`, `planner`, `researcher` - -### V3 Specialized Agents -`security-architect`, `security-auditor`, `memory-specialist`, `performance-engineer` - -### @claude-flow/security Module -CVE remediation, input validation, path security: -- `InputValidator` β€” Zod-based validation at boundaries -- `PathValidator` β€” Path traversal prevention -- `SafeExecutor` β€” Command injection protection -- `PasswordHasher` β€” bcrypt hashing -- `TokenGenerator` β€” Secure token generation - -### Swarm Coordination -`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator`, `collective-intelligence-coordinator`, `swarm-memory-manager` - -### Consensus & Distributed -`byzantine-coordinator`, `raft-manager`, `gossip-coordinator`, `consensus-builder`, `crdt-synchronizer`, `quorum-manager`, `security-manager` - -### Performance & Optimization -`perf-analyzer`, `performance-benchmarker`, `task-orchestrator`, `memory-coordinator`, `smart-agent` - -### GitHub & Repository -`github-modes`, `pr-manager`, `code-review-swarm`, `issue-tracker`, `release-manager`, `workflow-automation`, `project-board-sync`, `repo-architect`, `multi-repo-swarm` - -### SPARC Methodology -`sparc-coord`, `sparc-coder`, `specification`, `pseudocode`, `architecture`, `refinement` - -### Specialized Development -`backend-dev`, `mobile-dev`, `ml-developer`, `cicd-engineer`, `api-docs`, `system-architect`, `code-analyzer`, `base-template-generator` - -### Testing & Validation -`tdd-london-swarm`, `production-validator` - -## V3 Hooks System (17 Hooks + 12 Workers) - -### Hook Categories - -| Category | Hooks | Purpose | -|----------|-------|---------| -| **Core** | `pre-edit`, `post-edit`, `pre-command`, `post-command`, `pre-task`, `post-task` | Tool lifecycle | -| **Session** | `session-start`, `session-end`, `session-restore`, `notify` | Context management | -| **Intelligence** | `route`, `explain`, `pretrain`, `build-agents`, `transfer` | Neural learning | -| **Learning** | `intelligence` (trajectory-start/step/end, pattern-store/search, stats, attention) | Reinforcement | - -### 12 Background Workers - -| Worker | Priority | Description | -|--------|----------|-------------| -| `ultralearn` | normal | Deep knowledge acquisition | -| `optimize` | high | Performance optimization | -| `consolidate` | low | Memory consolidation | -| `predict` | normal | Predictive preloading | -| `audit` | critical | Security analysis | -| `map` | normal | Codebase mapping | -| `preload` | low | Resource preloading | -| `deepdive` | normal | Deep code analysis | -| `document` | normal | Auto-documentation | -| `refactor` | normal | Refactoring suggestions | -| `benchmark` | normal | Performance benchmarking | -| `testgaps` | normal | Test coverage analysis | - -### Essential Hook Commands - -```bash -# Core hooks -npx claude-flow hooks pre-task --description "[task]" -npx claude-flow hooks post-task --task-id "[id]" --success true -npx claude-flow hooks post-edit --file "[file]" --train-patterns - -# Session management -npx claude-flow hooks session-start --session-id "[id]" -npx claude-flow hooks session-end --export-metrics true -npx claude-flow hooks session-restore --session-id "[id]" - -# Intelligence routing -npx claude-flow hooks route --task "[task]" -npx claude-flow hooks explain --topic "[topic]" - -# Neural learning -npx claude-flow hooks pretrain --model-type moe --epochs 10 -npx claude-flow hooks build-agents --agent-types coder,tester - -# Background workers -npx claude-flow hooks worker list -npx claude-flow hooks worker dispatch --trigger audit -npx claude-flow hooks worker status -``` - -## Intelligence System (RuVector) - -V3 includes the RuVector Intelligence System: -- **SONA**: Self-Optimizing Neural Architecture (<0.05ms adaptation) -- **MoE**: Mixture of Experts for specialized routing -- **HNSW**: 150x-12,500x faster pattern search -- **EWC++**: Elastic Weight Consolidation (prevents forgetting) -- **Flash Attention**: 2.49x-7.47x speedup - -The 4-step intelligence pipeline: -1. **RETRIEVE** β€” Fetch relevant patterns via HNSW -2. **JUDGE** β€” Evaluate with verdicts (success/failure) -3. **DISTILL** β€” Extract key learnings via LoRA -4. **CONSOLIDATE** β€” Prevent catastrophic forgetting via EWC++ - -## Hive-Mind Consensus - -### Topologies -- `hierarchical` β€” Queen controls workers directly -- `mesh` β€” Fully connected peer network -- `hierarchical-mesh` β€” Hybrid (recommended) -- `adaptive` β€” Dynamic based on load - -### Consensus Strategies -- `byzantine` β€” BFT (tolerates f < n/3 faulty) -- `raft` β€” Leader-based (tolerates f < n/2) -- `gossip` β€” Epidemic for eventual consistency -- `crdt` β€” Conflict-free replicated data types -- `quorum` β€” Configurable quorum-based - -## V3 Performance Targets - -| Metric | Target | Status | -|--------|--------|--------| -| HNSW Search | 150x-12,500x faster | **Implemented** (persistent) | -| Memory Reduction | 50-75% with quantization | **Implemented** (3.92x Int8) | -| SONA Integration | Pattern learning | **Implemented** (ReasoningBank) | -| Flash Attention | 2.49x-7.47x speedup | In progress | -| MCP Response | <100ms | Achieved | -| CLI Startup | <500ms | Achieved | -| SONA Adaptation | <0.05ms | In progress | - -## Environment Variables - -```bash -# Configuration -CLAUDE_FLOW_CONFIG=./claude-flow.config.json -CLAUDE_FLOW_LOG_LEVEL=info - -# Provider API Keys -ANTHROPIC_API_KEY=sk-ant-... -OPENAI_API_KEY=sk-... -GOOGLE_API_KEY=... - -# MCP Server -CLAUDE_FLOW_MCP_PORT=3000 -CLAUDE_FLOW_MCP_HOST=localhost -CLAUDE_FLOW_MCP_TRANSPORT=stdio - -# Memory -CLAUDE_FLOW_MEMORY_BACKEND=hybrid -CLAUDE_FLOW_MEMORY_PATH=./data/memory -``` - -## Quick Setup - -```bash -# Add MCP servers -claude mcp add claude-flow npx claude-flow mcp start -claude mcp add ruv-swarm npx ruv-swarm mcp start # Optional - -# For Codex CLI -codex mcp add claude-flow npx claude-flow mcp start - -# Start daemon -npx claude-flow daemon start - -# Run doctor -npx claude-flow doctor --fix -``` - -## Security - -### Critical Rules -- NEVER commit secrets, credentials, or .env files -- NEVER hardcode API keys -- Always validate user input -- Use parameterized queries for SQL -- Sanitize output to prevent XSS - -### Path Security -- Validate all file paths -- Prevent directory traversal (../) -- Use absolute paths internally - -## Optional Plugins (20 Available) - -| Plugin | Description | -|--------|-------------| -| `@claude-flow/embeddings` | Vector embeddings with sql.js, HNSW, hyperbolic support | -| `@claude-flow/security` | Input validation, path security, CVE remediation | -| `@claude-flow/claims` | Claims-based authorization | -| `@claude-flow/neural` | Neural pattern training (SONA, MoE, EWC++) | -| `@claude-flow/plugins` | Plugin system core | -| `@claude-flow/performance` | Performance profiling and benchmarking | - -## Support - -- Documentation: https://github.com/ruvnet/claude-flow -- Issues: https://github.com/ruvnet/claude-flow/issues --- -Remember: **Claude Flow coordinates, agents execute!** +## πŸ”§ CLI REFERENCE + +### Swarm Commands +```bash +npx claude-flow swarm init [--topology TYPE] [--max-agents N] [--v3-mode] +npx claude-flow swarm start --objective "task" --strategy [development|research] +npx claude-flow swarm status [SWARM_ID] +npx claude-flow swarm stop [SWARM_ID] +npx claude-flow swarm scale --count N +npx claude-flow swarm coordinate --agents N +``` + +### Agent Commands +```bash +npx claude-flow agent spawn --type TYPE --name NAME +npx claude-flow agent list [--filter active|idle|busy] +npx claude-flow agent status AGENT_ID +npx claude-flow agent stop AGENT_ID +npx claude-flow agent metrics [AGENT_ID] +npx claude-flow agent health +npx claude-flow agent logs AGENT_ID +``` + +### Task Commands +```bash +npx claude-flow task create --type TYPE --description "desc" +npx claude-flow task list [--all] +npx claude-flow task status TASK_ID +npx claude-flow task assign TASK_ID --agent AGENT_NAME +npx claude-flow task cancel TASK_ID +npx claude-flow task retry TASK_ID +``` + +### Memory Commands +```bash +npx claude-flow memory store --key KEY --value VALUE [--namespace NS] +npx claude-flow memory search --query "terms" [--namespace NS] +npx claude-flow memory list [--namespace NS] +npx claude-flow memory retrieve --key KEY [--namespace NS] +npx claude-flow memory init [--force] +``` + +### Hooks Commands +```bash +npx claude-flow hooks pre-task --description "task" +npx claude-flow hooks post-task --task-id ID --success true +npx claude-flow hooks route --task "task" +npx claude-flow hooks session-start --session-id ID +npx claude-flow hooks session-end --export-metrics true +npx claude-flow hooks worker list +npx claude-flow hooks worker dispatch --trigger audit +``` + +### System Commands +```bash +npx claude-flow init [--wizard] [--codex] [--full] +npx claude-flow daemon start +npx claude-flow daemon stop +npx claude-flow daemon status +npx claude-flow doctor [--fix] +npx claude-flow status +npx claude-flow mcp start +``` + +--- + +## πŸ”Œ TOPOLOGIES + +| Topology | Use Case | Command Flag | +|----------|----------|--------------| +| `hierarchical` | Coordinated teams, anti-drift | `--topology hierarchical` | +| `mesh` | Peer-to-peer, equal agents | `--topology mesh` | +| `hierarchical-mesh` | Hybrid (recommended for V3) | `--topology hierarchical-mesh` | +| `ring` | Sequential processing | `--topology ring` | +| `star` | Central coordinator | `--topology star` | +| `adaptive` | Dynamic switching | `--topology adaptive` | + +## πŸ€– AGENT TYPES + +### Core +`coordinator`, `coder`, `tester`, `reviewer`, `architect`, `researcher` + +### Specialized +`security-architect`, `security-auditor`, `memory-specialist`, `performance-engineer` + +### Swarm Coordination +`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator` + +### Consensus +`byzantine-coordinator`, `raft-manager`, `gossip-coordinator` + +--- + +## βš™οΈ CONFIGURATION + +### Default Swarm Config +- Topology: `hierarchical` +- Max Agents: 8 +- Strategy: `specialized` +- Consensus: `raft` +- Memory: `hybrid` + +### Environment Variables +```bash +CLAUDE_FLOW_CONFIG=./claude-flow.config.json +CLAUDE_FLOW_LOG_LEVEL=info +CLAUDE_FLOW_MEMORY_BACKEND=hybrid +``` + +--- + +## πŸ”— SKILLS + +Invoke with `$skill-name`: + +| Skill | Purpose | +|-------|---------| +| `$swarm-orchestration` | Multi-agent coordination | +| `$memory-management` | Pattern storage/retrieval | +| `$sparc-methodology` | Structured development | +| `$security-audit` | Security scanning | +| `$performance-analysis` | Profiling | +| `$github-automation` | CI/CD management | +| `$hive-mind` | Byzantine consensus | +| `$neural-training` | Pattern learning | + +--- + +## πŸ“š SUPPORT + +- Docs: https://github.com/ruvnet/claude-flow +- Issues: https://github.com/ruvnet/claude-flow/issues + +**Remember: Copy-paste commands, no discovery needed!** diff --git a/v3/@claude-flow/codex/README.md b/v3/@claude-flow/codex/README.md new file mode 100644 index 0000000000..aee4c602b4 --- /dev/null +++ b/v3/@claude-flow/codex/README.md @@ -0,0 +1,218 @@ +# @claude-flow/codex + +OpenAI Codex CLI adapter for Claude Flow V3. Enables multi-agent orchestration for OpenAI Codex CLI following the [Agentic AI Foundation](https://agenticfoundation.org) standard. + +## Features + +- **AGENTS.md Generation** - Creates project instructions in Codex format +- **Skill Management** - 137+ skills with `$skill-name` invocation +- **Config Generation** - `.agents/config.toml` for Codex configuration +- **Dual Platform** - Supports both Claude Code and Codex simultaneously +- **Migration** - Convert CLAUDE.md to AGENTS.md format + +## Installation + +```bash +# Via claude-flow CLI (recommended) +npx claude-flow@alpha init --codex + +# Or install package directly +npm install @claude-flow/codex +``` + +## Quick Start + +### Using the CLI + +```bash +# Initialize for Codex +npx claude-flow@alpha init --codex + +# Full setup with all 137+ skills +npx claude-flow@alpha init --codex --full + +# Dual mode (both Claude Code and Codex) +npx claude-flow@alpha init --dual +``` + +### Programmatic Usage + +```typescript +import { CodexInitializer, initializeCodexProject } from '@claude-flow/codex'; + +// Quick initialization +const result = await initializeCodexProject('/path/to/project', { + template: 'full', + force: true, + dual: false, +}); + +// Or use the class directly +const initializer = new CodexInitializer(); +const result = await initializer.initialize({ + projectPath: '/path/to/project', + template: 'enterprise', + skills: ['swarm-orchestration', 'memory-management'], + force: false, + dual: true, +}); +``` + +## Directory Structure + +``` +project/ +β”œβ”€β”€ AGENTS.md # Main project instructions (Codex format) +β”œβ”€β”€ .agents/ +β”‚ β”œβ”€β”€ config.toml # Project configuration +β”‚ β”œβ”€β”€ skills/ # 137+ skills +β”‚ β”‚ β”œβ”€β”€ swarm-orchestration/ +β”‚ β”‚ β”‚ └── SKILL.md +β”‚ β”‚ β”œβ”€β”€ memory-management/ +β”‚ β”‚ β”‚ └── SKILL.md +β”‚ β”‚ └── ... +β”‚ └── README.md # Directory documentation +β”œβ”€β”€ .codex/ +β”‚ β”œβ”€β”€ config.toml # Local overrides (gitignored) +β”‚ └── AGENTS.override.md # Local instruction overrides +└── .claude-flow/ + β”œβ”€β”€ config.yaml # Runtime configuration + β”œβ”€β”€ data/ # Memory and cache + └── logs/ # Log files +``` + +## Templates + +| Template | Skills | Description | +|----------|--------|-------------| +| `minimal` | 2 | Core skills only | +| `default` | 4 | Standard setup | +| `full` | 137+ | All available skills | +| `enterprise` | 137+ | Full + governance | + +## Platform Comparison + +| Feature | Claude Code | OpenAI Codex | +|---------|-------------|--------------| +| Config File | CLAUDE.md | AGENTS.md | +| Skills Dir | .claude/skills/ | .agents/skills/ | +| Skill Syntax | `/skill-name` | `$skill-name` | +| Settings | settings.json | config.toml | +| Approval | 3 levels | 4 levels | + +## Skill Invocation + +In OpenAI Codex CLI, invoke skills with `$` prefix: + +``` +$swarm-orchestration +$memory-management +$sparc-methodology +$security-audit +$agent-coder +$agent-tester +``` + +## Configuration + +### .agents/config.toml + +```toml +# Model configuration +model = "gpt-4" + +# Approval policy +approval_policy = "on-request" + +# Sandbox mode +sandbox_mode = "workspace-write" + +# Skills +[[skills]] +path = ".agents/skills/swarm-orchestration" +enabled = true + +[[skills]] +path = ".agents/skills/memory-management" +enabled = true +``` + +### .codex/config.toml (Local) + +```toml +# Local development overrides (gitignored) +approval_policy = "never" +sandbox_mode = "danger-full-access" +web_search = "live" +``` + +## API Reference + +### CodexInitializer + +```typescript +class CodexInitializer { + async initialize(options: CodexInitOptions): Promise; + async dryRun(options: CodexInitOptions): Promise; +} +``` + +### initializeCodexProject + +```typescript +async function initializeCodexProject( + projectPath: string, + options?: Partial +): Promise; +``` + +### Types + +```typescript +interface CodexInitOptions { + projectPath: string; + template?: 'minimal' | 'default' | 'full' | 'enterprise'; + skills?: string[]; + force?: boolean; + dual?: boolean; +} + +interface CodexInitResult { + success: boolean; + filesCreated: string[]; + skillsGenerated: string[]; + warnings?: string[]; + errors?: string[]; +} +``` + +## Migration + +Convert an existing CLAUDE.md project to Codex format: + +```typescript +import { migrate } from '@claude-flow/codex'; + +const result = await migrate({ + sourcePath: './CLAUDE.md', + targetPath: './AGENTS.md', + preserveComments: true, + generateSkills: true, +}); +``` + +## Related Packages + +- [@claude-flow/cli](https://www.npmjs.com/package/@claude-flow/cli) - Main CLI +- [claude-flow](https://www.npmjs.com/package/claude-flow) - Umbrella package +- [@claude-flow/memory](https://www.npmjs.com/package/@claude-flow/memory) - AgentDB memory +- [@claude-flow/security](https://www.npmjs.com/package/@claude-flow/security) - Security module + +## License + +MIT + +## Support + +- Documentation: https://github.com/ruvnet/claude-flow +- Issues: https://github.com/ruvnet/claude-flow/issues