这是 bro CLI 的文档技能说明页，用于在直接操作 bro 文档（任务 beads 与存储 store）时提供策略约定。实际机制全部由 bro CLI 实现，该技能本身只包含策略，不包含实现。
用途 bro 的文档接口采用名词优先的 gh 风格：bro <noun> <verb> [ref…] [--flags]。文档类型由插件注册，目前包含 task 和 store。每种类型的适配器方法就是动词注册表，因此没有统一的动词列表可供查阅。动词位于所属名词的命名空间内，插件文档类型可以自由定义任意自定义动词。
主要能力 任务类支持列出任务、查看单个文档（可根据 ref 前缀推断类型）、创建文档并返回、更新字段、关闭或删除任务，以及通过 exec 对存储执行原始 bd 命令。存储类支持列出存储清单（路径、前缀、健康状态）、查看解析后的全局目录详情、初始化并校验全局存储、打印解析后的全局存储目录，以及从全局队列调度任务。任务动词通过 tasks 连接器门面解析，内置提供者为 beads；bro.config.json 中的 connectors.tasks 或插件自带的连接器可以重定向这些动词。
使用方式 任务动词同时支持动词优先的简写：bro list、bro show <id>、bro close <id> 等价于 bro task …。单独一个 ref 会根据其前缀推断类型；单独一个名词（bro task、bro store）表示执行列出操作。--global 是作用域标志，而不是命令：同样的动词会作用于用户级存储（默认 ~/.local/share/bro/beads，可通过 bro.config.json 的 beads.global 或环境变量 $BRO_GLOBAL_BEADS 重新定位，环境变量优先）。存储从不混用：bro list、bro flow next、bro flow loop 和钩子只读取当前检出的 .beads；全局工作必须在每次调用时显式启用（--global）。全局存储默认仅限本地，没有同步远端；如需跨机器队列，应在该存储内部设置其自身的 Dolt remote（bd dolt remote），bro 不负责管理。
适用场景 项目工作应写入项目 beads；全局 beads 只能通过 bro flow next --global 或带 --global 的文档动词操作。全局存储用于用户级工作，例如跨仓库任务、个人待办，以及不应进入项目 issue 跟踪器或 PR 的内容。如有疑问，应写入项目。
限制 应优先使用类型化动词，而不是 exec；bro task exec -- … 仅用于文档层尚未建模的 bd 功能，工作流输出应通过类型化动词产生，以保持 ref 推断和渲染正常工作。文档命名空间受保护：保留字由插件命令名、文档名词与别名、简写动词组成；如果插件占用了保留名，或文档类型在名词、别名、idPrefix 上发生冲突，该插件会被跳过并给出警告，其余内容仍可使用。