@logicseek/hello-cc 0.1.2 → 0.1.4

package/docs/README.md

@@ -10,9 +10,11 @@ summary and first command. Use these docs when you need more detail.
 - [Command Reference](commands.md): compact list of public commands and the
   intended use of each command group.
 - [Changelog](../CHANGELOG.md): release notes for published versions.
-- Release notes: run `npm run release:check` before publishing, and use
-  `npm run release:notes` to print the current changelog section for GitHub
-  Release notes.
+- Release notes: run `npm run release:check` and
+  `npm run release:github:dry-run` before publishing. Pushing a `v*` tag runs
+  `.github/workflows/github-release.yml`, which creates or updates the GitHub
+  Release description from the current changelog section. Use
+  `workflow_dispatch` to backfill older releases without a personal token.
 
 ## Design And Implementation
 

package/docs/README.zh-CN.md

@@ -9,9 +9,11 @@
   peer 身份和环境变量行为。
 - [命令参考](commands.zh-CN.md)：公共命令的紧凑清单，以及每组命令的用途。
 - [更新日志](../CHANGELOG.md)：已发布版本的 release notes。
-- 发行说明：发布前运行 `npm run release:check`，用
-  `npm run release:notes` 输出当前版本的 changelog 小节，作为 GitHub
-  Release 描述。
+- 发行说明：发布前运行 `npm run release:check` 和
+  `npm run release:github:dry-run`。推送 `v*` tag 会触发
+  `.github/workflows/github-release.yml`，根据当前 changelog 小节创建或更新
+  GitHub Release 描述。旧版本可用 `workflow_dispatch` 补写描述，不需要个人
+  token。
 
 ## 设计和实现
 

package/docs/commands.md

@@ -18,20 +18,25 @@ current project's `.hello-cc` data and guidance blocks.
 ## Start And Stop
 
 ```text
-hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-discover] [--no-guidance]
+hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-token] [--no-discover] [--no-guidance]
 hcc down
 hcc up [--no-discover] [--no-guidance]
 ```
 
 `hcc web` is the default entry. It initializes coordination, installs hooks and
-shims, starts or reuses the Web console, and returns the terminal to you. Use
-`hcc up` only when you want coordination without the Web console or shims.
+shims, starts or reuses the Web console, and returns the terminal to you. Bare
+`hcc web` listens on `0.0.0.0` and uses a saved URL token, generating one on
+first use. Use `--local` to bind only `127.0.0.1`, `--token` or `HCC_WEB_TOKEN`
+to replace the saved token, and
+`--no-token` only in trusted local/test environments. Use `hcc up` only when you
+want coordination without the Web console or shims.
 
 ## Peers And Status
 
 ```text
 hcc peers
 hcc status [--peer ID]
+hcc state [--peer ID] [--resource PATH] [--intent work|stop|finish]
 hcc scan [--register]
 hcc prompt --peer ID [--kind codex|claude|shell|other] [--role ROLE]
 hcc join --peer ID [--kind codex|claude|shell|other] [--role ROLE]
@@ -41,7 +46,12 @@ hcc run --peer ID --kind codex|claude|shell --role ROLE -- COMMAND [ARGS...]
 ```
 
 Use these commands to inspect live project state, register terminals, and run a
-CLI with `HCC_PEER`, `HCC_ROOT`, and `HCC_DB` set.
+CLI with `HCC_PEER`, `HCC_ROOT`, and `HCC_DB` set. `hcc state` does not execute
+coordination actions such as acking messages, claiming tasks, acquiring locks, or
+creating handoffs. It adds a unified collaboration timeline plus
+`automation.next_action.argv`, a machine-readable next coordination command for
+agents to execute explicitly. `automation.current_task` records the peer's active
+task when one exists.
 
 ## Browser-Controllable Terminals
 
@@ -66,12 +76,16 @@ controlled from the Web console.
 hcc msg send [--from ID] [--to ID|all] --body TEXT [--task N] [--kind note|task|handoff]
 hcc msg inbox [--peer ID] [--wait SEC] [--all] [--limit N]
 hcc msg ack [--peer ID] --id N
+hcc msg reply [--from ID] --id N --body TEXT [--to ID] [--kind reply]
+hcc msg thread --id N [--limit N]
 hcc ask PEER MESSAGE [--from ID] [--task N] [--inject]
 hcc broadcast MESSAGE [--from ID] [--task N] [--inject]
 ```
 
 Messages are addressed mailbox items. `ask` and `broadcast` also support live
-terminal injection with `--inject`.
+terminal injection with `--inject`. Use `msg reply` when answering a specific
+message; the reply stays in the same thread and is sent back to the original
+sender by default. Use `msg thread` to inspect the full thread for one message.
 
 ## Tasks
 
@@ -79,13 +93,30 @@ terminal injection with `--inject`.
 hcc task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
 hcc task list [--status S] [--peer ID] [--all]
 hcc task claim [--peer ID] --id N
-hcc task next [--peer ID]
+hcc task next [--peer ID] [--force]
+hcc task create --title TEXT --parent N [--team-role ROLE]
 hcc task update [--peer ID] --id N --status running|review|blocked|done|abandoned [--summary TEXT] [--body TEXT] [--to ID]
 hcc task done [--peer ID] --id N --summary TEXT
 ```
 
 Tasks are shared project facts. They remain visible until marked `done` or
-`abandoned`.
+`abandoned`. `task next` returns your existing claimed/running/review/blocked
+task before claiming a new pending task; use `--force` only when intentionally
+taking another pending task.
+
+## Teams
+
+```text
+hcc team plan --from-task N [--item ROLE:TITLE] [--item PEER:ROLE:TITLE] [--workers A,B|codex:2,claude:1]
+hcc team start --from-task N [--item ROLE:TITLE] [--item PEER:ROLE:TITLE] [--workers A,B|codex:2,claude:1] [--force]
+hcc team status --task N
+```
+
+Teams are explicit parent-task splits. `team plan` is read-only and shows the
+subtasks that would be created. `team start` creates child tasks under the
+parent and optionally assigns them to worker peer IDs. It does not silently
+spawn model processes or override the current-task rule. `--workers` accepts
+explicit peer IDs or kind counts such as `codex:2,claude:1`.
 
 ## Locks, Handoffs, And Events
 

package/docs/commands.zh-CN.md

@@ -17,20 +17,23 @@ hcc uninstall [--purge --yes]
 ## 启动和停止
 
 ```text
-hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-discover] [--no-guidance]
+hcc web [--host HOST] [--port N] [--token TEXT] [--local] [--no-token] [--no-discover] [--no-guidance]
 hcc down
 hcc up [--no-discover] [--no-guidance]
 ```
 
 `hcc web` 是默认入口。它会初始化协作状态，安装 hooks 和 shims，启动或复用
-Web 控制台，然后把终端还给你。只想使用本地协作、不需要 Web 或 shims 时，
-再使用 `hcc up`。
+Web 控制台，然后把终端还给你。裸 `hcc web` 会监听 `0.0.0.0` 并使用固定
+URL token；首次使用时自动生成并保存。用 `--local` 可只绑定 `127.0.0.1`，
+用 `--token` 或 `HCC_WEB_TOKEN` 可替换保存的 token，只有在可信本地/测试环境才使用 `--no-token`。
+只想使用本地协作、不需要 Web 或 shims 时，再使用 `hcc up`。
 
 ## Peers 和状态
 
 ```text
 hcc peers
 hcc status [--peer ID]
+hcc state [--peer ID] [--resource PATH] [--intent work|stop|finish]
 hcc scan [--register]
 hcc prompt --peer ID [--kind codex|claude|shell|other] [--role ROLE]
 hcc join --peer ID [--kind codex|claude|shell|other] [--role ROLE]
@@ -40,7 +43,10 @@ hcc run --peer ID --kind codex|claude|shell --role ROLE -- COMMAND [ARGS...]
 ```
 
 这些命令用于查看项目状态、注册终端，以及用 `HCC_PEER`、`HCC_ROOT`、
-`HCC_DB` 环境运行 CLI。
+`HCC_DB` 环境运行 CLI。`hcc state` 不会执行确认消息、认领任务、获取锁或
+创建 handoff 这类协作动作；它会返回统一协作时间线，以及
+`automation.next_action.argv` 这种机器可读的下一步协作命令，供 agent 显式执行
+并留下审计记录。`automation.current_task` 会记录当前 peer 已经拥有的活动任务。
 
 ## Web 可控终端
 
@@ -64,12 +70,15 @@ hcc inject PEER TEXT [--no-enter]
 hcc msg send [--from ID] [--to ID|all] --body TEXT [--task N] [--kind note|task|handoff]
 hcc msg inbox [--peer ID] [--wait SEC] [--all] [--limit N]
 hcc msg ack [--peer ID] --id N
+hcc msg reply [--from ID] --id N --body TEXT [--to ID] [--kind reply]
+hcc msg thread --id N [--limit N]
 hcc ask PEER MESSAGE [--from ID] [--task N] [--inject]
 hcc broadcast MESSAGE [--from ID] [--task N] [--inject]
 ```
 
 消息是带收件人的邮箱记录。`ask` 和 `broadcast` 加 `--inject` 后，也会把内容
-实时注入到终端。
+实时注入到终端。回复某条消息时使用 `msg reply`；默认会发回原 sender，并保留
+在同一个 thread 中。使用 `msg thread` 可以查看某条消息所在的完整线程。
 
 ## 任务
 
@@ -77,12 +86,28 @@ hcc broadcast MESSAGE [--from ID] [--task N] [--inject]
 hcc task create --title TEXT [--body TEXT] [--from ID] [--to ID] [--priority N]
 hcc task list [--status S] [--peer ID] [--all]
 hcc task claim [--peer ID] --id N
-hcc task next [--peer ID]
+hcc task next [--peer ID] [--force]
+hcc task create --title TEXT --parent N [--team-role ROLE]
 hcc task update [--peer ID] --id N --status running|review|blocked|done|abandoned [--summary TEXT] [--body TEXT] [--to ID]
 hcc task done [--peer ID] --id N --summary TEXT
 ```
 
 任务是项目共享事实。任务会一直可见，直到被标记为 `done` 或 `abandoned`。
+`task next` 会优先返回当前 peer 已经认领、运行、审查或阻塞中的任务；只有明确
+要再接一个 pending 任务时才使用 `--force`。
+
+## 团队
+
+```text
+hcc team plan --from-task N [--item ROLE:TITLE] [--item PEER:ROLE:TITLE] [--workers A,B|codex:2,claude:1]
+hcc team start --from-task N [--item ROLE:TITLE] [--item PEER:ROLE:TITLE] [--workers A,B|codex:2,claude:1] [--force]
+hcc team status --task N
+```
+
+团队是显式的父任务拆分。`team plan` 只读，只展示会创建哪些子任务。
+`team start` 会在父任务下创建子任务，并可把子任务分配给 worker peer。
+它不会静默启动模型进程，也不会绕过“先继续当前任务”的规则。`--workers`
+支持显式 peer ID，也支持 `codex:2,claude:1` 这种 kind 数量形式。
 
 ## 锁、交接和事件
 

package/docs/design.md

@@ -170,12 +170,13 @@ Server polls/captures tmux pane output and broadcasts it to browsers.
 ```text
 peers         stable terminal identities and heartbeat
 peer_bindings provider session binding and runtime transport metadata
-tasks         task assignment, ownership, and lifecycle
-messages      direct or broadcast messages
+tasks         task assignment, ownership, hierarchy, and lifecycle
+messages      direct, broadcast, or threaded messages
 message_reads per-peer ack state
 locks         advisory exclusive locks with TTL
 handoffs      durable cross-session handoff summaries
 events        audit trail for observability
+schema_migrations applied SQLite schema version history
 ```
 
 ## Coordination Semantics
@@ -185,10 +186,17 @@ events        audit trail for observability
 - SQLite runs with WAL and `busy_timeout=5000`.
 - Tasks are project facts. They remain visible to all peers until status becomes
   `done` or `abandoned`.
+- Tasks can form explicit parent/child hierarchies for team splits. Team commands
+  create auditable child tasks; they do not silently spawn model processes.
 - Messages are addressed mailbox items. Read state is tracked per peer.
+- Message replies keep `reply_to` and `thread_id` so peer-visible collaboration
+  history can be reconstructed without terminal capture.
 - Broadcast messages use per-peer acknowledgement, so one peer cannot consume a
   message for everyone else.
 - Locks are advisory and TTL-based. Peers must follow the protocol.
+- `hcc state` and `/api/state` expose a derived timeline plus
+  `automation.next_action.argv`; the command is advisory and does not execute
+  coordination actions itself.
 
 ## Hook Path
 
@@ -196,8 +204,8 @@ The primary model-facing path is hook context injection, not project markdown.
 
 `hcc web` installs hooks that register sessions and inject hello-cc snapshots at
 session start and before model answers. The injected snapshot contains current
-peer identity, active peers, open tasks, unread messages, active locks, and the
-commands the model should use to inspect state.
+peer identity, active peers, open tasks, unread messages, active locks, the
+current task when one exists, and the next auditable coordination action.
 
 `CLAUDE.md`, `AGENTS.md`, and `.hello-cc/HCC.md` are fallback instruction
 layers. Existing root files are updated only inside a bounded hello-cc block.

package/docs/guide.md

@@ -70,8 +70,8 @@ project: /path/to/project
 database: /path/to/project/.hello-cc/mesh.db
 runtime: /path/to/project/.hello-cc/runtime.json
 log: /path/to/project/.hello-cc/web.log
-open: http://<machine-ip>:8787/?project=%2Fpath%2Fto%2Fproject
-local: http://127.0.0.1:8787/?project=%2Fpath%2Fto%2Fproject
+open: http://<machine-ip>:8787/?token=<token>&project=%2Fpath%2Fto%2Fproject
+local: http://127.0.0.1:8787/?token=<token>&project=%2Fpath%2Fto%2Fproject
 shims: installed claude, codex
 PATH updated in ~/.bashrc; open a new terminal or source it
 stop: hcc down
@@ -157,6 +157,8 @@ Tasks and messages have different read semantics:
   `abandoned`.
 - Messages are addressed mailbox items. `hcc msg inbox` defaults to unread
   messages for the current peer, and `hcc msg ack` records per-peer read state.
+- Message replies are threaded. Use `hcc msg reply --id N --body "..."` when
+  answering a message, and use `hcc msg thread --id N` to read the full thread.
 - `ask` and `broadcast` write durable messages. With `--inject`, they also send
   live input to runtime-attached terminals.
 - Locks use SQLite transactions and TTLs. They are coordination locks, not a
@@ -175,8 +177,9 @@ into the model context:
 - open tasks
 - unread messages for the current peer
 - active locks
-- suggested commands such as `hcc status`, `hcc peers`, `hcc task list`,
-  `hcc msg inbox`, and `hcc lock list`
+- a machine-readable next action from `hcc state`
+- suggested commands such as `hcc status`, `hcc state`, `hcc peers`,
+  `hcc task list`, `hcc msg inbox`, and `hcc lock list`
 
 When an attached Claude/Codex session is asked what other sessions are doing,
 it should answer from the latest hello-cc state instead of generic isolation
@@ -202,31 +205,46 @@ claude -p 'Do you see hello-cc open tasks?' --debug hooks --debug-file /tmp/hcc-
 The debug log should contain `Hook UserPromptSubmit ... provided
 additionalContext` and the `hello-cc coordination` block.
 
+`hcc state --peer <peer> [--resource PATH]` exposes the same coordination state
+without performing coordination actions such as acking messages, claiming tasks,
+acquiring locks, sending messages, creating handoffs, or marking tasks done. It
+returns the existing project arrays plus a unified `timeline` and an
+`automation` object. The important machine field is
+`automation.next_action.argv`: agents can execute that explicit hcc command, so
+the coordination flow becomes auditable instead of being only a prompt
+instruction. `automation.current_task` carries the peer's active task so a
+resumed session keeps working on the same task until it is handed off, done, or
+blocked.
+
 ## Web Console
 
-Start local and LAN-visible control:
+Start local and LAN-visible control with token authentication:
 
 ```bash
 hcc web
 ```
 
-Use a token only when you want one:
+Bare `hcc web` stores its generated token and reuses it across restarts. Set a
+token explicitly when you want to replace the saved value:
 
 ```bash
-HCC_WEB_TOKEN='choose-a-long-token' hcc web --host 0.0.0.0 --port 8787
+HCC_WEB_TOKEN='choose-a-long-token' hcc web --port 8787
 ```
 
 Open from another machine on the same network:
 
 ```text
-http://<machine-ip>:8787/
+http://<machine-ip>:8787/?token=<token>
 ```
 
+Use `hcc web --local` to bind only `127.0.0.1`. Use `hcc web --no-token` only
+in a trusted local/test environment.
+
 The web console can:
 
 - switch between multiple registered project roots on one port
 - register another project path from the browser
-- show project state: peers, tasks, messages, locks, handoffs, events
+- show project state: next action, timeline, peers, tasks, and locks
 - operate local terminals: start Claude/Codex/shell, send keyboard input, view
   output, detach runtime control
 
@@ -240,6 +258,8 @@ Browser-controlled sessions are local tmux terminals:
 Already-open raw terminals cannot be captured or controlled unconditionally
 unless they started under tmux, screen, or a hello-cc shim. They can still
 participate in tasks, messages, and locks through hooks and `hcc` commands.
+For these coordination-only peers, the Web console shows collaboration through
+the Timeline rather than a terminal stream.
 
 ## Command Reference
 
@@ -281,10 +301,35 @@ hcc task next
 hcc lock acquire --resource vllm/router --ttl 900 --reason "implement diagnostics"
 ```
 
+`task next` first returns the peer's current claimed/running/review/blocked task.
+Use `hcc task next --force` only when intentionally taking another pending task.
+
+Split a task into an explicit team when the work is genuinely parallel:
+
+```bash
+hcc team plan --from-task 12 \
+  --item "docs:Update user guide" \
+  --item "tests:Add regression" \
+  --workers codex:1,claude:1
+
+hcc team start --from-task 12 \
+  --item "docs:Update user guide" \
+  --item "tests:Add regression" \
+  --workers codex:1,claude:1
+
+hcc team status --task 12
+```
+
+`team plan` is read-only. `team start` creates child tasks and assignment
+messages, but it does not spawn hidden model processes. Agents still claim,
+lock, hand off, and finish their own child tasks through the normal commands.
+
 Message or inject:
 
 ```bash
 hcc msg send --to claude-a --body "Implementation is ready for review."
+hcc msg reply --id 12 --body "Reviewed; no blocker found."
+hcc msg thread --id 12
 hcc ask claude-a "Please review the current implementation." --inject
 hcc broadcast "Pause edits under vllm/router until this task finishes." --inject
 ```
@@ -308,7 +353,7 @@ hcc lock release --resource vllm/router
 | `HCC_PEER` | default peer identity |
 | `HCC_ROOT` | override project root |
 | `HCC_DB` | override database path |
-| `HCC_WEB_TOKEN` | optional token for web access |
+| `HCC_WEB_TOKEN` | replace and save the stable web access token |
 | `HCC_RUNTIME_URL` | direct runtime URL |
 | `HCC_NO_AUTO_INSTALL_TMUX=1` | disable tmux auto-install, mainly for tests |
 

package/docs/guide.zh-CN.md

@@ -67,8 +67,8 @@ project: /path/to/project
 database: /path/to/project/.hello-cc/mesh.db
 runtime: /path/to/project/.hello-cc/runtime.json
 log: /path/to/project/.hello-cc/web.log
-open: http://<machine-ip>:8787/?project=%2Fpath%2Fto%2Fproject
-local: http://127.0.0.1:8787/?project=%2Fpath%2Fto%2Fproject
+open: http://<machine-ip>:8787/?token=<token>&project=%2Fpath%2Fto%2Fproject
+local: http://127.0.0.1:8787/?token=<token>&project=%2Fpath%2Fto%2Fproject
 shims: installed claude, codex
 PATH updated in ~/.bashrc; open a new terminal or source it
 stop: hcc down
@@ -143,6 +143,8 @@ Claude/Codex/普通 shell
 
 - 任务是项目事实。所有 peer 默认都能看到未 `done` 且未 `abandoned` 的任务。
 - 消息是带收件人的邮箱消息。`hcc msg inbox` 默认读取当前 peer 的未读消息，`hcc msg ack` 记录每个 peer 的已读状态。
+- 消息回复有 thread。回复某条消息时使用 `hcc msg reply --id N --body "..."`，
+  查看完整线程时使用 `hcc msg thread --id N`。
 - `ask` 和 `broadcast` 会写入持久消息；加 `--inject` 时，还会把内容实时注入到 Web runtime 已接管的终端。
 - 锁使用 SQLite 事务和 TTL，是协作式冲突避免，不是文件系统强制沙箱。
 
@@ -157,7 +159,8 @@ Claude/Codex/普通 shell
 - 未完成任务
 - 当前 peer 的未读消息
 - 活跃锁
-- 建议执行的 `hcc status`、`hcc peers`、`hcc task list`、`hcc msg inbox`、`hcc lock list`
+- 来自 `hcc state` 的机器可读下一步动作
+- 建议执行的 `hcc status`、`hcc state`、`hcc peers`、`hcc task list`、`hcc msg inbox`、`hcc lock list`
 
 因此，当你在已接入的 Claude/Codex 里问“其他会话在做什么”，模型应该基于 hello-cc 注入的最新状态回答，而不是回答“我无法知道其他会话”。
 
@@ -178,31 +181,41 @@ claude -p 'Do you see hello-cc open tasks?' --debug hooks --debug-file /tmp/hcc-
 
 debug 日志里应该出现 `Hook UserPromptSubmit ... provided additionalContext`，并包含 `hello-cc coordination` 块。
 
+`hcc state --peer <peer> [--resource PATH]` 会读取同一份协作状态，但不会执行
+确认消息、认领任务、获取锁、发送消息、创建 handoff 或标记完成这类协作动作。
+它返回现有项目数组、统一 `timeline`，以及 `automation` 对象。关键机器字段是
+`automation.next_action.argv`：agent 可以显式执行这条 hcc 命令，让协作流程留下
+可审计记录，而不是只依赖 prompt 里的自然语言规则。`automation.current_task`
+会携带当前 peer 的活动任务，让恢复后的会话继续同一个任务，直到交接、完成或阻塞。
+
 ## Web 控制台
 
-默认本机和内网访问：
+默认开启本机和内网访问，并启用 token 认证：
 
 ```bash
 hcc web
 ```
 
-需要令牌时再显式开启：
+裸 `hcc web` 会保存自动生成的 token，并在重启后复用。需要替换保存值时可显式设置：
 
 ```bash
-HCC_WEB_TOKEN='choose-a-long-token' hcc web --host 0.0.0.0 --port 8787
+HCC_WEB_TOKEN='choose-a-long-token' hcc web --port 8787
 ```
 
 同一内网机器打开：
 
 ```text
-http://<machine-ip>:8787/
+http://<machine-ip>:8787/?token=<token>
 ```
 
+使用 `hcc web --local` 可只监听 `127.0.0.1`。只有在可信本地/测试环境才使用
+`hcc web --no-token`。
+
 Web 控制台能做这些事：
 
 - 在一个端口里切换多个已注册项目 root
 - 直接在浏览器里注册新的项目路径
-- 查看项目状态：peers、tasks、messages、locks、handoffs、events
+- 查看项目状态：下一步动作、timeline、peers、tasks、locks
 - 操作本地终端：启动 Claude/Codex/shell、发送键盘输入、查看输出、停止接管
 
 Web 操作的是 hello-cc 管理的本机 tmux 终端：
@@ -213,6 +226,7 @@ Web 操作的是 hello-cc 管理的本机 tmux 终端：
 - 通过 `hcc peer attach` 接入的已有 tmux pane
 
 已经打开的普通 raw 终端不能被无条件捕获或控制，除非它原本就在 tmux、screen 或 hello-cc shim 之下。它仍然可以通过 hooks 和 `hcc` 命令参与任务、消息和锁。
+对于这类 coordination-only peer，Web 会通过 Timeline 展示协作轨迹，而不是显示终端流。
 
 ## 命令参考
 
@@ -252,10 +266,34 @@ hcc task next
 hcc lock acquire --resource vllm/router --ttl 900 --reason "实现路由诊断"
 ```
 
+`task next` 会先返回当前 peer 已经认领、运行、审查或阻塞中的任务。只有明确
+要再接一个 pending 任务时，才使用 `hcc task next --force`。
+
+当工作确实可以并行时，用显式团队把父任务拆成子任务：
+
+```bash
+hcc team plan --from-task 12 \
+  --item "docs:更新用户指南" \
+  --item "tests:增加回归测试" \
+  --workers codex:1,claude:1
+
+hcc team start --from-task 12 \
+  --item "docs:更新用户指南" \
+  --item "tests:增加回归测试" \
+  --workers codex:1,claude:1
+
+hcc team status --task 12
+```
+
+`team plan` 是只读命令。`team start` 会创建子任务和分配消息，但不会隐藏地启动
+模型进程。每个 agent 仍然通过普通任务、锁、交接和完成命令处理自己的子任务。
+
 发消息或实时注入：
 
 ```bash
 hcc msg send --to claude-a --body "实现已准备好供审查。"
+hcc msg reply --id 12 --body "已审查，未发现阻塞问题。"
+hcc msg thread --id 12
 hcc ask claude-a "请审查当前实现。" --inject
 hcc broadcast "暂停编辑 vllm/router，等待任务完成。" --inject
 ```
@@ -279,7 +317,7 @@ hcc lock release --resource vllm/router
 | `HCC_PEER` | 默认 peer 身份 |
 | `HCC_ROOT` | 覆盖项目根目录 |
 | `HCC_DB` | 覆盖数据库路径 |
-| `HCC_WEB_TOKEN` | 可选 Web 访问令牌 |
+| `HCC_WEB_TOKEN` | 替换并保存固定 Web 访问令牌 |
 | `HCC_RUNTIME_URL` | 直接指定 runtime URL |
 | `HCC_NO_AUTO_INSTALL_TMUX=1` | 禁用 tmux 自动安装，主要用于测试 |
 

package/docs/implementation.md

@@ -119,7 +119,9 @@ Messages:
 ```text
 from peer
 to peer | all | tag:<tag> | task:<task-id>
-kind note | ask | handoff | system
+kind note | ask | reply | handoff | system
+reply_to optional source message id
+thread_id root message id for threaded collaboration history
 delivery store-only | inject-terminal | both
 ```
 
@@ -128,11 +130,29 @@ Tasks:
 ```text
 pending -> claimed -> running -> review/block/done|abandoned
 owner is dynamic; there is no fixed dispatcher
+parent_id/team_role record explicit team child tasks
 ```
 
 Default task reads are lifecycle-based: all peers see tasks until they are
 `done` or `abandoned`. Read/ack state exists only for messages.
 
+`hcc team plan` is read-only. `hcc team start` creates child tasks under the
+parent and assignment messages; it does not spawn hidden agents or bypass the
+normal claim/lock/handoff protocol.
+
+State:
+
+```text
+hcc state / /api/state
+timeline derived from messages, handoffs, tasks, locks, and selected events
+automation.next_action.argv suggests the next explicit hcc command
+automation.current_task preserves sticky task context across prompts
+```
+
+State inspection does not perform coordination actions such as acking messages,
+claiming tasks, acquiring locks, sending messages, creating handoffs, or marking
+tasks done. Opening a DB may still run schema/version maintenance.
+
 Locks:
 
 ```text