Beans 是一个命令行驱动的扁平文件议题跟踪器，定位是让任务管理紧贴代码仓库，同时服务于人类开发者与编码智能体。
一、基本形态 任务（称为 bean）以 Markdown 文件保存在项目的 .beans/ 目录下，随代码一起版本控制。仓库地址为 https://github.com/hmans/beans，资料标注 760+ stars。安装方式、beans init 初始化以及智能体集成步骤位于 references/setup.md，资料未给出具体安装命令。文件格式（YAML frontmatter、文件名约定、字段结构）见 references/bean-file-format.md；文件由 CLI 管理，不应手工编辑 .beans/*.md。
二、结构模型 采用三级树：epic（一个目标，无父级，也可作为多 epic 程序根）→ task 或 bug（一个需求或问题，叶节点）→ 子任务以任务正文中的验收标准复选框表示，而非独立 bean（CLI 拒绝任务挂在任务下）。类型取值为 task / bug / feature / idea；父级约束为：epic 无父级，feature 父级为 epic，task 父级为 epic 或 feature，task 永不能作为父级。层级由 parent 字段并由 CLI 在创建时强制校验。资料明确建议不使用 milestone 类型，需要发布分组时改用 --tag；如扁平任务确需子 bean，可用 beans update <id> -t epic 就地转换类型并保留 id 与历史。
三、状态流转 所有 bean 默认以 draft 创建，须经 triage（深度调研）后才能转为 todo；随后为 in-progress，最终 completed 或 scrapped。beans list --ready 返回 todo 与 in-progress 的 bean。triage 要求：重读原始请求、阅读相关代码与文档必要时在线检索并注明来源、拆分粒度、编写可独立验证的验收标准复选框、为编码类叶子任务列出 ## Skills for coder 技能路径、用 --blocked-by 标注阻塞，然后才 beans update <id> -s todo。资料还规定缺陷必须先文档化并 triage，不得先改代码。
四、常用命令 beans prime（会话开始加载项目 bean 状态与建议动作）、beans list --json（可加 --ready、-s draft、--no-parent、--parent、--no-status 等过滤）、beans create、beans update（支持 -s、-t、--body-replace-old/new、--body-append）、beans show（--body-only、--etag-only）。无 beans comment 子命令，审核意见通过 beans update <id> --body-append 追加带日期的段落。
五、关闭门槛 任务关闭须在正文含 ## Proof of Work，记录所运行的确切命令、观察到的结果以及 Residual 行；epic 关闭须所有子项已 completed 或 scrapped，并附端到端测试证据。缺失证据的关闭会被拒绝。资料建议为批量导入分两遍进行：先创建并记录 CLI 生成的 id，再依据 id 映射配置 --parent / --blocked-by。
六、适用场景与限制 适合在代码仓库内管理任务、缺陷、功能并从命令行操作，适合让编码智能体跟踪工作。限制包括：严格的层级与状态约束、关闭必须有验证证据、需遵守 triage 流程；资料未提供图形界面、托管服务、价格或平台兼容性等信息。