Skip to main content
skill CX Codex

pro-workflow — Claude Code skill: what it does, how to install

pro-workflow — a skill that packages coding habits for AI agents: correction loops, pre-flight rules, worktree sessions and a wrap-up ritual.

MIT ★ 2,966 updated 2026-09-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow
Open on GitHub

What pro-workflow does

The skill hands the agent a routine. A mistake gets turned into a rule instead of another retry: the agent names what went wrong, drafts a one-line lesson marked [LEARN], and after your approval it lands in the LEARNED section of CLAUDE.md. Four pre-flight rules run in front of that and catch wrong assumptions, oversized diffs and edits to code nobody asked about.

Long builds don't leave you idle. A second session starts in its own worktree with claude -w or git worktree add, and /wrap-up closes things down: changed files, git status, tests, lessons learned, a short summary. Bigger projects can split memory across AGENTS.md, SOUL.md and LEARNED.md. One section covers picking a model and an effort level for the task.

Sections flagged for Claude lean on features other tools don't have. The Ctrl+B background shortcut and isolation: worktree in subagent frontmatter won't work in Cursor, so those parts get skipped or replaced with the alternatives the skill names.

What it helps with

  • turn a correction into a lasting rule in CLAUDE.md
  • keep working while a long build runs in another worktree
  • close a session with verified state and a summary
  • split project memory into workflow rules and style notes
  • pick a model and effort level for the task at hand

Example prompts for the agent

  • Add the self-correction protocol from pro-workflow to CLAUDE.md
  • Create the wrap-up command using the checklist from pro-workflow
  • Split my project memory into AGENTS.md, SOUL.md and LEARNED.md the way pro-workflow suggests

How to install pro-workflow

1Plugin marketplace

/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow

This installs the whole pro-workflow plugin with all its skills

2Skills CLI (Vercel)

npx skills add rohitg00/pro-workflow --skill pro-workflow -a claude-code

3Manually: put the files in place

~/.claude/skills/pro-workflow/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pro-workflow/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about pro-workflow

How do I install pro-workflow in Claude Code?

From the plugin marketplace: run /plugin marketplace add rohitg00/pro-workflow, then /plugin install pro-workflow@pro-workflow.

What does pro-workflow do?

It documents a self-correction loop that writes rules into project memory, pre-flight rules before editing code, parallel worktree sessions, a /wrap-up command and review checkpoints.

Does pro-workflow work outside Claude?

It's built for several agents, including Cursor, Claude and Gemini CLI. Parts marked Claude rely on features those editors lack, and the skill lists alternatives for them.

Source text

SKILL.md · MIT
---
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:
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)

Skills with `user-invocable: true` are called via `/skill-name`. Use `context: fork` for isolated execution that doesn't pollute main context.

### When to Orchestrate

| Scenario | Pattern |
|----------|---------|
| Feature > 5 files | `/develop` with orchestrator |
| Bug investigation | debugger agent |
| Quick exploration | scout agent (background) |
| Code review | reviewer agent |
| Simple task | Just do it directly |

---

## 10. Daily Habits

### Every Session
- Run `/doctor` if things feel off
- Manual `/compact` at 50% — don't wait for auto-compact
- `ultrathink` in prompts for maximum reasoning
- Name sessions with `/rename` for easy `/resume`
- End with `/wrap-up` to capture learnings

### Context Management
- CLAUDE.md: < 60 lines root, < 150 max
- Use `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50` for proactive compaction
- Delegate heavy exploration to subagents
- Keep <10 MCPs, <80 tools

### Cross-Agent Tips
- Use Cursor for tab completions + Claude Code in terminal for hard problems
- Same MCP servers work across both (share `.mcp.json` at project root)
- skills add installs to any agent: `npx skills add rohitg00/pro-workflow`

---

## MCP Config *(Claude Code)*

Start with 3 MCPs. Add only for concrete needs.

Essential:
- `context7` — Live documentation lookup
- `playwright` — Browser automation (most token-efficient)
- `github` — PRs, issues, code search

See `mcp-config.example.json` for setup and curated recommendations.

---

## Commands *(Claude Code)*

| Command | Purpose | Cursor Equivalent |
|---------|---------|-------------------|
| `/wrap-up` | End-of-session ritual | `wrap-up` skill |
| `/learn-rule` | Extract correction to memory | `learn-rule` skill |
| `/develop` | Multi-phase feature build | `orchestrate` skill |
| `/doctor` | Health check | — |
| `/commit` | Smart commit with quality gates | `smart-commit` skill |
| `/insights` | Session analytics and patterns | `insights` skill |
| `/replay` | Surface past learnings | `replay-learnings` skill |
| `/handoff` | Session handoff document | `session-handoff` skill |
| `/search` | Search learnings by keyword | — |
| `/list` | List all stored learnings | — |
| `/learn` | Topic-by-topic Claude Code guide | — |

---

## Reference Guides

Deep dives on configuration and features:

| Guide | Topics |
|-------|--------|
| `references/settings-guide.md` | All settings keys, permission modes, hierarchy, sandbox, env vars |
| `references/cli-cheatsheet.md` | Every CLI flag, keyboard shortcut, slash command |
| `references/orchestration-patterns.md` | Command > Agent > Skill architecture, frontmatter reference |
| `references/context-loading.md` | CLAUDE.md monorepo loading, agent memory, skills discovery |
| `references/cross-agent-workflows.md` | Claude Code + Cursor config mapping, background agents |
| `references/new-features.md` | Voice mode, agent teams, checkpointing, new hook events |
| `references/daily-habits.md` | Session habits, debugging tips, terminal setup, anti-patterns |

---

## Philosophy

1. **Compound improvements** - Small corrections lead to big gains
2. **Trust but verify** - Let AI work, review at checkpoints
3. **Zero dead time** - Parallel sessions keep momentum
4. **Memory is precious** - Yours and the AI's
5. **Orchestrate, don't micromanage** - Wire patterns together, let agents execute

---

*Complete AI coding workflow system from production use across Claude Code, Cursor, and beyond.*

© Rohit Ghumare · MIT · rohitg00/pro-workflow

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set83

The whole set →
skill-router The skill-router skill maps pro-workflow skills and commands to jobs, with guidance on when to use each and whether a person or the agent starts it. Use it when you’re unsure what fits. CX Codex +1 ★ 2,966repo stars permission-analyst permission-analyst analyzes permission prompts and auto mode denials, recommends permissions rules and autoMode entries. Use it when prompts slow you down or auto mode keeps falling back to confirmations. CX Codex ★ 2,966repo stars safe-mode safe-mode intercepts destructive terminal commands and confines agent edits to a specific directory using Claude Code hooks. CX Codex +1 ★ 2,966repo stars wiki-research-loop wiki-research-loop is a Claude Code skill that researches a topic and adds pages to a wiki. It runs on requests such as research <topic> or instructions to grow a wiki automatically. CX Codex +1 ★ 2,966repo stars survey-generator survey-generator generates structured literature surveys on AI/ML topics. Output is a wiki page in markdown with bibliography, not a one-off HTML file. CX Codex +1 ★ 2,966repo stars context-engineering context-engineering guides Claude Code through the four context operations — Write, Select, Compress, and Isolate — to prevent context degradation. CX Codex +1 ★ 2,966repo stars learn learn is a Claude Code command that shows topic-based guidance and saves confirmed takeaways from a session. CX Codex +1 ★ 2,966repo stars pro-workflow The pro-workflow plugin for Claude Code adds persistent SQLite memory, FTS5-indexed project wikis, and 23 slash commands to carry instructions across sessions. ★ 2,966repo stars

Project sponsors

Companies that keep this analytics open