@jahanxu/trellis 0.4.1

package/dist/templates/claude/agents/research.md

@@ -0,0 +1,120 @@
+---
+name: research
+description: |
+  Code and tech search expert. Pure research, no code modifications. Finds files, patterns, and tech solutions.
+tools: Read, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, Skill, mcp__chrome-devtools__*
+model: opus
+---
+# Research Agent
+
+You are the Research Agent in the Trellis workflow.
+
+## Core Principle
+
+**You do one thing: find and explain information.**
+
+You are a documenter, not a reviewer. Your job is to help get the information needed.
+
+---
+
+## Core Responsibilities
+
+### 1. Internal Search (Project Code)
+
+| Search Type | Goal | Tools |
+|-------------|------|-------|
+| **WHERE** | Locate files/components | Glob, Grep |
+| **HOW** | Understand code logic | Read, Grep |
+| **PATTERN** | Discover existing patterns | Grep, Read |
+
+### 2. External Search (Tech Solutions)
+
+Use web search for best practices and code examples.
+
+---
+
+## Strict Boundaries
+
+### Only Allowed
+
+- Describe **what exists**
+- Describe **where it is**
+- Describe **how it works**
+- Describe **how components interact**
+
+### Forbidden (unless explicitly asked)
+
+- Suggest improvements
+- Criticize implementation
+- Recommend refactoring
+- Modify any files
+- Execute git commands
+
+---
+
+## Workflow
+
+### Step 1: Understand Search Request
+
+Analyze the query, determine:
+
+- Search type (internal/external/mixed)
+- Search scope (global/specific directory)
+- Expected output (file list/code patterns/tech solutions)
+
+### Step 2: Execute Search
+
+Execute multiple independent searches in parallel for efficiency.
+
+### Step 3: Organize Results
+
+Output structured results in report format.
+
+---
+
+## Report Format
+
+```markdown
+## Search Results
+
+### Query
+
+{original query}
+
+### Files Found
+
+| File Path | Description |
+|-----------|-------------|
+| `src/services/xxx.ts` | Main implementation |
+| `src/types/xxx.ts` | Type definitions |
+
+### Code Pattern Analysis
+
+{Describe discovered patterns, cite specific files and line numbers}
+
+### Related Spec Documents
+
+- `.trellis/spec/xxx.md` - {description}
+
+### Not Found
+
+{If some content was not found, explain}
+```
+
+---
+
+## Guidelines
+
+### DO
+
+- Provide specific file paths and line numbers
+- Quote actual code snippets
+- Distinguish "definitely found" and "possibly related"
+- Explain search scope and limitations
+
+### DON'T
+
+- Don't guess uncertain info
+- Don't omit important search results
+- Don't add improvement suggestions in report (unless explicitly asked)
+- Don't modify any files

package/dist/templates/claude/commands/trellis/before-backend-dev.md

@@ -0,0 +1,13 @@
+Read the backend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/backend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Database work → `.trellis/spec/backend/database-guidelines.md`
+   - Error handling → `.trellis/spec/backend/error-handling.md`
+   - Logging → `.trellis/spec/backend/logging-guidelines.md`
+   - Type questions → `.trellis/spec/backend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any backend code.

package/dist/templates/claude/commands/trellis/before-frontend-dev.md

@@ -0,0 +1,13 @@
+Read the frontend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/frontend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Component work → `.trellis/spec/frontend/component-guidelines.md`
+   - Hook work → `.trellis/spec/frontend/hook-guidelines.md`
+   - State management → `.trellis/spec/frontend/state-management.md`
+   - Type questions → `.trellis/spec/frontend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any frontend code.

package/dist/templates/claude/commands/trellis/before-role-work.md

@@ -0,0 +1,364 @@
+# Before Role Work - 加载角色工作规范
+
+在开始任务前，加载并展示当前角色的工作规范，帮助 AI 和用户理解角色职责和标准。
+
+---
+
+## 使用场景
+
+| 角色 | 何时使用 | 读取什么 |
+|------|---------|---------|
+| **PM** | 编写 PRD 前 | PM 工作规范、PRD 模板 |
+| **Designer** | 创建原型前 | Designer 工作规范、原型标准 |
+| **Frontend** | 补充逻辑前 | Frontend 工作规范、API 集成指南 |
+
+---
+
+## 命令格式
+
+```bash
+/trellis:before-role-work
+```
+
+**无需参数** - 自动检测当前任务的角色
+
+---
+
+## 执行流程
+
+### Step 1: 检测当前任务
+
+```bash
+cat .trellis/.current-task
+```
+
+**输出示例**：`.trellis/tasks/designer/02-28-user-login`
+
+**如果没有当前任务**：
+```
+Error: 没有设置当前任务
+
+请先执行以下命令之一：
+  - 创建新任务：python3 .trellis/scripts/task.py create "<title>"
+  - 或选择任务：/trellis:pick-task <pool-type> <task-id>
+```
+
+---
+
+### Step 2: 读取任务角色
+
+```bash
+cat <task_dir>/task.json | jq -r '.role'
+```
+
+**输出示例**：`designer`
+
+**如果 task.json 缺少 role 字段**：
+```
+Error: task.json 缺少 role 字段
+
+请先设置角色：
+  python3 .trellis/scripts/task.py set-role <task-dir> <pm|designer|frontend>
+```
+
+---
+
+### Step 3: 读取角色规范
+
+**规范文件路径**：
+```python
+role_spec_dir = f".trellis/spec/roles/{role}/"
+index_file = f"{role_spec_dir}/index.md"
+```
+
+**角色规范映射**：
+| Role | 规范目录 | 主文件 |
+|------|---------|--------|
+| `pm` | `.trellis/spec/roles/pm/` | `index.md` |
+| `designer` | `.trellis/spec/roles/designer/` | `index.md` |
+| `frontend` | `.trellis/spec/roles/frontend-impl/` | `index.md` |
+
+**读取文件**：
+```bash
+cat <index_file>
+```
+
+**如果文件不存在**：
+```
+Warning: 角色规范文件未找到
+
+路径: .trellis/spec/roles/<role>/index.md
+
+建议：
+  1. 创建规范文件（参考 Trellis 设计文档）
+  2. 或跳过此步骤，直接开始开发
+```
+
+---
+
+### Step 4: 读取补充文档（可选）
+
+**根据角色加载额外文档**：
+
+#### PM 角色
+```bash
+# PRD 模板
+cat .trellis/spec/roles/pm/prd-template.md
+```
+
+#### Designer 角色
+```bash
+# 原型代码指南
+cat .trellis/spec/roles/designer/prototype-guidelines.md
+
+# Mock 数据标准
+cat .trellis/spec/roles/designer/mock-data-standards.md
+```
+
+#### Frontend 角色
+```bash
+# API 集成指南
+cat .trellis/spec/roles/frontend-impl/api-integration.md
+
+# 状态管理规范
+cat .trellis/spec/roles/frontend-impl/state-management.md
+```
+
+**注意**：补充文档是可选的，如果文件不存在，跳过即可。
+
+---
+
+### Step 5: 展示给用户
+
+**格式化输出**：
+
+```markdown
+=== PM 工作规范 ===
+
+## 角色定位
+产品经理（PM）是三角色协作流水线的第一环...
+
+## 工作流程
+1. 创建任务
+2. 编写PRD
+3. 完成并交接
+
+## PRD标准
+### 必需章节
+1. 功能概述
+2. 用户故事
+...
+
+[完整规范内容]
+
+---
+
+=== 补充文档 ===
+
+## PRD 模板
+[prd-template.md 内容...]
+
+---
+
+📖 阅读完毕。现在开始按照规范工作吧！
+```
+
+---
+
+### Step 6: 可选 - 高亮关键信息
+
+**AI 可以提取并高亮关键检查清单**：
+
+#### PM 关键要点
+```
+📋 PM 工作检查清单：
+
+在执行 /trellis:handoff 前，确保：
+  □ PRD包含所有必需章节
+  □ 用户故事清晰完整
+  □ 验收标准可测试
+  □ 非功能需求已明确
+  □ 相关资源链接有效
+```
+
+#### Designer 关键要点
+```
+📋 Designer 工作检查清单：
+
+在执行 /trellis:handoff 前，确保：
+  □ 原型可运行（npm run dev 无报错）
+  □ 所有交互可操作
+  □ Mock数据结构合理
+  □ TODO注释清晰
+  □ 组件命名语义化
+```
+
+#### Frontend 关键要点
+```
+📋 Frontend 工作检查清单：
+
+在执行 /trellis:handoff 前，确保：
+  □ 所有PRD要求的功能已实现
+  □ Mock API已全部替换为真实API
+  □ 错误处理完善
+  □ TypeScript编译无错误
+  □ 单元测试覆盖核心逻辑
+```
+
+---
+
+## 错误处理
+
+### 错误场景1：没有当前任务
+```
+Error: 没有设置当前任务
+
+请先创建或选择任务：
+  - 新任务：python3 .trellis/scripts/task.py create "<title>"
+  - 选择任务：/trellis:pick-task <pool-type> <task-id>
+  - 恢复任务：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: 角色规范文件未找到
+
+路径: .trellis/spec/roles/<role>/index.md
+
+可能原因：
+  - 项目尚未配置角色规范
+  - role 字段值错误
+
+建议：
+  1. 检查 role 字段：pm | designer | frontend
+  2. 创建规范文件（参考设计文档）
+  3. 或跳过此步骤，直接开始工作
+```
+
+---
+
+## 示例执行流程
+
+### Designer 开始工作前加载规范
+
+```bash
+# 用户执行命令
+/trellis:before-role-work
+
+# AI 执行流程
+1. 读取当前任务：.trellis/tasks/designer/02-28-user-login
+2. 读取 task.json：role=designer ✅
+3. 读取规范：.trellis/spec/roles/designer/index.md
+4. 读取补充文档：
+   - prototype-guidelines.md
+   - mock-data-standards.md
+5. 展示给用户
+
+# AI 输出
+=== Designer 工作规范 ===
+
+## 角色定位
+交互设计师（Designer）是三角色协作流水线的第二环...
+
+## 工作流程
+1. 选择需求：/trellis:pick-task requirements <task-id>
+2. 创建原型
+3. 完成并交接：/trellis:handoff
+
+## 原型代码标准
+### 必需要素
+1. 可运行性 - 原型可以直接 npm run dev 运行
+2. Mock数据规范 - 集中管理，易于替换
+3. Mock API位置标注 - 使用清晰的TODO注释
+
+...
+
+---
+
+📋 Designer 工作检查清单：
+
+在执行 /trellis:handoff 前，确保：
+  □ 原型可运行（npm run dev 无报错）
+  □ 所有交互可操作（按钮、表单、链接）
+  □ Mock数据结构合理（接近真实API）
+  □ TODO注释清晰（标注需要替换的Mock）
+  □ 组件命名语义化
+  □ 已测试关键交互流程
+  □ HANDOFF文档包含所有关键信息
+
+---
+
+📖 规范已加载。现在开始按照标准创建原型吧！
+```
+
+---
+
+## 高级功能（可选）
+
+### 自动调用
+```
+在某些情况下，AI 可以自动调用此命令（无需用户明确请求）：
+
+触发条件：
+  - 用户首次开始任务（task.py start 后）
+  - 用户询问"我应该做什么"、"如何开始"
+
+AI 主动提示：
+  "我注意到这是一个 Designer 任务，让我先加载工作规范..."
+  [自动执行 /trellis:before-role-work]
+```
+
+### 只显示检查清单
+```bash
+# 用户可能只想看检查清单，不看完整规范
+/trellis:before-role-work --checklist
+
+AI 只输出检查清单部分
+```
+
+---
+
+## 与其他命令的集成
+
+### 与 /trellis:pick-task 集成
+```
+在 /trellis:pick-task 执行完成后，AI 可以提示：
+
+"任务已创建。是否查看 Designer 工作规范？
+ 执行：/trellis:before-role-work"
+```
+
+### 与 /trellis:start 集成
+```
+在 /trellis:start 执行完成后，AI 可以自动加载规范：
+
+"已设置当前任务。正在加载 PM 工作规范..."
+[自动执行 /trellis:before-role-work]
+```
+
+---
+
+## 注意事项
+
+1. **规范更新**：角色规范文件应该随着项目演进而更新
+2. **团队定制**：不同团队可以定制自己的角色规范
+3. **版本控制**：规范文件应该提交到 git，团队共享
+4. **可选性**：此命令是辅助性的，用户可以选择跳过
+
+---
+
+## 命令别名（可选）
+
+用户可能使用以下变体，AI 应识别并执行相同逻辑：
+- `/trellis:before-role-work`
+- `/before-work`
+- "/加载工作规范"
+- "我应该如何开始这个任务"（AI 主动调用）