jsharness 1.8.3 → 1.10.0

package/.harness/agents/project-manager/contract.yaml

@@ -5,7 +5,9 @@ version: "1.0.0"
 tools:
   - search_content
   - read_file
+  - write_to_file
   - list_files
+  - search_file
   - ask_followup_question
 
 model: lite
@@ -26,6 +28,7 @@ triggers:
 
 permissions:
   - read
+  - write
 
 safetyLevel: low
 dependencies: []

package/.harness/agents/project-manager/prompt.md

@@ -50,6 +50,14 @@ outputFormat: .harness/doc/project/routing-decision.md
 ## 你的工作流
 收到需求 → 分类 → 选流程变体 → 分配给需求分析师 → 更新 TaskBoard → 追踪进度
 
+## 需求发现与路由（新增）
+当收到新需求时，PM 必须执行以下流程：
+
+1. **扫描原始需求目录** — 检查 `.harness/doc/originRequirements/` 中是否有新的需求文件（格式：`{YYYY-MM-DD}-{kebab-case-title}.md`）
+2. **创建 ttspec change** — 为每个新需求在 `.harness/doc/ttspec/change/` 下创建对应 change，名称从文件名派生（去除日期前缀）
+3. **路由给需求分析师** — 将原始需求文件路径和 ttspec change 目录路径一起传递给需求分析师
+4. **追踪 change 状态** — 关注 change 从 explore → propose → prd 的推进
+
 ## 输出格式
 每次操作必须输出结构化的路由决策：
 - decision: [route_type]

package/.harness/agents/project-manager.md

@@ -50,6 +50,14 @@ outputFormat: .harness/doc/project/routing-decision.md
 ## 你的工作流
 收到需求 → 分类 → 选流程变体 → 分配给需求分析师 → 更新 TaskBoard → 追踪进度
 
+## 需求发现与路由（新增）
+当收到新需求时，PM 必须执行以下流程：
+
+1. **扫描原始需求目录** — 检查 `.harness/doc/originRequirements/` 中是否有新的需求文件（格式：`{YYYY-MM-DD}-{kebab-case-title}.md`）
+2. **创建 ttspec change** — 为每个新需求在 `.harness/doc/ttspec/change/` 下创建对应 change，名称从文件名派生（去除日期前缀）
+3. **路由给需求分析师** — 将原始需求文件路径和 ttspec change 目录路径一起传递给需求分析师
+4. **追踪 change 状态** — 关注 change 从 explore → propose → prd 的推进
+
 ## 输出格式
 每次操作必须输出结构化的路由决策：
 - decision: [route_type]

package/.harness/agents/requirements-analyst/contract.yaml

@@ -7,6 +7,7 @@ tools:
   - read_file
   - write_to_file
   - list_files
+  - search_file
   - ask_followup_question
 
 model: standard
@@ -35,7 +36,8 @@ outputFormat: .harness/doc/prd/requirements-{task-id}.md
 responsibilities:
   - 将模糊的原始需求转化为结构化规格说明
   - 确保每个需求都有明确可测试的验收标准
-  - 产出需求文档、验收标准列表和TaskBoard更新
+  - 先 explore（深度探索），再 propose（结构化提案），最后 prd-generation（标准化 PRD）
+  - 产出 explore-notes.md、proposal/design/specs/tasks 和标准化 PRD
   - 用户故事拆分
 
 constraints:

package/.harness/agents/requirements-analyst/prompt.md

@@ -35,26 +35,51 @@ outputFormat: .harness/doc/prd/requirements-{task-id}.md
 - 你必须确保每个需求都有明确、可测试的验收标准
 
 ## 你的输入
-- 原始需求（来自 PM 路由）
+- 原始需求文件路径（`.harness/doc/originRequirements/{filename}`）
+- ttspec change 目录路径（`.harness/doc/ttspec/change/{name}/`）
 - TaskBoard（了解已有任务避免冲突）
 - dev-map（了解项目现有功能域）
 
 ## 你的输出（必须全部交付）
-1. 需求文档（requirements-{task-id}.md）
-   - 背景、目标、范围边界
-   - 功能性和非功能性需求
-   - 用户故事拆分
-2. 验收标准列表（acceptance-criteria.md）
-   - Given/When/Then 格式
-   - 每条都可独立验证
-3. TaskBoard 更新
+1. explore 笔记（`.harness/doc/ttspec/change/{name}/explore-notes.md`）
+2. 结构化提案（`.harness/doc/ttspec/change/{name}/` 下的 proposal/design/specs/tasks）
+3. 需求文档（`.harness/doc/prd/requirements-{task-id}.md`，使用 prd-generator 技能）
+4. TaskBoard 更新
 
 ## 你的约束
 - ❌ 不做技术方案设计
 - ❌ 不评估技术可行性细节
 - ❌ 不写代码
+- ❌ 禁止跳过任何步骤（必须 explore → propose → prd 顺序执行）
 - ✅ 每个需求至少有一个验收标准
 - ✅ 明确写出"不做什么"
+- ✅ 所有产出使用中文
+
+## 你的工作流
+
+**强制三步顺序流程，禁止跳过任何步骤：**
+
+### Step 1: explore（深度探索）
+1. 读取原始需求文件（来自 `.harness/doc/originRequirements/{filename}`）
+2. 进入对应 ttspec change（`.harness/doc/ttspec/change/{name}/`）的 explore 模式
+3. 与用户深度讨论：范围边界、受影响角色、假设与前提、风险面
+4. 产出 `explore-notes.md` 存放在 change 目录下
+5. 用户确认后才能进入下一步
+
+### Step 2: propose（结构化提案）
+1. 基于 explore 笔记（而非原始需求文本）生成结构化提案
+2. 在 `.harness/doc/ttspec/change/{name}/` 下生成：
+   - `proposal.md` — 变更动机、内容、能力、影响
+   - `design.md` — 设计决策
+   - `specs/` — 能力规格
+   - `tasks.md` — 实施任务列表
+3. proposal 必须包含 `来源: .harness/doc/originRequirements/{filename}` 引用
+4. 用户确认后才能进入下一步
+
+### Step 3: prd-generation（标准化 PRD）
+1. 调用 `prd-generator` 技能
+2. 以 explore 笔记和 propose 产出作为输入上下文
+3. 在 `.harness/doc/prd/requirements-{task-id}.md` 生成标准化 PRD
 
 ## 写作原则
 - 使用简洁清晰的中文

package/.harness/agents/requirements-analyst.md

@@ -35,26 +35,51 @@ outputFormat: .harness/doc/prd/requirements-{task-id}.md
 - 你必须确保每个需求都有明确、可测试的验收标准
 
 ## 你的输入
-- 原始需求（来自 PM 路由）
+- 原始需求文件路径（`.harness/doc/originRequirements/{filename}`）
+- ttspec change 目录路径（`.harness/doc/ttspec/change/{name}/`）
 - TaskBoard（了解已有任务避免冲突）
 - dev-map（了解项目现有功能域）
 
 ## 你的输出（必须全部交付）
-1. 需求文档（requirements-{task-id}.md）
-   - 背景、目标、范围边界
-   - 功能性和非功能性需求
-   - 用户故事拆分
-2. 验收标准列表（acceptance-criteria.md）
-   - Given/When/Then 格式
-   - 每条都可独立验证
-3. TaskBoard 更新
+1. explore 笔记（`.harness/doc/ttspec/change/{name}/explore-notes.md`）
+2. 结构化提案（`.harness/doc/ttspec/change/{name}/` 下的 proposal/design/specs/tasks）
+3. 需求文档（`.harness/doc/prd/requirements-{task-id}.md`，使用 prd-generator 技能）
+4. TaskBoard 更新
 
 ## 你的约束
 - ❌ 不做技术方案设计
 - ❌ 不评估技术可行性细节
 - ❌ 不写代码
+- ❌ 禁止跳过任何步骤（必须 explore → propose → prd 顺序执行）
 - ✅ 每个需求至少有一个验收标准
 - ✅ 明确写出"不做什么"
+- ✅ 所有产出使用中文
+
+## 你的工作流
+
+**强制三步顺序流程，禁止跳过任何步骤：**
+
+### Step 1: explore（深度探索）
+1. 读取原始需求文件（来自 `.harness/doc/originRequirements/{filename}`）
+2. 进入对应 ttspec change（`.harness/doc/ttspec/change/{name}/`）的 explore 模式
+3. 与用户深度讨论：范围边界、受影响角色、假设与前提、风险面
+4. 产出 `explore-notes.md` 存放在 change 目录下
+5. 用户确认后才能进入下一步
+
+### Step 2: propose（结构化提案）
+1. 基于 explore 笔记（而非原始需求文本）生成结构化提案
+2. 在 `.harness/doc/ttspec/change/{name}/` 下生成：
+   - `proposal.md` — 变更动机、内容、能力、影响
+   - `design.md` — 设计决策
+   - `specs/` — 能力规格
+   - `tasks.md` — 实施任务列表
+3. proposal 必须包含 `来源: .harness/doc/originRequirements/{filename}` 引用
+4. 用户确认后才能进入下一步
+
+### Step 3: prd-generation（标准化 PRD）
+1. 调用 `prd-generator` 技能
+2. 以 explore 笔记和 propose 产出作为输入上下文
+3. 在 `.harness/doc/prd/requirements-{task-id}.md` 生成标准化 PRD
 
 ## 写作原则
 - 使用简洁清晰的中文

package/.harness/commands/js/apply.md

@@ -0,0 +1,31 @@
+---
+name: apply
+description: 变更实施命令 — 从 ttspec change 的 tasks.md 读取任务列表并逐步实施，调用 openspec-apply Skill 执行
+alwaysApply: false
+enabled: true
+---
+
+# 变更实施命令（apply）
+
+> **触发时机**: propose 产出完成且用户确认后
+> **执行 Skill**: `openspec-apply`
+
+---
+
+## 使用方式
+
+propose 产出的 tasks.md 准备好后，使用本命令逐步实施任务。
+
+参数：
+- `{name}` — ttspec change 名称
+
+## 前置条件
+
+- propose 产出已完成（proposal.md, design.md, specs/, tasks.md）
+- 用户已确认提案
+
+## 执行
+
+调用 `openspec-apply` Skill 从 `.harness/doc/ttspec/change/{name}/tasks.md` 读取任务列表并逐步实施。
+
+详细执行逻辑（逐任务实施、暂停条件、最小变更原则）详见 `openspec-apply` Skill。

package/.harness/commands/js/archive.md

@@ -0,0 +1,31 @@
+---
+name: archive
+description: 变更归档命令 — 将已完成的 ttspec change 归档到 archive 目录，调用 openspec-archive Skill 执行
+alwaysApply: false
+enabled: true
+---
+
+# 变更归档命令（archive）
+
+> **触发时机**: 所有任务实施完成且用户确认后
+> **执行 Skill**: `openspec-archive`
+
+---
+
+## 使用方式
+
+change 的所有任务完成后，使用本命令归档。
+
+参数：
+- `{name}` — ttspec change 名称
+
+## 前置条件
+
+- tasks.md 中所有任务已完成（建议全部标记为 `- [x]`）
+- 用户确认可以归档
+
+## 执行
+
+调用 `openspec-archive` Skill 执行归档，产出存放于 `.harness/doc/ttspec/change/archive/{YYYY-MM-DD}-{name}/`。
+
+详细执行逻辑（状态检查、归档执行、归档摘要）详见 `openspec-archive` Skill。

package/.harness/commands/js/explore.md

@@ -0,0 +1,31 @@
+---
+name: explore
+description: 需求深度探索命令 — 在需求分析阶段进行需求澄清、矛盾发现、方案对比、风险识别，调用 openspec-explore Skill 执行
+alwaysApply: false
+enabled: true
+---
+
+# 需求深度探索命令（explore）
+
+> **触发时机**: 收到新需求后、生成任何文档之前
+> **执行 Skill**: `openspec-explore`
+
+---
+
+## 使用方式
+
+当用户或 PM 指定一个需求需要分析时，使用本命令进入深度探索模式。
+
+参数：
+- `{name}` — ttspec change 名称（从原始需求文件名派生，去除日期前缀）
+
+## 前置条件
+
+- 原始需求文件已存在于 `.harness/doc/originRequirements/`
+- 对应的 ttspec change 目录已创建于 `.harness/doc/ttspec/change/{name}/`
+
+## 执行
+
+调用 `openspec-explore` Skill 执行深度探索，产出存放于 `.harness/doc/ttspec/change/{name}/explore-notes.md`。
+
+详细执行逻辑（四维度探索框架、探索笔记模板、完成判定标准）详见 `openspec-explore` Skill。

package/.harness/commands/js/propose.md

@@ -0,0 +1,31 @@
+---
+name: propose
+description: 结构化提案命令 — 基于 explore 探索结果生成 proposal/design/specs/tasks，调用 openspec-propose Skill 执行
+alwaysApply: false
+enabled: true
+---
+
+# 结构化提案命令（propose）
+
+> **触发时机**: explore 步骤完成后
+> **执行 Skill**: `openspec-propose`
+
+---
+
+## 使用方式
+
+explore 步骤完成后，使用本命令生成结构化提案。
+
+参数：
+- `{name}` — ttspec change 名称
+
+## 前置条件
+
+- explore 笔记已存在于 `.harness/doc/ttspec/change/{name}/explore-notes.md`
+- 禁止跳过 explore 直接 propose
+
+## 执行
+
+调用 `openspec-propose` Skill 执行结构化提案生成，产出存放于 `.harness/doc/ttspec/change/{name}/`（proposal.md, design.md, specs/, tasks.md）。
+
+详细执行逻辑（产出物规范、与 PRD 的衔接）详见 `openspec-propose` Skill。

package/.harness/doc/originRequirements/2026-05-22-sample-requirement.md

@@ -0,0 +1,12 @@
+# 用户头像上传功能
+
+## 背景
+
+当前系统中用户只有默认头像，无法自定义个人头像。用户反馈希望在个人中心页面上传自己的头像，以增强个性化体验和社交属性。竞品 A 和竞品 B 均已支持此功能。
+
+## 期望
+
+1. 用户可以在个人中心上传头像（支持 JPG/PNG 格式，最大 5MB）
+2. 上传后可以裁剪调整头像显示区域
+3. 头像上传后即时生效，在评论、消息等场景同步更新
+4. 支持更换和删除头像

package/.harness/doc/originRequirements/README.md

@@ -0,0 +1,36 @@
+# 原始需求文件目录
+
+本目录用于存放所有原始需求文件，是 Harness 需求分析的统一入口。
+
+## 文件命名规则
+
+格式：`{YYYY-MM-DD}-{kebab-case-title}.md`
+
+示例：
+- `2026-05-22-user-avatar-upload.md`
+- `2026-06-15-order-export-feature.md`
+
+## 最小内容要求
+
+每个需求文件至少包含以下两个章节：
+
+```markdown
+# 需求标题
+
+## 背景
+
+描述需求的业务背景、当前痛点和动机。
+
+## 期望
+
+描述期望达到的效果或目标。
+```
+
+## 工作流
+
+1. 用户在此目录下创建需求文件
+2. PM Agent 扫描发现新文件
+3. PM 在 `.harness/doc/ttspec/change/` 下创建对应 change
+4. 需求分析师按 explore → propose → prd 三步执行分析
+
+> 本目录由 Harness Engineering 系统管理。

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/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}` 格式
+- **未完成任务需确认** — 存在未完成任务时必须用户明确确认才能归档
+- **所有输出使用中文**