# Nytid Todo

> Manages work items via nytid todo subcommands as worker dan-claude. Relevant when the user asks to check, start, or complete tasks, view task details, add progress notes, create subtasks, reprioritize items, or import/sync GitHub issues. Also triggered by "what should I work on next?", "show my tasks", "mark that done", "what's in progress?", or mentions of nytid, todo, or work items. Also use when handing the user a batch of follow-ups from a session ("add todos to my nytid", papers to download, things only the user can do) and when a todo should resume the current Claude session (`claude --resume`) in a given working directory.

- Skill: `dbosk/nytid-todo` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dbosk/nytid-todo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dbosk/nytid-todo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: dbosk (https://skillmd.com/u/dbosk)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/dbosk/nytid-todo

---


# Managing work with `nytid todo`

## Identity: always use `--who dan-claude`

Every `nytid todo` command defaults to the current system user (`dbosk`). **Pass
`--who dan-claude` on every invocation** — listing, adding, starting,
completing, everything. Forgetting this flag means reading or modifying the
wrong person's tasks.

Omitting or widening `--who` is acceptable when *reading* tasks to get context
(see "Getting context from other assignees" below). **Never modify tasks that
are not assigned to `dan-claude`.**

### Exception: user-owned work (omit `--who`)

`dan-claude` is a delegated worker for code/tooling tasks, not a stand-in
for the user. When the todo is something **only the user can do**, **omit
`--who`** entirely so it defaults to the current user (`dbosk`):

- **Email-derived todos** — when the `inbox-info` skill is active and the
  user is converting flagged emails into todos. Assigning email replies to
  `dan-claude` mis-routes human communication. See
  `~/.claude/skills/inbox-info/references/todo-conversion-rules.md`.
- **Batches of follow-ups the user asked to have "in my nytid"** — e.g.
  papers to fetch through the library proxy, credentials to obtain, people
  to contact. See "Handing the user follow-ups from a session" below.

All other `nytid todo` work still uses `--who dan-claude`.

## Discovering options

Each subcommand has its own `--help` flag. Always consult it for exact syntax,
available flags, and defaults:

```
nytid todo <subcommand> --help
```

The rest of this document describes workflows, not exact command syntax.

## Core workflows

### See what to work on

Use `ls` to list your tasks sorted by effective priority. Key options control
depth (`--all` for subtasks), count limits, status filters, and output format —
check `ls --help`. The default shows only top-level items; use `--all` or
`--flat` to see the full hierarchy.

Use `status` to see the currently active task stack (what is already in
progress). Use `next` to let the system pick the highest-priority pending task.

### Work on a task

The task lifecycle follows a stack model:

1. **Start** a task with `start` (or let `next` pick one). This pushes it onto
   the active stack and optionally spawns a shell in the task's working
   directory.
2. **Stop** pauses the task and pops it from the stack without completing it.
3. **Done** marks the task complete and pops it from the stack.

Check `start --help` for options like tmux integration, timeouts, and working
directory handling.

If a task is already in progress, `next` will start its highest-priority pending
child rather than a new top-level task — this is how you drill into subtasks.

### Get context on a task

Use `view` to see full details of a task (title, description, labels, deadline,
estimate, notes, parent/child relationships). Without an ID it shows the
currently active task.

### Update tasks and leave notes

Use `edit` to change metadata (title, description, deadline, estimate, labels,
assignment, parent). Use `note` to append progress updates, blockers, or
decisions. Both support `--help` for available options.

Prefer `note` for incremental updates (progress, findings, blockers) and `edit`
for structural changes (reassignment, deadline shifts, re-parenting).

### Create subtasks

Use `add` to break a task into smaller pieces. **Auto-parenting**: if a task
is already in-progress (visible via `status`) and you omit both `--parent`
and `--top-level`, the new task auto-parents under the active todo. This is
the most ergonomic way to add subtasks while working on something — just
`nytid todo add ...` and the parent is inferred. Pass `--top-level` to opt
out and add at the root, or `--parent <id>` to target a specific parent.

**Priority assignment** defaults to interactive binary-search comparison
against existing siblings (you'll be prompted to compare priorities). For
non-interactive batch adds use one of:

- `--append` — places the new task just below the lowest-priority sibling.
  Safe even when the parent has no existing children (the first child gets
  a sensible default). When batch-adding in priority order (highest first),
  each `--append` slots one rung below the previous, encoding the order
  without prompts.
- `--skip-priority` — no numeric priority assigned; the task sorts by
  deadline only. Use for "do whenever" buckets.

**Default-command** (`-c`/`--command`): the value passed here becomes the
command `nytid todo start <id>` runs (replacing the worker's default, which
is `bash`). Useful for embedding a one-step action — opening a file in an
editor, launching a query in NeoMutt, running a script — so the user goes
from `start` to working with no copy-paste.

### Reprioritize

Use `reprioritize` (alias `reprio`) to rerun the binary-search priority
comparison for a task whose importance has changed.

## Handing the user follow-ups from a session

When a session produces a batch of items the user must do personally (e.g.
"the papers that couldn't be downloaded: add todos so I try to fetch them"),
build **one parent todo that resumes the session, with one subtask per
item**, all assigned to the user (omit `--who`):

1. **Parent** — top-level, `--append` (no interactive priority prompt), a
   description saying where the session's artefacts live (scratchpad paths,
   scholar sessions, plan file), and a default command that lands the user
   back in *this* session in the right directory:

   ```
   nytid todo add <labels> --top-level --append -t "<what and why>" \
     --description "<artefact locations; ordering rule for subtasks>" \
     -C <working directory of the session> \
     -c "claude --resume <session-id>"
   ```

   The session id is the UUID in the session's scratchpad path
   (`…/<project>/<session-id>/scratchpad`); the working directory is the
   session's primary working directory (a worktree path when working in
   one). `-C` and `-c` can also be set afterwards with `edit`.
2. **Subtasks** — `--parent <parent-id> --append`, added in priority order
   (most load-bearing first, so `--append` encodes the order), each with a
   one-step default command (`-c "xdg-open https://doi.org/<doi>"` for a
   paper, an editor or URL otherwise) and a description stating **what to
   check once the item is obtained** (e.g. "verify the 13/3/÷16 parameters
   attributed to it"), so the user does not have to reconstruct the context.
3. Report the parent id and the few subtasks that matter most; the rest
   are visible via `view <parent-id>`.

Batch the subtask adds in one shell loop; each `add` prints `Added todo
#<id>`, so capture the parent's id from its own output before the loop.

## Getting context from other assignees

Your tasks often exist as children of broader items assigned to `dbosk` or
others. To understand the full picture:

- Use `ls` without `--who` (or with a wider filter) to see all assignees' tasks.
- Use `view` on a parent item to read its description and notes, even if it is
  not assigned to you.

This is read-only context gathering.

## GitHub integration

Use `import` to pull GitHub issues/PRs into the todo system and `sync` to keep
them updated. Both support `--help` for repository, type, and metadata options.
Always pass `--who dan-claude` when importing to ensure correct assignment.

## Quick reference

| Intent | Subcommand | Key flags to check |
|--------|------------|--------------------|
| List my top-level tasks | `ls` | `--all`, `--status`, `--flat`, `-n` (positional args = label filters, **not** parent IDs) |
| What am I working on? | `status` | — |
| Start next task | `next` | `--headless` |
| Start specific task | `start` | `--timeout`, tmux flags |
| Pause current task | `stop` | — |
| Complete current task | `done` | — |
| View task + its sub-items | `view <id>` | shows description, notes, children — use this instead of `ls <id>` |
| Edit task metadata | `edit` | `--edit` for editor, `-c` for default command |
| Add progress note | `note` | `--message`, `--edit` |
| Create subtask | `add` | `--parent`, `--top-level`, `--append`, `-c` (auto-parents to active todo by default) |
| Change priority | `reprioritize` | — |
| Import from GitHub | `import` | `--number`, `--type` |
| Sync with GitHub | `sync` | `--repo` |
| Remove a task | `rm` | `--force` |