Creating Tasks from Code
Depth:
When you spot a TODO, a design problem or a bug while reading a file, you can create a task that points at those lines without leaving the code browser. The task records them in its file_references field, so the agent that implements it starts with that context, and the board can take you back to the code later.
Create a task from the code browser
- Run
ait codebrowserand open the file. - Select the lines with Shift+Up / Shift+Down or by dragging with the mouse. Without a selection of at least two lines, the task references the whole file.
- Press n. A dialog opens with a create command that already carries the reference, such as
--file-ref lib/auth.py:42-68. - Optionally edit the command. Adding
--auto-mergefolds pending tasks that already reference the same file into the new one without asking (see step 6). - Choose Run in terminal on the Direct tab, or Run in tmux on the Tmux tab.
- Walk through the usual create flow, which starts by listing the reference it was given, and finalize the task. If pending tasks (status
ReadyorEditing) already reference the same file, you are asked whether to fold them into the new task. Answer No to keep them separate; they are then listed as a warning.
The committed task carries file_references: [lib/auth.py:42-68]. Because it has a file reference, it also records the commit it was created at as its premise_baseline, so the premise staleness check can tell you, when the task is picked, whether those files changed in the meantime.
The codebrowser reference lists which reference each selection produces, and ait create describes which tasks are folded and what folding does to them.
Open a task’s code from the board
- In
ait board, press Enter on a task card to open Task Detail. - Move to the File Refs row with Up / Down or Tab, and press Enter. If the task has several references, pick one from the list.
The codebrowser in your project’s tmux session shows the file at the referenced lines. This needs the project’s tmux session to be running, though the board itself can run outside tmux; the board reference has the details.
Do it from the command line
ait create and ait update take references as flags:
# Create a task from a line range and fold pending tasks that reference the same file
ait create --batch --commit \
--name "rework_token_validation" --priority medium --effort medium \
--type refactor --labels "auth,tech-debt" \
--file-ref "lib/auth.py:42-68" \
--auto-merge \
--desc "Rework the token validation path"
# Several references, one of them with two ranges on the same file
ait create --batch --commit \
--name "login_cleanup" \
--file-ref "lib/login.py:10-20^89-100" \
--file-ref "lib/auth.py:42-68" \
--desc "Unify login edge cases"
# Add a reference to task 42 and remove an old one
ait update --batch 42 \
--file-ref "lib/auth.py:100-150" \
--remove-file-ref "lib/auth.py:42-68"
--file-ref is repeatable on both commands, and --remove-file-ref removes the entry that matches it exactly. Without --auto-merge, a batch create folds nothing: it lists the overlapping pending tasks as a warning.
To see which pending tasks already reference a file before you create one, run the aitask_find_by_file.sh script with the file’s path; Finding tasks by file reference describes how to call it and what it prints.
See also
- Task Format: the
file_referencessyntax and the rest of the frontmatter schema - Code Browser: the n key in context; the overview’s Creating Tasks from Code section walks through it
- Board How-To: the File Refs row among the other relationship fields
/aitask-create: the skill that drives the interactive create flow- Follow-Up Tasks: capturing tasks during implementation