task-tree

Task Tree

Overview

The subtask tree IS the plan. Each subtask = a step. Body text under a heading = annotation with details. No translation step between plan and work — workers read the tree directly.

Two tools, two purposes:

• flicknote — orientation docs (what/why): goals, anti-goals, trade-offs, context, architecture decisions
• task tree — execution plans (how/steps): subtask hierarchy, each subtask = a step

Creating a Plan

task plan is for decomposition — building a subtask tree from scratch by breaking a goal into steps. Think of it as the "outline" phase.

Not for surgical edits to individual subtasks. If you already have a tree and just need to update one subtask's details, use task annotate or task modify (see Common Mistakes below).

Pipe markdown to task <parent-uuid> plan:

cat <<'PLAN' | task <parent-uuid> plan
## Add validation layer
Add input validation to the API handler. Check required fields, validate types, return 400 on failure.

## Write tests
Unit tests for validation: missing fields, wrong types, valid input.

## Update error responses
Standardize error response format to match API conventions.
PLAN

View what you created:

task <parent-uuid> tree

Each ## heading becomes a direct subtask. Body text becomes the subtask's annotation. Use ### for sub-subtasks when a step needs its own breakdown.

Markdown Format

Markdown	What it creates
# Title or ## Title	Direct subtask of parent
### Title	Sub-subtask (child of the subtask above)
#### Title	One level deeper
Text after a heading	Annotation on that subtask

Iterating on a Plan

# Replace the entire subtask tree with a new version
# ⚠️ Destructive: drops ALL existing subtasks before creating new ones
cat updated-plan.md | task <parent-uuid> plan replace

# Append more subtasks (keeps existing ones)
cat more-steps.md | task <parent-uuid> plan

# Add a single subtask manually
task add "Deploy and verify" parent_id:<parent-uuid>

# Reorder subtasks
task <subtask-uuid> modify before:<other-subtask-uuid>
task <subtask-uuid> modify after:<other-subtask-uuid>

# Move a subtask to a different parent
task <subtask-uuid> modify parent_id:<new-parent-uuid>

# Promote a subtask to root level
task <subtask-uuid> modify parent_id:

Viewing and Checking

# View the full subtask tree
task <uuid> tree

# View tree filtered by project
task project:ttal tree

# View task details including parent and children
task <uuid> information

Completing Work

# Complete a parent -- cascades to ALL descendants automatically
task <parent-uuid> done

# Complete a single subtask -- only that subtask, siblings/parent unaffected
task <subtask-uuid> done

Handoff to Workers

Workers read their subtask tree to know what to do. The plan review process uses task <uuid> tree to review the plan structure. No separate annotation linking is needed — the subtasks are already under the parent task.

Common Mistakes

Treating task plan as a surgical editor

task plan (without replace) appends subtasks. task plan replace replaces the entire tree. Neither is safe for editing one subtask's details — you'd lose the rest of the tree.

For editing individual subtask details, use:

# Update a subtask's description
task <subtask-uuid> modify "Updated description"

# Add or update annotation text on a subtask
task <subtask-uuid> annotate "Additional detail: ..."

# Change a subtask's status
task <subtask-uuid> start
task <subtask-uuid> done

Creating duplicate subtask trees

Agents sometimes write detailed plans in task annotations, then also pipe similar markdown to task plan, resulting in two copies of the same work. The tree is the plan — don't duplicate it in annotations.

• Use subtask tree for the execution steps (workers read this)
• Use flicknote for orientation context (goals, trade-offs, architecture)

Using task plan replace casually

task plan replace drops ALL existing subtasks before creating new ones. It's destructive. Prefer appending or creating from scratch in a fresh task. Only use replace when you intentionally want a full rebuild.