@devcxl/opencode-cabbage 1.2.0 → 2.0.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "opencode-cabbage",
+  "version": "2.0.0",
+  "description": "全流程开发编排插件 — 需求→设计→任务→编码→测试→审查→自动合并，支持 OpenCode 与 Codex 双平台",
+  "author": {
+    "name": "devcxl",
+    "url": "https://github.com/devcxl"
+  },
+  "homepage": "https://devcxl.github.io/opencode-cabbage/",
+  "repository": "https://github.com/devcxl/opencode-cabbage",
+  "license": "MIT",
+  "keywords": [
+    "development-workflow",
+    "orchestration",
+    "tdd",
+    "codex",
+    "codex-plugin",
+    "opencode",
+    "opencode-plugin"
+  ],
+  "skills": "./codex-skills/",
+  "interface": {
+    "displayName": "OpenCode Cabbage",
+    "shortDescription": "全流程开发编排 — 需求到自动合并，双平台兼容",
+    "longDescription": "覆盖需求、设计、DAG 任务拆解、并行编码（TDD）、审查与自动合并的全流程开发编排插件。兼容 OpenCode 与 Codex 双平台，提供 9 个 flow skills 和 6 个 agent skills。",
+    "developerName": "devcxl",
+    "category": "Developer Tools",
+    "capabilities": ["Read", "Write"],
+    "defaultPrompt": [
+      "使用 OpenCode Cabbage 初始化项目开发环境 — 加载 flow-setup skill",
+      "使用 OpenCode Cabbage 的 flow-setup skill 初始化项目开发环境",
+      "使用 OpenCode Cabbage 的 agent-dev-lifecycle skill 编排全流程"
+    ],
+    "brandColor": "#00bcd4"
+  }
+}

package/README.md

@@ -14,16 +14,53 @@
 
 ---
 
+## OpenCode Compatibility
+
+**Requires OpenCode v2 (tested on v2.0.28).** Version 2.0.0 is a V2-only line built on the `@opencode/plugin` 2.x API (`Plugin.define` setup, domain transforms, turn-end-event driven auto-continuation). OpenCode v1 users should stay on the `1.x` release line.
+
 ## Installation
 
-```json
-// opencode.json
-{
-  "plugin": ["@devcxl/opencode-cabbage"]
-}
+```bash
+opencode plugin add @devcxl/opencode-cabbage
 ```
 
-Once started, the plugin automatically injects 7 slash commands, 9 flow skills, 6 agents, and 1 goal tool.
+This installs the plugin and registers it in the global OpenCode configuration (`plugins: ["@devcxl/opencode-cabbage"]`). Restart OpenCode or run `opencode reload` to activate.
+
+Once started, the plugin automatically injects 7 slash commands, 12 flow skills, 6 agents, and 2 tools (`goal` for flow state, `cabbage` for change records).
+
+> **⚠️ Plugin conflict — do not combine with other goal plugins.** cabbage ships its own `goal` tool with an auto-continuation loop driven by turn-end events. Installing it together with another goal / auto-continue plugin (e.g. `@prevalentware/opencode-goal-plugin`, `opencode-goal-mode`) risks both loops reacting to the same session activity and injecting continuation prompts: work gets continued twice, continuation counts and token budgets drift out of sync, and abort handling interferes across plugins. Use exactly one goal engine per session — if you rely on an external goal plugin, do not trigger cabbage's goal tool (it is restricted to the `dev-lifecycle` / `goal-verify` agents).
+
+## Built-in change records (Cabbage engine)
+
+The plugin bundles the Cabbage engine (`vendor/cabbage`, version-pinned by `scripts/sync-cabbage.mjs`) and injects a `flow-change` skill plus a `cabbage` tool: create a change record, declare risk flags, verify stages, pass gates, sync current-state docs, and archive after merge. A record is one directory under `.cabbage/changes/<id>/` — a single `tasks.md` by default; specialist documents (`design` / `rfc` / `adr` / `api` / `database` / `security` / `release`) open only for declared risks.
+
+- **Requirements**: Python 3.10+ on the machine. The CLI is released per plugin version to `~/.config/opencode/cabbage/cli@<version>/`; without Python the tool returns a readable error and everything else keeps working.
+- **Bootstrap a project**: `cabbage({op:"init"})` scaffolds `.cabbage/`, the docs skeleton, the CI template, and a vendored CLI copy for GitHub Actions. Existing docs: `cabbage({op:"adopt"})` inventories markdown outside the docs tree (moves stay manual).
+- **Light path**: `new` → fill `tasks.md` → `verify` → `gate merge` → `archive` after the merge is confirmed. The tool is restricted to the `dev-lifecycle` orchestrator.
+
+## Codex Installation (Compatibility Layer)
+
+This package also ships a Codex plugin compatibility layer (`codex-skills/` + `hooks/` + `.codex-plugin/`) so the flow skills and agent prompts work in Codex as well.
+
+The repository is a Codex marketplace: add it as a marketplace source, then install the plugin from it.
+
+```bash
+# 1. Add this repository as a Codex marketplace
+codex plugin marketplace add devcxl/opencode-cabbage
+
+# 2. Confirm the plugin is available
+codex plugin list --available
+
+# 3. Install the plugin (pulled from the npm package, which bundles all Codex files)
+codex plugin add opencode-cabbage@cabbage
+```
+
+Notes:
+
+- **Build artifact included**: the SessionStart hook (`dist/hooks/session-start.js`) ships inside the published npm package — no local build required.
+- **Hook trust review**: Codex requires interactive trust approval for hooks (`/hooks` command) on first run — approve the `SessionStart` hook to enable context injection.
+- **Marketplace name**: the marketplace is named `cabbage` (see `.agents/plugins/marketplace.json`); use `opencode-cabbage@cabbage` as the plugin selector.
+- **Platform differences**: the Codex layer is a pure-Prompt downgrade — no `goal` tool, no slash commands, no automatic continuation. Agents are plain skills (referenced as `@agent-*`), and flow state is tracked via GitHub Issue checklists. See `codex-skills/agent-dev-lifecycle/SKILL.md` for details.
 
 ## Command Overview
 
@@ -41,12 +78,9 @@ Once started, the plugin automatically injects 7 slash commands, 9 flow skills,
 
 ```bash
 # 1. Install
-npm install @devcxl/opencode-cabbage
-
-# 2. Add the plugin to opencode.json
-# { "plugin": ["@devcxl/opencode-cabbage"] }
+opencode plugin add @devcxl/opencode-cabbage
 
-# 3. Run in OpenCode
+# 2. Run in OpenCode
 # /setup → /requirements → @dev-lifecycle
 ```
 
@@ -58,17 +92,23 @@ npm install @devcxl/opencode-cabbage
 ## Architecture
 
 ```
-src/                          # Thin TypeScript layer
-├── index.ts                  # Plugin entry point
-├── plugin.ts                 # Package root resolution
-├── plugin/                   # Loaders + goal tool
-│   ├── server.ts             # Main factory: injects skills/commands/agents, goal tool, context, auto-continuation
-│   ├── goal.ts               # goal tool (status + goal-verify authorization)
-│   ├── commands.ts           # Command loader
-│   ├── skills.ts             # Skill loader
+src/                          # Thin TypeScript layer (OpenCode V2 plugin)
+├── index.ts                  # Default export (Plugin.define)
+├── plugin.ts                 # Plugin definition: id + setup wiring
+├── plugin/                   # Setup glue + built-in tools
+│   ├── server.ts             # setup(ctx): domain transforms (skills/commands/agents/tools), hooks, event dispatch
+│   ├── continuation.ts       # Turn-end driven continuation + auto-resume + child-session activity tracker
+│   ├── goal.ts               # goal tool (status machine + goal-verify authorization)
+│   ├── goal-store.ts         # Goal persistence (session metadata)
+│   ├── cabbage-cli.ts        # Releases the bundled Cabbage engine per plugin version; python detection + exec
+│   ├── cabbage-tool.ts       # `cabbage` tool: change records (ops mapped to the bundled CLI, agent-gated)
+│   ├── install-dir.ts        # Versioned dir install (lock + completeness check; shared by skills and the engine)
+│   ├── session-abort.ts      # User-interrupt markers (shared by events/tool/continuation)
+│   ├── commands.ts           # Command loader (execute-style registration)
+│   ├── skills.ts             # Skill loader + V2 registration entries
 │   ├── prompts.ts            # Prompt loader
 │   ├── bootstrap.ts          # Startup guidance
-│   ├── agents.ts             # Agent injection
+│   ├── agents.ts             # Agent loader + V1→V2 permission/tools rule conversion
 │   ├── shell.ts              # Agent shell env isolation
 │   └── prompt-lint.ts        # Prompt asset consistency checks
 └── kernel/                   # Minimal supporting modules
@@ -78,11 +118,17 @@ src/                          # Thin TypeScript layer
     ├── permission.ts         # Permission matching semantics
     └── mutex.ts              # Keyed async mutex
 
+vendor/cabbage/               # Bundled Cabbage engine (synced via scripts/sync-cabbage.mjs; hash-pinned)
+
 assets/                       # Runtime assets (pure Prompt flows)
 ├── commands/                 # 7 slash commands
-├── skills/                   # 9 flow-* skills (Prompt-driven, direct git/gh)
+├── skills/                   # 12 flow-* skills (Prompt-driven, direct git/gh)
 ├── agents/                   # 6 agent definitions
 └── prompts/                  # Guidance prompts and templates
+
+codex-skills/                 # Codex compatibility layer (mirrors assets/, agent-* prefixed)
+hooks/                        # Codex SessionStart hook (hooks.json + compiled dist/hooks/)
+.codex-plugin/                # Codex plugin manifest (plugin.json)
 ```
 
 ## Documentation

package/README.zh.md

@@ -14,16 +14,29 @@
 
 ---
 
+## OpenCode 兼容性
+
+> **要求 OpenCode v2（已在 v2.0.28 实测）。** 2.0.0 为 V2-only 版本线，基于 `@opencode/plugin` 2.x（`Plugin.define` 入口、域 transform、轮次结束事件驱动的自动续接）。OpenCode v1 用户请继续使用 `1.x` 版本线。
+
 ## 安装
 
-```json
-// opencode.json
-{
-  "plugin": ["@devcxl/opencode-cabbage"]
-}
+```bash
+opencode plugin add @devcxl/opencode-cabbage
 ```
 
-插件启动后自动注入 7 个 slash command、9 个 flow skill、6 个 agent 与 1 个 goal 工具。
+该命令会安装插件并写入全局配置（`plugins: ["@devcxl/opencode-cabbage"]`）。重启 OpenCode 或执行 `opencode reload` 后生效。
+
+插件启动后自动注入 7 个 slash command、12 个 flow skill、6 个 agent 与 2 个工具（`goal` 管流程状态、`cabbage` 管变更记录）。
+
+> **⚠️ 插件冲突——不要与其他 goal 插件同时安装。** cabbage 自带 `goal` 工具与轮次结束事件驱动的自动续接循环。若与其他 goal / 自动续接类插件（如 `@prevalentware/opencode-goal-plugin`、`opencode-goal-mode`）同时安装，存在双方同时响应会话活动并注入续接 prompt 的风险：任务被重复续接、续接计数与 token 预算互不同步、abort 处理互相干扰。同一会话只能保留一个 goal 引擎——若使用外部 goal 插件，请勿触发 cabbage 的 goal 工具（仅 `dev-lifecycle` / `goal-verify` agent 可调用）。
+
+## 内置变更记录（Cabbage 引擎）
+
+插件捆绑 Cabbage 引擎（`vendor/cabbage`，由 `scripts/sync-cabbage.mjs` 固定版本生成），并注入 `flow-change` 技能与 `cabbage` 工具：创建变更记录、声明风险标记、验证阶段、通过门禁、同步当前文档、合并确认后归档。一份记录 = `.cabbage/changes/<id>/` 一个目录：默认只有 `tasks.md`；专项文档（`design` / `rfc` / `adr` / `api` / `database` / `security` / `release`）仅在声明风险时展开。
+
+- **运行要求**：机器需 Python 3.10+。CLI 按插件版本释放到 `~/.config/opencode/cabbage/cli@<version>/`；缺 Python 时工具返回明确错误，其余功能不受影响。
+- **项目接入**：`cabbage({op:"init"})` 生成 `.cabbage/`、docs 骨架、CI 模板与供 GitHub Actions 使用的 vendored CLI。
+- **轻量路径**：`new` → 填写 `tasks.md` → `verify` → `gate merge` → 合并确认后 `archive`。工具仅 `dev-lifecycle` 编排器可用。
 
 ## 命令一览
 
@@ -41,12 +54,9 @@
 
 ```bash
 # 1. 安装
-npm install @devcxl/opencode-cabbage
-
-# 2. 在 opencode.json 中添加
-# { "plugin": ["@devcxl/opencode-cabbage"] }
+opencode plugin add @devcxl/opencode-cabbage
 
-# 3. 在 OpenCode 中执行
+# 2. 在 OpenCode 中执行
 # /setup → /requirements → @dev-lifecycle
 ```
 
@@ -61,9 +71,12 @@ npm install @devcxl/opencode-cabbage
 src/                          # TypeScript 薄层
 ├── index.ts                  # 插件入口
 ├── plugin.ts                 # 包路径解析
-├── plugin/                   # 加载器 + goal 工具
-│   ├── server.ts             # 主工厂：注入 skills/commands/agents、goal 工具、Context、自动续接
+├── plugin/                   # 加载器 + 内置工具
+│   ├── server.ts             # 主工厂：注入 skills/commands/agents/tools、Context、自动续接
 │   ├── goal.ts               # goal 工具（状态管理 + goal-verify 授权）
+│   ├── cabbage-cli.ts        # 释放捆绑 Cabbage 引擎（按版本隔离）+ python 探测与执行
+│   ├── cabbage-tool.ts       # `cabbage` 工具：变更记录全流程（agent 门控）
+│   ├── install-dir.ts        # 版本化目录安装（锁 + 完整性校验，skills 与引擎共用）
 │   ├── commands.ts           # Command 加载器
 │   ├── skills.ts             # Skill 加载器
 │   ├── prompts.ts            # Prompt 加载器

package/assets/agents/dev-lifecycle.md

@@ -107,6 +107,12 @@ permission:
 
 ### 轻量路径执行要点
 
+**统一前置：变更记录（`flow-change`）**。凡涉及代码改动的路径（Bug 修复 / 紧急修复 / 业务调整 /
+重构 / 技术债 / 基础设施），先用内置引擎建立记录：`cabbage({op:"new", type:"change", change:"<slug>"})`，
+随实现更新 `tasks.md`；高风险用 `impact` 标记展开专项文档；验证通过、合并确认后 `op:"archive"`。
+紧急修复同样先建记录（声明 `deployment=true`）。纯文档路径按 `flow-docs` 规范直接改归属文档；
+调研路径不建记录；事故复盘走 `flow-incident`（incident → postmortem → tasks）。
+
 **Bug 修复（Corrective Flow）**
 1. 分诊严重度；创建 goal 绑定 Flow Record，链接导致回归的原 Flow（不改其完成状态）
 2. 建立反馈回路（失败测试/脚本/夹具），确认复现用户描述的**同一**故障

package/assets/prompts/bootstrap.md

@@ -14,6 +14,10 @@
 - 新功能/需求：setup → requirements → design → tasks → code → review → release
 - 非功能场景（Bug 修复/紧急修复/业务调整/重构/技术债/基础设施/文档/回滚）：输入 @dev-lifecycle，自动分诊并按对应轻量路径执行
 
+变更记录：任何代码改动先经内置 `cabbage` 工具建立/更新变更记录（flow-change 技能）——
+默认一份 tasks.md（Goal/Design/Tasks/Verification），高风险经 impact 标记展开专项文档，
+验证通过、合并确认后归档并同步 docs/。
+
 阶段契约：每个 stage 的完成权威是 Parent Issue body checklist（`- [x] <stage>`），
 阶段顺序与约束详见 stage-contract。
 

package/assets/skills/flow-change/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: flow-change
+description: Maintain a Cabbage change record (tasks + documents) through the built-in `cabbage` tool — create the record, declare risk flags, verify stages, pass gates, sync to docs, archive after merge. Use for bug fixes, refactors, small features, hotfixes, or whenever a tracked record with tasks.md and verification evidence is required in this repository.
+---
+
+# flow-change
+
+本仓库的变更记录机制由插件内置的 Cabbage 引擎提供（`cabbage` 工具，无需手工安装）。
+一份记录 = 一个目录（`.cabbage/changes/<id>/`）：默认只有一份 `tasks.md`，
+高风险时用影响标记展开专项文档；验证通过、合并确认后归档并同步到 `docs/`。
+
+## 何时启用
+
+- 任何需要留痕的代码改动：bug 修复、重构、小功能、紧急修复、业务调整。
+- 大流程（requirements/design/code/...）中的具体代码改动：在对应阶段用记录承载
+  Goal/Design/Tasks/Verification 与验收证据。
+- **不启用**：纯文档小修（直接改归属文档，用 `flow-docs` 约定）、一次性问答、纯调研
+  （见 `flow-research`，调研本身不建记录）。
+
+## 默认路径：一次变更一份记录
+
+1. 创建记录（需要项目已初始化；未初始化先 `op:"init"`）：
+   - `cabbage({op:"new", type:"change", change:"fix-label"})`
+   - 事故复盘用 `type:"incident"`（incident → postmortem → tasks）。
+2. 填写 `tasks.md`：`Goal`（含复现的问题）、`Design`（最小方案）、`Tasks`、`Verification`。
+3. 实现前评估风险并声明标记（会生成对应专项文档）：
+   - `cabbage({op:"impact", change:"fix-label", impact:["api=true","design=true"]})`
+   - 标记表：`design`→tech-spec、`rfc`→rfc、`architecture`→adr、`api`→api-design、
+     `database`→database-design、`security`→security-review、`deployment`→release-plan。
+   - 数据迁移 = `database` + `deployment`；跨团队评审 = `rfc`（+按需 `design`）。
+4. 复现失败 → 最小修复 → 回归测试；完成任务清单并写入真实命令与结果。
+5. 逐级验证与门禁：
+   - `cabbage({op:"verify", change:"fix-label", stage:"tasks"})`（有专项阶段先逐一验证）
+   - `cabbage({op:"gate", change:"fix-label", target:"merge"})` → 应输出 ALLOWED。
+6. 合并后收尾：确认合并 → `cabbage({op:"archive", change:"fix-label"})`（自动 sync + 归档）。
+
+速查（亮路径全链路）：
+
+```text
+cabbage({op:"new", type:"change", change:"fix-label"})
+cabbage({op:"impact", change:"fix-label", impact:["api=true"]})   # 仅在确有风险时
+cabbage({op:"verify", change:"fix-label", stage:"tasks"})          # 专项阶段先行
+cabbage({op:"gate", change:"fix-label", target:"merge"})           # 期望 ALLOWED
+cabbage({op:"archive", change:"fix-label"})                        # 确认合并后
+```
+
+## 约束
+
+- `change.yaml` 与 `state.json` 由 CLI 管理，不要手工编辑；验证后修改产物会让阶段 `stale`。
+- 只声明真实风险；不为省文档隐瞒影响，也不为凑文档虚报标记。
+- `archive` 不检查 Git 合并状态：必须人工确认合并后再归档。
+- 记录描述单次改动；系统当前行为写入 `docs/` 编号目录（sync 只按映射复制，不做语义合并）。
+- CLI 不可用（缺 Python 3.10+）时工具会返回明确错误：告知用户安装 Python，不要伪造验证结果。
+
+## 常用操作
+
+| 操作 | 用途 |
+| --- | --- |
+| `init` | 初始化 `.cabbage/`（工作流、CI 模板、vendored CLI），每项目一次 |
+| `status` / `next` | 记录列表与阶段就绪/阻塞（不猜阶段 ID，以 `next` 为准） |
+| `verify` / `gate` | 阶段验证与门禁（`target`：阶段 ID / `merge` / `archive`） |
+| `validate` | 结构校验（省略 `change` 校验全部） |
+| `sync` / `archive` | 同步当前文档 / 收尾归档 |
+| `tasks` / `discard` | 任务清单只读视图 / 废弃记录 |
+
+> 无本插件工具的环境（如 Codex）：以上操作对应 `python3 -m cabbage_cli <操作>` 直跑 CLI
+> （CLI 需本地可用），语义与参数一致。
+
+## Contract
+
+### Trigger
+由 `@dev-lifecycle` 分诊（Bug 修复、重构、业务调整、紧急修复等轻量路径）或用户要求建立变更记录时触发；
+大流程的代码改动也可在实现阶段引用本 skill。
+
+### Inputs
+- 变更描述（问题/目标、影响范围）
+- 变更 id（kebab-case，按功能派生）
+- 可选：影响标记（design/rfc/architecture/api/database/security/deployment）
+
+### Preconditions
+- 项目已初始化（无 `.cabbage/` 时先 `init`）
+- 插件内置引擎可用（缺 Python 3.10+ 时停止并告知用户）
+
+### Procedure
+1. 创建记录并填写 `tasks.md` 的 Goal 与 Design
+2. 实现前声明真实风险标记（必要时）
+3. 实现并完成 Tasks 清单，记录真实验证命令与结果
+4. 逐一 `verify` 已启用阶段（专项在前、`tasks` 在后）
+5. `gate merge` 通过后交回编排器提交；合并确认后 `archive`
+
+### Outputs
+- `.cabbage/changes/<id>/`：tasks.md 与按需专项文档（验证后签名写入 state.json）
+- 归档：`.cabbage/archive/<year>/<id>/` 与 `docs/` 的同步文档
+
+### Failure
+- `gate` BLOCKED → 用 `next` 找到未完成的已启用前置阶段并验证
+- `placeholder content remains` / `unchecked tasks remain` → 清除模板提示、勾选任务后再验证
+- 阶段 `stale` → 对照上游变化重新审阅并重新验证
+- CLI 不可用 → 告知用户安装 Python 3.10+，不得伪造记录或验证结果
+
+### Idempotency
+- 同名记录已存在 → 复用并更新（`new` 报错说明已存在）
+- 重复 `verify` 同一未变化阶段 → 幂等，仅刷新签名时间
+- 重复 `sync` → 按映射覆盖目标文档，无副作用
+
+### Prohibited Actions
+- 不手工编辑 `change.yaml` / `state.json`
+- 不在实现前伪造验证结果（专项文档写待执行步骤，真实结果回填 `tasks.md`）
+- 不在未确认合并时 `archive`；不为通过门禁删改 CI 与工作流文件

package/assets/skills/flow-design/SKILL.md

@@ -29,6 +29,21 @@ description: 技术方案设计 → 方案文档 + ADR → Planning PR
    ```
 4. **合入基线**：PR 合并后即形成设计基线（Planning Baseline），后续任务拆解以此为前置。
 
+## ADR 内容标准
+
+ADR 是决策记录，不是设计文档。只有改变组件边界、拓扑、关键依赖或数据归属的决策才写 ADR；
+仅实现细节、内部重构、无长期影响的选型不写，记入变更记录即可。
+
+必需标题（工作流逐字校验 `Context` / `Decision` / `Consequences`）：
+
+- `Context`：约束和现状，不写解决方案。
+- `Decision`：选了什么**以及为什么**，列出被否决的备选方案和否决理由。
+- `Consequences`：同时写正面和负面影响，包括引入的运维负担与待办。
+
+需要跨团队评审、方案尚未定案时先写 RFC（`Problem` / `Proposal` / `Alternatives`），评审通过后再落 ADR。
+**已合并的 ADR/RFC 不重命名、不改写**：新决策用新记录显式取代旧的，旧记录保留可追溯。
+完整接口契约进 API 文档、表结构与迁移进数据库文档、测试策略进测试计划——不要塞进 ADR。
+
 ## 设计约束
 
 技术方案必须遵循以下原则：

package/assets/skills/flow-docs/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: flow-docs
+description: Write and organize long-lived project documentation — numbered docs tree placement, stable naming, relative links and anchors, Mermaid diagrams, ownership, and site preview or build. Use when authoring or moving current-state docs, fixing broken links, or running the documentation site.
+---
+
+# flow-docs
+
+面向长期存在的**当前状态文档**（系统现在如何工作）。变更记录与门禁由 `flow-change` 负责。
+
+## 目录归属（编号树）
+
+`cabbage init` 生成的当前状态文档写入 `docs/` 下的编号目录，只创建有实际内容的目录：
+
+| 目录 | 内容 |
+| --- | --- |
+| `00-overview/` | 项目概览、范围、快速上手 |
+| `01-product/` | 需求、用户故事、验收标准 |
+| `02-design/` | 交互与视觉设计、原型说明 |
+| `03-architecture/` | 系统设计、`adr/`、`rfc/` |
+| `04-domain/` | 数据模型、数据库设计、迁移与回滚 |
+| `05-api/` | 接口契约、事件、集成 |
+| `06-development/` | 本地开发环境、构建与调试 |
+| `07-standards/` | 编码规范、评审约定 |
+| `08-testing/` | 测试策略与用例 |
+| `09-security/` | 威胁模型、权限与合规控制 |
+| `10-infrastructure/` | 部署拓扑、容量、环境配置 |
+| `11-ci-cd/` | 流水线定义与门禁说明 |
+| `12-release/` | 发布流程与版本策略 |
+| `13-operations/` | 运行手册、监控、应急预案 |
+| `14-performance/` | 性能基线与压测结果 |
+| `15-incidents/` | 事故记录与复盘（不可改写的历史） |
+| `16-dependencies/` | 外部依赖清单与升级策略 |
+| `17-compliance/` | 合规要求与审计证据 |
+
+- 变更记录归档时 `archive` 自动 `sync`，把专项文档复制进对应编号目录；`sync` 只按映射复制，
+  不做语义合并。
+- 流程阶段产出的 PRD / 技术方案 / ADR 保留各自路径（`docs/prd/`、`docs/dev/specs/`、`docs/adr/`），
+  与编号树各司其职：前者是流程产物，后者是长期当前状态。
+- `.cabbage/changes/` 是变更历史，`docs/` 是当前状态，两者不互相复制内容。
+
+## 写作原则
+
+1. **单一事实来源**：一个事实只在一处定义，其他文档链接过去，不复制正文。
+2. **当前状态 vs 决策历史**：当前状态文档原处更新；ADR/RFC/事故记录是不可改写的历史。
+3. **稳定路径**：不使用 `spec-v2-final.md`、`_latest.md`、`_copy.md` 这类文件名，版本交给 Git。
+4. **相对链接**：仓内链接一律用相对路径并带文件扩展名，不写 `/docs/...` 绝对路径。
+5. **不写占位内容**：`TODO`、`TBD`、`FIXME` 会导致校验失败。
+
+## 校验与站点
+
+```bash
+cabbage({op:"validate"})            # 结构、标题锚点、相对路径、Mermaid 围栏（不要求先建变更）
+cabbage({op:"validate", change:"x"})  # 或只校验某条记录
+```
+
+站点（如仓库使用 VitePress）：`pnpm --dir docs run dev` 预览、`pnpm --dir docs run build` 构建；
+构建失败先跑 `validate`（省略 `change` 校验全部）定位死链，再检查围栏闭合与 HTML 标签。
+
+## 图表
+
+使用 Mermaid，写在 ` ```mermaid ` 围栏内；围栏必须闭合，否则校验与站点构建都会失败。
+常用类型：流程图、时序图、状态图、ER 图。图表只画难以用文字表达的关系。
+
+## 归属与评审
+
+关键长期文档应在 frontmatter 声明维护方：
+
+```yaml
+---
+owner: team-billing
+maintained-by: ["@alice"]
+last-reviewed: 2026-03-01
+---
+```
+
+用 `.github/CODEOWNERS` 让架构、安全等目录的改动必须由对应负责人评审。
+该 frontmatter 是约定，CLI 不校验也不强制；真正的强制来自代码托管平台的分支保护。
+
+## Contract
+
+### Trigger
+撰写或移动当前状态文档、修复死链、整理文档归属、预览或构建文档站点时触发。
+
+### Inputs
+- 文档内容或需要修复的链接/结构问题
+- 目标编号目录（按内容性质选择）
+
+### Preconditions
+- 项目 docs 树已存在（未初始化时先经 `flow-change` 执行 `op:"init"`）
+
+### Procedure
+1. 按内容性质选择编号目录；只创建有实际内容的目录
+2. 遵循写作原则（单一事实来源、稳定路径、相对链接、无占位）
+3. `op:"validate"` 校验结构与链接；站点项目再执行构建
+4. 关键文档补 frontmatter 归属；治理目录配 CODEOWNERS
+
+### Outputs
+- `docs/` 编号目录下的当前状态文档（或修复后的链接/结构）
+
+### Failure
+- `broken link` → 修正相对路径层级或锚点 slug，确认目标文件存在
+- 链接越出项目根 → 改用仓内相对路径
+- 站点依赖缺失 → 重新安装站点依赖后再构建
+
+### Idempotency
+- 重复 `validate` → 幂等只读
+- 同一批移动操作分批提交 → 每批后校验保持可构建
+
+### Prohibited Actions
+- 不用 `final-v2`、`_latest`、`_copy` 之类文件名
+- 不改写已归档的历史记录（ADR/RFC/事故）
+- 不在当前状态文档与变更记录间复制正文

package/assets/skills/flow-incident/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: flow-incident
+description: Document production incidents and postmortems — incident timeline, impact, containment and recovery, blameless root cause, corrective actions grounded through the built-in Cabbage engine. Use for outages, severity events, live-service failures, or writing a postmortem retrospective.
+---
+
+# flow-incident
+
+处置生产事故时，先止损、再取证、后复盘。**不要在事故进行中伪造完整时间线或结论。**
+
+## 流程（经内置引擎）
+
+```text
+cabbage({op:"new", type:"incident", change:"payment-timeout-2026-08-29"})
+cabbage({op:"next", change:"payment-timeout-2026-08-29"})        # 阶段：incident → postmortem → tasks
+# 1. 记录事实：填写 incident.md
+cabbage({op:"verify", change:"payment-timeout-2026-08-29", stage:"incident"})
+# 2. 分析根因：填写 postmortem.md
+cabbage({op:"verify", change:"payment-timeout-2026-08-29", stage:"postmortem"})
+# 3. 预防措施落地：完成任务清单
+cabbage({op:"verify", change:"payment-timeout-2026-08-29", stage:"tasks"})
+cabbage({op:"gate", change:"payment-timeout-2026-08-29", target:"merge"})
+# 合并确认后：
+cabbage({op:"archive", change:"payment-timeout-2026-08-29"})
+```
+
+阶段 ID 以 `next` 输出为准：`incident` → `postmortem` → `tasks`。前两个阶段是事实与分析，第三个阶段是实际修复与预防措施。
+
+**分级降载**：正在处置的紧急故障不要为了走流程而拖延止血。先经 `flow-change` 走最小修复路径
+（`type:"change"` + 声明 `deployment=true`），事后另立 incident 记录复盘；不要把两者混在同一记录里。
+
+## incident.md：先记事实
+
+必需标题 `Impact` / `Timeline` / `Mitigation`。
+
+- 时间戳统一用 UTC 或明确标注时区；事故期间先记原始观测，不追求措辞。
+- `Impact` 量化受影响用户数、时长、区域、功能、数据与 SLO 影响；无法量化时写估计方法与误差。
+- `Timeline` 记录事件、观测与采取的行动及其执行人，包括误判和无效尝试。
+- `Mitigation` 区分 **Containment**（如何限制影响，如回滚、摘流量、限流）与 **Recovery**（如何恢复，
+  及仍然降级的行为）。
+- 恢复后补 `Recovery Verification`：证明恢复的指标、检查项与观察窗口。
+- 不要写"疑似"当结论；不确定的内容标注为待确认。
+
+## postmortem.md：对事不对人
+
+必需标题 `Root Cause` / `Contributing Factors` / `Corrective Actions`。
+
+- 区分 **触发点**（直接原因）与 **根因**（使其可能且未被拦截的系统条件）。
+- 根因结论要有证据支撑：日志、指标、变更记录、复现步骤，而非推测。
+- `Corrective Actions` 每项必须有单一责任人、期限、验证方式与状态；笼统的"加强监控""提高意识"
+  不是可验证的措施。
+- 保持无责文化：记录系统为何允许人为错误造成影响，不记录个人过失。
+
+## tasks.md：预防措施落地
+
+`postmortem.md` 中的措施要落到实际任务，完成并验证后才通过阶段。
+只写计划不执行会阻塞合并门禁，这是刻意的：复盘结论必须兑现。
+
+## 边界
+
+- 事故记录与变更记录都属于决策历史，归档后不重写、不"现代化"措辞。
+- 当前系统的运行方式写到长期运行文档；事故报告本身是历史记录。
+- 结构校验只检查标题、占位符与链接，不判断根因分析是否正确；复盘质量仍需人工评审。
+
+## Contract
+
+### Trigger
+生产事故、严重事件、线上服务故障的处置与复盘；或用户要求撰写事故报告时触发。
+
+### Inputs
+- 事故基本事实（时间、影响、止损与恢复过程）
+- 证据材料（日志、指标、变更记录、复现步骤）
+
+### Preconditions
+- 事故已止血或已恢复（进行中不写完整复盘）
+- 项目已初始化（无 `.cabbage/` 时先经 `flow-change` 执行 `op:"init"`）
+
+### Procedure
+1. `op:"new" type:"incident"` 创建记录并如实填写 incident.md（Impact/Timeline/Mitigation）
+2. 验证 incident 阶段后撰写 postmortem.md（根因、促成因素、纠正措施）
+3. 将纠正措施落成 tasks.md 清单并实际执行
+4. 逐阶段 `verify` → `gate merge` → 合并确认后 `archive`
+
+### Outputs
+- `.cabbage/changes/<id>/`：incident.md、postmortem.md、tasks.md（验证后签名）
+- 归档后：`.cabbage/archive/<year>/<id>/`
+
+### Failure
+- 时间线/证据不完整 → 标注待确认，不编造；补齐后重新验证
+- 措施无法在本次完成 → 转入独立变更（flow-change）跟踪，本记录如实标注状态
+
+### Idempotency
+- 重复 `verify` 未变化阶段 → 幂等
+- 事故期间多次追加时间线 → 更新产物后重新验证
+
+### Prohibited Actions
+- 不在处置进行中伪造完整时间线或根因结论
+- 不把紧急修复与事故复盘混在同一记录
+- 不将未执行的预防措施勾选为完成

package/assets/skills/flow-research/SKILL.md

@@ -21,6 +21,15 @@ description: 调研/事实核查 — 迭代深化 + 一手来源评分 + 反方
 7. **元评审**（输出前自省）：剩余未知、最弱证据、可能错误的假设、遗漏角度、边际收益。
 8. **输出**：写 `docs/dev/research/<topic>.md`，并在消息中给结论/可执行建议摘要。
 
+## 调研纪律
+
+1. **先定义决策，后收集资料**：开始前写下"要回答什么问题"和"什么条件下选哪个方案"；结论不改变决策就不调研。
+2. **硬性约束优先于加权评分**：不满足硬性约束的方案直接淘汰，不进入评分表。
+3. **事实、推断、未知项分开**：不得把推断写成事实；无法验证就写"待验证"，禁止补全式猜测。
+4. **优先验证失败路径**，不只验证正常路径。
+5. **PoC 边界**：只验证会导致方案被否决的那个假设，不开发完整系统。
+6. **推荐必须包含适用边界、代价和退出条件**（什么信号出现时需要重新评估）。
+
 ## 何时停止迭代
 
 - 所有关键问题 ≥2 个独立来源支持

package/assets/skills/flow-setup/SKILL.md

@@ -39,6 +39,19 @@ description: 初始化 — 探测环境 → 确认 Profile
 - release workflow: `.github/workflows/release.yml`
 ```
 
+## 存量项目接入（adopt）
+
+仓库已有文档时（`init` 只新增骨架、不改写已有文件；无 `.cabbage/` 时先经 flow-change 执行 `op:"init"`）：
+
+1. `cabbage({op:"adopt"})` 盘点 `docs/` 树之外的 Markdown → 生成 `.cabbage/` 下的 `adoption-report.md`；
+   每份文档得到四种动作：`keep`（已在编号目录）/ `migrate`（当前状态文档）/ `import`（历史记录）/
+   `review`（无法归类）。分类仅基于目录与文件名推断，**始终需要人工确认**。
+2. 逐行处理 `review`，与文档负责人确认归属；`import` 的历史记录（ADR/RFC/事故）原样归档，
+   **不改写内容**。
+3. `migrate` 用 `git mv` 保留历史，一个逻辑批次一个提交；移动后立即修正相对链接。
+4. 每批后 `cabbage({op:"validate"})` + 站点构建，确认无死链。
+5. 接入完成的判据：再次 `op:"adopt"` 应全部报告 `keep`。
+
 ## Output
 - readiness 报告（git/gh 可用性、CI/release workflow 存在性）
 - 根 AGENTS.md `## Project Profile` 区块