ws-spec-kit 0.1.0-beta.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "ws-spec-kit",
+  "version": "0.1.0-beta.0",
+  "description": "由 Agent Skill 驱动的可定制软件交付工作流引擎",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "wspec": "./dist/cli/main.js"
+  },
+  "files": [
+    "dist",
+    "resources",
+    "schemas",
+    "LICENSE"
+  ],
+  "exports": {
+    "./resources/catalog": "./dist/resources/catalog.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test tests/**/*.test.ts",
+    "test:contract": "node --import tsx --test tests/contract/**/*.test.ts",
+    "test:e2e": "node --import tsx --test tests/e2e/**/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "schemas:generate": "tsx src/schemas/generate.ts schemas"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "canonicalize": "^2.1.0",
+    "ulid": "^3.0.2",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "tsx": "^4.23.12",
+    "typescript": "^5.9.3"
+  }
+}

package/resources/catalog.yaml

@@ -0,0 +1,37 @@
+version: 1
+workflows:
+  - feature-delivery
+  - documentation-delivery
+connectors:
+  - git-native
+  - github-cli
+  - gitlab-cli
+  - lark-cli
+skills:
+  - id: requirement-exploration
+    version: 1.0.0
+    description: 探索代码并澄清功能需求
+  - id: solution-design
+    version: 1.0.0
+    description: 编写可实施的技术方案
+  - id: task-planning
+    version: 1.0.0
+    description: 将方案拆分为可验证任务
+  - id: tdd-implementation
+    version: 1.0.0
+    description: 以测试驱动方式实现任务
+  - id: code-review
+    version: 1.0.0
+    description: 审查实现缺陷与需求偏差
+  - id: bug-fixing
+    version: 1.0.0
+    description: 修复审查发现并重新验证
+  - id: documentation-exploration
+    version: 1.0.0
+    description: 探索文档现状和事实来源
+  - id: documentation-editing
+    version: 1.0.0
+    description: 按事实编辑中文文档
+  - id: documentation-review
+    version: 1.0.0
+    description: 审查文档准确性和完整性

package/resources/connectors/github-cli.yaml

@@ -0,0 +1,24 @@
+id: github-cli
+capabilities: [github.issue, issue.read, issue.write, issue.close]
+securityClass: external-write
+executable: gh
+minimumVersion: 2.0.0
+argvTemplates:
+  - [api, --method, GET, "repos/{owner}/{repo}/issues/{number}", --hostname, "{host}"]
+  - [api, --method, GET, "repos/{owner}/{repo}/issues/comments/{commentId}", --hostname, "{host}"]
+  - [api, --method, POST, "repos/{owner}/{repo}/issues/{number}/comments", --hostname, "{host}", --input, "-"]
+  - [api, --method, PATCH, "repos/{owner}/{repo}/issues/{number}", --hostname, "{host}", --input, "-"]
+doctor:
+  version:
+    kind: version
+    argv: [--version]
+    parser: { kind: text-semver }
+  auth:
+    kind: auth
+    argv: [auth, status, --active]
+    parser: { kind: exit-code }
+    outcomes: { authenticated: [0], unauthenticated: [1] }
+envPolicy:
+  allow: [HOME, XDG_CONFIG_HOME, GH_CONFIG_DIR]
+timeoutMs: 30000
+maxStdoutBytes: 1048576

package/resources/connectors/gitlab-cli.yaml

@@ -0,0 +1,24 @@
+id: gitlab-cli
+capabilities: [gitlab.issue, issue.read, issue.write, issue.close]
+securityClass: external-write
+executable: glab
+minimumVersion: 1.0.0
+argvTemplates:
+  - [api, --method, GET, "projects/{encodedPath}/issues/{iid}", --hostname, "{host}"]
+  - [api, --method, GET, "projects/{encodedPath}/issues/{iid}/notes/{noteId}", --hostname, "{host}"]
+  - [api, --method, POST, "projects/{encodedPath}/issues/{iid}/notes", --hostname, "{host}", --input, "-"]
+  - [api, --method, PUT, "projects/{encodedPath}/issues/{iid}", --hostname, "{host}", --input, "-"]
+doctor:
+  version:
+    kind: version
+    argv: [--version]
+    parser: { kind: text-semver }
+  auth:
+    kind: auth
+    argv: [auth, status]
+    parser: { kind: exit-code }
+    outcomes: { authenticated: [0], unauthenticated: [1] }
+envPolicy:
+  allow: [HOME, XDG_CONFIG_HOME, GLAB_CONFIG_DIR]
+timeoutMs: 30000
+maxStdoutBytes: 1048576

package/resources/connectors/lark-cli.yaml

@@ -0,0 +1,28 @@
+id: lark-cli
+capabilities:
+  - feishu.document
+  - document.read
+  - knowledge.publish
+securityClass: external-write
+executable: lark-cli
+minimumVersion: 1.0.0
+argvTemplates:
+  - [docs, +fetch, --doc, "{documentToken}", --format, json, --as, "{identity}"]
+  - [docs, +fetch, --doc, "{documentToken}", --offset, "{offset}", --limit, "100", --format, json, --as, "{identity}"]
+  - [docs, +create, --title, "{title}", --folder-token, "{folderToken}", --markdown, "{markdown}", --as, "{identity}"]
+  - [docs, +create, --title, "{title}", --wiki-node, "{wikiNode}", --markdown, "{markdown}", --as, "{identity}"]
+  - [docs, +create, --title, "{title}", --wiki-space, "{wikiSpace}", --markdown, "{markdown}", --as, "{identity}"]
+  - [docs, +update, --doc, "{documentToken}", --mode, overwrite, --markdown, "{markdown}", --new-title, "{title}", --as, "{identity}"]
+doctor:
+  version:
+    kind: version
+    argv: [--version]
+    parser:
+      kind: text-semver
+  auth:
+    kind: unavailable
+    reasonCode: WSSPEC_CONNECTOR_AUTH_PROBE_UNAVAILABLE
+envPolicy:
+  allow: [HOME, XDG_CONFIG_HOME, LARK_CONFIG_DIR]
+timeoutMs: 30000
+maxStdoutBytes: 1048576

package/resources/skills/bug-fixing/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: bug-fixing
+description: 修复审查问题
+---
+
+# 修复审查问题
+
+目标：修复审查问题。
+
+输入：有效 Review Finding。
+
+输出：修复及回归证据。
+
+停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+
+禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。

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

@@ -0,0 +1,16 @@
+---
+name: code-review
+description: 审查代码实现
+---
+
+# 审查代码实现
+
+目标：审查代码实现。
+
+输入：需求、方案、变更和验证证据。
+
+输出：按严重级别排序的问题。
+
+停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+
+禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。

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

@@ -0,0 +1,16 @@
+---
+name: documentation-editing
+description: 编辑中文文档
+---
+
+# 编辑中文文档
+
+目标：编辑中文文档。
+
+输入：事实清单和文档目标。
+
+输出：准确、完整的文档变更。
+
+停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+
+禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。

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

@@ -0,0 +1,16 @@
+---
+name: documentation-exploration
+description: 探索文档事实
+---
+
+# 探索文档事实
+
+目标：探索文档事实。
+
+输入：文档目标和仓库事实。
+
+输出：事实清单与文档范围。
+
+停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+
+禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。

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

@@ -0,0 +1,16 @@
+---
+name: documentation-review
+description: 审查文档质量
+---
+
+# 审查文档质量
+
+目标：审查文档质量。
+
+输入：文档变更和事实来源。
+
+输出：准确性、完整性审查结果。
+
+停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+
+禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。

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

@@ -0,0 +1,16 @@
+---
+name: requirement-exploration
+description: 探索代码与需求
+---
+
+# 探索代码与需求
+
+目标：探索代码与需求。
+
+输入：需求描述和仓库状态。
+
+输出：澄清问题与需求规格。
+
+停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+
+禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。

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

@@ -0,0 +1,16 @@
+---
+name: solution-design
+description: 设计技术方案
+---
+
+# 设计技术方案
+
+目标：设计技术方案。
+
+输入：已确认需求和代码事实。
+
+输出：方案文档与取舍。
+
+停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+
+禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。

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

@@ -0,0 +1,16 @@
+---
+name: task-planning
+description: 拆分实施任务
+---
+
+# 拆分实施任务
+
+目标：拆分实施任务。
+
+输入：批准方案。
+
+输出：按依赖排序的可验证任务。
+
+停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+
+禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。

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

@@ -0,0 +1,16 @@
+---
+name: tdd-implementation
+description: 执行测试驱动实现
+---
+
+# 执行测试驱动实现
+
+目标：执行测试驱动实现。
+
+输入：当前任务和验收条件。
+
+输出：Red、Green 与实现结果。
+
+停止条件：缺少必要事实、授权或前置产物时停止并报告阻塞。
+
+禁止副作用：不得自行提交、推送、写入外部系统或扩大允许修改路径。

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

@@ -0,0 +1,8 @@
+version: 1
+id: documentation-delivery
+description: 纯文档交付工作流
+profiles: [quick, standard, governed]
+entry: workflow.yaml
+capabilities: [agent-execution, command-execution, connector-execution, control-flow]
+externalSideEffects: [git-commit, issue-update, knowledge-publish, issue-close]
+connectors: [requirement, git, issue, knowledge]

package/resources/workflows/documentation-delivery/profiles/governed.yaml

@@ -0,0 +1,23 @@
+version: 1
+profile:
+  id: governed
+  workflow: documentation-delivery
+steps:
+  clarify:
+    approval: true
+    artifacts:
+      specification: { required: true, contentLevel: complete }
+  plan:
+    approval: true
+    artifacts:
+      tasks: { required: true, contentLevel: complete }
+  review-fix: { maxIterations: 5, independentReviewActor: true }
+  verify-document: { gates: [docs.integrity] }
+publishing: { issueRequired: true, knowledgeRequired: true, readBackRequired: true }
+audit:
+  level: complete
+  retention: extended
+  recordDecisions: true
+  recordApprovals: true
+  recordActors: true
+  recordPublishing: true

package/resources/workflows/documentation-delivery/profiles/quick.yaml

@@ -0,0 +1,23 @@
+version: 1
+profile:
+  id: quick
+  workflow: documentation-delivery
+steps:
+  clarify:
+    artifactLevel: compact
+    artifacts:
+      specification: { required: true, contentLevel: compact }
+  plan:
+    artifactLevel: compact
+    artifacts:
+      tasks: { required: true, contentLevel: compact }
+  review-fix: { maxIterations: 1 }
+  verify-document: { gates: [docs.integrity] }
+publishing: { issueRequired: false, knowledgeRequired: false, readBackRequired: false }
+audit:
+  level: standard
+  retention: standard
+  recordDecisions: false
+  recordApprovals: false
+  recordActors: false
+  recordPublishing: false

package/resources/workflows/documentation-delivery/profiles/standard.yaml

@@ -0,0 +1,21 @@
+version: 1
+profile:
+  id: standard
+  workflow: documentation-delivery
+steps:
+  clarify:
+    artifacts:
+      specification: { required: true, contentLevel: complete }
+  plan:
+    artifacts:
+      tasks: { required: true, contentLevel: complete }
+  review-fix: { maxIterations: 5 }
+  verify-document: { gates: [docs.integrity] }
+publishing: { issueRequired: false, knowledgeRequired: false, readBackRequired: false }
+audit:
+  level: standard
+  retention: standard
+  recordDecisions: false
+  recordApprovals: false
+  recordActors: false
+  recordPublishing: false

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

@@ -0,0 +1,109 @@
+version: 1
+workflow:
+  id: documentation-delivery
+  version: 1
+inputs:
+  requirement:
+    accepts: [user.prompt, local.file, github.issue, gitlab.issue, feishu.document]
+steps:
+  - id: intake
+    uses: connector.execute
+    action: requirement.capture
+    inputs: [requirement-source]
+    outputs: [requirement-source]
+  - id: explore
+    uses: agent.execute
+    needs: [intake]
+    inputs: [requirement-source]
+    skills:
+      - ref: builtin://skills/documentation-exploration
+        required: true
+    outputs: [documentation-context]
+  - id: clarify
+    uses: agent.execute
+    needs: [explore]
+    inputs: [documentation-context]
+    skills:
+      - ref: builtin://skills/requirement-exploration
+        required: true
+    outputs: [specification]
+  - id: plan
+    uses: agent.execute
+    needs: [clarify]
+    inputs: [specification]
+    skills:
+      - ref: builtin://skills/task-planning
+        required: true
+    outputs: [tasks]
+  - id: edit-document
+    uses: agent.execute
+    actorRole: implementation
+    needs: [plan]
+    inputs: [tasks]
+    skills:
+      - ref: builtin://skills/documentation-editing
+        required: true
+    outputs: [documentation-result]
+  - id: verify-document
+    uses: command.execute
+    action: quality.docs.integrity
+    needs: [edit-document]
+    inputs: [documentation-result]
+    outputs: [documentation-evidence]
+  - id: review-fix
+    uses: control.loop
+    needs: [verify-document]
+    inputs: [documentation-evidence]
+    until: ${artifacts.review-result.approved}
+    maxIterations: 5
+    steps:
+      - id: review
+        uses: agent.execute
+        actorRole: review
+        skills:
+          - ref: builtin://skills/documentation-review
+            required: true
+        outputs: [review-result]
+      - id: fix
+        uses: agent.execute
+        actorRole: fix
+        when: ${artifacts.review-result.approved == false}
+        skills:
+          - ref: builtin://skills/documentation-editing
+            required: true
+      - id: verify
+        uses: command.execute
+        action: quality.docs.integrity
+  - id: commit
+    uses: connector.execute
+    action: git.commit
+    needs: [review-fix]
+    approval: required
+  - id: update-issue
+    uses: connector.execute
+    action: issue.update
+    needs: [commit]
+    inputs: [documentation-result]
+    when: ${bindings.issue.exists}
+  - id: update-wiki
+    uses: connector.execute
+    action: knowledge.publish
+    needs: [update-issue]
+    inputs: [documentation-result]
+    when: ${bindings.knowledge.exists}
+  - id: close-issue
+    uses: connector.execute
+    action: issue.close
+    needs: [update-wiki]
+    when: ${bindings.issue.exists}
+    approval: required
+  - id: close
+    uses: control.close
+    needs: [close-issue]
+gates:
+  - id: docs.integrity
+    evidence: trusted
+    command: [wspec, gate, docs.integrity]
+changePolicy:
+  kind: documentation-only
+  allowedPaths: ["README*.md", "CHANGELOG*.md", "docs/**/*.md", "docs/**/*.mdx", "docs/**/*.txt"]

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

@@ -0,0 +1,8 @@
+version: 1
+id: feature-delivery
+description: 基础功能交付工作流
+profiles: [quick, standard, governed]
+entry: workflow.yaml
+capabilities: [agent-execution, command-execution, connector-execution, control-flow]
+externalSideEffects: [git-commit, issue-update, knowledge-publish, issue-close]
+connectors: [requirement, git, issue, knowledge]

package/resources/workflows/feature-delivery/profiles/governed.yaml

@@ -0,0 +1,27 @@
+version: 1
+profile:
+  id: governed
+  workflow: feature-delivery
+steps:
+  clarify:
+    approval: true
+    artifacts:
+      specification: { required: true, contentLevel: complete }
+  design:
+    approval: true
+    artifacts:
+      design: { required: true, contentLevel: complete }
+  plan:
+    approval: true
+    artifacts:
+      tasks: { required: true, contentLevel: complete }
+  review-fix: { maxIterations: 5, independentReviewActor: true }
+  verify-green: { gates: [test] }
+publishing: { issueRequired: true, knowledgeRequired: true, readBackRequired: true }
+audit:
+  level: complete
+  retention: extended
+  recordDecisions: true
+  recordApprovals: true
+  recordActors: true
+  recordPublishing: true

package/resources/workflows/feature-delivery/profiles/quick.yaml

@@ -0,0 +1,25 @@
+version: 1
+profile:
+  id: quick
+  workflow: feature-delivery
+steps:
+  clarify:
+    approval: false
+    artifactLevel: compact
+    artifacts:
+      specification: { required: true, contentLevel: compact }
+  design: { enabled: false }
+  plan:
+    artifactLevel: compact
+    artifacts:
+      tasks: { required: true, contentLevel: compact }
+  review-fix: { maxIterations: 1 }
+  verify-green: { gates: [test] }
+publishing: { issueRequired: false, knowledgeRequired: false, readBackRequired: false }
+audit:
+  level: standard
+  retention: standard
+  recordDecisions: false
+  recordApprovals: false
+  recordActors: false
+  recordPublishing: false

package/resources/workflows/feature-delivery/profiles/standard.yaml

@@ -0,0 +1,26 @@
+version: 1
+profile:
+  id: standard
+  workflow: feature-delivery
+steps:
+  clarify:
+    approval: true
+    artifacts:
+      specification: { required: true, contentLevel: complete }
+  design:
+    approval: true
+    artifacts:
+      design: { required: true, contentLevel: complete }
+  plan:
+    artifacts:
+      tasks: { required: true, contentLevel: complete }
+  review-fix: { maxIterations: 5 }
+  verify-green: { gates: [test] }
+publishing: { issueRequired: false, knowledgeRequired: false, readBackRequired: false }
+audit:
+  level: standard
+  retention: standard
+  recordDecisions: false
+  recordApprovals: false
+  recordActors: false
+  recordPublishing: false