jsharness 1.8.3 → 1.10.0

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 阶段可追踪
+- **所有输出使用中文**

package/.harness/skills/openspec-skill-creator/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: openspec-skill-creator
+description: Skill 创建辅助技能 — 在 Harness 体系内创建新 Skill 的模板和流程，包含命名校验、Agent 关联和标准 SKILL.md 模板
+alwaysApply: false
+enabled: true
+outputPath: .harness/skills/
+---
+
+# Skill 创建辅助技能 (openspec-skill-creator)
+
+> **Skill 类型**: 工程基础设施 Skill
+> **触发场景**: 需要在 Harness 体系内创建新的 Skill
+> **所属 Agent**: developer / solution-designer
+> **输出路径**: `.harness/skills/{skill-name}/SKILL.md`
+
+---
+
+## 1. 核心职责
+
+作为 Skill 创建辅助技能，核心职责是：
+
+1. **生成符合 Harness 规范的 SKILL.md 文件**
+2. **校验 Skill 命名和冲突**
+
+### 1.1 输入
+
+| 输入项 | 说明 | 必须 |
+|--------|------|------|
+| Skill 名称 | kebab-case 格式（如 `user-profile-export`） | 是 |
+| Skill 描述 | 中文简要描述 | 是 |
+| 所属 Agent | 可调用此 Skill 的 Agent 角色 | 是 |
+| 输出路径 | Skill 产出的目标目录 | 否（有默认值） |
+
+### 1.2 输出
+
+| 输出项 | 路径 | 格式 |
+|--------|------|------|
+| SKILL.md 文件 | `.harness/skills/{skill-name}/SKILL.md` | Markdown |
+
+---
+
+## 2. 命名校验
+
+### 2.1 格式校验
+
+Skill 名称**必须**为 kebab-case 格式：
+
+- ✅ 正确：`user-profile-export`、`data-sync`、`api-gateway`
+- ❌ 错误：`UserProfileExport`、`user_profile_export`、`userProfileExport`
+
+如果用户提供的名称不符合格式，建议转换：
+- `UserProfileExport` → `user-profile-export`
+- `user_profile_export` → `user-profile-export`
+
+### 2.2 冲突校验
+
+检查 `.harness/skills/` 目录下是否已存在同名 Skill：
+- 如果存在 → 拒绝创建，报告冲突并提示已有 Skill 的路径
+- 如果不存在 → 继续创建
+
+---
+
+## 3. SKILL.md 标准模板
+
+生成的 SKILL.md 文件**必须**遵循以下模板结构：
+
+```markdown
+---
+name: {skill-name}
+description: {中文描述}
+alwaysApply: false
+enabled: true
+outputPath: {输出路径}
+---
+
+# {Skill 标题} ({skill-name})
+
+> **Skill 类型**: {类型描述}
+> **触发场景**: {何时使用}
+> **所属 Agent**: {agent-name}
+> **输出路径**: {输出路径}
+
+---
+
+## 1. 核心职责
+
+作为 {技能定位}，核心职责是：
+
+1. **{职责1}**
+2. **{职责2}**
+
+### 1.1 输入
+
+| 输入项 | 路径/说明 | 格式 | 必须 |
+|--------|----------|------|------|
+| {输入1} | {路径} | {格式} | 是 |
+
+### 1.2 输出
+
+| 输出项 | 路径/说明 | 格式 | 必须 |
+|--------|----------|------|------|
+| {输出1} | {路径} | {格式} | 是 |
+
+---
+
+## 2. 执行步骤
+
+### Step 1: {步骤1描述}
+
+{步骤1详细说明}
+
+### Step 2: {步骤2描述}
+
+{步骤2详细说明}
+
+---
+
+## 3. 约束
+
+- **{约束1}**
+- **{约束2}**
+- **所有输出使用中文**
+```
+
+---
+
+## 4. 执行步骤
+
+### Step 1: 获取 Skill 信息
+
+与用户确认：
+1. Skill 名称（kebab-case）
+2. Skill 描述（中文）
+3. 所属 Agent
+4. 输出路径（可选，默认 `.harness/doc/`）
+
+### Step 2: 执行命名校验
+
+1. 检查名称是否符合 kebab-case 格式
+2. 检查是否与已有 Skill 冲突
+
+### Step 3: 生成 SKILL.md
+
+基于标准模板生成 SKILL.md 文件，填入用户提供的信息。
+
+### Step 4: 确认
+
+展示生成的 SKILL.md 内容摘要，请用户确认。
+
+---
+
+## 5. 约束
+
+- **仅在 Harness 体系内创建** — 产出路径必须在 `.harness/skills/` 下
+- **遵循命名规范** — 名称必须 kebab-case，不得与已有 Skill 冲突
+- **遵循模板结构** — 必须包含 frontmatter、核心职责、输入输出、执行步骤、约束五个部分
+- **所有输出使用中文**

package/.harness/workflow/definition.yaml

@@ -52,9 +52,15 @@ workflow:
       max_turns: 10
       
       inputs:
-        - name: "原始需求"
-          source: "pm_routing"
-          format: "natural_language / issue"
+        - name: "原始需求文件"
+          source: "origin_requirements"
+          path: ".harness/doc/originRequirements/{filename}"
+          format: "markdown"
+          required: true
+        - name: "ttspec change 目录"
+          source: "ttspec_change"
+          path: ".harness/doc/ttspec/change/{name}/"
+          format: "directory"
           required: true
         - name: "TaskBoard 状态"
           source: "task_board"
@@ -65,17 +71,44 @@ workflow:
           format: "markdown"
           required: true
       
+      internal_steps:
+        - step: 1
+          name: "explore"
+          description: "深度探索需求 — 范围边界、受影响角色、假设与前提、风险面"
+          input: "原始需求文件"
+          output: ".harness/doc/ttspec/change/{name}/explore-notes.md"
+          command: "explore"
+          max_turns: 10
+        - step: 2
+          name: "propose"
+          description: "生成结构化提案 — proposal/design/specs/tasks"
+          input: "explore-notes.md"
+          output: ".harness/doc/ttspec/change/{name}/ (proposal.md, design.md, specs/, tasks.md)"
+          command: "propose"
+        - step: 3
+          name: "prd-generation"
+          description: "使用 prd-generator 技能生成标准化 PRD"
+          input: "explore-notes.md + propose 产出"
+          output: ".harness/doc/prd/requirements-{task-id}.md"
+          skill: "prd-generator"
+      
       outputs:
-        - name: "需求文档"
+        - name: "explore 笔记"
           format: "markdown"
-          template: ".harness/templates/requirements.md"
+          path: ".harness/doc/ttspec/change/{name}/explore-notes.md"
+          required: true
+        - name: "结构化提案"
+          format: "directory"
+          path: ".harness/doc/ttspec/change/{name}/"
           required: true
-        - name: "验收标准列表"
+        - name: "需求文档（PRD）"
           format: "markdown"
+          path: ".harness/doc/prd/requirements-{task-id}.md"
+          template: ".harness/skills/prd-generator/SKILL.md"
           required: true
-        - name: "用户故事集"
+        - name: "TaskBoard 更新"
           format: "markdown"
-          required: false
+          required: true
       
       transitions:
         - to: solution-design