trekoon 0.3.2 → 0.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. package/.agents/skills/trekoon/SKILL.md +55 -6
  2. package/README.md +156 -122
  3. package/docs/ai-agents.md +105 -104
  4. package/docs/commands.md +137 -167
  5. package/docs/machine-contracts.md +67 -68
  6. package/docs/quickstart.md +87 -143
  7. package/package.json +2 -2
  8. package/src/board/assets/state/utils.js +1 -1
  9. package/src/commands/arg-parser.ts +10 -0
  10. package/src/commands/help.ts +243 -239
  11. package/src/commands/quickstart.ts +67 -77
  12. package/src/commands/skills.ts +517 -168
  13. package/src/commands/sync.ts +93 -5
  14. package/src/domain/tracker-domain.ts +210 -37
  15. package/src/runtime/cli-shell.ts +5 -0
  16. package/src/storage/events-retention.ts +72 -0
  17. package/src/storage/migrations.ts +28 -0
  18. package/src/sync/event-writes.ts +8 -6
  19. package/src/sync/service.ts +80 -52
  20. package/src/sync/types.ts +12 -0
package/src/commands/quickstart.ts CHANGED
@@ -4,90 +4,73 @@ import { type CliContext, type CliResult } from "../runtime/command-types";
4
4
  const QUICKSTART_TEXT = [
5
5
  "Trekoon quickstart",
6
6
  "",
7
- "This quickstart is aligned with .agents/skills/trekoon/SKILL.md.",
8
- "For agents: always use --toon for every command.",
7
+ "Agents: always use --toon on every command.",
8
+ "Aligned with: .agents/skills/trekoon/SKILL.md",
9
9
  "",
10
- "1) Shared storage model",
11
- "- In git repos and worktrees, Trekoon resolves one repo-scoped .trekoon directory.",
12
- "- Every worktree for the same repo points at the same .trekoon/trekoon.db file.",
13
- "- Keep .trekoon gitignored: the SQLite DB is live operational state, not source.",
14
- "- Committing the DB is the wrong fix for setup drift because it snapshots machine-local state.",
10
+ "1) Storage model",
11
+ " In git repos and worktrees, Trekoon keeps one shared .trekoon directory",
12
+ " and one shared .trekoon/trekoon.db database per repository.",
13
+ " Keep .trekoon gitignored. The DB is live state, not source code.",
14
+ " Don't commit the DB; that snapshots machine-local state and won't help.",
15
15
  "",
16
- "2) Bootstrap and agent startup (primary)",
17
- "- Single call: trekoon --toon session",
18
- "- Replaces: init + sync status + task next + dep list + task show in one call.",
19
- "- Returns diagnostics, next ready task, its dependencies, and full task payload.",
20
- "- If diagnostics show recoveryRequired or a tracked/ignored mismatch, stop and repair setup.",
21
- "- Do not continue after storage mismatch, ambiguous recovery, or broken bootstrap warnings.",
22
- "- In worktrees, confirm meta.storageRootDiagnostics.sharedStorageRoot matches the repo root.",
16
+ "2) Agent startup",
17
+ " Single call: trekoon --toon session",
18
+ " Returns diagnostics, sync status, next ready task, its dependencies,",
19
+ " and the full task payload. Replaces init + sync status + task next in one call.",
23
20
  "",
24
- "2a) Bootstrap (manual/legacy — use session instead)",
25
- "- 1. Initialize or verify shared storage: trekoon --toon init",
26
- "- 2. Read machine diagnostics: trekoon --toon sync status",
27
- "- 3. Select next task: trekoon --toon task next",
28
- "- 4. Check dependencies: trekoon --toon dep list <task-id>",
29
- "- 5. Show full task: trekoon --toon task show <task-id> --all",
21
+ " If diagnostics show recoveryRequired or a tracked/ignored mismatch,",
22
+ " stop and fix the setup before continuing.",
30
23
  "",
31
- "3) AI execution loop (deterministic, dependency-aware)",
32
- "- 1. Start or resume session: trekoon --toon session",
33
- "- 2. Claim work: trekoon --toon task update <task-id> --status in_progress",
34
- "- 3. Complete with context: trekoon --toon task done <task-id> --append \"Completed implementation\"",
35
- " - Replaces: update status done + task next + dep list + task show in one call.",
36
- " - Returns next ready task, its dependencies, and full task payload.",
37
- "- 4. Or report block: trekoon --toon task update <task-id> --append \"Blocked by <reason>\" --status blocked",
24
+ " Manual bootstrap (step by step):",
25
+ " trekoon --toon init",
26
+ " trekoon --toon sync status",
27
+ " trekoon --toon task next",
38
28
  "",
39
- "4) Worktree diagnostics and recovery",
40
- "- Read machine fields when available: storageMode, repoCommonDir, worktreeRoot, sharedStorageRoot, databaseFile.",
41
- "- sharedStorageRoot differs from worktreeRoot in linked worktrees; that is expected and should be visible.",
42
- "- If recoveryRequired is true, run trekoon --toon init and follow the reported recovery action before more commands.",
43
- "- If tracked and ignored storage disagree, delete the bad fix in Git and re-bootstrap local storage instead.",
29
+ "3) Execution loop",
30
+ " 1. Start session: trekoon --toon session [--epic <epic-id>]",
31
+ " 2. Claim work: trekoon --toon task update <task-id> --status in_progress",
32
+ " 3. Log progress: trekoon --toon task update <task-id> --append \"Done with implementation\"",
33
+ " 4. Finish: trekoon --toon task done <task-id>",
34
+ " Returns the next ready task, its deps, and full payload.",
35
+ " 5. Or report block: trekoon --toon task update <task-id> --append \"Blocked: <reason>\" --status blocked",
44
36
  "",
45
- "5) Power-user command patterns (aligned with skill)",
46
- "- Inspect full epic tree: trekoon --toon epic show <epic-id> --all",
47
- "- Inspect full task payload: trekoon --toon task show <task-id> --all",
48
- "- Check direct dependencies before starting: trekoon --toon dep list <task-id>",
49
- "- Find what this item unblocks: trekoon --toon dep reverse <task-or-subtask-id>",
50
- "- Filter list explicitly: trekoon --toon task list --status in_progress,todo --limit 20",
51
- "- Paginate deterministically: trekoon --toon task list --cursor <n>",
52
- "- Bulk append/status update: trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
37
+ "4) Orientation and suggestions",
38
+ " Next-action suggestions: trekoon --toon suggest [--epic <epic-id>]",
39
+ " Epic progress: trekoon --toon epic progress <epic-id>",
40
+ " Open the board: trekoon board open",
53
41
  "",
54
- "6) Task details and description",
55
- "- Human list and show views default to table format.",
56
- "- Alternate list view: add --view compact.",
57
- "- task/epic/subtask list defaults: open work only (in_progress/in-progress, todo), max 10.",
58
- "- Filter list by status: --status in_progress,todo (CSV).",
59
- "- Change page size: --limit <n>. Show all statuses and all rows with --all.",
60
- "- Continue pagination with --cursor <n> (offset-like list position).",
61
- "- --all cannot be combined with --status, --limit, or --cursor.",
62
- "- Bulk update: use --all or --ids <csv> with --append and/or --status.",
63
- "- Bulk update rejects positional id, and --all/--ids cannot be combined.",
64
- "- Ready queue: trekoon task ready [--limit <n>] [--epic <id>] (deterministic order).",
65
- "- Next execution candidate: trekoon task next [--epic <id>]",
66
- "- Full tree + descriptions (canonical): trekoon --toon epic show <epic-id> --all",
67
- "- Full task payload (including description): trekoon --toon task show <task-id> --all",
68
- "- Optional integration format: trekoon --json task show <task-id> --all",
42
+ "5) Common commands",
43
+ " Full epic tree: trekoon --toon epic show <epic-id> --all",
44
+ " Full task payload: trekoon --toon task show <task-id> --all",
45
+ " Check dependencies: trekoon --toon dep list <task-id>",
46
+ " What does this unblock: trekoon --toon dep reverse <task-or-subtask-id>",
47
+ " Filtered list: trekoon --toon task list --status in_progress,todo --limit 20",
48
+ " Paginate: trekoon --toon task list --cursor <n>",
49
+ " Bulk update: trekoon --toon task update --ids id1,id2 --append \"...\" --status in_progress",
50
+ " Ready queue: trekoon --toon task ready [--limit <n>] [--epic <id>]",
51
+ " Next candidate: trekoon --toon task next [--epic <id>]",
69
52
  "",
70
- "7) Pre-merge sync flow",
71
- "- Run: trekoon --toon sync status",
72
- "- Pull upstream tracker events: trekoon --toon sync pull --from main",
73
- "- Resolve conflicts if needed: trekoon --toon sync resolve <id> --use ours",
74
- "- Run sync status again before opening or merging a PR.",
53
+ "6) List and view defaults",
54
+ " Default scope: open work (in_progress, todo), limit 10.",
55
+ " Filters: --status <csv>, --limit <n>, --cursor <n>, or --all for everything.",
56
+ " Views: --view table (default) or --view compact.",
57
+ " --all cannot be combined with --status, --limit, or --cursor.",
75
58
  "",
76
- "8) Shared-storage wipe warning",
77
- "- trekoon wipe --yes removes the shared repo-scoped .trekoon directory for every worktree in the repo.",
78
- "- Treat wipe as destructive recovery, not routine cleanup.",
79
- "- Never use wipe as a substitute for sync, bootstrap, or gitignore fixes.",
59
+ "7) Pre-merge sync",
60
+ " trekoon --toon sync status",
61
+ " trekoon --toon sync pull --from main",
62
+ " trekoon --toon sync conflicts list",
63
+ " trekoon --toon sync conflicts show <id>",
64
+ " trekoon --toon sync resolve <id> --use theirs --dry-run",
65
+ " trekoon --toon sync resolve <id> --use ours|theirs",
66
+ " trekoon --toon sync status",
67
+ " Always inspect conflicts before resolving. In human mode, --use theirs",
68
+ " prompts for confirmation (30s timeout, defaults to reject).",
80
69
  "",
81
- "9) Machine output examples",
82
- "- trekoon --toon quickstart",
83
- "- trekoon --toon session",
84
- "- trekoon --toon task done <task-id> --append \"Completed implementation\"",
85
- "- trekoon --toon task show <task-id> --all",
86
- "- trekoon --toon epic show <epic-id> --all",
87
- "- trekoon --toon sync status",
88
- "- trekoon --toon task ready --limit 5",
89
- "- trekoon --toon task next",
90
- "- trekoon --toon dep reverse <task-or-subtask-id>",
70
+ "8) Wipe (destructive recovery only)",
71
+ " trekoon wipe --yes",
72
+ " Removes the shared .trekoon directory for every worktree in the repo.",
73
+ " Don't use this for routine cleanup, sync fixes, or gitignore issues.",
91
74
  ].join("\n");
92
75
 
93
76
  export async function runQuickstart(_: CliContext): Promise<CliResult> {
@@ -120,13 +103,17 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
120
103
  preMergeFlow: [
121
104
  "trekoon --toon sync status",
122
105
  "trekoon --toon sync pull --from main",
123
- "trekoon --toon sync resolve <id> --use ours",
106
+ "trekoon --toon sync conflicts list",
107
+ "trekoon --toon sync conflicts show <id>",
108
+ "trekoon --toon sync resolve <id> --use theirs --dry-run",
109
+ "trekoon --toon sync resolve <id> --use ours|theirs",
124
110
  "trekoon --toon sync status",
125
111
  ],
126
112
  executionLoop: [
127
113
  "trekoon --toon session",
128
114
  "trekoon --toon task update <task-id> --status in_progress",
129
- "trekoon --toon task done <task-id> --append \"Completed implementation\"",
115
+ "trekoon --toon task update <task-id> --append \"Completed implementation\"",
116
+ "trekoon --toon task done <task-id>",
130
117
  ],
131
118
  diagnostics: [
132
119
  "storageMode",
@@ -153,7 +140,10 @@ export async function runQuickstart(_: CliContext): Promise<CliResult> {
153
140
  machineExamples: [
154
141
  "trekoon --toon quickstart",
155
142
  "trekoon --toon session",
156
- "trekoon --toon task done <task-id> --append \"Completed implementation\"",
143
+ "trekoon --toon session --epic <epic-id>",
144
+ "trekoon --toon suggest",
145
+ "trekoon --toon epic progress <epic-id>",
146
+ "trekoon --toon task done <task-id>",
157
147
  "trekoon --toon task show <task-id> --all",
158
148
  "trekoon --toon epic show <epic-id> --all",
159
149
  "trekoon --toon sync status",