diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 09069c4..ef36516 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ { "name": "pro-workflow", "source": "./", - "description": "Self-correcting memory, parallel worktrees, wrap-up rituals, and the 80/20 AI coding ratio. Complete hooks, agents, and commands.", + "description": "Complete AI coding workflow: orchestration patterns, 18 hook events, 5 agents, cross-agent support, reference guides, and searchable learnings.", "author": { "name": "Rohit Ghumare" }, @@ -24,7 +24,11 @@ "self-correction", "worktrees", "hooks", - "agents" + "agents", + "orchestration", + "cross-agent", + "cursor", + "codex" ], "category": "workflow", "tags": [ @@ -33,7 +37,11 @@ "agents", "commands", "productivity", - "best-practices" + "best-practices", + "orchestration", + "settings-guide", + "cli-reference", + "cross-agent" ] } ] diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 19013b1..a3fc9a1 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "pro-workflow", - "version": "1.3.0", - "description": "Battle-tested Claude Code workflows with persistent storage and searchable learnings. Self-correcting memory, parallel worktrees, wrap-up rituals, and the 80/20 AI coding ratio.", + "version": "2.0.0", + "description": "Complete AI coding workflow system. Orchestration patterns, 18 hook events, 5 agents, 7 reference guides, cross-agent support, and searchable learnings.", "author": { "name": "Rohit Ghumare", "url": "https://github.com/rohitg00" @@ -26,6 +26,8 @@ "agents": [ "./agents/planner.md", "./agents/reviewer.md", - "./agents/scout.md" + "./agents/scout.md", + "./agents/orchestrator.md", + "./agents/debugger.md" ] } diff --git a/README.md b/README.md index 742c67e..8009815 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,75 @@ -# Pro Workflow +

+ Pro Workflow +

+ +

+ Stars + npm + License + SkillKit +

+ +

+ Complete AI coding workflow system.
+ Orchestration patterns • 18 hook events • 5 agents • 7 reference guides • Cross-agent support
+ Works with Claude Code, Cursor, and 32+ agents via SkillKit. +

-[![GitHub stars](https://img.shields.io/github/stars/rohitg00/pro-workflow?style=social)](https://github.com/rohitg00/pro-workflow) -[![npm version](https://img.shields.io/npm/v/pro-workflow)](https://www.npmjs.com/package/pro-workflow) +--- + +## What's New in v2.0 -Battle-tested AI coding workflows from power users. Self-correcting memory, parallel worktrees, wrap-up rituals, and the 80/20 AI coding ratio. Works with **Claude Code** and **Cursor**. + + + + + + + + + + +
Orchestration PatternsCommand > Agent > Skill architecture with multi-phase development
5 Agentsplanner, reviewer, scout, orchestrator (RPI workflow), debugger
18 Hook EventsAdded SubagentStart/Stop, TaskCompleted, PermissionRequest, TeammateIdle, PostToolUseFailure
7 Reference GuidesSettings, CLI cheatsheet, orchestration patterns, context loading, cross-agent workflows, new features, daily habits
Context OptimizerToken management and context budget planning skill
Production SettingsFull settings.example.json with permissions, spinner, output style
Curated MCP ConfigBattle-tested server recommendations with scope guidance
/develop CommandResearch > Plan > Implement > Review & Commit with validation gates
/doctor CommandHealth check for your pro-workflow setup
+ +--- -## The Core Idea +## How It Works > "80% of my code is written by AI, 20% is spent reviewing and correcting it." — Karpathy -This skill optimizes for that ratio. Every pattern reduces correction cycles. +Pro Workflow optimizes for that ratio. Every pattern reduces correction cycles. + +### The Self-Correction Loop + +

+ Self-Correction Loop Demo +

+ +Corrections compound. Each mistake becomes a rule that prevents future mistakes. After 50 sessions, Claude barely needs correcting. + +### The `/develop` Flow + +

+ Development Flow +

+ +Multi-phase development with validation gates. Research before planning, plan before implementing, review before committing. + +### The `/develop` Command in Action + +

+ Terminal Demo +

+ +--- + +## Architecture + +

+ Architecture Diagram +

+ +--- ## Patterns @@ -23,6 +83,8 @@ This skill optimizes for that ratio. Every pattern reduces correction cycles. | **Model Selection** | Opus 4.6 adaptive thinking, Sonnet 4.6 (1M context) | | **Context Discipline** | Manage your 200k token budget | | **Learning Log** | Auto-document insights | +| **Orchestration** | Command > Agent > Skill wiring for complex features | +| **Multi-Phase Dev** | Research > Plan > Implement > Review & Commit with validation gates | ## Installation @@ -32,58 +94,35 @@ This skill optimizes for that ratio. Every pattern reduces correction cycles. /add-plugin pro-workflow ``` -The plugin includes 9 skills, 3 agents, and 6 rules that load automatically. +The plugin includes 11 skills, 5 agents, and 6 rules that load automatically. ### Claude Code — One-Click Plugin Install ```bash -# Add marketplace /plugin marketplace add rohitg00/pro-workflow - -# Install plugin /plugin install pro-workflow@pro-workflow ``` -Or via CLI: - -```bash -claude plugin marketplace add rohitg00/pro-workflow -claude plugin install pro-workflow@pro-workflow -``` - ### Claude Code — Build with SQLite Support -After installation, build the TypeScript for persistent storage: - ```bash -cd ~/.claude/plugins/*/pro-workflow # Navigate to plugin directory +cd ~/.claude/plugins/*/pro-workflow npm install && npm run build ``` -This creates the SQLite database at `~/.pro-workflow/data.db`. - ### Or load directly ```bash claude --plugin-dir /path/to/pro-workflow ``` -### Manual 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/ -cp -r /tmp/pw/hooks/* ~/.claude/ -``` - ### Minimal (Just add to CLAUDE.md) ```markdown ## Pro Workflow ### Self-Correction -When corrected, propose rule → add to LEARNED after approval. +When corrected, propose rule -> add to LEARNED after approval. ### Planning Multi-file: plan first, wait for "proceed". @@ -94,11 +133,23 @@ After edits: lint, typecheck, test. ### LEARNED ``` -## Skills (Cursor) +## Reference Guides + +| Guide | What's Covered | +|-------|---------------| +| [`docs/settings-guide.md`](docs/settings-guide.md) | All settings keys, permission modes, hierarchy, sandbox, MCP approval | +| [`docs/cli-cheatsheet.md`](docs/cli-cheatsheet.md) | Every CLI flag, keyboard shortcut, slash command, scripting patterns | +| [`docs/orchestration-patterns.md`](docs/orchestration-patterns.md) | Command > Agent > Skill architecture, frontmatter reference, agent teams | +| [`docs/context-loading.md`](docs/context-loading.md) | CLAUDE.md loading in monorepos, agent memory, skills discovery | +| [`docs/cross-agent-workflows.md`](docs/cross-agent-workflows.md) | Using Claude Code + Cursor together, config mapping, SkillKit translation | +| [`docs/new-features.md`](docs/new-features.md) | Voice mode, agent teams, checkpointing, remote control, new hook events | +| [`docs/daily-habits.md`](docs/daily-habits.md) | Session habits, debugging tips, terminal setup, anti-patterns | + +## Skills | Skill | Description | |:------|:------------| -| `pro-workflow` | Core 8 workflow patterns for AI-assisted coding | +| `pro-workflow` | Core workflow patterns for AI-assisted coding | | `smart-commit` | Quality gates, staged review, and conventional commits | | `wrap-up` | End-of-session ritual with change audit and learning capture | | `learn-rule` | Capture corrections as persistent learning rules | @@ -107,6 +158,86 @@ After edits: lint, typecheck, test. | `session-handoff` | Generate handoff documents for session continuity | | `insights` | Session analytics, correction trends, and productivity metrics | | `deslop` | Remove AI-generated code slop and clean up style | +| `context-optimizer` | Token management, context budget, MCP audit | +| `orchestrate` | Wire Commands, Agents, and Skills for multi-phase development | + +## Agents + +| Agent | Purpose | Key Feature | +|-------|---------|-------------| +| **planner** | Break down complex tasks | Read-only, approval-gated | +| **reviewer** | Code review, security audit | Checklist-based, severity levels | +| **scout** | Confidence-gated exploration | Background, worktree-isolated | +| **orchestrator** | Multi-phase feature development | Research > Plan > Implement > Review, memory-enabled | +| **debugger** | Systematic bug investigation | Hypothesis-driven, root cause analysis | + +## Commands (Claude Code) + +When installed as a plugin, commands are available as `/pro-workflow:`. Short forms like `/develop` also work directly after plugin install. + +| Command | Alias | Purpose | +|---------|-------|---------| +| `/pro-workflow:wrap-up` | `/wrap-up` | End-of-session checklist | +| `/pro-workflow:learn-rule` | `/learn-rule` | Extract correction to memory | +| `/pro-workflow:commit` | `/commit` | Smart commit with quality gates | +| `/pro-workflow:develop` | `/develop` | Multi-phase feature build (Research > Plan > Implement > Review & Commit) | +| `/pro-workflow:doctor` | `/doctor` | Health check for setup and configuration | +| `/pro-workflow:insights` | `/insights` | Session analytics and correction heatmap | +| `/pro-workflow:replay` | `/replay` | Surface past learnings for current task | +| `/pro-workflow:handoff` | `/handoff` | Generate session handoff document | +| `/pro-workflow:search` | `/search` | Search learnings by keyword | +| `/pro-workflow:list` | `/list` | List all stored learnings | + +## Hooks (18 Events) + +| Hook | When | What | +|------|------|------| +| PreToolUse | Before edits | Track edit count, quality gate reminders | +| PreToolUse | Before git commit/push | Remind about quality gates, wrap-up | +| PostToolUse | After code edits | Check for console.log, TODOs, secrets | +| PostToolUse | After tests | Suggest [LEARN] from failures | +| UserPromptSubmit | Each prompt | Drift detection, correction tracking | +| SessionStart | New session | Load learnings from database | +| Stop | Each response | Context-aware reminders | +| SessionEnd | Session close | Save session stats to database | +| PreCompact | Before compaction | Save context state | +| ConfigChange | Settings modified | Detect mid-session changes | +| Notification | System events | Log permission requests | +| **SubagentStart** | Subagent spawns | Log agent lifecycle | +| **SubagentStop** | Subagent finishes | Collect results | +| **TaskCompleted** | Task marked done | Quality gate on completion | +| **PermissionRequest** | Permission dialog | Flag dangerous operations | +| **PostToolUseFailure** | Tool fails | Track failures, suggest learnings | +| **TeammateIdle** | Teammate goes idle | Detect blockers in agent teams | +| **Setup** | Initial setup | One-time initialization (available, not configured) | +| **WorktreeCreate** | Worktree created | Set up worktree config (available, not configured) | +| **WorktreeRemove** | Worktree removed | Cleanup (available, not configured) | + +### Hook Lifecycle + +```mermaid +graph LR + A[SessionStart] --> B[UserPromptSubmit] + B --> C[PreToolUse] + C --> D{Tool Runs} + D -->|Success| E[PostToolUse] + D -->|Failure| F[PostToolUseFailure] + E --> G[Stop] + F --> G + G -->|More prompts| B + G -->|Session ends| H[SessionEnd] + + C -->|Spawns agent| I[SubagentStart] + I --> J[SubagentStop] + + C -->|Needs permission| K[PermissionRequest] + + style A fill:#6366f1,color:#fff,stroke:none + style H fill:#ef4444,color:#fff,stroke:none + style D fill:#f59e0b,color:#000,stroke:none + style E fill:#22c55e,color:#fff,stroke:none + style F fill:#ef4444,color:#fff,stroke:none +``` ## Rules (Cursor) @@ -119,221 +250,159 @@ After edits: lint, typecheck, test. | `no-debug-statements` | `*.{ts,tsx,js,jsx,py,go,rs}` | Remove console.log, debugger, print before committing | | `communication-style` | Always | Concise, action-oriented, no over-engineering | -## Commands (Claude Code) - -After plugin install, commands are namespaced: - -| Command | Purpose | -|---------|---------| -| `/pro-workflow:wrap-up` | End-of-session checklist | -| `/pro-workflow:learn-rule` | Extract correction to memory (file-based) | -| `/pro-workflow:parallel` | Worktree setup guide | -| `/pro-workflow:learn` |Claude Code best practices & save learnings | -| `/pro-workflow:search` |Search learnings by keyword | -| `/pro-workflow:list` |List all stored learnings | -| `/pro-workflow:commit` | Smart commit with quality gates and code review | -| `/pro-workflow:insights` | Session analytics, learning patterns, and correction heatmap | -| `/pro-workflow:replay` |Surface past learnings for current task | -| `/pro-workflow:handoff` |Generate session handoff document for next session | - -## Database Features - -### Persistent Learnings +## Configuration -Learnings are stored in SQLite with FTS5 full-text search: +### Settings Example -``` -~/.pro-workflow/ -└── data.db # SQLite database with learnings and sessions -``` +See [`settings.example.json`](settings.example.json) for a production-ready configuration including: +- Permission rules (allow/deny/ask) +- Output style and status line +- Auto-compaction at 80% +- Custom spinner verbs and tips +- Attribution disabled +- Plans directory -### Search Examples +### MCP Config -``` -/search testing # Find all testing-related learnings -/search "file paths" # Exact phrase search -/search git commit # Multiple terms -``` +See [`mcp-config.example.json`](mcp-config.example.json) for curated server recommendations: +- **context7** — Live documentation lookup +- **playwright** — Browser automation (most token-efficient) +- **GitHub** — PRs, issues, code search -### Learning Categories +Rule: Start with 3 MCPs. Add only for concrete needs. -- Navigation (file paths, finding code) -- Editing (code changes, patterns) -- Testing (test approaches) -- Git (commits, branches) -- Quality (lint, types, style) -- Context (when to clarify) -- Architecture (design decisions) -- Performance (optimization) -- Claude-Code (sessions, modes, CLAUDE.md, skills, subagents, hooks, MCP) -- Prompting (scope, constraints, acceptance criteria) +## Cross-Agent Support -## Hooks +Works across 32+ AI coding agents via [SkillKit](https://agenstskills.com): -Automated enforcement of workflow patterns. +```mermaid +graph TD + PW[Pro Workflow] --> CC[Claude Code] + PW --> CU[Cursor] + PW --> SK[SkillKit] -| Hook | When | What | -|------|------|------| -| PreToolUse | Before edits | Track edit count, quality gate reminders | -| PreToolUse | Before git commit/push | Remind about quality gates, wrap-up | -| PostToolUse | After code edits | Check for console.log, TODOs, secrets | -| PostToolUse | After tests | Suggest [LEARN] from failures | -| UserPromptSubmit | Each prompt | Drift detection — warns when straying from original intent | -| SessionStart | New session | Load learnings from database | -| Stop | Each response | Context-aware reminders using `last_assistant_message` | -| SessionEnd | Session close | Save session stats to database | -| ConfigChange | Settings modified | Detect when quality gates or hooks are changed mid-session | + CC --> |"CLAUDE.md + hooks + agents"| CC + CU --> |".cursorrules + skills + agents"| CU -### Install Hooks + SK --> CO[Codex CLI] + SK --> GC[Gemini CLI] + SK --> WS[Windsurf] + SK --> MORE[27+ more] -```bash -# Full setup with hooks -git clone https://github.com/rohitg00/pro-workflow.git /tmp/pw -cp -r /tmp/pw/hooks/* ~/.claude/ -cp -r /tmp/pw/scripts ~/.claude/scripts/pro-workflow/ -cp -r /tmp/pw/commands/* ~/.claude/commands/ + style PW fill:#6366f1,color:#fff,stroke:none + style CC fill:#a78bfa,color:#fff,stroke:none + style CU fill:#f59e0b,color:#000,stroke:none + style SK fill:#22c55e,color:#fff,stroke:none ``` -## Contexts & Agents - -| Context | When | Behavior | -|---------|------|----------| -| dev | Building | Code first, iterate | -| review | PRs | Read-only, security focus | -| research | Exploring | Summarize, plan | - -| Agent | Purpose | -|-------|---------| -| planner | Break down complex tasks | -| reviewer | Code review, security audit | -| scout | Background confidence-gated exploration with worktree isolation | - -### Agent Teams (Experimental) - -Coordinate multiple Claude Code sessions working together: - ```bash -# Enable in settings.json -{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } } +npx skillkit install pro-workflow +npx skillkit translate pro-workflow --agent cursor +npx skillkit translate pro-workflow --agent codex +npx skillkit translate pro-workflow --agent gemini-cli ``` -- Lead session coordinates, teammates work independently -- Teammates message each other directly -- Shared task list with dependency management -- Display modes: in-process (`Shift+Down` to navigate, wraps around) or split panes (tmux/iTerm2) -- Delegate mode (`Shift+Tab`): lead orchestrates only -- Docs: https://code.claude.com/docs/agent-teams +See [`docs/cross-agent-workflows.md`](docs/cross-agent-workflows.md) for configuration mapping between Claude Code, Cursor, Codex, and Gemini CLI. ## Structure -``` +```text pro-workflow/ ├── .claude-plugin/ # Claude Code plugin -│ ├── plugin.json -│ ├── marketplace.json -│ ├── settings.json # Default permissions for quality gates -│ └── README.md ├── .cursor-plugin/ # Cursor plugin -│ └── plugin.json -├── skills/ # Shared skills (Cursor + Claude Code) +├── skills/ # 11 skills (Cursor + Claude Code) │ ├── pro-workflow/SKILL.md │ ├── smart-commit/SKILL.md -│ ├── wrap-up/SKILL.md -│ ├── learn-rule/SKILL.md -│ ├── parallel-worktrees/SKILL.md -│ ├── replay-learnings/SKILL.md -│ ├── session-handoff/SKILL.md -│ ├── insights/SKILL.md -│ └── deslop/SKILL.md -├── agents/ # Shared agents (Cursor + Claude Code) +│ ├── context-optimizer/SKILL.md +│ ├── orchestrate/SKILL.md +│ └── ... +├── agents/ # 5 agents │ ├── planner.md │ ├── reviewer.md -│ └── scout.md -├── rules/ # Rules -│ ├── core-rules.md # Claude Code rules -│ ├── quality-gates.mdc # Cursor rules -│ ├── atomic-commits.mdc -│ ├── context-discipline.mdc -│ ├── self-correction.mdc -│ ├── no-debug-statements.mdc -│ └── communication-style.mdc -├── commands/ # Claude Code commands -│ ├── wrap-up.md -│ ├── learn-rule.md +│ ├── scout.md +│ ├── orchestrator.md +│ └── debugger.md +├── commands/ # 10 slash commands +│ ├── develop.md # Multi-phase feature build +│ ├── doctor.md # Health check │ ├── commit.md -│ ├── insights.md -│ ├── replay.md -│ ├── handoff.md │ └── ... -├── hooks/ # Claude Code hooks +├── hooks/ # 18 hook events │ └── hooks.json -├── scripts/ # Hook scripts (includes config-watcher.js) -├── contexts/ # Context modes -│ ├── dev.md -│ ├── review.md -│ └── research.md +├── docs/ # Reference guides +│ ├── settings-guide.md +│ ├── cli-cheatsheet.md +│ ├── orchestration-patterns.md +│ ├── context-loading.md +│ ├── cross-agent-workflows.md +│ ├── new-features.md +│ └── daily-habits.md +├── rules/ # 6 Cursor rules +├── contexts/ # 3 context modes +├── templates/ # Split CLAUDE.md templates +├── references/ # Claude Code resources +├── scripts/ # Hook scripts +├── settings.example.json # Production settings template +├── mcp-config.example.json # Curated MCP recommendations ├── src/ # TypeScript source (SQLite) -│ ├── db/ -│ └── search/ -├── assets/ -│ └── logo.svg # Plugin logo -├── package.json -├── tsconfig.json -└── README.md +└── config.json ``` -## Learn Claude Code - -Pro-workflow teaches Claude Code best practices directly, with links to official documentation for deep dives. - -**Official Docs:** https://code.claude.com/docs/ +## Database Features -Topics covered: sessions, context management, modes, CLAUDE.md, prompting, writing rules, skills, subagents, hooks, MCP, security, and IDE integration. +Learnings stored in SQLite with FTS5 full-text search: -``` -/pro-workflow:learn # Best practices guide & save learnings -/pro-workflow:learn-rule # Capture corrections to memory -/pro-workflow:search claude-code # Find past Claude Code learnings +```text +~/.pro-workflow/ +└── data.db # SQLite database with learnings and sessions ``` -## SkillKit - Universal AI Skills - -**One skill. 32+ AI coding agents.** Install pro-workflow across Claude Code, Cursor, Codex, Gemini CLI, and more with [SkillKit](https://agenstskills.com). - ```bash -# Install this skill -npx skillkit install pro-workflow - -# Translate to any agent format -npx skillkit translate pro-workflow --agent cursor - -# Get AI-powered skill recommendations -npx skillkit primer +/search testing # Find all testing-related learnings +/search "file paths" # Exact phrase search ``` -**Why SkillKit?** -- Install once, use everywhere -- 15,000+ skills in the marketplace -- Works with Claude Code, Cursor, Codex, Gemini CLI, Windsurf, and 27+ more agents - -Explore the marketplace at [agenstskills.com](https://agenstskills.com) - ## Philosophy -1. **Compound improvements** - Small corrections → big gains over time +1. **Compound improvements** - Small corrections lead to big gains over time 2. **Trust but verify** - Let AI work, review at checkpoints 3. **Zero dead time** - Parallel sessions keep momentum 4. **Memory is precious** - Both yours and Claude's +5. **Orchestrate, don't micromanage** - Wire patterns together, let agents execute --- -## Support +## Quick Start (30 seconds) + +```bash +# Option A: Plugin install (Claude Code) +/plugin marketplace add rohitg00/pro-workflow +/plugin install pro-workflow@pro-workflow -If you find this useful: -- **Star this repo** to help others discover it -- Check out [SkillKit](https://agenstskills.com) for more AI coding skills -- [Report issues](https://github.com/rohitg00/pro-workflow/issues) or suggest improvements +# Option B: Plugin install (Cursor) +/add-plugin pro-workflow + +# Option C: Manual (any agent) +git clone https://github.com/rohitg00/pro-workflow.git /tmp/pw +cp -r /tmp/pw/templates/split-claude-md/* ./.claude/ + +# Then try it (use /pro-workflow: with plugin install): +/pro-workflow:develop add user authentication # Multi-phase feature build +/pro-workflow:doctor # Check your setup +/pro-workflow:wrap-up # End session properly +``` --- -*Distilled from Claude Code power users and real production use.* +

+
+ If you find this useful, star the repo to help others discover it. +

+ Stars +

+ SkillKit Marketplace • + Report Issues • + Reference Guides +

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

diff --git a/agents/debugger.md b/agents/debugger.md new file mode 100644 index 0000000..2fb7f62 --- /dev/null +++ b/agents/debugger.md @@ -0,0 +1,86 @@ +--- +name: debugger +description: Specialized debugging agent. Use when facing hard bugs, test failures, or runtime errors that need systematic investigation. +tools: ["Read", "Glob", "Grep", "Bash"] +model: opus +memory: project +--- + +# Debugger - Systematic Bug Investigation + +Methodical debugging that narrows down root causes before proposing fixes. + +## Workflow + +### 1. Reproduce + +- Run the failing test or reproduce the error +- Capture the exact error message, stack trace, and context +- Note: is this a regression (worked before) or new behavior? + +### 2. Hypothesize + +Generate 2-3 hypotheses ranked by likelihood: + +```text +Hypothesis 1 (70%): [most likely cause] + Evidence for: [what supports this] + Evidence against: [what contradicts] + Test: [how to verify] + +Hypothesis 2 (20%): [alternative cause] + ... + +Hypothesis 3 (10%): [unlikely but possible] + ... +``` + +### 3. Investigate + +Test each hypothesis starting with the most likely: + +- Read relevant code paths +- Check git log for recent changes to affected files +- Search for similar patterns that work correctly +- Add targeted debug output if needed + +### 4. Root Cause + +Present the confirmed root cause: + +```text +ROOT CAUSE: [what's actually wrong] +WHERE: [file:line] +WHY: [how it got this way] +SINCE: [when it was introduced, if knowable] +``` + +### 5. Fix Proposal + +Propose the minimal fix. Explain why this fix is correct. + +```text +FIX: [description] +CHANGES: + - file.ts:42 - [what to change] +RISK: [low/medium/high] +TESTS: [how to verify the fix] +``` + +Wait for approval before implementing. + +## Rules + +- Never guess. Investigate systematically. +- Never apply fixes without finding root cause first. +- Check the git blame — recent changes are more likely to be the cause. +- Use project memory to recall previous bugs in the same area. +- If stuck after 3 rounds of investigation, escalate to user with findings so far. +- Capture debugging learnings: `[LEARN] Debugging: ` + +## Anti-Patterns to Avoid + +- "Shotgun debugging" — changing random things hoping something works +- Ignoring stack traces — they tell you exactly where to look +- Not reproducing first — you can't fix what you can't see +- Fixing symptoms instead of root causes diff --git a/agents/orchestrator.md b/agents/orchestrator.md new file mode 100644 index 0000000..356f198 --- /dev/null +++ b/agents/orchestrator.md @@ -0,0 +1,81 @@ +--- +name: orchestrator +description: Multi-phase development agent. Research > Plan > Implement with validation gates. Use PROACTIVELY when building features that touch >5 files or require architecture decisions. +tools: ["Read", "Glob", "Grep", "Bash", "Edit", "Write"] +skills: ["pro-workflow"] +model: opus +memory: project +--- + +# Orchestrator - Multi-Phase Development + +Build features through three validated phases. Each phase must pass before the next begins. + +## Phase 1: Research (GO/NO-GO) + +Explore the codebase to assess feasibility. + +1. Find all relevant files and patterns +2. Check dependencies and constraints +3. Identify existing patterns to follow +4. Score confidence (0-100 across 5 dimensions) + +### Confidence Scoring + +- **Scope clarity** (0-20): Know exactly what files change? +- **Pattern familiarity** (0-20): Similar patterns exist in codebase? +- **Dependency awareness** (0-20): Know what depends on changed code? +- **Edge cases** (0-20): Can identify the edge cases? +- **Test strategy** (0-20): Know how to verify changes? + +Score >= 70 → GO to planning +Score < 70 → Gather more context, re-score. If < 70 after 2 rounds, ask user. + +## Phase 2: Plan (Approval Required) + +Design the solution. Present for approval before any code changes. + +### Output + +```text +PLAN: [Feature Name] + +Goal: [one sentence] + +Files to modify: +1. path/file.ts - [what changes, why] + +New files: +1. path/new-file.ts - [purpose] + +Approach: +1. [step with rationale] + +Risks: +- [potential issue and mitigation] + +Test strategy: +- [how to verify] + +Estimated scope: [S/M/L] +``` + +Wait for explicit "proceed" or "approved" before Phase 3. + +## Phase 3: Implement + +Execute the plan step by step. + +1. Make changes in the order specified in the plan +2. After each file: run relevant tests +3. After every 5 edits: pause for review checkpoint +4. After all changes: run full quality gates (lint, typecheck, test) +5. Present summary for final review + +## Rules + +- Never skip phases. Research before planning, plan before implementing. +- Never proceed without approval between phases. +- If implementation reveals the plan was wrong, go back to Phase 2. +- Use project memory to recall patterns from previous feature builds. +- Capture learnings at the end: `[LEARN] Category: Rule` diff --git a/assets/architecture.svg b/assets/architecture.svg new file mode 100644 index 0000000..2f0a7c8 --- /dev/null +++ b/assets/architecture.svg @@ -0,0 +1,107 @@ + + + + + + + + + + + + + + + + + + + + + Pro Workflow Architecture + Command > Agent > Skill Orchestration + + + + COMMANDS (User Entry Points) + + + /develop + + + /commit + + + /wrap-up + + + /doctor + + + /insights + + + /replay + + + + + + + AGENTS (Execution Layer) + + + orchestrator + Research > Plan > Build + + + reviewer + Security + Quality + + + planner + Read-Only Plans + + + scout + Background Explore + + + debugger + Root Cause Analysis + + + + + + + SKILLS (Domain Knowledge) + + + pro-workflow + + + smart-commit + + + wrap-up + + + orchestrate + + + +6 more + + + + HOOKS (18 Events) + + PreToolUse PostToolUse + SessionStart SubagentStart + TaskCompleted +12 more + + + + Works with: + Claude Code | Cursor | Codex | Gemini CLI | 32+ agents via SkillKit + diff --git a/assets/banner.svg b/assets/banner.svg new file mode 100644 index 0000000..0aaf77f --- /dev/null +++ b/assets/banner.svg @@ -0,0 +1,103 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Pro Workflow + Pro Workflow + v2.0 + Complete AI coding workflow system + + + + + 10 Patterns + + + 5 Agents + + + 18 Hooks + + + 11 Skills + + + 7 Guides + + + + + $ claude --worktree + $ /develop add auth + Research... GO (85/100) + Plan... approved + Implement... 5 files + Review... PASS + $ /wrap-up + 3 learnings captured + $ /commit + feat(auth): add login + Quality: PASS + + + + + diff --git a/assets/self-correction-demo.svg b/assets/self-correction-demo.svg new file mode 100644 index 0000000..314eca9 --- /dev/null +++ b/assets/self-correction-demo.svg @@ -0,0 +1,47 @@ + + + + + + + + + + + + + + + + + self-correction loop + + + + you: + No, that's the wrong file. The utils are in src/lib/ + + + claude: + You're right. I edited src/utils.ts but should have + edited src/lib/utils.ts. + + + [LEARN] Navigation: When multiple files share a name, + confirm the full path before editing. + + Add to LEARNED section? + + + you: + yes + + + Saved to LEARNED + (42 learnings total, applied 0 times) + + + --- next session --- + SessionStart: Loaded 42 learnings. Navigation rules active. + + diff --git a/assets/terminal-demo.svg b/assets/terminal-demo.svg new file mode 100644 index 0000000..4bc0e5e --- /dev/null +++ b/assets/terminal-demo.svg @@ -0,0 +1,57 @@ + + + + + + + + + + + + + + + + + + pro-workflow demo + + + + + + $ + /develop add webhook support for payment events + + + RESEARCH PHASE + Exploring codebase... + Found: src/payments/ (4 files), src/events/ (2 files) + Existing pattern: EventEmitter in src/events/bus.ts + Confidence: 85/100 + Scope clarity: 18/20 + Pattern familiarity: 17/20 + Dependencies: 18/20 + Edge cases: 16/20 + Test strategy: 16/20 + VERDICT: GO + + + PLAN + 1. src/payments/webhook.ts new: webhook handler + 2. src/events/bus.ts add: payment events + 3. src/payments/types.ts add: WebhookEvent type + 4. tests/payments/webhook.test new: webhook tests + + ? + Proceed with plan? + approved + + + IMPLEMENTING + [1/4] webhook.ts DONE tests: 3/3 pass + [2/4] bus.ts DONE tests: 8/8 pass + [3/4] types.ts ... + + diff --git a/assets/workflow-flow.svg b/assets/workflow-flow.svg new file mode 100644 index 0000000..b5335ca --- /dev/null +++ b/assets/workflow-flow.svg @@ -0,0 +1,88 @@ + + + + + + + + + + + + + + + + + The /develop Flow + Multi-phase development with validation gates + + + + 1. Research + Explore codebase + Score confidence + GO if >= 70 + + + + + + + GO? + + + + + + + 2. Plan + Design solution + List all changes + Identify risks + + + + + + + OK? + + + + + + + 3. Implement + Execute plan + Quality gates / 5 edits + Run tests + + + + + + + 4. Review + Security + Quality + Commit + + + + Hooks firing throughout: + + SubagentStart + UserPromptSubmit + PostToolUse + PreToolUse + TaskCompleted + Stop + + drift-detector + quality-gate + post-edit-check + learn-capture + session-check + session-end + diff --git a/commands/develop.md b/commands/develop.md new file mode 100644 index 0000000..1bc2492 --- /dev/null +++ b/commands/develop.md @@ -0,0 +1,79 @@ +--- +description: Build a feature using Research > Plan > Implement phases +argument-hint: +--- + +# /develop - Multi-Phase Feature Development + +Build features through structured phases with validation gates. + +## Feature: $ARGUMENTS + +### Phase 1: Research + +Explore the codebase to understand the scope: + +1. Find all relevant files and existing patterns +2. Check dependencies and constraints +3. Score confidence across 5 dimensions (0-100) + +**Scoring:** +- Scope clarity (0-20): Know exactly what files change? +- Pattern familiarity (0-20): Similar patterns exist? +- Dependency awareness (0-20): Know what depends on changed code? +- Edge cases (0-20): Can identify the edge cases? +- Test strategy (0-20): Know how to verify? + +**Decision:** +- Score >= 70 → Present research findings and move to Phase 2 +- Score < 70 → Identify gaps, gather more context, re-score + +### Phase 2: Plan + +Present a plan for approval: + +```text +PLAN: [Feature Name] + +Goal: [one sentence] + +Files to modify: +1. path/file.ts - [what changes] + +New files: +1. path/new.ts - [purpose] + +Approach: +1. [step with rationale] + +Risks: +- [potential issue and mitigation] + +Test strategy: +- [how to verify] +``` + +**Wait for "proceed" or "approved" before continuing.** + +### Phase 3: Implement + +Execute the approved plan: + +1. Make changes in plan order +2. Run tests after each file change +3. Pause for review every 5 edits +4. Run full quality gates at the end (lint, typecheck, test) + +### Phase 4: Review & Commit + +1. Self-review all changes for issues +2. Check for console.log, TODOs, secrets +3. Present summary for final approval +4. Commit with conventional message + +### Learning Capture + +After completing, ask: +- What corrections were made during implementation? +- Any patterns worth adding to LEARNED? +- Format: `[LEARN] Category: Rule` diff --git a/commands/doctor.md b/commands/doctor.md new file mode 100644 index 0000000..aa51298 --- /dev/null +++ b/commands/doctor.md @@ -0,0 +1,85 @@ +--- +description: Diagnose pro-workflow setup and Claude Code configuration +--- + +# /doctor - Configuration Health Check + +Run a diagnostic on your pro-workflow and Claude Code setup. + +## Check These + +### 1. Pro-Workflow Installation +```bash +ls -la ~/.claude/commands/wrap-up.md 2>/dev/null && echo "Commands: OK" || echo "Commands: MISSING" +ls -la ~/.pro-workflow/data.db 2>/dev/null && echo "Database: OK" || echo "Database: MISSING" +``` + +### 2. Hooks Status +Check if hooks.json is loaded and hooks are active. Run: +```bash +cat ~/.claude/settings.local.json 2>/dev/null | head -5 +``` + +If hooks aren't firing, check: +- hooks.json is in the right location +- Script paths use `${CLAUDE_PLUGIN_ROOT}` or absolute paths +- Scripts have execute permissions + +### 3. Context Health +```text +/context +``` +- Usage < 70%: Healthy +- Usage 70-90%: Consider `/compact` +- Usage > 90%: Compact immediately or start fresh + +### 4. MCP Servers +Check active MCPs. Target: <10 servers, <80 tools. + +### 5. CLAUDE.md Size +```bash +wc -l CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found" +``` +- < 60 lines: Ideal +- 60-150 lines: Acceptable +- > 150 lines: Too long, split into modules + +### 6. Git Status +```bash +git status --short +git stash list +``` +- Uncommitted changes? Commit or stash. +- Stale stashes? Clean up. + +### 7. Settings Validation +```bash +cat .claude/settings.json 2>/dev/null | head -3 +cat ~/.claude/settings.json 2>/dev/null | head -3 +``` +- Check for conflicting settings between project and user level +- Verify permission rules are correct + +## Quick Fixes + +| Issue | Fix | +|-------|-----| +| Commands missing | `cp -r /path/to/pro-workflow/commands/* ~/.claude/commands/` | +| Database missing | `mkdir -p ~/.pro-workflow && npm run build` (in plugin dir) | +| Hooks not firing | Check paths in hooks.json use absolute paths | +| Context degraded | Run `/compact` or start fresh session | +| Too many MCPs | Disable unused: `disabledMcpjsonServers` in settings | +| CLAUDE.md too long | Split into root + package-level files | + +## Report + +After running checks, summarize: +```text +Pro-Workflow Health Check + Installation: OK / NEEDS SETUP + Hooks: ACTIVE / INACTIVE + Context: XX% (healthy/warning/critical) + MCPs: X active (OK / TOO MANY) + CLAUDE.md: XX lines (OK / SPLIT RECOMMENDED) + Git: clean / X uncommitted files +``` diff --git a/docs/cli-cheatsheet.md b/docs/cli-cheatsheet.md new file mode 100644 index 0000000..4a72518 --- /dev/null +++ b/docs/cli-cheatsheet.md @@ -0,0 +1,182 @@ +# CLI Cheatsheet + +Every CLI flag and keyboard shortcut organized by workflow. + +## Startup Flags + +### Session Management + +```bash +claude # New session +claude --continue # Continue last session +claude --resume # Pick from recent sessions +claude --from-pr 123 # Start from a PR's context +claude --session-id # Resume specific session +claude --fork-session # Fork an existing session +``` + +### System Prompt + +```bash +claude --system-prompt "You are a Go expert" +claude --system-prompt-file ./prompts/go.md +claude --append-system-prompt "Also run tests after changes" +``` + +### Agent & Subagent Control + +```bash +claude --agent researcher # Run with specific agent +claude --agents '{"name":"researcher","tools":["Read","Grep"]}' +claude --teammate-mode # Launch as a teammate in agent teams +``` + +### Permission Control + +```bash +claude --permission-mode plan # Force plan mode +claude --allowedTools Read,Grep # Whitelist specific tools +claude --disallowedTools Bash # Blacklist tools +``` + +### Output & Scripting + +```bash +claude --print "explain this code" # One-shot, no interactive +claude --output-format json # JSON output for scripting +claude --json-schema '{"type":"object"}' # Structured output +claude --verbose # Debug output +``` + +### Budget & Limits + +```bash +claude --max-budget-usd 5.00 # Cap spending +claude --max-turns 50 # Limit conversation turns +``` + +### Workspace + +```bash +claude --worktree # or -w: auto-create git worktree +claude --add-dir ../lib # Add extra directory to context +``` + +### MCP & Plugins + +```bash +claude --mcp-config ./mcp.json # Load MCP config +claude --strict-mcp-config # Fail if MCP server errors +claude --plugin-dir ./my-plugin # Load a plugin directory +``` + +### Integration + +```bash +claude --chrome # Enable Chrome integration +claude --no-chrome # Disable Chrome integration +claude --ide vscode # Set IDE context +``` + +## Keyboard Shortcuts + +### During Prompting + +| Key | Action | +|-----|--------| +| `Enter` | Submit prompt | +| `Shift+Tab` | Cycle modes (Normal > Auto > Plan) | +| `Ctrl+C` | Cancel current generation | +| `Ctrl+L` | Clear screen | +| `Ctrl+B` | Send current task to background | +| `Ctrl+F` | Kill all background agents (two-press) | +| `Up/Down` | Navigate prompt history | +| `Esc Esc` | Rewind to last checkpoint | + +### Agent Teams + +| Key | Action | +|-----|--------| +| `Shift+Down` | Navigate between teammates (wraps) | +| `Shift+Tab` | Toggle delegate mode | + +## Slash Commands + +### Session + +| Command | Purpose | +|---------|---------| +| `/clear` | Reset conversation | +| `/compact` | Compress context (do at task boundaries) | +| `/context` | Show context window usage | +| `/resume` | Resume a previous session | +| `/rename` | Rename current session | +| `/cost` | Show session cost (API key users) | +| `/usage` | Check plan limits | +| `/extra-usage` | Pay-as-you-go overflow billing | + +### Modes & Models + +| Command | Purpose | +|---------|---------| +| `/model` | Switch model or effort level | +| `/fast` | Toggle fast mode | +| `/voice` | Toggle voice mode (hold spacebar to talk) | + +### Project + +| Command | Purpose | +|---------|---------| +| `/permissions` | Manage tool permissions | +| `/agents` | Create and manage subagents | +| `/memory` | View/edit auto memory | +| `/doctor` | Diagnose configuration issues | + +### Configuration + +| Command | Purpose | +|---------|---------| +| `/config` | Open settings | +| `/terminal-setup` | Configure terminal | +| `/statusline` | Customize status bar | +| `/keybindings` | Customize keyboard shortcuts | +| `/sandbox` | Configure sandboxing | +| `/vim` | Toggle vim keybindings | + +### Export & Debug + +| Command | Purpose | +|---------|---------| +| `/export` | Export conversation | +| `/debug` | Toggle debug mode | +| `/rewind` | Rewind to checkpoint | + +## Scripting Patterns + +### One-Shot Execution + +```bash +echo "explain this error" | claude --print +``` + +### Capture Session ID + +```bash +SESSION_ID=$(claude --output-format json --print "fix the bug" | jq -r '.session_id') +claude --session-id "$SESSION_ID" --print "now add tests" +``` + +### Budget-Controlled CI + +```bash +claude --max-budget-usd 2.00 --max-turns 20 --print "review this PR" +``` + +## Pro Tips + +- **`ultrathink`** in your prompt triggers maximum reasoning effort +- **`/doctor`** diagnoses config issues — run when things feel off +- **Manual `/compact` at 50%** prevents the "agent dumb zone" near capacity +- **`/rename` your sessions** — easier to find with `/resume` later +- **`claude -w`** is faster than manually creating worktrees +- **Voice mode** (`/voice`) — hold spacebar, speak, release to transcribe diff --git a/docs/context-loading.md b/docs/context-loading.md new file mode 100644 index 0000000..78ebc03 --- /dev/null +++ b/docs/context-loading.md @@ -0,0 +1,158 @@ +# Context Loading: How CLAUDE.md Works in Monorepos + +Understanding how Claude Code loads memory files is critical for large projects. + +## Two Loading Mechanisms + +### 1. Ancestor Loading (UP the tree) + +When you start Claude Code, it walks UP from your current directory to the root, loading every `CLAUDE.md` it finds. + +```text +/ ← loaded (if exists) +├── CLAUDE.md ← loaded at startup +├── packages/ +│ ├── CLAUDE.md ← loaded at startup (you're deeper) +│ ├── api/ +│ │ ├── CLAUDE.md ← loaded at startup (you started here) +│ │ └── src/ +│ └── web/ +│ ├── CLAUDE.md ← NOT loaded (sibling) +│ └── src/ +``` + +**Running from `packages/api/`**: loads root, packages, and api CLAUDE.md files. +**Running from `packages/web/`**: loads root, packages, and web CLAUDE.md files. + +Siblings never load each other. + +### 2. Descendant Loading (DOWN, lazy) + +When Claude reads or edits a file in a subdirectory, it lazy-loads that directory's CLAUDE.md. + +```bash +# You start at root. Claude reads packages/web/src/app.tsx +# → packages/web/CLAUDE.md gets lazy-loaded into context +``` + +This happens automatically. You don't control it. + +## What This Means for Monorepos + +### Good Structure + +```text +monorepo/ +├── CLAUDE.md # Shared: repo conventions, build commands +├── packages/ +│ ├── api/ +│ │ ├── CLAUDE.md # API-specific: endpoints, auth patterns +│ │ └── src/ +│ ├── web/ +│ │ ├── CLAUDE.md # Frontend-specific: component patterns +│ │ └── src/ +│ └── shared/ +│ ├── CLAUDE.md # Shared library conventions +│ └── src/ +``` + +### Root CLAUDE.md (< 60 lines ideal, < 150 max) + +Keep it lean. This loads every session regardless of where you work. + +```markdown +# MyProject + +## Build +pnpm build # Build all packages +pnpm test # Run all tests +pnpm lint # Lint everything + +## Conventions +- TypeScript strict mode +- snake_case for database, camelCase for code +- All API responses follow RFC 7807 for errors + +## Packages +- `packages/api` - Express REST API +- `packages/web` - Next.js frontend +- `packages/shared` - Shared types and utils +``` + +### Package CLAUDE.md + +Detailed, package-specific context. Only loads when working in that package. + +```markdown +# API Package + +## Run +pnpm dev # Start with hot reload on :3001 +pnpm test # Jest with --coverage + +## Architecture +- Express + Prisma + PostgreSQL +- Auth: JWT with refresh tokens in httpOnly cookies +- Rate limiting: Redis sliding window + +## Gotchas +- Prisma client must be regenerated after schema changes: pnpm prisma generate +- Test database is SQLite (different from prod PostgreSQL) +``` + +## CLAUDE.local.md + +For personal preferences. Gitignored. + +```markdown +# My Preferences (not committed) +- I prefer verbose test output +- Always show file paths in suggestions +- My editor is Neovim +``` + +## Skills Loading (Different from CLAUDE.md) + +Skills do NOT follow ancestor/descendant loading. They have fixed discovery locations: + +```text +1. Enterprise policies (managed) +2. ~/.claude/skills/ (user-global) +3. .claude/skills/ (project) +4. Plugins +``` + +Skills from nested `.claude/skills/` directories ARE discovered automatically when Claude accesses files in those directories. + +Key difference: skill descriptions are always in context (for the `/` menu), but full skill content is only loaded on invocation. This keeps context lean. + +### Character Budget + +If you have many skills, they share a character budget for descriptions. Set `SLASH_COMMAND_TOOL_CHAR_BUDGET` env var to increase the limit if needed. + +## Agent Memory (Persistent per Agent) + +Agents with `memory: user` get their own MEMORY.md: + +```text +~/.claude/agent-memory//MEMORY.md +``` + +- First 200 lines injected at agent startup +- Agent auto-curates: creates topic files, links from MEMORY.md +- Three scopes: `user` (global), `project` (per-project), `local` (per-directory) + +This is different from CLAUDE.md — it's agent-specific and self-managed. + +## Memory Systems Comparison + +| System | Scope | Managed By | When Loaded | +|--------|-------|-----------|-------------| +| CLAUDE.md | Project | You | Every session (ancestors), lazy (descendants) | +| CLAUDE.local.md | Personal | You | Every session (gitignored) | +| Auto Memory | User | Claude | Session start (first 200 lines) | +| Agent Memory | Per-agent | Agent | Agent invocation | +| `/memory` command | User | You | On demand | +| Pro-Workflow DB | User | Hooks | Session start (via SessionStart hook) | + +These systems are complementary. Use CLAUDE.md for project conventions, auto memory for personal patterns, and agent memory for specialized agent knowledge. diff --git a/docs/cross-agent-workflows.md b/docs/cross-agent-workflows.md new file mode 100644 index 0000000..cf1a205 --- /dev/null +++ b/docs/cross-agent-workflows.md @@ -0,0 +1,176 @@ +# Cross-Agent Workflows + +How to use pro-workflow patterns across Claude Code, Cursor, Codex, and other AI coding agents. + +## The Layered Approach + +The most productive teams in 2026 don't choose one tool — they layer them: + +| Layer | Tool | Strength | +|-------|------|----------| +| Editor | Cursor / VS Code + Copilot | Tab completions, inline edits, visual diffs | +| Terminal | Claude Code / Codex CLI | Deep reasoning, multi-file changes, CI/CD | +| Background | Cursor Background Agents | Long-running tasks, PR creation | +| Review | Claude Code reviewer agent | Security audit, code quality | + +### Common Setup + +```text +Cursor for daily coding (tab completions, inline edits) + └── Claude Code in Cursor's terminal (hard problems, refactors) + └── Subagents for parallel exploration +``` + +The overlap in capabilities is worth the combined cost. + +## Configuration Mapping + +### Claude Code → Cursor + +| Claude Code | Cursor Equivalent | +|-------------|-------------------| +| `CLAUDE.md` | `.cursorrules` or `.cursor/rules/*.mdc` | +| `.claude/settings.json` | `.cursor/settings.json` | +| `.claude/agents/*.md` | `.cursor/agents/*.md` (v2.4+) | +| `.claude/skills/*/SKILL.md` | `.cursor/skills/*/SKILL.md` (v2.4+) | +| `.claude/commands/*.md` | Built-in `/` commands | +| `hooks.json` | Not supported (use rules instead) | +| `.mcp.json` | `.cursor/mcp.json` | + +### Claude Code → Codex CLI + +| Claude Code | Codex Equivalent | +|-------------|-----------------| +| `CLAUDE.md` | `AGENTS.md` | +| Settings | `codex.json` | +| Agents | Not supported | +| Skills | Not supported | +| Hooks | Not supported | +| MCP | Supported via config | + +### Claude Code → Gemini CLI + +| Claude Code | Gemini Equivalent | +|-------------|-------------------| +| `CLAUDE.md` | `GEMINI.md` | +| Settings | `gemini.json` | +| Agents | Not supported | +| Skills | Not supported | + +## Pro-Workflow on Each Agent + +### Claude Code (Full Support) + +Everything works: commands, agents, skills, hooks, rules, contexts, MCP config. + +```bash +/plugin marketplace add rohitg00/pro-workflow +/plugin install pro-workflow@pro-workflow +``` + +### Cursor (Skills + Rules) + +Uses skills (.mdc rules) instead of hooks. Same patterns, different enforcement. + +```bash +/add-plugin pro-workflow +``` + +What loads: +- 9 skills (pro-workflow, smart-commit, wrap-up, learn-rule, etc.) +- 6 rules (quality-gates, atomic-commits, context-discipline, etc.) +- 3 agents (planner, reviewer, scout) + +### Other Agents (via SkillKit) + +```bash +npx skillkit install pro-workflow +npx skillkit translate pro-workflow --agent codex +npx skillkit translate pro-workflow --agent gemini-cli +npx skillkit translate pro-workflow --agent windsurf +``` + +SkillKit translates the SKILL.md format to each agent's native format. + +## Shared Patterns That Work Everywhere + +These patterns are agent-agnostic: + +### 1. Self-Correction Loop +Works in any agent that reads a memory file. Add to CLAUDE.md / .cursorrules / AGENTS.md: +```markdown +When corrected, propose a rule. After approval, append to LEARNED section. +``` + +### 2. Plan Before Multi-File Changes +Universal pattern. Every agent benefits from planning mode: +- Claude Code: `Shift+Tab` to plan mode +- Cursor: Agent mode with planning prompt +- Codex: Start with "plan this before implementing" + +### 3. Quality Gates Before Commit +Add to any agent's rules: +```markdown +Before committing: run lint, typecheck, and tests. Fix failures before proceeding. +``` + +### 4. Context Management +Every agent has finite context. The discipline is the same: +- Read before edit +- Compact/clear at task boundaries +- Delegate heavy exploration to subagents +- Keep <10 MCP servers, <80 tools + +### 5. Session Handoffs +End sessions intentionally. Capture state for the next session: +```markdown +When ending a session: +1. List what's done, in progress, and pending +2. Note any decisions made and why +3. Write a one-line resume prompt for next session +``` + +## Background Agent Patterns + +### Claude Code +```bash +Ctrl+B # Send to background +claude -w # Worktree for parallel session +``` + +### Cursor +Background agents run on isolated VMs. They can: +- Work on separate branches +- Open PRs for review +- Record video of their work +- Run indefinitely + +### When to Use Each + +| Task | Claude Code | Cursor | +|------|-------------|--------| +| Quick exploration | Subagent (in-process) | Tab in sidebar | +| Long refactor | Worktree session | Background agent | +| PR creation | `gh pr create` in session | Background agent auto-PR | +| Code review | Reviewer agent | Inline review comments | + +## MCP Server Sharing + +MCP servers work across both Claude Code and Cursor. Share a single `.mcp.json`: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + }, + "playwright": { + "command": "npx", + "args": ["-y", "@anthropic/mcp-playwright"] + } + } +} +``` + +Place at project root. Both tools discover it. diff --git a/docs/daily-habits.md b/docs/daily-habits.md new file mode 100644 index 0000000..7881dc6 --- /dev/null +++ b/docs/daily-habits.md @@ -0,0 +1,122 @@ +# Daily Habits for AI-Assisted Development + +Practical habits organized by frequency. Tested across Claude Code, Cursor, and Codex workflows. + +## Every Session + +### Start Right +- Run `/doctor` if things feel off +- Check context with `/context` — know your budget +- Name your session with `/rename` for easy `/resume` later +- For returning tasks: `/replay ` to surface past learnings + +### During Work +- **Commit early, commit often** — as soon as a logical unit is done +- **Manual `/compact` at 50%** — don't wait for auto-compact at 95% (the "dumb zone") +- **Read before edit** — always understand what's there before changing it +- **Plan mode for multi-file changes** — `Shift+Tab` to toggle +- **Subagents for heavy lifting** — delegate exploration, tests, docs + +### Before Ending +- Run `/wrap-up` — audit changes, capture learnings +- Or at minimum: `git status`, check for uncommitted work +- Generate `/handoff` if continuing later + +## Every Day + +### Update +- Keep Claude Code updated (it auto-updates, but check) +- Read the changelog for new features +- Review your `LEARNED.md` — prune stale rules + +### Terminal Setup +- Use a capable terminal: iTerm2, Ghostty, Warp, or Kitty +- Avoid IDE embedded terminals for heavy Claude Code sessions +- tmux for split pane agent teams +- Short alias: `alias c='claude'` + +### Monitor Usage +- `/usage` to check plan limits +- `/cost` for API key users +- Watch for fast mode billing (charges extra usage from first token) + +## Every Week + +### Review Patterns +- Run `/insights` to see correction trends +- Identify hot learnings (corrected often, not learned) +- Prune cold learnings (learned but never applied) + +### Optimize CLAUDE.md +- Keep root CLAUDE.md under 150 lines +- Move specialized knowledge to package-level CLAUDE.md files +- Move personal preferences to CLAUDE.local.md (gitignored) + +## Debugging Tips + +### When Claude Gets Stuck +1. Try a different model — switch to Opus for hard problems +2. Use `ultrathink` in your prompt for maximum reasoning +3. Provide a screenshot (Claude is multimodal) +4. Share browser console logs via MCP +5. Start a fresh session with more targeted context + +### When Context Is Degraded +1. Run `/compact` manually +2. Or start a new session with `/resume` +3. Set `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50` for proactive compaction +4. Use subagents to isolate heavy output (test results, logs) + +### When You're Blocked +1. `/doctor` for configuration issues +2. Try a different approach — don't brute force +3. Use the `debugger` agent for systematic investigation +4. Check if it's a model limitation vs. a prompt issue +5. Ask Claude to "think step by step about why this isn't working" + +## Environment Tips + +### Terminal Recommendations + +| Terminal | Platform | Why | +|----------|----------|-----| +| iTerm2 | macOS | Split panes, tmux integration | +| Ghostty | macOS/Linux | Fast, GPU-rendered | +| Warp | macOS | AI-native, blocks | +| Kitty | Cross-platform | GPU-rendered, scriptable | +| Windows Terminal | Windows | WSL support | + +### Voice Prompting + +If you have voice mode access: +- `/voice` to enable +- Hold spacebar → speak → release +- Great for: describing bugs, architecture discussions, code reviews +- Mix with typed input for precise file paths + +### Tool Layering + +The most productive setup uses multiple tools: + +```text +Primary editor (Cursor/VS Code) + ├── Tab completions for small edits + ├── Inline chat for quick questions + └── Claude Code in terminal for: + ├── Multi-file changes + ├── Debugging hard issues + ├── Architecture decisions + └── CI/CD and git operations +``` + +## Anti-Patterns + +| Don't | Do Instead | +|-------|-----------| +| Skip quality gates to save time | Gates prevent more corrections later | +| Use `dontAsk` permission mode daily | Use `default` with specific allow rules | +| Load 15+ MCP servers | Keep <10 active, disable unused | +| Compact mid-task | Compact at task boundaries | +| Fight the AI on style | Add rules to CLAUDE.md instead | +| Use one huge CLAUDE.md | Split into root + package-level files | +| Ignore the correction pattern | Every correction is a learning opportunity | diff --git a/docs/new-features.md b/docs/new-features.md new file mode 100644 index 0000000..00fd4d5 --- /dev/null +++ b/docs/new-features.md @@ -0,0 +1,198 @@ +# New Claude Code Features (2026) + +Latest capabilities and how to use them with pro-workflow. + +## Voice Mode + +Talk to Claude Code instead of typing. Rolling out to Pro, Max, Team, and Enterprise plans. + +### Setup + +```bash +/voice # Toggle voice mode on/off +``` + +### Usage + +- Hold **spacebar** to talk, release to transcribe +- Mix typed and spoken input in a single prompt +- Works alongside all other features (hooks still fire, modes still apply) + +### When Voice Helps + +| Scenario | Why Voice | +|----------|----------| +| Describing architecture | Faster than typing long descriptions | +| Quick fixes | "Fix the import on line 42" | +| Exploring ideas | Stream-of-consciousness brainstorming | +| Reviewing code | "Walk me through this function" | + +### Pro-Workflow Integration + +Voice mode works with all pro-workflow patterns. Corrections spoken verbally still trigger the self-correction loop if you say "remember that" or "add to rules". + +## Agent Teams + +Coordinate multiple Claude Code sessions working as a team. + +### Enable + +```json +{ + "env": { + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" + } +} +``` + +### How It Works + +1. One session is the **lead** — coordinates work, assigns tasks +2. **Teammates** work independently in their own context windows +3. Teammates message each other directly (not just report to lead) +4. Shared task list with dependency tracking + +### Display Modes + +| Mode | How | Best For | +|------|-----|----------| +| In-process | `Shift+Down` to navigate | Quick coordination | +| Split panes | tmux or iTerm2 splits | Visual monitoring | + +### Delegate Mode + +Press `Shift+Tab` to toggle delegate mode. Lead orchestrates only, no direct code edits. + +### Team Patterns + +| Pattern | Lead | Teammate A | Teammate B | +|---------|------|-----------|-----------| +| Frontend/Backend | Coordinate | UI changes | API changes | +| Feature/Tests | Plan | Implementation | Test coverage | +| Competing hypotheses | Evaluate | Approach A | Approach B | +| Cross-layer | Integrate | Database | Application | + +### Docs + +https://code.claude.com/docs/agent-teams + +## Checkpointing & Rewind + +Claude Code automatically tracks checkpoints during your session. + +### Usage + +- **`Esc Esc`** — Rewind to the last checkpoint +- **`/rewind`** — Browse and select a checkpoint to restore +- Checkpoints are git-based — your code state is saved at each point + +### When to Rewind + +- Claude went down the wrong path +- An approach isn't working out +- You want to try a different solution +- Something broke that was previously working + +### Pro-Workflow Integration + +The `PreCompact` hook saves context state, which complements checkpointing. Between checkpoints (code state) and pre-compact saves (context state), you can recover from most mistakes. + +## Remote Control + +Continue sessions from phone, tablet, or browser. + +### How It Works + +- Start Claude Code on your machine +- Access it remotely via `--remote` flag +- Continue interacting from any device +- Session state persists + +### Headless Mode + +Run Claude Code without a terminal UI for CI/CD and automation: + +```bash +claude --print "review and fix lint errors" --max-turns 10 +``` + +## New Hook Events + +Claude Code has expanded from 8 to 18+ hook event types. + +### Newly Available + +| Event | When | Use Case | In hooks.json | +|-------|------|----------|:-------------:| +| `SubagentStart` | Subagent spawns | Log agent activity, set up context | Yes | +| `SubagentStop` | Subagent finishes | Collect results, update metrics | Yes | +| `TaskCompleted` | Task marked complete | Quality gate on completion | Yes | +| `PermissionRequest` | Permission dialog | Flag dangerous operations | Yes | +| `PostToolUseFailure` | Tool use fails | Error tracking, retry logic | Yes | +| `TeammateIdle` | Team member goes idle | Force continuation, reassign | Yes | +| `ConfigChange` | Settings modified | Detect mid-session changes | Yes | +| `Setup` | Initial setup (30s timeout) | One-time initialization | No | +| `WorktreeCreate` | Worktree created | Set up worktree-specific config | No | +| `WorktreeRemove` | Worktree removed | Cleanup | No | + +Events marked "No" are available in Claude Code but not configured in `hooks.json` by default. Add them to your `hooks.json` or `settings.local.json` as needed. + +### Hook Types + +| Type | How It Works | +|------|-------------| +| `command` | Run shell script, receive JSON on stdin | +| `prompt` | Single-turn model evaluation (Haiku default) | +| `agent` | Multi-turn subagent with Read/Grep/Glob (up to 50 turns) | + +### Agent Hooks Example + +```json +{ + "PostToolUse": [{ + "matcher": "tool == 'Edit'", + "hooks": [{ + "type": "agent", + "agent": "reviewer", + "prompt": "Review this edit for security issues", + "timeout": 30000 + }] + }] +} +``` + +### Prompt Hooks Example + +```json +{ + "PreToolUse": [{ + "matcher": "tool == 'Bash' && tool_input.command matches 'rm'", + "hooks": [{ + "type": "prompt", + "prompt": "Is this rm command safe? Check for wildcards and critical paths.", + "model": "haiku" + }] + }] +} +``` + +## Extra Usage & Billing + +### Check Your Usage + +| Command | Shows | +|---------|-------| +| `/usage` | Plan limits and remaining | +| `/extra-usage` | Pay-as-you-go overflow ($2,000/day cap) | +| `/cost` | Current session cost (API key users) | + +### Fast Mode Billing + +Fast mode is always billed to extra usage from the first token, even if you have remaining plan usage. Toggle with `/fast`. + +### Budget Control + +```bash +claude --max-budget-usd 5.00 # Cap at $5 +claude --max-turns 50 # Limit turns +``` diff --git a/docs/orchestration-patterns.md b/docs/orchestration-patterns.md new file mode 100644 index 0000000..e050cb9 --- /dev/null +++ b/docs/orchestration-patterns.md @@ -0,0 +1,294 @@ +# Orchestration Patterns + +How to wire Commands, Agents, and Skills together for complex workflows. + +## The Three Layers + +```text +Command (entry point, user-facing) + └── Agent (execution, constrained tools) + └── Skill (domain knowledge, preloaded) +``` + +Each layer has a single responsibility: +- **Commands** handle user interaction and parameter collection +- **Agents** execute workflows with constrained tool access +- **Skills** provide domain-specific knowledge and procedures + +## Pattern 1: Command > Agent > Skill + +The most powerful pattern. A slash command delegates to an agent that has skills preloaded. + +### Example: Feature Builder + +**Command** (`commands/build-feature.md`): +```markdown +--- +description: Build a feature end-to-end with planning, implementation, and tests +argument-hint: +--- + +Build this feature using a structured approach: + +1. Delegate to the planner agent to create a plan +2. Wait for plan approval +3. Implement the plan +4. Run quality gates +5. Create a commit + +Feature: $ARGUMENTS +``` + +**Agent** (`agents/planner.md`): +```yaml +--- +name: planner +description: Break down tasks into plans +tools: ["Read", "Glob", "Grep"] +skills: ["api-conventions", "project-patterns"] +model: opus +--- +``` + +**Skill** (`skills/api-conventions/SKILL.md`): +```yaml +--- +name: api-conventions +description: API design patterns for this project +user-invocable: false +--- + +REST endpoints use camelCase. Auth via Bearer tokens. +Error responses follow RFC 7807. +``` + +### How It Flows + +1. User runs `/build-feature add user preferences` +2. Command expands `$ARGUMENTS` and delegates to planner agent +3. Planner loads with `api-conventions` skill already in context +4. Planner explores code, produces plan using skill knowledge +5. Control returns to command for approval +6. Implementation proceeds with full context + +## Pattern 2: Multi-Phase Development (RPI) + +Research > Plan > Implement with validation gates between phases. + +### Structure + +```text +.claude/ +├── commands/ +│ └── develop.md # Entry point +├── agents/ +│ ├── researcher.md # Phase 1: explore and validate +│ ├── architect.md # Phase 2: design +│ └── implementer.md # Phase 3: build +└── skills/ + └── project-patterns/ + └── SKILL.md # Shared knowledge +``` + +### The Flow + +```text +/develop "add webhook support" + │ + ▼ +[Research Phase] → researcher agent + │ - Explore existing code + │ - Find similar patterns + │ - Check dependencies + │ - Score confidence (0-100) + │ + ├── Score < 70 → HOLD (ask user for more context) + │ + ▼ +[Plan Phase] → architect agent + │ - Design the solution + │ - List all files to change + │ - Identify risks + │ - Present plan for approval + │ + ├── User rejects → Back to research + │ + ▼ +[Implement Phase] → implementer agent + │ - Execute the plan step by step + │ - Run tests after each step + │ - Quality gates at checkpoints + │ + ▼ +[Verify] → reviewer agent + │ - Code review the changes + │ - Security check + │ - Performance check + │ + ▼ +[Commit] → /commit command +``` + +### Researcher Agent + +```yaml +--- +name: researcher +description: Explore codebase to assess feasibility before implementation +tools: ["Read", "Glob", "Grep", "Bash"] +background: true +isolation: worktree +memory: project +--- +``` + +Key: runs in background with worktree isolation so it doesn't block the main session. + +### Architect Agent + +```yaml +--- +name: architect +description: Design implementation plans with risk assessment +tools: ["Read", "Glob", "Grep"] +skills: ["project-patterns"] +model: opus +--- +``` + +Key: read-only tools, Opus model for deep reasoning, preloaded project patterns. + +## Pattern 3: Agent Skills vs On-Demand Skills + +Two ways to use skills — understand when to use each. + +### Agent Skills (Preloaded) + +```yaml +# In agent frontmatter +skills: ["api-conventions", "error-handling"] +``` + +- Full skill content injected into agent context at startup +- Always available, no invocation needed +- Use for: domain knowledge the agent always needs +- Cost: uses context tokens + +### On-Demand Skills (Invoked) + +```yaml +# In skill frontmatter +user-invocable: true +``` + +- User runs `/skill-name` or Claude invokes via `Skill()` tool +- Content loaded only when called +- Use for: procedures run occasionally +- `context: fork` runs in isolated subagent context + +### Decision Matrix + +| Scenario | Use | +|----------|-----| +| Agent always needs this knowledge | Agent skill (preloaded) | +| User triggers occasionally | On-demand skill | +| Heavy procedure, don't pollute context | On-demand with `context: fork` | +| Background-only, never user-facing | `user-invocable: false` | + +## Pattern 4: Agent Teams Orchestration + +For large tasks, coordinate multiple agents working in parallel. + +```bash +# Enable agent teams +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 +``` + +### Team Composition + +| Role | Agent | Responsibility | +|------|-------|---------------| +| Lead | Main session | Coordinate, assign tasks, synthesize | +| Frontend | Teammate 1 | UI components, styling, client logic | +| Backend | Teammate 2 | API endpoints, database, server logic | +| Tests | Teammate 3 | Test coverage, integration tests | + +### Communication Flow + +- Lead assigns tasks via shared task list +- Teammates work independently in their own context windows +- Teammates message each other directly (not just report back) +- Lead synthesizes results and handles conflicts + +### When to Use Agent Teams vs Subagents + +| Factor | Subagents | Agent Teams | +|--------|-----------|-------------| +| Context | Shares parent session | Independent windows | +| Communication | Returns result only | Direct messaging | +| Duration | Short tasks | Long sessions | +| Isolation | Optional worktree | Always isolated | +| Coordination | Parent manages | Shared task list | + +## Pattern 5: Dynamic Command Substitution + +Commands support string substitution for dynamic context. + +```markdown +# In a command file + +Current branch: !`git branch --show-current` +Last commit: !`git log --oneline -1` +Modified files: !`git diff --name-only` + +Session: ${CLAUDE_SESSION_ID} +User argument: $ARGUMENTS +First word: $ARGUMENTS[0] +``` + +The `` !`command` `` syntax injects live output. Use for context-aware commands. + +## Frontmatter Quick Reference + +### Command Frontmatter + +| Field | Type | Purpose | +|-------|------|---------| +| `description` | string | Shown in `/` menu | +| `argument-hint` | string | Placeholder text | +| `allowed-tools` | string[] | Tool whitelist | +| `model` | string | Override model | + +### Agent Frontmatter + +| Field | Type | Purpose | +|-------|------|---------| +| `name` | string | Agent identifier | +| `description` | string | When to use (include PROACTIVELY for auto-invoke) | +| `tools` | string[] | Allowed tools | +| `disallowedTools` | string[] | Blocked tools | +| `model` | string | Model override | +| `permissionMode` | string | Permission level | +| `maxTurns` | number | Turn limit | +| `skills` | string[] | Preloaded skills | +| `mcpServers` | object | Agent-specific MCP servers | +| `hooks` | object | Agent-specific hooks | +| `memory` | string | `user` / `project` / `local` | +| `background` | boolean | Default to background execution | +| `isolation` | string | `worktree` for git isolation | +| `color` | string | Display color in agent teams | + +### Skill Frontmatter + +| Field | Type | Purpose | +|-------|------|---------| +| `name` | string | Skill identifier | +| `description` | string | When to invoke | +| `argument-hint` | string | Parameter hint | +| `disable-model-invocation` | boolean | Prevent auto-invocation | +| `user-invocable` | boolean | Show in `/` menu | +| `allowed-tools` | string[] | Tool whitelist | +| `model` | string | Model override | +| `context` | string | `fork` for isolated execution | +| `agent` | string | Delegate to specific agent | +| `hooks` | object | Skill-specific hooks | diff --git a/docs/settings-guide.md b/docs/settings-guide.md new file mode 100644 index 0000000..63fcefc --- /dev/null +++ b/docs/settings-guide.md @@ -0,0 +1,227 @@ +# Settings Guide + +Complete reference for configuring Claude Code. Settings control permissions, behavior, and integrations. + +## Settings Hierarchy (Top Wins) + +```text +1. CLI flags --permission-mode, --max-budget-usd +2. .claude/settings.local.json Project-local (gitignored) +3. .claude/settings.json Project-shared (committed) +4. ~/.claude/settings.local.json User-local (personal) +5. ~/.claude/settings.json User-global +6. managed-settings.json Enterprise policy (read-only) +``` + +First match wins. Project settings override user settings. CLI flags override everything. + +## Permission Modes + +| Mode | Behavior | +|------|----------| +| `default` | Ask for dangerous operations | +| `acceptEdits` | Auto-approve file edits, ask for shell | +| `askEdits` | Ask for everything including edits | +| `dontAsk` | Auto-approve everything (trusted environments) | +| `viewOnly` | Read-only, no modifications | +| `bypassPermissions` | Skip all checks (CI/CD only) | +| `plan` | Research and plan, require approval to execute | + +Set via CLI: `claude --permission-mode plan` + +## Permission Rules + +Rules follow `Tool` or `Tool(specifier)` format. Evaluated in order: deny > ask > allow. + +```json +{ + "permissions": { + "deny": [ + "Bash(rm -rf *)", + "Bash(curl * | bash)", + "Edit(/vendor/**)" + ], + "ask": [ + "Bash(git push *)", + "Bash(docker *)", + "Bash(npm publish)" + ], + "allow": [ + "Read", + "Glob", + "Grep", + "Edit", + "Write", + "Bash(npm run *)", + "Bash(git status)", + "Bash(git diff *)", + "Bash(git log *)", + "Bash(ls *)", + "WebFetch(domain:code.claude.com)", + "MCP(github:*)", + "Task(*)", + "Agent(*)" + ] + } +} +``` + +### Wildcard Syntax + +| Pattern | Matches | +|---------|---------| +| `Bash(npm run *)` | Any npm script | +| `Edit(/src/**)` | Any file under src/ recursively | +| `WebFetch(domain:*.github.com)` | Any GitHub subdomain | +| `MCP(github:*)` | Any tool from github MCP server | +| `Task(planner)` | Only the planner subagent | +| `Agent(*)` | Any agent type | + +## Key Settings + +### Behavior + +```json +{ + "outputStyle": "Explanatory", + "fastMode": false, + "prefersReducedMotion": false, + "fileSuggestion": true +} +``` + +Output styles: `"Concise"`, `"Explanatory"`, `"Learning"`, `"Custom:"` + +### Context & Compaction + +```json +{ + "env": { + "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80" + } +} +``` + +Default auto-compact triggers at ~95%. Set lower for proactive compaction. `50` is good for long sessions. + +### Plans Directory + +```json +{ + "plansDirectory": ".claude/plans" +} +``` + +Stores plan mode artifacts for team sharing and review. + +### Status Line + +```json +{ + "statusLine": "model branch tokens" +} +``` + +Shows model, git branch, and token usage in the status bar. Customize via `/statusline`. + +### Spinner Customization + +```json +{ + "spinnerVerbs": ["Thinking", "Analyzing", "Crafting", "Brewing"], + "spinnerTipsOverride": [ + "Tip: Use /compact at task boundaries", + "Tip: Plan mode for >3 files", + "Tip: Ctrl+B sends tasks to background" + ] +} +``` + +### Attribution + +```json +{ + "attribution": { + "commitMessage": "", + "prDescription": "" + } +} +``` + +Set to empty strings to disable "Co-Authored-By" and PR footers. + +### Sandbox + +```json +{ + "sandbox": { + "filesystem": { + "allow": ["/home/user/project"], + "deny": ["/etc", "/root"] + }, + "network": { + "allowDomains": ["api.github.com", "registry.npmjs.org"], + "denyDomains": ["*"] + } + } +} +``` + +### MCP Server Approval + +```json +{ + "enableAllProjectMcpServers": false, + "enabledMcpjsonServers": ["context7", "playwright"], + "disabledMcpjsonServers": ["unused-server"] +} +``` + +### Budget Control + +Via CLI flags (not settings.json): +```bash +claude --max-budget-usd 5.00 +claude --max-turns 50 +``` + +## Production-Ready Example + +See `settings.example.json` in the repo root for a full working configuration. + +## Scope: What Lives Where + +| Feature | Global Only | Dual Scope | +|---------|:-----------:|:----------:| +| Tasks & Task Lists | Y | | +| Agent Teams | Y | | +| Auto Memory | Y | | +| Credentials/Auth | Y | | +| Keybindings | Y | | +| MCP User Servers | Y | | +| CLAUDE.md | | Y | +| Settings | | Y | +| Agents | | Y | +| Commands | | Y | +| Skills | | Y | +| Hooks | | Y | +| MCP Project Servers | | Y | +| Rules | | Y | + +Global = `~/.claude/`, Project = `.claude/` + +## Environment Variables + +Key env vars (set in settings or shell): + +| Variable | Purpose | +|----------|---------| +| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Trigger compaction earlier (default ~95) | +| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Enable agent teams | +| `CLAUDE_CODE_TMPDIR` | Custom temp directory | +| `DISABLE_AUTOUPDATER` | Prevent auto-updates | +| `CLAUDE_CODE_SIMPLE` | Simplified output mode | + +## Cross-Agent Note + +Cursor uses `.cursor/rules/` and `.cursorrules` for similar configuration. See `docs/cross-agent-workflows.md` for mapping between Claude Code settings and Cursor rules. diff --git a/hooks/hooks.json b/hooks/hooks.json index 1377f39..78d47c4 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -158,6 +158,78 @@ ], "description": "Log permission requests" } + ], + "SubagentStart": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);console.error('[ProWorkflow] Subagent started: '+(i.agent_name||'unnamed'));console.log(d)})\"" + } + ], + "description": "Log subagent lifecycle for observability" + } + ], + "SubagentStop": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);console.error('[ProWorkflow] Subagent finished: '+(i.agent_name||'unnamed'));console.log(d)})\"" + } + ], + "description": "Log subagent completion and capture results" + } + ], + "TaskCompleted": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);console.error('[ProWorkflow] Task completed: '+(i.task_id||'unknown'));console.error('[ProWorkflow] Run quality gates before marking done');console.log(d)})\"" + } + ], + "description": "Quality gate check when tasks are marked complete" + } + ], + "PermissionRequest": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const tool=i.tool||'unknown';const cmd=(i.tool_input&&i.tool_input.command)||'';const dangerous=['rm -rf','docker','deploy','npm publish','push --force','reset --hard'];const isDangerous=dangerous.some(p=>tool.includes(p)||cmd.includes(p));if(isDangerous){console.error('[ProWorkflow] CAUTION: Dangerous operation requested: '+tool+(cmd?' cmd: '+cmd:''))}console.log(d)})\"" + } + ], + "description": "Flag dangerous operations in permission requests" + } + ], + "PostToolUseFailure": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);console.error('[ProWorkflow] Tool failed: '+(i.tool||'unknown'));console.error('[ProWorkflow] Consider: [LEARN] Debugging: Tool failure in '+(i.tool||'unknown'));console.log(d)})\"" + } + ], + "description": "Track tool failures and suggest debugging learnings" + } + ], + "TeammateIdle": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);console.error('[ProWorkflow] Teammate idle: '+(i.teammate_name||'unnamed'));console.error('[ProWorkflow] Consider reassigning or checking for blockers');console.log(d)})\"" + } + ], + "description": "Detect idle teammates in agent teams" + } ] } } diff --git a/mcp-config.example.json b/mcp-config.example.json index 5928c05..70e93f5 100644 --- a/mcp-config.example.json +++ b/mcp-config.example.json @@ -1,41 +1,46 @@ { "$schema": "https://json.schemastore.org/claude-code-settings.json", "mcpServers": { - "github": { + "context7": { "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-github"], - "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" - } + "args": ["-y", "@upstash/context7-mcp@latest"], + "_comment": "Live documentation lookup. Eliminates outdated API guessing." }, - "memory": { + "playwright": { "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-memory"] + "args": ["-y", "@anthropic/mcp-playwright"], + "_comment": "Browser automation and E2E testing. Most token-efficient browser MCP." }, - "filesystem": { + "github": { "command": "npx", - "args": ["-y", "@anthropic/server-filesystem"] + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" + }, + "_comment": "PRs, issues, code search. Essential for any GitHub-based project." } }, - "projects": { - "disabledMcpServers": [] + "_recommendations": { + "daily_use": [ + "context7 - Live docs. Use instead of guessing API signatures.", + "playwright - E2E testing and browser automation. 13.7k tokens avg.", + "github - PRs, issues, code search." + ], + "add_when_needed": [ + "supabase - Database operations (when using Supabase)", + "linear - Issue tracking (when using Linear)", + "slack - Team notifications (when using Slack)" + ], + "wisdom": "Start with 3 MCPs. Add only when you hit a concrete need. Most developers who start with 10+ end up using 3-4 daily." + }, + "_scopes": { + "project": ".mcp.json at project root (shared with team)", + "user": "~/.claude.json mcpServers section (personal)", + "agent": "mcpServers field in agent frontmatter (per-agent)" }, - "_comment": [ - "Pro Workflow MCP Config", - "", - "RULE: Keep <10 MCPs enabled, <80 tools total", - "", - "Essential MCPs:", - "- github: PR creation, issue tracking", - "- memory: Persist learnings across sessions", - "- filesystem: File operations", - "", - "Add as needed:", - "- supabase: Database operations", - "- vercel: Deployment", - "- context7: Live documentation", - "", - "Disable when not using:", - "- Add to projects.disabledMcpServers" - ] + "_approval_settings": { + "auto_approve_all": "\"enableAllProjectMcpServers\": true in settings.json", + "selective": "\"enabledMcpjsonServers\": [\"context7\", \"github\"] in settings.json", + "block": "\"disabledMcpjsonServers\": [\"unused-server\"] in settings.json" + } } diff --git a/package.json b/package.json index 9352320..7096026 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "pro-workflow", - "version": "1.3.0", - "description": "Battle-tested Claude Code workflows with agent teams, smart commit, insights, and searchable learnings", + "version": "2.0.0", + "description": "Complete AI coding workflow system with orchestration patterns, cross-agent support, reference guides, and searchable learnings", "main": "dist/index.js", "types": "dist/index.d.ts", "scripts": { @@ -57,7 +57,10 @@ "rules", "references", "skills", + "docs", "config.json", + "settings.example.json", + "mcp-config.example.json", "README.md" ] } diff --git a/references/claude-code-resources.md b/references/claude-code-resources.md index 38d3a38..609fbae 100644 --- a/references/claude-code-resources.md +++ b/references/claude-code-resources.md @@ -1,244 +1,84 @@ -# Claude Code Best Practices +# Claude Code Resources -Essential patterns for mastering Claude Code. Internalized from production use, referencing official documentation at https://code.claude.com/docs/ for deep dives. +Essential references and community workflows. ## Official Documentation -**Source:** https://code.claude.com/docs/ - -| Topic | URL | When to Reference | -|-------|-----|-------------------| -| Quickstart | https://code.claude.com/docs/quickstart | First-time setup, onboarding | -| Common Workflows | https://code.claude.com/docs/common-workflows | Day-to-day patterns | -| CLI Reference | https://code.claude.com/docs/cli-reference | Commands, flags, shortcuts | -| Settings | https://code.claude.com/docs/settings | CLAUDE.md, config, preferences | -| Sub-agents | https://code.claude.com/docs/sub-agents | Task delegation, parallel work | -| MCP | https://code.claude.com/docs/mcp | External tool integration | -| Hooks | https://code.claude.com/docs/hooks | Automation, quality gates | -| Security | https://code.claude.com/docs/security | Permissions, sandboxing | -| Troubleshooting | https://code.claude.com/docs/troubleshooting | Common issues | -| GitHub Actions | https://code.claude.com/docs/github-actions | CI/CD automation | -| IDE Integration | https://code.claude.com/docs/ide-integration | VS Code, JetBrains | - -## Sessions & Context - -Every Claude Code invocation is a session. Claude reads your project structure on start. - -**Key practices:** -- Context window is finite (200k tokens). Use `/context` to check usage. -- Use `/compact` at task boundaries — after planning, after completing a feature, when context >70%. -- Don't compact mid-task. You lose important working context. -- Summarize exploration results before moving to implementation. - -**Pro-Workflow pattern:** Context Discipline (Pattern 7) -**Docs:** https://code.claude.com/docs/common-workflows - -## CLAUDE.md & Memory - -CLAUDE.md is persistent project memory that loads every session. It's the most important file for productivity. - -**What to put in CLAUDE.md:** -- Project structure and architecture overview -- Build/test/lint commands -- Code conventions and style rules -- Common gotchas specific to your project -- Constraints Claude should respect - -**What NOT to put:** -- Entire file contents (wastes context) -- Obvious things any developer would know -- Rapidly changing information - -**Pro-Workflow pattern:** Split Memory (Pattern 4), Self-Correction Loop (Pattern 1) -**Docs:** https://code.claude.com/docs/settings - -## Modes - -Three modes for different work styles: - -| Mode | When | Behavior | -|------|------|----------| -| **Normal** | Default | Claude asks before edits | -| **Auto-Accept** | Trusted iteration | Claude edits without asking | -| **Plan** | Complex tasks | Research first, then propose plan | - -**When to use Plan mode:** -- Task touches >3 files -- Architecture decisions needed -- Multiple valid approaches exist -- Requirements are unclear - -**Toggle:** `Shift+Tab` cycles through modes. - -**Pro-Workflow pattern:** 80/20 Review (Pattern 5) -**Docs:** https://code.claude.com/docs/common-workflows - -## CLI Navigation - -Essential shortcuts for speed: - -| Shortcut | Action | -|----------|--------| -| `Shift+Tab` | Cycle modes (Normal → Auto → Plan) | -| `Ctrl+L` | Clear screen | -| `Ctrl+C` | Cancel current generation | -| `Ctrl+B` | Run current task in background | -| `Up/Down` | Navigate prompt history | -| `/compact` | Compact context | -| `/context` | Check context usage | -| `/clear` | Clear conversation | - -**Pro-Workflow pattern:** Context Discipline (Pattern 7) -**Docs:** https://code.claude.com/docs/cli-reference - -## Prompting - -Good prompts have four parts: - -1. **Scope** — What files/area to work in -2. **Context** — Background info Claude needs -3. **Constraints** — What NOT to do, limits -4. **Acceptance criteria** — How to know it's done - -**Example of a good prompt:** -``` -In src/auth/, add rate limiting to the login endpoint. -We use Express with Redis for sessions. -Don't change the session middleware. -It should return 429 after 5 failed attempts per IP in 15 minutes. -``` - -**Example of a bad prompt:** -``` -Add rate limiting -``` - -**Pro-Workflow pattern:** 80/20 Review (Pattern 5) - -## Writing Rules & Constraints - -Rules in CLAUDE.md prevent Claude from going off-track. Be specific. - -**Good rules:** -``` -- Always use snake_case for database columns -- Never modify files in vendor/ -- Run `pytest -x` after any Python file change -- Use TypeScript strict mode, no `any` types -``` - -**Bad rules:** -``` -- Write good code -- Follow best practices -- Be careful -``` - -**Pro-Workflow pattern:** Self-Correction Loop (Pattern 1) - -## Skills & Automation - -Skills are reusable Claude Code commands defined in markdown with frontmatter. - -**When to create a skill:** -- You repeat the same prompt pattern >3 times -- A workflow has a consistent structure -- You want to share a pattern with your team - -**Skill structure:** -```markdown ---- -name: my-skill -description: What this skill does -tools: Read, Grep, Edit ---- - -Instructions for Claude when this skill is invoked. -``` - -**Pro-Workflow pattern:** Learning Log (Pattern 8) -**Docs:** https://code.claude.com/docs/settings - -## Subagents & Parallelism - -Subagents run in separate context windows. Use them for parallel work. - -**When to use subagents:** -- Parallel file exploration -- Background long-running operations -- Independent research tasks - -**When NOT to use subagents:** -- Simple single-file reads -- Tasks needing conversation context -- Sequential dependent operations - -**Background execution:** Press `Ctrl+B` to send a task to background while you continue working. - -**Pro-Workflow pattern:** Parallel Worktrees (Pattern 2) -**Docs:** https://code.claude.com/docs/sub-agents - -## Hooks - -Hooks automate quality enforcement. They run scripts on specific events. - -**Hook types:** -- `PreToolUse` — Before edits, commits, pushes -- `PostToolUse` — After edits, test runs -- `SessionStart` — Load patterns, check state -- `SessionEnd` — Capture learnings, check uncommitted -- `Stop` — After each response -- `UserPromptSubmit` — Before processing user input - -**Pro-Workflow pattern:** All hooks in `hooks/hooks.json` -**Docs:** https://code.claude.com/docs/hooks - -## Security & Permissions - -Claude Code has a permission model. Understand it before handling sensitive data. - -**Key principles:** -- Review permission requests carefully -- Don't auto-approve shell commands you don't understand -- Keep secrets out of CLAUDE.md -- Use `.gitignore` and `.claudeignore` for sensitive files - -**Docs:** https://code.claude.com/docs/security - -## MCP (Model Context Protocol) - -MCP connects Claude to external tools and data sources. - -**Guidelines:** -- Keep <10 MCPs enabled -- Keep total tools <80 -- Disable MCPs you're not actively using -- Each MCP adds context overhead - -**Docs:** https://code.claude.com/docs/mcp - -## Integration - -| Platform | Docs | -|----------|------| -| VS Code | https://code.claude.com/docs/ide-integration | -| JetBrains | https://code.claude.com/docs/ide-integration | +| Topic | URL | +|-------|-----| +| Quickstart | https://code.claude.com/docs/quickstart | +| Common Workflows | https://code.claude.com/docs/common-workflows | +| CLI Reference | https://code.claude.com/docs/cli-reference | +| Settings | https://code.claude.com/docs/settings | +| Sub-agents | https://code.claude.com/docs/sub-agents | +| Agent Teams | https://code.claude.com/docs/agent-teams | +| MCP | https://code.claude.com/docs/mcp | +| Hooks | https://code.claude.com/docs/hooks | +| Security | https://code.claude.com/docs/security | | GitHub Actions | https://code.claude.com/docs/github-actions | +| IDE Integration | https://code.claude.com/docs/ide-integration | +| Troubleshooting | https://code.claude.com/docs/troubleshooting | + +## Community Workflows & Tools + +| Resource | Focus | +|----------|-------| +| HumanLayer RPI Workflow | Research > Plan > Implement with validation gates | +| GitHub SpecKit | Specification-driven development | +| GSD (Get Shit Done) | Pragmatic productivity patterns | +| OpenSpec OPSX | Open specification format for AI agents | +| Superpower by obra | Advanced Claude Code customization | +| Karpathy Skills | 80/20 AI coding ratio patterns | +| AgentOS by Brian Casel | Operating system for AI coding sessions | +| Ralph Wiggum Loop | Autonomous bash-loop development plugin | +| Boris Cherny Workflows | Claude Code creator's personal setup and tips | +| Trail of Bits Config | Security-focused Claude Code configuration | +| Addy Osmani LLM Workflow | Google Chrome team member's AI coding setup | + +## Key Blog Posts & Articles + +| Title | Source | +|-------|--------| +| Claude Code Tips That Changed How I Work | Medium (Ian Adera) | +| 17 Claude Code Workflows That Separate Amateurs from Pros | Medium (Joe Njenga) | +| How I Use Claude Code (+ My Best Tips) | Builder.io | +| Best Practices for Coding with Agents | Cursor Blog | +| My LLM Coding Workflow Going Into 2026 | AddyOsmani.com | +| Agent Best Practices | https://cursor.com/blog/agent-best-practices | + +## Pro-Workflow Reference Guides + +| Guide | Path | Topics | +|-------|------|--------| +| Settings Guide | `docs/settings-guide.md` | Hierarchy, permissions, sandbox, env vars | +| CLI Cheatsheet | `docs/cli-cheatsheet.md` | Flags, shortcuts, slash commands, scripting | +| Orchestration Patterns | `docs/orchestration-patterns.md` | Command > Agent > Skill, frontmatter | +| Context Loading | `docs/context-loading.md` | Monorepo CLAUDE.md, agent memory, skills | +| Cross-Agent Workflows | `docs/cross-agent-workflows.md` | Claude Code + Cursor config mapping | +| New Features | `docs/new-features.md` | Voice, teams, checkpointing, hooks | +| Daily Habits | `docs/daily-habits.md` | Session habits, debugging, terminal setup | + +## Learning Path + +1. **Start** — CLI shortcuts, context management, modes +2. **Build** — CLAUDE.md, writing rules, prompting, skills +3. **Scale** — Custom subagents, agent teams, hooks, MCP +4. **Orchestrate** — Command > Agent > Skill wiring, multi-phase dev +5. **Optimize** — Pro-Workflow patterns 1-10, daily habits +6. **Cross-Agent** — Use patterns across Claude Code, Cursor, Codex, Gemini CLI ## How to Use These Practices ### With /learn-rule -When you discover a Claude Code best practice: -``` +```text [LEARN] Claude-Code: ``` ### With /learn Save to database with `Claude-Code` category for searchability. -### Learning Path -1. **Start** — Read the quickstart, learn CLI shortcuts, understand context limits -2. **Build** — Write a good CLAUDE.md, learn modes, improve your prompts -3. **Scale** — Create skills, use subagents, set up hooks -4. **Optimize** — Layer Pro-Workflow patterns 1-8 for production use -5. **Reference** — Official docs for deep dives on any topic +### With SkillKit +```bash +npx skillkit install pro-workflow +npx skillkit translate pro-workflow --agent cursor +``` diff --git a/settings.example.json b/settings.example.json new file mode 100644 index 0000000..835c2ad --- /dev/null +++ b/settings.example.json @@ -0,0 +1,81 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "permissions": { + "deny": [ + "Bash(rm -rf *)", + "Bash(curl * | bash)", + "Bash(wget * | sh)", + "Edit(/vendor/**)", + "Edit(/node_modules/**)" + ], + "ask": [ + "Bash(git push *)", + "Bash(git reset *)", + "Bash(docker *)", + "Bash(npm publish *)", + "Bash(npx * deploy *)" + ], + "allow": [ + "Read", + "Glob", + "Grep", + "Edit", + "Write", + "Bash(npm run *)", + "Bash(pnpm *)", + "Bash(git status)", + "Bash(git diff *)", + "Bash(git log *)", + "Bash(git branch *)", + "Bash(git checkout *)", + "Bash(git add *)", + "Bash(git commit *)", + "Bash(ls *)", + "Bash(cat *)", + "Bash(head *)", + "Bash(tail *)", + "Bash(wc *)", + "Bash(find *)", + "Bash(grep *)", + "Bash(node *)", + "Bash(npx jest *)", + "Bash(npx vitest *)", + "Bash(npx tsc *)", + "Bash(npx eslint *)", + "MCP(github:*)", + "MCP(context7:*)", + "Task(*)", + "Agent(*)" + ] + }, + "outputStyle": "Explanatory", + "statusLine": "model branch tokens", + "plansDirectory": ".claude/plans", + "enableAllProjectMcpServers": false, + "attribution": { + "commitMessage": "", + "prDescription": "" + }, + "env": { + "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80" + }, + "spinnerVerbs": [ + "Thinking", + "Analyzing", + "Exploring", + "Investigating", + "Crafting", + "Reviewing" + ], + "spinnerTipsOverride": [ + "Use /compact at task boundaries to keep context fresh", + "Shift+Tab cycles modes: Normal > Auto > Plan", + "Ctrl+B sends the current task to background", + "Use subagents for parallel exploration", + "claude -w creates an instant parallel worktree session", + "Voice mode: /voice then hold spacebar to talk", + "Esc Esc rewinds to the last checkpoint", + "Write tests alongside code for better AI output", + "/doctor diagnoses configuration issues" + ] +} diff --git a/skills/context-optimizer/SKILL.md b/skills/context-optimizer/SKILL.md new file mode 100644 index 0000000..fcca5c1 --- /dev/null +++ b/skills/context-optimizer/SKILL.md @@ -0,0 +1,91 @@ +--- +name: context-optimizer +description: Optimize token usage and context management. Use when sessions feel slow, context is degraded, or you're running out of budget. +--- + +# Context Optimizer + +Manage your context window and token budget effectively. + +## Quick Diagnosis + +1. Run `/context` to check current usage +2. If > 70% → compact now before it degrades +3. If > 90% → you're in the "dumb zone", compact immediately + +## Optimization Strategies + +### Immediate + +| Action | Saves | When | +|--------|-------|------| +| `/compact` | 30-50% context | At task boundaries | +| Disable unused MCPs | ~5% per MCP | When switching domains | +| Use subagents for exploration | Keeps main context clean | Heavy search/read tasks | +| Fresh session via `/resume` | 100% reset | When starting unrelated work | + +### Configuration + +Set proactive auto-compaction: +```json +{ + "env": { + "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50" + } +} +``` + +### MCP Audit + +Keep <10 MCPs enabled, <80 tools total. Each MCP adds overhead to every request. + +```bash +/mcp # List active servers +# Disable what you're not using +``` + +### Prompt Engineering for Token Efficiency + +- Scope your prompts: "In src/auth/, fix the login bug" +- Provide constraints: "Don't modify the middleware" +- Give acceptance criteria: "Should return 429 after 5 attempts" +- Avoid vague prompts: "Fix the code" (forces Claude to read everything) + +### Subagent Delegation + +Heavy operations that generate lots of output should go to subagents: + +- Test suite output → subagent +- Large file exploration → subagent +- Documentation generation → subagent +- Log analysis → subagent + +The main session stays clean while subagents handle the volume. + +## Context Budget Planning + +| Phase | Target Usage | Action If Over | +|-------|-------------|----------------| +| Planning | < 20% | Keep plans concise | +| Implementation | < 60% | Compact between files | +| Testing | < 80% | Delegate to subagent | +| Review | < 90% | Start fresh session | + +## CLAUDE.md Optimization + +- Root CLAUDE.md: < 60 lines ideal, < 150 max +- Move package-specific info to package-level CLAUDE.md +- Move personal preferences to CLAUDE.local.md +- Remove obvious or rapidly-changing information + +## When Context Is Degraded + +Signs: +- Claude repeats itself or forgets earlier context +- Responses become generic or lose project-specific knowledge +- Tool calls start failing for reasons that worked earlier + +Fix: +1. Manual `/compact` +2. If still bad: new session with `/resume` +3. For recurring issues: reduce CLAUDE.md size, disable MCPs diff --git a/skills/orchestrate/SKILL.md b/skills/orchestrate/SKILL.md new file mode 100644 index 0000000..3ad7b12 --- /dev/null +++ b/skills/orchestrate/SKILL.md @@ -0,0 +1,69 @@ +--- +name: orchestrate +description: Wire Commands, Agents, and Skills together for complex features. Use when building features that need research, planning, and implementation phases. +--- + +# Orchestrate - Multi-Phase Feature Development + +Build features through structured phases with validation gates. + +## The Pattern + +```text +/develop + │ + ├── Phase 1: Research (orchestrator agent) + │ └── Score confidence → GO/HOLD + │ + ├── Phase 2: Plan (orchestrator agent) + │ └── Present plan → wait for approval + │ + ├── Phase 3: Implement (orchestrator agent) + │ └── Execute plan → quality gates + │ + └── Phase 4: Review (reviewer agent) + └── Code review → commit +``` + +## Usage + +When asked to build a feature: + +1. **Start with research**: Delegate to the orchestrator agent or scout agent to explore the codebase +2. **Wait for GO/HOLD**: Don't proceed if confidence is below 70 +3. **Present a plan**: List all files to change, the approach, and risks +4. **Get approval**: Never implement without explicit "proceed" +5. **Implement step by step**: Quality gates every 5 edits +6. **Review before commit**: Run the reviewer agent on changes + +## When to Use This + +- Feature touches >5 files +- Architecture decisions needed +- Requirements are unclear or complex +- Cross-cutting concerns (auth, logging, error handling) +- New patterns not yet established in the codebase + +## When NOT to Use This + +- Quick bug fixes (just fix it) +- Single-file changes +- Well-understood patterns (follow existing code) +- Documentation-only changes + +## Agent Selection + +| Phase | Agent | Why | +|-------|-------|-----| +| Research | scout (background, worktree) | Non-blocking exploration | +| Plan | orchestrator (opus, memory) | Deep reasoning, pattern recall | +| Implement | orchestrator (opus, memory) | Full tool access | +| Review | reviewer (read + bash) | Security and quality focus | +| Debug | debugger (opus, memory) | Systematic investigation | + +## Integration with Pro-Workflow + +- Corrections during implementation trigger self-correction loop +- Quality gates fire at checkpoints via hooks +- Learnings are captured at the end of each phase +- Session handoff works across phases diff --git a/skills/pro-workflow/SKILL.md b/skills/pro-workflow/SKILL.md index 44c850a..46d0601 100644 --- a/skills/pro-workflow/SKILL.md +++ b/skills/pro-workflow/SKILL.md @@ -1,13 +1,13 @@ --- name: pro-workflow -description: Implement self-correcting memory, parallel worktrees, wrap-up rituals, and review checkpoints for AI coding sessions. Configures CLAUDE.md rules, quality gates, and context management. Use when setting up AI coding best practices, optimising agent workflows, or asking about Claude Code or Cursor productivity patterns. +description: Complete AI coding workflow system. Orchestration patterns, 18 hook events, 5 agents, cross-agent support, reference guides, and searchable learnings. Works with Claude Code, Cursor, and 32+ agents. --- # Pro Workflow -Real-world AI coding patterns from power users who ship production code daily. Not theory - workflows that compound over time. +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, and other AI coding agents. Sections marked *(Claude Code)* use features specific to Claude Code — Cursor users can skip those or use the noted alternatives. +**Works with:** Claude Code, Cursor, Codex, Gemini CLI, and 32+ AI coding agents via SkillKit. Sections marked *(Claude Code)* use features specific to Claude Code — Cursor users can skip those or use the noted alternatives. ## The Core Insight @@ -51,7 +51,7 @@ When the user corrects me or I make a mistake: ### Example Flow -``` +```text User: You edited the wrong file Claude: I edited src/utils.ts when you meant src/lib/utils.ts. @@ -137,7 +137,7 @@ For complex projects, modularize Claude memory. ### Structure -``` +```text .claude/ ├── CLAUDE.md # Entry point ├── AGENTS.md # Workflow rules @@ -197,7 +197,7 @@ Between: proceed with confidence. ## 6. Model Selection -**Opus 4.6 and Sonnet 4.6** both support adaptive thinking and 1M-token context. The 1M context is available as a beta option (via the `context-1m-2025-08-07` beta header); the default context window remains 200K. Sonnet 4.5 (200K context) has been retired from the Max plan in favor of Sonnet 4.6. +**Opus 4.6 and Sonnet 4.6** both support adaptive thinking and 1M-token context (as of 2025-08). The 1M context is available as a beta option (via the `context-1m-2025-08-07` beta header); the default context window remains 200K. Sonnet 4.5 (200K context) has been retired from the Max plan in favor of Sonnet 4.6. See [Models overview](https://docs.anthropic.com/en/docs/about-claude/models/overview) for current capabilities. | Task | Model | |------|-------| @@ -213,9 +213,10 @@ Opus 4.6 and Sonnet 4.6 automatically calibrate reasoning depth per task — lig ### Add to CLAUDE.md ```markdown -## Model Hints +## Model Hints (as of 2025-08) Opus 4.6 and Sonnet 4.6 auto-calibrate reasoning depth — no need to toggle thinking mode. Use subagents with Haiku for fast read-only exploration, Sonnet 4.6 for balanced work. +Docs: https://docs.anthropic.com/en/docs/about-claude/models/overview ``` --- @@ -266,7 +267,7 @@ 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. Official docs: **https://code.claude.com/docs/** +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/** --- @@ -404,31 +405,131 @@ Coordinate multiple Claude Code sessions as a team: --- +## 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 + +Never skip phases. Never proceed without approval between phases. + +### 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) +- SkillKit translates skills to any agent: `npx skillkit translate pro-workflow --agent cursor` + +--- + ## MCP Config *(Claude Code)* -Keep <10 MCPs enabled, <80 tools total. +Start with 3 MCPs. Add only for concrete needs. Essential: -- `github` - PRs, issues -- `memory` - Persist learnings -- `filesystem` - File ops +- `context7` — Live documentation lookup +- `playwright` — Browser automation (most token-efficient) +- `github` — PRs, issues, code search -See `mcp-config.example.json` for setup. +See `mcp-config.example.json` for setup and curated recommendations. --- ## Commands *(Claude Code)* -These slash commands are available when using pro-workflow as a Claude Code plugin. Cursor users get the same functionality through the **skills** listed above (wrap-up, smart-commit, parallel-worktrees, etc.). - | Command | Purpose | Cursor Equivalent | |---------|---------|-------------------| | `/wrap-up` | End-of-session ritual | `wrap-up` skill | | `/learn-rule` | Extract correction to memory | `learn-rule` skill | -| `/parallel` | Worktree setup guide | `parallel-worktrees` skill | -| `/learn` | Best practices & save learnings | — | -| `/search` | Search learnings by keyword | — | -| `/list` | List all stored learnings | — | +| `/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 | +|-------|--------| +| `docs/settings-guide.md` | All settings keys, permission modes, hierarchy, sandbox, env vars | +| `docs/cli-cheatsheet.md` | Every CLI flag, keyboard shortcut, slash command | +| `docs/orchestration-patterns.md` | Command > Agent > Skill architecture, frontmatter reference | +| `docs/context-loading.md` | CLAUDE.md monorepo loading, agent memory, skills discovery | +| `docs/cross-agent-workflows.md` | Claude Code + Cursor config mapping, background agents | +| `docs/new-features.md` | Voice mode, agent teams, checkpointing, new hook events | +| `docs/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.*