@php-workx/skill-tk 0.1.0

package/skills/tk/references/PATTERNS.md

@@ -0,0 +1,219 @@
+# Common Usage Patterns
+
+Practical patterns for using tk effectively across different scenarios.
+
+## Contents
+
+- [Knowledge Work Session](#knowledge-work-session)
+- [Broad Parent Narrowing](#broad-parent-narrowing)
+- [Side Quest Handling](#side-quest-handling)
+- [Multi-Session Project Resume](#multi-session-project-resume)
+- [Status Transitions](#status-transitions)
+- [Compaction Recovery](#compaction-recovery)
+- [Ticket Closure](#ticket-closure)
+- [Reading Tickets Directly](#reading-directly)
+
+---
+
+## Knowledge Work Session
+
+**Scenario**: User asks "Help me write a proposal for expanding the analytics platform"
+
+**What you see**:
+```bash
+$ tk ready
+mp-42  [P2][in_progress] - Research analytics platform expansion proposal
+
+$ tk show mp-42
+# Full ticket markdown with notes:
+# COMPLETED: Reviewed current stack (Mixpanel, Amplitude)
+# IN PROGRESS: Drafting cost-benefit analysis section
+# NEXT: Need user input on budget constraints
+```
+
+**What you do**:
+1. Read ticket notes to understand current state
+2. Create Task tools for immediate work
+3. Work on tasks, mark completed as you go
+4. At milestone, update ticket notes:
+   ```bash
+   tk add-note mp-42 "COMPLETED: Cost-benefit analysis drafted.
+   KEY DECISION: User confirmed $50k budget cap - ruled out enterprise options.
+   IN PROGRESS: Finalizing recommendations (Posthog + custom ETL).
+   NEXT: Get user review of draft before closing."
+   ```
+
+**Key insight**: Notes field captures the "why" and context; Task tools track the "doing" right now.
+
+---
+
+## Broad Parent Narrowing
+
+**Scenario**: `tk ready` surfaces a parent ticket that is still open but only a narrow gap remains.
+
+**Pattern**:
+1. Read the parent with `tk show <parent-id>`
+2. Assess: what specific work is left?
+3. Create a focused child ticket for the remaining gap
+4. Implement the child
+5. Close child, then close parent if fully resolved
+
+```bash
+$ tk show mp-epic1
+# Title: "API Overhaul"
+# Children: mp-c1 [closed], mp-c2 [closed], mp-c3 [open]
+# Notes say: "All endpoints migrated except /api/legacy/export"
+
+# Create precise child for remaining work
+tk create "Migrate /api/legacy/export to v2 format" --parent mp-epic1 -p 2
+
+# After implementing and closing the new child:
+tk close mp-epic1
+```
+
+---
+
+## Side Quest Handling
+
+**Scenario**: While implementing a feature, you discover an unrelated bug.
+
+### Assess
+
+```
+Is this bug blocking my current work?
+  YES → Create ticket with dep, switch context
+  NO  → Create ticket, link, continue current work
+```
+
+### Non-blocking Side Quest
+
+```bash
+# Capture without losing context
+tk create "Bug: cache returns stale data after TTL" -t bug -p 2 --tags cache
+tk link mp-current mp-new-bug
+# Continue with current work
+```
+
+### Blocking Side Quest
+
+```bash
+# Create and mark as blocker
+tk create "Fix: database timeout on large queries" -t bug -p 0 --tags db
+# Output: mp-fix1
+tk dep mp-current mp-fix1
+tk start mp-fix1
+# Fix the bug, then:
+tk close mp-fix1
+tk start mp-current  # Resume original work
+```
+
+---
+
+## Multi-Session Project Resume
+
+**Scenario**: Returning to a project after days or weeks.
+
+```bash
+# Step 1: Active work
+$ tk ls --status=in_progress
+mp-a3x9  [in_progress] - Implement search indexing
+
+# Step 2: Read context
+$ tk show mp-a3x9
+# Notes reveal: "COMPLETED: Elasticsearch client configured.
+# IN PROGRESS: Building index mappings for products table.
+# BLOCKER: Need to decide between nested vs. flattened schema."
+
+# Step 3: Ready queue
+$ tk ready
+mp-b2y7  [P1][open] - Add product search API endpoint
+mp-c4z1  [P2][open] - Search results pagination
+
+# Step 4: Blocked queue
+$ tk blocked
+mp-d6w3  [P1][open] - Deploy search to staging <- [mp-a3x9, mp-b2y7]
+```
+
+Now you have full context without any prior conversation history.
+
+---
+
+## Status Transitions
+
+### When to Change Status
+
+| Event | Action |
+|-------|--------|
+| Picking up a ticket to work on | `tk start <id>` |
+| Work completed, acceptance met | `tk close <id>` |
+| Closed ticket needs more work | `tk reopen <id>` |
+| Pausing work (session end) | Keep `in_progress`, update notes |
+| Discovered ticket is invalid | `tk close <id>` with note explaining why |
+
+### Status Hygiene
+
+- Don't leave tickets `in_progress` across sessions without notes explaining state
+- `tk ready` only surfaces `open` and `in_progress` tickets — `closed` are excluded
+- Review `in_progress` tickets at session start: are they still active?
+
+---
+
+## Compaction Recovery
+
+**After conversation compaction**, you lose all chat context but tickets persist.
+
+```bash
+# What was I doing?
+tk ls --status=in_progress
+
+# What's the full context?
+tk show <each-in-progress-id>
+
+# What can I work on next?
+tk ready
+```
+
+Tickets with good notes are self-documenting. The notes section is your compaction-proof memory.
+
+---
+
+## Ticket Closure
+
+### Document Completion
+
+```bash
+# Add completion context before closing
+tk add-note mp-a3x9 "COMPLETED: Search indexing fully implemented.
+Chose nested schema for products (better query flexibility).
+Tests added: unit (12), integration (4). All passing."
+
+tk close mp-a3x9
+```
+
+### Reconcile Parent
+
+```bash
+# After closing a child, check parent
+tk show mp-parent
+# If all children closed → tk close mp-parent
+# If work remains → update parent notes
+```
+
+---
+
+## Reading Tickets Directly {#reading-directly}
+
+Since tickets are plain markdown files, you can read them directly when `tk` is unavailable or for batch processing:
+
+```bash
+# Read a specific ticket
+cat .tickets/mp-a3x9.md
+
+# Search across all tickets
+grep -l "OAuth" .tickets/*.md
+
+# Find all open tickets (checking frontmatter)
+grep -l "status: open" .tickets/*.md
+```
+
+**Prefer `tk show`** when available — it adds computed sections (Blockers, Blocking, Children, Linked) that raw file reads miss. But direct file access is always an option.

package/skills/tk/references/PLUGIN_SYSTEM.md

@@ -0,0 +1,178 @@
+# Plugin System
+
+How to discover, use, and create tk plugins.
+
+## Contents
+
+- [Overview](#overview)
+- [Bundled Plugins](#bundled-plugins)
+- [Plugin Discovery](#plugin-discovery)
+- [Using Plugins](#using-plugins)
+- [Creating Plugins](#creating-plugins)
+- [Package Distribution](#package-distribution)
+
+---
+
+## Overview {#overview}
+
+tk has a plugin system based on executable naming conventions. Any executable named `tk-<cmd>` or `ticket-<cmd>` in `$PATH` is automatically discovered as a plugin.
+
+**Plugin precedence**:
+1. `tk-<cmd>` prefix takes precedence over `ticket-<cmd>`
+2. Plugin lookup happens **before** built-in command dispatch
+3. Use `tk super <cmd>` to bypass plugins and run built-in commands
+
+---
+
+## Bundled Plugins {#bundled-plugins}
+
+These ship with the `ticket-extras` package:
+
+### `tk edit <id>`
+
+Opens a ticket file in `$EDITOR` (falls back to `vi`).
+
+**For humans only** — agents should read/modify ticket files directly or use `tk add-note`.
+
+### `tk ls` / `tk list`
+
+List tickets with optional filters:
+
+```bash
+tk ls                          # All tickets
+tk ls --status=open            # Filter by status
+tk ls -a "Jane Doe"            # Filter by assignee
+tk ls -T backend               # Filter by tag
+```
+
+Output format: `<id>     [<status>] - <title> <- [dep1, dep2]`
+
+### `tk query [jq-filter]`
+
+Output tickets as JSONL, optionally filtered with jq:
+
+```bash
+# All tickets as JSONL
+tk query
+
+# Filter with jq
+tk query '.status == "open" and .priority <= 1'
+```
+
+**Requires**: `jq` installed
+
+### `tk migrate-beads`
+
+Import tickets from a `.beads/issues.jsonl` file:
+
+```bash
+tk migrate-beads
+```
+
+Converts beads issues to tk markdown format. **Requires**: `jq` installed
+
+---
+
+## Plugin Discovery {#plugin-discovery}
+
+tk discovers plugins by:
+1. Searching `$PATH` for executables named `tk-*` or `ticket-*`
+2. Reading plugin metadata from the script
+
+### Listing Installed Plugins
+
+```bash
+tk help
+```
+
+The help output shows all built-in commands plus discovered plugins with descriptions.
+
+### Plugin Metadata
+
+Plugins expose metadata via comments in the first 10 lines:
+
+```bash
+#!/bin/bash
+# tk-plugin: Brief description of what this plugin does
+# tk-plugin-version: 1.0.0
+```
+
+For compiled binaries, support the `--tk-describe` flag:
+
+```bash
+$ tk-myplugin --tk-describe
+Brief description of what this plugin does
+```
+
+---
+
+## Using Plugins {#using-plugins}
+
+Plugins are invoked transparently — just use the command name:
+
+```bash
+tk ls --status=open            # Runs tk-ls or ticket-ls plugin
+tk query '.priority == 0'      # Runs tk-query or ticket-query plugin
+```
+
+### Bypassing Plugins
+
+If a plugin shadows a built-in command:
+
+```bash
+tk super <cmd> [args]          # Always runs the built-in
+```
+
+---
+
+## Creating Plugins {#creating-plugins}
+
+### Minimum Requirements
+
+1. Executable file named `tk-<cmd>` or `ticket-<cmd>`
+2. In `$PATH`
+3. Plugin metadata comment in first 10 lines (optional but recommended)
+
+### Environment Variables Available to Plugins
+
+| Variable | Description |
+|----------|-------------|
+| `TICKETS_DIR` | Absolute path to the `.tickets/` directory |
+| `TK_SCRIPT` | Absolute path to the main tk script |
+
+### Example Plugin
+
+```bash
+#!/bin/bash
+# tk-plugin: Show ticket statistics
+# tk-plugin-version: 1.0.0
+
+total=$(ls "$TICKETS_DIR"/*.md 2>/dev/null | wc -l)
+open=$(grep -l "status: open" "$TICKETS_DIR"/*.md 2>/dev/null | wc -l)
+in_progress=$(grep -l "status: in_progress" "$TICKETS_DIR"/*.md 2>/dev/null | wc -l)
+closed=$(grep -l "status: closed" "$TICKETS_DIR"/*.md 2>/dev/null | wc -l)
+
+echo "Total: $total | Open: $open | In Progress: $in_progress | Closed: $closed"
+```
+
+Save as `tk-stats`, make executable, place in `$PATH`.
+
+---
+
+## Package Distribution {#package-distribution}
+
+tk is distributed as multiple packages:
+
+| Package | Contents |
+|---------|----------|
+| `ticket` | Meta-package (depends on ticket-core + ticket-extras) |
+| `ticket-core` | Core `ticket` script only |
+| `ticket-extras` | Curated plugins (edit, ls, query, migrate-beads) |
+| `ticket-<plugin>` | Individual plugin packages (e.g., `ticket-query`) |
+
+Install via Homebrew:
+
+```bash
+brew install ticket             # Full install
+brew install ticket-core        # Core only
+```

package/skills/tk/references/TICKET_CREATION.md

@@ -0,0 +1,153 @@
+# Ticket Creation Guidelines
+
+Guidance on when and how to create tk tickets for maximum effectiveness.
+
+## Contents
+
+- [When to Ask First vs Create Directly](#when-to-ask)
+- [Ticket Quality](#quality)
+- [Making Tickets Resumable](#resumable)
+- [Design vs Acceptance Criteria](#design-vs-acceptance)
+- [Ticket File Format](#file-format)
+
+## When to Ask First vs Create Directly {#when-to-ask}
+
+### Ask the user before creating when:
+- Knowledge work with fuzzy boundaries
+- Task scope is unclear
+- Multiple valid approaches exist
+- User's intent needs clarification
+
+### Create directly when:
+- Clear bug discovered during implementation
+- Obvious follow-up work identified
+- Technical debt with clear scope
+- Dependency or blocker found
+
+**Why ask first for knowledge work?** Task boundaries in strategic/research work are often unclear until discussed. Technical implementation tasks are usually well-defined. Discussion prevents poorly-scoped tickets that need immediate revision.
+
+## Ticket Quality {#quality}
+
+Use clear, specific titles and include sufficient context in descriptions to resume work later.
+
+### Field Usage
+
+**Use --design flag for:**
+- Implementation approach decisions
+- Architecture notes
+- Trade-offs considered
+
+**Use --acceptance flag for:**
+- Definition of done
+- Testing requirements
+- Success metrics
+
+### Good vs Bad Titles
+
+```bash
+# BAD - vague
+tk create "Fix the bug"
+tk create "Update stuff"
+
+# GOOD - specific and actionable
+tk create "Fix redirect loop on OAuth callback when session expired" -t bug -p 1
+tk create "Add rate limiting to /api/upload endpoint" -t feature -p 2
+```
+
+## Making Tickets Resumable {#resumable}
+
+For complex technical features spanning multiple sessions, use notes to capture implementation state.
+
+### Valuable note content for technical work:
+- Working code snippets (tested, with response format)
+- Sample API responses showing actual data
+- Desired output format examples (show, don't describe)
+- Research context (why this approach, what was discovered)
+
+### Example pattern:
+
+```bash
+tk add-note mp-a3x9 "IMPLEMENTATION GUIDE:
+WORKING CODE: service.about().get(fields='importFormats')
+Returns: dict with 49 entries like {'text/markdown': [...]}
+OUTPUT FORMAT: # Drive Import Formats (markdown with categorized list)
+CONTEXT: text/markdown support added July 2024, not in static docs"
+```
+
+**When to add:** Multi-session technical features with APIs or specific formats. Skip for simple tasks.
+
+## Design vs Acceptance Criteria {#design-vs-acceptance}
+
+Common mistake: Putting implementation details in acceptance criteria.
+
+### DESIGN field (HOW to build it):
+- "Use two-phase approach: validate input first, then process"
+- "Parse with regex to find markers"
+- "Use JWT tokens with 1-hour expiry"
+- Trade-offs: "Chose batch API over streaming for atomicity"
+
+### ACCEPTANCE CRITERIA (WHAT SUCCESS LOOKS LIKE):
+- "Users can log in with Google OAuth"
+- "Rate limiter returns 429 after 100 req/min"
+- "All existing tests continue to pass"
+- "Response time under 200ms at p95"
+
+## Ticket File Format {#file-format}
+
+Tickets are stored as markdown files in `.tickets/` with YAML frontmatter:
+
+```markdown
+---
+id: mp-a3x9
+status: open
+deps: []
+links: []
+created: 2026-01-15T10:30:00Z
+type: task
+priority: 2
+assignee: Jane Doe
+external-ref: gh-456
+parent: mp-b2y7
+tags: [ui, backend, urgent]
+---
+# Implement OAuth Flow
+
+Add Google and GitHub OAuth providers using passport.js strategy pattern.
+
+## Design
+
+Use passport.js strategy pattern. Google strategy first, then GitHub.
+Token refresh handled via middleware.
+
+## Acceptance Criteria
+
+- Users can log in with Google
+- Users can log in with GitHub
+- Session persists across page refreshes
+
+## Notes
+
+**2026-01-15T12:00:00Z**
+
+Discovered that passport-google-oauth20 requires specific callback URL format.
+
+**2026-01-16T09:00:00Z**
+
+GitHub strategy working. Google needs additional scope for email access.
+```
+
+### Frontmatter Fields
+
+| Field | Type | Values/Default |
+|-------|------|----------------|
+| `id` | string | Auto-generated `<prefix>-<4chars>` |
+| `status` | string | `open`, `in_progress`, `closed` |
+| `deps` | array | Ticket IDs this depends on |
+| `links` | array | Symmetrically linked ticket IDs |
+| `created` | string | ISO 8601 UTC `YYYY-MM-DDTHH:MM:SSZ` |
+| `type` | string | `bug`, `feature`, `task`, `epic`, `chore` (default: `task`) |
+| `priority` | integer | 0-4, 0=highest (default: 2) |
+| `assignee` | string | Defaults to `git config user.name` |
+| `external-ref` | string | External reference (e.g., `gh-123`) |
+| `parent` | string | Parent ticket ID |
+| `tags` | array | Tags (e.g., `[ui, backend]`) |