CLAUDE.md · ruvnet/ruflo

Sections

1. Behavioral Rules (Always Enforced)
2. Capability Brain and Governed Implementation
3. File Organization
4. Project Architecture
5. Concurrent Automated Development
6. Swarm Orchestration
7. Swarm Configuration & Anti-Drift
8. Dual-Mode Collaboration (Claude Code + Codex)
9. Swarm Protocols & Routing
10. Project Configuration
11. V3 CLI Commands (26 Commands, 140+ Subcommands)
12. Headless Background Instances (claude -p)
13. Available Agents (60+ Types)
14. Agent Teams & Comms System
15. V3 Hooks System (17 Hooks + 12 Workers)
16. Intelligence System (RuVector)
17. Embeddings Package (v3.0.0-alpha.12)
18. Hive-Mind Consensus
19. V3 Performance Targets
20. Environment Variables

First lines (shown under the repo's MIT license)

# Claude Code Configuration - Ruflo V3

> Public release train: `@claude-flow/cli`, `claude-flow`, and `ruflo`.
> Use package manifests and the registry as version truth; do not copy stale
> version or capability counts into agent guidance.

## 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

## Capability Brain and Governed Implementation

Ruflo is the coordination ledger and policy decision point. Claude Code
executes code, tests, commands, and file changes. A Ruflo coordination call
records work; it does not perform the implementation.

When registered, call
`guidance_brain({ mode: "recommend", task: "..." })` before complex Ruflo
work. Use its live registry rather than guessing tool names. Treat
`registered`, `configured`, `reachable`, `healthy`, and `authorized` as
separate facts. If unavailable, continue with compatible guidance tools, CLI
discovery, and these repository instructions.

Use this loop: recall → inspect → route → plan → execute → test → validate →
benchmark → optimize → receipt → handoff → separately authorized publish.

## 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/codex` | `v3/@claude-flow/codex/` | Dual-mode Claude + Codex collaboration |
| `@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 |

## Concurrent Automated Development

- Parallelize independent research, tests, reviews, and non-overlapping
  implementation.
- Never allow two writers in one worktree. Give every writing agent an isolated
  worktree and explicit file ownership.
- Read-only agents may share a checkout; writing agents may not.
- Only the integration owner edits shared manifests and lockfiles or reconciles
  overlapping changes.
- Continue independent local work after spawning agents; wait only when a real
  dependency blocks progress. Do not repeatedly poll.
- A lease or work claim coordinates ownership; it never grants authority.
- Bind tests, benchmarks, policy decisions, and handoffs to an exact clean
  commit or immutable dirty-worktree snapshot.
- Darwin, Flywheel, MetaHarness, memory, and neural systems may propose and
  evaluate candidates, but cannot self-promote or expand tools, network,
  secrets, spend, concurrency, or release authority.

---

## Swarm Orchestration

- MUST initialize the swarm using MCP tools when starting complex tasks
- MUST spawn concurrent agents using Claude Code's Task tool
- Never use MCP tools alone for execution — Task tool agents do the actual work

### MCP + Task Tool in SAME Message

- MUST call MCP tools AND Task tool in ONE message for complex work
- Always call MCP first, then IMMEDIATELY call Task tool to spawn agents

### 3-Tier Model Routing (ADR-026, ADR-143)

| Tier | Handler | Latency | Cost | Use Cases |
|------|---------|---------|------|-----------|
| **1** | Deterministic codemod | ~1ms | $0 | Structural transforms with **no LLM**: `var-to-const`, `remove-console`, `add-logging` |
| **2** | Haiku | ~500ms | $0.0002 | Simple tasks, low complexity (<30%) |
| **3** | Sonnet/Opus | 2-5s | $0.003-0.015 | Complex reasoning, architecture, security (>30%) |

- Always check for `[CODEMOD_AVAILABLE]` or `[TASK_MODEL_RECOMMENDATION]` before spawning agents
- When you see `[CODEMOD_AVAILABLE]`, call the `hooks_codemod` MCP tool (intent + file) — it applies the transform deterministically via the TypeScript compiler at $0, no LLM. Deterministic intents only: `var-to-const`, `remove-console`, `add-logging`
- `add-types`, `add-error-handling`, `async-await` need judgement and route to a model (Tier 2/3) — they are **not** $0 codemods (see ADR-143)
- Agent Booster (`agent-booster`) is a fast-apply merge engine for arbitrary LLM-produced edit snippets, not an intent-transform engine — it is **not** the Tier-1 path

## 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
mcp__ruv-swarm__swarm_init({
  topology: "hierarchical",
  maxAgents: 8,
  strategy: "specialized"
})
```

## Dual-Mode Collaboration (Claude Code + Codex)

This repository uses **dual-mode orchestration** to run Claude Code (🔵) and OpenAI Codex (🟢) workers in parallel with shared memory coordination. Both platforms collaborate on development tasks with cross-learning.

### Why Dual-Mode?

| Single Platform | Dual-Mode Collaboration |
|----------------|------------------------|
| One model's perspective | Two AI platforms cross-validating |
| Limited reasoning styles | Complementary strengths |
| No external verification | Built-in code review |
| Sequential workflows | Parallel execution |

### Dual-Mode Swarm Protocol

For complex tasks, spawn both Claude and Codex workers in parallel:

```javascript
// STEP 1: Initialize dual-mode swarm
mcp__ruv-swarm__swarm_init({
  topology: "hierarchical",
  maxAgents: 8,
  strategy: "specialized"
})

// STEP 2: Spawn BOTH platforms in parallel via Task tool
// 🔵 Claude Code workers (architecture, security, testing)
Task("Architect", "Design the implementation. Store design in memory namespace 'collaboration'.", "system-architect")
Task("Tester", "Write tests based on architect's design. Read from 'collaboration' namespace.", "tester")
Task("Reviewer", "Review code quality and security. Store findings in 'collaboration'.", "reviewer")

// 🟢 Codex workers (implementation, optimization)
// Spawn via CLI for Codex platform