trak_flow 0.1.3

data/docs/cli/label-commands.md

@@ -0,0 +1,222 @@
+# Label Commands
+
+Commands for managing task labels.
+
+## Add Label
+
+Add a label to a task.
+
+```bash
+tf label add TASK_ID LABEL
+```
+
+### Examples
+
+```bash
+tf label add tf-abc123 "frontend"
+tf label add tf-abc123 "urgent"
+tf label add tf-abc123 "v2.0"
+```
+
+## Remove Label
+
+Remove a label from a task.
+
+```bash
+tf label remove TASK_ID LABEL
+```
+
+### Examples
+
+```bash
+tf label remove tf-abc123 "urgent"
+```
+
+## List Labels
+
+### Labels on a Task
+
+```bash
+tf label list TASK_ID
+```
+
+#### Output
+
+```
+Labels for tf-abc123:
+  - frontend
+  - urgent
+  - v2.0
+```
+
+### All Labels in Project
+
+```bash
+tf label list-all
+```
+
+#### Output
+
+```
+All labels:
+  - backend (3 tasks)
+  - frontend (5 tasks)
+  - urgent (2 tasks)
+  - v2.0 (8 tasks)
+```
+
+## Filter by Label
+
+Use `--label` with the list command:
+
+```bash
+# Single label
+tf list --label frontend
+tf list -l urgent
+
+# Multiple labels (AND)
+tf list --label frontend --label urgent
+```
+
+Multiple labels shows tasks with ALL specified labels.
+
+## Label Naming
+
+### Conventions
+
+Labels are case-sensitive strings. Common conventions:
+
+| Category | Examples |
+|----------|----------|
+| Components | `frontend`, `backend`, `api`, `database` |
+| Priority | `urgent`, `quick-win`, `stretch-goal` |
+| Version | `v1.0`, `v2.0`, `next-release` |
+| Team | `team-a`, `team-b`, `platform` |
+| Status | `needs-review`, `blocked-external`, `ready-for-qa` |
+| Type | `tech-debt`, `documentation`, `security` |
+
+### Best Practices
+
+1. **Use lowercase** - `frontend` not `Frontend`
+2. **Use hyphens** - `needs-review` not `needs_review`
+3. **Be consistent** - Agree on conventions with your team
+4. **Keep it simple** - Fewer labels = easier to manage
+
+## Use Cases
+
+### Component Tracking
+
+```bash
+tf label add tf-abc123 "frontend"
+tf label add tf-def456 "backend"
+tf label add tf-ghi789 "api"
+
+# Find all frontend tasks
+tf list --label frontend
+```
+
+### Sprint Planning
+
+```bash
+tf label add tf-abc123 "sprint-42"
+tf label add tf-def456 "sprint-42"
+
+# Sprint backlog
+tf list --label sprint-42 --status open
+```
+
+### Release Management
+
+```bash
+tf label add tf-abc123 "v2.0"
+tf label add tf-def456 "v2.0"
+
+# What's in v2.0?
+tf list --label v2.0
+
+# What's not done for v2.0?
+tf list --label v2.0 --status open
+```
+
+### Priority Escalation
+
+```bash
+# Mark as urgent
+tf label add tf-abc123 "urgent"
+
+# Find all urgent tasks
+tf list --label urgent
+
+# De-escalate
+tf label remove tf-abc123 "urgent"
+```
+
+### Workflow States
+
+Labels can track custom workflow states:
+
+```bash
+tf label add tf-abc123 "needs-review"
+tf label add tf-abc123 "in-qa"
+tf label add tf-abc123 "approved"
+
+# Find tasks needing review
+tf list --label needs-review
+```
+
+## Bulk Operations
+
+### Add Label to Multiple Tasks
+
+```bash
+# Using shell loop
+for id in tf-abc123 tf-def456 tf-ghi789; do
+  tf label add $id "sprint-42"
+done
+```
+
+### Remove Label from All Tasks
+
+```bash
+# Find all tasks with label and remove
+tf list --label old-label --json | \
+  jq -r '.[].id' | \
+  xargs -I {} tf label remove {} "old-label"
+```
+
+### Rename a Label
+
+```bash
+# Remove old, add new
+tf list --label old-name --json | \
+  jq -r '.[].id' | \
+  while read id; do
+    tf label remove $id "old-name"
+    tf label add $id "new-name"
+  done
+```
+
+## Labels vs Other Features
+
+| Use Case | Use Labels | Use Dependencies | Use Priority |
+|----------|------------|------------------|--------------|
+| Grouping | Yes | No | No |
+| Blocking work | No | Yes | No |
+| Filtering | Yes | Limited | Yes |
+| Order/sequence | No | Yes | Yes |
+| Urgency | Maybe | No | Yes |
+| Categories | Yes | No | No |
+
+### When to Use Labels
+
+- Categorization without blocking
+- Cross-cutting concerns
+- Temporary states
+- Filtering/search
+- Organizing by component, team, or version
+
+### When NOT to Use Labels
+
+- Representing task priority (use priority field)
+- Blocking relationships (use dependencies)
+- Hierarchical organization (use parent_id)

data/docs/cli/overview.md

@@ -0,0 +1,163 @@
+# CLI Overview
+
+TrakFlow provides a powerful command-line interface (`tf`) for managing tasks, plans, workflows, and dependencies.
+
+## Basic Usage
+
+```bash
+tf COMMAND [SUBCOMMAND] [OPTIONS]
+```
+
+## Getting Help
+
+```bash
+# List all commands
+tf help
+
+# Help for a specific command
+tf help create
+tf help plan
+
+# Subcommand help
+tf plan help start
+```
+
+## Command Categories
+
+| Category | Command | Description |
+|----------|---------|-------------|
+| **Tasks** | `tf create` | Create new tasks |
+| | `tf list` | List tasks with filters |
+| | `tf show` | Show task details |
+| | `tf update` | Modify task properties |
+| | `tf start` | Begin working on a task |
+| | `tf close` | Complete a task |
+| | `tf block` | Mark task as blocked |
+| | `tf defer` | Postpone a task |
+| | `tf reopen` | Reopen a closed task |
+| **Plans** | `tf plan create` | Create a Plan blueprint |
+| | `tf plan add` | Add step to a Plan |
+| | `tf plan show` | View Plan details |
+| | `tf plan start` | Create persistent Workflow |
+| | `tf plan execute` | Create ephemeral Workflow |
+| **Workflows** | `tf workflow list` | List Workflows |
+| | `tf workflow show` | View Workflow progress |
+| | `tf workflow summarize` | Summarize and close |
+| | `tf workflow discard` | Discard ephemeral Workflow |
+| | `tf workflow gc` | Garbage collect |
+| **Dependencies** | `tf dep add` | Add dependency |
+| | `tf dep remove` | Remove dependency |
+| | `tf dep tree` | Show dependency tree |
+| | `tf ready` | Find ready tasks |
+| **Labels** | `tf label add` | Add label to task |
+| | `tf label remove` | Remove label |
+| | `tf label list` | List labels on task |
+| | `tf label list-all` | List all labels |
+| **Comments** | `tf comment add` | Add comment to task |
+| | `tf comment list` | List task comments |
+| **Admin** | `tf admin init` | Initialize TrakFlow |
+| | `tf admin export` | Export to JSONL |
+| | `tf admin import` | Import from JSONL |
+| | `tf admin graph` | Generate dependency graph |
+| | `tf admin analyze` | Analyze project |
+
+## Common Options
+
+Most commands support these options:
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output in JSON format |
+| `--quiet`, `-q` | Suppress non-essential output |
+| `--verbose`, `-v` | Show detailed output |
+| `--help`, `-h` | Show command help |
+
+## Task ID Format
+
+TrakFlow uses hash-based IDs:
+
+```
+tf-a1b2c3d4
+```
+
+You can use partial IDs if unique:
+
+```bash
+tf show tf-a1b    # Works if only one ID starts with tf-a1b
+tf show a1b       # Also works without the tf- prefix
+```
+
+## Output Formats
+
+### Default (Human-Readable)
+
+```bash
+tf list
+```
+
+```
+ID          Title                 Status       Priority
+tf-abc123   Fix login bug         in_progress  high
+tf-def456   Add OAuth support     open         medium
+tf-ghi789   Update documentation  open         low
+```
+
+### JSON Output
+
+```bash
+tf list --json
+```
+
+```json
+[
+  {"id": "tf-abc123", "title": "Fix login bug", "status": "in_progress", "priority": 1},
+  {"id": "tf-def456", "title": "Add OAuth support", "status": "open", "priority": 2}
+]
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TRAK_FLOW_DIR` | Data directory location | `.trak_flow` |
+| `TRAK_FLOW_DEBUG` | Enable debug output | `false` |
+| `TRAK_FLOW_COLOR` | Color output | `true` |
+
+## Shell Completion
+
+### Bash
+
+```bash
+# Add to ~/.bashrc
+eval "$(tf completion bash)"
+```
+
+### Zsh
+
+```bash
+# Add to ~/.zshrc
+eval "$(tf completion zsh)"
+```
+
+### Fish
+
+```bash
+# Add to ~/.config/fish/config.fish
+tf completion fish | source
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments |
+| 3 | Task not found |
+| 4 | Validation error |
+
+## Next Steps
+
+- [Task Commands](task-commands.md) - Create and manage tasks
+- [Plan Commands](plan-commands.md) - Work with Plans and Workflows
+- [Dependency Commands](dependency-commands.md) - Manage task relationships

data/docs/cli/plan-commands.md

@@ -0,0 +1,344 @@
+# Plan & Workflow Commands
+
+Commands for creating and managing Plans (blueprints) and Workflows (running instances).
+
+## Plan Commands
+
+### Create Plan
+
+Create a new Plan blueprint.
+
+```bash
+tf plan create TITLE [OPTIONS]
+```
+
+#### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--description` | `-d` | Plan description |
+
+#### Examples
+
+```bash
+tf plan create "Deploy to Production"
+
+tf plan create "Release Checklist" -d "Standard release process"
+```
+
+### Add Step to Plan
+
+Add a task definition to a Plan.
+
+```bash
+tf plan add PLAN_ID STEP_TITLE [OPTIONS]
+```
+
+#### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--description` | `-d` | Step description |
+| `--type` | `-t` | Step type |
+| `--priority` | `-p` | Step priority |
+
+#### Examples
+
+```bash
+tf plan add tf-plan1 "Run test suite"
+tf plan add tf-plan1 "Build Docker image"
+tf plan add tf-plan1 "Deploy to staging"
+tf plan add tf-plan1 "Run smoke tests"
+tf plan add tf-plan1 "Deploy to production"
+```
+
+### Show Plan
+
+Display Plan details and steps.
+
+```bash
+tf plan show PLAN_ID
+```
+
+#### Output
+
+```
+Plan: Deploy to Production [tf-plan1]
+Status: open (blueprint)
+Steps: 5
+
+  [ ] Run test suite
+  [ ] Build Docker image
+  [ ] Deploy to staging
+  [ ] Run smoke tests
+  [ ] Deploy to production
+```
+
+### List Plans
+
+List all Plan blueprints.
+
+```bash
+tf plan list [OPTIONS]
+```
+
+#### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | Output as JSON |
+
+### Convert Task to Plan
+
+Convert an existing task into a Plan.
+
+```bash
+tf plan convert TASK_ID
+```
+
+This sets `plan: true` on the task, making it a reusable blueprint.
+
+### Start Workflow (Persistent)
+
+Create a persistent Workflow from a Plan.
+
+```bash
+tf plan start PLAN_ID [OPTIONS]
+```
+
+#### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--title` | `-t` | Custom Workflow title |
+
+#### Examples
+
+```bash
+tf plan start tf-plan1
+
+tf plan start tf-plan1 --title "Deploy v1.2.0"
+```
+
+Persistent Workflows:
+- Are exported to JSONL
+- Appear in `tf workflow list`
+- Kept after completion for history
+
+### Execute Workflow (Ephemeral)
+
+Create an ephemeral Workflow from a Plan.
+
+```bash
+tf plan execute PLAN_ID [OPTIONS]
+```
+
+#### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--title` | `-t` | Custom Workflow title |
+
+#### Examples
+
+```bash
+tf plan execute tf-plan1
+
+tf plan execute tf-plan1 --title "Quick deploy"
+```
+
+Ephemeral Workflows:
+- NOT exported to JSONL
+- Auto-cleaned after completion
+- For temporary operations
+
+## Workflow Commands
+
+### List Workflows
+
+List all Workflows.
+
+```bash
+tf workflow list [OPTIONS]
+```
+
+#### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--ephemeral` | `-e` | Only ephemeral Workflows |
+| `--persistent` | `-p` | Only persistent Workflows |
+| `--status` | `-s` | Filter by status |
+| `--plan` | | Filter by source Plan |
+| `--json` | | Output as JSON |
+
+#### Examples
+
+```bash
+# All Workflows
+tf workflow list
+
+# Only ephemeral
+tf workflow list -e
+
+# Only in-progress
+tf workflow list -s in_progress
+
+# From a specific Plan
+tf workflow list --plan tf-plan1
+```
+
+### Show Workflow
+
+Display Workflow details and progress.
+
+```bash
+tf workflow show WORKFLOW_ID
+```
+
+#### Output
+
+```
+Workflow: Deploy v1.2.0 [tf-wf1]
+Source Plan: tf-plan1
+Type: Persistent
+Status: in_progress
+
+  [x] Run test suite
+  [x] Build Docker image
+  [~] Deploy to staging
+  [ ] Run smoke tests
+  [ ] Deploy to production
+
+Progress: 2/5 completed
+```
+
+Legend:
+- `[x]` - Completed
+- `[~]` - In progress
+- `[ ]` - Open
+- `[!]` - Blocked
+
+### Summarize Workflow
+
+Add a summary and close a Workflow.
+
+```bash
+tf workflow summarize WORKFLOW_ID --summary "SUMMARY"
+```
+
+#### Examples
+
+```bash
+tf workflow summarize tf-wf1 --summary "Deployed v1.2.0 successfully"
+
+tf workflow summarize tf-wf1 -s "Failed: staging smoke tests"
+```
+
+This:
+1. Adds the summary to Workflow notes
+2. Closes the Workflow
+3. Records completion timestamp
+
+### Discard Workflow
+
+Delete an ephemeral Workflow.
+
+```bash
+tf workflow discard WORKFLOW_ID
+```
+
+!!! note
+    Only ephemeral Workflows can be discarded.
+
+### Garbage Collect
+
+Clean up old ephemeral Workflows.
+
+```bash
+tf workflow gc [OPTIONS]
+```
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--older-than` | Age threshold (default: 7d) |
+| `--dry-run` | Show what would be deleted |
+
+#### Examples
+
+```bash
+# Default cleanup
+tf workflow gc
+
+# Clean Workflows older than 24 hours
+tf workflow gc --older-than 24h
+
+# Preview without deleting
+tf workflow gc --dry-run
+```
+
+## Example: Complete Workflow
+
+### 1. Create a Plan
+
+```bash
+tf plan create "Code Review Process"
+tf plan add tf-plan1 "Check code style"
+tf plan add tf-plan1 "Review logic"
+tf plan add tf-plan1 "Check test coverage"
+tf plan add tf-plan1 "Security review"
+tf plan add tf-plan1 "Approve or request changes"
+```
+
+### 2. Start a Workflow
+
+```bash
+tf plan start tf-plan1 --title "Review PR #42"
+```
+
+### 3. Work Through Tasks
+
+```bash
+# Start first task
+tf start tf-task1
+tf close tf-task1
+
+# Continue with remaining tasks
+tf start tf-task2
+tf close tf-task2
+
+# ... etc
+```
+
+### 4. Complete the Workflow
+
+```bash
+tf workflow summarize tf-wf1 --summary "Approved with minor suggestions"
+```
+
+## Use Case: Release Process
+
+```bash
+# Create the Plan once
+tf plan create "Release Process"
+tf plan add tf-release "Update version in package.json"
+tf plan add tf-release "Update CHANGELOG.md"
+tf plan add tf-release "Run full test suite"
+tf plan add tf-release "Build release artifacts"
+tf plan add tf-release "Create GitHub release"
+tf plan add tf-release "Deploy to production"
+tf plan add tf-release "Announce on social media"
+
+# For each release, start a Workflow
+tf plan start tf-release --title "Release v2.0.0"
+
+# Work through the checklist
+tf start tf-task1
+tf close tf-task1
+# ...
+
+# Summarize when done
+tf workflow summarize tf-wf1 --summary "Released v2.0.0"
+```