> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 附录 C：task.json Schema 参考

## 附录 C：`task.json` Schema 参考

对齐 `.trellis/scripts/common/task_store.py` 里 `task.py create` 当前写出的结构：

```json theme={null}
{
  "id": "string", // 任务 ID（= slug，如 02-27-user-login）
  "name": "string", // Slug 名（单仓库下和 id 相同；monorepo 可能不同）
  "title": "string", // 任务标题
  "description": "string", // 描述（不传 --description 时为 ""）
  "status": "string", // planning（默认）| in_progress | completed；task.py list --status 还接受 review
  "dev_type": "string", // backend | frontend | fullstack | test | docs（默认 null，由手工编辑或自定义 hook 填入）
  "scope": "string", // Commit scope，如 "auth"（set-scope 前为 null）
  "package": "string", // Monorepo 包名（单仓库为 null）
  "priority": "string", // P0 | P1 | P2 | P3（默认 P2）
  "creator": "string", // 创建者 id
  "assignee": "string", // 指派人 id
  "createdAt": "string", // YYYY-MM-DD 创建日期
  "completedAt": "string", // YYYY-MM-DD 完成日期（未完成为 null）
  "branch": "string", // Feature 分支名（set-branch 前为 null）
  "base_branch": "string", // PR 目标分支（创建时按当前分支记录）
  "worktree_path": "string", // Schema 占位——创建时写 null，没有脚本会填
  "commit": "string", // Schema 占位——创建时写 null，没有脚本会填
  "pr_url": "string", // Schema 占位——创建时写 null，没有脚本会填
  "subtasks": [], // 任务内部的 todo checklist（{name, status} 对），与 children 无关
  "children": [], // 子任务目录名数组（父→子链接）
  "parent": "string", // 父任务目录名（顶层任务为 null）
  "relatedFiles": [], // 相关文件列表
  "notes": "string", // 备注（默认 ""）
  "meta": {} // 项目级元数据（如 Linear issue id）
}
```

字段顺序与 `.trellis/scripts/common/task_store.py` 里 `task_data` 一致——`task.py` 就按这个顺序写入。

<Note>
  `worktree_path` / `commit` / `pr_url` 是 schema 占位字段，创建时写 null 之后没有 Trellis
  脚本再动它们。想记 commit hash 或 PR URL 请用 `meta: {}` 自定义键，或写个 `after_archive` hook
  自己回写。
</Note>

早期版本创建的老任务可能少某些新字段（如 `package` 支持前的任务没有 `"package"` 键），`task.py` 把缺失字段按 null 处理，不会出错。

### 父子关系 vs `subtasks`——别混

| 字段         | 含义                                                                   |
| ---------- | -------------------------------------------------------------------- |
| `parent`   | 父任务的目录名；顶层任务为 `null`。由 `task.py create --parent` 或 `add-subtask` 设置。 |
| `children` | 子任务目录名数组，与子任务的 `parent` 双向维护。                                        |
| `subtasks` | **单个任务内部的** `{name, status}` todo checklist。bootstrap 任务用到；和子任务关系无关。 |

***