trak_flow 0.1.3

data/docs/index.md

@@ -0,0 +1,169 @@
+# TrakFlow
+
+<div class="grid" markdown>
+
+<div markdown>
+
+![TrakFlow](assets/trak_flow.jpg){ width="100%" }
+
+</div>
+
+<div markdown>
+
+**A distributed task tracking system for Robots with a DAG-based workflow engine.**
+
+TrakFlow helps Robots (what some might call AI agents) manage complex, multi-step work pipelines without losing track of what they need to do.
+
+| | |
+|---|---|
+| :material-git: Git-Backed | :material-database: SQLite Cache |
+| :material-identifier: Hash-Based IDs | :material-graph: Dependency Graph |
+| :material-robot: MCP Server | :material-workflow: Plans & Workflows |
+
+</div>
+
+</div>
+
+<p align="center" markdown>
+[:material-download: Install](getting-started/installation.md){ .md-button .md-button--primary }
+[:material-rocket-launch: Quick Start](getting-started/quick-start.md){ .md-button }
+</p>
+
+---
+
+## Features
+
+### Git-Backed Persistence
+
+Tasks are stored as human-readable JSONL files that live alongside your code. No external database server required. Every change is versioned through Git, giving you full history, branching, and collaboration capabilities. Roll back mistakes, review task history in PRs, and keep your project management data where it belongs—in your repository.
+
+### Hash-Based IDs
+
+TrakFlow generates unique task IDs using content hashing, eliminating merge conflicts when multiple AI agents or team members create tasks simultaneously. No central ID server needed. IDs are deterministic and portable, making it safe to work offline and sync later without coordination overhead.
+
+### SQLite Cache
+
+While JSONL provides persistence, a local SQLite database delivers blazing-fast queries with millisecond response times. Full-text search, indexed lookups by status, priority, labels, and dependencies—all optimized for the rapid-fire queries that AI agents generate. The cache rebuilds automatically from JSONL on each session.
+
+### Dependency Graph
+
+Model complex task relationships with a directed acyclic graph (DAG). Define blocking dependencies, related tasks, and parent-child hierarchies. TrakFlow automatically detects cycles, identifies tasks ready for work (no open blockers), and visualizes your workflow as a graph. Perfect for multi-step pipelines where order matters.
+
+### MCP Server
+
+Expose your task data to AI agents through the Model Context Protocol (MCP) standard. Compatible with Claude Desktop, VS Code extensions, and any MCP-enabled application. Supports both STDIO transport for local development and HTTP/SSE for remote access. Agents can create, query, and update tasks programmatically.
+
+### Plans & Workflows
+
+Define reusable workflow blueprints (Plans) and instantiate them as running Workflows. Perfect for repeatable processes like deployments, code reviews, or onboarding checklists. Choose persistent Workflows for audit trails or ephemeral Workflows for temporary operations that auto-clean after completion.
+
+## Quick Example
+
+```bash
+# Initialize TrakFlow in your project
+tf init
+
+# Create a task
+tf create "Implement user authentication" -t feature -p 1
+
+# Create a Plan (workflow blueprint)
+tf plan create "Deploy to Production"
+
+# Add steps to the Plan
+tf plan add tf-abc123 "Run tests"
+tf plan add tf-abc123 "Build artifacts"
+tf plan add tf-abc123 "Deploy"
+
+# Execute the Plan as a Workflow
+tf plan start tf-abc123
+
+# Find tasks ready for work
+tf ready
+```
+
+## Three Ways to Use TrakFlow
+
+### 1. CLI Tool
+
+Use `tf` commands to manage tasks from the terminal:
+
+```bash
+tf create "Fix login bug" -t bug -p 1
+tf list --status open
+tf close tf-abc123
+```
+
+### 2. Ruby Library
+
+Integrate TrakFlow directly into your Ruby applications:
+
+```ruby
+require 'trak_flow'
+
+TrakFlow.ensure_initialized!
+db = TrakFlow::Storage::Database.new
+db.connect
+
+task = TrakFlow::Models::Task.new(
+  title: "Automated task",
+  type: "task",
+  priority: 2
+)
+db.insert_task(task)
+```
+
+### 3. MCP Server
+
+Expose TrakFlow to AI agents via the Model Context Protocol:
+
+```bash
+# Start the MCP server (STDIO transport)
+tf_mcp
+
+# Or HTTP transport
+tf_mcp --http --port 3333
+```
+
+## Architecture Overview
+
+```
+.trak_flow/
+├── trak_flow.db   # SQLite database (gitignored)
+├── issues.jsonl   # Git-tracked source of truth
+├── config.json    # Project configuration
+└── .gitignore
+```
+
+TrakFlow uses a three-layer architecture:
+
+1. **CLI/MCP Interface** - User and agent-facing commands
+2. **SQLite Database** - Fast local queries and indexing
+3. **JSONL Format** - Git-tracked persistence for collaboration
+
+## Getting Started
+
+<div class="grid cards" markdown>
+
+-   :material-download:{ .lg .middle } **[Installation](getting-started/installation.md)**
+
+    ---
+
+    Install TrakFlow via RubyGems or from source
+
+-   :material-rocket-launch:{ .lg .middle } **[Quick Start](getting-started/quick-start.md)**
+
+    ---
+
+    Get up and running in minutes
+
+-   :material-cog:{ .lg .middle } **[Configuration](getting-started/configuration.md)**
+
+    ---
+
+    Customize TrakFlow for your project
+
+</div>
+
+## License
+
+TrakFlow is released under the MIT License.

data/docs/mcp/integration.md

@@ -0,0 +1,302 @@
+# MCP Integration Guide
+
+This guide covers integrating TrakFlow's MCP server with various AI applications and development tools.
+
+## Claude Desktop
+
+### Configuration
+
+Add TrakFlow to your Claude Desktop configuration file:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "trak_flow": {
+      "command": "tf",
+      "args": ["mcp", "start"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+### Usage
+
+Once configured, Claude can:
+
+- View your tasks: "What tasks are currently open?"
+- Create tasks: "Create a task to fix the login bug"
+- Update status: "Mark task tf-abc123 as in progress"
+- Find work: "What should I work on next?"
+
+## VS Code / Cursor
+
+### With MCP Extension
+
+If using an MCP-enabled extension:
+
+```json
+{
+  "mcp.servers": {
+    "trak_flow": {
+      "command": "tf",
+      "args": ["mcp", "start"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}
+```
+
+### With Continue.dev
+
+Add to your `.continue/config.json`:
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "trak_flow",
+      "command": "tf",
+      "args": ["mcp", "start"]
+    }
+  ]
+}
+```
+
+## Ruby Applications
+
+### Using ruby_llm-mcp
+
+```ruby
+require 'ruby_llm'
+require 'ruby_llm/mcp'
+
+# Connect via STDIO
+client = RubyLLM::MCP::Client.new(
+  transport_type: :stdio,
+  command: ["tf", "mcp", "start"],
+  working_dir: "/path/to/project"
+)
+
+# List available tools
+client.tools.each do |tool|
+  puts "#{tool.name}: #{tool.description}"
+end
+
+# Create a task
+create_tool = client.tool("task_create")
+result = create_tool.execute(
+  title: "Implement feature",
+  type: "feature",
+  priority: 1
+)
+
+puts "Created task: #{result['task']['id']}"
+
+# Get ready tasks
+ready_tool = client.tool("ready_tasks")
+ready = ready_tool.execute
+puts "Ready to work on: #{ready['tasks'].map { |t| t['title'] }}"
+```
+
+### Using HTTP Transport
+
+```ruby
+require 'ruby_llm/mcp'
+
+# Connect via HTTP/SSE
+client = RubyLLM::MCP::Client.new(
+  transport_type: :sse,
+  url: "http://localhost:9292/sse"
+)
+
+# Same API as STDIO
+tools = client.tools
+resources = client.resources
+```
+
+## Python Applications
+
+### Using mcp Package
+
+```python
+import asyncio
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+async def main():
+    server_params = StdioServerParameters(
+        command="tf",
+        args=["mcp", "start"],
+        cwd="/path/to/project"
+    )
+
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            # Initialize
+            await session.initialize()
+
+            # List tools
+            tools = await session.list_tools()
+            for tool in tools.tools:
+                print(f"{tool.name}: {tool.description}")
+
+            # Create a task
+            result = await session.call_tool(
+                "task_create",
+                {"title": "Task from Python", "priority": 1}
+            )
+            print(result)
+
+asyncio.run(main())
+```
+
+## JavaScript/TypeScript
+
+### Using @modelcontextprotocol/sdk
+
+```typescript
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const transport = new StdioClientTransport({
+  command: 'tf',
+  args: ['mcp', 'start'],
+  cwd: '/path/to/project'
+});
+
+const client = new Client({
+  name: 'my-app',
+  version: '1.0.0'
+}, {
+  capabilities: {}
+});
+
+await client.connect(transport);
+
+// List tools
+const { tools } = await client.listTools();
+console.log('Available tools:', tools.map(t => t.name));
+
+// Create a task
+const result = await client.callTool('task_create', {
+  title: 'Task from JavaScript',
+  type: 'feature'
+});
+console.log('Created:', result);
+```
+
+## HTTP API (Direct)
+
+For applications that can't use MCP directly, start the HTTP server:
+
+```bash
+tf mcp start --http --port 9292
+```
+
+### Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/sse` | GET | SSE connection for MCP messages |
+| `/messages` | POST | Send MCP request |
+
+### Example with curl
+
+```bash
+# Initialize session (returns session ID in SSE stream)
+curl -N http://localhost:9292/sse &
+
+# Send a tool call
+curl -X POST http://localhost:9292/messages \
+  -H "Content-Type: application/json" \
+  -d '{
+    "method": "tools/call",
+    "params": {
+      "name": "task_list",
+      "arguments": {"status": "open"}
+    }
+  }'
+```
+
+## Custom Integration
+
+### Starting the Server Programmatically
+
+```ruby
+require 'trak_flow/mcp'
+
+# Create server with custom configuration
+server = TrakFlow::Mcp::Server.new(
+  db_path: "/custom/path/trak_flow.db",
+  jsonl_path: "/custom/path/issues.jsonl"
+)
+
+# STDIO mode
+server.run
+
+# Or HTTP mode
+server.run_http(
+  port: 9292,
+  host: "0.0.0.0"
+)
+```
+
+### Adding Custom Tools
+
+```ruby
+require 'trak_flow/mcp'
+
+server = TrakFlow::Mcp::Server.new
+
+# Add a custom tool
+server.add_tool(
+  name: "my_custom_tool",
+  description: "Does something custom",
+  parameters: {
+    param1: { type: "string", required: true }
+  }
+) do |params|
+  # Tool implementation
+  { result: "Custom result for #{params[:param1]}" }
+end
+
+server.run
+```
+
+## Best Practices
+
+### Performance
+
+1. **Reuse connections** - Don't create new clients for each request
+2. **Use STDIO for local** - Lower overhead than HTTP
+3. **Cache resource data** - Resources are snapshots, cache appropriately
+
+### Error Handling
+
+```ruby
+begin
+  result = tool.execute(title: "New task")
+rescue RubyLLM::MCP::ToolError => e
+  puts "Tool error: #{e.message}"
+rescue RubyLLM::MCP::ConnectionError => e
+  puts "Connection lost: #{e.message}"
+end
+```
+
+### Concurrency
+
+The MCP server handles concurrent requests, but consider:
+
+1. **SQLite limitations** - Write operations are serialized
+2. **JSONL sync** - Writes are atomic but sequential
+3. **Long operations** - Consider timeouts for complex queries
+
+### Security
+
+1. **Local only by default** - HTTP binds to 127.0.0.1
+2. **No auth built-in** - Add authentication at network layer
+3. **Read project data only** - Server can't access arbitrary files

data/docs/mcp/overview.md

@@ -0,0 +1,206 @@
+# MCP Server Overview
+
+TrakFlow includes a Model Context Protocol (MCP) server that allows AI agents and LLM-powered applications to interact with your task data.
+
+## What is MCP?
+
+The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI applications to external data sources and tools. TrakFlow's MCP server exposes:
+
+- **Tools** - Actions agents can perform (create, update, list tasks)
+- **Resources** - Data agents can read (task lists, dependencies)
+
+## Quick Start
+
+### STDIO Transport (Recommended for Local Use)
+
+```ruby
+require 'trak_flow'
+require 'trak_flow/mcp'
+
+# Start the MCP server over STDIO
+TrakFlow::Mcp::Server.new.run
+```
+
+### HTTP/SSE Transport (For Remote Access)
+
+```ruby
+require 'trak_flow'
+require 'trak_flow/mcp'
+
+# Start with HTTP/SSE transport
+server = TrakFlow::Mcp::Server.new
+server.run_http(port: 9292)
+```
+
+## Architecture
+
+```mermaid
+graph LR
+    subgraph "AI Application"
+        LLM[LLM]
+        Client[MCP Client]
+    end
+
+    subgraph "TrakFlow MCP Server"
+        Server[FastMcp Server]
+        Tools[Tools]
+        Resources[Resources]
+    end
+
+    subgraph "TrakFlow Core"
+        DB[(SQLite)]
+        JSONL[issues.jsonl]
+    end
+
+    LLM <--> Client
+    Client <-->|STDIO or HTTP/SSE| Server
+    Server --> Tools
+    Server --> Resources
+    Tools --> DB
+    Resources --> DB
+    DB --> JSONL
+```
+
+## Transport Options
+
+### STDIO Transport
+
+Best for:
+- Local development
+- IDE integrations (VS Code, Cursor)
+- Single-user setups
+- Command-line tools
+
+Communication happens through standard input/output streams.
+
+### HTTP/SSE Transport
+
+Best for:
+- Remote access
+- Multi-client scenarios
+- Web applications
+- API integrations
+
+Uses HTTP for requests and Server-Sent Events (SSE) for real-time updates.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `task_create` | Create a new task |
+| `task_list` | List tasks with filters |
+| `task_show` | Get task details |
+| `task_update` | Modify a task |
+| `task_start` | Begin working on a task |
+| `task_close` | Complete a task |
+| `task_block` | Mark as blocked |
+| `task_reopen` | Reopen a closed task |
+| `plan_create` | Create a Plan blueprint |
+| `plan_start` | Start a Workflow |
+| `dep_add` | Add dependency |
+| `dep_remove` | Remove dependency |
+| `label_add` | Add label to task |
+| `label_remove` | Remove label |
+
+## Available Resources
+
+| Resource | URI | Description |
+|----------|-----|-------------|
+| Task List | `trak_flow://tasks` | All tasks |
+| Ready Tasks | `trak_flow://ready` | Tasks with no blockers |
+| Dependencies | `trak_flow://dependencies` | Dependency graph |
+| Plans | `trak_flow://plans` | Plan blueprints |
+| Labels | `trak_flow://labels` | All labels |
+
+## Integration Examples
+
+### With Claude Desktop
+
+Add to your Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "trak_flow": {
+      "command": "tf",
+      "args": ["mcp", "start"],
+      "cwd": "/path/to/your/project"
+    }
+  }
+}
+```
+
+### With VS Code
+
+If using an MCP-enabled VS Code extension:
+
+```json
+{
+  "mcp.servers": {
+    "trak_flow": {
+      "command": "tf",
+      "args": ["mcp", "start"]
+    }
+  }
+}
+```
+
+### With Ruby LLM
+
+```ruby
+require 'ruby_llm'
+require 'ruby_llm/mcp'
+
+# Connect to TrakFlow MCP server
+client = RubyLLM::MCP::Client.new(
+  transport_type: :stdio,
+  command: ["tf", "mcp", "start"],
+  working_dir: "/path/to/project"
+)
+
+# Use tools
+create_tool = client.tool("task_create")
+result = create_tool.execute(
+  title: "New task from AI",
+  priority: 1
+)
+```
+
+## Security Considerations
+
+### File System Access
+
+The MCP server only accesses:
+- `.trak_flow/` directory in the working directory
+- SQLite database file
+- JSONL data file
+
+### Authentication
+
+Currently, the MCP server does not implement authentication. For production use:
+
+1. Run behind a reverse proxy with authentication
+2. Use network-level access controls
+3. Consider implementing custom middleware
+
+### Data Privacy
+
+- Task data stays local
+- No external API calls
+- No telemetry or analytics
+
+## Configuration
+
+Environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TRAK_FLOW_DIR` | Data directory | `.trak_flow` |
+| `TRAK_FLOW_MCP_PORT` | HTTP port | `9292` |
+| `TRAK_FLOW_MCP_HOST` | HTTP host | `127.0.0.1` |
+
+## Next Steps
+
+- [Tools Reference](tools.md) - Detailed tool documentation
+- [Resources Reference](resources.md) - Available resources
+- [Integration Guide](integration.md) - Integration examples