@devcxl/opencode-cabbage 1.1.0 → 1.3.0

package/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）

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

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

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

@@ -0,0 +1,90 @@
+---
+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（低保真验证）。
+Research 型 Ticket → 派发 `@agent-researcher` 加载 `flow-research` skill 产出调研文档后，据结论 resolved。
+
+## 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` 命令或 `@agent-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（复用已有编号）

package/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
+- 不编造来源、数据、案例或结论
+- 不改动代码（仅产出调研文档）
+- 不把未验证的二手/社区信息当作核心结论依据

package/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 清理

package/codex-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（按用户确认的技术栈）