authors: Bryon bryon@fryer.io state: pre-discussion labels: process, collaboration, workflow

Pair Programming Workflow

Overview

This document outlines our pair programming workflow for building this project. It ensures consistent process, proper testing, and knowledge capture as we work through the project plan.

Workflow Process

1. Task Selection & Planning

Claude’s Actions:

• Pick up the next Pending task from the project_plan.md table
• Review the task’s acceptance criteria and testing requirements in the linked task document
• Create a brief implementation plan (2-3 bullet points)
• Confirm plan with human before proceeding

Human’s Actions:

• Review and approve Claude’s implementation plan
• Create a new git branch for the task: git checkout -b task/[task_number] (e.g., task/1.2)
• Confirm Claude should proceed with implementation

Claude’s Actions (before proceeding):

• Verify git branch is ready: Use git branch -a to confirm the correct task branch is active
• If branch is not ready, remind human to create it before proceeding

Branch Creation Safety Checks

Before requesting branch creation, Claude should verify:

• Current branch status with git status shows clean working tree
• Currently on main branch (or appropriate base branch)
• No uncommitted changes that could be lost
• No untracked files that might indicate work in progress

Safe conditions for automatic branch creation:

# These conditions must ALL be true:
git status --porcelain  # Returns empty (no changes)
git branch --show-current  # Returns "main" (on base branch)
git diff --staged  # Returns empty (no staged changes)

If all safety checks pass, Claude can:

• Inform human of the safe state
• Suggest the exact branch creation command
• Proceed only after human confirmation

If safety checks fail, Claude must:

• Report the unsafe conditions found
• Ask human to resolve before proceeding
• Never attempt automatic branch operations

2. Implementation Preparation

Claude’s Actions:

• After brief plan is approved by human and git branch is created, create a comprehensive implementation plan
• Update task status in the project_plan.md table (change status from “Pending” to “In Progress”)
• Build a detailed todo list for the task implementation using TodoWrite tool
• Review CLAUDE.md for project-specific commands and architecture notes
• Update todo list to mark task as “in_progress”
• Read any relevant existing files to understand current state

3. Implementation

Claude’s Actions:

• Implement the task following acceptance criteria
• Write clean, well-structured code following established patterns
• Use proper error handling where needed

4. Testing & Verification

Claude’s Actions:

• Run specified tests from the task (unit/integration/manual)
• Use make build to verify no compilation errors (includes vendor unpack)
• Use make test to run all tests (includes vendor unpack)
• Use make lint for code quality checks (vet + format validation)
• Use make fmt if code formatting issues are found

5. Human Verification Request

Claude’s Actions:

• Summarize what was implemented
• List what should be visible/testable in the app
• Provide specific testing steps for the human
• Prompt human to verify in running app

Required format:

“## Task X.Y Implementation Complete!

Changes made:

• [Bulleted list of key changes]

Please verify in the app:

• [Specific steps to test the functionality]
• [Expected behavior/output]

Expected results:

• [What should happen if working correctly]
• [Any specific UI changes to look for]

Ready for your verification!”

6. Human Testing & Feedback

Human’s Actions:

• Test the changes in the running app
• Verify acceptance criteria are met
• Provide feedback: “Perfect! That worked!” or describe issues

If Issues Found:

• Human describes what went wrong or what’s not working
• Claude investigates and fixes the issues
• Return to step 4 (Testing & Verification) after fixes
• Repeat until verification succeeds

7. Task Completion

Claude’s Actions (after human confirms success):

• Create git commit for all task changes using proper commit message format
• Update task status in the project_plan.md table (change status from “In Progress” to “Completed”)
• Update todo list to completed
• Update technical_considerations.md with lessons learned
• Important: Ensure the project_plan.md status change is included in the final task commit

Git Commit Format:

Task [X.Y]: [Brief description of changes]

- [Bulleted list of key changes made]
- [Focus on what was implemented/fixed]

See: docs/todo/task_[X.Y].md

Commit Message Guidelines:

• First line: Task number and brief description of what was implemented
• Body: Bulleted list of specific changes made during implementation
• Footer: Reference to the detailed task document for full context

Documentation Updates

Project Plan Table Format

The project_plan.md uses a streamlined table format for quick reference:

• Each task is a single table row with aligned columns
• Status values: “Pending”, “In Progress”, “Testing”, “Completed”
• Links to detailed task documents in the Details column
• No emoji usage - clean text-based status indicators

During Each Task

Claude should update these files as needed:

CLAUDE.md Updates

• Add new commands discovered during implementation
• Update architecture notes if patterns change
• Document any new dependencies or tools
• Note any gotchas or important considerations

RFD Updates

In the appropriate RFD document:

• Document technical decisions and rationale
• Record issues encountered and solutions
• Note what works well and what to avoid
• Capture performance considerations
• Document testing strategies that work If a new RFD topic is appropriate:
• Follow the RFD purpose and procedures in RFD 001
• Document what new topic requires a new discussion
• Propose an RFD with the next RFD number

Quality Checks

Before Marking task Complete

• All acceptance criteria met
• All specified tests pass (make test)
• Build succeeds without errors (make build)
• Code passes linting checks (make lint)
• Code is properly formatted (make fmt if needed)
• No new console errors or warnings
• Relevant documentation updated
• Human verification completed

Code Quality Standards

• Handle errors gracefully
• Write clear, self-documenting code
• Keep functions small and focused

Communication Patterns

Starting a task

Claude: “Ready for Task X.Y: [Title]. My plan: [brief plan]. Does this approach sound good?”

During Implementation

Claude: [Work silently through implementation, testing, and verification]

Requesting Verification

Claude: “Task X.Y implementation complete! Changes: [summary]. Please verify: [specific things to check]. Ready for your verification!”

After Human Confirmation

Claude: “Great! Marking Task X.Y as completed. Moving to next task…”

Emergency Procedures

If Task Becomes Too Complex

• Break it down into smaller sub-tasks
• Document the breakdown in the appropriate RFD document
• Get human approval for the new approach

If Architecture Changes Needed

• Document the change rationale in the appropriate RFD document
• Get human approval before major changes

If Stuck on Technical Issue

• Document the issue in in the appropriate RFD document
• Propose 2-3 alternative approaches
• Ask human for guidance

Success Metrics

• Tasks completed per session
• Build success rate (should be 100%)
• Quality of human verification feedback
• Documentation completeness
• Knowledge capture effectiveness

This workflow ensures we maintain quality, capture knowledge, and make steady progress toward our goals.