trekoon 0.2.6 → 0.2.8

package/docs/ai-agents.md

@@ -0,0 +1,198 @@
+# AI agents and the Trekoon skill
+
+Use this guide when an AI agent needs to plan work in Trekoon, execute it, and
+keep task state current while it works.
+
+## What the `trekoon` skill does
+
+The bundled `trekoon` skill is the operating guide for agents. It tells the
+agent to:
+
+- use `--toon` on Trekoon commands
+- prefer the smallest sufficient read
+- use transactional bulk planning commands when possible
+- append progress and blocker notes instead of rewriting full descriptions
+- preview scoped replace before `--apply`
+- treat `.trekoon` as shared repo-scoped operational state
+
+The canonical installed file lives at:
+
+- `.agents/skills/trekoon/SKILL.md`
+
+## Install the skill
+
+Install the bundled skill into the repository:
+
+```bash
+trekoon skills install
+```
+
+Create a project-local editor link when your agent environment supports it:
+
+```bash
+trekoon skills install --link --editor opencode
+trekoon skills install --link --editor claude
+trekoon skills install --link --editor pi
+trekoon skills install --link --editor opencode --to ./.custom-editor/skills
+trekoon skills update
+```
+
+Path behavior:
+
+- canonical install path: `.agents/skills/trekoon/SKILL.md`
+- default OpenCode link path: `.opencode/skills/trekoon`
+- default Claude link path: `.claude/skills/trekoon`
+- default Pi link path: `.pi/skills/trekoon`
+- `--to <path>` changes only the editor link root
+- `--allow-outside-repo` is for intentional external links
+
+## Recommended skill stack
+
+If your agent environment supports skills, this is the cleanest split of
+responsibilities:
+
+| Job | Skill | Why |
+| --- | --- | --- |
+| Turn a request into a concrete backlog | `writing-plans` | Breaks work into epics, tasks, subtasks, and dependencies |
+| Create and update tracker state | `trekoon` | Uses Trekoon safely and efficiently |
+| Execute the plan in dependency order | `executing-plans` | Helps the agent work through the backlog without losing the sequence |
+| Clarify architecture before planning | `architecting-systems` | Useful when boundaries or ownership are still fuzzy |
+
+In practice, the flow is usually:
+
+1. plan the work
+2. load `trekoon`
+3. create or update the Trekoon graph
+4. execute the next ready task
+5. update progress, blockers, and completion state as work moves forward
+
+## Default execution loop for agents
+
+The main loop is: **session → work → task done → repeat**.
+
+Start with a single orientation call:
+
+```bash
+trekoon --toon session
+```
+
+If the session output shows you are behind, pull tracker events before claiming
+work:
+
+```bash
+trekoon --toon sync pull --from main
+```
+
+Claim work, then finish or report a block:
+
+```bash
+trekoon --toon task update <task-id> --status in_progress
+trekoon --toon task done <task-id>
+trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
+```
+
+Use `task done` when the task is actually finished. It marks the task complete
+and returns the next ready candidate with blockers inline.
+
+## Use descendant cascade mode when closing a whole tree
+
+When an agent needs to close or reopen an entire epic or task tree from the
+command layer, use positional-ID `update --all` instead of looping one row at a
+time:
+
+```bash
+trekoon --toon epic update <epic-id> --all --status done
+trekoon --toon epic update <epic-id> --all --status todo
+trekoon --toon task update <task-id> --all --status done
+trekoon --toon task update <task-id> --all --status todo
+trekoon --toon subtask update <subtask-id> --all --status done
+```
+
+Notes:
+
+- Epic/task cascade mode is atomic: blocked descendants abort the whole update
+- Use it only with `--status done|todo`
+- Do not combine positional ID + `--all` with `--append`, `--description`,
+  `--title`, or `--ids`
+- Subtask positional-ID `--all` is accepted for contract consistency, but it is
+  equivalent to a normal single-subtask status update
+
+## Tell the agent exactly what to do
+
+These prompts work well because they are explicit about the skill order and the
+expected loop.
+
+### Plan first, then create the backlog
+
+```text
+Load writing-plans, break this feature into one epic with tasks and subtasks,
+then load trekoon and create that graph in Trekoon.
+```
+
+### Execute an existing backlog
+
+```text
+Load trekoon, run `trekoon --toon session`, take the next ready task, do the
+work, append progress notes, mark it done, and repeat until there are no ready
+tasks or you hit a blocker.
+```
+
+### Use planning, tracking, and execution together
+
+```text
+Load writing-plans to shape the backlog, load trekoon to create and update the
+tasks, then load executing-plans and complete the work in dependency order.
+```
+
+## Keep reads small and mutations safe
+
+Use the narrowest command that answers the question:
+
+| Need | Preferred command |
+| --- | --- |
+| Session startup | `trekoon --toon session` |
+| Next task only | `trekoon --toon task next` |
+| A few ready options | `trekoon --toon task ready --limit 5` |
+| One task with subtasks | `trekoon --toon task show <task-id> --all` |
+| One epic tree | `trekoon --toon epic show <epic-id> --all` |
+| Repeated text in one scope | `trekoon --toon epic|task|subtask search ...` |
+
+For repeated text changes, use the safe replace loop:
+
+1. search the narrowest valid scope
+2. preview replace
+3. run `--apply` only after the preview matches the intended scope
+
+Example:
+
+```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
+```
+
+## Worktree and sync rules
+
+- Treat `meta.storageRootDiagnostics` as the source of truth for storage.
+- In linked worktrees, `sharedStorageRoot` may differ from `worktreeRoot`. That
+  is expected.
+- Do not commit `.trekoon/trekoon.db` as a recovery fix.
+- Run `trekoon sync status` at session start and before merge.
+- Resolve sync conflicts explicitly when they appear.
+
+Useful commands:
+
+```bash
+trekoon --toon sync status
+trekoon --toon sync pull --from main
+trekoon --toon sync conflicts list
+trekoon --toon sync conflicts show <conflict-id>
+trekoon --toon sync resolve <conflict-id> --use ours
+```
+
+## Related docs
+
+- [Quickstart](quickstart.md)
+- [Command reference](commands.md)
+- [Machine contracts](machine-contracts.md)
+- [Installed skill source](../.agents/skills/trekoon/SKILL.md)

package/docs/commands.md

@@ -0,0 +1,226 @@
+# Command reference
+
+Use this page when you already know what Trekoon does and just need the command
+surface, defaults, and flag rules.
+
+## Command surface
+
+- `trekoon init`
+- `trekoon board <open|update>`
+- `trekoon help [command]`
+- `trekoon quickstart`
+- `trekoon epic <create|expand|list|show|search|replace|update|delete>`
+- `trekoon session`
+- `trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete>`
+- `trekoon subtask <create|create-many|list|search|replace|update|delete>`
+- `trekoon dep <add|add-many|remove|list|reverse>`
+- `trekoon events prune [--dry-run] [--archive] [--retention-days <n>]`
+- `trekoon migrate <status|rollback> [--to-version <n>]`
+- `trekoon sync <status|pull|resolve|conflicts>`
+- `trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]`
+- `trekoon skills update`
+- `trekoon wipe --yes`
+
+## Global output modes
+
+- `--json` for structured JSON output
+- `--toon` for true TOON-encoded output
+- `--compat <mode>` for explicit machine compatibility behavior
+- `--help` for root and command help
+- `--version` for CLI version
+
+Global options can be used before or after the command:
+
+```bash
+trekoon --toon quickstart
+trekoon quickstart --toon
+trekoon --json quickstart
+trekoon quickstart --json
+```
+
+Trekoon uses long-form options for command and subcommand flags. Root help and
+version aliases `-h` and `-v` are also supported.
+
+## Board lifecycle commands
+
+Board terminology in docs matches `trekoon help board`:
+
+- `trekoon board open`
+  - ensures board assets are installed in the repo-shared runtime directory
+  - starts a local board server on `127.0.0.1`
+  - launches the browser and returns the board URL, fallback URL, and launch
+    metadata in machine output
+- `trekoon board update`
+  - refreshes board runtime assets only
+  - does not start the server or open a browser
+
+Operator guidance:
+
+- use `trekoon board open` as the normal one-command startup path
+- use `trekoon board update` when you specifically need to refresh copied assets
+  before the next launch
+
+Board commands do not accept command-specific options yet. For tests and local
+development only, `TREKOON_BOARD_ASSET_ROOT` can override the bundled asset
+source used by `init`, `board open`, and `board update`.
+
+Runtime layout and security model:
+
+- `trekoon init` installs or refreshes the board runtime under `.trekoon/board`
+- `board open` serves those bundled files over a loopback-only server instead of
+  opening a raw file directly
+- the server binds to `127.0.0.1` on a random port
+- every session gets a per-session token; browser/API requests must present that
+  token
+- static responses use `cache-control: no-store`, and CLI output always includes
+  a manual fallback URL
+
+Current shell/runtime notes:
+
+- the runtime copied into `.trekoon/board` includes the HTML shell, local app
+  modules, and shared styles
+- the current shell also requests Vue from `unpkg.com`, Tailwind from
+  `cdn.tailwindcss.com`, and Google-hosted fonts/icons in the browser
+- if those remote dependencies are blocked, the local server still starts and
+  the fallback URL remains valid, but the browser UI may not fully load until
+  network access is restored
+
+Board UI architecture:
+
+- the board is a single-page application served from `.trekoon/board` with Vue 3
+  (shell) and vanilla JS (board app) loaded from CDN dependencies
+- the backend is a Bun HTTP server exposing a REST API at `/api/*` with
+  token-based authentication; every mutation response includes an updated
+  snapshot so the client always has fresh state
+- the frontend uses optimistic updates: the UI changes immediately on user
+  action, then rolls back if the server rejects the mutation
+
+Board layout behavior:
+
+- the topbar is a compact flex-row navbar with workspace identity, Epics and
+  Board navigation pills, a debounced search input, theme toggle, and a
+  workspace info popover
+- extra-wide layouts show the epic switcher sidebar, task workspace, and task
+  inspector or detail modal together
+- narrower layouts progressively collapse support surfaces into stacked panels
+  or drawer-style views
+- task cards show truncated descriptions; clicking anywhere on a card opens the
+  task detail modal
+
+Scroll and overlay behavior:
+
+- the page scrolls naturally as a single document; there are no internal scroll
+  containers trapping wheel events in the main content area
+- when a modal overlay opens (task detail, subtask editor), body scroll is
+  locked and the modal surface becomes the scroll container
+- close overlays from the top down: subtask modal → task detail → broader board
+  context; each close unlocks body scroll and returns to the previous context
+
+Board API endpoints (all require token authentication):
+
+- `GET /api/snapshot` — full board state (epics, tasks, subtasks, dependencies,
+  counts)
+- `PATCH /api/epics/{id}` — update epic title, description, or status
+- `PATCH /api/tasks/{id}` — update task title, description, or status
+- `PATCH /api/subtasks/{id}` — update subtask title, description, or status
+- `POST /api/subtasks` — create subtask (requires taskId, title)
+- `DELETE /api/subtasks/{id}` — delete subtask
+- `POST /api/dependencies` — add dependency edge (sourceId, dependsOnId)
+- `DELETE /api/dependencies?sourceId=...&dependsOnId=...` — remove dependency
+
+Token is sent as `Authorization: Bearer {token}` header or `x-trekoon-token`
+header or `?token={token}` query parameter. Invalid tokens return `401`.
+
+Examples:
+
+```bash
+trekoon init
+trekoon board open
+trekoon --json board open
+trekoon board update
+```
+
+## Human views
+
+- List and show commands default to table output in human mode.
+- Use `--view compact` to restore compact pipe output.
+- `epic list`, `task list`, and `subtask list` support `--view table|compact`.
+- `epic show` and `task show` support `--view table|compact|tree|detail`.
+
+## List defaults and filters
+
+These defaults apply to `epic list`, `task list`, and `subtask list`:
+
+- Default scope: open work only (`in_progress`, `in-progress`, `todo`)
+- Default limit: `10`
+- Status filter: `--status in_progress,todo`
+- Custom limit: `--limit <n>`
+- Cursor pagination: `--cursor <n>`
+- All rows and statuses: `--all`
+- `--all` is mutually exclusive with `--status`, `--limit`, and `--cursor`
+
+## Update modes
+
+`epic update`, `task update`, and `subtask update` now have two meanings for
+`--all`, depending on whether you also pass a positional ID.
+
+### Repo-wide bulk mode
+
+Use `update --all` or `update --ids <csv>` when you want to target multiple
+top-level rows directly.
+
+This mode preserves the existing per-row update behavior. It is **not** the same
+as descendant cascade mode and is not one atomic multi-row transaction.
+
+- Target all rows: `--all`
+- Target specific rows: `--ids <id1,id2,...>`
+- Bulk mode supports only `--append <text>`, `--status <status>`, or both
+- In bulk mode, do not pass a positional ID
+- `--all` and `--ids` are mutually exclusive
+- `--append` and `--description` are mutually exclusive
+
+Examples:
+
+```bash
+trekoon task update --all --status in_progress
+trekoon task update --ids <task-1>,<task-2> --append "\nFollow-up note"
+trekoon subtask update --all --status done
+trekoon subtask update --ids <subtask-1>,<subtask-2> --append "\nFollow-up note"
+trekoon epic update --ids <epic-1>,<epic-2> --status done
+```
+
+### Descendant cascade mode
+
+Use positional-ID `update <id> --all --status done|todo` when you want to close
+or reopen a whole tree from one root.
+
+- `trekoon epic update <epic-id> --all --status done|todo`
+  - updates the epic and all descendant tasks/subtasks in one atomic operation
+- `trekoon task update <task-id> --all --status done|todo`
+  - updates the task and all descendant subtasks in one atomic operation
+- `trekoon subtask update <subtask-id> --all --status done|todo`
+  - accepts the same syntax for consistency, but behaves like a normal
+    single-subtask status update because there are no descendants
+- Positional-ID cascade mode supports only `--status done|todo`
+- Do not combine positional ID + `--all` with `--ids`, `--append`,
+  `--description`, or `--title`
+- For epic/task cascades, unresolved external dependencies abort the whole
+  update with `dependency_blocked`; no partial writes are committed
+- Successful machine output includes `data.cascade` with the root, target
+  status, atomic flag, changed IDs, unchanged IDs, and per-kind counts
+
+Examples:
+
+```bash
+trekoon epic update <epic-id> --all --status done
+trekoon epic update <epic-id> --all --status todo
+trekoon task update <task-id> --all --status done
+trekoon task update <task-id> --all --status todo
+trekoon subtask update <subtask-id> --all --status done
+```
+
+## Related docs
+
+- [Quickstart](quickstart.md)
+- [AI agents and the Trekoon skill](ai-agents.md)
+- [Machine contracts](machine-contracts.md)

package/docs/machine-contracts.md

@@ -0,0 +1,253 @@
+# Machine contracts
+
+Use `--toon` for production agent loops. Use `--json` only when an integration
+explicitly requires JSON.
+
+## Base envelope
+
+All machine responses use the same top-level shape:
+
+```text
+ok: true|false
+command: <stable command id>
+data: <payload>
+metadata:
+  contractVersion: "1.0.0"
+  requestId: req-<stable-id>
+```
+
+Most subcommand identifiers are dot-namespaced, such as `task.list` or
+`sync.pull`. Root-level commands may use single-token IDs such as `help`,
+`init`, `quickstart`, `wipe`, or `version`.
+
+Additional metadata may appear when relevant:
+
+- `metadata.compatibility` when `--compat` mode is active
+- `meta.storageRootDiagnostics` when storage resolves from a non-canonical cwd
+
+## Ready queue contract
+
+```bash
+trekoon --toon task ready --limit 3
+```
+
+Payload fields:
+
+```text
+ok: true
+command: task.ready
+data:
+  candidates[]:
+    task: { id, epicId, title, status, ... }
+    readiness: { isReady, reason }
+    blockerSummary: { blockedByCount, totalDependencies, blockedBy[] }
+    ranking: { rank, blockerCount, statusPriority }
+  blocked[]: (same shape, non-ready items)
+  summary:
+    totalOpenTasks
+    readyCount
+    returnedCount
+    appliedLimit
+    blockedCount
+    unresolvedDependencyCount
+```
+
+## Reverse dependency walk
+
+```bash
+trekoon --toon dep reverse <task-or-subtask-id>
+```
+
+Payload fields:
+
+```text
+ok: true
+command: dep.reverse
+data:
+  targetId: <id>
+  targetKind: task|subtask
+  blockedNodes[]: { id, kind, distance, isDirect }
+```
+
+## Pagination contract for list calls
+
+```bash
+trekoon --toon task list --status todo --limit 2
+trekoon --toon task list --status todo --limit 2 --cursor 2
+```
+
+Cursor rules:
+
+- `--cursor <n>` is offset-like pagination for `epic list`, `task list`, and
+  `subtask list`
+- do not combine `--all` with `--cursor`
+- machine consumers should page using `meta.pagination.hasMore` and
+  `meta.pagination.nextCursor`
+
+Payload fields:
+
+```text
+ok: true
+command: task.list
+data:
+  tasks[]: ...
+metadata:
+  contractVersion: "1.0.0"
+  requestId: req-<stable-id>
+meta:
+  pagination: { hasMore, nextCursor }
+```
+
+## Descendant cascade update contract
+
+```bash
+trekoon --toon epic update <epic-id> --all --status done
+trekoon --toon task update <task-id> --all --status todo
+```
+
+Success payload fields for epic/task cascade mode:
+
+```text
+ok: true
+command: epic.update | task.update
+data:
+  epic | task: { ...updated root row... }
+  cascade:
+    mode: descendants
+    root: { kind: epic|task, id: <root-id> }
+    targetStatus: done|todo
+    atomic: true
+    changedIds[]
+    unchangedIds[]
+    counts:
+      scope
+      changed
+      unchanged
+      blockers
+      changedEpics
+      changedTasks
+      changedSubtasks
+```
+
+Failure contract for blocked epic/task cascade mode:
+
+```text
+ok: false
+error:
+  code: dependency_blocked
+data:
+  entity: epic|task
+  id: <root-id>
+  status: done|todo
+  atomic: true
+  changedIds[]
+  unchangedIds[]
+  blockerCount
+  blockedNodeIds[]
+  unresolvedDependencyIds[]
+  blockers[]:
+    sourceId
+    sourceKind
+    dependsOnId
+    dependsOnKind
+    dependsOnStatus
+    inScope
+    willCascade
+```
+
+Notes:
+
+- `subtask update <subtask-id> --all --status done|todo` is accepted, but it
+  returns the normal single-subtask `subtask.update` payload because there are
+  no descendants to traverse
+- Cascade mode is reserved for status-only close/reopen operations; combine
+  append/title/description changes in separate commands
+
+## Batch create and expand payloads
+
+Trekoon uses stable batch payloads for one-shot graph creation and sibling batch
+creation commands.
+
+### `epic create` and `epic expand`
+
+```bash
+trekoon --toon epic create --title "..." --description "..." --task "..."
+trekoon --toon epic expand <epic-id> --task "..."
+```
+
+Payload fields:
+
+```text
+ok: true
+command: epic.create | epic.expand
+data:
+  epic: { ... }                    # epic.create only
+  epicId: <epic-id>                # epic.expand only
+  tasks[]
+  subtasks[]
+  dependencies[]
+  result:
+    mappings[]: { kind, tempKey, id }
+    counts: { tasks, subtasks, dependencies }
+```
+
+### `task create-many`
+
+```bash
+trekoon --toon task create-many --epic <epic-id> --task "..."
+```
+
+Payload fields:
+
+```text
+ok: true
+command: task.create-many
+data:
+  epicId: <epic-id>
+  tasks[]
+  result:
+    mappings[]: { kind: task, tempKey, id }
+```
+
+### `subtask create-many`
+
+```bash
+trekoon --toon subtask create-many --task <task-id> --subtask "..."
+```
+
+Payload fields:
+
+```text
+ok: true
+command: subtask.create-many
+data:
+  taskId: <task-id>
+  subtasks[]
+  result:
+    mappings[]: { kind: subtask, tempKey, id }
+```
+
+## Sync compatibility mode
+
+Compatibility mode exists for integrations that still consume legacy sync
+command IDs:
+
+```bash
+trekoon --json --compat legacy-sync-command-ids sync status
+trekoon --toon --compat legacy-sync-command-ids sync pull --from main
+```
+
+Behavior:
+
+- default output uses canonical dotted IDs such as `sync.status`
+- compatibility mode rewrites sync command IDs to legacy forms such as
+  `sync_status`
+- compatibility mode is machine-only and valid only for `sync` commands
+- machine output includes `metadata.compatibility` with migration guidance and
+  removal timing
+
+## Related docs
+
+- [Quickstart](quickstart.md)
+- [Command reference](commands.md)
+- [AI agents and the Trekoon skill](ai-agents.md)

package/docs/plans/2026-03-15-trekoon-board-design.md

@@ -0,0 +1,13 @@
+<section name="problem">
+Add a no-install HTML board generated by Trekoon that opens fast and lets developers browse epics, filter/search, and manage tasks with kanban and list views. It should support inline editing, drag-and-drop status changes, and a GitLab-like task detail view with subtasks and dependencies. The board should be created on `trekoon init`, open via a CLI command, and be updatable with a future `trekoon board update` command. Include light/dark mode.
+</section>
+
+<section name="findings">
+- Visual design: Soft studio aesthetic with warm neutrals, layered surfaces, subtle gradients, and refined typography to keep dense data readable and calm.
+- Data flow: Pinia as the primary client-side state layer coordinating epics, filters/search, kanban status moves, and task edits across views.
+- UX flow: Emphasize speed, keyboard-first actions, progressive disclosure, inline editing, and context preservation using a split-view layout.
+</section>
+
+<section name="recommendation">
+Generate a static `board/index.html` on `trekoon init` with Vue + Tailwind via CDN, Pinia for shared state, and a small JSON payload from `trekoon epic list --all` embedded as initial data. Use a split-view layout: left column for epics and filters/search, right column for epic details with a tabbed kanban/list switch and a task detail drawer. Provide drag-and-drop in kanban to update status, inline edits in list rows, and a GitLab-style task detail view with subtasks and dependencies. Add a `trekoon board open` command to open the HTML file and a `trekoon board update` command to refresh the generated assets. Support light/dark mode via CSS variables and a theme toggle persisted in localStorage.
+</section>