@devcxl/opencode-cabbage 1.2.0 → 2.0.0

package/codex-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/codex-skills/flow-code/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: flow-code
+description: 编码实现 — worktree + TDD（flow-tdd 协议）
+---
+
+# flow-code
+
+认领 Task Record（Sub Issue），在 worktree 内按 TDD 实现代码与单测。
+worktree 创建、PR 提交由 primary 编排器执行，本 skill 定义编码流程。
+
+## 核心流程
+
+1. **创建/复用 worktree**（编排器执行）
+   ```bash
+   BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
+   git worktree add ".worktree/<task-slug>" -b "feat/<task-slug>" "$BASE"
+   cd ".worktree/<task-slug>" && pwd
+   ```
+2. 加载 `flow-tdd` skill，按 Task 的验收标准执行 RED→GREEN cycle（self-report）
+3. 本地 `git add`（限定文件）+ `git commit`（多次提交）
+4. **不 push、不创建 PR** — 由 primary 编排器统一执行
+
+## 编码约束
+
+- 只改 Task 相关的文件；遵循项目现有代码规范与分层结构
+- 遵循工程原则（KISS/YAGNI/DRY/SRP/最小变更，单份引用仓库 AGENTS.md）
+- 文档同步：涉及 guides/api/db 变更时随代码同 PR 更新
+
+## TDD 引用
+
+> `flow-tdd` skill 是 TDD 协议的唯一来源，包含完整的 RED→GREEN cycle 状态机、
+> abandon-cycle 规则和 final-regression/verification 流程。测试质量由仓库 CI 把关。
+
+## Output
+- 本地 commit 就绪（分支推送与 PR 由编排器完成）
+
+## 后续
+- **/review** — 审查 PR
+
+## Contract
+
+### Trigger
+由 `/code` 命令或 `@dev-lifecycle` Phase 3 触发。
+
+### Inputs
+- Task Record（Sub Issue 编号与标题，来源：`/tasks` 产出）
+
+### Preconditions
+- `/tasks` 已完成 → Sub Issues 就绪
+- 设计基线已合入；前置依赖任务已合并
+
+### Procedure
+1. 在 `.worktree/<task-slug>` 创建/复用 worktree（编排器执行）
+2. 加载 `flow-tdd`，按 Task 验收标准执行 RED→GREEN cycle
+3. 本地 git add + commit（不 push）
+4. 交回 primary 编排器 push + 创建 PR
+
+### Outputs
+- 本地 commit
+
+### Failure
+- worktree 创建失败 → 检查分支冲突或目录残留
+- 测试失败 → 修复后重试（不跳过 RED）
+
+### Idempotency
+- worktree 已存在 → 校验分支一致性后复用
+- 代码已提交 → 追加提交
+
+### Prohibited Actions
+- 不 push、不创建 PR、不操作 Issue（由编排器统一执行）
+- 不使用 `git add .`（限定变更文件）

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

@@ -0,0 +1,161 @@
+---
+name: flow-design
+description: 技术方案设计 → 方案文档 + ADR → Planning PR
+---
+
+# flow-design
+
+基于 PRD 进行技术方案设计，产出方案文档与 ADR，并通过 Planning PR 合入形成设计基线。
+
+## 核心流程
+
+1. **创建工作分支**（在默认分支基础上）
+   ```bash
+   BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
+   git checkout $BASE && git pull origin $BASE
+   git checkout -b "feat/<slug>-design"
+   ```
+2. **产出文档**：
+   - 根 `CONTEXT.md` 术语更新（如发现新领域术语）
+   - `docs/prd/<title>.md`（PRD 确认版）
+   - `docs/dev/specs/<title>.md`（技术方案）
+   - `docs/adr/<date>-<slug>.md`（ADR 决议）
+3. **提交并创建 Planning PR**
+   ```bash
+   git add -A && git commit -m "docs: <slug> design baseline"
+   git push -u origin "feat/<slug>-design"
+   gh pr create --base $BASE --head "feat/<slug>-design" \
+     --title "design: <slug>" --body "Planning Baseline for <slug>"
+   ```
+4. **合入基线**：PR 合并后即形成设计基线（Planning Baseline），后续任务拆解以此为前置。
+
+## ADR 内容标准
+
+ADR 是决策记录，不是设计文档。只有改变组件边界、拓扑、关键依赖或数据归属的决策才写 ADR；
+仅实现细节、内部重构、无长期影响的选型不写，记入变更记录即可。
+
+必需标题（工作流逐字校验 `Context` / `Decision` / `Consequences`）：
+
+- `Context`：约束和现状，不写解决方案。
+- `Decision`：选了什么**以及为什么**，列出被否决的备选方案和否决理由。
+- `Consequences`：同时写正面和负面影响，包括引入的运维负担与待办。
+
+需要跨团队评审、方案尚未定案时先写 RFC（`Problem` / `Proposal` / `Alternatives`），评审通过后再落 ADR。
+**已合并的 ADR/RFC 不重命名、不改写**：新决策用新记录显式取代旧的，旧记录保留可追溯。
+完整接口契约进 API 文档、表结构与迁移进数据库文档、测试策略进测试计划——不要塞进 ADR。
+
+## 设计约束
+
+技术方案必须遵循以下原则：
+
+1. **首选最简单方案** — 如果两个方案都能满足 PRD，选更简单的
+2. **不引入不必要的新技术** — 不要因为"这个技术很流行"而使用它
+3. **方案自检** — 每个设计决策必须能回答"为什么不用更简单的替代方案？"
+4. **ADR 记录简化决策** — 如果选择复杂方案，必须在 ADR 中说明为何简单方案不够
+
+## 设计语言
+
+技术方案使用以下语言描述可测试设计：
+
+- **Module** — 具有 Interface 与 Implementation 的模块，不限定为函数、类或包。
+- **Interface** — 调用者正确使用 Module 必须知道的全部信息，包括输入输出、约束、错误与副作用。
+- **Seam** — 可以通过 Interface 观察或替换行为的位置，也是测试验证行为的公共边界。
+- **Adapter** — 在 Seam 处满足 Interface 的具体实现。
+- **Depth** — Interface 越小、背后隐藏的有效复杂性越多，Module 越深。
+
+设计时必须检查：
+
+1. Interface 是否保持小而完整，并把复杂性留在 Module 内部，而不是泄漏给多个调用者。
+2. 调用者与测试是否可以通过同一个 Seam 使用和验证行为。
+3. 是否真的需要新的 Seam。一个 Adapter 只代表假设的 Seam；只有存在真实替换需求或多个 Adapter 时才引入抽象。
+4. 是否出现只做透传的浅 Module、`FooService/FooServiceImpl` 式空壳抽象或为未来预留的 Interface。
+
+## Testing Decisions
+
+技术方案必须包含 `Testing Decisions`，在进入 Task Planning 前为每个关键行为明确：
+
+```markdown
+## Testing Decisions
+
+### <behavior>
+
+- Test Seam: <用于触发并观察行为的公共 Interface>
+- Observable Result: <通过该 Seam 可观察的结果或错误>
+- Test Level: <与仓库现有测试体系一致的最窄有效层级>
+```
+
+Test Seam 应描述公共行为边界，例如 Session API，而不是 `SessionRepositoryImpl.restore()` 等实现细节。优先复用现有 Seam；不要为了方便 mock 而创建生产抽象。
+
+## 存量 Design Amendment
+
+当 tasks、code 或 review 阶段发现旧技术方案缺少 `Testing Decisions` 时，调用方可以在**保持当前 lifecycle stage 不变**的前提下委派 `@architect` 补齐设计：
+
+1. 读取 Design Gap、原技术方案、相关 PRD / ADR 与 repository context。
+2. 优先识别仓库已有的公共 Interface 和测试惯例，不为了补字段创建新 Seam。
+3. 只向原技术方案补充缺失行为的 `Testing Decisions`，不重写其他设计内容。
+4. 返回已修改文件和补充的 behavior / Test Seam / Observable Result。
+
+如果补齐过程暴露新的架构取舍或多个无法直接判断的 Seam 方案，停止 amendment 并把决策交给用户；不得静默扩大设计。Design Amendment 不回退 goal stage、不重复勾选阶段，也不单独创建新的 lifecycle 状态。
+
+Design Amendment 是兼容子流程，覆盖本 skill 的普通发布流程：不创建 design 分支、Planning PR 或新 ADR。`@architect` 只修改技术方案，primary 负责在当前 stage 保存变更并把补充内容传给后续 agent。
+
+## CONTEXT.md 术语
+
+阅读项目根 CONTEXT.md（领域术语权威，已自动注入内容与 digest）；
+设计中发现的新术语经用户确认后写入根 CONTEXT.md。
+
+## Output
+- `docs/dev/specs/<title>.md` — 技术方案（包含 Module / Interface 设计与 Testing Decisions）
+- `docs/adr/<date>-<slug>.md` — ADR 决议
+- 根 CONTEXT.md 术语更新（如发现新术语）
+- Planning PR（合入后 = 设计基线）
+
+## 后续
+- **/tasks** — 基于设计方案拆解为 DAG 任务
+
+## Contract
+
+### Trigger
+由 `/design` 命令、`@dev-lifecycle` Phase 1，或存量 Flow 的 Testing Decisions 兼容门触发。
+
+### Inputs
+- `docs/prd/<title>.md` — 上游 PRD（来源：requirements 阶段产出）
+- Parent Issue 编号（来源：requirements 阶段产出）
+
+### Preconditions
+- `/requirements` 已完成 → PRD 与 Parent Issue 存在
+- requirements 基线已用户确认
+
+### Procedure
+普通 design 流程：
+
+1. 基于默认分支创建工作分支
+2. 阅读 PRD、已有 ADR、根 CONTEXT.md 术语
+3. 识别 Module、Interface 与真实 Seam，检查深度、局部性和抽象必要性
+4. 为关键行为定义 Testing Decisions，明确公共 Test Seam 与可观察结果
+5. 输出技术方案到 `docs/dev/specs/<title>.md`
+6. 记录 ADR 到 `docs/adr/<YYYY-MM-DD>-<slug>.md`
+7. 提交并创建 Planning PR
+
+存量 Design Amendment 改用“存量 Design Amendment”章节的受限流程，不执行以上分支、ADR 与 Planning PR 步骤。
+
+### Outputs
+- 技术方案（包含 Testing Decisions）+ ADR
+- Planning PR
+
+### Failure
+- ADR 与已有决策冲突 → 记录冲突并标注
+- 关键行为没有稳定的公共 Test Seam → 暂停设计，先调整 Interface 或明确缺失决策
+- Planning PR 创建失败 → 通知用户手动处理
+
+### Idempotency
+- 技术方案已存在 → 读取并更新
+- 已有完整 `Testing Decisions` → 不重复 amendment
+- ADR 已存在 → 不重复创建
+- 分支已存在 → 检出后追加提交
+
+### Prohibited Actions
+- 不跳过 ADR 兼容性检查
+- 不创建只有一个假设 Adapter、没有真实替换需求的 Seam
+- 不以实现方法、私有协作对象或调用顺序作为 Test Seam
+- 不直接 push 到默认分支（写操作走分支 + PR）

package/codex-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/codex-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/codex-skills/flow-release/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: flow-release
+description: 版本 → Release PR → GitHub Actions 发布（仅人工）
+---
+
+# flow-release
+
+完成版本提议、Release PR、合并发布与发布监控。
+发布流程技术栈无关：按 Profile 的版本规则（version file / tag format / release workflow）执行，
+最终发布走项目自己的 GitHub Actions release workflow（不假设 npm 或任何特定生态）。
+
+## 核心流程
+
+1. **确定版本**：聚合上一 tag 后全部 commit，按 Profile 版本规则分类（breaking→major, feature→minor, fix→patch），输出提议版本
+   ```bash
+   git describe --tags --abbrev=0
+   git log --oneline <last-tag>..HEAD
+   ```
+2. **创建 Release 分支 + 更新版本文件**
+   ```bash
+   git checkout -b "release/<version>"
+   # 按 Profile 版本文件规则更新版本号（如 package.json 的 version 字段）
+   git add -A && git commit -m "chore: release <version>"
+   git push -u origin "release/<version>"
+   ```
+3. **创建 Release PR**（人工确认后）
+   ```bash
+   gh pr create --base <default> --head "release/<version>" \
+     --title "release: <version>" --body "<release notes>"
+   ```
+4. **合并 + 打 tag push**
+   ```bash
+   HEAD_SHA=$(gh pr view <pr-number> --json headRefOid --jq .headRefOid)
+   gh pr merge <pr-number> --squash --delete-branch --match-head-commit "$HEAD_SHA"
+   MERGE_SHA=$(gh pr view <pr-number> --json mergeCommit --jq .mergeCommit.oid)
+   git tag "v<version>" "$MERGE_SHA"
+   git push origin "v<version>"
+   ```
+5. **监控发布**：tag push 触发项目 GitHub Actions release workflow，跟踪其运行结果；瞬时失败可重跑；代码/配置缺陷 → Corrective Flow
+
+## 版本规则（Profile）
+
+版本分类依赖 AGENTS.md `## Project Profile` 的 `version bump rule`：
+`breaking→major, feature→minor, fix→patch`（0.x breaking 也 major）。
+未分类 commit → 请用户分类后重试。
+
+## Output
+- 提议版本
+- Release PR（合并 + tag push）
+- GitHub Actions release workflow 运行结果
+
+## 后续
+- 发布完成后 Flow 结束（goal-verify 独立验证 → goal complete）
+
+## Contract
+
+### Trigger
+由 `/release` 命令触发。**仅手动触发**，不包含在自动流程中。
+
+### Inputs
+- 用户对提议版本/Release 的确认
+
+### Preconditions
+- 所有 PR 已合并
+- 默认分支最新且 CI 通过
+- Release Profile 已确认（AGENTS.md Project Profile）
+
+### Procedure
+1. 聚合 commit 确定版本
+2. 创建 release 分支 + 更新版本文件
+3. 创建 Release PR（人工确认）
+4. 合并 + 打 tag push
+5. 监控发布 workflow
+
+### Outputs
+- GitHub Release（经项目 release workflow）
+- tag 已推送
+
+### Failure
+- 发布 workflow 失败 → 识别瞬时失败并重跑；代码/配置缺陷 → Corrective Flow + 新版本
+- tag 已存在 → 提示版本冲突，不强制覆盖
+
+### Idempotency
+- 相同版本号 → 阻止重复发布（tag 不可变）
+
+### Prohibited Actions
+- 不在自动模式中执行（release 为人工流程）
+- 不假设 npm 或其他特定技术生态（按 Profile 规则 + 项目 GitHub Actions release workflow）
+- 不跳过测试/CI 直接发布
+- 不强制覆盖已存在的 tag