u-foo 1.0.0

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

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# bus-listen.sh
+# Foreground listener that prints incoming messages.
+#
+# Usage:
+#   bash bus-listen.sh <subscriber> [options]
+#
+# Options:
+#   --from-beginning  Print existing queued messages first
+#   --reset           Truncate pending queue before listening
+#   --auto-join       Auto-join bus to get subscriber ID
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+BUS_DIR=".ufoo/bus"
+FROM_BEGINNING=0
+RESET=0
+AUTO_JOIN=0
+
+SUBSCRIBER="${1:-}"
+shift || true
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --from-beginning)
+      FROM_BEGINNING=1
+      shift
+      ;;
+    --reset)
+      RESET=1
+      shift
+      ;;
+    --auto-join)
+      AUTO_JOIN=1
+      shift
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+# Auto-join if requested
+if [[ "$AUTO_JOIN" == "1" ]] && [[ -z "$SUBSCRIBER" ]]; then
+  SUBSCRIBER="$(ufoo bus join 2>/dev/null | tail -1)"
+  echo "[listen] Auto-joined as: $SUBSCRIBER"
+fi
+
+if [[ -z "$SUBSCRIBER" ]]; then
+  echo "Usage: bus-listen.sh <subscriber> [options]" >&2
+  echo "  or:  bus-listen.sh --auto-join" >&2
+  exit 1
+fi
+
+# Sanitize subscriber for filename
+SAFE_SUB="${SUBSCRIBER//:/_}"
+QUEUE_FILE="$BUS_DIR/queues/${SAFE_SUB}/pending.jsonl"
+QUEUE_DIR="$BUS_DIR/queues/${SAFE_SUB}"
+
+mkdir -p "$QUEUE_DIR"
+touch "$QUEUE_FILE"
+
+# Reset queue if requested
+if [[ "$RESET" == "1" ]]; then
+  echo "[listen] Resetting queue..."
+  : > "$QUEUE_FILE"
+fi
+
+# Print existing messages if requested
+if [[ "$FROM_BEGINNING" == "1" ]] && [[ -s "$QUEUE_FILE" ]]; then
+  echo "[listen] Existing messages:"
+  echo "---"
+  while IFS= read -r line; do
+    # Parse JSON and extract message
+    msg="$(echo "$line" | jq -r '.data.message // .data // .' 2>/dev/null || echo "$line")"
+    from="$(echo "$line" | jq -r '.publisher // "unknown"' 2>/dev/null || echo "unknown")"
+    ts="$(echo "$line" | jq -r '.ts // ""' 2>/dev/null || echo "")"
+    short_ts="${ts:11:8}"  # Extract HH:MM:SS
+    echo "[$short_ts] <$from> $msg"
+  done < "$QUEUE_FILE"
+  echo "---"
+fi
+
+echo "[listen] Listening for new messages... (Ctrl+C to stop)"
+
+# Track last line count
+LAST_LINES=0
+if [[ -s "$QUEUE_FILE" ]]; then
+  LAST_LINES="$(wc -l < "$QUEUE_FILE" | tr -d ' ')"
+fi
+
+while true; do
+  if [[ -f "$QUEUE_FILE" ]]; then
+    CURRENT_LINES="$(wc -l < "$QUEUE_FILE" | tr -d ' ')"
+
+    if [[ "$CURRENT_LINES" -gt "$LAST_LINES" ]]; then
+      # Read new lines
+      tail -n "+$((LAST_LINES + 1))" "$QUEUE_FILE" | while IFS= read -r line; do
+        msg="$(echo "$line" | jq -r '.data.message // .data // .' 2>/dev/null || echo "$line")"
+        from="$(echo "$line" | jq -r '.publisher // "unknown"' 2>/dev/null || echo "unknown")"
+        ts="$(echo "$line" | jq -r '.ts // ""' 2>/dev/null || echo "")"
+        short_ts="${ts:11:8}"
+
+        # Bell notification
+        printf '\a'
+
+        echo "[$short_ts] <$from> $msg"
+      done
+
+      LAST_LINES="$CURRENT_LINES"
+    fi
+  fi
+
+  sleep 1
+done

package/modules/context/ASSUMPTIONS.md

@@ -0,0 +1,7 @@
+# Assumptions
+
+- Users work with multiple AI tools
+- AI agents can read markdown files
+- AI agents respect explicit file instructions
+- Written context survives session boundaries
+- Less structure is better than over-engineering

package/modules/context/CONSTRAINTS.md

@@ -0,0 +1,7 @@
+# Constraints
+
+- Model-agnostic (no Claude/GPT-specific instructions)
+- Project-agnostic (no specific tech stack assumptions)
+- Files are authoritative, not conversations
+- Decisions are append-only
+- All rules must be enforceable by file inspection

package/modules/context/CONTEXT-STRUCTURE.md

@@ -0,0 +1,49 @@
+# Context Structure
+
+## Global (read-only)
+
+```
+~/.ufoo/
+└── modules/
+    └── context/     # installed context module
+```
+
+- **Read-only**
+- Template source for init
+- No decisions, no assumptions
+- Law, not truth
+
+## Project-local (writable)
+
+```
+<project>/
+└── .context/
+    ├── README.md
+    ├── SYSTEM.md
+    ├── CONSTRAINTS.md
+    ├── ASSUMPTIONS.md
+    ├── TERMINOLOGY.md
+    └── DECISIONS/
+```
+
+- **In the repo** — can diff, can review
+- This is where truth lives
+- Must be versionable
+
+## Required files (project)
+
+| File | Purpose |
+|------|---------|
+| README.md | Entry point; how to use this context |
+| SYSTEM.md | Project architecture and purpose |
+| CONSTRAINTS.md | Non-negotiable rules |
+| ASSUMPTIONS.md | Current assumptions (update when changed) |
+| TERMINOLOGY.md | Shared vocabulary |
+| DECISIONS/ | Append-only decision log |
+
+## Red line
+
+**Never write decisions or assumptions to global.**
+
+Global = law.
+Project = truth.

package/modules/context/DECISION-PROTOCOL.md

@@ -0,0 +1,62 @@
+# Decision Protocol
+
+## What is a Decision?
+
+A decision is any new or changed “shared truth” that affects future work, including:
+- Architecture
+- Semantics
+- Roles or responsibilities
+- UI meaning or behavior
+- Naming or structure
+- Installation / distribution / tooling workflows
+- Trade-offs and “we chose X over Y”
+
+## Triage (Must / Ask / Skip)
+
+### Must record (no confirmation needed)
+
+Write a decision **before replying** when you do any of the following:
+
+- Provide an evaluation / analysis / recommendation that could steer future work
+- Propose an improvement plan or a set of next steps
+- Introduce or change any rule/constraint/process
+- Choose a default (e.g. install method, folder structure, version pinning policy)
+- Decide between alternatives (trade-off)
+
+### Ask first (medium importance)
+
+If you’re unsure whether the recommendation should become shared truth, ask:
+
+> “Should I record a decision for X?”
+
+Examples:
+- Optional refactors or style preferences
+- Suggestions that depend on missing info (URL, constraints, team preference)
+- Reversible tweaks that may not be adopted
+
+### Skip (not worth a decision)
+
+Do **not** write a decision for:
+
+- One-off clarifications or Q&A that doesn’t change future behavior
+- Trivial edits (formatting, typos) with no semantic impact
+- Ephemeral runtime details (logs, transient errors) unless they affect policy
+
+## Where Decisions Live
+
+- **Never** write decisions to global `~/.context/` (global = law).
+- Always write decisions to the project-local log:
+  - `<project>/.context/DECISIONS/`
+  - For this repo, that is: `.context/DECISIONS/`
+
+## Rules
+
+- Decisions are append-only.
+- Do not rewrite history.
+- AI agents are allowed to write decisions.
+
+## Minimum Content
+
+- Context: why this matters now
+- Decision: what is now considered true
+- Implications: what must follow from this

package/modules/context/HANDOFF.md

@@ -0,0 +1,33 @@
+# AI Handoff Protocol
+
+## When taking over work
+
+1. Read this repository (global protocol).
+2. Read the project-local `.context/`.
+3. Check for open decisions: `bash scripts/context-decisions.sh -l`
+
+## Processing open decisions
+
+Open decisions are messages from other agents. You MUST:
+
+1. **Read** — Read the full content, not just the title.
+2. **Understand** — Sync their decisions to your understanding.
+3. **Execute** — If action is required, do it first.
+4. **Verify** — Confirm the action succeeded.
+5. **Resolve** — Only then mark as resolved.
+
+```yaml
+---
+status: resolved
+resolved_by: <your-agent-name>
+resolved_at: <date>
+---
+```
+
+**NEVER resolve blindly.** This defeats the purpose of multi-agent collaboration.
+
+## Before finishing work
+
+- Declare whether any new decisions were introduced.
+- Ensure all decisions are written down.
+- Leave the project ready for the next agent.

package/modules/context/README.md

@@ -0,0 +1,82 @@
+# context
+
+A collaboration protocol that constrains AI behavior through explicit, versioned files.
+
+## Why
+
+AI coding agents (Claude Code, Codex, Cursor, etc.) have two fundamental problems:
+
+1. **No shared memory** — Decisions made in one session are invisible to other agents or future sessions. Each agent starts fresh, repeating mistakes or contradicting prior work.
+
+This protocol solves it by treating decisions and context as files:
+- **Decisions as files** — Persistent, versioned, reviewable. All agents read the same truth.
+
+## Core Principle
+
+```
+Global context defines the law.
+Project context defines the truth.
+```
+
+**Files are truth, not memory.**
+
+## Quick Start
+
+```bash
+# Install `ufoo` globally (once), then use it to install modules and init projects.
+```
+
+This repository is the `context` module. The recommended entrypoint is `ufoo`.
+
+## Architecture
+
+### Global: `~/.ufoo/` (read-only for agents, managed by humans)
+
+Global modules live under `~/.ufoo/modules/`.
+
+### Project: `<project>/.context/` (writable)
+
+```
+.context/
+├── README.md        # Entry point / how to use this context
+├── SYSTEM.md        # Project architecture
+├── CONSTRAINTS.md   # Non-negotiable rules
+├── ASSUMPTIONS.md   # Current assumptions
+├── TERMINOLOGY.md   # Shared vocabulary
+└── DECISIONS/       # Append-only log
+```
+
+Must be in Git. Must be reviewable. Truth.
+
+## Protocol Structure
+
+```
+context/                 # This repo
+├── SYSTEM.md               # Protocol definition
+├── RULES.md                # Collaboration rules
+├── CONSTRAINTS.md          # Protocol constraints
+├── DECISION-PROTOCOL.md    # How to write decisions
+├── HANDOFF.md              # Session handoff rules
+├── CONTEXT-STRUCTURE.md    # Project structure spec
+├── TEMPLATES/              # AI behavior constraint
+├── SKILLS/                 # tool skill docs (module-local)
+└── .context/            # Local project context for this repo (ignored; not part of protocol distribution)
+```
+
+## For AI Agents
+
+1. Read installed module from `~/.ufoo/modules/context/`
+2. Read/write context from `<project>/.context/`
+3. **Never write to global** — only to project
+4. When unsure, write a decision
+5. Do not modify TEMPLATES/ without a decision
+
+## Validate
+
+```bash
+# protocol repo
+ufoo ctx lint
+
+# project-local context (in a real project repo)
+ufoo ctx lint --project <path-to-project-context>
+```

package/modules/context/RULES.md

@@ -0,0 +1,15 @@
+# Collaboration Rules
+
+## Core rules
+
+- Always read this repository before coding.
+- Do not rely on model-internal memory.
+- All shared understanding must exist as files.
+- Decisions override comments and discussions.
+- When unsure, write a decision.
+
+## Decision handling
+
+- Open decisions are unprocessed messages from other agents.
+- You must read, understand, and act before resolving.
+- Never resolve without reading the full content.

package/modules/context/SKILLS/README.md

@@ -0,0 +1,14 @@
+# Skills
+
+Protocol-level skills that enforce context rules.
+
+- NOT memory systems
+- Do NOT store project knowledge
+- Only bootstrap and validate protocol compliance
+
+Available:
+- `uctx` — quick context check (list decisions, show latest, report status)
+
+Helpers:
+- `bash scripts/skills.sh list`
+- `bash scripts/skills.sh install <name|all> --codex|--agents|--target <dir>`

package/modules/context/SKILLS/uctx/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: uctx
+description: |
+  Quick ufoo context status check. Shows decisions and context health.
+  Use when: (1) Starting a session, (2) User says "uctx", (3) Need quick context refresh.
+  For full initialization, use uinit (ufoo init CLI).
+---
+
+# /uctx - AI Context Quick Check
+
+## What this does
+
+Fast context check for daily use. Run at session start or anytime.
+
+Pre-flight reminder:
+- If the user is asking for evaluation/recommendation/plan, write a decision before replying.
+
+## Workflow
+
+### 1. Verify structure exists
+
+Check `.ufoo/context/` exists. If missing, tell user to run `uinit` (ufoo init CLI).
+
+### 2. List all decisions
+
+```bash
+ufoo ctx decisions -l
+```
+
+### 3. Show latest decision
+
+```bash
+ufoo ctx decisions -n 1
+```
+
+### 4. Report status
+
+Brief summary:
+- Open decisions count (need attention)
+- Total decisions count
+- Any issues found
+- Ready to work
+
+## Output format
+
+```
+=== ufoo context status ===
+Project: <cwd>
+Decisions: N open, M total
+Latest open: DECISION XXXX: <title>
+
+[Latest decision content]
+
+Status: Ready ✓
+```
+
+## Handling Open Decisions
+
+When there are open decisions, you MUST:
+
+### 1. Read and understand
+- Read the full content of each open decision
+- Understand what other agents decided
+- This is "syncing their memory to yours"
+
+### 2. Check if action needed
+- Does the decision require implementation?
+- Is something already done that needs verification?
+- Are there implications you need to follow?
+
+### 3. Execute if needed
+- If the decision requires action, do it first
+- Verify the action was successful
+
+### 4. Then resolve
+Only after understanding and completing any required actions:
+```yaml
+---
+status: resolved
+resolved_by: <your-agent-name>
+resolved_at: <date>
+---
+```
+
+**NEVER resolve blindly.** Reading the title is not enough.
+
+## Notes
+
+- Script defaults to showing only `open` decisions
+- Resolved decisions are skipped (already processed)
+- Use `-s all` to see all decisions regardless of status

package/modules/context/SYSTEM.md

@@ -0,0 +1,18 @@
+# AI System Contract
+
+This repository defines the canonical collaboration context
+for all AI agents working on a codebase.
+
+## Purpose
+
+Solve one core problem with AI coding agents:
+
+1. **Memory sync across agents** — Multiple AI tools (Claude Code, Codex, Cursor, etc.) have no shared memory. Decisions made in one session are lost to others. This protocol makes decisions persist as files, enabling true multi-agent collaboration.
+
+## Rules
+
+- Files in this repository are authoritative.
+- Constraints are hard requirements, not suggestions.
+- Silent architectural or semantic decisions are forbidden.
+- If conflict or ambiguity exists, stop and ask.
+- Shared truth must be written, not remembered.

package/modules/context/TEMPLATES/assumptions.md

@@ -0,0 +1,4 @@
+# Assumptions
+
+- List assumptions currently considered true.
+- Update when assumptions change.

package/modules/context/TEMPLATES/constraints.md

@@ -0,0 +1,4 @@
+# Constraints
+
+- Non-negotiable rules.
+- Must always be followed.

package/modules/context/TEMPLATES/decision.md

@@ -0,0 +1,16 @@
+---
+status: open
+---
+# DECISION XXXX: <Title>
+
+Date:
+Author:
+
+Context:
+What led to this decision?
+
+Decision:
+What is now considered true?
+
+Implications:
+What must follow from this?

package/modules/context/TEMPLATES/project-context-readme.md

@@ -0,0 +1,6 @@
+# Project AI Context
+
+This directory contains the canonical AI context
+for this project.
+
+All AI agents must read this directory before working.

package/modules/context/TEMPLATES/system.md

@@ -0,0 +1,3 @@
+# System Overview
+
+[Describe the system architecture and purpose]

package/modules/context/TEMPLATES/terminology.md

@@ -0,0 +1,4 @@
+# Terminology
+
+| Term | Definition |
+|------|------------|

package/modules/context/TERMINOLOGY.md

@@ -0,0 +1,10 @@
+# Terminology
+
+| Term | Definition |
+|------|------------|
+| Protocol | The rules defined in this repository |
+| Decision | A recorded change affecting architecture/semantics/behavior |
+| Context | Project-specific knowledge stored in context/ |
+| Handoff | One AI session ending, another beginning |
+| Constraint | Non-negotiable rule |
+| Assumption | Belief currently considered true, subject to change |

package/modules/resources/ICONS/README.md

@@ -0,0 +1,12 @@
+# Icon Context
+
+Icons here define visual grammar, not shippable assets.
+
+They are used as:
+- Reference bases
+- Modification sources
+- Style constraints
+
+Do not copy blindly into projects.
+
+`libraries/` contains minimal subsets of third-party icon libraries (with licenses) as reference material.

package/modules/resources/ICONS/libraries/README.md

@@ -0,0 +1,17 @@
+# Icon Libraries (Minimal Subsets)
+
+This directory vendors **small, representative subsets** of third-party icon libraries.
+
+Purpose:
+- Provide strong, unambiguous signal that icons are **canonical protocol context**
+- Serve as reference bases and modification sources
+
+Non-goals:
+- Shipping assets for products
+- Full icon sets
+
+Each library subfolder contains:
+- A minimal set of SVGs
+- The upstream license text
+- A short README with source info
+

package/modules/resources/ICONS/libraries/heroicons/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) Tailwind Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/modules/resources/ICONS/libraries/heroicons/README.md

@@ -0,0 +1,15 @@
+# Heroicons (Minimal Subset)
+
+Source:
+- Repository: https://github.com/tailwindlabs/heroicons
+- Path: `optimized/24/outline/`
+- License: MIT (see `LICENSE`)
+- Fetched: 2026-01-27
+
+Included icons:
+- `arrow-right.svg`
+- `chevron-down.svg`
+- `magnifying-glass.svg`
+- `cog-6-tooth.svg`
+- `check.svg`
+- `x-mark.svg`

package/modules/resources/ICONS/libraries/heroicons/arrow-right.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="M13.5 4.5 21 12m0 0-7.5 7.5M21 12H3"/>
+</svg>
+

package/modules/resources/ICONS/libraries/heroicons/check.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="m4.5 12.75 6 6 9-13.5"/>
+</svg>
+

package/modules/resources/ICONS/libraries/heroicons/chevron-down.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5"/>
+</svg>
+

package/modules/resources/ICONS/libraries/heroicons/cog-6-tooth.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="M9.594 3.94c.09-.542.56-.94 1.11-.94h2.593c.55 0 1.02.398 1.11.94l.213 1.281c.063.374.313.686.645.87.074.04.147.083.22.127.325.196.72.257 1.075.124l1.217-.456a1.125 1.125 0 0 1 1.37.49l1.296 2.247a1.125 1.125 0 0 1-.26 1.431l-1.003.827c-.293.241-.438.613-.43.992a7.723 7.723 0 0 1 0 .255c-.008.378.137.75.43.991l1.004.827c.424.35.534.955.26 1.43l-1.298 2.247a1.125 1.125 0 0 1-1.369.491l-1.217-.456c-.355-.133-.75-.072-1.076.124a6.47 6.47 0 0 1-.22.128c-.331.183-.581.495-.644.869l-.213 1.281c-.09.543-.56.94-1.11.94h-2.594c-.55 0-1.019-.398-1.11-.94l-.213-1.281c-.062-.374-.312-.686-.644-.87a6.52 6.52 0 0 1-.22-.127c-.325-.196-.72-.257-1.076-.124l-1.217.456a1.125 1.125 0 0 1-1.369-.49l-1.297-2.247a1.125 1.125 0 0 1 .26-1.431l1.004-.827c.292-.24.437-.613.43-.991a6.932 6.932 0 0 1 0-.255c.007-.38-.138-.751-.43-.992l-1.004-.827a1.125 1.125 0 0 1-.26-1.43l1.297-2.247a1.125 1.125 0 0 1 1.37-.491l1.216.456c.356.133.751.072 1.076-.124.072-.044.146-.086.22-.128.332-.183.582-.495.644-.869l.214-1.28Z"/>
+  <path stroke-linecap="round" stroke-linejoin="round" d="M15 12a3 3 0 1 1-6 0 3 3 0 0 1 6 0Z"/>
+</svg>
+

package/modules/resources/ICONS/libraries/heroicons/magnifying-glass.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607Z"/>
+</svg>
+

package/modules/resources/ICONS/libraries/heroicons/x-mark.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12"/>
+</svg>
+