No epic view with total vs open children; list --json omits closed beads, so the update-specs-status shortcut reads bead files directly
- Dominant language
- TypeScript
- Stars
- 79
- Forks
- 9
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 42
Description
## Summary
There is no single command that answers "is this epic finished, or was it never decomposed?" That needs the total child count and the open child count, and tbd exposes neither together.
## What happened
- `tbd list --json` omits closed beads, so an epic whose children all closed and an epic that never had children look identical.
- `child_order_hints` holds internal ids while `parentId` holds display ids, so joining them from the JSON is error-prone (the shortcut even warns: "if every epic looks closable, that is the bug").
- `tbd list --pretty` shows the tree but no counts; `tbd list --all --parent --count` works but is one call per epic, so triaging 137 epics is 274 calls before reading anything.
The consequence is that the shipped `update-specs-status` shortcut tells agents to "read the committed bead files directly" under the data-sync worktree to tally `spec_path` against `status`, which contradicts the "you operate tbd, the user doesn't" rule in the same skill and is exactly the scratch-scripting the rest of the skill forbids. Measured once on a real repository, 23 of 33 candidate specs were undecomposed drafts, so the distinction matters.
## Suggested change
- `tbd list --type epic --children` (or a `tbd epics` triage command) adding total / open / closed child counts per row, in text and `--json`.
- Have `--json` include closed beads when `--all` is given, with `parentId` and `child_order_hints` in the same id space.
- Rewrite the shortcut step to use `tbd list --all --parent --count` (or the new column) instead of reading bead files.
Environment: tbd 0.8.1, Node v24.19.0, macOS 26 (Darwin 25.5), Linear integration enabled. Repository scale when observed: 7,156 beads, 137 open epics, 171 tracker links, about 110 plan specs in `active/`.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the tbd list command and the update-specs-status shortcut described in the issue, then trace how child counts and IDs are represented in text and JSON output. Done means the command exposes total, open, and closed child counts without direct bead-file reads, and the shortcut uses the supported tbd interface.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- nodejs, typescript
- Domain
- cli, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100