Operate on superRA/ task trees. Use to query frontier, DAG, or tree views; create or restructure tasks; edit statuses; serve dashboards; or migrate legacy PLAN.md/RESULTS.md.
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Task Tree?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/fuzhiyu-task-tree)
---
name: task-tree
description: Operate on superRA/ task trees. Use to query frontier, DAG, or tree views; create or restructure tasks; edit statuses; serve dashboards; or migrate legacy PLAN.md/RESULTS.md.
user-invocable: true
---
# Task Tree
## Core Concepts
- **Task** — an immediate subdirectory of a task directory or the rootless `./superRA` forest that contains `task.md`. `attachments/` is always an asset container, never a task. A leaf task has no child task directories.
- **Filesystem hierarchy is the task hierarchy.** `walk_plan()` discovers children by scanning subdirectories.
- Retained files are companions, not task nodes — classification, placement, and lifecycle in `../using-superra/references/task-companion-files.md`.
- **`depends_on` decides readiness; file dependencies inform.** `depends_on` names sibling directories; a task can start once each one, own or inherited, is `implemented`, `approved`, or `revise`. File edges between steps order builds and are reported as inputs, never gating: [Effective Dependencies](references/task-file-contract.md#effective-dependencies).
- **Parent status rolls up** from children automatically — `approved` only when all active (non-parked) children are `approved`; `archived` and `postponed` children are excluded.
- **DAG order vs. display order.** The dependency DAG controls execution order; numeric directory prefixes (`01-load`, `02-merge`) control display order only. Independent.
## CLI Setup
Bootstrap a fresh project's wrapper from the loaded skill directory (`<skill-dir>` = the directory holding this `SKILL.md`; substitute the real path), then use the wrapper for everything after:
```bash
uv run --script <skill-dir>/scripts/cli.py wrapper init # writes superRA/superra (planner/main bootstrap)
./superRA/superra wrapper init # refresh an existing wrapper; idempotent
```
## Reading the Tree
Run the committed `./superRA/superra` wrapper created above — contributors inside the superRA checkout substitute `uv run --script skills/task-tree/scripts/cli.py`. Every `superra …` example below and in the references denotes it:
```bash
./superRA/superra task tree # tree with status badges
./superRA/superra task frontier # ready tasks, each with its inputs whose producer is stale, missing, or failed
./superRA/superra task dag 01-data # dependency DAG for a subtree (Mermaid)
./superRA/superra task tree --json # JSON output
./superRA/superra dashboard --no-open # idempotent; starts or reuses a server and prints this worktree's scoped URL
```
**Deep-link a dashboard task:** append `#/<task-path>` to the scoped URL from `dashboard --no-open`. `<task-path>` is the `task read` locator (no `superRA/` prefix, empty for the tree root). Use the emitted URL as-is — its URL-encoded `?wt=` selector handles worktree-name collisions.
## Task File Format
```yaml
---
title: "Merge with Fund Characteristics"
status: not-started
depends_on:
- 01-sample-design
---
## Objective
Left join holdings with fund characteristics on fund_id x date.
Use CRSP-style merge conventions. Validate row counts post-merge.
## Results
Left join preserved all 4.7M holdings rows.
Quarterly characteristics were matched to monthly holdings by nearest prior date.
## Review Notes
> [BLOCKING] Inner join used instead of left join
```
Field-by-field anatomy and body-section ownership: `references/task-file-contract.md` §Task Anatomy.
## Routing — operate on the tree
| To do X | See |
|---|---|
| Create / rename / link / move tasks; bulk status propagation; append results programmatically | `references/commands.md` |
| Read or resolve task comments (the read/resolve loop; comments also surface via `superra task read`) | `references/commands.md §Comments` |
| Validate tree structure, fix status inconsistencies, diagnose orphaned `depends_on` entries | `references/commands.md §Diagnostics` |
| Rebuild steps, inspect change impact, or accept reviewed results | [commands.md §Reproduction](references/commands.md#reproduction) |
| Task-file anatomy, fields, status/dependencies, inherited context, results shape, stale-content, figure embedding | `references/task-file-contract.md` |
| Task companion-file classification, placement, reproducibility, promotion, and maturation | `../using-superra/references/task-companion-files.md` |
| Objective writing, task splitting, placement, durable homes, update-task lifecycle, retroactive task-tree creation | `../superplan/references/task-tree-design.md` |
| Migrate legacy `PLAN.md` + `RESULTS.md`, or upgrade `superRA/` v1 → v2 | `references/internals.md §Migration` |
| Dashboard server mechanics (idempotent ensure-running, task URLs, artifact export) | `references/internals.md §Dashboard` |
| Modify the skill itself (data layer, hooks, scripts) | `references/internals.md`; hook coverage details live in `§Hook Architecture` |
Intentional task path changes go through `superra task move` (`task rename` for same-parent compatibility), never raw `mv` / `git mv`. It resolves the fallout — relative Markdown links, root-relative task paths, and sibling-only `depends_on` edges — so run the move directly rather than rewriting them by hand first. Mechanics and cross-parent dependency rules: `references/commands.md §Move / rename a task`.