@bumpyclock/tasque-linux-x64-gnu 0.3.0 → 0.4.1

package/SKILLS/tasque/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: tasque
+description: Operational guide for Tasque (tsq) local task tracking and management.
+---
+
+<!-- tsq-managed-skill:v1 -->
+
+Tasque = durable, local-first task memory for agent work.
+Default day-to-day playbook.
+
+## When to use tsq
+
+- Use `tsq` for multi-step, multi-session, dependency-blocked, shared-agent work.
+- Use transient checklist for short linear single-session work.
+
+## Session routine (default)
+
+```bash
+tsq ready --lane planning
+tsq ready --lane coding
+tsq list --status blocked
+```
+
+Pick one task; inspect context:
+
+```bash
+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
+```
+
+Planning already done:
+
+```bash
+tsq create "Implement <feature>" --planning planned
+```
+
+### 2) Split parent into many children (single command)
+
+```bash
+tsq create --parent <parent-id> \
+  --child "Design API contract" \
+  --child "Implement service logic" \
+  --child "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"
+```
+
+Safe reruns without duplicate children:
+
+```bash
+tsq create --parent <parent-id> --ensure \
+  --child "Wire CLI args" \
+  --child "Update docs" \
+  --child "Add integration tests"
+```
+
+### 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
+```
+
+### 4) Model deps for parallel agents
+
+Hard blocker (changes readiness):
+
+```bash
+tsq dep add <child-id> <blocker-id> --type blocks
+```
+
+Soft ordering only:
+
+```bash
+tsq dep add <later-id> <earlier-id> --type starts_after
+```
+
+Check actionable tasks:
+
+```bash
+tsq ready --lane coding
+tsq 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
+```
+
+### 5b) Idempotent root/parent create for automation
+
+```bash
+tsq create "Implement auth module" --ensure
+tsq create --parent <parent-id> --child "Add tests" --ensure
+```
+
+`--ensure` returns existing task when same normalized title already exists under the same parent.
+
+### 6) Park / unpark work
+
+```bash
+tsq update <id> --status deferred
+tsq list --status deferred
+tsq update <id> --status open
+```
+
+### 7) Resolve duplicate/superseded work
+
+```bash
+tsq duplicate <id> --of <canonical-id> --reason "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"
+```
+
+### 8) Close / report
+
+```bash
+tsq update <id> --status closed
+tsq history <id> --limit 20
+tsq list --tree
+```
+
+Agent/tool handoff: add `--json`.
+
+## Built-in task authoring checklist
+
+### Minimum quality bar
+
+- Titles: clear, action-oriented (verb + object + scope).
+- Set `kind`: `task|feature|epic`.
+- Set priority intentionally: `0..3`.
+- Add labels with consistent naming.
+- Attach spec when scope/acceptance non-trivial.
+- Add explicit deps/relations when relevant.
+
+### Parallelization guidance
+
+- Prefer multiple independent tasks over one large task.
+- Use `blocks` only when work truly gates another task.
+- Use `starts_after` for sequencing without blocking readiness.
+- Add discovered work as new tasks via `--discovered-from`.
+- Keep each task small enough for one focused agent pass.
+
+### 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
+```
+
+## Required habits
+
+- 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.
+- Use `--ensure` in scripts to prevent duplicate creates on rerun.
+
+## Read when needed
+
+- Planning/deferred semantics: `references/planning-workflow.md`
+- JSON schema + durability details: `references/machine-output-and-durability.md`
+- Full option matrix (edge cases): `references/command-reference.md`
+- Install if missing: `npm install -g @bumpyclock/tasque`

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

@@ -0,0 +1,61 @@
+# Command Reference
+
+Read when: you need exact command syntax or available options.
+
+## Core workflow
+
+- `tsq` (no args, TTY): open read-only TUI
+- `tsq init [--wizard|--no-wizard] [--yes] [--preset <name>] [--sync-branch <branch>]`
+- `tsq init --install-skill|--uninstall-skill [--skill-targets ...] [--skill-name <name>] [--force-skill-overwrite]`
+- `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>]`
+
+## 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 duplicates [--limit <n>]`
+- `tsq merge <source-id...> --into <target-id> [--reason <text>] [--force] [--dry-run]`
+- `tsq supersede <old-id> --with <new-id> [--reason <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 history <id> [--limit <n>] [--type <event-type>] [--actor <name>] [--since <iso>]`
+
+## Reporting and maintenance
+
+- `tsq watch [--once] [--interval <seconds>] [--status <csv>] [--assignee <name>] [--tree]`
+- `tsq tui [--once] [--interval <seconds>] [--status <csv>] [--assignee <name>] [--board|--epics]`
+- `tsq stale [--days <n>] [--status <status>] [--assignee <name>] [--limit <n>]`
+- `tsq orphans`
+- `tsq doctor`
+- `tsq repair [--fix] [--force-unlock]`
+- `tsq sync [--no-push]`
+- `tsq hooks install [--force]`
+- `tsq hooks uninstall`
+- `tsq migrate --sync-branch <branch>`
+- `tsq merge-driver <ancestor> <ours> <theirs>`
+
+## Global options and status alias
+
+- Add `--json` to any command for stable machine output.
+- Add `--exact-id` to disable fuzzy id matching.
+- Status alias: `done` maps to `closed`.

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

@@ -0,0 +1,48 @@
+# Machine Output and Durability
+
+Read when: automating `tsq` or reasoning about storage/recovery behavior.
+
+## Stable machine output
+
+Use `--json` on any command.
+
+Success envelope:
+
+```json
+{
+  "schema_version": 1,
+  "command": "tsq ...",
+  "ok": true,
+  "data": {}
+}
+```
+
+Error envelope:
+
+```json
+{
+  "schema_version": 1,
+  "command": "tsq ...",
+  "ok": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "..."
+  }
+}
+```
+
+## Storage model
+
+- Canonical source of truth: `.tasque/events.jsonl` (append-only)
+- Derived cache: `.tasque/state.json` (rebuildable, gitignored)
+- Legacy cache fallback: `.tasque/tasks.jsonl` (read-only fallback when `state.json` is absent; removal target)
+- Optional replay checkpoints: `.tasque/snapshots/`
+- Config: `.tasque/config.json`
+- Ephemeral lock: `.tasque/.lock`
+
+## Recovery model
+
+- Read path: load latest snapshot, replay event tail, refresh state cache.
+- Write path: append event(s), update projection, periodically write snapshot.
+- Startup recovery tolerates one malformed trailing JSONL line.
+- Do not create or edit `.tasque/tasks.jsonl`; new writes use `.tasque/state.json`.

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

@@ -0,0 +1,99 @@
+# Planning Workflow
+
+Read when: deciding whether work belongs in planning lane vs coding lane, or when parking work as deferred.
+
+## Overview
+
+Tasque supports a planning-aware workflow via the `planning_state` field, orthogonal to lifecycle `status`.
+
+This separation allows teams to track **what needs design/planning** independently from **what is actively being worked on**. A task can be `open` but still need planning, or `in_progress` with planning already complete.
+
+## Planning State
+
+Every task carries a `planning_state` field with two values:
+
+- `needs_planning` — task needs planning before coding work can begin (default for new tasks)
+- `planned` — planning is complete, task is ready for coding
+
+New tasks default to `planning_state: "needs_planning"`. Legacy tasks (created before this feature) are treated as `needs_planning`.
+
+## Deferred Status
+
+The `deferred` status is an active-but-parked lifecycle state. Tasks with `status: deferred`:
+
+- Are **not ready** (excluded from the `ready` command 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
+
+The `ready` command 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` |
+
+A task is "ready" when:
+- Its status is `open` or `in_progress`
+- It has zero open blockers (all dependency targets are `closed` or `canceled`)
+- It is not `canceled`, `closed`, or `deferred`
+
+Lane filtering is applied on top of the standard ready check.
+
+## CLI Usage
+
+### Create with planning state
+
+```bash
+# Explicit planning state
+tsq create "Design auth module" --planning needs_planning
+tsq create "Design auth module" --needs-planning    # shorthand for --planning needs_planning
+
+# Mark as already planned
+tsq create "Implement auth module" --planning planned
+```
+
+### Filter by planning state
+
+```bash
+tsq list --planning needs_planning   # tasks that still need planning
+tsq list --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
+```
+
+### 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
+```
+
+### 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
+```
+
+## 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
+5. Claim and work on tasks normally
+6. Use `tsq update <id> --status deferred` to park tasks that are valid but not actionable yet

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

@@ -0,0 +1,29 @@
+# Task Authoring Checklist
+
+Read when: creating/refining tasks or splitting work for parallel execution.
+
+## Minimum quality bar
+
+- Use clear, action-oriented titles.
+- Set `kind` correctly (`task`, `feature`, `epic`).
+- Assign priority (`0..3`) intentionally.
+- Add labels using a consistent format.
+- Attach spec content when scope/acceptance is non-trivial.
+- Link task dependencies and relations explicitly.
+
+## Parallelization guidance
+
+- Prefer multiple independent tasks over one large task.
+- Use `blocks` only when completion truly gates another task.
+- Use `starts_after` for ordering without readiness blocking.
+- Add discovered follow-up work as new tasks with `--discovered-from <id>`.
+- Keep each task sized so one agent can complete it in one focused pass.
+
+## 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
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bumpyclock/tasque-linux-x64-gnu",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Tasque binary for Linux x64 (glibc)",
   "license": "MIT",
   "repository": {
@@ -17,7 +17,8 @@
     "glibc"
   ],
   "files": [
-    "tsq"
+    "tsq",
+    "SKILLS/**"
   ],
   "publishConfig": {
     "access": "public",