brain-dump-workflow

Brain Dump Workflow

Core Concepts

• MCP Server: Structured ticket operations via tools
• Local-first: No cloud dependencies
• Agent Integration: Ralph/Ticket Worker use MCP tools
• Ticket States: Backlog → Ready → In Progress → Review → Done

Essential MCP Tools

# Project Management
find_project_by_path()    # Identify current project
list_projects()           # Show all projects

# Ticket Operations
list_tickets()            # Show tickets with status
create_ticket()           # Create new ticket
update_ticket_status()    # Change ticket state
add_ticket_comment()       # Add comments/updates

# Workflow Tools
start_ticket_work(ticketId)     # Create branch + set in_progress
complete_ticket_work()         # Mark done + update PRD

Agent Patterns

Ralph (Autonomous)

# Trigger: Run Ralph without specific ticket
1. Read plans/prd.json for incomplete tickets
2. Check plans/progress.txt for context
3. Select optimal ticket by priority/dependencies
4. Call start_ticket_work() to begin
5. Implement, test, commit
6. Call complete_ticket_work() to finish

Ticket Worker (Interactive)

# Trigger: @ticket-worker or select ticket
1. Use list_tickets() to show options
2. User selects ticket to work on
3. Call start_ticket_work(ticketId)
4. Implement with user guidance
5. Update progress with add_ticket_comment()

Quick Reference

Ticket Structure

## Title (action-oriented)

## Description (what + why)

## Acceptance Criteria

- [ ] Specific, testable requirement
- [ ] Integration point

Workflow Commands

# Start work
@ticket-worker    # Interactive mode
@ralph            # Autonomous mode
@planner "feature"  # Plan and create tickets

# During development
add_ticket_comment(ticketId, "progress", "claude", "progress")
add_ticket_comment(ticketId, "decision", "claude", "decision")

# Complete work
complete_ticket_work(ticketId, "summary of changes")
update_ticket_status(ticketId, "done")

Best Practices

1. Clear tickets: Specific acceptance criteria
2. Progress updates: Regular comments
3. Test before done: Verify criteria
4. Use agents wisely: Ralph for autonomy, Ticket Worker for collaboration
5. Document decisions: Comments explain "why"

Size Guidelines

• Target: 1-4 hours per ticket
• Too large: Break into multiple tickets
• Too small: Combine related work