u-foo 3.0.13 → 3.0.15

package/OPTIONAL_SKILLS/ubus-poll/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: ubus-poll
+description: |
+  Explicitly start a resident ufoo bus stream in an agent host that has been
+  configured to deliver streaming background-task output. Install by name only.
+---
+
+# /ubus-poll - Resident Bus Stream
+
+This is an opt-in session-start skill. Run it only in a host where a human has
+configured this fallback. Do not install or invoke it for Codex CLI, Claude
+Code CLI, Agy, Kimi, or native ucode; those runtimes already have their own
+ufoo delivery path.
+
+## Start once per agent session
+
+Reuse the provisioned subscriber identity. Never create a second identity just
+for the poll process.
+
+```bash
+SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-}"
+test -n "$SUBSCRIBER" || {
+  echo "ubus-poll requires a provisioned UFOO_SUBSCRIBER_ID"
+  exit 1
+}
+```
+
+Identity provisioning is a host/human setup step. Do not guess an agent type,
+call bare `ufoo bus join`, or borrow the workspace's current subscriber.
+
+Use the agent host's **streaming background-task** facility to start:
+
+```bash
+ufoo bus poll "$SUBSCRIBER" --follow --interval 2
+```
+
+The command must remain owned by that facility. Do not use `nohup`, shell `&`,
+or an OS-detached daemon: those routes can put output in a log that never
+reaches the agent. The command rejects a second resident poll for the same
+subscriber.
+
+The poll is deliberately queue-read-only. It emits current pending events at
+startup, waits for that batch to be acknowledged, then emits the next pending
+batch. It does not ack, claim, inject, or clear messages itself.
+
+## When background output arrives
+
+For every `[ufoo]<from:...>` event:
+
+1. Read `Content.message` and execute actionable work.
+2. After handling the emitted batch, run the exact `ack --through <seq>`
+   command printed by the poll stream. For example:
+
+   ```bash
+   ufoo bus ack "$SUBSCRIBER" --through 42
+   ```
+
+   `--through` preserves any later message that was not in the displayed batch.
+
+3. Reply to the sender only for a requested result, an answer, or information
+   they need to continue:
+
+   ```bash
+   ufoo bus send "<sender-id>" "<substantive result>"
+   ```
+
+Ack-only messages, greetings, and thanks need no reply.
+
+After sending, do not poll, sleep, or wait for a reply. Keep working; this
+resident stream will emit any follow-up.
+
+## Host requirement
+
+This flow works only when the agent host forwards incremental output from a
+still-running background task into the agent session. If it only returns output
+after process exit, use an explicitly invoked `/ubus` instead.

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
@@ -199,6 +204,23 @@ Use `/bus status` to find the real subscriber ID or resolvable nickname
 before sending. Agents should handle pending work, reply to the sender, and
 acknowledge their queue.
 
+Agent hosts that cannot receive ufoo prompt injection can opt into a resident,
+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
+```
+
+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
+installed by postinstall or `skills install all`, and follow mode refuses Codex
+CLI, Claude Code CLI, Agy, Kimi, and native ucode subscriber types so their
+existing delivery paths remain untouched.
+
 ### Context, Memory, History, Reports
 
 Inside chat:

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
@@ -193,6 +197,22 @@ ufoo -g
 发送消息前，先用 `/bus status` 查看真实 subscriber ID 或可解析昵称。
 Agent 应处理 pending work、回复发送方，并 ack 自己的队列。
 
+无法接收 ufoo prompt 注入的 Agent host 可以显式启用常驻、队列只读的
+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
+```
+
+最后一条命令必须由该 host 的流式后台任务能力托管。它只输出新观察到的
+pending event，不 claim、不 ack；Agent 处理完输出批次后，再执行输出中
+给出的 `ufoo bus ack --through <seq>`，以保留稍后到达的消息。
+这个 fallback 不会被 postinstall 或 `skills install all` 安装，而且
+follow 模式会拒绝 Codex CLI、Claude Code CLI、Agy、Kimi 和原生 ucode
+的 subscriber 类型，确保其现有投递链路不受影响。
+
 ### Context、Memory、History、Report
 
 在 chat 内：

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."