Core Workflow

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