Tracks

進行中の作業を表す task と goal です。

Track は、完了に向かって進む作業を表します。Status、担当者、期限、依存関係、progress を持つものは track にします。

Track types

Type	用途	Status values
`task`	具体的な作業単位	`backlog`, `todo`, `in_progress`, `done`
`goal`	Progress を持つ成果目標	`not_started`, `on_track`, `at_risk`, `postponed`, `completed`

Task は operational な作業です。Goal は outcome-oriented な目標です。Task は goalId で goal に紐づけられます。

Task と goal の dueDate は YYYY-MM-DD です。Update で空文字を渡すと optional date fields を clear できます。Task status, parentId, goalId も対応箇所では空文字で clear できます。

Task fields

Task は次の field を持てます。

Field	意味
`status`	現在の task state
`dueDate`	`YYYY-MM-DD` 形式の日付
`assignee`	Workspace user ID または installed agent ID
`parentId`	Parent task ID
`dependsOn`	先に完了すべき task IDs
`goalId`	この task が貢献する goal

{
	"type": "task",
	"title": "Review API docs",
	"scope": { "type": "personal" },
	"task": {
		"status": "todo",
		"dueDate": "2026-06-05"
	}
}

Goal fields

Goal は status, dueDate, progress を持ちます。Progress は 0 から 100 の整数です。

{
	"type": "goal",
	"title": "Ship docs v1",
	"scope": { "type": "projects", "ids": ["project-id"] },
	"goal": {
		"status": "on_track",
		"progress": 40
	}
}

Bulk planning

Agent や script が複数の関連 track を作る場合は bulk apply を使います。非 UUID の draft ID は新規作成として扱われ、同じ request 内の他 draft から参照できます。

{
	"scope": { "type": "personal" },
	"updateDrafts": [
		{ "id": "t001", "title": "Task A", "task": { "status": "todo" } },
		{ "id": "t002", "title": "Task B", "task": { "status": "todo", "dependsOn": ["t001"] } }
	]
}

Server は作成後に t001 や t002 を実際の UUID に解決します。

Type inference in bulk apply

updateDrafts では、server が task または goal の存在から track type を推論します。Task なら task を含め goal を省略します。Goal なら goal を含め task を省略します。同じ draft に両方を渡すと invalid です。

New draft には title が必要です。既存 UUID draft は PATCH semantics で、省略した fields は維持されます。