pro-workflow

# Pro Workflow Complete AI coding workflow system from production use. Orchestration patterns, reference guides, and battle-tested habits that compound over time. **Works with:** Claude Code, Cursor, Codex, Gemini CLI, and 32+ AI coding agents via skills add. Sections marked *(Claude Code)* use features specific to Claude Code — Cursor users can skip those or use the noted alternatives. ## The Core Insight > "80% of my code is written by AI, 20% is spent reviewing and correcting it." — Karpathy This skill optimizes for that ratio. Every pattern here reduces correction cycles. --- ## 1. The Self-Correction Loop **The single most powerful pattern.** Your CLAUDE.md trains itself through corrections. ### How It Works When you correct Claude: 1. Claude acknowledges the mistake 2. Proposes a rule to prevent it 3. You approve → rule goes into memory 4. Future sessions avoid the same mistake ### Add to CLAUDE.md ```markdown ## Self-Correction Protocol When the user corrects me or I make a mistake: 1. Acknowledge specifically what went wrong 2. Propose a concise rule: `[LEARN] Category: One-line rule` 3. Wait for approval before adding to LEARNED section ### LEARNED <!-- Auto-populated through corrections --> ``` ### Trigger Phrases - "Add that to your rules" - "Remember this" - "Don't do that again" ### Example Flow ```text User: You edited the wrong file Claude: I edited src/utils.ts when you meant src/lib/utils.ts. [LEARN] Navigation: Confirm full path before editing files with common names. Should I add this? ``` --- ## 1b. Pre-Flight Discipline **Self-correction catches mistakes after the fact. This catches them before.** Karpathy's [observations on LLM coding pitfalls](https://x.com/karpathy/status/2015883857489522876) name the upstream failures: silent assumptions, overcomplicated diffs, drive-by edits, vague success criteria. Four rules prevent each one. | Rule | Prevents | |------|----------| | **Surface, don't assume** | Wrong interpretation, hidden confusion, missing tradeoffs | | **Minimum viable code** | 200-line diffs that should be 50, speculative abstractions | | **Stay in your lane** | Drive-by refactors, "improvements" to adjacent code | | **Verifiable goals** | Endless re-clarification, "make it work" loops | Full rules in `rules/pre-flight-discipline.mdc` (`alwaysApply: true`). Pairs with self-correction: pre-flight stops the mistake, self-correction captures the lesson when one slips through. ### Add to CLAUDE.md ```markdown ## Pre-Flight Discipline Before coding: state assumptions, present ambiguity, push back if simpler exists. Every changed line traces to the request - no drive-by edits. Convert imperatives to verifiable goals: "fix bug" → "failing test → make it pass". ``` --- ## 2. Parallel Sessions with Worktrees **Zero dead time.** While one Claude thinks, work on something else. ### Setup **Claude Code:** ```bash claude --worktree # or claude -w (auto-creates isolated worktree) ``` **Cursor / Any editor:** ```bash git worktree add ../project-feat feature-branch git worktree add ../project-fix bugfix-branch ``` ### Background Agent Management *(Claude Code)* - `Ctrl+F` — Kill all background agents (two-press confirmation) - `Ctrl+B` — Send task to background - Subagents support `isolation: worktree` in agent frontmatter ### When to Parallelize | Scenario | Action | |----------|--------| | Waiting on tests | Start new feature in worktree | | Long build | Debug issue in parallel | | Exploring approaches | Try 2-3 simultaneously | ### Add to CLAUDE.md ```markdown ## Parallel Work When blocked on long operations, use `claude -w` for instant parallel sessions. Subagents with `isolation: worktree` get their own safe working copy. ``` --- ## 3. The Wrap-Up Ritual End sessions with intention. Capture learnings, verify state. ### /wrap-up Checklist 1. **Changes Audit** - List modified files, uncommitted changes 2. **State Check** - Run `git status`, tests, lint 3. **Learning Capture** - What mistakes? What worked? 4. **Next Session** - What's next? Any blockers? 5. **Summary** - One paragraph of what was accomplished ### Create Command `~/.claude/commands/wrap-up.md`: ```markdown Execute wrap-up checklist: 1. `git status` - uncommitted changes? 2. `npm test -- --changed` - tests passing? 3. What was learned this session? 4. Propose LEARNED additions 5. One-paragraph summary ``` --- ## 4. Split Memory Architecture For complex projects, modularize Claude memory. ### Structure ```text .claude/ ├── CLAUDE.md # Entry point ├── AGENTS.md # Workflow rules ├── SOUL.md # Style preferences └── LEARNED.md # Auto-populated ``` ### AGENTS.md ```markdown # Workflow Rules ## Planning Plan mode when: >3 files, architecture decisions, multiple approaches. ## Quality Gates Before complete: lint, typecheck, test --related. ## Subagents Use for: parallel exploration, background tasks. Avoid for: tasks needing conversation context. ``` ### SOUL.md ```markdown # Style - Concise over verbose - Action over explanation - Acknowledge mistakes directly - No features beyond scope ``` --- ## 5. The 80/20 Review Pattern Batch reviews at checkpoints, not every change. ### Review Points 1. After plan approval 2. After each milestone 3. Before destructive operations 4. At /wrap-up ### Add to CLAUDE.md ```markdown ## Review Checkpoints Pause for review at: plan completion, >5 file edits, git operations, auth/security code. Between: proceed with confidence. ``` --- ## 6. Model Selection **Current lineup (2026):** Fable 5.1, Opus 5.5, Sonnet 5, and Haiku 4.5. The flagship tiers carry a 1M-token context; Haiku 4.5 is 200K. Frontier models converged, so the harness and the effort setting decide output quality more than the model choice. See [`references/models-2026.md`](../../references/models-2026.md) for strings, prices, and routing. | Task | Model | Effort | |------|-------|--------| | Quick fixes, lookups | Haiku 4.5 | low | | Features, balanced work | Sonnet 5 | high | | Refactors, architecture, hard debug | Opus 5.5 | xhigh | | Long-horizon autonomous builds | Fable 5.1 | high / xhigh | ### Effort and adaptive thinking Fixed thinking budgets are retired on the current tiers. Control depth with `effort` (`low` through `xhigh` to `max`); `xhigh` is the default for coding and agentic work. Adaptive thinking lets the model calibrate reasoning per step with no fixed budget. Run grunt subagents at `low` effort on Haiku and keep the reasoning path on the capable tier. ### Add to CLAUDE.md ```markdown ## Model Hints Route by task: Haiku 4.5 for lookups, Sonnet 5 for features, Opus 5.5 for architecture and hard debugging, Fable 5.1 for long-horizon builds. Effort is the lever, not thinking budgets: xhigh for coding, low for subagents. ``` --- ## 7. Context Discipline Context is finite even at 1M tokens (200K on Haiku 4.5). Manage it. ### Rules 1. Read before edit 2. Compact at task boundaries 3. Disable unused MCPs (<10 enabled, <80 tools) 4. Summarize explorations 5. Use subagents to isolate high-volume output (tests, logs, docs) ### Context Compaction - Auto-compacts at ~95% capacity (keeps long-running agents alive) - Configure earlier compaction: `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50` - Use PreCompact hooks to save state before compaction - Subagents auto-compact independently from the main session ### Good Compact Points - After planning, before execution - After completing a feature - When context >70% - Before switching task domains --- ## 8. Learning Log Auto-document insights from sessions. ### Add to CLAUDE.md ```markdown ## Learning Log After tasks, note learnings: `[DATE] [TOPIC]: Key insight` Append to .claude/learning-log.md ``` --- ## Learn Claude Code Run `/learn` for a topic-by-topic guide covering sessions, context, CLAUDE.md, subagents, hooks, and more (see `commands/learn.md`). Official docs: **https://code.claude.com/docs/** --- ## Quick Setup ### Minimal Add to your CLAUDE.md: ```markdown ## Pro Workflow ### Self-Correction When corrected, propose rule → add to LEARNED after approval. ### Planning Multi-file: plan first, wait for "proceed". ### Quality After edits: lint, typecheck, test. ### LEARNED ``` ### Full Setup ```bash git clone https://github.com/rohitg00/pro-workflow.git /tmp/pw cp -r /tmp/pw/templates/split-claude-md/* ./.claude/ cp -r /tmp/pw/commands/* ~/.claude/commands/ ``` --- ## Hooks *(Claude Code)* Pro-workflow includes automated hooks to enforce the patterns. Cursor users get equivalent enforcement through `.mdc` rules in the `rules/` directory. ### PreToolUse Hooks | Trigger | Action | |---------|--------| | Edit/Write | Track edit count, remind at 5/10 edits | | git commit | Remind to run quality gates | | git push | Remind about /wrap-up | ### PostToolUse Hooks | Trigger | Action | |---------|--------| | Code edit (.ts/.js/.py/.go) | Check for console.log, TODOs, secrets | | Test commands | Suggest [LEARN] from failures | ### Session Hooks | Hook | Action | |------|--------| | SessionStart | Load LEARNED patterns, show worktree count | | Stop | Context-aware reminders using `last_assistant_message` | | SessionEnd | Check uncommitted changes, prompt for learnings | | ConfigChange | Detect when quality gates or hooks are modified mid-session | ### Install Hooks ```bash # Copy hooks to your settings cp ~/skills/pro-workflow/hooks/hooks.json ~/.claude/settings.local.json # Or merge with existing settings ``` ### Hook Philosophy Based on Twitter thread insights: - **Non-blocking** - Hooks remind, don't block (except dangerous ops) - **Checkpoint-based** - Quality gates at intervals, not every edit - **Learning-focused** - Always prompt for pattern capture --- ## Contexts Switch modes based on what you're doing. | Context | Trigger | Behavior | |---------|---------|----------| | **dev** | "Let's build" | Code first, iterate fast | | **review** | "Review this" | Read-only, security focus | | **research** | "Help me understand" | Explore, summarize, plan | Use: "Switch to dev mode" or load context file. --- ## Agents Specialized subagents for focused tasks. | Agent | Purpose | Tools | |-------|---------|-------| | **planner** | Break down complex tasks | Read-only | | **reviewer** | Code review, security audit | Read + test | ### When to Delegate Use planner agent when: - Task touches >5 files - Architecture decision needed - Requirements unclear Use reviewer agent when: - Before committing - PR reviews - Security concerns ### Custom Subagents *(Claude Code)* Create project-specific subagents in `.claude/agents/` or user-wide in `~/.claude/agents/`: - Define with YAML frontmatter + markdown system prompt - Control tools, model, permission mode, hooks, and persistent memory - Use `/agents` to create, edit, and manage interactively - Preload skills into subagents for domain knowledge ### Agent Teams *(Claude Code, Experimental)* Coordinate multiple Claude Code sessions as a team: - Enable: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` - Lead session coordinates, teammates work independently - Teammates message each other directly (not just report back) - Shared task list with dependency management - Display: in-process (`Shift+Down` to navigate, wraps around) or split panes (tmux/iTerm2) - Delegate mode (Shift+Tab): lead coordinates only, no code edits - Best for: parallel reviews, competing hypotheses, cross-layer changes - **Docs:** https://code.claude.com/docs/agent-teams --- ## 9. Orchestration: Command > Agent > Skill The most powerful pattern for complex features. Three layers, each with a single job. ### The Architecture ```text Command (user-facing entry point) └── Agent (execution, constrained tools, preloaded skills) └── Skill (domain knowledge, injected at startup) ``` ### Multi-Phase Development (/develop) For features touching >5 files or needing architecture decisions: 1. **Research** → orchestrator agent explores codebase, scores confidence (0-100) 2. **Plan** → presents approach, files to change, risks. Waits for approval. 3. **Implement** → executes plan step by step with quality gates every 5 edits 4. **Review** → reviewer agent checks for security, logic, quality All four phases run in order. Each phase requires explicit user approval before the next phase begins. ### Agent Skills (Preloaded) ```yaml # Agent frontmatter skills: ["api-conventions", "project-patterns"] ``` Full skill content injected at agent startup. Use for knowledge the agent always needs. ### On-Demand Skills (Invoked)