aodw-skill 0.7.3

package/.aodw/01-core/csf-thinking-framework.md

@@ -0,0 +1,373 @@
+# CSF 思维框架（Critical Success Factors Thinking Framework）
+
+## 1. 框架概述
+
+CSF 思维框架是一套"以终为始"的分析和决策思路，用于在 AODW 关键阶段进行战略层面的反思和审计，确保工作直接贡献于目标达成。
+
+**核心原则**：
+- 以终为始：明确目标（现状与期望的差距）
+- 结构化分解：MECE 原则，区分静态/动态分解
+- 关键要素识别：识别 CSF 和关键控制变量
+- 流程与系统观：全流程分析，端到端关键路径
+- 多维决策：多维度权重评分，矩阵分析
+
+---
+
+## 2. 在 AODW 中的集成点
+
+### 2.1 关键节点（Mandatory CSF Review）
+
+以下节点**必须**执行 CSF 审查：
+
+1. **Decision 阶段后**（decided）
+   - 审查 Profile 选择是否合理
+   - 验证目标与复杂度匹配
+
+2. **Spec/Plan 阶段后**（in-progress，Plan 批准前）
+   - 审查方案是否直接贡献于目标
+   - 验证分解是否 MECE
+   - 识别关键成功要素
+
+3. **Implementation 阶段中**（in-progress，关键里程碑）
+   - 审查实现路径是否偏离目标
+   - 验证关键控制变量
+
+4. **Verification 阶段**（reviewing）
+   - 审查端到端关键路径
+   - 验证多维决策的合理性
+
+### 2.2 可选节点（Optional CSF Review）
+
+以下节点**建议**执行 CSF 审查：
+
+- **Intake 阶段后**：验证需求理解是否准确
+- **Analysis 阶段后**：验证影响分析是否全面
+- **Completion 阶段前**：最终目标达成度评估
+
+---
+
+## 3. CSF 审查清单（CSF Review Checklist）
+
+### 3.1 以终为始检查（Begin with the End）
+
+**问题清单**：
+- [ ] 本 RT 的明确目标是什么？（用一句话描述）
+- [ ] 当前现状是什么？（问题/痛点/缺失）
+- [ ] 期望状态是什么？（成功后的状态）
+- [ ] 目标与现状的差距是否清晰？
+- [ ] 当前工作是否直接贡献于缩小这个差距？
+- [ ] 是否存在无效工作？（不贡献于目标的工作）
+
+**输出要求**：
+- 在 `RT/RT-XXX/csf-review.md` 中记录目标、现状、期望、差距
+- 识别并标记无效工作（如有）
+
+---
+
+### 3.2 结构化分解检查（Structured Decomposition）
+
+**问题清单**：
+- [ ] 复杂问题是否已分解为子目标/子模块？
+- [ ] 分解是否符合 MECE 原则（不重不漏）？
+- [ ] 是否区分了"静态分解"（组成部分）和"动态分解"（流程步骤）？
+- [ ] 分解粒度是否合适？（不过细也不过粗）
+- [ ] 子目标之间是否存在依赖关系？
+- [ ] 依赖关系是否清晰？
+
+**输出要求**：
+- 在 `csf-review.md` 中记录分解结构（树状图或列表）
+- 标注静态/动态分解类型
+- 标注依赖关系
+
+---
+
+### 3.3 关键要素识别检查（Identify CSFs）
+
+**问题清单**：
+- [ ] 影响目标达成的关键成功要素（CSF）是什么？
+- [ ] 关键控制变量是什么？（可以影响结果的变量）
+- [ ] 是否识别了瓶颈点？（限制目标达成的关键点）
+- [ ] 是否对要素进行了优先级排序？
+- [ ] 是否平均用力？（应聚焦 CSF，而非平均分配资源）
+
+**输出要求**：
+- 在 `csf-review.md` 中列出 CSF 清单（按优先级排序）
+- 标注关键控制变量
+- 标注瓶颈点
+
+---
+
+### 3.4 流程与系统观检查（Process & Systems View）
+
+**问题清单**：
+- [ ] 是否进行了全流程分析？（从触发到完成的端到端）
+- [ ] 端到端关键路径是什么？
+- [ ] 关键路径上的瓶颈是什么？
+- [ ] 是否存在单点故障？
+- [ ] 系统各组件之间的交互是否清晰？
+- [ ] 是否考虑了上下游影响？
+
+**输出要求**：
+- 在 `csf-review.md` 中绘制或描述端到端流程图
+- 标注关键路径
+- 标注瓶颈点
+- 标注潜在风险点
+
+---
+
+### 3.5 多维决策检查（Multi-dimensional Decision）
+
+**问题清单**：
+- [ ] 技术方案是否基于多维度评估？（而非非黑即白）
+- [ ] 评估维度是否全面？（如：性能、成本、复杂度、可维护性、风险等）
+- [ ] 是否进行了权重评分或矩阵分析？
+- [ ] 各维度的权重是否合理？
+- [ ] 是否有明确的决策标准？
+- [ ] 备选方案是否充分？
+
+**输出要求**：
+- 在 `csf-review.md` 中记录多维度评估矩阵
+- 标注各维度权重
+- 标注最终决策理由
+
+---
+
+## 4. CSF 审查执行流程
+
+### 4.1 触发时机
+
+**自动触发**（AI 必须执行）：
+- Decision 阶段完成后
+- Spec/Plan 阶段完成后（Plan 批准前）
+- Verification 阶段开始时
+
+**手动触发**（用户可随时要求）：
+- 用户说"执行 CSF 审查"、"做 CSF 检查"、"CSF 审计"等
+- 用户对当前方向有疑虑时
+
+### 4.2 执行步骤
+
+1. **创建/更新 CSF 审查文档**
+   - 位置：`RT/RT-XXX/csf-review.md`
+   - 如果已存在，追加新的审查记录（带时间戳）
+
+2. **按清单逐项检查**
+   - 使用上述 5 个维度的检查清单
+   - 对每个问题给出明确答案
+   - 记录发现的问题和改进建议
+
+3. **生成审查报告**
+   - 总结关键发现
+   - 标注风险点
+   - 提供改进建议
+
+4. **与用户确认**
+   - 展示审查结果摘要
+   - 询问是否需要调整方向
+   - 记录用户反馈
+
+### 4.3 输出格式
+
+CSF 审查文档应包含：
+
+```markdown
+# CSF Review: RT-XXX - <title>
+
+## 审查时间
+- 审查时间：YYYY-MM-DD HH:MM:SS
+- 审查阶段：Decision/Spec-Plan/Implementation/Verification
+- 审查人：AI + 用户（如参与）
+
+## 1. 以终为始检查
+- 目标：[一句话描述]
+- 现状：[当前状态]
+- 期望：[期望状态]
+- 差距：[差距描述]
+- 无效工作识别：[如有]
+
+## 2. 结构化分解检查
+- 分解结构：[树状图或列表]
+- MECE 验证：[是否不重不漏]
+- 静态/动态分解：[标注类型]
+- 依赖关系：[如有]
+
+## 3. 关键要素识别检查
+- CSF 清单：[按优先级排序]
+- 关键控制变量：[列出]
+- 瓶颈点：[标注]
+
+## 4. 流程与系统观检查
+- 端到端流程图：[描述或引用]
+- 关键路径：[标注]
+- 瓶颈点：[标注]
+- 潜在风险：[标注]
+
+## 5. 多维决策检查
+- 评估维度：[列出]
+- 评估矩阵：[表格]
+- 决策理由：[说明]
+
+## 关键发现
+- [ ] 发现的问题
+- [ ] 风险点
+- [ ] 改进建议
+
+## 后续行动
+- [ ] 需要调整的方向
+- [ ] 需要补充的工作
+- [ ] 需要用户确认的事项
+```
+
+---
+
+## 5. 与现有流程的集成
+
+### 5.1 与 Spec-Full Profile 的集成
+
+在 `spec-full-profile.md` 的 Plan 阶段，添加 CSF 审查要求：
+
+- Plan 完成后，必须执行 CSF 审查
+- CSF 审查通过后，才能进入"计划批准"节点
+- CSF 审查结果应记录在 `csf-review.md`，并在 `plan.md` 中引用
+
+### 5.2 与 Spec-Lite Profile 的集成
+
+在 `spec-lite-profile.md` 中：
+
+- Plan-Lite 完成后，建议执行 CSF 审查（可选但推荐）
+- 如果发现复杂度超出预期，应建议升级为 Spec-Full
+
+### 5.3 与 Verification 阶段的集成
+
+在 `verification` 阶段，CSF 审查应作为增强项：
+
+- 不仅检查文档一致性，还要检查目标达成度
+- 验证端到端关键路径是否完整
+- 评估多维决策的合理性
+
+---
+
+## 6. 快速唤起机制
+
+### 6.1 用户触发方式
+
+用户可以通过以下方式快速唤起 CSF 审查：
+
+- **自然语言**：
+  - "执行 CSF 审查"
+  - "做 CSF 检查"
+  - "CSF 审计"
+  - "检查关键成功要素"
+  - "审查目标达成度"
+
+- **命令式**（如 Cursor 等支持命令的平台）：
+  - `/csf-review`
+  - `/csf-check`
+  - `/csf-audit`
+
+### 6.2 AI 识别模式
+
+AI 应识别以下意图并自动触发 CSF 审查：
+
+- 用户表达对方向的疑虑
+- 用户要求"重新审视"、"重新评估"
+- 用户询问"这样做对吗？"、"目标是什么？"
+- 用户要求"检查关键要素"、"识别瓶颈"
+
+---
+
+## 7. 最佳实践
+
+### 7.1 审查频率
+
+- **关键节点**：必须执行（Decision、Spec/Plan、Verification）
+- **复杂 RT**：建议在 Implementation 阶段增加 1-2 次审查
+- **简单 RT**：可在关键节点执行，不必过度审查
+
+### 7.2 审查深度
+
+- **快速审查**（5-10 分钟）：
+  - 适用于简单 RT 或日常检查
+  - 重点关注"以终为始"和"关键要素识别"
+
+- **深度审查**（20-30 分钟）：
+  - 适用于复杂 RT 或关键决策点
+  - 完整执行 5 个维度的检查
+  - 生成详细的审查报告
+
+### 7.3 审查输出
+
+- CSF 审查结果应**始终记录**在 `csf-review.md`
+- 关键发现应在相关文档中引用（如 `plan.md`、`decision.md`）
+- 审查发现的问题应转化为改进行动项
+
+---
+
+## 8. 示例场景
+
+### 场景 1：Decision 阶段后的 CSF 审查
+
+**触发**：Decision 阶段完成，已选择 Spec-Full
+
+**审查重点**：
+- 以终为始：验证复杂度判断是否准确，目标是否清晰
+- 关键要素识别：识别影响目标达成的关键要素
+- 多维决策：评估 Spec-Full vs Spec-Lite 的决策是否合理
+
+**输出**：`csf-review.md` 记录审查结果，如发现判断有误，建议调整 Profile
+
+### 场景 2：Plan 批准前的 CSF 审查
+
+**触发**：Plan 文档已完成，准备进入"计划批准"节点
+
+**审查重点**：
+- 结构化分解：验证方案分解是否 MECE
+- 流程与系统观：检查端到端关键路径
+- 多维决策：评估技术方案的合理性
+
+**输出**：`csf-review.md` 记录审查结果，如发现问题，Plan 需调整后才能批准
+
+### 场景 3：Implementation 阶段中的 CSF 审查
+
+**触发**：实现过程中遇到困难，或用户要求审查
+
+**审查重点**：
+- 以终为始：验证实现是否偏离目标
+- 关键要素识别：识别当前瓶颈
+- 流程与系统观：检查实现路径是否合理
+
+**输出**：`csf-review.md` 记录审查结果，提供调整建议
+
+---
+
+## 9. 与 AODW 规范的兼容性
+
+CSF 思维框架与 AODW 核心原则完全兼容：
+
+- **简洁至上**：CSF 审查聚焦关键要素，避免过度分析
+- **深度分析**：CSF 审查基于第一性原理，深入思考
+- **事实为本**：CSF 审查以目标为基准，客观评估
+- **渐进式开发**：CSF 审查在关键节点进行，支持迭代调整
+- **中文交流**：CSF 审查文档和报告均使用中文
+
+---
+
+## 10. 实施建议
+
+### 10.1 渐进式引入
+
+1. **第一阶段**：在 Spec/Plan 阶段引入 CSF 审查（必须）
+2. **第二阶段**：在 Decision 和 Verification 阶段引入（必须）
+3. **第三阶段**：在 Implementation 阶段引入（可选，按需）
+
+### 10.2 工具支持
+
+- 创建 CSF 审查模板（`.aodw/templates/csf-review-template.md`）
+- 在平台适配器中添加 CSF 审查触发规则（如 `aodw-csf-review.md`）
+- 在相关流程文档中引用 CSF 审查要求
+
+### 10.3 培训与推广
+
+- 在 AODW 文档中说明 CSF 审查的价值和使用场景
+- 提供 CSF 审查示例
+- 鼓励用户在关键节点主动触发 CSF 审查

package/.aodw/01-core/git-discipline.md

@@ -0,0 +1,226 @@
+# Git Discipline for AODW
+
+本文件定义 AODW 工作流中必须遵守的 Git 操作规范。
+这些规则旨在确保代码历史清晰、可回溯，并便于自动化工具检查。
+
+> **重要原则**：AI **禁止**自动执行合并和推送操作。AI 应提供完整的命令脚本，由用户确认并手动执行。
+
+---
+
+## 0. AI 操作边界
+
+**AI 可以自动执行的操作：**
+- 创建 feature 分支
+- 切换分支
+- 提交代码（`git add` + `git commit`）
+- 创建标签（仅限特殊情况，如发布流程）
+
+**AI 禁止自动执行的操作：**
+- 合并分支（`git merge`）
+- 推送到远程（`git push`）
+- 删除分支（`git branch -d`）
+- 变基操作（`git rebase`）
+
+**原因**：AI 可能过早地认为任务完成，而实际需要多次迭代调整。用户应在充分验证后手动执行最终的合并和推送。
+
+---
+
+## 1. 分支命名 (Branch Naming)
+
+所有开发工作必须在 Feature 分支上进行，禁止直接在主分支（master/main）提交。
+
+### 1.1 命名格式
+```text
+feature/RT-{seq}-{short-name}
+```
+
+- **RT-{seq}**: 关联的 RT ID，必须与 `RT/` 目录下的 ID 一致（如 `RT-001`）。
+- **{short-name}**: 简短描述，使用小写英文和连字符（kebab-case），建议 2-4 个单词。
+
+### 1.2 示例
+- ✅ `feature/RT-001-login-fix`
+- ✅ `feature/RT-023-export-csv`
+- ❌ `feature/login-fix` (缺少 RT ID)
+- ❌ `RT-001/login` (格式错误)
+
+---
+
+## 2. 提交信息 (Commit Message)
+
+提交信息必须遵循 Conventional Commits 规范，并包含 RT 引用。
+
+### 2.1 格式模板
+```text
+<type>(<scope>): <subject>
+
+[optional body]
+
+Refs: <RT-ID>
+```
+
+### 2.2 字段说明
+- **type**:
+  - `feat`: 新功能
+  - `fix`: 修复 bug
+  - `docs`: 文档变更
+  - `style`: 代码格式（不影响逻辑）
+  - `refactor`: 重构（既不是新增功能也不是修改 bug）
+  - `perf`: 性能优化
+  - `test`: 增加测试
+  - `chore`: 构建过程或辅助工具的变动
+- **scope**: (可选) 影响范围，如 `auth`, `api`, `ui`。
+- **subject**: 简短描述，使用祈使句，不加句号。
+- **Refs**: (必须) 关联的 RT ID，用于链接 Git 历史与需求文档。
+
+### 2.3 示例
+```text
+fix(auth): handle token expiration gracefully
+
+Update the interceptor to refresh token on 401 error.
+
+Refs: RT-001
+```
+
+---
+
+## 3. 标签 (Tagging)
+
+当一个 RT 完成并合并到主分支后，必须打标签以标记里程碑。
+
+### 3.1 命名格式
+```text
+done-<RT-ID>
+```
+
+### 3.2 示例
+- ✅ `done-RT-001`
+- ✅ `done-RT-042`
+
+---
+
+## 4. 合并策略 (Merge Strategy)
+
+- **禁止 Fast-forward**: 合并 Feature 分支时应使用 `--no-ff`，以保留分支历史。
+- **Squash**: 对于琐碎的提交（如 "fix typo", "update"），建议在合并前进行 Squash，但保留关键的逻辑提交。
+
+---
+
+## 5. 合并前检查清单 (Pre-Merge Checklist)
+
+在合并 feature 分支到主分支前，必须完成以下检查：
+
+### 5.1 功能检查
+- [ ] 功能测试通过
+- [ ] 单元测试通过
+- [ ] 集成测试通过（如适用）
+
+### 5.2 编码规范检查（必须）
+
+> **注意**：编码规范检查是合并的硬性要求，未通过编码规范检查的代码不能合并。
+
+- [ ] **前端编码规范**（如涉及）：
+  - [ ] ESLint 检查全部通过
+  - [ ] Prettier 格式化已运行
+  - [ ] 目录结构和分层符合规范（参考 `.aodw/03-standards/stacks/react-typescript/ai-coding-rules-frontend.md`）
+  - [ ] 文件大小和复杂度符合规范（页面 ≤ 300 行，组件 ≤ 200 行，函数 ≤ 60 行，复杂度 ≤ 10）
+- [ ] **后端编码规范**（如涉及）：
+  - [ ] Ruff 检查全部通过
+  - [ ] Black 格式化已运行
+  - [ ] 分层架构符合规范（api → services → repositories，参考 `.aodw/03-standards/stacks/python-fastapi/ai-coding-rules-backend.md`）
+  - [ ] 文件大小和复杂度符合规范（模块 ≤ 300 行，函数 ≤ 60 行）
+- [ ] **通用编码规范**：
+  - [ ] 文件大小符合规范（参考 `.aodw/03-standards/ai-coding-rules-common.md`）
+  - [ ] 函数/方法长度符合规范
+  - [ ] 复杂度符合规范
+
+### 5.3 文档检查
+- [ ] 相关文档已更新（spec / plan / changelog）
+- [ ] 模块 README 已更新（如涉及）
+
+### 5.4 CI 检查
+- [ ] CI 检查全部通过
+- [ ] 代码覆盖率符合要求（如适用）
+
+---
+
+## 6. 自动化检查 (Automation)
+
+AI 或 CI 工具应检查：
+
+### Step 0: Knowledge Distillation (知识蒸馏) - **必须优先执行**
+在合并代码前，必须检查：
+1.  **模块文档更新**：本次改动是否修改了系统行为？如果是，对应的 `docs/modules/*.md` 是否已更新？
+2.  **索引一致性**：`modules-index.yaml` 是否准确反映了当前的模块结构？
+
+### Step 1: Git 规范检查
+1.  当前分支名是否符合 `feature/RT-*` 格式。
+2.  提交信息是否包含 `Refs: RT-*`。
+3.  RT 完成时是否已创建对应的 `done-*` 标签。
+
+### Step 2: 编码规范检查
+1.  前端代码（如涉及）：ESLint 和 Prettier 检查是否通过
+2.  后端代码（如涉及）：Ruff 和 Black 检查是否通过
+3.  文件大小和复杂度是否符合规范
+
+---
+
+## 7. RT 完成流程 (Completion Workflow)
+
+当 RT 的所有工作完成后，AI **必须**遵循以下流程：
+
+### Step 1: 知识蒸馏（Knowledge Distillation）
+AI 自动执行：
+1. 读取 `modules-index.yaml`，找到受影响的模块
+2. 更新对应的模块文档（`docs/modules/*.md`）
+3. 确认文档与代码一致
+
+### Step 2: 提供完成脚本
+AI **不得自动执行**，而应提供完整的手动命令脚本，例如：
+
+```bash
+# RT-XXX 完成脚本（请逐行检查后执行）
+
+# 1. 确认当前在 feature 分支
+git branch
+
+# 2. 确认所有改动已提交
+git status
+
+# 3. 切换到主分支并拉取最新代码
+git checkout main
+git pull origin main
+
+# 4. 合并 feature 分支（保留分支历史）
+git merge --no-ff feature/RT-XXX-short-name
+
+# 5. 打标签
+git tag done-RT-XXX
+
+# 6. 推送代码和标签
+git push origin main
+git push origin done-RT-XXX
+
+# 7. 删除本地 feature 分支
+git branch -d feature/RT-XXX-short-name
+
+# 8. 更新 RT 状态
+# 编辑 RT/index.yaml，将 RT-XXX 的 status 改为 done
+```
+
+### Step 3: 用户确认
+用户应：
+1. **验证代码质量**：Review 代码改动，运行测试
+2. **验证文档更新**：检查模块文档是否准确
+3. **手动执行脚本**：逐行检查并执行上述命令
+4. **验证推送结果**：确认远程仓库已更新
+
+---
+
+## 8. 紧急情况例外
+
+仅在以下特殊情况下，AI 可以自动 push（需明确用户授权）：
+- 用户明确说"直接 push"、"自动推送"等
+- 紧急 hotfix 场景（需事先约定）
+- 自动化发布流程（如 CI/CD）
+
+**默认行为**：AI 始终提供手动命令，等待用户执行。

package/.aodw/01-core/module-doc-rules.md

@@ -0,0 +1,90 @@
+1. 每个模块必须有 README
+
+新模板文件：
+.aodw/templates/module-readme-template.md
+
+内容包括：
+# <模块名称>
+
+## 1. 职责（Responsibilities）
+- 说明此模块的职责范围
+- 它解决什么问题
+
+## 2. 目录结构（Files）
+- 列出关键文件
+- 用 frontmatter mapping 连接文档与文件
+---
+module: orders
+files:
+  - apps/api/src/orders/**
+  - apps/web/src/pages/orders/**
+---
+
+## 3. 不可破坏原则（Invariants）
+- 必须遵守哪些行为
+- 不能改变的数据结构
+- API 契约
+
+## 4. 依赖关系（Dependencies）
+### 上游：
+- users
+- auth
+
+### 下游：
+- reporting
+
+## 5. 常见流程说明（Workflows）
+- 一个典型流程如何运作
+
+## 6. 历史行为（History）
+- 本模块的重大演化记录（RT 关联）
+
+
+⸻
+
+2. AI 必须维护模块的 mapping
+
+每次修改以下内容时必须更新 module README 的 frontmatter：
+	•	新增模块目录
+	•	修改模块包路径
+	•	新增关键文件
+	•	移除关键文件
+	•	API 行为修改
+	•	数据结构修改
+
+mapping 规范（写入 ai-knowledge-rules）：
+related_files:
+  - apps/api/src/orders/order_service.ts
+  - apps/api/src/orders/order_model.ts
+
+AI 必须同时在 RT 的 invariants.md 和 module README 里更新对应说明。
+
+⸻
+
+3. 模块总索引
+
+新增文件：
+.aodw/06-project/modules-index.yaml
+
+格式：
+version: 1
+
+modules:
+  - name: orders
+    path: docs/modules/orders.md
+    root: apps/api/src/orders
+  - name: payments
+    path: docs/modules/payments.md
+    root: apps/api/src/payments
+
+
+⸻
+
+4. 模块知识的优先级
+
+AI 必须：
+	•	修改代码前先查模块 README
+	•	决策 Spec-Full / Lite 时必须引用模块 invariants
+	•	改动完成后必须更新模块 README 和 modules-index.yaml
+
+⸻