trak_flow 0.1.3

data/docs/core-concepts/tasks.md

@@ -0,0 +1,205 @@
+# Tasks
+
+Tasks are the fundamental unit in TrakFlow. This page covers task properties and behavior in detail.
+
+## Task Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `id` | string | Auto | Unique identifier (e.g., `tf-abc123`) |
+| `title` | string | Yes | Short description of the task |
+| `description` | string | No | Detailed description |
+| `status` | string | No | Current status (default: `open`) |
+| `priority` | integer | No | Priority level 0-4 (default: `2`) |
+| `type` | string | No | Task type (default: `task`) |
+| `assignee` | string | No | Assigned user/agent |
+| `parent_id` | string | No | Parent task for hierarchy |
+| `created_at` | datetime | Auto | Creation timestamp |
+| `updated_at` | datetime | Auto | Last update timestamp |
+| `closed_at` | datetime | Auto | When task was closed |
+| `notes` | string | No | Free-form notes and trace log |
+
+### Plan/Workflow Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `plan` | boolean | True if this is a Plan blueprint |
+| `source_plan_id` | string | ID of Plan this Workflow was created from |
+| `ephemeral` | boolean | True if this is a one-shot workflow |
+
+## Task Types
+
+| Type | Description | Use Case |
+|------|-------------|----------|
+| `task` | General task | Default for most work items |
+| `bug` | Bug fix | Defect tracking |
+| `feature` | New feature | Feature development |
+| `epic` | Large initiative | Container for related tasks |
+| `chore` | Maintenance | Technical debt, cleanup |
+
+### Creating Different Types
+
+```bash
+tf create "Fix null pointer exception" -t bug
+tf create "Add OAuth support" -t feature
+tf create "User Management" -t epic
+tf create "Update dependencies" -t chore
+```
+
+## Priority Levels
+
+| Level | Name | Color | Description |
+|-------|------|-------|-------------|
+| 0 | Critical | Red Bold | Urgent, drop everything |
+| 1 | High | Red | Important, do soon |
+| 2 | Medium | Yellow | Normal priority (default) |
+| 3 | Low | Blue | Do when time permits |
+| 4 | Backlog | Gray | Future consideration |
+
+### Setting Priority
+
+```bash
+tf create "Security vulnerability" -p 0
+tf create "Nice to have feature" -p 4
+tf update tf-abc123 --priority 1
+```
+
+## Task Statuses
+
+### Status Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> open
+    open --> in_progress: tf start
+    open --> blocked: tf block
+    open --> deferred: tf defer
+    in_progress --> closed: tf close
+    in_progress --> blocked: tf block
+    blocked --> open: tf unblock
+    blocked --> in_progress: tf start
+    deferred --> open: tf reopen
+    closed --> open: tf reopen
+    closed --> tombstone: tf admin archive
+```
+
+### Status Commands
+
+```bash
+tf start tf-abc123      # open → in_progress
+tf block tf-abc123      # → blocked
+tf defer tf-abc123      # → deferred
+tf close tf-abc123      # → closed
+tf reopen tf-abc123     # → open
+```
+
+## Hierarchical Tasks
+
+Tasks can have parent-child relationships for organization.
+
+### Creating Child Tasks
+
+```bash
+# Create parent
+tf create "User Authentication" -t epic
+
+# Create children
+tf create "Login page" --parent tf-auth1
+tf create "Logout functionality" --parent tf-auth1
+tf create "Password reset" --parent tf-auth1
+```
+
+### Viewing Hierarchy
+
+```bash
+tf show tf-auth1 --tree
+```
+
+Output:
+
+```
+[tf-auth1] User Authentication (epic)
+├── [tf-login] Login page (task)
+├── [tf-logout] Logout functionality (task)
+└── [tf-reset] Password reset (task)
+```
+
+## Content Hash
+
+Each task has a `content_hash` that:
+
+1. **Detects changes** - Know when content was modified
+2. **Enables deduplication** - Identify identical tasks
+3. **Supports sync** - Merge changes from multiple sources
+
+The hash is computed from all properties except `updated_at` and `content_hash` itself.
+
+## Notes and Trace Log
+
+The `notes` field stores free-form text and automatic trace entries:
+
+```bash
+tf update tf-abc123 --notes "Waiting for design review"
+```
+
+Automatic trace entries are added for state changes:
+
+```
+[2024-01-15T10:30:00Z] [CLOSED] Implemented in PR #42
+[2024-01-14T09:00:00Z] [STARTED] Beginning implementation
+[2024-01-13T14:00:00Z] [CREATED] Initial task creation
+```
+
+## Validation Rules
+
+Tasks are validated on creation and update:
+
+| Rule | Error |
+|------|-------|
+| Title required | "Title is required" |
+| Valid status | "Invalid status: {status}" |
+| Valid priority | "Invalid priority: {priority}" |
+| Valid type | "Invalid type: {type}" |
+| Plans can't be ephemeral | "Plans cannot be ephemeral" |
+| Plans stay open | "Plans cannot change status" |
+| Plans can't derive from Plans | "Plans cannot be derived from other Plans" |
+
+## JSON Representation
+
+```json
+{
+  "id": "tf-abc123",
+  "title": "Implement feature X",
+  "description": "Detailed description here",
+  "status": "in_progress",
+  "priority": 1,
+  "type": "feature",
+  "assignee": "claude",
+  "parent_id": null,
+  "created_at": "2024-01-15T10:00:00Z",
+  "updated_at": "2024-01-15T14:30:00Z",
+  "closed_at": null,
+  "content_hash": "a1b2c3d4",
+  "plan": false,
+  "source_plan_id": null,
+  "ephemeral": false,
+  "notes": ""
+}
+```
+
+## Task Predicates
+
+In Ruby code, tasks expose these predicate methods:
+
+```ruby
+task.open?        # status == "open"
+task.closed?      # status == "closed" or "tombstone"
+task.in_progress? # status == "in_progress"
+task.blocked?     # status == "blocked"
+task.epic?        # type == "epic"
+task.plan?        # plan == true
+task.workflow?    # source_plan_id present and not a plan
+task.ephemeral?   # ephemeral == true
+task.executable?  # not a plan (can be executed)
+task.discardable? # ephemeral (can be discarded)
+```

data/docs/getting-started/configuration.md

@@ -0,0 +1,120 @@
+# Configuration
+
+TrakFlow stores configuration in `.trak_flow/config.json`.
+
+## View Current Configuration
+
+```bash
+tf config list
+```
+
+## Get a Value
+
+```bash
+tf config get actor
+```
+
+## Set a Value
+
+```bash
+tf config set actor "username"
+```
+
+## Configuration Options
+
+### General Settings
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `actor` | string | `""` | Current user/agent identifier |
+| `stealth` | boolean | `false` | Suppress status messages |
+| `no_push` | boolean | `false` | Disable auto-push to git |
+
+### Import Settings
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `import.orphan_handling` | string | `"allow"` | How to handle orphaned parent references |
+
+### Validation Settings
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `validation.strict` | boolean | `false` | Enable strict validation |
+
+### ID Generation Settings
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `id_generator.min_hash_length` | integer | `8` | Minimum length for generated IDs |
+
+### MCP Server Settings
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `mcp.port` | integer | `3333` | Default HTTP port for MCP server |
+
+## Example Configuration
+
+```json
+{
+  "actor": "claude-agent",
+  "stealth": false,
+  "no_push": true,
+  "import": {
+    "orphan_handling": "allow"
+  },
+  "validation": {
+    "strict": true
+  },
+  "id_generator": {
+    "min_hash_length": 8
+  },
+  "mcp": {
+    "port": 3333
+  }
+}
+```
+
+## Nested Configuration
+
+Access nested values with dot notation:
+
+```bash
+# Get nested value
+tf config get import.orphan_handling
+
+# Set nested value
+tf config set mcp.port 4000
+```
+
+## Environment Variables
+
+Some settings can be overridden via environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `TRAK_FLOW_ACTOR` | Override the actor setting |
+| `TRAK_FLOW_STEALTH` | Set to "1" for stealth mode |
+
+## Reset to Defaults
+
+Delete the config file to reset:
+
+```bash
+rm .trak_flow/config.json
+tf init  # Recreates with defaults
+```
+
+## Git Integration
+
+The configuration file is git-tracked by default, allowing team members to share settings. The SQLite database is gitignored.
+
+### Recommended .gitignore
+
+```gitignore
+.trak_flow/trak_flow.db
+.trak_flow/trak_flow.db-*
+```
+
+This is created automatically by `tf init`.

data/docs/getting-started/installation.md

@@ -0,0 +1,79 @@
+# Installation
+
+## Requirements
+
+- Ruby 3.2 or later
+- Git (for version-controlled persistence)
+
+## Install from RubyGems
+
+```bash
+gem install trak_flow
+```
+
+## Add to Your Gemfile
+
+```ruby
+gem 'trak_flow'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Install from Source
+
+```bash
+git clone https://github.com/MadBomber/trak_flow.git
+cd trak_flow
+bundle install
+bundle exec rake install
+```
+
+## Verify Installation
+
+```bash
+tf --version
+```
+
+You should see:
+
+```
+TrakFlow version 0.0.1
+```
+
+## Initialize a Project
+
+Navigate to your project directory and run:
+
+```bash
+tf init
+```
+
+This creates a `.trak_flow/` directory with:
+
+- `issues.jsonl` - Git-tracked task storage
+- `trak_flow.db` - SQLite cache (gitignored)
+- `config.json` - Project configuration
+- `.gitignore` - Ignores the database file
+
+## Dependencies
+
+TrakFlow depends on these gems (installed automatically):
+
+| Gem | Purpose |
+|-----|---------|
+| `thor` | CLI framework |
+| `sqlite3` | Local database |
+| `oj` | Fast JSON parsing |
+| `pastel` | Terminal colors |
+| `tty-table` | Table formatting |
+| `fast_mcp` | MCP server support |
+| `puma` | HTTP server for MCP |
+
+## Next Steps
+
+- [Quick Start](quick-start.md) - Create your first tasks
+- [Configuration](configuration.md) - Customize TrakFlow settings

data/docs/getting-started/quick-start.md

@@ -0,0 +1,245 @@
+# Quick Start
+
+This guide walks you through basic TrakFlow usage.
+
+## Initialize Your Project
+
+```bash
+cd your-project
+tf init
+```
+
+## Create Tasks
+
+### Basic Task
+
+```bash
+tf create "Update documentation"
+```
+
+### Task with Options
+
+```bash
+tf create "Implement OAuth login" \
+  --type feature \
+  --priority 1 \
+  --description "Add Google and GitHub OAuth providers"
+```
+
+### Shorthand Flags
+
+```bash
+tf create "Fix memory leak" -t bug -p 0 -d "Memory grows unbounded in worker"
+```
+
+## View Tasks
+
+### List All Open Tasks
+
+```bash
+tf list
+```
+
+### Filter by Status
+
+```bash
+tf list --status in_progress
+tf list -s blocked
+```
+
+### Filter by Type
+
+```bash
+tf list --type bug
+tf list -T feature
+```
+
+### Show Task Details
+
+```bash
+tf show tf-abc123
+```
+
+## Update Tasks
+
+### Start Working
+
+```bash
+tf start tf-abc123
+```
+
+### Mark as Blocked
+
+```bash
+tf block tf-abc123
+```
+
+### Close a Task
+
+```bash
+tf close tf-abc123 --reason "Implemented in PR #42"
+```
+
+## Work with Dependencies
+
+### Add a Dependency
+
+```bash
+# Task A blocks Task B (B cannot start until A is done)
+tf dep add tf-taskA tf-taskB
+```
+
+### View Dependencies
+
+```bash
+tf dep tree tf-abc123
+```
+
+### Find Ready Work
+
+```bash
+tf ready
+```
+
+This shows tasks with no open blockers.
+
+## Create a Plan (Workflow Blueprint)
+
+Plans are reusable templates for common workflows.
+
+### Create a Plan
+
+```bash
+tf plan create "Release Checklist"
+```
+
+### Add Steps
+
+```bash
+tf plan add tf-plan1 "Run test suite"
+tf plan add tf-plan1 "Update changelog"
+tf plan add tf-plan1 "Bump version"
+tf plan add tf-plan1 "Create release tag"
+tf plan add tf-plan1 "Deploy to production"
+```
+
+### View Plan
+
+```bash
+tf plan show tf-plan1
+```
+
+## Execute a Workflow
+
+### Persistent Workflow
+
+Creates a workflow that persists in history:
+
+```bash
+tf plan start tf-plan1
+```
+
+### Ephemeral Workflow
+
+Creates a one-shot workflow (auto-cleaned):
+
+```bash
+tf plan execute tf-plan1
+```
+
+### Monitor Workflow
+
+```bash
+tf workflow show tf-wf1
+```
+
+### Complete Workflow
+
+```bash
+tf workflow summarize tf-wf1 --summary "Released v1.2.0 successfully"
+```
+
+## Use Labels
+
+### Add Labels
+
+```bash
+tf label add tf-abc123 "frontend"
+tf label add tf-abc123 "urgent"
+```
+
+### Filter by Label
+
+```bash
+tf list --label frontend
+```
+
+### Remove Labels
+
+```bash
+tf label remove tf-abc123 "urgent"
+```
+
+## JSON Output
+
+All commands support JSON output for scripting:
+
+```bash
+tf list --json
+tf show tf-abc123 -j
+tf ready -j
+```
+
+## Common Workflows
+
+### Bug Triage
+
+```bash
+# Create bug
+tf create "App crashes on startup" -t bug -p 0
+
+# Start investigating
+tf start tf-abc123
+
+# Mark blocked if waiting on info
+tf block tf-abc123
+
+# Close when fixed
+tf close tf-abc123 -r "Fixed null pointer in init"
+```
+
+### Feature Development
+
+```bash
+# Create feature
+tf create "Add dark mode" -t feature -p 2
+
+# Create subtasks
+tf create "Design dark theme colors" --parent tf-feature1
+tf create "Implement CSS variables" --parent tf-feature1
+tf create "Add theme toggle" --parent tf-feature1
+
+# Track dependencies
+tf dep add tf-design tf-implement
+tf dep add tf-implement tf-toggle
+```
+
+### Sprint Planning
+
+```bash
+# Create Plan for sprint workflow
+tf plan create "Sprint Workflow"
+tf plan add tf-plan1 "Sprint planning meeting"
+tf plan add tf-plan1 "Daily standups"
+tf plan add tf-plan1 "Sprint review"
+tf plan add tf-plan1 "Retrospective"
+
+# Start each sprint
+tf plan start tf-plan1
+```
+
+## Next Steps
+
+- [Configuration](configuration.md) - Customize settings
+- [Core Concepts](../core-concepts/overview.md) - Understand the data model
+- [CLI Reference](../cli/overview.md) - Complete command reference