本目录是项目唯一的文档存放处。需求、设计、计划、工单、调研、指南、架构决策统一归档于此,任何 agent(无论 pi / trae / zcode / claude / codex / opencode)产出文档时都必须写入下表对应的目录,并同步更新本文件的索引。
| 目录 | 职责 | 命名规范 |
|---|---|---|
adr/ |
架构决策记录(为什么这样设计) | NNNN-slug.md,顺序编号取现有最大值 +1 |
specs/ |
设计文档 / 需求规格(做什么、为什么、怎么设计) | YYYY-MM-DD-<slug>.md |
plans/ |
实施计划 / 执行方案(怎么做、分几步) | YYYY-MM-DD-<slug>.md |
tickets/ |
工单(可执行的实施单元,按 feature 分组) | tickets/<feature-slug>/<NN>-<slug>.md,NN 从 01 起 |
research/ |
调研笔记(外部方案调研、根因排查) | YYYY-MM-DD-<slug>.md |
guides/ |
使用 / 运维指南(长期有效的 how-to) | <topic>-guide.md,kebab-case |
agents/ |
给 agent 的仓库协作约定(issue 追踪方式等) | <topic>.md,kebab-case |
约定:
<slug>用英文 kebab-case;中文标题写在文档 H1。- 同一 feature 的 spec / plan / tickets 使用相同
<slug>,便于互查。 - 日期取文档创建日(git 首次提交日),不是最后修改日。
| 场景 | 权威路径 |
|---|---|
| brainstorming / 设计文档 | docs/specs/YYYY-MM-DD-<slug>.md(覆盖全局 brainstorming skill 的 docs/superpowers/specs/) |
| writing-plans / 实施计划 | docs/plans/YYYY-MM-DD-<slug>.md(覆盖全局 writing-plans skill 的 docs/superpowers/plans/) |
| to-tickets / wayfinder 工单 | docs/tickets/<feature-slug>/<NN>-<slug>.md(repo 内 skill 副本已更新) |
| wayfinder 决策地图 | docs/plans/YYYY-MM-DD-<effort>-map.md |
| research / 调研 | docs/research/YYYY-MM-DD-<slug>.md |
| 架构决策 | docs/adr/NNNN-<slug>.md |
| 使用 / 运维指南 | docs/guides/<topic>-guide.md |
历史路径 docs/superpowers/、.scratch/、.pi/plan/、.zcode/plans/、.trae/specs/、.trae/documents/ 已退役,不要再写入。
| 文件 | 标题 |
|---|---|
| agent-provider-profiles-guide.md | 智能体供应商使用说明 |
| ai-agent-permission-approval-guide.md | AI Agent 权限审批功能实现总结与指导 |
| codex-routing-proxy-guide.md | Codex 路由代理实现指导说明 |
| computer-use-guide.md | 电脑控制使用指南（提示条、全局 Esc 急停与审批口径） |
| desktop-release-guide.md | CodeMUX 桌面端发版指南 |
| mcp-unified-management-guide.md | MCP 统一管理实现指导说明 |
| skills-unified-management-guide.md | Skills 统一管理实现指导说明 |
架构决策记录见 adr/,当前 0002–0019,格式与编号规则见 domain-modeling skill 的 ADR-FORMAT。
近期记录:
- 0011 — Daemon 权威与 Local Daemon Token
- 0012 — Daemon 独立进程与 Electron 桌面壳
- 0013 — 用户可配置键盘快捷键
- 0014 — pi 项目资源默认不信任
- 0015 — 模型能力目录只是建议，provider.models 始终是权威
- 0016 — 模型展示名来自目录，手写映射表退役
- 0017 — OpenCode 免费模型以虚拟供应商进入选择器，发送走原生 opencode provider
- 0018 — 电脑控制「正在驱动」与急停的权威移入 daemon，壳退化为显示/输入适配器
- 0019 — 电脑控制审批口径（严格/本会话/持久）与提示条 30s 空闲回收
- 0020 — 项目多根目录只经提示词声明，不启用各运行时的原生多目录能力
- 0021 —
projects.path删除，主根只存在于project_roots
| 文档 | 用途 |
|---|---|
| issue-tracker | 本仓库的 issue 追踪约定:spec 与 ticket 的落盘位置、状态与评论写法,以及 skill 提到 "publish to the issue tracker" 时的处理方式 |