@jahanxu/trellis 0.4.1

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

@@ -0,0 +1,445 @@
+# Handoff - 完成任务并生成交接文档
+
+完成当前任务，AI自动生成 HANDOFF.md 交接文档，并将产出加入任务池供下游消费。
+
+---
+
+## 使用场景
+
+| 角色 | 何时使用 | 产出去向 |
+|------|---------|---------|
+| **PM** | 完成 PRD 编写 | → requirements 池 |
+| **Designer** | 完成原型代码 | → prototypes 池 |
+| **Frontend** | 完成生产代码 | → implementations 池 |
+
+---
+
+## 执行流程
+
+### Step 1: 检查当前任务状态
+
+```bash
+python3 .trellis/scripts/get_context.py
+```
+
+**验证点**：
+- ✅ 当前任务已设置（`.trellis/.current-task`）
+- ✅ 任务目录存在
+- ✅ `task.json` 包含 `role` 字段
+
+**如果验证失败**：
+```
+如果没有当前任务：
+  → 先执行: python3 .trellis/scripts/task.py start <task-dir>
+
+如果没有 role 字段：
+  → 先执行: python3 .trellis/scripts/task.py set-role <task-dir> <pm|designer|frontend>
+```
+
+---
+
+### Step 2: 读取任务配置
+
+```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)
+"
+```
+
+**默认路径映射**（如果 `.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` 自定义产出目录结构：
+
+```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 5: AI 生成 HANDOFF.md
+
+调用 Python 脚本生成初稿：
+
+```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 集成情况
+
+## 🔌 API集成
+| 端点 | 方法 | 用途 | 位置 |
+|------|------|------|------|
+| [TODO] | POST | [TODO] | [TODO:文件:行号] |
+
+→ AI应该：
+  - 搜索代码中的 API 调用（axios, fetch）
+  - 提取端点、方法、用途
+```
+
+---
+
+### Step 6: 询问用户交接留言
+
+```
+AI 提示用户：
+  "HANDOFF 文档已生成。请查看：
+
+   <产出目录>/HANDOFF.md
+
+   是否需要添加额外的交接留言？（可选）
+   例如：重点关注第三方登录流程、Mock 数据在 src/mocks/auth.ts"
+
+用户输入：<留言内容> 或直接回车跳过
+```
+
+**如果用户提供留言**：
+- 追加到 HANDOFF.md 末尾：
+  ```markdown
+  ## 📝 交接留言
+
+  {用户留言内容}
+  ```
+
+---
+
+### Step 7: 复制文件到产出目录
+
+**创建产出目录**：
+```bash
+mkdir -p <产出目录>
+```
+
+**复制规则**：
+
+#### PM 角色
+```bash
+cp <task-dir>/prd.md <产出目录>/
+cp <task-dir>/user-stories.md <产出目录>/  # 如果存在
+cp <task-dir>/HANDOFF.md <产出目录>/      # 已生成
+```
+
+#### 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/  # 如果存在
+
+# 复制 HANDOFF
+cp <task-dir>/HANDOFF.md <产出目录>/
+```
+
+#### Frontend 角色
+```bash
+# 获取 git 修改的文件
+git diff --name-only > /tmp/modified_files.txt
+
+# 复制修改的文件到产出目录（保持目录结构）
+while read file; do
+  mkdir -p <产出目录>/$(dirname "$file")
+  cp "$file" <产出目录>/"$file"
+done < /tmp/modified_files.txt
+
+# 复制 HANDOFF
+cp <task-dir>/HANDOFF.md <产出目录>/
+```
+
+---
+
+### Step 8: 加入任务池
+
+调用 pool.py 添加到对应池子：
+
+```bash
+python3 .trellis/scripts/pool.py add <pool-type> <task-data-json>
+```
+
+**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格式>"
+}
+```
+
+**获取当前开发者**：
+```bash
+python3 .trellis/scripts/get_developer.py
+```
+
+---
+
+### Step 9: 更新任务状态
+
+**更新 task.json**：
+```json
+{
+  ...
+  "status": "completed",
+  "completedAt": "<当前日期 YYYY-MM-DD>",
+  "output_dir": "<产出目录相对路径>"
+}
+```
+
+**清除当前任务**（可选）：
+```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`
+- "完成任务并交接"

package/dist/templates/claude/commands/trellis/integrate-skill.md

@@ -0,0 +1,219 @@
+# Integrate Claude Skill into Project Guidelines
+
+Adapt and integrate a Claude global skill into your project's development guidelines (not directly into project code).
+
+## Usage
+
+```
+/trellis:integrate-skill <skill-name>
+```
+
+**Examples**:
+```
+/trellis:integrate-skill frontend-design
+/trellis:integrate-skill mcp-builder
+```
+
+## Core Principle
+
+> [!] **Important**: The goal of skill integration is to update **development guidelines**, not to generate project code directly.
+>
+> - Guidelines content -> Write to `.trellis/spec/{target}/doc.md`
+> - Code examples -> Place in `.trellis/spec/{target}/examples/skills/<skill-name>/`
+> - Example files -> Use `.template` suffix (e.g., `component.tsx.template`) to avoid IDE errors
+>
+> Where `{target}` is `frontend` or `backend`, determined by skill type.
+
+## Execution Steps
+
+### 1. Read Skill Content
+
+```bash
+openskills read <skill-name>
+```
+
+If the skill doesn't exist, prompt user to check available skills:
+```bash
+# Available skills are listed in AGENTS.md under <available_skills>
+```
+
+### 2. Determine Integration Target
+
+Based on skill type, determine which guidelines to update:
+
+| Skill Category | Integration Target |
+|----------------|-------------------|
+| UI/Frontend (`frontend-design`, `web-artifacts-builder`) | `.trellis/spec/frontend/` |
+| Backend/API (`mcp-builder`) | `.trellis/spec/backend/` |
+| Documentation (`doc-coauthoring`, `docx`, `pdf`) | `.trellis/` or create dedicated guidelines |
+| Testing (`webapp-testing`) | `.trellis/spec/frontend/` (E2E) |
+
+### 3. Analyze Skill Content
+
+Extract from the skill:
+- **Core concepts**: How the skill works and key concepts
+- **Best practices**: Recommended approaches
+- **Code patterns**: Reusable code templates
+- **Caveats**: Common issues and solutions
+
+### 4. Execute Integration
+
+#### 4.1 Update Guidelines Document
+
+Add a new section to the corresponding `doc.md`:
+
+```markdown
+@@@section:skill-<skill-name>
+## # <Skill Name> Integration Guide
+
+### Overview
+[Core functionality and use cases of the skill]
+
+### Project Adaptation
+[How to use this skill in the current project]
+
+### Usage Steps
+1. [Step 1]
+2. [Step 2]
+
+### Caveats
+- [Project-specific constraints]
+- [Differences from default behavior]
+
+### Reference Examples
+See `examples/skills/<skill-name>/`
+
+@@@/section:skill-<skill-name>
+```
+
+#### 4.2 Create Examples Directory (if code examples exist)
+
+```bash
+# Directory structure ({target} = frontend or backend)
+.trellis/spec/{target}/
+|-- doc.md                      # Add skill-related section
+|-- index.md                    # Update index
++-- examples/
+    +-- skills/
+        +-- <skill-name>/
+            |-- README.md               # Example documentation
+            |-- example-1.ts.template   # Code example (use .template suffix)
+            +-- example-2.tsx.template
+```
+
+**File naming conventions**:
+- Code files: `<name>.<ext>.template` (e.g., `component.tsx.template`)
+- Config files: `<name>.config.template` (e.g., `tailwind.config.template`)
+- Documentation: `README.md` (normal suffix)
+
+#### 4.3 Update Index File
+
+Add to the Quick Navigation table in `index.md`:
+
+```markdown
+| <Skill-related task> | <Section name> | `skill-<skill-name>` |
+```
+
+### 5. Generate Integration Report
+
+---
+
+## Skill Integration Report: `<skill-name>`
+
+### # Overview
+- **Skill description**: [Functionality description]
+- **Integration target**: `.trellis/spec/{target}/`
+
+### # Tech Stack Compatibility
+
+| Skill Requirement | Project Status | Compatibility |
+|-------------------|----------------|---------------|
+| [Tech 1] | [Project tech] | [OK]/[!]/[X] |
+
+### # Integration Locations
+
+| Type | Path |
+|------|------|
+| Guidelines doc | `.trellis/spec/{target}/doc.md` (section: `skill-<name>`) |
+| Code examples | `.trellis/spec/{target}/examples/skills/<name>/` |
+| Index update | `.trellis/spec/{target}/index.md` |
+
+> `{target}` = `frontend` or `backend`
+
+### # Dependencies (if needed)
+
+```bash
+# Install required dependencies (adjust for your package manager)
+npm install <package>
+# or
+pnpm add <package>
+# or
+yarn add <package>
+```
+
+### [OK] Completed Changes
+
+- [ ] Added `@@@section:skill-<name>` section to `doc.md`
+- [ ] Added index entry to `index.md`
+- [ ] Created example files in `examples/skills/<name>/`
+- [ ] Example files use `.template` suffix
+
+### # Related Guidelines
+
+- [Existing related section IDs]
+
+---
+
+## 6. Optional: Create Usage Command
+
+If this skill is frequently used, create a shortcut command:
+
+```bash
+/trellis:create-command use-<skill-name> Use <skill-name> skill following project guidelines
+```
+
+## Common Skill Integration Reference
+
+| Skill | Integration Target | Examples Directory |
+|-------|-------------------|-------------------|
+| `frontend-design` | `frontend` | `examples/skills/frontend-design/` |
+| `mcp-builder` | `backend` | `examples/skills/mcp-builder/` |
+| `webapp-testing` | `frontend` | `examples/skills/webapp-testing/` |
+| `doc-coauthoring` | `.trellis/` | N/A (documentation workflow only) |
+
+## Example: Integrating `mcp-builder` Skill
+
+### Directory Structure
+
+```
+.trellis/spec/backend/
+|-- doc.md                           # Add MCP section
+|-- index.md                         # Add index entry
++-- examples/
+    +-- skills/
+        +-- mcp-builder/
+            |-- README.md
+            |-- server.ts.template
+            |-- tools.ts.template
+            +-- types.ts.template
+```
+
+### New Section in doc.md
+
+```markdown
+@@@section:skill-mcp-builder
+## # MCP Server Development Guide
+
+### Overview
+Create LLM-callable tool services using MCP (Model Context Protocol).
+
+### Project Adaptation
+- Place services in a dedicated directory
+- Follow existing TypeScript and type definition conventions
+- Use project's logging system
+
+### Reference Examples
+See `examples/skills/mcp-builder/`
+
+@@@/section:skill-mcp-builder
+```