diff --git a/agents/domain.md b/agents/domain.md new file mode 100644 index 0000000..d2fe9df --- /dev/null +++ b/agents/domain.md @@ -0,0 +1,46 @@ +# Domain Docs + +各工程技能在探索代码库时,应按本文件读取本工作区的领域文档。 + +## 布局:单上下文 + +本工作区不是 monorepo(没有 pnpm-workspace / package.json workspaces),按**单上下文**处理。 + +``` +d:\cherry\ ← 工作区根 = 上下文根 +├── CONTEXT.md ← 领域术语表(尚未创建,按需惰性生成) +├── CLAUDE.md ← 工作区约定 +├── docs/ ← ring-health-docs 仓库 +│ ├── adr/ ← 架构决策记录(尚未创建,按需惰性生成) +│ └── agents/ ← 本目录:技能配置 +└── repos/ + ├── ring-health-app/ ← Android App(Kotlin + Compose) + └── ring-health-api/ ← 后端 API +``` + +注意:本工作区是**多仓库**(三个独立 git 仓库),但领域上是**单一上下文**—— +三个仓库共用同一套术语(戒指、指标、连接态…),不需要 per-context 的 `CONTEXT.md`。 + +## Before exploring, read these + +- **`CONTEXT.md`**(工作区根 `d:\cherry\CONTEXT.md`),或 +- **`CONTEXT-MAP.md`**(工作区根,如果存在):它指向每个上下文一份 `CONTEXT.md`,逐个读相关的。 +- **`docs/adr/`**(`d:\cherry\docs\adr\`):读与你即将改动的区域相关的 ADR。 + +这些文件不存在时,**静默继续**。不要指出它们缺失,也不要一上来就建议创建它们。 +`/domain-modeling` 技能(经由 `/grill-with-docs` 和 `/improve-codebase-architecture` 到达) +会在术语或决策真正定下来时惰性创建。 + +## Use the glossary's vocabulary + +当你的产出中出现领域概念(issue 标题、重构提案、假设、测试名),使用 `CONTEXT.md` 中定义的术语。 +不要漂移到术语表明确避免的同义词。 + +如果你需要的概念还不在术语表里,这本身是个信号:要么你在发明项目不用的说法(重新考虑), +要么确实存在缺口(记下来交给 `/domain-modeling`)。 + +## Flag ADR conflicts + +如果你的产出与既有 ADR 冲突,明确指出,而不是悄悄覆盖: + +> _与 ADR-0007(事件溯源订单)冲突,但值得重新讨论,因为……_ diff --git a/agents/issue-tracker.md b/agents/issue-tracker.md new file mode 100644 index 0000000..355bd17 --- /dev/null +++ b/agents/issue-tracker.md @@ -0,0 +1,38 @@ +# Issue tracker: Local Markdown + +本工作区的 issue 与 spec 以 markdown 文件形式存放。 + +**位置:工作区根目录的 `.scratch/`**(即 `d:\cherry\.scratch\`),不在各个 `repos/*` 内部。 +这样三个仓库的 issue 集中一处,不会因为切换仓库而丢失上下文。 + +## Conventions + +- 一个特性一个目录:`.scratch//` +- Spec 是 `.scratch//spec.md` +- 实施工单每个一张文件:`.scratch//issues/-.md`,从 `01` 开始编号, + **不要**写成一个合并的 tickets 文件 +- 分诊状态记录为文件靠上的 `Status:` 行(取值见 `triage-labels.md`) +- 评论与讨论历史追加到文件底部的 `## Comments` 标题下 +- `.scratch/` 不纳入版本控制;需要长期留存的结论要回写到 `docs/`(ring-health-docs 仓库) + +## When a skill says "publish to the issue tracker" + +在 `.scratch//` 下新建文件(目录不存在就创建)。 + +## When a skill says "fetch the relevant ticket" + +读取对应路径的文件。用户通常会直接给出路径或工单编号。 + +## Wayfinding operations + +供 `/wayfinder` 使用。**地图**是一份文件,每个工单是它的一个**子**文件。 + +- **Map**:`.scratch//map.md`(正文为 Notes / Decisions-so-far / Fog)。 +- **Child ticket**:`.scratch//issues/NN-.md`,从 `01` 开始编号,正文写问题。 + `Type:` 行记录工单类型(`research`/`prototype`/`grilling`/`task`); + `Status:` 行记录 `claimed`/`resolved`。 +- **Blocking**:靠上的 `Blocked by: NN, NN` 行。当它列出的每个文件都是 `resolved` 时,该工单解除阻塞。 +- **Frontier**:扫描 `.scratch//issues/`,找未关闭、未阻塞、未被认领的文件;编号最小的优先。 +- **Claim**:动手前先置 `Status: claimed` 并保存。 +- **Resolve**:在 `## Answer` 标题下追加答案,置 `Status: resolved`, + 然后把一条上下文指针(要点 + 链接)追加到 `map.md` 的 Decisions-so-far。 diff --git a/agents/triage-labels.md b/agents/triage-labels.md new file mode 100644 index 0000000..e7fbfb7 --- /dev/null +++ b/agents/triage-labels.md @@ -0,0 +1,19 @@ +# Triage Labels + +各技能用五个规范的分诊角色说话。本文件把角色映射到本工作区 issue tracker 里实际使用的字符串。 + +本工作区用的是本地 markdown tracker(见 `issue-tracker.md`),没有真正的 label 机制, +因此右列的值写进工单文件的 **`Status:` 行**。 + +| 角色(技能内用语) | 本工作区的取值 | 含义 | +| --- | --- | --- | +| `needs-triage` | `needs-triage` | 待维护者评估 | +| `needs-info` | `needs-info` | 等待报告者补充信息 | +| `ready-for-agent` | `ready-for-agent` | 已完整定义,可交给 AFK agent 执行 | +| `ready-for-human` | `ready-for-human` | 需要人来实施 | +| `wontfix` | `wontfix` | 不予处理 | + +当某个技能提到某个角色(例如「打上 AFK-ready 分诊标签」)时,取本表对应的字符串。 + +> 说明:本工作区**沿用默认取值,未做重映射**。如果你的 tracker 里已经在用别的词 +> (例如用 `bug:triage` 表示 `needs-triage`),改右列即可。