任务管理全流程
6.1 任务生命周期
create → init-context → add-context → start → implement/check → finish → archive
│ │ │ │ │ │ │
│ │ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼ ▼
创建目录 初始化JSONL 添加上下文 设为当前 开发/检查 清除当前 归档到
task.json 配置文件 条目 任务指针 循环 任务 archive/
6.2 task.py 14 个子命令详解
任务创建
# 创建任务
TASK_DIR=$(./.trellis/scripts/task.py create "添加用户登录" \
--slug user-login \ # 目录名后缀 (可选，否则自动 slugify)
--assignee alice \ # 指派人 (可选)
--priority P1 \ # 优先级: P0/P1/P2/P3 (可选，默认 P2)
--description "实现JWT登录") # 描述 (可选)
# 创建的目录: .trellis/tasks/02-27-user-login/
# 创建的文件: task.json
上下文配置
# 初始化 JSONL 配置
./.trellis/scripts/task.py init-context "$TASK_DIR" backend
# dev_type: backend | frontend | fullstack | test | docs
# 可选: --platform cursor (默认 claude)
# 添加额外上下文条目
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
"src/services/auth.ts" "Existing auth patterns"
# 目标: implement | check | debug (简写，自动加 .jsonl)
# 会自动检测是文件还是目录
# 验证所有 JSONL 引用的文件是否存在
./.trellis/scripts/task.py validate "$TASK_DIR"
# 查看所有 JSONL 条目
./.trellis/scripts/task.py list-context "$TASK_DIR"
任务控制
# 设为当前任务（Hook 会读取此指针进行注入）
./.trellis/scripts/task.py start "$TASK_DIR"
# 清除当前任务（无需参数，自动读取 .current-task）
./.trellis/scripts/task.py finish
# 设置 Git 分支名
./.trellis/scripts/task.py set-branch "$TASK_DIR" "feature/user-login"
# 设置 PR 目标分支
./.trellis/scripts/task.py set-base-branch "$TASK_DIR" "main"
# 设置 scope（用于 commit message: feat(scope): ...）
./.trellis/scripts/task.py set-scope "$TASK_DIR" "auth"
任务管理
# 列出活跃任务
./.trellis/scripts/task.py list
./.trellis/scripts/task.py list --mine # 只看自己的
./.trellis/scripts/task.py list --status review # 按状态过滤
# 归档完成的任务
./.trellis/scripts/task.py archive user-login
# 移动到 archive/2026-02/
# 列出归档任务
./.trellis/scripts/task.py list-archive
./.trellis/scripts/task.py list-archive 2026-02 # 按月过滤
# 创建 PR（委托给 multi-agent/create-pr.py）
./.trellis/scripts/task.py create-pr
6.3 task.json Schema
{
"id": "02-27-user-login",
"name": "user-login",
"title": "添加用户登录",
"description": "实现 JWT 登录流程",
"status": "in_progress",
"dev_type": "backend",
"scope": "auth",
"priority": "P1",
"creator": "alice",
"assignee": "alice",
"createdAt": "2026-02-27T10:00:00Z",
"completedAt": null,
"branch": "feature/user-login",
"base_branch": "main",
"worktree_path": null,
"current_phase": 1,
"next_action": [
{"phase": 1, "action": "implement"},
{"phase": 2, "action": "check"},
{"phase": 3, "action": "finish"},
{"phase": 4, "action": "create-pr"}
],
"commit": null,
"pr_url": null,
"subtasks": [],
"relatedFiles": [],
"notes": ""
}
planning → in_progress → review → completed
↘ rejected
6.4 JSONL 上下文配置实战
自动生成的默认配置
task.py init-context 会根据 dev_type 生成默认的 JSONL 文件：
backend 类型默认 implement.jsonl：
{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
{"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"}
{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
{"file": ".trellis/spec/backend/api-module.md", "reason": "API module conventions"}
{"file": ".trellis/spec/backend/quality.md", "reason": "Code quality requirements"}
{"file": ".claude/commands/trellis/finish-work.md", "reason": "Finish work checklist"}
{"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"}
{"file": ".claude/commands/trellis/check-backend.md", "reason": "Backend check spec"}
添加自定义上下文
# 添加现有代码作为参考（文件）
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
"src/services/user.ts" "Existing user service patterns"
# 添加整个目录（自动读取所有 .md 文件）
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
"src/services/" "Existing service patterns"
# 添加自定义 check 上下文
./.trellis/scripts/task.py add-context "$TASK_DIR" check \
".trellis/spec/guides/cross-layer-thinking-guide.md" "Cross-layer verification"
6.5 Plan Agent 与需求评估
Plan Agent 在接受需求前会进行严格评估，可能会拒绝。 5 类拒绝原因：| 拒绝类型 | 触发条件 | 示例 |
|---|---|---|
| Unclear or Vague | 没有具体结果定义 | ”Make it better”、“Fix the bugs” |
| Incomplete Information | 缺少关键实现细节 | 引用了未知系统 |
| Out of Scope | 不属于本项目 | 需要修改外部系统 |
| Potentially Harmful | 安全风险 | 故意开后门 |
| Too Large | 应该拆分 | 一次要做 6 个功能 |
task.json状态设为"rejected"- 生成
REJECTED.md包含原因和改进建议 - 任务目录保留供用户查看
Input: "Add user authentication, authorization, password reset,
2FA, OAuth integration, and audit logging"
=== PLAN REJECTED ===
Reason: Too Large / Should Be Split
Details:
This requirement bundles 6 distinct features:
1. User authentication (login/logout)
2. Authorization (roles/permissions)
3. Password reset flow
4. Two-factor authentication
5. OAuth integration
6. Audit logging
Suggestions:
- Start with basic authentication first
- Create separate features for each capability