@devcxl/opencode-cabbage 0.1.0 → 0.2.1

package/README.md

@@ -1,14 +1,17 @@
-# @devcxl/opencode-cabbage
-
-全流程开发 OpenCode 插件 — 覆盖需求→设计→任务→编码→测试→审查→发布完整开发生命周期，支持自动编排与并行 Subagent。
-
-[![npm version](https://img.shields.io/npm/v/@devcxl/opencode-cabbage)](https://www.npmjs.com/package/@devcxl/opencode-cabbage)
-[![CI](https://github.com/devcxl/opencode-cabbage/actions/workflows/ci.yml/badge.svg)](https://github.com/devcxl/opencode-cabbage/actions/workflows/ci.yml)
-[![GitHub Pages](https://github.com/devcxl/opencode-cabbage/actions/workflows/pages.yml/badge.svg)](https://devcxl.github.io/opencode-cabbage)
+<div align="center">
+  <h1>@devcxl/opencode-cabbage</h1>
+  <p>A full-lifecycle development plugin for OpenCode, covering requirements, design, tasks, coding, testing, review, and release with automated orchestration and parallel subagents.</p>
+  <p>
+    <a href="https://www.npmjs.com/package/@devcxl/opencode-cabbage"><img src="https://img.shields.io/npm/v/@devcxl/opencode-cabbage" alt="npm version"></a>
+    <a href="https://github.com/devcxl/opencode-cabbage/actions/workflows/ci.yml"><img src="https://github.com/devcxl/opencode-cabbage/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+    <a href="https://devcxl.github.io/opencode-cabbage"><img src="https://github.com/devcxl/opencode-cabbage/actions/workflows/pages.yml/badge.svg?branch=main" alt="GitHub Pages"></a>
+  </p>
+  <p>English | <a href="README.zh.md">简体中文</a></p>
+</div>
 
 ---
 
-## 安装
+## Installation
 
 ```json
 // opencode.json
@@ -17,72 +20,72 @@
 }
 ```
 
-插件启动后自动注入 9 个 slash command、9 个 flow skill、5 个 agent。
+Once started, the plugin automatically injects 9 slash commands, 9 flow skills, and 5 agents.
 
-## 命令一览
+## Command Overview
 
-| 命令 | 阶段 | 产出 |
-|------|------|------|
-| `/setup` | 初始化 | docs/ 目录结构、环境验证 |
-| `/requirements` | 需求 | PRD → `docs/prd/` + GitHub Issue |
-| `/design` | 设计 | 技术方案 + ADR → `docs/dev/specs/` + `docs/adr/` |
-| `/tasks` | 任务拆解 | DAG 任务 + Sub Issues → `docs/dev/tasks/` |
-| `/code` | 编码 | 分支 + 代码 + 单测 + PR |
-| `/test` | 测试 | 触发 CI + 监控 + 汇报 |
-| `/review` | 审查 | 双轴审查 + 自动合并 |
-| `/release` | ⚠️ 手动发布 | 版本 → Changelog → Release → npm publish |
-| `/handoff` | 交接 | 打包上下文，跨会话传递 |
+| Command | Stage | Output |
+|---------|-------|--------|
+| `/setup` | Setup | `docs/` directory structure and environment validation |
+| `/requirements` | Requirements | PRD → `docs/prd/` + GitHub Issue |
+| `/design` | Design | Technical specification + ADR → `docs/dev/specs/` + `docs/adr/` |
+| `/tasks` | Task decomposition | DAG tasks + Sub Issues → `docs/dev/tasks/` |
+| `/code` | Coding | Branch + code + unit tests + PR |
+| `/test` | Testing | Trigger CI + monitor + report |
+| `/review` | Review | Dual-axis review + automatic merge |
+| `/release` | ⚠️ Manual release | Version → Changelog → Release → npm publish |
+| `/handoff` | Handoff | Package context for transfer across sessions |
 
-## 快速开始
+## Quick Start
 
 ```bash
-# 1. 安装
+# 1. Install
 npm install @devcxl/opencode-cabbage
 
-# 2. 在 opencode.json 中添加
+# 2. Add the plugin to opencode.json
 # { "plugin": ["@devcxl/opencode-cabbage"] }
 
-# 3. 在 OpenCode 中执行
+# 3. Run in OpenCode
 # /setup → /requirements → @dev-lifecycle
 ```
 
-## 两种模式
+## Two Modes
 
-- **手动模式** — 按顺序逐一执行命令，适合精细控制
-- **自动模式** — 需求确认后输入 `@dev-lifecycle`，全自动完成剩余流程
+- **Manual mode** — Run each command sequentially for fine-grained control
+- **Automatic mode** — Once the requirements are confirmed, enter `@dev-lifecycle` to automatically complete the remaining workflow
 
-## 架构
+## Architecture
 
 ```
-src/                          # TypeScript 薄层
-├── index.ts                  # 插件入口
-├── plugin.ts                 # 包路径解析
+src/                          # Thin TypeScript layer
+├── index.ts                  # Plugin entry point
+├── plugin.ts                 # Package root resolution
 └── plugin/
-    ├── server.ts             # 主工厂：注入 skills/commands/agents
-    ├── commands.ts           # Command 加载器
-    ├── skills.ts             # Skill 加载器
-    ├── prompts.ts            # Prompt 加载器
-    ├── bootstrap.ts          # 启动引导
-    └── agents.ts             # Agent 注入
-
-assets/                       # 运行时资源
-├── commands/                 # 9 个 slash command
-├── skills/                   # 9 个 flow-* skill
-├── agents/                   # 5 个 agent 定义
-├── context/                  # 领域词汇表
-└── prompts/                  # 引导提示词 + 模板
+    ├── server.ts             # Main factory: injects skills, commands, and agents
+    ├── commands.ts           # Command loader
+    ├── skills.ts             # Skill loader
+    ├── prompts.ts            # Prompt loader
+    ├── bootstrap.ts          # Startup guidance
+    └── agents.ts             # Agent injection
+
+assets/                       # Runtime assets
+├── commands/                 # 9 slash commands
+├── skills/                   # 9 flow-* skills
+├── agents/                   # 5 agent definitions
+├── context/                  # Domain glossary
+└── prompts/                  # Guidance prompts and templates
 ```
 
-## 文档
+## Documentation
 
-| 文档 | 链接 |
-|------|------|
-| 快速开始 | [docs/guides/quickstart.md](docs/guides/quickstart.md) |
-| 配置指南 | [docs/guides/configuration.md](docs/guides/configuration.md) |
-| 使用指南 | [docs/guides/usage.md](docs/guides/usage.md) |
-| 架构概览 | [docs/guides/architecture.md](docs/guides/architecture.md) |
-| 贡献指南 | [docs/dev/guides/contributing.md](docs/dev/guides/contributing.md) |
+| Document | Link |
+|----------|------|
+| Quick Start | [docs/guides/quickstart.md](docs/guides/quickstart.md) |
+| Configuration Guide | [docs/guides/configuration.md](docs/guides/configuration.md) |
+| Usage Guide | [docs/guides/usage.md](docs/guides/usage.md) |
+| Architecture Overview | [docs/guides/architecture.md](docs/guides/architecture.md) |
+| Contributing Guide | [docs/dev/guides/contributing.md](docs/dev/guides/contributing.md) |
 
-## 许可
+## License
 
 MIT

package/README.zh.md

@@ -0,0 +1,91 @@
+<div align="center">
+  <h1>@devcxl/opencode-cabbage</h1>
+  <p>全流程开发 OpenCode 插件 — 覆盖需求、设计、任务、编码、测试、审查和发布完整开发生命周期，支持自动编排与并行 Subagent。</p>
+  <p>
+    <a href="https://www.npmjs.com/package/@devcxl/opencode-cabbage"><img src="https://img.shields.io/npm/v/@devcxl/opencode-cabbage" alt="npm version"></a>
+    <a href="https://github.com/devcxl/opencode-cabbage/actions/workflows/ci.yml"><img src="https://github.com/devcxl/opencode-cabbage/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+    <a href="https://devcxl.github.io/opencode-cabbage"><img src="https://github.com/devcxl/opencode-cabbage/actions/workflows/pages.yml/badge.svg?branch=main" alt="GitHub Pages"></a>
+  </p>
+  <p><a href="README.md">English</a> | 简体中文</p>
+</div>
+
+---
+
+## 安装
+
+```json
+// opencode.json
+{
+  "plugin": ["@devcxl/opencode-cabbage"]
+}
+```
+
+插件启动后自动注入 9 个 slash command、9 个 flow skill、5 个 agent。
+
+## 命令一览
+
+| 命令 | 阶段 | 产出 |
+|------|------|------|
+| `/setup` | 初始化 | `docs/` 目录结构、环境验证 |
+| `/requirements` | 需求 | PRD → `docs/prd/` + GitHub Issue |
+| `/design` | 设计 | 技术方案 + ADR → `docs/dev/specs/` + `docs/adr/` |
+| `/tasks` | 任务拆解 | DAG 任务 + Sub Issues → `docs/dev/tasks/` |
+| `/code` | 编码 | 分支 + 代码 + 单测 + PR |
+| `/test` | 测试 | 触发 CI + 监控 + 汇报 |
+| `/review` | 审查 | 双轴审查 + 自动合并 |
+| `/release` | ⚠️ 手动发布 | 版本 → Changelog → Release → npm publish |
+| `/handoff` | 交接 | 打包上下文，跨会话传递 |
+
+## 快速开始
+
+```bash
+# 1. 安装
+npm install @devcxl/opencode-cabbage
+
+# 2. 在 opencode.json 中添加
+# { "plugin": ["@devcxl/opencode-cabbage"] }
+
+# 3. 在 OpenCode 中执行
+# /setup → /requirements → @dev-lifecycle
+```
+
+## 两种模式
+
+- **手动模式** — 按顺序逐一执行命令，适合精细控制
+- **自动模式** — 需求确认后输入 `@dev-lifecycle`，全自动完成剩余流程
+
+## 架构
+
+```
+src/                          # TypeScript 薄层
+├── index.ts                  # 插件入口
+├── plugin.ts                 # 包路径解析
+└── plugin/
+    ├── server.ts             # 主工厂：注入 skills/commands/agents
+    ├── commands.ts           # Command 加载器
+    ├── skills.ts             # Skill 加载器
+    ├── prompts.ts            # Prompt 加载器
+    ├── bootstrap.ts          # 启动引导
+    └── agents.ts             # Agent 注入
+
+assets/                       # 运行时资源
+├── commands/                 # 9 个 slash command
+├── skills/                   # 9 个 flow-* skill
+├── agents/                   # 5 个 agent 定义
+├── context/                  # 领域词汇表
+└── prompts/                  # 引导提示词 + 模板
+```
+
+## 文档
+
+| 文档 | 链接 |
+|------|------|
+| 快速开始 | [docs/guides/quickstart.md](docs/guides/quickstart.md) |
+| 配置指南 | [docs/guides/configuration.md](docs/guides/configuration.md) |
+| 使用指南 | [docs/guides/usage.md](docs/guides/usage.md) |
+| 架构概览 | [docs/guides/architecture.md](docs/guides/architecture.md) |
+| 贡献指南 | [docs/dev/guides/contributing.md](docs/dev/guides/contributing.md) |
+
+## 许可
+
+MIT

package/assets/agents/dev-lifecycle.md

@@ -20,14 +20,15 @@ color: '#00bcd4'
 1. 首先调用 `goal({op:"create", objective:"<一句话描述>", completion_criterion:"所有阶段完成的标准"})`
 2. 然后按下方 Phase 顺序执行
 3. 每个阶段完成后，Plugin 会自动 continuation，进入下一阶段
-4. 最终全部完成后调用 `goal({op:"complete"})` → 会被 BLOCKED，按指示操作
+4. 最终全部完成后，直接使用 Task 工具派发 `@goal-verify` 做独立验证
 
 ## 调度团队
 
 - @architect：技术方案、ADR、DAG 任务拆解
-- @backend：后端代码 TDD 实现
-- @frontend：前端代码 TDD 实现
-- @reviewer：代码审查、质量把关（**只有它才能调用 goal({op:"complete"}) 完成验证**）
+- @backend：后端代码 TDD 实现（编码 + 测试 + commit + push，不创建 PR）
+- @frontend：前端代码 TDD 实现（编码 + 测试 + commit + push，不创建 PR）
+- @reviewer：只读代码审查，输出结构化审查报告（不操作 git/GitHub，不写文件）
+- @goal-verify：独立验证 Goal 完成状态（**只有它可以调用 goal({op:"complete"})**）
 
 ## 全局约束
 
@@ -77,22 +78,28 @@ color: '#00bcd4'
 For each batch:
   For each task in batch (可并行):
     0. 安全检查：提交设计阶段可能遗留的未提交文档
+       BASE=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
        if [ -n "$(git status --short docs/)" ]; then
          git add docs/ && git commit -m "docs: 提交设计阶段未提交的文档"
-         git push origin main
+         git push origin $BASE
        fi
     1. 检查 worktree 是否存在
-       - 不存在 → git worktree add .worktree/<task-slug> feat/<task-slug>
-       - 存在（串行复用）→ 跳过
+       - 不存在 → git worktree add -b feat/<task-slug> .worktree/<task-slug> $BASE
+       - 存在 → 验证分支一致，一致则复用，不一致则报错
     2. 并行派发 @backend/@frontend 到各 worktree 路径
-    3. 每个 agent 在 worktree 内:
+    3. 每个 agent 在 worktree 内（不创建 PR）:
        - npm install（如未安装）
        - 编码 + 单测
-       - 提交 + push + 创建 PR
-    4. 等待 batch 内所有 task 完成
-    5. 委派 @reviewer 审查各 PR
-    6. CI 通过后自动合并
-    7. 合并后清理 worktree（git worktree remove --force）
+       - commit + push
+       - 返回 branch、commit、test result
+    4. 编排器（你）为每个完成的 task 创建 PR：
+       gh pr create --title "<title>" --body "Closes #<issue-num>"
+    5. 等待 batch 内所有 PR 就绪
+    6. 委派 @reviewer 审查各 PR，接收结构化审查报告
+    7. 编排器发布审查结果：
+       gh pr review <pr-number> --approve|--request-changes --body "<报告>"
+    8. CI 通过后合并 PR
+    9. 合并后清理 worktree
 
 串行 task（有依赖关系）使用清理后重建策略：
   上一 task 合并 → git worktree remove → git worktree add 新 task
@@ -102,6 +109,7 @@ For each batch:
 - 并行 task 使用不同分支名 `feat/<task-slug>`，避免 `git worktree add` 的分支冲突
 - 每个 agent 启动时显式 `cd .worktree/<task-slug>` 并验证 `pwd`
 - 分支冲突时暂停并提示用户手动清理
+- @backend / @frontend 不创建 PR、不操作 Issue — 编排器负责所有 GitHub 操作
 
 ---
 
@@ -120,9 +128,9 @@ For each batch:
 
 ## 完成
 
-所有阶段完成后，调用 `goal({op:"complete"})`。
+所有阶段完成后，直接使用 Task 工具派发 `@goal-verify` 子 agent 做独立验证。
 
-**如果被 BLOCKED：** 使用 Task 工具派发 `@goal-verify` 子 agent 做独立验证。只有它能完成 goal。
+无需先调用 `goal({op:"complete"})`。主会话不能自行完成 Goal，只有 goal-verify 验证通过后可以完成。
 
 ---
 

package/assets/agents/team/backend.md

@@ -8,6 +8,14 @@ tools:
   bash: true
   write: true
   edit: true
+capabilities:
+  create_pr: false
+  merge_pr: false
+  modify_files: true
+  run_tests: true
+  push_branch: true
+  approve_review: false
+  complete_goal: false
 ---
 
 <system-reminder>

package/assets/agents/team/frontend.md

@@ -8,6 +8,14 @@ tools:
   bash: true
   write: true
   edit: true
+capabilities:
+  create_pr: false
+  merge_pr: false
+  modify_files: true
+  run_tests: true
+  push_branch: true
+  approve_review: false
+  complete_goal: false
 ---
 
 <system-reminder>

package/assets/agents/team/reviewer.md

@@ -8,35 +8,47 @@ tools:
   bash: false
   write: false
   edit: false
+capabilities:
+  create_pr: false
+  merge_pr: false
+  modify_files: false
+  run_tests: false
+  push_branch: false
+  approve_review: false
+  complete_goal: false
 ---
 
 <system-reminder>
 你是团队中的 @reviewer，负责代码审查和质量把关。
 
-你在 @backend 和 @frontend 实现完成后介入审查。
+你是一个**只读**审查者：
+- 你可以读取代码、PR diff、文档和规格
+- 你**不执行** git push、gh pr merge、gh pr review、gh pr close
+- 你**不写**任何文件
+- 你**不调用** goal({op:"complete"}) — 只有 goal-verify 可以完成 Goal
 
-如果你是作为 goal-verify 子 agent 被调用：
-1. 先调用 `goal({op:"get"})` 获取目标
-2. 然后按下方流程审查
-3. 如果全部通过，调用 `goal({op:"complete"})` 完成验证
-4. 只有你可以调用 complete，主 agent 被 BLOCKED
+你的职责是输出结构化审查报告，由编排器使用你的报告执行后续操作。
 </system-reminder>
 
 ## 审查流程
 
 ### 1. 获取变更
-```bash
-gh pr diff <pr-number>
-gh pr view <pr-number> --json title,body,files
-```
+查阅 PR diff 和元数据，了解变更范围。
 
 ### 2. 双轴审查
 - **规范轴**：代码是否符合编码标准？参考代码气味基线
 - **规格轴**：代码是否忠实实现了 PRD/技术方案？
 
 ### 3. 输出审查报告
+以结构化文本返回审查结论：
 
 ```
+## 审查结论: APPROVED | CHANGES_REQUESTED
+
+### 审查摘要
+...
+
+### 发现
 [CRITICAL] 标题 - 必须修复
 - 文件:path:行号
 - 问题
@@ -44,11 +56,15 @@ gh pr view <pr-number> --json title,body,files
 
 [HIGH] 标题 - 应该修复
 [MEDIUM] 标题 - 建议修复
+
+### 规范轴
+...
+
+### 规格轴
+...
 ```
 
-### 4. 审查结论
-- Critical/High 存在 → 先将审查报告写入 `docs/dev/handoff/review-report.md`，然后 `gh pr review <pr-number> --request-changes --body-file docs/dev/handoff/review-report.md`，**不可调 goal({op:"complete"})**
-- 无 Critical/High → 写入 `docs/dev/handoff/review-report.md` 后 `gh pr review <pr-number> --approve --body-file docs/dev/handoff/review-report.md`，然后调 `goal({op:"complete"})` 完成验证
+编排器将使用此报告执行 gh pr review。
 
 ## 原则
 - 不修改代码

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

@@ -22,18 +22,39 @@ description: 分支 → 编码 + 单测 → PR 提交（Worktree 模式）
 
 ### 3. 创建/复用 Worktree
 ```bash
-# 检查 worktree 是否已存在
-if [ ! -d ".worktree/<task-slug>" ]; then
-  git worktree add .worktree/<task-slug> feat/<task-slug>
+# 探测默认分支
+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/<task-slug>
+cd "$WORKTREE"
 ```
-
-> **串行 task 说明**：当 DAG 存在依赖关系时，flow-review 会在上一 task 合并后自动清理其 worktree。
-> 因此下一 task 执行时 worktree 不存在，会触发新建流程，天然实现"清理后重建"策略。
-> 无需额外处理，worktree 创建逻辑对串行/并行场景透明。
 ### 4. 安装依赖
 
 ```bash
@@ -65,7 +86,18 @@ npm test
 ### 7. 提交 PR
 ```bash
 # 在 worktree 内执行
-git add .
+
+# 根据 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
@@ -91,3 +123,40 @@ gh pr create --title "<title>" --body-file docs/dev/handoff/pr-body.md
 ## 后续
 - **/test** — 触发 CI E2E 测试
 - **/review** — 审查 PR
+
+## Contract
+
+### Trigger
+由 `/code` 命令或 `@dev-lifecycle` Phase 3 触发。
+
+### Inputs
+- Sub Issue 编号（来源：`/tasks` 产出）
+- task 文件 frontmatter 中的 `worktree_root`（来源：task 文件）
+
+### Preconditions
+- `/tasks` 已完成 → Sub Issues 就绪
+- 前置依赖任务已合并
+
+### Procedure
+1. 选择依赖已满足的 Sub Issue
+2. 创建或复用 Worktree（`git worktree add -b`）
+3. 安装依赖 → 编码 + 单测 → commit + push
+4. 编排器创建 PR
+
+### Outputs
+- Worktree 已创建（`.worktree/<task-slug>/`）
+- 代码已推送
+- PR 已创建（Orchestrator 执行）
+
+### Failure
+- Worktree 创建失败 → 检查分支冲突或目录残留
+- 测试失败 → 修复后重试
+
+### Idempotency
+- Worktree 已存在 → 复用
+- 代码已提交 → 追加提交
+
+### Prohibited Actions
+- Worker 不创建 PR、不操作 Issue
+- 不使用 `git add .`
+- 不直接 push 到默认分支

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

@@ -9,7 +9,7 @@ description: 技术方案设计 → 方案文档 + ADR 输出
 
 ## Prerequisites
 - `/requirements` 已完成 → `docs/prd/<title>.md` + Parent Issue 存在
-- 阅读 `../CONTEXT.md` 了解领域术语
+- 阅读 `../_context/CONTEXT.md` 了解领域术语
 
 ## Workflow
 
@@ -27,7 +27,7 @@ description: 技术方案设计 → 方案文档 + ADR 输出
 
 ### 3. 记录 ADR
 为每个关键决策记录 ADR 到 `docs/adr/<YYYY-MM-DD>-<slug>.md`。
-ADR 格式参考 `../_prompts/adr-format`。
+ADR 格式参考 `_prompts/adr-format` 中的格式要求。
 
 ADR 至少记录：
 - 技术选型决策
@@ -51,20 +51,69 @@ EOF
 gh issue comment <issue-number> --body-file docs/dev/handoff/design-comment.md
 ```
 
-### 5. 提交文档
-设计文档和 ADR 是设计阶段产物，直接提交到 main，确保后续 worktree 创建时能读取：
+### 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 main
+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
 ```
 
 ## Output
 - `docs/dev/specs/<title>.md` — 技术方案
 - `docs/adr/<date>-<slug>.md` — ADR 决议
 - Parent Issue 收到设计评论
-- 文档已提交到 main
+- 文档通过 Planning PR 合入默认分支
 
 ## 后续
 - **/tasks** — 基于设计方案拆解为 DAG 任务
+
+## Contract
+
+### Trigger
+由 `/design` 命令或 `@dev-lifecycle` Phase 1 触发。
+
+### Inputs
+- `docs/prd/<title>.md` — 上游 PRD（来源：requirements 阶段产出）
+- Parent Issue 编号（来源：Goal metadata 或 `/requirements` 阶段产出）
+
+### Preconditions
+- `/requirements` 已完成 → `docs/prd/<title>.md` 存在
+- Parent Issue 存在
+
+### 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 提交文档
+
+### Outputs
+- `docs/dev/specs/<title>.md` — 技术方案
+- `docs/adr/<date>-<slug>.md` — ADR 决议
+
+### Failure
+- ADR 与已有决策冲突 → 记录冲突并标注
+- Planning PR 合并失败 → 通知用户手动处理
+
+### Idempotency
+- 技术方案已存在 → 读取并更新
+- ADR 已存在 → 不重复创建
+
+### Prohibited Actions
+- 不直接 push 到默认分支
+- 不跳过 ADR 兼容性检查

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

@@ -45,3 +45,32 @@ description: 打包上下文，跨会话传递进度
 
 ## Output
 - `docs/dev/handoff-<date>.md`
+
+## Contract
+
+### Trigger
+由 `/handoff` 命令触发。上下文窗口接近极限或需跨会话传递进度时使用。
+
+### Inputs
+- 当前 Goal 状态（来源：Goal metadata）
+
+### Preconditions
+- 存在 Active Goal
+
+### Procedure
+1. 打包当前流程状态（阶段、任务、进度）
+2. 列出已完成和待完成项
+3. 确定下一步骤
+4. 保存到 handoff 文件
+
+### Outputs
+- `docs/dev/handoff-<date>.md` — 交接文件
+
+### Failure
+- 无 Goal → 仅输出当前会话摘要
+
+### Idempotency
+- 同一天多次执行 → 覆盖前一次 handoff
+
+### Prohibited Actions
+- 不修改代码或文档