# Claude Code Configuration — Ruflo Dual-Agent Workflow

## Agent Roles (Non-Negotiable)

| Agent | Responsibilities |
|-------|-----------------|
| **Claude** | Planning, architecture, pseudocode, tradeoff analysis, validation, review |
| **Codex** | All implementation: writing files, editing code, CLI ops, refactoring, debugging |
| **Ruflo** | Orchestration, task delegation, shared memory between agents |

**Claude MUST NOT write production code, full implementations, or complete file edits.**
**Claude MUST NOT output full files or multi-function implementations — all such work must be delegated.**
**Claude MUST delegate all execution to Codex via Ruflo before attempting it directly.**

## The Mandatory Workflow Loop

For every task that involves implementation:

1. **Analyze** — understand requirements, constraints, relevant files
2. **Decompose** — break into discrete units (each unit = one Codex call)
3. **Delegate** — assign each unit to Codex with a clear, structured spec
4. **Wait** — do not add tool calls after delegating; wait for results
5. **Review** — critically examine Codex output for correctness and completeness
6. **Refine** — if output is wrong or incomplete, re-delegate with corrected spec

**FAILSAFE: If Claude detects it is about to write code, edit a file, or run a CLI command — STOP and delegate instead.**

## Delegation Rules

**Use Codex for:**
- Writing any source file (any language)
- Editing existing files
- Refactoring and mechanical fixes
- Running validation, lint, tests
- Writing shell scripts and config files
- Debugging implementation errors

**Use Claude for:**
- Requirements analysis
- System design and API contract design
- Pseudocode and algorithm sketches (illustrative only, not production)
- Architecture Decision Records
- Reviewing and critiquing Codex output
- Tradeoff analysis

**Codex invocation pattern:**
```bash
/home/aaron/.npm-global/bin/codex "<structured task spec with exact file paths, requirements, and acceptance criteria>"
```

## Exceptions — Claude Writes Directly Only When

- The task requires judgment Codex demonstrably cannot provide (novel validation logic, cross-reference reasoning)
- Codex has already failed on the same task in this session
- The change is a single Edit tool call on a non-production file (config, doc)

## Behavioral Rules (Always Enforced)

- Read `CLAUDE.md`, `AGENTS.md`, and `AGENT_RULES.md` before starting substantive work
- Read `RTK.md` and prefer `rtk` for noisy shell output, including Codex task specs that ask agents to inspect, search, test, or summarize command output
- Do what has been asked; nothing more, nothing less
- NEVER create files unless absolutely necessary for achieving the goal
- ALWAYS prefer editing an existing file to creating a new one
- NEVER proactively create documentation or README files unless explicitly requested
- NEVER save working files or scratch notes to the root folder
- ALWAYS read a file before editing it
- NEVER commit secrets, credentials, or `.env` files
- Never continuously check status after spawning a swarm — wait for results

## File Organization

- `/src` — source code
- `/tests` — test files
- `/docs` — documentation and markdown
- `/config` — configuration files
- `/scripts` — utility scripts
- `/examples` — example code

## Project Architecture

- Domain-Driven Design with bounded contexts
- Files under 500 lines
- Typed interfaces for all public APIs
- TDD London School (mock-first) for new code
- Event sourcing for state changes
- Input validation at all system boundaries

### Project Config

- **Topology**: hierarchical-mesh
- **Max Agents**: 15
- **Memory**: hybrid
- **HNSW**: Enabled
- **Neural**: Enabled

## Build & Test

```bash
npm run build   # Build
npm test        # Test
npm run lint    # Lint
```

- ALWAYS run tests after any code change (via Codex)
- ALWAYS verify build succeeds before committing

## Security Rules

- NEVER hardcode API keys, secrets, or credentials in source files
- NEVER commit `.env` files or any file containing secrets
- Always validate user input at system boundaries
- Always sanitize file paths to prevent directory traversal
- Run `npx @claude-flow/cli@latest security scan` after security-related changes

## Concurrency: 1 Message = All Related Operations

- All operations MUST be concurrent/parallel in a single message
- ALWAYS spawn ALL agents in ONE message with full instructions via Agent tool
- ALWAYS batch ALL file reads in ONE message
- ALWAYS batch ALL Bash commands in ONE message

## Swarm Orchestration

- Initialize swarm via CLI for complex tasks before delegating
- Spawn concurrent agents using Claude Code's Agent tool
- Never use CLI tools alone for execution — Agent tool agents do the actual work
- Call CLI tools AND Agent tool in ONE message for complex work

```bash
npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized
```

## Swarm Execution Rules

- ALWAYS use `run_in_background: true` for all Agent tool calls
- ALWAYS put ALL Agent calls in ONE message for parallel execution
- After spawning, STOP — do NOT add more tool calls or check status
- Never poll agent status repeatedly — trust agents to return
- Review ALL results before proceeding

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

| Tier | Handler | Cost | Use Cases |
|------|---------|------|-----------|
| **1** | Edit tool directly | $0 | Single-line transforms — skip LLM |
| **2** | Haiku | $0.0002 | Simple tasks (<30% complexity) |
| **3** | Sonnet/Opus | $0.003–0.015 | Complex reasoning, architecture, security |

## Ruflo Memory & Shared Context

Keep shared context between Claude and Codex via Ruflo memory so Codex always has full task specs:

| Tool | Description |
|------|-------------|
| `memory_store` | Store design decisions and task specs |
| `memory_search` | Semantic search before starting work |
| `memory_search_unified` | Search across Claude + AgentDB + patterns |
| `memory_retrieve` | Retrieve a stored spec by key |

```bash
# Store a design decision before delegating
npx @claude-flow/cli@latest memory store --key "task-<name>" --value "<full spec>" --namespace tasks

# Search for prior patterns
npx @claude-flow/cli@latest memory search --query "<feature keyword>"
```

## Key MCP Tools (discover via ToolSearch)

| Category | Tools |
|----------|-------|
| Memory | `memory_store`, `memory_search`, `memory_search_unified` |
| Swarm | `swarm_init`, `swarm_status`, `swarm_health` |
| Agents | `agent_spawn`, `agent_list`, `agent_status` |
| Hive-Mind | `hive-mind_init`, `hive-mind_spawn`, `hive-mind_consensus` |
| Hooks | `hooks_route`, `hooks_session-start`, `hooks_post-task` |
| Security | `aidefence_scan`, `aidefence_is_safe` |

```
ToolSearch("memory search")  → memory_store, memory_search, memory_search_unified
ToolSearch("swarm")          → swarm_init, swarm_status, swarm_health
ToolSearch("+aidefence")     → aidefence_scan, aidefence_is_safe, aidefence_has_pii
```

## Support

- Documentation: https://github.com/ruvnet/ruflo
- Issues: https://github.com/ruvnet/ruflo/issues