SDD Agent Platform

SDD Agent Platform 是一个本地优先的规格驱动开发（SDD）与 Claude Code subagent workflow 平台。它把需求、计划、任务边界、运行状态、agent 证据、验证结果和出货前门禁串成一条可审计的本地证据链。

它不是 Spec Kit、GSD、OpenSpec、BMAD 或 Oh My OpenCode 的封装，而是吸收这些工具的共同机制后，为 Claude Code 工作流设计的一套 CLI/core harness。

核心目标：

Controlled phase transitions, automated intra-phase orchestration.
阶段推进可控，阶段内编排自动化。

同时坚持：

Sufficient SDD, not maximum SDD.
只做足以安全完成当前需求的规格化，不多做，不少做。

适合解决什么问题

普通 agent 可以直接改代码，但在高风险任务里容易把需求边界、状态流转、并发、数据库、审查、验证和出货门禁混在主会话里。SDD Agent Platform 在 Claude Code 外增加一层可检查的工程约束：

| 维度 | 普通 agent 直接执行 | SDD Agent Platform | |---|---|---| | 路径选择 | 依赖 prompt 判断 | lifecycle decision 选择 direct / compact / full / research | | 任务边界 | 容易随实现扩大 | sdd tasks inspect 固定 Boundary / Acceptance / affected files | | agent 参与 | 证据混在主会话 | implementer / reviewer / validator 输出 .sdd/runs/<branch>/<stage>/*.md stage evidence | | 验收 | 自然语言总结 | .sdd/runtime.sqlite + stage evidence refs/hashes + acceptance coverage | | 状态推进 | 人工记得改状态 | runtime 更新 lifecycle/task/validation/gate/truthAlignment；Markdown 由 agent/stage-manager 编写 | | 健康检查 | 临时脚本 | sdd doctor 检查配置、runtime state、current evidence、generated entry drift |

5 分钟快速开始

1. 安装 CLI

普通用户不需要 clone 本仓库：

npm install -g sdd-agent-platform@latest
sdd --version
sdd --help

卸载：

npm uninstall -g sdd-agent-platform

平台开发者本地验证可使用构建后的 dist CLI：

npm run build
node ./packages/cli/dist/main.js --help

2. 在目标项目初始化

在目标 Git 仓库中执行：

sdd init --ai claude-code
sdd status
sdd doctor

初始化后会稳定出现：

.sdd/project.yml
.sdd/runtime.sqlite
.claude/commands/...      # managed generated entries
.claude/skills/sdd/...    # managed generated skill

sdd init 是项目级接入，不是每个 branch 都要重复执行的 workflow 入口。具体需求进入哪个 workflow partition，由当前 Git branch 或显式 --branch 决定；specs/<partition>/spec.md、plan.md、tasks.md 通常在 spec / plan / tasks 阶段逐步建立，或在显式 --scaffold-docs 时生成 starter docs。

3. 在 Claude Code 里继续

如果已经生成 Claude Code 入口，在项目里输入：

/sdd

/sdd 会先读取 sdd status，再根据 CLI/core 的 recommended next command 判断下一步是补 spec、写 plan、拆 tasks、继续顺序 sdd do task、按 task/batch/wave 边界运行 /sdd:test，还是进入 sdd ship --dry-run 出货前检查。当前 Claude Code 投影正常入口为 spec、plan、tasks、do、test、ship、doctor；verifies 与 goal-verify 是 tasks/test bundle 内部 continuation，verify、init、update、run-task、verify-task 是 CLI / instruction action，不是当前默认 slash 用户入口。

主工作流

常见主路径如下。/sdd:do 负责把 T1 或任务标题语义绑定到同一个 task boundary 并组织实现证据，/sdd:test 按 verify.md 中声明的 validation unit / batch / wave 验证边界执行；sdd verify task 仅保留为低级诊断入口，不是 happy path。

# 读状态、任务边界和路由
sdd status --branch master
sdd tasks inspect <task_id> --branch master
sdd tasks route <task_id> --branch master

# tasks 阶段应产出 tasks.md 与 verify.md；do 阶段只消费已接受 task boundary
sdd do task <task_id-or-task-text> --branch master

# 执行验证命令、生成 test evidence、判断 acceptance coverage；batch_end/wave_end 任务按 verify.md 合并验证
sdd test task <task_id> --branch master
sdd test batch <batch_id> --branch master
sdd test wave --branch master --wave 1

# /sdd:test bundle 完成 test -> goal-verify 后，ship 消费 accepted evidence 与 aligned truth
sdd test close --branch master
sdd test close --branch master --target goal-verify
sdd ship close --branch master

# 可选：让前台 subagent 做观察/调研，主 agent 先消费 digest，需要时再 deep-read stage evidence
sdd subagents run <task_id> --branch master --run <run_id> --agent observer --json

# 低级诊断：sdd verifies write、sdd verify task

subagent 输出的 agents[].digest、summaryRefs 和 doNotReadUnlessNeededRefs 用于主 agent 快速消费观察结果；它们始终是 non-authoritative guidance，不能替代 /sdd:test、decision card、ship 或最终风险判断。

核心事实源

| 事实源 | 含义 | |---|---| | specs/<partition>/spec.md | 需求、范围、验收标准 | | specs/<partition>/plan.md | 设计方案、风险控制、验证矩阵 | | specs/<partition>/tasks.md | 可执行 task、边界、stage evidence 要求 | | specs/<partition>/verify.md | 验证设计契约；独立于 task planning / implementation authority | | .sdd/runtime.sqlite | runtime state、events、projections、evidence ledger、selection pointers、refs/hashes 的事实源 | | .sdd/run-index.json | 可重建的本地查询索引，不是权威事实源 | | .sdd/runs/<branch>/<stage>/*.md | agent/stage-manager authored stage evidence；runtime 只注册 ref/hash/gate metadata | | .claude/** | managed AI entry projection，不是手写事实源 |

文档地图

| 文档 | 面向对象 | 用途 | |---|---|---| | 用户指南 | 人类用户 | 安装、初始化、执行任务、test gate、truthAlignment、subagent digest、doctor、常见问题 | | AI README | Claude Code / AI 操作者 | status-first、stage evidence、task boundary、truthAlignment 策略 | | 文档信息架构 | 维护者 | Markdown 分类、迁移风险、当前入口地图 | | 命令信息架构 | 平台维护者 | CLI 命令分层、入口职责和用户路径 | | 架构设计 | 平台维护者 | 平台架构和核心设计 | | Lifecycle Decision Model | 平台维护者 | direct / compact / full / research 的决策模型 | | Phase artifacts index | 平台维护者 | 本仓库 SDD phase 归档入口 | | Phase status | 平台维护者 | 当前阶段状态；Phase 9 正在收敛 runtime control-plane、six-bundle 入口、truthAlignment 与旧 surface 清理 |

研究与历史分析材料保留在 docs/research/；runtime contract assets 保留在 commands/、agents/、templates/、workflows/ 等目录，不作为普通 Markdown 文档搬迁。

项目结构

packages/          TypeScript runtime 与 CLI
commands/          Claude Code 命令入口说明源材料
agents/            SDD lifecycle agent contract
templates/         spec / plan / tasks / project 模板
workflows/         阶段 workflow contract
adapters/          项目适配模板
schemas/           runtime、stage evidence 与 contract pack
docs/              用户、AI、架构、研究文档
specs/             本项目自身的 SDD 文档
runs/              agent/stage-manager authored branch stage evidence
.sdd/              本地 runtime 状态和索引
context/           项目记忆与决策上下文

本地开发

npm run typecheck
npm test
npm run build
npm pack --dry-run --json

常用只读 CLI smoke：

npm run sdd -- status --branch master
npm run sdd -- instructions overview --json
npm run sdd -- tasks list --branch master

健康检查按需要单独运行 sdd doctor fast --branch master；如果本地 run index 与 runtime.sqlite 漂移，先运行 sdd run index rebuild，再判断是否属于当前验证范围。

npm 发布维护速查

普通安装路径是：

npm install -g sdd-agent-platform@latest

平台维护者发布新版本时，先完成本地验证和 dry-run：

npm whoami
npm publish --dry-run

真实发布必须显式确认后执行：

npm publish --access public

如果真实发布返回 EOTP 并提示打开 https://www.npmjs.com/auth/cli/...，这是 npm security-key/browser authentication 流程，不是 Google Authenticator 扫码页。发布人应在本机终端或 Claude Code prompt 中执行 ! npm publish --access public，打开终端里完整的 npm auth URL，按页面完成 security key / passkey / Windows Hello / browser authentication；如果命令已经退出，认证后重新执行 npm publish --access public。

发布成功后验证：

npm view sdd-agent-platform name version --json
npm install -g sdd-agent-platform@latest
sdd --version
# clean Git repo
sdd init --ai claude-code
sdd status
sdd doctor

不要把长期 npm token、.npmrc、recovery code 写入仓库、文档或对话。recovery code 不能转换成 Google Authenticator OTP；已经发布过的版本不能覆盖，后续发包必须先 bump version。

安全边界

默认不做：

• 自动 commit / push / force push。
• 自动创建 PR、issue、外部评论或修改共享系统。
• 自动执行 destructive git、清理未提交变更或删除历史 run evidence。
• 绕过 runtime gate、truthAlignment、accepted evidence selection 或人工确认要求直接标记通过。
• 把 .claude/**、commands/**、agents/**、templates/**、workflows/** 当作普通文档随意搬迁。

已有未提交变更不应阻塞 SDD workflow；正确做法是通过 branch/partition、runtime state、stage evidence refs/hashes 和 accepted selection pointers 隔离风险，而不是要求工作树必须干净。

当前状态

截至当前主线文档，Phase 1~8 已完成平台编排、入口投影、分发、harness engineering、agent/skill/team runtime、storage v2、verification/test、ship 和 core modularization 等基础；Phase 9 正在落地 runtime control-plane：six-bundle 用户入口、八个内部 runtime stage、SQLite current state、stage evidence refs/hashes、truthAlignment、accepted evidence selection、advisory nextIntent，以及旧入口/旧 evidence surface 清理。