Core Workflow Patterns

Comprehensive development workflow reference. This loads on-demand for detailed patterns.

Quick links to rules: ~/.claude/rules/ for stack-specific and task-type checklists.

Session Protocol

Start Checklist

# 1. Sync with remote (ALWAYS FIRST)
git fetch origin main && git merge origin/main --no-edit
# or: git fetch origin master && git merge origin/master --no-edit

# 2. Get context
git log -3

# 3. Check for existing work
ls tasks/*.md 2>/dev/null || echo "No active tasks"

CRITICAL: Check <env> section for today's date. NEVER guess dates.

End Checklist

# 1. Verify
npm run test && npm run type-check  # or project equivalent

# 2. Archive completed work
mv tasks/<completed-task>.md .archive/completed-tasks/

# 3. Commit with comprehensive message
git add .
git commit  # See Git Conventions below
git push origin main

Stop dev server after testing: lsof -ti:PORT | xargs kill (or Windows equivalent)

GSD (Get Shit Done) - Multi-Phase Projects

For complex features spanning days/weeks, use GSD.

When to Use GSD

GSD Quick Start

/gsd:new-project       # Initialize with brief + config
/gsd:create-roadmap    # Create phases and state tracking
/gsd:plan-phase 1      # Create detailed plan for phase
/gsd:execute-plan <path>  # Execute the plan

GSD Commands Reference

GSD File Structure

.planning/
├── PROJECT.md          # Vision and requirements
├── ROADMAP.md          # Phase breakdown
├── STATE.md            # Project memory (context accumulation)
├── config.json         # Workflow mode (interactive/yolo)
└── phases/
    └── 01-foundation/
        ├── 01-01-PLAN.md
        └── 01-01-SUMMARY.md

Git Conventions

Commit Types

feat | fix | refactor | perf | test | docs | chore

Commit Message Format

type: Short summary (50 chars max)

## What Changed
- File X: Added feature Y
- File Z: Updated config for A

## Why
- User requested feature Y
- Config A needed update

## Testing
- All tests passing
- Manual verification done

Auto-Commit on Task Completion

When a task or plan is complete, automatically commit without being asked.

Pre-Commit Checks

# 1. Check this is a user-owned repo (not external)
git remote get-url origin | grep -q "travisjneuman" && echo "OK: User repo"

# 2. Check push is not blocked
git remote get-url --push origin | grep -q "no_push" && echo "SKIP: External repo"

Rules

Security Checklist

Frontend

• textContent not innerHTML
• unknown type for external data
• No exposed API keys
• HTTPS for external requests
• Input sanitization

Backend

• Input validation on all endpoints
• Auth guards on protected routes
• Parameterized queries (no raw SQL)
• Secrets in environment variables

Performance Targets

Accessibility (WCAG AA)

• Semantic HTML structure
• Alt text for meaningful images
• Keyboard navigation (Tab, Enter, Escape)
• Focus indicators visible
• Color contrast >= 4.5:1
• ARIA labels on interactive elements
• Touch targets >= 44x44px

Testing Strategy

Before committing: npm run test && npm run type-check

Thinking Frameworks

Use structured decision-making for complex choices:

Debugging Protocol

Standard Issues

1. Reproduce the issue
2. Read relevant code
3. Identify root cause
4. Fix + add test
5. Verify fix

Intermittent/Complex Issues

Use debug-like-expert skill for systematic approach.

Build vs Buy Philosophy

We build features. We use utilities.

• Build: All feature logic, business rules, UI/UX, data models
• Use: Low-level abstractions (D3, Recharts, Lexical, Konva)
• Criterion: We own the feature, library handles complexity

License Requirements

• Must use: MIT, Apache 2.0, BSD
• Never use: GPL, AGPL (blocks commercialization)

Communication Standards

Progress Updates

Give high-level updates, not spam:

✅ Added authentication middleware (3 files)
✅ Updated user store with new fields
⏳ Testing login flow...

When to Ask

Use AskUserQuestion when:

• Requirements are ambiguous
• Multiple valid architectures exist
• Scope might expand
• Design decisions need validation

Directness Protocol

• Logic over feelings
• Correctness over validation
• Direct feedback over diplomacy
• Best solution over agreement

Context Hygiene

Reduce Token Usage

• Short, high-signal summaries over long logs
• Don't @-embed large docs by default
• Reference paths + when to read them
• Use /clear after completing work units

Delegation Patterns

Quick Reference

Common Commands

npm run dev          # Start dev server
npm run build        # Production build
npm run test         # Run tests
npm run type-check   # TypeScript check

File Naming

Resources

Official

• Claude Code Docs
• Anthropic Best Practices

Community

• awesome-claude-code
• awesome-claude-md

See Also

• ~/.claude/docs/reference/checklists/ - Task-type specific checklists
• ~/.claude/docs/reference/stacks/ - Stack-specific patterns
• ~/.claude/docs/reference/tooling/ - Tool configuration guides
• ~/.claude/skills/MASTER_INDEX.md - Full skills catalog
• ~/.claude/agents/README.md - Agents directory