@trench-craft/sds 1.0.0

package/skills/core/opsx-archive/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: opsx-archive
+description: "Archive completed changes from changes/ to archive/. Final phase of the SDS workflow."
+---
+
+# opsx:archive — 归档变更
+
+## 触发条件
+
+**触发**：
+- opsx:verify 已通过，变更已验证完成
+- 用户说"归档"、"完成"、"收尾"
+
+**不触发**：
+- ❌ 任何非开发类对话
+- ❌ verify 尚未通过
+
+将已完成的变更从 `openspec/changes/<name>/` 移动到 `openspec/archive/`，保留历史记录。
+
+## SDS Workflow 位置
+
+**Phase 6** — 归档交付（最终阶段）
+
+```
+Phase 5          Phase 6
+opsx:verify  →   opsx:archive
+                  │
+                  └── openspec/archive/{date}-{name}/
+```
+
+## 输入
+
+- `openspec/changes/<name>/`：已完成验证的变更目录（含所有工件）
+
+## 输出
+
+- `openspec/archive/{date}-{name}/`：归档后的变更目录
+
+## 流程
+
+### 1. 前置检查
+
+- [ ] verify.md 是否存在？
+- [ ] verify.md 中所有 7 项检查是否通过？
+- [ ] 所有代码是否已 commit？
+
+如果 verify 未通过 → **退回 opsx:verify 修复**，不能归档未通过的变更。
+
+### 2. 执行归档
+
+```bash
+# 创建归档目录
+mkdir -p openspec/archive/{date}-{name}/
+
+# 复制变更工件
+cp -r openspec/changes/{name}/* openspec/archive/{date}-{name}/
+
+# 移除原变更
+rm -rf openspec/changes/{name}
+```
+
+### 3. 更新归档索引
+
+更新 `openspec/archive/INDEX.md`（如存在）：
+
+```markdown
+| 日期 | 名称 | 描述 | 验证状态 |
+|------|------|------|----------|
+| 2026-05-13 | login-feature | 用户登录功能 | ✅ 通过 |
+```
+
+### 4. 通知用户
+
+归档完成通知，包含：
+- 变更摘要
+- 归档路径
+- 可用的清理选项（如删除分支）
+
+## 要点
+
+- **仅归档已验证的变更** — verify 通过是前置条件
+- **保留完整历史** — 所有工件（含 verify.md）一同归档
+- **不删除代码** — 归档仅移动文档工件，不删除业务代码

package/skills/core/opsx-archive/skill.yaml

@@ -0,0 +1,12 @@
+id: "opsx:archive"
+version: "2.0.0"
+name: "archive-changes"
+description: "将变更归档到 archive 目录"
+category: "core"
+phase: "phase-6"
+source: "openspec"
+dependencies: ["opsx:verify"]
+inputs: ["openspec/changes/{name}/"]
+outputs: ["openspec/archive/{date}-{name}/"]
+size: "small"
+cache_ttl: "30d"

package/skills/core/opsx-explore/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: opsx-explore
+description: "Deep codebase exploration — investigate problems, map architecture, gather context before making changes. Phase 0 of the SDS workflow. Use when entering a new project or exploring unfamiliar code."
+---
+
+# opsx:explore — 深度探索
+
+Deep codebase exploration mode. Investigate problems, map architecture, gather context.
+
+## SDS Workflow 位置
+
+**Phase 0** — 上下文感知阶段
+- 输入: 用户的问题或探索方向
+- 输出: 探索报告（可用作 brainstorming 的输入）
+
+```
+Phase 0          Phase 1        Phase 2         Phase 3
+opsx:explore  →  brainstorming → opsx:propose → writing-plans
+↓
+探索报告
+```
+
+## 触发条件
+
+**触发**：
+- 用户说"帮我看看..."、"分析一下..."、"这个项目是做什么的"
+- 需要了解现有代码库特定模块时
+- **项目非空**（存在 package.json、源码目录等）
+
+**不触发**：
+- ❌ 项目为空（无任何代码文件）→ 直接跳转到 Phase 1 brainstorming
+- ❌ 问候、闲聊、概念问答
+
+## 空项目检测
+
+开始探索前，先检查项目是否为空：
+
+```bash
+# 检测是否有源码文件
+dir /s /b *.js *.ts *.py *.go *.rs *.java 2>nul | find /c /v ""
+```
+
+如果项目为空（或仅含配置文件）：
+1. **跳过 Phase 0 探索**
+2. **直接进入 Phase 1 brainstorming**
+3. 通知用户："项目为空，跳过代码探索阶段，直接进行需求分析"
+
+## 流程
+
+### 1. 理解探索目标
+
+明确用户想了解什么：现有代码库、技术方案评估、问题诊断？
+
+### 2. 并行探索
+
+对 2+ 个独立方向，必须使用 explore agent + `run_in_background=true`：
+
+```typescript
+task(subagent_type="explore", run_in_background=true, description="...", prompt="...")
+task(subagent_type="explore", run_in_background=true, description="...", prompt="...")
+```
+
+**后台任务验证规则**:
+- `<system-reminder>` 通知完成 → 调用 `background_output(task_id="...")`
+- 输出含 `not found`、`IO error` 等 → 任务失败，重试
+- 输出含实际数据 → 真正完成
+
+### 3. 结构化输出
+
+探索结果至少包含：
+
+```
+## 探索结果: <主题>
+
+### 架构概览
+ASCII 图表展示模块关系、数据流
+
+### 文件映射
+| 功能 | 文件 | 行号 |
+|------|------|------|
+| xxx | path/to/file.js | 10-30 |
+
+### 关键发现
+- 技术栈: React 18 + Express 4 + PostgreSQL
+- 模块数: 6 个核心模块
+- 风险: <发现的任何问题>
+
+### 建议
+- <对接下来的 brainstorming/设计阶段的建议>
+```
+
+## 输出格式
+
+探索结果直接展示给用户，同时可保存到 `openspec/explore-output.md`（可选）供后续阶段使用。
+
+## 要点
+
+- **只读** — 探索阶段不修改任何文件
+- **可视化** — 多用 ASCII 图表，帮助理解
+- **不急于结论** — 探索是思考时间，不是任务时间
+- **并行** — 独立方向必须并行搜索

package/skills/core/opsx-explore/skill.yaml

@@ -0,0 +1,12 @@
+id: "opsx:explore"
+version: "2.0.0"
+name: "deep-explore"
+description: "扫描项目结构和依赖关系"
+category: "core"
+phase: "phase-0"
+source: "openspec"
+dependencies: []
+inputs: []
+outputs: ["openspec/explore-output.md"]
+size: "medium"
+cache_ttl: "30d"

package/skills/core/opsx-propose/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: opsx-propose
+description: "Generate all four OpenSpec artifacts (proposal, design, specs, tasks) from user requirements. Phase 2 of the SDS workflow."
+---
+
+# opsx:propose — 生成 4 份工件
+
+从用户需求生成 proposal、design、specs、tasks 四份标准化工件。
+
+## 触发条件
+
+**触发**：
+- 用户已批准设计方案（来自 brainstorming 阶段的用户确认，或直接调用）
+- 用户主动调用 `opsx:propose` 或 `generate-artifacts`
+
+**不触发**：
+- ❌ 任何非开发类对话
+- ❌ 用户尚未明确需求或设计方案时
+- ❌ 用户还在澄清需求阶段
+
+> ⚠️ **这 4 份工件均为强制性产出。** 必须全部生成，缺一不可，不可跳过。
+
+## SDS Workflow 位置
+
+**Phase 2** — 规范建档阶段
+
+```
+Phase 1          Phase 2              Phase 3
+brainstorming →  opsx:propose     →  writing-plans
+                 ├── proposal.md
+                 ├── design.md
+                 ├── specs.md
+                 └── tasks.md
+```
+
+## 输入
+
+- `user_request`：经过 brainstorming 收敛的用户需求
+- `brainstorming.md`（可选）：brainstorming 阶段的输出
+
+## 输出（4 份工件）
+
+所有工件写入 `openspec/changes/<name>/` 目录：
+
+| 工件 | 内容 | 用途 |
+|------|------|------|
+| `proposal.md` | 背景、目标、范围、技术选型 | 明确做什么、为什么做 |
+| `design.md` | 架构图、接口定义、数据模型、安全设计 | 技术方案决策 |
+| `specs.md` | 功能规格、非功能规格、验收标准 | 定义"做成什么样" |
+| `tasks.md` | 任务列表、依赖关系、预估时间 | 可执行的开发计划 |
+
+## 流程
+
+### 1. 创建变更目录
+
+```bash
+mkdir -p openspec/changes/<name>/
+```
+
+### 2. 生成 proposal.md
+
+包含：背景、目标、范围（包含/不包含）、技术选型表、交付物清单
+
+```markdown
+## 背景
+[为什么要做这个变更]
+
+## 目标
+- [具体目标 1]
+- [具体目标 2]
+
+## 范围
+### 包含
+- [功能 1]
+### 不包含
+- [功能 2]
+
+## 技术选型
+| 层级 | 技术 | 理由 |
+```
+
+### 3. 生成 design.md
+
+包含：架构概览（ASCII 图）、数据模型、接口定义、安全设计
+
+```markdown
+## 架构概览
+```
+请求 → Router → Middleware → Controller → Service → DB
+```
+
+## API 接口
+### POST /api/login
+- Request: `{ username, password }`
+- Response 200: `{ token, user }`
+- Response 401: `{ message }`
+```
+
+### 4. 生成 specs.md
+
+包含：功能规格（用户场景）、非功能规格、验收标准
+
+```markdown
+## F1: 用户登录
+- 输入: 用户名、密码
+- 行为: 验证凭据 → 签发 Token → 返回用户信息
+- 验证: 用户名密码不能为空
+- 错误: 凭据错误时提示"用户名或密码错误"
+```
+
+### 5. 生成 tasks.md
+
+包含：任务列表、依赖关系图、验收契约
+
+```markdown
+## 依赖关系
+T1 (初始化) → T2 (后端 API) + T3 (前端模块) → T4 (页面) → T5 (测试)
+
+## 任务
+### T1: 项目初始化
+- [ ] 初始化 Express 项目
+- [ ] 安装依赖
+- 预估: 15min
+```
+
+## 要点
+
+- ⚠️ **缺一不可** — proposal、design、specs、tasks 4 份必须全部生成，每份都必须有实质内容
+- **依赖 brainstorming** — 不要在需求不明确时生成工件
+- **验收标准必须可测试** — 每个功能要有明确的通过/不通过标准
+- **任务粒度** — 每个任务独立可执行，2-5 分钟一个步骤

package/skills/core/opsx-propose/skill.yaml

@@ -0,0 +1,16 @@
+id: "opsx:propose"
+version: "2.0.0"
+name: "generate-artifacts"
+description: "从 user_request 生成 proposal/design/specs/tasks 四份标准化工件"
+category: "core"
+phase: "phase-2"
+source: "openspec"
+dependencies: ["brainstorming"]
+inputs: ["user_request"]
+outputs:
+  - "openspec/changes/{name}/proposal.md"
+  - "openspec/changes/{name}/design.md"
+  - "openspec/changes/{name}/specs.md"
+  - "openspec/changes/{name}/tasks.md"
+size: "medium"
+cache_ttl: "30d"

package/skills/core/opsx-verify/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: opsx-verify
+description: "Run 7 quality checks on completed changes: compile, tests, spec alignment, completeness, code quality, docs, breaking changes. Phase 5 of the SDS workflow."
+---
+
+# opsx:verify — 验证变更
+
+## 触发条件
+
+**触发**：
+- opsx:apply 已完成，代码变更已就绪
+- 用户说"验证"、"检查"、"测试"
+
+**不触发**：
+- ❌ 任何非开发类对话
+- ❌ 实现尚未完成
+
+通过 7 项检查验证变更质量，确保变更符合预期。
+
+## SDS Workflow 位置
+
+**Phase 5** — 质量门阶段
+
+```
+Phase 4          Phase 5            Phase 6
+opsx:apply   →   opsx:verify    →  opsx:archive
+                 │
+                 └── verify.md（验证报告）
+```
+
+## 输入
+
+- `openspec/changes/<name>/` 下的所有工件
+- 变更代码
+
+## 输出
+
+- `openspec/changes/<name>/verify.md`：验证报告
+
+## 7 项检查清单
+
+### 1. 编译检查
+```bash
+# TypeScript
+npx tsc --noEmit
+
+# 或其它语言
+go build ./...
+npm run build
+```
+✅ 通过 / ❌ 失败
+
+### 2. 测试检查
+```bash
+npm test
+# 或 pytest / go test ./... / cargo test
+```
+✅ 全部通过 / ❌ 有失败测试
+
+### 3. 规格符合性
+- [ ] 所有 specs.md 中的功能需求是否已实现？
+- [ ] 验收标准是否全部满足？
+- [ ] 是否有多余的未在规格中定义的代码？（过度构建）
+
+### 4. 任务完整性
+- [ ] tasks.md 中的所有任务是否已完成？
+- [ ] 是否有未标记为完成的任务？
+
+### 5. 代码质量
+- [ ] LSP diagnostics 无错误
+- [ ] 无死代码、TODO、FIXME
+- [ ] 命名一致、遵循项目规范
+
+### 6. 文档同步
+- [ ] README 是否需要更新？
+- [ ] API 文档是否同步？
+- [ ] 环境变量是否已记录？
+
+### 7. Breaking Changes
+- [ ] API 向后兼容？
+- [ ] 配置格式有变？
+- [ ] 数据库迁移需要？
+
+## 验证报告格式
+
+```markdown
+# 验证报告: <name>
+
+## 结果: ✅ 通过 / ❌ 未通过
+
+| # | 检查项 | 状态 | 说明 |
+|---|--------|------|------|
+| 1 | 编译检查 | ✅ | tsc --noEmit 通过 |
+| 2 | 测试检查 | ✅ | 15/15 通过 |
+| 3 | 规格符合性 | ✅ | 全部实现 |
+| ... | ... | ... | ... |
+
+## 问题（如有）
+- [ ] <问题描述>
+
+## 备注
+<任何需要记录的额外信息>
+```
+
+## 要点
+
+- **全量检查** — 7 项都必须检查，不可跳过
+- **发现问题必须修复** — 修复后重新运行 verify
+- **规格偏离必须记录** — 如果实现偏离了规格，需说明原因

package/skills/core/opsx-verify/skill.yaml

@@ -0,0 +1,12 @@
+id: "opsx:verify"
+version: "2.0.0"
+name: "verify-changes"
+description: "7 项检查验证变更质量"
+category: "core"
+phase: "phase-5"
+source: "openspec"
+dependencies: ["opsx:apply"]
+inputs: ["openspec/changes/{name}/"]
+outputs: ["openspec/changes/{name}/verify.md"]
+size: "medium"
+cache_ttl: "7d"

package/skills/core/subagent-driven-development/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: subagent-driven-development
+description: "通过为每个任务分派独立的子代理来执行实现计划，每个任务完成后进行两阶段审查。当 plan.md 就绪且任务可独立执行时使用。"
+---
+
+# Subagent-Driven Development
+
+## 触发条件
+
+**触发**：
+- opsx:apply 阶段选择了子代理执行方式
+- plan.md 或 plan/ 目录已就绪，任务可独立执行
+- 用户明确要求"用子代理执行"
+
+**不触发**：
+- ❌ 任何非开发类对话
+- ❌ 计划尚未生成
+- ❌ 不需要并行执行的任务
+
+通过为每个任务分派一个全新的子代理来执行计划，每个任务完成后进行两阶段审查：先审查规格合规性，再审查代码质量。
+
+**为什么用子代理：** 你将任务委派给具有隔离上下文的专用代理。通过精心设计它们的指令和上下文，确保它们专注并成功完成任务。它们不应继承你的会话上下文或历史记录——你要精确构造它们所需的一切。这样也能为你自己保留用于协调工作的上下文。
+
+**核心原则：** 每个任务一个全新子代理 + 两阶段审查（先规格后质量）= 高质量、快速迭代
+
+## OpenSpec 工作流中的位置
+
+此技能在 OpenSpec worktree 中运行。在开始之前，worktree 已创建并包含了完整的规格上下文。
+
+支持两种计划格式：
+
+### 目录化计划（计划较大时）
+
+```
+openspec/changes/<name>/
+├── brainstorming.md  (Phase 1 产出)
+├── proposal.md       (Phase 2 产出)
+├── design.md         (Phase 2 产出)
+├── specs.md          (Phase 2 产出)
+├── tasks.md          (Phase 2 产出)
+└── plan/             (Phase 3 产出) ← 你在这里
+    ├── index.md      (执行顺序 + 状态)
+    ├── auth.md       (自包含：接口契约 + 任务)
+    └── user.md       (自包含：内联依赖接口)
+```
+
+### 单文件计划（默认）
+
+```
+openspec/changes/<name>/
+├── ...
+├── plan.md           (Phase 3 产出) ← 你在这里
+```
+
+## 何时使用
+
+- 有实现计划且任务基本独立时
+- 希望在当前会话中执行（无上下文切换）
+- 每个任务后需要两阶段审查
+
+## 流程
+
+### 单文件模式
+
+```
+读取 plan.md（全文自包含）
+↓
+记录项目上下文（specs、现有代码结构、命名约定）
+↓
+对每个任务：
+  提取任务文本（含接口契约 + 步骤 + 代码）
+  ↓
+  ┌─────────────────────────────────────────────┐
+  │ 分派实现子代理 (./implementer-prompt.md)      │
+  │ → 实现 → 测试 → TDD → 自审 → 提交             │
+  └─────────────────────────────────────────────┘
+  ↓ DONE
+  ┌───────────────────────────────────────────┐
+  │ 分派规格审查子代理 (./spec-reviewer-prompt.md) │
+  └───────────────────────────────────────────┘
+  ↓ 通过
+  ┌──────────────────────────────────────────────┐
+  │ 分派代码质量审查子代理 (./code-quality-reviewer)│
+  └──────────────────────────────────────────────┘
+  ↓ 通过
+  更新 plan.md 标记任务完成
+↓
+全部完成 → finishing-a-development-branch
+```
+
+### 目录化模式
+
+```
+读取 plan/index.md → 获取 chunk 执行顺序
+↓
+按顺序逐 chunk：
+  读取 plan/<chunk>.md（自包含，无需读其他 chunk）
+  ↓
+  对 chunk 内每个任务：
+    提取任务文本（含接口契约 + 步骤 + 代码）
+    ↓
+    [同单文件模式的子代理 → 审查 → 标记流程]
+  ↓
+  chunk 全部完成 → 更新 plan/index.md 状态
+↓
+全部完成 → finishing-a-development-branch
+```
+
+**关键：协调器处理每个 chunk 时，只读该 chunk 文件。不从其他 chunk 或 index.md 提取信息。每个 chunk 自包含所有执行所需信息。**
+
+## 处理实现者状态
+
+实现子代理报告四种状态之一：
+
+**DONE：** 进入规格合规性审查。
+
+**DONE_WITH_CONCERNS：** 实现者完成了工作但标记了疑虑。在继续之前阅读这些疑虑。如果涉及正确性或范围，在审查前解决。如果只是观察性说明，记录下来并继续审查。
+
+**NEEDS_CONTEXT：** 实现者需要未提供的信息。提供缺失的上下文并重新分派。
+
+**BLOCKED：** 实现者无法完成任务。评估阻塞原因：
+1. 如果是上下文问题，提供更多上下文并重新分派
+2. 如果任务需要更强的推理能力，用更强的模型重新分派
+3. 如果任务太大，拆分为更小的部分
+4. 如果计划本身有问题，上报给人类
+
+**绝不** 忽略上报或在不做任何更改的情况下让同一模型重试。
+
+## 提示词模板
+
+- `./implementer-prompt.md` — 分派实现子代理
+- `./spec-reviewer-prompt.md` — 分派规格合规审查子代理
+- `./code-quality-reviewer-prompt.md` — 分派代码质量审查子代理
+
+## 红线
+
+**绝不：**
+- 未经用户明确同意就在 main/master 分支上开始实现
+- 跳过审查（规格合规性或代码质量）
+- 带着未修复的问题继续
+- 并行分派多个实现子代理（会冲突）
+- 让子代理读取计划文件（应提供完整文本）
+- 忽视子代理的问题（在让它们继续之前先回答）
+- 在规格合规性审查通过之前开始代码质量审查（顺序错误）
+- 在任一审查有未解决问题时就进入下一个任务
+
+**如果审查者发现问题：**
+- 实现者（同一子代理）修复
+- 审查者再次审查
+- 重复直到通过
+
+## 依赖技能
+
+- **using-git-worktrees** — 必需：在开始前建立隔离 worktree
+- **writing-plans** — 创建本技能执行的计划
+- **finishing-a-development-branch** — 所有任务完成后收尾
+- **test-driven-development** — 子代理对每个任务遵循 TDD

package/skills/core/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -0,0 +1,64 @@
+# 代码质量审查者提示词模板
+
+分派代码质量审查子智能体时使用此模板。
+
+**目的：** 验证实现是否构建良好（整洁、有测试、可维护）
+
+**仅在规格合规性审查通过后才分派。**
+
+```
+spawn_agent:
+  description: "审查任务 N 的代码质量"
+  message: |
+    你正在审查一个实现的代码质量。
+
+    ## 实现者声称构建了什么
+
+    [来自实现者的报告]
+
+    ## 计划中的要求
+
+    [plan-file] 中的任务 N
+
+    ## 审查清单
+
+    ### 代码质量
+    - 命名是否清晰准确（匹配事物做什么，而非怎么做）？
+    - 代码是否整洁且可维护？
+    - 是否有死代码、未使用的导入、冗余逻辑？
+
+    ### 测试质量
+    - 测试是否真正验证了行为（而非只是 mock 行为）？
+    - 测试是否覆盖了正向+反向+边界情况？
+    - 测试命名是否清晰描述了被测行为？
+
+    ### 架构
+    - 每个文件是否有单一明确的职责和定义清晰的接口？
+    - 各单元是否拆分得足以独立理解和测试？
+    - 实现是否遵循了计划中的文件结构？
+    - 本次实现是否创建了已经很大的新文件，或显著增大了现有文件？
+
+    ### 安全与健壮性
+    - 是否有未处理的错误或异常？
+    - 是否有硬编码的敏感信息？
+    - 是否有潜在的竞态条件或资源泄漏？
+
+    **报告格式：**
+
+    ## 代码质量审查
+
+    **状态：** 通过 | 发现问题
+
+    **优点：**
+    - [实现中做得好的方面]
+
+    **问题（如有）：**
+    - [严重] [file:line] [问题描述]
+    - [重要] [file:line] [问题描述]
+    - [次要] [file:line] [问题描述]
+
+    **建议（仅供参考，不阻止通过）：**
+    - [改进建议]
+```
+
+**审查者返回：** 优点、问题（严重/重要/次要）、评估结论