trekoon 0.1.0

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

@@ -0,0 +1,91 @@
+---
+name: trekoon
+description: Use Trekoon to create issues/tasks, plan backlog and sprints, create epics, update status, track progress, and manage dependencies/sync across repository workflows.
+---
+
+# Trekoon Skill
+
+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.
+
+## 1) Load existing work first
+
+Before creating or changing anything, inspect current context:
+
+```bash
+trekoon epic list --toon
+trekoon task list --toon
+trekoon epic show <id> --all --toon
+trekoon task show <id> --all --toon
+```
+
+- `epic list` / `task list` defaults:
+  - open work only (`in_progress`, `in-progress`, `todo`)
+  - prioritized as `in_progress`/`in-progress` first, then `todo`
+  - default limit `10`
+- Filter list explicitly when needed:
+
+```bash
+trekoon task list --status in_progress,todo --limit 20 --toon
+trekoon epic list --status done --toon
+trekoon task list --all --toon
+```
+
+- `--all` cannot be combined with `--status` or `--limit`.
+- `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)
+
+```bash
+trekoon epic create --title "..." --description "..." --status todo --toon
+trekoon task create --epic <epic-id> --title "..." --description "..." --status todo --toon
+trekoon subtask create --task <task-id> --title "..." --description "..." --status todo --toon
+```
+
+Notes:
+- `description` is required for epic/task create and it must be well written.
+- `status` defaults to `todo` if omitted.
+
+## 3) Update work
+
+### Single-item update
+
+```bash
+trekoon epic update <epic-id> --title "..." --description "..." --status in_progress --toon
+trekoon task update <task-id> --title "..." --description "..." --status in_progress --toon
+trekoon subtask update <subtask-id> --title "..." --description "..." --status in_progress --toon
+```
+
+### Bulk update (task/epic)
+
+```bash
+trekoon task update --all --append "..." --status in_progress --toon
+trekoon task update --ids id1,id2 --append "..." --status in_progress --toon
+
+trekoon epic update --all --append "..." --status in_progress --toon
+trekoon epic update --ids id1,id2 --append "..." --status in_progress --toon
+```
+
+Rules:
+- `--all` and `--ids` are mutually exclusive.
+- In bulk mode, do not pass a positional ID.
+- Bulk update supports `--append` and/or `--status`.
+
+## 4) 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:
+
+```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
+
+- Never edit `.trekoon/trekoon.db` directly.
+- `trekoon wipe --yes` is prohibited unless the user explicitly confirms they want a destructive wipe.

package/AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS.md
+
+This file contains guidelines for agents.
+
+## Mandatory: Atomic Commit Policy
+
+Every code change MUST be followed by an immediate commit.
+
+**Commit format**:
+```
+<imperative verb> <what changed>     ← Line 1: max 50 chars
+<blank line>                         ← Line 2: blank
+<why/context, one point per line>    ← Body: max 72 chars per line
+```
+
+**Rules**:
+1. One commit per logical change
+2. Small, atomic commits - one file per commit preferred
+3. Never batch unrelated changes
+
+**Enforcement**:
+- After any file modification, stop and commit before modifying another file
+- Run `git status --short` after each commit to verify clean tree
+- At milestones: run `bun run build && bun run lint && bun run test`
+
+**Anti-patterns**:
+- ❌ Multiple unrelated files in one commit
+- ❌ Generic messages like "Update file", "WIP", "Fix stuff"
+- ❌ Commit message over 50 chars on first line
+
+## Coding Conventions
+
+For Bun/TypeScript code:
+- **Imports**: Group order (stdlib → third-party → local), explicit named imports, remove unused
+- **Formatting**: Consistent quotes, avoid mixed tabs/spaces
+- **Types**: Prefer explicit types at API boundaries, avoid `any` unless justified
+- **Naming**: `camelCase` (vars/functions), `PascalCase` (types), `UPPER_SNAKE_CASE` (constants)
+
+**Error handling**:
+- Never silently swallow errors
+- Include actionable context (operation + endpoint + status code)
+- Redact secrets from errors and logs
+
+## Agent Behavior
+
+- Prefer minimal, targeted edits; avoid broad rewrites
+- Preserve existing examples unless fixing factual issues
+- For CLI changes, prioritize startup speed and low-latency UX
+- Keep commands compatible with macOS and Linux shells
+
+## Security
+
+- Never commit secrets (tokens, credentials)
+- Redact secrets from errors and logs

package/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing to Trekoon
+
+## No-copy implementation policy
+
+Trekoon is implemented in this repository root. The `trekker/` directory is
+reference-only.
+
+- Do not copy code or files from `trekker/` into root `src/`.
+- Do not mirror file layout one-to-one from `trekker/`.
+- Write root implementation code directly, with Trekoon-native structure.
+
+## PR checklist
+
+- [ ] Any new logic was written directly in root project files.
+- [ ] Changes were reviewed for suspiciously identical blocks/comments versus
+      `trekker/` reference code.
+- [ ] Sync-related writes preserve git context (`branch`, `head`, `worktree`).
+- [ ] README command/flag examples match actual implemented CLI behavior.

package/README.md

@@ -0,0 +1,151 @@
+# Trekoon
+
+AI-first issue tracking for humans and agents.
+
+Trekoon is a Bun-powered CLI focused on execution workflows where AI agents and humans share the same task graph.
+
+## What Trekoon is
+
+- Local-first CLI issue tracker
+- Structured hierarchy: **epic → task → subtask**
+- UUID-based references for durable linking across branches/worktrees
+- Dependency-aware planning and execution
+- Output modes:
+  - **Human mode** for terminal users
+  - **JSON mode** for stable machine parsing
+  - **TOON mode** for true TOON-encoded payloads
+
+## What Trekoon aims to accomplish
+
+1. Make issue tracking fast enough for daily terminal use.
+2. Make issue data deterministic and machine-readable for AI automation.
+3. Keep branch/worktree-aware state so parallel execution can be coordinated safely.
+4. Stay minimal in code size while preserving robustness and clear boundaries.
+
+## Command surface
+
+- `trekoon init`
+- `trekoon quickstart`
+- `trekoon epic <create|list|show|update|delete>`
+- `trekoon task <create|list|show|update|delete>`
+- `trekoon subtask <create|list|update|delete>`
+- `trekoon dep <add|remove|list>`
+- `trekoon sync <status|pull|resolve>`
+- `trekoon wipe --yes`
+
+Global output modes:
+
+- `--json` for structured JSON output
+- `--toon` for true TOON-encoded output (not JSON text)
+- `--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 currently accepts long option form (`--option`).
+
+Human view options:
+
+- List and show commands default to table output in human mode.
+- Use `--view compact` to restore compact pipe output.
+- `epic list` and `task list` support `--view table|compact`.
+- `epic show` and `task show` support `--view table|compact|tree|detail`.
+
+List defaults and filters (`epic list`, `task list`):
+
+- Default scope: open work only (`in_progress`, `in-progress`, `todo`)
+- Default limit: `10`
+- Status filter: `--status in_progress,todo` (CSV)
+- Custom limit: `--limit <n>`
+- All rows and statuses: `--all`
+- `--all` is mutually exclusive with `--status` and `--limit`
+
+Bulk updates (`epic update`, `task update`):
+
+- Target all rows: `--all`
+- Target specific rows: `--ids <id1,id2,...>`
+- Bulk updates support only `--append <text>` and/or `--status <status>`
+- 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 epic update --ids <epic-1>,<epic-2> --status done
+```
+
+## Quickstart
+
+Trekoon is local-first: each worktree uses its own `.trekoon/trekoon.db`.
+Git does not merge this DB file; Trekoon sync commands merge tracker state.
+
+### 1) Initialize
+
+```bash
+trekoon init
+trekoon --version
+```
+
+### 2) Create epic → task → subtask
+
+```bash
+trekoon 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
+trekoon task list
+trekoon task list --status done
+trekoon task list --limit 25
+trekoon task list --all --view compact
+```
+
+### 3) Add dependencies
+
+```bash
+trekoon dep add <task-id> <depends-on-id>
+trekoon dep list <task-id>
+```
+
+### 4) Use JSON or TOON output for agents
+
+```bash
+trekoon --json epic show <epic-id>
+trekoon --json task show <task-id>
+trekoon --toon epic show <epic-id>
+trekoon --toon task show <task-id>
+```
+
+### 5) Sync workflow for worktrees
+
+- Run `trekoon sync status` at session start and before PR/merge.
+- Run `trekoon sync pull --from main` before merge to align tracker state.
+- If conflicts exist, resolve explicitly:
+
+```bash
+trekoon sync status
+trekoon sync pull --from main
+trekoon sync resolve <conflict-id> --use ours
+```
+
+### 6) Pre-merge checklist
+
+- [ ] `trekoon sync status` shows no unresolved conflicts
+- [ ] done tasks/subtasks are marked completed
+- [ ] dependency graph has no stale blockers
+- [ ] final AI check: `trekoon --json epic show <epic-id>`
+
+## Implementation principles
+
+- Minimal, composable modules
+- Strict validation at command boundaries
+- Stable automation envelope for JSON/TOON modes
+- No unnecessary feature sprawl

package/bin/trekoon

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+
+import { run } from "../src/index";
+
+await run(process.argv.slice(2));

package/bun.lock

@@ -0,0 +1,28 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "trekoon",
+      "dependencies": {
+        "@toon-format/toon": "^2.1.0",
+      },
+      "devDependencies": {
+        "@types/bun": "^1.3.0",
+        "typescript": "^5.9.2",
+      },
+    },
+  },
+  "packages": {
+    "@toon-format/toon": ["@toon-format/toon@2.1.0", "", {}, "sha512-JwWptdF5eOA0HaQxbKAzkpQtR4wSWTEfDlEy/y3/4okmOAX1qwnpLZMmtEWr+ncAhTTY1raCKH0kteHhSXnQqg=="],
+
+    "@types/bun": ["@types/bun@1.3.9", "", { "dependencies": { "bun-types": "1.3.9" } }, "sha512-KQ571yULOdWJiMH+RIWIOZ7B2RXQGpL1YQrBtLIV3FqDcCu6FsbFUBwhdKUlCKUpS3PJDsHlJ1QKlpxoVR+xtw=="],
+
+    "@types/node": ["@types/node@25.2.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ=="],
+
+    "bun-types": ["bun-types@1.3.9", "", { "dependencies": { "@types/node": "*" } }, "sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "trekoon",
+  "version": "0.1.0",
+  "description": "AI-first local issue tracker CLI.",
+  "type": "module",
+  "bin": {
+    "trekoon": "./bin/trekoon"
+  },
+  "scripts": {
+    "run": "bun run ./src/index.ts",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test ./tests"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@toon-format/toon": "^2.1.0"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  }
+}

package/src/commands/arg-parser.ts

@@ -0,0 +1,93 @@
+export interface ParsedArgs {
+  readonly positional: readonly string[];
+  readonly options: ReadonlyMap<string, string>;
+  readonly flags: ReadonlySet<string>;
+  readonly missingOptionValues: ReadonlySet<string>;
+}
+
+const LONG_PREFIX = "--";
+
+export function parseArgs(args: readonly string[]): ParsedArgs {
+  const positional: string[] = [];
+  const options = new Map<string, string>();
+  const flags = new Set<string>();
+  const missingOptionValues = new Set<string>();
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token: string | undefined = args[index];
+    if (!token) {
+      continue;
+    }
+
+    if (!token.startsWith(LONG_PREFIX)) {
+      positional.push(token);
+      continue;
+    }
+
+    const key = token.slice(LONG_PREFIX.length);
+    const value = args[index + 1];
+    if (!value || value.startsWith(LONG_PREFIX)) {
+      flags.add(key);
+      missingOptionValues.add(key);
+      continue;
+    }
+
+    options.set(key, value);
+    index += 1;
+  }
+
+  return {
+    positional,
+    options,
+    flags,
+    missingOptionValues,
+  };
+}
+
+export function readOption(options: ReadonlyMap<string, string>, ...keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value: string | undefined = options.get(key);
+    if (value !== undefined) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+export function hasFlag(flags: ReadonlySet<string>, ...keys: string[]): boolean {
+  return keys.some((key) => flags.has(key));
+}
+
+export function readMissingOptionValue(
+  missingOptionValues: ReadonlySet<string>,
+  ...keys: string[]
+): string | undefined {
+  return keys.find((key) => missingOptionValues.has(key));
+}
+
+export function parseStrictPositiveInt(rawValue: string | undefined): number | undefined {
+  if (rawValue === undefined) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(rawValue, 10);
+  if (!Number.isInteger(parsed) || parsed < 1 || `${parsed}` !== rawValue.trim()) {
+    return Number.NaN;
+  }
+
+  return parsed;
+}
+
+export function readEnumOption<const T extends readonly string[]>(
+  options: ReadonlyMap<string, string>,
+  allowed: T,
+  ...keys: string[]
+): T[number] | undefined {
+  const value: string | undefined = readOption(options, ...keys);
+  if (value === undefined) {
+    return undefined;
+  }
+
+  return allowed.includes(value) ? value : undefined;
+}

package/src/commands/dep.ts

@@ -0,0 +1,105 @@
+import { parseArgs } from "./arg-parser";
+
+import { DomainError } from "../domain/types";
+import { TrackerDomain } from "../domain/tracker-domain";
+import { failResult, okResult } from "../io/output";
+import { type CliContext, type CliResult } from "../runtime/command-types";
+import { openTrekoonDatabase } from "../storage/database";
+
+function failFromError(error: unknown): CliResult {
+  if (error instanceof DomainError) {
+    return failResult({
+      command: "dep",
+      human: error.message,
+      data: {
+        code: error.code,
+        ...(error.details ?? {}),
+      },
+      error: {
+        code: error.code,
+        message: error.message,
+      },
+    });
+  }
+
+  return failResult({
+    command: "dep",
+    human: "Unexpected dep command failure",
+    data: {},
+    error: {
+      code: "internal_error",
+      message: "Unexpected dep command failure",
+    },
+  });
+}
+
+export async function runDep(context: CliContext): Promise<CliResult> {
+  const database = openTrekoonDatabase(context.cwd);
+
+  try {
+    const parsed = parseArgs(context.args);
+    const subcommand: string | undefined = parsed.positional[0];
+    const sourceId: string = parsed.positional[1] ?? "";
+    const dependsOnId: string = parsed.positional[2] ?? "";
+    const domain = new TrackerDomain(database.db);
+
+    switch (subcommand) {
+      case "add": {
+        const dependency = domain.addDependency(sourceId, dependsOnId);
+
+        return okResult({
+          command: "dep.add",
+          human: `Added dependency ${dependency.sourceId} -> ${dependency.dependsOnId}`,
+          data: { dependency },
+        });
+      }
+      case "remove": {
+        const removed: number = domain.removeDependency(sourceId, dependsOnId);
+
+        return okResult({
+          command: "dep.remove",
+          human:
+            removed > 0
+              ? `Removed dependency ${sourceId} -> ${dependsOnId}`
+              : `No dependency found for ${sourceId} -> ${dependsOnId}`,
+          data: {
+            sourceId,
+            dependsOnId,
+            removed,
+          },
+        });
+      }
+      case "list": {
+        const dependencies = domain.listDependencies(sourceId);
+
+        return okResult({
+          command: "dep.list",
+          human:
+            dependencies.length === 0
+              ? `No dependencies for ${sourceId}`
+              : dependencies.map((item) => `${item.sourceId} -> ${item.dependsOnId}`).join("\n"),
+          data: {
+            sourceId,
+            dependencies,
+          },
+        });
+      }
+      default:
+        return failResult({
+          command: "dep",
+          human: "Usage: trekoon dep <add|remove|list>",
+          data: {
+            args: context.args,
+          },
+          error: {
+            code: "invalid_subcommand",
+            message: "Invalid dep subcommand",
+          },
+        });
+    }
+  } catch (error: unknown) {
+    return failFromError(error);
+  } finally {
+    database.close();
+  }
+}