agent-docs-channel

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.