trak_flow 0.1.3

data/docs/cli/task-commands.md

@@ -0,0 +1,333 @@
+# Task Commands
+
+Commands for creating and managing tasks.
+
+## Create Task
+
+Create a new task.
+
+```bash
+tf create TITLE [OPTIONS]
+```
+
+### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--description` | `-d` | Detailed description |
+| `--type` | `-t` | Task type (task, bug, feature, epic, chore) |
+| `--priority` | `-p` | Priority level (0-4) |
+| `--assignee` | `-a` | Assign to user/agent |
+| `--parent` | | Parent task ID for hierarchy |
+| `--plan` | | Create as a Plan blueprint |
+
+### Examples
+
+```bash
+# Basic task
+tf create "Fix login bug"
+
+# With type and priority
+tf create "Security vulnerability" -t bug -p 0
+
+# With description
+tf create "Add OAuth" -d "Implement OAuth 2.0 with Google and GitHub providers"
+
+# Child task
+tf create "Design login page" --parent tf-abc123
+
+# Create a Plan
+tf create "Release Checklist" --plan
+```
+
+## List Tasks
+
+List tasks with filtering options.
+
+```bash
+tf list [OPTIONS]
+```
+
+### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--status` | `-s` | Filter by status |
+| `--type` | `-t` | Filter by type |
+| `--priority` | `-p` | Filter by priority |
+| `--assignee` | `-a` | Filter by assignee |
+| `--label` | `-l` | Filter by label (repeatable) |
+| `--parent` | | Show only children of task |
+| `--no-children` | | Exclude child tasks |
+| `--json` | | Output as JSON |
+
+### Examples
+
+```bash
+# All open tasks
+tf list
+
+# By status
+tf list --status in_progress
+tf list -s blocked
+
+# By type
+tf list --type bug
+tf list -t feature
+
+# By priority
+tf list --priority 0
+tf list -p high
+
+# By label
+tf list --label frontend
+tf list -l urgent -l frontend
+
+# Combine filters
+tf list -s open -t bug -p 0
+
+# JSON output
+tf list --json
+```
+
+### Status Values
+
+- `open` - Ready to work on
+- `in_progress` - Currently being worked on
+- `blocked` - Waiting on something
+- `deferred` - Postponed
+- `closed` - Completed
+- `all` - Include all statuses
+
+## Show Task
+
+Display detailed information about a task.
+
+```bash
+tf show TASK_ID [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--tree` | Show child tasks in tree format |
+| `--deps` | Show dependencies |
+| `--json` | Output as JSON |
+
+### Examples
+
+```bash
+tf show tf-abc123
+
+tf show tf-abc123 --tree
+
+tf show tf-abc123 --deps
+```
+
+### Output
+
+```
+Task: tf-abc123
+Title: Implement user authentication
+Type: feature
+Status: in_progress
+Priority: 1 (high)
+Assignee: claude
+Created: 2024-01-15 10:00:00
+Updated: 2024-01-16 14:30:00
+
+Description:
+  Add authentication system with login, logout, and session management.
+
+Labels:
+  - backend
+  - security
+
+Dependencies:
+  Blocked by:
+    - tf-design1 (closed)
+  Blocks:
+    - tf-test1 (open)
+    - tf-docs1 (open)
+
+Notes:
+  [2024-01-16T14:30:00Z] [STARTED] Beginning implementation
+  [2024-01-15T10:00:00Z] [CREATED] Initial task creation
+```
+
+## Update Task
+
+Modify task properties.
+
+```bash
+tf update TASK_ID [OPTIONS]
+```
+
+### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--title` | | New title |
+| `--description` | `-d` | New description |
+| `--type` | `-t` | New type |
+| `--priority` | `-p` | New priority |
+| `--assignee` | `-a` | New assignee |
+| `--notes` | `-n` | Append to notes |
+
+### Examples
+
+```bash
+# Change title
+tf update tf-abc123 --title "New title"
+
+# Change priority
+tf update tf-abc123 -p 0
+
+# Add notes
+tf update tf-abc123 --notes "Waiting for design review"
+
+# Change assignee
+tf update tf-abc123 -a alice
+```
+
+## Status Commands
+
+### Start Task
+
+Mark a task as in progress.
+
+```bash
+tf start TASK_ID
+```
+
+### Block Task
+
+Mark a task as blocked.
+
+```bash
+tf block TASK_ID [--reason "reason"]
+```
+
+### Defer Task
+
+Postpone a task.
+
+```bash
+tf defer TASK_ID [--until DATE]
+```
+
+### Close Task
+
+Complete a task.
+
+```bash
+tf close TASK_ID [--summary "completion summary"]
+```
+
+### Reopen Task
+
+Reopen a closed or deferred task.
+
+```bash
+tf reopen TASK_ID
+```
+
+### Examples
+
+```bash
+# Start working
+tf start tf-abc123
+
+# Hit a blocker
+tf block tf-abc123 --reason "Waiting for API access"
+
+# Postpone
+tf defer tf-abc123 --until "next week"
+
+# Complete
+tf close tf-abc123 --summary "Implemented in PR #42"
+
+# Reopen
+tf reopen tf-abc123
+```
+
+## Find Ready Tasks
+
+Find tasks that are ready to work on (no open blockers).
+
+```bash
+tf ready [OPTIONS]
+```
+
+### Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--type` | `-t` | Filter by type |
+| `--priority` | `-p` | Filter by priority |
+| `--assignee` | `-a` | Filter by assignee |
+| `--label` | `-l` | Filter by label |
+| `--limit` | `-n` | Max results |
+
+### Examples
+
+```bash
+# All ready tasks
+tf ready
+
+# Ready bugs
+tf ready -t bug
+
+# Ready high-priority tasks
+tf ready -p 0,1
+
+# Top 5 ready tasks
+tf ready -n 5
+```
+
+## Delete Task
+
+Remove a task permanently.
+
+```bash
+tf delete TASK_ID [--force]
+```
+
+!!! warning
+    This is destructive. Use `--force` to skip confirmation.
+
+### Examples
+
+```bash
+# With confirmation
+tf delete tf-abc123
+
+# Without confirmation
+tf delete tf-abc123 --force
+```
+
+## Bulk Operations
+
+### Using Shell Loops
+
+```bash
+# Close all tasks with a label
+tf list --label sprint-42 --json | \
+  jq -r '.[].id' | \
+  xargs -I {} tf close {}
+
+# Add label to multiple tasks
+for id in tf-abc123 tf-def456 tf-ghi789; do
+  tf label add $id "urgent"
+done
+```
+
+### Using xargs
+
+```bash
+# Defer all low-priority tasks
+tf list -p 4 --json | \
+  jq -r '.[].id' | \
+  xargs -I {} tf defer {}
+```

data/docs/core-concepts/dependencies.md

@@ -0,0 +1,232 @@
+# Dependencies
+
+TrakFlow maintains a dependency graph to track relationships between tasks.
+
+## Dependency Types
+
+| Type | Description | Use Case |
+|------|-------------|----------|
+| `blocks` | Hard dependency (default) | Task A must complete before Task B |
+| `related` | Soft link | Reference between related tasks |
+| `parent-child` | Hierarchical | Subtask relationship |
+| `discovered-from` | Traceability | Track where a task originated |
+
+## Adding Dependencies
+
+### Basic Syntax
+
+```bash
+tf dep add SOURCE TARGET [--type TYPE]
+```
+
+The source task blocks/relates-to the target task.
+
+### Examples
+
+```bash
+# Design must complete before implementation
+tf dep add tf-design tf-implement
+
+# Specify dependency type
+tf dep add tf-design tf-implement --type blocks
+tf dep add tf-bug1 tf-bug2 -t related
+```
+
+## Removing Dependencies
+
+```bash
+tf dep remove SOURCE TARGET
+```
+
+## Viewing Dependencies
+
+### Dependency Tree
+
+```bash
+tf dep tree tf-implement
+```
+
+Output:
+
+```
+tf-implement
+├── blocked by:
+│   └── tf-design (open)
+└── blocks:
+    ├── tf-test (open)
+    └── tf-deploy (open)
+```
+
+### Dependency Graph
+
+Generate a visual graph:
+
+```bash
+tf admin graph
+tf admin graph --format svg --output deps.svg
+```
+
+## Ready Work Detection
+
+Find tasks with no open blockers:
+
+```bash
+tf ready
+```
+
+A task is "ready" when:
+- Status is `open`
+- All blocking dependencies are `closed`
+- Not a Plan (Plans can't be executed directly)
+
+### How It Works
+
+```mermaid
+graph LR
+    A[Design ✓] -->|blocks| B[Implement]
+    B -->|blocks| C[Test]
+    B -->|blocks| D[Docs]
+
+    style A fill:#90EE90
+    style B fill:#90EE90
+    style C fill:#FFE4B5
+    style D fill:#FFE4B5
+```
+
+In this example:
+- Design is closed (✓)
+- Implement is **ready** (no open blockers)
+- Test and Docs are NOT ready (blocked by Implement)
+
+## Common Patterns
+
+### Sequential Workflow
+
+```bash
+tf create "Step 1: Research"
+tf create "Step 2: Design"
+tf create "Step 3: Implement"
+tf create "Step 4: Test"
+
+tf dep add tf-step1 tf-step2
+tf dep add tf-step2 tf-step3
+tf dep add tf-step3 tf-step4
+```
+
+```mermaid
+graph LR
+    A[Research] --> B[Design] --> C[Implement] --> D[Test]
+```
+
+### Parallel Tasks with Sync Point
+
+```bash
+tf create "Frontend work"
+tf create "Backend work"
+tf create "Integration"
+
+tf dep add tf-frontend tf-integration
+tf dep add tf-backend tf-integration
+```
+
+```mermaid
+graph LR
+    A[Frontend] --> C[Integration]
+    B[Backend] --> C
+```
+
+### Feature with Prerequisites
+
+```bash
+tf create "Add payment support" -t feature
+tf create "Set up Stripe account"
+tf create "Get API keys"
+tf create "Implement payment flow"
+
+tf dep add tf-stripe tf-implement
+tf dep add tf-keys tf-implement
+```
+
+```mermaid
+graph LR
+    A[Stripe Account] --> C[Implement Payment]
+    B[Get API Keys] --> C
+```
+
+## Dependency Validation
+
+TrakFlow validates dependencies:
+
+| Rule | Error |
+|------|-------|
+| No self-reference | Can't add dependency to itself |
+| Tasks must exist | Both source and target must exist |
+| No cycles (optional) | Prevents circular dependencies |
+
+### Cycle Detection
+
+```bash
+# This would create a cycle: A → B → C → A
+tf dep add tf-c tf-a
+
+# Warning: Creates circular dependency
+```
+
+## Querying Dependencies
+
+### Find Blocked Tasks
+
+```bash
+tf list --status blocked
+```
+
+### Find Tasks Blocking Others
+
+```bash
+# Show what a task blocks
+tf dep tree tf-abc123
+```
+
+### Find Orphan Tasks
+
+Tasks with no dependencies:
+
+```bash
+tf admin analyze
+```
+
+## Impact on Operations
+
+### Closing Tasks
+
+When you close a task, dependent tasks may become ready:
+
+```bash
+tf close tf-design
+# tf-implement is now ready (if it was only blocked by tf-design)
+```
+
+### Reopening Tasks
+
+Reopening a task re-blocks its dependents:
+
+```bash
+tf reopen tf-design
+# tf-implement is blocked again
+```
+
+## Best Practices
+
+### Dependency Guidelines
+
+1. **Keep graphs simple** - Avoid overly complex dependency chains
+2. **Use meaningful types** - Choose the right dependency type
+3. **Document relationships** - Add notes explaining why dependencies exist
+4. **Review regularly** - Clean up stale dependencies
+
+### Avoiding Issues
+
+1. **Check for cycles** - Before adding dependencies
+2. **Don't over-connect** - Not everything needs to be linked
+3. **Use labels for grouping** - Instead of `related` dependencies
+4. **Keep chains short** - Long chains slow progress