Tracks

Tasks and goals for active work.

Tracks represent work that is moving toward completion. Use tracks when something has status, ownership, a due date, dependencies, or progress.

Track types

Type	Use for	Status values
`task`	Concrete units of work	`backlog`, `todo`, `in_progress`, `done`
`goal`	Outcomes with progress	`not_started`, `on_track`, `at_risk`, `postponed`, `completed`

Tasks are operational. Goals are outcome-oriented. A task can link to a goal through goalId.

Task and goal dueDate values use YYYY-MM-DD. On update, passing an empty string clears optional date fields. Task status, parentId, and goalId can also be cleared with an empty string where supported.

Task fields

Tasks can include:

Field	Meaning
`status`	Current task state
`dueDate`	Date in `YYYY-MM-DD` format
`assignee`	Workspace user ID or installed agent ID
`parentId`	Parent task ID
`dependsOn`	IDs of tasks that must happen first
`goalId`	Goal this task contributes to

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

Goal fields

Goals include status, dueDate, and progress. Progress is an integer from 0 to 100.

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

Bulk planning

Use bulk apply when an agent or script needs to create multiple related tracks from scratch. If the structure already exists as a workflow pack, use a pack run instead. Non-UUID ids create new records and can be referenced by other upserts in the same request.

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

The server resolves t001 and t002 into real UUIDs after creation.

Type inference in bulk apply

In upserts, the server infers the track type from the presence of task or goal. Include task and omit goal for a task. Include goal and omit task for a goal. Passing both in the same upsert is invalid.

New tracks require title. Existing tracks (UUID id) use PATCH semantics: omitted fields keep their current value.

Reviews

A review (also referred to as a Learning Review) is a generated, read-only analysis of one or more tasks or goals. It collects the target tracks, linked goals/tasks, child/dependency tasks, logs, and source workflow/context packs to extract reusable learning and suggest next actions (e.g., creating/updating a pack or suggesting a change).

When reviews appear

Epismo may return a lightweight review object containing basic stats during status updates when a track reaches a reviewable outcome:

Track type	Trigger status	Why it matters
`task`	`done`	Extract local execution notes and reusable steps.
`goal`	`completed`	Capture successful processes and decision criteria.
`goal`	`postponed`	Capture assumptions, risks, and lessons from a pivot or delay.

For a detailed Markdown review containing in-depth generated content, run a manual review using the API (POST /v1/tracks/review) or the CLI (epismo track review). Detailed reviews consume credits based on AI token usage, whereas lightweight status-update reviews are free.

See Logs for the comment/activity timeline attached to a track.