Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

Checkpoint: File edits

rUv0acaf1dbf853
diff --git a/agents/architect.yaml b/agents/architect.yaml
index 6a70dce3b8..22ea4bd174 100644
--- a/agents/architect.yaml
+++ b/agents/architect.yaml
@@ -8,4 +8,4 @@ capabilities:
optimizations:
- context-caching
- memory-persistence
-createdAt: "2026-02-02T06:42:11.370Z"
+createdAt: "2026-02-07T15:58:18.961Z"
diff --git a/agents/coder.yaml b/agents/coder.yaml
index cfad696206..5dff386291 100644
--- a/agents/coder.yaml
+++ b/agents/coder.yaml
@@ -8,4 +8,4 @@ capabilities:
optimizations:
- flash-attention
- token-reduction
-createdAt: "2026-02-02T06:42:11.370Z"
+createdAt: "2026-02-07T15:58:18.960Z"
diff --git a/agents/reviewer.yaml b/agents/reviewer.yaml
index 88990357d1..d1866c1111 100644
--- a/agents/reviewer.yaml
+++ b/agents/reviewer.yaml
@@ -7,4 +7,4 @@ capabilities:
- best-practices
optimizations:
- incremental-analysis
-createdAt: "2026-02-02T06:42:11.370Z"
+createdAt: "2026-02-07T15:58:18.961Z"
diff --git a/agents/security-architect.yaml b/agents/security-architect.yaml
index da9c86b336..bba2db1e99 100644
--- a/agents/security-architect.yaml
+++ b/agents/security-architect.yaml
@@ -7,4 +7,4 @@ capabilities:
- security-review
optimizations:
- pattern-matching
-createdAt: "2026-02-02T06:42:11.370Z"
+createdAt: "2026-02-07T15:58:18.961Z"
diff --git a/agents/tester.yaml b/agents/tester.yaml
index 4fb79b58b5..119bc78421 100644
--- a/agents/tester.yaml
+++ b/agents/tester.yaml
@@ -7,4 +7,4 @@ capabilities:
- coverage
optimizations:
- parallel-execution
-createdAt: "2026-02-02T06:42:11.370Z"
+createdAt: "2026-02-07T15:58:18.961Z"
diff --git a/docs/adr/ADR-027-codex-integration.md b/docs/adr/ADR-027-codex-integration.md
new file mode 100644
index 0000000000..afe53bd8ff
--- /dev/null
+++ b/docs/adr/ADR-027-codex-integration.md
@@ -0,0 +1,481 @@
+# ADR-027: OpenAI Codex Integration
+
+## Status
+**Proposed** | 2026-02-07
+
+## Context
+
+### The Agentic Coding Landscape
+
+The agentic coding tool landscape has evolved into two major platforms:
+
+1. **Claude Code** (Anthropic) - CLI tool using CLAUDE.md for project instructions
+2. **OpenAI Codex** (OpenAI) - CLI tool using AGENTS.md for project instructions
+
+Both tools share similar concepts but with different implementations:
+
+| Concept | Claude Code | OpenAI Codex |
+|---------|-------------|--------------|
+| Project Instructions | `CLAUDE.md` | `AGENTS.md` |
+| Nested Instructions | `CLAUDE.local.md` | `AGENTS.override.md` |
+| Skills | `.claude/skills/` | `.agents/skills/` + `SKILL.md` |
+| Configuration | `.claude/settings.json` | `~/.codex/config.toml` |
+| MCP Integration | `.mcp.json` | `config.toml [mcp_servers]` |
+| Agent Types | Task tool with subagent_type | Agents SDK integration |
+| Automation | Hooks system | Automations (scheduled tasks) |
+| Session Management | Session persistence | `codex resume`, `codex fork` |
+| Non-interactive | `claude -p` | `codex exec` |
+| Approval Modes | Permission modes | Approval policies |
+| Sandbox | Sandboxing settings | Sandbox modes (read-only, workspace-write, full-access) |
+
+### Research Findings
+
+#### AGENTS.md Specification
+
+AGENTS.md is an open standard managed by the [Agentic AI Foundation](https://agents.md/) under the Linux Foundation. Key characteristics:
+
+- **Discovery Precedence**: Global (`~/.codex/AGENTS.md`) β†’ Project root β†’ Current directory
+- **Override Mechanism**: `AGENTS.override.md` takes precedence over `AGENTS.md`
+- **Byte Limit**: Default 32 KiB combined instruction size (`project_doc_max_bytes`)
+- **Fallback Filenames**: Configurable via `project_doc_fallback_filenames`
+- **Monorepo Support**: Nested AGENTS.md files per package/directory
+
+#### Skills System
+
+Codex Skills follow the [Open Agent Skills Specification](https://developers.openai.com/codex/skills):
+
+```
+my-skill/
+β”œβ”€β”€ SKILL.md # Required: instructions + metadata
+β”œβ”€β”€ scripts/ # Optional: executable code
+β”œβ”€β”€ references/ # Optional: documentation
+β”œβ”€β”€ assets/ # Optional: templates, resources
+└── agents/
+ └── openai.yaml # Optional: UI config and dependencies
+```
+
+SKILL.md format:
+```yaml
+---
+name: skill-name
+description: When this skill should and should not trigger.
+---
+
+Skill instructions for Codex to follow.
+```
+
+**Progressive Disclosure**: Codex loads only skill metadata initially, full instructions load on-demand.
+
+**Skill Locations**:
+| Scope | Path |
+|-------|------|
+| Repository (CWD) | `.agents/skills` |
+| Repository (Root) | `$REPO_ROOT/.agents/skills` |
+| User | `$HOME/.agents/skills` |
+| Admin | `/etc/codex/skills` |
+| System | Bundled with Codex |
+
+#### Config.toml Configuration
+
+Codex configuration is TOML-based with extensive options:
+
+```toml
+# Core settings
+model = "gpt-5.3-codex"
+approval_policy = "on-request" # untrusted | on-failure | on-request | never
+sandbox_mode = "workspace-write" # read-only | workspace-write | danger-full-access
+web_search = "cached" # disabled | cached | live
+
+# Features
+[features]
+shell_snapshot = true
+child_agents_md = true
+
+# MCP servers
+[mcp_servers.my-server]
+command = "npx"
+args = ["my-mcp-server"]
+enabled = true
+
+# Profiles for different workflows
+[profiles.dev]
+approval_policy = "never"
+sandbox_mode = "danger-full-access"
+```
+
+#### Automations
+
+Codex Automations enable scheduled background tasks:
+- Run on configurable schedules
+- Combine with skills via `$skill-name` syntax
+- Results appear in triage inbox
+- Respect sandbox settings
+
+#### Agents SDK Integration
+
+Codex can run as an MCP server for multi-agent orchestration:
+```bash
+codex mcp-server
+```
+
+Exposes tools: `codex` (start session) and `codex-reply` (continue session).
+
+## Decision
+
+We will create a **parallel Codex integration** in claude-flow that:
+
+1. **Adds `init --codex` flag** to generate Codex-compatible configuration
+2. **Generates AGENTS.md** instead of/alongside CLAUDE.md
+3. **Creates `.agents/skills/`** with SKILL.md format skills
+4. **Generates `config.toml`** for Codex settings
+5. **Maps claude-flow concepts** to Codex equivalents
+6. **Supports dual-mode** projects (both Claude Code and Codex)
+
+### Architecture
+
+```
+claude-flow init --codex
+β”œβ”€β”€ AGENTS.md # Project instructions (Codex format)
+β”œβ”€β”€ .agents/
+β”‚ β”œβ”€β”€ skills/ # Skills directory
+β”‚ β”‚ β”œβ”€β”€ swarm-orchestration/
+β”‚ β”‚ β”‚ β”œβ”€β”€ SKILL.md
+β”‚ β”‚ β”‚ β”œβ”€β”€ scripts/
+β”‚ β”‚ β”‚ └── references/
+β”‚ β”‚ β”œβ”€β”€ memory-management/
+β”‚ β”‚ β”œβ”€β”€ sparc-methodology/
+β”‚ β”‚ └── ...
+β”‚ └── config.toml # Project-level Codex config
+β”œβ”€β”€ .codex/ # Local overrides (gitignored)
+β”‚ β”œβ”€β”€ config.toml # User config overrides
+β”‚ └── AGENTS.override.md # Local instruction overrides
+└── .claude-flow/ # Runtime (shared between both)
+ β”œβ”€β”€ config.yaml
+ └── data/
+```
+
+### Mapping Table
+
+| claude-flow Concept | Claude Code Output | Codex Output |
+|---------------------|-------------------|--------------|
+| Project instructions | `CLAUDE.md` | `AGENTS.md` |
+| Local overrides | `CLAUDE.local.md` | `AGENTS.override.md` |
+| Skills directory | `.claude/skills/` | `.agents/skills/` |
+| Skill format | `skill-name.md` (YAML frontmatter) | `skill-name/SKILL.md` |
+| Settings | `.claude/settings.json` | `.agents/config.toml` |
+| MCP config | `.mcp.json` | `config.toml [mcp_servers]` |
+| Hooks | `settings.json` hooks | Automations |
+| Agent definitions | `.claude/agents/` | Skills with agent-specific SKILL.md |
+
+### Command-Line Interface
+
+```bash
+# Initialize for Codex only
+claude-flow init --codex
+
+# Initialize for both platforms (dual-mode)
+claude-flow init --dual
+
+# Initialize with wizard (auto-detects or asks)
+claude-flow init wizard
+
+# Convert existing Claude Code setup to Codex
+claude-flow init --codex --from-claude
+
+# Convert existing Codex setup to Claude Code
+claude-flow init --from-codex
+```
+
+### Generated AGENTS.md Structure
+
+```markdown
+# Claude Flow V3
+
+## Project Overview
+[Auto-detected project description]
+
+## Quick Start
+[Build and test commands]
+
+## Agent Coordination
+
+### Swarm Configuration
+- Topology: hierarchical
+- Max Agents: 8
+- Strategy: specialized
+
+### Available Skills
+Use `$skill-name` to invoke:
+- `$swarm-orchestration` - Multi-agent coordination
+- `$memory-management` - AgentDB integration
+- `$sparc-methodology` - SPARC development workflow
+
+## Code Standards
+[From CLAUDE.md Code Quality Rules]
+
+## Security
+- Never commit secrets
+- Input validation at boundaries
+- Path traversal prevention
+
+## Performance Targets
+[From V3 performance targets]
+```
+
+### Generated SKILL.md Example
+
+```yaml
+---
+name: swarm-orchestration
+description: >
+ Use when coordinating multiple agents for complex tasks.
+ Triggers for: multi-file changes, feature implementation,
+ refactoring, performance optimization, security audits.
+ Skip for: single file edits, simple fixes, documentation.
+---
+
+# Swarm Orchestration Skill
+
+## When to Use
+- Complex tasks requiring 3+ agents
+- Multi-file changes
+- Cross-module refactoring
+
+## Available Agents
+| Type | Use Case |
+|------|----------|
+| researcher | Requirements analysis |
+| architect | System design |
+| coder | Implementation |
+| tester | Test writing |
+| reviewer | Code review |
+
+## Execution Pattern
+
+### 1. Initialize Swarm
+```bash
+npx claude-flow@v3alpha swarm init --topology hierarchical
+```
+
+### 2. Spawn Agents
+Use Codex to orchestrate via MCP:
+```bash
+npx claude-flow@v3alpha mcp start
+```
+
+### 3. Monitor Progress
+```bash
+npx claude-flow@v3alpha swarm status
+```
+
+## Memory Integration
+Store patterns for learning:
+```bash
+npx claude-flow@v3alpha memory store --key "[pattern]" --value "[learned]"
+```
+```
+
+### Generated config.toml
+
+```toml
+# Claude Flow V3 - Codex Configuration
+# Generated by: claude-flow init --codex
+
+model = "gpt-5.3-codex"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+web_search = "cached"
+
+# Project documentation
+project_doc_max_bytes = 65536
+project_doc_fallback_filenames = ["AGENTS.md", "TEAM_GUIDE.md", ".agents.md"]
+
+[features]
+child_agents_md = true
+shell_snapshot = true
+request_rule = true
+
+# MCP Servers
+[mcp_servers.claude-flow]
+command = "npx"
+args = ["-y", "@claude-flow/cli@latest"]
+enabled = true
+tool_timeout_sec = 120
+
+[mcp_servers.ruv-swarm]
+command = "npx"
+args = ["-y", "ruv-swarm", "mcp", "start"]
+enabled = true
+
+# Skills configuration
+[[skills.config]]
+path = ".agents/skills/swarm-orchestration"
+enabled = true
+
+[[skills.config]]
+path = ".agents/skills/memory-management"
+enabled = true
+
+[[skills.config]]
+path = ".agents/skills/sparc-methodology"
+enabled = true
+
+# Profiles
+[profiles.dev]
+approval_policy = "never"
+sandbox_mode = "danger-full-access"
+
+[profiles.safe]
+approval_policy = "untrusted"
+sandbox_mode = "read-only"
+```
+
+## Consequences
+
+### Positive
+1. **Cross-platform support** - Users can use either Claude Code or Codex
+2. **Ecosystem reach** - AGENTS.md is supported by 20+ tools (Cursor, Copilot, etc.)
+3. **Standard compliance** - Follows AAIF and Open Agent Skills specifications
+4. **Migration path** - Easy conversion between platforms
+5. **Dual-mode** - Single project can support both tools
+
+### Negative
+1. **Maintenance burden** - Two sets of generators to maintain
+2. **Sync complexity** - Keeping CLAUDE.md and AGENTS.md in sync
+3. **Feature parity** - Some features may not map 1:1
+
+### Risks
+1. **Specification drift** - AGENTS.md spec may evolve
+2. **Tool differences** - Behavioral differences between platforms
+3. **Ecosystem fragmentation** - Users may expect identical behavior
+
+## Implementation Plan
+
+### Phase 1: Core Infrastructure (Week 1-2)
+1. Create `@claude-flow/codex` package
+2. Implement AGENTS.md generator
+3. Implement SKILL.md generator
+4. Implement config.toml generator
+
+### Phase 2: Init Integration (Week 3)
+1. Add `--codex` flag to init command
+2. Add `--dual` flag for both platforms
+3. Add `--from-claude` and `--from-codex` conversion
+4. Update wizard to support platform selection
+
+### Phase 3: Skills Library (Week 4)
+1. Convert all `.claude/skills/` to `.agents/skills/` format
+2. Create skill migration script
+3. Test skill discovery and loading
+
+### Phase 4: Automation Integration (Week 5)
+1. Map claude-flow hooks to Codex Automations
+2. Create automation templates
+3. Document automation patterns
+
+## References
+
+### Official Documentation
+- [AGENTS.md Specification](https://agents.md/)
+- [OpenAI Codex CLI](https://developers.openai.com/codex/cli/)
+- [Codex Skills](https://developers.openai.com/codex/skills)
+- [Codex Configuration Reference](https://developers.openai.com/codex/config-reference/)
+- [Codex Automations](https://developers.openai.com/codex/app/automations/)
+- [Agents SDK Integration](https://developers.openai.com/codex/guides/agents-sdk/)
+
+### GitHub Repositories
+- [OpenAI Codex](https://github.com/openai/codex)
+- [Codex AGENTS.md Example](https://github.com/openai/codex/blob/main/AGENTS.md)
+
+### Related Standards
+- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
+- [Agentic AI Foundation](https://aaif.org/)
+
+## Appendix A: Complete Feature Mapping
+
+### AGENTS.md Sections (Claude Flow Template)
+
+| Section | Content Source |
+|---------|----------------|
+| Project Overview | Auto-detected from package.json, README |
+| Quick Start | Build/test commands from package.json |
+| Agent Coordination | From CLAUDE.md swarm config |
+| Code Standards | From CLAUDE.md behavioral rules |
+| Security | From @claude-flow/security patterns |
+| Performance | From V3 performance targets |
+| Testing | From TDD/testing patterns |
+| Memory | From AgentDB integration |
+
+### Skill Mapping (Full List)
+
+| Claude Code Skill | Codex Skill Directory |
+|-------------------|----------------------|
+| `swarm-orchestration.md` | `.agents/skills/swarm-orchestration/` |
+| `agentdb-advanced.md` | `.agents/skills/memory-management/` |
+| `sparc-methodology.md` | `.agents/skills/sparc-methodology/` |
+| `github-workflow-automation.md` | `.agents/skills/github-automation/` |
+| `v3-core-implementation.md` | `.agents/skills/v3-core/` |
+| `pair-programming.md` | `.agents/skills/pair-programming/` |
+| `performance-analysis.md` | `.agents/skills/performance-analysis/` |
+| `v3-security-overhaul.md` | `.agents/skills/security-audit/` |
+| `hive-mind-advanced.md` | `.agents/skills/hive-mind/` |
+| `reasoningbank-intelligence.md` | `.agents/skills/adaptive-learning/` |
+
+### Config.toml Feature Mapping
+
+| Claude Code Feature | Codex config.toml |
+|--------------------|--------------------|
+| Hooks: PreToolUse | `approval_policy` |
+| Hooks: PostToolUse | Automations |
+| Hooks: UserPromptSubmit | Skills + Automations |
+| Permission modes | `approval_policy` + `sandbox_mode` |
+| MCP servers | `[mcp_servers]` table |
+| Model selection | `model` |
+| Session persistence | `history.persistence` |
+
+## Appendix B: Codex CLI Reference
+
+### Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `codex` | Interactive terminal UI |
+| `codex exec` | Non-interactive execution |
+| `codex resume` | Continue previous session |
+| `codex fork` | Branch from existing session |
+| `codex cloud` | Cloud task management |
+| `codex apply` | Apply diffs from cloud tasks |
+
+### MCP Commands
+
+| Command | Description |
+|---------|-------------|
+| `codex mcp list` | List configured servers |
+| `codex mcp add <name>` | Add new server |
+| `codex mcp remove <name>` | Remove server |
+| `codex mcp-server` | Run Codex as MCP server |
+
+### Feature Commands
+
+| Command | Description |
+|---------|-------------|
+| `codex features list` | Show feature flags |
+| `codex features enable <flag>` | Enable feature |
+| `codex features disable <flag>` | Disable feature |
+
+### Approval Policies
+
+| Policy | Behavior |
+|--------|----------|
+| `untrusted` | Prompt for every command |
+| `on-failure` | Prompt only on failures |
+| `on-request` | Prompt when agent requests |
+| `never` | Never prompt (dangerous) |
+
+### Sandbox Modes
+
+| Mode | Behavior |
+|------|----------|
+| `read-only` | No file/network modifications |
+| `workspace-write` | Write only to workspace |
+| `danger-full-access` | Full system access |