Skip to content

Task File Format

Tasks in TaskRepo are stored as markdown files with YAML frontmatter.

File Structure

Tasks are stored in the tasks/ subdirectory of each repository:

tasks-work/
├── tasks/
│   ├── task-a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b.md
│   ├── task-b4e8f3a1-5c6d-4e2f-8a9b-1c2d3e4f5a6b.md
│   └── task-c5f9e4b2-6d7e-4f3a-9b1c-2d3e4f5a6b7c.md
└── archive/
    └── task-d6a1f5c3-7e8f-4a4b-1c2d-3e4f5a6b7c8d.md

Filename Convention

task-{uuid}.md
  • Prefix: Always task-
  • UUID: Globally unique identifier (UUID v4)
  • Extension: .md (markdown)

Example: task-a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b.md

File Format

Complete Example

---
uuid: 'a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b'
title: Fix authentication bug
status: pending
priority: H
project: backend
assignees:
  - '@alice'
  - '@bob'
tags:
  - bug
  - security
links:
  - https://github.com/org/repo/issues/123
  - https://mail.google.com/mail/u/0/#inbox/abc123
due: '2025-11-15T00:00:00'
created: '2025-10-20T10:30:00'
modified: '2025-10-20T14:22:00'
depends:
  - 'b4e8f3a1-5c6d-4e2f-8a9b-1c2d3e4f5a6b'
---

## Description

The login endpoint is not properly validating JWT tokens.

## Steps to reproduce

1. Attempt to login with expired token
2. Observe that access is granted

## Solution

Update JWT validation middleware to check expiration.

Structure

  1. YAML frontmatter (between --- delimiters)
  2. Task metadata

  3. Structured data in YAML format

  4. Markdown body (after second ---)

  5. Task description
  6. Free-form markdown content
  7. Optional sections

YAML Frontmatter Fields

Required Fields

uuid

Type: String (UUID v4) Format: 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx' Required: Yes Generated: Automatically on task creation

Globally unique identifier for the task. Never changes after creation.

uuid: 'a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b'

title

Type: String Required: Yes Constraints: Non-empty

Short description of the task (typically one line).

title: Fix authentication bug

status

Type: String Required: Yes Values: pending, in-progress, completed, cancelled

Current state of the task.

status: pending

Status meanings: - pending - Not started - in-progress - Currently being worked on - completed - Finished successfully - cancelled - Abandoned or no longer relevant

created

Type: String (ISO 8601 timestamp) Required: Yes Generated: Automatically on task creation

Timestamp when task was created.

created: '2025-10-20T10:30:00'

modified

Type: String (ISO 8601 timestamp) Required: Yes Updated: Automatically on any task modification

Timestamp of last modification.

modified: '2025-10-20T14:22:00'

Optional Fields

priority

Type: String Values: H (High), M (Medium), L (Low) Default: From config (default_priority)

Task priority level.

priority: H

project

Type: String Optional: Yes

Project or category the task belongs to.

project: backend

Display: Color-coded in task lists for visual grouping

assignees

Type: List of strings Format: GitHub handles with @ prefix Optional: Yes

People assigned to the task.

assignees:
  - '@alice'
  - '@bob'

Validation: Must start with @ Default: Uses default_assignee from config if set and no assignees provided

tags

Type: List of strings Optional: Yes

Tags for categorization and filtering.

tags:
  - bug
  - security
  - urgent

Usage: Supports filtering via --tag option

Type: List of strings (URLs) Optional: Yes Validation: Must be valid HTTP/HTTPS URLs

Associated URLs (GitHub issues, PRs, emails, documentation, etc.).

links:
  - https://github.com/org/repo/issues/123
  - https://github.com/org/repo/pull/456
  - https://mail.google.com/mail/u/0/#inbox/abc123
  - https://docs.example.com/api/auth

Display: Shown with 🔗 indicator in task lists

due

Type: String (ISO 8601 timestamp) Optional: Yes

Due date/time for the task.

due: '2025-11-15T00:00:00'

Display: Shown as countdown ("3 days", "1 week", etc.) in task lists Overdue: Displayed in red if past current date

depends

Type: List of strings (UUIDs) Optional: Yes

UUIDs of tasks that must be completed before this task can start.

depends:
  - 'b4e8f3a1-5c6d-4e2f-8a9b-1c2d3e4f5a6b'
  - 'c5f9e4b2-6d7e-4f3a-9b1c-2d3e4f5a6b7c'

Note: Dependency resolution is planned for future versions

Markdown Body

The content after the YAML frontmatter is free-form markdown.

Common Sections

While not enforced, these sections are commonly used:

## Description

High-level overview of the task.

## Context

Why this task is needed, background information.

## Steps to reproduce

(For bugs) How to reproduce the issue.

## Acceptance criteria

What needs to be done for the task to be considered complete.

## Solution

Proposed or implemented solution.

## Notes

Additional information, links, references.

Markdown Features

Full markdown is supported:

  • Headings: ##, ###, etc.
  • Lists: Bullet and numbered
  • Code blocks: With syntax highlighting
  • Links: [text](url)
  • Images: ![alt](url)
  • Tables: For structured data
  • Blockquotes: For emphasis
  • Bold/italic: Standard markdown formatting

File Encoding

  • Encoding: UTF-8
  • Line endings: Unix (LF) or Windows (CRLF) - both supported
  • BOM: Not required, but accepted if present

Task Lifecycle

Creation

  1. Task created with tsk add
  2. UUID generated via uuid.uuid4()
  3. File created as tasks/task-{uuid}.md
  4. Initial commit to git

Modification

  1. Task edited via tsk edit or direct file edit
  2. modified timestamp updated automatically (if using CLI)
  3. Changes committed to git (manual or via tsk sync)

Completion

  1. Task marked complete with tsk done
  2. Status changed to completed
  3. Task remains in tasks/ directory

Archiving

  1. Task archived with tsk archive
  2. File moved to archive/ subdirectory
  3. No longer appears in default task listings
  4. Can be unarchived with tsk unarchive

Deletion

  1. Task deleted with tsk del
  2. File permanently removed
  3. Git commit records deletion

Display IDs vs UUIDs

UUIDs

  • In file: Tasks use UUIDs internally
  • Globally unique: Safe across all repositories
  • Permanent: Never changes

Display IDs

  • For users: Simple numbers (1, 2, 3...)
  • Cached: Stored in ~/.TaskRepo/id_cache.json
  • Temporary: Mapping may change as tasks are added/removed

Example: 

Display ID  →  UUID
---------      ------------------------------------
1           →  a3f2e1d9-4b7c-4e3f-9a1b-2c3d4e5f6a7b
2           →  b4e8f3a1-5c6d-4e2f-8a9b-1c2d3e4f5a6b
3           →  c5f9e4b2-6d7e-4f3a-9b1c-2d3e4f5a6b7c

In CLI: Use display IDs (e.g., tsk edit 1) In files: Always use UUIDs (e.g., in depends field)

Validation

TaskRepo validates task files when reading:

Required Field Validation

  • UUID must be present and valid UUID format
  • Title must be non-empty
  • Status must be valid value
  • Created and modified must be valid timestamps

Optional Field Validation

  • Priority must be H/M/L if present
  • Assignees must start with @ if present
  • Links must be valid HTTP/HTTPS URLs if present
  • Due date must be valid timestamp if present
  • Depends must be valid UUIDs if present

Invalid Tasks

Tasks failing validation: - Show warning in CLI output - Are skipped in task listings - Can be fixed by editing the file directly

Direct File Editing

You can edit task files directly with any text editor:

# Find task file by display ID
tsk list  # See display ID

# Edit with your editor
vim ~/tasks/tasks-work/tasks/task-{uuid}.md

After editing: - Ensure YAML syntax is valid - Update modified timestamp (or let CLI do it next time) - Commit changes with git

Advantages of direct editing: - Full control over content - Batch editing with scripts - Integration with other tools

Git Integration

Task files are version-controlled with git:

# View task history
cd ~/tasks/tasks-work
git log tasks/task-{uuid}.md

# See changes
git diff tasks/task-{uuid}.md

# Revert changes
git checkout tasks/task-{uuid}.md

Next Steps