Subtasks & Dependencies

Backlog.md supports breaking complex work into subtasks and defining execution order between tasks through dependencies.

Creating Subtasks

When creating a task, use --parent (or -p) to specify the parent task ID to create a subtask:

backlog task create "Design database tables" -p back-4
backlog task create "Implement REST API" -p back-4
backlog task create "Write unit tests" -p back-4

Decimal Numbering Rules

Subtasks use a decimal numbering system in the format parentID.sequence:

Numbering rules:

• Subtask sequence numbers auto-increment by creation order
• A parent task can have any number of subtasks
• Subtasks cannot have subtasks (single-level structure)
• Subtasks are associated with the parent in lists, boards, and the Web UI by default

Viewing Subtasks

# View all subtasks of a specific parent
backlog task list -p back-4

# Subtasks are automatically listed when viewing task details
backlog task view back-4

Changing Parent-Child Relationships

Existing tasks can be reassigned to a different parent without deleting and recreating:

# Move task under a new parent
backlog task edit back-10 --parent back-4

# Remove parent-child relationship (return to top level)
backlog task edit back-10 --clear-parent

--parent / --clear-parent is shared between CLI and MCP: it only rewrites the task's parent_task_id edge, normalizes the input ID, and prevents cycles before writing (rolling back and erroring if one would form). Re-parenting does not change the task's sequence number or content, only its hierarchical position.

Setting Task Dependencies

When creating a task, use --dep (or --depends-on) to specify tasks it depends on:

backlog task create "Deploy to production" \
  --dep "back-5,back-6" \
  --notes "Wait for frontend and backend tasks to complete"

You can also add or modify dependencies after creation:

# Overwrite dependencies
backlog task edit back-10 --dep "back-3,back-4"

# When depending on multiple tasks, you can repeat the option
backlog task edit back-10 --dep "back-3" --dep "back-4"

Dependency Target Resolution Rules

Dependency targets are resolved against working-copy tasks and the completed corpus:

• Depending on a completed task is valid—completed records are the "completion evidence" used by readiness determination
• Archived task IDs can be reused by new tasks, so archived records do not participate in dependency resolution; IDs that exist only in archive are treated as unknown
• When one ID is claimed by multiple records, or one input matches multiple identities, the command fails with an ambiguity error (fail-closed) rather than picking one
• Drafts cannot be dependency targets (drafts can depend on tasks, but tasks cannot depend on drafts)

Write Gate: Self-Dependency and Cycle Rejection

Creating and editing dependencies performs hard validation:

• Depending on itself (--dep back-10 on back-10) is rejected
• Dependencies that would form a cycle are rejected, with the full chain in the error message (e.g., TASK-1 -> TASK-2 -> TASK-1)
• Unresolvable new dependency entries are rejected (strict at creation time)

Softened rule for existing defects: when editing a task, unresolvable entries that already existed and were not modified in this edit are preserved as-is (CLI prints a warning; JSON/MCP results carry them as data), so you are not forced to clean up historical debt just to edit a title. Once an entry is rewritten, it is validated under the new rules.

Dependency Defect Diagnosis (doctor)

backlog doctor includes a dependency defect report, organized by category across the whole corpus:

• Circular dependencies (including self-loops), listed by ID order
• Dangling dependencies: tasks referencing non-existent IDs, listed one by one
• Draft targets: tasks that depend on drafts (forbidden direction)
• Released IDs: dependencies pointing to archived, reusable old IDs, with rebinding warnings
• Ambiguous references: cross-referenced with duplicate-ID reports

This report is diagnostic only: it reports but does not fix (--fix still only repairs duplicate IDs). Dependency defects do not affect the exit code—long-standing historical issues should not cause every diagnosis to fail.

How Dependencies Affect Sequences

Backlog.md automatically calculates execution sequences from task dependencies:

• Tasks with no dependencies, no dependents, and no ordinal are classified as Unsequenced
• Tasks with dependencies are layered by topological sort, forming Sequence 1, Sequence 2...
• Tasks in the same Sequence do not depend on each other and can run in parallel
• Different Sequences have ordering: all tasks in Sequence N must wait until Sequence N-1 is complete

Viewing Sequences

backlog sequence list

Example output:

Unsequenced:
  back-8 - Optimize build speed

Sequence 1:
  back-1 - Design database tables
  back-2 - Set up project skeleton

Sequence 2:
  back-3 - Implement user registration API
  back-4 - Implement user login API

Sequence 3:
  back-5 - Deploy to test environment

In this example:

• back-1 and back-2 can be developed in parallel
• back-3 and back-4 depend on back-1 and back-2, so they start only after those finish
• back-3 and back-4 can run in parallel with each other
• back-5 depends on back-3 and back-4, so it must run last

Web UI Dependency Drill-Down

In the Web task detail panel, the Dependencies section lists all tasks this task depends on. Each dependency is shown as a blue badge:

• Click a dependency badge: opens that dependency's detail panel directly, without returning to the board or list
• Back button: after drilling into a subtask, a ← Back arrow appears in the task detail panel header; click it to return to the previous parent task
• Close button: clicking × in the top-right is equivalent to the browser back button, going back one level at a time—when already drilled in, it returns to the previous parent; one more click from the outermost level closes the entire modal

This feature is unavailable in new-task or edit-task modes; it only works in preview mode.

Parent/Child Hierarchy Block in the Modal

The task detail modal provides a hierarchy block below the title for direct up/down navigation:

• PARENT row: shown when the current task has a parent; includes parent ID, title, and status badge; click to open the parent
• SUBTASKS section: shown when the current task has subtasks; shows completion count (e.g., 1/6) and progress bar; click the section header to expand or collapse; each subtask shows completion indicator, ID, title, status badge, and drill arrow; click to open that subtask

Both blocks render only when the corresponding relationship exists; tasks without parent-child relationships do not show them.

Completed subtasks are also included: the parent task's SUBTASKS section now lists both active and completed subtasks; previously completed subtasks could disappear from the parent view. The completion count (e.g., 1/6) is now accurate. About 100 historical files still use the old task- prefix references and are outside the scope of this change.

Drilling Down via Markdown Links

In task descriptions, documents, decision records, and Wiki pages, links to other tasks such as /task/:id (e.g., http://localhost:6420/task/506) open the target task directly in the modal, with the same experience as clicking a dependency badge:

• Prefix-agnostic matching: both bare numbers (/task/123) and full IDs with prefix resolve correctly
• The system automatically renders full URLs as a short alias TASK#506 for readability
• After drilling down, the back button and browser forward/back navigation work the same way

Stable URLs and Sharing

Every task has an independent /task/:id/:title URL:

http://localhost:6420/task/506/Fix-CLI-actualStart-actualEnd-missing-local-to-UTC-conversion

You can copy the address-bar link and share it with team members; opening it shows the task detail over the default view and allows further dependency drill-down.

Dependency Planning Recommendations