Ruflo for IEXDG
and for Her Mac

Why Ruflo

Ruflo is not the executor. Ruflo coordinates topology and state. Execution still runs on the Claude Code Agent runtime as subagents. What Ruflo enforces is the contract that makes a fleet of agents legible to each other and to us. The standing directive on every IEXDG task is the same: create, assign, coordinate. Every agent returns the same JSON shape. Every blindspot becomes someone else's findings array.

ruflo task create  "research the inbox"
ruflo task assign  --task <id> --agent <agent>
ruflo swarm coordinate   # or hive-mind broadcast

🔃 Create, Assign, Coordinate

Three commands, in this order, every time. The order is not aesthetic, it is structural. create writes the task to disk so it can be referenced. assign binds the agent identity to the task so the result is attributable. coordinate (or broadcast in hive-mind) merges the results into a fleet view that the next layer can synthesize.

📄 The Composability JSON Contract

Every agent, on every task, returns the same JSON shape. This is the lingua franca of the fleet. A synthesizer agent does not need to know which executor wrote the findings, what model produced them, or which tools were called. It only needs the contract. The contract is the API.

{
  "agent":        "iexdg-inbox-auditor",
  "task_id":      "task-1779836550401-7q1cw9",
  "findings": [
    {
      "id":       "F1",
      "severity": "info",
      "claim":    "Dr. DNicole replied yes on copy thread",
      "evidence": "gmail:msg_19e5f103d05e2cf6"
    }
  ],
  "next_agents": [
    {
      "agent":  "iexdg-catchup-reply-sender",
      "reason": "send catchup with 7 open asks"
    }
  ],
  "token_cost":   null
}

🦄 Hive-Mind Topology: Queen plus 6 Workers

This session spawned one queen and six workers from a single command pair. The queen broadcasts the parent task. Each worker pulls a slice, executes on its own context, and returns the contract. The queen reduces the six results into a synthesizer briefing. The whole topology is one shell pipeline.

ruflo hive-mind init  -t hierarchical-mesh
ruflo hive-mind spawn -n 6 -r worker

📎 Real Session Evidence, Sprint 35

Numbers from the IEXDG_Complete_Action_Ledger.html Sprint 35 block, dated 2026-05-25. Every number here has a source pointer. No vibes. No marketing math.

🔥 The 11-Day Frustration Loop

On 2026-05-15 Dr. DNicole escalated 11 days of visual-direction frustration. The escalation was a stream of feedback that did not ship cleanly because her CC did not have a way to structure WHY she was frustrated into action items. The fix is not a better prompt. The fix is a structured thinking tool that converts a stream into the same composability contract our side already speaks.

Her three use-cases

💾 Install Plan for Her Mac CC

Same filename-as-version-lock pattern that worked for the IEXDG MCP install (v3, v3.2, v3_apr21, v3_2_apr22 each on its own filename). Her Mac home folder is /Users/drdnicolefields/. The install is a four-step runbook she can paste-run, with the diagnostic guardrail wired into step one.

which ruflo  || echo "NOT INSTALLED"
ruflo --version 2>&1 | tee ~/ruflo_preflight.log

npm install -g ruflo@3.7.0-alpha
node ~/node_modules/ruflo/bin/ruflo.js --version
# Windows-style invocation as documented in ruflo_runtime_reality memory

ruflo task create  "hello from her CC"
ruflo task assign  --task <id> --agent her-test-agent
ruflo swarm coordinate
# Expect: 1 task record, 1 valid JSON return, 0 raises

✉️ Cross-CC Bus: Her Mac ↔ Ruflo ↔ Our CC

The composability JSON IS the lingua franca. Her CC writes the same shape ours reads. The task layer between them is an opaque queue that does not care which CC produced the payload, only that the payload is valid. This is how a one-person decision on her side becomes a fleet execution on ours, without anyone retyping the brief.

   [her Mac CC]
        |  ruflo task create  + findings + next_agents
        v
   [task record]  task-XXXX-her-frustration-images
        |
        |  ==> bus carries the JSON, no re-typing
        v
   [our hive queen]
        |  reads as remote-worker finding
        |  fans next_agents to fleet
        v
   [execution fleet]  (deploy, copy, brand, content)
        |
        |  result returns with same task_id ancestry
        v
   [her Mac CC]  structured ack + delta
  

🧬 The Ruflo Disease & the 5 Shields That Make Her CC Immune

A bus is only as healthy as the loops that close on it. The previous section shows what the contract carries; this section names the chronic failure mode that quietly hollows it out, and the five antibodies that prevent it on her Mac CC. The disease has been formally named so we can hunt it on sight: RUFLO-ORCHESTRATION-LOOP-NOT-CLOSED.

📋 Open Questions + Next Install Steps

Honest status. What is shipped, what is staged, what is gated. Same discipline we apply to the Sprint blocks in the action ledger.