From 96d9217c318fb73c6aa55c06bb922fd8c4c90d75 Mon Sep 17 00:00:00 2001 From: duthaho Date: Sat, 29 Nov 2025 22:02:48 +0700 Subject: [PATCH] Enhance Claude Kit with new features and optimizations --- .claude/CLAUDE.md | 156 ++++++++++++- .claude/commands/brainstorm.md | 30 +++ .claude/commands/checkpoint.md | 134 +++++++++++ .claude/commands/feature.md | 19 ++ .claude/commands/fix.md | 28 +++ .claude/commands/index.md | 122 ++++++++++ .claude/commands/load.md | 108 +++++++++ .claude/commands/mode.md | 166 ++++++++++++++ .claude/commands/plan.md | 29 +++ .claude/commands/research.md | 30 +++ .claude/commands/review.md | 39 ++++ .claude/commands/spawn.md | 173 ++++++++++++++ .claude/commands/test.md | 39 ++++ .claude/mcp/README.md | 160 +++++++++++++ .claude/mcp/context7.json | 31 +++ .claude/mcp/magic.json | 43 ++++ .claude/mcp/puppeteer.json | 43 ++++ .claude/mcp/sequential.json | 31 +++ .claude/modes/brainstorm.md | 87 +++++++ .claude/modes/deep-research.md | 132 +++++++++++ .claude/modes/default.md | 50 +++++ .claude/modes/implementation.md | 120 ++++++++++ .claude/modes/orchestration.md | 182 +++++++++++++++ .claude/modes/review.md | 145 ++++++++++++ .claude/modes/token-efficient.md | 116 ++++++++++ .claude/settings.json | 20 ++ .../methodology/sequential-thinking/SKILL.md | 212 ++++++++++++++++++ .../optimization/token-efficient/SKILL.md | 198 ++++++++++++++++ README.md | 120 +++++++++- 29 files changed, 2752 insertions(+), 11 deletions(-) create mode 100644 .claude/commands/checkpoint.md create mode 100644 .claude/commands/index.md create mode 100644 .claude/commands/load.md create mode 100644 .claude/commands/mode.md create mode 100644 .claude/commands/spawn.md create mode 100644 .claude/mcp/README.md create mode 100644 .claude/mcp/context7.json create mode 100644 .claude/mcp/magic.json create mode 100644 .claude/mcp/puppeteer.json create mode 100644 .claude/mcp/sequential.json create mode 100644 .claude/modes/brainstorm.md create mode 100644 .claude/modes/deep-research.md create mode 100644 .claude/modes/default.md create mode 100644 .claude/modes/implementation.md create mode 100644 .claude/modes/orchestration.md create mode 100644 .claude/modes/review.md create mode 100644 .claude/modes/token-efficient.md create mode 100644 .claude/skills/methodology/sequential-thinking/SKILL.md create mode 100644 .claude/skills/optimization/token-efficient/SKILL.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index c060ba6..1868735 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -6,6 +6,8 @@ This is a comprehensive Claude Kit for Claude Code, designed to accelerate devel ## Quick Reference +### Core Commands + | Command | Description | |---------|-------------| | `/feature [desc]` | Full feature development workflow | @@ -14,12 +16,28 @@ This is a comprehensive Claude Kit for Claude Code, designed to accelerate devel | `/test [scope]` | Generate tests | | `/ship [msg]` | Commit + PR automation | | `/plan [task]` | Task decomposition | +| `/doc [target]` | Documentation generation | +| `/deploy [env]` | Deployment workflow | + +### Enhanced Commands + +| Command | Description | +|---------|-------------| | `/plan --detailed [task]` | Detailed plan with 2-5 min tasks | | `/brainstorm [topic]` | Interactive design session | | `/execute-plan [file]` | Subagent-driven plan execution | | `/tdd [feature]` | Test-driven development workflow | -| `/doc [target]` | Documentation generation | -| `/deploy [env]` | Deployment workflow | +| `/research [topic]` | Technology research | + +### New Commands + +| Command | Description | +|---------|-------------| +| `/mode [name]` | Switch behavioral mode | +| `/index` | Generate project structure index | +| `/load [component]` | Load project context | +| `/checkpoint [action]` | Save/restore session state | +| `/spawn [task]` | Launch parallel background task | ## Tech Stack @@ -148,6 +166,130 @@ Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` - Reproduce before fixing - Add regression tests +## Behavioral Modes + + + +Modes adjust communication style, output format, and problem-solving approach. + +| Mode | Description | Best For | +|------|-------------|----------| +| `default` | Balanced standard behavior | General tasks | +| `brainstorm` | Creative exploration, questions | Design, ideation | +| `token-efficient` | Compressed, concise output | High-volume, cost savings | +| `deep-research` | Thorough analysis, citations | Investigation, audits | +| `implementation` | Code-focused, minimal prose | Executing plans | +| `review` | Critical analysis, finding issues | Code review, QA | +| `orchestration` | Multi-task coordination | Complex parallel work | + +### Mode Activation + +```bash +/mode brainstorm # Switch mode for session +/feature --mode=implementation # Override for single command +``` + +Mode files: `.claude/modes/` + +## Command Flags + + + +All commands support combinable flags for flexible customization. + +### Universal Flags + +| Flag | Description | Values | +|------|-------------|--------| +| `--mode=[mode]` | Behavioral mode | default, brainstorm, token-efficient, etc. | +| `--depth=[1-5]` | Thoroughness level | 1=quick, 5=exhaustive | +| `--format=[fmt]` | Output format | concise, detailed, json | +| `--save=[path]` | Save output to file | File path | +| `--checkpoint` | Create state checkpoint | Boolean | + +### Persona Flags + +| Flag | Description | +|------|-------------| +| `--persona=security` | Security-focused analysis | +| `--persona=performance` | Performance-focused analysis | +| `--persona=architecture` | Architecture-focused analysis | + +### Examples + +```bash +/review --persona=security --depth=5 src/auth/ +/plan --mode=brainstorm --save=plans/design.md "feature" +/fix --format=concise "error message" +``` + +## Token Optimization + + + +Control output verbosity for cost optimization. + +| Level | Flag | Savings | Description | +|-------|------|---------|-------------| +| Standard | (default) | 0% | Full explanations | +| Concise | `--format=concise` | 30-40% | Reduced explanations | +| Ultra | `--format=ultra` | 60-70% | Code-only responses | + +### Session-Wide Optimization + +```bash +/mode token-efficient # Enable for entire session +``` + +Reference: `.claude/skills/optimization/token-efficient/SKILL.md` + +## Context Management + +### Project Indexing + +Generate and use project structure index for faster navigation: + +```bash +/index # Generate PROJECT_INDEX.md +/load api # Load API context +/load --all # Load full project context +``` + +### Session Checkpoints + +Save and restore conversation state: + +```bash +/checkpoint save "feature-x" # Save current state +/checkpoint list # List checkpoints +/checkpoint restore "feature-x" # Restore state +``` + +### Parallel Tasks + +Launch background tasks for concurrent work: + +```bash +/spawn "research auth patterns" +/spawn --list # Check status +/spawn --collect # Gather results +``` + +## MCP Integrations + + + +Optional MCP servers for extended capabilities. + +| Server | Purpose | Status | +|--------|---------|--------| +| Context7 | Library documentation lookup | Optional | +| Sequential | Multi-step reasoning tools | Optional | +| Puppeteer | Browser automation | Optional | +| Magic | UI component generation | Optional | + +Setup: See `.claude/mcp/README.md` + ## Methodology Settings @@ -203,6 +345,12 @@ Enable mandatory verification before completion claims: Skills location: `.claude/skills/methodology/` +### Sequential Thinking + +For complex problems requiring step-by-step analysis: +- Reference: `.claude/skills/methodology/sequential-thinking/SKILL.md` +- Activation: `/research --sequential [topic]` or use deep-research mode + ## Environment Configuration @@ -287,6 +435,6 @@ pnpm install ## Kit Version -- **Claude Kit Version**: 1.0.0 -- **Last Updated**: 2025-01-27 +- **Claude Kit Version**: 2.0.0 +- **Last Updated**: 2025-01-29 - **Compatible with**: Claude Code 1.0+ diff --git a/.claude/commands/brainstorm.md b/.claude/commands/brainstorm.md index 92925d1..ee127d6 100644 --- a/.claude/commands/brainstorm.md +++ b/.claude/commands/brainstorm.md @@ -150,6 +150,36 @@ After design is complete: 2. Use `/plan --detailed` for implementation planning 3. Use `/execute-plan` for automated implementation +## Flags + +| Flag | Description | Example | +|------|-------------|---------| +| `--mode=[mode]` | Use specific behavioral mode | `--mode=brainstorm` | +| `--depth=[1-5]` | Exploration depth level | `--depth=4` | +| `--format=[fmt]` | Output format (concise/detailed) | `--format=detailed` | +| `--save=[path]` | Save design document to file | `--save=docs/design.md` | +| `--quick` | Shorter session, fewer questions | `--quick` | +| `--comprehensive` | Longer session, thorough exploration | `--comprehensive` | + +### Flag Usage Examples + +```bash +/brainstorm --comprehensive "authentication system design" +/brainstorm --save=docs/payment-design.md "payment integration" +/brainstorm --quick "simple file upload feature" +/brainstorm --depth=5 "microservices architecture" +``` + +### Session Depth + +| Level | Questions | Exploration | +|-------|-----------|-------------| +| 1 | 2-3 | Quick validation only | +| 2 | 4-5 | Standard session | +| 3 | 6-8 | Thorough exploration | +| 4 | 8-10 | Comprehensive | +| 5 | 10+ | Exhaustive, all angles | + ## When NOT to Use - Clear "mechanical" processes with known implementation diff --git a/.claude/commands/checkpoint.md b/.claude/commands/checkpoint.md new file mode 100644 index 0000000..e9ea41d --- /dev/null +++ b/.claude/commands/checkpoint.md @@ -0,0 +1,134 @@ +# /checkpoint + +## Purpose + +Save and restore conversation context using git-based checkpoints. Enables session recovery and state preservation for complex, multi-session work. + +--- + +Manage checkpoints for the current work session. + +## Checkpoint Operations + +### Save Checkpoint + +Create a checkpoint of current state: + +```bash +/checkpoint save [name] +``` + +**Process:** +1. Create git stash with descriptive message +2. Record current context (files being worked on, task state) +3. Save checkpoint metadata to `.claude/checkpoints/[name].json` + +**Metadata Format:** +```json +{ + "name": "feature-auth", + "created": "2024-01-15T14:30:00Z", + "git_stash": "stash@{0}", + "files_in_context": ["src/auth/login.ts", "src/auth/token.ts"], + "current_task": "Implementing JWT refresh", + "notes": "User-provided notes" +} +``` + +### List Checkpoints + +Show available checkpoints: + +```bash +/checkpoint list +``` + +**Output:** +```markdown +## Available Checkpoints + +| Name | Created | Task | Stash | +|------|---------|------|-------| +| feature-auth | 2h ago | JWT refresh | stash@{0} | +| bugfix-login | 1d ago | Login timeout | stash@{1} | +``` + +### Restore Checkpoint + +Restore a previous checkpoint: + +```bash +/checkpoint restore [name] +``` + +**Process:** +1. Apply git stash +2. Load checkpoint metadata +3. Summarize restored context +4. Ready to continue work + +### Delete Checkpoint + +Remove a checkpoint: + +```bash +/checkpoint delete [name] +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--notes="[text]"` | Add notes to checkpoint | +| `--force` | Overwrite existing checkpoint | +| `--include-uncommitted` | Include uncommitted changes | +| `--dry-run` | Show what would be saved | + +## Usage Examples + +```bash +/checkpoint save auth-progress # Save current state +/checkpoint save auth --notes="WIP tokens" # Save with notes +/checkpoint list # Show checkpoints +/checkpoint restore auth-progress # Restore state +/checkpoint delete old-checkpoint # Remove checkpoint +``` + +## Arguments + +$ARGUMENTS + +Parse the operation (save/list/restore/delete) and checkpoint name. + +--- + +## Auto-Checkpoint + +For complex tasks, checkpoints are automatically suggested: +- Before major refactoring +- When switching contexts +- Before risky operations +- At natural breakpoints + +## Best Practices + +1. **Name Descriptively**: Use task-related names +2. **Add Notes**: Future you will thank present you +3. **Checkpoint Often**: Before context switches +4. **Clean Up**: Delete obsolete checkpoints + +## Recovery Workflow + +When resuming work: +``` +1. /checkpoint list # See available states +2. /checkpoint restore [name] # Restore context +3. Continue where you left off # Context is loaded +``` + +## Limitations + +- Checkpoints use git stash (requires git repo) +- Large uncommitted changes may be slow +- Metadata stored in `.claude/checkpoints/` +- Consider committing before checkpointing for safety diff --git a/.claude/commands/feature.md b/.claude/commands/feature.md index 3905aaa..6031685 100644 --- a/.claude/commands/feature.md +++ b/.claude/commands/feature.md @@ -181,6 +181,25 @@ git diff --staged 4. Updated API documentation 5. Commit message and PR description +## Flags + +| Flag | Description | Example | +|------|-------------|---------| +| `--mode=[mode]` | Use specific behavioral mode | `--mode=implementation` | +| `--depth=[1-5]` | Planning thoroughness level | `--depth=3` | +| `--checkpoint` | Create checkpoint before starting | `--checkpoint` | +| `--skip-tests` | Skip test generation phase | `--skip-tests` | +| `--skip-review` | Skip code review phase | `--skip-review` | +| `--format=[fmt]` | Output format (concise/detailed) | `--format=concise` | + +### Flag Usage Examples + +```bash +/feature --mode=implementation "add user profile page" +/feature --depth=5 --checkpoint "implement payment flow" +/feature --format=concise "add logging utility" +``` + ## Variations diff --git a/.claude/commands/fix.md b/.claude/commands/fix.md index 69d9f9f..6ad5328 100644 --- a/.claude/commands/fix.md +++ b/.claude/commands/fix.md @@ -234,6 +234,34 @@ for item in items: 3. Fix: Add null check and proper async handling 4. Regression test: Test for case when user is not loaded +## Flags + +| Flag | Description | Example | +|------|-------------|---------| +| `--mode=[mode]` | Use specific behavioral mode | `--mode=deep-research` | +| `--persona=[type]` | Apply persona expertise | `--persona=security` | +| `--depth=[1-5]` | Investigation thoroughness | `--depth=4` | +| `--format=[fmt]` | Output format (concise/detailed) | `--format=concise` | +| `--skip-regression` | Skip regression test creation | `--skip-regression` | +| `--checkpoint` | Create checkpoint before fixing | `--checkpoint` | + +### Flag Usage Examples + +```bash +/fix --mode=deep-research "intermittent timeout error" +/fix --persona=security "SQL injection vulnerability" +/fix --depth=5 "race condition in auth flow" +/fix --format=concise "typo in error message" +``` + +### Persona Options + +| Persona | Focus Area | +|---------|------------| +| `security` | Security vulnerabilities, OWASP | +| `performance` | Speed, memory, efficiency | +| `reliability` | Error handling, edge cases | + ## Variations diff --git a/.claude/commands/index.md b/.claude/commands/index.md new file mode 100644 index 0000000..164db3c --- /dev/null +++ b/.claude/commands/index.md @@ -0,0 +1,122 @@ +# /index + +## Purpose + +Generate a comprehensive project structure index for faster navigation and context loading. Creates a `PROJECT_INDEX.md` file mapping the codebase structure. + +--- + +Analyze the current project and generate a comprehensive index. + +## Index Generation + +### Step 1: Scan Project Structure + +Scan the entire project directory structure, excluding: +- `node_modules/` +- `.git/` +- `__pycache__/` +- `dist/`, `build/`, `.next/` +- `venv/`, `.venv/` +- Coverage and cache directories + +### Step 2: Identify Key Components + +Categorize files by type: +- **Entry Points**: Main files, index files, app entry +- **API/Routes**: Endpoint definitions +- **Models/Types**: Data structures, schemas +- **Services**: Business logic +- **Utilities**: Helper functions +- **Tests**: Test files +- **Configuration**: Config files, env templates +- **Documentation**: README, docs + +### Step 3: Map Dependencies + +Identify: +- Package managers and dependencies (package.json, requirements.txt, etc.) +- Internal import relationships between key files +- External service integrations + +### Step 4: Generate Index + +Create `PROJECT_INDEX.md` with this structure: + +```markdown +# Project Index: [Project Name] + +Generated: [timestamp] + +## Quick Navigation + +| Category | Key Files | +|----------|-----------| +| Entry Points | [list] | +| API Routes | [list] | +| Core Services | [list] | +| Models | [list] | + +## Directory Structure + +``` +[tree view] +``` + +## Key Files + +### Entry Points +- `[path]` - [description] + +### API/Routes +- `[path]` - [description] + +### Services +- `[path]` - [description] + +### Models/Types +- `[path]` - [description] + +## Dependencies + +### External +- [package]: [purpose] + +### Internal +- [module] → [depends on] + +## Architecture Notes +[Brief description of patterns observed] +``` + +## Flags + +| Flag | Description | +|------|-------------| +| `--depth=[N]` | Limit directory depth (default: 5) | +| `--include=[pattern]` | Include additional patterns | +| `--exclude=[pattern]` | Exclude additional patterns | +| `--output=[path]` | Custom output path | + +## Usage Examples + +```bash +/index # Standard index +/index --depth=3 # Shallow index +/index --include="*.graphql" # Include GraphQL files +/index --output=docs/INDEX.md # Custom output location +``` + +## Arguments + +$ARGUMENTS + +If no arguments provided, generate standard index with default settings. + +--- + +After generating the index, inform the user: +1. Index file location +2. Number of files indexed +3. Key components discovered +4. Suggest using `/load` to load specific components into context diff --git a/.claude/commands/load.md b/.claude/commands/load.md new file mode 100644 index 0000000..22e1548 --- /dev/null +++ b/.claude/commands/load.md @@ -0,0 +1,108 @@ +# /load + +## Purpose + +Load specific project components into context for focused work. Uses the project index to efficiently load relevant files. + +--- + +Load the requested component(s) into context. + +## Loading Process + +### Step 1: Check for Index + +First, check if `PROJECT_INDEX.md` exists: +- If exists: Use index for efficient loading +- If not: Suggest running `/index` first, or do quick scan + +### Step 2: Identify Component + +Parse the requested component: + +| Request Type | Action | +|--------------|--------| +| Category name | Load all files in category | +| File path | Load specific file | +| Pattern | Load matching files | +| `--all` | Load key files from all categories | + +### Step 3: Load Files + +Read the identified files and summarize: +- File purposes +- Key exports/functions +- Dependencies +- Current state + +### Step 4: Context Summary + +Provide a brief summary: +```markdown +## Loaded Context + +### Files Loaded (N) +- `path/to/file1.ts` - [purpose] +- `path/to/file2.ts` - [purpose] + +### Key Components +- [Component]: [description] + +### Ready For +- [Suggested actions based on loaded context] +``` + +## Component Categories + +| Category | What It Loads | +|----------|---------------| +| `api` | API routes and endpoints | +| `models` | Data models and types | +| `services` | Business logic services | +| `utils` | Utility functions | +| `tests` | Test files | +| `config` | Configuration files | +| `auth` | Authentication related | +| `db` | Database related | + +## Flags + +| Flag | Description | +|------|-------------| +| `--all` | Load all key components | +| `--shallow` | Load only file summaries | +| `--deep` | Load full file contents | +| `--related` | Include related files | + +## Usage Examples + +```bash +/load api # Load all API routes +/load models # Load all data models +/load src/services/user.ts # Load specific file +/load auth --related # Load auth + related files +/load --all # Load all key components +/load --all --shallow # Quick overview of everything +``` + +## Arguments + +$ARGUMENTS + +If no arguments, show available components from index. + +--- + +## Best Practices + +1. **Start Narrow**: Load specific components first +2. **Expand as Needed**: Use `--related` when you need more context +3. **Check Index**: Run `/index` if loading seems slow +4. **Use Categories**: Category names are faster than patterns + +## After Loading + +Suggest next actions: +- "Ready to work on [component]. What would you like to do?" +- "I see [patterns/issues]. Want me to address them?" +- "Related files that might be relevant: [list]" diff --git a/.claude/commands/mode.md b/.claude/commands/mode.md new file mode 100644 index 0000000..e18f164 --- /dev/null +++ b/.claude/commands/mode.md @@ -0,0 +1,166 @@ +# /mode + +## Purpose + +Switch between behavioral modes to optimize responses for different task types. Modes adjust communication style, output format, and problem-solving approach. + +--- + +Switch to the specified behavioral mode. + +## Available Modes + +| Mode | Description | Best For | +|------|-------------|----------| +| `default` | Balanced standard behavior | General tasks | +| `brainstorm` | Creative exploration, more questions | Design, ideation | +| `token-efficient` | Compressed, concise output | High-volume, cost savings | +| `deep-research` | Thorough analysis, citations | Investigation, audits | +| `implementation` | Code-focused, minimal prose | Executing plans | +| `review` | Critical analysis, finding issues | Code review, QA | +| `orchestration` | Multi-task coordination | Complex parallel work | + +## Mode Switching + +### Activate Mode +```bash +/mode [mode-name] +``` + +### Check Current Mode +```bash +/mode +``` +(Shows current active mode) + +### Reset to Default +```bash +/mode default +``` + +## Mode Details + +### Default Mode +- Standard balanced responses +- Mix of explanation and code +- Normal verification steps + +### Brainstorm Mode +- Ask more clarifying questions +- Present multiple alternatives +- Explore trade-offs explicitly +- Delay convergence on solutions + +### Token-Efficient Mode +- Minimal explanations +- Code-only responses where possible +- Skip obvious context +- 30-70% token savings + +### Deep-Research Mode +- Thorough investigation +- Evidence and citations +- Confidence levels stated +- Comprehensive analysis + +### Implementation Mode +- Jump straight to code +- Progress indicators +- Minimal discussion +- Execute don't deliberate + +### Review Mode +- Look for issues first +- Categorized findings +- Severity levels +- Actionable feedback + +### Orchestration Mode +- Task breakdown +- Parallel execution planning +- Result aggregation +- Coordination focus + +## Flags + +| Flag | Description | +|------|-------------| +| `--info` | Show detailed mode description | +| `--list` | List all available modes | + +## Usage Examples + +```bash +/mode brainstorm # Switch to brainstorm mode +/mode token-efficient # Switch to efficient mode +/mode # Show current mode +/mode --list # List all modes +/mode default # Reset to default +``` + +## Arguments + +$ARGUMENTS + +If mode name provided: switch to that mode +If no arguments: show current mode +If `--list`: show all modes + +--- + +## Mode Persistence + +- Modes persist for the session +- Explicitly switch when task type changes +- Mode affects all subsequent responses +- Can be overridden per-command with flags + +## Command Flag Override + +Override mode for single command: +```bash +/feature --mode=implementation [desc] +/review --mode=deep-research [file] +/plan --mode=brainstorm [task] +``` + +## Recommended Workflows + +### Feature Development +``` +/mode brainstorm # Explore approaches +[discuss design] +/mode implementation # Execute plan +[write code] +/mode review # Check quality +[review code] +``` + +### Bug Investigation +``` +/mode deep-research # Investigate thoroughly +[analyze bug] +/mode implementation # Apply fix +[fix bug] +/mode default # Return to normal +``` + +### Cost-Conscious Session +``` +/mode token-efficient # Set for session +[work on multiple tasks] +/mode default # Reset when done +``` + +## Mode Files + +Mode definitions are in `.claude/modes/`: +- `default.md` +- `brainstorm.md` +- `token-efficient.md` +- `deep-research.md` +- `implementation.md` +- `review.md` +- `orchestration.md` + +Customize modes by editing these files. diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md index cc2afbd..961f311 100644 --- a/.claude/commands/plan.md +++ b/.claude/commands/plan.md @@ -256,6 +256,35 @@ Use `/execute-plan [plan-file]` for subagent-driven execution with code review g **Reference**: `.claude/skills/methodology/executing-plans/SKILL.md` +## Flags + +| Flag | Description | Example | +|------|-------------|---------| +| `--mode=[mode]` | Use specific behavioral mode | `--mode=brainstorm` | +| `--detailed` | Use superpowers methodology (2-5 min tasks) | `--detailed` | +| `--depth=[1-5]` | Planning thoroughness level | `--depth=4` | +| `--format=[fmt]` | Output format (concise/detailed/json) | `--format=detailed` | +| `--save=[path]` | Save plan to file | `--save=plans/auth.md` | +| `--checkpoint` | Create checkpoint after planning | `--checkpoint` | + +### Flag Usage Examples + +```bash +/plan --detailed "implement user authentication" +/plan --mode=brainstorm "redesign checkout flow" +/plan --depth=5 --save=plans/migration.md "database migration" +/plan --format=json "api endpoint structure" +``` + +### Mode Recommendations + +| Mode | Best For | +|------|----------| +| `default` | Standard planning | +| `brainstorm` | Exploratory planning, multiple approaches | +| `deep-research` | Complex features needing investigation | +| `implementation` | Quick plans for clear tasks | + ## Variations diff --git a/.claude/commands/research.md b/.claude/commands/research.md index f17f03a..8874098 100644 --- a/.claude/commands/research.md +++ b/.claude/commands/research.md @@ -31,6 +31,36 @@ Research: **$ARGUMENTS** - Recommendation - Next steps +## Flags + +| Flag | Description | Example | +|------|-------------|---------| +| `--mode=[mode]` | Use specific behavioral mode | `--mode=deep-research` | +| `--depth=[1-5]` | Research thoroughness level | `--depth=5` | +| `--format=[fmt]` | Output format (concise/detailed/json) | `--format=detailed` | +| `--save=[path]` | Save research to file | `--save=docs/research.md` | +| `--compare` | Focus on comparing alternatives | `--compare` | +| `--sequential` | Use sequential thinking methodology | `--sequential` | + +### Flag Usage Examples + +```bash +/research --depth=5 "authentication libraries for Node.js" +/research --compare "React vs Vue vs Svelte" +/research --sequential "root cause of memory leak" +/research --save=docs/orm-research.md "ORM comparison" +``` + +### Depth Levels + +| Level | Behavior | +|-------|----------| +| 1 | Quick overview, key points only | +| 2 | Standard analysis | +| 3 | Thorough with examples | +| 4 | Comprehensive with trade-offs | +| 5 | Exhaustive with citations | + ## Output ```markdown diff --git a/.claude/commands/review.md b/.claude/commands/review.md index b383902..30a86b6 100644 --- a/.claude/commands/review.md +++ b/.claude/commands/review.md @@ -252,6 +252,45 @@ Found **1 critical issue** (security), **2 recommendations**, and **2 suggestion **Output**: Complete review of all staged changes with security scan, code quality assessment, and actionable feedback organized by severity. +## Flags + +| Flag | Description | Example | +|------|-------------|---------| +| `--mode=[mode]` | Use specific behavioral mode | `--mode=review` | +| `--persona=[type]` | Apply persona expertise | `--persona=security` | +| `--depth=[1-5]` | Review thoroughness level | `--depth=5` | +| `--format=[fmt]` | Output format (concise/detailed/json) | `--format=detailed` | +| `--focus=[area]` | Focus on specific area | `--focus=performance` | +| `--save` | Save review to file | `--save` | + +### Flag Usage Examples + +```bash +/review --persona=security src/auth/ +/review --depth=5 --format=detailed staged +/review --focus=performance src/services/heavy-computation.ts +/review --mode=deep-research --save pr +``` + +### Persona Options + +| Persona | Focus Area | +|---------|------------| +| `security` | Vulnerabilities, auth, data protection | +| `performance` | Efficiency, queries, caching | +| `architecture` | Patterns, coupling, SOLID | +| `testing` | Coverage, test quality | +| `accessibility` | A11y compliance | + +### Focus Areas + +| Focus | Checks | +|-------|--------| +| `security` | OWASP top 10, auth, input validation | +| `performance` | N+1, complexity, memory | +| `quality` | Readability, maintainability | +| `testing` | Coverage, test patterns | + ## Variations diff --git a/.claude/commands/spawn.md b/.claude/commands/spawn.md new file mode 100644 index 0000000..e738c27 --- /dev/null +++ b/.claude/commands/spawn.md @@ -0,0 +1,173 @@ +# /spawn + +## Purpose + +Launch background tasks for parallel execution. Enables concurrent work on independent tasks with result aggregation. + +--- + +Launch a background task or manage running tasks. + +## Spawn Operations + +### Launch Task + +Start a new background task: + +```bash +/spawn "[task description]" +``` + +**Process:** +1. Analyze task for parallelizability +2. Launch subagent with task +3. Return task ID for tracking +4. Continue main conversation + +**Output:** +```markdown +Spawned: Task #1 +- Description: Research authentication patterns +- Status: Running +- Agent: researcher + +Continue working. Use `/spawn --list` to check status. +``` + +### List Tasks + +Show running and completed tasks: + +```bash +/spawn --list +``` + +**Output:** +```markdown +## Active Tasks + +| ID | Description | Status | Duration | +|----|-------------|--------|----------| +| #1 | Research auth patterns | Running | 2m | +| #2 | Analyze security | Complete | 5m | + +## Completed Tasks (last hour) +| #2 | Analyze security | ✅ Complete | Results ready | +``` + +### Collect Results + +Gather results from completed tasks: + +```bash +/spawn --collect +``` + +**Output:** +```markdown +## Collected Results + +### Task #1: Research auth patterns +**Status**: Complete +**Findings**: +- Pattern A: JWT with refresh tokens +- Pattern B: Session-based with Redis +- Recommendation: JWT for stateless API + +### Task #2: Analyze security +**Status**: Complete +**Findings**: +- 2 high-priority issues found +- See detailed report below +``` + +### Cancel Task + +Stop a running task: + +```bash +/spawn --cancel [id] +``` + +## Task Types + +| Type | Best For | Agent Used | +|------|----------|------------| +| Research | Information gathering | researcher | +| Analysis | Code analysis | scout | +| Review | Code review | code-reviewer | +| Test | Test generation | tester | +| Scan | Security scanning | security-auditor | + +## Flags + +| Flag | Description | +|------|-------------| +| `--list` | Show all tasks | +| `--collect` | Gather completed results | +| `--cancel [id]` | Cancel running task | +| `--wait` | Wait for all tasks to complete | +| `--agent=[type]` | Specify agent type | +| `--priority=[high\|normal]` | Task priority | + +## Usage Examples + +```bash +/spawn "Research OAuth2 best practices" +/spawn "Analyze user service for performance issues" +/spawn "Review security of auth module" --agent=security-auditor +/spawn --list +/spawn --collect +/spawn --wait # Block until all complete +``` + +## Arguments + +$ARGUMENTS + +If quoted text: spawn that task +If flag: execute that operation + +--- + +## Parallel Workflow + +### Pattern: Research Phase +```bash +/spawn "Research authentication approaches" +/spawn "Analyze current auth implementation" +/spawn "Review competitor auth patterns" +# Continue other work... +/spawn --wait +/spawn --collect +# Synthesize findings +``` + +### Pattern: Multi-File Review +```bash +/spawn "Review src/auth/ for security" +/spawn "Review src/api/ for performance" +/spawn "Review src/db/ for SQL injection" +/spawn --collect +# Address findings +``` + +## Best Practices + +1. **Independent Tasks**: Only spawn truly independent work +2. **Clear Descriptions**: Specific task descriptions get better results +3. **Regular Collection**: Don't let results pile up +4. **Resource Awareness**: Don't spawn too many concurrent tasks + +## Limitations + +- Tasks cannot communicate with each other +- Results are collected, not streamed +- Heavy tasks may take time +- Some tasks benefit from sequential execution + +## Combines With + +- Orchestration mode: Manages multiple spawned tasks +- `/plan`: Plan tasks, then spawn parallel execution +- `/execute-plan`: Orchestrated task execution diff --git a/.claude/commands/test.md b/.claude/commands/test.md index f6943c4..107a36b 100644 --- a/.claude/commands/test.md +++ b/.claude/commands/test.md @@ -249,6 +249,45 @@ pytest tests/services/auth.test.ts -v - Consider adding integration tests for full auth flow ``` +## Flags + +| Flag | Description | Example | +|------|-------------|---------| +| `--coverage` | Generate coverage-focused tests | `--coverage` | +| `--type=[type]` | Test type to generate | `--type=integration` | +| `--format=[fmt]` | Output format (concise/detailed) | `--format=concise` | +| `--framework=[fw]` | Specify test framework | `--framework=vitest` | +| `--tdd` | Generate TDD-style with failing tests first | `--tdd` | +| `--edge-cases` | Focus on edge case coverage | `--edge-cases` | + +### Flag Usage Examples + +```bash +/test --coverage src/services/ +/test --type=integration src/api/users.ts +/test --tdd src/utils/validator.ts +/test --edge-cases --framework=pytest src/models/user.py +``` + +### Test Types + +| Type | Description | +|------|-------------| +| `unit` | Isolated function tests (default) | +| `integration` | Multi-component tests | +| `e2e` | End-to-end workflow tests | +| `snapshot` | Snapshot tests for UI | +| `property` | Property-based testing | + +### Framework Options + +| Framework | Language | +|-----------|----------| +| `pytest` | Python | +| `vitest` | TypeScript/JavaScript | +| `jest` | JavaScript | +| `playwright` | E2E (any) | + ## Variations diff --git a/.claude/mcp/README.md b/.claude/mcp/README.md new file mode 100644 index 0000000..87ea10b --- /dev/null +++ b/.claude/mcp/README.md @@ -0,0 +1,160 @@ +# MCP Server Integrations + +Model Context Protocol (MCP) servers extend Claude Code capabilities with specialized tools and integrations. + +## Available MCP Servers + +| Server | Purpose | Status | +|--------|---------|--------| +| Context7 | Up-to-date library documentation | Optional | +| Sequential | Multi-step reasoning tools | Optional | +| Puppeteer | Browser automation | Optional | +| Magic | UI component generation | Optional | + +## Installation + +### Prerequisites +- Node.js 18+ +- npx available in PATH + +### Global Configuration + +MCP servers are configured in your Claude Code settings: + +**Location**: `~/.claude/settings.json` (user) or `.claude/settings.json` (project) + +### Quick Setup + +1. Copy the desired configuration from the server-specific JSON files +2. Add to your `settings.json` under `mcpServers` +3. Restart Claude Code + +## Server Configurations + +### Context7 (Documentation Lookup) + +Provides up-to-date documentation for libraries and frameworks. + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@context7/mcp-server"] + } + } +} +``` + +**Usage**: Ask about any library and get current documentation. + +### Sequential Thinking + +Provides structured reasoning tools for complex problem-solving. + +```json +{ + "mcpServers": { + "sequential": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] + } + } +} +``` + +**Usage**: Complex analysis with step-by-step reasoning. + +### Puppeteer (Browser Automation) + +Enables browser automation for testing and web interaction. + +```json +{ + "mcpServers": { + "puppeteer": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-puppeteer"] + } + } +} +``` + +**Usage**: Web testing, screenshots, form automation. + +### Magic (UI Generation) + +Generates UI components from descriptions. + +```json +{ + "mcpServers": { + "magic": { + "command": "npx", + "args": ["-y", "@anthropic/magic-mcp-server"] + } + } +} +``` + +**Usage**: Generate React/Vue components from descriptions. + +## Full Configuration Example + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@context7/mcp-server"] + }, + "sequential": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] + }, + "puppeteer": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-puppeteer"] + } + } +} +``` + +## Verification + +After configuration, verify servers are loaded: + +1. Start a new Claude Code session +2. Check for MCP tools in available capabilities +3. Test with a simple request + +## Troubleshooting + +### Server Not Loading +- Check Node.js version (18+ required) +- Verify npx is in PATH +- Check for typos in configuration +- Review Claude Code logs + +### Permission Errors +- Ensure network access for package installation +- Check firewall settings +- Verify npm registry access + +### Slow Startup +- First run downloads packages (one-time) +- Subsequent starts should be faster +- Consider pre-installing packages globally + +## Security Notes + +- MCP servers run with your user permissions +- Review server source before installing +- Puppeteer has browser access - use carefully +- Context7 makes network requests to documentation sources + +## Resources + +- [MCP Protocol Documentation](https://modelcontextprotocol.io/) +- [Available MCP Servers](https://github.com/modelcontextprotocol/servers) +- [Claude Code MCP Guide](https://docs.anthropic.com/claude-code/mcp) diff --git a/.claude/mcp/context7.json b/.claude/mcp/context7.json new file mode 100644 index 0000000..fd9ed40 --- /dev/null +++ b/.claude/mcp/context7.json @@ -0,0 +1,31 @@ +{ + "name": "context7", + "description": "Up-to-date library documentation lookup via Context7", + "config": { + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@context7/mcp-server"] + } + } + }, + "capabilities": [ + "Library documentation lookup", + "API reference retrieval", + "Framework documentation", + "Package documentation" + ], + "usage": { + "example_prompts": [ + "What's the latest API for React useEffect?", + "Show me FastAPI dependency injection docs", + "How do I use Prisma transactions?", + "What are the Next.js 14 app router conventions?" + ] + }, + "requirements": { + "node": ">=18.0.0", + "network": true + }, + "notes": "Provides real-time documentation lookup. Useful for getting current API information that may be newer than training data." +} diff --git a/.claude/mcp/magic.json b/.claude/mcp/magic.json new file mode 100644 index 0000000..66897b2 --- /dev/null +++ b/.claude/mcp/magic.json @@ -0,0 +1,43 @@ +{ + "name": "magic", + "description": "AI-powered UI component generation from descriptions", + "config": { + "mcpServers": { + "magic": { + "command": "npx", + "args": ["-y", "@anthropic/magic-mcp-server"] + } + } + }, + "capabilities": [ + "UI component generation", + "React component creation", + "Tailwind CSS styling", + "Responsive design", + "Component variations" + ], + "usage": { + "example_prompts": [ + "Generate a pricing card component", + "Create a navigation header with dropdown menus", + "Build a user profile card with avatar and stats", + "Design a dashboard layout with sidebar", + "Make a responsive hero section" + ] + }, + "requirements": { + "node": ">=18.0.0", + "network": true + }, + "output": { + "formats": ["React", "Vue", "HTML"], + "styling": ["Tailwind CSS", "CSS Modules", "Styled Components"], + "features": [ + "Responsive by default", + "Accessible markup", + "Dark mode support", + "Component composition" + ] + }, + "notes": "Generates production-ready UI components. Best used with Tailwind CSS projects. Review generated code before using in production." +} diff --git a/.claude/mcp/puppeteer.json b/.claude/mcp/puppeteer.json new file mode 100644 index 0000000..43666fb --- /dev/null +++ b/.claude/mcp/puppeteer.json @@ -0,0 +1,43 @@ +{ + "name": "puppeteer", + "description": "Browser automation for testing and web interaction", + "config": { + "mcpServers": { + "puppeteer": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-puppeteer"] + } + } + }, + "capabilities": [ + "Browser automation", + "Screenshot capture", + "Form interaction", + "Page navigation", + "DOM manipulation", + "Network interception" + ], + "usage": { + "example_prompts": [ + "Take a screenshot of the login page", + "Fill out the registration form and submit", + "Navigate through the checkout flow", + "Extract data from this web page", + "Test the responsive design at different viewports" + ] + }, + "requirements": { + "node": ">=18.0.0", + "chromium": "Auto-downloaded by Puppeteer" + }, + "security": { + "warning": "Puppeteer has full browser access. Use with caution.", + "recommendations": [ + "Only use on trusted sites", + "Avoid entering real credentials", + "Review actions before execution", + "Use in sandboxed environments when possible" + ] + }, + "notes": "Powerful for E2E testing and web automation. Use responsibly and verify actions before execution." +} diff --git a/.claude/mcp/sequential.json b/.claude/mcp/sequential.json new file mode 100644 index 0000000..491a6dd --- /dev/null +++ b/.claude/mcp/sequential.json @@ -0,0 +1,31 @@ +{ + "name": "sequential-thinking", + "description": "Structured multi-step reasoning tools for complex analysis", + "config": { + "mcpServers": { + "sequential": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] + } + } + }, + "capabilities": [ + "Step-by-step reasoning", + "Hypothesis tracking", + "Evidence collection", + "Confidence scoring", + "Decision documentation" + ], + "usage": { + "example_prompts": [ + "Analyze this bug systematically", + "Walk through this architecture decision step by step", + "Investigate the root cause with sequential thinking", + "Document the reasoning for this design choice" + ] + }, + "requirements": { + "node": ">=18.0.0" + }, + "notes": "Enhances complex problem-solving with structured reasoning. Pairs well with the sequential-thinking skill and deep-research mode." +} diff --git a/.claude/modes/brainstorm.md b/.claude/modes/brainstorm.md new file mode 100644 index 0000000..3293734 --- /dev/null +++ b/.claude/modes/brainstorm.md @@ -0,0 +1,87 @@ +# Brainstorm Mode + +## Description + +Creative exploration mode optimized for ideation, design discussions, and exploring alternatives. Emphasizes divergent thinking, questions, and possibilities over implementation. + +## When to Use + +- Initial feature exploration +- Architecture decisions +- Problem definition +- Design sessions +- When stuck on approach + +--- + +## Behavior + +### Communication +- Ask more questions before concluding +- Present multiple alternatives +- Explore edge cases verbally +- Use "what if" scenarios + +### Problem Solving +- Divergent thinking first +- Delay convergence on solutions +- Consider unconventional approaches +- Map trade-offs explicitly + +### Output Format +- Structured comparisons +- Pro/con lists +- Decision matrices +- Visual diagrams (ASCII/Mermaid) + +--- + +## Activation + +``` +Use mode: brainstorm +``` + +Or use command flag: +``` +/plan --mode=brainstorm [task] +/feature --mode=brainstorm [desc] +``` + +--- + +## Example Behaviors + +### Before Implementing +``` +Before we implement, let me explore some approaches: + +Option A: [approach] +- Pros: ... +- Cons: ... + +Option B: [approach] +- Pros: ... +- Cons: ... + +Which direction interests you? Or should we explore more options? +``` + +### Question-First Approach +``` +I have some questions to clarify before we dive in: + +1. [Clarifying question about scope] +2. [Question about constraints] +3. [Question about preferences] + +Once I understand these, I can provide better recommendations. +``` + +--- + +## Combines Well With + +- `/brainstorm` command +- `/plan` command +- Deep research mode (for informed exploration) diff --git a/.claude/modes/deep-research.md b/.claude/modes/deep-research.md new file mode 100644 index 0000000..f111757 --- /dev/null +++ b/.claude/modes/deep-research.md @@ -0,0 +1,132 @@ +# Deep Research Mode + +## Description + +Thorough analysis mode for comprehensive investigation. Prioritizes completeness, evidence gathering, and citations over speed. Use when accuracy and depth matter more than efficiency. + +## When to Use + +- Technology evaluation +- Architecture research +- Security audits +- Performance analysis +- Complex debugging +- Due diligence tasks + +--- + +## Behavior + +### Communication +- Cite sources and evidence +- Acknowledge uncertainty explicitly +- Present confidence levels +- Include caveats and limitations + +### Problem Solving +- Exhaustive exploration +- Multiple verification passes +- Cross-reference findings +- Document assumptions + +### Output Format +- Structured reports +- Evidence sections +- Source citations +- Confidence indicators + +--- + +## Research Process + +### Phase 1: Scope Definition +- Clarify research questions +- Define success criteria +- Identify constraints + +### Phase 2: Information Gathering +- Search codebase thoroughly +- Consult documentation +- Web research if needed +- Gather all relevant data + +### Phase 3: Analysis +- Cross-reference findings +- Identify patterns +- Note contradictions +- Assess reliability + +### Phase 4: Synthesis +- Draw conclusions +- Present evidence +- State confidence levels +- Acknowledge gaps + +--- + +## Output Format + +```markdown +## Research: [Topic] + +### Question +[What we're investigating] + +### Methodology +[How we researched] + +### Findings + +#### Finding 1: [Title] +- Evidence: [source/location] +- Confidence: [High/Medium/Low] +- Details: [explanation] + +#### Finding 2: [Title] +... + +### Conclusions +- [Conclusion 1] (Confidence: X/10) +- [Conclusion 2] (Confidence: X/10) + +### Gaps & Limitations +- [What we couldn't determine] +- [Areas needing more investigation] + +### Sources +- [Source 1] +- [Source 2] +``` + +--- + +## Activation + +``` +Use mode: deep-research +``` + +Or use command flag: +``` +/research --mode=deep-research [topic] +/review --depth=5 [file] +``` + +### Depth Levels + +| Level | Behavior | +|-------|----------| +| 1 | Quick scan, surface findings | +| 2 | Standard analysis | +| 3 | Thorough investigation | +| 4 | Comprehensive with cross-references | +| 5 | Exhaustive, leave no stone unturned | + +--- + +## Combines Well With + +- `/research` command +- Sequential thinking skill +- Security audits +- Performance optimization diff --git a/.claude/modes/default.md b/.claude/modes/default.md new file mode 100644 index 0000000..62ec19a --- /dev/null +++ b/.claude/modes/default.md @@ -0,0 +1,50 @@ +# Default Mode + +## Description + +Standard balanced mode for general development tasks. This is the baseline behavior that provides a good mix of thoroughness and efficiency. + +## When Active + +This mode is active by default unless another mode is explicitly specified. + +--- + +## Behavior + +### Communication +- Clear, concise responses +- Balance between explanation and action +- Standard code comments where helpful + +### Problem Solving +- Balanced analysis depth +- Standard verification steps +- Normal iteration cycles + +### Output Format +- Full code blocks with context +- Explanations where helpful +- Standard documentation level + +--- + +## Activation + +This mode is active by default. No activation needed. + +To switch to another mode: +``` +Use mode: [mode-name] +``` + +Or use command flags: +``` +/command --mode=default +``` + +--- + +## Compatible With + +All commands and workflows. This mode provides baseline behavior that other modes modify. diff --git a/.claude/modes/implementation.md b/.claude/modes/implementation.md new file mode 100644 index 0000000..fca4886 --- /dev/null +++ b/.claude/modes/implementation.md @@ -0,0 +1,120 @@ +# Implementation Mode + +## Description + +Code-focused execution mode that minimizes discussion and maximizes code output. For when the plan is clear and it's time to build. + +## When to Use + +- Executing approved plans +- Clear, well-defined tasks +- Repetitive code generation +- When design is already decided +- Batch file operations + +--- + +## Behavior + +### Communication +- Minimal prose +- Action-oriented updates +- Progress indicators only +- Skip explanations unless asked + +### Problem Solving +- Execute, don't deliberate +- Follow established patterns +- Make reasonable defaults +- Flag blockers immediately + +### Output Format +- Code blocks primarily +- File paths clearly marked +- Minimal inline comments +- Progress checkmarks + +--- + +## Output Pattern + +```markdown +Creating `src/services/user-service.ts`: +```typescript +[code] +``` + +Creating `src/services/user-service.test.ts`: +```typescript +[code] +``` + +Running tests... +✓ 5 passing + +Committing: `feat(user): add user service` +``` + +--- + +## Execution Flow + +### Standard Pattern +1. Read task requirements +2. Identify files to create/modify +3. Generate code +4. Run verification +5. Report completion + +### Progress Updates +``` +[1/5] Creating model... +[2/5] Creating service... +[3/5] Creating tests... +[4/5] Running tests... ✓ +[5/5] Committing... + +Done. Created 3 files, all tests passing. +``` + +--- + +## Activation + +``` +Use mode: implementation +``` + +Or use command flag: +``` +/feature --mode=implementation [desc] +/execute-plan --mode=implementation [file] +``` + +--- + +## Decision Making + +When encountering choices during implementation: + +| Situation | Behavior | +|-----------|----------| +| Style choice | Follow existing patterns | +| Missing detail | Use reasonable default | +| Ambiguity | Flag and continue with assumption | +| Blocker | Stop and report immediately | + +### Flagging Format +``` +⚠️ Assumed: [assumption made] +Continuing with [choice]. Let me know if you'd prefer different. +``` + +--- + +## Combines Well With + +- `/execute-plan` command +- Token-efficient mode (for maximum efficiency) +- After brainstorm/planning phases +- TDD workflow diff --git a/.claude/modes/orchestration.md b/.claude/modes/orchestration.md new file mode 100644 index 0000000..f88cba0 --- /dev/null +++ b/.claude/modes/orchestration.md @@ -0,0 +1,182 @@ +# Orchestration Mode + +## Description + +Multi-agent coordination mode for managing complex tasks that benefit from parallel execution, task delegation, and result aggregation. Optimized for efficiency through parallelization. + +## When to Use + +- Large-scale refactoring +- Multi-file changes +- Complex feature implementation +- When tasks are parallelizable +- Coordinating multiple concerns + +--- + +## Behavior + +### Communication +- Task delegation clarity +- Progress aggregation +- Coordination updates +- Final synthesis + +### Problem Solving +- Identify parallelizable work +- Delegate to specialized agents +- Aggregate results +- Resolve conflicts + +### Output Format +- Task breakdown +- Agent assignments +- Progress tracking +- Consolidated results + +--- + +## Orchestration Pattern + +### Phase 1: Analysis +```markdown +## Task Decomposition + +Total work: [description] + +### Parallelizable Tasks +1. [Task A] - Can run independently +2. [Task B] - Can run independently +3. [Task C] - Can run independently + +### Sequential Tasks +4. [Task D] - Depends on A, B +5. [Task E] - Final integration +``` + +### Phase 2: Delegation +```markdown +## Agent Assignments + +| Task | Agent Type | Status | +|------|------------|--------| +| Task A | researcher | 🔄 Running | +| Task B | tester | 🔄 Running | +| Task C | code-reviewer | 🔄 Running | +``` + +### Phase 3: Aggregation +```markdown +## Results + +### Task A: Complete ✅ +- Findings: [summary] + +### Task B: Complete ✅ +- Results: [summary] + +### Task C: Complete ✅ +- Findings: [summary] + +### Synthesis +[Combined conclusions and next steps] +``` + +--- + +## Spawn Pattern + +For launching parallel background tasks: + +```markdown +Spawning parallel agents: + +1. `/spawn "Research authentication patterns"` → Agent #1 +2. `/spawn "Analyze current security"` → Agent #2 +3. `/spawn "Review competitor approaches"` → Agent #3 + +Monitoring progress... + +Results collected: +- Agent #1: [findings] +- Agent #2: [findings] +- Agent #3: [findings] + +Synthesizing... +``` + +--- + +## Activation + +``` +Use mode: orchestration +``` + +Or use command flag: +``` +/feature --mode=orchestration [desc] +/plan --mode=orchestration [task] +``` + +--- + +## Task Parallelization Rules + +### Good Candidates for Parallel +- Independent file modifications +- Research tasks across different areas +- Test generation for different modules +- Documentation for separate components + +### Must Be Sequential +- Tasks with dependencies +- Database migrations +- Changes to shared state +- Integration after parallel work + +### Decision Matrix + +| Condition | Parallelize? | +|-----------|--------------| +| No shared files | ✅ Yes | +| Independent modules | ✅ Yes | +| Shared dependencies | ❌ No | +| Order matters | ❌ No | +| Can merge results | ✅ Yes | + +--- + +## Quality Gates + +Between parallel phases: +1. Verify all agents completed +2. Check for conflicts +3. Review combined results +4. Run integration tests +5. Proceed to next phase + +```markdown +## Quality Gate: Phase 1 → Phase 2 + +### Completion Check +- [x] Agent A: Complete +- [x] Agent B: Complete +- [x] Agent C: Complete + +### Conflict Check +- [x] No file conflicts +- [x] No logical conflicts +- [x] Results consistent + +### Proceeding to Phase 2... +``` + +--- + +## Combines Well With + +- `/spawn` command +- `/execute-plan` command +- Dispatching-parallel-agents skill +- Complex feature development diff --git a/.claude/modes/review.md b/.claude/modes/review.md new file mode 100644 index 0000000..cfba28c --- /dev/null +++ b/.claude/modes/review.md @@ -0,0 +1,145 @@ +# Review Mode + +## Description + +Critical analysis mode optimized for code review, auditing, and quality assessment. Emphasizes finding issues, suggesting improvements, and thorough examination. + +## When to Use + +- Code reviews +- Security audits +- Performance reviews +- Pre-merge checks +- Quality assessments +- Architecture reviews + +--- + +## Behavior + +### Communication +- Direct feedback +- Prioritized findings +- Constructive criticism +- Specific, actionable suggestions + +### Problem Solving +- Look for issues first +- Question assumptions +- Check edge cases +- Verify against standards + +### Output Format +- Categorized findings +- Severity levels +- Line-specific comments +- Improvement suggestions + +--- + +## Review Categories + +### Severity Levels + +| Level | Icon | Description | Action | +|-------|------|-------------|--------| +| Critical | 🔴 | Bugs, security issues | Must fix before merge | +| Important | 🟠 | Code smells, performance | Should fix | +| Minor | 🟡 | Style, naming | Consider fixing | +| Nitpick | ⚪ | Preferences | Optional | + +### Review Areas + +| Area | Focus | +|------|-------| +| Correctness | Does it work? Edge cases? | +| Security | Vulnerabilities, data exposure | +| Performance | Efficiency, scalability | +| Maintainability | Readability, complexity | +| Testing | Coverage, quality of tests | +| Standards | Convention compliance | + +--- + +## Output Format + +```markdown +## Code Review: [file/PR] + +### Summary +[1-2 sentence overview] + +### Critical Issues 🔴 +1. **[Issue]** (line X) + - Problem: [description] + - Fix: [suggestion] + +### Important Issues 🟠 +1. **[Issue]** (line X) + - Problem: [description] + - Suggestion: [improvement] + +### Minor Issues 🟡 +- Line X: [issue and suggestion] +- Line Y: [issue and suggestion] + +### Positive Notes ✅ +- [What was done well] + +### Verdict +[ ] Ready to merge +[x] Needs changes (N critical, M important issues) +``` + +--- + +## Activation + +``` +Use mode: review +``` + +Or use command flag: +``` +/review --mode=review [file] +/review --persona=security [file] +``` + +### Persona Options + +| Persona | Focus | +|---------|-------| +| `security` | OWASP, vulnerabilities, auth | +| `performance` | Efficiency, caching, queries | +| `architecture` | Patterns, coupling, design | +| `testing` | Coverage, test quality | + +--- + +## Checklist Template + +```markdown +### Pre-Review Checklist +- [ ] Tests pass +- [ ] Lint clean +- [ ] No security warnings +- [ ] Coverage maintained + +### Review Checklist +- [ ] Logic correctness verified +- [ ] Edge cases handled +- [ ] Error handling adequate +- [ ] Security patterns followed +- [ ] Performance acceptable +- [ ] Code readable/maintainable +- [ ] Tests cover new code +``` + +--- + +## Combines Well With + +- `/review` command +- Deep research mode (for thorough audits) +- Security auditor agent +- Code reviewer agent diff --git a/.claude/modes/token-efficient.md b/.claude/modes/token-efficient.md new file mode 100644 index 0000000..5a9d666 --- /dev/null +++ b/.claude/modes/token-efficient.md @@ -0,0 +1,116 @@ +# Token-Efficient Mode + +## Description + +Cost optimization mode that produces compressed, concise outputs while maintaining accuracy. Reduces token usage by 30-70% depending on task type. + +## When to Use + +- High-volume sessions +- Simple tasks +- When cost is a concern +- Repeated similar operations +- Quick iterations + +--- + +## Behavior + +### Communication +- Minimal explanations +- No conversational filler +- Direct answers only +- Skip obvious context + +### Problem Solving +- Jump to solutions +- Assume competence +- Skip basic explanations +- Reference docs instead of explaining + +### Output Format +- Code without surrounding prose +- Abbreviated comments +- Terse commit messages +- Bullet points over paragraphs + +--- + +## Output Patterns + +### Standard vs Token-Efficient + +**Standard:** +``` +I'll help you fix this bug. First, let me explain what's happening. +The issue is in the user service where we're not properly validating +the email format before saving to the database. Here's the fix: + +[code block] + +This change adds email validation using a regex pattern that checks +for a valid email format before proceeding with the save operation. +``` + +**Token-Efficient:** +``` +Fix: Add email validation + +[code block] +``` + +### Compression Techniques + +| Technique | Savings | +|-----------|---------| +| Skip preambles | 20-30% | +| Code-only responses | 40-50% | +| Abbreviated comments | 10-15% | +| Reference over explain | 30-40% | + +--- + +## Activation + +``` +Use mode: token-efficient +``` + +Or use command flag: +``` +/fix --format=concise [error] +/feature --format=ultra [desc] +``` + +### Format Levels + +| Level | Flag | Savings | +|-------|------|---------| +| Concise | `--format=concise` | 30-40% | +| Ultra | `--format=ultra` | 60-70% | + +--- + +## When NOT to Use + +- Complex architectural decisions +- Code reviews (need thorough analysis) +- Documentation tasks +- Teaching/explanation requests +- Debugging complex issues + +--- + +## Example Output + +**Request:** Fix the null pointer in user.ts + +**Token-Efficient Response:** +```typescript +// user.ts:42 +if (!user) return null; +// Before: user.name (crashes when null) +// After: user?.name ?? 'Unknown' +``` + +Done. Test: `npm test -- --grep "null user"` diff --git a/.claude/settings.json b/.claude/settings.json index 6c5bd15..4dcf6ec 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -3,6 +3,7 @@ "allow": [ "Bash(git:*)", "Bash(npm:*)", + "Bash(npx:*)", "Bash(pnpm:*)", "Bash(yarn:*)", "Bash(pip:*)", @@ -22,6 +23,25 @@ ], "deny": [] }, + "mcpServers": { + "_comment": "Uncomment servers to enable. See .claude/mcp/README.md for setup.", + "_context7": { + "command": "npx", + "args": ["-y", "@context7/mcp-server"] + }, + "_sequential": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] + }, + "_puppeteer": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-puppeteer"] + }, + "_magic": { + "command": "npx", + "args": ["-y", "@anthropic/magic-mcp-server"] + } + }, "hooks": { "PostToolUse": [ { diff --git a/.claude/skills/methodology/sequential-thinking/SKILL.md b/.claude/skills/methodology/sequential-thinking/SKILL.md new file mode 100644 index 0000000..6a24609 --- /dev/null +++ b/.claude/skills/methodology/sequential-thinking/SKILL.md @@ -0,0 +1,212 @@ +# Sequential Thinking + +## Description + +Step-by-step reasoning methodology with explicit evidence collection and confidence tracking. Use for complex problems requiring careful analysis and documented decision-making. + +## When to Use + +- Complex debugging +- Architecture decisions +- Security analysis +- Performance investigation +- Any problem with multiple possible causes +- When decisions need documentation + +--- + +## The Sequential Process + +### Step 1: Define the Question +Clearly state what you're trying to determine. + +```markdown +## Question +What is causing the authentication timeout for users with special characters in passwords? +``` + +### Step 2: Gather Evidence +Collect all relevant information systematically. + +```markdown +## Evidence Collection + +### Evidence 1: Error Logs +- Source: `logs/auth-service.log` +- Finding: Timeout occurs at password encoding step +- Confidence: High (direct observation) + +### Evidence 2: Code Review +- Source: `src/auth/password.ts:42` +- Finding: URL encoding applied to password +- Confidence: High (code inspection) + +### Evidence 3: Test Results +- Source: Manual testing +- Finding: Works with alphanumeric, fails with `@#$` +- Confidence: High (reproducible) +``` + +### Step 3: Form Hypotheses +Generate possible explanations. + +```markdown +## Hypotheses + +### Hypothesis A: URL Encoding Issue +- Evidence supporting: E1, E2, E3 +- Evidence against: None +- Probability: 80% + +### Hypothesis B: Character Set Mismatch +- Evidence supporting: E3 +- Evidence against: E2 (UTF-8 used) +- Probability: 15% + +### Hypothesis C: Database Encoding +- Evidence supporting: None directly +- Evidence against: E1 (fails before DB) +- Probability: 5% +``` + +### Step 4: Test Hypotheses +Verify the most likely explanation. + +```markdown +## Testing + +### Test for Hypothesis A +Action: Remove URL encoding, use base64 instead +Result: Password `test@123` now works +Conclusion: Hypothesis A confirmed +``` + +### Step 5: Document Conclusion +State the final answer with confidence. + +```markdown +## Conclusion + +**Root Cause**: URL encoding in password.ts:42 mangles special characters + +**Confidence**: 9/10 + +**Evidence Chain**: +1. Timeout at encoding step (logs) +2. URL encoding in code (review) +3. Special char passwords fail (testing) +4. Removing encoding fixes issue (verification) + +**Fix**: Replace URL encoding with base64 at line 42 +``` + +--- + +## Output Template + +```markdown +# Sequential Analysis: [Problem Description] + +## Question +[Clear statement of what we're investigating] + +## Evidence + +### Evidence 1: [Title] +- Source: [where found] +- Finding: [what it shows] +- Confidence: [High/Medium/Low] + +### Evidence 2: [Title] +... + +## Hypotheses + +### Hypothesis A: [Name] +- Supporting evidence: [list] +- Contradicting evidence: [list] +- Probability: [X%] + +### Hypothesis B: [Name] +... + +## Testing + +### Test 1: [What tested] +- Action: [what was done] +- Expected: [what should happen if hypothesis true] +- Actual: [what happened] +- Result: [confirms/refutes hypothesis] + +## Conclusion + +**Answer**: [clear statement] +**Confidence**: [X/10] +**Key Evidence**: [most important findings] +**Recommended Action**: [what to do next] +``` + +--- + +## Confidence Scoring + +| Score | Meaning | Evidence Required | +|-------|---------|-------------------| +| 9-10 | Certain | Multiple independent confirmations | +| 7-8 | High | Strong evidence, tested hypothesis | +| 5-6 | Medium | Good evidence, some uncertainty | +| 3-4 | Low | Limited evidence, multiple possibilities | +| 1-2 | Guess | Insufficient evidence | + +--- + +## Anti-Patterns + +### Jumping to Conclusions +```markdown +❌ "The bug is probably in the database" +✅ "Let me gather evidence before hypothesizing" +``` + +### Confirmation Bias +```markdown +❌ Only looking for evidence supporting first guess +✅ Actively seeking contradicting evidence +``` + +### Skipping Documentation +```markdown +❌ Fixing without recording reasoning +✅ Document even simple analysis for future reference +``` + +--- + +## Activation + +### Via Mode +``` +Use mode: deep-research +``` + +### Via Command +``` +Apply sequential thinking to analyze [problem] +``` + +### Via Skill Reference +``` +Use skill: sequential-thinking +``` + +--- + +## Combines Well With + +- Deep research mode +- Systematic debugging skill +- Root cause tracing skill +- Security audits +- Performance investigations + +--- diff --git a/.claude/skills/optimization/token-efficient/SKILL.md b/.claude/skills/optimization/token-efficient/SKILL.md new file mode 100644 index 0000000..62dd6fb --- /dev/null +++ b/.claude/skills/optimization/token-efficient/SKILL.md @@ -0,0 +1,198 @@ +# Token Optimization + +## Description + +Patterns and techniques for reducing token usage while maintaining response quality. Achieve 30-70% cost savings through strategic output compression. + +## When to Use + +- High-volume development sessions +- Repetitive tasks +- Simple, clear requests +- Cost-sensitive projects +- Quick iterations + +--- + +## Compression Levels + +### Level 1: Concise (30-40% savings) +- Remove conversational filler +- Skip obvious explanations +- Use bullet points +- Shorter variable names in examples + +### Level 2: Compact (50-60% savings) +- Code-only responses +- No surrounding prose +- Abbreviated comments +- Reference docs instead of explaining + +### Level 3: Ultra (60-70% savings) +- Minimal viable response +- Essential code only +- No comments +- Diff format for changes + +--- + +## Compression Techniques + +### Remove Preambles + +```markdown +❌ VERBOSE: +"I'll help you with that. Let me analyze the code and provide +a solution. Based on what I see, the issue is..." + +✅ CONCISE: +"Issue: null check missing at line 42. Fix:" +``` + +### Code-Only Responses + +```markdown +❌ VERBOSE: +"Here's the implementation. I've added proper error handling +and made sure to follow the existing patterns in your codebase. +The function now validates input and returns early if invalid." + +[large code block] + +"This should fix the issue. Let me know if you have questions." + +✅ CONCISE: +[code block] +``` + +### Reference Over Explain + +```markdown +❌ VERBOSE: +"React's useEffect hook runs after render. The dependency array +controls when it re-runs. Empty array means run once on mount..." + +✅ CONCISE: +"Add `userId` to deps array. See: https://react.dev/reference/react/useEffect" +``` + +### Diff Format for Changes + +```markdown +❌ VERBOSE: +"I've updated the file. Here's the complete new version:" +[entire file] + +✅ CONCISE: +```diff +- const user = getUser(); ++ const user = getUser() ?? defaultUser; +``` +Line 42 in user-service.ts +``` + +--- + +## Output Templates + +### Bug Fix +``` +Fix: [brief description] +File: [path:line] +[code or diff] +Verify: [test command] +``` + +### Feature Addition +``` +Added: [feature] +Files: [list] +[code blocks] +Test: [command] +``` + +### Refactor +``` +Refactor: [what] +[diff format changes] +No behavior change. +``` + +--- + +## When NOT to Compress + +| Situation | Why | +|-----------|-----| +| Complex architecture | Need full context | +| Security issues | Must explain risks | +| Code reviews | Thoroughness required | +| Teaching/explaining | Clarity matters | +| Debugging complex issues | Details help | +| First-time patterns | Context needed | + +--- + +## Activation + +### Via Mode +``` +Use mode: token-efficient +``` + +### Via Flag +``` +/command --format=concise +/command --format=ultra +``` + +### Session-Wide +``` +For this session, use token-efficient mode. +``` + +--- + +## Metrics + +### Typical Savings by Task + +| Task Type | Verbose Tokens | Concise Tokens | Savings | +|-----------|----------------|----------------|---------| +| Bug fix | ~500 | ~150 | 70% | +| Feature | ~2000 | ~800 | 60% | +| Refactor | ~1000 | ~400 | 60% | +| Explanation | ~800 | ~300 | 62% | + +### ROI Calculation +``` +Sessions per day: 10 +Avg tokens per session: 50,000 +With optimization: 25,000 +Daily savings: 250,000 tokens +Monthly savings: ~7.5M tokens +``` + +--- + +## Best Practices + +1. **Match compression to task complexity** + - Simple task → High compression + - Complex task → Lower compression + +2. **Preserve essential information** + - File paths always included + - Test commands always included + - Error context when relevant + +3. **Use progressive disclosure** + - Start concise + - Expand if asked + +4. **Know when to stop compressing** + - User confusion → Add context + - Errors occurring → Add detail + - Review needed → Full output + +--- diff --git a/README.md b/README.md index 5d0bb22..8ac42a1 100644 --- a/README.md +++ b/README.md @@ -5,10 +5,13 @@ A comprehensive toolkit for Claude Code to accelerate development workflows for ## Features - **20 Specialized Agents** - From planning to deployment -- **22+ Slash Commands** - Workflow automation -- **28+ Skills** - Framework, language, and methodology expertise -- **13 Methodology Skills** - Superpowers development workflow -- **CI/CD, Security, and API Extensions** - Extended capabilities +- **27+ Slash Commands** - Workflow automation with flag support +- **30+ Skills** - Framework, language, methodology, and optimization expertise +- **7 Behavioral Modes** - Task-specific response optimization +- **Command Flag System** - Combinable `--flag` syntax for customization +- **Token Optimization** - 30-70% cost savings with compressed output modes +- **MCP Integrations** - Context7, Sequential Thinking, Puppeteer, Magic +- **Context Management** - Project indexing, checkpoints, parallel tasks ## Quick Start @@ -21,10 +24,16 @@ A comprehensive toolkit for Claude Code to accelerate development workflows for ``` .claude/ ├── CLAUDE.md # Project context (customize this!) -├── settings.json # Hooks and permissions +├── settings.json # Hooks, permissions, and MCP config ├── agents/ # 20 specialized agents -├── commands/ # 20+ workflow commands -└── skills/ # Framework and language skills +├── commands/ # 27+ workflow commands +├── modes/ # 7 behavioral mode definitions +├── mcp/ # MCP server configurations +└── skills/ # Framework, language, and methodology skills + ├── frameworks/ # FastAPI, Next.js, React, etc. + ├── languages/ # Python, TypeScript, JavaScript + ├── methodology/ # TDD, debugging, planning (14 skills) + └── optimization/ # Token efficiency patterns ``` ## Agents @@ -94,6 +103,15 @@ A comprehensive toolkit for Claude Code to accelerate development workflows for /optimize [file] # Performance optimization ``` +### Context & Modes (New) +```bash +/mode [name] # Switch behavioral mode +/index # Generate project index +/load [component] # Load project context +/checkpoint [action] # Save/restore session state +/spawn [task] # Launch parallel background task +``` + ## Skills ### Languages @@ -117,6 +135,10 @@ A comprehensive toolkit for Claude Code to accelerate development workflows for ### Testing - pytest, vitest +### Optimization +- Token-efficient output patterns +- Sequential thinking methodology + ### Methodology (Superpowers) | Category | Skills | @@ -131,6 +153,78 @@ Key methodology principles: - **Verification**: Evidence-based completion claims - **Quality Gates**: Code review between every task - **Bite-sized Tasks**: 2-5 minute increments with exact code +- **Sequential Thinking**: Step-by-step reasoning with confidence scores + +## Behavioral Modes + +Switch modes to optimize responses for different task types: + +| Mode | Description | Best For | +|------|-------------|----------| +| `default` | Balanced standard behavior | General tasks | +| `brainstorm` | Creative exploration, questions | Design, ideation | +| `token-efficient` | Compressed, concise output | Cost savings | +| `deep-research` | Thorough analysis, citations | Investigation | +| `implementation` | Code-focused, minimal prose | Executing plans | +| `review` | Critical analysis, finding issues | Code review | +| `orchestration` | Multi-task coordination | Parallel work | + +```bash +/mode brainstorm # Switch for session +/feature --mode=implementation # Override per command +``` + +## Command Flags + +All commands support combinable flags: + +```bash +# Mode and depth +/plan --mode=brainstorm --depth=5 "feature design" + +# Persona-based review +/review --persona=security --format=detailed src/auth/ + +# Token optimization +/fix --format=concise "error message" + +# Save output +/research --save=docs/research.md "auth libraries" +``` + +### Available Flags + +| Flag | Description | +|------|-------------| +| `--mode=[mode]` | Behavioral mode | +| `--depth=[1-5]` | Thoroughness (1=quick, 5=exhaustive) | +| `--format=[fmt]` | Output format (concise/detailed/json) | +| `--persona=[type]` | Expertise focus (security/performance/architecture) | +| `--save=[path]` | Save output to file | +| `--checkpoint` | Create state checkpoint | + +## Token Optimization + +Reduce costs by 30-70% with compressed output modes: + +| Level | Activation | Savings | +|-------|------------|---------| +| Concise | `--format=concise` | 30-40% | +| Ultra | `--format=ultra` | 60-70% | +| Session | `/mode token-efficient` | 30-70% | + +## MCP Integrations + +Optional MCP servers for extended capabilities: + +| Server | Purpose | +|--------|---------| +| Context7 | Up-to-date library documentation | +| Sequential | Multi-step reasoning tools | +| Puppeteer | Browser automation | +| Magic | UI component generation | + +Setup: See `.claude/mcp/README.md` ## Customization @@ -213,6 +307,18 @@ Your patterns and examples here. ``` Uses one-question-at-a-time design, 2-5 min tasks with exact code, subagent execution with code review gates. +### Parallel Research +``` +/spawn "research auth" → /spawn "analyze security" → /spawn --collect +``` +Launch multiple background tasks, then aggregate results. + +### Cost-Optimized Session +``` +/mode token-efficient → [work on tasks] → /mode default +``` +Enable compressed outputs for high-volume sessions. + ## Requirements - Claude Code 1.0+