--- # workaround: anthropics/claude-code#13005 setup: | All projects that depend on this skill should have as CLAUDE.md frontmatter:

```yaml
--- # workaround: anthropics/claude-code#13003
depends:
- Skill(llm-subtask)
```

And include a "Current Work" section pointing to the todo system:

```markdown
## Current Work

Check `.claude/todo.md` and `.claude/todo.kb/` for active efforts. Load `Skill("llm-subtask")` for maintenance.
```

This gives future sessions a clear entry point for ongoing/planned work.

default: subtask load

Subtask Management

Four-tier task decomposition (finest to coarsest):

Conversational -- Question preemption (pattern, not tool)
Ephemeral -- In-context subtasks via marker commands
Tactical -- Cross-session checkboxes in .claude/todo.md
Strategic -- Planning files in .claude/todo.kb/

Use when breaking down complex work, coordinating across sessions, or transitioning between tiers.

Default to the lightest tier that fits. A batch of related lightweight feedback is .claude/todo.md bullets (sub-bullets carry extra detail), not one ideas.kb/ file per item — reserve ideas.kb//todo.kb/ for work that genuinely needs its own file (multi-step, its own frontmatter/tracking, or outlives a single session). If you're about to file several ideas.kb/ entries in one pass for what's really one topic, that's a todo.md bullet list instead.

Overview

Audience: Both humans and LLMs during work sessions

Purpose: Track current tasks, priorities, and blockers across sessions

Artifacts:

$PWD/.claude/todo.md - Quick checklist of active tasks (Tier 2: Tactical)
$PWD/.claude/todo.kb/YYYY-MM-DD-NNN-title.md - Detailed task breakdowns (Tier 3: Strategic)
$PWD/.claude/ideas.kb/YYYY-MM-DD-NNN-title.md - Unprioritized ideas (may become todos)
Conversation context - Ephemeral subtasks (Tier 1)

Marker Commands

Ephemeral (Tier 1)

Mostly notional, only reified on demand.

subtask prepend -- Signal priority shift, refocus on new work stream
subtask append -- Queue a subtask behind all current work; chat-local, nothing written to a file
subtask pop -- Mark current subtask complete
subtask list -- Enumerate pending work from conversation context

Persistent (Tier 2 & 3)

subtask load
1. read .claude/todo.md
2. list .claude/todo.kb/
subtask save
1. review chat history for incomplete, unpersisted subtasks
2. items with subtasks → todo.kb/ (strategic); all others → todo.md (tactical)
3. confirm with user before abandoning anything
session end -- Run bin/session-end script
todo append -- Append a task
todo pop -- Mark the current task (should be first) as complete
todo list -- Read and display .claude/todo.md
todo clear
1. for each [x] item, grep devlog for its key phrase
2. if no match, ask user before removing
3. also delete completed todo.kb/ files

File initialization: bin/llm-subtask-init creates .claude/todo.md from skeleton if missing (idempotent).

Strategic (Tier 3)

Create planning files via: ~/.claude/skills/llm-subtask/bin/llm-subtask-todo --title "Task title" (add -C <dir> to target another directory without cd)

The Checkbox Is Load-Bearing — Never Use Bare `-` for Tasks

The inventory pipeline (~/bin/claude-open-tasks-list) keys off the - [<char>] checkbox syntax — brackets present, any status character ( , x, ~, ...) — not specifically an empty box. A bare - bullet with no brackets at all is invisible to backlog enumeration — it will not appear in task-list.md, will not be rated by wsjf-rank, and will be silently lost when the work needs to compete for time.

This applies in every location the inventory scans:

*/.claude/todo.md
*/.claude/sessions.kb/*.md
CLAUDE.*Task*.md
(todo.kb/ and todo.d/ use "existence is signal" — files there count regardless of bullets — but their inline items still need brackets to be enumerated.)

Rule: any line you intend to track as work uses a bracketed status — - [ ] not started, - [~] in progress, - [x] done (see "Example: subtask list" below for the full status-indicator set). Anti-rule: never use bare - for a task. Use prose, full sentences, or nested narrative when the content is not a task.

Why this matters: real work has surfaced weeks late because someone wrote - pick an oss project instead of - [ ] pick an oss project. The line was real, the bullet was wrong, the work was invisible to every sweep that ran in between.

Audit: when reviewing a file for tasks, search for ^ *- [^[] — those are non-task bullets (no brackets at all). Convert to a bracketed status if they're work; rewrite as prose if they're not.

Integration: todo.md + todo.kb/

Tier 2 (tactical) and Tier 3 (strategic) work together: https:todo.md is a single prioritized list containing both inline tasks and references to planning files in https:todo.kb/. The only permitted section break is ## Later, and it is a commitment boundary, not a priority bucket: lines below it are uncommitted might-never items (the line-grain form of ideas.kb/ — see Ideas Pattern), which sweeps may surface but must never nag. Low-priority committed work doesn't go there — it just sits lower in the list.

Example pattern:

- [ ] <https:todo.kb/2025-11-26-001-research-local-climbing-gyms.md>
- [ ] Buy climbing shoes
  - [ ] Measure foot size
  - [ ] Check REI sale section
- [ ] Schedule first climbing session

Cross-Repo Ownership

A todo belongs to the repo whose work it tracks, not the repo you happened to be in when it came up (e.g. a todo raised while working in repo A but about repo B's work belongs in repo B). In a monorepo of sub-projects, use breadcrumb checkboxes: the root todo.md points at each subpath's todo.md/todo.kb/ entry; details live at the pointed-to location, never duplicated upward.

Nesting: Goal-First

Nest prerequisites under goals. Children complete before parent.

- [ ] Make a sandwich
  - [ ] Buy bread
  - [ ] Buy cheese

Granularity: Items >60 minutes are hiding scope. Decompose until each subtask is a single focused effort.

Example: subtask list

When user requests subtask list, enumerate pending work from conversation context using markdown list format with status indicators.

Important: Wrap task lists in a "code fence" to prevent the client from stripping status indicators. Without a code fence, - [x] and - [ ] are rendered as -.

Example output:

```
- [x] Completed item
- [~] In-flight item
  - [x] Completed sub-item
  - [ ] Pending sub-item
- [ ] Pending item
```

Session Lifecycle

Start: subtask load reads tactical todos from .claude/todo.md

Uncommitted [x] markers are unverified claims. Check git status — if todo.md has uncommitted changes, verify completed items before trusting them.

During: Work with ephemeral subtasks (subtask append/pop/prepend/list)

End: subtask save + update devlog (load llm-collab skill for devlog conventions)

Agent Initiative

Suggest subtask save when user says "done", "wrap up", "gotta go", or "that's all".

Suggest todo clear when [x] items outnumber [ ] items in todo.md.

Ideas Pattern

.claude/ideas.kb/ captures unprioritized ideas without disrupting focused work.

When to use: Mid-task inspiration that deserves capture but not immediate pursuit.

Lifecycle:

Exploring — Initial capture, may be refined over time
Promoted → Becomes todo.kb/ entry when ready for action
Rejected → Document reasoning (optionally as ADR), delete file
Forgotten — Acceptable; important ideas resurface naturally

Key distinction:

todo.kb/ = committed work, will be done
ideas.kb/ = speculative, might never happen

Create ideas via: ~/.claude/skills/llm-subtask/bin/llm-subtask-idea --title "Idea title"

References

Deep dives available in references/:

four-tier-system.md - Full explanation of all four tiers
marker-commands.md - How marker commands work (unusual pattern)

Architecture Decisions

See docs/adr/ for design rationale.