@jahanxu/trellis 0.4.2 → 0.5.1

package/dist/templates/claude/commands/trellis/handoff.md

@@ -1,445 +1,148 @@
-# Handoff - 完成任务并生成交接文档
+# Handoff - Complete Task and Add to Pool
 
-完成当前任务，AI自动生成 HANDOFF.md 交接文档，并将产出加入任务池供下游消费。
+Complete the current task, generate a HANDOFF.md document, and add the deliverable to the appropriate pool.
 
 ---
 
-## 使用场景
+## Prerequisites
 
-| 角色 | 何时使用 | 产出去向 |
-|------|---------|---------|
-| **PM** | 完成 PRD 编写 | → requirements 池 |
-| **Designer** | 完成原型代码 | → prototypes 池 |
-| **Frontend** | 完成生产代码 | → implementations 池 |
+- Must have a current task set (`.trellis/.current-task`)
+- Task must have deliverable files in the output directory
 
 ---
 
-## 执行流程
+## Process `[AI]`
 
-### Step 1: 检查当前任务状态
+### Step 1: Read Current Task
 
 ```bash
-python3 .trellis/scripts/get_context.py
+python3 ./.trellis/scripts/get_context.py
 ```
 
-**验证点**：
-- ✅ 当前任务已设置（`.trellis/.current-task`）
-- ✅ 任务目录存在
-- ✅ `task.json` 包含 `role` 字段
+Read the task's `task.json` to get:
+- `output_dir`: where deliverables are stored
+- `role`: which role completed this task
+- `title`: task title
+- `slug`: task slug / deliverable ID
 
-**如果验证失败**：
-```
-如果没有当前任务：
-  → 先执行: python3 .trellis/scripts/task.py start <task-dir>
-
-如果没有 role 字段：
-  → 先执行: python3 .trellis/scripts/task.py set-role <task-dir> <pm|designer|frontend>
-```
+If no current task is set, inform the user and stop.
 
----
+### Step 2: Check Deliverables
 
-### Step 2: 读取任务配置
+Verify that the output directory exists and contains files:
 
 ```bash
-cat .trellis/.current-task
-# 输出任务目录，例如：.trellis/tasks/01-21-user-login
-```
-
-基于当前任务目录，读取：
-- `task.json` - 获取 role, id, title 等元数据
-- `source.json` - （Designer/Frontend）获取上游产出引用
-- `prd.md` - （所有角色）获取需求文档
-
----
-
-### Step 3: 确定产出目录
-
-**读取项目配置**：
-
-```python
-# 使用配置化路径（框架层与业务层分离）
-python3 -c "
-import sys
-from pathlib import Path
-sys.path.insert(0, str(Path('.trellis/scripts/common')))
-from project_paths import get_output_dir_for_task, get_repo_root
-
-repo_root = get_repo_root()
-role = '<role>'  # 从 task.json 读取
-task_id = '<task-id>'  # 从 task.json 读取
-
-output_dir = get_output_dir_for_task(repo_root, role, task_id)
-print(output_dir)
-"
+ls -la <output_dir>/
 ```
 
-**默认路径映射**（如果 `.trellis/paths.yaml` 不存在）：
-
-| Role | 默认产出目录 | 示例 |
-|------|-------------|------|
-| `pm` | `deliverables/requirements/{task-id}/` | `deliverables/requirements/user-login/` |
-| `designer` | `deliverables/prototypes/{task-id}/` | `deliverables/prototypes/user-login/` |
-| `frontend` | `deliverables/production/features/{task-id}/` | `deliverables/production/features/user-login/` |
-
-**自定义路径**：
-
-项目可以通过修改 `.trellis/paths.yaml` 自定义产出目录结构：
+If empty or missing, warn the user:
+> "The output directory `<output_dir>` appears empty. Would you like to continue anyway?"
 
-```yaml
-deliverables_base: "outputs"  # 可改为任何名称
-role_outputs:
-  pm:
-    dir: "specs"
-  designer:
-    dir: "designs"
-  frontend:
-    dir: "code"
-```
-
-**任务ID** 从 `task.json` 的 `id` 字段读取。
-
----
-
-### Step 4: 检查产出完整性
-
-**PM 角色必需文件**：
-- [ ] `prd.md` 存在且非空
-- [ ] （可选）`user-stories.md`
-
-**Designer 角色必需文件**：
-- [ ] 至少1个 `.tsx` 或 `.vue` 文件（原型代码）
-- [ ] 至少1个 Mock 数据文件（`mocks/` 或 `*.mock.ts`）
-
-**Frontend 角色必需文件**：
-- [ ] 修改了至少1个代码文件（通过 `git diff --name-only` 检查）
-
-**如果检查失败**：
-```
-警告用户产出不完整，询问是否继续：
-  "⚠️  检测到以下问题：
-   - PM: 缺少 prd.md
-
-   是否继续生成 HANDOFF？[y/N]"
-
-如果用户选择 N，中止执行。
-如果用户选择 y，继续但在 HANDOFF 中标注警告。
-```
-
----
+### Step 3: Generate HANDOFF.md
 
-### Step 5: AI 生成 HANDOFF.md
+Analyze all files in the output directory and generate a `HANDOFF.md` document.
 
-调用 Python 脚本生成初稿：
+**For PM role (requirements pool):**
 
-```bash
-python3 .trellis/scripts/handoff_generator.py \
-  <task-dir> \
-  <role> \
-  --output <产出目录>/HANDOFF.md
-```
-
-**脚本输出**：
-- 基于角色模板生成的 HANDOFF.md
-- 包含 TODO 标记需要 AI 补充的部分
-
-**AI 任务**：
-1. 读取生成的 HANDOFF.md
-2. 分析任务目录中的文件（prd.md, 代码文件等）
-3. 替换所有 `[TODO: AI填写...]` 标记为实际内容
-
-**AI 补充内容指南**：
-
-#### PM 角色 HANDOFF
-```markdown
-## 🎯 核心需求
-[TODO: AI根据PRD总结核心要点（2-3段）]
-
-→ AI应该：
-  - 阅读 prd.md
-  - 提炼最重要的2-3个功能点
-  - 用简洁的语言（每段50-100字）总结
-
-## 🔑 关键设计要点
-1. [TODO: AI填写关键功能点1]
-2. [TODO: AI填写关键功能点2]
-
-→ AI应该：
-  - 从 PRD 中提取 Designer 需要重点关注的 UI/交互要求
-  - 例如："支持邮箱+密码登录"、"第三方登录按钮布局参考设计稿"
-
-## ⚠️ 特别注意事项
-- [TODO: AI填写注意事项1 - 如UI布局要求]
-
-→ AI应该：
-  - 提取技术限制、兼容性要求、时间节点等
-  - 例如："支持 IE11"、"密码输入框需要显示/隐藏切换"
-```
-
-#### Designer 角色 HANDOFF
-```markdown
-## 🎨 设计说明
-[TODO: AI总结设计思路（2-3段）]
-
-→ AI应该：
-  - 阅读原型代码文件
-  - 总结布局结构、主要组件、交互流程
-
-## 🧩 组件结构
-[TODO: AI绘制组件树]
-
-→ AI应该：
-  - 分析代码文件依赖关系
-  - 绘制组件树（Markdown 文本格式）
-
-## 💾 Mock数据说明
-[TODO: AI填写Mock数据示例]
-
-→ AI应该：
-  - 搜索 `*.mock.ts` 或 `mocks/` 目录
-  - 提取关键 Mock 数据结构
-  - 标注文件位置和行号
-
-## 🔄 需要Frontend补充的逻辑
-1. **API集成** - 替换Mock为真实API调用
-   - 位置: [TODO: 文件名:行号]
-
-→ AI应该：
-  - 搜索代码中的 `TODO` 或 `MOCK` 注释
-  - 或搜索包含 `setTimeout`、`Promise.resolve` 的 Mock 实现
-  - 列出每个需要替换的位置
-```
-
-#### Frontend 角色 HANDOFF
 ```markdown
-## 🎯 实现总结
-[TODO: AI总结实现要点（2-3段）]
-
-→ AI应该：
-  - 运行 `git diff --name-only` 获取修改的文件列表
-  - 总结主要功能实现、API 集成情况
+# {Title} - Requirements Handoff
 
-## 🔌 API集成
-| 端点 | 方法 | 用途 | 位置 |
-|------|------|------|------|
-| [TODO] | POST | [TODO] | [TODO:文件:行号] |
+## Task Info
+- **Feature ID**: {slug}
+- **Title**: {title}
+- **Completed by**: {developer}
+- **Completed at**: {timestamp}
 
-→ AI应该：
-  - 搜索代码中的 API 调用（axios, fetch）
-  - 提取端点、方法、用途
-```
+## Core Requirements
+(AI-generated summary of PRD key points, 2-3 paragraphs)
 
----
-
-### Step 6: 询问用户交接留言
-
-```
-AI 提示用户：
-  "HANDOFF 文档已生成。请查看：
+## Deliverable Files
+- `prd.md` - Product requirements document
+- (list all files)
 
-   <产出目录>/HANDOFF.md
+## Key Design Points
+1. (extracted from PRD)
+2. ...
 
-   是否需要添加额外的交接留言？（可选）
-   例如：重点关注第三方登录流程、Mock 数据在 src/mocks/auth.ts"
+## Special Notes for Downstream
+- (important details the Designer should know)
+- (constraints, edge cases, specific UI requirements)
 
-用户输入：<留言内容> 或直接回车跳过
+## Related Resources
+- (links if any)
 ```
 
-**如果用户提供留言**：
-- 追加到 HANDOFF.md 末尾：
-  ```markdown
-  ## 📝 交接留言
+**For Designer role (prototypes pool):**
 
-  {用户留言内容}
-  ```
+```markdown
+# {Title} - Prototype Handoff
 
----
+## Task Info
+- **Feature ID**: {slug}
+- **Based on**: {source requirement}
+- **Completed by**: {developer}
+- **Completed at**: {timestamp}
 
-### Step 7: 复制文件到产出目录
+## Design Notes
+(AI-generated summary of design approach, 2-3 paragraphs)
 
-**创建产出目录**：
-```bash
-mkdir -p <产出目录>
-```
+## Deliverable Files
+- (list all component files)
 
-**复制规则**：
+## Component Structure
+(component tree overview)
 
-#### PM 角色
-```bash
-cp <task-dir>/prd.md <产出目录>/
-cp <task-dir>/user-stories.md <产出目录>/  # 如果存在
-cp <task-dir>/HANDOFF.md <产出目录>/      # 已生成
+## Mock Data Notes
+Current mock data used:
+```typescript
+// Document all mock data and their locations
+// Include file name and line numbers
 ```
 
-#### Designer 角色
-```bash
-# 复制所有原型代码文件（.tsx, .ts, .vue, .jsx, .js）
-find <task-dir> -name "*.tsx" -o -name "*.ts" | while read file; do
-  cp "$file" <产出目录>/
-done
-
-# 复制 Mock 数据
-cp -r <task-dir>/mocks/ <产出目录>/mocks/  # 如果存在
+## Logic for Frontend to Implement
+1. Replace mock login handler with real API call (file:line)
+2. Add error handling for network failures
+3. Implement loading state management
+4. ...
 
-# 复制 HANDOFF
-cp <task-dir>/HANDOFF.md <产出目录>/
+## Special Notes for Downstream
+- (interactions to preserve)
+- (SDK dependencies)
+- (form validation already implemented)
 ```
 
-#### Frontend 角色
-```bash
-# 获取 git 修改的文件
-git diff --name-only > /tmp/modified_files.txt
+Write the generated HANDOFF.md to `<output_dir>/HANDOFF.md`.
 
-# 复制修改的文件到产出目录（保持目录结构）
-while read file; do
-  mkdir -p <产出目录>/$(dirname "$file")
-  cp "$file" <产出目录>/"$file"
-done < /tmp/modified_files.txt
+### Step 4: Ask for Handoff Message (Optional)
 
-# 复制 HANDOFF
-cp <task-dir>/HANDOFF.md <产出目录>/
-```
+Ask the user:
+> "Any additional notes for the downstream role? (Press Enter to skip)"
 
----
+If provided, append to the Special Notes section.
 
-### Step 8: 加入任务池
+### Step 5: Add to Pool
 
-调用 pool.py 添加到对应池子：
+Determine the target pool based on role:
+- `pm` -> `requirements`
+- `designer` -> `prototypes`
+- `frontend-impl` or `frontend` -> `implementations`
 
 ```bash
-python3 .trellis/scripts/pool.py add <pool-type> <task-data-json>
+python3 ./.trellis/scripts/pool.py add <pool> <slug> "<title>" <output_dir>
 ```
 
-**pool-type 映射**：
-- `pm` → `requirements`
-- `designer` → `prototypes`
-- `frontend` → `implementations`
-
-**task-data-json 格式**：
-```json
-{
-  "id": "<task-id>",
-  "title": "<task-title>",
-  "path": "<产出目录相对路径>",
-  "completed_by": "<当前开发者>",
-  "handoff_doc": "<产出目录>/HANDOFF.md",
-  "completed_at": "<当前时间 ISO格式>"
-}
-```
+### Step 6: Report
 
-**获取当前开发者**：
-```bash
-python3 .trellis/scripts/get_developer.py
+Output a summary:
 ```
+Handoff complete!
+- Deliverable: <slug>
+- Pool: <pool>
+- HANDOFF.md: <output_dir>/HANDOFF.md
+- Status: available
 
----
-
-### Step 9: 更新任务状态
-
-**更新 task.json**：
-```json
-{
-  ...
-  "status": "completed",
-  "completedAt": "<当前日期 YYYY-MM-DD>",
-  "output_dir": "<产出目录相对路径>"
-}
+Next: The downstream role can pick this up with:
+  /trellis:pick-task <pool> <slug>
 ```
 
-**清除当前任务**（可选）：
-```bash
-python3 .trellis/scripts/task.py finish
-```
-
----
-
-### Step 10: 输出通知信息
-
-```
-✅ 任务交接完成！
-
-产出目录: <产出目录>
-HANDOFF 文档: <产出目录>/HANDOFF.md
-已加入任务池: <pool-type>
-
-下游可通过以下命令消费：
-  /trellis:pick-task <pool-type> <task-id>
-
-提示：记得提醒下游角色（通过IM、邮件等）
-```
-
----
-
-## 错误处理
-
-### 错误场景1：没有当前任务
-```
-Error: 没有设置当前任务
-
-请先执行：python3 .trellis/scripts/task.py start <task-dir>
-```
-
-### 错误场景2：task.json 缺少 role 字段
-```
-Error: task.json 缺少 role 字段
-
-请先执行：python3 .trellis/scripts/task.py set-role <task-dir> <pm|designer|frontend>
-```
-
-### 错误场景3：产出目录已存在
-```
-Warning: 产出目录已存在：<产出目录>
-
-是否覆盖？[y/N]
-```
-
-### 错误场景4：HANDOFF 生成失败
-```
-Error: HANDOFF 文档生成失败
-
-可能原因：
-  - task.json 格式错误
-  - Python 脚本路径错误
-
-请检查并重试，或手动创建 HANDOFF.md
-```
-
----
-
-## 示例执行流程
-
-### PM 完成 PRD 后交接
-
-```bash
-# 用户执行命令
-/trellis:handoff
-
-# AI 执行流程
-1. 读取当前任务：.trellis/tasks/01-21-user-login
-2. 读取 task.json：role=pm, id=user-login
-3. 确定产出目录：deliverables/requirements/user-login/
-4. 检查文件：prd.md ✅
-5. 生成 HANDOFF.md（AI 补充核心要点）
-6. 询问交接留言：用户输入"重点关注第三方登录流程"
-7. 复制文件：prd.md, HANDOFF.md → deliverables/requirements/user-login/
-8. 加入池子：pool.py add requirements {...}
-9. 更新状态：task.json status=completed
-10. 输出通知：✅ 已加入 requirements 池，Designer 可消费
-```
-
----
-
-## 注意事项
-
-1. **HANDOFF 质量**：AI 补充的内容应该准确、简洁、有用
-2. **文件完整性**：确保复制所有必要文件到产出目录
-3. **任务池状态**：成功加入池子后，任务状态应为 `available`
-4. **交接通知**：提醒用户通知下游角色（命令只更新池子，不发送通知）
-
----
-
-## 命令别名（可选）
-
-用户可能使用以下变体，AI 应识别并执行相同逻辑：
-- `/trellis:handoff`
-- `/handoff`
-- "完成任务并交接"
+Remind the user to commit and push so the downstream role can access the deliverables.