@php-workx/skill-tk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ronny Unger
+
+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

@@ -0,0 +1,70 @@
+# tk
+
+Git-native ticket tracking skill for Claude Code and Codex. Track issues as plain markdown files alongside your code — no databases, no daemons, just files in `.tickets/`.
+
+## Why Use This?
+
+- **Plain markdown**: Tickets are markdown files with YAML frontmatter, directly readable by AI agents without JSON parsing
+- **Git-native**: Tickets live alongside code, tracked by git, survive compaction and session boundaries
+- **Dependency graphs**: Track blockers with cycle detection; `tk ready` shows only unblocked work
+- **IDE-friendly**: Ticket IDs double as filenames — Ctrl+Click on `nw-5c46` in git log opens the ticket
+- **Plugin-extensible**: Drop `tk-<cmd>` executables in PATH to extend functionality
+
+## Quick Start
+
+```text
+tk ready                        # what's unblocked and ready to work on
+tk create "Fix login bug" -t bug -p 1
+tk show mp-a3x9                 # full ticket with computed context
+tk start mp-a3x9                # mark as in progress
+tk close mp-a3x9                # done
+```
+
+## Install
+
+**Prerequisites**: [ticket CLI](https://github.com/wedow/ticket) installed (`brew install ticket`).
+
+```bash
+# Via installer script
+git clone --depth 1 https://github.com/php-workx/skill-tk.git
+cd skill-tk && bash scripts/install-tk-skill.sh
+
+# Via OpenSkills
+npx openskills install php-workx/skill-tk
+```
+
+After install, restart Claude/Codex so the new skill is loaded.
+
+## What It Does
+
+The skill teaches Claude/Codex how to use `tk` for persistent issue tracking:
+
+1. **Session start**: `tk ready` shows actionable work
+2. **During work**: Create, update, and close tickets as context changes
+3. **Session end**: Ticket notes preserve state across sessions
+4. **After compaction**: Tickets survive — they're files in git, not conversation memory
+
+## Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [`CLI_REFERENCE.md`](skills/tk/references/CLI_REFERENCE.md) | All commands, flags, environment variables |
+| [`TICKET_CREATION.md`](skills/tk/references/TICKET_CREATION.md) | When/how to create tickets, file format |
+| [`DEPENDENCIES.md`](skills/tk/references/DEPENDENCIES.md) | Dependencies, links, parent-child hierarchy |
+| [`WORKFLOWS.md`](skills/tk/references/WORKFLOWS.md) | Session start, epic planning, checklists |
+| [`PATTERNS.md`](skills/tk/references/PATTERNS.md) | Knowledge work, resume, side quests |
+| [`INTEGRATION_PATTERNS.md`](skills/tk/references/INTEGRATION_PATTERNS.md) | Task tools layering, RPI workflow |
+| [`PLUGIN_SYSTEM.md`](skills/tk/references/PLUGIN_SYSTEM.md) | Using and creating plugins |
+| [`ANTI_PATTERNS.md`](skills/tk/references/ANTI_PATTERNS.md) | Common mistakes and how to avoid them |
+| [`TROUBLESHOOTING.md`](skills/tk/references/TROUBLESHOOTING.md) | Fixing common issues |
+
+## Development
+
+```bash
+bash scripts/validate.sh       # validate skill structure
+just check                     # full local quality gate
+```
+
+## License
+
+See [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@php-workx/skill-tk",
+  "version": "0.1.0",
+  "description": "Git-native ticket tracking skill for Claude Code and Codex. Plain markdown tickets with YAML frontmatter, dependency graphs, and plugin system.",
+  "keywords": [
+    "skill",
+    "claude",
+    "codex",
+    "ticket",
+    "issue-tracker",
+    "ai-agent",
+    "openskills",
+    "git-native",
+    "markdown"
+  ],
+  "scripts": {
+    "validate": "bash scripts/validate.sh",
+    "test": "npm run validate",
+    "prepublishOnly": "npm run validate"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/php-workx/skill-tk.git"
+  },
+  "license": "MIT",
+  "files": [
+    "skills/",
+    "scripts/install-tk-skill.sh",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/scripts/install-tk-skill.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SKILL_NAME="tk"
+
+SRC_SKILL="$REPO_ROOT/skills/tk"
+
+if [[ ! -d "$SRC_SKILL" ]]; then
+	echo "error: missing source skill directory at $SRC_SKILL" >&2
+	exit 1
+fi
+
+if [[ -d "$HOME/.claude/skills" ]]; then
+	DEST_CLAUDE_BASE="${CLAUDE_SKILLS_DIR:-$HOME/.claude/skills}"
+else
+	DEST_CLAUDE_BASE="${CLAUDE_SKILLS_DIR:-$HOME/.agents/skills}"
+fi
+DEST_CODEX_BASE="${CODEX_SKILLS_DIR:-$HOME/.codex/skills}"
+
+DEST_CLAUDE="$DEST_CLAUDE_BASE/$SKILL_NAME"
+DEST_CODEX="$DEST_CODEX_BASE/$SKILL_NAME"
+
+mkdir -p "$DEST_CLAUDE_BASE" "$DEST_CODEX_BASE"
+
+# Atomic install: copy to temp dirs first, then move into place so a failed
+# copy never leaves the destination in a broken state.
+DEST_CLAUDE_TMP="${DEST_CLAUDE}.installing"
+DEST_CODEX_TMP="${DEST_CODEX}.installing"
+rm -rf "$DEST_CLAUDE_TMP" "$DEST_CODEX_TMP"
+
+cp -R "$SRC_SKILL" "$DEST_CLAUDE_TMP" || {
+	echo "error: failed to copy skill to Claude destination" >&2
+	rm -rf "$DEST_CLAUDE_TMP"
+	exit 1
+}
+cp -R "$SRC_SKILL" "$DEST_CODEX_TMP" || {
+	echo "error: failed to copy skill to Codex destination" >&2
+	rm -rf "$DEST_CLAUDE_TMP" "$DEST_CODEX_TMP"
+	exit 1
+}
+
+rm -rf "$DEST_CLAUDE" "$DEST_CODEX"
+mv "$DEST_CLAUDE_TMP" "$DEST_CLAUDE"
+mv "$DEST_CODEX_TMP" "$DEST_CODEX"
+
+# Make all scripts executable
+for dest in "$DEST_CLAUDE" "$DEST_CODEX"; do
+	for pat in "$dest/scripts/"*.sh; do
+		if compgen -G "$pat" >/dev/null 2>&1; then
+			chmod +x "$pat" || {
+				echo "error: failed to chmod +x $pat" >&2
+				exit 1
+			}
+		fi
+	done
+done
+
+cat <<EOF
+Installed $SKILL_NAME:
+- Claude: $DEST_CLAUDE
+- Codex:  $DEST_CODEX
+EOF

package/skills/tk/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: tk
+description: 'Manages git-backed issue tracking using the tk (ticket) CLI: creates tickets as markdown files with YAML frontmatter in .tickets/, tracks dependencies and links, routes work by priority and assignee, and organizes tickets hierarchically with parent-child relationships. Tickets are plain markdown files, searchable by AI agents without JSON parsing. Use when: "track tickets", "create ticket", "show blockers", "what''s ready to work on", "ticket dependencies", "add note to ticket", or git-based issue tracking with tk.'
+user-invocable: true
+skill_api_version: 1
+context:
+  window: fork
+  intent:
+    mode: task
+  sections:
+    exclude: [HISTORY]
+  intel_scope: topic
+metadata:
+  tier: library
+  dependencies: []
+  internal: false
+---
+
+# tk - Git-Native Ticket Tracking for AI Agents
+
+Plain-markdown ticket tracker that lives alongside your code.
+
+## Overview
+
+**tk (ticket)** stores tickets as markdown files with YAML frontmatter in a `.tickets/` directory. No databases, no daemons — just files tracked by git.
+
+**Key Distinction**:
+- **tk**: Multi-session work, dependencies, survives compaction, git-backed, plain markdown
+- **Task tools (TaskCreate/TaskUpdate/TaskList)**: Single-session tasks, status tracking, conversation-scoped
+
+**Decision Rule**: If resuming in 2 weeks would be hard without tk, use tk.
+
+**Why tk over beads?** Tickets are plain markdown files, directly readable by AI agents without JSON parsing. Ticket IDs double as filenames for IDE navigation (Ctrl+Click on `nw-5c46` in git log opens the ticket).
+
+## Operating Rules
+
+- Treat live `tk` reads as authoritative. Use `tk show`, `tk ready`, `tk ls`, and `tk query` to inspect current tracker state. The `.tickets/` directory contains the canonical data as markdown files.
+- After closing or materially updating a child ticket, reconcile the open parent in the same session. Close the parent when the child resolved the parent's last real gap.
+- If `tk ready` returns a broad umbrella ticket, do not implement directly against vague parent wording. First narrow the remaining gap into an execution-ready child ticket, then land the child and reconcile the parent.
+- Always commit `.tickets/` changes to git after mutations to maintain history.
+- Use this post-mutation sequence when tracker state changes:
+
+```bash
+tk ...                              # mutate tracker state
+git add .tickets/
+git commit -m "tk: <description>"   # commit ticket changes
+```
+
+## Prerequisites
+
+- **tk CLI**: Installed and in PATH (alias for `ticket`)
+- **Git Repository**: Current directory must be within a git repo
+- **Initialization**: `tk create` auto-creates `.tickets/` if not present, or create it manually
+
+## Ticket ID Format
+
+IDs are auto-generated as `<prefix>-<4-char-random>`:
+- Prefix derived from directory name segments (e.g., `my-project` → `mp`, `plan` → `pla`)
+- Random suffix is 4 lowercase alphanumeric characters
+- Examples: `mp-a3x9`, `nw-5c46`, `pla-k2m8`
+- All commands support **partial ID matching** (e.g., `tk show 5c4` matches `nw-5c46`)
+
+## Quick Reference
+
+```bash
+# Find work
+tk ready                        # Open tickets with all deps resolved
+tk blocked                      # Tickets with unresolved deps
+tk ls                           # List all tickets (plugin)
+tk closed                       # Recently closed tickets
+
+# Ticket lifecycle
+tk create "Title" [options]     # Create ticket, prints ID
+tk start <id>                   # Set status → in_progress
+tk close <id>                   # Set status → closed
+tk reopen <id>                  # Set status → open
+tk show <id>                    # Display ticket with context
+
+# Dependencies and links
+tk dep <id> <dep-id>            # Add dependency (first depends on second)
+tk dep tree <id>                # Show dependency tree
+tk dep cycle                    # Find cycles in open tickets
+tk undep <id> <dep-id>          # Remove dependency
+tk link <id> <id> [id...]       # Bidirectional link between tickets
+tk unlink <id> <target-id>      # Remove link
+
+# Notes
+tk add-note <id> "text"         # Append timestamped note
+
+# Escape hatch
+tk super <cmd> [args]           # Bypass plugins, run built-in directly
+```
+
+## Examples
+
+### Skill Loading from /vibe
+
+**User says:** `/vibe`
+
+**What happens:**
+1. Agent loads tk skill automatically via dependency
+2. Agent calls `tk show <id>` to read ticket metadata
+3. Agent links validation findings to the ticket being checked
+4. Output references ticket ID in validation report
+
+**Result:** Validation report includes ticket context, no manual tk lookups needed.
+
+### Skill Loading from /implement
+
+**User says:** `/implement mp-a3x9`
+
+**What happens:**
+1. Agent loads tk skill to understand ticket structure
+2. Agent calls `tk show mp-a3x9` to read ticket body
+3. Agent checks dependencies with `tk dep tree mp-a3x9`
+4. Agent closes ticket with `tk close mp-a3x9` after completion
+
+**Result:** Ticket lifecycle managed automatically during implementation.
+
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| tk command not found | tk CLI not installed or not in PATH | Install via `brew install ticket` or add to PATH |
+| "No .tickets directory found" | `.tickets/` directory missing | Run `tk create` to auto-create, or `mkdir .tickets` |
+| Partial ID matches multiple | Ambiguous short ID | Provide more characters of the ID |
+| Plugin not found | Plugin not in PATH or wrong naming | Name as `tk-<cmd>` or `ticket-<cmd>`, ensure executable |
+
+## Reference Documents
+
+- [references/CLI_REFERENCE.md](references/CLI_REFERENCE.md)
+- [references/TICKET_CREATION.md](references/TICKET_CREATION.md)
+- [references/DEPENDENCIES.md](references/DEPENDENCIES.md)
+- [references/WORKFLOWS.md](references/WORKFLOWS.md)
+- [references/PATTERNS.md](references/PATTERNS.md)
+- [references/INTEGRATION_PATTERNS.md](references/INTEGRATION_PATTERNS.md)
+- [references/PLUGIN_SYSTEM.md](references/PLUGIN_SYSTEM.md)
+- [references/ANTI_PATTERNS.md](references/ANTI_PATTERNS.md)
+- [references/TROUBLESHOOTING.md](references/TROUBLESHOOTING.md)

package/skills/tk/references/ANTI_PATTERNS.md

@@ -0,0 +1,202 @@
+# Anti-Patterns
+
+Hard-won lessons from production tk usage. Avoid these mistakes.
+
+---
+
+## Critical Anti-Patterns
+
+### 1. Modifying Frontmatter Manually Without Understanding Format
+
+**DON'T**: Edit YAML frontmatter with arbitrary formatting
+
+```yaml
+# WRONG — missing brackets, inconsistent formatting
+deps: mp-a3x9, mp-b2y7
+tags: ui backend
+```
+
+**DO**: Follow the exact YAML format tk expects
+
+```yaml
+# CORRECT
+deps: [mp-a3x9, mp-b2y7]
+tags: [ui, backend]
+```
+
+**Why it breaks**: tk parses frontmatter with sed/awk. Non-standard YAML formatting causes parse errors or silent data loss.
+
+---
+
+### 2. Creating Tickets Outside tk
+
+**DON'T**: Manually create markdown files in `.tickets/`
+
+```bash
+# WRONG — ID may collide, frontmatter may be malformed
+echo "---\nid: my-ticket\n---\n# Title" > .tickets/my-ticket.md
+```
+
+**DO**: Always use `tk create`
+
+```bash
+# CORRECT — generates unique ID, proper frontmatter
+tk create "My ticket title" -d "Description"
+```
+
+**Why it breaks**: tk generates IDs based on the directory prefix and random suffix. Manual IDs may not match the expected format, breaking `tk ready`, `tk blocked`, and dependency resolution.
+
+---
+
+### 3. Implementing Directly Against Broad Parent Tickets
+
+**DON'T**: Pick up an epic or broad parent ticket and start coding
+
+```bash
+$ tk ready
+mp-epic1  [P1][open] - API Overhaul
+# Agent starts implementing "API Overhaul" directly
+```
+
+**DO**: Narrow into a focused child ticket first
+
+```bash
+# CORRECT
+tk show mp-epic1    # Read what's left
+tk create "Migrate /users endpoint to v2" --parent mp-epic1 -t task -p 1
+# Implement the specific child
+```
+
+**Why it breaks**: Broad tickets lead to unfocused implementation, scope creep, and incomplete work that's hard to resume.
+
+---
+
+### 4. Forgetting to Reconcile Parents
+
+**DON'T**: Close child tickets without checking the parent
+
+```bash
+tk close mp-child1
+tk close mp-child2
+# Parent mp-epic1 left open with stale notes
+```
+
+**DO**: Reconcile parent after each child closure
+
+```bash
+tk close mp-child1
+tk show mp-epic1                    # Check remaining children
+tk add-note mp-epic1 "child1 done, remaining: child2, child3"
+# ... later, after all children:
+tk close mp-epic1
+```
+
+**Why it breaks**: Stale parent tickets poison `tk ready` with work that's actually done.
+
+---
+
+### 5. Using Dependencies for Soft Preferences
+
+**DON'T**: Add deps when it's "nice to have" ordering
+
+```bash
+# WRONG — tests don't truly need to wait for the refactor
+tk dep mp-tests mp-refactor
+```
+
+**DO**: Use links for related-but-not-blocking work
+
+```bash
+# CORRECT — linked for context, both can proceed independently
+tk link mp-tests mp-refactor
+```
+
+**Why it breaks**: Over-constraining deps creates unnecessary sequential chains, reducing parallelism and making `tk ready` return fewer results.
+
+---
+
+### 6. Leaving Tickets In-Progress Without Notes
+
+**DON'T**: `tk start` a ticket and end the session without context
+
+```bash
+tk start mp-a3x9
+# ... work for a while ...
+# Session ends with no notes added
+```
+
+**DO**: Always leave breadcrumbs
+
+```bash
+tk start mp-a3x9
+# ... work for a while ...
+tk add-note mp-a3x9 "COMPLETED: Schema migration written.
+IN PROGRESS: Endpoint handler for /api/users.
+BLOCKER: Need to decide on pagination strategy (offset vs cursor)."
+```
+
+**Why it breaks**: Without notes, the next session (or post-compaction) has no context. The ticket title alone isn't enough to resume complex work.
+
+---
+
+### 7. Silently Skipping Stale Tickets
+
+**DON'T**: See a stale ticket in `tk ready` and just ignore it
+
+```bash
+$ tk ready
+mp-old1  [P2][open] - Update deployment script  # Seems outdated?
+# Agent skips it without action
+```
+
+**DO**: Normalize or close stale tickets
+
+```bash
+# Option A: Ticket is still relevant but needs updating
+tk add-note mp-old1 "Ticket still valid. Deployment moved to GitHub Actions.
+Updated scope: migrate deploy.sh to .github/workflows/deploy.yml"
+
+# Option B: Ticket is no longer relevant
+tk add-note mp-old1 "No longer needed — deployment was automated in PR #234"
+tk close mp-old1
+```
+
+**Why it breaks**: Ignored stale tickets accumulate, making `tk ready` unreliable.
+
+---
+
+### 8. Cycle-Creating Dependency Chains
+
+**DON'T**: Add dependencies without checking for cycles
+
+```bash
+tk dep mp-a mp-b
+tk dep mp-b mp-c
+tk dep mp-c mp-a    # Creates cycle! All three permanently blocked
+```
+
+**DO**: Check for cycles after complex dependency changes
+
+```bash
+tk dep mp-a mp-b
+tk dep mp-b mp-c
+tk dep cycle         # Verify no cycles before proceeding
+```
+
+**Why it breaks**: Cycles make all involved tickets permanently blocked. They never appear in `tk ready`.
+
+---
+
+## Moderate Anti-Patterns
+
+### 9. Giant Ticket Descriptions
+
+Keep descriptions focused. Long descriptions with implementation details, code snippets, and extensive research belong in notes or linked documents, not the initial description.
+
+### 10. Too Many Tags
+
+Tags are useful for filtering, but don't over-tag. 1-3 tags per ticket is ideal. More than 5 reduces signal-to-noise.
+
+### 11. Priority 0 for Everything
+
+Priority 0 means "drop everything." If everything is P0, nothing is. Reserve P0 for genuine emergencies. Default to P2.