pro-workflow

name pro-workflow description Complete AI coding workflow system. Orchestration patterns, 18 hook events, 8 agents, cross-agent support, reference guides, and searchable learnings. Works with Claude Code, Cursor, and 32+ agents. 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: Claude acknowledges the mistake Proposes a rule to prevent it You approve → rule goes into memory Future sessions avoid the same mistake Add to CLAUDE.md ## 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 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 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 ## 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: claude --worktree # or claude -w (auto-creates isolated worktree) Cursor / Any editor: 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 ## 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 Changes Audit - List modified files, uncommitted changes State Check - Run git status , tests, lint Learning Capture - What mistakes? What worked? Next Session - What's next? Any blockers? Summary - One paragraph of what was accomplished Create Command ~/.claude/commands/wrap-up.md : 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 .claude/ ├── CLAUDE.md # Entry point ├── AGENTS.md # Workflow rules ├── SOUL.md # Style preferences └── LEARNED.md # Auto-populated AGENTS.md # 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 # 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 After plan approval After each milestone Before destructive operations At /wrap-up Add to CLAUDE.md ## 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, Opus 4.8, 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 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 4.8 xhigh Long-horizon autonomous builds Fable 5 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 ## Model Hints Route by task: Haiku 4.5 for lookups, Sonnet 5 for features, Opus 4.8 for architecture and hard debugging, Fable 5 for long-horizon builds. Effort is the lever, not thinking budgets: xhigh for coding, low for subagents. 7. Context Discipline 200k tokens is precious. Manage it. Rules Read before edit Compact at task boundaries Disable unused MCPs (<10 enabled, <80 tools) Summarize explorations 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 ## 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: ## 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 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 # 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 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: Research → orchestrator agent explores codebase, scores confidence (0-100) Plan → presents approach, files to change, risks. Waits for approval. Implement → executes plan step by step with quality gates every 5 edits 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) # 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) Skills with user-invocable: true are called via /skill-name . Use context: fork for isolated execution that doesn't pollute main context.