@dtt_siye/atool 1.3.0 → 1.4.0

package/skills/requirements-writer/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: requirements-writer
 description: "Guide users through writing PRDs and requirements documents with Multi-Agent architecture. 在需要撰写 PRD、需求文档、用户故事时使用。Supports Quick PRD (single feature) and Full PRD (multi-module project). Integrates with project-analyze for code-driven requirement reverse-engineering."
-version: 2.1.0
+version: 2.2.0
 category: documentation
 ---
 
@@ -413,6 +413,52 @@ Then: 系统删除用户记录，返回 204，列表刷新且不再显示该用
 
 ---
 
+## Refine Mode（精炼模式 — 由 project-analyze Phase 2.5 调用）
+
+### 触发条件
+
+Phase 2.5 通过 sub-agent prompt 内联激活，不由用户手动触发。当 `atool-analysis/modules/{name}/prd.md` 存在时自动进入。
+
+### 输入
+
+| 文件 | 用途 |
+|------|------|
+| `atool-analysis/modules/{name}/prd.md` | Phase 2 初稿（4 节结构） |
+| `atool-analysis/modules/{name}/api.md` | 接口定义 → 自动生成 AC |
+| `atool-analysis/modules/{name}/data-model.md` | 数据模型 → 填充 §4 数据需求 |
+| `.atool-docs/modules/{name}/data.json` | 结构化数据 → 提取依赖和业务术语 |
+
+### 精炼逻辑
+
+1. **保留**初稿的 §1 模块概述、§2 功能需求、§3 非功能需求、原 §4 非目标（移至 §6）
+2. **补全**缺失的 4 节：
+   - §4 数据需求：从 `data-model.md` 提取实体字段表 + 从 `api.md` 提取接口 Schema
+   - §5 跨模块依赖：从 `data.json` 的 `dependencies` 提取外部 API 契约 + 事件契约
+   - §7 风险与假设：从初稿内容推断技术风险 + 业务假设
+   - §8 需求追溯矩阵：从 §2 的 FR-ID 和 AC 自动生成 FR → US → AC 映射表
+3. **增强**已有节：
+   - §2 功能需求：补充 FR-{MOD}-NNN 编号 + Given-When-Then AC + UI 交互表（按钮行为/输入字段/四种状态）+ RBAC 矩阵
+   - §3 非功能需求：加 NFR-{MOD}-NNN 编号，标注 `[待系统级确认]`
+4. **输出**：原地覆盖 `atool-analysis/modules/{name}/prd.md`，结构与 Phase 1 MODULE PRD 模板完全一致（8 节）
+
+### 不做的事（硬性）
+
+- ❌ 不运行 Phase D（DISCOVERY）— Phase 2 已完成发现
+- ❌ 不运行 Phase 2（USER STORIES）— 精炼只到 PRD 粒度
+- ❌ 不做交互式问答 — 所有信息从 Phase 2 产物中提取
+- ❌ 不修改 README.md / api.md / data-model.md — 只精炼 prd.md
+
+### 输出质量门禁
+
+精炼后的 prd.md 必须通过以下检查（由 Phase 2.5 Gate 2 执行）：
+- 8 节结构完整（§1-§8 标题均存在）
+- FR-{MOD}-NNN 编号存在
+- 至少 1 个 Given-When-Then AC
+- NFR-{MOD}-NNN 编号存在
+- 覆盖率评分 ≥ 70%
+
+---
+
 ## 并行 Agent 规则
 
 - 每批最多 5 个 Agent 并行
@@ -432,4 +478,5 @@ Then: 系统删除用户记录，返回 204，列表刷新且不再显示该用
 | project-analyze | atool-analysis/ 存在时 | 读取分析结果作为数据源（后向增强模式） |
 | doc-standards-enforcer | 所有文档输出 | 验证格式/命名/frontmatter 合规 |
 | software-architecture | PRD 涉及架构决策 | 建议运行 /software-architecture |
+| software-architecture | NFR-{MOD}-* 不可超出 NFR-SYS-* 范围 | 读取系统级 NFR 约束（Phase 4 生成后回扫确认） |
 | code-review | PRD 完成后需要验证代码一致性 | 建议运行 /code-review |

package/skills/software-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: software-architecture
 description: Use when designing, reviewing, or scaffolding system architecture — covers architecture style selection, high-concurrency/HA design, DDD, clean architecture, microservice boundaries, and deployment strategy.
-version: 1.1.0
+version: 1.2.0
 category: architecture
 ---
 
@@ -462,6 +462,76 @@ For existing projects requiring architecture assessment:
 4. Produce ADR or architecture improvement plan
 5. Validate output with `doc-standards-enforcer`
 
+### project-analyze 数据契约（Refine Mode 输入）
+
+以下文件是 Refine Mode 的输入数据源，project-analyze 必须确保这些文件在 Phase 2.5 调用前存在：
+
+| 文件 | 内容 | 生成阶段 |
+|------|------|---------|
+| `.atool-docs/knowledge-graph.json` | 耦合度量、依赖图 | Phase 3 |
+| `.atool-docs/multi-dimensional-analysis.json` | 五维分析数据 | Phase 3 |
+| `.atool-docs/modules/*/data.json` | 模块级结构化数据 | Phase 2 |
+| `atool-analysis/modules/*/prd.md` | 精炼后的模块 PRD（含 NFR-{MOD}-NNN） | Phase 2.5 |
+| `atool-analysis/modules/*/dev-guide.md` | 精炼后的架构文档（含 ADR） | Phase 2.5 |
+
+---
+
+## Refine Mode（精炼模式 — 由 project-analyze Phase 2.5 调用）
+
+### 触发条件
+
+Phase 2.5 通过 sub-agent prompt 内联激活，不由用户手动触发。在 requirements-writer Refine Mode 完成后自动进入。
+
+### 输入
+
+| 文件 | 用途 |
+|------|------|
+| `atool-analysis/modules/{name}/README.md` | 模块业务概述 |
+| `atool-analysis/modules/{name}/prd.md` | 精炼后的标准 PRD（8 节，含 NFR-{MOD}-NNN） |
+| `atool-analysis/modules/{name}/api.md` | 接口定义 → API 契约设计 |
+| `atool-analysis/modules/{name}/data-model.md` | 数据模型 → 数据所有权 |
+| `atool-analysis/modules/{name}/dev-guide.md` | Phase 2 初稿 → 追加架构章节 |
+| `.atool-docs/modules/{name}/data.json` | 结构化数据（含 refine_hints） |
+| `{stack}-conventions` Architecture + API Design 节 | 栈级架构规范约束 |
+
+### 精炼逻辑
+
+在 `dev-guide.md` 基础上**追加**架构章节（不删除原有内容）：
+
+1. **B-subset. 组件设计**（从 Output Format B 裁剪到模块级）：
+   - 模块内部分层表（层名 / 职责 / 关键类）
+   - 边界定义（公开接口 vs 内部实现）
+   - 依赖方向约束
+
+2. **C-subset. 数据与交互设计**（从 Output Format C 裁剪到模块级）：
+   - 数据所有权声明（本模块拥有哪些实体）
+   - 同步/异步通信边界表
+   - API 契约摘要（引用 api.md）
+
+3. **ADR（架构决策记录）**：
+   - 使用 G. ADR Template 的 7 节结构
+   - 至少 1 个 ADR（该模块最关键的架构决策）
+   - Status / Context / Decision / Options / Consequences / NFR Impact / Related
+
+4. **NFR 对齐**：
+   - 确保 prd.md 中的 NFR-{MOD}-NNN 与架构选择一致
+   - 首轮标注 `[待系统级确认]`（Phase 4 生成 NFR-SYS-NNN 后回扫替换）
+
+### 不做的事（硬性）
+
+- ❌ 不生成 A（Architecture Summary）— 项目级，Phase 4 负责
+- ❌ 不生成 D（Deployment）— 项目级，Phase 4 负责
+- ❌ 不生成 E（Risk）/ F（Roadmap）— 项目级，Phase 4 负责
+- ❌ 不做交互式 6 步决策工作流 — 信息从 Phase 2 产物中提取
+- ❌ 不修改 prd.md / api.md / data-model.md — 只精炼 dev-guide.md
+
+### 输出质量门禁
+
+精炼后的 dev-guide.md 必须通过以下检查（由 Phase 2.5 Gate 3 执行）：
+- 包含"组件设计"或"Component Design"章节
+- 包含至少 1 个 ADR 条目
+- ADR 包含 Status + Decision + Consequences（7 节中最关键的 3 节）
+
 ---
 
 ## Guardrails
@@ -499,11 +569,11 @@ Do **not**:
 
 | 协作 Skill | 触发条件 | 交互方式 |
 |-----------|---------|---------|
-| **project-analyze** | 需要分析现有项目架构 | 先运行 `/project-analyze` 生成知识图谱，再用数据驱动架构评审 |
+| **project-analyze** | Phase 2.5 Refine Mode 调用；Phase 4 聚合时引用 A/E/F 模板结构 | 读取模块文档 + 知识图谱 |
 | **code-review** | 架构合规性验证 | code-review Dimension 5 验证架构合规；重大违规时建议运行本 skill 深度评审 |
 | **doc-standards-enforcer** | 产出架构文档（ADR、HLD/LLD） | 架构交付物完成后，用 `doc-standards-enforcer` 验证文档格式 |
 | **doc-coauthoring** | 协作撰写技术规格或设计文档 | 本 skill 提供技术内容准确性，`doc-coauthoring` 管理协作流程 |
 | **project-query** | 需要查询架构分析详细数据（层违反、耦合度等） | 建议运行 |
-| **requirements-writer** | Architecture NFR 需要传递到模块 PRD | 系统级 NFR（NFR-SYS-*）作为模块级 NFR 的上游约束 |
+| **requirements-writer** | NFR-SYS-* 是 NFR-{MOD}-* 的上游约束 | 系统级 NFR 约束模块级 NFR 范围 |
 | **java-conventions** | Java/Spring 项目架构设计 | 加载栈级分层/命名/并发规范 |
 | **web-conventions** | 前端项目架构设计 | 加载前端项目结构/组件规范 |