aodw-skill 0.7.13 → 0.7.17

package/.aodw-next/02-workflow/rt-manager.md

@@ -1,24 +1,26 @@
-# RT-Manager Specification  
+# RT-Manager Specification
+
 统一请求票编排器（Request Ticket Manager）
 
-RT-Manager 是 AODW 的 Orchestration Layer 核心组件，负责：
+RT-Manager 是 AODW 的核心组件，负责：
+- RT 编号管理
+- 立项流程
+- Full / Lite（Spec-Full / Spec-Lite）流程分流
+- RT 目录和分支的创建与约束
 
-- RT 编号管理；
-- 立项（Intake）流程；
-- Full / Lite（Spec-Full / Spec-Lite）流程分流；
-- RT 目录和分支的创建与约束；
-- 全局状态机更新。
+---
 
-本文件定义 RT-Manager 的行为规范与文件结构。
+## 0. 核心原则
 
-> **🚨 关键规则**：AI 在开始任何代码工作前，**必须**先创建并切换到 feature 分支！  
-> 严禁在 `main`/`master` 分支上直接修改业务代码。
+**简洁至上**：保持简单清晰的流程，避免复杂度
+**自动化优先**：自动化可自动化的操作（RT-ID 生成、目录创建）
+**分支隔离**：每个 RT 独立工作分支，避免相互干扰
 
 ---
 
-## 0. 工作前强制检查 (Pre-Work Mandatory Check)
+## 1. 工作前强制检查
 
-**AI 在执行任何文件修改操作（`write_to_file`、`replace_file_content`）之前，必须先执行以下检查序列：**
+AI 在执行任何文件修改操作前，必须先执行以下检查序列：
 
 ### Step 1: 验证 RT 是否已创建
 - 检查 `RT/RT-XXX/` 目录是否存在
@@ -29,371 +31,98 @@ RT-Manager 是 AODW 的 Orchestration Layer 核心组件，负责：
 - ✅ 如果显示 `feature/RT-XXX-xxx`：继续工作
 - ❌ 如果显示 `main` 或 `master`：**立即停止**，提示用户并创建分支
 
-### Step 3: 创建分支（如果不存在）
-如果分支不存在，AI 必须：
-1. 建议分支名：`feature/RT-XXX-{short-name}`
-2. 创建并切换：`git checkout -b feature/RT-XXX-{short-name}`
-3. 验证切换成功：`git branch` 显示 `* feature/RT-XXX-xxx`
-4. **仅在验证通过后**才允许进行代码修改
-
-### Step 4: 暂停并通知用户（首次创建分支时）
-首次为 RT 创建分支时，AI 应暂停并告知用户：
-```
-已创建 feature 分支：feature/RT-XXX-{short-name}
-当前分支：* feature/RT-XXX-xxx ✅
-即将开始代码工作，请确认。
-```
-
-**违规处理**：如果 AI 在 main/master 分支上修改了业务代码，必须立即回滚并切换到正确的分支。
-
-**RT-ID 使用位置**：
-- 分支名：`feature/RT-XXX-short-name`
-- 提交信息：`Refs: RT-XXX`
-- 标签名：`done-RT-XXX`
+**🚨 强制规则**：AI 在开始任何代码工作前，必须先创建并切换到 feature 分支！
+严禁在 `main`/`master` 分支上直接修改业务代码。
 
 ---
 
-## 1. RT-ID 获取规则
-
-⚠️ **关键规则**：AI 在创建新 RT 时，**必须**先检查 `.aodw/config.yaml` 确定开发模式，然后按照相应规则获取 RT-ID。
-
-**详细规则请参考**：`.aodw/02-workflow/rt-id-generation-rules.md`
-
-本文件包含完整的 RT-ID 获取规则，包括：
-- 配置文件检查流程
-- 协作模式（从远程服务器获取）
-- 独立模式（本地生成）
-- 决策树和执行规范
-- 错误处理机制
-
----
+## 2. 流程状态机
 
-## 2. 目录与分支创建
-
-当用户提出新需求或问题时：
-
-1. RT-Manager 为其分配新的 RT-ID；
-2. 创建对应目录：
-
-```text
-/RT/RT-XXX/
-  meta.yaml
-  intake.md
-  decision.md
-  task.md              # 任务追踪文档（复杂任务必须）
-  docs/                    # 过程文档目录（可选，按需创建）
-  (其他文件由后续流程按需创建)
 ```
-
-**目录结构说明**：
-- **核心文档**：位于 RT 目录根目录，包括 `intake.md`、`decision.md`、`spec.md`、`plan.md` 等标准文档
-- **任务追踪文档**：`task.md` 用于复杂任务的进度追踪（详见第 8 节）
-- **过程文档目录**：`docs/` 子目录用于存放执行过程中产生的分析、调研、决策等过程文档
-
-
-3. 生成 feature 分支名建议，例如：
-
-```text
-feature/RT-XXX-{short-name}
-```
-
-其中 `{short-name}` 为 2–4 个词组成的短英文标识（例如 `user-auth-bugfix`）。
-
-AI 应：
-
-- 建议一个 `{short-name}`（简短、描述性，使用小写和连字符）；
-- 解释命名含义；
-- 根据 Profile 创建分支：
-  - **Spec-Lite**：自动创建并切换到分支（用户可在后续调整）
-  - **Spec-Full**：建议分支名，等待用户确认后创建
-- 创建分支后，必须立即切换到该分支
-- 验证当前分支：执行 `git branch`，应显示 `* feature/RT-XXX-xxx`
-
-**强制要求**：在进入 `in-progress` 状态前，必须确保已在正确的 feature 分支上。
-
----
-
-## 3. 状态机
-
-RT 的状态机定义如下：
-
-```text
 created → intaking → decided → in-progress → reviewing → done
 ```
 
-- `created`：刚创建 RT-ID，尚未进行 Intake。
-- `intaking`：AI 与用户进行互动提问，补充立项信息。
-- `decided`：Spec-Full / Spec-Lite 决策已完成，**feature 分支已创建且已切换**，基础文件已创建。
-  - 检查点：
-    - ✅ feature 分支存在：`git branch` 列表中有 `feature/RT-XXX-xxx`
-    - ✅ 已切换到该分支：`git branch` 显示 `* feature/RT-XXX-xxx`
-    - ✅ 基础文档已创建：spec/spec-lite.md, plan/plan-lite.md 等
-- `in-progress`：正在实现（包括 Spec 编写、Plan 制定、代码修改等）。
-- `reviewing`：实现完成，正在进行代码与文档审查与测试验证。
-- `done`：本 RT 正式完成（分支合并 / tag 打上 / 文档更新完毕）。
-
-RT 状态可以记录在：
-
-- 一个集中式索引文件（例如 `RT/index.yaml`），或
-- 每个 `RT-XXX` 目录中的元数据文件（如 `meta.yaml`）。
-
-具体实现可根据项目需要定制。
+RT-Manager 统一管理全局状态机更新。
 
 ---
 
-## 3.1 状态转换检查点
-
-为确保 AODW 流程的严格执行，在关键状态转换时，AI 必须进行以下检查：
-
-### decided → in-progress
-
-在从 `decided` 进入 `in-progress` 状态前，AI 必须验证以下条件：
+## 3. Intake（立项）流程
 
-1.  **强制分支创建 (Creation Node)**
-    - **操作**：必须执行 `git checkout -b feature/RT-XXX-{short-name}`。
-    - **验证**：`git branch` 显示 `* feature/RT-XXX-xxx`。
+### 3.1 触发条件
+用户表达以下意图时：
+- 新功能
+- Bug 修复
+- 需求
+- 改进
+- 重构
 
-2.  **基础文档已准备**
-    - Spec-Lite：spec-lite.md, plan-lite.md
-    - Spec-Full：spec.md, plan.md
-
-3.  **计划确认节点 (Plan Confirmation Node)**
-    - **触发时机**：Plan 文档编写完成后。
-    - **行为**：AI 必须暂停，展示 Plan 的摘要，并询问：“计划已就绪，是否批准执行？”
-    - **禁止**：严禁在未获批准前直接开始修改代码。
-
-### 持续分支检查 (Continuous Branch Check)
-
-**规则**：每次写代码前，必须检查当前分支。如在 `main`/`master` 分支，立即切换到 feature 分支。
-
-**严禁**：在 `main`/`master` 分支上修改业务代码（仅允许修改 meta.yaml 或 index.yaml 等管理文件）。
-
-### 提交前确认节点 (Pre-Commit Node)
-
-- **触发时机**：代码修改完成，准备 Git Commit 前。
-- **行为**：AI 必须展示 `git status` 和关键 `diff`，询问：“修改已完成，是否提交？”
-- **禁止**：严禁在未获用户确认前直接 Commit。
-
-**严格禁止**：在 master/main 分支上直接修改代码。所有代码修改必须在 feature 分支上进行。
+### 3.2 执行步骤
+1. 生成 RT-ID（使用本地生成或远程获取）
+2. 创建 RT 目录结构
+3. 执行交互式澄清（选项化提问）
+4. 记录立项信息到 `intake.md`
+5. 决定使用 Spec-Full 还是 Spec-Lite profile
 
 ---
 
-## 4. Intake（立项）流程
-
-当用户提出自然语言需求时，RT-Manager：
-
-1. **UI 任务识别（前置检查）**
-   - 在执行 Intake 前，必须首先判断是否为 UI 相关任务
-   - 判断标准：参考 `.aodw/01-core/ai-interaction-rules.md` 第 0 节
-   - 如果识别为 UI 任务，在后续记录中标注 `ui_related: true`
-   - 提示：此 RT 将进入 UI 专用流程（详见 `.aodw/02-workflow/ui-workflow-rules.md`）
+## 4. 流程分流决策
 
-2. 解析需求初步类型：
-   - Feature / Bug / Enhancement / Refactor / Research / Other；
-3. 提出若干澄清问题，每个问题：
-   - 提供 2–5 个选项；
-   - 对某个选项给出"推荐理由"，用户可直接接受推荐；
-   - 允许短自定义答案（≤ 5 词）；
-   - **必须停止并等待**：输出必须以提问或选项列表结束，**严禁**在同一回复中自问自答并继续执行。
-4. 在 `intake.md` 中记录：
-   - 原始描述；
-   - 问题与答案摘要；
-   - 需求类型、范围、风险等级、影响模块估计；
-   - **UI 相关标识**（如适用）：`ui_related: true`
-   - **技术约束**（如涉及前端/后端开发，标注相关编码规范，参考 `.aodw/03-standards/stacks/react-typescript/ai-coding-rules-frontend.md` 或 `.aodw/03-standards/stacks/python-fastapi/ai-coding-rules-backend.md`）。
+### 4.1 Spec-Full 适用场景
+- 跨模块影响
+- 数据模型/schema 变更
+- 外部 API/协议变更
+- 高风险或高复杂度变更
 
-Intake 完成后，将 RT 状态从 `intakeing` 更新为 `decided`（在流程决策完成后）。
+### 4.2 Spec-Lite 适用场景
+- Bug 修复
+- 单模块小改进
+- 简单 UI 或交互调整
+- 不涉及数据结构与 API 约约变更的工作
 
 ---
 
-## 5. Spec-Full vs Spec-Lite 决策
-
-RT-Manager 根据 Intake 信息进行初步判断：
-
-- 应使用 **Spec-Full** 的典型情况：
-  - 影响数据模型；
-  - 影响对外 API 或协议；
-  - 跨多个子系统或模块；
-  - 对性能、安全、合规有显著影响；
-  - 大规模重构或新功能。
+## 5. 目录结构
 
-- 应使用 **Spec-Lite** 的典型情况：
-  - 单模块 bug 修复；
-  - 小幅度行为调整或 UI 改进；
-  - 不改变数据结构或对外接口；
-  - 风险低，可快速回滚。
-
-RT-Manager 应：
-
-1. 在 `decision.md` 中记录：
-   - AI 的判断与理由；
-   - 推荐使用的 Profile（Full / Lite）；
-   - 提供备选（如用户强制 Full / Lite 的选项）；
-2. 询问用户确认：
-   - 用户可选择“使用推荐方案”或显式切换；
-3. 决策确认后：
-   - 创建 Spec-Full 或 Spec-Lite 所需的基础文件；
-   - 创建 feature 分支（或建议用户执行相应命令）。
+```
+RT/RT-XXX/
+  meta.yaml          ← RT 元数据
+  intake.md          ← 立项记录
+  decision.md        ← Profile 决策
+  spec.md            ← Spec-Full 完整需求
+  plan.md            ← Spec-Full 技术方案
+  impact.md          ← 影响分析
+  invariants.md       ← 不可破坏边界
+  tests.md           ← 验证计划
+  task.md           ← AI 任务追踪（仅 Spec-Full）
+  changelog.md        ← 变更记录
+  
+  或（Spec-Lite）：
+  rt-lite.md         ← 单文件整合所有内容
+```
 
 ---
 
-## 6. 与其他层的协作
+## 6. 分支命名与隔离策略
 
-**Execution Layer**：Profile 决定后，由 `spec-full-profile.md` 或 `spec-lite-profile.md` 接手。RT-Manager 负责更新状态、确保在正确目录和分支操作、触发完成流程。
+**分支命名**：`feature/RT-XXX-short-name`
+**工作区隔离**：每个 RT 对应一个独立的 Git worktree
 
-**Knowledge Layer**：确保每个 RT 至少有 `intake.md`、`decision.md`，流水线结束时文档完整（spec/plan/impact/invariants/tests/changelog）。详见 `.aodw/01-core/ai-knowledge-rules.md`。
+**🚨 关键规则**：一个 RT = 一个 Worktree = 一个 Feature 分支
 
 ---
 
-## 8. RT 任务追踪（Task Tracking）
-
-### 8.1 task.md 的创建时机
-
-- **Spec-Full RT**：在创建 `plan.md` 后，必须立即创建 `task.md`
-- **Spec-Lite RT**：如果 `plan-lite.md` 中任务项 > 3，必须创建 `task.md`
-- **位置**：`RT/RT-XXX/task.md`
+## 7. Profile 调用规范
 
-### 8.2 task.md 的更新规则
+AI 根据决策结果，加载对应的 Profile：
 
-- 必须与 `plan.md` 或 `plan-lite.md` 中的任务清单保持一致
-- 每完成一个阶段（Phase）后必须更新
-- 每次提交代码前必须更新
-- 状态变更时（如从 `in-progress` 到 `reviewing`）必须更新
-
-### 8.3 task.md 的内容要求
-
-- 必须包含任务状态总览（已完成/进行中/待执行）
-- 必须包含详细任务清单（与 plan 对应）
-- 必须包含当前进度说明
-- 必须包含下一步计划
+- Spec-Full → 加载 `02-workflow/spec-full-profile.md`
+- Spec-Lite → 加载 `02-workflow/spec-lite-profile.md`
 
 ---
 
-## 9. RT 元数据与全局索引（meta.yaml & RT/index.yaml）
-
-为便于 AI 与人类快速了解所有 RT 的状态与分布，AODW 定义了两层元数据：
-
-1. 每个 RT 自身的元数据文件：`RT/RT-XXX/meta.yaml`
-2. 全局 RT 索引文件：`RT/index.yaml`
-
-### 9.1 meta.yaml：单个 RT 的权威来源
-
-- 路径：`RT/RT-XXX/meta.yaml`
-- 格式：参考 `.aodw/templates/rt-meta-template.yaml`
-- 内容包括：
-  - id / title / type / profile / status
-  - modules / tool / owner
-  - created_at / updated_at / closed_at
-  - external_ids / notes
-
-规则：**meta.yaml 是本 RT 的权威来源（single source of truth）。**  
-任何关于状态、类型、模块范围等的变更，都必须首先更新 meta.yaml。
-
-### 9.2 index.yaml：全局缩影视图
-
-- 路径：`RT/index.yaml`
-- 初始结构：
-
-```yaml
-version: 1
-last_updated_at: null
-items: []
-```
-
-- `items` 为数组，每个元素为某个 RT 的摘要信息，字段是 meta.yaml 的子集：
-  - id, title, type, profile, status, modules, owner, tool, created_at, closed_at
-
-规则：**index.yaml 是基于各 RT meta.yaml 构建的汇总视图。**  
-如 meta.yaml 与 index.yaml 不一致，以 meta.yaml 为准，AI 应尝试用 meta.yaml 修正 index.yaml。
-
-### 9.3 RT-Manager 在不同阶段的职责补充
-
-RT 创建时：
-
-1. 生成 RT-ID（RT-XXX）；
-2. 创建目录 `RT/RT-XXX/`；
-3. 复制 `.aodw/templates/rt-meta-template.yaml` 为 `RT/RT-XXX/meta.yaml`：
-   - 填写：
-     - id
-     - title（从 intake 中提炼）
-     - type（初步判断结果）
-     - profile（在 Full / Lite 决策后填写）
-     - status = `created`
-     - created_at / updated_at（必须使用系统命令或 API 获取真实时间，见第 10 节）
-4. 在 `RT/index.yaml` 的 `items` 中新增一条记录，内容与 meta.yaml 对应；
-5. 更新 `RT/index.yaml.last_updated_at`（必须使用系统命令或 API 获取真实时间，见第 10 节）。
-
-RT 状态或基本属性变化时（例如：decided → in-progress → reviewing → done）：
-
-1. 更新 `RT/RT-XXX/meta.yaml` 中的：
-   - status
-   - updated_at（必须使用系统命令或 API 获取真实时间，见第 10 节）
-   - 如完成则写入 closed_at（必须使用系统命令或 API 获取真实时间，见第 10 节）
-2. 在 `RT/index.yaml.items` 中找到 id = RT-XXX 的条目，并同步修改：
-   - status / owner / modules / tool / created_at / closed_at 等必要字段；
-3. 更新 `RT/index.yaml.last_updated_at`（必须使用系统命令或 API 获取真实时间，见第 10 节）。
-
-从 Spec-Lite 升级为 Spec-Full 时：
-
-1. 在 `meta.yaml` 中将 `profile` 从 `Spec-Lite` 改为 `Spec-Full`；
-2. 在 `RT/index.yaml.items` 中同步修改该 RT 的 profile；
-3. 在本 RT 的 `changelog.md` 中记录本次 Profile 变更。
-
-RT-Manager 和所有执行 AODW 的 AI 工具，在处理任何 RT 时，  
-应优先读取 `meta.yaml` 来确定当前 RT 的基础信息。
-
----
-
-## 10. 时间字段获取规则（强制要求）
-
-⚠️ **重要**：所有时间字段必须使用系统真实时间，严禁 AI 自行推断或使用假时间。
-
-### 10.1 适用范围
-
-以下时间字段必须遵循本规则：
-- `meta.yaml` 中的 `created_at`, `updated_at`, `closed_at`
-- `RT/index.yaml` 中的 `created_at`, `closed_at`, `last_updated_at`
-- `AODW_Governance/version.md` 中的 `updated_at` 和 changelog 中的 `date`
-
-### 10.2 获取方法
-
-在创建或更新 RT 时，必须通过以下方式之一获取当前时间：
-
-**命令行方式**（推荐）：
-```bash
-# Unix/Linux/macOS
-date -u +"%Y-%m-%dT%H:%M:%SZ"  # UTC 时间
-date +"%Y-%m-%dT%H:%M:%S%z"    # 本地时间带时区
-
-# Windows PowerShell
-Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ"
-```
-
-**编程方式**：
-- Node.js: `new Date().toISOString()`
-- Python: `datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')` 或 `datetime.now().astimezone().isoformat()`
-
-### 10.3 时间格式
-
-- 格式：ISO8601 格式
-- 示例：`2025-11-28T11:54:45Z` (UTC) 或 `2025-11-28T19:54:45+08:00` (带时区)
-
-### 10.4 禁止行为
-
-❌ 禁止使用 AI 训练数据中的时间  
-❌ 禁止使用对话上下文中的时间  
-❌ 禁止自行推断或猜测时间  
-❌ 禁止使用固定的示例时间  
-❌ 禁止使用 `2024-01-01T00:00:00Z` 等占位符时间
-
-### 10.5 执行要求
-
-- 在 RT 创建时，必须通过系统命令或 API 获取 `created_at` 和 `updated_at`
-- 在 RT 状态更新时，必须通过系统命令或 API 获取 `updated_at`
-- 在 RT 完成时，必须通过系统命令或 API 获取 `closed_at`
-- 在更新 `RT/index.yaml` 时，必须通过系统命令或 API 获取 `last_updated_at`
+## 8. 集成规范
 
-AI 在执行这些操作时，应：
-1. 先执行系统命令或调用 API 获取当前时间
-2. 将获取到的时间值写入相应字段
-3. 不得跳过时间获取步骤，直接写入时间值
+与以下规范配合使用：
+- `01-core/git-discipline.md`（分支与提交规范）
+- `01-core/ai-interaction-rules.md`（交互规范）
+- `01-core/ai-knowledge-rules.md`（知识同步规范）