u-foo 3.0.14 → 3.0.16

package/OPTIONAL_SKILLS/ufoo-bus-poll/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: ufoo-bus-poll
+description: >-
+  Stream pending ufoo bus messages through a resident background task for an
+  MCP-registered or externally provisioned agent whose host cannot receive
+  automatic ufoo prompt injection. Use only with a host that forwards streaming
+  background-task output into the agent session; do not use for Codex CLI,
+  Claude Code CLI, Agy, Kimi, or native ucode.
+---
+
+# ufoo bus poll
+
+Attach one provisioned external subscriber to a host-managed background stream.
+Keep the stream queue-read-only so the agent controls acknowledgement.
+
+## Attach the registered subscriber
+
+1. Reuse the exact subscriber returned by MCP `register_agent` or supplied by
+   the host. Never create a second identity for the stream, call bare
+   `ufoo bus join`, guess an agent type, or borrow another workspace subscriber.
+2. Start exactly one streaming background task for that subscriber:
+
+   ```bash
+   ufoo bus poll "<subscriber-id>" --follow --interval 2
+   ```
+
+3. Keep the command owned by the host's streaming background-task facility.
+   Do not use `nohup`, shell `&`, or an OS-detached daemon; those routes can
+   write output somewhere the agent never receives.
+
+The command rejects a second resident poll for the same subscriber. It emits
+the current pending batch, waits for that batch to be acknowledged, then emits
+the next batch. It never acknowledges, claims, injects, or clears messages.
+
+## Handle stream batches
+
+For every `[ufoo]<from:...>` event:
+
+1. Read `Content.message` and execute actionable work.
+2. After handling the emitted batch, run the exact acknowledgement command
+   printed by the stream:
+
+   ```bash
+   ufoo bus ack "<subscriber-id>" --through <seq>
+   ```
+
+   Preserve `--through`; it keeps later messages pending.
+3. Reply only with a requested result, answer, blocker, or fact the sender
+   needs:
+
+   ```bash
+   ufoo bus send "<sender-id>" "<substantive result>"
+   ```
+
+Do not reply to greetings, thanks, or acknowledgement-only messages. After
+sending, continue the current task; do not start another poll, sleep, or wait.
+The resident stream delivers follow-up output.
+
+If the host cannot forward incremental output from a still-running task, stop
+this workflow and use an explicitly invoked `$ufoo-bus` inbox check instead.

package/OPTIONAL_SKILLS/ufoo-bus-poll/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ufoo bus poll"
+  short_description: "Stream ufoo bus messages for non-injectable agents"
+  default_prompt: "Use $ufoo-bus-poll to attach this MCP-registered agent to its resident ufoo bus stream."

package/README.md

@@ -185,6 +185,11 @@ symlink; edit project instructions in `AGENTS.md`.
 Before a project has been initialized, the equivalent CLI form is also useful:
 `ufoo init --targets context,bus`.
 
+The default agent skill set is intentionally limited to `ufoo`, `ufoo-bus`,
+`ufoo-context`, and `ufoo-online`. They are installed only as skills, not as a
+second command catalog. Initialization and unified status are handled by
+`ufoo`.
+
 ### Event Bus
 
 ```text
@@ -204,11 +209,12 @@ queue-read-only bus stream:
 
 ```bash
 ufoo skills list --optional
-ufoo skills install ubus-poll --target /path/to/that/agent/skills
-ufoo bus poll "$UFOO_SUBSCRIBER_ID" --follow --interval 2
+ufoo skills install ufoo-bus-poll --target /path/to/that/agent/skills
+ufoo bus poll "<subscriber-id>" --follow --interval 2
 ```
 
-Run the final command through that host's streaming background-task facility.
+Use the subscriber returned by MCP `register_agent` or provisioned by the host,
+then run the final command through that host's streaming background-task facility.
 It prints newly observed pending events but never claims or acknowledges them;
 the agent runs the printed `ufoo bus ack --through <seq>` command only after
 handling the emitted batch, preserving later arrivals. The fallback is not

package/README.zh-CN.md

@@ -180,6 +180,10 @@ ufoo -g
 
 项目尚未初始化时，也可以先在外部执行等价 CLI：`ufoo init --targets context,bus`。
 
+默认 Agent skill 有意精简为 `ufoo`、`ufoo-bus`、`ufoo-context` 和
+`ufoo-online`。它们只作为 skill 安装，不再生成一份 command 目录，
+避免宿主显示两个入口；初始化和统一状态统一由 `ufoo` 处理。
+
 ### 事件总线
 
 ```text
@@ -198,11 +202,12 @@ bus 消息流：
 
 ```bash
 ufoo skills list --optional
-ufoo skills install ubus-poll --target /path/to/that/agent/skills
-ufoo bus poll "$UFOO_SUBSCRIBER_ID" --follow --interval 2
+ufoo skills install ufoo-bus-poll --target /path/to/that/agent/skills
+ufoo bus poll "<subscriber-id>" --follow --interval 2
 ```
 
-最后一条命令必须由该 host 的流式后台任务能力托管。它只输出新观察到的
+使用 MCP `register_agent` 返回或由 host 预配的 subscriber，并由该 host 的
+流式后台任务能力托管最后一条命令。它只输出新观察到的
 pending event，不 claim、不 ack；Agent 处理完输出批次后，再执行输出中
 给出的 `ufoo bus ack --through <seq>`，以保留稍后到达的消息。
 这个 fallback 不会被 postinstall 或 `skills install all` 安装，而且

package/SKILLS/ufoo/SKILL.md

@@ -1,219 +1,96 @@
 ---
 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).
+description: >-
+  Coordinate a ufoo workspace across context decisions, durable memory, event-bus
+  delivery, status, and initialization. Use at the start of an agent session in
+  a ufoo project, or when asked to initialize, inspect, or coordinate the unified
+  ufoo protocol.
 ---
 
-# ufoo — Unified Agent Protocol
+# ufoo
 
-ufoo is the multi-agent coordination layer. It provides four capabilities:
+Apply the unified workspace protocol. Use `$ufoo-bus`, `$ufoo-context`, or
+`$ufoo-online` when the task needs the focused workflow.
 
-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
+## Synchronize workspace state
 
-## 1. Context Decisions (uctx)
+1. Read open decisions before related work:
 
-### When to Record
+   ```bash
+   ufoo ctx decisions -s open
+   ```
 
-**"Only record decisions that matter beyond this session."**
+2. Read each relevant decision fully. Follow unresolved implications; never
+   resolve a decision from its title alone.
+3. Consume relevant shared memory before writing new memory.
+4. Keep the default as no new decision and no new memory entry.
 
-The default is **no new decision**. Record one only for important, plan-level knowledge that other agents or your future self will need.
+## Handle injected messages
 
-- **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
+Treat these prompt prefixes as work inputs:
 
-### Commands
+- `[ufoo]<from:id(nickname)>` — event-bus delivery from another agent.
+- `[manual]<to:id(nickname)>` — manual work directed to this agent.
 
-```bash
-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/`
-
-```yaml
----
-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
+For each received bus task:
 
-- **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
+1. Execute it immediately within the current authority.
+2. Acknowledge it only after handling:
 
-### Commands
+   ```bash
+   ufoo bus ack "$UFOO_SUBSCRIBER_ID"
+   ```
 
-```bash
-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. Reply only with a requested answer, delegated result, or fact the sender
+   needs to continue. Do not reply with greetings or bare acknowledgements.
+4. Emit a concise runtime report for delegated work:
 
-## 3. Event Bus (ubus)
+   ```bash
+   ufoo report done "<summary>" --agent "$UFOO_SUBSCRIBER_ID"
+   ```
 
-### Delivery Rule
+After sending or broadcasting a message, continue the current task. Do not
+poll, invoke a bus-check skill, sleep, or wait for a reply; follow-up messages
+are injected automatically.
 
-After `ufoo bus send` or `ufoo bus broadcast`, do not run
-`ufoo bus check`, invoke `/ubus`, sleep, or wait for a reply. Continue the
-current task. Any follow-up message will be automatically injected into your
-prompt/session.
+## Preserve shared knowledge
 
-When `/ubus` is explicitly requested, follow its pending-message flow
-immediately. Do not invoke it merely to wait for a reply to a message you sent.
-
-### Commands
+Record a decision only for architecture, meaningful trade-offs, cross-agent
+contracts, or precedent that constrains future work:
 
 ```bash
-ufoo bus check "$UFOO_SUBSCRIBER_ID"        # Used by an explicit /ubus request
-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
+ufoo ctx decisions new "<title>"
 ```
 
-### Runtime Report (Unified for assistant/ucodex/uclaude)
-
-Use the same report contract for runtime progress sync:
+Store only durable project facts in shared memory:
 
 ```bash
-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
+ufoo memory add "<title>" --body "<durable fact>" --tags <tags>
+ufoo memory list
+ufoo memory show <memory-id>
+ufoo memory edit <memory-id>
 ```
 
-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 a message is received
-
-**EXECUTE tasks immediately. Do NOT ask the user.**
+Do not use decisions or memory as progress logs, scratchpads, or transient
+status storage.
 
-1. Read the available `[ufoo]<from:...>` message.
-2. Execute each task.
-3. **Always ack after handling**: `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>"`
+## Inspect unified status
 
-If `/ubus` is explicitly requested, run
-`ufoo bus check "$UFOO_SUBSCRIBER_ID"` and then follow the same execute → ack
-flow.
+Run:
 
----
-
-## 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:
 ```bash
-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
+ufoo status
 ```
 
----
+Summarize unread messages, open decisions, and any immediate action needed.
 
-## 6. Initialization (uinit)
+## Initialize workspace state
 
-Trigger: `/uinit` or `/ufoo init`
+Initialize only the required targets:
 
 ```bash
-ufoo init --targets context,bus --project $(pwd)
+ufoo init --targets context,bus --project "$(pwd)"
 ```
 
-After init, auto-join bus if enabled.
+Reuse an existing subscriber identity after initialization. Join the bus only
+when no current identity can be recovered.

package/SKILLS/ufoo/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ufoo"
+  short_description: "Coordinate ufoo workspace state and agent protocol"
+  default_prompt: "Use $ufoo to synchronize and coordinate this ufoo workspace."

package/SKILLS/ufoo-bus/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: ufoo-bus
+description: >-
+  Operate the local ufoo event bus: check and acknowledge pending messages,
+  identify or join a subscriber, inspect status, resolve targets, send results,
+  and broadcast updates. Use when asked to handle bus messages or perform local
+  agent-to-agent routing.
+---
+
+# ufoo bus
+
+Operate the project-local event bus without creating reply loops or competing
+with automatic prompt injection.
+
+## Establish the subscriber
+
+Verify `.ufoo/bus/` exists. If it does not, initialize it:
+
+```bash
+ufoo init --targets bus --project "$(pwd)"
+```
+
+Prefer `UFOO_SUBSCRIBER_ID`, then recover the current identity:
+
+```bash
+ufoo bus whoami
+```
+
+Run `ufoo bus join` only when neither source yields an identity. Rejoining can
+cause identity drift.
+
+## Handle pending messages
+
+Check messages only when this skill was invoked to do so:
+
+```bash
+ufoo bus check "$UFOO_SUBSCRIBER_ID"
+```
+
+For every pending batch:
+
+1. Read the sender from `[ufoo]<from:id(nickname)>`.
+2. Execute each actionable task.
+3. Acknowledge after handling:
+
+   ```bash
+   ufoo bus ack "$UFOO_SUBSCRIBER_ID"
+   ```
+
+   When a batch supplies a final sequence, prefer
+   `ufoo bus ack "$UFOO_SUBSCRIBER_ID" --through <seq>` so later arrivals stay
+   pending.
+4. Reply only when the sender requested an answer, delegated work whose result
+   is needed, or needs a discovered blocker or fact.
+
+Do not reply to greetings, thanks, `ok`, `收到`, or other acknowledgement-only
+messages. Acknowledge them locally and stop.
+
+## Route messages
+
+Inspect identities and nicknames before sending:
+
+```bash
+ufoo bus status
+ufoo bus resolve "$UFOO_SUBSCRIBER_ID" <target>
+```
+
+Send to an exact subscriber ID, unique nickname, or agent type:
+
+```bash
+ufoo bus send "<target>" "<substantive message>"
+ufoo bus broadcast "<substantive message>"
+```
+
+Target resolution order is exact ID, nickname, agent type, then `*`.
+
+After sending or broadcasting, continue the current task. Do not run
+`ufoo bus check`, poll, sleep, or wait for a reply. Follow-up messages are
+injected into the prompt/session automatically.
+
+## Report delegated work
+
+Use the shared report contract when bus work represents a task:
+
+```bash
+ufoo report start "<task>" --task <id> --agent "$UFOO_SUBSCRIBER_ID"
+ufoo report progress "<detail>" --task <id> --agent "$UFOO_SUBSCRIBER_ID"
+ufoo report done "<summary>" --task <id> --agent "$UFOO_SUBSCRIBER_ID"
+ufoo report error "<reason>" --task <id> --agent "$UFOO_SUBSCRIBER_ID"
+```
+
+Use `--scope private` only for helper-internal reports.

package/SKILLS/ufoo-bus/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ufoo bus"
+  short_description: "Handle local ufoo bus messages and agent routing"
+  default_prompt: "Use $ufoo-bus to check and handle pending event-bus work."

package/SKILLS/ufoo-context/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: ufoo-context
+description: >-
+  Synchronize ufoo context decisions and durable shared memory. Use when
+  starting work in a ufoo project, reviewing open architectural decisions,
+  recording a consequential decision, recalling durable project facts, or
+  maintaining the shared context index.
+---
+
+# ufoo context
+
+Read shared context before writing it. Keep decisions sparse and memory
+durable.
+
+## Read decisions first
+
+List open decisions:
+
+```bash
+ufoo ctx decisions -s open
+```
+
+Read each relevant decision fully. Determine whether its implications require
+work, verification, or no action. Never resolve a decision from its title.
+
+Use these commands for broader inspection:
+
+```bash
+ufoo ctx decisions -l
+ufoo ctx decisions -n 1
+ufoo ctx decisions -s all
+ufoo ctx decisions index
+```
+
+If context state is missing, initialize it:
+
+```bash
+ufoo init --targets context --project "$(pwd)"
+```
+
+## Record only consequential decisions
+
+Create a decision only for:
+
+- architectural choices;
+- meaningful trade-offs with rejected alternatives;
+- cross-agent or integration contracts;
+- precedent that constrains future work.
+
+Do not create decisions for routine fixes, implementation details, generic
+plans, transient findings, or task progress.
+
+Create a decision before acting on it:
+
+```bash
+ufoo ctx decisions new "<short title>"
+```
+
+Use the canonical body:
+
+```yaml
+---
+status: open
+nickname: <nickname>
+---
+# DECISION NNNN: <Title>
+
+Date: YYYY-MM-DD
+Author: <agent>
+Nickname: <nickname>
+
+Context:
+<why a decision was required>
+
+Decision:
+<what is now true>
+
+Implications:
+<what future work must follow>
+```
+
+Resolve only after required implications are understood and completed. Change
+frontmatter status fields without rewriting historical content.
+
+## Maintain durable memory
+
+Search or recall before adding:
+
+```bash
+ufoo memory list
+ufoo memory show <memory-id>
+ufoo memory add "<title>" --body "<durable fact>" --tags <tags>
+ufoo memory edit <memory-id>
+ufoo memory forget <memory-id>
+ufoo memory rebuild-index
+ufoo memory audit <memory-id>
+```
+
+Store stable project invariants, ownership facts, and long-lived integration
+constraints. Do not store current task state, user preferences, ephemeral
+observations, or facts likely to expire.

package/SKILLS/ufoo-context/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ufoo context"
+  short_description: "Sync ufoo decisions and durable shared memory"
+  default_prompt: "Use $ufoo-context to review shared decisions and durable project memory."