Shadow Dev Workflow v6

自包含的 Knowledge 驱动开发工作流。

架构

skills/
├── shadow-dev-propose/     # 需求对齐、方案设计、知识影响预评估
├── shadow-dev-design/      # UI 设计大师：高保真视觉提案与布局交互打磨
├── shadow-dev-apply/       # 加载 active Knowledge，执行与验证
├── shadow-dev-tdd/         # 实现计划执行调度：波次并行 + 审查重叠 + 分级审查（可选，独立 plan 场景）
├── shadow-dev-debug/       # Bug 根因调查：复现固定、假设验证、同源扫描（调查态技能）
├── shadow-dev-review/      # 质量门禁和最终知识评估
├── shadow-dev-release/     # Knowledge 闭环 + 提交 + PR + merged 后归档
├── shadow-dev-archive/     # 归档恢复入口（漏归档 / Actions 失败时幂等补跑）
├── shadow-dev-publish/     # 正式发版：bump + tag + Release + 审查发布链
├── shadow-dev-knowledge/   # 精确查询 active Knowledge
└── shadow-dev-hotfix/      # 紧急修复快车道：最小修复直达 PR

norms/                      # 跨项目硬规则与工程规范
├── knowledge-cards.md
├── ui-patterns.md
├── api-design.md
├── interaction.md
├── code-style.md
├── domain-model.md
└── verification.md

knowledge/                  # 跨项目经验与协作知识
menu.md                     # 任务到规范和 Knowledge 的路由
rules/                      # 行为准则与铁律
hooks/                      # SessionStart 自举（node）：CLI 锁版本就位 + 本机插件自同步
scripts/install-cli.sh      # vendored CLI 仓库安装器（hook 与手工共用）

项目使用：

shadow-docs/
├── INDEX.md
├── menu.md
├── knowledge/              # 项目当前执行真相
└── changes/
    ├── <name>/brief.md
    └── archive/<name>/brief.md

知识职责

位置	职责
`norms/`	跨项目硬规则与工程规范
`knowledge/`	跨项目经验和协作知识
项目 `shadow-docs/knowledge/`	项目独有的 active 执行真相
`menu.md`	精确路由，不全文读取所有卡片
change brief / INDEX	变更过程与历史追溯，不覆盖 active Knowledge

项目外 memory 不作为执行依据。代码与 Knowledge 冲突时，先用可重复验证确认代码是有意变更、回归还是卡片过期。

工作流

propose → apply → review → release → publish

propose： 按 menu 读取和引用 active Knowledge，做领域对齐（限界上下文 / 不变量），记录预期知识影响。
apply： 按引用约束执行，以 brief 的 INV-n 不变量为验收对象逐条留观察点；L 级在 propose 批准取证策略（observation 默认，assert-first＝先写失败断言，只在四条触发判据成立时）；冲突时暂停并查明原因。
review： 验证实现、约束、模型一致性和卡片检查方法，按三条放行判据收口——观察点闭合 ∧ guard 探针绿 ∧ regression 探针绿（该仓 CI 实测耗时 ≤ 60s 时适用），给出最终知识动作。
release： 新增、原位更新、废弃卡片或记录无需变更，提交并发布 PR；PR merged 后在本阶段末段把 brief 移入 archive/ 并重建 INDEX——所有代码问题提交完即收口。
publish： 正式对外发版，与单个 change 解耦：只在要求发布可安装产物时运行，一次可攒多个已合并 change。bump 三份 manifest → 提交合并 → 打 tag 创建 Release → 审查 publish-release 发布链与冒烟。发版自身也建一个 chore change 作载体，结论回填后归档。

漏归档、Actions 自动归档失败或 hotfix 事后补归档，用 shadow-dev-archive 作为幂等恢复入口。

brief

一个变更一个 brief.md，记录动机、引用规范、决策、任务、结果和知识评估。Knowledge 记录“现在应怎么做”，brief 记录“这次发生了什么”。

历史迁移说明

早期流程曾使用 OpenSpec 多制品结构；该信息仅供历史追溯，不是当前入口或兼容层。当前只执行 shadow-dev v6。

Deterministic CLI

CLI 独立分发于 stack-wuh/shadow-dev-cli（纯脚手架实现：brief、INDEX、Git 与 GitHub 写操作的确定性执行层）。插件不再内置或 vendored CLI，而是通过 SessionStart hook 自动安装锁版本 CLI：

package.json 的 cliVersion 字段锁定 CLI 版本（当前 v1.5.0），与插件版本配对发布，兼容配对由 manifest 机检；此外产物用 requiresCommands 自声明所需命令键，CLI 在物化/直通落盘前断言（缺失即 ARTIFACT_INCOMPATIBLE，指针不动）。
首次会话自动安装到 ~/.local/share/shadow-dev-cli/shadow-dev-cli-<ver>/（版本化目录 + CURRENT/PREVIOUS 指针），并在 ~/.local/bin/shadow-dev 生成托管 shim；此后每次会话幂等秒退（不触网）。
hook 永不阻塞会话：安装失败仅 stderr 警告；CLI 未就位时 skills 中 shadow-dev 命令不可用。
SHADOW_CLI_HOOK_DISABLE=1 跳过自举（双仓开发时保护手动 --channel main / --from 安装）。

手动管理（vendored 安装器随插件分发）：

bash scripts/install-cli.sh install                       # 装锁版本（同 hook 行为）
bash scripts/install-cli.sh install --version v1.5.0      # 显式锁版本
bash scripts/install-cli.sh rollback                      # 切回上一版（离线）
bash scripts/install-cli.sh status                        # 查看当前/上一版本指针

排障：

shadow-dev: command not found：确认 ~/.local/bin 在 PATH（export PATH="$HOME/.local/bin:$PATH"）。
升级 CLI 与更新 pin：CLI 仓库发新版 → 验证 → 本仓库改 cliVersion 并同步 scripts/install-cli.sh，随插件发版；改完必须跑 npm run check:requires——它判 skills 引用 ⊆ requiresCommands ⊆ 已装 CLI 命令目录，pin 与能力声明不再靠人记忆同步。

示例：

shadow-dev --help
shadow-dev repo inspect --json
shadow-dev branch plan --name <name> --json
shadow-dev branch execute --name <name> --confirm --json

brief、INDEX、Git 和 GitHub 写操作由 CLI 统一管理。写操作需要 --confirm；plan/execute 重新验证 planHash；commit 只接受明确文件列表；archive 仅在 GitHub API 证明 PR merged 后执行。完整命令参考与典型工作流见 docs/cli-guide.md。

安装

原生宿主是 Claude Code（本插件为其开发），Codex 以 .codex-plugin/ 清单 + hooks/hooks.codex.json 原生消费，zcode 等兼容宿主可直接消费同一产物。安装入口正从「插件引导 CLI」反转为「CLI 驱动分发」：

当前形态（v6.5.0）：作为 Claude Code 插件安装，SessionStart hook 自动就位锁版本 CLI，无需手动初始化。

Codex 宿主

同一份产物，两条路线：

插件路线（推荐，跨文件引用完整） —— .codex-plugin/plugin.json 声明 skills 与 hooks/hooks.codex.json，.agents/plugins/marketplace.json 是 Codex 侧的 marketplace 目录：

codex plugin marketplace add stack-wuh/shadow-dev-workflow      # 本机开发：codex plugin marketplace add D:/works/shadow-dev-workflow
codex plugin add shadow-dev-workflow@shadow-dev-workflow-local   # 装完重启桌面应用

整包（norms/、menu.md、knowledge/）随插件进 ~/.codex/plugins/cache/，技能里的跨文件引用保持有效；
插件钩子属非托管钩子，装完需在 CLI 里 /hooks 审查并信任才会执行，未信任时静默跳过（不报错、不阻塞会话）；
带 lifecycle hooks 的插件不进公共 plugin directory，本地/GitHub marketplace 安装不受影响。

bind 路线 —— shadow-dev workflow link/install 就位产物后 shadow-dev bind plan --host codex + bind execute，描述符为 adapters/codex.json（skillsDir: ~/.codex/skills）。注意 bind 只复制 skills/，技能正文对 norms/ 与 menu.md 的引用会脱离产物根目录，需要插件路线才等价。

Windows 自举：hook 入口是 node（hooks/bootstrap.mjs，三宿主统一），不再依赖 PATH 上的裸 bash——Windows 上 bash 常先命中 System32\bash.exe / WindowsApps\bash.exe 这两个 WSL 入口桩（未启用子系统时只打印安装提示、不执行脚本，hook 静默失败）。可信 bash 由 scripts/resolve-bash.mjs 统一解析（先认 %ProgramFiles%\Git\bin\bash.exe 等 Git 安装位，明确去桩）；可用 SHADOW_DEV_BASH 显式指定（指向无效路径即按不可用告警，不静默改用别的解释器），SHADOW_CLI_HOOK_DISABLE=1 关闭 CLI 自举。

CLI 轨（shadow-dev-cli 的 workflow/bind 域，v1.4.0 起可用，已实测）：

shadow-dev workflow plan && shadow-dev workflow execute --plan-hash <哈希> --confirm   # 物化本仓 release tarball 到 ~/.local/share/shadow-dev-workflow/
shadow-dev bind plan --host auto && shadow-dev bind execute --host <名> --plan-hash <哈希> --confirm   # 按 adapters/<host>.json 把 skills 绑入宿主发现目录

产物与 adapters 契约：

发版（publish 阶段）

发版是独立入口，与单个 change 解耦——可攒多个已合并 change 一次发布，且每次发版自身建一个 chore 载体 change（YYYYMMDD-chore-release-vX.Y.Z）承接 bump、tag、run 结论与冒烟证据，merged 后随 release 末段归档。

版本权威是 GitHub Release tag：tag 名去 v 必须与 package.json.version 及 .claude-plugin、.codex-plugin 三处同源，不一致时 publish-release 工作流直接判红。

node scripts/bump-version.mjs 6.10.0    # 一次同步三处 manifest（也可 --check 只判定）
npm run ci                              # 版本 + requires:strict + 知识治理 + brief 契约 + 发布冒烟契约 + 测试，六门一体
git tag v6.10.0 && git push origin v6.10.0
gh release create v6.10.0 --generate-notes   # 之后由 publish-release.yml 接手

打 tag 与创建 Release 目前仍由人执行：已 pin 的 CLI 命令目录不含发版命令键，本仓按「能力缺失只能阻塞、不降级」的契约把这两步留在 shadow-dev-publish 的委托清单里。待 execution-layer 发布含该能力的版本后，本仓同步 requiresCommands 与 cliVersion，把委托换成 CLI 调用。

publish-release.yml（on: release.published）依次执行：版本权威判定 → 装 pin CLI → 六门 → scripts/pack.mjs → 资产名契约断言（CLI 只认 ^shadow-dev-workflow-v[0-9][0-9.]*\.tar\.gz$，名字写错等于没发布）→ gh release upload --clobber → 发布冒烟：隔离 prefix 里用真实 CLI 跑 workflow plan --release → workflow execute → bind plan，核对物化的 9 个 skills 与规范文件。产物永远不被手工搬运，人只负责 bump 与打 tag。

机器门（GitHub Actions）

门	命令	判什么	CI
版本同源	`npm run check:version`	`package.json` 与两份宿主清单版本一致	quality-gate + publish-release
能力一致性	`npm run check:requires` / `:strict`	`skills 引用 ⊆ requiresCommands ⊆ CLI 命令目录`	CI 用 strict：解析不到命令目录即判红，禁止「未参与断言」的半绿
发布冒烟契约	`npm run check:smoke`	yml 读的 payload 字段、物化 ROOT 派生、skills 期望值不得写死；离线 `--from` 本地资产复现冒烟（Windows 遇 execution-layer 的 tar 路径缺陷时显式 deferred）
brief 契约	`npm run check:brief`	领域模型段存在性、`INV-n` 编号与去重、结果段对账闭合、取证策略取值、S/M 级新建套件断言判红；`archive/` 与豁免名单不追溯判红，但每次点名
知识治理	`npm run check:knowledge`	卡片字段与 status、source 存在性（含归档兜底）、active 卡 menu 路由、引用死链、废弃 token 残留（`--forbid`）、孤儿规范、技能 `name/description` 一致性	quality-gate
产物与安装器	`npm test`	pack 产物内容契约、三清单版本机检、hook wrapper 装配、离线安装	quality-gate（ubuntu/macos/windows × node 20/22）

quality-gate.yml 在 push main 与每个 PR 上跑全部六门。它存在的原因很实在：这些门此前只能靠执行者本机口头自证，而半绿的门比没有门更危险。

但门是探针，不是验收：完成证据永远是 brief 里「不变量 × 观察点」的对账表；探针绿不加分，探针红必须归因（真实回归 / 环境噪声），未归因即未验证。分工见 knowledge/contract-probe.md。2026-10-11 用户裁定彻底去 TDD 后，「套件必须全绿」类门槛已从规范清除，旧措辞进入 CI 禁项集合，一出现即判红。

release 产物 shadow-dev-workflow-v<ver>.tar.gz 由 scripts/pack.mjs 打包（发版链见上文「发版」），解包为 shadow-dev-workflow/，只含运行必需集（marketplace.json / package.json / README / menu.md / skills / hooks / rules / knowledge / norms / docs / scripts）。
adapters/<host>.json（schema shadow-dev-adapter/v1）声明宿主的 skills 发现目录、复制策略、托管标记与 hook 支持位；新增宿主 = 新增描述符，CLI 零改动。

依赖

Node.js 20+
Git
bash + curl（安装器拉取 release 产物）
GitHub token（Issue、PR、发布和归档校验）
Codex CLI（可选，插件路线需 codex plugin marketplace add；实测 0.160.1）

License

MIT

Navigation Menu

Repository navigation

About

Repository files navigation

Shadow Dev Workflow v6

架构

知识职责

工作流

brief

历史迁移说明

Deterministic CLI

安装

Codex 宿主

发版（publish 阶段）

机器门（GitHub Actions）

依赖

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.agents/plugins		.agents/plugins
.claude-plugin		.claude-plugin
.codex-plugin		.codex-plugin
.github/workflows		.github/workflows
adapters		adapters
docs		docs
hooks		hooks
knowledge		knowledge
norms		norms
rules		rules
scripts		scripts
shadow-docs		shadow-docs
skills		skills
test		test
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
marketplace.json		marketplace.json
menu.md		menu.md
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation

Shadow Dev Workflow v6

架构

知识职责

工作流

brief

历史迁移说明

Deterministic CLI

安装

Codex 宿主

发版（publish 阶段）

机器门（GitHub Actions）

依赖

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages