sysadmin-chronicles/CLAUDE.md

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:

/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

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

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

# 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