ticket: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

See @README.md for usage documentation. Run tk help for command reference. Always update the README.md usage content when adding/changing commands and flags.

Architecture

Core script: Single-file bash implementation (ticket, ~1000 lines). Uses awk for performant bulk operations on large ticket sets.

Key functions:

• generate_id() - Creates IDs from directory name prefix + random suffix
• ticket_path() - Resolves partial IDs to full file paths
• yaml_field() / update_yaml_field() - YAML frontmatter manipulation via sed
• cmd_*() - Command handlers
• cmd_ready(), cmd_blocked(), cmd_ls() - awk-based bulk listing with sorting

Dependencies: bash, sed, awk, find. Optional: ripgrep (faster grep).

Plugin system: Commands can be extended via external executables in PATH.

• tk foo checks for tk-foo then ticket-foo in PATH
• tk super foo bypasses plugins, runs built-in directly
• Plugins receive TICKETS_DIR and TK_SCRIPT environment variables
• See plugins/README.md for full conventions

Plugins

Directory Structure

plugins/
├── README.md              # Plugin conventions documentation
├── ticket-query           # Extracted from core (requires jq)
├── ticket-migrate-beads   # Extracted from core (requires jq)
└── ...

pkg/
├── extras.txt             # Curated list for ticket-extras meta-package
└── aur/                   # PKGBUILD templates

Plugin File Conventions

Plugins in this repo use ticket- prefix (matching the script name). Both tk-* and ticket-* work at runtime.

Required metadata in first 10 lines:

#!/usr/bin/env bash
# tk-plugin: Short description for tk help
# tk-plugin-version: 1.0.0

Extracting Commands to Plugins

When moving a command from core to a plugin:

1. Create plugins/ticket-<name> with the extracted logic
2. Add metadata comments (tk-plugin:, tk-plugin-version:)
3. Remove cmd_<name>() from core script
4. Remove from dispatch case statement
5. Add <name> to pkg/extras.txt
6. Update CHANGELOG.md (see below)
7. Update README.md usage section