u-foo 1.0.0

package/modules/AGENTS.template.md

@@ -0,0 +1,87 @@
+<!-- ufoo -->
+## ufoo Protocol
+
+This project uses **ufoo** for agent coordination. Read the full documentation at `.ufoo/docs/` (symlinked from ufoo installation).
+
+### Core Principles
+
+1. **Agents are autonomous** - Execute tasks without asking for permission
+2. **Communication via bus** - Use `ufoo bus` for inter-agent messaging
+3. **Decisions are recorded** - Use `ufoo ctx` for decision tracking
+4. **Context is shared** - All agents read from `.ufoo/context/`
+
+### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `uinit` | Initialize/repair .ufoo directory |
+| `uctx` | Check context status and decisions |
+| `ustatus` | Unified status view (banner, unread bus, open decisions) |
+| `ubus` | Check bus messages and **auto-execute** them |
+
+### Quick Reference
+
+```bash
+# Context
+ufoo ctx decisions -l          # List all decisions
+ufoo ctx decisions -n 1        # Show latest decision
+
+# Bus
+ufoo bus join                  # Join bus (auto by uclaude/ucodex)
+ufoo bus check $SUBSCRIBER     # Check pending messages
+ufoo bus send "<id>" "<msg>"   # Send message
+ufoo bus status                # Show bus status
+```
+
+---
+
+## ufoo context Protocol
+
+On session start, check context status:
+```bash
+ufoo ctx decisions -l
+ufoo ctx decisions -n 1
+```
+
+Key files in `.ufoo/context/`:
+- `DECISIONS/` - Decision log (append-only)
+- `SYSTEM.md` - System overview
+- `CONSTRAINTS.md` - Non-negotiable rules
+
+**Decision recording policy:**
+- **Must record**: evaluations, architecture, naming, trade-offs
+- Write decision **before replying** when applicable
+
+---
+
+## ufoo bus Protocol
+
+### CRITICAL: `ubus` Command Behavior
+
+**When you receive `ubus`, you MUST:**
+1. Check pending messages: `ufoo bus check $SUBSCRIBER`
+2. **EXECUTE each task immediately** - Do NOT ask the user
+3. Reply to sender: `ufoo bus send "<publisher>" "<result>"`
+
+**Rules:**
+- Execute tasks immediately without asking
+- Always reply to the sender
+- Do NOT ask "Want me to...?" or "Should I...?"
+- Do NOT wait for user confirmation
+
+### Message Format
+
+```
+@you from claude-code:abc123
+Type: message/targeted
+Content: {"message":"Please analyze the project structure"}
+```
+
+Extract sender ID from "from" field, use it to reply.
+
+### Example
+
+1. Receive: `@you from claude-code:bd36dda0 Content: {"message":"Please analyze the project structure"}`
+2. Execute: Analyze the project structure
+3. Reply: `ufoo bus send "claude-code:bd36dda0" "Project contains src/, scripts/, modules/"`
+<!-- /ufoo -->

package/modules/bus/README.md

@@ -0,0 +1,132 @@
+# bus
+
+File-system based Agent event bus for async communication between multiple AI Coding Agents.
+
+## Overview
+
+bus solves communication problems in multi-agent collaboration:
+
+- Multiple Claude Code instances collaborating on the same project
+- Communication between different AI tools (Claude Code, Cursor, Copilot)
+- Task delegation and response
+- Broadcast messages
+
+## Installation
+
+Initialize via ufoo:
+
+```bash
+ufoo init --modules context,bus
+```
+
+## Directory Structure
+
+```
+.bus/
+├── bus.json      # Bus metadata + subscriber status
+├── events/       # Event stream (JSONL, sharded by date)
+├── offsets/      # Each Agent's consumption progress
+└── queues/       # Targeted event queues
+```
+
+## Usage
+
+### Join Bus
+
+```bash
+SUBSCRIBER=$(bash scripts/bus.sh join)
+# Output: claude-code:a1b2c3
+```
+
+### Check Pending Messages
+
+```bash
+bash scripts/bus.sh check $SUBSCRIBER
+```
+
+### Send Messages
+
+```bash
+# Send to specific instance
+bash scripts/bus.sh send "claude-code:abc123" "Please help me review"
+
+# Send to all instances of same type
+bash scripts/bus.sh send "claude-code" "Everyone please review"
+
+# Broadcast to all
+bash scripts/bus.sh broadcast "I completed feature-x"
+```
+
+### View Status
+
+```bash
+bash scripts/bus.sh status
+```
+
+## Notifications/Alerts (no key injection, recommended)
+
+If you want to receive "new message alerts" while running Codex/Claude in another terminal, use **agent-side alert/listen** (avoids IME/accessibility permission/window positioning fragmentation issues):
+
+```bash
+SUBSCRIBER=$(bash scripts/bus.sh join | tail -n 1)
+
+# Background alert: title badge + bell + optional macOS notification center
+bash scripts/bus-alert.sh "$SUBSCRIBER" 1 --notify --daemon
+
+# Or: foreground continuous print of new messages (suitable for a side terminal)
+bash scripts/bus-listen.sh "$SUBSCRIBER" --from-beginning
+```
+
+## Unattended Auto-Execute (recommended)
+
+If you need **Claude A to notify Claude B / Codex C and have the target auto-execute** (e.g., auto-trigger `/ubus`), use `autotrigger`:
+
+1) First `join` in each terminal session (records `tty`, also records `TMUX_PANE` if in tmux):
+
+```bash
+SUBSCRIBER=$(bash scripts/bus.sh join | tail -n 1)
+```
+
+2) Start autotrigger in the project (runs as background daemon):
+
+```bash
+# backend=auto prefers tmux (if available), otherwise tries Terminal.app do script (pure Automation), finally Accessibility
+bash scripts/bus-autotrigger.sh start --interval 1 --command "/ubus" --backend auto
+```
+
+3) After sending a message, autotrigger injects `/ubus` into the target session and presses Enter:
+- tmux: `send-keys`
+- Terminal.app (pure Automation): `do script` (no Accessibility needed, but requires Automation authorization; compatibility depends on whether target program accepts input)
+- Terminal.app (Accessibility): System Events (needs Accessibility), injection sequence is Escape + paste + Return (avoids IME issues)
+
+Tips:
+- Terminal.app backend depends on `tty` in `bus.json`. Execute `join` in the target terminal session (ensure `tty` is not `not a tty`).
+- Pure Automation backend needs one-time authorization: System Preferences → Privacy & Security → Automation (allow script to control Terminal).
+- Accessibility backend needs one-time authorization: System Preferences → Privacy & Security → Accessibility (for Terminal / script host).
+
+Stop/view status:
+
+```bash
+bash scripts/bus-autotrigger.sh status
+bash scripts/bus-autotrigger.sh stop
+```
+
+## Subscriber ID Format
+
+```
+{agent_type}:{instance_id}
+
+Examples:
+  claude-code:a1b2c3
+  cursor-ai:main
+  copilot:session1
+```
+
+## Relationship with context
+
+| Module | Problem Solved |
+|--------|----------------|
+| context | Shared context, decision recording, knowledge persistence |
+| bus | Real-time communication, task delegation, message passing |
+
+Both are independent peer modules that can be used separately or together.

package/modules/bus/SKILLS/ubus/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: ubus
+description: |
+  Poll event bus, check pending messages.
+  Use when: (1) check if other Agents sent messages, (2) view bus status, (3) periodic polling.
+  If not yet joined bus, will auto-join.
+---
+
+# /ubus - Event Bus Polling
+
+Check pending messages on the event bus.
+
+## Arguments
+
+- `/ubus` - Check messages and show status
+- `/ubus watch` - Start background auto-notification (title badge + bell + notification center)
+- `/ubus stop` - Stop background auto-notification
+- `/ubus listen` - Foreground continuous listener, print new messages (suitable for side terminal)
+- `/ubus auto` - Unattended auto-execute (auto-inject `/ubus` and press Enter)
+
+## Execution Flow
+
+### 1. Check if .ufoo/bus exists
+
+```bash
+if [[ ! -d ".ufoo/bus" ]]; then
+  echo "Event bus not initialized, please run /uinit and select bus module"
+  exit
+fi
+```
+
+### 2. Check if already joined bus
+
+Read `.ufoo/bus/bus.json`, check if current session is registered.
+
+If not, auto-join (will auto-generate a friendly nickname like "codex-1", "claude-1"):
+
+```bash
+SUBSCRIBER=$(ufoo bus join | tail -n 1)
+echo "Joined event bus: $SUBSCRIBER"
+# Example output: codex:0e293156 (nickname: codex-1)
+```
+
+To join with a custom nickname:
+
+```bash
+ufoo bus join [session-id] [agent-type] "your-nickname"
+# Example: ufoo bus join abc123 claude-code "architect"
+```
+
+### 3. Handle arguments
+
+If argument is `watch`, use **Bash tool's `run_in_background: true`** to start background notification:
+
+```bash
+# Title badge + bell + notification center (no accessibility permission needed)
+ufoo bus alert "$SUBSCRIBER" 2 --notify --daemon
+```
+
+If argument is `listen`, foreground blocking listener (no background task tool needed):
+
+```bash
+ufoo bus listen "$SUBSCRIBER" --from-beginning
+```
+
+If argument is `auto`, unattended auto-execute:
+
+```bash
+# Start daemon (background resident), auto-inject /ubus + Enter on new message
+ufoo bus daemon --daemon
+```
+
+Tips:
+- Need to use `uclaude`/`ucodex` wrapper to start Claude Code/Codex (auto-records tty)
+- Terminal.app needs Accessibility permission (for keyboard input injection)
+
+If argument is `stop`, stop background notification:
+
+```bash
+ufoo bus alert "$SUBSCRIBER" --stop
+```
+
+### 4. Check pending events
+
+```bash
+ufoo bus check "$SUBSCRIBER"
+```
+
+If pending events exist, show:
+
+```
+=== Pending Messages ===
+
+@you from claude-code:abc123
+  Type: task/delegate
+  Content: {"task":"review","file":"src/main.ts"}
+
+---
+Please handle the above messages, after completion you can reply:
+ufoo bus send "claude-code:abc123" "Review completed, found 2 issues..."
+```
+
+### 5. IMPORTANT: Acknowledge messages after handling
+
+After you have read and processed the messages, you MUST acknowledge them to prevent repeated notifications:
+
+```bash
+ufoo bus ack "$SUBSCRIBER"
+```
+
+**This is critical** - if you don't ack, the daemon will keep injecting `/ubus` commands.
+
+If there's nothing to do (no actionable task), just ack immediately without sending a reply.
+
+### 6. Routing Override
+
+If the message explicitly instructs you to report to a specific PM/DEV/TEST ID, **send the result to that ID instead of the publisher**.
+
+### 5. Show bus status
+
+```bash
+ufoo bus status
+```
+
+Output (now includes nicknames):
+
+```
+=== Event Bus Status ===
+My identity: claude-code:xyz789
+Online subscribers: 2
+  - claude-code:abc123 (architect)
+  - claude-code:xyz789 (dev-lead)
+Recent events: 5
+```
+
+## Managing Nicknames
+
+### View and Change Nicknames
+
+```bash
+# Change an agent's nickname
+ufoo bus rename <subscriber-id> "new-nickname"
+# Example: ufoo bus rename claude-code:47b1d525 "backend-dev"
+
+# Nickname alias command
+ufoo bus nick <subscriber-id> "new-nickname"
+```
+
+**Important Notes:**
+- Nicknames must be globally unique
+- Cannot change nickname during join (use `rename` command instead)
+- Re-joining with same subscriber ID will reuse existing nickname
+- Auto-generated nicknames: `codex-1`, `codex-2`, `claude-1`, `claude-2`, etc.
+
+## Handling Received Messages
+
+When receiving targeted messages:
+
+1. **Understand request** - Read message content
+2. **Execute task** - If task delegation, execute it
+3. **Reply to sender** - Send response after completion
+
+```bash
+ufoo bus send "<sender-id>" "<reply-content>"
+```
+
+## Sending Messages
+
+### Smart Routing (when you don't know the target ID)
+
+If the user says "notify codex to do X" without specifying an ID, use smart routing:
+
+```bash
+# Step 1: Find candidates
+ufoo bus resolve "$SUBSCRIBER" codex
+
+# Output shows:
+# - If only 1 codex: directly shows the ID
+# - If multiple: shows each with nickname and message history
+```
+
+Based on the output:
+- **Single match**: Use that ID directly
+- **Multiple matches**: Analyze the message history to find the right target
+  - Look for context clues in previous conversations
+  - If still unclear, ask the user which one, or send to all of that type
+
+### Direct Send
+
+```bash
+# Send to specific Agent by full ID
+ufoo bus send "claude-code:abc123" "message content"
+
+# Send to specific Agent by nickname (NEW!)
+ufoo bus send "architect" "message content"
+ufoo bus send "backend-dev" "message content"
+
+# Send to all Agents of same type
+ufoo bus send "codex" "message content"
+
+# Broadcast to everyone
+ufoo bus broadcast "message content"
+```
+
+**Target Resolution Priority:**
+1. Exact subscriber ID (e.g., `claude-code:abc123`)
+2. Nickname match (e.g., `architect` → resolves to subscriber ID)
+3. Agent type (e.g., `codex` → all codex agents)
+4. Wildcard (`*` → all agents)

package/modules/bus/scripts/bus-alert.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# bus-alert.sh
+# Background notification daemon for a single subscriber.
+#
+# Usage:
+#   bash bus-alert.sh <subscriber> [interval] [options]
+#
+# Options:
+#   --notify     Enable macOS Notification Center
+#   --daemon     Run in background
+#   --stop       Stop running alert for this subscriber
+#   --no-title   Disable terminal title badge
+#   --no-bell    Disable terminal bell
+
+BUS_DIR=".ufoo/bus"
+INTERVAL=2
+DAEMON_MODE=0
+USE_NOTIFY=0
+USE_TITLE=1
+USE_BELL=1
+STOP_MODE=0
+
+usage() {
+  cat <<'USAGE'
+bus-alert.sh - Background notification daemon for a single subscriber
+
+Usage:
+  bus-alert.sh <subscriber> [interval] [options]
+
+Options:
+  --notify     Enable macOS Notification Center
+  --daemon     Run in background
+  --stop       Stop running alert for this subscriber
+  --no-title   Disable terminal title badge
+  --no-bell    Disable terminal bell
+  -h, --help   Show this help
+USAGE
+}
+
+# Handle --help first
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  usage
+  exit 0
+fi
+
+SUBSCRIBER="${1:-}"
+shift || true
+
+if [[ -z "$SUBSCRIBER" ]]; then
+  usage >&2
+  exit 1
+fi
+
+# Parse interval if numeric
+if [[ "${1:-}" =~ ^[0-9]+$ ]]; then
+  INTERVAL="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --notify)
+      USE_NOTIFY=1
+      shift
+      ;;
+    --daemon)
+      DAEMON_MODE=1
+      shift
+      ;;
+    --stop)
+      STOP_MODE=1
+      shift
+      ;;
+    --no-title)
+      USE_TITLE=0
+      shift
+      ;;
+    --no-bell)
+      USE_BELL=0
+      shift
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+# Sanitize subscriber for filename: claude-code:abc123 -> claude-code_abc123
+SAFE_SUB="${SUBSCRIBER//:/_}"
+PID_FILE="$BUS_DIR/pids/alert-${SAFE_SUB}.pid"
+QUEUE_FILE="$BUS_DIR/queues/${SAFE_SUB}/pending.jsonl"
+
+mkdir -p "$BUS_DIR/pids"
+
+# Stop mode
+if [[ "$STOP_MODE" == "1" ]]; then
+  if [[ -f "$PID_FILE" ]]; then
+    pid="$(cat "$PID_FILE" 2>/dev/null || true)"
+    if [[ -n "$pid" ]]; then
+      kill "$pid" 2>/dev/null && echo "[alert] Stopped $SUBSCRIBER (pid=$pid)" || echo "[alert] Not running"
+    fi
+    rm -f "$PID_FILE"
+  else
+    echo "[alert] Not running for $SUBSCRIBER"
+  fi
+  exit 0
+fi
+
+# Daemon mode - fork to background
+if [[ "$DAEMON_MODE" == "1" ]]; then
+  # Check if already running
+  if [[ -f "$PID_FILE" ]]; then
+    existing="$(cat "$PID_FILE" 2>/dev/null || true)"
+    if [[ -n "$existing" ]] && kill -0 "$existing" 2>/dev/null; then
+      echo "[alert] Already running for $SUBSCRIBER (pid=$existing)"
+      exit 0
+    fi
+  fi
+
+  LOG_FILE="$BUS_DIR/logs/alert-${SAFE_SUB}.log"
+  mkdir -p "$BUS_DIR/logs"
+
+  args=("$SUBSCRIBER" "$INTERVAL")
+  [[ "$USE_NOTIFY" == "1" ]] && args+=("--notify")
+  [[ "$USE_TITLE" == "0" ]] && args+=("--no-title")
+  [[ "$USE_BELL" == "0" ]] && args+=("--no-bell")
+
+  nohup bash "$0" "${args[@]}" >> "$LOG_FILE" 2>&1 &
+  echo $! > "$PID_FILE"
+  echo "[alert] Started for $SUBSCRIBER (pid=$!, log=$LOG_FILE)"
+  exit 0
+fi
+
+# Record PID for foreground mode too
+echo $$ > "$PID_FILE"
+trap 'rm -f "$PID_FILE" 2>/dev/null || true' EXIT
+
+echo "[alert] Watching $SUBSCRIBER (interval=${INTERVAL}s)"
+
+LAST_COUNT=0
+
+# Get initial count
+if [[ -f "$QUEUE_FILE" ]] && [[ -s "$QUEUE_FILE" ]]; then
+  LAST_COUNT="$(wc -l < "$QUEUE_FILE" | tr -d ' ')"
+fi
+
+while true; do
+  # Get current count
+  if [[ -f "$QUEUE_FILE" ]] && [[ -s "$QUEUE_FILE" ]]; then
+    count="$(wc -l < "$QUEUE_FILE" | tr -d ' ')"
+  else
+    count=0
+  fi
+
+  # New messages arrived
+  if [[ "$count" -gt "$LAST_COUNT" ]]; then
+    new_count=$((count - LAST_COUNT))
+    echo "[alert] $(date '+%H:%M:%S') +${new_count} new message(s)"
+
+    # Terminal bell
+    if [[ "$USE_BELL" == "1" ]]; then
+      printf '\a'
+    fi
+
+    # Terminal title badge
+    if [[ "$USE_TITLE" == "1" ]]; then
+      printf '\033]0;[%d] %s\007' "$count" "$SUBSCRIBER"
+    fi
+
+    # macOS notification
+    if [[ "$USE_NOTIFY" == "1" ]]; then
+      osascript -e "display notification \"${new_count} new message(s)\" with title \"ufoo bus\" subtitle \"$SUBSCRIBER\"" 2>/dev/null || true
+    fi
+  fi
+
+  # Update title even if no new messages (show current count)
+  if [[ "$USE_TITLE" == "1" ]] && [[ "$count" -gt 0 ]]; then
+    printf '\033]0;[%d] %s\007' "$count" "$SUBSCRIBER"
+  fi
+
+  LAST_COUNT="$count"
+  sleep "$INTERVAL"
+done