ws-spec-kit 0.1.0-beta.0 → 0.1.0-beta.2

package/resources/skills/documentation-editing/SKILL.md

@@ -1,16 +1,24 @@
 ---
 name: documentation-editing
-description: 编辑中文文档
+description: 按事实编辑中文文档。用于 edit-document：只改允许路径，句子能指回事实。
 ---
 
 # 编辑中文文档
 
-目标：编辑中文文档。
+改文档是在更新缓存。每个陈述句都要指回已确认事实。
 
-输入：事实清单和文档目标。
+## 步骤
 
-输出：准确、完整的文档变更。
+1. **读事实清单**
+   完成：知道增、删、改哪几句。
 
-停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+2. **只改允许路径**
+   在 `allowedPaths` 内编辑中文正文。完成：diff 不含代码、配置或范围外文件。
 
-禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。
+3. **交文档变更**
+   完成：新增句都能指证；过时句已删或已改。
+
+## 规则
+
+- 先写清完成标准，再堆解释。
+- 范围外或事实不足：停止并报告阻塞。

package/resources/skills/documentation-exploration/SKILL.md

@@ -1,16 +1,24 @@
 ---
 name: documentation-exploration
-description: 探索文档事实
+description: 探索文档事实。用于文档 explore：只收录仓库与原文里能指证的事实。
 ---
 
 # 探索文档事实
 
-目标：探索文档事实。
+文档只陈述能指证的事实。代码、配置、帮助输出是真源；旧文档是待核缓存。
 
-输入：文档目标和仓库事实。
+## 步骤
 
-输出：事实清单与文档范围。
+1. **钉范围**
+   读允许的文档路径与目标。完成：知道哪些文件能改。
 
-停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+2. **对事实**
+   每条将写入的句子都能指到源文件、命令或已确认原文。完成：过时文档被标成缓存，不当新事实。
 
-禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。
+3. **交事实清单**
+   写出现状、缺口、过时句。完成：编辑者不用再猜 API 或行为。
+
+## 规则
+
+- 查得到的不抄进清单当永久正文，只记「到哪查」。
+- 事实对不上：停止并报告阻塞。

package/resources/skills/documentation-review/SKILL.md

@@ -1,16 +1,27 @@
 ---
 name: documentation-review
-description: 审查文档质量
+description: 审查文档。用于文档 review：核对准确性与完整性，不改文件。
 ---
 
 # 审查文档质量
 
-目标：审查文档质量。
+对照事实清单审 diff。准确且完整才能批准。
 
-输入：文档变更和事实来源。
+## 步骤
 
-输出：准确性、完整性审查结果。
+1. **钉变更**
+   读允许路径内的 diff 与事实清单。完成：每处改动都已看见。
 
-停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+2. **审准确**
+   句子不得与代码、配置或原文冲突。完成：过时或臆造句都是 finding。
 
-禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。
+3. **审完整**
+   事实清单里要公开的点都有落点。完成：缺口都列出来。
+
+4. **交审查结果**
+   完成：`approved` 仅在准确且完整时为真。
+
+## 规则
+
+- 不改文档。修复走 documentation-editing。
+- 事实对不上：停止并报告阻塞。

package/resources/skills/requirement-exploration/SKILL.md

@@ -1,16 +1,30 @@
 ---
 name: requirement-exploration
-description: 探索代码与需求
+description: 探索代码与需求。用于 explore/clarify：grill 未决决策、从仓库取事实、写出规格。
 ---
 
 # 探索代码与需求
 
-目标：探索代码与需求。
+事实从仓库取；决策问用户。未证实的业务当缺口，不当规格。
 
-输入：需求描述和仓库状态。
+## 步骤
 
-输出：澄清问题与需求规格。
+1. **读 Work Package**
+   记下 `requiredOutputs`、允许路径、已有 Artifact。完成：能复述本步要交的 `outputId`。
 
-停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+2. **取事实**
+   顺着调用链读现有模块、配置、测试和 Issue/规格原文。完成：每条约束都能指到文件或原文，没有猜的 API。
 
-禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。
+3. **摊 frontier**
+   一次列出所有已解锁、必须人答的决策。完成：没有「先假设再继续」的开放问题。
+
+4. **交产物**
+   - explore：写 `exploration-report`（现状、约束、缺口、风险信号）。
+   - clarify：只把已确认事实写成 `specification`。
+   完成：产物覆盖 `requiredOutputs`，缺口标成阻塞而不是默认值。
+
+## 规则
+
+- 一轮问完当前 frontier，等答复再写规格。
+- 风险信号（外部写入、密钥、跨仓、破坏兼容）写进报告，供 Profile 升级，不在这里改档。
+- 缺授权、缺原文或路径越界：停止并报告阻塞。

package/resources/skills/solution-design/SKILL.md

@@ -1,16 +1,28 @@
 ---
 name: solution-design
-description: 设计技术方案
+description: 设计可实施的技术方案。用于 design：在已确认规格上选 seam、写取舍。
 ---
 
 # 设计技术方案
 
-目标：设计技术方案。
+设计对着已确认规格，不发明需求。优先加深现有模块，不平行再造一套。
 
-输入：已确认需求和代码事实。
+## 步骤
 
-输出：方案文档与取舍。
+1. **钉规格**
+   读 `specification` 与探索报告。完成：每个要动的行为都能指回规格句子。
 
-停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+2. **找 seam**
+   标出将要切开的公共边界（入口、配置、Gate、适配器）。完成：能一句话说清「外面看见什么，里面藏什么」。
 
-禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。
+3. **写取舍**
+   每个关键缝至少两个真方案，写清为何选这个。完成：落选方案有具体代价，不是空对比。
+
+4. **交 `design`**
+   写模块形状、数据流、失败方式和验证点。完成：实现者不用再猜接口；测试能钉在这些 seam 上。
+
+## 规则
+
+- 非法状态用类型消掉，不在调用点反复校验。
+- 不扩允许路径，不引入未声明的外部写入。
+- 规格未决：停止并报告阻塞，不把设计当拍板。

package/resources/skills/task-planning/SKILL.md

@@ -1,16 +1,28 @@
 ---
 name: task-planning
-description: 拆分实施任务
+description: 把设计拆成可验证任务。用于 plan：tracer-bullet、声明阻塞边。
 ---
 
 # 拆分实施任务
 
-目标：拆分实施任务。
+一张任务做一件可观察行为。先做挡住别人的，再做被挡住的。
 
-输入：批准方案。
+## 步骤
 
-输出：按依赖排序的可验证任务。
+1. **读设计**
+   对照 `specification` 与 `design`。完成：每个任务能指回一个设计缝或规格条款。
 
-停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+2. **切 tracer**
+   按可独立验证的行为切开，写下阻塞边。完成：没有「做完功能 X」这种大篮子；环被拆开。
 
-禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。
+3. **标验证**
+   每个任务写清红测会看见什么。完成：验收是命令或断言，不是「看起来对」。
+
+4. **交 `tasks`**
+   按阻塞序排列。完成：实现者可以一次只拿一张任务，不必回头猜依赖。
+
+## 规则
+
+- 实现与其测试是同一张任务。
+- 目录不同且可独立回滚的，拆开。
+- 设计缺口：停止并报告阻塞。

package/resources/skills/tdd-implementation/SKILL.md

@@ -1,16 +1,36 @@
 ---
 name: tdd-implementation
-description: 执行测试驱动实现
+description: 测试驱动实现。用于 write-tests/implement：先 red，再最小 green。钉在公开 seam。
 ---
 
-# 执行测试驱动实现
+# 测试驱动实现
 
-目标：执行测试驱动实现。
+先 red，再 green。测公开 seam，不测私有结构。
 
-输入：当前任务和验收条件。
+## write-tests
 
-输出：Red、Green 与实现结果。
+1. **钉一张任务**
+   只取当前 `tasks` 中未完成的第一张。完成：知道这条红测失败时证明什么。
 
-停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+2. **写红测**
+   Given / When / Then；期望值来自规格或字面量，不从实现反推。完成：跑项目 Test Gate 时因**断言**失败，不是缺模块或语法错。
 
-禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。
+3. **交 `red-test-result`**
+   完成：写明测了哪条行为、失败种类是 assertion。
+
+## implement
+
+1. **保住红测**
+   不删、不放宽、不改断言含义。完成：红测文件身份仍是 verify-red 绑过的那批。
+
+2. **最小 green**
+   只写让这条红测通过的代码。完成：同一 Test Gate 退出码为 0，且红测仍在。
+
+3. **交 `implementation-result`**
+   完成：列出改动的 seam，没有顺手做下一张任务。
+
+## 规则
+
+- 一次一条。下一条是下一轮 red。
+- Mock 是最后手段。能用真实对象、内存 fake 或 Test Gate 就不要 mock。
+- 缺完整 Test Gate、红测不是 assertion、或路径越界：停止并报告阻塞。

package/resources/workflows/documentation-delivery/workflow.yaml

@@ -8,11 +8,13 @@ inputs:
 steps:
   - id: intake
     uses: connector.execute
+    workspace: read-only
     action: requirement.capture
     inputs: [requirement-source]
     outputs: [requirement-source]
   - id: explore
     uses: agent.execute
+    workspace: read-only
     needs: [intake]
     inputs: [requirement-source]
     skills:
@@ -21,6 +23,7 @@ steps:
     outputs: [documentation-context]
   - id: clarify
     uses: agent.execute
+    workspace: read-only
     needs: [explore]
     inputs: [documentation-context]
     skills:
@@ -29,6 +32,7 @@ steps:
     outputs: [specification]
   - id: plan
     uses: agent.execute
+    workspace: read-only
     needs: [clarify]
     inputs: [specification]
     skills:
@@ -37,6 +41,7 @@ steps:
     outputs: [tasks]
   - id: edit-document
     uses: agent.execute
+    workspace: isolated-worktree
     actorRole: implementation
     needs: [plan]
     inputs: [tasks]
@@ -46,12 +51,14 @@ steps:
     outputs: [documentation-result]
   - id: verify-document
     uses: command.execute
+    workspace: isolated-worktree
     action: quality.docs.integrity
     needs: [edit-document]
     inputs: [documentation-result]
     outputs: [documentation-evidence]
   - id: review-fix
     uses: control.loop
+    workspace: isolated-worktree
     needs: [verify-document]
     inputs: [documentation-evidence]
     until: ${artifacts.review-result.approved}
@@ -59,6 +66,7 @@ steps:
     steps:
       - id: review
         uses: agent.execute
+        workspace: isolated-worktree
         actorRole: review
         skills:
           - ref: builtin://skills/documentation-review
@@ -66,6 +74,7 @@ steps:
         outputs: [review-result]
       - id: fix
         uses: agent.execute
+        workspace: isolated-worktree
         actorRole: fix
         when: ${artifacts.review-result.approved == false}
         skills:
@@ -73,32 +82,38 @@ steps:
             required: true
       - id: verify
         uses: command.execute
+        workspace: isolated-worktree
         action: quality.docs.integrity
   - id: commit
     uses: connector.execute
+    workspace: isolated-worktree
     action: git.commit
     needs: [review-fix]
     approval: required
   - id: update-issue
     uses: connector.execute
+    workspace: read-only
     action: issue.update
     needs: [commit]
     inputs: [documentation-result]
     when: ${bindings.issue.exists}
   - id: update-wiki
     uses: connector.execute
+    workspace: read-only
     action: knowledge.publish
     needs: [update-issue]
     inputs: [documentation-result]
     when: ${bindings.knowledge.exists}
   - id: close-issue
     uses: connector.execute
+    workspace: read-only
     action: issue.close
     needs: [update-wiki]
     when: ${bindings.issue.exists}
     approval: required
   - id: close
     uses: control.close
+    workspace: read-only
     needs: [close-issue]
 gates:
   - id: docs.integrity

package/resources/workflows/feature-delivery/workflow.yaml

@@ -8,11 +8,13 @@ inputs:
 steps:
   - id: intake
     uses: connector.execute
+    workspace: read-only
     action: requirement.capture
     inputs: [requirement-source]
     outputs: [requirement-source]
   - id: explore
     uses: agent.execute
+    workspace: read-only
     needs: [intake]
     inputs: [requirement-source]
     objective: 探索代码并提取需求相关约束
@@ -22,6 +24,7 @@ steps:
     outputs: [exploration-report]
   - id: clarify
     uses: agent.execute
+    workspace: read-only
     needs: [explore]
     inputs: [exploration-report]
     objective: 澄清需求并生成可验收规格
@@ -32,6 +35,7 @@ steps:
     approval: required
   - id: design
     uses: agent.execute
+    workspace: read-only
     needs: [clarify]
     inputs: [specification]
     objective: 形成可实施的技术方案
@@ -42,6 +46,7 @@ steps:
     approval: required
   - id: plan
     uses: agent.execute
+    workspace: read-only
     needs: [clarify, design]
     objective: 将设计拆分为可验证任务
     skills:
@@ -55,6 +60,7 @@ steps:
         required: false
   - id: write-tests
     uses: agent.execute
+    workspace: isolated-worktree
     needs: [plan]
     inputs: [tasks]
     objective: 根据当前任务先编写能够因缺少功能而失败的测试
@@ -64,6 +70,7 @@ steps:
     outputs: [red-test-result]
   - id: verify-red
     uses: command.execute
+    workspace: isolated-worktree
     action: quality.test
     expectedOutcome: test-failure
     needs: [write-tests]
@@ -71,6 +78,7 @@ steps:
     outputs: [red-evidence]
   - id: implement
     uses: agent.execute
+    workspace: isolated-worktree
     actorRole: implementation
     needs: [verify-red]
     inputs: [tasks]
@@ -81,6 +89,7 @@ steps:
     outputs: [implementation-result]
   - id: verify-green
     uses: command.execute
+    workspace: isolated-worktree
     action: quality.test
     expectedOutcome: success
     needs: [implement]
@@ -88,12 +97,14 @@ steps:
     outputs: [tdd-evidence]
   - id: review-fix
     uses: control.loop
+    workspace: isolated-worktree
     needs: [verify-green]
     until: ${artifacts.review-result.approved}
     maxIterations: 5
     steps:
       - id: review
         uses: agent.execute
+        workspace: isolated-worktree
         actorRole: review
         skills:
           - ref: builtin://skills/code-review
@@ -101,6 +112,7 @@ steps:
         outputs: [review-result]
       - id: fix
         uses: agent.execute
+        workspace: isolated-worktree
         actorRole: fix
         when: ${artifacts.review-result.approved == false}
         skills:
@@ -108,32 +120,38 @@ steps:
             required: true
       - id: verify
         uses: command.execute
+        workspace: isolated-worktree
         action: quality.verify
   - id: commit
     uses: connector.execute
+    workspace: isolated-worktree
     action: git.commit
     needs: [review-fix]
     approval: required
   - id: update-issue
     uses: connector.execute
+    workspace: read-only
     action: issue.update
     needs: [commit]
     inputs: [implementation-result]
     when: ${bindings.issue.exists}
   - id: update-wiki
     uses: connector.execute
+    workspace: read-only
     action: knowledge.publish
     needs: [update-issue]
     inputs: [implementation-result]
     when: ${bindings.knowledge.exists}
   - id: close-issue
     uses: connector.execute
+    workspace: read-only
     action: issue.close
     needs: [update-wiki]
     when: ${bindings.issue.exists}
     approval: required
   - id: close
     uses: control.close
+    workspace: read-only
     needs: [close-issue]
 gates:
   - id: test

package/schemas/builtin-agent-action-v1.schema.json

@@ -21,6 +21,7 @@
             "workItemId",
             "stepId",
             "attemptId",
+            "workspace",
             "lease",
             "objective",
             "skills",
@@ -46,6 +47,25 @@
               "type": "string",
               "pattern": "^attempt-.+$"
             },
+            "workspace": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "mode",
+                "materialized"
+              ],
+              "properties": {
+                "mode": {
+                  "enum": [
+                    "read-only",
+                    "isolated-worktree"
+                  ]
+                },
+                "materialized": {
+                  "type": "boolean"
+                }
+              }
+            },
             "lease": {
               "type": "object",
               "additionalProperties": false,

package/schemas/builtin-work-item-v1.schema.json

@@ -58,8 +58,7 @@
         "baselineRevision",
         "baselineTreeDigest",
         "workflowDigest",
-        "configDigest",
-        "schemaDigest"
+        "configDigest"
       ],
       "properties": {
         "worktree": {
@@ -70,6 +69,9 @@
           "type": "string",
           "minLength": 1
         },
+        "materialized": {
+          "type": "boolean"
+        },
         "baselineRevision": {
           "type": "string",
           "minLength": 1

package/schemas/builtin-work-package-v1.schema.json

@@ -8,6 +8,7 @@
     "workItemId",
     "stepId",
     "attemptId",
+    "workspace",
     "lease",
     "objective",
     "skills",
@@ -33,6 +34,25 @@
       "type": "string",
       "pattern": "^attempt-.+$"
     },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode",
+        "materialized"
+      ],
+      "properties": {
+        "mode": {
+          "enum": [
+            "read-only",
+            "isolated-worktree"
+          ]
+        },
+        "materialized": {
+          "type": "boolean"
+        }
+      }
+    },
     "lease": {
       "type": "object",
       "additionalProperties": false,