trekoon 0.4.1 → 0.4.3

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

@@ -1,292 +1,292 @@
 # Planning Reference
 
-Write implementation plans directly into Trekoon as epics with task/subtask
-DAGs. Plans must be directly executable without re-interpretation.
+Write plans directly into Trekoon as epics with task/subtask DAGs. A plan is
+done only when the epic exists, the graph is validated, and the user can run
+`trekoon <epic-id> execute` without reinterpretation.
 
-**Plan mode contract:** planning is complete only when the epic exists in
-Trekoon, the dependency graph is validated, and the user can immediately run
-`trekoon <epic-id> execute`.
+Ask planning-critical questions before writing. Use the harness question tool
+when available (`question`, `AskUserQuestion`, or native equivalent); otherwise
+ask one concise plain-text question. Use multi-select only for independent
+features that can combine. Use single-select for mutually exclusive choices.
 
-**Clarify ambiguity upfront.** If the plan has unclear requirements or meaningful
-tradeoffs, ask the user before writing. Present options with clear tradeoffs.
-Use multi-select for independent features that can be combined; use single-select
-for mutually exclusive choices.
+## Before You Create Records
 
-Use the harness's interactive user-question tool when you need clarification:
+Synthesize existing context instead of rediscovering it:
 
-- OpenCode: `question`
-- Claude Code: `AskUserQuestion`
+1. Goal and user outcome.
+2. Decisions already made and rejected options.
+3. Constraints: architecture, compatibility, safety, timelines, libraries.
+4. Affected areas: subsystems, paths, interfaces, workflows.
+5. Verification evidence needed for completion.
+6. Unknowns that block graph creation.
 
-Do not hide planning-critical questions inside a long narrative response.
+If the brief is sufficient, plan. If not, do targeted research or ask one narrow
+question. Preserve prior user decisions unless they explicitly reopen them.
+Expand existing Trekoon items when they already represent the work.
 
-## Pre-plan synthesis
+## Data Model
 
-Before creating or expanding an epic, synthesize the context you already have.
-Planning should consume previous brainstorming, research, and codebase discovery
-rather than redoing it from scratch.
+- Epic: full outcome, scope, constraints, and verification gates.
+- Task: one complete subsystem/domain work unit that one agent can own.
+- Subtask: concrete implementation/test/verification step under a task.
+- Dependency: hard prerequisite only, not "nice to have" ordering.
 
-Build a short internal planning brief with:
+All new entities start as `todo`. Do not create records as `in_progress`,
+`blocked`, or `done`.
 
-1. **Goal** — what outcome the user wants
-2. **Decisions already made** — chosen direction, rejected options, known tradeoffs
-3. **Known constraints** — architecture, library constraints, timelines, safety, compatibility
-4. **Affected areas** — subsystems, files, interfaces, or workflows likely involved
-5. **Verification expectations** — what evidence will prove the work is complete
-6. **Remaining unknowns** — only the ones that actually block graph creation
+## Write Detailed, Executable Records
 
-If the brief is already sufficient, go straight into planning. If important
-unknowns remain, do targeted research or ask a narrow user question before
-creating the graph.
+### Epic
 
-## Research-aware planning rules
-
-- Reuse research conclusions in the epic and task descriptions.
-- Carry forward concrete patterns, file paths, APIs, and constraints that were
-  discovered earlier.
-- Do not replace prior decisions with generic planning boilerplate.
-- If the user already chose an approach during brainstorming, plan that approach
-  unless they explicitly reopen the decision.
-- If existing Trekoon items already represent part of the work, expand or refine
-  them instead of recreating parallel tracking state.
-
-## Planning data model
-
-- **Epic** = full feature outcome and constraints.
-- **Task** = one complete subsystem/domain work unit that can be owned by one
-  agent.
-- **Subtask** = concrete implementation/test/verification step under a task.
-- **Dependency edge** = strict prerequisite only (do not add "nice to have"
-  dependencies).
-
-All entities start in `todo`. See the status machine in the main SKILL.md.
-
-Plan implications:
-- Never set initial status to anything other than `todo` in create commands.
-- Task descriptions should reference valid transitions when documenting
-  completion flow (e.g., "todo -> in_progress -> done", not "todo -> done").
-- `task done` auto-transitions through `in_progress`, but `task update` does
-  not — plan descriptions should note this for agents.
-
-## Information-dense writing standard
-
-### Epic title
-
-Use a functional, outcome-oriented format:
+Title format:
 
 `<Product/Area>: <deliverable> to <user/system outcome> (<key constraint>)`
 
-Example: `Checkout: add idempotent payment capture to prevent duplicate charges
-(Stripe + retries)`
-
-### Epic description
+Description must include:
 
-Include:
+- Goal and why now.
+- In scope and out of scope.
+- Success criteria.
+- Risks and constraints.
+- Verification gates.
+- Key prior decisions or research findings that affect implementation.
 
-1. **Goal & why now**
-2. **In scope** (specific capabilities)
-3. **Out of scope** (explicit exclusions)
-4. **Success criteria** (testable outcomes)
-5. **Risks/constraints** (data migration, latency budgets, auth boundaries)
-6. **Verification gates** (tests, manual checks, perf/security checks)
-7. **Key prior decisions or research findings** when they materially affect the
-   implementation path
+### Task
 
-### Task title
-
-Use a structure that encodes subsystem + action + outcome:
+Title format:
 
 `[<Subsystem>] <verb> <artifact/interface> to <observable outcome>`
 
-Example: `[API/Auth] issue refresh-token rotation endpoint to invalidate
-replayed sessions`
-
-### Task description
+Description must include:
 
-Must include:
-
-- concrete scope and affected paths/symbols
-- acceptance criteria (observable behavior)
-- required tests/verification commands
-- integration constraints (contracts, backward compatibility)
-- explicit "can run in parallel with ..." or "blocked by ..." note
-- relevant findings from prior research or brainstorming that execution agents
-  should not have to rediscover
-
-**File scope** — declare explicitly so the agent doesn't waste tokens exploring:
-
-- **Target files**: files to create or modify
-- **Read-first files**: files the agent should read for context
-- **Do-not-touch**: paths that parallel agents own — prevents merge conflicts
-
-**Context loading hints** — point the agent to existing patterns:
-
-- Reference a concrete file as the pattern to mirror
-- Name the specific function/class/export to extend or integrate with
-- State project conventions rather than assuming the agent will discover them
-
-**Owner assignment** — when the plan has clear subsystem lanes, assign owners in
-task descriptions so the executor knows which agent/person owns each task:
-
-```
-Owner: auth-lane
-Can run in parallel with: billing-lane tasks
-```
+- Target files: files to create or modify.
+- Read first: files, functions, or patterns to inspect before editing.
+- Do not touch: paths owned by other lanes.
+- Acceptance criteria with observable behavior.
+- Required tests or manual verification commands.
+- Integration constraints and compatibility requirements.
+- Owner/lane when clear.
+- Parallelism note: "can run in parallel with ..." or "blocked by ...".
+- Relevant prior findings so execution agents do not rediscover context.
 
-Example task description:
+Example:
 
-```
+```text
 Implement refresh-token rotation endpoint.
 
 Target files: src/auth/refresh.ts (new), src/auth/refresh.test.ts (new)
-Read first: src/auth/login.ts (follow same handler pattern)
+Read first: src/auth/login.ts (follow handler pattern)
 Do not touch: src/billing/* (owned by billing-lane)
 
-Follow the handler pattern in login.ts: schema validation -> service call ->
-response mapping.
-
-Acceptance: POST /auth/refresh returns new token pair, invalidates old token.
+Follow login.ts: schema validation -> service call -> response mapping.
+Acceptance: POST /auth/refresh returns a new token pair and invalidates old token.
 Verify: bun test src/auth/refresh.test.ts
 Owner: auth-lane
-Can run in parallel with: billing-lane. Blocked by: task-types (needs AuthToken).
+Can run in parallel with: billing-lane. Blocked by: task-types.
 ```
 
-### Subtask title/description
-
-- Titles are imperative and specific, not generic.
-- Description states exact artifact and completion signal.
-- Use subtasks for real units, not filler checklist noise.
-- Inherit file scope from parent task — only override if different files.
-
-## Parallelism & dependencies
-
-Model execution lanes intentionally:
+### Subtask
+
+- Use imperative, specific titles.
+- State exact artifact and completion signal.
+- Use subtasks for real execution units, not filler checklist noise.
+- Inherit parent task file scope unless a subtask differs.
+
+## Design For Delegated Execution
+
+Plan so meaningful independent work can run in subagents:
+
+- Tasks with no dependency edge are parallel candidates.
+- Different subsystems usually become different lanes.
+- Same subsystem work should usually be grouped or sequenced.
+- Keep each active subsystem lane to about 3-4 tasks.
+- Add owners after creation when lanes are clear:
+  ```bash
+  trekoon --toon task update <task-id> --owner auth-lane
+  trekoon --toon task update <task-id> --owner billing-lane
+  ```
+
+Use dependencies only for hard prerequisites. Prefer task-to-task dependencies.
+Use subtask dependencies only when task-level ordering is too coarse.
+
+## Create Records Efficiently
+
+Use `--toon` on every planning command. It saves tokens and gives agents a
+stable structured response.
+
+Prefer one transactional planning command over repeated single-item creates. If
+you know the epic, tasks, subtasks, and dependencies, one-shot the whole epic
+with `epic create --task ... --subtask ... --dep ...`. This saves tool calls and
+keeps the graph internally consistent.
+
+| Situation | Command |
+|---|---|
+| New epic with known graph | Prefer `trekoon --toon epic create ... --task ... --subtask ... --dep ...` |
+| Existing epic needs linked additions | `trekoon --toon epic expand <epic-id> ...` |
+| Many sibling tasks | `trekoon --toon task create-many --epic <epic-id> --task ...` |
+| Many sibling subtasks | `trekoon --toon subtask create-many <task-id> --subtask ...` |
+| Many dependency edges across existing IDs | `trekoon --toon dep add-many --dep ...` |
+| One record only | `epic create`, `task create`, or `subtask create` |
+
+Compact specs use pipe-delimited values. `\` is the escape character:
+
+| Sequence | Produces |
+|---|---|
+| `\|` | literal `|` |
+| `\\` | literal `\` |
+| `\n` | newline |
+| `\r` | carriage return |
+| `\t` | tab |
+
+Any other `\X` is invalid. Do not paste regex-escaped or shell-escaped
+patterns directly into compact specs: sequences like `\?`, `\.`, `\{`, `\}`,
+`\(`, `\)`, `\[`, and `\]` will fail before records are created. When a task
+description needs a search pattern, prefer prose over exact regex syntax. Avoid
+operators like `!=` in descriptions because shell or compact-spec escaping can
+be confusing; rephrase as words.
+
+Good:
+
+```text
+Verify: search docs for currentUpdatedAt, updatedAt-ms, SSE auth token rides, and token query contract text.
+```
 
-- Tasks with no dependency edge between them are parallel candidates.
-- Tasks in different subsystems should usually run in parallel.
-- Tasks in the same subsystem should be combined or sequenced.
-- Keep task groups to ~3-4 tasks per active subsystem lane.
+Bad:
 
-Dependency policy:
+```text
+Verify: search with regex "currentUpdatedAt|<updatedAt-ms>|/api/snapshot/stream\?token|\?token=\{token\}" in docs and README.md
+```
 
-1. Add an edge only for hard prerequisites.
-2. Prefer task-to-task dependencies; use subtask dependencies only when required.
-3. Validate acyclic graph assumptions before finalizing.
+One-shot rules:
 
-## Assign owners after creation
+- Declare tasks/subtasks with plain temp keys, e.g. `task-api`, `sub-tests`.
+- Refer to records created in the same command as `@task-api` or `@sub-tests`.
+- Use `@task-key` as the subtask parent ref and in `--dep` specs.
+- `--dep <source>|<depends-on>` points from blocked item to prerequisite.
+- `epic create` returns `result.mappings` and counts. Use those real UUIDs in
+  handoff summaries and follow-up updates. Never show temp keys as real IDs.
+- `dep add-many` does not resolve temp keys from earlier commands. Use real IDs.
 
-After creating tasks, assign ownership for multi-agent execution:
+One-shot example:
 
 ```bash
-trekoon --toon task update <task-id> --owner auth-lane
-trekoon --toon task update <task-id> --owner billing-lane
+trekoon --toon epic create \
+  --title "Checkout: add idempotent payment capture" \
+  --description "Goal: prevent duplicate charges.\nVerification: bun test tests/payments" \
+  --task "task-api|[API] add capture endpoint|Target files: src/payments/capture.ts\nRead first: src/payments/service.ts\nDo not touch: src/ui/*\nAcceptance: duplicate request returns prior result.\nVerify: bun test tests/payments/capture.test.ts\nOwner: api-lane\nCan run in parallel with: task-ui.|todo" \
+  --task "task-ui|[UI] show capture states|Target files: src/ui/checkout.tsx\nRead first: src/ui/form.tsx\nDo not touch: src/payments/*\nAcceptance: loading and retry states render.\nVerify: bun test tests/ui/checkout.test.ts\nOwner: ui-lane\nBlocked by: task-api.|todo" \
+  --subtask "@task-api|sub-api-tests|Write capture tests|Cover idempotent retry and conflict responses.|todo" \
+  --subtask "@task-ui|sub-ui-states|Write UI state tests|Cover loading, success, retry, and error states.|todo" \
+  --dep "@task-ui|@task-api"
 ```
 
-## Validate the plan
+## Append Efficiently
 
-After creating the epic, validate before handing off to execution.
+Use `--append` for progress notes, shared findings, verification requirements,
+or planning refinements. Appending is cheaper and safer than rewriting full
+descriptions.
 
-### Check progress structure
+Entity-specific append:
 
 ```bash
-trekoon --toon epic progress <epic-id>
+trekoon --toon epic update <epic-id> --append "Planning note: <text>"
+trekoon --toon task update <task-id> --append "Planning note: <text>"
+trekoon --toon subtask update <subtask-id> --append "Planning note: <text>"
 ```
 
-Verify: total count matches expectations, all tasks are in `todo`, ready count
-equals the number of tasks with no dependencies.
-
-### Run suggest to confirm sanity
+Append to selected tasks or subtasks with IDs from `result.mappings`:
 
 ```bash
-trekoon --toon suggest --epic <epic-id>
+trekoon --toon task update --ids id1,id2,id3 --append "Shared verification: bun test tests/payments"
+trekoon --toon subtask update --ids id1,id2 --append "Shared note: follow capture endpoint contract"
 ```
 
-`suggest` will surface issues: sync gaps, recovery needs, or unexpected blocker
-states. If it suggests claiming a task, the plan's dependency graph is valid and
-execution-ready.
+Important:
 
-### Verify dependency graph
+- `epic update <epic-id> --append ...` appends only to the epic description.
+- There is no scoped "append to all tasks in this epic" command. Use task IDs
+  from one-shot mappings, `epic show --all`, or `task ready`, then
+  `task update --ids ... --append ...`.
+- Do not use `task update --all --append ...` unless you truly mean every task
+  in the database.
+- `epic update <epic-id> --all` is cascade status mode only and rejects
+  `--append`.
+- Bulk append is per-row, not one atomic transaction.
+
+## Validate Before Handoff
+
+After creating or expanding the epic:
 
 ```bash
+trekoon --toon epic progress <epic-id>
+trekoon --toon suggest --epic <epic-id>
 trekoon --toon task ready --epic <epic-id> --limit 50
 ```
 
-Confirm that the expected first-wave tasks appear as ready candidates and
-second-wave tasks appear as blocked with the right dependencies.
-
-## Plan output and handoff
+Verify:
 
-After creating the epic and validating, present a summary to the user. This
-summary is the primary handoff artifact — it must be self-contained and
-actionable.
+- Counts match expectations.
+- All new tasks are `todo`.
+- Ready count equals first-wave tasks with no dependencies.
+- Blocked tasks show the expected dependencies.
+- `suggest` returns a sensible first execution candidate and no recovery/sync
+  issue that blocks execution.
 
-Do not stop at a prose-only design. The final handoff must reference the actual
-Trekoon epic and the first execution wave.
+## Handoff Summary
 
-### ID rules
+Do not stop at a prose-only design. Return the actual Trekoon epic and first
+execution wave.
 
-- **Always use full UUIDs** for epic and task IDs. Never use temp-keys
-  (`task-truthy`, `@task-api`, etc.) in the summary — those are ephemeral
-  creation-time references that do not exist in the database.
-- IDs must be copy-friendly: render them in monospace/code formatting so the
-  user can select and copy a UUID directly.
+Rules:
 
-### Summary structure
+- Always use full UUIDs for epic/task IDs in summaries.
+- Never use temp keys (`task-api`, `@sub-tests`) outside create commands.
+- Render IDs in code formatting.
+- Group tasks by wave with title, owner/lane, and dependencies.
+- Include final verification gate.
 
-1. **Epic ID + title** — displayed prominently at the top, e.g.:
-   ```
-   Epic: <full-uuid>
-   Title: <epic title>
-   ```
-2. Tasks grouped by wave/batch with columns: full UUID, title, owner/lane
-3. Dependencies shown per task (using full UUIDs or task titles, not temp-keys)
-4. Verification gate (commands to run after all tasks complete)
+Format:
 
-### Example format
-
-```
-Epic: 904b3129-be2d-4b20-8030-537dc327491a
-Title: Checkout: add idempotent payment capture
+```text
+Epic: <full-uuid>
+Title: <epic title>
 
 Wave 1 (parallel)
-| ID                                   | Task                          | Owner        |
-|--------------------------------------|-------------------------------|--------------|
-| c12c9746-dbae-4660-bcbb-ebe660cb7054 | [API] Payment capture endpoint| api-lane     |
-| 4f0848f3-538a-44d3-8415-5bb16cf3f39e | [UI] Checkout button states   | ui-lane      |
+| ID | Task | Owner |
+|---|---|---|
+| <uuid> | [API] Payment capture endpoint | api-lane |
 
-Wave 2 (depends on wave 1)
-| ID                                   | Task                          | Depends on                           |
-|--------------------------------------|-------------------------------|--------------------------------------|
-| 8a76afac-155d-45b3-b205-df2e4ef8988b | [API] Retry logic             | c12c9746-dbae-4660-bcbb-ebe660cb7054 |
+Wave 2
+| ID | Task | Depends on |
+|---|---|---|
+| <uuid> | [API] Retry logic | <wave-1-uuid> |
 
 Verification: bun run build && bun run test
 ```
 
-### Execution handoff contract
+## Search And Replace
+
+Use scoped search before manual tree reads when locating repeated paths, labels,
+owners, or migration targets.
 
-Every plan must be directly executable without re-interpretation. Include these
-in task descriptions:
+Narrowest valid scope first:
 
-1. **Lane/subsystem ownership** (`[Subsystem] ...` in title, `--owner` set).
-2. **Dependency intent** (explicit `blocked by ...` / `can run in parallel
-   with ...`).
-3. **Verification evidence** (exact commands and expected outcome).
-4. **Completion semantics** (`done` means verified and handoff-ready; use
-   `blocked` with reason when not).
-5. **Stable contract** (execution appends progress notes rather than rewriting
-   original plan text unless the plan itself is wrong).
+1. `subtask search` / `subtask replace`
+2. `task search` / `task replace`
+3. `epic search` / `epic replace`
 
-## Quality rules
+Workflow:
 
-1. **No markdown plan files** as source of truth.
-2. **No vague titles** ("Refactor stuff", "Fix bugs").
-3. **Descriptions must be implementation-usable** by another agent without
-   guessing.
-4. **Every task must define completion evidence** (tests/manual checks).
-5. **Parallelism must be explicit** (not implied).
-6. **Status transitions must be valid** — never describe a `todo -> done` flow.
-7. **Owners should be assigned** when multiple execution lanes exist.
+```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
+```
 
-## Large initiatives
+Guardrails:
 
-For large scope, create multiple epics with explicit cross-epic boundaries. Use
-dependencies within each epic DAG and keep each epic executable in bounded time.
+- Use literal, explicit search text.
+- Narrow fields when useful: `--fields title`, `--fields description`, or
+  `--fields title,description`.
+- Preview before `--apply`.
+- Prefer scoped replace over manually editing many records one by one.

package/.agents/skills/trekoon/reference/status-machine.md

@@ -0,0 +1,21 @@
+# Status Machine Reference
+
+Trekoon enforces a status transition graph. Only these transitions are valid:
+
+| From | Allowed targets |
+|---|---|
+| `todo` | `in_progress`, `blocked` |
+| `in_progress` | `done`, `blocked` |
+| `blocked` | `in_progress`, `todo` |
+| `done` | `in_progress` |
+
+Invalid transitions (e.g. `todo → done`) return error code
+`status_transition_invalid`. Always transition through `in_progress` to reach
+`done`.
+
+**Exception:** `task done` auto-transitions through `in_progress` when the task
+is in `todo` or `blocked` status, so you can call `task done` from any
+non-done status.
+
+Recommended statuses for consistent workflows: `todo`, `in_progress`, `done`.
+Use `blocked` with an appended reason when work is stuck.

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

@@ -0,0 +1,82 @@
+# Sync Reference
+
+Trekoon uses one live SQLite database per repository at
+`<sharedStorageRoot>/.trekoon/trekoon.db`. Linked worktrees share it. `git
+checkout` and `git switch` do not roll back tracker state. Sync imports tracker
+events between branches; never copy or commit the `.db` file.
+
+Same-branch sync is a no-op. Cross-branch sync matters before merging a feature
+branch back.
+
+## Before Merge
+
+Pull tracker events from the base branch:
+
+```bash
+trekoon --toon sync pull --from main
+```
+
+If conflicts exist:
+
+```bash
+trekoon --toon sync conflicts list
+trekoon --toon sync conflicts show <conflict-id>
+trekoon --toon sync resolve <conflict-id> --use theirs --dry-run
+trekoon --toon sync resolve <conflict-id> --use ours
+```
+
+## Conflict Rules
+
+Conflicts are field-level, not whole-record. Each conflict targets one field on
+one entity.
+
+- `--use ours`: keep the current shared DB field value; mark conflict resolved.
+- `--use theirs`: write the source-branch field value into the shared DB; mark
+  conflict resolved.
+- `--dry-run`: preview without mutation. Returns `oursValue`, `theirsValue`,
+  `wouldWrite`, and `dryRun: true`.
+
+Always inspect with `sync conflicts show` before resolving. Choosing `theirs`
+without inspection can overwrite in-progress shared DB work.
+
+Typical choices:
+
+| Scenario | Usually use | Why |
+|---|---|---|
+| Completed work vs stale main | ours | Your branch has latest progress |
+| Enriched descriptions vs original | ours | Your descriptions are more detailed |
+| Upstream updates from another agent | theirs | Accept newer upstream state |
+| User-intentional reset | theirs | Respect explicit user action |
+
+When unsure, ask the user.
+
+## Batch Resolve
+
+```bash
+trekoon --toon sync resolve --all --use ours --dry-run
+trekoon --toon sync resolve --all --use ours
+trekoon --toon sync resolve --all --use ours --field status
+trekoon --toon sync resolve --all --use theirs --entity <id>
+trekoon --toon sync resolve --all --use ours --entity <id> --field description
+```
+
+Use batch resolve only when the conflict pattern is uniform. Otherwise inspect
+and resolve individually or narrow by `--entity` / `--field`.
+
+## Worktree Scope
+
+Inspect machine-readable storage fields when debugging worktrees:
+`storageMode`, `repoCommonDir`, `worktreeRoot`, `sharedStorageRoot`, and
+`databaseFile`.
+
+Conflicts are scoped per worktree and branch. `sync conflicts list` and
+`sync resolve` only act on rows for the current worktree/branch, so resolving a
+conflict does not erase a peer worktree's conflict on the same entity.
+
+## Destructive Recovery
+
+`sharedStorageRoot` is the repo-scoped source of truth for `.trekoon` in git
+worktrees. If the user explicitly requests `trekoon wipe --yes --toon`, warn
+that it deletes shared storage for the whole repository and every linked
+worktree. Wipe is destructive recovery only; it is never the fix for a tracked
+DB or gitignore mistake.