task-track 0.7.0

A JJ workspace-based task and TODO management CLI tool
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

# Task Execution — Detailed Guide

Complete workflow for working through TODOs and completing tasks.

**Skill:** [track-task-execute](../SKILL.md) · **Setup:** [track-task-setup](../../track-task-setup/SKILL.md) · **Archive:** [track-advanced](../../track-advanced/SKILL.md)

## When to Use

- `workflow.phase` is `sync_required` or `execute`
- Ready to implement changes
- Working through a task's TODO list

## Prerequisites

- Task created with TODOs
- Repos registered (if using workspaces)

## Step-by-Step Workflow

### Step 1: Read JSON Context

```bash
track status --json
```

Follow `workflow.next_action.command` — do not guess the next step.

Key fields:

| Field | Action |
|-------|--------|
| `workflow.phase` | `sync_required` → sync; `execute` → work TODO |
| `todos_agent[].is_next` | Current TODO |
| `todos_agent[].allowed_actions` | Only listed actions (no reopen) |
| `guardrails.must_sync_before_code_changes` | Run `track sync` before edits |

---

### Step 2: Sync and Verify Bookmark

```bash
track sync
jj status
jj bookmark list -r @
```

Stop if bookmark is `main` / `master` / `develop`.

---

### Step 3: Navigate to Workspace

```bash
cd "$(track todo workspace <index>)"
jj status
```

---

### Step 4: Implement and Test

```bash
jj describe -m "<summary>"
# run project tests / linters
```

---

### Step 5: Record Progress

```bash
track scrap add "<note>"
```

---

### Step 6: Complete TODO

```bash
track todo done <index>
```

**Never** `track todo update <index> done` — that skips JJ merge.

**Never** reopen done/cancelled TODOs — add a new TODO instead.

---

### Step 7: Repeat

Re-run `track status --json` until `workflow.phase` is `task_complete`.

---

## Complete Example

```bash
track status --json
track sync
cd "$(track todo workspace 2)"
# ... implement, test ...
jj describe -m "Implement Google OAuth flow"
track scrap add "Completed Google OAuth. Tests passing."
track todo done 2
track status --json
```

---

## Task Completion

When all TODOs are done:

1. `track status --json` — confirm `task_complete`
2. `track scrap list` — review notes
3. `jj git push --bookmark task/PROJ-123`
4. Switch to **track-advanced** for archive/handoff

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `todo done` fails (dirty workspace) | `jj describe`, retry |
| Workspace missing | `track sync` |
| Wrong bookmark | `track sync`, verify with `jj status` |

## Quick Reference

| Command | Purpose |
|---------|---------|
| `track status --json` | Machine-readable context |
| `track sync` | Bookmarks + workspaces |
| `track scrap add` | Record progress |
| `track todo done <index>` | Complete + JJ merge |
| `jj describe -m "..."` | Describe changes |