@bumpyclock/tasque-linux-x64-gnu 0.5.2 → 0.6.0

package/SKILLS/tasque/SKILL.md

@@ -16,9 +16,9 @@ Default day-to-day playbook.
 ## Session routine (default)
 
 ```bash
-tsq ready --lane planning
-tsq ready --lane coding
-tsq list --status blocked
+tsq find ready --lane planning
+tsq find ready --lane coding
+tsq find blocked
 ```
 
 Pick one task; inspect context:
@@ -31,85 +31,102 @@ tsq show <id>
 ### 1) Capture new work
 
 ```bash
-tsq create "Implement <feature>" --kind feature -p 1 --needs-planning
-tsq create "Fix <bug>" --kind task -p 1 --needs-planning
+tsq create "Implement <feature>" --kind feature -p 1 --needs-plan
+tsq create "Fix <bug>" --kind task -p 1 --needs-plan
 ```
 
 Planning already done:
 
 ```bash
-tsq create "Implement <feature>" --planning planned
+tsq create "Implement <feature>" --planned
 ```
 
-### 2) Split parent into many children (single command)
+### 2) Split parent into many children
 
 ```bash
 tsq create --parent <parent-id> \
-  --child "Design API contract" \
-  --child "Implement service logic" \
-  --child "Add regression tests"
+  "Design API contract" \
+  "Implement service logic" \
+  "Add regression tests"
 ```
 
 Shared defaults for all children:
 
 ```bash
-tsq create --parent <parent-id> --kind task -p 2 --planning planned \
-  --child "Wire CLI args" \
-  --child "Update docs" \
-  --child "Add integration tests"
+tsq create --parent <parent-id> --kind task -p 2 --planned \
+  "Wire CLI args" \
+  "Update docs" \
+  "Add integration tests"
 ```
 
 Safe reruns without duplicate children:
 
 ```bash
 tsq create --parent <parent-id> --ensure \
-  --child "Wire CLI args" \
-  --child "Update docs" \
-  --child "Add integration tests"
+  "Wire CLI args" \
+  "Update docs" \
+  "Add integration tests"
 ```
 
+Batch from `tasks.md`:
+
+```md
+- Add parser tests
+  - Cover nested task hierarchy
+  - Cover invalid indentation
+- Wire CLI command
+- Update skill docs
+```
+
+```bash
+tsq create --parent <parent-id> --from-file tasks.md
+```
+
+Use `tsq create --parent <id> --from-file tasks.md` for many tasks.
+
 ### 3) Planning handoff -> coding
 
 ```bash
-tsq spec attach <id> --text "## Plan\n...\n## Acceptance\n..."
-tsq update <id> --planning planned
-tsq update <id> --claim --assignee <name>
-tsq update <id> --status in_progress
+tsq spec <id> --text "## Plan\n...\n## Acceptance\n..."
+tsq planned <id>
+tsq claim <id> --assignee <name> --start
 ```
 
+Use `tsq spec <id> --show` when you need spec markdown from sync worktree.
+
 ### 4) Model deps for parallel agents
 
 Hard blocker (changes readiness):
 
 ```bash
-tsq dep add <child-id> <blocker-id> --type blocks
+tsq block <child-id> by <blocker-id>
 ```
 
 Soft ordering only:
 
 ```bash
-tsq dep add <later-id> <earlier-id> --type starts_after
+tsq order <later-id> after <earlier-id>
 ```
 
 Check actionable tasks:
 
 ```bash
-tsq ready --lane coding
-tsq ready --lane planning
+tsq find ready --lane coding
+tsq find ready --lane planning
 ```
 
 ### 5) Capture discovered follow-up work
 
 ```bash
-tsq create "Handle edge case <x>" --discovered-from <current-id> --needs-planning
-tsq link add <new-id> <current-id> --type relates_to
+tsq create "Handle edge case <x>" --discovered-from <current-id> --needs-plan
+tsq relate <new-id> <current-id>
 ```
 
 ### 5b) Idempotent root/parent create for automation
 
 ```bash
 tsq create "Implement auth module" --ensure
-tsq create --parent <parent-id> --child "Add tests" --ensure
+tsq create --parent <parent-id> "Add tests" --ensure
 ```
 
 `--ensure` returns existing task when same normalized title already exists under the same parent.
@@ -117,30 +134,30 @@ tsq create --parent <parent-id> --child "Add tests" --ensure
 ### 6) Park / unpark work
 
 ```bash
-tsq update <id> --status deferred
-tsq list --status deferred
-tsq update <id> --status open
+tsq defer <id> --note "waiting"
+tsq find deferred
+tsq open <id>
 ```
 
 ### 7) Resolve duplicate/superseded work
 
 ```bash
-tsq duplicate <id> --of <canonical-id> --reason "same root issue"
+tsq duplicate <id> of <canonical-id> --note "same root issue"
 tsq duplicates
 tsq merge <source-id...> --into <target-id> --dry-run
 tsq merge <source-id...> --into <target-id> --force
-tsq supersede <old-id> --with <new-id> --reason "replaced approach"
+tsq supersede <old-id> with <new-id> --note "replaced approach"
 ```
 
 ### 8) Close / report
 
 ```bash
-tsq update <id> --status closed
+tsq done <id> --note "verified"
 tsq history <id> --limit 20
-tsq list --tree
+tsq find open --tree
 ```
 
-Agent/tool handoff: add `--json`.
+Use `--format json` only when scripting/parsing; human output is fine for inspection.
 
 ## Built-in task authoring checklist
 
@@ -164,10 +181,10 @@ Agent/tool handoff: add `--json`.
 ### Practical authoring starter
 
 ```bash
-tsq create "<title>" --kind task -p 2 --needs-planning
-tsq spec attach <id> --text "<markdown spec>"
-tsq dep add <child> <blocker> --type blocks
-tsq link add <src> <dst> --type relates_to
+tsq create "<title>" --kind task -p 2 --needs-plan
+tsq spec <id> --text "<markdown spec>"
+tsq block <child> by <blocker>
+tsq relate <src> <dst>
 ```
 
 ## Required habits
@@ -175,7 +192,7 @@ tsq link add <src> <dst> --type relates_to
 - Keep lifecycle `status` and `planning_state` separate.
 - Use deps to make parallel execution explicit.
 - Create follow-up tasks; avoid chat TODOs.
-- Prefer `--json` for automation.
+- Prefer `--format json` for automation; inspect with human output.
 - Use `--ensure` in scripts to prevent duplicate creates on rerun.
 
 ## Read when needed

package/SKILLS/tasque/references/command-reference.md

@@ -14,37 +14,57 @@ Use `--sync-branch <name>` or `--worktree-name <name>` to choose another branch/
 and create the worktree on first use. `tsq sync` pushes the sync branch to `origin`
 and sets upstream automatically when needed. Non-git directories use local `.tasque/` storage.
 
-- `tsq create [<title>] [--child <title> ...] [--kind ...] [-p ...] [--parent <id>] [--description <text>] [--external-ref <ref>] [--discovered-from <id>] [--planning <needs_planning|planned>] [--needs-planning] [--ensure] [--id <tsq-xxxxxxxx>] [--body-file <path|->]`
-- `tsq show <id>`
-- `tsq list [--status ...] [--assignee ...] [--unassigned] [--external-ref <ref>] [--discovered-from <id>] [--kind ...] [--label ...] [--label-any ...] [--created-after <iso>] [--updated-after <iso>] [--closed-after <iso>] [--id <id,...>] [--planning <needs_planning|planned>] [--dep-type <blocks|starts_after>] [--dep-direction <in|out|any>] [--tree] [--full]`
-- `tsq search <query>`
-- `tsq update <id> [--title ...] [--description ...] [--clear-description] [--status ...] [--priority ...] [--external-ref <ref>] [--clear-external-ref] [--discovered-from <id>] [--clear-discovered-from] [--planning <needs_planning|planned>]`
-- `tsq update <id> --claim [--assignee <a>] [--require-spec]`
-- `tsq close <id...> [--reason <text>]`
-- `tsq reopen <id...>`
-- `tsq ready [--lane <planning|coding>]`
+- `tsq create <title...> [--kind ...] [-p ...] [--parent <id>] [--from-file tasks.md] [--description <text>] [--external-ref <ref>] [--discovered-from <id>] [--planned|--needs-plan] [--ensure] [--id <tsq-xxxxxxxx>] [--body-file <path|->]`
+
+`tasks.md` supports nested two-space bullets:
+
+```md
+- Parent task
+  - Child task
+    - Grandchild task
+- [ ] Another parent task
+```
+
+- `tsq show <id> [--with-spec]`
+- `tsq find ready [--lane <planning|coding>] [--assignee <name>] [--unassigned] [--kind ...] [--label ...] [--planning <needs_planning|planned>] [--tree] [--full]`
+- `tsq find <blocked|open|in-progress|deferred|done|canceled> [filters...] [--tree] [--full]`
+- `tsq find search <query> [--full]`
+- `tsq edit <id> [--title ...] [--description ...] [--clear-description] [--priority ...] [--external-ref <ref>] [--clear-external-ref] [--discovered-from <id>] [--clear-discovered-from]`
+- `tsq claim <id> [--assignee <a>] [--start] [--require-spec]`
+- `tsq assign <id> --assignee <a>`
+- `tsq start <id>`
+- `tsq planned <id>`
+- `tsq needs-plan <id>`
+- `tsq open <id>`
+- `tsq blocked <id>`
+- `tsq defer <id> [--note <text>]`
+- `tsq done <id...> [--note <text>]`
+- `tsq reopen <id...> [--note <text>]`
+- `tsq cancel <id...> [--note <text>]`
 
 ## Dependencies and relations
 
-- `tsq dep add <child> <blocker> [--type <blocks|starts_after>]`
-- `tsq dep remove <child> <blocker> [--type <blocks|starts_after>]`
-- `tsq dep tree <id> [--direction <up|down|both>] [--depth <n>]`
-- `tsq link add <src> <dst> --type <relates_to|replies_to|duplicates|supersedes>`
-- `tsq link remove <src> <dst> --type <relates_to|replies_to|duplicates|supersedes>`
-- `tsq duplicate <id> --of <canonical-id> [--reason <text>]`
+- `tsq block <task> by <blocker>`
+- `tsq unblock <task> by <blocker>`
+- `tsq order <later> after <earlier>`
+- `tsq unorder <later> after <earlier>`
+- `tsq deps <id> [--direction <up|down|both>] [--depth <n>]`
+- `tsq relate <src> <dst>`
+- `tsq unrelate <src> <dst>`
+- `tsq duplicate <id> of <canonical-id> [--note <text>]`
 - `tsq duplicates [--limit <n>]`
 - `tsq merge <source-id...> --into <target-id> [--reason <text>] [--force] [--dry-run]`
-- `tsq supersede <old-id> --with <new-id> [--reason <text>]`
+- `tsq supersede <old-id> with <new-id> [--note <text>]`
 
 ## Specs, notes, labels, history
 
-- `tsq spec attach <id> [source] [--file <path> | --stdin | --text <markdown>]`
-- `tsq spec check <id>`
-- `tsq note add <id> <text>`
-- `tsq note list <id>`
-- `tsq label add <id> <label>`
-- `tsq label remove <id> <label>`
-- `tsq label list`
+- `tsq spec <id> [--file <path> | --stdin | --text <markdown> | --show | --check] [--force]`
+- `tsq note <id> <text>`
+- `tsq note <id> --stdin`
+- `tsq notes <id>`
+- `tsq label <id> <label>`
+- `tsq unlabel <id> <label>`
+- `tsq labels`
 - `tsq history <id> [--limit <n>] [--type <event-type>] [--actor <name>] [--since <iso>]`
 
 ## Reporting and maintenance
@@ -63,6 +83,7 @@ and sets upstream automatically when needed. Non-git directories use local `.tas
 
 ## Global options and status alias
 
-- Add `--json` to any command for stable machine output.
+- Use `--format json` when scripting/parsing.
+- `--json` remains shorthand for `--format json`.
 - Add `--exact-id` to disable fuzzy id matching.
 - Status alias: `done` maps to `closed`.

package/SKILLS/tasque/references/machine-output-and-durability.md

@@ -4,7 +4,8 @@ Read when: automating `tsq` or reasoning about storage/recovery behavior.
 
 ## Stable machine output
 
-Use `--json` on any command.
+Use `--format json` only when scripting/parsing. Human output is fine for inspection.
+`--json` remains shorthand for `--format json`.
 
 Success envelope:
 

package/SKILLS/tasque/references/planning-workflow.md

@@ -21,22 +21,22 @@ New tasks default to `planning_state: "needs_planning"`. Legacy tasks (created b
 
 The `deferred` status is an active-but-parked lifecycle state. Tasks with `status: deferred`:
 
-- Are **not ready** (excluded from the `ready` command output)
+- Are **not ready** (excluded from `tsq find ready` output)
 - **Are** included in `stale` scans (they can become stale like any non-terminal task)
 - Can transition to any non-terminal status (`open`, `in_progress`, `blocked`)
 - Are **not terminal** — unlike `closed` or `canceled`, deferral is reversible
 
 Use `deferred` when a task is valid but not actionable right now (e.g., waiting on external input, deprioritized, or parked for a future iteration).
 
-## Lane-Aware Ready
+## Lane-Aware Find Ready
 
-The `ready` command supports lane filtering to separate planning work from coding work:
+`tsq find ready` supports lane filtering to separate planning work from coding work:
 
 | Command | Returns |
 |---|---|
-| `tsq ready` | All ready tasks (both planning and coding) |
-| `tsq ready --lane planning` | Ready tasks with `planning_state` = `needs_planning` (or unset) |
-| `tsq ready --lane coding` | Ready tasks with `planning_state` = `planned` |
+| `tsq find ready` | All ready tasks (both planning and coding) |
+| `tsq find ready --lane planning` | Ready tasks with `planning_state` = `needs_planning` (or unset) |
+| `tsq find ready --lane coding` | Ready tasks with `planning_state` = `planned` |
 
 A task is "ready" when:
 - Its status is `open` or `in_progress`
@@ -51,49 +51,48 @@ Lane filtering is applied on top of the standard ready check.
 
 ```bash
 # Explicit planning state
-tsq create "Design auth module" --planning needs_planning
-tsq create "Design auth module" --needs-planning    # shorthand for --planning needs_planning
+tsq create "Design auth module" --needs-plan
 
 # Mark as already planned
-tsq create "Implement auth module" --planning planned
+tsq create "Implement auth module" --planned
 ```
 
 ### Filter by planning state
 
 ```bash
-tsq list --planning needs_planning   # tasks that still need planning
-tsq list --planning planned          # tasks with planning complete
+tsq find open --planning needs_planning   # tasks that still need planning
+tsq find open --planning planned          # tasks with planning complete
 ```
 
 ### Update planning state
 
 ```bash
-tsq update <id> --planning planned          # mark planning as done
-tsq update <id> --planning needs_planning   # revert to needs-planning
+tsq planned <id>      # mark planning as done
+tsq needs-plan <id>   # revert to needs-planning
 ```
 
 ### Lane-aware ready
 
 ```bash
-tsq ready                    # all ready tasks
-tsq ready --lane planning    # what needs planning?
-tsq ready --lane coding      # what's ready to code?
-tsq ready --lane coding --json   # machine-readable output
+tsq find ready                    # all ready tasks
+tsq find ready --lane planning    # what needs planning?
+tsq find ready --lane coding      # what's ready to code?
+tsq --format json find ready --lane coding   # machine-readable output
 ```
 
 ### Deferred status
 
 ```bash
-tsq update <id> --status deferred    # park a task
-tsq list --status deferred           # see parked tasks
-tsq update <id> --status open        # un-park a task
+tsq defer <id> --note "waiting"      # park a task
+tsq find deferred                    # see parked tasks
+tsq open <id>                        # un-park a task
 ```
 
 ## Typical Workflow
 
 1. Create tasks — they start as `open` + `needs_planning`
-2. Run `tsq ready --lane planning` to find tasks needing planning work
-3. Do planning; mark complete with `tsq update <id> --planning planned`
-4. Run `tsq ready --lane coding` to find tasks ready for implementation
+2. Run `tsq find ready --lane planning` to find tasks needing planning work
+3. Do planning; mark complete with `tsq planned <id>`
+4. Run `tsq find ready --lane coding` to find tasks ready for implementation
 5. Claim and work on tasks normally
-6. Use `tsq update <id> --status deferred` to park tasks that are valid but not actionable yet
+6. Use `tsq defer <id>` to park tasks that are valid but not actionable yet

package/SKILLS/tasque/references/task-authoring-checklist.md

@@ -22,8 +22,21 @@ Read when: creating/refining tasks or splitting work for parallel execution.
 ## Practical starter flow
 
 ```bash
-tsq create "<title>" --kind task -p 2 --needs-planning
-tsq spec attach <id> --text "<markdown spec>"
-tsq dep add <child> <blocker> --type blocks
-tsq link add <src> <dst> --type relates_to
+tsq create "<title>" --kind task -p 2 --needs-plan
+tsq spec <id> --text "<markdown spec>"
+tsq block <child> by <blocker>
+tsq relate <src> <dst>
+```
+
+For many tasks, write `tasks.md` with nested two-space bullets:
+
+```md
+- Parent task
+  - Child task
+    - Grandchild task
+- [ ] Another parent task
+```
+
+```bash
+tsq create --parent <id> --from-file tasks.md
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bumpyclock/tasque-linux-x64-gnu",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Tasque binary for Linux x64 (glibc)",
   "license": "MIT",
   "repository": {