Skip to content

Task Structure

Learn how TaskGuard tasks are structured and organized.

File Format

TaskGuard tasks are Markdown files with YAML front-matter, combining structured metadata with human-readable content.

File location: tasks/{area}/{id}.md

Example: tasks/backend/backend-001.md

Anatomy of a Task File

---
id: backend-001                    # Unique task ID
title: "Implement user auth"       # Task title
status: todo                       # Current status
priority: high                     # Priority level
tags: [backend, security]          # Tags for categorization
dependencies: [setup-001]          # Task dependencies
assignee: developer                # Who's working on it
created: 2025-10-05T10:00:00Z     # Creation timestamp
estimate: 4h                       # Time estimate
complexity: 6                      # Complexity score (1-10)
area: backend                      # Task area
---

# Implement user authentication

## Context
The application needs secure user authentication using JWT tokens.

## Objectives
- Implement JWT token generation
- Create login endpoint
- Add authentication middleware

## Tasks
- [ ] Install JWT libraries
- [ ] Create auth middleware
- [ ] Implement login endpoint
- [ ] Write tests

## Acceptance Criteria
✅ **Security:**
- Passwords hashed with bcrypt
- JWT tokens expire after 24h
- Invalid tokens rejected with 401

Required Fields

id (String)

Format: {area}-{number} Example: backend-001, frontend-042

  • Auto-generated by taskguard create
  • Unique within project
  • Used for dependencies and references
  • Three-digit zero-padded number

title (String)

Example: "Implement user authentication"

  • Brief, descriptive task name
  • Shown in task lists
  • Should be action-oriented

area (String)

Options: setup, backend, frontend, api, auth, testing, deployment

  • Organizational category
  • Determines subdirectory
  • Configurable in .taskguard/config.toml

Optional Fields

status (Enum)

Options: - todo - Not started (default) - doing - In progress - review - Under review - done - Completed - blocked - Blocked by dependencies or issues

Usage: 

taskguard update status backend-001 doing

priority (Enum)

Options: - low - Nice to have - medium - Normal priority (default) - high - Important - critical - Urgent/blocking

Visual indicators: - 🔴 Critical - 🟠 High - 🟡 Medium - ⚪ Low

tags (Array)

Example: [backend, security, auth]

  • Used for categorization
  • Searchable and filterable
  • Free-form strings

dependencies (Array)

Example: [setup-001, backend-002]

  • List of task IDs this task depends on
  • Enables dependency blocking
  • Validated by taskguard validate

Example: 

dependencies: [setup-001, config-001]

This task is blocked until both setup-001 AND config-001 are done.

assignee (String)

Example: "developer" or "alice@example.com"

  • Who's responsible for the task
  • Free-form string
  • Optional

created (DateTime)

Format: ISO 8601 Example: 2025-10-05T10:00:00Z

  • Auto-generated on creation
  • Immutable
  • Used for sorting and history

estimate (String)

Example: "4h", "2d", "1w"

  • Time estimate (free-form)
  • Not enforced
  • For planning purposes

complexity (Number)

Range: 1-10 Example: 6

  • Subjective complexity score
  • Default: 3
  • Used by taskguard lint for analysis

Markdown Content

The content after the YAML front-matter is free-form Markdown.

## Context

Why this task exists and what problem it solves.

## Context
Current state: Basic auth exists but uses plain passwords.
Need to: Implement JWT-based authentication for API security.

## Objectives

What you aim to accomplish.

## Objectives
- Replace password-based auth with JWT
- Support token refresh
- Add role-based permissions

## Tasks

Checklist of specific work items.

## Tasks
- [ ] Install jsonwebtoken package
- [ ] Create JWT signing function
- [ ] Implement /auth/login endpoint
- [ ] Add token validation middleware

Update checklist items: 

taskguard task update backend-001 1 done

## Acceptance Criteria

How you know the task is complete.

## Acceptance Criteria
✅ **Login Success:**
- User can login with email/password
- Server returns valid JWT
- Token contains user ID and role

✅ **Security:**
- Passwords hashed with bcrypt
- Tokens expire after 24h

## Technical Notes

Implementation details and decisions.

## Technical Notes
- Use RS256 algorithm for JWT
- Store secret in environment variable
- Token payload: {userId, role, exp}

## Updates

Change log for the task.

## Updates
- 2025-10-05: Task created
- 2025-10-06: Started implementation
- 2025-10-07: Completed and tested

File Organization

tasks/
├── setup/
│   ├── setup-001.md
│   ├── setup-002.md
│   └── setup-003.md
├── backend/
│   ├── backend-001.md
│   ├── backend-002.md
│   └── backend-003.md
├── frontend/
│   └── frontend-001.md
└── api/
    └── api-001.md

Rules: - One task per file - Files organized by area - ID matches filename: backend-001.md contains id: backend-001

ID Generation

IDs are auto-generated by taskguard create:

  1. Determine area: From --area flag or default
  2. Find highest number: In that area's directory
  3. Increment: Next number in sequence
  4. Format: {area}-{number:03d}

Example: 

# Existing: backend-001.md, backend-002.md
taskguard create --title "New task" --area backend
# Creates: backend-003.md with id: backend-003

Best Practices

Task Titles

✅ Good: - "Implement user authentication" - "Fix database connection pooling" - "Add dark mode to settings"

❌ Bad: - "Auth" (too vague) - "Stuff to do" (not descriptive) - "Investigate issue" (unclear outcome)

Task Size

  • Sweet spot: 2-8 hours of work
  • Too small: "Change button color" → Combine with other UI tasks
  • Too large: "Build entire backend" → Break into multiple tasks

Dependencies

  • Only depend on tasks in the same project
  • Avoid circular dependencies (A → B → A)
  • Keep dependency chains manageable (<5 levels deep)

Markdown Content

  • Keep it concise (1-2 pages max)
  • Use bullet lists for scannability
  • Include code examples where helpful
  • Update ## Updates section when making changes

Editing Tasks

Via File System

vim tasks/backend/backend-001.md

Edit YAML and Markdown directly.

Via CLI

# Update status
taskguard update status backend-001 doing

# Update priority
taskguard update priority backend-001 critical

# Update dependencies
taskguard update dependencies backend-001 "setup-001,config-001"

# Update checklist item
taskguard task update backend-001 1 done

Validation

TaskGuard validates task files on every command:

taskguard validate

Checks: - Valid YAML front-matter - Required fields present - Dependencies exist - No circular dependencies - ID matches filename

Errors: 

❌ backend-001: Missing required field 'title'
❌ api-001: Depends on non-existent task 'backend-099'
❌ setup-002: Circular dependency detected (setup-002 → backend-001 → setup-002)

Next Steps