@jahanxu/trellis 0.4.2 → 0.5.0

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

@@ -1,515 +1,145 @@
-# Pick Task - 从任务池选择上游产出
+# Pick Task - Select Upstream Deliverable and Start Working
 
-从上游产出池选择一个任务开始开发，自动创建任务目录并注入上游产出。
+Pick a deliverable from an upstream pool, create a task directory, and inject upstream context.
 
 ---
 
-## 使用场景
+## Usage
 
-| 当前角色 | 从哪个池子选择 | 选择什么 |
-|---------|--------------|---------|
-| **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 是起点）
-
-**如果角色不匹配**：
+/trellis:pick-task <pool> <id>
 ```
-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>
-```
+- `<pool>`: `requirements` (for Designers) or `prototypes` (for Frontend)
+- `<id>`: deliverable ID to pick (e.g., `user-login`)
 
 ---
 
-### Step 2: 列出可用任务
+## Process `[AI]`
 
-调用 pool.py 列出指定池子的任务：
+### Step 1: Validate Role
 
 ```bash
-python3 .trellis/scripts/pool.py list <pool-type> --status available
+python3 ./.trellis/scripts/get_context.py
 ```
 
-**输出示例**：
-```
-=== Requirements Pool ===
-
-Available (2):
-  • user-login: 用户登录功能
-    Completed by: pm-alice
-    Path: deliverables/requirements/user-login
+Read the developer name from `.developer` file. Parse role from `{role}-{name}` convention.
 
-  • payment: 支付功能
-    Completed by: pm-alice
-    Path: deliverables/requirements/payment
+Validate role-pool match:
+- `designer` can pick from `requirements`
+- `frontend` / `frontend-impl` can pick from `prototypes`
+- `pm` should NOT pick from pools (PMs create tasks directly)
 
-Consumed (0):
-  (none)
-```
-
-**AI 展示给用户**：
-```
-可用的 requirements 任务：
+If role cannot be parsed, warn but continue (soft detection).
 
-1. user-login - 用户登录功能
-   完成人: pm-alice
-   路径: deliverables/requirements/user-login
+### Step 2: Check Pool Availability
 
-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
-
-如需重新处理，请联系消费者或创建新任务
+python3 ./.trellis/scripts/pool.py status <pool> <id>
 ```
 
----
-
-### Step 4: 读取上游 HANDOFF 文档
-
-**HANDOFF 文档路径**：
-```python
-handoff_path = task["handoff_doc"]  # 例如：deliverables/requirements/user-login/HANDOFF.md
-```
-
-**读取并展示给用户**（可选）：
-```
-AI 提示：
-  "即将基于以下上游产出创建任务：
-
-   === 上游交接文档摘要 ===
-   功能ID: user-login
-   功能名称: 用户登录功能
-   完成人: pm-alice
-
-   核心需求：
-   - 支持邮箱+密码登录
-   - 支持第三方登录（微信、GitHub）
-   ...
+Verify the item:
+- Exists in the pool
+- Status is `available` (not `consumed`)
 
-   是否继续？[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}"
+If not available, list what IS available:
+```bash
+python3 ./.trellis/scripts/pool.py list <pool>
 ```
 
-**注意**：按角色隔离任务目录
+### Step 3: Check Current Task
 
-**创建目录**：
-```bash
-mkdir -p <task_dir>
-```
+If there is already a current task set, ask:
+> "You have an active task: `<current-task>`. Would you like to finish it first, or switch to the new task?"
 
----
+If user wants to continue, proceed.
 
-### Step 6: 生成 task.json
+### Step 4: Create Task Directory
 
-**基本信息**：
-```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": ""
-}
-```
+Determine task suffix based on pool:
+- `requirements` pool -> `{id}-prototype`
+- `prototypes` pool -> `{id}-impl`
 
-**写入文件**：
 ```bash
-echo '<task-json>' > <task_dir>/task.json
+TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <id>-<suffix>)
 ```
 
----
+### Step 5: Write source.json
 
-### Step 7: 生成 source.json
+Create `source.json` in the task directory to reference upstream:
 
-**引用上游产出**：
 ```json
 {
   "based_on": {
-    "type": "<pool-type-singular>",
-    "id": "<task-id>",
-    "path": "<上游产出路径>",
-    "handoff_doc": "<上游 HANDOFF 路径>"
+    "type": "<requirement|prototype>",
+    "id": "<id>",
+    "path": "<deliverable path>",
+    "handoff_doc": "<path>/HANDOFF.md"
   }
 }
 ```
 
-**pool-type 转换**：
-- `requirements` → `requirement`
-- `prototypes` → `prototype`
-
-**写入文件**：
+Write this file:
 ```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": "上游交接文档"}
+cat > "$TASK_DIR/source.json" << 'EOF'
+{content}
+EOF
 ```
 
-#### 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: 消费任务（更新池子状态）
+### Step 6: Configure Context (JSONL)
 
-调用 pool.py 标记任务为已消费：
+Initialize context files for the task:
 
 ```bash
-python3 .trellis/scripts/pool.py consume <pool-type> <task-id> <当前开发者>
+python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" frontend
 ```
 
-**池子状态变化**：
-- 任务从 `available` 列表移动到 `consumed` 列表
-- 添加 `consumed_by` 和 `consumed_at` 字段
-
----
-
-### Step 10: 设置为当前任务
+Add upstream deliverable files and role specs to context:
 
 ```bash
-python3 .trellis/scripts/task.py start <task_dir>
-```
+# Add role spec
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement ".trellis/spec/roles/<role>/index.md" "Role guidelines"
 
-**效果**：
-- 更新 `.trellis/.current-task` 为新任务路径
-- Hook 会自动注入上游产出
+# Add upstream HANDOFF doc
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<handoff_doc>" "Upstream handoff document"
 
----
-
-### 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
+# Add upstream deliverable directory files
+# (add each significant file from the upstream output)
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<upstream_file>" "Upstream deliverable"
 ```
 
-### 错误场景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 的需求
+### Step 7: Consume from Pool
 
 ```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"
+python3 ./.trellis/scripts/pool.py consume <pool> <id> <developer>
 ```
 
----
-
-## 高级功能（可选）
+### Step 8: Activate Task
 
-### 批量查看任务
 ```bash
-# 用户可以不指定任务ID，先查看列表
-/trellis:pick-task requirements
-
-AI 展示列表，等待用户选择
+python3 ./.trellis/scripts/task.py start "$TASK_DIR"
 ```
 
-### 任务预览
-```bash
-# 在选择任务前预览 HANDOFF 内容
-/trellis:pick-task requirements user-login --preview
-
-AI 只展示 HANDOFF 摘要，不创建任务
-```
+### Step 9: Read Upstream Context
 
----
+Read and summarize the upstream deliverables for the user:
 
-## 注意事项
+1. Read the HANDOFF.md document
+2. List all upstream files
+3. Summarize key points the user should know
 
-1. **角色隔离**：任务目录按角色隔离（`.trellis/tasks/{role}/`）
-2. **上游注入**：`source.json` 确保 Hook 能找到上游产出
-3. **池子状态**：成功 pick 后，任务从 `available` 变为 `consumed`
-4. **防重复**：如果任务目录已存在，拒绝创建（或提示用户确认覆盖）
+### Step 10: Report
 
----
+```
+Task picked and ready!
+- Task: <task-dir>
+- Based on: <pool>/<id>
+- Upstream: <deliverable-path>
+- Role specs loaded: .trellis/spec/roles/<role>/
 
-## 命令别名（可选）
+Key points from upstream HANDOFF:
+- (summary point 1)
+- (summary point 2)
 
-用户可能使用以下变体，AI 应识别并执行相同逻辑：
-- `/trellis:pick-task`
-- `/pick-task`
-- `/pick`
-- "从需求池选择任务"
-- "选择原型任务"
+What would you like to work on first?
+```