Skip to content

AGENTS.md

Latest commit

 

History

History
77 lines (62 loc) · 3.2 KB

AGENTS.md

File metadata and controls

77 lines (62 loc) · 3.2 KB
Raw

track — AI Agent Instructions

track is a personal task tracker backed by a central SQLite database at ~/.track/track.db. It is designed for both humans and AI agents to read and update work items across sessions.

Quick reference

track init                        # Initialize project in current directory (shorthand)
track init --name api             # Initialize with custom project name
track project init                # Same as above (explicit form)
track project list                # List all tracked projects
track item add "title" [--summary "..."] [-t tracker] [-p high|medium|low]
track item list                   # Open items in current project
track item list --all             # Open items across ALL projects
track item list -s in_progress    # Filter by status
track item list -t testing        # Filter by tracker name
track item show <ID>              # Full item detail (includes description)
track item edit <ID> [--title "..."] [--priority high] [--tags a,b]
track item start <ID>             # → in_progress
track item done  <ID>             # → done
track item block <ID>             # → blocked
track item defer <ID>             # → deferred
track item reopen <ID>            # → open (undo done/blocked/deferred)
track item delete <ID>            # Remove an item permanently
track item next                   # High-priority open items
track tracker add <name> <prefix> # Add a named tracker (e.g. "track tracker add testing T")
track tracker list                # List trackers with item counts
track note add "..." [--tags decision,storage]
track note list [--tag <tag>] [--all]
track note show <ID>              # Full detail for a single note
track note delete <ID>            # Remove a note permanently
track --json <cmd>                # Any command: output as JSON (also works as: track <cmd> --json)

Status transitions

Items follow a defined state machine. Invalid transitions are rejected with a helpful error:

open → in_progress, blocked, deferred, done, wont_do
in_progress → done, blocked, deferred, open
blocked → open, in_progress, deferred, wont_do
deferred → open, in_progress, blocked, wont_do
done → open, in_progress
wont_do → open

Use track item reopen <ID> to move a done/blocked/deferred item back to open.

Typical agent workflow

# Start of session: orient
track item list --all             # What's open?
track note list --tag decision    # What did we decide?

# During session: update status
track item start T03

# End of session: persist decisions
track item done T03
track note add "Chose X over Y because Z" --tags decision,architecture

Key concepts

  • Item ID: per-tracker prefix + number (e.g. T04, I01). IDs are globally unique across projects.
  • Tracker: named group of related items (inbox, testing, tui-polish, etc.)
  • Note: persistent cross-session knowledge (decisions, context, rationale)
  • JSON output: use --json for machine-readable output
  • Status transitions: validated — e.g. you can't go directly from done to blocked

Environment

  • Database: ~/.track/track.db (override with --db or TRACK_DB env var)
  • Binary: track (install with cargo install --path crates/track-cli)