用途
plan-docs 用于在代码仓库的 plans/ 目录中捕获想法、起草设计、跟踪进行中的工作。它是一套结构化、有状态的计划文件约定：每个想法或设计对应一个 plans/YYYY-MM-DD-topic.md 文件，文件头部使用 YAML frontmatter 的 status 字段，使计划的生命周期无需打开文件即可查看。约定强调 plans/ 是工作集，不是永久归档。
主要能力
- 计划文件约定：plans/YYYY-MM-DD-topic.md，一个想法或设计一个文件，frontmatter 含 status 字段。
- 配套脚本 scripts/plans.py：使用标准库，除注明外为只读，负责目录选择、以正确 frontmatter 创建文件、状态索引、锚定标签检索、晋升与删除门禁、入站引用等机械步骤。
- 计划存放路由：repo（仓库自身 plans/，随代码提交）、store（外部存储，按仓库路径镜像）、both（同时读取、写入其一）。路由由配置决定，不按会话临时判断。
- store 分层：contractor 设备（默认）下 store 分为 shareable 与 sensitive 两个 git 仓库；work 设备只有一个 store，无分层。
- 命令集：new、set-status、move、attach、graduate、archive、refs、scan、doctor、list、tags、commit、where、repos、orgs、install、config set、describe、uninstall 等。
- 所有读取类命令支持 --json。
- 内容扫描：scan 支持 --mode history、--mode staged、--mode tree，用于防止私有名称进入对外发布的仓库。
使用方式
脚本路径需在每次调用时写全，因为 shell 变量不会在 agent 的 Bash 调用之间保留。示例：
python3 ~/.agents/skills/plan-docs/scripts/plans.py list
常用命令：
python3 <path> where # 该仓库读取和写入哪些目录
python3 <path> repos --search <words> # 各仓库用途，用于按仓库路由计划
python3 <path> new <topic> --for <repo> # 属于你不在其中的某个仓库
python3 <path> new <topic> --to store # 本仓库的计划，存放在另一会话持有的树之外
python3 <path> commit <file>... -m "<msg>" # 仅提交这些计划
python3 <path> new <topic> --unscoped # 尚无仓库的想法
python3 <path> graduate <file> --to <repo> # 一旦有了仓库
python3 <path> set-status <file> planned # 若该状态的门禁失败则拒绝
python3 <path> tags --tag DEFERRED # 跨该仓库可见的所有计划锚定检索
python3 <path> move <file> --to store # 仓库切换计划存放位置
python3 <path> attach <plan> <file>... # 将证据复制到稳定位置并记录
python3 <path> refs <file> # 退役前的入站引用
python3 <path> archive --search <words> # 从 git 历史中取回已退役计划
python3 <path> scan # 确保私有名称不进入对外发布的仓库
python3 <path> orgs # 各目录属于谁，依据其自身 remote
python3 <path> install --explain # 逐项决策地设置机器
status: 和 updated: 由 set-status 输出，不应手动输入。frontmatter 只能通过 python3 <path> set-status <file> <status> 修改，因为该命令是唯一运行门禁并知道当天日期的命令。
文件参数在 set-status、move、refs、graduate 中是位置参数；在 tags、archive 中为 --file，用于缩小默认范围。
适用场景
- 在自有仓库中随代码提交计划文件。
- 在雇主或客户仓库中无法添加 plans/ 目录时，将计划存放在外部 store。
- 仓库在 repo 与 store 之间切换时使用 both 路由。
- 从 git worktree 工作时，store 镜像按仓库而非按检出共享。
- 在 contractor 设备上按敏感度分离可分享与敏感计划。
- 在 work 设备上使用单一 store，并按 remote 检查推送目标。
- 推送 shareable store 前进行内容扫描，防止客户身份信息进入发布仓库。
限制
- 不进行网络访问；推送 store 需用户自行执行，并先通过 scan。
- 脚本除注明外为只读；写入仅限自身配置（通过 install、config set、describe、uninstall）以及计划文件、store 目录与 README、attach 复制、store 提交。
- 从不在会话仓库中提交，也从不在其他仓库的工作树中写入文件；new 会拒绝并提示 --for。
- archive、list、tags、refs、doctor、scan、where 不写入任何内容。
- store 目录以 0700 创建，但之后不做检查；在共享机器上如需保护需自行 chmod 700。
- 历史重写后需删除 refs/original/ 并清理 reflog，否则 scan --mode history 会持续报告命中。
- 重写前应先复制整个目录，因为这是该约定中唯一可能丢失计划的危险操作。
- 关于是否应采用现有工具（markdown 任务跟踪器、git-bug、beads 等）的讨论见 references/prior-art-task-trackers.md；设计理由与示例见 references/design-rationale.md。
- 官方文本暂未提供。