From 9cabab8a1ebfd7923a391b483a2be4d6efcf3e98 Mon Sep 17 00:00:00 2001 From: Bruno Bornsztein Date: Fri, 16 Jan 2026 12:21:40 -0600 Subject: [PATCH] feat: add demo database and video walkthrough script Add tooling for creating screencast demos of TaskYou: - cmd/demoseed: Go tool to create a demo database with realistic sample data including projects, tasks in various states, and project memories - docs/VIDEO_WALKTHROUGH.md: Complete video script with narration, timing, and technical tips for recording - Makefile targets: `make demo-seed` and `make demo` for easy setup The demo database uses the existing WORKTREE_DB_PATH environment variable, allowing the app to run with sample data without exposing real task lists. Co-Authored-By: Claude Opus 4.5 --- Makefile | 8 + cmd/demoseed/main.go | 385 ++++++++++++++++++++++++++++++++++++++ docs/VIDEO_WALKTHROUGH.md | 265 ++++++++++++++++++++++++++ 3 files changed, 658 insertions(+) create mode 100644 cmd/demoseed/main.go create mode 100644 docs/VIDEO_WALKTHROUGH.md diff --git a/Makefile b/Makefile index 38ffa53..50e51e7 100644 --- a/Makefile +++ b/Makefile @@ -98,4 +98,12 @@ fmt: lint: golangci-lint run +# Demo database setup for screencasts +demo-seed: + go run ./cmd/demoseed + +# Run with demo database +demo: demo-seed + WORKTREE_DB_PATH=~/.local/share/task/demo.db ./bin/task -l + .DEFAULT_GOAL := build diff --git a/cmd/demoseed/main.go b/cmd/demoseed/main.go new file mode 100644 index 0000000..f4811e7 --- /dev/null +++ b/cmd/demoseed/main.go @@ -0,0 +1,385 @@ +// demoseed creates a demo database with sample data for screencasts. +// Usage: go run ./cmd/demoseed [output.db] +// Default output: ~/.local/share/task/demo.db +package main + +import ( + "fmt" + "os" + "path/filepath" + "time" + + "github.com/bborn/workflow/internal/db" +) + +func main() { + // Determine output path + var dbPath string + if len(os.Args) > 1 { + dbPath = os.Args[1] + } else { + home, _ := os.UserHomeDir() + dbPath = filepath.Join(home, ".local", "share", "task", "demo.db") + } + + // Remove existing demo database if it exists + if _, err := os.Stat(dbPath); err == nil { + if err := os.Remove(dbPath); err != nil { + fmt.Fprintf(os.Stderr, "Error removing existing db: %v\n", err) + os.Exit(1) + } + } + + // Open/create the database + database, err := db.Open(dbPath) + if err != nil { + fmt.Fprintf(os.Stderr, "Error opening database: %v\n", err) + os.Exit(1) + } + defer database.Close() + + fmt.Printf("Creating demo database at: %s\n", dbPath) + + // Create sample projects + projects := []struct { + Name string + Path string + Instructions string + Color string + }{ + { + Name: "acme-webapp", + Path: "/tmp/demo/acme-webapp", + Instructions: "This is the main Acme Corp web application. Built with React + TypeScript frontend and Go backend. Follow the existing patterns for API endpoints and use the shared component library.", + Color: "#61AFEF", + }, + { + Name: "mobile-app", + Path: "/tmp/demo/mobile-app", + Instructions: "React Native mobile app for iOS and Android. Uses Expo for development. Test changes on both platforms before submitting.", + Color: "#98C379", + }, + { + Name: "infra", + Path: "/tmp/demo/infra", + Instructions: "Infrastructure-as-code repository using Terraform and Kubernetes. Always run `terraform plan` before applying changes. Use staging environment for testing.", + Color: "#E5C07B", + }, + { + Name: "personal", + Path: "/tmp/demo/personal", + Instructions: "Personal tasks and notes.", + Color: "#C678DD", + }, + } + + for _, p := range projects { + // Create dummy project directory + os.MkdirAll(p.Path, 0755) + + _, err := database.Exec(` + INSERT OR REPLACE INTO projects (name, path, instructions, color) + VALUES (?, ?, ?, ?) + `, p.Name, p.Path, p.Instructions, p.Color) + if err != nil { + fmt.Fprintf(os.Stderr, "Error creating project %s: %v\n", p.Name, err) + os.Exit(1) + } + fmt.Printf(" Created project: %s\n", p.Name) + } + + // Create sample tasks with realistic scenarios + now := time.Now() + tasks := []struct { + Title string + Body string + Status string + Type string + Project string + CreatedAt time.Time + StartedAt *time.Time + CompletedAt *time.Time + Tags string + }{ + // Done tasks + { + Title: "Add dark mode toggle to settings page", + Body: "Users have requested a dark mode option. Add a toggle in the settings page that persists the preference to localStorage and applies the appropriate CSS variables.", + Status: db.StatusDone, + Type: db.TypeCode, + Project: "acme-webapp", + CreatedAt: now.Add(-72 * time.Hour), + StartedAt: ptr(now.Add(-70 * time.Hour)), + CompletedAt: ptr(now.Add(-68 * time.Hour)), + Tags: "ui,feature,settings", + }, + { + Title: "Fix login redirect loop on Safari", + Body: "Users on Safari are experiencing an infinite redirect loop after login. Investigate the cookie handling and fix the issue.", + Status: db.StatusDone, + Type: db.TypeCode, + Project: "acme-webapp", + CreatedAt: now.Add(-48 * time.Hour), + StartedAt: ptr(now.Add(-47 * time.Hour)), + CompletedAt: ptr(now.Add(-46 * time.Hour)), + Tags: "bug,auth,safari", + }, + { + Title: "Write Q4 product roadmap", + Body: "Create the product roadmap document for Q4 2024. Include: feature priorities, timeline estimates, and resource allocation. Reference the customer feedback survey results.", + Status: db.StatusDone, + Type: db.TypeWriting, + Project: "personal", + CreatedAt: now.Add(-96 * time.Hour), + StartedAt: ptr(now.Add(-94 * time.Hour)), + CompletedAt: ptr(now.Add(-90 * time.Hour)), + Tags: "planning,roadmap", + }, + + // Processing task + { + Title: "Implement user activity dashboard", + Body: "Create a new dashboard showing user activity metrics including:\n- Daily/weekly/monthly active users\n- Feature usage statistics\n- User retention charts\n\nUse the existing analytics API and create new React components in the dashboard module.", + Status: db.StatusProcessing, + Type: db.TypeCode, + Project: "acme-webapp", + CreatedAt: now.Add(-2 * time.Hour), + StartedAt: ptr(now.Add(-1 * time.Hour)), + Tags: "feature,dashboard,analytics", + }, + + // Blocked task + { + Title: "Upgrade Kubernetes cluster to 1.28", + Body: "Upgrade the production Kubernetes cluster from 1.26 to 1.28. Review breaking changes and update any deprecated APIs. Coordinate with the team for maintenance window.", + Status: db.StatusBlocked, + Type: db.TypeCode, + Project: "infra", + CreatedAt: now.Add(-24 * time.Hour), + StartedAt: ptr(now.Add(-20 * time.Hour)), + Tags: "kubernetes,upgrade,infrastructure", + }, + + // Queued tasks + { + Title: "Add push notification support", + Body: "Implement push notifications for the mobile app using Firebase Cloud Messaging. Support both iOS and Android. Allow users to configure notification preferences.", + Status: db.StatusQueued, + Type: db.TypeCode, + Project: "mobile-app", + CreatedAt: now.Add(-6 * time.Hour), + Tags: "feature,notifications,mobile", + }, + + // Backlog tasks + { + Title: "Refactor authentication middleware", + Body: "The current auth middleware is becoming complex. Refactor it to use a cleaner pattern with proper separation of concerns. Consider using middleware chains.", + Status: db.StatusBacklog, + Type: db.TypeCode, + Project: "acme-webapp", + CreatedAt: now.Add(-120 * time.Hour), + Tags: "refactor,auth,technical-debt", + }, + { + Title: "Add E2E tests for checkout flow", + Body: "Create comprehensive end-to-end tests for the entire checkout flow including cart, payment, and order confirmation. Use Playwright for browser automation.", + Status: db.StatusBacklog, + Type: db.TypeCode, + Project: "acme-webapp", + CreatedAt: now.Add(-96 * time.Hour), + Tags: "testing,e2e,checkout", + }, + { + Title: "Design API rate limiting strategy", + Body: "We need to implement rate limiting for our public API. Research best practices and propose a strategy considering:\n- Rate limits per endpoint\n- User tier-based limits\n- Response headers\n- Error handling", + Status: db.StatusBacklog, + Type: db.TypeThinking, + Project: "acme-webapp", + CreatedAt: now.Add(-72 * time.Hour), + Tags: "api,security,architecture", + }, + { + Title: "Investigate slow search performance", + Body: "Users are reporting slow search results (>3s response time). Profile the search API and database queries. Identify optimization opportunities.", + Status: db.StatusBacklog, + Type: db.TypeCode, + Project: "acme-webapp", + CreatedAt: now.Add(-48 * time.Hour), + Tags: "performance,search,investigation", + }, + { + Title: "Create onboarding tutorial for mobile app", + Body: "Design and implement an onboarding flow for new users. Include feature highlights, permission requests, and account setup.", + Status: db.StatusBacklog, + Type: db.TypeCode, + Project: "mobile-app", + CreatedAt: now.Add(-24 * time.Hour), + Tags: "onboarding,ux,mobile", + }, + { + Title: "Set up automated database backups", + Body: "Configure automated daily backups for production databases. Store backups in S3 with 30-day retention. Include backup verification.", + Status: db.StatusBacklog, + Type: db.TypeCode, + Project: "infra", + CreatedAt: now.Add(-168 * time.Hour), + Tags: "backup,database,automation", + }, + } + + for _, t := range tasks { + var startedAt, completedAt interface{} + if t.StartedAt != nil { + startedAt = *t.StartedAt + } + if t.CompletedAt != nil { + completedAt = *t.CompletedAt + } + + _, err := database.Exec(` + INSERT INTO tasks (title, body, status, type, project, created_at, started_at, completed_at, tags) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) + `, t.Title, t.Body, t.Status, t.Type, t.Project, t.CreatedAt, startedAt, completedAt, t.Tags) + if err != nil { + fmt.Fprintf(os.Stderr, "Error creating task %s: %v\n", t.Title, err) + os.Exit(1) + } + fmt.Printf(" Created task: [%s] %s\n", t.Status, truncate(t.Title, 50)) + } + + // Create sample memories + memories := []struct { + Project string + Category string + Content string + }{ + // acme-webapp memories + { + Project: "acme-webapp", + Category: db.MemoryCategoryPattern, + Content: "Use React Query for all data fetching. Mutations should invalidate relevant queries.", + }, + { + Project: "acme-webapp", + Category: db.MemoryCategoryPattern, + Content: "API endpoints follow RESTful conventions with versioning (e.g., /api/v1/users).", + }, + { + Project: "acme-webapp", + Category: db.MemoryCategoryContext, + Content: "The app uses Tailwind CSS for styling. Custom colors are defined in tailwind.config.js.", + }, + { + Project: "acme-webapp", + Category: db.MemoryCategoryDecision, + Content: "Chose Zustand over Redux for state management due to simpler boilerplate and better TypeScript support.", + }, + { + Project: "acme-webapp", + Category: db.MemoryCategoryGotcha, + Content: "The authentication token refresh happens silently - don't store tokens in localStorage, use httpOnly cookies.", + }, + { + Project: "acme-webapp", + Category: db.MemoryCategoryGotcha, + Content: "Safari has stricter cookie policies. Always test auth flows in Safari before deploying.", + }, + + // mobile-app memories + { + Project: "mobile-app", + Category: db.MemoryCategoryPattern, + Content: "Use expo-router for navigation. All screens are in the app/ directory following file-based routing.", + }, + { + Project: "mobile-app", + Category: db.MemoryCategoryContext, + Content: "The app targets iOS 14+ and Android 10+. Use platform-specific code sparingly.", + }, + { + Project: "mobile-app", + Category: db.MemoryCategoryDecision, + Content: "Using react-native-reanimated for animations instead of Animated API for better performance.", + }, + + // infra memories + { + Project: "infra", + Category: db.MemoryCategoryPattern, + Content: "All Terraform changes must go through PR review. Use terraform plan output in PR descriptions.", + }, + { + Project: "infra", + Category: db.MemoryCategoryGotcha, + Content: "The staging cluster uses a smaller node pool. Don't copy production HPA settings directly.", + }, + { + Project: "infra", + Category: db.MemoryCategoryContext, + Content: "AWS us-east-1 is primary region, us-west-2 is DR. All critical services are multi-region.", + }, + } + + for _, m := range memories { + _, err := database.Exec(` + INSERT INTO project_memories (project, category, content) + VALUES (?, ?, ?) + `, m.Project, m.Category, m.Content) + if err != nil { + fmt.Fprintf(os.Stderr, "Error creating memory: %v\n", err) + os.Exit(1) + } + } + fmt.Printf(" Created %d project memories\n", len(memories)) + + // Add some sample task logs for the processing task + _, err = database.Exec(` + INSERT INTO task_logs (task_id, line_type, content) + SELECT id, 'system', 'Starting task execution...' + FROM tasks WHERE status = 'processing' LIMIT 1 + `) + if err != nil { + fmt.Fprintf(os.Stderr, "Warning: Could not create sample logs: %v\n", err) + } + + _, err = database.Exec(` + INSERT INTO task_logs (task_id, line_type, content) + SELECT id, 'tool', 'Read: src/components/Dashboard.tsx' + FROM tasks WHERE status = 'processing' LIMIT 1 + `) + if err != nil { + fmt.Fprintf(os.Stderr, "Warning: Could not create sample logs: %v\n", err) + } + + _, err = database.Exec(` + INSERT INTO task_logs (task_id, line_type, content) + SELECT id, 'output', 'Analyzing existing dashboard structure...' + FROM tasks WHERE status = 'processing' LIMIT 1 + `) + if err != nil { + fmt.Fprintf(os.Stderr, "Warning: Could not create sample logs: %v\n", err) + } + + fmt.Printf(" Created sample task logs\n") + + fmt.Println() + fmt.Println("Demo database created successfully!") + fmt.Println() + fmt.Println("To use the demo database, run:") + fmt.Printf(" WORKTREE_DB_PATH=%s ./bin/task -l\n", dbPath) + fmt.Println() + fmt.Println("Or add to your shell session:") + fmt.Printf(" export WORKTREE_DB_PATH=%s\n", dbPath) +} + +func ptr(t time.Time) *time.Time { + return &t +} + +func truncate(s string, max int) string { + if len(s) <= max { + return s + } + return s[:max-3] + "..." +} diff --git a/docs/VIDEO_WALKTHROUGH.md b/docs/VIDEO_WALKTHROUGH.md new file mode 100644 index 0000000..350a865 --- /dev/null +++ b/docs/VIDEO_WALKTHROUGH.md @@ -0,0 +1,265 @@ +# TaskYou Video Walkthrough Script + +This document provides a complete script and walkthrough for creating a screencast demo of TaskYou. + +## Pre-Recording Setup + +### 1. Create Demo Database + +```bash +# Build the project first +make build + +# Create a fresh demo database with sample data +make demo-seed +``` + +This creates `~/.local/share/task/demo.db` with: +- 4 sample projects (acme-webapp, mobile-app, infra, personal) +- 12 sample tasks in various states (backlog, queued, processing, blocked, done) +- Project memories demonstrating the learning feature +- Sample task logs + +### 2. Terminal Setup + +- Use a clean terminal with good contrast (dark theme recommended) +- Set terminal to ~120 columns x 40 rows for good visibility +- Font size: 14-16pt for readability in video +- Consider using a simple prompt like `$` or hide it entirely + +### 3. Start Recording + +```bash +# Launch TaskYou with demo database +WORKTREE_DB_PATH=~/.local/share/task/demo.db ./bin/task -l + +# Or use the shortcut: +make demo +``` + +--- + +## Video Script + +### Opening (~15 seconds) + +**[Show terminal with TaskYou logo/title if you have one, or just start with launch]** + +> "TaskYou is a terminal-based task queue that lets Claude Code work on your tasks autonomously. Let me show you how it works." + +--- + +### Scene 1: The Kanban Board (~30 seconds) + +**[Launch the app - it opens in tmux with the Kanban board visible]** + +> "When you open TaskYou, you see a Kanban-style board. Tasks flow from Backlog, through In Progress, and either get Blocked waiting for input, or end up Done." + +**[Use arrow keys to navigate between columns]** + +> "I can navigate between columns with the arrow keys. Each task shows its project, type, and when it was created." + +**[Highlight the different colored project labels]** + +> "Notice the color-coded project labels - this makes it easy to see what you're working on at a glance." + +--- + +### Scene 2: Task Detail View (~45 seconds) + +**[Press Enter on a task to open the detail view]** + +> "Press Enter to see the full details of a task." + +**[Show a task with a detailed body]** + +> "Here I can see the complete task description, any tags for categorization, and the task history." + +**[Navigate to a completed task with PR info if available]** + +> "For completed tasks, I can see the Pull Request that was created. TaskYou automatically submits PRs when code tasks are done." + +**[Press Escape to go back]** + +--- + +### Scene 3: Creating a New Task (~45 seconds) + +**[Press 'n' to open the new task form]** + +> "To create a new task, I press 'n'. The form lets me specify everything Claude needs." + +**[Fill in the form as you talk]** + +> "I'll add a title... select my project from the dropdown... choose 'Code' as the task type since this is a development task..." + +**[Type in the body field]** + +> "In the body, I describe what I want done. The more detail I provide, the better Claude understands the task." + +**[Show the tags field]** + +> "I can add tags for organization and searching." + +**[Navigate to Save with Tab, or press Ctrl+S]** + +> "When I'm ready, I save the task and it goes into the Backlog." + +--- + +### Scene 4: Starting a Task (~30 seconds) + +**[Navigate to a backlog task]** + +> "To start working on a task, I select it and press 's' to start. This queues it for execution." + +**[The task moves to "In Progress" column]** + +> "The task moves to In Progress, and the background executor picks it up. Claude Code begins working in its own git worktree, completely isolated." + +--- + +### Scene 5: Watching Claude Work (~60 seconds) + +**[Press 'w' to watch the Claude session, or show the split pane]** + +> "The magic of TaskYou is watching Claude work. Press 'w' and I can see exactly what Claude is doing in real-time." + +**[Show the tmux split pane with Claude's output]** + +> "Claude reads files, makes edits, runs tests - all the things you'd do yourself, but automated." + +**[Point out the status changes]** + +> "Watch the status - when Claude needs my input, the task moves to Blocked and I get a notification." + +**[Press 'q' to exit the watch view]** + +--- + +### Scene 6: Handling Blocked Tasks (~30 seconds) + +**[Navigate to a Blocked task]** + +> "Sometimes Claude needs clarification or a decision. These tasks show up in the Blocked column." + +**[Press Enter to see the task, then 'r' to reply]** + +> "I can see what Claude is asking, type my response, and the task continues. It's like having a conversation with my AI assistant." + +--- + +### Scene 7: Project Memories (~45 seconds) + +**[Press 'm' to open the memories view]** + +> "One of TaskYou's best features is Project Memories. Press 'm' to see them." + +**[Show the memories list]** + +> "Claude learns about your project as it works. It remembers coding patterns, architectural decisions, gotchas to avoid." + +**[Navigate through different categories]** + +> "Memories are categorized - patterns for coding conventions, context for project background, decisions for architectural choices, and gotchas for things to watch out for." + +> "Every future task gets this context automatically. Claude gets smarter about your project over time." + +--- + +### Scene 8: Search and Filter (~20 seconds) + +**[Press '/' to open search]** + +> "With lots of tasks, search helps me find what I need. Press slash and type to filter." + +**[Type a search term]** + +> "I can search by title, tags, or project name." + +--- + +### Scene 9: Settings and Configuration (~20 seconds) + +**[Press 'S' (shift+s) to open settings]** + +> "In settings, I can configure projects, customize task types, and set up the workflow for my needs." + +**[Show the projects list briefly]** + +> "Each project points to a git repository and can have specific instructions for how Claude should work with it." + +--- + +### Closing (~15 seconds) + +**[Return to the Kanban board with tasks in various states]** + +> "That's TaskYou - a terminal task queue that lets you delegate work to Claude Code. Create tasks, let Claude work, review the results, and ship." + +> "Check out the GitHub repo for installation instructions and more documentation." + +**[End on the Kanban board]** + +--- + +## Key Moments to Capture + +1. **The "aha" moment**: Watching Claude actively working in real-time +2. **Seamless flow**: Task going from Backlog → Processing → Done +3. **Interaction**: Replying to a blocked task and seeing it continue +4. **Intelligence**: Showing project memories that make Claude smarter + +## Keyboard Shortcuts Reference + +| Key | Action | +|-----|--------| +| `n` | New task | +| `Enter` | View task details | +| `s` | Start/queue task | +| `w` | Watch Claude session | +| `r` | Reply to blocked task | +| `m` | View memories | +| `/` | Search | +| `S` | Settings | +| `?` | Help | +| `q` | Quit / Close | +| Arrow keys | Navigate | + +## Technical Tips for Recording + +1. **Use demo database**: Always use `WORKTREE_DB_PATH` to keep your real tasks private +2. **Reset between takes**: Run `make demo-seed` to reset to a fresh state +3. **Pause the executor**: If you want to prevent tasks from actually running during recording, don't start the daemon +4. **Window size**: The TUI looks best at 120+ columns width +5. **Recording software**: OBS Studio or similar with terminal capture works well +6. **Audio**: Record voiceover separately for cleaner editing + +## Sample Narration Timing + +| Scene | Duration | Cumulative | +|-------|----------|------------| +| Opening | 15s | 0:15 | +| Kanban Board | 30s | 0:45 | +| Task Detail | 45s | 1:30 | +| Creating Task | 45s | 2:15 | +| Starting Task | 30s | 2:45 | +| Watching Claude | 60s | 3:45 | +| Blocked Tasks | 30s | 4:15 | +| Memories | 45s | 5:00 | +| Search | 20s | 5:20 | +| Settings | 20s | 5:40 | +| Closing | 15s | 5:55 | + +**Total runtime: ~6 minutes** + +--- + +## Alternative Short Version (2 minutes) + +For a quick demo, focus on: +1. Opening + Kanban overview (20s) +2. Creating a task (30s) +3. Watching Claude work (45s) +4. Showing memories (20s) +5. Closing (10s)