trekoon 0.1.1 → 0.1.4

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

@@ -7,9 +7,154 @@ description: Use Trekoon to create issues/tasks, plan backlog and sprints, creat
 
 Trekoon is a local-first issue tracker for epics, tasks, and subtasks.
 
-Use long flags (`--status`, `--description`, etc.) and ALWAYS prefer `--toon` for machine-readable output.
+## 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
+```
+
+On error:
+
+```yaml
+ok: false
+command: task.show
+data: {}
+error:
+  code: not_found
+  message: task not found: invalid-id
+```
+
+### Key Fields
+
+| 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.) |
+| `error` | Present only on failure, contains `code` and `message` |
+
+Use long flags (`--status`, `--description`, etc.) and ALWAYS append `--toon` to every command.
+
+## 1) Status Management
+
+### Valid Statuses
+
+| Status | Meaning |
+|--------|---------|
+| `todo` | Work not started (default for new items) |
+| `in_progress` | Actively being worked on |
+| `done` | Completed successfully |
+
+Note: `in-progress` (hyphenated) is equivalent to `in_progress`.
+
+### When to Change Status
+
+| 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 |
+
+### Status Change Commands
+
+```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
+```
+
+## 2) Dependency Management
+
+Dependencies define what must be completed before a task can start. A task/subtask can depend on other tasks/subtasks.
+
+### Commands
+
+```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
+```
+
+- `<source-id>`: The task/subtask that has the dependency
+- `<depends-on-id>`: The task/subtask that must be completed first
 
-## 1) Load existing work first
+### Checking Dependencies
+
+Before starting any task, always check its dependencies:
+
+```bash
+trekoon dep list <task-id> --toon
+```
+
+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
+
+### Before Starting a Task
+
+1. Check if task has unmet dependencies:
+   ```bash
+   trekoon dep list <task-id> --toon
+   ```
+
+2. If dependencies exist and are not `done`, complete those first
+
+3. Only mark `in_progress` when all dependencies are `done`
+
+### 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:
+   - List all tasks: `trekoon task list --all --toon`
+   - Check which tasks have dependencies on the completed task
+   - The task(s) with all dependencies now satisfied are ready to start
+
+### Finding Next Work
+
+```bash
+trekoon task list --status todo --limit 20 --toon
+```
+
+Tasks are sorted with `in_progress` first, then `todo`. Look for tasks with no dependencies or all dependencies satisfied.
+
+## 4) Load existing work first
 
 Before creating or changing anything, inspect current context:
 
@@ -36,7 +181,14 @@ trekoon task list --all --toon
 - `epic show <id> --all --toon`: full epic tree (tasks + subtasks)
 - `task show <id> --all --toon`: task plus its subtasks
 
-## 2) Create work (epic/task/subtask)
+### View Options
+
+| Command | `--view` options |
+|---------|------------------|
+| `list` | `table` (default), `compact` |
+| `show` | `table` (default), `compact`, `tree`, `detail` |
+
+## 5) Create work (epic/task/subtask)
 
 ```bash
 trekoon epic create --title "..." --description "..." --status todo --toon
@@ -47,8 +199,9 @@ trekoon subtask create --task <task-id> --title "..." --description "..." --stat
 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.
 
-## 3) Update work
+## 6) Update work
 
 ### Single-item update
 
@@ -73,7 +226,7 @@ Rules:
 - In bulk mode, do not pass a positional ID.
 - Bulk update supports `--append` and/or `--status`.
 
-## 4) Setup/install/init (if `trekoon` is unavailable)
+## 7) Setup/install/init (if `trekoon` is unavailable)
 
 1. Install Trekoon (or make sure it is on `PATH`).
 2. In the target repository/worktree, initialize tracker state:
@@ -81,11 +234,12 @@ Rules:
 ```bash
 trekoon init
 ```
+
 3. You can always run `trekoon quickstart` or `trekoon --help` to get more information.
 
 If `.trekoon/trekoon.db` is missing, initialize before any create/update commands.
 
-## 5) Safety
+## 8) Safety
 
 - Never edit `.trekoon/trekoon.db` directly.
 - `trekoon wipe --yes` is prohibited unless the user explicitly confirms they want a destructive wipe.

package/README.md

@@ -52,6 +52,7 @@ npm i -g trekoon
 - `trekoon subtask <create|list|update|delete>`
 - `trekoon dep <add|remove|list>`
 - `trekoon sync <status|pull|resolve>`
+- `trekoon skills install [--link --editor opencode|claude] [--to <path>]`
 - `trekoon wipe --yes`
 
 Global output modes:
@@ -88,7 +89,7 @@ List defaults and filters (`epic list`, `task list`):
 - All rows and statuses: `--all`
 - `--all` is mutually exclusive with `--status` and `--limit`
 
-Bulk updates (`epic update`, `task update`):
+Bulk updates (`epic update`, `task update`, `subtask update`):
 
 - Target all rows: `--all`
 - Target specific rows: `--ids <id1,id2,...>`
@@ -102,6 +103,8 @@ 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
 ```
 
@@ -157,7 +160,57 @@ trekoon sync pull --from main
 trekoon sync resolve <conflict-id> --use ours
 ```
 
-### 6) Pre-merge checklist
+### 6) Install project-local Trekoon skill for agents
+
+`trekoon skills install` always writes the bundled skill file into the current
+repository at:
+
+- `.agents/skills/trekoon/SKILL.md`
+
+You can also create a project-local editor link:
+
+```bash
+trekoon skills install
+trekoon skills install --link --editor opencode
+trekoon skills install --link --editor claude
+trekoon skills install --link --editor opencode --to ./.custom-editor/skills
+```
+
+Path behavior:
+
+- Default opencode link path: `.opencode/skills/trekoon`
+- Default claude link path: `.claude/skills/trekoon`
+- `--to <path>` overrides the editor root for link creation only.
+- `--to` does **not** move or copy `SKILL.md` to that path.
+- Re-running install is idempotent: it refreshes `SKILL.md` and reuses/replaces
+  the same symlink target.
+- If the link destination exists as a non-link path, install fails with an
+  actionable conflict error.
+
+How `--to` works (step-by-step):
+
+1. Trekoon always installs/copies to:
+   - `<repo>/.agents/skills/trekoon/SKILL.md`
+2. If `--link` is present, Trekoon creates a `trekoon` symlink directory entry.
+3. `--to <path>` sets the symlink root directory.
+4. Final link path is:
+   - `<resolved-to-path>/trekoon -> <repo>/.agents/skills/trekoon`
+
+Example:
+
+```bash
+trekoon skills install --link --editor opencode --to ./.custom-editor/skills
+```
+
+This produces:
+
+- `<repo>/.agents/skills/trekoon/SKILL.md` (copied file)
+- `<repo>/.custom-editor/skills/trekoon` (symlink)
+- symlink target: `<repo>/.agents/skills/trekoon`
+
+Trekoon does not mutate global editor config directories.
+
+### 7) Pre-merge checklist
 
 - [ ] `trekoon sync status` shows no unresolved conflicts
 - [ ] done tasks/subtasks are marked completed

package/package.json

@@ -1,16 +1,24 @@
 {
   "name": "trekoon",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "AI-first local issue tracker CLI.",
   "license": "MIT",
   "type": "module",
   "bin": {
     "trekoon": "./bin/trekoon"
   },
+  "files": [
+    "bin",
+    "src",
+    ".agents/skills/trekoon/SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "run": "bun run ./src/index.ts",
     "build": "bun build ./src/index.ts --outdir ./dist --target bun",
-    "test": "bun test ./tests"
+    "test": "bun test ./tests",
+    "lint": "bunx tsc --noEmit"
   },
   "devDependencies": {
     "@types/bun": "^1.3.9",

package/src/commands/events.ts

@@ -0,0 +1,88 @@
+import { hasFlag, parseArgs, parseStrictPositiveInt, readMissingOptionValue, readOption } from "./arg-parser";
+
+import { failResult, okResult } from "../io/output";
+import { type CliContext, type CliResult } from "../runtime/command-types";
+import { openTrekoonDatabase } from "../storage/database";
+import { DEFAULT_EVENT_RETENTION_DAYS, pruneEvents } from "../storage/events-retention";
+
+const EVENTS_USAGE = "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]";
+
+function usage(message: string): CliResult {
+  return failResult({
+    command: "events",
+    human: `${message}\n${EVENTS_USAGE}`,
+    data: { message },
+    error: {
+      code: "invalid_args",
+      message,
+    },
+  });
+}
+
+function invalidInput(command: string, message: string, option: string): CliResult {
+  return failResult({
+    command,
+    human: message,
+    data: {
+      option,
+    },
+    error: {
+      code: "invalid_input",
+      message,
+    },
+  });
+}
+
+export async function runEvents(context: CliContext): Promise<CliResult> {
+  const parsed = parseArgs(context.args);
+  const subcommand: string | undefined = parsed.positional[0];
+
+  if (!subcommand) {
+    return usage("Missing events subcommand.");
+  }
+
+  if (subcommand !== "prune") {
+    return usage(`Unknown events subcommand '${subcommand}'.`);
+  }
+
+  if (parsed.positional.length > 1) {
+    return usage("Unexpected positional arguments for events prune.");
+  }
+
+  const missingOption: string | undefined = readMissingOptionValue(parsed.missingOptionValues, "retention-days");
+  if (missingOption !== undefined) {
+    return invalidInput("events.prune", `Option --${missingOption} requires a value.`, missingOption);
+  }
+
+  const parsedRetentionDays: number | undefined = parseStrictPositiveInt(readOption(parsed.options, "retention-days"));
+  if (Number.isNaN(parsedRetentionDays)) {
+    return invalidInput("events.prune", "--retention-days must be a positive integer.", "retention-days");
+  }
+
+  const retentionDays: number = parsedRetentionDays ?? DEFAULT_EVENT_RETENTION_DAYS;
+  const dryRun: boolean = hasFlag(parsed.flags, "dry-run");
+  const archive: boolean = hasFlag(parsed.flags, "archive");
+  const storage = openTrekoonDatabase(context.cwd);
+
+  try {
+    const summary = pruneEvents(storage.db, {
+      retentionDays,
+      dryRun,
+      archive,
+    });
+
+    return okResult({
+      command: "events.prune",
+      human: [
+        dryRun ? "Dry run complete." : "Prune complete.",
+        `Retention days: ${summary.retentionDays}`,
+        `Candidates: ${summary.candidateCount}`,
+        `Archived: ${summary.archivedCount}`,
+        `Deleted: ${summary.deletedCount}`,
+      ].join("\n"),
+      data: summary,
+    });
+  } finally {
+    storage.close();
+  }
+}

package/src/commands/help.ts

@@ -21,7 +21,10 @@ const ROOT_HELP = [
   "  task         Task lifecycle commands",
   "  subtask      Subtask lifecycle commands",
   "  dep          Dependency graph commands",
+  "  events       Event retention and cleanup commands",
+  "  migrate      Migration status and rollback commands",
   "  sync         Cross-branch sync commands",
+  "  skills       Project-local skill install/link commands",
 ].join("\n");
 
 const COMMAND_HELP: Record<string, string> = {
@@ -32,9 +35,14 @@ const COMMAND_HELP: Record<string, string> = {
     "Usage: trekoon epic <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --status <csv> | --limit <n> | --all | --view table|compact; show: compact=epic summary, tree=hierarchy, detail=descriptions, and --all defaults to detail in machine modes; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
   task:
     "Usage: trekoon task <subcommand> [options] (list defaults: open statuses + limit 10; list flags: --status <csv> | --limit <n> | --all | --view table|compact; show: compact=task summary, tree=hierarchy, detail=descriptions, and --all defaults to detail in machine modes; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
-  subtask: "Usage: trekoon subtask <subcommand> [options] (list supports --view table|compact)",
+  subtask:
+    "Usage: trekoon subtask <subcommand> [options] (list supports --view table|compact; update bulk flags: --all | --ids <csv> with --append <text> and/or --status <status>)",
   dep: "Usage: trekoon dep <subcommand> [options]",
+  events: "Usage: trekoon events prune [--dry-run] [--archive] [--retention-days <n>]",
+  migrate: "Usage: trekoon migrate <status|rollback> [--to-version <n>]",
   sync: "Usage: trekoon sync <subcommand> [options]",
+  skills:
+    "Usage: trekoon skills install [--link --editor opencode|claude] [--to <path>] (--to sets symlink root for --link only; install path always <cwd>/.agents/skills/trekoon/SKILL.md)",
   help: "Usage: trekoon help [command] [--json|--toon]",
 };
 

package/src/commands/migrate.ts

@@ -0,0 +1,123 @@
+import { parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
+
+import { failResult, okResult } from "../io/output";
+import { type CliContext, type CliResult } from "../runtime/command-types";
+import { openTrekoonDatabase } from "../storage/database";
+import { describeMigrations, rollbackDatabase } from "../storage/migrations";
+
+const MIGRATE_USAGE = "Usage: trekoon migrate <status|rollback> [--to-version <n>]";
+
+function usage(message: string): CliResult {
+  return failResult({
+    command: "migrate",
+    human: `${message}\n${MIGRATE_USAGE}`,
+    data: { message },
+    error: {
+      code: "invalid_args",
+      message,
+    },
+  });
+}
+
+function parseVersion(rawValue: string | undefined): number | null {
+  if (rawValue === undefined) {
+    return null;
+  }
+
+  if (!/^\d+$/.test(rawValue)) {
+    return Number.NaN;
+  }
+
+  return Number.parseInt(rawValue, 10);
+}
+
+export async function runMigrate(context: CliContext): Promise<CliResult> {
+  const parsed = parseArgs(context.args);
+  const subcommand: string | undefined = parsed.positional[0];
+
+  if (!subcommand) {
+    return usage("Missing migrate subcommand.");
+  }
+
+  const missingOption = readMissingOptionValue(parsed.missingOptionValues, "to-version");
+  if (missingOption !== undefined) {
+    return failResult({
+      command: "migrate",
+      human: `Option --${missingOption} requires a value.`,
+      data: {
+        option: missingOption,
+      },
+      error: {
+        code: "invalid_input",
+        message: `Option --${missingOption} requires a value.`,
+      },
+    });
+  }
+
+  const storage = openTrekoonDatabase(context.cwd, { autoMigrate: false });
+
+  try {
+    if (subcommand === "status") {
+      const status = describeMigrations(storage.db);
+
+      return okResult({
+        command: "migrate.status",
+        human: [
+          `Current version: ${status.currentVersion}`,
+          `Latest version: ${status.latestVersion}`,
+          `Pending migrations: ${status.pending.length}`,
+        ].join("\n"),
+        data: status,
+      });
+    }
+
+    if (subcommand === "rollback") {
+      const status = describeMigrations(storage.db);
+      const parsedVersion: number | null = parseVersion(readOption(parsed.options, "to-version"));
+
+      if (Number.isNaN(parsedVersion)) {
+        return failResult({
+          command: "migrate.rollback",
+          human: "--to-version must be a non-negative integer.",
+          data: {
+            option: "to-version",
+          },
+          error: {
+            code: "invalid_input",
+            message: "--to-version must be a non-negative integer.",
+          },
+        });
+      }
+
+      const targetVersion: number = parsedVersion ?? Math.max(0, status.currentVersion - 1);
+      const summary = rollbackDatabase(storage.db, targetVersion);
+
+      return okResult({
+        command: "migrate.rollback",
+        human: [
+          `Rolled back ${summary.rolledBack} migration(s).`,
+          `From version ${summary.fromVersion} to ${summary.toVersion}.`,
+        ].join("\n"),
+        data: summary,
+      });
+    }
+
+    return usage(`Unknown migrate subcommand '${subcommand}'.`);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : "Unknown migration failure.";
+
+    return failResult({
+      command: "migrate",
+      human: message,
+      data: {
+        reason: "migrate_failed",
+      },
+      error: {
+        code: "migrate_failed",
+        message,
+      },
+    });
+  } finally {
+    storage.close();
+  }
+}