@kunlv/atdc 1.0.0

package/prompts/X-diagnose.md

@@ -0,0 +1,116 @@
+---
+name: atd-diagnose
+description: >
+  Structured debugging loop for hard bugs and performance regressions.
+  Reproduce → minimise → hypothesise → instrument → fix → regression-test.
+  Use when: "debug this", "diagnose", bug report, code that keeps failing,
+  or when 3-impl TDD/C3 fails ≥2 times.
+argument-hint: "What's the bug or unexpected behavior?"
+---
+
+# prompts/X-diagnose · 结构化调试
+
+横向命令，任意时刻可触发：`/atdc:diagnose <问题描述>`
+也可由 `3-impl` 的 TDD 失败 / C3 验证失败自动切入。
+
+---
+
+## Phase 1：复现（Reproduce）
+
+**目标**：把问题变成可重复的复现步骤。
+
+1. 询问用户：bug 的具体表现？触发操作？是否 100% 复现？
+2. 如无法复现 → 分析错误堆栈 / 日志 / 监控数据
+3. 输出：**一条可执行的复现命令或操作步骤**，任何人执行都能看到相同错误
+
+```
+📋 复现步骤：
+<命令或操作序列>
+预期：<期望行为>
+实际：<错误行为>
+```
+
+---
+
+## Phase 2：最小化（Minimise）
+
+**目标**：剥离无关因素，定位最小触发条件。
+
+- 二分法注释/删除代码，逐步缩小范围
+- 替换外部依赖为 mock / fake / stub
+- 检查是否为环境差异（Node 版本、OS、配置、时区）
+- 检查是否为数据差异（特定输入值、边界数据）
+
+输出：**最小复现用例**（≤ 50 行代码 / ≤ 5 步操作）
+
+---
+
+## Phase 3：假设（Hypothesise）
+
+**目标**：基于最小用例，枚举所有可能的根因。
+
+指令：
+- 列出 ≥ 3 个可能根因，按概率排序
+- 每个假设写出「如果为真，应该看到什么现象」
+- 选出最可能的一个作为优先验证目标
+
+```
+🔬 假设列表（按概率排序）：
+1. <假设>（概率：高/中/低）
+   预测：如果为真 → <可观测现象>
+2. <假设>（概率：高/中/低）
+   预测：如果为真 → <可观测现象>
+...
+```
+
+---
+
+## Phase 4：插桩（Instrument）
+
+**目标**：用日志/断点/工具验证假设。
+
+指令：
+- 在关键路径插入 console.log / debugger / 监控埋点
+- 运行 Phase 1 的复现用例，收集输出
+- 对比输出与 Phase 3 的预测
+
+优先验证概率最高的假设；若被否定则验证下一个。
+
+---
+
+## Phase 5：修复（Fix）
+
+**目标**：确认根因后，用最小改动修复。
+
+约束：
+- 修复必须通过 Phase 1 的复现用例
+- 不得引入新依赖（除非确有必要且记录在案）
+- 如修复涉及多文件 → 先检查 blast radius
+
+---
+
+## Phase 6：回归测试（Regression-test）
+
+**目标**：确保修复不改坏现有功能。
+
+1. 为本次 bug 写回归测试（Intent: "防止 <bug描述> 再次出现"）
+2. 运行全量相关测试套件
+3. 用 `codegraph_impact` 检查受影响流程
+
+---
+
+## 硬约束
+
+- 任何 Phase 不通过 → 回到上一 Phase，最多循环 3 次
+- 3 次后仍未解决 → 输出「调试报告」：已排除假设、剩余假设、建议下一步
+- **不得跳过 Phase 2（最小化）直接写修复**
+- 不得引入 `// TODO` 或临时 workaround（除非用户明确同意）
+
+---
+
+## 衔接 3-impl
+
+当由 `3-impl` 自动切入时：
+- Phase 1 的「复现步骤」从失败的测试命令/错误输出中提取
+- 不询问用户，直接从已有信息开始
+- Phase 5 修复后自动回到 `3-impl` 的当前步骤继续

package/prompts/X-grill-with-docs.md

@@ -0,0 +1,120 @@
+---
+name: atd-grill-with-docs
+description: >
+  Grilling session that challenges your plan against existing domain model,
+  sharpens terminology, and updates CONTEXT.md + ADRs inline as decisions
+  crystallise. Use when user wants to stress-test a plan, build shared
+  language with AI, or after 1-spec/2-qa when there are decisions to persist.
+argument-hint: "What plan or proposal do you want to grill?"
+---
+
+# prompts/X-grill-with-docs · 深度拷问 + 文档沉淀
+
+横向命令：`/atdc:grill-with-docs [<change-name>]`
+也由 `1-spec Phase 3` 和 `2-qa Step 6` 自动建议触发。
+
+与 `2-qa` 的区别：2-qa 重在找漏洞，grill-with-docs 重在**建立共享语言并持久化**。
+
+---
+
+## Step 0：前置检查
+
+```bash
+# 确认 CONTEXT.md 存在
+cat CONTEXT.md 2>/dev/null || echo "[CONTEXT.md 不存在，将创建]"
+
+# 确认 docs/adr/ 目录
+ls docs/adr/ 2>/dev/null || echo "[docs/adr/ 不存在，将创建]"
+
+# 确认当前 change（如有）
+ls openspec/changes/ 2>/dev/null | grep -v archive
+```
+
+无 CONTEXT.md → 先用 `X-context-scan` 生成基础版本再继续。
+无 docs/adr/ → 创建目录。
+
+---
+
+## Step 1：读取当前领域知识
+
+从 CONTEXT.md 提取并内化：
+
+```bash
+grep -E "^## |^- " CONTEXT.md 2>/dev/null
+```
+
+重点关注：
+- **领域词汇表**：现有术语定义
+- **模块边界**：哪些模块负责什么
+- **已知约束**：性能/兼容性/依赖限制
+- **ADR 摘要**：已有架构决策
+
+---
+
+## Step 2：对照拷问
+
+按以下维度逐条拷问，每次一条，等用户回答：
+
+### 2a. 术语一致性
+- 方案中使用的术语是否与 CONTEXT.md 一致？
+- 是否有歧义术语需要精确定义？
+- 示例：方案说「订单状态变更」→ CONTEXT.md 定义的状态机是否覆盖？
+
+### 2b. 模块边界
+- 方案涉及的功能是否落在正确的模块边界内？
+- 是否有跨边界操作（模块 A 直接操作模块 B 的内部数据）？
+- 是否需要新增模块 / 拆分现有模块？
+
+### 2c. 与已有架构决策的一致性
+- 方案是否违反现有 ADR？
+- 如果是 → 是需要推翻旧决策（生成新 ADR），还是需要调整方案？
+
+### 2d. 隐性约束
+- 方案是否依赖了某些未在 CONTEXT.md 中声明的假设？
+- 这些假设是否应该记录为约束？
+
+---
+
+## Step 3：更新 CONTEXT.md
+
+拷问过程中发现的术语澄清和约束，实时追加到 CONTEXT.md：
+
+- **术语澄清** → 追加到「领域词汇表」段
+- **模块边界调整** → 更新「模块结构」段
+- **新约束** → 追加到「已知约束」段
+- **隐性假设揭示** → 追加到「关键假设」段
+
+---
+
+## Step 4：生成 ADR（重大决策时）
+
+以下情况生成 `docs/adr/<序号>-<标题>.md`：
+
+| 触发条件 | 示例 |
+|---------|------|
+| 推翻了已有 ADR | ADR-003 选择了 Redis，本次改为本地缓存 |
+| 在多个可行方案中做了取舍 | A 方案 vs B 方案，选 A 因为... |
+| 引入了新的技术依赖 | 引入消息队列处理异步任务 |
+| 改变了核心领域模型 | 将「用户」和「账户」拆分为两个聚合 |
+
+ADR 格式参考 `templates/adr.md`。
+
+---
+
+## Step 5：输出总结
+
+```
+🔍 Grill-with-Docs 完成 — <change-name 或 主题>
+
+### 术语澄清（已更新 CONTEXT.md）
+- <术语>：<精确定义>
+
+### 架构决策（已生成 ADR）
+- docs/adr/<序号>-<标题>.md
+
+### 模块边界调整
+- <调整内容>
+
+### 未解决项
+- <拷问中未能闭环的问题>
+```

package/prompts/X-handoff.md

@@ -0,0 +1,80 @@
+---
+name: atd-handoff
+description: >
+  Compact the current conversation or change context into a handoff document
+  for another agent or human to pick up. Use when user wants to hand off
+  work, or after archiving a change (5-done Step 3.5).
+argument-hint: "Which change or topic should the handoff cover?"
+---
+
+# prompts/X-handoff · 会话交接
+
+横向命令：`/atdc:handoff [<change-name>]`
+也由 `5-done Step 3.5` 自动建议触发。
+
+---
+
+## Step 1：确认交接范围
+
+- 指定了 change-name → 从 `openspec/changes/archive/<name>/` 或 `openspec/changes/<name>/` 读取
+- 未指定 → 从当前会话上下文提取（当前讨论的功能/bug/决策）
+
+---
+
+## Step 2：收集交接信息
+
+```bash
+# 从 change 目录提取
+grep -E "^## |^- " openspec/changes/<name>/proposal.md 2>/dev/null
+grep -E "^## |^- " openspec/changes/<name>/design.md 2>/dev/null
+
+# 从 memory 提取相关条目
+_PROJ=$(basename "$(git worktree list 2>/dev/null | head -1 | awk '{print $1}')" 2>/dev/null || basename "$PWD")
+grep "<change-name>" ~/.atdc/memory/$_PROJ/.memory.md 2>/dev/null
+```
+
+---
+
+## Step 3：生成交接文档
+
+按 `templates/handoff.md` 格式生成 `.handoffs/<change-name>.md`：
+
+> `.handoffs/` 通过 `~/atdc/central/link.sh` 自动软链到主仓库，所有分支+worktree 共享，不入 git。
+
+### 必须包含
+
+- **做了什么**：Why + What，一句话说清动机和结果（不要 How）
+- **关键决策**：选了哪个方案，排除了什么，为什么
+- **受影响模块**：变更涉及的文件和模块清单
+- **未解决问题**：暴露但未修复的技术债、待验证的假设
+- **下一步**：接手的人/Agent 应该从哪里开始
+
+### 可选包含
+
+- **测试状态**：哪些已覆盖，哪些有缺口
+- **回滚风险**：如果出问题，回滚的步骤和风险
+- **相关资源**：ADR 引用、监控面板、相关 Issue
+
+---
+
+## Step 4：输出
+
+```
+📋 交接文档已生成：.handoffs/<change-name>.md
+
+内容摘要：
+- 做了什么：<一句话>
+- 关键决策（<N> 条）：<第一条摘要>
+- 受影响模块：<N> 个
+- 未解决问题：<N> 个
+
+💡 下一次会话开始时，Agent 可读取此文件快速恢复上下文。
+```
+
+---
+
+## 衔接 5-done
+
+当由 `5-done Step 3.5` 触发时：
+- 范围自动确定为当前归档的 change
+- 生成完毕后回到 5-done Step 4 继续

package/prompts/X-health.md

@@ -0,0 +1,78 @@
+# prompts/X-health · 项目健康巡检
+
+横向命令，任意时刻可触发：`@atdc/GO.md health`
+
+---
+
+## 检查项
+
+### 1. 活跃 change 状态
+
+```bash
+ls openspec/changes/ | grep -v archive
+```
+
+每个活跃 change 检查：
+- 是否有 `.progress.json`（有无断点）
+- proposal.md / design.md / tasks.md 是否齐全
+- 最后更新时间（超过 7 天未动的标记为"僵尸 change"）
+
+### 2. 记忆文件健康
+
+```bash
+_PROJ=$(basename "$(git worktree list 2>/dev/null | head -1 | awk '{print $1}')" 2>/dev/null || basename "$PWD")
+grep -c "^## " ~/.atdc/memory/$_PROJ/.memory.md 2>/dev/null || echo 0
+```
+
+- 条目数超过 20 → 提示需要裁剪
+- 文件不存在 → 提示首次建立
+
+### 3. 野代码检测
+
+```bash
+git diff --name-only main HEAD 2>/dev/null || git diff --name-only master HEAD 2>/dev/null
+```
+
+对比当前变更文件 vs 所有活跃 change 的追溯矩阵，识别无主变更。
+
+### 4. spec 覆盖率
+
+检查 `openspec/specs/` 主目录下是否有孤立模块（有 spec 但无对应 change 或代码）。
+
+### 5. 图引擎健康
+
+```bash
+# CRG（code-review-graph）状态
+~/.claude/scripts/link-crg.sh 2>/dev/null || true
+ls .code-review-graph/graph.db 2>/dev/null && echo "✓ CRG 图存在" || echo "⚠️  CRG 未初始化"
+
+# CodeGraph 状态
+ls .codegraph/ 2>/dev/null && echo "✓ CodeGraph 已索引" || echo "⚠️  CodeGraph 未初始化（运行 codegraph init -i）"
+```
+
+如 CRG 图不存在或为空，提示：
+```
+build_or_update_graph_tool(full_rebuild=true)
+```
+
+---
+
+## 输出报告
+
+```
+🏥 项目健康报告 — <项目名> — <日期>
+
+活跃 change：
+  ✅ <name>  进行中（Task N/M）
+  ⚠️  <name>  僵尸（超过 7 天未更新）
+
+记忆文件：N 条（<正常/建议裁剪>）
+
+野代码：<文件列表 / 无>
+
+图引擎：
+  CRG：<N 节点 / M 边 / 未初始化>
+  CodeGraph：<已索引 / 未初始化>
+
+建议下一步：<具体操作>
+```

package/prompts/X-learn.md

@@ -0,0 +1,151 @@
+# prompts/X-learn · self-learning → atd 桥接
+
+横向命令，手动触发或由其他阶段自动调用。
+
+---
+
+## 🔴 Step -1：规则加载
+
+```
+Read @atdc/reference/learn.md → self-learning → atd 桥接协议（promotion rule + triage 路由）
+```
+
+> 核心协议见 `@atdc/reference/learn.md`
+
+---
+
+## Phase 0：判断触发模式
+
+- **无参数 / 手动触发** → Phase 1（扫描当前 session 的 golden path）
+- **`--auto`（由 4-verify / 5-done 自动调用）** → Phase 2（静默检测 + 自动路由）
+
+---
+
+## Phase 1：手动扫描当前 session
+
+回顾当前对话历史，识别值得沉淀的路径：
+
+1. **搜索信号**：
+   - 重试了 2 次以上的操作
+   - 用户纠正过的错误
+   - 非显而易见的命令/配置
+   - 刚发现的 project-specific fact（DB 连接方式、部署命令等）
+2. **列出候选**：最多 3 条，每条一句话描述
+3. **交互确认**：让用户选择要沉淀哪条，跳过哪些
+
+输出格式：
+```
+🔍 检测到以下 golden path 候选：
+
+1. <路径描述>（重试了 N 次，排除过 M 个方案）
+2. <路径描述>
+
+选择：输入编号沉淀，或 "all" 全部，"skip" 跳过。
+```
+
+确认后进入 Phase 3。
+
+---
+
+## Phase 2：静默自动检测
+
+由 4-verify.md / 5-done.md 调用时，不交互，直接检测：
+
+1. 检查当前 change 的 `.progress.json`，看 `failedAt` / `failedReason` 是否有记录
+2. 检查本次 session 是否涉及超过 2 次尝试的操作
+3. 如有 → 按 promotion rule 判断是否可晋升
+4. 满足 → 自动路由（不询问）；不满足 → 写 memory note
+
+### 2a. Triage 路由
+
+```
+检测到候选 → 判断类型
+  │
+  ├─ 单事实 / 一行纠正
+  │   └─→ 追加到 .memory.md（⚠️ gotcha）
+  │
+  ├─ 失败模式 + 死路（满足 .errors-log 条件）
+  │   └─→ 追加到 .errors-log.md
+  │       + .memory.md 加交叉引用简记
+  │
+  └─ 满足 promotion rule 3 条
+      └─→ 进入 Phase 3（生成 atd 命令）
+```
+
+---
+
+## Phase 3：生成 atd 命令
+
+当满足 promotion rule 全 3 条时：
+
+### 3a. 确定命令名
+
+从路径描述中提取 kebab-case 名称，格式：`learn-<domain>-<action>`
+例：`learn-db-connect`、`learn-deploy-staging`、`learn-kugo-sign`
+
+### 3b. Dedup
+
+检查是否已有同名或相似命令：
+```bash
+ls ~/atdc/commands/opencode/atd/ | grep -i "<keyword>"
+```
+
+已有 → 更新现有 prompt（追加 "What didn't work" section）
+没有 → 新建
+
+### 3c. 调用 add-command.py
+
+```bash
+python3 ~/atdc/bin/add-command.py <name> \
+  "<描述>" \
+  "learn-<name>、记住<name>、<name>怎么搞" \
+  --from-learn \
+  --failure "<named failure pattern>" \
+  --dead-end "<ruled-out approach>"
+```
+
+`--from-learn` flag 会让 add-command.py 使用 `templates/learn-skill.md` 模板，
+自动填充 "What didn't work" 和 "失败模式" section。
+
+### 3d. 写记忆
+
+```bash
+# 写入 .memory.md（🧠 learned-skill 类型）
+# 写入 .errors-log.md（如果涉及失败模式）
+```
+
+### 3e. 输出结果
+
+```
+✅ 已从本次 session 沉淀 skill
+
+新命令：/atdc:<name>
+触发词：learn-<name>、记住<name>
+提示词：prompts/X-<name>.md
+
+记忆写入：~/.atdc/memory/<项目>/.memory.md
+失败记录：~/.atdc/memory/<项目>/.errors-log.md（如有）
+
+下次 session 启动时，Agent 可通过触发词直接调用此 skill。
+```
+
+---
+
+## Phase 4：仅写记忆（不晋升 skill）
+
+不满足 promotion rule 时的降级处理：
+
+```bash
+_PROJ=$(basename "$(git worktree list 2>/dev/null | head -1 | awk '{print $1}')" 2>/dev/null || basename "$PWD")
+MEMORY_DIR="$HOME/.atdc/memory/$_PROJ"
+mkdir -p "$MEMORY_DIR"
+cat >> "$MEMORY_DIR/.memory.md" << EOF
+
+## ⚠️ [$(date +%Y-%m-%d)] <简短描述>  | ~100t
+done: <一句话>
+gotcha: <发现的坑 / 非显而易见的点>
+note: <未晋升原因：缺少 passing check / 缺少命名失败模式 / 缺少排除死路>
+EOF
+```
+
+未晋升原因记录在 `note:` 字段，供后续 `/atd compound` 扫描时提示用户补充验证后晋升。