Shadow Dev Workflow v6

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

架构

skills/
├── shadow-dev-propose/     # 需求对齐、方案设计、知识影响预评估
├── shadow-dev-design/      # UI 设计大师：高保真视觉提案与布局交互打磨
├── shadow-dev-apply/       # 加载 active Knowledge，执行与验证
├── shadow-dev-review/      # 质量门禁和最终知识评估
├── shadow-dev-release/     # Knowledge 闭环 + 提交 + PR
├── shadow-dev-archive/     # 归档 merged change + 重建 INDEX
├── 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 自举：确保锁版本 shadow-dev-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 → archive

propose： 按 menu 读取和引用 active Knowledge，做领域对齐（限界上下文 / 不变量），记录预期知识影响。
apply： 按引用约束执行，以 brief 的不变量为验收对象逐条留观察点；冲突时暂停并查明原因。
review： 验证实现、约束、模型一致性和卡片检查方法，给出最终知识动作。
release： 新增、原位更新、废弃卡片或记录无需变更，然后提交发布 PR。
archive： PR merged 后将 brief 移到 archive/ 并重建 INDEX；也可由 GitHub Actions 在 issue close 时自动触发。

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 自举：Codex 走 hooks.codex.json 里的 commandWindows 覆盖，优先 %ProgramFiles%\Git\bin\bash.exe，找不到再退回 PATH 上的 bash。若 PATH 上只有 WSL 的 System32\bash.exe，自举会把 CLI 装进 WSL 文件系统、Windows 侧看不到 shim——此时手动 bash scripts/install-cli.sh install，或设 SHADOW_CLI_HOOK_DISABLE=1 关掉自举。

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 契约：

发版（Release 控制版本号）

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

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

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，核对物化的 8 个 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: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 上跑全部四门。它存在的原因很实在：这三类门此前只能靠执行者本机口头自证，而半绿的门比没有门更危险。

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 宿主

发版（Release 控制版本号）

机器门（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 宿主

发版（Release 控制版本号）

机器门（GitHub Actions）

依赖

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages