FidgetFlo V3 - Agent Guide

For OpenAI Codex CLI - Agentic AI Foundation standard Skills: $skill-name | Config: .agents/config.toml

📢 TL;DR - READ THIS FIRST

╔═══════════════════════════════════════════════════════════════════════════╗
║  1. fidgetflo = LEDGER (tracks state, stores memory, coordinates)       ║
║  2. Codex = EXECUTOR (writes code, runs commands, creates files)          ║
║  3. NEVER stop after calling fidgetflo - IMMEDIATELY continue working   ║
║  4. If you need something BUILT/EXECUTED, YOU do it, not fidgetflo      ║
║  5. ALWAYS search memory BEFORE starting: memory search --query "task"    ║
║  6. ALWAYS store patterns AFTER success: memory store --namespace patterns║
╚═══════════════════════════════════════════════════════════════════════════╝

Workflow (Use MCP Tools):

1. memory_search(query="task keywords") → LEARN from past patterns (score > 0.7 = use it)
2. swarm_init(topology="hierarchical") → coordination record (instant)
3. YOU write the code / run the commands ← THIS IS WHERE WORK HAPPENS
4. memory_store(key="pattern-x", value="what worked", namespace="patterns") → REMEMBER for next time

🚨 CRITICAL: CODEX DOES THE WORK, FIDGETFLO ORCHESTRATES

┌─────────────────────────────────────────────────────────────┐
│  FIDGETFLO = ORCHESTRATOR (tracks state, coordinates)     │
│  CODEX = WORKER (writes code, runs commands, implements)    │
└─────────────────────────────────────────────────────────────┘

❌ WRONG: Expecting fidgetflo to execute tasks

npx fidgetflo swarm start --objective "Build API"
# WRONG: Waiting for fidgetflo to build the API
# Claude-flow does NOT execute code!

✅ CORRECT: Codex executes, fidgetflo tracks

# 1. Tell fidgetflo what you're doing (optional coordination)
npx fidgetflo swarm init --topology hierarchical --max-agents 1
npx fidgetflo agent spawn --type coder --name codex-worker

# 2. YOU (CODEX) DO THE ACTUAL WORK:
mkdir -p src
cat > src/api.ts << 'EOF'
export function hello() { return "Hello World"; }
EOF

# 3. Report to fidgetflo what you did (optional)
npx fidgetflo memory store --key "api-created" --value "src/api.ts" --namespace results

The Division of Labor

⛔ DON'T STOP AFTER CALLING FIDGETFLO

┌─────────────────────────────────────────────────────────────────────────┐
│  ❌ WRONG: Call fidgetflo → STOP → Wait for results                   │
│  ✅ RIGHT: Call fidgetflo → IMMEDIATELY continue → YOU do the work    │
└─────────────────────────────────────────────────────────────────────────┘

❌ WRONG Pattern (Stopping)

npx fidgetflo swarm init --topology hierarchical
npx fidgetflo agent spawn --type coder --name worker-1
npx fidgetflo swarm start --objective "Build hello world"
# WRONG: Codex stops here and waits for something to happen
# Nothing will happen! Claude-flow doesn't execute code!

✅ CORRECT Pattern (Continue Immediately)

# Step 1: Coordination (optional)
npx fidgetflo swarm init --topology hierarchical
npx fidgetflo agent spawn --type coder --name worker-1

# Step 2: IMMEDIATELY DO THE WORK YOURSELF - DON'T WAIT!
echo 'console.log("Hello World!");' > hello.js
node hello.js

# Step 3: Report what you did
npx fidgetflo memory store --key "result" --value "Hello World printed" --namespace results

The Rule

After ANY fidgetflo command, IMMEDIATELY continue with your own work.

Claude-flow commands return instantly. They create coordination RECORDS only. You must ALWAYS follow up with YOUR OWN execution.

When to Use FidgetFlo Commands

Hello World - Correct Pattern

# STEP 1: Optional - register with orchestrator
npx fidgetflo swarm init --topology mesh --max-agents 1

# STEP 2: CODEX DOES THE WORK
echo 'console.log("Hello World!");' > hello.js
node hello.js

# STEP 3: Optional - report completion
npx fidgetflo memory store --key "hello-result" --value "printed Hello World" --namespace results

REMEMBER: If you need something DONE, YOU do it. Claude-flow just tracks.

⚡ QUICK COMMANDS (NO DISCOVERY NEEDED)

Spawn N-Agent Swarm (Copy-Paste Ready)

# 5-AGENT SWARM - Run these commands in sequence:
npx fidgetflo swarm init --topology hierarchical --max-agents 8
npx fidgetflo agent spawn --type coordinator --name coord-1
npx fidgetflo agent spawn --type coder --name coder-1
npx fidgetflo agent spawn --type coder --name coder-2
npx fidgetflo agent spawn --type tester --name tester-1
npx fidgetflo agent spawn --type reviewer --name reviewer-1
npx fidgetflo swarm start --objective "Your task here" --strategy development

Common Swarm Patterns

Agent Types (Use with --type)

Task Commands

Memory Commands

🚀 SWARM RECIPES

Recipe 1: Hello World Test (COMPLETE EXAMPLE)

Step 1: Setup coordination (returns instantly - don't stop!)

npx fidgetflo swarm init --topology mesh --max-agents 5
npx fidgetflo agent spawn --type coder --name hello-main
# ⚠️ DON'T STOP HERE - CONTINUE IMMEDIATELY TO STEP 2

Step 2: YOU (Codex) execute the task (THIS IS THE REAL WORK)

# ✅ YOU create the file
echo 'console.log("Hello World from Swarm!");' > /tmp/hello-swarm.js

# ✅ YOU execute it
node /tmp/hello-swarm.js
# Output: Hello World from Swarm!

Step 3: Report completion (optional - store results)

npx fidgetflo memory store --key "hello-world-result" --value "Executed: Hello World from Swarm!" --namespace results

Recipe 1b: 5-Agent Concurrent Hello World (COMPLETE)

# COORDINATION (instant - creates records only)
npx fidgetflo swarm init --topology hierarchical --max-agents 5
for i in 1 2 3 4 5; do
  npx fidgetflo agent spawn --type coder --name "worker-$i"
done

# ⚠️ NOW YOU DO THE ACTUAL CONCURRENT WORK:
for i in 1 2 3 4 5; do
  (echo "Worker $i: Hello World!" && sleep 0.$i) &
done
wait
echo "All 5 workers completed!"

# REPORT (optional)
npx fidgetflo memory store --key "concurrent-result" --value "5 workers completed" --namespace results

Recipe 1b: Hello World (Single Command Block)

# All-in-one execution
npx fidgetflo swarm init --topology mesh --max-agents 5 && \
npx fidgetflo agent spawn --type coder --name hello-main && \
npx fidgetflo swarm start --objective "Print hello world" --strategy development && \
echo 'console.log("Hello World from Swarm!");' > /tmp/hello-swarm.js && \
node /tmp/hello-swarm.js && \
npx fidgetflo memory store --key "hello-world-result" --value "Success" --namespace results

Recipe 2: Feature Implementation (6 Agents)

npx fidgetflo swarm init --topology hierarchical --max-agents 8
npx fidgetflo agent spawn --type coordinator --name lead
npx fidgetflo agent spawn --type architect --name arch
npx fidgetflo agent spawn --type coder --name impl-1
npx fidgetflo agent spawn --type coder --name impl-2
npx fidgetflo agent spawn --type tester --name test
npx fidgetflo agent spawn --type reviewer --name review
npx fidgetflo swarm start --objective "Implement [feature]" --strategy development

Recipe 3: Bug Fix (4 Agents)

npx fidgetflo swarm init --topology hierarchical --max-agents 4
npx fidgetflo agent spawn --type coordinator --name lead
npx fidgetflo agent spawn --type researcher --name debug
npx fidgetflo agent spawn --type coder --name fix
npx fidgetflo agent spawn --type tester --name verify
npx fidgetflo swarm start --objective "Fix [bug]" --strategy development

Recipe 4: Security Audit (3 Agents)

npx fidgetflo swarm init --topology hierarchical --max-agents 4
npx fidgetflo agent spawn --type coordinator --name lead
npx fidgetflo agent spawn --type security-architect --name audit
npx fidgetflo agent spawn --type reviewer --name review
npx fidgetflo swarm start --objective "Security audit" --strategy development

Recipe 5: V3 Full Coordination (15 Agents)

npx fidgetflo swarm init --v3-mode
npx fidgetflo swarm coordinate --agents 15

📋 BEHAVIORAL RULES

• YOU (CODEX) execute tasks - fidgetflo only orchestrates
• 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 wait for fidgetflo to "do work" - it doesn't execute, YOU do
• Use fidgetflo commands to TRACK progress, not to EXECUTE tasks

📁 FILE ORGANIZATION

🎯 WHEN TO USE SWARMS

USE SWARM:

• Multiple files (3+)
• New feature implementation
• Cross-module refactoring
• API changes with tests
• Security-related changes
• Performance optimization

SKIP SWARM:

• Single file edits
• Simple bug fixes (1-2 lines)
• Documentation updates
• Configuration changes

🔧 CLI REFERENCE

Swarm Commands

npx fidgetflo swarm init [--topology TYPE] [--max-agents N] [--v3-mode]
npx fidgetflo swarm start --objective "task" --strategy [development|research]
npx fidgetflo swarm status [SWARM_ID]
npx fidgetflo swarm stop [SWARM_ID]
npx fidgetflo swarm scale --count N
npx fidgetflo swarm coordinate --agents N

Agent Commands

npx fidgetflo agent spawn --type TYPE --name NAME
npx fidgetflo agent list [--filter active|idle|busy]
npx fidgetflo agent status AGENT_ID
npx fidgetflo agent stop AGENT_ID
npx fidgetflo agent metrics [AGENT_ID]
npx fidgetflo agent health
npx fidgetflo agent logs AGENT_ID

Task Commands

npx fidgetflo task create --type TYPE --description "desc"
npx fidgetflo task list [--all]
npx fidgetflo task status TASK_ID
npx fidgetflo task assign TASK_ID --agent AGENT_NAME
npx fidgetflo task cancel TASK_ID
npx fidgetflo task retry TASK_ID

Memory Commands

npx fidgetflo memory store --key KEY --value VALUE [--namespace NS]
npx fidgetflo memory search --query "terms" [--namespace NS]
npx fidgetflo memory list [--namespace NS]
npx fidgetflo memory retrieve --key KEY [--namespace NS]
npx fidgetflo memory init [--force]

Hooks Commands

npx fidgetflo hooks pre-task --description "task"
npx fidgetflo hooks post-task --task-id ID --success true
npx fidgetflo hooks route --task "task"
npx fidgetflo hooks session-start --session-id ID
npx fidgetflo hooks session-end --export-metrics true
npx fidgetflo hooks worker list
npx fidgetflo hooks worker dispatch --trigger audit

System Commands

npx fidgetflo init [--wizard] [--codex] [--full]
npx fidgetflo daemon start
npx fidgetflo daemon stop
npx fidgetflo daemon status
npx fidgetflo doctor [--fix]
npx fidgetflo status
npx fidgetflo mcp start

🔌 TOPOLOGIES

🤖 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

FIDGETFLO_CONFIG=./fidgetflo.config.json
FIDGETFLO_LOG_LEVEL=info
FIDGETFLO_MEMORY_BACKEND=hybrid

🔗 SKILLS

Invoke with $skill-name:

🔌 MCP INTEGRATION (Learning & Coordination)

Codex doesn't have native hooks like Claude Code, but uses MCP (Model Context Protocol) for learning and coordination.

MCP Auto-Registration

When you run npx fidgetflo init --codex, the MCP server is automatically registered with Codex.

# Verify MCP is registered:
codex mcp list

# Expected output:
# Name         Command  Args                   Status
# fidgetflo  npx      fidgetflo mcp start  enabled

# If not present, add manually:
codex mcp add fidgetflo -- npx fidgetflo mcp start

Test MCP Connection

# Test MCP server starts correctly:
npx fidgetflo mcp start --test

MCP Tools Available

Once added, Codex can use these tools via MCP:

Coordination:

Learning & Memory (USE THESE!):

Hive Mind (Advanced):

Self-Learning via MCP Tools (PREFERRED)

Use MCP tools directly - faster than CLI commands:

BEFORE starting any task - SEARCH for patterns:

Use tool: memory_search
  query: "keywords related to your task"
  namespace: "patterns"

AFTER completing successfully - STORE the pattern:

Use tool: memory_store
  key: "pattern-[descriptive-name]"
  value: "What worked: approach, code patterns, gotchas"
  namespace: "patterns"

MCP Learning Workflow (Use This!)

1. LEARN: memory_search(query="task keywords", namespace="patterns")
   → If score > 0.7, USE that pattern

2. COORDINATE: swarm_init(topology="hierarchical")
   → agent_spawn(type="coder", name="worker-1")

3. EXECUTE: YOU write the code, run commands, create files

4. REMEMBER: memory_store(key="pattern-x", value="what worked", namespace="patterns")

MCP Tools for Learning

Example: Learning-Enabled Task

STEP 1 - LEARN:
Use tool: memory_search
  query: "validation utility function"
  namespace: "patterns"

→ Found: pattern-email-validator (score: 0.82)
→ Use this pattern as reference!

STEP 2 - COORDINATE:
Use tool: swarm_init with topology="hierarchical", maxAgents=3

STEP 3 - EXECUTE:
YOU create the files:
  echo 'export function validate(x) { ... }' > /tmp/validator.js
  node --test /tmp/validator.js

STEP 4 - REMEMBER:
Use tool: memory_store
  key: "pattern-phone-validator"
  value: "Phone validation: regex /^\+?[\d\s-]{10,}$/, normalize first, test edge cases"
  namespace: "patterns"

Vector Search Tips

• Searches are SEMANTIC (meaning-based, not just keywords)
• Score > 0.7 = strong match, use that pattern
• Score 0.5-0.7 = partial match, adapt as needed
• Store DETAILED values for better future retrieval

CLI Fallback (if MCP unavailable)

npx fidgetflo memory search --query "keywords" --namespace patterns
npx fidgetflo memory store --key "pattern-x" --value "what worked" --namespace patterns

Coordination via MCP

When fidgetflo is added as MCP server, Codex can call tools directly:

Use tool: swarm_init with topology="hierarchical"
Use tool: memory_store with key="result" value="success"

config.toml MCP Setup

# ~/.codex/config.toml
[mcp_servers.fidgetflo]
command = "npx"
args = ["fidgetflo", "mcp", "start"]
enabled = true

📚 SUPPORT

• Docs: https://github.com/ruvnet/claude-flow
• Issues: https://github.com/ruvnet/claude-flow/issues

Remember: Codex executes, fidgetflo orchestrates!