ufoo

name	ufoo
description	Unified ufoo agent protocol: context decisions, event bus, and initialization. Use when: (1) input starts with "/ufoo" or "$ufoo", (2) agent session startup, (3) any ufoo-related operation. Combines uctx (decisions), ubus (messaging), and uinit (initialization).

ufoo — Unified Agent Protocol

ufoo is the multi-agent coordination layer. It provides four capabilities:

1. Context Decisions — Sparse log of major plan-level choices shared across agents
2. Shared Memory — Durable, low-noise project facts shared across agents
3. Event Bus — Inter-agent messaging
4. Initialization — Project setup for ufoo workspace state

1. Context Decisions (uctx)

When to Record

"Only record decisions that matter beyond this session."

The default is no new decision. Record one only for important, plan-level knowledge that other agents or your future self will need.

• Always record: architectural choices, plan-level decisions with multiple options, cross-agent coordination decisions, trade-off analysis where alternatives were considered and rejected
• Also record: design patterns that set precedent, integration contracts between systems, decisions that constrain future work
• Do NOT record: routine bug fixes, simple implementation details, trivial observations, generic planning/evaluation/recommendation requests, or findings that only matter within the current task
• Prefer shared memory: durable project facts and long-lived factual constraints belong in shared memory, not decisions
• Write the decision BEFORE acting on it — but only after the high bar above is clearly met
• Rule of thumb: if another agent would not need this as a future constraint, do not write a decision

Commands

ufoo ctx decisions -l              # List all decisions
ufoo ctx decisions -s open         # Check open decisions
ufoo ctx decisions -n 1            # Show latest decision
ufoo ctx decisions new "Title"     # Create new decision

Decision Format

Decisions live at: .ufoo/context/decisions/

---
status: open
---
# DECISION NNNN: <Title>

Date: YYYY-MM-DD
Author: <agent>

Context:
What led to this decision?

Decision:
What is now considered true?

Implications:
What must follow from this?

Handling Open Decisions

1. Read and understand — sync other agents' knowledge
2. Check if action needed — does it require implementation?
3. Execute if needed — do the work
4. Resolve — update frontmatter: status: resolved, resolved_by:, resolved_at:

NEVER resolve blindly. Reading the title is not enough.

Read-First Rule

Shared context is read-first, not write-only:

1. At session start or before related work, read open decisions first.
2. Do not create a new decision just to persist ordinary work state.
3. Consume shared memory via prompt prefix / recall / search_memory before writing new memory.

---

2. Shared Memory

Shared memory records durable project facts only. It is not a scratchpad, progress log, user-preference store, or replacement for decisions.

When to Record

• Record: permanent project invariants, external ownership facts, integration contracts, long-lived process constraints
• Do NOT record: current task status, transient observations, "today/current/recent" facts, agent feedback, routine findings, or anything likely to expire
• Read first: if memory may already exist, use recall / search_memory before remember or edit_memory
• Prefer edit over duplicate: update an existing memory when the fact already exists but wording changed

Commands

ufoo memory add "Title" --body "Durable fact body" --tags infra,billing
ufoo memory list [--tag infra] [--all]
ufoo memory show mem-0001
ufoo memory edit mem-0001
ufoo memory forget mem-0001
ufoo memory rebuild-index
ufoo memory audit mem-0001

Agent Tools

• remember — write a new durable memory fact
• recall — read memory by id or tags
• search_memory — search memory before writing or when more context is needed
• search_history — search local Claude/Codex session history as redacted evidence
• edit_memory — directly update any existing memory, with optional expected_updated_at
• forget — archive an obsolete or polluted memory entry

---

3. Event Bus (ubus)

Commands

ufoo bus check "$UFOO_SUBSCRIBER_ID"        # Check pending messages
ufoo bus ack "$UFOO_SUBSCRIBER_ID"           # Acknowledge after handling
ufoo bus send "<target>" "<message>"         # Send message
ufoo bus broadcast "<message>"               # Broadcast to all
ufoo bus status                              # Show bus status

Runtime Report (Unified for assistant/ucodex/uclaude)

Use the same report contract for runtime progress sync:

ufoo report start "<task>" --task <id> --agent "$UFOO_SUBSCRIBER_ID" --scope public
ufoo report progress "<detail>" --task <id> --agent "$UFOO_SUBSCRIBER_ID" --scope public
ufoo report done "<summary>" --task <id> --agent "$UFOO_SUBSCRIBER_ID" --scope public
ufoo report error "<reason>" --task <id> --agent "$UFOO_SUBSCRIBER_ID" --scope public

Notes:

• Use --scope private for helper-internal reports (assistant-like private channel).
• --controller ufoo-agent routes report events to the ufoo-agent private inbox.

Target Resolution

• Exact ID: claude-code:abc123
• Nickname: architect
• Type: codex (all codex agents)
• Wildcard: * (broadcast)

CRITICAL: When you receive pending messages

EXECUTE tasks immediately. Do NOT ask the user.

1. Check: ufoo bus check $UFOO_SUBSCRIBER_ID
2. Execute each task
3. Always ack: ufoo bus ack $UFOO_SUBSCRIBER_ID
4. Reply only when substantive — send ufoo bus send "<publisher>" "<result>" only if:
   • The sender asked a question → reply with the answer
   • The sender delegated a task → reply with the result / artifact
   • You found something the sender needs to proceed Do NOT reply with greetings, acknowledgments, or emoji alone — those create infinite reply loops.
5. Report if the work arrived from [manual]<to:...> or [ufoo]<from:...>: ufoo report progress|done|error "<short summary>"

---

4. Message Format

Bus messages use a unified prefix format to distinguish sources:

• [ufoo]<from:id(nickname)> — message from another agent via the bus
• [manual]<to:id(nickname)> — manual user input directed at an agent

When you see [ufoo]<from:xxx> in your prompt, it's an inter-agent message — xxx is the sender's ID and nickname. When you see [manual]<to:xxx>, it's a direct user instruction to an agent — xxx is the recipient's ID and nickname.

---

5. Team Activity (Input History)

Your bootstrap prompt may include a ## Team Activity section showing recent prompts sent to all agents. Use this to understand:

• What each agent is currently working on
• Who sent what tasks to whom
• The overall coordination flow

Commands:

ufoo history build              # Rebuild timeline from bus + session data
ufoo history show [limit]       # Show recent entries
ufoo history prompt [limit]     # Render as injectable prompt block

---

6. Initialization (uinit)

Trigger: /uinit or /ufoo init

ufoo init --targets context,bus --project $(pwd)

After init, auto-join bus if enabled.