Core Workflow Patterns

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

Quick links to rules:

~/.claude/rules/

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>

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

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:progress

/gsd:resume-work

/gsd:pause-work

/gsd:plan-phase <n>

/gsd:execute-plan <path>

/gsd:add-phase <desc>

/gsd:insert-phase <after> <desc>

/gsd:complete-milestone <ver>

/gsd:help

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

no_push

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

src/**/__tests__/

tests/integration/

tests/e2e/

Before committing:

npm run test && npm run type-check

Thinking Frameworks

Use structured decision-making for complex choices:

/consider:10-10-10

/consider:5-whys

/consider:eisenhower-matrix

/consider:first-principles

/consider:inversion

/consider:occams-razor

/consider:one-thing

/consider:opportunity-cost

/consider:pareto

/consider:second-order

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

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

• 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

/create-prompt

/run-prompt

/create-meta-prompt

/whats-next

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

UserCard.tsx

useAuth.ts

utils.ts

utils.test.ts

Resources

Official

• Claude Code Docs
• Anthropic Best Practices

Community

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

See Also

• ~/.claude/rules/checklists/

  - Task-type specific checklists

• ~/.claude/rules/stacks/

  - Stack-specific patterns

• ~/.claude/rules/tooling/

  - Tool configuration guides

• ~/.claude/skills/MASTER_INDEX.md

  - Full skills catalog

• ~/.claude/agents/README.md

  - Agents directory