| name | agent-docs-channel |
| description | Use Agent Docs channel for live multi-agent collaboration, spawned workers, cross-agent review, progress inspection, forum channels, and channel log debugging. |
agent-docs-channel
agent-docs channel is the local multi-agent collaboration runtime. Reach for it when agents need to talk through a durable event log, when a worker should be spawned as a peer process, when an in-flight worker needs interrupt / debugging, or when feedback should be recorded on a durable --type forum channel.
Typical user signals: "和 codex/claude 讨论", "brainstorm with another agent", "spawn an implement/check worker", "let agent review", "open an issue board / changelog forum", "look at this thread", "channel is stuck / no output", "progress was truncated", "how do I write that channel command".
This skill is an index. Load only the reference file for the current job — do not preload all of them.
First Commands
agent-docs --version
agent-docs channel --help
agent-docs channel list --all
agent-docs channel list --scope global --all
If the user names a channel or thread, inspect it before asking for background:
agent-docs channel forum <board> --scope global
agent-docs channel thread <board> <thread> --scope global
agent-docs channel context list <board> --scope global --thread <thread>
Route By User Intent
| User intent | Read |
|---|
| "和 codex/claude 讨论一下", "brainstorm with another agent" | references/workflows.md |
| "派一个 implement/check agent", "让 agent review", "spawn a worker" | references/workflows.md, then references/workers.md |
| "开 issue 区 / topic 群 / changelog / board", "make a forum" | references/forum.md |
| "看看这个 thread / linked context", "inspect a thread" | references/forum.md |
| "channel 卡住了 / 没输出 / progress 被截断", "worker stalled" | references/progress-debugging.md |
| "具体命令怎么写", "what flags does X take" | references/command-reference.md |
Core Rules
- New forum channels use
--type forum. A thread is one item inside a forum channel.
- Use
--context-file / --context-raw and agent-docs channel context add/delete/list. --linked-context-* is deprecated terminology.
- Use
--stdin or --text-file for long messages. Do not put long mixed Chinese/English text in the positional shell argument.
- Pretty
messages output is an operator dashboard and may truncate progress. Use --raw for audit.
--as is the speaker or worker handle, depending on the command. Use explicit, stable names when multiple agents or sessions are involved.--scope project (default) operates on the current cwd's project bucket; --scope global operates on the shared __global__ bucket. Pick scope deliberately — a global board is invisible from project listings unless --scope global is passed.- For brainstorm, do multiple pressure-test rounds. One answer plus one confirmation is review, not brainstorm.
- Dispatcher wait pattern: use
--kind done / --kind turn_finished (agent-docs-emitted system events), NOT a user --tag as the completion signal. CLI help lists phase_done / question as --tag examples but only interrupt is a reserved tag with hardcoded agent-docs behavior; the others are opaque user labels. Relying on a worker to run send --tag <my_signal> is unreliable — LLM workers commonly write the tag string into prose instead of running the actual CLI command. See references/command-reference.md "tag vs kind".
- Forum channels are event-sourced. Do not parse
events.jsonl first; use forum, thread, messages --thread, and context list.
@mindfoldhq/agent-docs-core owns reusable channel/thread state, event append, seq allocation, context/title projection, reducers, and task helpers. The CLI owns flags, terminal rendering, prompts, worker lifecycle, and process exits.
Reference Files
references/workflows.md — canonical collaboration patterns A–F (peer brainstorm, spawned review, dispatch-and-wait, forum issue capture, interrupt-and-redirect, one-shot run).references/forum.md — forum channels, context, title, rename, changelog forums, thread filtering.references/workers.md — spawn, agent cards, context injection (--file / --jsonl), interrupts, kill semantics.references/progress-debugging.md — progress/raw inspection, stalled worker diagnosis, OOM guard, exit codes.references/command-reference.md — current CLI command reference (every subcommand, every flag, output conventions, scope/type model).
Not For
- One static review where a markdown file and prompt are enough.
- Replacing normal tool calls with self-logging.
- Long-term memory retrieval. Use durable forum channels for actionable issues, and
agent-docs mem (the agent-docs-session-insight skill) for session/history search.
