トラック

進行中の作業を表すタスクとゴールです。

トラックは、完了に向かって進む作業を表します。ステータス、担当者、期限、依存関係、進捗を持つものはトラックにします。

トラックの種類

種別	用途	ステータスの値
`task`	具体的な作業単位	`backlog`, `todo`, `in_progress`, `done`
`goal`	進捗を持つ成果目標	`not_started`, `on_track`, `at_risk`, `postponed`, `completed`

タスクは実務的な作業です。ゴールは成果を志向した目標です。タスクは goalId でゴールに紐づけられます。

タスクとゴールの dueDate は YYYY-MM-DD です。更新で空文字を渡すと、任意の日付項目をクリアできます。タスクの status, parentId, goalId も、対応箇所では空文字でクリアできます。

タスクの項目

タスクは次の項目を持てます。

項目	意味
`status`	現在のタスクの状態
`dueDate`	`YYYY-MM-DD` 形式の日付
`assignee`	ワークスペースのユーザー ID またはインストール済みエージェント ID
`parentId`	親タスクの ID
`dependsOn`	先に完了すべきタスクの ID
`goalId`	このタスクが貢献するゴール

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

ゴールの項目

ゴールは status, dueDate, progress を持ちます。進捗は0から100の整数です。

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

まとめて計画する

エージェントやスクリプトが複数の関連トラックを作る場合は一括適用を使います。非 UUID の id は新規作成として扱われ、同じリクエスト内の他の作成・更新から参照できます。

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

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

一括適用での型推論

upserts では、task または goal の存在からサーバーがトラックの種別を推論します。タスクなら task を含め goal を省略します。ゴールなら goal を含め task を省略します。同じ作成・更新に両方を渡すと不正です。

新規トラックには title が必要です。既存トラック（UUID の id）は PATCH 方式で、省略した項目は維持されます。