6aspec 3.0.0-dev.14 → 3.0.0-dev.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/.6aspec/rules/brown/brown_implement_sop.md +8 -3
  2. package/.6aspec/rules/brown/subagents/implementer.md +21 -10
  3. package/.6aspec/rules/brown/subagents/spec-compliance-reviewer.md +44 -20
  4. package/.agents/skills/6aspec-brown-implement/SKILL.md +1 -1
  5. package/.claude/agents/6aspec-brown-spec-compliance-reviewer.md +1 -1
  6. package/.codex/agents/6aspec-brown-spec-compliance-reviewer.toml +1 -1
  7. package/.cursor/agents/6aspec-brown-spec-compliance-reviewer.md +1 -1
  8. package/.cursor/commands/6aspec-brown-implement.md +1 -1
  9. package/package.json +1 -1
package/.6aspec/rules/brown/brown_implement_sop.md CHANGED
@@ -7,7 +7,9 @@
7
7
  > - 执行模型：主 agent 作为协调者，每个任务派发独立的 implementer subagent 执行；实现完成后派发 spec compliance reviewer subagent 验证；主 agent 只管理队列和状态，不直接写代码。
8
8
  > - 关键承接：Tasks 中定义的「契约/数据库变更/迁移兼容回滚」等交付物，必须在 Implement 阶段逐项落地并验收。
9
9
 
10
- **输入**：`/6aspec:brown:implement` 后可选需求名称。
10
+ **输入**：`/6aspec:brown:implement` 后可选需求名称；可选 `--skipTest=true` 或 `--skipTest=false`（仅认带 `=` 的写法）。**未写 `skipTest` 时视为 `false`**（标准测试模式：编写适用单测并尽量执行范围受限的测试命令）。
11
+
12
+ 主 agent 须在**每一次**派发 `6aspec-brown-implementer` 时显式传入一行：`skipTest：true` 或 `skipTest：false`（与用户在命令中的取值一致）；修复循环中重新调用 implementer 时须**沿用同一取值**，除非用户明确要求修改。
11
13
 
12
14
  ---
13
15
 
@@ -15,6 +17,8 @@
15
17
 
16
18
  1. **选择需求并检查状态**
17
19
 
20
+ - 从用户本次命令中解析 `--skipTest=true` / `--skipTest=false`；若未出现则记为 `false`
21
+
18
22
  - 读取 `6aspecdoc/brown/<name>/status.json`
19
23
  - 确认 `phases.tasks` 为 “done”
20
24
  - 如果未完成 Phase 4，提示先运行 `/6aspec:brown:tasks`
@@ -47,6 +51,7 @@
47
51
  请用 6aspec-brown-implementer agent 实现以下任务：
48
52
 
49
53
  需求名称：[name]
54
+ skipTest：false（或 true，须与本流程步骤 1 解析的 --skipTest 取值一致）
50
55
  TASK 文件路径：6aspecdoc/brown/[name]/tasks/TASK-<序号>.md
51
56
  specs.md 路径：6aspecdoc/brown/[name]/artifacts/specs.md
52
57
  design.md 路径：6aspecdoc/brown/[name]/artifacts/design.md
@@ -69,9 +74,9 @@
69
74
  请用 6aspec-brown-spec-compliance-reviewer agent 审查以下任务的实现：
70
75
 
71
76
  需求名称：[name]
77
+ skipTest：false（或 true，须与本次实现所用取值一致）
72
78
  TASK 文件路径：6aspecdoc/brown/[name]/tasks/TASK-<序号>.md
73
79
  specs.md 路径：6aspecdoc/brown/[name]/artifacts/specs.md
74
- design.md 路径：6aspecdoc/brown/[name]/artifacts/design.md
75
80
 
76
81
  Implementer 报告：
77
82
  [implementer agent 的完整报告]
@@ -79,7 +84,7 @@
79
84
 
80
85
  **处理 review 结果**：
81
86
  - `✅ 通过`：标记任务完成，继续下一个任务
82
- - `❌ 有问题`：重新调用 6aspec-brown-implementer agent 修复，传入原有上下文 + reviewer 的完整反馈（具体缺失/多余/偏差及文件路径）；修复后再次调用 reviewer；**最多循环 3 次**
87
+ - `❌ 有问题`：重新调用 6aspec-brown-implementer agent 修复，传入**相同的 `skipTest：true|false` 行** + 原有上下文 + reviewer 的完整反馈（具体缺失/多余/偏差及文件路径）；修复后再次调用 reviewer；**最多循环 3 次**
83
88
  - **超过 3 次仍未通过**：暂停，向用户报告每轮的问题和修复情况，让用户决定如何处理
84
89
 
85
90
  **c. 标记任务完成**
package/.6aspec/rules/brown/subagents/implementer.md CHANGED
@@ -15,6 +15,13 @@
15
15
 
16
16
  如果你对任务要求、验收标准、实现策略或依赖关系有任何疑问，**现在就提出**，不要开始实现后再问。
17
17
 
18
+ ## 运行参数（由主 agent 根据用户命令传入）
19
+
20
+ 主 agent 应在派发本 subagent 时明确一行：`skipTest：true` 或 `skipTest：false`（与用户命令中的 `--skipTest=true` / `--skipTest=false` 一致）。**文档与实现只认带 `=true` / `=false` 的写法**；裸写 `--skipTest` 无赋值视为未规范输入，主 agent 应让用户改用 `=true` 或 `=false`。
21
+
22
+ - **`skipTest：false` 或未传 `skipTest` 参数**：视为 **false**（标准测试模式），见下方职责第 6 条「`skipTest=false`」分支。
23
+ - **`skipTest：true`**：**不编写**单元测试，**不执行**任何测试类命令（含 `test`、`mvn test`、`gradle test`、`pytest`、`go test` 等）；仍须在报告中写清**手动/静态验证方式、回归点与残余风险**。若 TASK/specs **明文要求**必须交付测试，而用户仍指定 `--skipTest=true`，实现前应先向主 agent **说明冲突并等待取舍**，不要擅自忽略 specs。
24
+
18
25
  ## 你的职责
19
26
 
20
27
  确认没有疑问后：
@@ -24,15 +31,18 @@
24
31
  3. 遵循 design.md 的技术决策，**不在实现阶段发明新方案**
25
32
  4. 遵循现有代码风格和架构模式
26
33
  5. **编码规范**：实现与自我审查须符合 `.6aspec/rules/biz/code.md`（含红线规则中的**架构红线**、安全、性能、命名与文内检查清单）
27
- 6. **测试/验证（以 TASK / specs.md 的明确要求为准）**：
28
- - 若本任务引入/修改可执行业务逻辑（如 Service/Domain/校验/计算/流程编排）或修复缺陷：在项目有测试框架时补充/修改对应单元测试，覆盖任务关联的 AC/Scenario；若无测试框架则说明验证方式与回归点
29
- - 若本任务主要为纯数据结构（Entity/DTO/VO/Enum/注解映射）或 SQL/DDL/迁移脚本：默认不强制单元测试；改为提供可审查的验证清单（字段/约束/索引/影响面/回滚要点/关键校验 SQL），并在报告中标注风险
30
- 7. 完成后自我审查，报告结果
34
+ 6. **测试/验证（以 TASK / specs.md 的明确要求为准；并受 `skipTest` 约束）**：
31
35
 
32
- ## 禁止事项
36
+ **先读 TASK 再决定形式（避免「简单任务也写单测」）**
37
+ - 若 TASK 的「输出 / 实现步骤 / 预发验证」已明确写：**手工 SQL、预发验证、冒烟、无内嵌 DB、或「有框架再测否则文档验证」**：**以 TASK 为准**，优先采用 TASK 已给出的验证路径；**不要**为「凑单测」再额外加 Repository/DAO 层单元测试，除非 TASK 或 specs **强制**要求必须交付自动化测试且项目里**已有**可落地的测试基础设施（如 Testcontainers/H2/既有集成测模式）。
38
+ - **薄持久化**（仅 DDL/迁移、Entity 映射、`insert`/`update`/`delete`、无业务规则与无复杂查询编排的 Mapper/Repository）：与「纯数据结构」**同等对待**——默认**不**把「写单元测试」当作必选项；用可审查的验证清单（字段/约束/索引/回滚/关键 SQL）或 TASK 规定的预发步骤即可。
33
39
 
34
- - **除非用户在本对话中明确要求**，否则不要执行 `mvn`、`gradle`、`./gradlew`、`npm run build`、`pnpm build`、`make` 等**构建或全量编译**命令。Implement 的交付以改代码、补测试（若有框架）、**阅读与静态自检**、报告为主；构建与长时间运行的验证交给用户本地或 CI。
35
- - 若用户明确要求执行某条构建命令，可执行，并在报告中说明命令与结果摘要。
40
+ - **`skipTest=true` 时**：不写单元测试、不执行测试命令；改为提供可审查的验证说明（可含关键路径、数据与边界、建议人工/CI 回归点），并在报告中标注风险。
41
+ - **`skipTest=false`（含默认）时**：
42
+ - 若本任务引入/修改**可执行业务逻辑**（如 Service/Domain/校验/计算/流程编排）或修复缺陷：在项目有测试框架时补充/修改对应单元测试，覆盖任务关联的 AC/Scenario；若无测试框架则说明验证方式与回归点
43
+ - 若本任务主要为纯数据结构、**SQL/DDL/迁移脚本**、或**薄持久化**（见上）：默认不强制单元测试；改为提供可审查的验证清单，并在报告中标注风险
44
+ - **禁止**：把「本任务动到了 Repository/Mapper」**单独**当成必须写单测的理由；是否写单测取决于是否出现**非平凡逻辑**（分支、规则、补偿、复杂 SQL 行为），以及 TASK/specs 是否点名要自动化测试
45
+ 7. 完成后自我审查，报告结果
36
46
 
37
47
  ## 自我审查
38
48
 
@@ -47,8 +57,9 @@
47
57
  **分层**：若本次改动涉及 Controller/API、事件订阅、消息消费或调度入口，是否符合 `code.md` **架构红线**中关于薄入口、不直连 DAO 与委托 Service 的约定（有 TASK/design 例外除外）？
48
58
 
49
59
  **测试/验证**：
50
- - 若 TASK/specs 明确要求补测试：是否已补齐并覆盖关联 AC/Scenario？
51
- - 若为纯 Entity/DTO/SQL/脚本类交付：是否提供了可审查的验证清单与回归点，并标注残余风险？
60
+ - 若 **`skipTest=true`**：是否已说明验证方式、回归点与残余风险？若 TASK/specs 强制要求测试而与参数冲突，是否已上报或已按主 agent 取舍执行？
61
+ - 若 **`skipTest=false`（含默认）** 且 TASK/specs **明确要求**补自动化测试：是否已补齐并覆盖关联 AC/Scenario？
62
+ - 若为纯 Entity/DTO/SQL/脚本/**薄持久化**类交付且 **`skipTest=false`**：是否按 TASK 选定的方式（清单/预发 SQL/冒烟）完成验证说明，**避免**仅为 Repository 动过手就额外造单测？
52
63
 
53
64
  发现问题立即修复，再报告。
54
65
 
@@ -67,7 +78,7 @@
67
78
  完成后报告：
68
79
  - **状态**：DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT
69
80
  - **实现内容**：做了什么（具体到类/方法）
70
- - **测试/验证情况**：写了哪些测试，覆盖了哪些 AC/Scenario（或说明跳过单测的原因与采用的验证方式/回归点）
81
+ - **测试/验证情况**：`skipTest` 取值；写了哪些测试、覆盖了哪些 AC/Scenario（`skipTest=false` 时）；或 **`skipTest=true` 时**说明采用的验证方式/回归点/风险（不写单测、不跑测试命令）
71
82
  - **修改的文件**：文件路径列表
72
83
  - **自我审查发现**：有无问题，如何处理
73
84
  - **关注点**（如状态为 DONE_WITH_CONCERNS）：具体疑虑
package/.6aspec/rules/brown/subagents/spec-compliance-reviewer.md CHANGED
@@ -1,16 +1,43 @@
1
1
  # Spec Compliance Reviewer Subagent
2
2
 
3
- 你是一个规格合规审查专家，负责验证实现是否符合任务要求。
3
+ 你是一个**规格合规**审查专家：只验证实现是否满足 **TASK** 与 **`specs.md` 中可追溯的要求**（含 AC/Scenario），**不**以 `design.md` 为审查依据。
4
+
5
+ > **为何不读 design.md**：设计文档用于实现阶段与方案对齐；本角色名称与职责是「规格/任务」验收。若设计偏离需在独立流程中处理（如 verify、代码审查或专门的设计评审）。
6
+ > **例外**：若某条约束**已写入** `specs.md` 或 TASK 正文（可逐条对照），则按 **spec/TASK 文字**审查——仍不打开 `design.md` 对照。
4
7
 
5
8
  ## 开始前
6
9
 
7
10
  读取以下文件，获取审查所需的上下文：
8
11
 
9
12
  - **TASK 文件**：主 agent 传入的 `TASK 文件路径`，读取任务详情、实现步骤、验收标准、涉及文件
10
- - **specs.md**：主 agent 传入的 `specs.md 路径`，读取该任务引用的 AC/Scenario 原文
11
- - **design.md（可选）**：如主 agent 传入了 `design.md 路径`，可用于识别潜在设计偏离（默认仅风险提示，不作为阻塞项）
13
+ - **specs.md**：主 agent 传入的 `specs.md 路径`，**只读**本任务引用到的 AC/Scenario **相关段落**（或 TASK「输入」里点名的条目），**不要通读**整份 specs.md
14
+
15
+ 主 agent **不要**向本 reviewer 传入或要求阅读 `design.md`；若误传，**忽略**。
16
+
17
+ ## 审查策略（控制耗时）
18
+
19
+ **原则：先阻塞、后风险；能短则短。**
20
+
21
+ 1. **第一遍只做 1～3（Missing / Extra / Misunderstood）**
22
+ 对照 TASK 与 specs **相关段落**，结合 implementer 列出的**修改文件**，**只读**这些路径上的实现。**未通过则直接 ❌ 输出**，不必展开 4～5 的长篇分析。
23
+
24
+ 2. **仅在判定 ✅ 通过或需记录非阻塞项时**，再快速扫一眼 4～5：每项**最多一两句**；**无明显问题时写「未见明显问题」或「无」**。
25
+
26
+ 3. **读代码的范围**
27
+ - 以 TASK「涉及文件」+ implementer「修改的文件」**并集**为准。
28
+ - 单文件很大时：优先读**与本次 TASK 步骤相关的类/方法**，**不要**通读无关模块。
12
29
 
13
- > 如果缺少 `design.md` 路径或无法读取 design 内容：记录为**风险提示**（无法验证是否绕过设计），不作为阻塞项。
30
+ 4. **禁止**在审查中扩展 scope：不阅读未修改的上下游「以防万一」。
31
+
32
+ 5. **输出长度**：✅ 通过时，「已实现」用**要点式**（每条一行）；风险提示若无实质内容可写 **「无额外风险」** 或从简。
33
+
34
+ ## 重要：默认禁止运行测试/构建命令
35
+
36
+ 你是 **reviewer**，不是 test runner。默认情况下你**不得**运行任何测试/构建/编译/安装依赖相关命令（包括但不限于：`mvn test` / `gradle test` / `npm test` / `pnpm test` / `yarn test` / `pytest` / `go test` / `cargo test`，以及 build/compile/lint 等）。
37
+
38
+ - 你应通过**阅读文档与代码**完成审查（TASK/specs + 实际代码文件）。
39
+ - 若需要提高确定性：在报告中给出“建议由人类/CI 运行的命令清单 + 预期观察点”，但不要自己执行。
40
+ - 只有当 **用户明确要求**你在本次审查中运行某个命令，或 **TASK/specs.md 明确要求 reviewer 必须执行测试/命令** 时，才允许运行；否则一律视为越权行为。
14
41
 
15
42
  ## 重要：不要信任 implementer 的报告
16
43
 
@@ -25,7 +52,7 @@ Implementer 的报告可能不完整或过于乐观。你**必须独立验证**
25
52
  读取 implementer 修改的文件，验证以下内容：
26
53
 
27
54
  - **阻塞项**：1~3 任一不满足都必须判定 ❌（以 TASK / specs.md 的明确要求为准）
28
- - **风险提示（非阻塞）**：4~6 默认仅记录风险，不作为不通过理由（除非它导致 1~3 直接不满足）
55
+ - **风险提示（非阻塞）**：4~5 默认仅记录风险，不作为不通过理由（除非它导致 1~3 直接不满足）
29
56
 
30
57
  **1. 没有少做（Missing）**
31
58
  - 任务要求的每一项是否都已实现？
@@ -43,36 +70,34 @@ Implementer 的报告可能不完整或过于乐观。你**必须独立验证**
43
70
  - 是否用了正确的方式解决了正确的问题？
44
71
  - 业务语义是否与 specs.md 的 AC/Scenario 一致？
45
72
 
46
- **4. 设计一致性（Design Compliance，默认仅风险提示）**
47
- - 如果提供了 design.md：检查是否存在明显绕过设计/关键约束不一致的实现，并记录为风险提示（引用 design 段落 + 对应代码文件路径和行号）
48
- - 如果未提供 design.md：记录为风险提示（无法验证设计一致性）
49
-
50
- **5. 边界与正确性（Boundary & Correctness，默认仅风险提示）**
73
+ **4. 边界与正确性（Boundary & Correctness，默认仅风险提示）**
51
74
  - 识别潜在幂等问题（重复请求/重试导致重复写入、重复扣款、重复发消息等），记录风险
52
75
  - 识别潜在空值/缺省值处理问题（NPE、字段缺失、空集合、空字符串等），记录风险
53
76
  - 识别潜在并发/竞态问题（重复提交、并发更新丢失、顺序依赖被破坏等），记录风险
54
77
 
55
- > 要求：判定基准以 `specs.md` / `TASK` 中可追溯的约束为主；`design.md` 仅用于风险提示（除非 TASK/specs.md 明确要求必须符合某条设计约束）。
78
+ > 要求：判定基准以 `specs.md` / `TASK` 中可追溯的约束为主。
56
79
  > - 若你发现“必须明确但 specs/TASK 没写清”的边界规则：记录为 **规格缺口风险**，不要仅因此判定不通过（不得在实现阶段临时发明规则）。
57
80
 
58
- **6. 测试覆盖关键场景（Testing Adequacy，默认仅风险提示）**
81
+ **5. 测试覆盖关键场景（Testing Adequacy，默认仅风险提示）**
59
82
  - 评估测试是否覆盖该任务涉及的关键 AC/Scenario。
60
83
  - 评估是否覆盖关键边界场景（幂等/空值/并发）对应的用例或回归点。
61
84
  - 如果 implementer 报告明确无测试，且你也未发现相关测试文件：仅记录为**风险提示**，不要仅因无测试而判定不通过。
62
- - 只有当 TASK/specs.md/design.md **明确要求必须补测试**时，缺失测试才属于 Missing 并必须判定 ❌。
85
+ - 若主 agent 传入上下文标明 **`skipTest：true`**（对应用户 `--skipTest=true`）：不因缺少单元测试或测试文件而判定不通过，仅记录**测试覆盖风险**与补充建议。
86
+ - 只有当 TASK/specs.md **明确要求必须补测试**时，缺失测试才属于 Missing 并必须判定 ❌。
87
+
88
+ **任务类型与 4～5 的深度**：若 TASK 主要为 DDL、迁移、Entity/薄 Repository、配置类变更，4～5 **只做一眼扫过**；无异常则一句话带过，**不要**按业务服务级任务的标准穷举。
63
89
 
64
90
  ## 报告格式
65
91
 
66
- **如果通过**：
92
+ **如果通过**（保持简短；通过且无明显风险时，风险提示可整段省略或写一句「无」）：
67
93
  ```
68
94
  ✅ 规格合规
69
95
 
70
96
  验证结论：
71
- - 已实现：[列出已覆盖的要求（按 TASK / specs.md 逐条）]
72
- - 风险提示（如有）：
73
- - 设计一致性风险：[如缺 design 或发现疑似偏离，引用 design 段落/说明缺失原因 + 对应代码文件路径和行号]
74
- - 边界风险（幂等/空值/并发）：[列出发现点 + 证据（文件路径和行号）]
75
- - 测试覆盖风险：[如无测试则标注风险]
97
+ - 已实现：[要点列表，对应 TASK 步骤/AC，每条一行]
98
+ - 风险提示（仅在有实质内容时展开；否则写「无」或省略子项）：
99
+ - 边界风险（幂等/空值/并发）：[…]
100
+ - 测试覆盖风险：[…]
76
101
  ```
77
102
 
78
103
  **如果有问题**：
@@ -89,7 +114,6 @@ Implementer 的报告可能不完整或过于乐观。你**必须独立验证**
89
114
  - [具体偏差描述，含文件路径和行号]
90
115
 
91
116
  风险提示（Risks，非阻塞）：
92
- - 设计一致性风险：[引用 design 段落/说明缺失原因 + 对应代码文件路径和行号]
93
117
  - 边界风险（幂等/空值/并发）：[具体描述，含文件路径和行号]
94
118
  - 规格缺口风险：[指出 specs/TASK 哪些需要补齐，为什么可能影响验收]
95
119
  - 测试覆盖风险：implementer 报告无测试/未发现测试文件，建议补充覆盖关键场景与边界用例
package/.agents/skills/6aspec-brown-implement/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: "6aspec-brown-implement"
3
- description: "执行任务实现"
3
+ description: "执行任务实现；可选 --skipTest=true|false（未写则 false）"
4
4
  ---
5
5
 
6
6
  # 操作流程
package/.claude/agents/6aspec-brown-spec-compliance-reviewer.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: 6aspec-brown-spec-compliance-reviewer
3
- description: 检查实现是否符合 TASK 的验收标准和 specs.md 的 AC/Scenario，适用于 TASK 完成后的合规验收
3
+ description: 检查实现是否符合 TASK 与 specs.md 的 AC/Scenario（不审查 design.md；设计对齐由实现阶段与 verify 等负责）
4
4
  model: gpt-5.3-codex
5
5
  ---
6
6
 
package/.codex/agents/6aspec-brown-spec-compliance-reviewer.toml CHANGED
@@ -1,7 +1,7 @@
1
1
  # .codex/agents/6aspec-brown-spec-compliance-reviewer.toml
2
2
 
3
3
  name = "6aspec-brown-spec-compliance-reviewer"
4
- description = "检查实现是否符合 TASK 的验收标准和 specs.md 的 AC/Scenario，适用于 TASK 完成后的合规验收"
4
+ description = "检查实现是否符合 TASK 与 specs.md 的 AC/Scenario（不审查 design.md）"
5
5
 
6
6
  # read-only | workspace-write | danger-full-access
7
7
  sandbox_mode = "read-only"
package/.cursor/agents/6aspec-brown-spec-compliance-reviewer.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: 6aspec-brown-spec-compliance-reviewer
3
- description: 检查实现是否符合 TASK 的验收标准和 specs.md 的 AC/Scenario，并强制校验 design.md 一致性（Cursor 版）
3
+ description: 检查实现是否符合 TASK 与 specs.md 的 AC/Scenario（不审查 design.md；设计对齐由实现阶段与 verify 等流程负责）
4
4
  model: gpt-5.3-codex
5
5
  readonly: true
6
6
  ---
package/.cursor/commands/6aspec-brown-implement.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: 执行任务实现
2
+ description: 执行任务实现；可选 --skipTest=true|false（未写则 false，标准单测模式）
3
3
  alwaysApply: false
4
4
  ---
5
5
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "6aspec",
3
- "version": "3.0.0-dev.14",
3
+ "version": "3.0.0-dev.15",
4
4
  "description": "6Aspec - 轻量级 spec 驱动开发框架，支持 Cursor 和 Claude Code",
5
5
  "main": "lib/installer.js",
6
6
  "bin": {