@jahanxu/trellis 0.4.1

package/dist/templates/claude/commands/trellis/pick-task.md

@@ -0,0 +1,515 @@
+# Pick Task - 从任务池选择上游产出
+
+从上游产出池选择一个任务开始开发，自动创建任务目录并注入上游产出。
+
+---
+
+## 使用场景
+
+| 当前角色 | 从哪个池子选择 | 选择什么 |
+|---------|--------------|---------|
+| **Designer** | `requirements` | PM 完成的 PRD |
+| **Frontend** | `prototypes` | Designer 完成的原型代码 |
+
+**注意**：PM 不从池子选择任务（PM 是流水线起点）
+
+---
+
+## 命令格式
+
+```bash
+/trellis:pick-task <pool-type> <task-id>
+```
+
+**参数**：
+- `pool-type`: `requirements` 或 `prototypes`
+- `task-id`: 上游任务的 ID（从池子列表获取）
+
+**示例**：
+```bash
+/trellis:pick-task requirements user-login
+/trellis:pick-task prototypes user-login
+```
+
+---
+
+## 执行流程
+
+### Step 1: 检查当前角色
+
+```bash
+python3 .trellis/scripts/get_developer.py
+```
+
+**输出示例**：`designer-bob`
+
+**解析角色**：
+```python
+developer = "designer-bob"
+role = developer.split('-')[0]  # "designer"
+```
+
+**角色验证**：
+- ✅ `designer` → 可以 pick `requirements`
+- ✅ `frontend` → 可以 pick `prototypes`
+- ❌ `pm` → 不允许 pick（PM 是起点）
+
+**如果角色不匹配**：
+```
+Error: PM 不能从池子选择任务
+
+PM 应该：
+  1. 创建新任务：python3 .trellis/scripts/task.py create "<title>"
+  2. 编写 PRD
+  3. 执行 /trellis:handoff
+```
+
+**如果角色与池子不匹配**：
+```
+Error: Designer 不能从 prototypes 池选择任务
+
+Designer 应该从 requirements 池选择：
+  /trellis:pick-task requirements <task-id>
+```
+
+---
+
+### Step 2: 列出可用任务
+
+调用 pool.py 列出指定池子的任务：
+
+```bash
+python3 .trellis/scripts/pool.py list <pool-type> --status available
+```
+
+**输出示例**：
+```
+=== Requirements Pool ===
+
+Available (2):
+  • user-login: 用户登录功能
+    Completed by: pm-alice
+    Path: deliverables/requirements/user-login
+
+  • payment: 支付功能
+    Completed by: pm-alice
+    Path: deliverables/requirements/payment
+
+Consumed (0):
+  (none)
+```
+
+**AI 展示给用户**：
+```
+可用的 requirements 任务：
+
+1. user-login - 用户登录功能
+   完成人: pm-alice
+   路径: deliverables/requirements/user-login
+
+2. payment - 支付功能
+   完成人: pm-alice
+   路径: deliverables/requirements/payment
+
+请选择任务 ID，或使用命令：
+  /trellis:pick-task requirements <task-id>
+```
+
+---
+
+### Step 3: 验证任务状态
+
+**读取任务池数据**：
+```bash
+cat .trellis/pool/<pool-type>.json
+```
+
+**查找任务**：
+```python
+# 伪代码
+pool_data = json.loads(pool_file.read_text())
+
+task = None
+for t in pool_data["available"]:
+    if t["id"] == task_id:
+        task = t
+        break
+
+if not task:
+    # 检查是否已被消费
+    for t in pool_data["consumed"]:
+        if t["id"] == task_id:
+            error(f"任务 '{task_id}' 已被消费")
+            return
+
+    error(f"任务 '{task_id}' 不存在")
+    return
+```
+
+**任务状态验证**：
+- ✅ `status == "available"` → 可以消费
+- ❌ `status == "consumed"` → 拒绝，提示已被谁消费
+
+**如果任务已被消费**：
+```
+Error: 任务 'user-login' 已被消费
+
+消费者: designer-bob
+消费时间: 2026-02-28 15:30:00
+
+如需重新处理，请联系消费者或创建新任务
+```
+
+---
+
+### Step 4: 读取上游 HANDOFF 文档
+
+**HANDOFF 文档路径**：
+```python
+handoff_path = task["handoff_doc"]  # 例如：deliverables/requirements/user-login/HANDOFF.md
+```
+
+**读取并展示给用户**（可选）：
+```
+AI 提示：
+  "即将基于以下上游产出创建任务：
+
+   === 上游交接文档摘要 ===
+   功能ID: user-login
+   功能名称: 用户登录功能
+   完成人: pm-alice
+
+   核心需求：
+   - 支持邮箱+密码登录
+   - 支持第三方登录（微信、GitHub）
+   ...
+
+   是否继续？[Y/n]"
+
+如果用户输入 n，中止执行。
+```
+
+---
+
+### Step 5: 创建任务目录
+
+**生成任务目录名**：
+```python
+from datetime import datetime
+
+date_prefix = datetime.now().strftime("%m-%d")
+dir_name = f"{date_prefix}-{task_id}"  # 例如：02-28-user-login
+```
+
+**任务目录路径**：
+```python
+# Designer
+task_dir = f".trellis/tasks/designer/{dir_name}"
+
+# Frontend
+task_dir = f".trellis/tasks/frontend/{dir_name}"
+```
+
+**注意**：按角色隔离任务目录
+
+**创建目录**：
+```bash
+mkdir -p <task_dir>
+```
+
+---
+
+### Step 6: 生成 task.json
+
+**基本信息**：
+```json
+{
+  "id": "<task-id>",
+  "name": "<task-id>",
+  "title": "<上游任务的 title>",
+  "description": "",
+  "role": "<当前角色>",
+  "status": "planning",
+  "dev_type": "frontend",
+  "scope": null,
+  "priority": "P2",
+  "creator": "<当前开发者>",
+  "assignee": "<当前开发者>",
+  "createdAt": "<今天日期>",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "main",
+  "worktree_path": null,
+  "current_phase": 0,
+  "next_action": [],
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "relatedFiles": [],
+  "notes": ""
+}
+```
+
+**写入文件**：
+```bash
+echo '<task-json>' > <task_dir>/task.json
+```
+
+---
+
+### Step 7: 生成 source.json
+
+**引用上游产出**：
+```json
+{
+  "based_on": {
+    "type": "<pool-type-singular>",
+    "id": "<task-id>",
+    "path": "<上游产出路径>",
+    "handoff_doc": "<上游 HANDOFF 路径>"
+  }
+}
+```
+
+**pool-type 转换**：
+- `requirements` → `requirement`
+- `prototypes` → `prototype`
+
+**写入文件**：
+```bash
+echo '<source-json>' > <task_dir>/source.json
+```
+
+---
+
+### Step 8: 初始化上下文配置
+
+**根据角色创建对应的 .jsonl 文件**：
+
+#### Designer 角色
+创建 `designer.jsonl`：
+```jsonl
+{"file": ".trellis/spec/roles/designer/index.md", "reason": "Designer工作规范"}
+{"file": ".trellis/spec/roles/designer/prototype-guidelines.md", "reason": "原型代码规范"}
+{"file": ".trellis/spec/frontend/component-guidelines.md", "reason": "组件开发规范"}
+{"file": "<上游产出路径>", "type": "directory", "reason": "上游需求文档（自动注入）"}
+{"file": "<上游HANDOFF路径>", "reason": "上游交接文档"}
+```
+
+#### Frontend 角色
+创建 `frontend.jsonl`：
+```jsonl
+{"file": ".trellis/spec/roles/frontend-impl/index.md", "reason": "Frontend工作规范"}
+{"file": ".trellis/spec/roles/frontend-impl/api-integration.md", "reason": "API集成指南"}
+{"file": ".trellis/spec/frontend/type-safety.md", "reason": "类型安全规范"}
+{"file": ".trellis/spec/backend/api-conventions.md", "reason": "API约定（理解后端）"}
+{"file": "<上游产出路径>", "type": "directory", "reason": "上游原型代码（自动注入）"}
+{"file": "<上游HANDOFF路径>", "reason": "上游交接文档"}
+```
+
+**注意**：上游产出路径标记为 `"type": "directory"`，Hook 会自动读取目录下所有文件。
+
+---
+
+### Step 9: 消费任务（更新池子状态）
+
+调用 pool.py 标记任务为已消费：
+
+```bash
+python3 .trellis/scripts/pool.py consume <pool-type> <task-id> <当前开发者>
+```
+
+**池子状态变化**：
+- 任务从 `available` 列表移动到 `consumed` 列表
+- 添加 `consumed_by` 和 `consumed_at` 字段
+
+---
+
+### Step 10: 设置为当前任务
+
+```bash
+python3 .trellis/scripts/task.py start <task_dir>
+```
+
+**效果**：
+- 更新 `.trellis/.current-task` 为新任务路径
+- Hook 会自动注入上游产出
+
+---
+
+### Step 11: 输出通知信息
+
+```
+✅ 任务已选择并创建！
+
+任务目录: <task_dir>
+基于上游: <pool-type>/<task-id>
+
+已注入上游产出：
+  - HANDOFF: <上游HANDOFF路径>
+  - 产出文件: <上游产出路径>
+
+下一步：
+  1. 查看上游交接文档：cat <task_dir>/source.json
+  2. 阅读角色规范：cat .trellis/spec/roles/<role>/index.md
+  3. 开始开发
+  4. 完成后执行：/trellis:handoff
+```
+
+---
+
+## 错误处理
+
+### 错误场景1：PM 尝试 pick 任务
+```
+Error: PM 不能从池子选择任务
+
+PM 是流水线起点，应该：
+  1. 创建新任务：python3 .trellis/scripts/task.py create "<title>"
+  2. 设置角色：python3 .trellis/scripts/task.py set-role <dir> pm
+  3. 编写 PRD
+  4. 执行 /trellis:handoff
+```
+
+### 错误场景2：角色与池子不匹配
+```
+Error: Frontend 不能从 requirements 池选择任务
+
+Frontend 应该从 prototypes 池选择：
+  /trellis:pick-task prototypes <task-id>
+
+流程说明：
+  requirements → Designer → prototypes → Frontend
+```
+
+### 错误场景3：任务不存在
+```
+Error: 任务 'user-login' 不存在于 requirements 池
+
+可用任务：
+  /trellis:pick-task requirements payment
+  /trellis:pick-task requirements shopping-cart
+
+或查看完整列表：
+  python3 .trellis/scripts/pool.py list requirements
+```
+
+### 错误场景4：任务已被消费
+```
+Error: 任务 'user-login' 已被消费
+
+消费者: designer-bob
+消费时间: 2026-02-28 15:30:00
+
+如需重新处理：
+  1. 联系 designer-bob 确认状态
+  2. 或创建新任务基于相同需求
+```
+
+### 错误场景5：上游 HANDOFF 缺失
+```
+Warning: 上游 HANDOFF 文档缺失
+
+路径: deliverables/requirements/user-login/HANDOFF.md
+
+将继续创建任务，但上游交接信息可能不完整。
+
+是否继续？[y/N]
+```
+
+### 错误场景6：任务目录已存在
+```
+Error: 任务目录已存在：.trellis/tasks/designer/02-28-user-login
+
+可能原因：
+  - 之前创建过相同任务
+  - 日期和任务ID重复
+
+解决方案：
+  1. 删除旧目录：rm -rf <task_dir>
+  2. 或使用不同的任务ID
+```
+
+---
+
+## 示例执行流程
+
+### Designer 选择 PM 的需求
+
+```bash
+# 1. 查看可用需求
+/trellis:pick-task requirements
+
+AI 输出：
+  "可用的 requirements 任务：
+   1. user-login - 用户登录功能 (完成人: pm-alice)
+   2. payment - 支付功能 (完成人: pm-alice)"
+
+# 2. 选择任务
+/trellis:pick-task requirements user-login
+
+AI 执行流程：
+  1. 检查角色：designer-bob → role=designer ✅
+  2. 验证池子匹配：designer + requirements ✅
+  3. 读取任务：user-login (status=available) ✅
+  4. 读取 HANDOFF：deliverables/requirements/user-login/HANDOFF.md
+  5. 创建目录：.trellis/tasks/designer/02-28-user-login/
+  6. 生成 task.json (role=designer)
+  7. 生成 source.json (based_on=requirement/user-login)
+  8. 创建 designer.jsonl (包含上游产出)
+  9. 消费任务：pool.py consume requirements user-login designer-bob
+  10. 设置当前：task.py start .trellis/tasks/designer/02-28-user-login
+  11. 输出通知
+
+AI 输出：
+  "✅ 任务已选择并创建！
+
+   任务目录: .trellis/tasks/designer/02-28-user-login
+   基于上游: requirement/user-login
+
+   下一步：
+     1. 查看需求：cat deliverables/requirements/user-login/HANDOFF.md
+     2. 阅读规范：cat .trellis/spec/roles/designer/index.md
+     3. 开始创建原型
+     4. 完成后执行：/trellis:handoff"
+```
+
+---
+
+## 高级功能（可选）
+
+### 批量查看任务
+```bash
+# 用户可以不指定任务ID，先查看列表
+/trellis:pick-task requirements
+
+AI 展示列表，等待用户选择
+```
+
+### 任务预览
+```bash
+# 在选择任务前预览 HANDOFF 内容
+/trellis:pick-task requirements user-login --preview
+
+AI 只展示 HANDOFF 摘要，不创建任务
+```
+
+---
+
+## 注意事项
+
+1. **角色隔离**：任务目录按角色隔离（`.trellis/tasks/{role}/`）
+2. **上游注入**：`source.json` 确保 Hook 能找到上游产出
+3. **池子状态**：成功 pick 后，任务从 `available` 变为 `consumed`
+4. **防重复**：如果任务目录已存在，拒绝创建（或提示用户确认覆盖）
+
+---
+
+## 命令别名（可选）
+
+用户可能使用以下变体，AI 应识别并执行相同逻辑：
+- `/trellis:pick-task`
+- `/pick-task`
+- `/pick`
+- "从需求池选择任务"
+- "选择原型任务"

package/dist/templates/claude/commands/trellis/record-session.md

@@ -0,0 +1,62 @@
+[!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
+
+**AI must NOT execute git commit** - only read history (`git log`, `git status`, `git diff`).
+
+---
+
+## Record Work Progress (Simplified - Only 2 Steps)
+
+### Step 1: Get Context
+
+```bash
+python3 ./.trellis/scripts/get_context.py
+```
+
+### Step 2: One-Click Add Session
+
+```bash
+# Method 1: Simple parameters
+python3 ./.trellis/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary of what was done"
+
+# Method 2: Pass detailed content via stdin
+cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"
+| Feature | Description |
+|---------|-------------|
+| New API | Added user authentication endpoint |
+| Frontend | Updated login form |
+
+**Updated Files**:
+- `packages/api/modules/auth/router.ts`
+- `apps/web/modules/auth/components/login-form.tsx`
+EOF
+```
+
+**Auto-completes**:
+- [OK] Appends session to journal-N.md
+- [OK] Auto-detects line count, creates new file if >2000 lines
+- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
+
+---
+
+## Archive Completed Task (if any)
+
+If a task was completed this session:
+
+```bash
+python3 ./.trellis/scripts/task.py archive <task-name>
+```
+
+---
+
+## Script Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| `python3 ./.trellis/scripts/get_context.py` | Get all context info |
+| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended)** |
+| `python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>]` | Create new task directory |
+| `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task |
+| `python3 ./.trellis/scripts/task.py list` | List active tasks |