Skip to content

quickstart.md

Latest commit

 

History

History
319 lines (236 loc) · 11.4 KB

quickstart.md

File metadata and controls

319 lines (236 loc) · 11.4 KB

Quickstart

Shortest path from zero to a working Trekoon workflow.

Recommended human workflow

If you are driving Trekoon with an AI agent, the usual path is:

/trekoon brainstorm: <topic>   # optional, design only
/trekoon plan <goal>
/trekoon <epic-id>
/trekoon <epic-id> execute
  • Use brainstorm: when the design is still fuzzy. The agent should explore options, recommend a lean path, and wait for acceptance before creating Trekoon items.
  • Use plan after you already have enough context from discussion, brainstorming, or research. Trekoon should turn that context into an execution-ready epic.
  • Use trekoon <epic-id> to inspect the created epic, next ready work, and any blockers before starting execution.
  • Use execute when you want the agent to keep working through the epic until it is done, all remaining work is blocked, or it needs your input.

The rest of this page is mostly the lower-level command surface that agents and power users rely on.

Brainstorm before planning

Use the skill's brainstorm mode when you need design help before Trekoon creates tracked work:

/trekoon brainstorm: <topic>

Brainstorming is intentionally not a planning command. The agent should inspect available context, compare a few approaches, ask focused questions, and preserve accepted decisions. It should create no epics, tasks, subtasks, dependencies, or status updates until you accept the design and ask it to plan.

How storage works

Trekoon keeps one SQLite database per repository at .trekoon/trekoon.db. In worktree setups, all worktrees share the same database because storage resolves from the repository root.

Key points:

  • .trekoon is gitignored. It's operational state, not source code.
  • Outside git repos, Trekoon falls back to the current working directory.
  • worktreeRoot is your checkout. sharedStorageRoot is the repo root that owns .trekoon.

Initialize

trekoon init
trekoon --version

If an agent is driving the workflow:

trekoon --toon init
trekoon --toon sync status

Run init once per repository. It creates the shared storage root. If sync status reports recoveryRequired or a tracked/ignored mismatch, fix the setup before continuing.

Open the board

trekoon board open

Starts a loopback-only server on 127.0.0.1, opens the browser, and prints a fallback URL. Board code (HTML, JS, CSS, fonts) comes from the running Trekoon install; board data comes from the repo where the command is invoked. The board works fully offline. To get an updated board UI, update Trekoon itself. Old ignored .trekoon/board copies are left on disk but are no longer used.

Create work

trekoon --toon epic create --title "Agent backlog stabilization" --description "Track stabilization work" --status todo
trekoon task create --title "Implement sync status" --description "Add status reporting" --epic <epic-id> --status todo
trekoon subtask create --task <task-id> --title "Add cursor model" --status todo

Browse results:

trekoon task list
trekoon task list --status done
trekoon task list --limit 25
trekoon task list --all --view compact

One-shot planning

If you already know the full epic tree, create everything in one call:

trekoon --toon epic create \
  --title "Batch command rollout" \
  --description "Ship one-shot planning workflows" \
  --task "task-a|First task|First description|todo" \
  --task "task-b|Second task|Second description|todo" \
  --subtask "@task-a|sub-a-first|First subtask|Subtask description|todo" \
  --dep "@task-b|@task-a" \
  --dep "@sub-a-first|@task-a"

All temp keys (task and subtask) must be unique across the whole command — they share one flat namespace. Declare temp keys bare in --task / --subtask, but reference same-command keys with @ in parent and dependency fields. For example, --task "task-a|First task|First description" declares task-a, while --subtask "@task-a|sub-a-first|First subtask|Subtask description" references it. Prefix subtask keys with the parent task key to stay unique.

Subtasks in epic create / epic expand require both title and description: @parent|key|title|description. Do not collapse the subtask into @parent|key|long title.

Trekoon accepts common aliases (--desc for --description, plus --deps, --dependency, --dependencies, --dependancy, and --dependancies for --dep). Treat them as recovery paths for agent input. Use canonical --description and --dep in reusable prompts and scripts.

Escape any literal | inside field values as \|. Three recurring footguns:

  • Single mid-value | on a spec without explicit |<status> silently pushes trailing text into the status slot (e.g. Verify: bun test foo | tail lets tail become the status, and creation still succeeds). Specs that already pass |<status> fail loudly on the same input.
  • || (JS logical-OR a || b, shell OR cmd || cmd) adds two extra fields per occurrence; the field-count gate rejects with Task specs must use ... / Subtask specs must use .... Rephrase || as "or" or escape as \|\|.
  • Trailing | is not a terminator. It creates an empty final field; on a 4-field subtask shape that empty field becomes the description and the parser rejects with "is missing a description". Drop trailing pipes.

Pre-flight any batch before invoking epic create/epic expand/task create-many/subtask create-many:

grep -nE '(^|[^\\])\|\||\|$' specs.txt

See the planning skill for full rules.

This is better than sequential creates because later records can reference earlier ones with @temp-key, and you get one atomic operation with mappings and counts in the response.

Dependencies

trekoon dep add <task-id> <depends-on-id>
trekoon dep list <task-id>

Batch commands

For larger updates, use batch commands instead of looping:

Need Command
Multiple tasks under one epic trekoon task create-many --epic <epic-id> --task ...
Multiple subtasks under one task trekoon subtask create-many <task-id> --subtask ...
Multiple dependency edges trekoon dep add-many --dep ...
Expand an existing epic trekoon --toon epic expand <epic-id> ...

These validate the whole batch before applying, so a bad input fails the entire operation instead of leaving partial state.

Close or reopen a whole tree

trekoon epic update <epic-id> --all --status done
trekoon task update <task-id> --all --status done

Cascades atomically through all descendants. If any descendant has an unresolved external dependency, the whole update fails with no partial writes. Works with --status done and --status todo only.

Export an epic to Markdown

trekoon epic export <epic-id>
trekoon epic export <epic-id> --path docs/plan.md        # exact file
trekoon epic export <epic-id> --path docs/plans           # default name inside dir
trekoon epic export <epic-id> --overwrite

Writes a readable Markdown snapshot under plans/ by default. With --path, a file extension means "write this file"; no extension means "put the default- named file in this directory". Use --overwrite to resave after the plan state changes.

Claim work atomically

When multiple agents or lanes work in parallel, use claim to avoid races:

trekoon task claim <task-id> --owner <owner>
trekoon subtask claim <subtask-id> --owner <owner>

Both commands use a SQL compare-and-swap: the claim succeeds only when the item is todo or blocked and the owner is NULL or already set to <owner>. 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:

trekoon migrate backup
trekoon migrate backup --retain 5   # keep last 5 backups (default 10)

This writes a timestamped copy of .trekoon/trekoon.db next to the live file. To check the current schema version or roll back:

trekoon migrate status
trekoon migrate rollback              # one version back
trekoon migrate rollback --to-version 1

Daemon mode (experimental)

Not for routine agent use. trekoon serve and --daemon are experimental; use the default one-shot CLI path in automated workflows.

trekoon serve starts a foreground daemon on a Unix-domain socket inside .trekoon. Subsequent calls skip Bun startup, module load, and database open — per bench/daemon-session.ts: daemon median < 10 ms vs. cold one-shot median > 50 ms:

trekoon serve                         # start the daemon (foreground)
trekoon --daemon session              # route a call through the daemon
TREKOON_DAEMON=1 trekoon session      # same, via environment variable

If the socket is missing or unreachable the client falls back silently to the normal one-shot path. The socket is 0o600 and .trekoon is forced to 0o700.

Check progress

trekoon epic progress <epic-id>
trekoon suggest
trekoon suggest --epic <epic-id>

epic progress returns task status counts and the next ready candidate. suggest gives priority-ranked next-action recommendations.

Status machine

Trekoon enforces status transitions. The statuses are todo, in_progress, done, and blocked.

From Allowed targets
todo in_progress, blocked
in_progress done, blocked
blocked in_progress, todo
done in_progress

Direct jumps like todo to done are rejected. Use task done instead, which auto-transitions through in_progress.

Install the AI skill

trekoon skills install                # repo-local (default)
trekoon skills install -g             # global (~/.agents/skills/trekoon)
trekoon skills install --link --editor claude  # repo-local + editor symlink

After upgrading Trekoon, refresh installed skills:

trekoon update                        # alias for: trekoon skills update

For agent integration details, see AI agents and the Trekoon skill.

Pre-merge sync

Before opening or merging a PR:

trekoon --toon sync status
trekoon --toon sync pull --from main
trekoon --toon sync conflicts list
trekoon --toon sync conflicts show <id>
trekoon --toon sync resolve <id> --use theirs --dry-run
trekoon --toon sync resolve <id> --use ours|theirs
trekoon --toon sync resolve --all --use ours          # batch: all pending at once
trekoon --toon sync status

Always run sync conflicts show before resolving so you know what you're overwriting. For uniform conflicts, --all resolves every pending conflict in one command. Optional --entity <id> and --field <name> narrow the batch. In human mode, --use theirs prompts for both single-conflict and batch resolve. Single-conflict prompts include field/value details; batch prompts use a count-only confirmation. All prompts time out after 30 seconds and default to rejection. Toon mode skips prompts.

What to read next