Example: Basic Workflow

This example demonstrates a complete Track CLI workflow from project initialization to completion, building a simple todo list application.

Scenario

You're building a todo list web app with a single feature (task management) and three tasks:

Create the UI component
Add state management
Implement persistence

Step-by-Step Workflow

1. Initialize the Project

cd ~/projects/todo-app
track init "Todo List App"

Output:

✓ Project initialized: Todo List App (a1b2c3d4)
  Database: /Users/you/projects/todo-app/.track/track.db

What happened:

Created .track/ directory
Created SQLite database
Created root track with ID a1b2c3d4

2. Check Initial Status

track status

Output:

Todo List App (a1b2c3d4) [planned]

The project starts with just the root track.

3. Create the Feature Track

track new "Task Management" \
  --summary "Core feature: users can add, complete, and delete tasks" \
  --next "Start with the UI component - task list and input form"

Output:

✓ Track created: Task Management (e5f6g7h8)
  Parent: a1b2c3d4 (Todo List App)
  Status: planned
  Files: 0

4. Check Status Again

track status

Output:

Todo List App (a1b2c3d4) [planned]
└── Task Management (e5f6g7h8) [planned]

Notice the hierarchy: feature under project.

5. Create First Task: UI Component

track new "TodoList UI Component" \
  --parent e5f6g7h8 \
  --summary "Need component to display tasks and input form" \
  --next "Create TodoList.tsx with task list and input field" \
  --file src/components/TodoList.tsx

Output:

✓ Track created: TodoList UI Component (i9j0k1l2)
  Parent: e5f6g7h8 (Task Management)
  Status: planned
  Files: 1

6. Start Working on the UI Component

track update i9j0k1l2 \
  --summary "Starting work on TodoList component" \
  --next "Create component structure with task list and input" \
  --status in_progress

Output:

✓ Track updated: i9j0k1l2
  Status: in_progress
  Files: 1

7. Check Status During Work

track status

Output:

Todo List App (a1b2c3d4) [planned]
└── Task Management (e5f6g7h8) [planned]
    └── TodoList UI Component (i9j0k1l2) [in_progress]
        Files: src/components/TodoList.tsx

The tree shows your current work: TodoList UI Component is in progress.

8. Update Progress: Component Structure Done

track update i9j0k1l2 \
  --summary "Created TodoList component with basic structure. Renders task list and has input form. Using map() for tasks. Input has onChange handler. No actual functionality yet - just UI skeleton." \
  --next "Add props interface: tasks array and onAddTask callback. Wire up input to call onAddTask on submit." \
  --status in_progress

Output:

✓ Track updated: i9j0k1l2
  Status: in_progress
  Files: 1

9. Complete the UI Component

track update i9j0k1l2 \
  --summary "TodoList component complete. Props: tasks (Task[]), onAddTask (fn), onToggle (fn), onDelete (fn). Renders task list with checkboxes and delete buttons. Input form with controlled component pattern. Form submit calls onAddTask. All interactions working. Responsive CSS added." \
  --next "None - component complete and ready for integration" \
  --status done \
  --file src/components/TodoList.css

Output:

✓ Track updated: i9j0k1l2
  Status: done
  Files: 2

10. Create Second Task: State Management

track new "Add State Management" \
  --parent e5f6g7h8 \
  --summary "Need to manage task state (add, toggle, delete)" \
  --next "Create useTodos hook with useState and handlers" \
  --file src/hooks/useTodos.ts

Output:

✓ Track created: Add State Management (m3n4o5p6)
  Parent: e5f6g7h8 (Task Management)
  Status: planned
  Files: 1

11. Check Status with Multiple Tasks

track status

Output:

Todo List App (a1b2c3d4) [planned]
└── Task Management (e5f6g7h8) [planned]
    ├── TodoList UI Component (i9j0k1l2) [done]
    │   Files: src/components/TodoList.tsx, src/components/TodoList.css
    └── Add State Management (m3n4o5p6) [planned]
        Files: src/hooks/useTodos.ts

First task is done, second task is planned.

12. Work on State Management

track update m3n4o5p6 \
  --summary "Created useTodos hook with useState<Task[]>. Implemented handlers: addTask (generates ID, appends), toggleTask (finds by ID, flips completed), deleteTask (filters out by ID). All handlers working correctly." \
  --next "None - hook complete" \
  --status done

Output:

✓ Track updated: m3n4o5p6
  Status: done
  Files: 1

13. Create Third Task: Persistence

track new "Add LocalStorage Persistence" \
  --parent e5f6g7h8 \
  --summary "Tasks should persist across page refreshes" \
  --next "Add localStorage.setItem on task changes, getItem on mount"

Output:

✓ Track created: Add LocalStorage Persistence (q7r8s9t0)
  Parent: e5f6g7h8 (Task Management)
  Status: planned
  Files: 0

14. Work on Persistence

track update q7r8s9t0 \
  --status in_progress \
  --summary "Working on localStorage integration" \
  --next "Add useEffect to save tasks on change, load on mount" \
  --file src/hooks/useTodos.ts

Output:

✓ Track updated: q7r8s9t0
  Status: in_progress
  Files: 1

15. Complete Persistence

track update q7r8s9t0 \
  --summary "Added localStorage persistence to useTodos hook. useEffect saves tasks to 'todos' key on any change. Initial state loads from localStorage with fallback to empty array. Tested: tasks persist across page refresh. Works correctly." \
  --next "None - persistence complete" \
  --status done

Output:

✓ Track updated: q7r8s9t0
  Status: done
  Files: 1

16. Update Feature Track

Now that all tasks are done, mark the feature as complete:

track update e5f6g7h8 \
  --summary "Task management feature complete. UI component (TodoList.tsx), state management (useTodos hook), and localStorage persistence all implemented and tested. Users can add, complete, and delete tasks. Data persists across sessions." \
  --next "None - feature ready for testing and code review" \
  --status done

Output:

✓ Track updated: e5f6g7h8
  Status: done
  Files: 0

17. Final Status Check

track status

Output:

Todo List App (a1b2c3d4) [planned]
└── Task Management (e5f6g7h8) [done]
    ├── TodoList UI Component (i9j0k1l2) [done]
    │   Files: src/components/TodoList.tsx, src/components/TodoList.css
    ├── Add State Management (m3n4o5p6) [done]
    │   Files: src/hooks/useTodos.ts
    └── Add LocalStorage Persistence (q7r8s9t0) [done]
        Files: src/hooks/useTodos.ts

All tasks and the feature are marked done.

18. View JSON Output

track status --json

Output (truncated for readability):

{
  "tracks": [
    {
      "id": "a1b2c3d4",
      "title": "Todo List App",
      "parent_id": null,
      "summary": "",
      "next_prompt": "",
      "status": "planned",
      "kind": "super",
      "files": []
    },
    {
      "id": "e5f6g7h8",
      "title": "Task Management",
      "parent_id": "a1b2c3d4",
      "summary": "Task management feature complete. UI component...",
      "next_prompt": "None - feature ready for testing and code review",
      "status": "done",
      "kind": "feature",
      "files": []
    },
    {
      "id": "i9j0k1l2",
      "title": "TodoList UI Component",
      "parent_id": "e5f6g7h8",
      "summary": "TodoList component complete. Props: tasks...",
      "next_prompt": "None - component complete and ready for integration",
      "status": "done",
      "kind": "task",
      "files": [
        "src/components/TodoList.tsx",
        "src/components/TodoList.css"
      ]
    }
  ]
}

Quick Sanity Checks (jq)

Validate the walkthrough left three tasks and nothing planned:

track status --json | jq '{tasks: [.tracks[] | select(.kind=="task")] | length, planned: [.tracks[] | select(.status=="planned")] | length}'

Expected after finishing: tasks: 3, planned: 0.

Surface the active next step (first non-done with a breadcrumb):

track status --json | jq -r '[.tracks[] | select(.status!="done" and .next_prompt|length>0)][0].next_prompt'

Key Takeaways

Hierarchy Structure

Project (super)
└── Feature (feature)
    ├── Task 1 (task)
    ├── Task 2 (task)
    └── Task 3 (task)

Super: Root project (a1b2c3d4)
Feature: Has children (e5f6g7h8)
Tasks: Leaf nodes (i9j0k1l2, m3n4o5p6, q7r8s9t0)

Status Progression

planned → Created but not started
in_progress → Currently working on
done → Completed

Summary Evolution

Summaries became more detailed as work progressed:

Start: "Starting work on TodoList component"
Mid: "Created TodoList component with basic structure..."
End: "TodoList component complete. Props: tasks..."

Each update adds more context, building a complete picture.

File Associations

Files were associated as created:

TodoList.tsx - Added during task creation
TodoList.css - Added when completed
useTodos.ts - Added during state management task

The final status shows which files belong to which tracks.

Workflow Pattern

Initialize project - track init
Create feature - track new (defaults to root parent)
Break into tasks - track new with --parent
Work sequentially - Start task → Update → Complete → Next task
Update feature - Mark feature done when all tasks complete

Common Queries

Find in-progress work:

track status --json | jq '.tracks[] | select(.status == "in_progress")'

Count tasks by status:

track status --json | jq '[.tracks | group_by(.status)[] | {status: .[0].status, count: length}]'

Get all files:

track status --json | jq -r '.tracks[].files[]' | sort | uniq

Output:

src/components/TodoList.css
src/components/TodoList.tsx
src/hooks/useTodos.ts

List task titles:

track status --json | jq -r '.tracks[] | select(.kind == "task") | .title'

Output:

TodoList UI Component
Add State Management
Add LocalStorage Persistence

Next Steps

See AI Agent Usage Example for AI session patterns
See Complex Project Example for multi-feature projects
Read Usage Guide for detailed workflows

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Example: Basic Workflow

Scenario

Step-by-Step Workflow

1. Initialize the Project

2. Check Initial Status

3. Create the Feature Track

4. Check Status Again

5. Create First Task: UI Component

6. Start Working on the UI Component

7. Check Status During Work

8. Update Progress: Component Structure Done

9. Complete the UI Component

10. Create Second Task: State Management

11. Check Status with Multiple Tasks

12. Work on State Management

13. Create Third Task: Persistence

14. Work on Persistence

15. Complete Persistence

16. Update Feature Track

17. Final Status Check

18. View JSON Output

Quick Sanity Checks (jq)

Key Takeaways

Hierarchy Structure

Status Progression

Summary Evolution

File Associations

Workflow Pattern

Common Queries

Find in-progress work:

Count tasks by status:

Get all files:

List task titles:

Next Steps

FilesExpand file tree

basic-workflow.md

Latest commit

History

basic-workflow.md

File metadata and controls

Example: Basic Workflow

Scenario

Step-by-Step Workflow

1. Initialize the Project

2. Check Initial Status

3. Create the Feature Track

4. Check Status Again

5. Create First Task: UI Component

6. Start Working on the UI Component

7. Check Status During Work

8. Update Progress: Component Structure Done

9. Complete the UI Component

10. Create Second Task: State Management

11. Check Status with Multiple Tasks

12. Work on State Management

13. Create Third Task: Persistence

14. Work on Persistence

15. Complete Persistence

16. Update Feature Track

17. Final Status Check

18. View JSON Output

Quick Sanity Checks (jq)

Key Takeaways

Hierarchy Structure

Status Progression

Summary Evolution

File Associations

Workflow Pattern

Common Queries

Find in-progress work:

Count tasks by status:

Get all files:

List task titles:

Next Steps