trak_flow 0.1.3

data/docs/core-concepts/labels.md

@@ -0,0 +1,217 @@
+# Labels
+
+Labels provide flexible categorization for tasks.
+
+## Adding Labels
+
+```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"
+```
+
+## Removing Labels
+
+```bash
+tf label remove TASK_ID LABEL
+```
+
+### Examples
+
+```bash
+tf label remove tf-abc123 "urgent"
+```
+
+## Viewing 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)
+```
+
+## Filtering by Label
+
+```bash
+tf list --label frontend
+tf list -l urgent
+```
+
+### Multiple Labels
+
+```bash
+tf list --label frontend --label urgent
+```
+
+This shows tasks with BOTH 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
+```
+
+## Labels vs Dependencies
+
+| Use | Labels | Dependencies |
+|-----|--------|--------------|
+| Grouping | Yes | No |
+| Blocking work | No | Yes |
+| Filtering | Yes | Limited |
+| Order/sequence | No | Yes |
+| Multiple per task | Yes | Yes |
+
+### When to Use Labels
+
+- Categorization without blocking
+- Cross-cutting concerns
+- Temporary states
+- Filtering/search
+
+### When to Use Dependencies
+
+- Task A must complete before Task B
+- Sequential workflows
+- Blocking relationships
+
+## JSON Representation
+
+Labels are stored as a separate entity with task associations:
+
+```json
+{
+  "id": "lbl-123",
+  "task_id": "tf-abc123",
+  "name": "frontend",
+  "created_at": "2024-01-15T10:00:00Z"
+}
+```
+
+## 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"
+```

data/docs/core-concepts/overview.md

@@ -0,0 +1,178 @@
+# Core Concepts Overview
+
+TrakFlow is built around a few key concepts that work together to provide flexible task management.
+
+## The Task Model
+
+Everything in TrakFlow is a **Task**. Tasks serve multiple roles depending on their flags:
+
+```mermaid
+graph TD
+    A[Task] --> B{plan?}
+    B -->|true| C[Plan Blueprint]
+    B -->|false| D{source_plan_id?}
+    D -->|set| E[Workflow Instance]
+    D -->|not set| F[Regular Task]
+
+    C --> G[Contains Steps]
+    E --> H[Contains Work Items]
+    F --> I[Standalone Task]
+```
+
+| Role | Identification | Description |
+|------|----------------|-------------|
+| **Task** | Default | A unit of work to be completed |
+| **Plan** | `task.plan? == true` | A reusable workflow blueprint |
+| **Step** | Child of a Plan | A task definition within a Plan |
+| **Workflow** | `task.source_plan_id` set | A running instance of a Plan |
+| **Work Item** | Child of a Workflow | A task within a running Workflow |
+
+## Task Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> open: Create
+    open --> in_progress: Start
+    open --> blocked: Block
+    open --> deferred: Defer
+    in_progress --> blocked: Block
+    in_progress --> closed: Close
+    blocked --> open: Unblock
+    blocked --> in_progress: Unblock & Start
+    deferred --> open: Reopen
+    closed --> open: Reopen
+    closed --> tombstone: Archive
+    tombstone --> [*]
+```
+
+### Statuses
+
+| Status | Description |
+|--------|-------------|
+| `open` | Ready to work on |
+| `in_progress` | Currently being worked on |
+| `blocked` | Waiting on something |
+| `deferred` | Postponed for later |
+| `closed` | Completed |
+| `tombstone` | Archived (permanent) |
+| `pinned` | Highlighted for visibility |
+
+## Dependency Graph
+
+Tasks can depend on other tasks. TrakFlow maintains a dependency graph to:
+
+1. **Track blockers** - Know what's preventing work
+2. **Find ready work** - Identify tasks with no open blockers
+3. **Visualize relationships** - Understand task connections
+
+```mermaid
+graph LR
+    A[Design API] -->|blocks| B[Implement API]
+    B -->|blocks| C[Write Tests]
+    B -->|blocks| D[Update Docs]
+    C -->|blocks| E[Deploy]
+    D -->|blocks| E
+```
+
+### Dependency Types
+
+| Type | Description |
+|------|-------------|
+| `blocks` | Hard dependency (default) |
+| `related` | Soft link for reference |
+| `parent-child` | Hierarchical relationship |
+| `discovered-from` | Traceability link |
+
+## Plans and Workflows
+
+Plans are reusable workflow templates. When executed, they create Workflows.
+
+```mermaid
+graph TB
+    subgraph Plan [Plan: Deploy Checklist]
+        P1[Run Tests]
+        P2[Build Artifacts]
+        P3[Deploy Staging]
+        P4[Deploy Production]
+    end
+
+    subgraph Workflow [Workflow: Deploy v1.2]
+        W1[Run Tests ✓]
+        W2[Build Artifacts ✓]
+        W3[Deploy Staging ~]
+        W4[Deploy Production]
+    end
+
+    Plan -->|start| Workflow
+```
+
+### Workflow Types
+
+| Type | Created By | Lifecycle | JSONL Export |
+|------|------------|-----------|--------------|
+| **Persistent** | `tf plan start` | Kept forever | Yes |
+| **Ephemeral** | `tf plan execute` | Auto-cleaned | No |
+
+## Labels
+
+Labels provide flexible categorization:
+
+```bash
+tf label add tf-abc123 "frontend"
+tf label add tf-abc123 "urgent"
+tf label add tf-abc123 "v2.0"
+```
+
+Labels can represent:
+- **Components**: `frontend`, `backend`, `api`
+- **Priority markers**: `urgent`, `quick-win`
+- **Versions**: `v1.0`, `v2.0`
+- **States**: `needs-review`, `blocked-external`
+
+## Data Storage
+
+TrakFlow uses a dual-storage approach:
+
+```
+.trak_flow/
+├── issues.jsonl    # Source of truth (git-tracked)
+├── trak_flow.db    # Fast cache (gitignored)
+└── config.json     # Settings (git-tracked)
+```
+
+### JSONL Format
+
+Human-readable, one task per line:
+
+```json
+{"id":"tf-abc123","title":"Fix bug","status":"open","priority":1}
+{"id":"tf-def456","title":"Add feature","status":"in_progress","priority":2}
+```
+
+### SQLite Cache
+
+Provides:
+- **Fast queries** - Millisecond response times
+- **Indexing** - By status, priority, labels
+- **Full-text search** - Search task content
+
+The cache is rebuilt automatically from JSONL on each session.
+
+## Hash-Based IDs
+
+TrakFlow generates IDs using content hashes:
+
+```
+tf-a1b2c3d4
+```
+
+Benefits:
+- **No collisions** - Multiple agents can create tasks simultaneously
+- **Merge-friendly** - Git merges work without conflicts
+- **Deterministic** - Same content = same ID (for deduplication)
+
+## Next Steps
+
+- [Tasks](tasks.md) - Deep dive into task properties
+- [Plans & Workflows](plans-workflows.md) - Workflow automation
+- [Dependencies](dependencies.md) - Managing task relationships

data/docs/core-concepts/plans-workflows.md

@@ -0,0 +1,264 @@
+# Plans & Workflows
+
+Plans and Workflows enable reusable, automated task sequences.
+
+## Concept Overview
+
+```mermaid
+graph TB
+    subgraph Definition
+        Plan[Plan Blueprint]
+        Step1[Step 1]
+        Step2[Step 2]
+        Step3[Step 3]
+        Plan --> Step1
+        Plan --> Step2
+        Plan --> Step3
+    end
+
+    subgraph Execution
+        Plan -->|start| PW[Persistent Workflow]
+        Plan -->|execute| EW[Ephemeral Workflow]
+        PW --> T1[Task 1]
+        PW --> T2[Task 2]
+        PW --> T3[Task 3]
+    end
+```
+
+| Concept | Description |
+|---------|-------------|
+| **Plan** | A reusable template defining a sequence of tasks |
+| **Step** | A task definition within a Plan |
+| **Workflow** | A running instance created from a Plan |
+| **Work Item** | A task within a Workflow |
+
+## Creating Plans
+
+### Create an Empty Plan
+
+```bash
+tf plan create "Deploy to Production"
+```
+
+### Add Steps
+
+```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"
+```
+
+### View Plan
+
+```bash
+tf plan show tf-plan1
+```
+
+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
+```
+
+### Convert Existing Task to Plan
+
+```bash
+tf plan convert tf-existing-task
+```
+
+## Executing Workflows
+
+### Persistent Workflow
+
+Creates a workflow that is kept in history:
+
+```bash
+tf plan start tf-plan1
+```
+
+- Exported to JSONL
+- Appears in `tf workflow list`
+- Kept after completion
+
+### Ephemeral Workflow
+
+Creates a one-shot workflow:
+
+```bash
+tf plan execute tf-plan1
+```
+
+- NOT exported to JSONL
+- Auto-cleaned after completion
+- Use for temporary operations
+
+## Managing Workflows
+
+### List Workflows
+
+```bash
+# All workflows
+tf workflow list
+
+# Only ephemeral
+tf workflow list --ephemeral
+tf workflow list -e
+```
+
+### View Workflow
+
+```bash
+tf workflow show tf-wf1
+```
+
+Output:
+
+```
+Workflow: Deploy to Production [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
+```
+
+### Work on Tasks
+
+```bash
+# Start a task
+tf start tf-task1
+
+# Complete a task
+tf close tf-task1
+```
+
+### Summarize and Close
+
+When all tasks are done:
+
+```bash
+tf workflow summarize tf-wf1 --summary "Deployed v1.2.0 successfully"
+```
+
+This:
+1. Adds the summary to workflow notes
+2. Closes the workflow
+3. Records completion timestamp
+
+### Discard Ephemeral Workflow
+
+```bash
+tf workflow discard tf-wf1
+```
+
+Only ephemeral workflows can be discarded.
+
+## Garbage Collection
+
+Clean up old ephemeral workflows:
+
+```bash
+tf workflow gc
+```
+
+This removes ephemeral workflows that are:
+- Closed
+- Older than the retention period
+
+## Plan vs Workflow Properties
+
+| Property | Plan | Workflow |
+|----------|------|----------|
+| `plan` | `true` | `false` |
+| `source_plan_id` | `null` | Set to Plan ID |
+| `ephemeral` | Always `false` | `true` or `false` |
+| `status` | Always `open` | Can change |
+| Contains | Steps (templates) | Work items (tasks) |
+| JSONL export | Yes | Persistent only |
+
+## Use Cases
+
+### Release Checklist
+
+```bash
+tf plan create "Release Checklist"
+tf plan add tf-plan1 "Update version number"
+tf plan add tf-plan1 "Update CHANGELOG"
+tf plan add tf-plan1 "Run full test suite"
+tf plan add tf-plan1 "Create release branch"
+tf plan add tf-plan1 "Build release artifacts"
+tf plan add tf-plan1 "Deploy to staging"
+tf plan add tf-plan1 "QA verification"
+tf plan add tf-plan1 "Deploy to production"
+tf plan add tf-plan1 "Create GitHub release"
+tf plan add tf-plan1 "Announce release"
+```
+
+### Code Review Process
+
+```bash
+tf plan create "Code Review"
+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 "Performance review"
+tf plan add tf-plan1 "Approve or request changes"
+```
+
+### Onboarding Workflow
+
+```bash
+tf plan create "New Team Member Onboarding"
+tf plan add tf-plan1 "Create accounts"
+tf plan add tf-plan1 "Grant repository access"
+tf plan add tf-plan1 "Add to Slack channels"
+tf plan add tf-plan1 "Schedule intro meetings"
+tf plan add tf-plan1 "Assign onboarding buddy"
+tf plan add tf-plan1 "First task assignment"
+```
+
+## Best Practices
+
+### Plan Design
+
+1. **Keep steps atomic** - Each step should be completable independently
+2. **Use clear names** - Steps should be self-explanatory
+3. **Order logically** - Steps should follow a natural sequence
+4. **Consider dependencies** - Add explicit dependencies if needed
+
+### Workflow Execution
+
+1. **Use persistent for auditing** - When you need a record
+2. **Use ephemeral for routine** - For repeatable, disposable operations
+3. **Summarize on completion** - Document what happened
+4. **Clean up regularly** - Run `tf workflow gc` periodically
+
+### Error Handling
+
+```bash
+# If a step fails, mark it blocked
+tf block tf-step3
+
+# Add notes about the issue
+tf update tf-step3 --notes "Staging deployment failed, investigating"
+
+# Once resolved, restart
+tf start tf-step3
+```