@php-workx/skill-tk 0.1.0

package/skills/tk/references/CLI_REFERENCE.md

@@ -0,0 +1,228 @@
+# CLI Command Reference
+
+**For:** AI agents and developers using the tk (ticket) command-line interface
+
+## Quick Navigation
+
+- [Finding Work](#finding-work)
+- [Ticket Lifecycle](#ticket-lifecycle)
+- [Dependencies](#dependencies)
+- [Links](#links)
+- [Notes](#notes)
+- [Listing and Querying](#listing-and-querying)
+- [Escape Hatch](#escape-hatch)
+
+## Finding Work
+
+### Ready Tickets (unblocked)
+
+```bash
+# List open/in_progress tickets with all deps resolved
+tk ready
+
+# Filter by assignee or tag
+tk ready -a "Jane Doe"
+tk ready -T backend
+```
+
+Output format (sorted by priority then ID):
+```
+mp-a3x9  [P1][open] - Implement auth endpoint
+mp-b2y7  [P2][in_progress] - Add input validation
+```
+
+### Blocked Tickets
+
+```bash
+# List tickets with unresolved deps
+tk blocked
+tk blocked -a "Jane Doe"
+tk blocked -T urgent
+```
+
+Output format:
+```
+mp-c4z1  [P1][open] - Deploy to prod <- [mp-a3x9, mp-b2y7]
+```
+
+### Closed Tickets
+
+```bash
+# Recently closed (default 20, sorted by mtime)
+tk closed
+tk closed --limit=5
+tk closed -a "Jane Doe"
+```
+
+## Ticket Lifecycle
+
+### Create
+
+```bash
+# Basic creation — prints the generated ID
+tk create "Fix login redirect bug"
+
+# Full options
+tk create "Implement OAuth flow" \
+  -d "Add Google and GitHub OAuth providers" \
+  --design "Use passport.js strategy pattern" \
+  --acceptance "Users can log in with Google or GitHub" \
+  -t feature \
+  -p 1 \
+  -a "Jane Doe" \
+  --tags ui,auth,backend \
+  --parent mp-a3x9 \
+  --external-ref gh-456
+```
+
+**Create flags:**
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--description` | `-d` | Description text | — |
+| `--design` | — | Design/implementation notes | — |
+| `--acceptance` | — | Acceptance criteria | — |
+| `--type` | `-t` | `bug\|feature\|task\|epic\|chore` | `task` |
+| `--priority` | `-p` | 0-4, 0=highest | `2` |
+| `--assignee` | `-a` | Assignee name | `git user.name` |
+| `--tags` | — | Comma-separated tags | — |
+| `--parent` | — | Parent ticket ID | — |
+| `--external-ref` | — | External ref (e.g., `gh-123`, `JIRA-456`) | — |
+
+### Status Transitions
+
+```bash
+tk start <id>                  # open → in_progress
+tk close <id>                  # any → closed
+tk reopen <id>                 # closed → open
+tk status <id> <status>        # Set to any valid status
+```
+
+Valid statuses: `open`, `in_progress`, `closed`
+
+### Show Ticket
+
+```bash
+tk show <id>
+```
+
+Displays the full ticket markdown plus dynamically computed sections:
+- **## Blockers** — tickets this depends on that are still open
+- **## Blocking** — open tickets that depend on this one
+- **## Children** — tickets with this as parent
+- **## Linked** — symmetrically linked tickets
+
+### Edit Ticket (Plugin, Humans Only)
+
+```bash
+tk edit <id>                   # Opens in $EDITOR
+```
+
+Agents should modify ticket files directly or use `tk add-note` instead.
+
+## Dependencies
+
+```bash
+# Add dependency: first ticket depends on second
+tk dep mp-a3x9 mp-b2y7
+
+# Show dependency tree
+tk dep tree mp-a3x9
+tk dep tree --full mp-a3x9     # Disable dedup for full tree
+
+# Find cycles in open tickets
+tk dep cycle
+
+# Remove dependency
+tk undep mp-a3x9 mp-b2y7
+```
+
+Dependencies affect `tk ready` — a ticket with unresolved deps is excluded from the ready list.
+
+## Links
+
+Links are symmetric/bidirectional and do **not** affect `tk ready`.
+
+```bash
+# Link tickets together
+tk link mp-a3x9 mp-b2y7 mp-c4z1
+
+# Remove a link
+tk unlink mp-a3x9 mp-b2y7
+```
+
+## Notes
+
+```bash
+# Append a timestamped note
+tk add-note mp-a3x9 "Discovered edge case in token refresh"
+
+# Pipe note from stdin
+echo "Detailed findings..." | tk add-note mp-a3x9
+```
+
+Notes are appended to the `## Notes` section with an ISO 8601 timestamp header.
+
+## Listing and Querying
+
+### List (Plugin)
+
+```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:
+```
+mp-a3x9  [open] - Implement auth endpoint <- [mp-b2y7]
+```
+
+### Query (Plugin, requires jq)
+
+```bash
+# Output as JSONL
+tk query
+
+# With jq filter
+tk query '.status == "open" and .priority <= 1'
+```
+
+## Escape Hatch
+
+```bash
+# Bypass plugins, run built-in command directly
+tk super <cmd> [args]
+```
+
+Use when a plugin overrides a built-in command and you need the original behavior.
+
+## Filter Flags (Common to ready, blocked, closed, ls)
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--assignee=X` | `-a X` | Filter by assignee |
+| `--tag=X` | `-T X` | Filter by tag |
+| `--status=X` | — | Filter by status (ls only) |
+| `--limit=N` | — | Limit results (closed only, default 20) |
+
+## Partial ID Matching
+
+All commands accepting an ID support partial matching. The shortest unambiguous prefix works:
+
+```bash
+tk show 5c4                    # Matches nw-5c46
+tk close a3x                   # Matches mp-a3x9
+```
+
+If multiple tickets match, tk reports an error asking for a longer prefix.
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `TICKETS_DIR` | Override `.tickets/` directory location |
+| `TICKET_PAGER` | Pager for `show` (TTY only, falls back to `PAGER`) |
+| `TK_SCRIPT` | Exported to plugins: absolute path to tk script |
+| `EDITOR` | Used by `edit` plugin (falls back to `vi`) |

package/skills/tk/references/DEPENDENCIES.md

@@ -0,0 +1,189 @@
+# Dependencies and Links Guide
+
+How tk manages relationships between tickets: dependencies (blocking) and links (informational).
+
+## Contents
+
+- [Overview](#overview)
+- [Dependencies (Blocking)](#dependencies)
+- [Links (Bidirectional)](#links)
+- [Parent-Child Hierarchy](#parent-child)
+- [Decision Guide](#decision-guide)
+- [Common Mistakes](#common-mistakes)
+
+## Overview {#overview}
+
+tk supports three relationship types:
+
+| Type | Purpose | Affects `tk ready`? | Storage |
+|------|---------|---------------------|---------|
+| **deps** | Hard blocker | Yes — blocked tickets excluded | `deps:` array in frontmatter |
+| **links** | Informational | No — just context | `links:` array in frontmatter |
+| **parent** | Hierarchy | No — structural only | `parent:` field in frontmatter |
+
+**Key insight**: Only `deps` affect what work is ready. Links and parent-child are organizational.
+
+## Dependencies (Blocking) {#dependencies}
+
+A dependency means "this ticket cannot proceed until the dependency is resolved."
+
+### When to Use
+- Sequential work: API must exist before UI can call it
+- Prerequisites: Schema migration before data import
+- Build order: Library before consumer
+
+### When NOT to Use
+- Soft preferences ("it would be nice to do X first")
+- Parallel work that happens to be related
+- Informational context
+
+### Creating Dependencies
+
+```bash
+# mp-a3x9 depends on mp-b2y7 (a3x9 blocked until b2y7 is closed)
+tk dep mp-a3x9 mp-b2y7
+
+# Check what's blocking
+tk blocked
+
+# Show dependency tree
+tk dep tree mp-a3x9
+
+# Find cycles (important before adding deps)
+tk dep cycle
+
+# Remove dependency
+tk undep mp-a3x9 mp-b2y7
+```
+
+### Automatic Unblocking
+
+When you `tk close mp-b2y7`, any ticket that depended solely on it automatically becomes ready (appears in `tk ready`).
+
+### Dependency Tree
+
+```bash
+$ tk dep tree mp-a3x9
+mp-a3x9 - Deploy to production
+  mp-b2y7 - Implement auth endpoint [open]
+    mp-c4z1 - Add database migration [closed] ✓
+  mp-d6w3 - Write integration tests [open]
+```
+
+The `--full` flag disables deduplication for diamond dependencies.
+
+### Cycle Detection
+
+```bash
+$ tk dep cycle
+CYCLE DETECTED: mp-a3x9 -> mp-b2y7 -> mp-c4z1 -> mp-a3x9
+```
+
+Always check for cycles after adding complex dependency chains.
+
+## Links (Bidirectional) {#links}
+
+Links are symmetric — linking A to B also links B to A. They provide context without blocking.
+
+### When to Use
+- Related features that inform each other
+- Research findings relevant to another ticket
+- Parallel work by different team members on connected areas
+
+### Creating Links
+
+```bash
+# Link multiple tickets (all become linked to each other)
+tk link mp-a3x9 mp-b2y7 mp-c4z1
+
+# Remove a specific link
+tk unlink mp-a3x9 mp-b2y7
+```
+
+Links appear in `tk show` output under the `## Linked` section.
+
+## Parent-Child Hierarchy {#parent-child}
+
+Parent-child relationships organize tickets into epics and subtasks.
+
+### Creating Hierarchies
+
+```bash
+# Create epic
+tk create "Auth System" -t epic -p 1
+# Output: mp-a3x9
+
+# Create children
+tk create "Login UI" --parent mp-a3x9 -p 1
+tk create "Backend validation" --parent mp-a3x9 -p 2
+tk create "Integration tests" --parent mp-a3x9 -p 2
+```
+
+Children appear in `tk show mp-a3x9` under the `## Children` section.
+
+### Combining with Dependencies
+
+Parent-child is structural. Add deps when order matters:
+
+```bash
+# Create children
+tk create "Schema migration" --parent mp-a3x9 -p 1    # → mp-e1r2
+tk create "API endpoints" --parent mp-a3x9 -p 1        # → mp-f3s4
+tk create "Frontend integration" --parent mp-a3x9 -p 2 # → mp-g5t6
+
+# Add sequential deps
+tk dep mp-f3s4 mp-e1r2     # API depends on schema
+tk dep mp-g5t6 mp-f3s4     # Frontend depends on API
+```
+
+## Decision Guide {#decision-guide}
+
+```
+Is ticket B required before ticket A can start?
+  YES → tk dep A B
+  NO  → Are they related but independent?
+    YES → tk link A B
+    NO  → Is B a subtask of A?
+      YES → tk create "B title" --parent A
+      NO  → No relationship needed
+```
+
+### Quick Reference by Situation
+
+| Situation | Relationship |
+|-----------|-------------|
+| "Can't start until X is done" | `tk dep` |
+| "Related to X, good to know" | `tk link` |
+| "Part of the X epic" | `--parent X` |
+| "We should probably do X first" (soft) | `tk link` (not dep) |
+| "X and Y touch the same code" | `tk link` |
+
+## Common Mistakes {#common-mistakes}
+
+### Using deps for preferences
+
+```bash
+# WRONG — soft preference, not a true blocker
+tk dep mp-tests mp-refactor
+
+# RIGHT — link for context, work on tests whenever
+tk link mp-tests mp-refactor
+```
+
+### Wrong dependency direction
+
+```bash
+# WRONG — says migration depends on API (backwards)
+tk dep mp-migration mp-api
+
+# RIGHT — API depends on migration being done first
+tk dep mp-api mp-migration
+```
+
+### Over-using deps
+
+Too many dependencies create long sequential chains. Ask: "Can these actually be done in parallel?" If yes, use links instead.
+
+### Not checking for cycles
+
+Always run `tk dep cycle` after adding complex dependency chains. Cycles make tickets permanently blocked.

package/skills/tk/references/INTEGRATION_PATTERNS.md

@@ -0,0 +1,149 @@
+# Integration Patterns with Other Skills
+
+How tk integrates with Task tools (TaskCreate, TaskUpdate, TaskList), planning skills, and the RPI workflow.
+
+## Contents
+
+- [Task Tools Integration](#task-tools-integration)
+- [RPI Workflow Integration](#rpi-integration)
+- [Cross-Skill Workflows](#cross-skill-workflows)
+- [Decision Framework](#decision-framework)
+
+---
+
+## Task Tools Integration
+
+**Both tools complement each other at different timescales:**
+
+### Temporal Layering Pattern
+
+**Task tools** (short-term working memory — this hour):
+- Tactical execution: "Review Section 3", "Expand Q&A answers"
+- Marked completed via TaskUpdate as you go
+- Present/future tense ("Review", "Expand", "Create")
+- Ephemeral: Task list resets when session ends
+
+**tk tickets** (long-term episodic memory — this week/month):
+- Strategic objectives: "Continue work on strategic planning document"
+- Key decisions and outcomes in notes field
+- Past tense in notes ("COMPLETED", "Discovered", "Blocked by")
+- Persistent: Survives compaction and session boundaries
+
+**Key insight**: Task tools = working copy for the current hour. Tickets = project journal for the current month.
+
+### The Handoff Pattern
+
+1. **Session start**: Read ticket → Create tasks via TaskCreate for immediate actions
+2. **During work**: Mark tasks completed via TaskUpdate as you go
+3. **Reach milestone**: `tk add-note <id>` with outcomes + context
+4. **Session end**: Task list resets, ticket survives with enriched notes
+
+**After compaction**: Task list is gone, but ticket notes reconstruct what happened.
+
+### Example: Task tools track execution, tk captures meaning
+
+**Task tools (ephemeral execution view):**
+```
+TaskCreate: "Implement login endpoint" (pending)
+TaskCreate: "Add password hashing with bcrypt" (pending)
+TaskCreate: "Create session middleware" (pending)
+Mark completed via TaskUpdate as you go.
+```
+
+**Corresponding ticket notes (persistent context):**
+```bash
+tk add-note mp-auth "COMPLETED: Login endpoint with bcrypt password
+hashing (12 rounds). KEY DECISION: Using JWT tokens (not sessions) for
+stateless auth - simplifies horizontal scaling. IN PROGRESS: Session
+middleware implementation. NEXT: Need user input on token expiry time
+(1hr vs 24hr trade-off)."
+```
+
+---
+
+## RPI Workflow Integration {#rpi-integration}
+
+tk integrates naturally with the Research-Plan-Implement workflow:
+
+### Research Phase
+- Use tk to track research topics and findings
+- Notes capture what was discovered and what questions remain
+
+### Plan Phase
+- `/plan` creates tk tickets for the decomposed work
+- Epic ticket with child tickets mirrors plan structure
+- Dependencies encode execution order
+
+### Implement Phase
+- `/implement <ticket-id>` reads the ticket for context
+- Agent follows ticket description, design, and acceptance criteria
+- Closes ticket on completion
+
+### Validate Phase
+- `/vibe` can reference ticket context
+- Validation findings linked back to ticket
+
+---
+
+## Cross-Skill Workflows
+
+### /implement + tk
+
+```bash
+# 1. Agent receives: /implement mp-a3x9
+# 2. Agent loads tk skill
+# 3. Agent reads: tk show mp-a3x9
+# 4. Agent implements based on ticket content
+# 5. Agent closes: tk close mp-a3x9
+# 6. Agent reconciles parent if applicable
+```
+
+### /plan + tk
+
+```bash
+# 1. Agent receives: /plan "Authentication system"
+# 2. Agent decomposes into tickets:
+tk create "Auth System" -t epic -p 1
+tk create "Schema migration" --parent <epic> -p 1
+tk create "Password service" --parent <epic> -p 1
+tk create "API endpoints" --parent <epic> -p 1
+# 3. Agent adds dependencies between children
+# 4. Agent verifies: tk dep cycle (no cycles)
+# 5. Agent reports plan with ticket IDs
+```
+
+### /crank + tk
+
+```bash
+# 1. /crank reads epic and its children
+# 2. Spawns agents for ready tickets (tk ready within epic)
+# 3. Each agent: implement → close → reconcile
+# 4. Loop until all children closed
+# 5. Close epic
+```
+
+---
+
+## Decision Framework
+
+### When to Use Which Tool
+
+| Scenario | Tool | Why |
+|----------|------|-----|
+| "Fix this function" (5 min) | Task tools only | Too small for a ticket |
+| "Implement auth" (multi-step, 1 session) | Both | Tasks for steps, ticket for persistence |
+| "Build search feature" (multi-session) | Both | Ticket survives between sessions |
+| "Track that we need to refactor X later" | tk only | Future work, no immediate tasks |
+| "What should I work on?" | tk | `tk ready` is the answer |
+| "What did I just finish?" | Task tools | TaskList shows recent completions |
+| "What did I finish last week?" | tk | `tk closed` or read ticket notes |
+
+### Size Heuristic
+
+```
+Will this take more than one session?
+  YES → tk ticket (mandatory)
+  NO  → Is it worth tracking for later reference?
+    YES → tk ticket
+    NO  → Task tools only
+```