From 40acb73fe194f7ef60984eb5659b1562d13465ef Mon Sep 17 00:00:00 2001
From: laserduor <312182928+laserduor@users.noreply.github.com>
Date: Mon, 3 Aug 2026 18:21:44 +0000
Subject: [PATCH 1/3] feat: add Codex plugin compatibility layer (skills +
hooks + manifest)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Add Codex plugin support alongside existing OpenCode plugin:
- .codex-plugin/plugin.json — Codex plugin manifest
- skills/ — 8 flow-* skill symlinks + 5 agent SKILL.md files
(agent-dev-lifecycle, agent-architect, agent-developer,
agent-reviewer, agent-goal-verify)
- hooks/hooks.json + hooks/session-start.ts — SessionStart hook
injecting skill overview and project context
- package.json — updated keywords and description
The Codex layer is purely additive: it reuses the same assets/skills/
and assets/agents/ content, repackaged as Codex-compatible skills.
No existing OpenCode functionality is modified.
---
.codex-plugin/plugin.json | 37 +++++++
hooks/hooks.json | 15 +++
hooks/session-start.ts | 56 ++++++++++
package.json | 7 +-
skills/agent-architect/SKILL.md | 64 +++++++++++
skills/agent-dev-lifecycle/SKILL.md | 162 ++++++++++++++++++++++++++++
skills/agent-developer/SKILL.md | 48 +++++++++
skills/agent-goal-verify/SKILL.md | 40 +++++++
skills/agent-reviewer/SKILL.md | 96 +++++++++++++++++
skills/flow-code | 1 +
skills/flow-design | 1 +
skills/flow-release | 1 +
skills/flow-requirements | 1 +
skills/flow-review | 1 +
skills/flow-setup | 1 +
skills/flow-tasks | 1 +
skills/flow-tdd | 1 +
17 files changed, 532 insertions(+), 1 deletion(-)
create mode 100644 .codex-plugin/plugin.json
create mode 100644 hooks/hooks.json
create mode 100644 hooks/session-start.ts
create mode 100644 skills/agent-architect/SKILL.md
create mode 100644 skills/agent-dev-lifecycle/SKILL.md
create mode 100644 skills/agent-developer/SKILL.md
create mode 100644 skills/agent-goal-verify/SKILL.md
create mode 100644 skills/agent-reviewer/SKILL.md
create mode 120000 skills/flow-code
create mode 120000 skills/flow-design
create mode 120000 skills/flow-release
create mode 120000 skills/flow-requirements
create mode 120000 skills/flow-review
create mode 120000 skills/flow-setup
create mode 120000 skills/flow-tasks
create mode 120000 skills/flow-tdd
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
new file mode 100644
index 0000000..57c4203
--- /dev/null
+++ b/.codex-plugin/plugin.json
@@ -0,0 +1,37 @@
+{
+ "name": "opencode-cabbage",
+ "version": "1.1.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": "./skills/",
+ "hooks": "./hooks/hooks.json",
+ "interface": {
+ "displayName": "OpenCode Cabbage",
+ "shortDescription": "全流程开发编排 — 需求到自动合并，双平台兼容",
+ "longDescription": "覆盖需求、设计、DAG 任务拆解、并行编码（TDD）、审查与自动合并的全流程开发编排插件。兼容 OpenCode 与 Codex 双平台，提供 8 个 flow skills 和 5 个 agent skills。",
+ "developerName": "devcxl",
+ "category": "Development",
+ "capabilities": ["Read", "Write"],
+ "defaultPrompt": [
+ "使用 OpenCode Cabbage 初始化项目 — 运行 /setup 开始",
+ "使用 OpenCode Cabbage 从需求到实现 — 使用 @dev-lifecycle 自动编排全流程",
+ "使用 OpenCode Cabbage 的 flow-setup skill 初始化项目开发环境"
+ ],
+ "brandColor": "#00bcd4"
+ }
+}
\ No newline at end of file
diff --git a/hooks/hooks.json b/hooks/hooks.json
new file mode 100644
index 0000000..e713cd5
--- /dev/null
+++ b/hooks/hooks.json
@@ -0,0 +1,15 @@
+{
+ "hooks": {
+ "SessionStart": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "node ${PLUGIN_ROOT}/dist/hooks/session-start.js",
+ "statusMessage": "Loading Cabbage development context"
+ }
+ ]
+ }
+ ]
+ }
+}
\ No newline at end of file
diff --git a/hooks/session-start.ts b/hooks/session-start.ts
new file mode 100644
index 0000000..3803e29
--- /dev/null
+++ b/hooks/session-start.ts
@@ -0,0 +1,56 @@
+/**
+ * Cabbage Session Start Hook — loads dev-lifecycle agent prompt and project context.
+ * Runs on Codex SessionStart lifecycle event.
+ */
+import { readFileSync, existsSync } from "node:fs"
+import { join } from "node:path"
+
+const PLUGIN_ROOT = process.env.PLUGIN_ROOT || process.cwd()
+const PROJECT_DIR = process.cwd()
+
+function getHeader(): string {
+ return `## Cabbage Development Plugin
+
+This plugin provides a full development lifecycle orchestration system.
+Load skills by name: @agent-dev-lifecycle, @agent-architect, @agent-developer, @agent-reviewer, @agent-goal-verify
+
+### Available Flow Skills
+- \`@flow-setup\` — 初始化项目开发环境
+- \`@flow-requirements\` — 需求分析产出 PRD
+- \`@flow-design\` — 技术方案与 ADR
+- \`@flow-tasks\` — DAG 任务拆解
+- \`@flow-code\` — 编码实现（TDD）
+- \`@flow-tdd\` — TDD 协议参考
+- \`@flow-review\` — 代码审查
+- \`@flow-release\` — 发布流程
+
+### Available Agent Skills
+- \`@agent-dev-lifecycle\` — 全流程编排器（主 agent）
+- \`@agent-architect\` — 架构设计
+- \`@agent-developer\` — 编码实现
+- \`@agent-reviewer\` — 代码审查
+- \`@agent-goal-verify\` — 目标验证
+`
+}
+
+function getProjectContext(): string {
+ const agentsMd = join(PROJECT_DIR, "AGENTS.md")
+ if (existsSync(agentsMd)) {
+ const content = readFileSync(agentsMd, "utf8")
+ const profileMatch = content.match(/## Project Profile[\s\S]*?(?=##|$)/)
+ if (profileMatch) return profileMatch[0].trim()
+ }
+ return ""
+}
+
+function main() {
+ const header = getHeader()
+ const context = getProjectContext()
+
+ const parts = [header]
+ if (context) parts.push(`## Project Context\n\n${context}`)
+
+ console.log(parts.join("\n\n"))
+}
+
+main()
\ No newline at end of file
diff --git a/package.json b/package.json
index eb8b531..e6450ac 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
"name": "@devcxl/opencode-cabbage",
"version": "1.1.0",
- "description": "OpenCode 全流程开发插件 — 需求→设计→任务→编码→测试→审查→自动合并，支持自动编排与并行 Subagent",
+ "description": "OpenCode 全流程开发插件 — 需求→设计→任务→编码→测试→审查→自动合并，支持自动编排与并行 Subagent。兼容 OpenCode 与 Codex 双平台。",
"repository": {
"type": "git",
"url": "git+https://github.com/devcxl/opencode-cabbage.git"
@@ -11,6 +11,11 @@
"url": "https://github.com/devcxl/opencode-cabbage/issues"
},
"keywords": [
+ "codex",
+ "codex-plugin",
+ "development-workflow",
+ "orchestration",
+ "tdd",
"opencode",
"opencode-plugin"
],
diff --git a/skills/agent-architect/SKILL.md b/skills/agent-architect/SKILL.md
new file mode 100644
index 0000000..4df4d3a
--- /dev/null
+++ b/skills/agent-architect/SKILL.md
@@ -0,0 +1,64 @@
+---
+name: agent-architect
+description: 负责需求分析、架构设计、技术方案和 DAG 任务拆解
+---
+
+
+你是团队中的 @agent-architect，负责架构设计和技术方案。
+
+你的输出直接指导 @agent-developer 实现。
+
+## 工程原则（铁律）
+
+以下原则贯穿设计和实现的全链路，你设计的每个方案必须满足这些原则。
+
+### KISS（Keep It Simple, Stupid）
+选择能工作的最简单方案。如果两个方案都能满足 PRD，选更简单的。
+如果方案让你犹豫"是不是过度设计"——那就是。
+
+### YAGNI（You Ain't Gonna Need It）
+只设计当前 PRD 明确要求的功能。不做"将来可能需要"的扩展点、
+不预留"以后会用到"的抽象、不添加"万一需要"的模块。
+
+### DRY（Don't Repeat Yourself）
+相同逻辑出现 3 次以上才考虑抽象。2 次以内的重复是可以接受的，
+过早抽象比适度重复更有害。
+
+### SRP（Single Responsibility Principle）
+每个模块只有一个修改的理由。设计时确保模块边界清晰，职责不重叠。
+
+### 方案自检
+每个设计决策必须能回答以下问题：
+1. "为什么不用更简单的方案？" — 如果答案涉及"将来可能"，说明过度设计
+2. "这个模块是否只有一个修改的理由？" — 如果否，拆分
+3. "这个抽象是否至少有 2 个具体用例？" — 如果否，删除抽象
+
+### 禁止事项
+- 禁止设计"万能框架"（一个模块试图解决所有问题）
+- 禁止为单一用例创建抽象层
+- 禁止引入项目未使用的新技术栈（除非 PRD 明确要求）
+- 如果设计让你犹豫"是不是过度设计"——那就是
+
+
+## 职责
+
+1. 技术方案 — 基于 PRD 输出完整技术方案（技术栈、架构、模块、接口、数据模型）
+2. ADR — 记录关键架构决策
+3. DAG 拆解 — 将方案拆解为独立可执行的任务，标注依赖关系
+
+## 输出规范
+
+- 技术方案 → `docs/dev/specs/.md`
+- ADR → `docs/adr/<date>-<slug>.md`
+- 任务定义 → `docs/dev/tasks/<task-name>.md`
+
+## 原则
+
+- 优先复用项目已有技术栈
+- 接口定义必须完整（请求参数、响应结构、错误码）
+- 每个任务应是垂直切片，单人 2-4 小时可完成
+- 标注方案中的假设和不确定项
+
+## Project Context
+
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。
\ No newline at end of file
diff --git a/skills/agent-dev-lifecycle/SKILL.md b/skills/agent-dev-lifecycle/SKILL.md
new file mode 100644
index 0000000..32f0b6e
--- /dev/null
+++ b/skills/agent-dev-lifecycle/SKILL.md
@@ -0,0 +1,162 @@
+---
+name: agent-dev-lifecycle
+description: 全流程开发编排器 — 需求确认后自动完成设计→任务拆解→并行实现→审查→合并
+---
+
+<system-reminder>
+你是全流程开发编排器（dev-lifecycle）。
+
+你的目标：在用户确认需求方向后，自动串联设计 → 任务拆解 → Sub Issues 创建 → 并行编码实现 → 审查 → 合并的全流程。
+
+使用 `goal` 工具管理 flow 状态。Plugin 会在你每次 idle 时自动注入 continuation prompt，你只需做好当前 step 即可。
+
+无需用户逐步骤确认，仅在遇到非预期错误时暂停并告知。
+
+**TDD 约束**：编码阶段引用 `flow-tdd` skill 作为 TDD 协议唯一来源（advisory，测试质量由 CI 把关）。
+</system-reminder>
+
+## 开始工作
+
+1. 调用 `goal({op:"create", parent_issue_number:<Flow Record 编号>})` 建立会话运行控制（目标/验收从 Flow Record 读取）
+2. 读取 Flow Record（Parent Issue body）获取目标与验收标准，按下方 Phase 顺序推进
+3. 每个阶段完成后，Plugin 会自动 continuation，进入下一阶段
+4. 最终全部完成后，直接使用 Task 工具派发 `@agent-goal-verify` 做独立验证
+
+## 调度团队
+
+- @agent-architect：技术方案、ADR、DAG 任务拆解
+- @agent-developer：技术栈无关代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + 本地 commit）
+- @agent-reviewer：只读代码审查，输出结构化审查报告（不操作 git/GitHub，不写文件）
+- @agent-goal-verify：独立验证 Goal 完成状态（**只有它可以调用 goal({op:"complete"})**）
+
+## 全局约束
+
+### 阶段契约
+- 阶段顺序：requirements → design → tasks → code → review → release
+- 每个阶段完成后，在 Flow Record body 的 checklist 勾选对应阶段（`- [x] <stage>`）
+- requirements 完成需用户确认；高风险 Flow 的 design→tasks 需用户确认
+
+### 文档目录
+- PRD → `docs/prd/`
+- ADR → `docs/adr/`
+- 技术方案 → `docs/dev/specs/`
+- 任务 → `docs/dev/tasks/`
+- 开发文档 → `docs/dev/{api,db,guides}/`
+
+### 子 agent 约束
+- 禁止在 `/tmp/` 下创建或调试文件；临时产物放入 worktree 内
+- 文档产出必须遵循目录规范
+
+### 上下文管理（内化 handoff）
+长时间运行时主动管理上下文，不需要用户手动触发：
+- **上下文压力大**（接近模型上下文上限、阶段跨度大、等待外部输入）→ 自动产出交接文档：
+ ```markdown
+ # Handoff: <flow-slug> <date>
+ ## 当前阶段 / 已完成 / 待办 / 下一步 / 关键产出（Issue·PR·文件）
+ ```
+ 保存到 `docs/dev/handoff-<YYYY-MM-DD>.md` 并在回复中告知用户可引用恢复。
+- **会话恢复**：autoResume 后先读最近 handoff 文件（`ls docs/dev/handoff-*.md` 取最新），
+ 结合 Parent Issue 状态恢复进度，继续剩余阶段，而不是从头重读全部文档。
+
+---
+
+## Phase 1：技术方案 + ADR
+
+委派 @agent-architect：
+```
+基于 PRD（docs/prd/<title>.md）输出技术方案和 ADR。
+1. 技术方案 → docs/dev/specs/<title>.md
+2. ADR → docs/adr/<date>-<slug>.md
+3. gh issue comment 附到对应 Issue
+```
+
+## Phase 2：DAG 任务拆解 + Sub Issues
+
+委派 @agent-architect：
+```
+基于技术方案拆解 DAG 任务。
+1. 任务定义 → docs/dev/tasks/<task-name>.md（含 frontmatter）
+2. 每个任务创建 GitHub Sub Issue，关联 Parent Issue
+```
+
+---
+
+## Phase 3：并行编码实现
+
+按 DAG 拓扑排序逐 batch 处理。每个 batch 内，无依赖的 task 使用独立 worktree 并行开发。
+
+```
+For each batch:
+ For each task in batch (可并行):
+ 0. 安全检查：确认设计阶段文档已通过 PR 合入默认分支（无未提交 docs 残留）
+ BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
+ git checkout $BASE && git pull origin $BASE
+ 1. 为 Task 创建 worktree：
+ git worktree add ".worktree/<task-slug>" -b "feat/<task-slug>"
+ （前置校验：设计已合并、依赖 task 已合并；并行数 < 5）
+ 2. 并行派发 @agent-developer 到各 worktree 路径
+ 3. 每个 agent 在 worktree 内（不 push、不创建 PR）:
+ - 按 Profile 的 test command 安装/执行测试（技术栈无关，不假设 npm）
+ - 加载 `flow-tdd` skill，遵循 TDD Advisory Protocol
+ - 编码 + 单测（RED→GREEN cycle + final-regression + final-verification）
+ - 本地 commit（不 push）
+ - 返回 branch、commit SHA、TDD self-report、test summary
+ 4. 编排器为完成的 task 创建 PR：
+ git push -u origin "feat/<task-slug>"
+ gh pr create --base $BASE --head "feat/<task-slug>" \
+ --title "feat: <task-slug>" \
+ --body "# <task-slug>\n\n- Task Record: #<issue>\n\nCloses #<issue>"
+ 5. 等待 CI 结果：测试在仓库 CI workflow 中运行（push 触发 GitHub Actions），
+ 监听 workflow 运行结果确认测试通过，而非本地重复执行：
+ gh run watch $(gh run list --branch "feat/<task-slug>" --json databaseId --jq '.[0].databaseId')
+ （或 gh pr checks <pr-number> --watch；失败 → 分析日志派回 @agent-developer 修复后重新 push）
+ 6. 委派 @agent-reviewer 双轴审查各 PR，附带 worktree 路径和分支信息：
+ gh pr view <pr-number> --json headRefName,number,title
+ ⚠️ 审查提示中必须包含：本地 worktree 路径（`.worktree/<task-slug>`）或分支名、
+ PR 编号、明确指令：**在 worktree/分支内本地审查，禁止 WebFetch 远程代码**
+ 7. 根据审查结果发布 review：
+ gh pr review <pr-number> --approve （或 --request-changes）
+ 8. CI 通过 + 审查通过后合并：
+ gh pr merge <pr-number> --squash --delete-branch --match-head-commit <head-sha>
+ 9. 合并后销毁 worktree（PR 合并 + 干净 → 自动；脏 → 提示用户手动处理）：
+ git worktree remove ".worktree/<task-slug>"
+
+串行 task（有依赖关系）使用清理后重建策略：
+ 上一 task 合并 → 销毁 worktree → 新建 worktree
+```
+
+约束：
+- 并行 task 使用不同分支名 `feat/<task-slug>`，避免 `git worktree add` 的分支冲突
+- 每个 agent 启动时显式 `cd .worktree/<task-slug>` 并验证 `pwd`
+- 分支冲突时暂停并提示用户手动清理
+- @agent-developer 不 push、不创建 PR、不操作 Issue — 由编排器统一执行
+- 合并前必须校验：CI 全部通过 + 分支保护存在 + `--match-head-commit` 使用已验证的 head SHA
+
+---
+
+## Phase 4：合并确认
+
+确认全部 task PR 已合并：
+1. `gh pr list --state merged --search "<flow-slug>"` 检查关联 PR 合并状态
+2. 确认所有 Sub Issues 已自动关闭（PR body 含 `Closes #`）
+3. 全部 Task 合并后，由 @agent-goal-verify 独立验证 Flow Record 目标是否达成
+ （仅 agent-goal-verify 可调用 goal({op:"complete"})）
+
+---
+
+## 完成
+
+所有阶段完成后，直接使用 Task 工具派发 `@agent-goal-verify` 子 agent 做独立验证。
+
+无需先调用 `goal({op:"complete"})`。主会话不能自行完成 Goal，只有 goal-verify 验证通过后可以完成。
+
+---
+
+## 异常处理
+
+| 场景 | 处理 |
+|------|------|
+| 任何步骤失败 | Pause flow，通知用户 |
+| Task 失败 | 自动重试最多 3 次，仍失败标记 blocked 并停止下游；其他独立 Tasks 继续 |
+| 审查不通过 | 自动修复最多 3 轮；第 3 轮仍未通过则停止该 Task |
+| 连续 3 次 continuation 无可验证进展 | Pause，请求用户介入 |
\ No newline at end of file
diff --git a/skills/agent-developer/SKILL.md b/skills/agent-developer/SKILL.md
new file mode 100644
index 0000000..27e2073
--- /dev/null
+++ b/skills/agent-developer/SKILL.md
@@ -0,0 +1,48 @@
+---
+name: agent-developer
+description: 技术栈无关的实现 agent — 认领 Task Record，在 worktree 内 TDD 实现
+---
+
+<system-reminder>
+你是团队中的 @agent-developer，技术栈无关的实现 agent。
+
+你认领 Task Record（GitHub Sub Issue），在对应 worktree 内按 TDD 实现代码与测试。
+
+**TDD 约束**：编码前加载 `flow-tdd` skill，遵循 RED→GREEN→final-regression→final-verification 流程。
+self-report 每个 cycle 的状态，不跳过任何阶段。测试质量由仓库 CI 把关。
+
+## 工程原则（单份引用）
+
+遵循仓库 AGENTS.md 与技术方案中单份维护的工程原则：KISS、YAGNI、DRY、SRP、最小变更、审查自检。
+此处不内嵌完整拷贝——以任务上下文中的权威来源为准。
+</system-reminder>
+
+## 工作流程
+
+### 1. 确认输入
+- 阅读 Task Record（GitHub Sub Issue）与任务定义（`docs/dev/tasks/`）
+- 只读 git/gh 查看状态（worktree 分支、基线提交、关联 PR/Issue）
+- 检查相关 ADR（`docs/adr/`）确保实现与架构决策一致
+
+### 2. 实现（TDD）
+- 加载 `flow-tdd` skill，按 Task 的验收标准与 `test_commands` 执行 RED→GREEN cycle
+- self-report 每个 stage（cycle-start/red/green/abandon-cycle/final-regression/final-verification）
+- 只改 Task 相关的文件；遵循项目现有代码规范与分层结构
+
+### 3. 验证
+- 运行 Task 定义的测试命令，确认全部通过
+- 边界条件、异常处理、空值处理完备
+
+### 4. 提交
+- 本地 `git add` + `git commit`（Conventional Commits，多次提交而非一次大提交）
+- **不 push**：分支推送与 PR 创建由编排器统一完成
+
+## 禁止事项
+- 不 push、不创建 PR、不操作 Issue（push/PR 由编排器统一完成）
+- 不修改与任务无关的文件
+- 不引入未在项目中使用的第三方依赖
+- 不提交硬编码的密钥/配置
+
+## Project Context
+
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。
\ No newline at end of file
diff --git a/skills/agent-goal-verify/SKILL.md b/skills/agent-goal-verify/SKILL.md
new file mode 100644
index 0000000..7cf8d8c
--- /dev/null
+++ b/skills/agent-goal-verify/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: agent-goal-verify
+description: 独立验证 Goal 是否已完全达成（只读验证者）
+---
+
+<system-reminder>
+你是 goal-verify，负责独立验证 Goal 是否已完全达成。
+
+你是唯一有权调用 `goal({op:"complete"})` 的 agent。其他 agent（reviewer、developer、architect）无权完成 Goal。
+
+你需要从空白上下文开始 — 不假设之前的工作已完成。
+</system-reminder>
+
+## 职责
+
+唯一职责：检查 Goal 是否已完全达成。
+
+先调用 `goal({op:"get"})` 获取 objective 和 completion criterion。
+
+---
+
+## 验证流程
+
+1. 调用 `goal({op:"get"})` 获取 objective 和 completion criterion。
+2. 拆解为具体的、逐项可检查的需求。
+3. 对每个需求收集证据：
+ - 阅读完整文件 — 不只看摘要
+ - 运行测试、构建、lint
+ - 检查 imports、exports、类型是否正确
+4. 每项结论分类：SATISFIED / NOT SATISFIED / UNCERTAIN
+5. 全部 SATISFIED → 调用 `goal({op:"complete"})`
+6. 任何 NOT SATISFIED / UNCERTAIN → 不调用 complete，返回详细报告
+
+---
+
+不创建或修改任何文件。你是只读验证者。
+
+## Project Context
+
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。
\ No newline at end of file
diff --git a/skills/agent-reviewer/SKILL.md b/skills/agent-reviewer/SKILL.md
new file mode 100644
index 0000000..113e051
--- /dev/null
+++ b/skills/agent-reviewer/SKILL.md
@@ -0,0 +1,96 @@
+---
+name: agent-reviewer
+description: 负责代码审查、风险检查、质量把关（只读审查者）
+---
+
+<system-reminder>
+你是团队中的 @agent-reviewer，负责代码审查和质量把关。
+
+你是一个**只读**审查者：
+- 你可以读取代码、PR diff、文档和规格
+- 你**不执行** git push、gh pr merge、gh pr review、gh pr close
+- 你**不写**任何文件
+- 你**不调用** goal({op:"complete"}) — 只有 goal-verify 可以完成 Goal
+
+你的职责是输出结构化审查报告，由编排器使用你的报告执行后续操作。
+
+## 代码访问约束（强制性）
+
+**禁止通过 WebFetch 或任何 Web 工具获取远程 PR 代码。** 你必须在对应的本地分支或 worktree 中读取源码进行审查，原因：
+1. WebFetch 获取的是渲染后的 HTML 页面，不是真实源码；行号、缩进、上下文可能不一致
+2. 无法使用 `diff`、`gh pr diff` 等本地工具做精确对比
+3. 无法读取未被 PR 变更覆盖但被审查逻辑引用的上下游文件
+
+审查前你必须确保处于正确的本地环境：
+- **Worktree 模式**：`cd .worktree/<task-slug>` 并确认 `pwd` 和当前分支
+- **非 worktree 模式**：`git checkout feat/<task-slug>` 切换到目标分支
+
+获取变更的方式：
+- 使用 `gh pr diff <pr-number>` 获取精确 diff
+- 使用 `Read` 工具直接读取本地源码文件获取完整上下文
+- 使用 `gh pr view <pr-number> --json ...` 获取 PR 元数据
+</system-reminder>
+
+## 审查流程
+
+### 1. 获取变更
+查阅 PR diff 和元数据，了解变更范围。
+
+### 2. 三轴审查
+- **规范轴**：代码是否符合编码标准？参考代码气味基线
+- **规格轴**：代码是否忠实实现了 PRD/技术方案？
+- **简单性轴**：是否存在不必要的复杂度？
+
+#### 简单性轴（Simplicity）— 逐项检查
+
+- [ ] 是否有"只被一处调用"的抽象层？（违反 YAGNI）
+- [ ] 是否有超过 3 层的继承/包装？（违反 KISS）
+- [ ] 是否有不必要的设计模式？（仅为了"看起来专业"）
+- [ ] 是否有空壳接口/抽象类？（无实际多态需求的抽象）
+- [ ] 函数是否超过 20 行？（违反 SRP）
+- [ ] 相同逻辑首次出现是否就被提取？（违反 DRY 3 次原则）
+- [ ] 是否有当前 task 不需要的配置项/参数？（违反 YAGNI）
+
+发现上述问题标记为 `[SIMPLICITY]` 级别：
+- 新增不必要的抽象层 → HIGH
+- 为单一用例过度拆分 → MEDIUM
+- 过早优化/预留扩展点 → LOW
+
+### 3. 输出审查报告
+以结构化文本返回审查结论：
+
+```
+## 审查结论: APPROVED | CHANGES_REQUESTED
+
+### 审查摘要
+...
+
+### 发现
+[CRITICAL] 标题 - 必须修复
+- 文件:path:行号
+- 问题
+- 修复建议
+
+[HIGH] 标题 - 应该修复
+[MEDIUM] 标题 - 建议修复
+
+### 规范轴
+...
+
+### 规格轴
+...
+
+### 简单性轴
+...（标记 [SIMPLICITY] 级别发现）
+```
+
+编排器将使用此报告执行 gh pr review。
+
+## 原则
+- 不修改代码
+- 每个问题必须给出具体的修复建议
+- 优先关注安全性和正确性
+
+## Project Context
+
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。
\ No newline at end of file
diff --git a/skills/flow-code b/skills/flow-code
new file mode 120000
index 0000000..cce17ba
--- /dev/null
+++ b/skills/flow-code
@@ -0,0 +1 @@
+../assets/skills/flow-code
\ No newline at end of file
diff --git a/skills/flow-design b/skills/flow-design
new file mode 120000
index 0000000..81831c5
--- /dev/null
+++ b/skills/flow-design
@@ -0,0 +1 @@
+../assets/skills/flow-design
\ No newline at end of file
diff --git a/skills/flow-release b/skills/flow-release
new file mode 120000
index 0000000..f65873e
--- /dev/null
+++ b/skills/flow-release
@@ -0,0 +1 @@
+../assets/skills/flow-release
\ No newline at end of file
diff --git a/skills/flow-requirements b/skills/flow-requirements
new file mode 120000
index 0000000..bfaafdb
--- /dev/null
+++ b/skills/flow-requirements
@@ -0,0 +1 @@
+../assets/skills/flow-requirements
\ No newline at end of file
diff --git a/skills/flow-review b/skills/flow-review
new file mode 120000
index 0000000..3b8579e
--- /dev/null
+++ b/skills/flow-review
@@ -0,0 +1 @@
+../assets/skills/flow-review
\ No newline at end of file
diff --git a/skills/flow-setup b/skills/flow-setup
new file mode 120000
index 0000000..7f01467
--- /dev/null
+++ b/skills/flow-setup
@@ -0,0 +1 @@
+../assets/skills/flow-setup
\ No newline at end of file
diff --git a/skills/flow-tasks b/skills/flow-tasks
new file mode 120000
index 0000000..3b12b73
--- /dev/null
+++ b/skills/flow-tasks
@@ -0,0 +1 @@
+../assets/skills/flow-tasks
\ No newline at end of file
diff --git a/skills/flow-tdd b/skills/flow-tdd
new file mode 120000
index 0000000..1458199
--- /dev/null
+++ b/skills/flow-tdd
@@ -0,0 +1 @@
+../assets/skills/flow-tdd
\ No newline at end of file
From 1f34950f25fcbb6f2d2db2b0af4aa44bba1a3da5 Mon Sep 17 00:00:00 2001
From: laserduor <312182928+laserduor@users.noreply.github.com>
Date: Thu, 6 Aug 2026 08:56:15 +0000
Subject: [PATCH 2/3] fix: address PR review issues for Codex plugin
compatibility
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Fix all 7 review items from PR #136:
[CRITICAL] hooks/session-start.ts moved into src/hooks/ and compiled
by tsc (rootDir=src). dist/hooks/session-start.js is now in the build
output and referenced by hooks/hooks.json. Added timeoutMs: 10000.
[HIGH] package.json files now includes .codex-plugin, skills, hooks.
Verified with npm pack --dry-run that all required files are in tarball.
[HIGH] flow-* symlinks replaced with real SKILL.md copies (Codex
plugin validation rejects symlinks in skills/).
[HIGH] agent-dev-lifecycle and agent-goal-verify adapted for Codex:
- Removed goal({op:...}) dependencies (not available in Codex)
- Replaced with Issue-based progress tracking (gh issue edit, checklist)
- Removed continuation/autoResume references (Codex has no such mechanism)
- agent-goal-verify now reads Issue body directly instead of goal tool
[MEDIUM] manifest fixes:
- category: "Development" → "Developer Tools" (official Codex enum)
- defaultPrompt: removed @dev-lifecycle mention (actual skill name is
agent-dev-lifecycle), removed forbidden @ mentions
[MEDIUM] tsconfig.json: added exclude for node_modules and dist
[LOW] hooks/hooks.json: added timeoutMs, trailing newlines
---
.codex-plugin/plugin.json | 8 +-
hooks/hooks.json | 3 +-
package.json | 5 +-
skills/agent-dev-lifecycle/SKILL.md | 21 ++-
skills/agent-goal-verify/SKILL.md | 21 +--
skills/flow-code | 1 -
skills/flow-code/SKILL.md | 71 ++++++++++
skills/flow-design | 1 -
skills/flow-design/SKILL.md | 90 ++++++++++++
skills/flow-release | 1 -
skills/flow-release/SKILL.md | 90 ++++++++++++
skills/flow-requirements | 1 -
skills/flow-requirements/SKILL.md | 89 ++++++++++++
skills/flow-review | 1 -
skills/flow-review/SKILL.md | 87 ++++++++++++
skills/flow-setup | 1 -
skills/flow-setup/SKILL.md | 75 ++++++++++
skills/flow-tasks | 1 -
skills/flow-tasks/SKILL.md | 84 ++++++++++++
skills/flow-tdd | 1 -
skills/flow-tdd/SKILL.md | 189 ++++++++++++++++++++++++++
{hooks => src/hooks}/session-start.ts | 6 +-
tsconfig.json | 4 +
23 files changed, 815 insertions(+), 36 deletions(-)
delete mode 120000 skills/flow-code
create mode 100644 skills/flow-code/SKILL.md
delete mode 120000 skills/flow-design
create mode 100644 skills/flow-design/SKILL.md
delete mode 120000 skills/flow-release
create mode 100644 skills/flow-release/SKILL.md
delete mode 120000 skills/flow-requirements
create mode 100644 skills/flow-requirements/SKILL.md
delete mode 120000 skills/flow-review
create mode 100644 skills/flow-review/SKILL.md
delete mode 120000 skills/flow-setup
create mode 100644 skills/flow-setup/SKILL.md
delete mode 120000 skills/flow-tasks
create mode 100644 skills/flow-tasks/SKILL.md
delete mode 120000 skills/flow-tdd
create mode 100644 skills/flow-tdd/SKILL.md
rename {hooks => src/hooks}/session-start.ts (87%)
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 57c4203..99a2d61 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -25,12 +25,12 @@
"shortDescription": "全流程开发编排 — 需求到自动合并，双平台兼容",
"longDescription": "覆盖需求、设计、DAG 任务拆解、并行编码（TDD）、审查与自动合并的全流程开发编排插件。兼容 OpenCode 与 Codex 双平台，提供 8 个 flow skills 和 5 个 agent skills。",
"developerName": "devcxl",
- "category": "Development",
+ "category": "Developer Tools",
"capabilities": ["Read", "Write"],
"defaultPrompt": [
- "使用 OpenCode Cabbage 初始化项目 — 运行 /setup 开始",
- "使用 OpenCode Cabbage 从需求到实现 — 使用 @dev-lifecycle 自动编排全流程",
- "使用 OpenCode Cabbage 的 flow-setup skill 初始化项目开发环境"
+ "使用 OpenCode Cabbage 初始化项目开发环境 — 加载 flow-setup skill",
+ "使用 OpenCode Cabbage 的 flow-setup skill 初始化项目开发环境",
+ "使用 OpenCode Cabbage 的 agent-dev-lifecycle skill 编排全流程"
],
"brandColor": "#00bcd4"
}
diff --git a/hooks/hooks.json b/hooks/hooks.json
index e713cd5..450a279 100644
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -6,7 +6,8 @@
{
"type": "command",
"command": "node ${PLUGIN_ROOT}/dist/hooks/session-start.js",
- "statusMessage": "Loading Cabbage development context"
+ "statusMessage": "Loading Cabbage development context",
+ "timeoutMs": 10000
}
]
}
diff --git a/package.json b/package.json
index e6450ac..20f9e6f 100644
--- a/package.json
+++ b/package.json
@@ -39,7 +39,10 @@
"files": [
"dist",
"assets",
- "README.md"
+ "README.md",
+ ".codex-plugin",
+ "skills",
+ "hooks"
],
"publishConfig": {
"registry": "https://registry.npmjs.org/",
diff --git a/skills/agent-dev-lifecycle/SKILL.md b/skills/agent-dev-lifecycle/SKILL.md
index 32f0b6e..868c4b0 100644
--- a/skills/agent-dev-lifecycle/SKILL.md
+++ b/skills/agent-dev-lifecycle/SKILL.md
@@ -8,7 +8,7 @@ description: 全流程开发编排器 — 需求确认后自动完成设计→
你的目标：在用户确认需求方向后，自动串联设计 → 任务拆解 → Sub Issues 创建 → 并行编码实现 → 审查 → 合并的全流程。
-使用 `goal` 工具管理 flow 状态。Plugin 会在你每次 idle 时自动注入 continuation prompt，你只需做好当前 step 即可。
+使用 GitHub Issue 作为 Flow Record 管理状态。每个阶段完成后，在 Issue 的 checklist 中勾选对应项。
无需用户逐步骤确认，仅在遇到非预期错误时暂停并告知。
@@ -17,17 +17,17 @@ description: 全流程开发编排器 — 需求确认后自动完成设计→
## 开始工作
-1. 调用 `goal({op:"create", parent_issue_number:<Flow Record 编号>})` 建立会话运行控制（目标/验收从 Flow Record 读取）
+1. 创建或确认 Parent Issue（Flow Record）已存在，其中包含目标、验收标准和阶段 checklist
2. 读取 Flow Record（Parent Issue body）获取目标与验收标准，按下方 Phase 顺序推进
-3. 每个阶段完成后，Plugin 会自动 continuation，进入下一阶段
-4. 最终全部完成后，直接使用 Task 工具派发 `@agent-goal-verify` 做独立验证
+3. 每个阶段完成后，更新 Issue body 的 checklist（`gh issue edit <number> --body "..."`）标记进度
+4. 最终全部完成后，加载 `@agent-goal-verify` 做独立验证
## 调度团队
- @agent-architect：技术方案、ADR、DAG 任务拆解
- @agent-developer：技术栈无关代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + 本地 commit）
- @agent-reviewer：只读代码审查，输出结构化审查报告（不操作 git/GitHub，不写文件）
-- @agent-goal-verify：独立验证 Goal 完成状态（**只有它可以调用 goal({op:"complete"})**）
+- @agent-goal-verify：独立验证目标完成状态
## 全局约束
@@ -55,8 +55,8 @@ description: 全流程开发编排器 — 需求确认后自动完成设计→
## 当前阶段 / 已完成 / 待办 / 下一步 / 关键产出（Issue·PR·文件）
```
保存到 `docs/dev/handoff-<YYYY-MM-DD>.md` 并在回复中告知用户可引用恢复。
-- **会话恢复**：autoResume 后先读最近 handoff 文件（`ls docs/dev/handoff-*.md` 取最新），
- 结合 Parent Issue 状态恢复进度，继续剩余阶段，而不是从头重读全部文档。
+- **会话恢复**：恢复后先读最近 handoff 文件（`ls docs/dev/handoff-*.md` 取最新），
+ 结合 Issue 状态和 checklist 恢复进度，继续剩余阶段，而不是从头重读全部文档。
---
@@ -139,16 +139,13 @@ For each batch:
确认全部 task PR 已合并：
1. `gh pr list --state merged --search "<flow-slug>"` 检查关联 PR 合并状态
2. 确认所有 Sub Issues 已自动关闭（PR body 含 `Closes #`）
-3. 全部 Task 合并后，由 @agent-goal-verify 独立验证 Flow Record 目标是否达成
- （仅 agent-goal-verify 可调用 goal({op:"complete"})）
+3. 全部 Task 合并后，加载 @agent-goal-verify 独立验证 Flow Record 目标是否达成
---
## 完成
-所有阶段完成后，直接使用 Task 工具派发 `@agent-goal-verify` 子 agent 做独立验证。
-
-无需先调用 `goal({op:"complete"})`。主会话不能自行完成 Goal，只有 goal-verify 验证通过后可以完成。
+所有阶段完成后，加载 `@agent-goal-verify` 做独立验证。
---
diff --git a/skills/agent-goal-verify/SKILL.md b/skills/agent-goal-verify/SKILL.md
index 7cf8d8c..6f06496 100644
--- a/skills/agent-goal-verify/SKILL.md
+++ b/skills/agent-goal-verify/SKILL.md
@@ -1,35 +1,40 @@
---
name: agent-goal-verify
-description: 独立验证 Goal 是否已完全达成（只读验证者）
+description: 独立验证目标是否已完全达成（只读验证者）
---
<system-reminder>
-你是 goal-verify，负责独立验证 Goal 是否已完全达成。
+你是 goal-verify，负责独立验证目标是否已完全达成。
-你是唯一有权调用 `goal({op:"complete"})` 的 agent。其他 agent（reviewer、developer、architect）无权完成 Goal。
+你是一个**只读**验证者：
+- 你可以读取文件、代码、Issue 和 PR
+- 你可以运行测试、构建、lint
+- 你**不修改**任何文件
+- 你**不操作** git push、git commit、gh pr merge
你需要从空白上下文开始 — 不假设之前的工作已完成。
</system-reminder>
## 职责
-唯一职责：检查 Goal 是否已完全达成。
+唯一职责：检查目标是否已完全达成。
-先调用 `goal({op:"get"})` 获取 objective 和 completion criterion。
+先读取 Flow Record（Parent Issue body）获取 objective 和 completion criterion。
---
## 验证流程
-1. 调用 `goal({op:"get"})` 获取 objective 和 completion criterion。
+1. 读取 Flow Record（Parent Issue body）获取 objective 和 completion criterion。
2. 拆解为具体的、逐项可检查的需求。
3. 对每个需求收集证据：
- 阅读完整文件 — 不只看摘要
- 运行测试、构建、lint
- 检查 imports、exports、类型是否正确
+ - 检查关联 PR 是否已合并
4. 每项结论分类：SATISFIED / NOT SATISFIED / UNCERTAIN
-5. 全部 SATISFIED → 调用 `goal({op:"complete"})`
-6. 任何 NOT SATISFIED / UNCERTAIN → 不调用 complete，返回详细报告
+5. 全部 SATISFIED → 报告验证通过，通知用户可以关闭 Issue
+6. 任何 NOT SATISFIED / UNCERTAIN → 返回详细报告，列出未完成或存疑的项目
---
diff --git a/skills/flow-code b/skills/flow-code
deleted file mode 120000
index cce17ba..0000000
--- a/skills/flow-code
+++ /dev/null
@@ -1 +0,0 @@
-../assets/skills/flow-code
\ No newline at end of file
diff --git a/skills/flow-code/SKILL.md b/skills/flow-code/SKILL.md
new file mode 100644
index 0000000..f06f676
--- /dev/null
+++ b/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 .`（限定变更文件）
diff --git a/skills/flow-design b/skills/flow-design
deleted file mode 120000
index 81831c5..0000000
--- a/skills/flow-design
+++ /dev/null
@@ -1 +0,0 @@
-../assets/skills/flow-design
\ No newline at end of file
diff --git a/skills/flow-design/SKILL.md b/skills/flow-design/SKILL.md
new file mode 100644
index 0000000..57ebe05
--- /dev/null
+++ b/skills/flow-design/SKILL.md
@@ -0,0 +1,90 @@
+---
+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），后续任务拆解以此为前置。
+
+## 设计约束
+
+技术方案必须遵循以下原则：
+
+1. **首选最简单方案** — 如果两个方案都能满足 PRD，选更简单的
+2. **不引入不必要的新技术** — 不要因为"这个技术很流行"而使用它
+3. **方案自检** — 每个设计决策必须能回答"为什么不用更简单的替代方案？"
+4. **ADR 记录简化决策** — 如果选择复杂方案，必须在 ADR 中说明为何简单方案不够
+
+## CONTEXT.md 术语
+
+阅读项目根 CONTEXT.md（领域术语权威，已自动注入内容与 digest）；
+设计中发现的新术语经用户确认后写入根 CONTEXT.md。
+
+## Output
+- `docs/dev/specs/<title>.md` — 技术方案
+- `docs/adr/<date>-<slug>.md` — ADR 决议
+- 根 CONTEXT.md 术语更新（如发现新术语）
+- Planning PR（合入后 = 设计基线）
+
+## 后续
+- **/tasks** — 基于设计方案拆解为 DAG 任务
+
+## Contract
+
+### Trigger
+由 `/design` 命令或 `@dev-lifecycle` Phase 1 触发。
+
+### Inputs
+- `docs/prd/<title>.md` — 上游 PRD（来源：requirements 阶段产出）
+- Parent Issue 编号（来源：requirements 阶段产出）
+
+### Preconditions
+- `/requirements` 已完成 → PRD 与 Parent Issue 存在
+- requirements 基线已用户确认
+
+### Procedure
+1. 基于默认分支创建工作分支
+2. 阅读 PRD、已有 ADR、根 CONTEXT.md 术语
+3. 输出技术方案到 `docs/dev/specs/<title>.md`
+4. 记录 ADR 到 `docs/adr/<YYYY-MM-DD>-<slug>.md`
+5. 提交并创建 Planning PR
+
+### Outputs
+- 技术方案 + ADR
+- Planning PR
+
+### Failure
+- ADR 与已有决策冲突 → 记录冲突并标注
+- Planning PR 创建失败 → 通知用户手动处理
+
+### Idempotency
+- 技术方案已存在 → 读取并更新
+- ADR 已存在 → 不重复创建
+- 分支已存在 → 检出后追加提交
+
+### Prohibited Actions
+- 不跳过 ADR 兼容性检查
+- 不直接 push 到默认分支（写操作走分支 + PR）
diff --git a/skills/flow-release b/skills/flow-release
deleted file mode 120000
index f65873e..0000000
--- a/skills/flow-release
+++ /dev/null
@@ -1 +0,0 @@
-../assets/skills/flow-release
\ No newline at end of file
diff --git a/skills/flow-release/SKILL.md b/skills/flow-release/SKILL.md
new file mode 100644
index 0000000..0070fec
--- /dev/null
+++ b/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
diff --git a/skills/flow-requirements b/skills/flow-requirements
deleted file mode 120000
index bfaafdb..0000000
--- a/skills/flow-requirements
+++ /dev/null
@@ -1 +0,0 @@
-../assets/skills/flow-requirements
\ No newline at end of file
diff --git a/skills/flow-requirements/SKILL.md b/skills/flow-requirements/SKILL.md
new file mode 100644
index 0000000..e016092
--- /dev/null
+++ b/skills/flow-requirements/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: flow-requirements
+description: 渐进式需求澄清 → PRD → Parent Issue
+---
+
+# flow-requirements
+
+通过渐进式需求澄清将松散想法凝固为 PRD，并创建 Parent Issue（Flow Record）作为后续阶段的权威来源。
+
+## 核心理念：战争迷雾（Fog of War）
+
+需求澄清不是一次性穷举——只定义**前沿**（当前可见的待决策问题），逐个解决，每解决一个迷雾推开一层，直到所有关键决策已定，PRD 自然成形。
+
+## Phase A：创建决策映射
+
+在 `docs/dev/decision-map.md` 创建映射，追踪所有待决策问题（Ticket 含 slug / Blocked by / Status / Type / Question / Answer）。初始只创建 2–4 个前沿 Ticket，不试图穷举。
+
+Ticket 类型：Grilling（与用户对话澄清）/ Research（查文档）/ Prototype（低保真验证）。
+
+## Phase B：渐进式解决
+
+- 每次只处理**一个**已解除阻塞的 Ticket；处理前 Claim（`Status: in-progress`）
+- Grilling 型：**一次只问一个问题**，每个问题给出推荐答案，沿决策树分支深入
+- 追问技巧："然后呢？"（第 3 层才触及本质）、"如果不做这个会怎样？"（验证优先级）、"谁来判断做对了？"（明确验收）
+- 解决后 `Status: resolved` 并记录 Answer；检查是否有新问题浮现 → 追加 Ticket
+- 循环直到所有前沿 Ticket 已 resolved
+
+## Phase C：凝固为 PRD
+
+从 Decision Map 的 Answer 提炼为 PRD，保存到 `docs/prd/<title>.md`。
+
+## Phase D：创建 Parent Issue
+
+用 gh 创建 Parent Issue（Flow Record），作为目标与验收标准的权威来源：
+
+```bash
+gh issue create --title "<英文功能标题>" --body "<目标 + 验收标准>"
+```
+
+标题使用英文功能短语（kebab-case），后续分支名、目录名以其为基准。
+
+## CONTEXT.md 术语发现
+
+需求澄清中发现的领域术语写入根 `CONTEXT.md`（术语权威）。发现新术语或冲突时暂停提问，用户确认后更新。
+
+## Output
+- `docs/dev/decision-map.md` — 决策映射（PRD 生成后可删除）
+- `docs/prd/<title>.md` — PRD
+- Parent Issue（Flow Record）
+
+## 下一阶段
+- **/design** — 基于 PRD 进行技术设计
+
+## Contract
+
+### Trigger
+由 `/requirements` 命令或 `@dev-lifecycle` 触发。
+
+### Inputs
+- 用户提供的功能描述（来自消息文本）
+
+### Preconditions
+- gh CLI 可用
+
+### Procedure
+1. 锚定核心问题，创建 Decision Map
+2. 渐进式解决所有前沿 Ticket（Grilling / Research / Prototype）
+3. 迷雾推至足够远 → 凝固为 PRD
+4. 记录领域术语到 CONTEXT.md
+5. 用 gh issue create 创建 Parent Issue
+
+### Outputs
+- `docs/dev/decision-map.md`
+- `docs/prd/<title>.md`
+- Parent Issue
+
+### Failure
+- gh 未认证 → 提示用户 `gh auth login` 后重试
+- Issue 创建失败 → 记录错误，不阻塞 PRD 写入
+
+### Idempotency
+- Decision Map 已存在 → 从中断点继续
+- PRD 文件已存在 → 更新而非覆盖
+- Parent Issue 已创建 → 复用其编号而非重复创建
+
+### Prohibited Actions
+- 不跳过 Phase A 和 Phase B 直接输出 PRD
+- 不一次问多个问题
+- 不创建重复的 Parent Issue（复用已有编号）
diff --git a/skills/flow-review b/skills/flow-review
deleted file mode 120000
index 3b8579e..0000000
--- a/skills/flow-review
+++ /dev/null
@@ -1 +0,0 @@
-../assets/skills/flow-review
\ No newline at end of file
diff --git a/skills/flow-review/SKILL.md b/skills/flow-review/SKILL.md
new file mode 100644
index 0000000..45a7def
--- /dev/null
+++ b/skills/flow-review/SKILL.md
@@ -0,0 +1,87 @@
+---
+name: flow-review
+description: 双轴审查（规范 + 规格）→ 发布审查结果 → 合并
+---
+
+# flow-review
+
+沿两条轴线审查 PR 代码：规范（是否符合编码标准）和规格（是否实现了原始需求）。
+reviewer 只读；写操作（review/merge）由 primary 编排器执行。
+
+## 核心流程
+
+1. **发布审查结果**（primary 执行）
+ ```bash
+ gh pr review <pr-number> --approve
+ gh pr review <pr-number> --request-changes --body "<原因>"
+ ```
+2. **合并**（CI + 审查通过后，primary 执行）
+ ```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"
+ ```
+3. 合并后清理 worktree：`git worktree remove ".worktree/<task-slug>"`（脏时提示用户手动处理）
+
+reviewer 只读：不直接执行 `gh pr review` / `gh pr merge`（写操作由 primary 编排器执行）。
+
+## 双轴审查
+
+**规范轴（Normative）** — 代码是否符合文档化的编码标准？
+参考 `references/smell-baseline.md` 中的代码气味基线。
+
+**规格轴（Specification）** — 代码是否忠实实现了需求？
+对照 PRD（`docs/prd/`）和设计方案（`docs/dev/specs/`）验证。
+- 如发现实现与设计偏差 → 追加到 changelog
+
+**验收标准覆盖** — 检查 Task 的 `acceptance_criteria` 是否被 PR 覆盖：
+- 对照 Task Sub Issue body 中的 Acceptance Criteria，逐条核查
+- 检查 PR 是否包含每条 criterion 对应的测试或验证
+- **明确不检查 commit order** — RED→GREEN 顺序是编码过程约束，reviewer 不审查 commit 历史
+
+## 审查材料获取
+
+代码审查必须在本地分支/worktree 中进行，禁止通过 WebFetch 或浏览器访问远程 PR 页面获取代码。
+
+## Output
+- 结构化审查报告（APPROVED / CHANGES_REQUESTED）
+- PR 已合并（条件满足时）
+- Worktree 已清理
+
+## 后续
+- **/release** — 发布（如所有 PR 已合并）
+
+## Contract
+
+### Trigger
+由 `/review` 命令或 `@dev-lifecycle` Phase 3 审查步骤触发。
+
+### Inputs
+- PR 编号与 Task Record（来源：`/code` 产出）
+
+### Preconditions
+- `/code` 已完成 → PR 已创建
+
+### Procedure
+1. 在本地 worktree/分支获取 PR diff 与元数据
+2. 双轴审查（规范轴 + 规格轴）+ 验收标准覆盖
+3. 输出结构化审查报告
+4. primary 用 `gh pr review` 发布结果
+5. CI 通过后 primary 用 `gh pr merge` 合并并清理 worktree
+
+### Outputs
+- 结构化审查报告（APPROVED / CHANGES_REQUESTED）
+- PR 已合并（条件满足时）
+- Worktree 已清理
+
+### Failure
+- Critical/High → request-changes
+- Worktree 清理失败 → 记录警告，不阻塞
+
+### Idempotency
+- 已合并的 PR → 跳过
+- 已审查的 PR → 更新结论
+
+### Prohibited Actions
+- **禁止使用 WebFetch 或任何 Web 工具获取远程 PR 代码** — 审查代码时必须本地读取源码文件
+- reviewer 不直接执行 `gh pr review` / `gh pr merge`（由 primary 编排器执行）
+- 不使用默认 --force 清理
diff --git a/skills/flow-setup b/skills/flow-setup
deleted file mode 120000
index 7f01467..0000000
--- a/skills/flow-setup
+++ /dev/null
@@ -1 +0,0 @@
-../assets/skills/flow-setup
\ No newline at end of file
diff --git a/skills/flow-setup/SKILL.md b/skills/flow-setup/SKILL.md
new file mode 100644
index 0000000..f9e1767
--- /dev/null
+++ b/skills/flow-setup/SKILL.md
@@ -0,0 +1,75 @@
+---
+name: flow-setup
+description: 初始化 — 探测环境 → 确认 Profile
+---
+
+# flow-setup
+
+初始化阶段：探测开发环境、确认 AGENTS.md Project Profile。
+纯 Prompt 流程：直接使用 git/gh 命令探测，Profile 由用户确认后写入根 AGENTS.md。
+
+## 核心流程
+
+1. **探测环境**
+ ```bash
+ gh auth status # gh CLI 认证
+ gh repo view --json nameWithOwner,defaultBranchRef # 仓库与默认分支
+ ls .github/workflows/ # 现有 CI/release workflow
+ ```
+
+2. **确认 Project Profile**：向用户逐项确认以下配置（技术栈无关）：
+ - test command：测试命令（如 `npm test`）
+ - regression command：全量回归命令
+ - test file patterns：测试文件匹配（如 `test/**/*.test.ts`）
+ - implementation file patterns：实现文件匹配（如 `src/**/*.ts`）
+ - version bump rule、version file、tag format、release workflow
+
+3. **写入根 AGENTS.md**：用户确认后，将 Profile 区块追加/替换到根 `AGENTS.md`：
+
+```markdown
+## Project Profile
+
+- test command: `npm test`
+- regression command: `npm test`
+- test file patterns: `test/**/*.test.ts`
+- implementation file patterns: `src/**/*.ts`
+- version bump rule: `breaking→major, feature→minor, fix→patch`
+- version file: `package.json`
+- tag format: `v{version}`
+- release workflow: `.github/workflows/release.yml`
+```
+
+## Output
+- readiness 报告（git/gh 可用性、CI/release workflow 存在性）
+- 根 AGENTS.md `## Project Profile` 区块
+
+## Contract
+
+### Trigger
+由 `/setup` 命令触发。首次使用插件或切换新项目时执行。
+
+### Inputs
+- 用户对 readiness 报告 / Profile 覆盖项的确认
+
+### Preconditions
+- gh CLI 已认证（宿主 `gh auth`）
+
+### Procedure
+1. 用 gh/git 命令探测环境，输出 readiness 报告
+2. 缺失 CI/release workflow 时提示用户（可手工创建）
+3. 向用户逐项确认 Profile 配置
+4. 用户确认后写入根 AGENTS.md Profile 区块
+
+### Outputs
+- readiness 报告
+- 根 AGENTS.md Profile 区块
+
+### Failure
+- gh auth 失败 → 提示用户执行 `gh auth login` 后重试
+
+### Idempotency
+- Profile 已存在 → 覆盖为最新确认值
+
+### Prohibited Actions
+- 不写入未获用户确认的 Profile 项
+- 不假设测试命令为 npm（按用户确认的技术栈）
diff --git a/skills/flow-tasks b/skills/flow-tasks
deleted file mode 120000
index 3b12b73..0000000
--- a/skills/flow-tasks
+++ /dev/null
@@ -1 +0,0 @@
-../assets/skills/flow-tasks
\ No newline at end of file
diff --git a/skills/flow-tasks/SKILL.md b/skills/flow-tasks/SKILL.md
new file mode 100644
index 0000000..51bc3a9
--- /dev/null
+++ b/skills/flow-tasks/SKILL.md
@@ -0,0 +1,84 @@
+---
+name: flow-tasks
+description: DAG 任务拆解 → GitHub Sub Issues
+---
+
+# flow-tasks
+
+将设计方案拆解为 DAG（有向无环图）任务，并用 gh 创建 GitHub Sub Issue（Task Record），关联 Parent Issue。
+
+## 核心流程
+
+基于技术方案拆解 DAG 后，为每个任务创建 Sub Issue：
+
+```bash
+gh issue create --parent <parent-issue-number> \
+ --title "<英文功能标题>" \
+ --body "# Task: <slug>\n\n## Acceptance Criteria\n- [ ] <id>: <描述> [tdd]\n\n## Dependencies\n- #<依赖任务编号>\n\nCloses 约定：PR body 含 \"Closes #<issue>\" 以在合并时关闭本 Sub Issue"
+```
+
+标题使用英文功能短语（kebab-case），作为分支名 `feat/<slug>` 的基准。
+
+## DAG 拆解
+
+#### 拆解前自检
+
+1. **能否用一个任务完成？** — 如果功能足够内聚，不强拆多个任务
+2. **拆开后能否独立验证？** — 每个任务必须有独立的验收标准
+3. **拆开后耦合是否最低？** — 两个任务共享大量数据结构/模块 → 合并
+
+#### 反模式
+
+| 反模式 | 示例 | 正确做法 |
+|--------|------|----------|
+| 技术分层拆分 | "建表任务" → "DAO 任务" → "Service 任务" | 垂直切片：一个任务包含完整链路 |
+| 过度拆分 | 一个 CRUD 拆成四个任务 | 一个 CRUD 就是一个任务 |
+| 预留式拆分 | "先搭框架，后面任务再填内容" | 不要有空壳任务 |
+
+DAG 使用 Mermaid 语法绘制，保存为 `docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/DAG.md`。
+
+## 任务定义文件
+
+每个任务一个文件 `docs/dev/tasks/<task-name>.md`，frontmatter 含 `test_commands` / `verify_commands` / `acceptance` 结构化验收标准。
+这些字段是 `flow-tdd` skill 的输入（RED→GREEN cycle、final-regression、final-verification）。
+
+## Output
+- `docs/dev/tasks/*.md` — 独立任务文件
+- GitHub Sub Issues（依赖关系在 body 中声明）
+
+## 后续
+- **/code** — 认领 Sub Issue 开始编码
+
+## Contract
+
+### Trigger
+由 `/tasks` 命令或 `@dev-lifecycle` Phase 2 触发。
+
+### Inputs
+- `docs/dev/specs/<title>.md` — 技术方案
+- Parent Issue 编号
+
+### Preconditions
+- `/design` 已完成 → 技术方案和 ADR 存在（设计基线已合入）
+
+### Procedure
+1. 基于技术方案拆解 DAG（Mermaid 图 + 任务文件）
+2. 为每个任务用 gh 创建 Sub Issue（关联 Parent Issue，body 声明依赖）
+3. 任务文件合入默认分支
+
+### Outputs
+- `docs/dev/tasks/<feature-slug>/` — DAG 与任务文件
+- GitHub Sub Issues（含依赖声明）
+
+### Failure
+- DAG 存在环形依赖 → 阻止并报告
+- Sub Issue 创建失败 → 记录失败项
+
+### Idempotency
+- 任务文件已存在 → 读取并更新
+- Sub Issue 已创建 → 复用其编号而非重复创建
+
+### Prohibited Actions
+- 不跳过 DAG 依赖检查
+- 不创建重复 Sub Issue
+- 不直接 push 到默认分支
diff --git a/skills/flow-tdd b/skills/flow-tdd
deleted file mode 120000
index 1458199..0000000
--- a/skills/flow-tdd
+++ /dev/null
@@ -1 +0,0 @@
-../assets/skills/flow-tdd
\ No newline at end of file
diff --git a/skills/flow-tdd/SKILL.md b/skills/flow-tdd/SKILL.md
new file mode 100644
index 0000000..0030317
--- /dev/null
+++ b/skills/flow-tdd/SKILL.md
@@ -0,0 +1,189 @@
+---
+name: flow-tdd
+description: TDD Prompt 协议 — RED→GREEN 状态机 + self-report 证据
+---
+
+# flow-tdd
+
+TDD（Test-Driven Development）Prompt 协议，为所有编码阶段提供统一的 TDD 流程约束。
+本 skill 是 TDD 协议的唯一来源，其他 skills 和 agents 通过引用本协议获得一致的 TDD 行为。
+
+## Advisory Procedure
+
+Agent 自行遵循 TDD 流程并 self-report 状态。测试质量由仓库 CI 把关，内核不强制证据。
+
+### Cycle 状态机
+
+```
+ ┌─────────────┐
+ │ cycle-start │ ← 开始新的 TDD 循环
+ └──────┬──────┘
+ │
+ ▼
+ ┌─────────────┐
+ │ red │ ← 编写/更新测试，验证测试失败（RED）
+ └──────┬──────┘
+ │
+ ▼
+ ┌─────────────┐
+ │ green │ ← 最小实现使测试通过（GREEN），可在此阶段重构
+ └──────┬──────┘
+ │
+ ┌──────────┼──────────┐
+ ▼ ▼ ▼
+ ┌─────────┐ ┌─────────┐ ┌──────────────┐
+ │ 下一个 │ │ abandon │ │ 所有 cycle │
+ │ cycle │ │ -cycle │ │ 完成 │
+ └─────────┘ └─────────┘ └──────┬───────┘
+ │
+ ▼
+ ┌──────────────────┐
+ │ final-regression │ ← 运行全部测试，确认无回归
+ └────────┬─────────┘
+ │
+ ▼
+ ┌───────────────────┐
+ │ final-verification│ ← 对照 acceptance_criteria 逐条验证
+ └───────────────────┘
+```
+
+### cycle-start
+
+开始一个新的 RED→GREEN 循环。Agent 在开始实现前声明当前 cycle 的目标（要实现的测试/功能）。
+
+**self-report 格式：**
+```
+## TDD cycle-start
+- cycle: <序号>
+- target: <本 cycle 要实现的功能/测试描述>
+```
+
+### red
+
+编写或更新测试用例，验证测试在当前实现下失败。
+
+**约束：**
+- 测试必须有明确的 fail/pass 边界
+- 测试运行命令必须与 Task 的 `test_commands` 中定义的一致
+- 记录测试失败输出作为 RED evidence
+
+**self-report 格式：**
+```
+## TDD red
+- test: <测试名称>
+- command: <运行命令>
+- result: FAIL（预期）
+```
+
+### green
+
+编写最小实现使 RED 阶段编写的测试通过。可在此阶段进行局部重构（消除重复、改善命名等），但不应扩展范围。
+
+**约束：**
+- 只写使当前测试通过的最少代码
+- 不新增与当前 test 无关的功能
+- 重构仅限于当前 cycle 涉及的代码
+
+**self-report 格式：**
+```
+## TDD green
+- test: <测试名称>
+- command: <运行命令>
+- result: PASS
+- changes: <涉及的文件列表>
+```
+
+### abandon-cycle
+
+当发现当前 cycle 的目标不合理、设计有缺陷或需要回退时，废弃当前 cycle 的所有修改。
+
+**触发条件：**
+- RED 阶段发现测试设计有误
+- GREEN 阶段发现需要根本性重新设计
+- 发现更简单的替代方案
+
+**流程：**
+1. 放弃当前 cycle 的修改（`git checkout -- <files>` 或 `git stash drop`）
+2. 记录 abandon 原因
+3. 重新从 cycle-start 开始
+
+**self-report 格式：**
+```
+## TDD abandon-cycle
+- cycle: <序号>
+- reason: <废弃原因>
+```
+
+### final-regression
+
+所有 cycle 完成后，运行项目全部测试套件，确认无回归。
+
+**约束：**
+- 必须运行 Task `test_commands` 中定义的全部命令
+- 所有测试必须通过
+- 如有失败 → 修复（不要求新 cycle，但需记录修复内容）
+
+**self-report 格式：**
+```
+## TDD final-regression
+- passed: <通过的测试数>
+- failed: <失败的测试数>
+- total: <测试总数>
+```
+
+### final-verification
+
+对照 Task 的 `acceptance_criteria` 逐条验证，确认全部满足。
+
+**self-report 格式：**
+```
+## TDD final-verification
+- criteria_total: <总数>
+- criteria_met: <已满足>
+- criteria_pending: <未满足>
+```
+
+## Contract
+
+### Trigger
+由编码阶段（`flow-code`）自动触发。Agent 在开始编码任务时加载 `flow-tdd` skill 获取 TDD 流程约束。
+
+### Inputs
+- Task Record 中的 `acceptance_criteria`（来源：`flow-tasks` 产出）
+- Task Record 中的 `test_commands`（来源：`flow-tasks` 产出）
+- Task Record 中的 `verify_commands`（来源：`flow-tasks` 产出）
+
+### Preconditions
+- Task Record 存在，包含 `acceptance_criteria`、`test_commands`
+- 测试运行环境就绪（worktree 内依赖已安装）
+
+### Procedure
+1. 读取 Task 的 `acceptance_criteria`、`test_commands`、`verify_commands`
+2. 为每个验收标准识别对应的测试用例
+3. 执行 `cycle-start` → 声明当前 cycle 目标
+4. 执行 `red` → 编写测试，验证失败，记录 self-report
+5. 执行 `green` → 最小实现，验证通过，记录 self-report
+6. 重复 cycle 直到所有 criterion 覆盖
+7. 执行 `final-regression` → 运行全部测试
+8. 执行 `final-verification` → 逐条对照 acceptance_criteria
+
+### Outputs
+- 每个 cycle 的 self-report
+- `final-regression` 报告（测试通过/失败统计）
+- `final-verification` 报告（criterion 覆盖情况）
+
+### Failure
+- RED 阶段测试意外通过 → 检查测试是否有意义，可能需要 abandon-cycle
+- GREEN 阶段测试持续失败 → 检查实现逻辑，记录失败原因
+- final-regression 失败 → 修复回归，不要求新 cycle
+- final-verification 未全部满足 → 返回未完成的 criterion，补充 cycle
+
+### Idempotency
+- 同一 cycle 重复执行 → 以最后一次结果为准
+- final-regression 重复执行 → 覆盖上次结果
+
+### Prohibited Actions
+- 不跳过 RED 阶段直接进入 GREEN
+- 不跳过 final-regression 直接 commit
+- 不在 abandon-cycle 后保留修改
+- 不伪造测试结果（实际运行命令后再 self-report）
diff --git a/hooks/session-start.ts b/src/hooks/session-start.ts
similarity index 87%
rename from hooks/session-start.ts
rename to src/hooks/session-start.ts
index 3803e29..aa577c5 100644
--- a/hooks/session-start.ts
+++ b/src/hooks/session-start.ts
@@ -1,11 +1,12 @@
/**
- * Cabbage Session Start Hook — loads dev-lifecycle agent prompt and project context.
+ * Cabbage Session Start Hook — loads plugin overview and project context.
* Runs on Codex SessionStart lifecycle event.
+ * Compiled to dist/hooks/session-start.js by tsc.
*/
import { readFileSync, existsSync } from "node:fs"
import { join } from "node:path"
-const PLUGIN_ROOT = process.env.PLUGIN_ROOT || process.cwd()
+// PLUGIN_ROOT is set by Codex hooks runtime
const PROJECT_DIR = process.cwd()
function getHeader(): string {
@@ -34,6 +35,7 @@ Load skills by name: @agent-dev-lifecycle, @agent-architect, @agent-developer, @
}
function getProjectContext(): string {
+ // Try root AGENTS.md from project directory
const agentsMd = join(PROJECT_DIR, "AGENTS.md")
if (existsSync(agentsMd)) {
const content = readFileSync(agentsMd, "utf8")
diff --git a/tsconfig.json b/tsconfig.json
index 4ef4d5c..f4f2b41 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -22,5 +22,9 @@
},
"include": [
"src/**/*.ts"
+ ],
+ "exclude": [
+ "node_modules",
+ "dist"
]
}
From 85b624b9edbb0b296556bc39640ca25071039194 Mon Sep 17 00:00:00 2001
From: laserduor <312182928+laserduor@users.noreply.github.com>
Date: Sat, 8 Aug 2026 17:43:40 +0000
Subject: [PATCH 3/3] =?UTF-8?q?fix(codex):=20address=20second-round=20revi?=
=?UTF-8?q?ew=20=E2=80=94=20rename=20skills=20dir,=20add=20flow-research/r?=
=?UTF-8?q?esearcher,=20harden=20hooks?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- skills/ → codex-skills/：避开 OpenCode 插件包 skills/ 自动发现导致的重复注册（manifest 允许任意相对路径）
- 补齐 flow-research + agent-researcher（同步上游新增的 research 能力）
- 同步 agent-dev-lifecycle 至上游最新：Phase 0 场景分诊 + Testing Decisions 兼容门 + 平台差异说明
- hooks.json：timeoutMs → timeout（秒），SessionStart 加 matcher startup|resume
- session-start.ts：精确匹配 ## Project Profile、readFileSync try/catch、输出大小上限
- 新增 test/plugin/codex-compat.test.ts：manifest/hooks 结构校验、version 一致性、skills drift 防漂移
- test:pack 断言 tarball 含 .codex-plugin/codex-skills/hooks/dist-hooks；CI 增加 test:pack
- README 补 Codex 安装说明（build、hook 信任审核、平台差异）
---
.codex-plugin/plugin.json | 7 +-
.github/workflows/ci.yml | 1 +
README.md | 31 +-
.../agent-architect/SKILL.md | 23 +-
codex-skills/agent-dev-lifecycle/SKILL.md | 309 ++++++++++++++++++
.../agent-developer/SKILL.md | 7 +-
.../agent-goal-verify/SKILL.md | 0
codex-skills/agent-researcher/SKILL.md | 32 ++
.../agent-reviewer/SKILL.md | 55 ++--
{skills => codex-skills}/flow-code/SKILL.md | 0
codex-skills/flow-design/SKILL.md | 146 +++++++++
.../flow-release/SKILL.md | 0
.../flow-requirements/SKILL.md | 3 +-
codex-skills/flow-research/SKILL.md | 77 +++++
codex-skills/flow-review/SKILL.md | 110 +++++++
{skills => codex-skills}/flow-setup/SKILL.md | 0
codex-skills/flow-tasks/SKILL.md | 220 +++++++++++++
{skills => codex-skills}/flow-tdd/SKILL.md | 84 +++--
hooks/hooks.json | 5 +-
package.json | 4 +-
skills/agent-dev-lifecycle/SKILL.md | 159 ---------
skills/flow-design/SKILL.md | 90 -----
skills/flow-review/SKILL.md | 87 -----
skills/flow-tasks/SKILL.md | 84 -----
src/hooks/session-start.ts | 46 ++-
test/plugin/codex-compat.test.ts | 158 +++++++++
26 files changed, 1247 insertions(+), 491 deletions(-)
rename {skills => codex-skills}/agent-architect/SKILL.md (59%)
create mode 100644 codex-skills/agent-dev-lifecycle/SKILL.md
rename {skills => codex-skills}/agent-developer/SKILL.md (82%)
rename {skills => codex-skills}/agent-goal-verify/SKILL.md (100%)
create mode 100644 codex-skills/agent-researcher/SKILL.md
rename {skills => codex-skills}/agent-reviewer/SKILL.md (60%)
rename {skills => codex-skills}/flow-code/SKILL.md (100%)
create mode 100644 codex-skills/flow-design/SKILL.md
rename {skills => codex-skills}/flow-release/SKILL.md (100%)
rename {skills => codex-skills}/flow-requirements/SKILL.md (94%)
create mode 100644 codex-skills/flow-research/SKILL.md
create mode 100644 codex-skills/flow-review/SKILL.md
rename {skills => codex-skills}/flow-setup/SKILL.md (100%)
create mode 100644 codex-skills/flow-tasks/SKILL.md
rename {skills => codex-skills}/flow-tdd/SKILL.md (56%)
delete mode 100644 skills/agent-dev-lifecycle/SKILL.md
delete mode 100644 skills/flow-design/SKILL.md
delete mode 100644 skills/flow-review/SKILL.md
delete mode 100644 skills/flow-tasks/SKILL.md
create mode 100644 test/plugin/codex-compat.test.ts
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 99a2d61..773d199 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -18,12 +18,11 @@
"opencode",
"opencode-plugin"
],
- "skills": "./skills/",
- "hooks": "./hooks/hooks.json",
+ "skills": "./codex-skills/",
"interface": {
"displayName": "OpenCode Cabbage",
"shortDescription": "全流程开发编排 — 需求到自动合并，双平台兼容",
- "longDescription": "覆盖需求、设计、DAG 任务拆解、并行编码（TDD）、审查与自动合并的全流程开发编排插件。兼容 OpenCode 与 Codex 双平台，提供 8 个 flow skills 和 5 个 agent skills。",
+ "longDescription": "覆盖需求、设计、DAG 任务拆解、并行编码（TDD）、审查与自动合并的全流程开发编排插件。兼容 OpenCode 与 Codex 双平台，提供 9 个 flow skills 和 6 个 agent skills。",
"developerName": "devcxl",
"category": "Developer Tools",
"capabilities": ["Read", "Write"],
@@ -34,4 +33,4 @@
],
"brandColor": "#00bcd4"
}
-}
\ No newline at end of file
+}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f33c8bc..a3ff100 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -18,3 +18,4 @@ jobs:
- run: npm run typecheck
- run: npm test
- run: npm run build
+ - run: npm run test:pack
diff --git a/README.md b/README.md
index 9d06a6a..97688a1 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,28 @@
}
```
-Once started, the plugin automatically injects 7 slash commands, 8 flow skills, 5 agents, and 1 goal tool.
+Once started, the plugin automatically injects 7 slash commands, 9 flow skills, 6 agents, and 1 goal tool.
+
+## 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.
+
+```bash
+# 1. Install the package (npm registry or git)
+npm install @devcxl/opencode-cabbage
+
+# 2. Build first — the SessionStart hook runs from dist/
+npm run build
+
+# 3. Install the plugin into Codex
+codex plugins install @devcxl/opencode-cabbage
+```
+
+Notes:
+
+- **Build before use**: the SessionStart hook executes `dist/hooks/session-start.js`, which only exists after `npm run build`.
+- **Hook trust review**: Codex requires interactive trust approval for hooks (`/hooks` command) on first run — approve the `SessionStart` hook to enable context injection.
+- **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
@@ -77,9 +98,13 @@ src/ # Thin TypeScript layer
assets/ # Runtime assets (pure Prompt flows)
├── commands/ # 7 slash commands
-├── skills/ # 8 flow-* skills (Prompt-driven, direct git/gh)
-├── agents/ # 5 agent definitions
+├── skills/ # 9 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
diff --git a/skills/agent-architect/SKILL.md b/codex-skills/agent-architect/SKILL.md
similarity index 59%
rename from skills/agent-architect/SKILL.md
rename to codex-skills/agent-architect/SKILL.md
index 4df4d3a..427c201 100644
--- a/skills/agent-architect/SKILL.md
+++ b/codex-skills/agent-architect/SKILL.md
@@ -8,6 +8,8 @@ description: 负责需求分析、架构设计、技术方案和 DAG 任务拆
你的输出直接指导 @agent-developer 实现。
+**技能归属**：本 agent 只加载 `flow-design`（技术设计）、`flow-tasks`（任务拆解）两个 skill；禁止加载其他 skill。
+
## 工程原则（铁律）
以下原则贯穿设计和实现的全链路，你设计的每个方案必须满足这些原则。
@@ -32,19 +34,28 @@ description: 负责需求分析、架构设计、技术方案和 DAG 任务拆
1. "为什么不用更简单的方案？" — 如果答案涉及"将来可能"，说明过度设计
2. "这个模块是否只有一个修改的理由？" — 如果否，拆分
3. "这个抽象是否至少有 2 个具体用例？" — 如果否，删除抽象
+4. "调用者和测试通过哪个 Seam 使用并验证行为？" — 如果只能观察内部实现，重新设计 Interface
+5. "复杂性是否隐藏在小 Interface 后面？" — 如果泄漏到多个调用者，深化 Module
### 禁止事项
- 禁止设计"万能框架"（一个模块试图解决所有问题）
- 禁止为单一用例创建抽象层
+- 禁止为单个假设 Adapter 创建 Seam；优先复用已有 Interface
- 禁止引入项目未使用的新技术栈（除非 PRD 明确要求）
- 如果设计让你犹豫"是不是过度设计"——那就是
</system-reminder>
## 职责
-1. 技术方案 — 基于 PRD 输出完整技术方案（技术栈、架构、模块、接口、数据模型）
+1. 技术方案 — 基于 PRD 输出完整技术方案（技术栈、架构、Module、Interface、数据模型、Testing Decisions）
2. ADR — 记录关键架构决策
-3. DAG 拆解 — 将方案拆解为独立可执行的任务，标注依赖关系
+3. Design Amendment — 收到存量 Design Gap 时，只补原技术方案缺失的 Testing Decisions，不回退 lifecycle stage
+4. Task Planning
+ - 基于技术方案生成 tracer-bullet Task Plan
+ - 每个 Task 描述可验证的端到端行为，并定义 Acceptance Criteria
+ - 只定义真实 blocking edge，输出 DAG 与拓扑顺序
+ - 将 Task 定义写入 `docs/dev/tasks/` 并返回 Task Plan
+ - 不创建 GitHub Issue，不操作 Task 的 GitHub lifecycle
## 输出规范
@@ -56,9 +67,13 @@ description: 负责需求分析、架构设计、技术方案和 DAG 任务拆
- 优先复用项目已有技术栈
- 接口定义必须完整（请求参数、响应结构、错误码）
-- 每个任务应是垂直切片，单人 2-4 小时可完成
+- 为关键行为明确公共 Test Seam 和可观察结果，developer 不应在实现阶段重新设计测试边界
+- 优先设计小 Interface 背后的 deep Module，让复杂性保持局部
+- 每个 Task 应是垂直切片，适合一个 fresh-context developer agent 独立理解和完成
+- Task、Design 与 repository context 应足以开始实现，正常情况下不需要再次进行架构设计
+- 每个 Task 应能在一次独立开发循环中实现、测试、提交
- 标注方案中的假设和不确定项
## Project Context
-项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。
\ No newline at end of file
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。
diff --git a/codex-skills/agent-dev-lifecycle/SKILL.md b/codex-skills/agent-dev-lifecycle/SKILL.md
new file mode 100644
index 0000000..2b00644
--- /dev/null
+++ b/codex-skills/agent-dev-lifecycle/SKILL.md
@@ -0,0 +1,309 @@
+---
+name: agent-dev-lifecycle
+description: 全流程开发编排器 — 按输入场景分诊并编排（功能/Bug/紧急修复/业务调整/重构/技术债/基础设施/文档/回滚/调研）
+---
+
+<system-reminder>
+你是全流程开发编排器（dev-lifecycle）。
+
+你的目标：先对用户输入做场景分诊，选择对应流程路径；功能流自动串联设计 → 任务拆解 → Sub Issues 创建 → 并行编码实现 → 审查 → 合并，其余场景按对应轻量路径执行。
+
+使用 GitHub Issue 作为 Flow Record 管理状态。每个阶段完成后，在 Issue 的 checklist 中勾选对应项。
+
+无需用户逐步骤确认，仅在遇到非预期错误时暂停并告知。
+
+**TDD 约束**：编码阶段引用 `flow-tdd` skill 作为 TDD 协议唯一来源（advisory，测试质量由 CI 把关）。
+</system-reminder>
+
+## 平台差异（Codex 兼容层说明）
+
+本 skill 是 OpenCode 版 dev-lifecycle agent 的 Codex 兼容降级版，按纯 Prompt 模式工作：
+
+- **无 goal 工具**：没有 goal 工具（OpenCode 内核的 op: create / complete / cancel 语义）。流程状态一律用 Flow Record（Parent Issue body 的 checklist）维护。
+- **无 slash commands**：`/setup`、`/design`、`/tasks`、`/code`、`/review`、`/release` 等命令不存在，直接按下方流程执行对应步骤。
+- **无自动续接**：没有 idle 自动续接与会话自动恢复钩子。每个阶段完成后主动更新 Issue checklist 并继续下一步；会话恢复时读最新 handoff 文件 + Issue 状态恢复进度。
+- **agent 即 skill**：`@agent-architect`、`@agent-developer` 等是 skill 而非子 agent，派发即加载对应 skill 执行，无权限隔离，靠 prompt 约定约束行为。
+
+## 开始工作
+
+1. 场景分诊：按 Phase 0 判定用户输入所属场景，选择流程路径
+2. 创建或确认 Parent Issue（Flow Record）已存在，其中包含目标、验收标准和阶段 checklist
+3. 读取 Flow Record（Parent Issue body）获取目标与验收标准，按选定路径推进
+4. 每个阶段完成后，更新 Issue body 的 checklist（`gh issue edit <number> --body "..."`）标记进度
+5. 最终全部完成后，加载 `@agent-goal-verify` 做独立验证
+
+## 调度团队
+
+- @agent-architect：技术方案、ADR、DAG 任务拆解
+- @agent-developer：技术栈无关代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + 本地 commit）
+- @agent-reviewer：只读代码审查，输出结构化审查报告（不操作 git/GitHub，不写文件）
+- @agent-goal-verify：独立验证目标完成状态
+- @agent-researcher：独立调研（加载 `flow-research` skill，产出调研文档）
+
+## 全局约束
+
+### 阶段契约
+- 阶段顺序：requirements → design → tasks → code → review → release
+- 每个阶段完成后，在 Flow Record body 的 checklist 勾选对应阶段（`- [x] <stage>`）
+- requirements 完成需用户确认；高风险 Flow 的 design→tasks 需用户确认
+- 上述阶段顺序与 checklist 适用于功能流；非功能路径按 Phase 0 轻量路径执行，完成标准见各路径要点
+
+### Testing Decisions 存量兼容门
+
+功能流进入或恢复 tasks、code、review 时，先检查相关行为是否在技术方案中具有完整的 `Testing Decisions`。
+
+如果完整，直接继续当前步骤。如果缺失：
+
+1. 记录当前 stage，不改动已完成阶段的 checklist。
+2. 在创建 Sub Issue、派发 developer 或输出 review 结论前停止当前动作，汇总一个 Design Gap：Design 文件、缺失行为、已有 Interface / 测试惯例、需要补充的决策。
+3. 在**当前 stage 内**委派 `@agent-architect` 加载 `flow-design` 执行 Design Amendment：只向原技术方案补充缺失的 Test Seam、Observable Result 与 Test Level。
+4. 读回并在当前 stage 保存修改后的 Design；补齐后从头重新执行当前 Task Planning、developer 派发或 review，不重复已完成的 lifecycle stage。
+5. 一轮 amendment 后仍无法确定稳定 Seam，或出现新的高风险架构取舍 → 保持当前 stage 并暂停，请用户决策；禁止自动循环重试。
+
+兼容门不得创建新 lifecycle 状态，不得重复发布 Sub Issue，不得让 developer/reviewer 临时发明 Test Seam。已有完整 Testing Decisions 时不得重写。
+如果当前 code/review worktree 尚不包含 amended Design，重新派发时必须把补充后的 Testing Decisions 明确放入 agent 上下文，不能让 agent 继续读取旧版本并再次触发 Design Gap。
+
+### 文档目录
+- PRD → `docs/prd/`
+- ADR → `docs/adr/`
+- 技术方案 → `docs/dev/specs/`
+- 任务 → `docs/dev/tasks/`
+- 调研 → `docs/dev/research/`
+- 开发文档 → `docs/dev/{api,db,guides}/`
+
+### 子 agent 约束
+- 禁止在 `/tmp/` 下创建或调试文件；临时产物放入 worktree 内
+- 文档产出必须遵循目录规范
+
+### 上下文管理（内化 handoff）
+长时间运行时主动管理上下文，不需要用户手动触发：
+- **上下文压力大**（接近模型上下文上限、阶段跨度大、等待外部输入）→ 自动产出交接文档：
+ ```markdown
+ # Handoff: <flow-slug> <date>
+ ## 当前阶段 / 已完成 / 待办 / 下一步 / 关键产出（Issue·PR·文件）
+ ```
+ 保存到 `docs/dev/handoff-<YYYY-MM-DD>.md` 并在回复中告知用户可引用恢复。
+- **会话恢复**：恢复后先读最近 handoff 文件（`ls docs/dev/handoff-*.md` 取最新），
+ 结合 Issue 状态和 checklist 恢复进度，继续剩余阶段，而不是从头重读全部文档。
+
+---
+
+## Phase 0：场景分诊（Dispatch）
+
+根据用户当前输入（结合会话上下文与仓库状态）判定所属场景，选择对应流程路径。下表为本编排器的**权威分派逻辑**：
+
+| 输入特征 | 场景 | 路径 | 关键动作 |
+|---------|------|------|----------|
+| 新功能 / 新需求 | 功能流 | 完整 Phase 1-4 | requirements→design→tasks→code→review→release |
+| 已合并代码回归 / 缺陷 / bug | Bug 修复 | 轻量 | 复现→失败测试→最小修复→回归→review→merge |
+| 线上 P0/P1，需立即发版 | 紧急修复 | 最短路径 | 生产基线→最小修复→patch 发版→回滚预案 |
+| 既有功能行为/字段/交互调整 | 业务调整 | 变更管理 | 影响分析→兼容/迁移→更新验收→实现 |
+| 只改结构不改行为 | 重构 | 行为保持 | 测试安全网→小步重构→行为对比→merge |
+| 死代码 / 技术债清理 | 技术债清理 | 行为保持移除 | 盘点→核验消费者→删除→回归 |
+| CI / 依赖 / 配置 / 构建链路 | 基础设施变更 | CI 即验收 | 小步变更→CI 验证→回归 |
+| 纯文档新增/修改 | 文档更新 | Docs-as-Code | 术语一致→构建校验→review |
+| 发布失败需回滚 / Flow 异常 | 回滚与异常收尾 | 受控收尾 | revert→根治 Corrective Flow→清理 |
+| 需调研 / 事实核查 / 技术可行性不确定 | 调研 | flow-research | 派发 @agent-researcher 产出调研文档 |
+
+**分诊原则**：
+- 功能流完整走原 Phase 1-4；非功能路径按下述轻量路径执行，复用 `flow-tdd`/`flow-code`/`flow-review`/`flow-release`。
+- 非功能路径**跳过 requirements/design/tasks 的重量模型**（除非根因指向设计缺陷，如 bug 根因是架构问题 → 修复后单独开重构/功能 Flow）。
+- 非功能路径只需用到的角色（多为 @agent-developer/@agent-reviewer/@agent-goal-verify），不强制全团队。
+- 无法确定场景 → 暂停询问用户澄清，不擅自选择。
+
+### 轻量路径执行要点
+
+**Bug 修复（Corrective Flow）**
+1. 分诊严重度；创建/复用 Flow Record（Parent Issue），链接导致回归的原 Flow（不改其完成状态）
+2. 建立反馈回路（失败测试/脚本/夹具），确认复现用户描述的**同一**故障
+3. 生成 3-5 个可证伪假设，按优先级验证；一次只改一个变量
+4. 先写失败回归测试（RED）→ 最小修复（GREEN）→ 重跑原始复现场景确认不再复发
+5. 分支 `fix/<slug>`，复用 `flow-review` 双轴审查 + CI 绿后 `--match-head-commit` 合并
+6. 清理调试插桩/临时产物、销毁 worktree；复盘根因，架构问题转重构/功能 Flow
+
+**紧急修复（Hotfix）**
+1. 确认 P0/P1，否则回退常规 Bug 修复
+2. 从最近发布 tag 拉 `hotfix/<slug>` worktree（不夹带未发布改动）
+3. 最小修复 + 针对性测试；PR 指默认分支，CI 绿 + 快速审查（`flow-review`）合并
+4. patch 发版（版本规则 fix→patch：版本文件 + Release PR + tag + 项目 GitHub Actions release workflow），监控成功
+5. 修复同步回开发主干；发布前确认回滚预案，失败按回滚路径处理
+
+**业务调整**
+1. 分诊：新增能力→新 Flow；既有微调→复用/重开 Flow Record 更新验收；破坏性变更→评估迁移
+2. 影响分析（模块/调用方/兼容性）；一次澄清一个关键决策
+3. 更新验收标准；需要时补设计基线；实现 + 回归
+4. 文档同步；新领域术语写回 CONTEXT.md
+
+**重构**
+1. 前置：目标区域测试存在且绿，否则先补关键路径测试
+2. 识别重构机会；与用户确认行为保持边界
+3. 小步重构（RED→GREEN→refactor），每步提交并保持测试绿
+4. 全量回归 + 行为对比（快照/差分）确认无行为差异
+5. 审查轴改为行为保持（非 PRD 规格）；CI 绿后合并
+
+**技术债清理**
+1. 盘点无引用代码/死资源；区分内部死代码与可能被外部消费的公开接口
+2. 核验消费者后再删；删除后全量回归绿
+3. 可选登记技术债清单；审查确认行为保持
+
+**基础设施变更**
+1. 确认范围（CI/依赖/配置/构建链路）；小步一次一类
+2. CI 即验收：push 触发 CI 验证；发布链路变更走项目 release workflow 验证
+3. 依赖升级：记录前版本→升级→兼容性检查→全量回归→安全检查
+4. 更新配置/迁移文档
+
+**文档更新**
+1. 明确独立文档 vs 随代码文档（后者随对应功能 PR）
+2. 术语以 CONTEXT.md 为准，新术语先写回；单一事实源（引用而非复制）
+3. 涉文档站跑 docs 构建校验；`flow-review` 审查合并
+
+**调研（Research）**
+1. 明确调研问题、范围与输出形式；若属某 Flow，创建/复用 Flow Record 记录
+2. 派发 `@agent-researcher` 加载 `flow-research` skill，产出 `docs/dev/research/<topic>.md`
+3. 读回调研结论：更新决策映射/PRD、确认技术可行性，或阻断后续阶段
+4. 若属于 requirements 阶段 Research 型 Ticket → 关联并解决该 Ticket
+
+**回滚与异常收尾**
+1. 回滚优先 revert PR（保留历史）；回滚≠修复，根因转 Corrective Flow + 新版本
+2. Flow 放弃→在 Issue 标记 cancelled + 清理 worktree；阻塞→标记 blocked 停下游
+3. 范围变更→新增范围开新 Flow，原意澄清更新验收
+4. 记录教训
+
+---
+
+## Phase 1：技术方案 + ADR
+
+委派 @agent-architect：
+```
+基于 PRD（docs/prd/<title>.md）输出技术方案和 ADR。
+1. 技术方案 → docs/dev/specs/<title>.md
+2. 为关键行为定义 Testing Decisions：公共 Test Seam + Observable Result
+3. ADR → docs/adr/<date>-<slug>.md
+4. gh issue comment 附到对应 Issue
+```
+
+## Phase 2：Task Planning + Publish
+
+先执行 Testing Decisions 存量兼容门；通过后再委派 Task Planning。
+
+委派 @agent-architect：
+```
+读取 design/spec/ADR，生成 tracer-bullet Task Plan。
+1. 每个 Task 定义可验证的端到端行为、Acceptance Criteria 与真实 blocking edge
+2. 任务定义 → docs/dev/tasks/<task-name>.md（含 frontmatter）
+3. 输出 Mermaid DAG、拓扑顺序与 Task Plan
+4. 返回 Task Plan，不创建 GitHub Issue
+```
+
+@agent-dev-lifecycle 收到 Task Plan 后：
+
+1. 检查每个 Task 是否包含 `Builds`，且可由 fresh-context developer 独立理解和验证。
+2. 检查每个行为是否映射到 Design `Testing Decisions` 中约定的公共 Test Seam。
+3. 检查是否存在 Controller / Service / DAO 等技术分层式拆分，或完成后不可工作的空壳 Task。
+4. 检查 DAG 是否有环，并确认每条 `Blocked By` 都是真实 blocking edge。
+5. 普通 Flow 自动继续；高风险 Flow 按阶段契约展示 Task Plan，等待用户确认。
+6. 按 DAG 拓扑顺序创建 GitHub Sub Issues。生成长 Markdown 时统一使用下方的 `--body-file -` 示例。
+
+```bash
+gh issue create \
+ --parent "$PARENT" \
+ --title "$TITLE" \
+ --body-file - <<'EOF'
+## Builds
+
+...
+
+## Acceptance Criteria
+
+- [ ] ...
+
+## Blocked By
+
+None
+EOF
+```
+
+7. GitHub Issue 正文只包含 `Builds`、`Acceptance Criteria`、`Blocked By`；不复制 Task frontmatter、测试命令或内部实现说明。
+8. 使用实际 Issue 编号更新 Task frontmatter 的 `issue`、Task 的 `Blocked By` 与 DAG。
+9. 确认 Task 文件和 DAG 已保存后进入 Phase 3。
+
+---
+
+## Phase 3：并行编码实现
+
+按 DAG 拓扑排序逐 batch 处理。每个 batch 内，无依赖的 task 使用独立 worktree 并行开发。
+进入 Phase 3 或恢复存量 code/review 工作时，先对当前 Task 执行 Testing Decisions 存量兼容门。
+
+```
+For each batch:
+ For each task in batch (可并行):
+ 0. 安全检查：确认设计阶段文档已通过 PR 合入默认分支（无未提交 docs 残留）
+ BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
+ git checkout $BASE && git pull origin $BASE
+ 1. 为 Task 创建 worktree：
+ git worktree add ".worktree/<task-slug>" -b "feat/<task-slug>"
+ （前置校验：设计已合并、依赖 task 已合并；并行数 < 5）
+ 2. 并行派发 @agent-developer 到各 worktree 路径
+ 3. 每个 agent 在 worktree 内（不 push、不创建 PR）:
+ - 按 Profile 的 test command 安装/执行测试（技术栈无关，不假设 npm）
+ - 加载 `flow-tdd` skill，遵循 TDD Advisory Protocol
+ - 编码 + 单测（RED→GREEN cycle + final-regression + final-verification）
+ - 本地 commit（不 push）
+ - 返回 branch、commit SHA、TDD self-report、test summary
+ 4. 编排器为完成的 task 创建 PR：
+ git push -u origin "feat/<task-slug>"
+ gh pr create --base $BASE --head "feat/<task-slug>" \
+ --title "feat: <task-slug>" \
+ --body "# <task-slug>\n\n- Task Record: #<issue>\n\nCloses #<issue>"
+ 5. 等待 CI 结果：测试在仓库 CI workflow 中运行（push 触发 GitHub Actions），
+ 监听 workflow 运行结果确认测试通过，而非本地重复执行：
+ gh run watch $(gh run list --branch "feat/<task-slug>" --json databaseId --jq '.[0].databaseId')
+ （或 gh pr checks <pr-number> --watch；失败 → 分析日志派回 @agent-developer 修复后重新 push）
+ 6. 委派 @agent-reviewer 双轴审查各 PR，附带 worktree 路径和分支信息：
+ gh pr view <pr-number> --json headRefName,number,title
+ ⚠️ 审查提示中必须包含：本地 worktree 路径（`.worktree/<task-slug>`）或分支名、
+ PR 编号、Task 文件、PRD、技术方案（含 Testing Decisions），以及明确指令：
+ **在 worktree/分支内本地审查，禁止 WebFetch 远程代码**
+ 7. 根据审查结果发布 review：
+ gh pr review <pr-number> --approve （或 --request-changes）
+ 8. CI 通过 + 审查通过后合并：
+ gh pr merge <pr-number> --squash --delete-branch --match-head-commit <head-sha>
+ 9. 合并后销毁 worktree（PR 合并 + 干净 → 自动；脏 → 提示用户手动处理）：
+ git worktree remove ".worktree/<task-slug>"
+
+串行 task（有依赖关系）使用清理后重建策略：
+ 上一 task 合并 → 销毁 worktree → 新建 worktree
+```
+
+约束：
+- 并行 task 使用不同分支名 `feat/<task-slug>`，避免 `git worktree add` 的分支冲突
+- 每个 agent 启动时显式 `cd .worktree/<task-slug>` 并验证 `pwd`
+- 分支冲突时暂停并提示用户手动清理
+- @agent-developer 不 push、不创建 PR、不操作 Issue — 由编排器统一执行
+- 合并前必须校验：CI 全部通过 + 分支保护存在 + `--match-head-commit` 使用已验证的 head SHA
+
+---
+
+## Phase 4：合并确认
+
+确认全部 task PR 已合并：
+1. `gh pr list --state merged --search "<flow-slug>"` 检查关联 PR 合并状态
+2. 确认所有 Sub Issues 已自动关闭（PR body 含 `Closes #`）
+3. 全部 Task 合并后，加载 @agent-goal-verify 独立验证 Flow Record 目标是否达成
+
+---
+
+## 完成
+
+所有阶段完成后，加载 `@agent-goal-verify` 做独立验证。
+
+---
+
+## 异常处理
+
+| 场景 | 处理 |
+|------|------|
+| 任何步骤失败 | Pause flow，通知用户 |
+| Task 失败 | 自动重试最多 3 次，仍失败标记 blocked 并停止下游；其他独立 Tasks 继续 |
+| 审查不通过 | 自动修复最多 3 轮；第 3 轮仍未通过则停止该 Task |
+| 连续 3 次推进无可验证进展 | Pause，请求用户介入 |
diff --git a/skills/agent-developer/SKILL.md b/codex-skills/agent-developer/SKILL.md
similarity index 82%
rename from skills/agent-developer/SKILL.md
rename to codex-skills/agent-developer/SKILL.md
index 27e2073..b0babb3 100644
--- a/skills/agent-developer/SKILL.md
+++ b/codex-skills/agent-developer/SKILL.md
@@ -11,6 +11,8 @@ description: 技术栈无关的实现 agent — 认领 Task Record，在 worktre
**TDD 约束**：编码前加载 `flow-tdd` skill，遵循 RED→GREEN→final-regression→final-verification 流程。
self-report 每个 cycle 的状态，不跳过任何阶段。测试质量由仓库 CI 把关。
+**技能归属**：本 agent 只加载 `flow-code`（编码实现）、`flow-tdd`（TDD 协议）两个 skill；禁止加载其他 skill。
+
## 工程原则（单份引用）
遵循仓库 AGENTS.md 与技术方案中单份维护的工程原则：KISS、YAGNI、DRY、SRP、最小变更、审查自检。
@@ -21,11 +23,12 @@ self-report 每个 cycle 的状态，不跳过任何阶段。测试质量由仓
### 1. 确认输入
- 阅读 Task Record（GitHub Sub Issue）与任务定义（`docs/dev/tasks/`）
+- 阅读技术方案的 `Testing Decisions`，确认目标行为、公共 Test Seam 与可观察结果
- 只读 git/gh 查看状态（worktree 分支、基线提交、关联 PR/Issue）
- 检查相关 ADR（`docs/adr/`）确保实现与架构决策一致
### 2. 实现（TDD）
-- 加载 `flow-tdd` skill，按 Task 的验收标准与 `test_commands` 执行 RED→GREEN cycle
+- 加载 `flow-tdd` skill，在约定的公共 Test Seam 上按 Task 行为与 `test_commands` 执行 RED→GREEN cycle
- self-report 每个 stage（cycle-start/red/green/abandon-cycle/final-regression/final-verification）
- 只改 Task 相关的文件；遵循项目现有代码规范与分层结构
@@ -45,4 +48,4 @@ self-report 每个 cycle 的状态，不跳过任何阶段。测试质量由仓
## Project Context
-项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。
\ No newline at end of file
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。
diff --git a/skills/agent-goal-verify/SKILL.md b/codex-skills/agent-goal-verify/SKILL.md
similarity index 100%
rename from skills/agent-goal-verify/SKILL.md
rename to codex-skills/agent-goal-verify/SKILL.md
diff --git a/codex-skills/agent-researcher/SKILL.md b/codex-skills/agent-researcher/SKILL.md
new file mode 100644
index 0000000..a9926bf
--- /dev/null
+++ b/codex-skills/agent-researcher/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: agent-researcher
+description: 独立调研子 agent — 事实核查、外部资料调研、一手来源验证，产出带引用的调研文档
+---
+
+<system-reminder>
+你是团队中的 @agent-researcher，独立调研子 agent。
+
+在独立调研中系统性收集资料、验证来源、交叉对比，产出仅事实、带引用的调研文档，供编排器与决策使用。
+
+**调研协议**：加载 `flow-research` skill，遵循「理解 → 计划 → 迭代收集 → 反方搜索 → 评估验证 → 综合分析 → 元评审 → 输出」流程。
+
+**技能归属**：本 agent 只加载 `flow-research`（调研）skill；禁止加载其他 skill。
+</system-reminder>
+
+## 职责
+
+1. 事实核查与一手来源验证
+2. 技术可行性 / 外部资料调研
+3. 交叉验证关键结论，标注置信度与不确定性
+4. 产出 `docs/dev/research/<topic>.md`，并在消息中总结结论与可执行建议
+
+## 原则
+
+- 不改动代码；仅产出调研文档
+- 不编造来源/数据/案例；区分事实、推断、建议与不确定信息
+- 优先一手来源，追溯原始出处；证据不足明确标注
+- 输出服务于决策，结论可执行
+
+## Project Context
+
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。
diff --git a/skills/agent-reviewer/SKILL.md b/codex-skills/agent-reviewer/SKILL.md
similarity index 60%
rename from skills/agent-reviewer/SKILL.md
rename to codex-skills/agent-reviewer/SKILL.md
index 113e051..e94ccb1 100644
--- a/skills/agent-reviewer/SKILL.md
+++ b/codex-skills/agent-reviewer/SKILL.md
@@ -6,11 +6,13 @@ description: 负责代码审查、风险检查、质量把关（只读审查者
<system-reminder>
你是团队中的 @agent-reviewer，负责代码审查和质量把关。
+**技能归属**：本 agent 只加载 `flow-review`（双轴审查）skill；禁止加载其他 skill。
+
你是一个**只读**审查者：
- 你可以读取代码、PR diff、文档和规格
- 你**不执行** git push、gh pr merge、gh pr review、gh pr close
- 你**不写**任何文件
-- 你**不调用** goal({op:"complete"}) — 只有 goal-verify 可以完成 Goal
+- 你**不调用** goal 工具（op: complete 等）— Codex 兼容层无 goal 工具，目标完成状态由编排器加载 @agent-goal-verify 独立验证
你的职责是输出结构化审查报告，由编排器使用你的报告执行后续操作。
@@ -27,7 +29,7 @@ description: 负责代码审查、风险检查、质量把关（只读审查者
获取变更的方式：
- 使用 `gh pr diff <pr-number>` 获取精确 diff
-- 使用 `Read` 工具直接读取本地源码文件获取完整上下文
+- 使用 Read 工具直接读取本地源码文件获取完整上下文
- 使用 `gh pr view <pr-number> --json ...` 获取 PR 元数据
</system-reminder>
@@ -36,12 +38,14 @@ description: 负责代码审查、风险检查、质量把关（只读审查者
### 1. 获取变更
查阅 PR diff 和元数据，了解变更范围。
-### 2. 三轴审查
-- **规范轴**：代码是否符合编码标准？参考代码气味基线
-- **规格轴**：代码是否忠实实现了 PRD/技术方案？
-- **简单性轴**：是否存在不必要的复杂度？
+### 2. 双轴审查
+
+两条轴线分别审查、分别报告，不混排发现：
-#### 简单性轴（Simplicity）— 逐项检查
+- **规格轴（Specification）**：代码是否忠实实现 PRD、Task `Builds`、Acceptance Criteria 与 Design `Testing Decisions`？检查遗漏、不完整实现、错误行为和 scope creep。
+- **规范轴（Convention / Code Quality）**：代码和测试是否符合仓库规范、代码气味基线与简单性原则？
+
+#### 规范轴的简单性检查
- [ ] 是否有"只被一处调用"的抽象层？（违反 YAGNI）
- [ ] 是否有超过 3 层的继承/包装？（违反 KISS）
@@ -51,13 +55,19 @@ description: 负责代码审查、风险检查、质量把关（只读审查者
- [ ] 相同逻辑首次出现是否就被提取？（违反 DRY 3 次原则）
- [ ] 是否有当前 task 不需要的配置项/参数？（违反 YAGNI）
-发现上述问题标记为 `[SIMPLICITY]` 级别：
+发现上述问题在规范轴标记为 `[SIMPLICITY]`：
- 新增不必要的抽象层 → HIGH
- 为单一用例过度拆分 → MEDIUM
- 过早优化/预留扩展点 → LOW
+同时检查：
+
+- Interface 是否小而完整，复杂性是否隐藏在 deep Module 内。
+- 是否为单个假设 Adapter 创建了不必要的 Seam。
+- 测试是否通过 Design 约定的公共 Test Seam 验证行为，而不是私有方法、调用次数、调用顺序或内部状态。
+
### 3. 输出审查报告
-以结构化文本返回审查结论：
+以结构化文本分轴返回审查结论；任一轴存在阻断问题都必须 `CHANGES_REQUESTED`：
```
## 审查结论: APPROVED | CHANGES_REQUESTED
@@ -65,23 +75,25 @@ description: 负责代码审查、风险检查、质量把关（只读审查者
### 审查摘要
...
-### 发现
-[CRITICAL] 标题 - 必须修复
+### 规格轴
+结果: PASS | FAIL
+发现数: <数量>
+最高严重度: <级别或 None>
+
+[SPEC][CRITICAL] 标题 - 必须修复
- 文件:path:行号
- 问题
- 修复建议
-[HIGH] 标题 - 应该修复
-[MEDIUM] 标题 - 建议修复
-
### 规范轴
-...
-
-### 规格轴
-...
+结果: PASS | FAIL
+发现数: <数量>
+最高严重度: <级别或 None>
-### 简单性轴
-...（标记 [SIMPLICITY] 级别发现）
+[CONVENTION][HIGH] 标题 - 应该修复
+- 文件:path:行号
+- 问题
+- 修复建议
```
编排器将使用此报告执行 gh pr review。
@@ -90,7 +102,8 @@ description: 负责代码审查、风险检查、质量把关（只读审查者
- 不修改代码
- 每个问题必须给出具体的修复建议
- 优先关注安全性和正确性
+- 不合并或跨轴线重排发现，不用代码质量通过掩盖规格失败
## Project Context
-项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。
\ No newline at end of file
+项目根 CONTEXT.md 是领域术语权威（消息中已自动注入内容与 digest）。遵循其中定义的领域术语；发现新术语或冲突时暂停提问。
diff --git a/skills/flow-code/SKILL.md b/codex-skills/flow-code/SKILL.md
similarity index 100%
rename from skills/flow-code/SKILL.md
rename to codex-skills/flow-code/SKILL.md
diff --git a/codex-skills/flow-design/SKILL.md b/codex-skills/flow-design/SKILL.md
new file mode 100644
index 0000000..33bb776
--- /dev/null
+++ b/codex-skills/flow-design/SKILL.md
@@ -0,0 +1,146 @@
+---
+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），后续任务拆解以此为前置。
+
+## 设计约束
+
+技术方案必须遵循以下原则：
+
+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 不变**的前提下委派 `@agent-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。`@agent-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` 命令、`@agent-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）
diff --git a/skills/flow-release/SKILL.md b/codex-skills/flow-release/SKILL.md
similarity index 100%
rename from skills/flow-release/SKILL.md
rename to codex-skills/flow-release/SKILL.md
diff --git a/skills/flow-requirements/SKILL.md b/codex-skills/flow-requirements/SKILL.md
similarity index 94%
rename from skills/flow-requirements/SKILL.md
rename to codex-skills/flow-requirements/SKILL.md
index e016092..ce8e6e6 100644
--- a/skills/flow-requirements/SKILL.md
+++ b/codex-skills/flow-requirements/SKILL.md
@@ -16,6 +16,7 @@ description: 渐进式需求澄清 → PRD → Parent Issue
在 `docs/dev/decision-map.md` 创建映射，追踪所有待决策问题（Ticket 含 slug / Blocked by / Status / Type / Question / Answer）。初始只创建 2–4 个前沿 Ticket，不试图穷举。
Ticket 类型：Grilling（与用户对话澄清）/ Research（查文档）/ Prototype（低保真验证）。
+Research 型 Ticket → 派发 `@agent-researcher` 加载 `flow-research` skill 产出调研文档后，据结论 resolved。
## Phase B：渐进式解决
@@ -54,7 +55,7 @@ gh issue create --title "<英文功能标题>" --body "<目标 + 验收标准>"
## Contract
### Trigger
-由 `/requirements` 命令或 `@dev-lifecycle` 触发。
+由 `/requirements` 命令或 `@agent-dev-lifecycle` 触发。
### Inputs
- 用户提供的功能描述（来自消息文本）
diff --git a/codex-skills/flow-research/SKILL.md b/codex-skills/flow-research/SKILL.md
new file mode 100644
index 0000000..a7d1ba4
--- /dev/null
+++ b/codex-skills/flow-research/SKILL.md
@@ -0,0 +1,77 @@
+---
+name: flow-research
+description: 调研/事实核查 — 迭代深化 + 一手来源评分 + 反方搜索 + 置信度 → 调研文档（由 @agent-researcher 加载）
+---
+
+# flow-research
+
+针对调研问题系统性收集资料、验证来源、交叉对比，产出仅事实、带引用的调研文档。由独立子 agent `@agent-researcher` 加载执行，可作为 Flow 的阶段，也可作为独立轻量路径。
+
+## 核心流程
+
+1. **理解任务**：辨明「真问题 vs 表象」、前置假设、输出形式与范围（技术/时间/地区/行业）。
+2. **制定计划**：拆成子问题，说明来源需求、关键项、预判信息偏差与迭代轮次。
+3. **迭代收集**（多轮深化）：
+ - 来源优先级：官方文档/标准 → 学术/白皮书 → GitHub/Release/Issue → 权威博客 → 行业媒体 → 社区（社区仅作辅助）。
+ - 一手来源：优先追溯原始出处；来源评分卡（权威性/一手性/时效性/独立性/可验证性，综合 ≤12 仅作辅助参考）。
+ - 时间标注：关键引用标注发布时间；超时效门槛（技术选型>1年、安全/合规>6月、商业数据>1年、学术>3年）明确警告。
+4. **反方搜索 + 遗漏检查**：主动找反方观点、失败案例、替代方案隐藏成本；检查是否遗漏反例、边界场景、不熟悉但关键的部分。
+5. **评估与验证**：冲突来源列出各方观点→分析冲突原因→判断更可靠方；关键结论标注置信度（高/中/低/未知）。
+6. **综合分析**：方案全景 ≥3（保守/中间/激进）+ 成本全景 + 影响面 + 最坏情况（能否回滚、损失是否可控）。
+7. **元评审**（输出前自省）：剩余未知、最弱证据、可能错误的假设、遗漏角度、边际收益。
+8. **输出**：写 `docs/dev/research/<topic>.md`，并在消息中给结论/可执行建议摘要。
+
+## 何时停止迭代
+
+- 所有关键问题 ≥2 个独立来源支持
+- 最重要的反方观点已覆盖
+- 剩余不确定性已标注，继续投入的边际收益递减
+
+## 输出
+
+- `docs/dev/research/<topic>.md`
+- 消息中的结论 / 可执行建议 / 待进一步盘问项
+
+## 获取仓库上下文（runnable）
+
+```bash
+REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
+gh issue view <issue-number> # 若调研属于某 Flow/Task，读取其上下文
+gh api repos/"$REPO"/issues/<issue-number>/comments --jq '.[].body'
+```
+
+## Contract
+
+### Trigger
+由 `@agent-dev-lifecycle` Phase 0 调研场景派发 `@agent-researcher` 触发。
+
+### Inputs
+- 用户的调研问题 / 需求（含范围与输出形式）
+
+### Preconditions
+- 调研目标与范围明确；gh/git 可读（获取仓库与 Issue 上下文）
+- 需要外部资料时具备网络读取能力
+
+### Procedure
+1. 理解任务并制定研究计划
+2. 迭代收集并评分来源，追溯一手来源
+3. 反方搜索与遗漏检查
+4. 冲突处理与置信度标注
+5. 综合分析（方案/成本/影响面/最坏情况）
+6. 元评审后写 `docs/dev/research/<topic>.md` 并总结
+
+### Outputs
+- `docs/dev/research/<topic>.md`
+- 消息摘要
+
+### Failure
+- 无法访问可靠外部来源 → 说明并基于本地证据降级
+- 来源不足 → 明确标注「证据不足」，不编造
+
+### Idempotency
+- `docs/dev/research/<topic>.md` 已存在 → 更新而非新建重复文件
+
+### Prohibited Actions
+- 不编造来源、数据、案例或结论
+- 不改动代码（仅产出调研文档）
+- 不把未验证的二手/社区信息当作核心结论依据
diff --git a/codex-skills/flow-review/SKILL.md b/codex-skills/flow-review/SKILL.md
new file mode 100644
index 0000000..6086634
--- /dev/null
+++ b/codex-skills/flow-review/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: flow-review
+description: 双轴审查（规范 + 规格）→ 发布审查结果 → 合并
+---
+
+# flow-review
+
+沿两条轴线审查 PR 代码：规范（是否符合编码标准）和规格（是否实现了原始需求）。
+reviewer 只读；写操作（review/merge）由 primary 编排器执行。
+
+## 核心流程
+
+1. **发布审查结果**（primary 执行）
+ ```bash
+ gh pr review <pr-number> --approve
+ gh pr review <pr-number> --request-changes --body "<原因>"
+ ```
+2. **合并**（CI + 审查通过后，primary 执行）
+ ```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"
+ ```
+3. 合并后清理 worktree：`git worktree remove ".worktree/<task-slug>"`（脏时提示用户手动处理）
+
+reviewer 只读：不直接执行 `gh pr review` / `gh pr merge`（写操作由 primary 编排器执行）。
+
+## 双轴审查
+
+两条轴线独立审查、分别报告；不把发现项混排，也不允许一条轴线的通过掩盖另一条轴线的失败。
+
+### 规格轴（Specification）
+
+回答“是否实现了正确的行为”：
+
+- 对照 PRD、Task `Builds`、`Acceptance Criteria` 与技术方案检查遗漏或不完整需求。
+- 检查 diff 是否增加规格未要求的行为或抽象，识别 scope creep。
+- 检查看似已实现但边界、错误或状态转换不符合规格的行为。
+- 逐条核查 Acceptance Criteria 是否由 Design `Testing Decisions` 约定的 Test Seam 上的行为测试或验证命令证明。
+- 测试存在不等于规格通过；实现与测试共同误解需求时仍应报告。
+
+### 规范轴（Convention / Code Quality）
+
+回答“实现是否写得正确”：
+
+- 检查仓库文档化规范、AGENTS.md 与相关 ADR；仓库规则优先。
+- 参考 `references/smell-baseline.md`，代码气味属于判断性问题，不冒充硬性规范。
+- 检查 KISS、YAGNI、SRP，以及是否存在浅 Module、透传层或只有一个假设 Adapter 的 Seam。
+- 检查测试是否描述行为、使用公共 Test Seam，并避免私有方法、内部调用次数/顺序、侧信道和循环论证。
+- 跳过 formatter、lint、typecheck 等工具已经强制执行且没有实际风险的机械问题。
+
+**明确不检查 commit order**：RED→GREEN 顺序是编码过程约束，reviewer 不审查 commit 历史。
+
+### 审查结论
+
+- 任一轴存在阻断问题 → `CHANGES_REQUESTED`。
+- 两轴都没有阻断问题 → `APPROVED`。
+- 报告必须分别给出每条轴线的发现数量和最高严重度，不跨轴线重新排序。
+
+## 审查材料获取
+
+代码审查必须在本地分支/worktree 中进行，禁止通过 WebFetch 或浏览器访问远程 PR 页面获取代码。
+
+## Output
+- 结构化审查报告（APPROVED / CHANGES_REQUESTED）
+- PR 已合并（条件满足时）
+- Worktree 已清理
+
+## 后续
+- **/release** — 发布（如所有 PR 已合并）
+
+## Contract
+
+### Trigger
+由 `/review` 命令或 `@agent-dev-lifecycle` Phase 3 审查步骤触发。
+
+### Inputs
+- PR 编号、Task 文件与 Task Record（来源：`/code` 产出）
+- PRD 与技术方案（包含 Testing Decisions）
+
+### Preconditions
+- `/code` 已完成 → PR 已创建
+- Design 已包含本 Task 相关行为的 Testing Decisions；存量 Design 缺失时先返回 Design Gap，不提前给出审查结论
+
+### Procedure
+1. 在本地 worktree/分支获取 PR diff 与元数据
+2. 独立执行规格轴审查，核对行为、范围与 Acceptance Criteria 证据
+3. 独立执行规范轴审查，核对仓库规范、实现质量与测试质量
+4. 分轴输出结构化审查报告，不合并或重排发现
+5. primary 用 `gh pr review` 发布结果
+6. CI 通过后 primary 用 `gh pr merge` 合并并清理 worktree
+
+### Outputs
+- 结构化审查报告（APPROVED / CHANGES_REQUESTED）
+- PR 已合并（条件满足时）
+- Worktree 已清理
+
+### Failure
+- Critical/High → request-changes
+- Testing Decisions 缺失或与仓库现实冲突 → 返回 Design Gap，由 primary 在当前 stage 完成 amendment 后重新审查
+- Worktree 清理失败 → 记录警告，不阻塞
+
+### Idempotency
+- 已合并的 PR → 跳过
+- 已审查的 PR → 更新结论
+
+### Prohibited Actions
+- **禁止使用 WebFetch 或任何 Web 工具获取远程 PR 代码** — 审查代码时必须本地读取源码文件
+- reviewer 不直接执行 `gh pr review` / `gh pr merge`（由 primary 编排器执行）
+- 不把规格轴与规范轴合并成单一问题列表或用一条轴线抵消另一条轴线
+- 不使用默认 --force 清理
diff --git a/skills/flow-setup/SKILL.md b/codex-skills/flow-setup/SKILL.md
similarity index 100%
rename from skills/flow-setup/SKILL.md
rename to codex-skills/flow-setup/SKILL.md
diff --git a/codex-skills/flow-tasks/SKILL.md b/codex-skills/flow-tasks/SKILL.md
new file mode 100644
index 0000000..3410a47
--- /dev/null
+++ b/codex-skills/flow-tasks/SKILL.md
@@ -0,0 +1,220 @@
+---
+name: flow-tasks
+description: 将技术方案拆解为可独立实现的 tracer-bullet Task Plan 与 DAG
+---
+
+# flow-tasks
+
+将设计方案拆解为 Task Plan 与 DAG（有向无环图）。每个 Task 都是一条完整但狭窄的行为切片，可以交给一个 fresh-context developer agent 独立实现和验证。
+
+本 skill 只定义任务拆解与 Task Plan 产出。`@agent-architect` 不创建 GitHub Issue、不操作 GitHub lifecycle；调用方负责检查并发布 Task Plan。
+
+## Task 拆解规则
+
+每个 Task 必须：
+
+1. 交付一个可以观察或验证的新行为。
+2. 是垂直切片，而不是 Controller / Service / DAO 等技术分层。
+3. 可以交给一个 fresh-context developer agent 独立理解和实现。
+4. 完成以后仓库处于可工作的状态，而不是为下一个 Task 留空壳。
+5. `Blocked By` 只声明“前者未完成时，本 Task 无法开始”的真实阻塞关系。
+
+每个 Task 应适合一个 fresh-context developer agent：
+
+- 不需要读取整个 Flow 历史才能理解。
+- Task、Design 与 repository context 足够开始工作。
+- 正常情况下不需要再次进行架构设计。
+- 可以在一次独立开发循环中实现、测试、提交。
+
+## 何时拆分
+
+不要为了制造并行度而拆 Task。
+
+如果一个行为高度内聚、修改范围集中、一个 fresh context 可以完成，且没有独立可验证的中间行为，则保持为一个 Task。
+
+如果一个 Task 同时包含三个以上相互独立的“用户可以……”行为，应考虑按这些可独立验证的行为拆分。
+
+拆分前检查：
+
+1. **能否用一个 Task 完成？** — 足够内聚时不强拆。
+2. **拆开后能否独立验证？** — 每个 Task 都必须交付可观察行为。
+3. **是否真的阻塞？** — 只有无法开始的前置关系才进入 DAG。
+4. **拆开后耦合是否更低？** — 大量共享同一数据结构或模块时优先合并。
+
+## Behavior-preserving Pre-refactor
+
+行为 Task 的唯一例外是必要的 behavior-preserving pre-refactor：当现有结构使后续行为无法在一个可测试、可工作的垂直切片中安全实现时，可以先建立一个重构 Task。
+
+Pre-refactor 必须同时满足：
+
+- 不改变现有可观察行为，并用回归验证证明行为保持。
+- 自身完成后仓库保持可工作，不留下迁移一半的状态。
+- 只消除阻碍后续行为的具体结构问题，不搭通用框架、不预留未来扩展点。
+- 后续行为确实无法安全开始时，才将 pre-refactor 声明为 blocking edge。
+
+仅仅“这样更整洁”或“以后可能复用”不构成 pre-refactor。优先直接交付行为切片。
+
+Pre-refactor 的 `Builds` 应说明“保持哪个现有行为不变，并消除哪个阻碍后续行为的具体结构问题”，不能写成文件或类的修改清单。
+
+## 反模式
+
+| 反模式 | 示例 | 正确做法 |
+|--------|------|----------|
+| 技术分层拆分 | `create-session-table` → `implement-session-service` → `implement-session-api` | `create-and-restore-session` |
+| 测试单独成 Task | `add-session-tests` | 测试随行为切片一起交付 |
+| 过度拆分 | 一个内聚 CRUD 拆成多个 Task | 保持为一个可独立验证的 Task |
+| 预留式拆分 | 先搭框架，后续 Task 再填内容 | 每个 Task 完成后仓库都可工作 |
+| 虚假依赖 | 因修改相邻文件而声明依赖 | 仅声明不完成前者就无法开始的依赖 |
+
+## Task 定义
+
+每个 Task 保存为 `docs/dev/tasks/<task-name>.md`，是 developer 使用的 **Agent Implementation Contract**：
+
+`task-name` 使用简短的英文 kebab-case 行为短语，并作为后续 `feat/<task-name>` 分支名的基准。
+
+```markdown
+---
+issue: null
+test_commands:
+ - <targeted test command>
+verify_commands:
+ - <verification command>
+---
+
+# <task-slug>
+
+## Builds
+
+<这个 Task 完成后，哪个端到端行为真正可以工作？>
+
+## Acceptance Criteria
+
+- [ ] <可观察行为>
+- [ ] <边界或异常行为>
+- [ ] <回归要求>
+
+## Blocked By
+
+- <blocking-task-slug>
+- 或 None
+
+## Implementation Notes
+
+<只记录真正限制实现方式的重要设计决策；不要复制具体实现步骤。>
+```
+
+`Builds` 必须直接说明完成后的可工作行为。`Acceptance Criteria` 是 `flow-tdd` 使用的行为规格；`test_commands` 与 `verify_commands` 只放在 Task 文件中。
+
+Task 的行为测试必须沿用 Design `Testing Decisions` 中约定的 Test Seam。Task 不重新设计 Seam；如果既有 Seam 无法验证该行为，应返回 Design Gap，由调用方在当前 stage 完成 amendment。
+
+### Design Gap
+
+存量 Design 缺少 `Testing Decisions` 时，不回退 lifecycle stage，也不生成半成品 Task Plan。返回给调用方：
+
+```markdown
+## Design Gap
+
+- Current Stage: tasks
+- Design File: <docs/dev/specs/...>
+- Missing Behaviors:
+ - <缺少 Test Seam 或 Observable Result 的行为>
+- Existing Context: <已发现的公共 Interface 与测试惯例；没有则写 None>
+- Required Amendment: 为以上行为补充 Testing Decisions
+```
+
+调用方在当前 tasks 阶段完成 Design Amendment 后，重新执行 Task Planning。`@agent-architect` 不在 flow-tasks 内自行修改测试设计。
+
+规划阶段尚无 Issue 编号，`Blocked By` 使用 task slug。发布后由调用方将其更新为真实 `#<issue-number>`；无依赖时写 `None`。
+
+## DAG
+
+DAG 使用 Mermaid 语法，保存为 `docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/DAG.md`。
+
+- 节点对应行为 Task，不对应技术层。
+- 边只表示真实 blocking edge。
+- 发布前必须检查环形依赖。
+- 发布后将 Task 节点与依赖更新为真实 Issue 编号。
+
+## GitHub 发布边界
+
+GitHub Sub Issue 是协作与生命周期记录，正文只提取 Task 中用户可读的内容：
+
+```markdown
+## Builds
+
+...
+
+## Acceptance Criteria
+
+- [ ] ...
+
+## Blocked By
+
+None
+```
+
+不得把 `issue`、`test_commands`、`verify_commands` 或内部实现说明复制到 GitHub Issue。
+
+发布由调用方执行：
+
+- 普通 Flow：`@agent-dev-lifecycle` 检查后自动发布。
+- 高风险 Flow：展示 Task Plan，用户确认后发布。
+- 用户主动 `/tasks`：展示 Task Plan，等待用户确认后发布。
+- `@agent-architect`：产出并返回 Task Plan 后停止，不执行发布。
+
+## Output
+
+- `docs/dev/tasks/*.md` — Agent Implementation Contracts
+- `docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/DAG.md` — Task DAG
+- 返回给调用方的 Task Plan 摘要与拓扑顺序
+
+## 后续
+
+- `@agent-dev-lifecycle` 检查并发布 GitHub Sub Issues
+- **/code** — 按 Task DAG 进入编码阶段
+
+## Contract
+
+### Trigger
+由 `/tasks` 命令或 `@agent-dev-lifecycle` Phase 2 委派 `@agent-architect` 触发。
+
+### Inputs
+- `docs/dev/specs/<title>.md` — 技术方案
+- 相关 PRD 与 ADR
+- Parent Issue 编号
+
+### Preconditions
+- `/design` 已完成，技术方案和 ADR 存在
+
+### Procedure
+1. 读取设计基线与必要的 repository context。
+2. 读取 Design `Testing Decisions`，确认关键行为已有公共 Test Seam；缺失时返回 Design Gap 并停止，不生成或更新 Task 文件。
+3. 识别可独立验证的 tracer-bullet 行为切片；仅在必要时增加 behavior-preserving pre-refactor。
+4. 为每个 Task 定义 `Builds`、`Acceptance Criteria`、`Blocked By` 与必要的 `Implementation Notes`。
+5. 生成 Task 文件与 Mermaid DAG。
+6. 检查技术分层式拆分、空壳 Task、虚假依赖、臆测性 pre-refactor 与环形依赖。
+7. 返回 Task Plan、文件路径与拓扑顺序；不创建 GitHub Issue。
+
+### Outputs
+- Task 定义文件
+- Task DAG
+- 供调用方检查与发布的 Task Plan
+- 或结构化 Design Gap（存量 Design 缺少 Testing Decisions 时）
+
+### Failure
+- 无法从设计中确定可验证行为 → 暂停并指出缺失信息
+- Design Amendment 后仍缺少稳定 Test Seam → 报告未解决的 Design Gap，由调用方暂停当前阶段
+- DAG 存在环形依赖 → 阻止并报告
+- Task 无法由 fresh-context developer 独立理解 → 重新拆分或补足契约
+
+### Idempotency
+- Task 文件已存在 → 读取并更新，不创建重复定义
+- 已有 `issue` 编号 → 保留并交给调用方核验，不重复发布
+
+### Prohibited Actions
+- 不按技术层拆分 Task
+- 不为制造并行度而拆分 Task
+- 不创建完成后不可工作的空壳 Task
+- 不用 pre-refactor 包装搭框架、清理代码或预留扩展点
+- 不把非阻塞关系写入 `Blocked By`
+- `@agent-architect` 不执行 `gh issue create`、`git push`、PR、merge 或 worktree 操作
diff --git a/skills/flow-tdd/SKILL.md b/codex-skills/flow-tdd/SKILL.md
similarity index 56%
rename from skills/flow-tdd/SKILL.md
rename to codex-skills/flow-tdd/SKILL.md
index 0030317..1b2b4d8 100644
--- a/skills/flow-tdd/SKILL.md
+++ b/codex-skills/flow-tdd/SKILL.md
@@ -1,6 +1,6 @@
---
name: flow-tdd
-description: TDD Prompt 协议 — RED→GREEN 状态机 + self-report 证据
+description: 公共 Test Seam 上的行为 TDD — RED→GREEN 状态机 + self-report 证据
---
# flow-tdd
@@ -8,6 +8,41 @@ description: TDD Prompt 协议 — RED→GREEN 状态机 + self-report 证据
TDD（Test-Driven Development）Prompt 协议，为所有编码阶段提供统一的 TDD 流程约束。
本 skill 是 TDD 协议的唯一来源，其他 skills 和 agents 通过引用本协议获得一致的 TDD 行为。
+## 核心原则
+
+测试是行为规格：通过 Design `Testing Decisions` 约定的公共 Test Seam 验证可观察行为，而不是验证内部实现。只要公共行为不变，重构 Module 内部实现不应导致测试失败。
+
+每个 TDD cycle 是一个最窄行为切片：
+
+```text
+确定 Test Seam 与一个行为
+ ↓
+写一个行为测试
+ ↓
+RED
+ ↓
+最小实现
+ ↓
+GREEN
+ ↓
+下一个行为
+```
+
+### 好测试
+
+- 名称描述调用者或用户可以完成什么，而不是调用了哪个内部方法。
+- 只通过约定的公共 Test Seam 触发并观察行为。
+- 期望值来自 Acceptance Criteria、已知正确示例或其他独立来源。
+- 实现重构但行为不变时仍然通过。
+
+### 反模式
+
+- **实现耦合** — 测试私有方法、内部协作对象、调用次数或调用顺序。
+- **侧信道验证** — 绕过公共 Seam 读取数据库或内部状态来证明行为。
+- **循环论证** — 用与实现相同的算法重新计算期望值。
+- **水平批量** — 先写完全部测试再实现；应按一个行为测试 → 一个最小实现逐次推进。
+- **为 mock 造抽象** — 仅允许在真实系统边界按既有 Interface 替换外部依赖，不为测试方便新增生产 Seam。
+
## Advisory Procedure
Agent 自行遵循 TDD 流程并 self-report 状态。测试质量由仓库 CI 把关，内核不强制证据。
@@ -26,7 +61,7 @@ Agent 自行遵循 TDD 流程并 self-report 状态。测试质量由仓库 CI
│
▼
┌─────────────┐
- │ green │ ← 最小实现使测试通过（GREEN），可在此阶段重构
+ │ green │ ← 最小实现使测试通过（GREEN），仅做局部行为保持整理
└──────┬──────┘
│
┌──────────┼──────────┐
@@ -43,19 +78,21 @@ Agent 自行遵循 TDD 流程并 self-report 状态。测试质量由仓库 CI
│
▼
┌───────────────────┐
- │ final-verification│ ← 对照 acceptance_criteria 逐条验证
+ │ final-verification│ ← 对照 Acceptance Criteria 逐条验证
└───────────────────┘
```
### cycle-start
-开始一个新的 RED→GREEN 循环。Agent 在开始实现前声明当前 cycle 的目标（要实现的测试/功能）。
+开始一个新的 RED→GREEN 循环。Agent 在实现前从 Design `Testing Decisions` 读取 Test Seam，并声明本 cycle 的一个可观察行为。
**self-report 格式：**
```
## TDD cycle-start
- cycle: <序号>
-- target: <本 cycle 要实现的功能/测试描述>
+- behavior: <本 cycle 要交付的可观察行为>
+- test_seam: <约定的公共 Test Seam>
+- test: <通过该 Seam 验证行为的测试名称>
```
### red
@@ -64,6 +101,8 @@ Agent 自行遵循 TDD 流程并 self-report 状态。测试质量由仓库 CI
**约束：**
- 测试必须有明确的 fail/pass 边界
+- 测试名称描述行为，且只通过 cycle-start 声明的 Test Seam 触发和观察结果
+- RED 必须因目标行为尚未实现而失败，不能把环境、语法或夹具错误当作证据
- 测试运行命令必须与 Task 的 `test_commands` 中定义的一致
- 记录测试失败输出作为 RED evidence
@@ -77,12 +116,13 @@ Agent 自行遵循 TDD 流程并 self-report 状态。测试质量由仓库 CI
### green
-编写最小实现使 RED 阶段编写的测试通过。可在此阶段进行局部重构（消除重复、改善命名等），但不应扩展范围。
+编写最小实现使 RED 阶段的行为测试通过。可进行局部、行为保持的整理，但不得改变约定的 Test Seam 或扩展范围。
**约束：**
- 只写使当前测试通过的最少代码
- 不新增与当前 test 无关的功能
- 重构仅限于当前 cycle 涉及的代码
+- 不为通过测试而暴露内部状态、增加仅供测试使用的生产接口或改成实现细节断言
**self-report 格式：**
```
@@ -133,7 +173,7 @@ Agent 自行遵循 TDD 流程并 self-report 状态。测试质量由仓库 CI
### final-verification
-对照 Task 的 `acceptance_criteria` 逐条验证，确认全部满足。
+对照 Task 的 `Acceptance Criteria` 逐条验证，确认每项都由公共 Test Seam 上的行为测试或 `verify_commands` 证明。
**self-report 格式：**
```
@@ -149,23 +189,24 @@ Agent 自行遵循 TDD 流程并 self-report 状态。测试质量由仓库 CI
由编码阶段（`flow-code`）自动触发。Agent 在开始编码任务时加载 `flow-tdd` skill 获取 TDD 流程约束。
### Inputs
-- Task Record 中的 `acceptance_criteria`（来源：`flow-tasks` 产出）
-- Task Record 中的 `test_commands`（来源：`flow-tasks` 产出）
-- Task Record 中的 `verify_commands`（来源：`flow-tasks` 产出）
+- Task 文件中的 `Builds` 与 `Acceptance Criteria`（来源：`flow-tasks`）
+- Task frontmatter 中的 `test_commands` 与 `verify_commands`
+- Design `Testing Decisions` 中约定的 Test Seam 与 Observable Result
### Preconditions
-- Task Record 存在，包含 `acceptance_criteria`、`test_commands`
+- Task 文件存在，包含 `Builds`、`Acceptance Criteria`、`test_commands`
+- Design 已为目标行为定义公共 Test Seam；存量 Design 缺失时先向 primary 返回 Design Gap，由兼容门在当前 stage 补齐
- 测试运行环境就绪（worktree 内依赖已安装）
### Procedure
-1. 读取 Task 的 `acceptance_criteria`、`test_commands`、`verify_commands`
-2. 为每个验收标准识别对应的测试用例
-3. 执行 `cycle-start` → 声明当前 cycle 目标
-4. 执行 `red` → 编写测试，验证失败，记录 self-report
-5. 执行 `green` → 最小实现，验证通过，记录 self-report
-6. 重复 cycle 直到所有 criterion 覆盖
-7. 执行 `final-regression` → 运行全部测试
-8. 执行 `final-verification` → 逐条对照 acceptance_criteria
+1. 读取 Task 的 `Builds`、`Acceptance Criteria`、`test_commands`、`verify_commands`。
+2. 读取 Design `Testing Decisions`，确认目标行为的 Test Seam 与 Observable Result。
+3. 选择一个尚未满足的行为，执行 `cycle-start` 声明 behavior、test_seam 与 test。
+4. 执行 `red` → 只写该行为测试，验证因行为缺失而失败，记录 self-report。
+5. 执行 `green` → 编写最小实现，验证通过，记录 self-report。
+6. 按一个行为切片一个 cycle 重复，直到所有 Acceptance Criteria 被覆盖。
+7. 执行 `final-regression` → 运行全部测试。
+8. 执行 `final-verification` → 通过 Test Seam 或 `verify_commands` 逐条验证 Acceptance Criteria。
### Outputs
- 每个 cycle 的 self-report
@@ -174,6 +215,8 @@ Agent 自行遵循 TDD 流程并 self-report 状态。测试质量由仓库 CI
### Failure
- RED 阶段测试意外通过 → 检查测试是否有意义，可能需要 abandon-cycle
+- RED 因环境、语法或夹具错误失败 → 修复测试基础设施，不能计为 RED evidence
+- 只能通过内部实现观察目标行为 → 停止编码并向 primary 返回 Design Gap，不自行修改 Design、不回退 lifecycle stage
- GREEN 阶段测试持续失败 → 检查实现逻辑，记录失败原因
- final-regression 失败 → 修复回归，不要求新 cycle
- final-verification 未全部满足 → 返回未完成的 criterion，补充 cycle
@@ -184,6 +227,9 @@ Agent 自行遵循 TDD 流程并 self-report 状态。测试质量由仓库 CI
### Prohibited Actions
- 不跳过 RED 阶段直接进入 GREEN
+- 不测试私有方法、内部调用次数、内部调用顺序或未约定的侧信道
+- 不一次批量编写多个行为测试后再统一实现
+- 不为了 mock 或测试方便新增生产抽象
- 不跳过 final-regression 直接 commit
- 不在 abandon-cycle 后保留修改
- 不伪造测试结果（实际运行命令后再 self-report）
diff --git a/hooks/hooks.json b/hooks/hooks.json
index 450a279..46d492b 100644
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -2,15 +2,16 @@
"hooks": {
"SessionStart": [
{
+ "matcher": "startup|resume",
"hooks": [
{
"type": "command",
"command": "node ${PLUGIN_ROOT}/dist/hooks/session-start.js",
"statusMessage": "Loading Cabbage development context",
- "timeoutMs": 10000
+ "timeout": 10
}
]
}
]
}
-}
\ No newline at end of file
+}
diff --git a/package.json b/package.json
index 20f9e6f..dfdbd5d 100644
--- a/package.json
+++ b/package.json
@@ -41,7 +41,7 @@
"assets",
"README.md",
".codex-plugin",
- "skills",
+ "codex-skills",
"hooks"
],
"publishConfig": {
@@ -54,7 +54,7 @@
"typecheck": "tsc -p tsconfig.json --noEmit",
"test": "vitest run",
"prompt-lint": "vitest run test/plugin/prompt-lint.test.ts",
- "test:pack": "npm run build && pack_out=$(npm pack --dry-run 2>&1); echo \"$pack_out\" | grep -q 'dist/kernel/' || { echo 'FAIL: tarball 缺少 dist/kernel/'; exit 1; }; echo \"$pack_out\" | grep -q 'dist/flowrun/' && { echo 'FAIL: tarball 含过期 flowrun/ 残留'; exit 1; }; echo 'PASS: tarball 含 dist/kernel/，无 flowrun/ 残留'",
+ "test:pack": "npm run build && pack_out=$(npm pack --dry-run 2>&1); echo \"$pack_out\" | grep -q 'dist/kernel/' || { echo 'FAIL: tarball 缺少 dist/kernel/'; exit 1; }; echo \"$pack_out\" | grep -q 'dist/flowrun/' && { echo 'FAIL: tarball 含过期 flowrun/ 残留'; exit 1; }; for f in '.codex-plugin/plugin.json' 'codex-skills/flow-setup/SKILL.md' 'codex-skills/agent-dev-lifecycle/SKILL.md' 'hooks/hooks.json' 'dist/hooks/session-start.js'; do echo \"$pack_out\" | grep -q \"$f\" || { echo \"FAIL: tarball 缺少 $f\"; exit 1; }; done; echo 'PASS: tarball 含 dist/kernel/ + Codex 插件文件（manifest/skills/hooks/dist-hooks），无 flowrun/ 残留'",
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
diff --git a/skills/agent-dev-lifecycle/SKILL.md b/skills/agent-dev-lifecycle/SKILL.md
deleted file mode 100644
index 868c4b0..0000000
--- a/skills/agent-dev-lifecycle/SKILL.md
+++ /dev/null
@@ -1,159 +0,0 @@
----
-name: agent-dev-lifecycle
-description: 全流程开发编排器 — 需求确认后自动完成设计→任务拆解→并行实现→审查→合并
----
-
-<system-reminder>
-你是全流程开发编排器（dev-lifecycle）。
-
-你的目标：在用户确认需求方向后，自动串联设计 → 任务拆解 → Sub Issues 创建 → 并行编码实现 → 审查 → 合并的全流程。
-
-使用 GitHub Issue 作为 Flow Record 管理状态。每个阶段完成后，在 Issue 的 checklist 中勾选对应项。
-
-无需用户逐步骤确认，仅在遇到非预期错误时暂停并告知。
-
-**TDD 约束**：编码阶段引用 `flow-tdd` skill 作为 TDD 协议唯一来源（advisory，测试质量由 CI 把关）。
-</system-reminder>
-
-## 开始工作
-
-1. 创建或确认 Parent Issue（Flow Record）已存在，其中包含目标、验收标准和阶段 checklist
-2. 读取 Flow Record（Parent Issue body）获取目标与验收标准，按下方 Phase 顺序推进
-3. 每个阶段完成后，更新 Issue body 的 checklist（`gh issue edit <number> --body "..."`）标记进度
-4. 最终全部完成后，加载 `@agent-goal-verify` 做独立验证
-
-## 调度团队
-
-- @agent-architect：技术方案、ADR、DAG 任务拆解
-- @agent-developer：技术栈无关代码 TDD 实现（加载 `flow-tdd` skill，遵循 RED→GREEN cycle，编码 + 测试 + 本地 commit）
-- @agent-reviewer：只读代码审查，输出结构化审查报告（不操作 git/GitHub，不写文件）
-- @agent-goal-verify：独立验证目标完成状态
-
-## 全局约束
-
-### 阶段契约
-- 阶段顺序：requirements → design → tasks → code → review → release
-- 每个阶段完成后，在 Flow Record body 的 checklist 勾选对应阶段（`- [x] <stage>`）
-- requirements 完成需用户确认；高风险 Flow 的 design→tasks 需用户确认
-
-### 文档目录
-- PRD → `docs/prd/`
-- ADR → `docs/adr/`
-- 技术方案 → `docs/dev/specs/`
-- 任务 → `docs/dev/tasks/`
-- 开发文档 → `docs/dev/{api,db,guides}/`
-
-### 子 agent 约束
-- 禁止在 `/tmp/` 下创建或调试文件；临时产物放入 worktree 内
-- 文档产出必须遵循目录规范
-
-### 上下文管理（内化 handoff）
-长时间运行时主动管理上下文，不需要用户手动触发：
-- **上下文压力大**（接近模型上下文上限、阶段跨度大、等待外部输入）→ 自动产出交接文档：
- ```markdown
- # Handoff: <flow-slug> <date>
- ## 当前阶段 / 已完成 / 待办 / 下一步 / 关键产出（Issue·PR·文件）
- ```
- 保存到 `docs/dev/handoff-<YYYY-MM-DD>.md` 并在回复中告知用户可引用恢复。
-- **会话恢复**：恢复后先读最近 handoff 文件（`ls docs/dev/handoff-*.md` 取最新），
- 结合 Issue 状态和 checklist 恢复进度，继续剩余阶段，而不是从头重读全部文档。
-
----
-
-## Phase 1：技术方案 + ADR
-
-委派 @agent-architect：
-```
-基于 PRD（docs/prd/<title>.md）输出技术方案和 ADR。
-1. 技术方案 → docs/dev/specs/<title>.md
-2. ADR → docs/adr/<date>-<slug>.md
-3. gh issue comment 附到对应 Issue
-```
-
-## Phase 2：DAG 任务拆解 + Sub Issues
-
-委派 @agent-architect：
-```
-基于技术方案拆解 DAG 任务。
-1. 任务定义 → docs/dev/tasks/<task-name>.md（含 frontmatter）
-2. 每个任务创建 GitHub Sub Issue，关联 Parent Issue
-```
-
----
-
-## Phase 3：并行编码实现
-
-按 DAG 拓扑排序逐 batch 处理。每个 batch 内，无依赖的 task 使用独立 worktree 并行开发。
-
-```
-For each batch:
- For each task in batch (可并行):
- 0. 安全检查：确认设计阶段文档已通过 PR 合入默认分支（无未提交 docs 残留）
- BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
- git checkout $BASE && git pull origin $BASE
- 1. 为 Task 创建 worktree：
- git worktree add ".worktree/<task-slug>" -b "feat/<task-slug>"
- （前置校验：设计已合并、依赖 task 已合并；并行数 < 5）
- 2. 并行派发 @agent-developer 到各 worktree 路径
- 3. 每个 agent 在 worktree 内（不 push、不创建 PR）:
- - 按 Profile 的 test command 安装/执行测试（技术栈无关，不假设 npm）
- - 加载 `flow-tdd` skill，遵循 TDD Advisory Protocol
- - 编码 + 单测（RED→GREEN cycle + final-regression + final-verification）
- - 本地 commit（不 push）
- - 返回 branch、commit SHA、TDD self-report、test summary
- 4. 编排器为完成的 task 创建 PR：
- git push -u origin "feat/<task-slug>"
- gh pr create --base $BASE --head "feat/<task-slug>" \
- --title "feat: <task-slug>" \
- --body "# <task-slug>\n\n- Task Record: #<issue>\n\nCloses #<issue>"
- 5. 等待 CI 结果：测试在仓库 CI workflow 中运行（push 触发 GitHub Actions），
- 监听 workflow 运行结果确认测试通过，而非本地重复执行：
- gh run watch $(gh run list --branch "feat/<task-slug>" --json databaseId --jq '.[0].databaseId')
- （或 gh pr checks <pr-number> --watch；失败 → 分析日志派回 @agent-developer 修复后重新 push）
- 6. 委派 @agent-reviewer 双轴审查各 PR，附带 worktree 路径和分支信息：
- gh pr view <pr-number> --json headRefName,number,title
- ⚠️ 审查提示中必须包含：本地 worktree 路径（`.worktree/<task-slug>`）或分支名、
- PR 编号、明确指令：**在 worktree/分支内本地审查，禁止 WebFetch 远程代码**
- 7. 根据审查结果发布 review：
- gh pr review <pr-number> --approve （或 --request-changes）
- 8. CI 通过 + 审查通过后合并：
- gh pr merge <pr-number> --squash --delete-branch --match-head-commit <head-sha>
- 9. 合并后销毁 worktree（PR 合并 + 干净 → 自动；脏 → 提示用户手动处理）：
- git worktree remove ".worktree/<task-slug>"
-
-串行 task（有依赖关系）使用清理后重建策略：
- 上一 task 合并 → 销毁 worktree → 新建 worktree
-```
-
-约束：
-- 并行 task 使用不同分支名 `feat/<task-slug>`，避免 `git worktree add` 的分支冲突
-- 每个 agent 启动时显式 `cd .worktree/<task-slug>` 并验证 `pwd`
-- 分支冲突时暂停并提示用户手动清理
-- @agent-developer 不 push、不创建 PR、不操作 Issue — 由编排器统一执行
-- 合并前必须校验：CI 全部通过 + 分支保护存在 + `--match-head-commit` 使用已验证的 head SHA
-
----
-
-## Phase 4：合并确认
-
-确认全部 task PR 已合并：
-1. `gh pr list --state merged --search "<flow-slug>"` 检查关联 PR 合并状态
-2. 确认所有 Sub Issues 已自动关闭（PR body 含 `Closes #`）
-3. 全部 Task 合并后，加载 @agent-goal-verify 独立验证 Flow Record 目标是否达成
-
----
-
-## 完成
-
-所有阶段完成后，加载 `@agent-goal-verify` 做独立验证。
-
----
-
-## 异常处理
-
-| 场景 | 处理 |
-|------|------|
-| 任何步骤失败 | Pause flow，通知用户 |
-| Task 失败 | 自动重试最多 3 次，仍失败标记 blocked 并停止下游；其他独立 Tasks 继续 |
-| 审查不通过 | 自动修复最多 3 轮；第 3 轮仍未通过则停止该 Task |
-| 连续 3 次 continuation 无可验证进展 | Pause，请求用户介入 |
\ No newline at end of file
diff --git a/skills/flow-design/SKILL.md b/skills/flow-design/SKILL.md
deleted file mode 100644
index 57ebe05..0000000
--- a/skills/flow-design/SKILL.md
+++ /dev/null
@@ -1,90 +0,0 @@
----
-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），后续任务拆解以此为前置。
-
-## 设计约束
-
-技术方案必须遵循以下原则：
-
-1. **首选最简单方案** — 如果两个方案都能满足 PRD，选更简单的
-2. **不引入不必要的新技术** — 不要因为"这个技术很流行"而使用它
-3. **方案自检** — 每个设计决策必须能回答"为什么不用更简单的替代方案？"
-4. **ADR 记录简化决策** — 如果选择复杂方案，必须在 ADR 中说明为何简单方案不够
-
-## CONTEXT.md 术语
-
-阅读项目根 CONTEXT.md（领域术语权威，已自动注入内容与 digest）；
-设计中发现的新术语经用户确认后写入根 CONTEXT.md。
-
-## Output
-- `docs/dev/specs/<title>.md` — 技术方案
-- `docs/adr/<date>-<slug>.md` — ADR 决议
-- 根 CONTEXT.md 术语更新（如发现新术语）
-- Planning PR（合入后 = 设计基线）
-
-## 后续
-- **/tasks** — 基于设计方案拆解为 DAG 任务
-
-## Contract
-
-### Trigger
-由 `/design` 命令或 `@dev-lifecycle` Phase 1 触发。
-
-### Inputs
-- `docs/prd/<title>.md` — 上游 PRD（来源：requirements 阶段产出）
-- Parent Issue 编号（来源：requirements 阶段产出）
-
-### Preconditions
-- `/requirements` 已完成 → PRD 与 Parent Issue 存在
-- requirements 基线已用户确认
-
-### Procedure
-1. 基于默认分支创建工作分支
-2. 阅读 PRD、已有 ADR、根 CONTEXT.md 术语
-3. 输出技术方案到 `docs/dev/specs/<title>.md`
-4. 记录 ADR 到 `docs/adr/<YYYY-MM-DD>-<slug>.md`
-5. 提交并创建 Planning PR
-
-### Outputs
-- 技术方案 + ADR
-- Planning PR
-
-### Failure
-- ADR 与已有决策冲突 → 记录冲突并标注
-- Planning PR 创建失败 → 通知用户手动处理
-
-### Idempotency
-- 技术方案已存在 → 读取并更新
-- ADR 已存在 → 不重复创建
-- 分支已存在 → 检出后追加提交
-
-### Prohibited Actions
-- 不跳过 ADR 兼容性检查
-- 不直接 push 到默认分支（写操作走分支 + PR）
diff --git a/skills/flow-review/SKILL.md b/skills/flow-review/SKILL.md
deleted file mode 100644
index 45a7def..0000000
--- a/skills/flow-review/SKILL.md
+++ /dev/null
@@ -1,87 +0,0 @@
----
-name: flow-review
-description: 双轴审查（规范 + 规格）→ 发布审查结果 → 合并
----
-
-# flow-review
-
-沿两条轴线审查 PR 代码：规范（是否符合编码标准）和规格（是否实现了原始需求）。
-reviewer 只读；写操作（review/merge）由 primary 编排器执行。
-
-## 核心流程
-
-1. **发布审查结果**（primary 执行）
- ```bash
- gh pr review <pr-number> --approve
- gh pr review <pr-number> --request-changes --body "<原因>"
- ```
-2. **合并**（CI + 审查通过后，primary 执行）
- ```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"
- ```
-3. 合并后清理 worktree：`git worktree remove ".worktree/<task-slug>"`（脏时提示用户手动处理）
-
-reviewer 只读：不直接执行 `gh pr review` / `gh pr merge`（写操作由 primary 编排器执行）。
-
-## 双轴审查
-
-**规范轴（Normative）** — 代码是否符合文档化的编码标准？
-参考 `references/smell-baseline.md` 中的代码气味基线。
-
-**规格轴（Specification）** — 代码是否忠实实现了需求？
-对照 PRD（`docs/prd/`）和设计方案（`docs/dev/specs/`）验证。
-- 如发现实现与设计偏差 → 追加到 changelog
-
-**验收标准覆盖** — 检查 Task 的 `acceptance_criteria` 是否被 PR 覆盖：
-- 对照 Task Sub Issue body 中的 Acceptance Criteria，逐条核查
-- 检查 PR 是否包含每条 criterion 对应的测试或验证
-- **明确不检查 commit order** — RED→GREEN 顺序是编码过程约束，reviewer 不审查 commit 历史
-
-## 审查材料获取
-
-代码审查必须在本地分支/worktree 中进行，禁止通过 WebFetch 或浏览器访问远程 PR 页面获取代码。
-
-## Output
-- 结构化审查报告（APPROVED / CHANGES_REQUESTED）
-- PR 已合并（条件满足时）
-- Worktree 已清理
-
-## 后续
-- **/release** — 发布（如所有 PR 已合并）
-
-## Contract
-
-### Trigger
-由 `/review` 命令或 `@dev-lifecycle` Phase 3 审查步骤触发。
-
-### Inputs
-- PR 编号与 Task Record（来源：`/code` 产出）
-
-### Preconditions
-- `/code` 已完成 → PR 已创建
-
-### Procedure
-1. 在本地 worktree/分支获取 PR diff 与元数据
-2. 双轴审查（规范轴 + 规格轴）+ 验收标准覆盖
-3. 输出结构化审查报告
-4. primary 用 `gh pr review` 发布结果
-5. CI 通过后 primary 用 `gh pr merge` 合并并清理 worktree
-
-### Outputs
-- 结构化审查报告（APPROVED / CHANGES_REQUESTED）
-- PR 已合并（条件满足时）
-- Worktree 已清理
-
-### Failure
-- Critical/High → request-changes
-- Worktree 清理失败 → 记录警告，不阻塞
-
-### Idempotency
-- 已合并的 PR → 跳过
-- 已审查的 PR → 更新结论
-
-### Prohibited Actions
-- **禁止使用 WebFetch 或任何 Web 工具获取远程 PR 代码** — 审查代码时必须本地读取源码文件
-- reviewer 不直接执行 `gh pr review` / `gh pr merge`（由 primary 编排器执行）
-- 不使用默认 --force 清理
diff --git a/skills/flow-tasks/SKILL.md b/skills/flow-tasks/SKILL.md
deleted file mode 100644
index 51bc3a9..0000000
--- a/skills/flow-tasks/SKILL.md
+++ /dev/null
@@ -1,84 +0,0 @@
----
-name: flow-tasks
-description: DAG 任务拆解 → GitHub Sub Issues
----
-
-# flow-tasks
-
-将设计方案拆解为 DAG（有向无环图）任务，并用 gh 创建 GitHub Sub Issue（Task Record），关联 Parent Issue。
-
-## 核心流程
-
-基于技术方案拆解 DAG 后，为每个任务创建 Sub Issue：
-
-```bash
-gh issue create --parent <parent-issue-number> \
- --title "<英文功能标题>" \
- --body "# Task: <slug>\n\n## Acceptance Criteria\n- [ ] <id>: <描述> [tdd]\n\n## Dependencies\n- #<依赖任务编号>\n\nCloses 约定：PR body 含 \"Closes #<issue>\" 以在合并时关闭本 Sub Issue"
-```
-
-标题使用英文功能短语（kebab-case），作为分支名 `feat/<slug>` 的基准。
-
-## DAG 拆解
-
-#### 拆解前自检
-
-1. **能否用一个任务完成？** — 如果功能足够内聚，不强拆多个任务
-2. **拆开后能否独立验证？** — 每个任务必须有独立的验收标准
-3. **拆开后耦合是否最低？** — 两个任务共享大量数据结构/模块 → 合并
-
-#### 反模式
-
-| 反模式 | 示例 | 正确做法 |
-|--------|------|----------|
-| 技术分层拆分 | "建表任务" → "DAO 任务" → "Service 任务" | 垂直切片：一个任务包含完整链路 |
-| 过度拆分 | 一个 CRUD 拆成四个任务 | 一个 CRUD 就是一个任务 |
-| 预留式拆分 | "先搭框架，后面任务再填内容" | 不要有空壳任务 |
-
-DAG 使用 Mermaid 语法绘制，保存为 `docs/dev/tasks/<YYYY-MM-DD-NNN-slug>/DAG.md`。
-
-## 任务定义文件
-
-每个任务一个文件 `docs/dev/tasks/<task-name>.md`，frontmatter 含 `test_commands` / `verify_commands` / `acceptance` 结构化验收标准。
-这些字段是 `flow-tdd` skill 的输入（RED→GREEN cycle、final-regression、final-verification）。
-
-## Output
-- `docs/dev/tasks/*.md` — 独立任务文件
-- GitHub Sub Issues（依赖关系在 body 中声明）
-
-## 后续
-- **/code** — 认领 Sub Issue 开始编码
-
-## Contract
-
-### Trigger
-由 `/tasks` 命令或 `@dev-lifecycle` Phase 2 触发。
-
-### Inputs
-- `docs/dev/specs/<title>.md` — 技术方案
-- Parent Issue 编号
-
-### Preconditions
-- `/design` 已完成 → 技术方案和 ADR 存在（设计基线已合入）
-
-### Procedure
-1. 基于技术方案拆解 DAG（Mermaid 图 + 任务文件）
-2. 为每个任务用 gh 创建 Sub Issue（关联 Parent Issue，body 声明依赖）
-3. 任务文件合入默认分支
-
-### Outputs
-- `docs/dev/tasks/<feature-slug>/` — DAG 与任务文件
-- GitHub Sub Issues（含依赖声明）
-
-### Failure
-- DAG 存在环形依赖 → 阻止并报告
-- Sub Issue 创建失败 → 记录失败项
-
-### Idempotency
-- 任务文件已存在 → 读取并更新
-- Sub Issue 已创建 → 复用其编号而非重复创建
-
-### Prohibited Actions
-- 不跳过 DAG 依赖检查
-- 不创建重复 Sub Issue
-- 不直接 push 到默认分支
diff --git a/src/hooks/session-start.ts b/src/hooks/session-start.ts
index aa577c5..ea561c1 100644
--- a/src/hooks/session-start.ts
+++ b/src/hooks/session-start.ts
@@ -1,6 +1,6 @@
/**
* Cabbage Session Start Hook — loads plugin overview and project context.
- * Runs on Codex SessionStart lifecycle event.
+ * Runs on Codex SessionStart lifecycle event (matcher: startup|resume).
* Compiled to dist/hooks/session-start.js by tsc.
*/
import { readFileSync, existsSync } from "node:fs"
@@ -8,51 +8,71 @@ import { join } from "node:path"
// PLUGIN_ROOT is set by Codex hooks runtime
const PROJECT_DIR = process.cwd()
+const MAX_OUTPUT_LENGTH = 12000
function getHeader(): string {
return `## Cabbage Development Plugin
This plugin provides a full development lifecycle orchestration system.
-Load skills by name: @agent-dev-lifecycle, @agent-architect, @agent-developer, @agent-reviewer, @agent-goal-verify
+Load skills by name: @agent-dev-lifecycle, @agent-architect, @agent-developer, @agent-reviewer, @agent-goal-verify, @agent-researcher
### Available Flow Skills
- \`@flow-setup\` — 初始化项目开发环境
- \`@flow-requirements\` — 需求分析产出 PRD
- \`@flow-design\` — 技术方案与 ADR
- \`@flow-tasks\` — DAG 任务拆解
+- \`@flow-research\` — 调研/事实核查
- \`@flow-code\` — 编码实现（TDD）
- \`@flow-tdd\` — TDD 协议参考
- \`@flow-review\` — 代码审查
- \`@flow-release\` — 发布流程
### Available Agent Skills
-- \`@agent-dev-lifecycle\` — 全流程编排器（主 agent）
+- \`@agent-dev-lifecycle\` — 全流程编排器（主 agent，场景分诊）
- \`@agent-architect\` — 架构设计
- \`@agent-developer\` — 编码实现
- \`@agent-reviewer\` — 代码审查
- \`@agent-goal-verify\` — 目标验证
+- \`@agent-researcher\` — 独立调研
`
}
-function getProjectContext(): string {
+function readProjectProfile(): string {
// Try root AGENTS.md from project directory
const agentsMd = join(PROJECT_DIR, "AGENTS.md")
- if (existsSync(agentsMd)) {
- const content = readFileSync(agentsMd, "utf8")
- const profileMatch = content.match(/## Project Profile[\s\S]*?(?=##|$)/)
- if (profileMatch) return profileMatch[0].trim()
+ if (!existsSync(agentsMd)) return ""
+
+ let content: string
+ try {
+ content = readFileSync(agentsMd, "utf8")
+ } catch {
+ return ""
}
- return ""
+
+ // Match only the exact "## Project Profile" heading line (not "## Project Profile Notes"),
+ // and stop at the next "## " heading or end of file.
+ const lines = content.split("\n")
+ const start = lines.findIndex((line) => line.trim() === "## Project Profile")
+ if (start === -1) return ""
+
+ const end = lines.findIndex((line, i) => i > start && /^##\s/.test(line.trim()))
+ const slice = end === -1 ? lines.slice(start) : lines.slice(start, end)
+ return slice.join("\n").trim()
}
function main() {
const header = getHeader()
- const context = getProjectContext()
+ const profile = readProjectProfile()
const parts = [header]
- if (context) parts.push(`## Project Context\n\n${context}`)
+ if (profile) parts.push(`## Project Context\n\n${profile}`)
+
+ let output = parts.join("\n\n")
+ if (output.length > MAX_OUTPUT_LENGTH) {
+ output = `${output.slice(0, MAX_OUTPUT_LENGTH)}\n\n[context truncated — output exceeds ${MAX_OUTPUT_LENGTH} chars]`
+ }
- console.log(parts.join("\n\n"))
+ console.log(output)
}
-main()
\ No newline at end of file
+main()
diff --git a/test/plugin/codex-compat.test.ts b/test/plugin/codex-compat.test.ts
new file mode 100644
index 0000000..d341dfa
--- /dev/null
+++ b/test/plugin/codex-compat.test.ts
@@ -0,0 +1,158 @@
+import { describe, it, expect } from "vitest"
+import path from "node:path"
+import fs from "node:fs"
+
+const PROJECT_ROOT = path.resolve(import.meta.dirname || __dirname, "..", "..")
+
+function readJson(rel: string): Record<string, unknown> {
+ const raw = fs.readFileSync(path.join(PROJECT_ROOT, rel), "utf8")
+ return JSON.parse(raw) as Record<string, unknown>
+}
+
+function listSkillNames(dirRel: string): string[] {
+ const dir = path.join(PROJECT_ROOT, dirRel)
+ if (!fs.existsSync(dir)) return []
+ return fs
+ .readdirSync(dir, { withFileTypes: true })
+ .filter((e) => e.isDirectory())
+ .map((e) => e.name)
+ .sort()
+}
+
+/** 解析 SKILL.md frontmatter 的 name/description */
+function parseSkillMeta(skillDir: string): { name: string; description: string } {
+ const content = fs.readFileSync(path.join(skillDir, "SKILL.md"), "utf8")
+ const m = content.match(/^---\n([\s\S]*?)\n---/)
+ if (!m) throw new Error(`SKILL.md missing frontmatter: ${skillDir}`)
+ const name = m[1].match(/^name:\s*(.+)$/m)?.[1]?.trim() ?? ""
+ const description = m[1].match(/^description:\s*(.+)$/m)?.[1]?.trim() ?? ""
+ return { name, description }
+}
+
+/** Codex 侧 agent 引用为 @agent-xxx，assets 侧为 @xxx —— 归一后比较 */
+function normalizeAgentRefs(content: string): string {
+ return content.replace(/@agent-([a-z0-9-]+)/g, "@$1")
+}
+
+describe("codex plugin manifest (.codex-plugin/plugin.json)", () => {
+ const manifest = readJson(".codex-plugin/plugin.json")
+ const pkg = readJson("package.json")
+
+ it("is valid JSON and has required fields", () => {
+ expect(manifest.name).toBe("opencode-cabbage")
+ expect(typeof manifest.skills).toBe("string")
+ expect(manifest.interface).toBeTruthy()
+ })
+
+ it("skills field points to an existing directory", () => {
+ const skillsRel = (manifest.skills as string).replace(/^\.\//, "")
+ expect(fs.existsSync(path.join(PROJECT_ROOT, skillsRel))).toBe(true)
+ expect(fs.statSync(path.join(PROJECT_ROOT, skillsRel)).isDirectory()).toBe(true)
+ })
+
+ it("version stays in sync with package.json", () => {
+ expect(manifest.version).toBe(pkg.version)
+ })
+
+ it("uses a valid category from the official enum", () => {
+ const category = (manifest.interface as Record<string, unknown>).category
+ expect(["Developer Tools", "Productivity", "Utilities", "Data & Analytics"]).toContain(category)
+ })
+
+ it("has no app @mention in defaultPrompt (rejected by marketplace)", () => {
+ const defaultPrompt = (manifest.interface as Record<string, unknown>).defaultPrompt as string[]
+ for (const p of defaultPrompt) {
+ expect(p).not.toMatch(/@[a-z-]+/)
+ }
+ })
+
+ it("does not declare hooks (default ./hooks/hooks.json is auto-loaded)", () => {
+ expect(manifest.hooks).toBeUndefined()
+ })
+})
+
+describe("codex hooks (hooks/hooks.json)", () => {
+ const hooksJson = readJson("hooks/hooks.json")
+ const hooks = hooksJson.hooks as Record<string, Array<{ matcher?: string; hooks: Array<Record<string, unknown>> }>>
+
+ it("is valid JSON with SessionStart event", () => {
+ expect(hooks.SessionStart).toBeDefined()
+ expect(Array.isArray(hooks.SessionStart)).toBe(true)
+ })
+
+ it("each hook group has a matcher (prevents re-injection on compact)", () => {
+ for (const group of hooks.SessionStart) {
+ expect(typeof group.matcher).toBe("string")
+ expect(group.matcher!.length).toBeGreaterThan(0)
+ }
+ })
+
+ it("uses timeout (seconds) — no invalid timeoutMs field", () => {
+ for (const group of hooks.SessionStart) {
+ for (const hook of group.hooks) {
+ expect(hook.timeoutMs).toBeUndefined()
+ expect(typeof hook.timeout).toBe("number")
+ expect(hook.timeout as number).toBeGreaterThan(0)
+ }
+ }
+ })
+
+ it("commands target compiled dist/ artifacts under ${PLUGIN_ROOT}", () => {
+ for (const group of hooks.SessionStart) {
+ for (const hook of group.hooks) {
+ const cmd = String(hook.command)
+ expect(cmd).toMatch(/\$\{PLUGIN_ROOT\}\/dist\//)
+ // 对应源文件必须存在且被 tsc 覆盖（rootDir=src）
+ const srcRel = cmd.replace(/^node\s+/, "").replace(/\$\{PLUGIN_ROOT\}\/dist\//, "src/").replace(/\.js$/, ".ts")
+ expect(fs.existsSync(path.join(PROJECT_ROOT, srcRel))).toBe(true)
+ }
+ }
+ })
+})
+
+describe("codex skills drift vs assets", () => {
+ const codexFlows = listSkillNames("codex-skills").filter((n) => n.startsWith("flow-"))
+ const assetFlows = listSkillNames("assets/skills")
+
+ it("flow-* coverage matches assets/skills exactly (9/9)", () => {
+ expect(codexFlows).toEqual(assetFlows)
+ })
+
+ it("flow-* SKILL.md contents match assets after agent-ref normalization", () => {
+ for (const name of codexFlows) {
+ const codex = fs.readFileSync(path.join(PROJECT_ROOT, "codex-skills", name, "SKILL.md"), "utf8")
+ const asset = fs.readFileSync(path.join(PROJECT_ROOT, "assets", "skills", name, "SKILL.md"), "utf8")
+ expect(normalizeAgentRefs(codex), `${name}: codex copy drifted from assets`).toBe(asset)
+ }
+ })
+
+ it("agent-* skills cover all upstream agents (dev-lifecycle + team/*)", () => {
+ const teamDir = path.join(PROJECT_ROOT, "assets", "agents", "team")
+ const teamAgents = fs
+ .readdirSync(teamDir)
+ .filter((f) => f.endsWith(".md"))
+ .map((f) => f.replace(/\.md$/, ""))
+ const upstreamAgents = ["dev-lifecycle", ...teamAgents]
+ const codexAgents = listSkillNames("codex-skills").filter((n) => n.startsWith("agent-"))
+ const mapped = codexAgents.map((n) => n.replace(/^agent-/, "")).sort()
+ expect(mapped).toEqual(upstreamAgents.sort())
+ })
+
+ it("every codex skill has valid name/description frontmatter", () => {
+ for (const name of listSkillNames("codex-skills")) {
+ const meta = parseSkillMeta(path.join(PROJECT_ROOT, "codex-skills", name))
+ expect(meta.name).toBe(name)
+ expect(meta.description.length).toBeGreaterThan(0)
+ }
+ })
+
+ it("no OpenCode-kernel-only constructs in codex skills (goal tool / continuation / autoResume)", () => {
+ const banned = [/goal\(\{op:/, /autoResume/, /continuation prompt/i]
+ for (const name of listSkillNames("codex-skills")) {
+ const content = fs.readFileSync(path.join(PROJECT_ROOT, "codex-skills", name, "SKILL.md"), "utf8")
+ for (const re of banned) {
+ expect(content, `${name}: banned construct ${re}`).not.toMatch(re)
+ }
+ }
+ })
+})