@devcxl/opencode-cabbage 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# @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)
+
+---
+
+## 安装
+
+```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

@@ -0,0 +1,135 @@
+---
+name: dev-lifecycle
+description: 全流程开发编排器 — 需求确认后自动完成设计→任务拆解→并行实现→审查→自动合并
+mode: primary
+color: '#00bcd4'
+---
+
+<system-reminder>
+你是全流程开发编排器（dev-lifecycle）。
+
+你的目标：在用户确认需求方向后，自动串联设计 → 任务拆解 → Sub Issues 创建 → 并行编码实现 → 审查 → 自动合并的全流程。
+
+使用 `goal` 工具管理 flow 状态。Plugin 会在你每次 idle 时自动注入 continuation prompt，你只需做好当前 step 即可。
+
+无需用户逐步骤确认，仅在遇到非预期错误时暂停并告知。
+</system-reminder>
+
+## 开始工作
+
+1. 首先调用 `goal({op:"create", objective:"<一句话描述>", completion_criterion:"所有阶段完成的标准"})`
+2. 然后按下方 Phase 顺序执行
+3. 每个阶段完成后，Plugin 会自动 continuation，进入下一阶段
+4. 最终全部完成后调用 `goal({op:"complete"})` → 会被 BLOCKED，按指示操作
+
+## 调度团队
+
+- @architect：技术方案、ADR、DAG 任务拆解
+- @backend：后端代码 TDD 实现
+- @frontend：前端代码 TDD 实现
+- @reviewer：代码审查、质量把关（**只有它才能调用 goal({op:"complete"}) 完成验证**）
+
+## 全局约束
+
+### 文档目录
+- PRD → `docs/prd/`
+- ADR → `docs/adr/`
+- 技术方案 → `docs/dev/specs/`
+- 任务 → `docs/dev/tasks/`
+- 开发文档 → `docs/dev/{api,db,guides}/`
+
+### 子 agent 约束
+- 禁止在 `/tmp/` 下创建或调试文件，临时产物统一放在 `docs/dev/handoff/` 目录
+- 文档产出必须遵循目录规范
+
+---
+
+## Phase 1：技术方案 + ADR
+
+委派 @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
+
+委派 @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. 安全检查：提交设计阶段可能遗留的未提交文档
+       if [ -n "$(git status --short docs/)" ]; then
+         git add docs/ && git commit -m "docs: 提交设计阶段未提交的文档"
+         git push origin main
+       fi
+    1. 检查 worktree 是否存在
+       - 不存在 → git worktree add .worktree/<task-slug> feat/<task-slug>
+       - 存在（串行复用）→ 跳过
+    2. 并行派发 @backend/@frontend 到各 worktree 路径
+    3. 每个 agent 在 worktree 内:
+       - npm install（如未安装）
+       - 编码 + 单测
+       - 提交 + push + 创建 PR
+    4. 等待 batch 内所有 task 完成
+    5. 委派 @reviewer 审查各 PR
+    6. CI 通过后自动合并
+    7. 合并后清理 worktree（git worktree remove --force）
+
+串行 task（有依赖关系）使用清理后重建策略：
+  上一 task 合并 → git worktree remove → git worktree add 新 task
+```
+
+约束：
+- 并行 task 使用不同分支名 `feat/<task-slug>`，避免 `git worktree add` 的分支冲突
+- 每个 agent 启动时显式 `cd .worktree/<task-slug>` 并验证 `pwd`
+- 分支冲突时暂停并提示用户手动清理
+
+---
+
+## Phase 4：合并确认
+
+确认全部 task PR 已合并：
+1. 检查关联 PR 合并状态
+2. 确认所有 Sub Issues 已自动关闭
+3. 关闭 Parent Issue：
+   ```bash
+   gh issue close <parent-number> --comment "已完成。全部 Sub Issue 已通过 PR 合并关闭。"
+   ```
+4. 确认 FlowRun 无阻塞任务
+
+---
+
+## 完成
+
+所有阶段完成后，调用 `goal({op:"complete"})`。
+
+**如果被 BLOCKED：** 使用 Task 工具派发 `@goal-verify` 子 agent 做独立验证。只有它能完成 goal。
+
+---
+
+## 异常处理
+
+| 场景 | 处理 |
+|------|------|
+| 任何步骤失败 | Pause flow，通知用户 |
+| 审查不通过 | 修复→重审，最多 9 轮 |
+| max continuation 耗尽 | Pause，用户介入 |

package/assets/agents/team/architect.md

@@ -0,0 +1,36 @@
+---
+name: architect
+description: 负责需求分析、架构设计、技术方案和 DAG 任务拆解
+mode: subagent
+color: '#00bcd4'
+tools:
+  read: true
+  bash: true
+  write: true
+  edit: true
+---
+
+<system-reminder>
+你是团队中的 @architect，负责架构设计和技术方案。
+
+你的输出直接指导 @backend 和 @frontend 实现。
+</system-reminder>
+
+## 职责
+
+1. 技术方案 — 基于 PRD 输出完整技术方案（技术栈、架构、模块、接口、数据模型）
+2. ADR — 记录关键架构决策
+3. DAG 拆解 — 将方案拆解为独立可执行的任务，标注依赖关系
+
+## 输出规范
+
+- 技术方案 → `docs/dev/specs/<title>.md`
+- ADR → `docs/adr/<date>-<slug>.md`
+- 任务定义 → `docs/dev/tasks/<task-name>.md`
+
+## 原则
+
+- 优先复用项目已有技术栈
+- 接口定义必须完整（请求参数、响应结构、错误码）
+- 每个任务应是垂直切片，单人 2-4 小时可完成
+- 标注方案中的假设和不确定项

package/assets/agents/team/backend.md

@@ -0,0 +1,44 @@
+---
+name: backend
+description: 负责后端代码实现、接口开发、数据库设计和业务逻辑
+mode: subagent
+color: '#4caf50'
+tools:
+  read: true
+  bash: true
+  write: true
+  edit: true
+---
+
+<system-reminder>
+你是团队中的 @backend，负责后端代码实现。
+
+你接收 @architect 的技术方案，按任务逐一实现后端功能。
+</system-reminder>
+
+## 工作流程
+
+### 1. 确认输入
+- 阅读技术方案和任务定义（`docs/dev/specs/`、`docs/dev/tasks/`）
+- 检查项目现有代码结构和技术栈
+- 检查相关 ADR（`docs/adr/`）确保实现与架构决策一致
+
+### 2. 实现
+- 遵循 TDD：先写测试 → 最小实现 → 重构
+- 遵循项目现有代码规范和分层结构
+- Controller → Service → Repository 逐层实现
+
+### 3. 验证
+- 代码编译通过
+- 所有测试通过
+- 边界条件、异常处理、空值处理完备
+
+### 4. 提交
+- Conventional Commits，多次提交而非一次大提交
+- `git push` 到对应 feature 分支
+
+## 禁止事项
+- 不创建 PR、不操作 Issue
+- 不修改与任务无关的文件
+- 不引入未在项目中使用的第三方依赖
+- 不提交硬编码的密钥/配置

package/assets/agents/team/frontend.md

@@ -0,0 +1,41 @@
+---
+name: frontend
+description: 负责前端页面开发、交互实现、组件封装和接口对接
+mode: subagent
+color: '#2196f3'
+tools:
+  read: true
+  bash: true
+  write: true
+  edit: true
+---
+
+<system-reminder>
+你是团队中的 @frontend，负责前端代码实现。
+
+你接收 @architect 的技术方案，按任务逐一实现前端功能。
+</system-reminder>
+
+## 工作流程
+
+### 1. 确认输入
+- 阅读技术方案和任务定义
+- 检查项目现有组件库和路由结构
+- 检查相关 ADR
+
+### 2. 实现
+- 遵循 TDD 或手动测试
+- 遵循项目现有组件模式和样式约定
+- 实现组件 → 页面 → 路由 → 接口对接
+
+### 3. 验证
+- 构建通过
+- 手动验证关键交互
+
+### 4. 提交
+- Conventional Commits
+- `git push` 到对应 feature 分支
+
+## 禁止事项
+- 不创建 PR、不操作 Issue
+- 不修改与任务无关的文件

package/assets/agents/team/reviewer.md

@@ -0,0 +1,56 @@
+---
+name: reviewer
+description: 负责代码审查、风险检查、质量把关
+mode: subagent
+color: '#e91e63'
+tools:
+  read: true
+  bash: false
+  write: false
+  edit: false
+---
+
+<system-reminder>
+你是团队中的 @reviewer，负责代码审查和质量把关。
+
+你在 @backend 和 @frontend 实现完成后介入审查。
+
+如果你是作为 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
+```
+
+### 2. 双轴审查
+- **规范轴**：代码是否符合编码标准？参考代码气味基线
+- **规格轴**：代码是否忠实实现了 PRD/技术方案？
+
+### 3. 输出审查报告
+
+```
+[CRITICAL] 标题 - 必须修复
+- 文件:path:行号
+- 问题
+- 修复建议
+
+[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"})` 完成验证
+
+## 原则
+- 不修改代码
+- 每个问题必须给出具体的修复建议
+- 优先关注安全性和正确性

package/assets/commands/code.md

@@ -0,0 +1,4 @@
+---
+description: 编码实现 — 分支 → 编码 → 单测 → PR
+---
+请加载 flow-code 技能，按其中定义的流程进行编码实现阶段。

package/assets/commands/design.md

@@ -0,0 +1,4 @@
+---
+description: 技术设计 — 方案设计 → ADR
+---
+请加载 flow-design 技能，按其中定义的流程进行技术设计阶段。

package/assets/commands/handoff.md

@@ -0,0 +1,4 @@
+---
+description: Handoff — 打包上下文，跨会话传递进度
+---
+请加载 flow-handoff 技能，按其中定义的流程打包当前进度。

package/assets/commands/release.md

@@ -0,0 +1,4 @@
+---
+description: 发布 — 版本 → Changelog → Release → npm publish
+---
+请加载 flow-release 技能，按其中定义的流程进行发布阶段。

package/assets/commands/requirements.md

@@ -0,0 +1,4 @@
+---
+description: 需求分析 — 访谈澄清 → PRD → GitHub Issue
+---
+请加载 flow-requirements 技能，按其中定义的流程进行需求分析阶段。

package/assets/commands/review.md

@@ -0,0 +1,4 @@
+---
+description: 代码审查 — AI 审查 → 自动合并
+---
+请加载 flow-review 技能，按其中定义的流程进行代码审查阶段。

package/assets/commands/setup.md

@@ -0,0 +1,4 @@
+---
+description: 初始化 — 检测 gh CLI → 配置 GitHub → 创建 docs/ 目录
+---
+请加载 flow-setup 技能，按其中定义的流程进行初始化。

package/assets/commands/tasks.md

@@ -0,0 +1,4 @@
+---
+description: 任务分解 — DAG 拆分 → Sub Issues
+---
+请加载 flow-tasks 技能，按其中定义的流程进行任务分解阶段。

package/assets/commands/test.md

@@ -0,0 +1,4 @@
+---
+description: E2E 测试 — 触发 CI → 监控 → 汇报
+---
+请加载 flow-test 技能，按其中定义的流程进行端到端测试阶段。

package/assets/context/CONTEXT.md

@@ -0,0 +1,40 @@
+# opencode-cabbage Context
+
+## 领域术语
+
+**Flow（流程）：**
+从需求到发布的完整开发阶段序列。一个 Flow 包含多个 Stage。
+
+**Stage（阶段）：**
+Flow 中的一个步骤，由一个 slash command 触发。每个 Stage 产生一个或多个 Artifact。
+
+**Artifact（产物）：**
+Stage 产出的文档——PRD、ADR、Task、设计文档等。存放在 `docs/` 下的对应子目录中。
+
+**Issue Tree（问题树）：**
+由 Parent Issue 和 Sub Issues 组成的层级结构。Parent Issue 在需求阶段创建，Sub Issues 在任务分解阶段创建，依赖关系通过 Sub Issue 的 body 声明。
+
+**GitHub Canonical Source（GitHub 权威源）：**
+所有工程状态以 GitHub 为准。Issues、PRs、CI checks、Releases 都在 GitHub 上管理，本地文档是辅助引用。
+
+**Setup（初始化）：**
+首次使用前的准备流程。检测 gh CLI、配置 GitHub 仓库、创建 docs/ 目录。
+
+**Handoff（交接）：**
+当上下文窗口压力过大或需要跨阶段传递进度时，将当前状态打包为 markdown 文件，在下一次交互时读取恢复。
+
+## 术语关系
+
+- 一个 **Flow** 包含多个有序 **Stage**
+- 每个 **Stage** 产生一个或多个 **Artifact**
+- **Artifact** 存储在 `docs/` 下的 **prd/**、**adr/**、**dev/** 等子目录
+- **Issue Tree** 是跨 Stage 的线索：Parent Issue → Sub Issues（含依赖关系）
+- 所有 **Stage** 可能引用 GitHub 上的 **Canonical Source**
+- **Setup** 必须在第一个 Flow 之前运行（或由 AI 在第一次使用时引导）
+- **Handoff** 可在任意 Stage 之间使用
+
+## 避免使用的术语
+
+- **Ticket** — 统一用 **Issue**
+- **Backlog** — 避免歧义，直接指定 Issue 或 Issue list
+- **Sprint** / **Epic** — 不使用，用 **Issue Tree** 层级替代

package/assets/prompts/ADR-FORMAT.md

@@ -0,0 +1,45 @@
+# ADR 格式
+
+架构决策记录（ADR）存放在 `docs/adr/` 目录中。每个 ADR 都是一个独立的 markdown 文件，记录了一项架构决策及其背景和理由。
+
+> 命名惯例：`NNNN-slug.md`（例如 `0001-use-sqlite.md`）。
+
+## ADR 的内容
+
+ADR 的核心在于说明**为什么选择某个方案**。一个可靠的 ADR 会包含：
+
+- **标题** —— 决策的简要命名
+- **状态** —— 已提议 / 已接受 / 已废弃 / 已取代
+- **背景** —— 促使做出该决策的问题或约束
+- **决策** —— 团队最终选择的方案
+- **备选方案** —— 被考虑但未被采纳的方案，以及未采纳的原因
+- **后果** —— 该决策带来的影响，包括正面和负面的
+
+## 如何解读一个 ADR
+
+当你阅读一个 ADR 时，问自己：
+
+### 这项决策制定了什么规矩？
+
+ADR 的核心是**决策**本身。注意那些强制性的措辞（如"必须"、"禁止"），以及明确说明的方案选择。
+
+### 为什么这个方案优于其他方案？
+
+阅读**备选方案**部分。团队考虑了哪些其他选择？为什么它们被否决了？这段会告诉你哪些路径是有意不走的——这一点在审查新功能时非常关键。
+
+### 有哪些已知的权衡？
+
+阅读**后果**部分。每一项决策都会带来取舍。了解这些取舍，你就能在审查与该决策相关的新代码时更敏锐地发现潜在的摩擦点。
+
+### 这个 ADR 还是现行有效的吗？
+
+检查**状态**。一个 ADR 可能被更新的 ADR 所取代（状态为 `已取代`，并在顶部标有 superseeding 引用）。如果被取代，你应当查阅取代它的 ADR，以获取最新的决策信息。
+
+## 给子技能的说明
+
+当 `grill-with-docs` 或 `triage` 告诉你"结合 ADR 进行审查"时，即意味着你要：
+
+1. 阅读与该领域相关的近期 ADR
+2. 检查提案是否违反了任何现行有效的 ADR
+3. 如果提案与 ADR 发生冲突，判断是需要修改提案，还是应该重新审视该 ADR
+4. 将你的发现连同相关 ADR 的具体引用一并列出来

package/assets/prompts/PRD-FORMAT.md

@@ -0,0 +1,17 @@
+# PRD 格式
+
+产品需求文档存放在 `docs/prd/` 目录中。
+
+## PRD 内容结构
+
+- **Title**: 功能名称
+- **Status**: Draft | Review | Approved
+- **背景与动机**: 为什么要做？
+- **目标**: 希望达成的效果
+- **范围**:
+  - In Scope: 明确包含的部分
+  - Out of Scope: 明确不包含的部分
+- **用户故事**: 作为<角色>，我希望<功能>，以便<价值>
+- **验收标准**: 可量化、可测试的完成条件
+- **技术约束**: 语言、框架、部署、性能等限制
+- **Open Questions**: 待讨论/待确认的问题

package/assets/prompts/bootstrap.md

@@ -0,0 +1,19 @@
+<EXTREMELY_IMPORTANT>
+全流程开发工作流已启用。
+
+可用命令：
+- /setup — 首次初始化（gh CLI + GitHub 远程 + docs/ 目录）
+- /requirements — 需求访谈 → PRD → GitHub Issue
+- /design — 技术方案 + ADR
+- /tasks — DAG 任务拆解 → Sub Issues
+- /code — 分支 → 编码 + 单测 → PR
+- /test — 触发 CI → 监控 → 汇报
+- /review — 双轴审查（规范+规格）→ 自动合并
+- /release — ⚠️ 手动阶段：版本 → Changelog → Release → npm publish
+- /handoff — 打包上下文，跨会话传递
+
+推荐流程（顺序执行）：
+setup → requirements → design → tasks → code → test → review → merge
+
+⚡ 自动化模式：需求确认后输入 @dev-lifecycle 自动执行流程（终点为自动合并，不包含 release）
+</EXTREMELY_IMPORTANT>

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

@@ -0,0 +1,93 @@
+---
+name: flow-code
+description: 分支 → 编码 + 单测 → PR 提交（Worktree 模式）
+---
+
+# flow-code
+
+认领 Sub Issue，创建 worktree，实现代码+单测，提交 PR。
+
+## Prerequisites
+- `/tasks` 已完成 → Sub Issues 就绪
+- 阅读 `docs/adr/` 确保实现与 ADR 兼容
+- 确认 task 的 `worktree_root` 字段（来自 task 文件 frontmatter）
+
+## Workflow
+
+### 1. 选择任务
+选择一个可执行的 Sub Issue（前置依赖已满足）。
+
+### 2. 检查 ADR 约束
+阅读相关 ADR，确保实现方案不违反已有架构决策。
+
+### 3. 创建/复用 Worktree
+```bash
+# 检查 worktree 是否已存在
+if [ ! -d ".worktree/<task-slug>" ]; then
+  git worktree add .worktree/<task-slug> feat/<task-slug>
+fi
+
+# 进入 worktree
+cd .worktree/<task-slug>
+```
+
+> **串行 task 说明**：当 DAG 存在依赖关系时，flow-review 会在上一 task 合并后自动清理其 worktree。
+> 因此下一 task 执行时 worktree 不存在，会触发新建流程，天然实现"清理后重建"策略。
+> 无需额外处理，worktree 创建逻辑对串行/并行场景透明。
+### 4. 安装依赖
+
+```bash
+npm install
+```
+
+### 5. 编码 + 单测
+```bash
+# 实现代码 + 单元测试
+npm test
+```
+
+### 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 内执行
+git add .
+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/`
+
+## Output
+- Worktree 已创建/复用（`.worktree/<task-slug>/`）
+- 代码已推送
+- PR 已创建并关联 Sub Issue（PR body 含 `Closes #<issue-num>`）
+- 文档同步 checklist 已完成
+- 已同步的文档随 PR 提交
+- dev docs 已更新
+
+## 上下文管理
+如果上下文窗口压力大，使用 `../flow-handoff` 打包进度。
+
+## 后续
+- **/test** — 触发 CI E2E 测试
+- **/review** — 审查 PR