trekoon 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esmaabi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,6 +4,27 @@ 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.
 
+## Installation
+
+Recommended (global install with Bun):
+
+```bash
+bun add -g trekoon
+```
+
+Then verify:
+
+```bash
+trekoon --help
+trekoon quickstart
+```
+
+Alternative (npm global install):
+
+```bash
+npm i -g trekoon
+```
+
 ## What Trekoon is
 
 - Local-first CLI issue tracker
@@ -31,6 +52,7 @@ Trekoon is a Bun-powered CLI focused on execution workflows where AI agents and
 - `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:
@@ -136,7 +158,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,11 +1,19 @@
 {
   "name": "trekoon",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",

package/src/commands/help.ts

@@ -22,6 +22,7 @@ const ROOT_HELP = [
   "  subtask      Subtask lifecycle commands",
   "  dep          Dependency graph commands",
   "  sync         Cross-branch sync commands",
+  "  skills       Project-local skill install/link commands",
 ].join("\n");
 
 const COMMAND_HELP: Record<string, string> = {
@@ -35,6 +36,8 @@ const COMMAND_HELP: Record<string, string> = {
   subtask: "Usage: trekoon subtask <subcommand> [options] (list supports --view table|compact)",
   dep: "Usage: trekoon dep <subcommand> [options]",
   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/skills.ts

@@ -0,0 +1,265 @@
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { hasFlag, parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
+
+import { failResult, okResult } from "../io/output";
+import { type CliContext, type CliResult } from "../runtime/command-types";
+
+const SKILLS_USAGE = "Usage: trekoon skills install [--link --editor opencode|claude] [--to <path>]";
+const EDITOR_NAMES = ["opencode", "claude"] as const;
+
+type EditorName = (typeof EDITOR_NAMES)[number];
+
+interface InstallOutcome {
+  readonly sourcePath: string;
+  readonly installedPath: string;
+  readonly installedDir: string;
+  readonly linkPath: string | null;
+  readonly linkTarget: string | null;
+}
+
+function invalidArgs(message: string): CliResult {
+  return failResult({
+    command: "skills",
+    human: `${message}\n${SKILLS_USAGE}`,
+    data: { message },
+    error: {
+      code: "invalid_args",
+      message,
+    },
+  });
+}
+
+function invalidInput(command: string, message: string, data: Record<string, unknown>): CliResult {
+  return failResult({
+    command,
+    human: message,
+    data: {
+      code: "invalid_input",
+      ...data,
+    },
+    error: {
+      code: "invalid_input",
+      message,
+    },
+  });
+}
+
+function resolveBundledSkillFilePath(): string {
+  return fileURLToPath(new URL("../../.agents/skills/trekoon/SKILL.md", import.meta.url));
+}
+
+function toAbsolutePath(cwd: string, pathValue: string): string {
+  if (isAbsolute(pathValue)) {
+    return pathValue;
+  }
+
+  return resolve(cwd, pathValue);
+}
+
+function resolveLinkRoot(cwd: string, editor: EditorName, toOverride: string | undefined): string {
+  if (toOverride !== undefined) {
+    return toAbsolutePath(cwd, toOverride);
+  }
+
+  if (editor === "opencode") {
+    return join(cwd, ".opencode", "skills");
+  }
+
+  return join(cwd, ".claude", "skills");
+}
+
+function replaceOrCreateSymlink(linkPath: string, targetPath: string): CliResult | null {
+  if (!existsSync(linkPath)) {
+    mkdirSync(dirname(linkPath), { recursive: true });
+    symlinkSync(targetPath, linkPath, "dir");
+    return null;
+  }
+
+  const existing = lstatSync(linkPath);
+  if (!existing.isSymbolicLink()) {
+    return failResult({
+      command: "skills.install",
+      human: `Cannot create symlink: path exists and is not a link (${linkPath}).`,
+      data: {
+        code: "path_conflict",
+        linkPath,
+        targetPath,
+      },
+      error: {
+        code: "path_conflict",
+        message: "Symlink destination exists as a non-link path",
+      },
+    });
+  }
+
+  const existingRawTarget: string = readlinkSync(linkPath);
+  const existingAbsoluteTarget: string = toAbsolutePath(dirname(linkPath), existingRawTarget);
+  const expectedTarget: string = resolve(targetPath);
+  if (existingAbsoluteTarget !== expectedTarget) {
+    return failResult({
+      command: "skills.install",
+      human: `Cannot replace existing link at ${linkPath}; it points to ${existingAbsoluteTarget}.`,
+      data: {
+        code: "path_conflict",
+        linkPath,
+        existingTarget: existingAbsoluteTarget,
+        expectedTarget,
+      },
+      error: {
+        code: "path_conflict",
+        message: "Symlink destination points to a different target",
+      },
+    });
+  }
+
+  rmSync(linkPath, { force: true });
+  symlinkSync(targetPath, linkPath, "dir");
+  return null;
+}
+
+function runSkillsInstall(context: CliContext): CliResult {
+  const parsed = parseArgs(context.args);
+  const missingValue = readMissingOptionValue(parsed.missingOptionValues, "editor", "to");
+  if (missingValue !== undefined) {
+    return invalidInput("skills.install", `Option --${missingValue} requires a value.`, {
+      option: missingValue,
+    });
+  }
+
+  if (parsed.positional.length > 1) {
+    return invalidArgs("Unexpected positional arguments for skills install.");
+  }
+
+  const wantsLink: boolean = hasFlag(parsed.flags, "link");
+  const rawEditor: string | undefined = readOption(parsed.options, "editor");
+  const rawTo: string | undefined = readOption(parsed.options, "to");
+
+  if (!wantsLink && rawEditor !== undefined) {
+    return invalidInput("skills.install", "--editor requires --link.", {
+      editor: rawEditor,
+    });
+  }
+
+  if (!wantsLink && rawTo !== undefined) {
+    return invalidInput("skills.install", "--to requires --link.", {
+      to: rawTo,
+    });
+  }
+
+  if (wantsLink && rawEditor === undefined) {
+    return invalidArgs("skills install --link requires --editor opencode|claude.");
+  }
+
+  if (rawEditor !== undefined && !EDITOR_NAMES.includes(rawEditor as EditorName)) {
+    return invalidInput("skills.install", "Invalid --editor value. Use: opencode, claude", {
+      editor: rawEditor,
+      allowedEditors: EDITOR_NAMES,
+    });
+  }
+
+  const editor: EditorName | undefined = rawEditor as EditorName | undefined;
+
+  const sourcePath: string = resolveBundledSkillFilePath();
+  if (!existsSync(sourcePath)) {
+    return failResult({
+      command: "skills.install",
+      human: `Bundled skill asset not found at ${sourcePath}`,
+      data: {
+        code: "missing_asset",
+        sourcePath,
+      },
+      error: {
+        code: "missing_asset",
+        message: "Bundled skill asset not found",
+      },
+    });
+  }
+
+  const installPath = join(context.cwd, ".agents", "skills", "trekoon", "SKILL.md");
+  const installDir = dirname(installPath);
+
+  let outcome: InstallOutcome;
+
+  try {
+    mkdirSync(installDir, { recursive: true });
+    copyFileSync(sourcePath, installPath);
+
+    let linkPath: string | null = null;
+    let linkTarget: string | null = null;
+
+    if (wantsLink && editor !== undefined) {
+      const linkRoot: string = resolveLinkRoot(context.cwd, editor, rawTo);
+      linkPath = join(linkRoot, "trekoon");
+      linkTarget = installDir;
+      const linkFailure = replaceOrCreateSymlink(linkPath, linkTarget);
+      if (linkFailure) {
+        return linkFailure;
+      }
+    }
+
+    outcome = {
+      sourcePath,
+      installedPath: installPath,
+      installedDir: installDir,
+      linkPath,
+      linkTarget,
+    };
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : "Unknown skills install failure";
+    return failResult({
+      command: "skills.install",
+      human: `Failed to install skill: ${message}`,
+      data: {
+        code: "install_failed",
+        message,
+      },
+      error: {
+        code: "install_failed",
+        message,
+      },
+    });
+  }
+
+  return okResult({
+    command: "skills.install",
+    human: outcome.linkPath
+      ? [
+          "Installed Trekoon skill and linked editor path.",
+          `Source: ${outcome.sourcePath}`,
+          `Installed file: ${outcome.installedPath}`,
+          `Link path: ${outcome.linkPath}`,
+          `Link target: ${outcome.linkTarget}`,
+        ].join("\n")
+      : [
+          "Installed Trekoon skill.",
+          `Source: ${outcome.sourcePath}`,
+          `Installed file: ${outcome.installedPath}`,
+        ].join("\n"),
+    data: {
+      sourcePath: outcome.sourcePath,
+      installedPath: outcome.installedPath,
+      installedDir: outcome.installedDir,
+      linked: outcome.linkPath !== null,
+      linkPath: outcome.linkPath,
+      linkTarget: outcome.linkTarget,
+    },
+  });
+}
+
+export async function runSkills(context: CliContext): Promise<CliResult> {
+  const parsed = parseArgs(context.args);
+  const subcommand: string | undefined = parsed.positional[0];
+  if (!subcommand) {
+    return invalidArgs("Missing skills subcommand.");
+  }
+
+  switch (subcommand) {
+    case "install":
+      return runSkillsInstall(context);
+    default:
+      return invalidArgs(`Unknown skills subcommand '${subcommand}'.`);
+  }
+}

package/src/runtime/cli-shell.ts

@@ -3,6 +3,7 @@ import { runDep } from "../commands/dep";
 import { runEpic } from "../commands/epic";
 import { runInit } from "../commands/init";
 import { runQuickstart } from "../commands/quickstart";
+import { runSkills } from "../commands/skills";
 import { runSubtask } from "../commands/subtask";
 import { runSync } from "../commands/sync";
 import { runTask } from "../commands/task";
@@ -13,6 +14,7 @@ import { type CliContext, type CliResult, type OutputMode } from "./command-type
 const CLI_VERSION = "0.1.0";
 
 const SUPPORTED_ROOT_COMMANDS: readonly string[] = [
+  "help",
   "init",
   "quickstart",
   "epic",
@@ -20,6 +22,7 @@ const SUPPORTED_ROOT_COMMANDS: readonly string[] = [
   "subtask",
   "dep",
   "sync",
+  "skills",
   "wipe",
 ];
 
@@ -128,6 +131,8 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
   };
 
   switch (parsed.command) {
+    case "help":
+      return runHelp(context);
     case "init":
       return runInit(context);
     case "quickstart":
@@ -144,6 +149,8 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
       return runDep(context);
     case "sync":
       return runSync(context);
+    case "skills":
+      return runSkills(context);
     default:
       return failResult({
         command: "shell",

package/AGENTS.md

@@ -1,54 +0,0 @@
-# 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

@@ -1,18 +0,0 @@
-# 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/bun.lock

@@ -1,28 +0,0 @@
-{
-  "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/tests/commands/dep.test.ts

@@ -1,101 +0,0 @@
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { afterEach, describe, expect, test } from "bun:test";
-
-import { runDep } from "../../src/commands/dep";
-import { runEpic } from "../../src/commands/epic";
-import { runSubtask } from "../../src/commands/subtask";
-import { runTask } from "../../src/commands/task";
-
-const tempDirs: string[] = [];
-
-function createWorkspace(): string {
-  const workspace = mkdtempSync(join(tmpdir(), "trekoon-dep-"));
-  tempDirs.push(workspace);
-  return workspace;
-}
-
-afterEach((): void => {
-  while (tempDirs.length > 0) {
-    const next = tempDirs.pop();
-    if (next) {
-      rmSync(next, { recursive: true, force: true });
-    }
-  }
-});
-
-async function createTaskGraph(cwd: string): Promise<{ taskA: string; taskB: string; subtask: string }> {
-  const epic = await runEpic({
-    cwd,
-    mode: "human",
-    args: ["create", "--title", "Roadmap", "--description", "desc"],
-  });
-  const epicId = (epic.data as { epic: { id: string } }).epic.id;
-
-  const taskA = await runTask({
-    cwd,
-    mode: "human",
-    args: ["create", "--epic", epicId, "--title", "Task A", "--description", "desc a"],
-  });
-  const taskAId = (taskA.data as { task: { id: string } }).task.id;
-
-  const taskB = await runTask({
-    cwd,
-    mode: "human",
-    args: ["create", "--epic", epicId, "--title", "Task B", "--description", "desc b"],
-  });
-  const taskBId = (taskB.data as { task: { id: string } }).task.id;
-
-  const subtask = await runSubtask({
-    cwd,
-    mode: "human",
-    args: ["create", "--task", taskBId, "--title", "Subtask"],
-  });
-
-  return {
-    taskA: taskAId,
-    taskB: taskBId,
-    subtask: (subtask.data as { subtask: { id: string } }).subtask.id,
-  };
-}
-
-describe("dep command", (): void => {
-  test("supports add/list/remove", async (): Promise<void> => {
-    const cwd = createWorkspace();
-    const nodes = await createTaskGraph(cwd);
-
-    const added = await runDep({ cwd, mode: "human", args: ["add", nodes.taskA, nodes.subtask] });
-    expect(added.ok).toBeTrue();
-
-    const listed = await runDep({ cwd, mode: "human", args: ["list", nodes.taskA] });
-    expect(listed.ok).toBeTrue();
-    expect((listed.data as { dependencies: unknown[] }).dependencies.length).toBe(1);
-
-    const removed = await runDep({ cwd, mode: "human", args: ["remove", nodes.taskA, nodes.subtask] });
-    expect(removed.ok).toBeTrue();
-    expect((removed.data as { removed: number }).removed).toBe(1);
-  });
-
-  test("enforces referential checks for task/subtask nodes", async (): Promise<void> => {
-    const cwd = createWorkspace();
-    const nodes = await createTaskGraph(cwd);
-
-    const bad = await runDep({ cwd, mode: "human", args: ["add", nodes.taskA, "missing-node-id"] });
-    expect(bad.ok).toBeFalse();
-    expect(bad.error?.code).toBe("not_found");
-  });
-
-  test("detects dependency cycles", async (): Promise<void> => {
-    const cwd = createWorkspace();
-    const nodes = await createTaskGraph(cwd);
-
-    const first = await runDep({ cwd, mode: "human", args: ["add", nodes.taskA, nodes.taskB] });
-    expect(first.ok).toBeTrue();
-
-    const cycle = await runDep({ cwd, mode: "human", args: ["add", nodes.taskB, nodes.taskA] });
-    expect(cycle.ok).toBeFalse();
-    expect(cycle.error?.code).toBe("invalid_dependency");
-  });
-});