@devcxl/opencode-cabbage 0.3.1 → 1.0.0

package/assets/prompts/stage-contract.md

@@ -0,0 +1,55 @@
+# Stage Contract
+
+Flow 阶段契约的单一来源。Primary（`dev-lifecycle`）与所有 stage 命令（`/setup /requirements /design /tasks /code /review /release`）共享本契约。
+
+## 阶段模型
+
+| Stage | 阶段名（flow_control） | 产出 | 工具 |
+|-------|----------------------|------|------|
+| setup | —（前置初始化） | Profile 确认、workflow 就绪 | `setup_control` |
+| requirements | `requirements` | PRD、Decision Map、Flow Record、CONTEXT.md 术语 | `flow_control{create-flow}` |
+| design | `design` | 技术方案 + ADR（Planning Baseline） | `flow_control{planning-start, planning-pr}` |
+| tasks | `tasks` | DAG 任务定义、Sub Issues | `task_control{create-task}` |
+| code | `code` | 实现 + TDD evidence + PR | `task_control{start-task, submit-task}` |
+| review | `review` | 审查报告、合并 | `task_control{submit-review, merge-task}` |
+| release | —（手动） | 版本、Release PR、GitHub Actions 发布 | `release_control` |
+
+## 完成权威
+
+- **阶段完成 = Flow Record（Parent Issue）body checklist 中的 `- [x] <stage>`**
+- 阶段推进由 `flow_control{op:"stage-start"|"stage-complete"}` 维护：start 打 `cabbage:stage:<name>` label，complete 标记 checklist
+- 已完成阶段重复 start/complete → 幂等通过
+
+## 门禁规则
+
+| 场景 | 要求 |
+|------|------|
+| stage-start X | 前置阶段须已 completed（requirements 无前置） |
+| stage-complete X | 前置阶段须已 completed；**requirements 完成需用户确认一次** |
+| stage-start tasks（高风险 Flow，label `cabbage:risk:high`） | 需用户确认（`user_confirmed: true`） |
+| 依赖 Task 启动 | 前置依赖 Task 已 merged、并行数 < 5 |
+
+## 阶段顺序与基线
+
+```
+setup → requirements → design → tasks → code → review → (release 手动)
+```
+
+- **Planning Baseline**：CONTEXT.md + PRD + Design + ADR 经单个 Planning PR 合入后，才允许创建 Task Record
+- **requirements 基线**：需求阶段结束须用户确认一次
+- **goal 最小化**：`goal({op:"create", parent_issue_number:<Flow Record 编号>})`，目标/验收从 Flow Record 读取
+
+## 各阶段关键约束
+
+- **requirements**：渐进式澄清（Decision Map），一次只问一个问题；领域术语写入根 CONTEXT.md
+- **design**：architect 在 planning worktree 产出文档；方案遵循工程原则（KISS/YAGNI/DRY/SRP）
+- **tasks**：垂直切片、可独立验证、无循环依赖；标题用英文功能标题（内核派生 slug）
+- **code**：TDD 协议唯一来源是 `flow-tdd` skill；证据经 `tdd_checkpoint` 提交，缺证据 PR 被拒
+- **review**：双轴审查（规范 + 规格）+ TDD criterion coverage；reviewer 只读，写操作经 `task_control`
+- **release**：人工流程；按 Profile 版本规则 + 项目 GitHub Actions release workflow（技术栈无关）
+
+## Prohibited Actions
+
+- 不跳过前置门禁直接 stage-start/complete
+- 不手工修改 Flow Record 的 stage checklist（由 flow_control 维护）
+- 不绕过工具直接执行高风险 git/gh 写操作（push/PR/merge/worktree）

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

@@ -1,140 +1,38 @@
 ---
 name: flow-code
-description: 分支 → 编码 + 单测 → PR 提交（Worktree 模式）
+description: 编码实现 — task_control 创建 worktree + TDD（flow-tdd 协议）
 ---
 
 # flow-code
 
-认领 Sub Issue，创建 worktree，实现代码+单测，提交 PR。
+认领 Task Record（Sub Issue），在 worktree 内按 TDD 实现代码与单测。
+worktree 创建、PR 提交由内核工具 `task_control` 完成，本 skill 不复制 shell 实现。
 
-## Prerequisites
-- `/tasks` 已完成 → Sub Issues 就绪
-- 阅读 `docs/adr/` 确保实现与 ADR 兼容
-- 确认 task 的 `worktree_root` 字段（来自 task 文件 frontmatter）
-
-## Workflow
-
-### 1. 选择任务
-选择一个可执行的 Sub Issue（前置依赖已满足）。
-
-### 2. 检查 ADR 约束
-阅读相关 ADR，确保实现方案不违反已有架构决策。
-
-### 3. 创建/复用 Worktree
-```bash
-# 探测默认分支
-BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")
-
-# 检查和创建 worktree
-WORKTREE=".worktree/<task-slug>"
-BRANCH="feat/<task-slug>"
-
-if [ -d "$WORKTREE" ]; then
-  # Worktree 目录已存在 → 验证一致性
-  EXISTING=$(git -C "$WORKTREE" rev-parse --abbrev-ref HEAD 2>/dev/null)
-  if [ "$EXISTING" != "$BRANCH" ]; then
-    echo "ERROR: $WORKTREE exists but tracks branch '$EXISTING' (expected '$BRANCH')"
-    exit 1
-  fi
-  echo "Worktree 已存在，复用：$WORKTREE"
-else
-  # 检查分支是否已存在
-  if git show-ref --verify "refs/heads/$BRANCH" >/dev/null 2>&1; then
-    # 分支已存在，检查是否已合并
-    if git branch --merged "$BASE" | grep -q "$BRANCH"; then
-      git branch -D "$BRANCH"
-    else
-      echo "ERROR: 分支 '$BRANCH' 已存在，请先处理"
-      exit 1
-    fi
-  fi
-  # 创建 worktree + 分支
-  git worktree add -b "$BRANCH" "$WORKTREE" "$BASE"
-fi
-
-# 进入 worktree
-cd "$WORKTREE"
-```
-### 4. 安装依赖
-
-```bash
-npm install
-```
-
-### 5. 编码 + 单测
-```bash
-# 实现代码 + 单元测试
-npm test
-```
-
-#### TDD Advisory Protocol
-
-编码阶段必须遵循 `flow-tdd` skill 定义的 TDD 流程。Agent 在编写任何功能代码前加载 `flow-tdd` skill。
-
-**TDD 检查点（commit 前自检）：**
-- [ ] 每个功能的代码变更都有对应的测试
-- [ ] 测试在修改前是 RED（失败），修改后是 GREEN（通过）
-- [ ] 已完成 `final-regression`（全部测试通过）
-- [ ] 已完成 `final-verification`（对照 acceptance_criteria）
-- [ ] self-report 已写入 commit message 或 PR body
-
-> 引用：`flow-tdd` skill 是 TDD 协议的唯一来源，包含完整的 RED→GREEN cycle 状态机、abandon-cycle 规则和 final-regression/verification 流程。
-
-### 6. 文档同步检查
-完成编码后，逐项检查以下文档是否需要同步更新：
-
-```
-## 文档同步检查清单
-□ guides/quickstart.md — 安装方式或前置条件有变化吗？
-□ guides/configuration.md — 新增/修改了配置项吗？
-□ guides/usage.md — 命令或行为有变化吗？
-□ guides/architecture.md — 架构或流程有变化吗？
-□ docs/dev/guides/contributing.md — 开发流程有变化吗？
-```
-
-- 逐项评估，无需修改的跳过
-- 需要修改的文档随代码一起提交到同一个 PR
-- PR body 中列出已同步的文档
-
-### 7. 提交 PR
-```bash
-# 在 worktree 内执行
-
-# 根据 task 预期文件和 git status 确定待暂存文件
-# Task 文件通常包含 frontmatter expected_files 字段
-git status --short
-
-# 显式暂存任务相关文件（不是 git add .）
-# 示例：git add src/plugin/goal.ts test/goal.test.ts assets/agents/team/reviewer.md
-git add <file1> <file2> ...
-
-# 提交前检查：确保无密钥、无超大文件、无任务范围外文件
-git diff --cached --name-only
-
-git commit -m "feat(<scope>): <title>"
-git push origin feat/<task-slug>
-mkdir -p docs/dev/handoff
-echo "Closes #<issue-num>" > docs/dev/handoff/pr-body.md
-gh pr create --title "<title>" --body-file docs/dev/handoff/pr-body.md
-```
-
-### 8. 更新开发文档
-如涉及 API 变更 → 更新 `docs/dev/api/`
-如涉及数据模型变更 → 更新 `docs/dev/db/`
+## 核心：调用 task_control + flow-tdd
 
-## Output
-- Worktree 已创建/复用（`.worktree/<task-slug>/`）
-- 代码已推送
-- PR 已创建并关联 Sub Issue（PR body 含 `Closes #<issue-num>`）
-- 文档同步 checklist 已完成
-- 已同步的文档随 PR 提交
-- dev docs 已更新
+1. `task_control{op:"start-task", task_id:"<slug>", ...}` — 创建 worktree + 记录基线 + 冻结 TDD policy
+2. 加载 `flow-tdd` skill，按 Task 的 `tdd` 配置执行 RED→GREEN cycle
+3. 每个 stage 通过 `tdd_checkpoint` 提交证据（唯一证据源，缺证据的 PR 会被拒绝）
+4. 本地 `git add` + `git commit`（多次提交）
+5. **不 push、不创建 PR** — 由 primary 的 `task_control{op:"submit-task"}` 完成
+
+## 编码约束
+
+- 只改 Task 相关的文件；遵循项目现有代码规范与分层结构
+- 遵循工程原则（KISS/YAGNI/DRY/SRP/最小变更，单份引用仓库 AGENTS.md）
+- 文档同步：涉及 guides/api/db 变更时随代码同 PR 更新
 
-## 上下文管理
-如果上下文窗口压力大，使用 `../flow-handoff` 打包进度。
+## TDD 引用
+
+> `flow-tdd` skill 是 TDD 协议的唯一来源，包含完整的 RED→GREEN cycle 状态机、
+> abandon-cycle 规则和 final-regression/verification 流程，以及 `tdd_checkpoint` 各 op 的调用方式。
+
+## Output
+- Worktree 已创建（task_control）
+- TDD evidence 已提交（tdd_checkpoint）
+- 本地 commit 就绪（分支推送与 PR 由 task_control 完成）
 
 ## 后续
-- **/test** — 触发 CI E2E 测试
 - **/review** — 审查 PR
 
 ## Contract
@@ -143,33 +41,33 @@ gh pr create --title "<title>" --body-file docs/dev/handoff/pr-body.md
 由 `/code` 命令或 `@dev-lifecycle` Phase 3 触发。
 
 ### Inputs
-- Sub Issue 编号（来源：`/tasks` 产出）
-- task 文件 frontmatter 中的 `worktree_root`（来源：task 文件）
+- Task Record（Sub Issue 编号与标题，来源：`/tasks` 产出）
 
 ### Preconditions
 - `/tasks` 已完成 → Sub Issues 就绪
-- 前置依赖任务已合并
+- Planning Baseline 已合入；前置依赖任务已合并（task_control 门禁）
 
 ### Procedure
-1. 选择依赖已满足的 Sub Issue
-2. 创建或复用 Worktree（`git worktree add -b`）
-3. 安装依赖 → 编码 + 单测 → commit + push
-4. 编排器创建 PR
+1. 调用 `task_control{op:"start-task"}` 创建/复用 worktree
+2. 加载 `flow-tdd`，按 Task 的 tdd 配置执行 RED→GREEN cycle
+3. 通过 `tdd_checkpoint` 提交证据
+4. 本地 git add + commit（不 push）
+5. 交回 primary 调用 `task_control{op:"submit-task"}` 创建 PR
 
 ### Outputs
 - Worktree 已创建（`.worktree/<task-slug>/`）
-- 代码已推送
-- PR 已创建（Orchestrator 执行）
+- TDD evidence（Task Record 单评论）
+- 本地 commit
 
 ### Failure
-- Worktree 创建失败 → 检查分支冲突或目录残留
-- 测试失败 → 修复后重试
+- worktree 创建失败 → 检查分支冲突或目录残留（task_control 报错）
+- 测试失败 → 修复后重试（不跳过 RED）
 
 ### Idempotency
-- Worktree 已存在 → 复用
+- worktree 已存在 → task_control 校验分支一致性后复用
 - 代码已提交 → 追加提交
 
 ### Prohibited Actions
-- Worker 不创建 PR、不操作 Issue
+- 不 push、不创建 PR、不操作 Issue（由 task_control 完成）
 - 不使用 `git add .`
-- 不直接 push 到默认分支
+- 不绕过 task_control 直接执行 worktree 创建 / PR 创建 / 分支推送

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

@@ -1,83 +1,40 @@
 ---
 name: flow-design
-description: 技术方案设计 → 方案文档 + ADR 输出
+description: 技术方案设计 → 方案文档 + ADR（planning worktree + Planning PR）
 ---
 
 # flow-design
 
-基于 PRD 进行技术方案设计，输出方案文档和 ADR。
+基于 PRD 进行技术方案设计，architect 在 planning worktree 产出 CONTEXT.md + PRD + Design + ADR，
+并由 `flow_control` 通过 Planning PR 合入形成 Planning Baseline。
 
-## Prerequisites
-- `/requirements` 已完成 → `docs/prd/<title>.md` + Parent Issue 存在
-- 阅读 `../_context/CONTEXT.md` 了解领域术语
+## 核心：调用 flow_control
 
-## Workflow
+1. `flow_control{op:"planning-start"}` — 创建 planning worktree `.worktree/planning-<slug>`（architect 在此写文档）
+2. 在 planning worktree 内产出：根 `CONTEXT.md` 术语更新 + `docs/prd/<title>.md` + `docs/dev/specs/<title>.md` + `docs/adr/<date>-<slug>.md`
+3. `flow_control{op:"planning-pr"}` — 对 planning worktree 变更创建 Planning PR（合并后 = Planning Baseline）
 
-### 1. 阅读上下文
-- 阅读 PRD：`docs/prd/<title>.md`
-- 阅读已有 ADR：`docs/adr/`（确保设计不与已有架构决策冲突）
-- 阅读 `docs/dev/out-of-scope.md`（了解已排除范围）
+worktree 创建与 Planning PR 创建均由内核工具完成，创建动作全部收敛到工具内。
 
-### 2. 技术方案设计
-输出到 `docs/dev/specs/<title>.md`，包含：
-- 技术选型与理由
-- 架构与数据流
-- API / 数据模型
-- 与已有的 ADR 的兼容性检查
+## 设计约束
 
-### 3. 记录 ADR
-为每个关键决策记录 ADR 到 `docs/adr/<YYYY-MM-DD>-<slug>.md`。
-ADR 格式参考 `_prompts/adr-format` 中的格式要求。
+技术方案必须遵循以下原则：
 
-ADR 至少记录：
-- 技术选型决策
-- 架构模式决策
-- 任何可能有争议的方案选择
+1. **首选最简单方案** — 如果两个方案都能满足 PRD，选更简单的
+2. **不引入不必要的新技术** — 不要因为"这个技术很流行"而使用它
+3. **方案自检** — 每个设计决策必须能回答"为什么不用更简单的替代方案？"
+4. **ADR 记录简化决策** — 如果选择复杂方案，必须在 ADR 中说明为何简单方案不够
 
-### 4. 附到 GitHub Issue
-```bash
-mkdir -p docs/dev/handoff
-cat > docs/dev/handoff/design-comment.md << 'EOF'
-## 技术方案
+## CONTEXT.md 术语
 
-...（摘要）
-
-## ADR
-
-...（ADR 列表）
-
-完整文档：docs/dev/specs/<title>.md
-EOF
-gh issue comment <issue-number> --body-file docs/dev/handoff/design-comment.md
-```
-
-### 5. 提交文档（Planning PR）
-设计文档和 ADR 通过 Planning PR 合入，确保分支保护下也能正常工作：
-
-```bash
-# 探测默认分支
-BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || echo "main")
-
-# 创建 planning 分支
-git checkout -b chore/plan-<slug> $BASE
-git add docs/dev/specs/<title>.md docs/adr/<date>-<slug>.md
-git commit -m "docs: <title> — 技术方案 + ADR"
-git push origin chore/plan-<slug>
-
-# 创建 PR
-gh pr create --title "docs: <title> — 技术方案 + ADR" \
-  --body "Planning PR：完整技术方案和架构决策记录" \
-  --base $BASE
-
-# 合并 PR 后切回 $BASE
-git checkout $BASE && git pull origin $BASE
-```
+阅读项目根 CONTEXT.md（领域术语权威，已自动注入内容与 digest）；
+设计中发现的新术语经用户确认后写入根 CONTEXT.md（术语权威）。
 
 ## Output
 - `docs/dev/specs/<title>.md` — 技术方案
 - `docs/adr/<date>-<slug>.md` — ADR 决议
-- Parent Issue 收到设计评论
-- 文档通过 Planning PR 合入默认分支
+- 根 CONTEXT.md 术语更新（如发现新术语）
+- Planning PR（由 flow_control 创建）
 
 ## 后续
 - **/tasks** — 基于设计方案拆解为 DAG 任务
@@ -89,31 +46,33 @@ git checkout $BASE && git pull origin $BASE
 
 ### Inputs
 - `docs/prd/<title>.md` — 上游 PRD（来源：requirements 阶段产出）
-- Parent Issue 编号（来源：Goal metadata 或 `/requirements` 阶段产出）
+- Flow Record 编号（来源：requirements 阶段产出）
 
 ### Preconditions
-- `/requirements` 已完成 → `docs/prd/<title>.md` 存在
-- Parent Issue 存在
+- `/requirements` 已完成 → PRD 与 Flow Record 存在
+- requirements 基线已用户确认
 
 ### Procedure
-1. 阅读 PRD、已有 ADR、Out of Scope
-2. 输出技术方案到 `docs/dev/specs/<title>.md`
-3. 记录 ADR 到 `docs/adr/<YYYY-MM-DD>-<slug>.md`
-4. 附设计评论到 Parent Issue
-5. 通过 Planning PR 提交文档
+1. 调用 `flow_control{op:"planning-start"}` 创建 planning worktree
+2. 阅读 PRD、已有 ADR、根 CONTEXT.md 术语
+3. 输出技术方案到 `docs/dev/specs/<title>.md`
+4. 记录 ADR 到 `docs/adr/<YYYY-MM-DD>-<slug>.md`
+5. 调用 `flow_control{op:"planning-pr"}` 创建 Planning PR
 
 ### Outputs
-- `docs/dev/specs/<title>.md` — 技术方案
-- `docs/adr/<date>-<slug>.md` — ADR 决议
+- 技术方案 + ADR（planning worktree 内）
+- Planning PR（Planning Baseline 的一部分）
 
 ### Failure
 - ADR 与已有决策冲突 → 记录冲突并标注
-- Planning PR 合并失败 → 通知用户手动处理
+- Planning PR 创建失败 → 通知用户手动处理
 
 ### Idempotency
 - 技术方案已存在 → 读取并更新
 - ADR 已存在 → 不重复创建
+- planning worktree 已存在 → 复用（工具校验分支一致性）
 
 ### Prohibited Actions
-- 不直接 push 到默认分支
+- 不绕过 flow_control 手工创建 worktree / Planning PR（由内核工具完成）
 - 不跳过 ADR 兼容性检查
+- 不直接 push 到默认分支

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

@@ -1,54 +1,34 @@
 ---
 name: flow-release
-description: 版本 → Changelog → Release → npm publish（仅人工）
+description: 版本 → Release PR → GitHub Actions 发布（release_control，仅人工）
 ---
 
 # flow-release
 
-版本号更新 → tag 推送 → Release 草稿 → 人工审核发布 → 自动 npm publish。
+通过 `release_control` 完成版本提议、Release PR、合并发布与发布监控。
+发布流程技术栈无关：按 Profile 的版本规则（version file / tag format / release workflow）执行，
+最终发布走项目自己的 GitHub Actions release workflow（不假设 npm 或任何特定生态）。
 
-## Prerequisites
-- main 分支最新，所有 PR 已合并
-- CI 通过
+## 核心：调用 release_control
 
-## Workflow
+1. `release_control{op:"propose-version"}` — 聚合上一 tag 后全部 commit，按 Profile 版本规则分类，输出提议版本
+2. `release_control{op:"open-release-pr"}` — 固定顺序：release branch → 按 Profile 写规则更新版本 → Release PR（人工确认后）
+3. `release_control{op:"merge-release-pr"}` — CI + 人工批准 → merge → SHA 校验 → 打 tag push
+4. `release_control{op:"monitor"}` — 轮询 GitHub Actions release workflow 至成功；瞬时失败 rerun；代码/配置缺陷 → Corrective Flow
 
-### 1. 确认版本号
-从 conventional commits 自动确定 semver bump：
-```bash
-git log $(git describe --tags --abbrev=0)..HEAD --oneline
-```
-- `fix:` → patch | `feat:` → minor | `BREAKING:` → major
+## 版本规则（Profile）
 
-### 2. 更新版本号 → 打 tag → 推送
-```bash
-npm version <major|minor|patch> --no-git-tag-version
-# 更新 CHANGELOG.md
-git commit -m "chore(release): v<version>"
-BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
-git tag v<version>
-git push origin $BASE --tags
-```
-
-### 3. Release 草稿（自动）
-tag 推送触发 `.github/workflows/release-draft.yml`：
-- 构建 + 测试
-- 生成 Release 草稿（含自动 release notes）
-
-### 4. 人工审核发布
-GitHub Releases 页面 → 检查 Release 草稿 → 点击 **Publish release**。
-
-发布触发 `.github/workflows/release-publish.yml`：
-- 自动 `npm publish`（需要 `NPM_TOKEN` 仓库 Secret）
+版本分类依赖 AGENTS.md `## Project Profile` 的 `version bump rule`：
+`breaking→major, feature→minor, fix→patch`（0.x breaking 也 major）。
+未分类 commit → release_control 要求用户分类后重试。
 
 ## Output
-- 版本已更新
-- tag 已推送
-- Release 草稿已创建（待人工发布）
-- 发布后自动推送 npm
+- 提议版本
+- Release PR（合并 + tag push）
+- GitHub Actions release workflow 运行结果
 
 ## 后续
-无需后续阶段。Flow 完成。
+- 发布完成后 Flow 结束（goal-verify 独立验证 → complete-flow）
 
 ## Contract
 
@@ -56,31 +36,31 @@ GitHub Releases 页面 → 检查 Release 草稿 → 点击 **Publish release**
 由 `/release` 命令触发。**仅手动触发**，不包含在自动流程中。
 
 ### Inputs
-- 版本号类型（patch/minor/major，来源：用户指定）
+- 用户对提议版本/Release 的确认
 
 ### Preconditions
 - 所有 PR 已合并
-- 默认分支最新
-- 所有测试通过
+- 默认分支最新且 CI 通过
+- Release Profile 已确认（AGENTS.md Project Profile）
 
 ### Procedure
-1. 确认版本号
-2. 更新版本（npm version）
-3. 生成 Changelog
-4. 创建 git tag → push → 触发 Release 草稿
-5. 人工审核发布 → npm publish
+1. 调用 `release_control{op:"propose-version"}` 确定版本
+2. 调用 `release_control{op:"open-release-pr"}` 创建 Release PR（人工确认）
+3. 调用 `release_control{op:"merge-release-pr"}` 合并 + 打 tag
+4. 调用 `release_control{op:"monitor"}` 监控发布 workflow
 
 ### Outputs
-- GitHub Release
-- npm 包已发布
+- GitHub Release（经项目 release workflow）
+- tag 已推送
 
 ### Failure
-- npm publish 失败 → 检查 npm 认证
+- 发布 workflow 失败 → monitor 识别瞬时失败并 rerun；代码/配置缺陷 → Corrective Flow + 新版本
 - tag 已存在 → 提示版本冲突
 
 ### Idempotency
-- 相同版本号 → 阻止
+- 相同版本号 → 阻止重复发布
 
 ### Prohibited Actions
-- 不在自动模式中执行
-- 不跳过测试直接发布
+- 不在自动模式中执行（release 为人工流程）
+- 不假设 npm 或其他特定技术生态（按 Profile 规则 + 项目 GitHub Actions release workflow）
+- 不跳过测试/CI 直接发布

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

@@ -1,82 +1,84 @@
 ---
 name: flow-requirements
-description: 需求访谈 → PRD 输出 → GitHub Issue 创建
+description: 渐进式需求澄清 → PRD → Flow Record（flow_control）
 ---
 
 # flow-requirements
 
-通过采访式对话澄清需求，输出 PRD 文档并创建 GitHub Issue。
+通过渐进式需求澄清将松散想法凝固为 PRD，并用 `flow_control{op:"create-flow"}` 创建 Flow Record（Parent Issue）。
 
-## Prerequisites
-- `/setup` 已完成（gh CLI 可用）
+## 核心理念：战争迷雾（Fog of War）
 
-## Workflow
+需求澄清不是一次性穷举——只定义**前沿**（当前可见的待决策问题），逐个解决，每解决一个迷雾推开一层，直到所有关键决策已定，PRD 自然成形。
 
-### 1. 需求访谈
-按参考文档 `references/interview-guide.md` 进行深度盘问，澄清：
-- 用户故事与业务价值
-- 边界条件
-- 验收标准
-- 技术约束
-- 排除范围（记录到 out-of-scope）
+## Phase A：创建决策映射
 
-### 2. 输出 PRD
-整理为 PRD 文档保存到 `docs/prd/<title>.md`。
+在 `docs/dev/decision-map.md` 创建映射，追踪所有待决策问题（Ticket 含 slug / Blocked by / Status / Type / Question / Answer）。初始只创建 2–4 个前沿 Ticket，不试图穷举。
 
-参考 `_prompts/prd-format` 中的格式要求。
+Ticket 类型：Grilling（与用户对话澄清）/ Research（查文档）/ Prototype（低保真验证）。
 
-### 3. 记录 Out-of-Scope
-将在访谈中明确排除的需求记入 `docs/dev/out-of-scope.md`：
-- 便于后续回顾为什么某些功能不做
-- 避免重复讨论
+## Phase B：渐进式解决
 
-### 4. 创建 Parent GitHub Issue
-```bash
-mkdir -p tmp
-gh issue create \
-  --title "<PRD Title>" \
-  --label "enhancement" \
-  --body-file docs/prd/<title>.md
-```
+- 每次只处理**一个**已解除阻塞的 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：创建 Flow Record
+
+调用 `flow_control{op:"create-flow", title:"<英文功能标题>"}` 创建 Draft Parent Issue（Flow Record）。
+内核负责 slug 派生与校验、Profile 门禁、双 session 检查、legacy 检测——创建动作全部收敛到工具内。
+
+## CONTEXT.md 术语发现
+
+需求澄清中发现的领域术语写入根 `CONTEXT.md`（术语权威）。发现新术语或冲突时暂停提问，用户确认后由 `flow_control` 更新。
 
 ## Output
-- `docs/prd/<title>.md` — PRD 文档
-- `docs/dev/out-of-scope.md` — 排除范围记录
-- GitHub Parent Issue 已创建
+- `docs/dev/decision-map.md` — 决策映射（PRD 生成后可删除）
+- `docs/prd/<title>.md` — PRD
+- Flow Record（Parent Issue，由 flow_control 创建）
 
 ## 下一阶段
-- **/design** — 基于此 PRD 进行技术设计
+- **/design** — 基于 PRD 进行技术设计
 
 ## Contract
 
 ### Trigger
-由 `/requirements` 命令或 `@dev-lifecycle` Phase 0 触发。
+由 `/requirements` 命令或 `@dev-lifecycle` 触发。
 
 ### Inputs
 - 用户提供的功能描述（来自消息文本）
 
 ### Preconditions
-- `/setup` 已完成（gh CLI 可用，docs 目录就绪）
+- `/setup` 已完成（Profile 已确认，gh CLI 可用）
 
 ### Procedure
-1. 按 interview-guide 进行需求访谈
-2. 输出 PRD 到 `docs/prd/<title>.md`
-3. 记录 Out of Scope 到 `docs/dev/out-of-scope.md`
-4. 创建 Parent GitHub Issue
+1. 锚定核心问题，创建 Decision Map
+2. 渐进式解决所有前沿 Ticket（Grilling / Research / Prototype）
+3. 迷雾推至足够远 → 凝固为 PRD
+4. 记录领域术语到 CONTEXT.md
+5. 调用 `flow_control{op:"create-flow"}` 创建 Flow Record
 
 ### Outputs
-- `docs/prd/<title>.md` — PRD 文档
-- `docs/dev/out-of-scope.md` — 排除范围记录
-- GitHub Parent Issue
+- `docs/dev/decision-map.md`
+- `docs/prd/<title>.md`
+- Flow Record（Parent Issue）
 
 ### Failure
-- gh CLI 不可用 → 提示先执行 /setup
+- Profile 未确认 → flow_control 返回 `SETUP_REQUIRED`，提示先执行 `/setup`
 - Issue 创建失败 → 记录错误，不阻塞 PRD 写入
 
 ### Idempotency
-- 如果 PRD 文件已存在 → 更新而非覆盖
-- 如果 Parent Issue 已创建 → 追加评论而非重复创建
+- Decision Map 已存在 → 从中断点继续
+- PRD 文件已存在 → 更新而非覆盖
+- Flow Record 已创建 → 绑定已有 Issue（`parent_issue_number`）而非重复创建
 
 ### Prohibited Actions
-- 不跳过访谈直接输出 PRD
-- 不省略 Out of Scope 记录
+- 不跳过 Phase A 和 Phase B 直接输出 PRD
+- 不一次问多个问题
+- 不绕过 flow_control 手工创建 Issue（由 create-flow 完成）