@@ -5,51 +5,182 @@ description: Operational guide for Tasque (tsq) local task tracking and manageme
55
66<!-- tsq-managed-skill:v1 -->
77
8- Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
9-
10- ** When to use tsq** :
11- - Work spans multiple sessions or days
12- - Tasks have dependencies or blockers
13- - Need to survive conversation compaction
14- - Exploratory/research work with fuzzy boundaries
15- - Collaboration with team (git sync)
16-
17- ** When to use native task tool** :
18- - Single-session linear tasks
19- - Simple checklist for immediate work
20- - All context is in current conversation
21- - Will complete within current session
22-
23- Durable task tracking via ` tsq ` .
24-
25- - Local-first and repo-local (` .tasque/ ` ), so tracking works offline with no external service.
26- - Append-only JSONL history is git-friendly and auditable across agent sessions.
27- - Durable restart/replay model survives context compaction and crashes.
28- - Lane-aware readiness plus typed dependencies makes parallel sub-agent execution explicit and safe.
29- - Stable ` --json ` output keeps agent automation predictable.
30- - Survive context compaction, session restarts, and crashes.
31-
32- ## What to do by default
33-
34- 1 . Run ` tsq ready --lane planning ` and ` tsq ready --lane coding ` .
35- 2 . Pick a task with ` tsq show <id> ` .
36- 3 . If planning is incomplete, collaborate with the user and attach/update spec.
37- 4 . Mark planning done: ` tsq update <id> --planning planned ` .
38- 5 . Claim/start work: ` tsq update <id> --claim [--assignee <name>] ` then ` tsq update <id> --status in_progress ` .
39- 6 . Close when complete: ` tsq update <id> --status closed ` .
8+ Tasque = durable, local-first task memory for agent work.
9+ Default day-to-day playbook.
10+
11+ ## When to use tsq
12+
13+ - Use ` tsq ` for multi-step, multi-session, dependency-blocked, shared-agent work.
14+ - Use transient checklist for short linear single-session work.
15+
16+ ## Session routine (default)
17+
18+ ``` bash
19+ tsq ready --lane planning
20+ tsq ready --lane coding
21+ tsq list --status blocked
22+ ```
23+
24+ Pick one task; inspect context:
25+
26+ ``` bash
27+ tsq show < id>
28+ ```
29+
30+
31+ ### 1) Capture new work
32+
33+ ``` bash
34+ tsq create " Implement <feature>"
35+ tsq create " Fix <bug>"
36+ ```
37+
38+ Planning already done:
39+
40+ ``` bash
41+ tsq create " Implement <feature>"
42+ ```
43+
44+ ### 2) Split parent into many children (single command)
45+
46+ ``` bash
47+ tsq create --parent < parent-id> \
48+ --child " Design API contract"
49+ --child " Implement service logic"
50+ --child " Add regression tests"
51+ ```
52+
53+ Shared defaults for all children:
54+
55+ ``` bash
56+ tsq create --parent < parent-id> --kind task -p 2 --planning planned \
57+ --child " Wire CLI args"
58+ --child " Update docs"
59+ --child " Add integration tests"
60+ ```
61+
62+ Safe reruns without duplicate children:
63+
64+ ``` bash
65+ tsq create --parent < parent-id> --ensure \
66+ --child " Wire CLI args"
67+ --child " Update docs"
68+ --child " Add integration tests"
69+ ```
70+
71+ ### 3) Planning handoff -> coding
72+
73+ ``` bash
74+ tsq spec attach < id> --text " ## Plan\n...\n## Acceptance\n..."
75+ tsq update < id> --planning planned
76+ tsq update < id> --claim --assignee < name>
77+ tsq update < id> --status in_progress
78+ ```
79+
80+ ### 4) Model deps for parallel agents
81+
82+ Hard blocker (changes readiness):
83+
84+ ``` bash
85+ tsq dep add < child-id> < blocker-id> --type blocks
86+ ```
87+
88+ Soft ordering only:
89+
90+ ``` bash
91+ tsq dep add < later-id> < earlier-id> --type starts_after
92+ ```
93+
94+ Check actionable tasks:
95+
96+ ``` bash
97+ tsq ready --lane coding
98+ tsq ready --lane planning
99+ ```
100+
101+ ### 5) Capture discovered follow-up work
102+
103+ ``` bash
104+ tsq create " Handle edge case <x>" < current-id> --needs-planning
105+ tsq link add < new-id> < current-id> --type relates_to
106+ ```
107+
108+ ### 5b) Idempotent root/parent create for automation
109+
110+ ``` bash
111+ tsq create " Implement auth module"
112+ tsq create --parent < parent-id> --child " Add tests"
113+ ```
114+
115+ ` --ensure ` returns existing task when same normalized title already exists under the same parent.
116+
117+ ### 6) Park / unpark work
118+
119+ ``` bash
120+ tsq update < id> --status deferred
121+ tsq list --status deferred
122+ tsq update < id> --status open
123+ ```
124+
125+ ### 7) Resolve duplicate/superseded work
126+
127+ ``` bash
128+ tsq duplicate < id> --of < canonical-id> --reason " same root issue"
129+ tsq duplicates
130+ tsq merge < source-id...> --into < target-id> --dry-run
131+ tsq merge < source-id...> --into < target-id> --force
132+ tsq supersede < old-id> --with < new-id> --reason " replaced approach"
133+ ```
134+
135+ ### 8) Close / report
136+
137+ ``` bash
138+ tsq update < id> --status closed
139+ tsq history < id> --limit 20
140+ tsq list --tree
141+ ```
142+
143+ Agent/tool handoff: add ` --json ` .
144+
145+ ## Built-in task authoring checklist
146+
147+ ### Minimum quality bar
148+
149+ - Titles: clear, action-oriented (verb + object + scope).
150+ - Set ` kind ` : ` task|feature|epic ` .
151+ - Set priority intentionally: ` 0..3 ` .
152+ - Add labels with consistent naming.
153+ - Attach spec when scope/acceptance non-trivial.
154+ - Add explicit deps/relations when relevant.
155+
156+ ### Parallelization guidance
157+
158+ - Prefer multiple independent tasks over one large task.
159+ - Use ` blocks ` only when work truly gates another task.
160+ - Use ` starts_after ` for sequencing without blocking readiness.
161+ - Add discovered work as new tasks via ` --discovered-from ` .
162+ - Keep each task small enough for one focused agent pass.
163+
164+ ### Practical authoring starter
165+
166+ ``` bash
167+ tsq create " <title>"
168+ tsq spec attach < id> --text " <markdown spec>"
169+ tsq dep add < child> < blocker> --type blocks
170+ tsq link add < src> < dst> --type relates_to
171+ ```
40172
41173## Required habits
42174
43175- Keep lifecycle ` status ` and ` planning_state ` separate.
44- - Add dependencies so parallel work is explicit ( ` blocks ` vs ` starts_after ` ) .
45- - Break work into small tasks that can run in parallel across sub-agents .
46- - Create new tasks for discovered bugs/follow-ups instead of leaving TODOs in chat .
47- - Prefer ` --json ` for automation and tool-to-tool handoffs .
176+ - Use deps to make parallel execution explicit.
177+ - Create follow-up tasks; avoid chat TODOs .
178+ - Prefer ` --json ` for automation .
179+ - Use ` --ensure ` in scripts to prevent duplicate creates on rerun .
48180
49181## Read when needed
50182
51- - Planning/deferred semantics and lane-ready behavior: ` references/planning-workflow.md `
52- - Full CLI command catalog and option matrix: ` references/command-reference.md `
53- - Task authoring checklist and naming/labeling standards: ` references/task-authoring-checklist.md `
54- - JSON schema and storage/durability model: ` references/machine-output-and-durability.md `
55- - Install tasque if it's not available : ` npm install -g @bumpyclock/tasque `
183+ - Planning/deferred semantics: ` references/planning-workflow.md `
184+ - JSON schema + durability details: ` references/machine-output-and-durability.md `
185+ - Full option matrix (edge cases): ` references/command-reference.md `
186+ - Install if missing: ` npm install -g @bumpyclock/tasque `
0 commit comments