trekoon 0.4.4 → 0.4.5

package/.agents/skills/trekoon/SKILL.md

@@ -98,6 +98,10 @@ matches the user intent.
   `task next`, `dep list`, `dep reverse`, targeted `show`.
 - Prefer transactional/bulk commands for planning and narrow `--ids` for bulk
   updates.
+- In Claude Code, keep parallel `Bash` batches read-only for Trekoon commands.
+  Only `task claim` and `subtask claim` are safe parallel write exceptions.
+  Run `task done` and other status-changing commands sequentially after reading
+  current state.
 - Append progress, verification, and blocker notes with `--append`; do not
   rewrite descriptions unless fixing the plan itself.
 - Preview search/replace before `--apply`.
@@ -112,7 +116,8 @@ matches the user intent.
 Normal status flow is `todo -> in_progress -> done`; `blocked` requires an
 appended reason. Use `task done` for task completion because it auto-transitions
 from `todo` or `blocked` through `in_progress`. Load
-`reference/status-machine.md` for transition errors or uncertainty.
+`reference/status-machine.md` for transition errors or uncertainty. For
+subtasks, claim or move through `in_progress` before marking `done`.
 
 ## Recovery
 

package/.agents/skills/trekoon/reference/execution-with-team.md

@@ -47,7 +47,10 @@ TaskCreate:
     While working:
     - Complete required subtasks.
     - Append progress notes; do not rewrite task descriptions.
-    - Use task done for completion.
+    - Use task done for task completion.
+    - For subtasks, claim or move through in_progress before done.
+    - Keep parallel Trekoon Bash calls read-only; serialize status-changing
+      commands unless using atomic claim.
     - Use --compact for noisy Trekoon reads.
 
     On completion:
@@ -82,7 +85,9 @@ Agent:
     Claim each Trekoon task before editing:
       trekoon --toon task claim <trekoon-task-id> --owner <your-name>
 
-    Use task done for completion. Read and report unblocked tasks, warnings,
+    Use task done for task completion. For subtasks, claim or move through
+    in_progress before done. Do not batch multiple Trekoon status-changing Bash
+    calls in one parallel tool turn. Read and report unblocked tasks, warnings,
     and next candidate via SendMessage.
 
     Communicate blockers and coordination needs via SendMessage.
@@ -126,6 +131,10 @@ For `status_transition_invalid`, inspect current status with:
 trekoon --toon --compact task show <id>
 ```
 
+If the error came from a cancelled parallel Bash batch, first re-read the
+affected task or subtask, then retry only the valid next transition. Do not
+replay the whole batch.
+
 For `dependency_blocked`, inspect the dependency, append a blocker note, then
 continue with a ready candidate from:
 

package/.agents/skills/trekoon/reference/execution.md

@@ -86,7 +86,8 @@ Before each task:
 While working:
 - Complete required subtasks and update subtask statuses.
 - Append meaningful progress notes; do not rewrite task descriptions.
-- Respect status flow: todo -> in_progress -> done. Use task done for completion.
+- Respect status flow: todo -> in_progress -> done. Use task done for task
+  completion; for subtasks, claim or move through in_progress before done.
 - Assume other agents may edit unrelated files. Do not revert unrelated changes.
 
 On completion:
@@ -102,6 +103,16 @@ If blocked:
 Use --compact in noisy Trekoon reads. Do not create branches, commits, pushes,
 or PRs unless the user explicitly asked and harness policy allows it.
 
+Claude Code parallel tool calls:
+- Parallel Trekoon Bash calls are for read-only commands such as session,
+  progress, ready, suggest, and targeted show.
+- Do not issue multiple Trekoon status-changing Bash commands in one parallel
+  tool batch. Use task/subtask claim for atomic races, then serialize updates
+  and completion commands.
+- If a parallel batch reports sibling cancellation, re-read the affected task or
+  subtask before retrying; recover from current Trekoon state, not the cancelled
+  command text.
+
 Final report: tasks completed, files changed, checks, review result/gap,
 task done response, blockers.
 ```

package/.agents/skills/trekoon/reference/harness-primitives.md

@@ -46,7 +46,10 @@ coordinating from the parent session?
   `wait_agent`, `resume_agent`, and `close_agent`.
 - Claude Code: use normal subagents for bounded side work. Use Agent Teams only
   when the user explicitly asks for team execution and the environment supports
-  it.
+  it. Treat parallel `Bash` tool calls as read-only unless every command is a
+  safe atomic claim. Do not batch multiple Trekoon status-changing commands in
+  one parallel tool turn; run them sequentially so one failed transition does
+  not cancel sibling mutations.
 - OpenCode: use `@explore` for read-only discovery and `@general` or native
   Task for write-capable lane work. Use `question` when available.
 - Pi/other harnesses: use the same intent and native task/subagent/question

package/docs/ai-agents.md

@@ -274,6 +274,14 @@ trekoon --toon epic replace <epic-id> --search "path/to/somewhere" --replace "pa
 trekoon --toon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --apply
 ```
 
+For Claude Code and similar harnesses with parallel tool calls, keep parallel
+Trekoon `Bash` batches read-only. It is safe to fan out `session`, `progress`,
+`ready`, `suggest`, and targeted `show` commands. Do not batch multiple
+status-changing Trekoon commands in one parallel tool turn; if one transition
+fails, sibling calls may be cancelled and the agent must re-read state before
+retrying. Use `task claim` / `subtask claim` for atomic races, then serialize
+status updates and completion commands.
+
 ## Shared-database model
 
 Trekoon uses one live SQLite database per repository at

package/docs/quickstart.md

@@ -163,6 +163,10 @@ The response includes `claimed` (true/false), `currentOwner`, `currentStatus`,
 and the full entity record on success. Two concurrent claims return exactly one
 `claimed=true`.
 
+In Claude Code, keep parallel Trekoon `Bash` calls read-only unless the command
+is an atomic `claim`. Run status updates and completion commands sequentially so
+a failed transition does not cancel sibling mutations.
+
 ## Database backup and migration
 
 Before any manual migration recovery, snapshot the database:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "AI-first task tracking that lives in your repo. You describe what to build, your agent plans it as a dependency graph, then executes it task by task",
   "keywords": [
     "ai",