Integrate kanban ticket system with tmux and worktree management

[thestumonkey]

Summary

This PR integrates a comprehensive kanban ticket management system directly into the Ushadow launcher, with deep integration into tmux sessions and git worktrees. The system enables context-aware development where tickets automatically manage their own tmux windows and branches, with support for shared context across related work.

What Changed

Backend (Python/FastAPI)

• New Models (ushadow/backend/src/models/kanban.py)

  • Epic: Groups related tickets with shared branches and color teams
  • Ticket: Individual work items with 1:1 tmux window mapping
  • Support for ticket statuses (backlog → done) and priorities (low → urgent)

• New API Router (ushadow/backend/src/routers/kanban.py)

  • Full CRUD operations for tickets and epics
  • Filtering by project, epic, status, tags, and assignments
  • Related ticket discovery (via epic and shared tags)
  • Board statistics endpoint

• Database Integration

  • MongoDB collections: tickets, epics
  • Indexed fields for efficient queries
  • Beanie ODM integration in main.py

Launcher Backend (Rust/Tauri)

• Tmux Integration (ushadow/launcher/src-tauri/src/commands/kanban.rs)
  • create_ticket_worktree(): Creates worktree + tmux window for new tickets
  • attach_ticket_to_worktree(): Attaches ticket to existing worktree (for epic collaboration)
  • Automatic tmux window naming: ushadow-{branch_name}
  • Support for shared branches across multiple tickets

Frontend (React/TypeScript)

• New Components (ushadow/launcher/src/components/)

  • KanbanBoard.tsx: Full kanban board with column layout
  • TicketCard.tsx: Color-coded ticket cards with epic inheritance
  • CreateTicketDialog.tsx: Modal for creating tickets
  • CreateEpicDialog.tsx: Modal for creating epics with team colors

• Navigation Integration

  • Added "Kanban" tab to launcher (Install | Infra | Environments | Kanban)
  • Full-screen kanban view with epic filtering
  • Auto-discovery of backend URL from running environments

• Environment Panel Enhancement

  • Added hover-reveal "Create Ticket" button to environment cards
  • Pre-links tickets to their originating environment
  • Seamless workflow: hover environment → click ticket icon → create linked ticket

Why These Changes

Problem Statement

• Managing multiple tickets often requires switching between branches and losing context
• No visual organization of related work (feature sets, bug batches)
• Disconnected workflow between task planning and development environment

Solution Architecture

1. Epic-Based Grouping

• Epics define shared branches and color teams
• All tickets in an epic use the same worktree/branch
• Visual consistency through color inheritance

2. Tag-Based Context Sharing

• Tickets with matching tags can discover each other
• Enables ad-hoc relationships across different epics
• Example: All api tagged tickets share context regardless of epic

3. 1:1 Ticket-Tmux Mapping

• Each ticket gets exactly one tmux window
• Simple mental model: one task, one window
• Persistent context across environment restarts

4. Shared Branch Workflow

Epic: "Authentication" (Purple)
├─ Ticket 1: "JWT validation" → uses: epic-auth branch
├─ Ticket 2: "Refresh tokens" → uses: epic-auth branch (shared\!)
└─ Ticket 3: "OAuth flow" → uses: epic-auth branch (shared\!)

All three tickets collaborate on the same code without context switching.

Implementation Details

Color Team System

Three-level color inheritance:

1. Ticket's own color (if explicitly set)
2. Epic's color (if ticket belongs to epic)
3. Generated color (hash-based from ticket ID)

Visual indicators:

• 4px left border in team color
• Epic badge with 20% opacity background
• Consistent color across all related tickets

Tmux Window Management

• Window naming: ushadow-{branch_name} or ushadow-ticket-{id}
• Session: Uses existing workmux session
• Creation flow:
  1. Check if epic has shared branch
  2. If yes → attach to existing worktree/window
  3. If no → create new worktree with create_worktree_with_workmux

API Endpoints

POST   /api/kanban/epics               - Create epic
GET    /api/kanban/epics               - List epics (filter by project)
PATCH  /api/kanban/epics/{id}          - Update epic
DELETE /api/kanban/epics/{id}          - Delete epic

POST   /api/kanban/tickets             - Create ticket
GET    /api/kanban/tickets             - List tickets (filter by project/epic/status/tags)
PATCH  /api/kanban/tickets/{id}        - Update ticket
DELETE /api/kanban/tickets/{id}        - Delete ticket
GET    /api/kanban/tickets/{id}/related - Find related tickets
GET    /api/kanban/stats               - Board statistics

Testing

Backend

# Start backend
cd ushadow/backend && uv run main.py

# Create epic
curl -X POST http://localhost:8000/api/kanban/epics \
  -H "Content-Type: application/json" \
  -d '{"title": "Test Epic", "color": "#3B82F6"}'

# Create ticket
curl -X POST http://localhost:8000/api/kanban/tickets \
  -H "Content-Type: application/json" \
  -d '{"title": "Test Ticket", "priority": "medium"}'

Frontend

cd ushadow/launcher && npm run dev
# Navigate to Kanban tab
# Create epics and tickets via UI
# Hover over environments to see "Create Ticket" button

Tmux Integration

# Create ticket via UI
# Verify tmux window created
tmux list-windows -t workmux
# Should see: ushadow-{branch-name}

Documentation

• KANBAN_INTEGRATION.md: Comprehensive architecture guide
• API endpoints reference
• Workflow examples
• Testing instructions
• Architecture diagrams

Future Enhancements

• Drag-and-drop status changes
• Ticket detail modals with comments
• Sprint planning mode
• Time tracking via tmux activity
• Auto-create ticket on /commit
• Link tickets to PRs via GitHub integration

Breaking Changes

None. The kanban system is fully additive and opt-in.

Related Issues

Addresses the need for context-aware task management integrated with the development environment.