jsharness 1.8.2 → 1.10.0

package/.harness/doc/ttspec/README.md

@@ -0,0 +1,33 @@
+# ttspec — 变更规格管理目录
+
+本目录用于存放 Harness 流程中 OpenSpec 的产出物，包括变更管理（change）和能力规格（specs）。
+
+## 目录结构
+
+```
+.harness/doc/ttspec/
+├── change/                    # 变更目录（每个需求对应一个子目录）
+│   ├── archive/               # 已归档的变更
+│   └── {change-name}/         # 活跃变更
+│       ├── explore-notes.md   # explore 阶段产出
+│       ├── proposal.md        # propose 阶段产出
+│       ├── design.md          # 设计决策
+│       ├── specs/             # 能力规格
+│       └── tasks.md           # 实施任务列表
+└── specs/                     # 全局能力规格
+    └── {capability}/
+        └── spec.md
+```
+
+## 变更命名规则
+
+change 名称从原始需求文件名派生：去除日期前缀，保留 kebab-case 标题。
+
+示例：需求文件 `2026-05-22-user-avatar-upload.md` → change 名 `user-avatar-upload`
+
+## 与 openspec/ 的关系
+
+- `openspec/` — OpenSpec CLI 原生操作目录（历史数据保持不动）
+- `.harness/doc/ttspec/` — Harness 流程中的变更管理产出目录
+
+> 本目录由 Harness Engineering 系统管理。

package/.harness/rules/global/process-discipline.md

@@ -126,12 +126,21 @@ PM Agent 的职责是**路由和协调**，不是技术判断：
 
 | 阶段 | 必须交付物 | 可选交付物 |
 |------|-----------|-----------|
-| **需求分析** | 需求文档（含验收标准）、TaskBoard 更新 | 竞品分析 |
+| **需求分析** | explore 笔记、结构化提案（proposal/design/specs/tasks）、PRD 需求文档（含验收标准）、TaskBoard 更新 | 竞品分析 |
 | **方案设计** | 技术设计文档、接口定义 | ADR 决策记录 |
 | **开发实现** | 代码（已 Commit）、单元测试、dev-map 更新 | 技术笔记 |
 | **代码审查** | 审查报告（PASS/FAIL 结论 + 逐项打分） | 重构建议 |
 | **测试验证** | 测试报告（覆盖范围 + 结果 + 缺陷列表） | 性能报告 |
 
+### 4.2 文件存放规范
+
+| 文档类型 | 存放路径 | 说明 |
+|---------|---------|------|
+| 原始需求文件 | `.harness/doc/originRequirements/` | 命名格式：`{YYYY-MM-DD}-{kebab-case-title}.md`，至少包含 `## 背景` 和 `## 期望` |
+| 变更管理产出 | `.harness/doc/ttspec/change/` | 每个需求对应一个 change 目录，名称从原始需求文件名派生 |
+| 能力规格 | `.harness/doc/ttspec/specs/` | 全局能力规格定义 |
+| PRD 文档 | `.harness/doc/prd/` | 标准化 PRD 文档 |
+
 ### 4.2 交付物质量标准
 
 - 所有文档必须是 **Markdown 格式**

package/.harness/skills/architecture-designer/SKILL.md

@@ -3,6 +3,7 @@ name: architecture-designer
 description: 专业架构设计技能 — C4 架构模型、用例图、领域模型、服务设计、ER图、类图的全套设计模板和 Mermaid 规范，支持简单/复杂需求分流
 alwaysApply: false
 enabled: true
+outputPath: .harness/doc/design/
 ---
 
 # Architecture Designer Skill
@@ -10,6 +11,7 @@ enabled: true
 > **Skill 类型**: 方案设计辅助 Skill
 > **触发场景**: 系统架构方案设计、技术设计文档编写、多维度架构评审优化
 > **所属 Agent**: solution-designer（方案设计师在方案设计阶段引用本 skill）
+> **输出路径**: 生成的架构设计文档写入项目根目录下 `.harness/doc/design/` 目录
 
 ---
 

package/.harness/skills/docs-update/SKILL.md

@@ -3,12 +3,14 @@ name: docs-update
 description: 文档更新技能 — CHANGELOG 更新、API 文档生成（JSDoc/Swagger）、README 维护、dev-map 同步及 ADR 决策记录
 alwaysApply: false
 enabled: true
+outputPath: .harness/doc/
 ---
 
 # 文档更新技能 (docs-update)
 
 > **执行角色**: 开发实现 Agent / 需求分析 Agent / 方案设计 Agent
 > **触发时机**: 每次代码变更后、阶段交付前
+> **输出路径**: 文档更新产物写入项目根目录下 `.harness/doc/` 目录（CHANGELOG、ADR 等按子目录组织）
 
 ---
 

package/.harness/skills/openspec-apply/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: openspec-apply
+description: 变更实施技能 — 从 ttspec change 的 tasks.md 读取任务列表并逐步实施，支持暂停条件和最小变更原则
+alwaysApply: false
+enabled: true
+outputPath: .harness/doc/ttspec/change/
+---
+
+# 变更实施技能 (openspec-apply)
+
+> **Skill 类型**: 开发实施辅助 Skill
+> **触发场景**: propose 产出完成且用户确认后，逐步实施 tasks.md 中的任务
+> **所属 Agent**: developer / requirements-analyst
+> **输出路径**: `.harness/doc/ttspec/change/{name}/tasks.md`（更新复选框状态）
+
+---
+
+## 1. 核心职责
+
+作为变更实施技能，核心职责是：
+
+1. **从 tasks.md 读取待完成任务**
+2. **逐任务实施代码/文档变更**
+3. **实时更新任务完成状态**
+
+### 1.1 输入
+
+| 输入项 | 路径 | 格式 | 必须 |
+|--------|------|------|------|
+| 任务列表 | `.harness/doc/ttspec/change/{name}/tasks.md` | Markdown | 是 |
+| 提案文档 | `.harness/doc/ttspec/change/{name}/proposal.md` | Markdown | 是 |
+| 设计文档 | `.harness/doc/ttspec/change/{name}/design.md` | Markdown | 是 |
+| 能力规格 | `.harness/doc/ttspec/change/{name}/specs/` | Markdown | 是 |
+
+### 1.2 输出
+
+| 输出项 | 路径 | 格式 | 必须 |
+|--------|------|------|------|
+| 更新后的任务列表 | `.harness/doc/ttspec/change/{name}/tasks.md` | Markdown | 是 |
+| 实施的代码/文档变更 | 对应源码/文档位置 | 各种 | 是 |
+| 实施总结 | 终端输出 | 文本 | 是 |
+
+---
+
+## 2. 执行步骤
+
+### Step 1: 读取任务列表
+
+从 `.harness/doc/ttspec/change/{name}/tasks.md` 读取任务列表，识别所有待完成任务（标记为 `- [ ]`）。
+
+### Step 2: 逐任务实施
+
+对每个待完成任务：
+
+1. 读取任务描述和涉及的文件路径
+2. 读取相关的 specs 和 design 文档获取上下文
+3. 实施代码/文档变更
+4. **立即**将任务标记为已完成：将 `- [ ]` 改为 `- [x]`
+5. 继续下一个任务
+
+### Step 3: 暂停条件
+
+以下情况**必须暂停**：
+
+| 暂停条件 | 处理方式 |
+|---------|---------|
+| 任务描述不清晰 | 暂停并询问用户澄清 |
+| 实施中发现设计问题 | 暂停并建议更新 design/specs |
+| 遇到错误或阻塞 | 暂停并报告，等待指导 |
+| 用户中断 | 保存当前进度并停止 |
+
+### Step 4: 完成后
+
+所有任务完成后：
+
+1. 显示实施总结：
+   - 完成的任务总数
+   - 修改的文件列表
+   - 遗留问题（如有）
+2. 建议用户使用 `openspec-archive` Skill 归档
+
+---
+
+## 3. 约束
+
+- **保持变更最小化** — 每个任务只做必要修改，不做额外重构
+- **立即标记完成** — 完成任务后立即更新 tasks.md 中的复选框
+- **遇到阻塞暂停** — 不猜测、不绕过，暂停并报告
+- **顺序执行** — 按 tasks.md 中的顺序执行，不跳跃
+- **所有输出使用中文**

package/.harness/skills/openspec-archive/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: openspec-archive
+description: 变更归档技能 — 将已完成的 ttspec change 归档到 archive 目录，包含状态检查、归档执行和归档摘要
+alwaysApply: false
+enabled: true
+outputPath: .harness/doc/ttspec/change/archive/
+---
+
+# 变更归档技能 (openspec-archive)
+
+> **Skill 类型**: 项目管理辅助 Skill
+> **触发场景**: 所有任务实施完成且用户确认后，归档变更
+> **所属 Agent**: project-manager / developer
+> **归档路径**: `.harness/doc/ttspec/change/archive/{YYYY-MM-DD}-{name}/`
+
+---
+
+## 1. 核心职责
+
+作为变更归档技能，核心职责是：
+
+1. **验证变更状态是否可归档**
+2. **执行归档操作**
+3. **输出归档摘要**
+
+### 1.1 输入
+
+| 输入项 | 路径 | 格式 | 必须 |
+|--------|------|------|------|
+| 变更目录 | `.harness/doc/ttspec/change/{name}/` | 目录 | 是 |
+| 任务列表 | `.harness/doc/ttspec/change/{name}/tasks.md` | Markdown | 是 |
+
+### 1.2 输出
+
+| 输出项 | 路径 | 格式 | 必须 |
+|--------|------|------|------|
+| 归档目录 | `.harness/doc/ttspec/change/archive/{YYYY-MM-DD}-{name}/` | 目录 | 是 |
+| 归档摘要 | 终端输出 | 文本 | 是 |
+
+---
+
+## 2. 执行步骤
+
+### Step 1: 检查变更状态
+
+确认 `.harness/doc/ttspec/change/{name}/tasks.md` 中所有任务均已标记为 `- [x]`。
+
+- 如果所有任务已完成 → 直接进入归档
+- 如果存在未完成任务 → 提示用户是否确认归档
+
+### Step 2: 执行归档
+
+将 `.harness/doc/ttspec/change/{name}/` **整个目录**移动到 `.harness/doc/ttspec/change/archive/{YYYY-MM-DD}-{name}/`。
+
+归档目录将包含所有原始文件：
+- `proposal.md`
+- `design.md`
+- `specs/` 目录
+- `tasks.md`
+- `explore-notes.md`（如存在）
+
+### Step 3: 输出归档摘要
+
+```
+✅ 变更 "{name}" 已归档
+   归档位置：.harness/doc/ttspec/change/archive/{date}-{name}/
+   包含文件：proposal.md, design.md, specs/, tasks.md
+```
+
+---
+
+## 3. 约束
+
+- **归档是移动操作** — 原目录从活跃区消失，归档后通过 archive 目录查阅历史
+- **日期格式** — 归档目录名使用 `{YYYY-MM-DD}-{name}` 格式
+- **未完成任务需确认** — 存在未完成任务时必须用户明确确认才能归档
+- **所有输出使用中文**

package/.harness/skills/openspec-explore/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: openspec-explore
+description: 需求深度探索技能 — 四维度探索框架（范围边界/受影响角色/假设前提/风险面）、探索笔记模板、完成判定标准，产出存放于 .harness/doc/ttspec/change/{name}/explore-notes.md
+alwaysApply: false
+enabled: true
+outputPath: .harness/doc/ttspec/change/
+---
+
+# 需求深度探索技能 (openspec-explore)
+
+> **Skill 类型**: 需求分析辅助 Skill
+> **触发场景**: 收到新需求后、生成任何文档之前，进行需求深度探索
+> **所属 Agent**: requirements-analyst（需求分析师在需求分析阶段引用本 skill）
+> **输出路径**: `.harness/doc/ttspec/change/{name}/explore-notes.md`
+
+---
+
+## 1. 核心职责
+
+作为需求深度探索技能，核心职责是：
+
+1. **围绕需求进行四维度深度探索**
+2. **产出结构化探索笔记**
+
+### 1.1 前置条件
+
+- 原始需求文件已存在于 `.harness/doc/originRequirements/` 目录
+- 对应的 ttspec change 目录已创建于 `.harness/doc/ttspec/change/{name}/`
+- change 名称 `{name}` 与原始需求文件的对应关系：change 名 `user-avatar-upload` 对应文件 `2026-05-22-user-avatar-upload.md`
+
+### 1.2 输入
+
+| 输入项 | 路径 | 格式 | 必须 |
+|--------|------|------|------|
+| 原始需求文件 | `.harness/doc/originRequirements/{filename}` | Markdown | 是 |
+| ttspec change 目录 | `.harness/doc/ttspec/change/{name}/` | 目录 | 是 |
+| dev-map 参考文档 | `.harness/dev-map/` | Markdown | 否 |
+
+### 1.3 输出
+
+| 输出项 | 路径 | 格式 | 必须 |
+|--------|------|------|------|
+| 探索笔记 | `.harness/doc/ttspec/change/{name}/explore-notes.md` | Markdown | 是 |
+
+---
+
+## 2. 四维度探索框架
+
+围绕以下四个维度与用户深度讨论，**所有维度必须全部覆盖**：
+
+### 2.1 范围边界
+
+- **包含什么？** — 明确本次需求要做什么
+- **排除什么？** — 明确本次需求不做什么
+- **边界在哪？** — 哪些是灰色地带，需要用户确认
+
+### 2.2 受影响角色
+
+- 哪些用户角色会受影响？
+- 他们各自的诉求是什么？
+- 角色之间是否存在冲突的诉求？
+
+### 2.3 假设与前提
+
+- 有哪些隐含假设？
+- 这些假设是否成立？
+- 如果假设不成立，需求是否需要调整？
+
+### 2.4 风险面
+
+- 存在哪些风险（技术/业务/组织）？
+- 如何缓解这些风险？
+- 哪些风险是可接受的，哪些必须规避？
+
+---
+
+## 3. 探索笔记模板
+
+讨论完成后，将结构化摘要写入 `.harness/doc/ttspec/change/{name}/explore-notes.md`，**必须**包含以下章节：
+
+```markdown
+# 需求探索笔记：{change-name}
+
+## 来源
+- 原始需求文件：.harness/doc/originRequirements/{filename}
+
+## 范围边界
+- **包含**：...
+- **排除**：...
+
+## 受影响角色
+- 角色A：...
+
+## 假设与前提
+- 假设1：...
+
+## 风险识别
+- 风险1：...缓解措施：...
+
+## 未决问题
+- 问题1：...
+```
+
+---
+
+## 4. 执行步骤
+
+### Step 1: 读取原始需求
+
+从 `.harness/doc/originRequirements/` 中读取对应的原始需求文件。
+
+### Step 2: 进入探索模式
+
+围绕四个维度与用户深度讨论，每个维度至少有一个确认项。
+
+### Step 3: 产出探索笔记
+
+按模板格式写入 `.harness/doc/ttspec/change/{name}/explore-notes.md`。
+
+### Step 4: 完成判定
+
+- 用户明确确认探索内容满意，或
+- 探索轮次达到上限（maxTurns: 10）且用户同意推进
+
+完成后进入 propose 步骤（调用 `openspec-propose` Skill）。
+
+---
+
+## 5. 约束
+
+- **禁止跳过** — 新需求必须先 explore 再 propose
+- **禁止编造** — 信息不足则追问，不编造假设
+- **四个维度必须全覆盖** — 缺少任何一个维度的探索都视为未完成
+- **轮次上限** — 最多 10 轮讨论，达到上限时总结当前发现并询问是否推进
+- **所有输出使用中文**

package/.harness/skills/openspec-propose/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: openspec-propose
+description: 结构化提案技能 — 从探索笔记生成 proposal/design/specs/tasks 的完整流程、产出物规范、与 PRD 的衔接，产出存放于 .harness/doc/ttspec/change/{name}/
+alwaysApply: false
+enabled: true
+outputPath: .harness/doc/ttspec/change/
+---
+
+# 结构化提案技能 (openspec-propose)
+
+> **Skill 类型**: 需求分析辅助 Skill
+> **触发场景**: explore 探索完成后，生成结构化提案
+> **所属 Agent**: requirements-analyst（需求分析师在需求分析阶段引用本 skill）
+> **输出路径**: `.harness/doc/ttspec/change/{name}/`（proposal.md, design.md, specs/, tasks.md）
+
+---
+
+## 1. 核心职责
+
+作为结构化提案技能，核心职责是：
+
+1. **基于探索笔记生成结构化提案**
+2. **衔接 PRD 生成**
+
+### 1.1 前置条件
+
+- explore 笔记已存在于 `.harness/doc/ttspec/change/{name}/explore-notes.md`
+- 禁止跳过 explore 直接 propose
+
+### 1.2 输入
+
+| 输入项 | 路径 | 格式 | 必须 |
+|--------|------|------|------|
+| 探索笔记 | `.harness/doc/ttspec/change/{name}/explore-notes.md` | Markdown | 是 |
+| 原始需求文件 | `.harness/doc/originRequirements/{filename}` | Markdown | 否（已含在探索笔记中） |
+| dev-map 参考文档 | `.harness/dev-map/` | Markdown | 否 |
+
+### 1.3 输出
+
+| 输出项 | 路径 | 格式 | 必须 |
+|--------|------|------|------|
+| 提案文档 | `.harness/doc/ttspec/change/{name}/proposal.md` | Markdown | 是 |
+| 设计文档 | `.harness/doc/ttspec/change/{name}/design.md` | Markdown | 是 |
+| 能力规格 | `.harness/doc/ttspec/change/{name}/specs/{capability}/spec.md` | Markdown | 是 |
+| 任务列表 | `.harness/doc/ttspec/change/{name}/tasks.md` | Markdown | 是 |
+
+---
+
+## 2. 产出物规范
+
+### 2.1 proposal.md — 提案文档
+
+**必须**包含以下章节：
+
+```markdown
+## 为什么
+<!-- 变更动机和背景 -->
+
+## 变更内容
+<!-- 具体要做什么 -->
+
+## 能力
+
+### 新增能力
+- `<capability-name>`: <简要描述>
+
+### 修改能力
+- `<existing-capability>`: <变更什么>
+
+## 影响
+| 影响域 | 具体内容 |
+|--------|----------|
+```
+
+**强制要求**：proposal 必须包含 `来源: .harness/doc/originRequirements/{filename}` 引用。
+
+### 2.2 design.md — 设计文档
+
+**必须**包含以下章节：
+
+```markdown
+## 背景
+<!-- 当前状况和问题 -->
+
+## 目标 / 非目标
+**目标：**
+<!-- 本设计要达成什么 -->
+
+**非目标：**
+<!-- 明确排除什么 -->
+
+## 设计决策
+### 决策 1: <标题>
+**选择**: ...
+**替代方案**: ...
+**理由**: ...
+
+## 风险与权衡
+| 风险 | 缓解措施 |
+|------|---------|
+```
+
+### 2.3 specs/{capability}/spec.md — 能力规格
+
+为每个能力（在 proposal 的"能力"章节中列出）生成独立规格文件。
+
+**必须**遵循以下格式：
+
+```markdown
+## ADDED Requirements
+
+### Requirement: <需求名称>
+<需求描述，使用 SHALL/MUST>
+
+#### Scenario: <场景名称>
+- **WHEN** <条件>
+- **THEN** <预期结果>
+```
+
+**关键规则**：
+- 每个 Requirement 必须至少有一个 Scenario
+- Scenario 必须使用 `####`（4 个井号）
+- 使用 WHEN/THEN 格式描述验收条件
+
+### 2.4 tasks.md — 任务列表
+
+**必须**遵循以下格式：
+
+```markdown
+## 1. <任务分组名>
+
+- [ ] 1.1 <任务描述>
+- [ ] 1.2 <任务描述>
+```
+
+**关键规则**：
+- 使用 `- [ ]` 复选框格式（apply 阶段依赖此格式追踪进度）
+- 任务足够小，可在一次会话中完成
+- 按依赖顺序排列
+- 包含涉及的文件路径
+
+---
+
+## 3. 执行步骤
+
+### Step 1: 读取探索笔记
+
+从 `.harness/doc/ttspec/change/{name}/explore-notes.md` 读取探索结果。
+
+### Step 2: 生成 proposal.md
+
+基于探索笔记（而非原始需求文本）生成提案文档。
+
+### Step 3: 生成 design.md
+
+基于提案生成设计决策文档。
+
+### Step 4: 生成 specs/
+
+为每个能力生成独立的 spec.md 文件。
+
+### Step 5: 生成 tasks.md
+
+生成实施任务列表。
+
+### Step 6: 衔接 PRD
+
+所有 propose 产出完成后，调用 `prd-generator` 技能，以探索笔记和 propose 产出作为输入上下文，在 `.harness/doc/prd/requirements-{task-id}.md` 生成标准化 PRD。
+
+---
+
+## 4. 约束
+
+- **必须基于探索笔记生成** — 禁止跳过 explore 直接 propose
+- **proposal 必须引用来源** — 包含 `来源: .harness/doc/originRequirements/{filename}`
+- **specs 必须使用 WHEN/THEN 格式** — 确保可测试
+- **tasks 必须使用复选框格式** — 确保 apply 阶段可追踪
+- **所有输出使用中文**