trekoon 0.2.0 → 0.2.4

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

@@ -7,382 +7,317 @@ description: Use Trekoon to create issues/tasks, plan backlog and sprints, creat
 
 Trekoon is a local-first issue tracker for epics, tasks, and subtasks.
 
-## CRITICAL: Always Use --toon Flag
-
-**Every trekoon command MUST include `--toon` for machine-readable output.**
-
-The `--toon` flag outputs structured YAML-like data that is easy to parse. Never run trekoon commands without it.
-
-### TOON Output Format
-
-All `--toon` output follows this structure:
-
-```yaml
-ok: true
-command: task.list
-data:
-  tasks[0]:
-    id: abc-123
-    epicId: epic-456
-    title: Implement feature X
-    status: todo
-    createdAt: 1700000000000
-    updatedAt: 1700000000000
-  tasks[1]:
-    id: def-789
-    epicId: epic-456
-    title: Write tests
-    status: in_progress
-    createdAt: 1700000001000
-    updatedAt: 1700000001000
-metadata:
-  contractVersion: 1.0.0
-  requestId: req-abc12345
-```
+This skill is the agent operating guide, not the full CLI reference. Use it to
+pick the right command with the fewest reads and mutations.
+
+## Non-negotiable defaults
+
+- Always include `--toon` on every Trekoon command.
+- Prefer the smallest sufficient scope.
+- Prefer transactional bulk commands over many single-item commands.
+- Prefer `--append` for progress notes, completion notes, and blocker notes.
+- Preview replace before `--apply`.
+- Prefer `--ids` over `--all` for bulk updates.
+- Never edit `.trekoon/trekoon.db` directly.
+- Treat `.trekoon` as shared repo-scoped operational state in git worktrees.
+- Keep `.trekoon` gitignored; do not commit the SQLite DB as a recovery fix.
+- Never run `trekoon wipe --yes --toon` unless the user explicitly asks for it.
+
+## Default agent loop
+
+The primary loop is: **session → work → task done → repeat**.
 
-On error:
-
-```yaml
-ok: false
-command: task.show
-data: {}
-metadata:
-  contractVersion: 1.0.0
-  requestId: req-def67890
-error:
-  code: not_found
-  message: task not found: invalid-id
+### 1. Orient with a single call
+
+```bash
+trekoon --toon session
 ```
 
-### Key Fields
+`session` replaces the old five-call bootstrap sequence
+(init + sync status + task next + dep list + task show) with a single DB open.
+It returns diagnostics, sync status, the full next-task tree with subtasks, blocker
+list, and readiness counts in one envelope.
 
-| Field | Meaning |
-|-------|---------|
-| `ok` | `true` if command succeeded, `false` on error |
-| `command` | The command that was executed (e.g., `task.list`, `epic.create`) |
-| `data` | The response payload (tasks, epics, dependencies, etc.) |
-| `metadata` | Contract metadata (`contractVersion`, `requestId`) |
-| `meta` | Optional command-specific metadata (pagination/defaults/filters/diagnostics) |
-| `error` | Present only on failure, contains `code` and `message` |
+Fail fast if the envelope reports `recoveryRequired`, a storage mismatch, or any
+bootstrap error. In linked worktrees, `sharedStorageRoot` may differ from
+`worktreeRoot`; that is expected because the repo shares one DB across checkouts.
 
-Use long flags (`--status`, `--description`, etc.) and ALWAYS append `--toon` to every command.
+### 2. Claim work explicitly
 
-### Contract details to rely on
+```bash
+trekoon --toon task update <task-id> --status in_progress
+```
 
-- Machine responses include `metadata.contractVersion` and `metadata.requestId`.
-- Command IDs are stable and typically dot namespaced (`task.list`, `sync.status`).
-- Some root commands use single-token IDs (`help`, `init`, `quickstart`, `wipe`, `version`).
-- Unknown options fail fast with deterministic `unknown_option` errors and may include:
-  - `data.option`
-  - `data.allowedOptions`
-  - `data.suggestions`
+### 3. Finish or report a block
 
-### Compatibility mode (legacy sync consumers)
+```bash
+trekoon --toon task done <task-id>
+trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
+```
 
-Default behavior is strict canonical IDs (for example `sync.status`).
+`task done` replaces the old three-call transition sequence
+(mark done + get next + load deps + show task) with a single call that marks the
+task done and returns the next ready candidate with its full tree and blockers.
 
-If a legacy consumer still expects underscore sync IDs, compatibility mode can be used:
+Append a completion note before calling `task done` when useful:
 
 ```bash
-trekoon --toon --compat legacy-sync-command-ids sync status
+trekoon --toon task update <task-id> --append "Completed implementation and checks"
+trekoon --toon task done <task-id>
 ```
 
-When enabled, output includes `metadata.compatibility` with migration/deprecation details.
+### 4. Repeat
 
-## 1) Status Management
+Run `session` again at the start of each new session. After `task done`, the
+returned next-task envelope is sufficient to continue; a fresh `session` call is
+not required mid-loop unless you need updated diagnostics or sync status.
 
-### Status values
+Recommended statuses for consistent workflows: `todo`, `in_progress`, `done`.
 
-Trekoon accepts any non-empty status string.
+## Read policy: use the smallest sufficient read
 
-Recommended statuses for consistent workflows:
+Use the narrowest command that answers the question.
 
-| Status | Meaning |
-|--------|---------|
-| `todo` | Work not started (default for new items) |
-| `in_progress` | Actively being worked on |
-| `done` | Completed successfully |
+| Need | Preferred command |
+|---|---|
+| Session startup (diagnostics + sync + next task) | `trekoon --toon session` |
+| Next task only | `trekoon --toon task next` |
+| A few ready options | `trekoon --toon task ready --limit 5` |
+| Direct blockers for one task | `trekoon --toon dep list <task-id>` |
+| What this item unblocks | `trekoon --toon dep reverse <task-or-subtask-id>` |
+| One full task payload | `trekoon --toon task show <task-id> --all` |
+| One full epic tree | `trekoon --toon epic show <epic-id> --all` |
+| Repeated text in one scope | `trekoon --toon epic|task|subtask search ...` |
 
-Note: `in-progress` (hyphenated) is treated the same as `in_progress` for default list ordering/filtering.
+Avoid broad scans such as `task list --all` or `epic show --all` when
+`task next`, `task ready`, `dep list`, `dep reverse`, or `search` can answer the
+question more cheaply.
 
-### When to Change Status
+## Creation policy: prefer bulk planning workflows
 
-| Transition | When to apply |
-|------------|---------------|
-| `todo → in_progress` | When you START working on a task/subtask/epic |
-| `in_progress → done` | When you COMPLETE the work and it is ready |
+When creating multiple related records, do not loop through repeated single-item
+creates unless only one record is needed.
 
-### Status Change Commands
+### Which command to use
 
-```bash
-trekoon task update <task-id> --status in_progress --toon
-trekoon task update <task-id> --status done --toon
-trekoon subtask update <subtask-id> --status done --toon
-trekoon epic update <epic-id> --status done --toon
-```
+| Situation | Preferred command |
+|---|---|
+| New epic and full graph already known | `trekoon --toon epic create ... --task ... --subtask ... --dep ...` |
+| Existing epic needs linked additions | `trekoon --toon epic expand <epic-id> ...` |
+| Multiple sibling tasks under one epic | `trekoon --toon task create-many --epic <epic-id> --task ...` |
+| Multiple sibling subtasks under one task | `trekoon --toon subtask create-many <task-id> --subtask ...` |
+| Multiple dependency edges across existing IDs | `trekoon --toon dep add-many --dep ...` |
+| One record only | `epic create`, `task create`, or `subtask create` |
 
-## 2) Dependency Management
+### Compact spec escaping rules
 
-Dependencies define what must be completed before a task can start. A task/subtask can depend on other tasks/subtasks.
+Compact specs (pipe-delimited `--task`, `--subtask`, `--dep` values) use `\` as
+the escape character. Only these sequences are valid:
 
-### Commands
+| Sequence | Produces |
+|---|---|
+| `\|` | literal `|` (not a field separator) |
+| `\\` | literal `\` |
+| `\n` | newline |
+| `\r` | carriage return |
+| `\t` | tab |
 
-```bash
-trekoon dep add <source-id> <depends-on-id> --toon
-trekoon dep list <source-id> --toon
-trekoon dep remove <source-id> <depends-on-id> --toon
-trekoon dep reverse <task-or-subtask-id> --toon
-```
+Any other `\X` combination (e.g., `\!`, `\=`, `\$`) is rejected with
+`Invalid escape sequence`. To avoid accidental escapes:
 
-- `<source-id>`: The task/subtask that has the dependency
-- `<depends-on-id>`: The task/subtask that must be completed first
+- Do not use `!=` or similar operators in description text; rephrase instead
+  (e.g., "null does not equal sourceBranch" instead of "null !== sourceBranch").
+- If a literal backslash is needed, double it: `\\`.
+- When using shell line continuations (`\` at end of line), ensure the next
+  line's first character is not one that forms an invalid escape with `\`.
 
-### Checking Dependencies
+### Critical temp-key rule
 
-Before starting any task, always check its dependencies:
+- Use plain temp keys when declaring records in compact specs, for example
+  `task-api` or `sub-tests`.
+- Refer to those records later in the same invocation as `@task-api` or
+  `@sub-tests`.
+- `@temp-key` references work in same-invocation graph workflows such as
+  one-shot `epic create` and `epic expand`.
+- `dep add-many` does **not** resolve temp keys from earlier commands. Use real
+  persisted IDs there.
 
-```bash
-trekoon dep list <task-id> --toon
-```
+### Compact examples
+
+#### One-shot epic creation
 
-The response `data.dependencies` array contains entries with:
-- `sourceId`: the task you're checking
-- `dependsOnId`: what must be done first
-- `dependsOnKind`: "task" or "subtask"
-
-### Dependency Rules
-
-1. A task with dependencies should only be marked `in_progress` when ALL dependencies have status `done`
-2. Dependencies can only exist between tasks and subtasks (not epics)
-3. Cycles are automatically detected and rejected
-
-## 3) Task Completion Flow
-
-### Canonical dependency-aware execution loop
-
-Run this sequence every session:
-
-1. Sync branch/worktree status:
-   ```bash
-   trekoon sync status --toon
-   ```
-2. Pull deterministic ready candidates (or next candidate):
-   ```bash
-   trekoon task ready --limit 5 --toon
-   trekoon task next --toon
-   ```
-3. Inspect downstream impact before changes:
-   ```bash
-   trekoon dep reverse <task-or-subtask-id> --toon
-   ```
-4. Start work with explicit status updates:
-   ```bash
-   trekoon task update <task-id> --status in_progress --toon
-   ```
-5. Finish or block with appended context + final status:
-   ```bash
-   trekoon task update <task-id> --append "Completed implementation" --status done --toon
-   trekoon task update <task-id> --append "Blocked by <reason>" --status blocked --toon
-   ```
-
-### When Completing a Task
-
-1. Mark the task as done:
-   ```bash
-   trekoon task update <task-id> --status done --toon
-   ```
-
-2. To find the next task that was blocked by this one:
-   - Inspect downstream nodes: `trekoon dep reverse <task-id> --toon`
-   - Pull ready queue: `trekoon task ready --limit 5 --toon`
-   - Pick one deterministically: `trekoon task next --toon`
-
-### Finding Next Work
+Use this when the epic does not exist yet and you already know the tree.
 
 ```bash
-trekoon task ready --limit 5 --toon
-trekoon task next --toon
-trekoon dep reverse <task-or-subtask-id> --toon
+trekoon --toon epic create \
+  --title "Batch command rollout" \
+  --description "Ship linked planning in one transaction" \
+  --task "task-api|Design API|Define compact grammar|todo" \
+  --task "task-cli|Wire CLI|Hook parser and output|todo" \
+  --subtask "@task-api|sub-tests|Write tests|Cover parser cases|todo" \
+  --dep "@task-cli|@task-api"
 ```
 
-Use `task ready` for ranked candidates and `task next` for the top deterministic pick.
-
-## 4) Load existing work first
+#### Expand an existing epic
 
-Before creating or changing anything, inspect current context:
+Use this when the epic already exists and the new batch needs internal links.
 
 ```bash
-trekoon epic list --toon
-trekoon task list --toon
-trekoon epic show <id> --all --toon
-trekoon task show <id> --all --toon
+trekoon --toon epic expand <epic-id> \
+  --task "task-docs|Document workflow|Write operator guide|todo" \
+  --subtask "@task-docs|sub-examples|Add examples|Show canonical flows|todo" \
+  --dep "@sub-examples|@task-docs"
 ```
 
-- `epic list` / `task list` / `subtask list` defaults:
-  - open work only (`in_progress`, `in-progress`, `todo`)
-  - prioritized as `in_progress`/`in-progress` first, then `todo`
-  - default limit `10`
-  - `--cursor <n>` is offset-like pagination for list endpoints
-- Filter list explicitly when needed:
+#### Create sibling tasks or subtasks
 
 ```bash
-trekoon task list --status in_progress,todo --limit 20 --toon
-trekoon epic list --status done --toon
-trekoon task list --all --toon
-```
+trekoon --toon task create-many --epic <epic-id> \
+  --task "seed-api|Design API|Define grammar|todo" \
+  --task "seed-cli|Wire CLI|Hook output|todo"
 
-- `--all` cannot be combined with `--status` or `--limit`.
-- `--all` cannot be combined with `--cursor`.
-- Machine pagination contract is in `meta.pagination.hasMore` and
-  `meta.pagination.nextCursor`.
-- Machine list/show responses may also include:
-  - `meta.defaults`
-  - `meta.filters`
-  - `meta.truncation`
-- `epic show <id> --all --toon`: full epic tree (tasks + subtasks)
-- `task show <id> --all --toon`: task plus its subtasks
+trekoon --toon subtask create-many <task-id> \
+  --subtask "seed-tests|Write tests|Cover happy path|todo" \
+  --subtask "seed-docs|Document flow|Add notes|todo"
+```
 
-### Canonical storage root behavior
+#### Add dependencies after records already exist
 
-- In git repos/worktrees, Trekoon resolves storage from repository top-level so
-  nested cwd invocations use one canonical `.trekoon/trekoon.db`.
-- In non-git directories, Trekoon falls back to invocation cwd.
-- If invocation cwd differs from canonical root, machine output may include
-  `meta.storageRootDiagnostics`.
+```bash
+trekoon --toon dep add-many \
+  --dep "<task-b>|<task-a>" \
+  --dep "<subtask-c>|<task-b>"
+```
 
-### View Options
+## Update policy: prefer append-based progress logging
 
-| Command | `--view` options |
-|---------|------------------|
-| `list` | `table` (default), `compact` |
-| `show` | `table` (default), `compact`, `tree`, `detail` |
+Use descriptions as the durable work log. For progress updates, append instead
+of rewriting full descriptions.
 
-## 5) Create work (epic/task/subtask)
+### Preferred patterns
 
 ```bash
-trekoon epic create --title "..." --description "..." --status todo --toon
-trekoon task create --epic <epic-id> --title "..." --description "..." --status todo --toon
-trekoon subtask create --task <task-id> --title "..." --description "..." --status todo --toon
+trekoon --toon task update <task-id> --append "Started implementation" --status in_progress
+trekoon --toon task update <task-id> --append "Completed implementation and checks" --status done
+trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
 ```
 
-Notes:
-- `description` is required for epic/task create and it must be well written.
-- `status` defaults to `todo` if omitted.
-- `description` is optional for subtask create.
+### Bulk update rules
 
-## 6) Update work
+- Bulk update is available for `epic update`, `task update`, and
+  `subtask update`.
+- Bulk mode uses `--ids <csv>` or `--all`.
+- Bulk mode supports only `--append` and/or `--status`.
+- Do not pass a positional ID in bulk mode.
+- `--append` and `--description` are mutually exclusive.
+- Prefer `--ids` for narrow, explicit updates.
+- Use `--all` only for clear maintenance sweeps or when the user explicitly wants
+  a broad update.
 
-### Single-item update
+Examples:
 
 ```bash
-trekoon epic update <epic-id> --title "..." --description "..." --status in_progress --toon
-trekoon task update <task-id> --title "..." --description "..." --status in_progress --toon
-trekoon subtask update <subtask-id> --title "..." --description "..." --status in_progress --toon
+trekoon --toon task update --ids id1,id2 --append "Waiting on release" --status blocked
+trekoon --toon epic update --ids epic1,epic2 --append "Sprint planning refreshed" --status in_progress
 ```
 
-### Bulk update (task/epic)
+## Search and replace policy
 
-```bash
-trekoon task update --all --append "..." --status in_progress --toon
-trekoon task update --ids id1,id2 --append "..." --status in_progress --toon
+Use scoped search before manual tree reads when you need to locate repeated
+paths, labels, owners, or migration targets.
 
-trekoon epic update --all --append "..." --status in_progress --toon
-trekoon epic update --ids id1,id2 --append "..." --status in_progress --toon
-```
+### Scope choice
 
-Rules:
-- `--all` and `--ids` are mutually exclusive.
-- In bulk mode, do not pass a positional ID.
-- Bulk update supports `--append` and/or `--status`.
+Prefer the narrowest valid root:
 
-## 7) Scoped search/replace recipes for agents
+1. `subtask search` or `subtask replace`
+2. `task search` or `task replace`
+3. `epic search` or `epic replace`
 
-Use scoped search/replace instead of repeated `show` scans when you need to
-locate or migrate repeated text inside one issue tree.
+Scope behavior:
 
-```bash
-trekoon epic search <epic-id> "path/to/somewhere" --toon
-trekoon task search <task-id> "path/to/somewhere" --toon
-trekoon subtask search <subtask-id> "path/to/somewhere" --toon
+- `subtask` scope scans only that subtask.
+- `task` scope scans the task plus descendant subtasks.
+- `epic` scope scans the epic plus descendant tasks and subtasks.
 
-trekoon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --toon
-trekoon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --apply --toon
+### Safe replace workflow
+
+1. Search first.
+2. Preview replace.
+3. Apply only after preview matches the intended scope.
+
+```bash
+trekoon --toon epic search <epic-id> "path/to/somewhere"
+trekoon --toon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path"
+trekoon --toon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --apply
 ```
 
 Guardrails:
 
-- Use `search` first when you only need to confirm whether the text exists.
-- Use preview `replace` next to confirm the exact candidate set.
-- Use `--apply` only after preview matches the intended scope.
-- Prefer the narrowest root that satisfies the task: `subtask` → `task` →
-  `epic`.
-- Keep prompts deterministic: literal search text, explicit IDs, no regex
-  assumptions.
-
-Agent contract for epic-scoped replace:
-
-- Exact search command:
-  `trekoon epic search <epic-id> "path/to/somewhere" --toon`
-- Exact replace command:
-  `trekoon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --toon`
-- Apply command:
-  `trekoon epic replace <epic-id> --search "path/to/somewhere" --replace "path/to/new-path" --apply --toon`
-- Epic scope includes the epic title/description plus every task and subtask
-  title/description in that epic tree.
-
-Compact TOON fields to expect:
-
-```text
-ok: true
-command: epic.search
-data:
-  scope: epic
-  query: { search, fields[], mode: preview }
-  matches[]: { kind, id, fields[]: { field, count, snippet } }
-  summary: { matchedEntities, matchedFields, totalMatches }
-metadata:
-  contractVersion: 1.0.0
-  requestId: req-<id>
-```
+- Use literal, explicit search text.
+- Narrow fields when useful: `--fields title`, `--fields description`, or
+  `--fields title,description`.
+- Do not jump straight to `--apply`.
+- Prefer scoped search/replace over manually reading a whole tree and editing
+  many records one by one.
+
+## Setup and fallback
 
-```text
-ok: true
-command: epic.replace
-data:
-  scope: epic
-  query: { search, replace, fields[], mode: preview|apply }
-  matches[]: { kind, id, fields[]: { field, count, snippet } }
-  summary: { matchedEntities, matchedFields, totalMatches, mode }
-metadata:
-  contractVersion: 1.0.0
-  requestId: req-<id>
+If Trekoon is unavailable or storage diagnostics require repair:
+
+```bash
+trekoon --toon init
+trekoon --toon sync status
+trekoon --toon quickstart
+trekoon --toon help sync
 ```
 
-Background behavior to assume:
+Rules:
 
-- Scope traversal is deterministic: epic first, then descendant tasks, then
-  descendant subtasks.
-- Field traversal is deterministic: `title` before `description`.
-- Preview reads and summarizes candidates without mutation.
-- `--apply` reuses the same scoped traversal, mutates only rows with real text
-  changes, and returns matched rows with `query.mode` and `summary.mode` set
-  to `"apply"`.
+- Re-bootstrap first, then re-read diagnostics.
+- Stop if `recoveryRequired` stays true or diagnostics report storage mismatch.
+- Do not continue with task selection after missing shared storage or broken
+  bootstrap.
+- Do not commit `.trekoon/trekoon.db`; remove the tracked DB and keep
+  `.trekoon` ignored instead.
 
-## 8) Setup/install/init (if `trekoon` is unavailable)
+Use `quickstart` for the canonical execution loop. Use help when you need exact
+syntax.
 
-1. Install Trekoon (or make sure it is on `PATH`).
-2. In the target repository/worktree, initialize tracker state:
+## Sync reminders
 
-```bash
-trekoon init --toon
-```
+Same-branch sync is a no-op: `sync pull --from main` while on `main` produces
+zero conflicts and simply advances the cursor. `sync status` returns `behind=0`
+on the source branch. No action is needed.
 
-3. You can always run `trekoon quickstart --toon` or `trekoon --help --toon` to
-   get more information.
+Cross-branch sync matters before merging a feature branch back:
 
-If `.trekoon/trekoon.db` is missing, initialize before any create/update commands.
+- Before merge, pull tracker events from the base branch:
 
-## 9) Safety
+  ```bash
+  trekoon --toon sync pull --from main
+  ```
 
-- Never edit `.trekoon/trekoon.db` directly.
-- `trekoon wipe --yes --toon` is prohibited unless the user explicitly confirms they want a destructive wipe.
+- If conflicts exist, inspect and resolve them explicitly:
+
+  ```bash
+  trekoon --toon sync conflicts list
+  trekoon --toon sync conflicts show <conflict-id>
+  trekoon --toon sync resolve <conflict-id> --use ours
+  ```
+
+## Worktree diagnostics and destructive scope
+
+- Inspect machine-readable storage fields when debugging worktrees:
+  `storageMode`, `repoCommonDir`, `worktreeRoot`, `sharedStorageRoot`, and
+  `databaseFile`.
+- `sharedStorageRoot` is the repo-scoped source of truth for `.trekoon` in git
+  worktrees.
+- If `trekoon wipe --yes --toon` is explicitly requested, warn that it deletes
+  shared storage for the entire repository and every linked worktree.
+- Wipe is destructive recovery only; it is never the right fix for a tracked DB
+  or gitignore mistake.
+
+Trekoon stores local state in `.trekoon/trekoon.db`. In git repos and
+worktrees, storage resolves from the shared repository root rather than each
+worktree independently.