Skip to content

tk - Plugin Specification Standard (PLUGIN_SPEC.md)

Architecture and compliance requirements for tk plugins.

1. Core Principles

  1. Decoupled: Plugins extend tk without modifying the core ticket CLI.
  2. Optional: Plugins are optional. Users who need only the core CLI never need external runtimes.
  3. Spec-Driven: Every plugin maintains a <PLUGIN-NAME>-SPEC.md specifying commands, flags, schema, and dependencies.
  4. Isolated: Each plugin lives in its own directory under plugins/<plugin-name>/.

2. Directory Layout Standard

Each plugin in the repository is organized in its own isolated subfolder:

plugins/
├── README.md
├── github/
│   ├── GITHUB-SPEC.md           # Plugin-specific specification
│   ├── ticket-github            # Executable binary / script
│   └── tk-github -> ticket-github
├── scion-taskforce/             # Python-backed plugin (thin bash entrypoint)
│   ├── SCION-TASKFORCE-SPEC.md
│   ├── install.sh               # Optional: standalone installer (--uninstall supported)
│   ├── scion-taskforce.yaml     # Optional: default config shipped with the plugin
│   ├── ticket-scion-taskforce   # Executable entrypoint
│   ├── tk-scion-taskforce -> ticket-scion-taskforce
│   └── tk_scion_taskforce/      # Plugin's own package; never imported by core
└── webui/
    └── WEBUI-SPEC.md -> ../../tk_webui/WEBUI-SPEC.md

2.1 Installation Contract

  • The repo-level install.sh MUST offer a dedicated target per plugin (--<plugin-name>) and MUST NOT add plugins to the default --full bundle (which ships only the Web UI alongside core and the agent skill); only --all installs every plugin.
  • A plugin MAY ship its own plugins/<name>/install.sh (supporting --uninstall). If it does, the repo-level target MUST delegate to it rather than duplicating the logic.
  • Installation MUST NOT touch the core ticket script. Discovery is purely by $PATH: once tk-<name> is installed, tk help lists it automatically using its # tk-plugin: description.

3. Metadata & Discovery Contract

tk automatically discovers plugins available in $PATH matching tk-<command> or ticket-<command>.

3.1 Header Comments (Scripts)

Shell, Python, or Ruby scripts MUST include metadata comments in their first 10 lines: 

#!/usr/bin/env bash
# tk-plugin: Single-line description of the plugin
# tk-plugin-version: 1.0.0

3.2 Flags (Compiled Binaries)

Compiled binaries (Go, Rust, C) MUST implement: - --tk-describe: Prints tk-plugin: <description> to stdout and exits with code 0. - --version / -v: Prints <plugin-name> <version> to stdout and exits with code 0. - --help / -h: Displays standard usage and command help.

4. Execution Protocol & Context

When tk <plugin-command> [args...] is executed: 1. tk looks for tk-<plugin-command> or ticket-<plugin-command> on $PATH, then under plugins/<plugin-command>/. A plugin takes precedence over a built-in command of the same name. 2. tk resolves the .tickets/ folder (TICKETS_DIR if set, else upward discovery) and exports environment variables: - TICKETS_DIR: Path to the .tickets/ directory. Exported only when set or found; plugins MUST handle it being unset. - TK_SCRIPT: Absolute path to tk executable. 3. tk invokes the plugin with the remaining arguments using exec.

4.1 Calling Core Built-Ins

Plugins can execute core tk routines without triggering recursion by using: 

"$TK_SCRIPT" super <built-in-command> [args...]

Plugins SHOULD write tickets through tk rather than editing files directly, so that locks, value validation and post-write hooks apply.

4.2 Reacting to Changes

Plugins that react to ticket writes SHOULD install an executable in .tickets/.hooks/post-write.d/ rather than polling or running a daemon. See SPEC §5.1 for events and environment.

5. Plugin Specification Template (<PLUGIN-NAME>-SPEC.md)

Each plugin's <PLUGIN-NAME>-SPEC.md must include: 1. Overview & Purpose: What the plugin does and why it exists. 2. Commands & CLI Flags: Exhaustive list of arguments and flags. 3. Data Schema / Metadata: Any tags, frontmatter keys, or file structures used. 4. Dependencies: External CLIs or runtimes required (e.g. gh, jq, python3). 5. Installation & Uninstallation: Instructions for installing and cleanly removing the plugin.