diff --git a/.claude/commands/analyze.md b/.claude/commands/analyze.md index d4fb42c..e8984d4 100644 --- a/.claude/commands/analyze.md +++ b/.claude/commands/analyze.md @@ -1,35 +1,4 @@ -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal Legend ## Command Execution Execute: immediate. --plan→show plan first @@ -38,23 +7,7 @@ Purpose: "[Action][Subject] in $ARGUMENTS" Multi-dimensional analysis on code, arch, or problem in $ARGUMENTS. -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always Examples: - `/analyze --code --think` - Code review w/ context @@ -77,53 +30,8 @@ Analysis modes: **--interactive:** Guided exploration | Step-by-step fixes | Live improvement +@include shared/research-patterns.yml#Mandatory_Research_Flows -```yaml -Mandatory_Research_Flows: - External_Library_Research: - Step_1: "Identify library/framework mentioned" - Step_2: "Context7 lookup for official documentation" - Step_3: "Verify API patterns and examples" - Step_4: "Check version compatibility" - Step_5: "Document findings in implementation" - - Pattern_Research: - Step_1: "Search existing codebase for similar patterns" - Step_2: "Magic component search if UI-related" - Step_3: "WebSearch for official documentation" - Step_4: "Validate approach with Sequential thinking" - Step_5: "Document pattern choice rationale" - - API_Integration_Research: - Step_1: "Official documentation lookup" - Step_2: "Authentication requirements" - Step_3: "Rate limiting and error handling" - Step_4: "SDK availability and examples" - Step_5: "Integration testing approach" -``` +@include shared/docs-patterns.yml#Standard_Notifications - -```yaml -Standard_Notifications: - Operation_Start: "▶ Starting {operation}" - Operation_Complete: "✅ {operation} completed successfully" - File_Created: "📝 Created: {file_path}" - File_Updated: "✏ Updated: {file_path}" - Report_Generated: "📄 Report saved to: {path}" - Error_Occurred: "❌ {operation} failed: {reason}" - Warning_Issued: "⚠ {warning_message}" - Info_Message: "ℹ {information}" - -Output_Notifications: - Success_Format: "✅ {operation} completed in {duration}" - Error_Format: "❌ {operation} failed: {error_details}" - Warning_Format: "⚠ {warning}: {details}" - Info_Format: "ℹ {message}" - Progress_Format: "🔄 {operation}: {current}/{total} ({percentage}%)" -``` - -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +@include shared/universal-constants.yml#Standard Messages & Templates \ No newline at end of file diff --git a/.claude/commands/build.md b/.claude/commands/build.md index e5ad097..e2b3b85 100644 --- a/.claude/commands/build.md +++ b/.claude/commands/build.md @@ -1,35 +1,4 @@ -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Command Execution Execute: immediate. --plan→show plan first @@ -38,23 +7,7 @@ Purpose: "[Action][Subject] in $ARGUMENTS" Build project/feature based on req in $ARGUMENTS. -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always Examples: - `/build --react --magic` - React app w/ UI gen @@ -78,81 +31,8 @@ Templates: **--watch:** Continuous build | Real-time feedback | Incremental | Live reload **--interactive:** Step-by-step cfg | Interactive deps | Build customization +@include shared/research-patterns.yml#Mandatory_Research_Flows -```yaml -Mandatory_Research_Flows: - External_Library_Research: - Step_1: "Identify library/framework mentioned" - Step_2: "Context7 lookup for official documentation" - Step_3: "Verify API patterns and examples" - Step_4: "Check version compatibility" - Step_5: "Document findings in implementation" - - Pattern_Research: - Step_1: "Search existing codebase for similar patterns" - Step_2: "Magic component search if UI-related" - Step_3: "WebSearch for official documentation" - Step_4: "Validate approach with Sequential thinking" - Step_5: "Document pattern choice rationale" - - API_Integration_Research: - Step_1: "Official documentation lookup" - Step_2: "Authentication requirements" - Step_3: "Rate limiting and error handling" - Step_4: "SDK availability and examples" - Step_5: "Integration testing approach" -``` +@include shared/execution-patterns.yml#Git_Integration_Patterns -```yaml -Git_Workflows: - Auto_Safety_Checks: - Before_Commit: - - "git status → Verify intended files" - - "git diff --staged → Review changes" - - "Run tests if available" - - "Check for secrets/credentials" - Before_Push: - - "Verify target branch & remote" - - "Check for force push implications" - - "Ensure CI/CD readiness" - Before_Merge: - - "Test for conflicts" - - "Verify branch policies" - - "Check approval requirements" - - Commit_Standards: - Format: "{type}: {description}\n\n{body}\n\n🤖 Generated with [Claude Code]\n\nCo-Authored-By: Claude" - Types: ["feat", "fix", "docs", "style", "refactor", "test", "chore"] - Validation: - - "Type matches change nature" - - "Description < 50 chars" - - "Body explains why, not what" - - Branch_Management: - Strategy: - Feature: "feature/{description}" - Bugfix: "bugfix/{description}" - Release: "release/{version}" - Hotfix: "hotfix/{description}" - Protection: - Main: "No direct push, PR required" - Release: "Admin approval required" - Feature: "Auto-delete after merge" - - Conflict_Resolution: - Detection: "Auto-detect during pull/merge" - Strategies: - Simple: "Auto-resolve if non-overlapping" - Complex: "Interactive 3-way merge" - Binary: "Choose version explicitly" - Recovery: - Abort: "git merge --abort → restore state" - Stash: "git stash → try different approach" - Branch: "Create conflict-resolution branch" -``` - -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +@include shared/universal-constants.yml#Success_Messages \ No newline at end of file diff --git a/.claude/commands/cleanup.md b/.claude/commands/cleanup.md index de9d3fa..d70d523 100644 --- a/.claude/commands/cleanup.md +++ b/.claude/commands/cleanup.md @@ -1,60 +1,11 @@ -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Command Execution -Execute: immediate. --plan→show plan first -Legend: Generated based on symbols used in command -Purpose: "[Action][Subject] in $ARGUMENTS" +@include shared/command-structure.yml#Base_Execution Cleanup project files, dependencies & artifacts in $ARGUMENTS. -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always Clean up project artifacts, code & cfg specified in $ARGUMENTS. @@ -90,52 +41,11 @@ Clean up project artifacts, code & cfg specified in $ARGUMENTS. ## Integration & Best Practices +@include shared/research-patterns.yml#Mandatory_Research_Flows -```yaml -Mandatory_Research_Flows: - External_Library_Research: - Step_1: "Identify library/framework mentioned" - Step_2: "Context7 lookup for official documentation" - Step_3: "Verify API patterns and examples" - Step_4: "Check version compatibility" - Step_5: "Document findings in implementation" - - Pattern_Research: - Step_1: "Search existing codebase for similar patterns" - Step_2: "Magic component search if UI-related" - Step_3: "WebSearch for official documentation" - Step_4: "Validate approach with Sequential thinking" - Step_5: "Document pattern choice rationale" - - API_Integration_Research: - Step_1: "Official documentation lookup" - Step_2: "Authentication requirements" - Step_3: "Rate limiting and error handling" - Step_4: "SDK availability and examples" - Step_5: "Integration testing approach" -``` - - -```yaml -Standard_Notifications: - Operation_Start: "▶ Starting {operation}" - Operation_Complete: "✅ {operation} completed successfully" - File_Created: "📝 Created: {file_path}" - File_Updated: "✏ Updated: {file_path}" - Report_Generated: "📄 Report saved to: {path}" - Error_Occurred: "❌ {operation} failed: {reason}" - Warning_Issued: "⚠ {warning_message}" - Info_Message: "ℹ {information}" - -Output_Notifications: - Success_Format: "✅ {operation} completed in {duration}" - Error_Format: "❌ {operation} failed: {error_details}" - Warning_Format: "⚠ {warning}: {details}" - Info_Format: "ℹ {message}" - Progress_Format: "🔄 {operation}: {current}/{total} ({percentage}%)" -``` +@include shared/user-experience.yml#Standard_Notifications - Space savings: `.claudedocs/metrics/cleanup-savings-.md` - Ensure dirs: `mkdir -p .claudedocs/reports/ .claudedocs/metrics/` - Include location: "📄 Cleanup report saved to: [path]" -Deliverables: Cleanup report w/ space saved, perf improvements, maintenance recommendations, safety analysis & cleanup strategy docs. +Deliverables: Cleanup report w/ space saved, perf improvements, maintenance recommendations, safety analysis & cleanup strategy docs. \ No newline at end of file diff --git a/.claude/commands/deploy.md b/.claude/commands/deploy.md index 1d4cd34..9ce4d2e 100644 --- a/.claude/commands/deploy.md +++ b/.claude/commands/deploy.md @@ -1,58 +1,9 @@ -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Command Execution -Execute: immediate. --plan→show plan first -Legend: Generated based on symbols used in command -Purpose: "[Action][Subject] in $ARGUMENTS" +@include shared/command-structure.yml#Base_Execution -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always Deploy application to env specified in $ARGUMENTS. @@ -100,53 +51,9 @@ Safety: - Always have rollback plan | Backups before deployment - Monitor key metrics during deployment | Gradual rollout→major changes +@include shared/research-patterns.yml#Mandatory_Research_Flows -```yaml -Mandatory_Research_Flows: - External_Library_Research: - Step_1: "Identify library/framework mentioned" - Step_2: "Context7 lookup for official documentation" - Step_3: "Verify API patterns and examples" - Step_4: "Check version compatibility" - Step_5: "Document findings in implementation" - - Pattern_Research: - Step_1: "Search existing codebase for similar patterns" - Step_2: "Magic component search if UI-related" - Step_3: "WebSearch for official documentation" - Step_4: "Validate approach with Sequential thinking" - Step_5: "Document pattern choice rationale" - - API_Integration_Research: - Step_1: "Official documentation lookup" - Step_2: "Authentication requirements" - Step_3: "Rate limiting and error handling" - Step_4: "SDK availability and examples" - Step_5: "Integration testing approach" -``` - - -```yaml -Standard_Notifications: - Operation_Start: "▶ Starting {operation}" - Operation_Complete: "✅ {operation} completed successfully" - File_Created: "📝 Created: {file_path}" - File_Updated: "✏ Updated: {file_path}" - Report_Generated: "📄 Report saved to: {path}" - Error_Occurred: "❌ {operation} failed: {reason}" - Warning_Issued: "⚠ {warning_message}" - Info_Message: "ℹ {information}" - -Output_Notifications: - Success_Format: "✅ {operation} completed in {duration}" - Error_Format: "❌ {operation} failed: {error_details}" - Warning_Format: "⚠ {warning}: {details}" - Info_Format: "ℹ {message}" - Progress_Format: "🔄 {operation}: {current}/{total} ({percentage}%)" -``` +@include shared/user-experience.yml#Standard_Notifications ## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +@include shared/user-experience.yml#Success_Notifications \ No newline at end of file diff --git a/.claude/commands/design.md b/.claude/commands/design.md index ca3a325..fb5f360 100644 --- a/.claude/commands/design.md +++ b/.claude/commands/design.md @@ -1,60 +1,11 @@ -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Command Execution -Execute: immediate. --plan→show plan first -Legend: Generated based on symbols used in command -Purpose: "[Action][Subject] in $ARGUMENTS" +@include shared/command-structure.yml#Base_Execution Design system architecture & APIs for $ARGUMENTS. -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always Design & architect software solutions based on requirements in $ARGUMENTS. @@ -142,4 +93,4 @@ Research requirements: Deliverables: - API: Complete spec, impl guide, docs | DDD: Domain model, bounded contexts, architecture diagrams, code structure -- PRD: Requirements doc, user stories, success metrics, timeline +- PRD: Requirements doc, user stories, success metrics, timeline \ No newline at end of file diff --git a/.claude/commands/dev-setup.md b/.claude/commands/dev-setup.md index 2eb07e5..a7e05b2 100644 --- a/.claude/commands/dev-setup.md +++ b/.claude/commands/dev-setup.md @@ -1,37 +1,6 @@ # /dev-setup - Configure development environment and CI/CD -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose Configure comprehensive development environments and CI/CD pipelines based on project requirements in $ARGUMENTS. @@ -39,213 +8,102 @@ Configure comprehensive development environments and CI/CD pipelines based on pr ## Syntax `/dev-setup [flags] [target]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always -## Command-Specific Flags +Thinking flags (optional): +- --think→environment configuration & dependency analysis +- --think-hard→complex CI/CD pipelines & multi-stage builds +- --ultrathink→complete development ecosystem design -**Setup Types:** -- `--install`: Install and configure development tools (Node.js, Git, Docker, databases) -- `--ci`: Configure CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins) -- `--monitor`: Setup observability tools (logging, monitoring, error tracking) -- `--docker`: Configure Docker development environment -- `--env`: Setup environment configuration and secrets management +## Core Flags -**Development Tools:** -- `--ide`: Configure IDE settings and extensions -- `--git`: Setup Git workflows, hooks, and repository configuration -- `--deps`: Configure dependency management and security scanning -- `--testing`: Setup testing frameworks and coverage tools -- `--linting`: Configure code quality tools (ESLint, Prettier, etc.) +--type flag: +- node: Node.js/TypeScript project setup +- python: Python virtual environment & tooling +- react: React + Vite/Next.js configuration +- fullstack: Complete full-stack environment +- monorepo: Multi-package monorepo setup -**Infrastructure:** -- `--local`: Local development environment setup -- `--cloud`: Cloud development environment configuration -- `--database`: Database setup and migration tools -- `--security`: Security tools and vulnerability scanning +--ci flag: +- github: GitHub Actions workflows +- gitlab: GitLab CI/CD pipelines +- jenkins: Jenkins pipeline configuration +- circleci: CircleCI configuration +- custom: Custom CI/CD solution + +--tools flag: +- Include dev tools: linters, formatters, pre-commit hooks +- Configure VS Code settings & extensions +- Setup debugging configurations +- Install recommended tooling + +## Setup Components + +Environment Configuration: +- Package manager setup (npm/yarn/pnpm) +- Version management (.nvmrc, .python-version) +- Environment variables & .env structure +- Docker configuration if needed + +Code Quality: +- ESLint/Prettier configuration +- Pre-commit hooks (husky, lint-staged) +- Test framework setup (Jest, Pytest, etc) +- Code coverage configuration + +CI/CD Pipeline: +- Build & test workflows +- Deployment configurations +- Security scanning (SAST/DAST) +- Dependency vulnerability checks +- Release automation + +Development Tools: +- VS Code workspace settings +- Debug configurations +- Task runners & scripts +- Documentation generation + +## Best Practices + +Security: +- Never commit secrets or credentials +- Use environment variables for sensitive data +- Configure security scanning in CI +- Implement dependency vulnerability checks + +Performance: +- Cache dependencies in CI +- Parallelize test execution +- Optimize build processes +- Use appropriate resource limits + +Maintainability: +- Consistent tooling across team +- Clear documentation +- Automated quality checks +- Reproducible environments ## Examples -- `/dev-setup --install --docker --think` → Docker dev environment with analysis -- `/dev-setup --ci --security --think-hard` → Secure CI/CD pipeline design -- `/dev-setup --monitor --cloud --ultrathink` → Enterprise observability infrastructure -- `/dev-setup --git --testing --linting` → Complete development workflow -- `/dev-setup --env --database --local` → Local development with database -## Installation Setup (--install) +```bash +# Node.js project with GitHub Actions +/dev-setup --type node --ci github --tools -**Core Development Tools:** -- Node.js with version management (nvm/fnm) -- Git with global configuration -- Docker and Docker Compose -- Database tools (PostgreSQL, Redis) -- Package managers (npm, yarn, pnpm) +# Python project with comprehensive tooling +/dev-setup --type python --tools --think -**IDE Configuration:** -- VS Code settings and extensions -- Consistent formatting and linting -- Debugging configurations -- Integrated terminal setup +# Full-stack monorepo with GitLab CI +/dev-setup --type monorepo --ci gitlab --think-hard -**Development Scripts:** -- npm/yarn scripts for common tasks -- Pre-commit hooks for code quality -- Git hooks for automated checks -- Build and deployment scripts - -## CI/CD Setup (--ci) - -**Pipeline Stages:** -- **Build**: Compile, bundle, and optimize code -- **Test**: Unit, integration, and E2E testing -- **Security**: Vulnerability scanning and code analysis -- **Deploy**: Automated deployment to environments -- **Monitor**: Post-deployment verification - -**Platform Configurations:** -- GitHub Actions workflows -- GitLab CI/CD pipelines -- Jenkins pipeline scripts -- Azure DevOps pipelines - -**Environment Management:** -- Development, staging, production environments -- Secret management and environment variables -- Infrastructure as Code (Terraform, CloudFormation) -- Container orchestration (Kubernetes, Docker Swarm) - -## Monitoring Setup (--monitor) - -**Observability Stack:** -- Application performance monitoring (APM) -- Centralized logging (ELK stack, Splunk) -- Metrics collection (Prometheus, Grafana) -- Distributed tracing (Jaeger, Zipkin) -- Error tracking (Sentry, Rollbar) - -**Alerting & Notifications:** -- Critical issue alerts -- Performance threshold monitoring -- Service health checks -- Deployment notifications +# React project with all quality tools +/dev-setup --type react --tools --ci github +``` ## Deliverables -- **Configuration Files**: Complete development and CI/CD configurations -- **Documentation**: Setup guides, workflows, and best practices -- **Scripts**: Automation scripts for environment setup -- **Templates**: Reusable configurations for new projects -- **Security Policies**: Development security guidelines and tools - -```yaml -Mandatory_Research_Flows: - External_Library_Research: - Step_1: "Identify library/framework mentioned" - Step_2: "Context7 lookup for official documentation" - Step_3: "Verify API patterns and examples" - Step_4: "Check version compatibility" - Step_5: "Document findings in implementation" - - Pattern_Research: - Step_1: "Search existing codebase for similar patterns" - Step_2: "Magic component search if UI-related" - Step_3: "WebSearch for official documentation" - Step_4: "Validate approach with Sequential thinking" - Step_5: "Document pattern choice rationale" - - API_Integration_Research: - Step_1: "Official documentation lookup" - Step_2: "Authentication requirements" - Step_3: "Rate limiting and error handling" - Step_4: "SDK availability and examples" - Step_5: "Integration testing approach" -``` - - -```yaml -Standard_Notifications: - Operation_Start: "▶ Starting {operation}" - Operation_Complete: "✅ {operation} completed successfully" - File_Created: "📝 Created: {file_path}" - File_Updated: "✏ Updated: {file_path}" - Report_Generated: "📄 Report saved to: {path}" - Error_Occurred: "❌ {operation} failed: {reason}" - Warning_Issued: "⚠ {warning_message}" - Info_Message: "ℹ {information}" - -Output_Notifications: - Success_Format: "✅ {operation} completed in {duration}" - Error_Format: "❌ {operation} failed: {error_details}" - Warning_Format: "⚠ {warning}: {details}" - Info_Format: "ℹ {message}" - Progress_Format: "🔄 {operation}: {current}/{total} ({percentage}%)" -``` - -## Best Practices & Security - -**Security First:** -- Secure secret management (never commit secrets) -- Vulnerability scanning in CI/CD -- Code analysis and security linting -- Environment isolation and access controls -- Regular security updates and patches - -**Development Standards:** -- Consistent code formatting and linting -- Automated testing at all levels -- Git workflow with protected branches -- Code review requirements -- Documentation standards - -**Performance & Reliability:** -- Fast feedback loops in CI/CD -- Efficient caching strategies -- Parallel execution where possible -- Robust error handling and recovery -- Monitoring and observability from day one - -## Environment-Specific Configurations - -**Local Development:** -- Hot reload and fast refresh -- Local database and service mocking -- Debug-friendly configurations -- Offline-first development tools - -**CI/CD Environments:** -- Optimized build times -- Comprehensive testing suites -- Security scanning integration -- Automated deployment gates - -**Production Monitoring:** -- Real-time performance metrics -- Error tracking and alerting -- Log aggregation and analysis -- User experience monitoring - -## Troubleshooting -- **Installation Issues**: Check system requirements and permissions -- **CI/CD Failures**: Review pipeline logs and dependency conflicts -- **Environment Conflicts**: Use containerization for consistency -- **Complex Setups**: Use `--think-hard` for architectural planning - -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +- Complete environment configuration files +- CI/CD pipeline definitions +- Development tool configurations +- Setup documentation & README updates +- Scripts for common development tasks \ No newline at end of file diff --git a/.claude/commands/document.md b/.claude/commands/document.md index 4787a77..af6bea4 100644 --- a/.claude/commands/document.md +++ b/.claude/commands/document.md @@ -1,38 +1,7 @@ # /document - Generate comprehensive documentation ## Legend -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose Generate comprehensive documentation for code, APIs, or systems specified in $ARGUMENTS with various output formats and styles. @@ -40,187 +9,99 @@ Generate comprehensive documentation for code, APIs, or systems specified in $AR ## Syntax `/document [flags] [target]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always -## Command-Specific Flags +## Core Flags -**Documentation Types:** -- `--api`: Generate API documentation with endpoints, schemas, examples -- `--user`: Create user-friendly guides with tutorials and walkthroughs -- `--architecture`: System design documentation with diagrams -- `--developer`: Developer guides with setup and implementation details -- `--readme`: Project README with overview and quick start +--type flag: +- api: API documentation (OpenAPI/Swagger) +- code: Code documentation (JSDoc/docstrings) +- readme: Project README files +- architecture: System architecture docs +- user: End-user documentation +- dev: Developer guides -**Output Format:** -- `--visual`: Include diagrams, flowcharts, and visual aids -- `--examples`: Generate practical code examples and snippets -- `--interactive`: Create interactive documentation with live examples +--format flag: +- markdown: Markdown format (default) +- html: HTML documentation +- pdf: PDF output +- docusaurus: Docusaurus compatible +- mkdocs: MkDocs compatible -**Content Depth:** -- `--depth`: Explanation depth (basic|intermediate|advanced|expert) -- `--complete`: Comprehensive documentation covering all aspects -- `--quick`: Essential documentation for rapid reference +--style flag: +- concise: Brief, essential information only +- detailed: Comprehensive with examples +- tutorial: Step-by-step guide format +- reference: API reference style ## Documentation Types -**README Documentation:** -- Project overview and purpose -- Installation instructions and requirements -- Quick start guide with examples -- Configuration options and environment setup -- Basic usage examples -- Contributing guidelines and standards +API Documentation: +- OpenAPI 3.0 specification +- Request/response examples +- Authentication details +- Error codes & handling +- Rate limiting information -**API Documentation:** -- Complete endpoint descriptions -- HTTP methods and status codes -- Request/response schemas with validation -- Authentication and authorization methods -- Rate limiting and quota information -- Code examples in multiple languages -- Error handling and troubleshooting +Code Documentation: +- Function/method descriptions +- Parameter & return types +- Usage examples +- Edge cases & limitations +- Related functions -**Architecture Documentation:** -- System design overview and principles -- Component relationships and dependencies -- Data flow diagrams and sequence charts -- Technology choices and rationale -- Scalability considerations and patterns -- Security architecture and threat model +Architecture Documentation: +- System overview diagrams +- Component interactions +- Data flow documentation +- Technology decisions +- Scalability considerations -**User Guides:** -- Getting started tutorials -- Feature walkthroughs with screenshots -- Best practices and common patterns -- Integration guides and examples -- Migration guides and upgrade paths -- FAQ and troubleshooting sections +User Documentation: +- Getting started guides +- Feature explanations +- Common use cases +- Troubleshooting guides +- FAQ sections -**Developer Documentation:** -- Codebase structure and organization -- Development environment setup -- Testing guidelines and frameworks -- Deployment processes and CI/CD -- Debugging tips and tools -- Performance optimization techniques +## Best Practices + +Structure: +- Clear hierarchy & navigation +- Consistent formatting +- Search-friendly content +- Version-specific docs +- Cross-references + +Content: +- Examples for everything +- Progressive disclosure +- Visual aids when helpful +- Keep updated with code +- Test documentation + +@include shared/docs-patterns.yml#Documentation_Standards ## Examples -- `/document --api --examples --c7` → API docs with framework examples -- `/document --user --visual --interactive` → Interactive user guides -- `/document --architecture --complete --seq` → Comprehensive system docs -- `/document --developer --depth advanced` → Advanced developer guides -- `/document --readme --quick --uc` → Concise project README -## Documentation Standards +```bash +# Generate API documentation +/document --type api --format openapi -**Content Quality:** -- Use clear, concise language appropriate for audience -- Include practical, tested examples -- Add visual aids where helpful -- Keep information current and accurate -- Make content searchable and navigable -- Version documentation with code changes +# Create comprehensive README +/document --type readme --style detailed -**Structure Guidelines:** -- Logical organization with clear hierarchy -- Progressive disclosure of complexity -- Cross-references between related topics -- Glossary for technical terms -- Index for quick reference -- Changelog maintenance +# Architecture documentation with diagrams +/document --type architecture --think -**UltraCompressed Mode (--uc):** -- Apply token reduction rules (~70% savings) -- Generate symbol/abbreviation legend -- Use telegram-style formatting -- Structure: YAML > tables > lists > prose -- Compress headers and sentences -- Focus on essential information only +# User guide with tutorials +/document --type user --style tutorial +``` ## Deliverables -- **Documentation Files**: Complete docs in specified format -- **Code Examples**: Working, tested code snippets -- **Visual Aids**: Diagrams, charts, and illustrations -- **Index Files**: Navigation and cross-reference guides -- **Templates**: Reusable documentation templates -## Output Locations -- **API Documentation**: `docs/api/` -- **User Guides**: `docs/guides/` -- **Architecture Docs**: `docs/architecture/` -- **Developer Docs**: `docs/development/` -- **README Files**: Project root and subdirectories -- **Index**: `docs/index.md` with navigation links - -## Research Requirements -External_Library_Research: - - Identify library/framework mentioned - - Context7 lookup for official documentation - - Verify API patterns and examples - - Check version compatibility - - Document findings in implementation -Pattern_Research: - - Search existing codebase for similar patterns - - Magic component search if UI-related - - WebSearch for official documentation - - Validate approach with Sequential thinking - - Document pattern choice rationale -API_Integration_Research: - - Official documentation lookup - - Authentication requirements - - Rate limiting and error handling - - SDK availability and examples - - Integration testing approach - -## Report Notifications -📄 Analysis report saved to: {path} -📊 Metrics updated: {path} -📋 Summary saved to: {path} -💾 Checkpoint created: {path} -📚 Documentation created: {path} -📁 Created directory: {path} -✅ {operation} completed successfully -❌ {operation} failed: {reason} -⚠ {operation} completed w/ warnings - -## Integration & Best Practices - -**Quality Assurance:** -- Test all code examples -- Verify links and references -- Review for clarity and accuracy -- Validate against actual implementation - -**Maintenance Strategy:** -- Update with code changes -- Regular review and refresh -- User feedback integration -- Version control alignment - -## Troubleshooting -- **Large Codebases**: Use `--depth` to control scope -- **Complex APIs**: Combine `--api --examples --c7` for comprehensive docs -- **Technical Concepts**: Use `--visual --examples` for clarity -- **Token Limits**: Apply `--uc` for compressed documentation - -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +- Documentation files in specified format +- Table of contents & navigation +- Code examples & snippets +- Diagrams & visual aids +- Search index if applicable \ No newline at end of file diff --git a/.claude/commands/estimate.md b/.claude/commands/estimate.md index 2b370ec..08c32e8 100644 --- a/.claude/commands/estimate.md +++ b/.claude/commands/estimate.md @@ -1,38 +1,7 @@ # /estimate - Estimate time, complexity and resources ## Legend -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose Provide comprehensive time, complexity, and resource estimates for tasks specified in $ARGUMENTS using data-driven analysis. @@ -40,199 +9,126 @@ Provide comprehensive time, complexity, and resource estimates for tasks specifi ## Syntax `/estimate [flags] [task]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always -## Command-Specific Flags +## Core Flags -**Estimation Types:** -- `--detailed`: Comprehensive breakdown with subtask analysis -- `--quick`: High-level estimate for rapid planning -- `--worst-case`: Risk-based estimation with comprehensive scenarios -- `--comparative`: Compare multiple approaches or solutions +--scope flag: +- feature: Single feature estimation +- epic: Multi-feature epic +- project: Full project scope +- refactor: Code refactoring effort +- migration: Data/system migration -**Analysis Depth:** -- `--dependencies`: Include cross-team and technical dependencies -- `--risks`: Detailed risk analysis with mitigation strategies -- `--resources`: Team composition and skill requirements -- `--timeline`: Milestone-based project timeline +--team flag: +- solo: Single developer +- small: 2-3 developers +- medium: 4-8 developers +- large: 9+ developers -**Research Integration:** -- `--c7`: Research similar projects and patterns -- `--seq`: Complex estimation with uncertainty modeling -- `--benchmarks`: Industry benchmark comparison +--detail flag: +- high: Detailed breakdown +- medium: Standard estimates +- low: Quick rough estimates -## Examples -- `/estimate --detailed --dependencies --think` → Detailed breakdown with dependency analysis -- `/estimate --worst-case --risks --think-hard` → Risk-based estimation with scenarios -- `/estimate "migrate to microservices" --comparative --ultrathink` → Complex architectural estimation -- `/estimate --quick --benchmarks --c7` → Rapid estimate with industry data -- `/estimate --timeline --resources --seq` → Resource planning with timeline +## Estimation Components -## Estimation Framework +Time Estimates: +- Development hours/days +- Testing & QA time +- Code review cycles +- Integration effort +- Buffer for unknowns -**Time Components:** -- **Development**: Implementation, code review, feedback cycles -- **Testing**: Unit, integration, end-to-end testing -- **Documentation**: Technical docs, user guides, API documentation -- **Deployment**: Release preparation, deployment, verification -- **Buffer**: Uncertainty, learning, unexpected issues +Complexity Analysis: +- Technical complexity score +- Integration points +- Dependencies & blockers +- Risk factors +- Learning curve -**Complexity Multipliers:** -- **New Feature**: 1.0x baseline (green field development) -- **Refactoring**: 1.5x (understanding existing + changes) -- **Legacy Integration**: 2.0x (constraints + unknowns) -- **Cross-Team Dependencies**: 1.5x (coordination overhead) -- **New Technology**: 1.8x (learning curve + risk) +Resource Requirements: +- Developer skill levels +- Infrastructure needs +- Third-party services +- Testing resources +- Documentation effort -**Uncertainty Factors:** -- **Clear Requirements + Known Tech**: ±10% variance -- **Some Unknowns + New Patterns**: ±25% variance -- **Significant Research Required**: ±50% variance -- **Completely New Territory**: ±100% variance +## Methodology -## Estimation Process +Estimation Factors: +- Historical data from similar tasks +- Code complexity metrics +- Team velocity & capacity +- Technical debt impact +- External dependencies -**1. Task Decomposition:** -- Break down into measurable subtasks -- Identify dependencies and prerequisites -- Map required skills and expertise -- Determine critical path items +Risk Assessment: +- Technical risks +- Resource availability +- Timeline constraints +- Scope creep potential +- Integration challenges -**2. Base Estimation:** -- Estimate each subtask individually -- Use historical data where available -- Apply complexity multipliers -- Add uncertainty buffers +## Output Format -**3. Scenario Planning:** -- **Best Case**: Everything goes smoothly (20% probability) -- **Most Likely**: Normal friction and discoveries (60% probability) -- **Worst Case**: Significant obstacles encountered (20% probability) - -**4. Validation:** -- Compare with similar projects -- Review with team members -- Validate assumptions -- Document reasoning - -## Context Factors - -**Team Factors:** -- Developer experience with codebase -- Team familiarity with technology stack -- Available mentorship and support -- Team size and composition - -**Project Factors:** -- Quality of existing documentation -- Codebase complexity and technical debt -- Testing and CI/CD maturity -- Deployment and infrastructure complexity - -**External Factors:** -- Stakeholder availability for feedback -- Third-party service dependencies -- Regulatory or compliance requirements -- Market or business constraints - -## Research Requirements - -**Data Sources:** -- Technology patterns → Research via `--c7` and official documentation -- Architecture patterns → Industry case studies and benchmarks -- Team velocity → Historical data and productivity metrics -- Risk assessment → Common pitfalls and mitigation strategies - -**Evidence-Based Estimation:** -- Never estimate based on intuition alone -- Always research comparable scenarios -- Cite sources for all estimates -- Validate assumptions with data - -## Deliverables -- **Estimate Summary**: Time ranges (min-max) with confidence levels -- **Complexity Assessment**: Technical difficulty and risk factors -- **Resource Requirements**: Team composition and skill needs -- **Risk Analysis**: Potential blockers and mitigation strategies -- **Timeline**: Milestone-based project schedule -- **Assumptions**: Key assumptions and dependencies - -## Output Locations -- **Estimates**: `.claudedocs/summaries/estimate-{timestamp}.md` -- **Risk Analysis**: `.claudedocs/reports/risk-analysis-{timestamp}.md` -- **Timelines**: `.claudedocs/summaries/timeline-{timestamp}.md` - -## Research Requirements -External_Library_Research: - - Identify library/framework mentioned - - Context7 lookup for official documentation - - Verify API patterns and examples - - Check version compatibility - - Document findings in implementation -Pattern_Research: - - Search existing codebase for similar patterns - - Magic component search if UI-related - - WebSearch for official documentation - - Validate approach with Sequential thinking - - Document pattern choice rationale -API_Integration_Research: - - Official documentation lookup - - Authentication requirements - - Rate limiting and error handling - - SDK availability and examples - - Integration testing approach - -## Report Notifications -📄 Analysis report saved to: {path} -📊 Metrics updated: {path} -📋 Summary saved to: {path} -💾 Checkpoint created: {path} -📚 Documentation created: {path} -📁 Created directory: {path} -✅ {operation} completed successfully -❌ {operation} failed: {reason} -⚠ {operation} completed w/ warnings +Standard Estimate: +```yaml +Task: [Description] +Complexity: [Low/Medium/High] +Time_Estimate: + Optimistic: X days + Realistic: Y days + Pessimistic: Z days +Resources: + Developers: N + QA: M hours + Infrastructure: [Details] +Risks: + - [Risk 1]: [Mitigation] + - [Risk 2]: [Mitigation] +Assumptions: + - [Assumption 1] + - [Assumption 2] +``` ## Best Practices -**Estimation Guidelines:** -- Provide ranges, not single numbers -- Include confidence levels -- Document all assumptions -- Plan for the unexpected -- Review and refine estimates regularly +Accuracy: +- Break down into smaller tasks +- Consider all phases (dev, test, deploy) +- Include communication overhead +- Account for code reviews +- Add appropriate buffers -**Common Pitfalls to Avoid:** -- Over-optimistic assumptions -- Ignoring integration complexity -- Underestimating testing time -- Forgetting documentation effort -- Missing deployment complexity +Communication: +- Provide ranges, not fixed numbers +- Document assumptions clearly +- Highlight major risks +- Update estimates as work progresses +- Track actual vs estimated -## Troubleshooting -- **Complex Projects**: Use `--ultrathink` for comprehensive analysis -- **Unknown Technologies**: Combine `--c7 --seq` for research-based estimates -- **High Uncertainty**: Use `--worst-case --risks` for scenario planning -- **Team Planning**: Include `--resources --timeline` for capacity planning +## Examples -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +```bash +# Quick feature estimate +/estimate "Add user authentication" + +# Detailed project estimation +/estimate --scope project --detail high --team medium + +# Refactoring estimate with risks +/estimate --scope refactor --think "Modernize legacy API" + +# Migration project estimation +/estimate --scope migration --team large --ultrathink +``` + +## Deliverables + +- Detailed time estimates with ranges +- Complexity analysis & metrics +- Resource allocation plan +- Risk assessment & mitigation +- Assumptions & dependencies +- Confidence levels \ No newline at end of file diff --git a/.claude/commands/explain.md b/.claude/commands/explain.md index 386b53b..7a7acd4 100644 --- a/.claude/commands/explain.md +++ b/.claude/commands/explain.md @@ -1,38 +1,7 @@ # /explain - Provide detailed technical explanations ## Legend -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose Provide comprehensive explanations of concepts, code, or systems specified in $ARGUMENTS with appropriate depth and visual aids. @@ -40,222 +9,105 @@ Provide comprehensive explanations of concepts, code, or systems specified in $A ## Syntax `/explain [flags] [concept/topic]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always -## Command-Specific Flags +## Core Flags -**Explanation Depth:** -- `--depth eli5`: Simple analogies, avoid jargon, focus on core concepts -- `--depth beginner`: Cover basics with step-by-step guidance and simple examples -- `--depth intermediate`: Technical details, best practices, common patterns -- `--depth expert`: Deep implementation details, edge cases, performance considerations +--depth flag: +- beginner: Basic concepts, simple language +- intermediate: Standard technical depth +- advanced: Deep technical details +- expert: Cutting-edge & internals -**Content Enhancement:** -- `--visual`: Create diagrams using Mermaid syntax, ASCII art, flowcharts -- `--examples`: Include practical, runnable code examples -- `--comparisons`: Add comparison tables and pros/cons analysis -- `--interactive`: Create interactive explanations with guided discovery +--style flag: +- tutorial: Step-by-step learning +- reference: Quick lookup format +- conversational: Natural dialogue +- academic: Formal & thorough -**Research Integration:** -- `--c7`: Fetch official library/framework documentation -- `--seq`: Step-by-step concept breakdown with complex analysis -- `--no-mcp`: Explain using only codebase context +--visual flag: +- Include diagrams & flowcharts +- Code examples with annotations +- Architecture visualizations +- Sequence diagrams for flows -**Output Format:** -- `--structured`: Organize explanation with clear sections and hierarchy -- `--quick`: Concise explanation focusing on key points -- `--comprehensive`: Complete explanation covering all aspects +## Explanation Types -## Examples -- `/explain --c7 "React hooks" --visual --think` → React hooks with diagrams and connections -- `/explain --seq "OAuth flow" --depth expert --think-hard` → Deep OAuth analysis with security implications -- `/explain --depth eli5 "async/await" --examples` → Simple async explanation with examples -- `/explain --visual --comparisons "REST vs GraphQL"` → API comparison with diagrams -- `/explain --comprehensive --c7 "Docker containers"` → Complete Docker explanation with docs +Code Explanation: +- Line-by-line breakdown +- Algorithm walkthrough +- Design pattern usage +- Performance implications +- Edge cases & limitations -## Explanation Structure +Concept Explanation: +- Core principles +- Real-world applications +- Common misconceptions +- Related concepts +- Best practices -**1. High-Level Overview:** -- Start with the big picture -- Define the problem or concept -- Explain why it matters -- Set context and scope +System Explanation: +- Architecture overview +- Component interactions +- Data flow analysis +- Scalability factors +- Security considerations -**2. Core Components:** -- Break down into logical parts -- Explain each component clearly -- Show relationships and dependencies -- Use appropriate technical depth +## Methodology -**3. Practical Application:** -- Provide concrete examples -- Show real-world usage -- Include code snippets -- Demonstrate best practices +Structure: +1. Overview - What & why +2. Core concepts - Building blocks +3. Deep dive - How it works +4. Examples - Practical usage +5. Gotchas - Common pitfalls +6. Resources - Further learning -**4. Advanced Concepts:** -- Cover edge cases and gotchas -- Explain performance implications -- Discuss alternatives and trade-offs -- Address common misconceptions - -## Content Types - -**Technical Concepts:** -- Explain "what" before "how" -- Connect to familiar concepts -- Build understanding incrementally -- Use analogies and metaphors -- Address common misconceptions - -**Code Explanations:** -- Walk through logic step by step -- Explain design decisions and rationale -- Highlight important patterns -- Point out potential pitfalls -- Show alternative approaches - -**System Architecture:** -- Start with overall design -- Explain component interactions -- Show data flow and processes -- Discuss scalability and performance -- Cover security considerations - -**Framework/Library Usage:** -- Explain core concepts first -- Show common usage patterns -- Provide working examples -- Explain configuration options -- Cover troubleshooting tips - -## Visual Aids (--visual) - -**Diagram Types:** -- **Mermaid Diagrams**: Flowcharts, sequence diagrams, class diagrams -- **ASCII Art**: Simple visualizations and layouts -- **Process Flows**: Step-by-step workflow diagrams -- **Architecture Diagrams**: System component relationships - -**When to Use Visuals:** -- Complex processes or workflows -- System architecture explanations -- Data flow and transformations -- Relationship mapping -- Timeline or sequence explanations - -## Research Requirements - -**Authoritative Sources:** -- Official documentation via `--c7` -- Framework guides and best practices -- Industry standards and specifications -- Expert opinions and case studies - -**Verification Standards:** -- Never explain without verification -- Always cite authoritative sources -- Test code examples before including -- Validate against current versions -- Include source references in explanations - -## UltraCompressed Mode (--uc) - -**Compression Rules:** -- ~70% token reduction from standard explanations -- Generate legend for symbols/abbreviations -- Use telegram-style formatting -- Structure: lists > paragraphs, tables > prose -- Remove articles, conjunctions, fillers -- Focus on essential information only - -**Example Transformation:** -- Standard: "The function takes three parameters and returns a boolean value" -- Compressed: "fn takes 3 params→bool" - -## Deliverables -- **Clear Explanations**: Appropriate depth level with structured content -- **Working Examples**: Tested, runnable code snippets -- **Visual Aids**: Diagrams, charts, and illustrations (if requested) -- **Learning Resources**: Curated resources for further study -- **Source References**: Comprehensive citations and links - -## Output Locations -- **Explanations**: `.claudedocs/summaries/explanation-{topic}-{timestamp}.md` -- **Learning Resources**: `.claudedocs/reports/learning-resources-{timestamp}.md` -- **Code Examples**: Embedded in explanation files - -## Research Requirements -External_Library_Research: - - Identify library/framework mentioned - - Context7 lookup for official documentation - - Verify API patterns and examples - - Check version compatibility - - Document findings in implementation -Pattern_Research: - - Search existing codebase for similar patterns - - Magic component search if UI-related - - WebSearch for official documentation - - Validate approach with Sequential thinking - - Document pattern choice rationale -API_Integration_Research: - - Official documentation lookup - - Authentication requirements - - Rate limiting and error handling - - SDK availability and examples - - Integration testing approach - -## Report Notifications -📄 Analysis report saved to: {path} -📊 Metrics updated: {path} -📋 Summary saved to: {path} -💾 Checkpoint created: {path} -📚 Documentation created: {path} -📁 Created directory: {path} -✅ {operation} completed successfully -❌ {operation} failed: {reason} -⚠ {operation} completed w/ warnings +Techniques: +- Analogies for complex concepts +- Progressive complexity +- Interactive examples +- Visual representations +- Real-world scenarios ## Best Practices -**Effective Explanations:** -- Start simple, build complexity gradually -- Use concrete examples and analogies -- Address the audience's experience level -- Anticipate and answer common questions -- Provide multiple perspectives when helpful +Clarity: +- Define terms before use +- Build on prior knowledge +- Use consistent terminology +- Provide context +- Summarize key points -**Quality Standards:** -- Verify all technical information -- Test all code examples -- Keep explanations current and accurate -- Use clear, precise language -- Structure content logically +Engagement: +- Start with "why it matters" +- Use relatable examples +- Address common questions +- Provide hands-on exercises +- Link to resources -## Troubleshooting -- **Complex Topics**: Use `--seq --think-hard` for step-by-step breakdown -- **Framework Questions**: Combine `--c7 --examples` for comprehensive coverage -- **Beginner Audiences**: Use `--depth eli5 --visual --examples` -- **Expert Deep Dives**: Apply `--depth expert --comprehensive --ultrathink` +## Examples -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +```bash +# Explain React hooks for beginners +/explain --depth beginner --style tutorial "React hooks" + +# Deep dive into database indexing +/explain --depth advanced --visual "B-tree indexes" + +# System architecture explanation +/explain --style reference --visual "microservices communication" + +# Algorithm explanation with complexity +/explain --depth expert --think "quicksort optimization" +``` + +## Deliverables + +- Comprehensive explanation document +- Code examples & snippets +- Visual diagrams if requested +- Practice exercises +- Resource links & references +- Summary & key takeaways \ No newline at end of file diff --git a/.claude/commands/git.md b/.claude/commands/git.md index 3d72035..f38aeec 100644 --- a/.claude/commands/git.md +++ b/.claude/commands/git.md @@ -1,38 +1,7 @@ # /git - Manage git workflows and repository operations ## Legend -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose Manage comprehensive git workflows for repositories specified in $ARGUMENTS with safety checks and automation. @@ -40,221 +9,132 @@ Manage comprehensive git workflows for repositories specified in $ARGUMENTS with ## Syntax `/git [flags] [operation/message]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" -## Execution Control ---watch: "Continuous monitoring w/ real-time feedback" ---interactive: "Step-by-step guided process w/ user control" ---dry-run: "Preview changes without execution" ---force: "Override safety checks & confirmations" +@include shared/flag-inheritance.yml#Universal_Always -## Command-Specific Flags +## Core Operations -**Core Operations:** -- `--status`: Comprehensive repository status with branch and remote information -- `--commit [message]`: Create commit with automated staging and validation -- `--branch [name]`: Create, switch, or manage branches -- `--sync`: Fetch, pull, and push with conflict resolution -- `--merge [branch]`: Merge branches with conflict analysis -- `--stash [message]`: Stash management with descriptive messages +--commit flag: +- Stage appropriate files +- Generate meaningful commit message +- Include co-author attribution +- Follow conventional commits -**Advanced Operations:** -- `--history`: Detailed commit history with filtering options -- `--checkpoint [message]`: Create tagged state snapshots for rollback -- `--rollback [checkpoint]`: Rollback to specific checkpoint safely -- `--rebase [branch]`: Interactive or automatic rebase operations +--pr flag: +- Create pull request +- Generate PR description +- Set reviewers & labels +- Link related issues -**Branch Management:** -- `--list`: Show all branches with descriptions and status -- `--delete [branch]`: Delete merged branches safely -- `--track [remote/branch]`: Set up branch tracking +--flow flag: +- feature: Feature branch workflow +- hotfix: Emergency fix workflow +- release: Release branch workflow +- gitflow: Full GitFlow model -**Safety & Validation:** -- `--verify`: Verify repository state and integrity -- `--cleanup`: Clean up stale branches and references -- `--backup`: Create backup before risky operations +## Git Workflows + +Feature Development: +```bash +# Start new feature +/git --flow feature "user-authentication" + +# Commit progress +/git --commit "Add login form validation" + +# Create PR when ready +/git --pr --reviewers @team +``` + +Hotfix Process: +```bash +# Emergency fix +/git --flow hotfix "security-patch" + +# Quick commit & PR +/git --commit --pr "Fix SQL injection vulnerability" +``` + +Release Management: +```bash +# Start release +/git --flow release "v2.0.0" + +# Tag & merge +/git --tag --merge "Release version 2.0.0" +``` + +## Safety Features + +Pre-commit Checks: +- Verify branch is up to date +- Run linters & formatters +- Execute test suite +- Check for secrets +- Validate commit message + +Merge Protection: +- Require PR reviews +- Ensure CI passes +- Check branch policies +- Prevent force pushes +- Backup before risky ops + +## Advanced Features + +--interactive flag: +- Interactive staging (git add -p) +- Commit message editor +- Conflict resolution helper +- Cherry-pick assistance + +--history flag: +- Clean up commit history +- Interactive rebase +- Squash related commits +- Reorder for clarity + +--stats flag: +- Contribution analytics +- Code churn metrics +- Review turnaround time +- Branch lifetime stats + +## Best Practices + +Commits: +- Atomic, focused changes +- Present tense messages +- Reference issue numbers +- Co-author attribution +- Sign commits when required + +Branches: +- Descriptive names +- Regular rebasing +- Clean before merging +- Delete after merge +- Protect main branches ## Examples -- `/git --status` → Comprehensive repository status -- `/git --commit "Add authentication feature"` → Create commit with message -- `/git --branch feature/ui-redesign` → Create and switch to branch -- `/git --sync --verify` → Sync with remote and verify state -- `/git --merge develop --think` → Merge with conflict analysis -- `/git --checkpoint "Before major refactor"` → Create safety checkpoint -- `/git --history --author "john" --since "2024-01-01"` → Filtered history -## Git Operations +```bash +# Standard commit with message +/git --commit "Add user profile API endpoint" -**Status Operation (--status):** -- Working tree status and staged changes -- Current branch and upstream tracking -- Stashed changes with timestamps -- Recent commits (last 5) with summaries -- Unpushed commits count -- Remote repository status +# Create PR with reviewers +/git --pr --reviewers alice,bob --labels api,feature -**Commit Operation (--commit):** -- Automatic staging of modified files -- Generate conventional commit message if missing -- Pre-commit hooks and validation -- Test verification before commit -- Create automatic checkpoint -- GPG signing if configured +# Interactive cleanup before PR +/git --history --interactive -**Branch Management (--branch):** -- Create new branch from HEAD or specified base -- Switch to existing branch with safety checks -- Delete merged branches with verification -- List all branches with descriptions -- Automatic remote tracking setup -- Protection for main/master branches - -**Sync Operations (--sync):** -- Fetch from all configured remotes -- Pull with rebase to maintain clean history -- Push to tracked remote branch -- Handle authentication automatically -- Resolve merge conflicts interactively -- Update submodules if present - -**Merge Operations (--merge):** -- Fetch target branch before merging -- Analyze potential conflicts -- Create checkpoint before merge -- Use appropriate merge strategy -- Handle conflicts with interactive resolution -- Verify merge results - -**Stash Management (--stash):** -- Save changes with descriptive message -- List stashes with timestamps and summaries -- Apply or pop specific stash entries -- Drop old or unnecessary stashes -- Handle conflicts during stash application - -**History Operations (--history):** -- Formatted commit log with customizable output -- Filter by author, date, or file path -- Branch topology visualization -- Search commit messages -- File change statistics - -**Checkpoint System (--checkpoint):** -- Create tagged state snapshots -- Store with descriptive messages -- Maintain checkpoint manifest -- Enable safe rollback operations -- Track checkpoint metadata - -**Rollback Operations (--rollback):** -- List available checkpoints with details -- Verify rollback safety -- Create pre-rollback checkpoint -- Execute rollback with validation -- Verify final repository state - -## Workflow Patterns - -**Standard Development Workflow:** -1. Check status → Understand current state -2. Create checkpoint → Safety backup -3. Execute operation → Perform git action -4. Verify results → Validate changes -5. Sync with remote → Update shared repository - -**Feature Development:** -1. `git --status` → Check current state -2. `git --branch feature/new-feature` → Create feature branch -3. Development work... -4. `git --commit "Implement feature"` → Commit changes -5. `git --sync` → Push to remote -6. `git --merge main` → Integrate with main - -**Safe Operations:** -- Always create checkpoints before risky operations -- Verify repository state after major changes -- Use interactive mode for conflict resolution -- Maintain clean commit history with conventional messages +# Full feature workflow +/git --flow feature "payment-integration" --think +``` ## Deliverables -- **Updated Repository State**: Clean, consistent git history -- **Branch Management**: Organized branch structure -- **Remote Synchronization**: Up-to-date remote repositories -- **Audit Trail**: Complete history of operations -- **Safety Checkpoints**: Rollback points for recovery - -## Research Requirements -External_Library_Research: - - Identify library/framework mentioned - - Context7 lookup for official documentation - - Verify API patterns and examples - - Check version compatibility - - Document findings in implementation -Pattern_Research: - - Search existing codebase for similar patterns - - Magic component search if UI-related - - WebSearch for official documentation - - Validate approach with Sequential thinking - - Document pattern choice rationale -API_Integration_Research: - - Official documentation lookup - - Authentication requirements - - Rate limiting and error handling - - SDK availability and examples - - Integration testing approach - -## Lifecycle -Pre_Execution: - Risk_Assessment: Calculate risk score 1-10 based on data loss potential, irreversibility, scope, security - Environment_Validation: Check required tools, permissions, resources, dependencies - State_Preparation: Create checkpoint before risky ops, cache previous results -During_Execution: - Progress_Monitoring: Track operation progress, resource usage, error rates, token consumption - Dynamic_Optimization: Adjust parallelism, switch strategies, cache results, fallback to native - Error_Handling: Detect errors immediately, classify transient vs permanent, retry/fallback/halt -Post_Execution: - Verification: Confirm expected outcomes achieved, no side effects, state consistent - Cleanup: Remove temp files, locks, cached data; update audit logs, metrics, docs - Reporting: Generate success/failure report, performance metrics, recommendations - -## Integration Patterns - -**Quality Assurance:** -- Pre-commit hooks for code quality -- Test verification before commits -- Conventional commit message enforcement -- Branch protection rules - -**Team Collaboration:** -- Consistent branching strategies -- Merge request workflows -- Code review integration -- Conflict resolution procedures - -## Troubleshooting -- **Merge Conflicts**: Use `--merge --interactive` for guided resolution -- **Complex History**: Apply `--history --visual` for topology understanding -- **Repository Issues**: Use `--verify --cleanup` for maintenance -- **Rollback Needs**: Apply `--rollback` with checkpoint selection - -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +- Clean git history +- Meaningful commit messages +- Automated PR creation +- Branch management +- Workflow documentation \ No newline at end of file diff --git a/.claude/commands/improve.md b/.claude/commands/improve.md index 59c9047..1ad5e7b 100644 --- a/.claude/commands/improve.md +++ b/.claude/commands/improve.md @@ -1,329 +1,58 @@ # /improve - Enhance code quality, performance and architecture -## Legend -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose -Enhance code quality, performance, and architecture for systems specified in $ARGUMENTS using systematic improvement methodologies. +Systematically improve code quality, performance, and architecture in $ARGUMENTS using best practices and optimization techniques. ## Syntax `/improve [flags] [target]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always + +Examples: +- `/improve --quality` - Code quality improvements +- `/improve --perf --iterate` - Performance optimization +- `/improve --arch --think-hard` - Architecture refactoring ## Command-Specific Flags +--quality: "Code quality improvements (readability, maintainability, DRY)" +--perf: "Performance optimizations (algorithms, caching, queries)" +--arch: "Architecture improvements (patterns, coupling, scalability)" +--refactor: "Safe refactoring preserving behavior" +--iterate: "Iterative improvement until threshold met" +--threshold: "Quality threshold (low|medium|high|perfect)" +--metrics: "Show before/after metrics" +--safe: "Conservative mode - only safe changes" -**Improvement Focus:** -- `--quality`: Code structure, maintainability, and clean code principles -- `--performance`: System performance, bottlenecks, and optimization -- `--security`: Security improvements and vulnerability fixes -- `--architecture`: System design and architectural improvements -- `--ux`: User experience and interface improvements +## Improvement Categories -**Quality Enhancements:** -- `--solid`: Apply SOLID principles systematically -- `--refactor`: Clean code refactoring with modern patterns -- `--metrics`: Generate comprehensive quality metrics -- `--coverage`: Improve test coverage and quality +**Code Quality:** Naming clarity | Function extraction | Duplication removal | Complexity reduction | Error handling | Type safety -**Performance Optimization:** -- `--profile`: Performance profiling and bottleneck analysis -- `--cache`: Implement caching strategies -- `--async`: Optimize for asynchronous operations -- `--database`: Database query and schema optimization +**Performance:** Algorithm optimization | Query optimization | Caching strategies | Lazy loading | Memory efficiency | Parallel processing -**Execution Modes:** -- `--iterate`: Iterative improvement until threshold reached -- `--threshold [percent]`: Set target improvement percentage (default 85%) -- `--watch`: Continuous improvement monitoring -- `--interactive`: Guided improvement with user choices +**Architecture:** Design patterns | Dependency injection | Layer separation | Module boundaries | API design | Scalability patterns -## Examples -- `/improve --quality --solid --metrics` → Code quality with SOLID principles -- `/improve --performance --profile --cache` → Performance optimization with caching -- `/improve --iterate --threshold 90 --interactive` → Iterative improvement to 90% -- `/improve --security --architecture --seq` → Security and architecture analysis -- `/improve --ux --performance --watch` → UX and performance with monitoring +**Maintainability:** Documentation | Test coverage | Configuration extraction | Magic number removal | Dead code elimination -## Code Quality Mode (--quality) +## Improvement Process -**SOLID Principles Application:** -- **Single Responsibility**: One class, one clear purpose -- **Open/Closed**: Extensible without modification -- **Liskov Substitution**: Subtypes must be substitutable -- **Interface Segregation**: Specific over general interfaces -- **Dependency Inversion**: Depend on abstractions, not concretions +**1. Analysis:** Current state assessment | Identify improvement areas | Prioritize by impact | Set measurable goals -**Refactoring Techniques:** -- Extract methods and classes for complex logic -- Inline unnecessary abstractions -- Rename variables and functions for clarity -- Move code to appropriate modules -- Remove duplication (DRY principle) -- Simplify conditionals and loops -- Reduce coupling, increase cohesion +**2. Planning:** Safe refactoring path | Preserve functionality | Incremental changes | Rollback strategy -**Quality Metrics Tracking:** -- Cyclomatic complexity (target < 5) -- Method/function length (target < 20 lines) -- Class cohesion and coupling metrics -- Code duplication percentage -- Test coverage (target > 80%) -- Documentation completeness -- Technical debt assessment +**3. Implementation:** Small atomic changes | Continuous testing | Performance monitoring | Code review ready -**Clean Code Principles:** -- Meaningful, self-documenting names -- Functions that do one thing well -- Consistent coding style and formatting -- Proper error handling and logging -- Elimination of magic numbers and strings -- Comments that explain why, not what +**4. Validation:** Behavior preservation | Performance gains | Quality metrics | Regression testing -## Performance Mode (--performance) - -**Code Optimization:** -- Algorithm complexity reduction (O(n²) → O(n log n)) -- Efficient data structures selection -- Caching frequently accessed data -- Lazy loading and pagination strategies -- Asynchronous and parallel processing -- Memory usage optimization - -**Database Optimization:** -- Query optimization and proper indexing -- N+1 query elimination -- Connection pooling implementation -- Batch operations for bulk updates -- Strategic denormalization -- Query result caching - -**Frontend Optimization:** -- Bundle size reduction and tree shaking -- Code splitting and lazy loading -- Image and asset optimization -- Render performance improvements -- Service worker caching strategies -- React/Vue re-render optimization - -**System Optimization:** -- Load balancing strategies -- CDN implementation and optimization -- Compression (gzip/brotli) -- HTTP/2 and proper caching headers -- Resource pooling and connection management -- Microservice communication optimization - -## Iterative Mode (--iterate) - -**Improvement Process:** - -**1. Baseline Measurement:** -- Current performance metrics -- Code quality scores -- Test coverage percentage -- User experience metrics -- System reliability indicators - -**2. Targeted Improvements:** -- Identify highest impact areas (80/20 rule) -- Prioritize improvements by ROI -- Make incremental, measurable changes -- Maintain working state throughout - -**3. Progress Tracking:** -- Measure improvement after each iteration -- Document changes and their impact -- Calculate return on investment -- Adjust strategy based on results - -**4. Completion Criteria:** -- Target threshold achievement -- Diminishing returns detection -- Time or budget constraints -- "Good enough" quality level - -**Focus Areas by Type:** -- **Quality**: Complexity reduction, duplication removal, coverage increase -- **Performance**: Response time, throughput, resource utilization -- **User Experience**: Load time, responsiveness, error reduction -- **Maintainability**: Documentation, test quality, code structure - -## Architecture Improvements (--architecture) - -**Design Patterns:** -- Apply appropriate design patterns -- Implement dependency injection -- Use domain-driven design principles -- Implement proper separation of concerns - -**System Architecture:** -- Microservices decomposition -- Event-driven architecture -- CQRS implementation where appropriate -- API design and optimization - -**Scalability Enhancements:** -- Horizontal scaling strategies -- Database sharding and replication -- Caching layer implementation -- Load balancing optimization +@include shared/quality-patterns.yml#Code_Quality_Metrics ## Deliverables -- **Improvement Reports**: Detailed analysis of changes and their impact -- **Quality Metrics**: Before/after comparison of quality indicators -- **Performance Benchmarks**: Speed and efficiency improvements -- **Refactored Code**: Clean, optimized, and maintainable codebase -- **Documentation**: Updated docs reflecting improvements -## Output Locations -- **Reports**: `.claudedocs/metrics/improvement-{type}-{timestamp}.md` -- **Benchmarks**: `.claudedocs/metrics/performance-{timestamp}.json` -- **Quality Metrics**: `.claudedocs/metrics/quality-{timestamp}.md` +**Improved Code:** Refactored files | Preserved functionality | Enhanced quality | Better performance -## Research Requirements -External_Library_Research: - - Identify library/framework mentioned - - Context7 lookup for official documentation - - Verify API patterns and examples - - Check version compatibility - - Document findings in implementation -Pattern_Research: - - Search existing codebase for similar patterns - - Magic component search if UI-related - - WebSearch for official documentation - - Validate approach with Sequential thinking - - Document pattern choice rationale -API_Integration_Research: - - Official documentation lookup - - Authentication requirements - - Rate limiting and error handling - - SDK availability and examples - - Integration testing approach +**Improvement Report:** Before/after metrics | Changes summary | Performance gains | Quality improvements -## Report Notifications -📄 Analysis report saved to: {path} -📊 Metrics updated: {path} -📋 Summary saved to: {path} -💾 Checkpoint created: {path} -📚 Documentation created: {path} -📁 Created directory: {path} -✅ {operation} completed successfully -❌ {operation} failed: {reason} -⚠ {operation} completed w/ warnings +**Documentation:** Refactoring decisions | Architecture changes | Performance optimizations | Future recommendations -## Best Practices - -**Improvement Methodology:** -1. **Measure Before Changing**: Establish baseline metrics -2. **Focus on Bottlenecks**: Address highest impact issues first -3. **Incremental Changes**: Make one improvement at a time -4. **Verify Improvements**: Validate changes with metrics -5. **Document Changes**: Record what was changed and why -6. **Consider Trade-offs**: Balance competing concerns - -**Common Pitfalls to Avoid:** -- Premature optimization without profiling -- Over-engineering simple solutions -- Breaking changes without proper testing -- Ignoring existing test suite -- Gold-plating beyond requirements - -**Balance Considerations:** -- Performance vs code readability -- Flexibility vs simplicity -- Speed vs correctness -- Present needs vs future scalability - -## Common Improvement Scenarios - -### Code Quality Issues -```bash -/improve --quality --solid --metrics --dry-run -# → Identifies SOLID principle violations -# → Suggests refactoring for better modularity -# → Measures complexity metrics before/after changes -``` - -### Performance Bottlenecks -```bash -/improve --performance --iterate --threshold 90% -# → Profiles CPU and memory usage patterns -# → Implements algorithmic optimizations -# → Continues until 90% performance threshold met -``` - -### Technical Debt Reduction -```bash -/improve --quality --iterate --technical-debt -# → Identifies code duplication and anti-patterns -# → Suggests consolidation opportunities -# → Implements incremental refactoring strategy -``` - -### Error Handling Enhancement -```bash -/improve --resilience --error-handling --comprehensive -# → Reviews exception handling patterns -# → Implements proper logging and monitoring -# → Adds circuit breakers and retry mechanisms -``` - -## Troubleshooting -- **Complex Codebases**: Use `--iterate --interactive` for guided improvements -- **Performance Issues**: Combine `--performance --profile --seq` for deep analysis -- **Quality Problems**: Apply `--quality --solid --metrics` for comprehensive fixes -- **Architecture Concerns**: Use `--architecture --think-hard` for system-wide improvements - -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +@include shared/universal-constants.yml#Success_Messages \ No newline at end of file diff --git a/.claude/commands/index.md b/.claude/commands/index.md index 4d37052..af7af28 100644 --- a/.claude/commands/index.md +++ b/.claude/commands/index.md @@ -37,17 +37,14 @@ ## Purpose Comprehensive reference guide for all SuperClaude commands, workflows, and system capabilities. -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" +## Optimization Update (v4.0.0) +🎯 **Major Streamlining Completed**: All 18 command files optimized using @include references +- **Token Reduction**: ~70% reduction in command file size +- **Maintainability**: Single source of truth for all shared content +- **Consistency**: Guaranteed uniformity across commands +- **Reference System**: Commands now use shared patterns from `shared/*.yml` files + +@include shared/flag-inheritance.yml#Universal_Always --all-mcp: "Enable all MCP servers" --no-mcp: "Disable all MCP servers (native tools only)" --no-c7: "Disable Context7 specifically" diff --git a/.claude/commands/load.md b/.claude/commands/load.md index 68b4e64..2dcb7f3 100644 --- a/.claude/commands/load.md +++ b/.claude/commands/load.md @@ -1,38 +1,7 @@ # /load - Load and analyze project context ## Legend -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose Load and analyze project context in $ARGUMENTS to build comprehensive understanding of codebase structure, architecture, and patterns. @@ -40,217 +9,136 @@ Load and analyze project context in $ARGUMENTS to build comprehensive understand ## Syntax `/load [flags] [path]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always -## Command-Specific Flags +## Core Flags -**Analysis Depth:** -- `--depth shallow`: Quick overview of project structure and purpose -- `--depth normal`: Standard analysis of main files and architecture (default) -- `--depth deep`: Comprehensive analysis of entire codebase +--scope flag: +- minimal: Core files only +- standard: Main source & config +- comprehensive: All relevant files +- full: Complete project analysis -**Analysis Focus:** -- `--architecture`: Focus on system design and component relationships -- `--dependencies`: Analyze dependency graph and package relationships -- `--security`: Include security considerations and potential issues -- `--performance`: Identify performance patterns and potential bottlenecks -- `--testing`: Analyze testing approach and coverage patterns +--focus flag: +- architecture: System design +- api: API endpoints & contracts +- database: Schema & queries +- frontend: UI components +- testing: Test coverage -**Output Control:** -- `--summary`: Generate concise project overview -- `--detailed`: Include comprehensive analysis details -- `--recommendations`: Provide actionable next steps and improvements +--format flag: +- summary: High-level overview +- detailed: Comprehensive analysis +- visual: Include diagrams +- structured: YAML/JSON output + +## Loading Strategy + +Progressive Loading: +1. Core files (package.json, config) +2. Entry points (main, index) +3. Key modules & components +4. Tests & documentation +5. Supporting files + +Smart Selection: +- Prioritize by importance +- Skip generated files +- Focus on active code +- Include critical configs +- Respect .gitignore + +## Analysis Components + +Structure Analysis: +- Directory organization +- Module dependencies +- Component hierarchy +- API surface area +- Database schema + +Pattern Detection: +- Design patterns used +- Coding conventions +- Architecture style +- Technology stack +- Best practices + +Quality Metrics: +- Code complexity +- Test coverage +- Documentation level +- Technical debt +- Security concerns + +## Output Format + +Standard Report: +```yaml +Project: [Name] +Type: [Web App/API/Library] +Stack: + Frontend: [Technologies] + Backend: [Technologies] + Database: [Type] +Architecture: + Style: [Monolith/Microservices] + Patterns: [List] +Key_Components: + - [Component]: [Purpose] +Quality: + Test_Coverage: X% + Documentation: [Level] + Complexity: [Score] +``` + +## Best Practices + +Efficiency: +- Load incrementally +- Cache analysis results +- Focus on changes +- Skip redundant files +- Optimize memory usage + +Accuracy: +- Verify assumptions +- Cross-reference files +- Check documentation +- Validate patterns +- Update regularly ## Examples -- `/load --depth shallow` → Quick project overview -- `/load --depth deep --architecture` → Comprehensive architectural analysis -- `/load --dependencies --security` → Focus on deps and security -- `/load --performance --testing --detailed` → Performance and testing analysis -- `/load --summary --recommendations` → Overview with actionable insights -## Loading Process +```bash +# Quick project overview +/load --scope minimal -**1. Project Structure Scan:** -- Directory layout and organization -- File types and distribution -- Module boundaries and hierarchies -- Entry points and main components +# Full architecture analysis +/load --scope comprehensive --focus architecture -**2. Configuration Analysis:** -- Package manifests (package.json, requirements.txt, go.mod) -- Build configurations (webpack, vite, rollup) -- Environment and deployment configs -- CI/CD pipeline definitions +# API documentation generation +/load --focus api --format detailed -**3. Code Architecture Review:** -- Design patterns and architectural style -- Component relationships and dependencies -- Data flow and state management -- API structure and endpoints +# Complete project understanding +/load --scope full --think-hard +``` -**4. Development Environment:** -- Git repository status and history -- Development workflow patterns -- Testing framework and approach -- Documentation quality and coverage +## Integration -**5. Technology Stack Identification:** -- Frontend and backend technologies -- Database and data storage solutions -- Third-party integrations and services -- Development and deployment tools +@include shared/loading-config.yml#Loading_Strategies -## Analysis Depth Levels - -**Shallow Depth:** -- Project purpose and business goals -- Primary technologies and frameworks -- High-level architecture overview -- Key dependencies and integrations -- Quick start and setup information -- Development team structure clues - -**Normal Depth:** -- Detailed file and directory structure -- Main components and their responsibilities -- API endpoints, routes, and data models -- Database schema and relationships -- Testing strategy and coverage areas -- Development workflow and best practices - -**Deep Depth:** -- Complete codebase analysis and mapping -- Detailed component interaction diagrams -- Comprehensive dependency relationships -- Performance characteristics and bottlenecks -- Security considerations and vulnerabilities -- Technical debt assessment -- Optimization opportunities and recommendations - -## Essential Files Analysis - -**Documentation:** -- README.md (project overview and setup) -- CONTRIBUTING.md (development guidelines) -- API documentation and specs -- Architecture decision records (ADRs) - -**Configuration:** -- Package managers (package.json, yarn.lock, requirements.txt) -- Build tools (webpack.config.js, vite.config.ts) -- Environment configs (.env files, docker-compose.yml) -- CI/CD pipelines (.github/workflows, .gitlab-ci.yml) - -**Source Code:** -- Entry points (main.js, app.py, index.html) -- Core modules and components -- Shared utilities and libraries -- Test files and test configurations - -**Version Control:** -- Git history and commit patterns -- Branch strategy and naming conventions -- Recent changes and active development areas -- Contributor patterns and team structure - -## Mental Model Construction - -**System Understanding:** -- Component interaction patterns -- Data flow through the application -- External service integrations -- Deployment and infrastructure architecture -- User journey and experience flows - -**Development Insights:** -- Code quality and consistency patterns -- Testing maturity and coverage -- Documentation completeness -- Development velocity indicators -- Technical debt and maintenance needs +Works with: +- /analyze for deep inspection +- /document for documentation +- /improve for enhancements +- /estimate for planning ## Deliverables -- **Project Overview**: Comprehensive understanding summary -- **Architecture Map**: System design and component relationships -- **Technology Inventory**: Complete stack and dependency analysis -- **Development Guide**: Quick reference for project navigation -- **Recommendations**: Next steps and improvement opportunities -- **Risk Assessment**: Potential issues and technical debt areas -## Output Locations -- **Analysis Reports**: `.claudedocs/summaries/project-analysis-{timestamp}.md` -- **Architecture Docs**: `.claudedocs/summaries/architecture-overview-{timestamp}.md` -- **Quick Reference**: `.claudedocs/summaries/project-guide-{timestamp}.md` - -## Research Requirements -External_Library_Research: - - Identify library/framework mentioned - - Context7 lookup for official documentation - - Verify API patterns and examples - - Check version compatibility - - Document findings in implementation -Pattern_Research: - - Search existing codebase for similar patterns - - Magic component search if UI-related - - WebSearch for official documentation - - Validate approach with Sequential thinking - - Document pattern choice rationale -API_Integration_Research: - - Official documentation lookup - - Authentication requirements - - Rate limiting and error handling - - SDK availability and examples - - Integration testing approach - -## Report Notifications -📄 Analysis report saved to: {path} -📊 Metrics updated: {path} -📋 Summary saved to: {path} -💾 Checkpoint created: {path} -📚 Documentation created: {path} -📁 Created directory: {path} -✅ {operation} completed successfully -❌ {operation} failed: {reason} -⚠ {operation} completed w/ warnings - -## Integration Patterns - -**Workflow Integration:** -- Load project context before major development work -- Refresh understanding after significant changes -- Share context with team members and new contributors -- Use as foundation for architecture decisions - -**Command Chaining:** -- `load` → `analyze --architecture` for design review -- `load` → `scan --security` for security assessment -- `load` → `improve --quality` for refactoring planning -- `load` → `document --architecture` for documentation - -## Troubleshooting -- **Large Codebases**: Use `--depth shallow` for initial overview -- **Complex Architecture**: Combine `--architecture --detailed` for comprehensive analysis -- **Performance Issues**: Include `--performance` flag for optimization insights -- **Security Concerns**: Add `--security` flag for vulnerability assessment - -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +- Project structure map +- Architecture diagram +- Component inventory +- Dependency graph +- Quality metrics report +- Pattern analysis \ No newline at end of file diff --git a/.claude/commands/migrate.md b/.claude/commands/migrate.md index 436ee1e..ec6ca5c 100644 --- a/.claude/commands/migrate.md +++ b/.claude/commands/migrate.md @@ -1,38 +1,7 @@ # /migrate - Execute database and code migrations ## Legend -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose Execute comprehensive database or code migrations based on specifications in $ARGUMENTS with safety checks and rollback capabilities. @@ -40,264 +9,138 @@ Execute comprehensive database or code migrations based on specifications in $AR ## Syntax `/migrate [flags] [migration-spec]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always -## Command-Specific Flags +## Core Flags -**Migration Types:** -- `--schema`: Database schema migrations (tables, indexes, constraints) -- `--data`: Data transformation and migration operations -- `--code`: Code refactoring and modernization migrations -- `--framework`: Framework or library version migrations -- `--config`: Configuration and environment migrations +--type flag: +- database: SQL schema migrations +- code: Codebase refactoring +- api: API version migration +- data: Data transformation +- full: Complete system migration -**Execution Control:** -- `--dry-run`: Preview changes without execution -- `--rollback`: Revert to pre-migration state -- `--checkpoint`: Create checkpoint before migration -- `--force`: Override safety checks (use with caution) +--direction flag: +- up: Apply migrations forward +- down: Rollback migrations +- status: Check migration state +- validate: Test without applying -**Safety & Validation:** -- `--backup`: Create full backup before migration -- `--validate`: Validate migration integrity and consistency -- `--test-mode`: Run in isolated test environment -- `--zero-downtime`: Implement zero-downtime migration strategy - -**Monitoring:** -- `--progress`: Show detailed progress during migration -- `--log-level [level]`: Set logging verbosity (info|debug|trace) -- `--timeout [seconds]`: Set maximum migration duration - -## Examples -- `/migrate --schema --dry-run --think` → Schema migration preview with analysis -- `/migrate --data --backup --validate --think-hard` → Data migration with safety checks -- `/migrate --framework --zero-downtime --ultrathink` → Framework upgrade with zero downtime -- `/migrate --rollback --checkpoint restore-20240115` → Rollback to specific checkpoint -- `/migrate --code --test-mode --progress` → Code migration in test environment +--target flag: +- latest: All pending migrations +- version: Specific version +- step: Number of migrations +- timestamp: Up to date/time ## Migration Types -**Schema Migrations:** -- Create, alter, or drop database tables -- Add or modify indexes for performance -- Update constraints and relationships -- Manage database versioning and compatibility -- Handle foreign key dependencies +Database Migrations: +- Schema changes (add/drop tables) +- Column modifications +- Index optimization +- Constraint updates +- Data transformations -**Data Migrations:** -- Transform existing data to new formats -- Backfill missing or derived data fields -- Clean up obsolete or orphaned records -- Ensure referential integrity throughout process -- Handle large dataset migrations efficiently +Code Migrations: +- API version updates +- Framework upgrades +- Dependency updates +- Structure refactoring +- Pattern modernization -**Code Migrations:** -- Refactor to new architectural patterns -- Update to new framework versions -- Migrate between different technologies -- Modernize legacy code and patterns -- Update API contracts and interfaces +Data Migrations: +- Format conversions +- Bulk transformations +- ETL operations +- Cleanup operations +- Normalization -**Framework Migrations:** -- Upgrade major framework versions -- Migrate between competing frameworks -- Update dependency chains -- Handle breaking changes systematically -- Maintain backward compatibility where possible +## Safety Features -## Safe Migration Workflow +Pre-Migration: +- Backup current state +- Validate migration files +- Check dependencies +- Test in transaction +- Estimate impact -**1. Planning Phase:** -- Analyze migration requirements and scope -- Design migration strategy and approach -- Create comprehensive rollback plan -- Identify dependencies and prerequisites -- Estimate duration and resource requirements +During Migration: +- Transaction wrapping +- Progress tracking +- Error handling +- Partial rollback +- Health checks -**2. Preparation Phase:** -- Create full backup of affected systems -- Set up isolated test environment -- Prepare migration scripts and procedures -- Validate rollback procedures -- Notify stakeholders and schedule downtime +Post-Migration: +- Verify integrity +- Update documentation +- Clear caches +- Run tests +- Monitor performance -**3. Testing Phase:** -- Run migration in test environment -- Validate data integrity and functionality -- Test rollback procedures -- Performance test with realistic data -- Document any issues and resolutions +## Migration Workflow -**4. Execution Phase:** -- Apply migration with transaction support -- Monitor system performance and health -- Track progress and log all operations -- Handle errors gracefully with fallbacks -- Maintain communication with stakeholders +1. Analysis Phase: + - Scan current state + - Identify changes needed + - Generate migration plan + - Estimate risks -**5. Verification Phase:** -- Validate migration success and completeness -- Verify data integrity with checksums -- Run comprehensive test suite -- Monitor system stability post-migration -- Document lessons learned and improvements +2. Preparation Phase: + - Create backups + - Prepare rollback plan + - Set up monitoring + - Notify stakeholders -## Dry Run Operations (--dry-run) +3. Execution Phase: + - Run migrations + - Track progress + - Handle errors + - Apply fixes -**Preview Capabilities:** -- Show all changes without executing them -- Display affected records and files count -- Estimate migration duration and resource usage -- Identify potential issues and conflicts -- Generate detailed execution plan - -**Risk Assessment:** -- Analyze impact on system performance -- Identify data integrity risks -- Assess rollback complexity -- Evaluate downtime requirements -- Calculate resource utilization - -## Rollback Operations (--rollback) - -**Rollback Strategies:** -- Transaction-based rollback for database changes -- Backup restoration for complex changes -- Code version control reversion -- Configuration rollback procedures -- Progressive rollback for staged migrations - -**Rollback Verification:** -- Verify system returns to pre-migration state -- Validate data integrity after rollback -- Test system functionality completely -- Monitor performance and stability -- Document rollback effectiveness - -## Zero-Downtime Migrations (--zero-downtime) - -**Strategies:** -- Blue-green deployment patterns -- Rolling updates with health checks -- Shadow migration and cutover -- Feature flags for gradual rollout -- Database read replica promotion - -**Implementation:** -- Maintain dual-write compatibility -- Implement backward-compatible schemas -- Use load balancers for traffic switching -- Monitor key metrics during transition -- Prepare instant rollback mechanisms - -## Safety Measures - -**Data Protection:** -- Automatic backup creation before migration -- Transaction atomicity for database operations -- Checksum validation for data integrity -- Idempotent migration scripts -- Recovery point objectives (RPO) compliance - -**System Protection:** -- Resource usage monitoring and limits -- Timeout protection for long operations -- Health checks and circuit breakers -- Progressive execution with validation -- Automated rollback triggers - -## Deliverables -- **Migration Scripts**: Complete, tested migration procedures -- **Execution Report**: Detailed migration statistics and outcomes -- **Backup Confirmation**: Verified backup creation and integrity -- **Data Integrity Report**: Validation of data consistency post-migration -- **Rollback Procedures**: Documented and tested rollback plans -- **Performance Metrics**: Before/after performance comparisons - -## Output Locations -- **Migration Logs**: `.claudedocs/reports/migration-{timestamp}.md` -- **Data Validation**: `.claudedocs/metrics/data-validation-{timestamp}.md` -- **Rollback Plans**: `.claudedocs/summaries/rollback-plan-{timestamp}.md` -- **Performance Reports**: `.claudedocs/metrics/migration-performance-{timestamp}.md` - -## Research Requirements -External_Library_Research: - - Identify library/framework mentioned - - Context7 lookup for official documentation - - Verify API patterns and examples - - Check version compatibility - - Document findings in implementation -Pattern_Research: - - Search existing codebase for similar patterns - - Magic component search if UI-related - - WebSearch for official documentation - - Validate approach with Sequential thinking - - Document pattern choice rationale -API_Integration_Research: - - Official documentation lookup - - Authentication requirements - - Rate limiting and error handling - - SDK availability and examples - - Integration testing approach - -## Report Notifications -📄 Analysis report saved to: {path} -📊 Metrics updated: {path} -📋 Summary saved to: {path} -💾 Checkpoint created: {path} -📚 Documentation created: {path} -📁 Created directory: {path} -✅ {operation} completed successfully -❌ {operation} failed: {reason} -⚠ {operation} completed w/ warnings +4. Validation Phase: + - Verify success + - Run test suite + - Check performance + - Update docs ## Best Practices -**Planning:** -- Always test migrations in staging environment -- Create detailed rollback plans before execution -- Communicate with stakeholders about timing -- Plan for peak and off-peak execution windows -- Document all migration decisions and rationale +Safety: +- Always backup first +- Test in staging +- Use transactions +- Plan rollbacks +- Monitor closely -**Execution:** -- Use transactions for atomicity where possible -- Monitor system health throughout migration -- Keep detailed logs of all operations -- Have rollback procedures ready and tested -- Validate data integrity at each step +Performance: +- Batch operations +- Off-peak execution +- Index management +- Query optimization +- Resource limits -**Post-Migration:** -- Verify system functionality completely -- Monitor performance for regression -- Clean up temporary migration artifacts -- Update documentation and procedures -- Conduct post-mortem for improvement +## Examples -## Troubleshooting -- **Large Datasets**: Use `--progress --timeout` for monitoring -- **Complex Dependencies**: Apply `--think-hard` for comprehensive planning -- **Production Systems**: Combine `--zero-downtime --backup --validate` -- **Failed Migrations**: Use `--rollback` with specific checkpoint +```bash +# Database migration to latest +/migrate --type database --direction up -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +# Rollback last 2 migrations +/migrate --type database --direction down --step 2 + +# Code migration with validation +/migrate --type code --validate --think + +# Full system migration plan +/migrate --type full --plan --ultrathink +``` + +## Deliverables + +- Migration scripts +- Rollback procedures +- Execution logs +- Validation reports +- Updated documentation +- Performance metrics \ No newline at end of file diff --git a/.claude/commands/scan.md b/.claude/commands/scan.md index 6d10896..090fb9d 100644 --- a/.claude/commands/scan.md +++ b/.claude/commands/scan.md @@ -1,351 +1,57 @@ -# /scan - Perform security and validation scans +# /scan - Security and quality scanning -## Legend -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose -Perform comprehensive security and validation scans on code, operations, or systems specified in $ARGUMENTS to identify vulnerabilities and safety issues. +Perform comprehensive security, quality, and dependency scanning on code specified in $ARGUMENTS. ## Syntax `/scan [flags] [target]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always + +Examples: +- `/scan --security` - Security vulnerability scan +- `/scan --deps` - Dependency audit +- `/scan --validate` - Full validation scan +- `/scan --quick` - Quick scan for critical issues ## Command-Specific Flags +--security: "Deep security vulnerability scanning (OWASP, CVEs, secrets)" +--deps: "Dependency vulnerability audit w/ fix recommendations" +--validate: "Comprehensive validation (syntax, types, logic, security)" +--quick: "Fast scan focusing on critical issues only" +--fix: "Auto-fix safe issues" +--strict: "Zero-tolerance mode (fail on any issue)" +--report: "Generate detailed report" +--ci: "CI-friendly output format" -**Scan Types:** -- `--validate`: Pre-execution safety validation and risk assessment -- `--security`: Comprehensive security analysis and vulnerability scanning -- `--owasp`: Focus on OWASP Top 10 security risks -- `--deps`: Dependency vulnerability and license scanning -- `--config`: Configuration security and compliance checking +## Scan Types -**Scan Depth:** -- `--quick`: Fast validation for common issues with rapid feedback -- `--comprehensive`: Deep analysis covering all security aspects -- `--strict`: Zero-tolerance mode flagging all potential issues +**Security Scan:** OWASP Top 10 | Injection vulnerabilities | Auth flaws | Sensitive data exposure | Hardcoded secrets | CVE database check -**Specialized Scans:** -- `--infrastructure`: Infrastructure and deployment security -- `--code`: Source code security analysis -- `--data`: Data protection and privacy compliance -- `--network`: Network security and exposure analysis +**Dependency Scan:** Known vulnerabilities | Outdated packages | License compliance | Supply chain risks | Transitive dependencies -**Output Control:** -- `--report`: Generate detailed security report -- `--json`: Output results in JSON format for automation -- `--summary`: Provide executive summary with key findings +**Code Quality:** Complexity metrics | Duplication | Dead code | Type safety | Best practices | Performance antipatterns -## Examples -- `/scan --validate --quick` → Fast pre-execution safety check -- `/scan --security --owasp --comprehensive` → Complete OWASP security audit -- `/scan --deps --strict --report` → Dependency scan with detailed report -- `/scan --validate --security --think` → Combined validation and security with analysis -- `/scan --infrastructure --config --json` → Infrastructure security in JSON format +**Configuration:** Misconfigured services | Insecure defaults | Missing security headers | Exposed endpoints | Weak crypto -## Validation Mode (--validate) +## Validation Levels -**Pre-Execution Safety Checks:** +**Quick (--quick):** Critical security only | Known CVEs | Hardcoded secrets | SQL injection | XSS vulnerabilities -**Security Validation:** -- Path traversal prevention and boundary enforcement -- Secrets and credentials detection in code -- Permission verification and access control -- Input sanitization and validation checks -- Output encoding and XSS prevention +**Standard (default):** All security checks | Major quality issues | Dependency vulnerabilities | Configuration problems -**Code Validation:** -- Syntax correctness and compilation checks -- Import and dependency verification -- Breaking change detection and compatibility -- Configuration validity and completeness -- Type safety and null pointer checks +**Strict (--strict):** Everything + minor issues | Style violations | Documentation gaps | Test coverage | Performance warnings -**Operation Validation:** -- Git repository state verification -- Branch protection compliance -- Resource availability and capacity -- Rollback capability assessment -- Blast radius and impact analysis - -**Risk Assessment Framework:** -- Calculate comprehensive risk score (1-10) -- Impact analysis (data loss, downtime, security) -- Reversibility and recovery evaluation -- Required permissions and access verification -- Compliance and regulatory checks - -**Validation Workflow:** -1. Parse and analyze intended operation -2. Run all applicable safety checks -3. Generate risk score and impact assessment -4. Report with clear status indicators: - - ✅ **Pass**: Safe to proceed without concerns - - ⚠️ **Warning**: Caution advised, review recommended - - ❌ **Block**: Do not proceed, issues must be resolved - -## Security Mode (--security) - -**OWASP Top 10 Analysis:** -- **Injection Flaws**: SQL, NoSQL, OS command, LDAP injection detection -- **Broken Authentication**: Session management and auth weakness detection -- **Sensitive Data Exposure**: Data protection and encryption analysis -- **XML External Entities (XXE)**: XML processing vulnerability detection -- **Broken Access Control**: Authorization and privilege escalation issues -- **Security Misconfiguration**: Configuration hardening assessment -- **Cross-Site Scripting (XSS)**: XSS vulnerability detection and prevention -- **Insecure Deserialization**: Object deserialization security analysis -- **Known Vulnerable Components**: Dependency vulnerability scanning -- **Insufficient Logging**: Security monitoring and audit trail analysis - -**Code Security Analysis:** -- Input validation gaps and boundary checks -- Output encoding issues and data sanitization -- Authentication mechanism weaknesses -- Authorization logic flaws and privilege escalation -- Cryptographic implementation problems -- Error handling information leakage -- Session management security issues -- File operation safety and path traversal - -**Dependency Security Scanning:** -- Known CVE (Common Vulnerabilities and Exposures) detection -- Outdated package identification with security implications -- License compliance and legal risk assessment -- Transitive dependency vulnerability analysis -- Security patch availability and update recommendations -- Typosquatting and malicious package detection - -**Configuration Security:** -- Hardcoded secrets and credentials scanning -- Environment variable security assessment -- File and directory permission configurations -- Network exposure and attack surface analysis -- TLS/SSL configuration and certificate validation -- CORS policies and cross-origin security -- Security headers implementation verification - -**Infrastructure Security:** -- Open ports and unnecessary services identification -- Firewall rules and network segmentation -- Access control lists and identity management -- Encryption in transit and at rest verification -- Backup security and disaster recovery assessment -- Logging configuration and audit trail analysis - -## Scan Execution Modes - -**Quick Scan (--quick):** -- Focus on most critical and common vulnerabilities -- Skip time-intensive deep analysis procedures -- Prioritize immediate security concerns -- Provide rapid feedback for development workflow -- Suitable for pre-commit hooks and fast CI/CD - -**Comprehensive Scan (--comprehensive):** -- Complete security analysis across all categories -- Deep dive into complex security patterns -- Thorough dependency and configuration analysis -- Detailed threat modeling and risk assessment -- Suitable for periodic security audits - -**Strict Mode (--strict):** -- Zero-tolerance approach to security issues -- Flag all potential security concerns -- Enforce industry best practices and standards -- Require explicit overrides for any findings -- Suitable for high-security environments - -## Scan Results and Reporting - -**Security Findings Classification:** -- **CRITICAL [10]**: Immediate action required, system at risk -- **HIGH [7-9]**: Fix before deployment, significant security risk -- **MEDIUM [4-6]**: Address in next development cycle -- **LOW [1-3]**: Best practice improvements, technical debt - -**Report Contents:** -- Executive summary with overall risk assessment -- Detailed findings categorized by security domain -- Specific remediation steps with code examples -- References to security resources and documentation -- Compliance mapping to relevant standards (SOC2, PCI-DSS) -- Trend analysis compared to previous scans - -**Integration Behavior:** -- Auto-trigger validation for high-risk operations -- Chain with execution: `scan --validate && command` -- Block execution for CRITICAL [10] severity issues -- Require explicit confirmation for HIGH [7-9] risks -- Log all scan results for audit and compliance +@include shared/security-patterns.yml#OWASP_Top_10 ## Deliverables -- **Security Report**: Comprehensive vulnerability assessment -- **Risk Matrix**: Prioritized list of security issues -- **Remediation Guide**: Step-by-step fix instructions -- **Compliance Report**: Regulatory and standard compliance status -- **Trend Analysis**: Security posture improvement tracking -## Output Locations -- **Security Reports**: `.claudedocs/reports/security-scan-{timestamp}.md` -- **Validation Results**: `.claudedocs/reports/validation-{timestamp}.md` -- **Compliance Reports**: `.claudedocs/reports/compliance-{timestamp}.md` -- **Metrics**: `.claudedocs/metrics/security-metrics-{timestamp}.json` +**Reports:** `.claudedocs/scans/security-{timestamp}.md` | Severity classification | Fix recommendations | Risk assessment -## Research Requirements -External_Library_Research: - - Identify library/framework mentioned - - Context7 lookup for official documentation - - Verify API patterns and examples - - Check version compatibility - - Document findings in implementation -Pattern_Research: - - Search existing codebase for similar patterns - - Magic component search if UI-related - - WebSearch for official documentation - - Validate approach with Sequential thinking - - Document pattern choice rationale -API_Integration_Research: - - Official documentation lookup - - Authentication requirements - - Rate limiting and error handling - - SDK availability and examples - - Integration testing approach +**Fix Scripts:** Auto-generated patches | Safe automated fixes | Manual fix instructions | Rollback procedures -## Report Notifications -📄 Analysis report saved to: {path} -📊 Metrics updated: {path} -📋 Summary saved to: {path} -💾 Checkpoint created: {path} -📚 Documentation created: {path} -📁 Created directory: {path} -✅ {operation} completed successfully -❌ {operation} failed: {reason} -⚠ {operation} completed w/ warnings +**CI Integration:** Exit codes | JSON output | SARIF format | GitHub/GitLab integration -## Integration Patterns - -**CI/CD Integration:** -- Fail builds on HIGH or CRITICAL security findings -- Generate security reports for each release -- Track security debt and improvement trends -- Automate security patch application - -**Development Workflow:** -- Pre-commit hooks for quick security validation -- Pull request security gates -- Regular scheduled comprehensive scans -- Security review integration with code reviews - -**Command Chaining:** -- `scan --validate` before `deploy` operations -- `scan --security --strict` for security audits -- `scan --deps` before `migrate` operations -- `scan --config` after `dev-setup` configuration - -## Best Practices - -**Regular Scanning:** -- Run validation before any risky operations -- Schedule weekly comprehensive security scans -- Implement automated dependency vulnerability monitoring -- Track and trend security findings over time - -**Response Procedures:** -- Document exceptions with business justification -- Implement fix verification with re-scanning -- Maintain security issue tracking and resolution -- Regular security training and awareness programs - -## Common Security Issues & Solutions - -### SQL Injection Vulnerabilities -```bash -/scan --security --owasp "SQL injection patterns" -# → Identifies unsanitized database queries -# → Suggests parameterized query implementations -# → Validates input sanitization functions -``` - -### Dependency Vulnerabilities -```bash -/scan --deps --security --json -# → Scans package.json/requirements.txt for known CVEs -# → Provides upgrade paths for vulnerable dependencies -# → Generates automated security patch recommendations -``` - -### Configuration Security Issues -```bash -/scan --config --env --validate -# → Checks for exposed API keys and secrets -# → Validates SSL/TLS configuration -# → Reviews permission and access control settings -``` - -### OWASP Top 10 Compliance Check -```bash -/scan --owasp --comprehensive --report -# → Performs full OWASP Top 10 vulnerability assessment -# → Generates compliance report with remediation steps -# → Tracks progress against security benchmarks -``` - -## Troubleshooting -- **False Positives**: Use `--quick` for initial assessment, then `--comprehensive` -- **Complex Applications**: Apply `--think-hard` for thorough analysis -- **CI/CD Integration**: Use `--json` output for automated processing -- **Legacy Systems**: Combine `--security --deps --config` for complete assessment - -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +@include shared/universal-constants.yml#Success_Messages \ No newline at end of file diff --git a/.claude/commands/shared/command-patterns.yml b/.claude/commands/shared/command-patterns.yml index 9fc4fd7..33ea620 100644 --- a/.claude/commands/shared/command-patterns.yml +++ b/.claude/commands/shared/command-patterns.yml @@ -14,6 +14,31 @@ Command_Header: Legend: "@cmd-specific legend gen" Purpose: "[Action][Subject] in $ARGUMENTS" +## Optimized Command File Template + +```yaml +# Standard template for all command files using @include references +Optimized_Command_Template: | + @include shared/universal-constants.yml#Universal_Legend + + ## Command Execution + Execute: immediate. --plan→show plan first + Legend: Generated based on symbols used in command + Purpose: "[Action][Subject] in $ARGUMENTS" + + [Command-specific description here] + + @include shared/flag-inheritance.yml#Universal_Always + + Examples: + - `/{command} --flag` - Description + - `/{command} --other-flag` - Description + - `/{command} --complex-example` - Description + + [Command-specific content sections] + + @include shared/universal-constants.yml#Success_Messages + ## UltraCompressed Command Structure ```yaml diff --git a/.claude/commands/spawn.md b/.claude/commands/spawn.md index cb6b8a6..39de465 100644 --- a/.claude/commands/spawn.md +++ b/.claude/commands/spawn.md @@ -1,38 +1,7 @@ # /spawn - Spawn focused agent for specialized tasks ## Legend -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose Spawn specialized sub-agents to handle specific tasks in $ARGUMENTS with focused expertise and parallel execution capabilities. @@ -40,272 +9,143 @@ Spawn specialized sub-agents to handle specific tasks in $ARGUMENTS with focused ## Syntax `/spawn [flags] [task-description]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always -## Command-Specific Flags +## Core Flags -**Agent Specialization:** -- `--frontend`: Spawn UI/UX and frontend development agent -- `--backend`: Spawn API and backend services agent -- `--devops`: Spawn infrastructure and deployment agent -- `--data`: Spawn data analysis and database agent -- `--security`: Spawn security and compliance agent -- `--qa`: Spawn quality assurance and testing agent +--agent flag: +- researcher: Deep research & analysis +- builder: Code generation +- reviewer: Code review & QA +- optimizer: Performance tuning +- documenter: Documentation expert -**Task Configuration:** -- `--task [description]`: Define clear, focused assignment with specific objectives -- `--context [info]`: Provide necessary background context and constraints -- `--scope [boundaries]`: Set clear task boundaries and limitations -- `--timeline [duration]`: Specify expected completion timeframe +--mode flag: +- sequential: One agent at a time +- parallel: Multiple agents +- collaborative: Agents work together +- supervisor: Oversee sub-agents -**Coordination:** -- `--parallel`: Enable parallel execution with main workflow -- `--sequential`: Require sequential execution after current tasks -- `--integrate`: Automatic integration of results with main context -- `--review`: Require manual review before integration +--scope flag: +- focused: Single specific task +- broad: Multiple related tasks +- exploratory: Open-ended research +- iterative: Refine through cycles -**Quality Control:** -- `--validate`: Validate agent output before integration -- `--test`: Include testing requirements in agent task -- `--document`: Require documentation of agent work +## Agent Types -## Examples -- `/spawn --frontend --task "implement user dashboard" --think` → Frontend agent with coordination analysis -- `/spawn --security --task "implement auth system" --validate --think-hard` → Security agent with validation -- `/spawn --devops --task "setup CI/CD pipeline" --document --ultrathink` → DevOps agent with documentation -- `/spawn --data --task "optimize database queries" --test --parallel` → Data agent with testing in parallel -- `/spawn --qa --task "comprehensive test suite" --integrate` → QA agent with auto-integration +Researcher Agent: +- Deep dive into topics +- Compare solutions +- Analyze trade-offs +- Find best practices +- Document findings -## Agent Specializations +Builder Agent: +- Generate code +- Implement features +- Create tests +- Build prototypes +- Integrate systems -**Frontend Agent:** -- User interface and user experience implementation -- Component development with modern frameworks -- State management and data flow -- Performance optimization and bundle analysis -- Accessibility compliance and responsive design -- Cross-browser compatibility and testing +Reviewer Agent: +- Code quality checks +- Security analysis +- Performance review +- Best practice validation +- Suggest improvements -**Backend Agent:** -- RESTful and GraphQL API development -- Database design and operations -- Business logic implementation -- Third-party service integrations -- Performance tuning and optimization -- Security implementation and hardening +Optimizer Agent: +- Performance profiling +- Resource optimization +- Algorithm improvements +- Database tuning +- Cache strategies -**DevOps Agent:** -- CI/CD pipeline setup and optimization -- Infrastructure as Code (IaC) development -- Deployment strategy design and implementation -- Monitoring and observability configuration -- Security hardening and compliance -- Container orchestration and scaling +Documenter Agent: +- API documentation +- User guides +- Code comments +- Architecture docs +- README files -**Data Agent:** -- Data analysis and statistical modeling -- Database optimization and query tuning -- ETL pipeline development and maintenance -- Data quality assurance and validation -- Reporting and visualization solutions -- Data governance and compliance +## Execution Modes -**Security Agent:** -- Security vulnerability assessment and remediation -- Authentication and authorization implementation -- Encryption and data protection strategies -- Compliance framework implementation -- Security monitoring and incident response -- Penetration testing and security audits +Sequential Mode: +```yaml +Flow: Agent1 → Agent2 → Agent3 +Use: When tasks depend on each other +Example: Research → Build → Review +``` -**QA Agent:** -- Test strategy and framework development -- Automated testing implementation -- Manual testing procedures and protocols -- Performance and load testing -- Quality metrics and reporting -- Bug tracking and resolution workflows +Parallel Mode: +```yaml +Flow: Agent1 | Agent2 | Agent3 +Use: For independent tasks +Example: Multiple feature builds +``` -## Agent Task Definition - -**Clear Scope Definition:** -- Specific, measurable deliverables -- Clear task boundaries and limitations -- Time constraints and deadlines -- Quality expectations and standards -- Success criteria and acceptance conditions - -**Context Provision:** -- Relevant code sections and documentation -- Architecture decisions and constraints -- Previous implementation decisions -- Technical requirements and dependencies -- Integration points with existing systems - -**Success Criteria:** -- Measurable outcomes and metrics -- Quality standards and benchmarks -- Integration requirements and compatibility -- Testing expectations and coverage -- Performance targets and constraints - -**Coordination Requirements:** -- Avoid conflicts with ongoing work -- Plan integration and merge points -- Handle inter-task dependencies -- Manage communication and updates -- Establish review and approval processes - -## Agent Workflow - -**1. Agent Spawning:** -- Analyze task requirements and complexity -- Select appropriate agent specialization -- Define clear task scope and objectives -- Provide necessary context and constraints -- Establish success criteria and timeline - -**2. Independent Execution:** -- Agent works autonomously on assigned task -- Focused context and specialized expertise -- Progress tracking and status updates -- Problem-solving within defined scope -- Quality assurance and self-validation - -**3. Progress Monitoring:** -- Regular status updates and checkpoints -- Issue escalation and dependency resolution -- Scope adjustment and timeline management -- Quality review and feedback incorporation -- Communication with main workflow - -**4. Result Integration:** -- Comprehensive result review and validation -- Integration planning and execution -- Knowledge transfer to main context -- Documentation and lessons learned -- Quality verification and testing - -**5. Completion Handoff:** -- Final deliverable validation -- Integration verification and testing -- Documentation and knowledge transfer -- Cleanup and resource management -- Success metrics and outcome assessment - -## Benefits of Agent Spawning - -**Efficiency Gains:** -- Parallel task execution and processing -- Specialized expertise and focused attention -- Reduced cognitive load on main workflow -- Faster task completion and delivery -- Improved resource utilization - -**Quality Improvements:** -- Domain-specific expertise application -- Focused quality assurance and testing -- Specialized best practices implementation -- Reduced context switching overhead -- Enhanced problem-solving capabilities - -**Scalability Advantages:** -- Distributed workload management -- Independent task scaling -- Flexible resource allocation -- Modular development approach -- Improved development velocity - -## Deliverables -- **Task Results**: Completed work from spawned agent with quality validation -- **Integration Plan**: Strategy for merging agent work with main context -- **Knowledge Transfer**: Documentation of agent decisions and implementation -- **Coordination Summary**: Agent workflow and communication log -- **Quality Report**: Validation and testing results from agent work - -## Output Locations -- **Agent Logs**: `.claudedocs/reports/agent-spawn-{timestamp}.md` -- **Task Results**: `.claudedocs/summaries/agent-results-{timestamp}.md` -- **Integration Plans**: `.claudedocs/summaries/integration-plan-{timestamp}.md` - -## Research Requirements -External_Library_Research: - - Identify library/framework mentioned - - Context7 lookup for official documentation - - Verify API patterns and examples - - Check version compatibility - - Document findings in implementation -Pattern_Research: - - Search existing codebase for similar patterns - - Magic component search if UI-related - - WebSearch for official documentation - - Validate approach with Sequential thinking - - Document pattern choice rationale -API_Integration_Research: - - Official documentation lookup - - Authentication requirements - - Rate limiting and error handling - - SDK availability and examples - - Integration testing approach - -## Report Notifications -📄 Analysis report saved to: {path} -📊 Metrics updated: {path} -📋 Summary saved to: {path} -💾 Checkpoint created: {path} -📚 Documentation created: {path} -📁 Created directory: {path} -✅ {operation} completed successfully -❌ {operation} failed: {reason} -⚠ {operation} completed w/ warnings +Collaborative Mode: +```yaml +Flow: Agents work together +Use: Complex problems +Example: System design session +``` ## Best Practices -**Agent Management:** -- Define clear, specific task objectives -- Provide comprehensive context and constraints -- Establish measurable success criteria -- Plan integration points and dependencies -- Monitor progress and provide feedback +Task Definition: +- Clear objectives +- Specific deliverables +- Success criteria +- Resource limits +- Time constraints -**Quality Assurance:** -- Validate agent output before integration -- Test agent deliverables thoroughly -- Review code quality and standards compliance -- Verify documentation completeness -- Assess performance and security implications +Agent Selection: +- Match expertise to task +- Consider dependencies +- Plan coordination +- Set boundaries +- Define handoffs -**Coordination:** -- Avoid task overlap and conflicts -- Manage dependencies and prerequisites -- Maintain clear communication channels -- Handle scope changes and adjustments -- Ensure knowledge transfer and documentation +Coordination: +- Clear communication +- Shared context +- Progress tracking +- Result integration +- Quality control -## Troubleshooting -- **Complex Tasks**: Use `--think-hard` for comprehensive planning -- **Integration Issues**: Apply `--review --validate` for quality control -- **Parallel Execution**: Use `--parallel --coordinate` for workflow management -- **Quality Concerns**: Combine `--qa --test --document` for thorough validation +## Examples -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +```bash +# Research then implement +/spawn --agent researcher "OAuth 2.0 best practices" +/spawn --agent builder "Implement OAuth based on research" + +# Parallel feature development +/spawn --mode parallel --agent builder "User auth, Profile API, Settings UI" + +# Full cycle with review +/spawn --mode sequential "Research → Build → Review payment integration" + +# Collaborative system design +/spawn --mode collaborative --ultrathink "Design microservices architecture" +``` + +## Integration + +Works with: +- All command flags pass through +- Inherits persona preferences +- Shares project context +- Accumulates findings +- Coordinates outputs + +## Deliverables + +- Agent execution logs +- Task completion reports +- Integrated results +- Performance metrics +- Lessons learned +- Handoff documentation \ No newline at end of file diff --git a/.claude/commands/task.md b/.claude/commands/task.md index 5265a9f..3785fba 100644 --- a/.claude/commands/task.md +++ b/.claude/commands/task.md @@ -1,38 +1,7 @@ # /task - Manage complex features and requirements ## Legend -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose Manage complex features and requirements across sessions with automatic breakdown, context preservation, and recovery capabilities. @@ -40,271 +9,135 @@ Manage complex features and requirements across sessions with automatic breakdow ## Syntax `/task [operation] [parameters]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always -## Command-Specific Operations +## Operations -**Task Operations:** -- `create `: Create new task with automatic breakdown -- `list`: Show tasks filtered by status or priority -- `start <id>`: Begin working on specific task -- `pause <id>`: Pause current work and save context -- `resume <id>`: Resume previously paused task -- `complete <id>`: Mark task as completed with verification -- `cancel <id>`: Cancel task and clean up resources -- `show <id>`: Display detailed task information -- `update <id>`: Modify task status, priority, or details +/task:create [description]: +- Create new task with automatic breakdown +- Generate subtasks & milestones +- Set up tracking structure +- Initialize context preservation -**Task Types:** -- `--type feature`: New feature development -- `--type bugfix`: Bug resolution and fixes -- `--type refactor`: Code refactoring and improvement -- `--type docs`: Documentation creation or updates -- `--type test`: Testing implementation or enhancement +/task:update [task-id] [updates]: +- Update task progress +- Modify requirements +- Adjust timeline +- Add discoveries -**Priority Levels:** -- `--priority high`: Critical or urgent tasks -- `--priority medium`: Standard priority tasks (default) -- `--priority low`: Nice-to-have or future enhancements +/task:status [task-id]: +- Show current progress +- List completed subtasks +- Display blockers +- Estimate remaining work -**Status Filters:** -- `--status pending`: Tasks waiting to be started -- `--status in-progress`: Currently active tasks -- `--status completed`: Finished tasks -- `--status cancelled`: Cancelled or abandoned tasks +/task:resume [task-id]: +- Load task context +- Continue from last point +- Restore working state +- Update progress -## Examples -- `/task create "User authentication system" --type feature --priority high` -- `/task list --status pending --priority high` -- `/task start 20250623-143052` -- `/task pause 20250623-143052` -- `/task resume 20250623-143052` -- `/task complete 20250623-143052` -- `/task show 20250623-143052` -- `/task update 20250623-143052 --priority low` +/task:complete [task-id]: +- Mark task as done +- Generate summary +- Archive artifacts +- Create documentation -## Task Workflow +## Task Structure -**Task Creation:** -1. **Requirement Analysis**: Analyze complexity and scope -2. **ID Generation**: Create unique task ID (YYYYMMDD-HHMMSS) -3. **Breakdown**: Decompose into phases and actionable steps -4. **File Creation**: Generate task file from appropriate template -5. **Git Integration**: Create dedicated branch for task -6. **Organization**: Move to pending folder for tracking +@include shared/task-patterns.yml#Task_Structure -**Task Execution:** -1. **Activation**: Move task to in-progress folder -2. **Checkpoint**: Create git checkpoint for safety -3. **Sequential Execution**: Work through steps systematically -4. **Progress Tracking**: Update progress and context continuously -5. **Session Management**: Handle interruptions and breaks gracefully +Task Components: +- Title & description +- Acceptance criteria +- Technical requirements +- Subtask breakdown +- Progress tracking +- Context preservation -**Task Completion:** -1. **Verification**: Ensure all steps completed successfully -2. **Testing**: Run comprehensive tests and validation -3. **Checkpoint**: Create completion checkpoint -4. **Organization**: Move to completed folder -5. **Integration**: Merge git branch and clean up +## Automatic Features -## Auto-Detection +Smart Breakdown: +- Analyze complexity +- Create subtasks +- Identify dependencies +- Estimate effort +- Set milestones -**Complexity Triggers:** -- "build feature X" or "implement functionality Y" -- "add component Z" or "create system W" -- Requirements affecting more than 3 files -- Multi-step work requiring coordination -- Complex integration or architectural changes +Context Preservation: +- Save working state +- Track decisions +- Store code changes +- Maintain history +- Enable recovery -**System Response:** -- Analyze request complexity automatically -- Suggest task creation for complex work -- Provide options: [Create task breakdown] [Proceed directly] -- Explain benefits of task management approach -- Respect user preference for simple tasks +Progress Tracking: +- Update automatically +- Track blockers +- Monitor velocity +- Adjust estimates +- Report status -## Session Recovery +## Recovery System -**Startup Process:** -1. **Scan**: Check `.claudedocs/tasks/in-progress/` directory -2. **Identify**: Find active tasks and their current state -3. **Restore**: Load context from task files and git history -4. **Suggest**: Recommend next steps for resumption +@include shared/session-recovery.yml#Recovery_Patterns -**Context Preservation:** -- Key architectural decisions and rationale -- Current implementation state and progress -- Known blockers and proposed solutions -- File modification history and dependencies -- Integration points and testing requirements - -## Task File Structure - -**Directory Organization:** -``` -.claudedocs/tasks/ -├── pending/ # Tasks waiting to be started -├── in-progress/ # Currently active tasks -├── completed/ # Finished tasks -├── cancelled/ # Cancelled or abandoned tasks -└── templates/ # Task templates by type -``` - -**File Naming Convention:** -``` -{type}-{id}-{slug}.md - -Examples: -feature-20250623-143052-user-auth.md -bugfix-20250623-144022-login-error.md -refactor-20250623-142033-api-cleanup.md -``` - -**Task File Content:** -- Task metadata (ID, type, priority, status) -- Detailed description and requirements -- Phase breakdown with progress tracking -- Context and architectural decisions -- Blockers and resolution strategies -- Testing and validation requirements - -## Integration Capabilities - -**Git Integration:** -- Automatic branch creation and management -- Checkpoint creation for safety and rollback -- Merge strategy and conflict resolution -- Commit message generation and conventions - -**TodoWrite Synchronization:** -- Sync with existing todo system -- Convert todos to tasks when appropriate -- Maintain consistency across systems -- Provide unified task management experience - -**Persona Activation:** -- Task-specific persona selection -- Specialized expertise for different task types -- Context-aware skill application -- Collaborative persona workflows - -**MCP Integration:** -- Context preservation across MCP tools -- State management for complex operations -- Tool coordination for task execution -- Resource optimization and sharing - -**Command Chaining:** -- Chain with other SuperClaude commands -- Workflow automation and optimization -- Cross-command context sharing -- Integrated development experience - -## Advanced Features - -**Task Dependencies:** -- Define prerequisite relationships -- Automatic dependency resolution -- Blocked task identification -- Parallel execution planning - -**Progress Tracking:** -- Phase-based progress measurement -- Milestone tracking and reporting -- Time estimation and actual tracking -- Velocity and performance metrics - -**Collaboration Support:** -- Multi-contributor task support -- Handoff procedures and documentation -- Knowledge transfer mechanisms -- Team coordination features - -## Deliverables -- **Task Files**: Comprehensive task documentation with progress tracking -- **Git Branches**: Dedicated branches with checkpoint history -- **Progress Reports**: Regular status updates and metrics -- **Context Documentation**: Preserved decision-making rationale -- **Integration Plans**: Merge and deployment strategies - -## Research Requirements -External_Library_Research: - - Identify library/framework mentioned - - Context7 lookup for official documentation - - Verify API patterns and examples - - Check version compatibility - - Document findings in implementation -Pattern_Research: - - Search existing codebase for similar patterns - - Magic component search if UI-related - - WebSearch for official documentation - - Validate approach with Sequential thinking - - Document pattern choice rationale -API_Integration_Research: - - Official documentation lookup - - Authentication requirements - - Rate limiting and error handling - - SDK availability and examples - - Integration testing approach - -## Report Notifications -📄 Analysis report saved to: {path} -📊 Metrics updated: {path} -📋 Summary saved to: {path} -💾 Checkpoint created: {path} -📚 Documentation created: {path} -📁 Created directory: {path} -✅ {operation} completed successfully -❌ {operation} failed: {reason} -⚠ {operation} completed w/ warnings +Session Recovery: +- Auto-detect incomplete tasks +- Load previous context +- Resume from checkpoint +- Maintain continuity +- Preserve momentum ## Best Practices -**Task Creation:** -- Define clear, specific objectives -- Break down complex work into manageable phases -- Set realistic timelines and expectations -- Include comprehensive context and requirements -- Plan for testing and validation +Task Creation: +- Clear requirements +- Measurable outcomes +- Realistic scope +- Defined boundaries +- Success criteria -**Execution Management:** -- Update progress regularly and consistently -- Document decisions and changes promptly -- Handle blockers and dependencies proactively -- Maintain clean git history and commits -- Communicate status changes effectively +Task Management: +- Regular updates +- Track blockers early +- Document decisions +- Test incrementally +- Communicate progress -**Quality Assurance:** -- Verify completion criteria before marking done -- Run comprehensive tests and validation -- Review code quality and standards compliance -- Update documentation and knowledge base -- Plan for maintenance and future enhancements +## Examples -## Troubleshooting -- **Complex Tasks**: Use automatic breakdown with phase management -- **Session Interruptions**: Leverage auto-save and context preservation -- **Integration Issues**: Apply git checkpoints and rollback capabilities -- **Progress Tracking**: Use detailed phase and milestone tracking +```bash +# Create complex feature task +/task:create "Implement OAuth 2.0 authentication system" -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +# Check task status +/task:status oauth-task-id + +# Resume work after break +/task:resume oauth-task-id + +# Update with discoveries +/task:update oauth-task-id "Found library conflict, switching approach" + +# Complete with summary +/task:complete oauth-task-id +``` + +## Integration + +Works with: +- TodoWrite for subtasks +- Git for version control +- Test for validation +- Document for artifacts +- All development commands + +## Deliverables + +- Task breakdown document +- Progress tracking reports +- Technical decisions log +- Implementation artifacts +- Completion summary +- Lessons learned \ No newline at end of file diff --git a/.claude/commands/test.md b/.claude/commands/test.md index dc33010..c55b38d 100644 --- a/.claude/commands/test.md +++ b/.claude/commands/test.md @@ -1,38 +1,6 @@ # /test - Create and run comprehensive tests -## Legend -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose Create or run comprehensive test suites for code specified in $ARGUMENTS using modern testing frameworks and methodologies. @@ -40,287 +8,72 @@ Create or run comprehensive test suites for code specified in $ARGUMENTS using m ## Syntax `/test [flags] [target]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always + +Examples: +- `/test --tdd` - Test-driven development workflow +- `/test --coverage` - Generate coverage report +- `/test --watch` - Continuous test mode +- `/test --integration` - Run integration tests +- `/test --e2e` - Run end-to-end tests ## Command-Specific Flags +--tdd: "Test-driven development workflow (write failing test→implement→pass)" +--coverage: "Generate detailed coverage reports w/ uncovered lines" +--integration: "Run integration tests across components/services" +--e2e: "Run end-to-end tests w/ real browser/environment" +--unit: "Focus on unit tests only (default)" +--mutation: "Run mutation testing to verify test quality" +--snapshot: "Update/verify snapshot tests" +--watch: "Run tests continuously on file changes" +--bail: "Stop on first test failure" +--parallel: "Run tests in parallel workers" +--update-snapshots: "Update all snapshot tests" -**Test Types:** -- `--unit`: Unit tests for individual functions and components -- `--integration`: Integration tests for APIs, services, and database interactions -- `--e2e`: End-to-end tests for complete user workflows -- `--performance`: Performance and load testing -- `--security`: Security testing and vulnerability assessment +## Testing Approaches -**Test Execution:** -- `--coverage`: Generate comprehensive code coverage reports -- `--watch`: Continuous test execution on file changes -- `--interactive`: Interactive test runner with real-time feedback -- `--parallel`: Run tests in parallel for faster execution -- `--isolated`: Run tests in isolated environments +**Unit Testing:** Isolated component/function tests | Mock all dependencies | Fast execution | High coverage target -**Testing Tools:** -- `--pup`: Browser-based E2E testing with Puppeteer automation -- `--c7`: Testing framework documentation and best practices -- `--seq`: Complex test scenario planning and analysis +**Integration Testing:** Component interaction tests | Real service calls | Database transactions | API endpoint tests -**Quality Control:** -- `--strict`: Strict testing mode with enhanced validation -- `--threshold [percent]`: Set minimum coverage threshold (default 80%) -- `--fail-fast`: Stop on first test failure -- `--retry [count]`: Retry failed tests specified number of times +**E2E Testing:** Full user workflows | Browser automation | Real environment | Critical path coverage -## Examples -- `/test --unit --coverage --watch` → Unit tests with coverage and live updates -- `/test --e2e --pup --think` → E2E tests with Puppeteer and analysis -- `/test --integration --c7 --parallel` → Integration tests with docs and parallel execution -- `/test --performance --threshold 90 --seq` → Performance testing with high coverage threshold -- `/test --security --strict --interactive` → Security testing with strict validation +**TDD Workflow:** Red→Green→Refactor cycle | Write minimal code | Comprehensive coverage | Design emergence -## Test Types and Implementation +## Testing Patterns -**Unit Tests:** -- Test individual functions, methods, and components in isolation -- Mock external dependencies and services -- Focus on business logic and edge cases -- Ensure fast execution and high reliability -- Cover both happy paths and error conditions +**Test Structure:** Arrange-Act-Assert (AAA) | Given-When-Then (BDD) | Setup→Execute→Verify→Teardown -**Integration Tests:** -- Test interactions between components and services -- Verify API contracts and data flow -- Test database operations and transactions -- Validate external service integrations -- Check error handling and recovery mechanisms +**Coverage Targets:** Statements: 80%+ | Branches: 75%+ | Functions: 90%+ | Lines: 80%+ -**End-to-End Tests:** -- Test complete user workflows and journeys -- Verify critical business paths through application -- Include both success and failure scenarios -- Test across different browsers and devices -- Validate user interface interactions and responses +**Test Organization:** +- `__tests__/` or `test/` directories +- `*.test.{js,ts}` or `*.spec.{js,ts}` naming +- Mirror source structure in test directories +- Group by feature or component -**Performance Tests:** -- Load testing with realistic user scenarios -- Stress testing to identify breaking points -- Spike testing for traffic surge handling -- Volume testing with large datasets -- Endurance testing for long-running operations +@include shared/quality-patterns.yml#Test_Quality_Standards -**Security Tests:** -- Vulnerability scanning and penetration testing -- Authentication and authorization testing -- Input validation and injection attack prevention -- Data encryption and privacy protection -- Session management and access control verification +## Framework Support -## Pre-Test Setup and Cleanup +**JavaScript/TypeScript:** Jest (default) | Mocha + Chai | Vitest | Testing Library -**Environment Preparation:** -- Clean test output directories (coverage/, test-results/) -- Remove artifacts from previous test runs -- Reset test databases to clean baseline state -- Clear test cache and temporary files -- Initialize test data and fixtures +**Python:** pytest (default) | unittest | nose2 | doctest -**Dependency Management:** -- Install and update testing dependencies -- Configure test environments and settings -- Set up mock services and test doubles -- Prepare test databases and seed data -- Configure network and security settings +**Go:** Built-in testing | Testify | Ginkgo/Gomega -## Coverage Analysis (--coverage) +**Java:** JUnit 5 | TestNG | Mockito | Spring Test -**Coverage Metrics:** -- Line coverage: Percentage of executed code lines -- Branch coverage: Percentage of executed conditional branches -- Function coverage: Percentage of called functions -- Statement coverage: Percentage of executed statements -- Path coverage: Percentage of executed code paths - -**Coverage Goals:** -- Aim for >80% overall code coverage -- Focus on critical business logic coverage -- Identify untested code paths and edge cases -- Track coverage trends and improvements -- Generate actionable coverage reports - -**Coverage Reports:** -- HTML reports with detailed line-by-line analysis -- JSON reports for programmatic consumption -- XML reports for CI/CD integration -- Summary reports with key metrics -- Trend analysis and historical comparison - -## Watch Mode (--watch) - -**Continuous Testing:** -- Automatic test execution on file changes -- Smart test selection based on changed files -- Fast feedback loop during development -- Real-time coverage updates -- Efficient resource utilization - -**Change Detection:** -- Monitor source code files for modifications -- Track test file changes and updates -- Detect configuration and dependency changes -- Handle file system events efficiently -- Provide clear change notifications - -## Interactive Mode (--interactive) - -**Interactive Features:** -- Test selection and filtering capabilities -- Real-time test execution and results -- Step-through debugging for failing tests -- Live code coverage visualization -- Dynamic test configuration and options - -**User Experience:** -- Clear and intuitive command interface -- Rich output formatting and highlighting -- Progress indicators and status updates -- Error highlighting and debugging aids -- Keyboard shortcuts and navigation - -## Testing Best Practices - -**Test Structure and Organization:** -- Use descriptive test names explaining what is being tested -- Follow AAA pattern: Arrange, Act, Assert -- Group related tests in logical test suites -- Maintain consistent test file organization -- Use clear and readable test code - -**Test Independence:** -- Ensure tests can run in any order -- Avoid dependencies between tests -- Clean up test state after each test -- Use fresh test data for each test -- Mock external dependencies appropriately - -**Test Data Management:** -- Create reusable test fixtures and factories -- Use meaningful test data that reflects real scenarios -- Maintain test data separately from production data -- Implement data seeding and cleanup procedures -- Version control test data and schemas - -**Mocking and Test Doubles:** -- Mock external services and APIs -- Use test doubles for database interactions -- Stub complex dependencies and integrations -- Verify mock interactions and expectations -- Balance mocking with integration testing - -## Test Framework Integration - -**Supported Frameworks:** -- **Jest**: Modern JavaScript testing framework -- **Mocha/Chai**: Flexible Node.js testing suite -- **Pytest**: Python testing framework -- **JUnit**: Java testing framework -- **RSpec**: Ruby testing framework - -**CI/CD Integration:** -- Automated test execution in pipelines -- Test result reporting and notifications -- Coverage threshold enforcement -- Parallel test execution for speed -- Test artifact collection and storage +**Other:** Framework-specific best practices | Native test runners ## Deliverables -- **Test Suites**: Comprehensive test coverage for all specified areas -- **Coverage Reports**: Detailed code coverage analysis and metrics -- **Test Documentation**: Test plans, strategies, and maintenance guides -- **CI/CD Integration**: Automated testing pipeline configuration -- **Performance Baselines**: Performance test results and benchmarks -## Output Locations -- **Coverage Reports**: `coverage/` directory with HTML, JSON, and XML reports -- **Test Results**: `test-results/` directory with detailed test outcomes -- **Performance Reports**: `.claudedocs/metrics/performance-test-{timestamp}.md` -- **Test Documentation**: `.claudedocs/reports/test-strategy-{timestamp}.md` +**Test Files:** Created in appropriate test directories | Following naming conventions | Comprehensive test cases -## Research Requirements -External_Library_Research: - - Identify library/framework mentioned - - Context7 lookup for official documentation - - Verify API patterns and examples - - Check version compatibility - - Document findings in implementation -Pattern_Research: - - Search existing codebase for similar patterns - - Magic component search if UI-related - - WebSearch for official documentation - - Validate approach with Sequential thinking - - Document pattern choice rationale -API_Integration_Research: - - Official documentation lookup - - Authentication requirements - - Rate limiting and error handling - - SDK availability and examples - - Integration testing approach +**Coverage Reports:** HTML report in `coverage/` | Console summary | Uncovered line identification -## Report Notifications -📄 Analysis report saved to: {path} -📊 Metrics updated: {path} -📋 Summary saved to: {path} -💾 Checkpoint created: {path} -📚 Documentation created: {path} -📁 Created directory: {path} -✅ {operation} completed successfully -❌ {operation} failed: {reason} -⚠ {operation} completed w/ warnings +**CI Configuration:** GitHub Actions | CircleCI | Jenkins | GitLab CI -## Quality Assurance Standards +**Documentation:** Test plan | Test cases | Coverage goals | CI/CD integration -**Test Quality:** -- Tests should be reliable and deterministic -- Avoid flaky tests that pass/fail inconsistently -- Maintain high test code quality standards -- Regular test review and refactoring -- Continuous improvement of test effectiveness - -**Coverage Standards:** -- Minimum 80% code coverage for new code -- 100% coverage for critical business logic -- Track and improve coverage over time -- Focus on meaningful coverage, not just metrics -- Regular coverage analysis and reporting - -**Performance Standards:** -- Unit tests should execute in milliseconds -- Integration tests should complete within seconds -- E2E tests should finish within reasonable timeframes -- Parallel execution for improved speed -- Regular performance optimization and monitoring - -## Troubleshooting -- **Slow Tests**: Use `--parallel` and optimize test performance -- **Flaky E2E Tests**: Apply `--retry` and improve test stability -- **Low Coverage**: Use `--coverage --interactive` for targeted improvement -- **Complex Scenarios**: Combine `--seq --think-hard` for comprehensive planning - -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +@include shared/universal-constants.yml#Success_Messages \ No newline at end of file diff --git a/.claude/commands/troubleshoot.md b/.claude/commands/troubleshoot.md index 73db7fd..e2ef7e1 100644 --- a/.claude/commands/troubleshoot.md +++ b/.claude/commands/troubleshoot.md @@ -1,328 +1,58 @@ # /troubleshoot - Debug and resolve issues systematically -## Legend -| Symbol | Meaning | | Abbrev | Meaning | -|--------|---------|---|--------|---------| -| → | leads to | | cfg | configuration | -| & | and/with | | impl | implementation | -| w/ | with | | perf | performance | -| @ | at/located | | ops | operations | -| > | greater than | | val | validation | -| ∀ | for all/every | | req | requirements | -| ∃ | exists/there is | | deps | dependencies | -| ∴ | therefore | | env | environment | -| ∵ | because | | db | database | -| ≡ | equivalent | | api | interface | -| ≈ | approximately | | docs | documentation | -| 📁 | directory/path | | std | standard | -| 🔢 | number/count | | def | default | -| 📝 | text/string | | ctx | context | -| ⚙ | setting/config | | err | error | -| 🎛 | control/flags | | exec | execution | -| 🔧 | configuration | | qual | quality | -| 📋 | group/category | | rec | recovery | -| 🚨 | critical/urgent | | sev | severity | -| ⚠ | warning/caution | | resp | response | -| 🔄 | retry/recovery | | esc | escalation | -| ✅ | success/fixed | | tok | token | -| ❌ | failure/error | | opt | optimization | -| ℹ | information | | UX | user experience | -| ⚡ | fast/quick | | UI | user interface | -| 🐌 | slow/delayed | | C | critical | -| ✨ | complete/done | | H | high | -| 📖 | read operation | | M | medium | -| ✏ | edit operation | | L | low | -| 🗑 | delete operation | | | +@include shared/universal-constants.yml#Universal_Legend ## Purpose -Debug and resolve issues in code or systems specified in $ARGUMENTS using systematic troubleshooting methodologies and analysis techniques. +Systematically debug and resolve issues in $ARGUMENTS using root cause analysis and evidence-based solutions. ## Syntax `/troubleshoot [flags] [issue-description]` -## Universal Flags ---plan: "Show execution plan before running" ---uc: "UltraCompressed mode (~70% token reduction)" ---ultracompressed: "Alias for --uc" ---think: "Multi-file analysis w/ context (4K tokens)" ---think-hard: "Deep architectural analysis (10K tokens)" ---ultrathink: "Critical system redesign (32K tokens)" ---c7: "Enable Context7→library documentation lookup" ---seq: "Enable Sequential→complex analysis & thinking" ---magic: "Enable Magic→UI component generation" ---pup: "Enable Puppeteer→browser automation & testing" ---all-mcp: "Enable all MCP servers" ---no-mcp: "Disable all MCP servers (native tools only)" ---no-c7: "Disable Context7 specifically" ---no-seq: "Disable Sequential thinking specifically" ---no-magic: "Disable Magic UI builder specifically" ---no-pup: "Disable Puppeteer specifically" +@include shared/flag-inheritance.yml#Universal_Always + +Examples: +- `/troubleshoot "app crashes on startup"` - Debug crash +- `/troubleshoot --performance "slow API"` - Performance issues +- `/troubleshoot --interactive "login fails"` - Guided debugging ## Command-Specific Flags +--performance: "Focus on performance bottlenecks" +--memory: "Memory leak detection and analysis" +--network: "Network-related debugging" +--interactive: "Step-by-step guided troubleshooting" +--trace: "Enable detailed execution tracing" +--bisect: "Git bisect to find breaking commit" -**Troubleshooting Modes:** -- `--investigate`: Focus on understanding and analyzing issues without immediate fixes -- `--fix`: Complete bug-fixing workflow with testing and verification (default) -- `--analyze`: Deep technical analysis of complex system interactions -- `--diagnose`: Systematic diagnostic approach with structured methodology +## Troubleshooting Approach -**Analysis Methods:** -- `--five-whys`: Apply root cause analysis methodology iteratively -- `--binary-search`: Use binary search approach to isolate problem scope -- `--timeline`: Analyze issue timeline and recent changes -- `--dependencies`: Focus on dependency and integration issues +**1. Reproduce:** Isolate minimal reproduction | Document steps | Verify consistency | Capture full context -**Environment Focus:** -- `--prod`: Production-specific issue handling with minimal disruption -- `--staging`: Staging environment debugging and testing -- `--local`: Local development environment troubleshooting -- `--cross-env`: Cross-environment consistency analysis +**2. Gather Evidence:** Error messages & stack traces | Logs & metrics | System state | Recent changes | Environment differences -**Investigation Tools:** -- `--logs`: Focus on log analysis and pattern detection -- `--performance`: Performance profiling and bottleneck analysis -- `--security`: Security-focused investigation and vulnerability analysis -- `--network`: Network connectivity and API integration debugging +**3. Form Hypotheses:** Most likely causes | Alternative explanations | Test predictions | Rule out possibilities -## Examples -- `/troubleshoot --investigate --logs --think` → Log analysis with context -- `/troubleshoot --five-whys --prod --think-hard` → Production root cause analysis -- `/troubleshoot --fix --performance --ultrathink` → Performance issue resolution -- `/troubleshoot --binary-search --dependencies` → Systematic dependency debugging -- `/troubleshoot --analyze --security --network` → Security and network analysis +**4. Test & Verify:** Targeted experiments | Change one variable | Document results | Confirm root cause -## Troubleshooting Workflow +**5. Fix & Prevent:** Implement solution | Add tests | Document fix | Prevent recurrence -**1. Issue Reproduction and Understanding** -- **Minimal Reproduction**: Create smallest possible reproduction case -- **Behavior Documentation**: Document expected vs actual behavior clearly -- **Impact Assessment**: Identify affected components, users, and business impact -- **Severity Classification**: Determine urgency and priority level -- **Environment Analysis**: Understand where and when the issue occurs +## Common Issue Categories -**2. Investigation and Isolation** -- **Tool Utilization**: Apply debugging tools and strategic logging -- **Scope Narrowing**: Use binary search to isolate problem area -- **Change Analysis**: Review recent changes using git history and blame -- **Data Collection**: Analyze logs, stack traces, and monitoring data -- **Factor Elimination**: Rule out environmental and configuration factors +**Performance:** Slow queries | Memory leaks | CPU bottlenecks | Network latency | Inefficient algorithms -**3. Root Cause Analysis** -- **Underlying Causes**: Look beyond symptoms to find root causes -- **Five-Whys Method**: Apply iterative questioning technique -- **Systemic Analysis**: Consider broader system and process issues -- **Contributing Factors**: Document all factors that led to the issue -- **Pattern Recognition**: Identify similar issues and common causes +**Crashes/Errors:** Null references | Type mismatches | Race conditions | Memory corruption | Stack overflow -**4. Solution Development (--fix mode)** -- **Test Creation**: Write failing test that reproduces the issue -- **Minimal Fix**: Implement focused solution addressing root cause -- **Compatibility**: Ensure backward compatibility and minimal disruption -- **Edge Cases**: Consider side effects and edge case scenarios -- **Code Review**: Apply standard code review and quality practices +**Integration:** API failures | Authentication issues | Version conflicts | Configuration problems | Network timeouts -**5. Verification and Prevention** -- **Fix Validation**: Verify solution resolves issue completely -- **Regression Testing**: Run full test suite to prevent regressions -- **Realistic Testing**: Test in production-like conditions -- **Monitoring**: Add monitoring and alerting for early detection -- **Documentation**: Record lessons learned and prevention measures +**Data Issues:** Corruption | Inconsistency | Migration failures | Encoding problems | Concurrency conflicts -## Investigation Techniques - -**Debugging Approaches:** -- **Strategic Logging**: Add targeted logging at key decision points -- **Breakpoint Analysis**: Use debugger breakpoints for step-through analysis -- **State Inspection**: Examine variable states and data structures -- **Call Stack Analysis**: Trace execution paths and function calls -- **Memory Debugging**: Analyze memory usage and potential leaks - -**Performance Analysis:** -- **Profiling Tools**: Use performance profilers for bottleneck identification -- **Resource Monitoring**: Track CPU, memory, and I/O usage patterns -- **Query Analysis**: Analyze database queries and execution plans -- **Network Inspection**: Monitor network requests and response times -- **Caching Evaluation**: Assess caching effectiveness and hit rates - -**System Analysis:** -- **Configuration Review**: Examine system and application configurations -- **Dependency Mapping**: Map and analyze component dependencies -- **Integration Testing**: Test inter-service communication and APIs -- **Infrastructure Analysis**: Review infrastructure and deployment setup -- **Security Assessment**: Analyze security configurations and access controls - -## Five-Whys Analysis (--five-whys) - -**Methodology:** -1. **Problem Statement**: Clearly define the observed problem -2. **First Why**: Why did this problem occur? (immediate cause) -3. **Second Why**: Why did that cause occur? (deeper cause) -4. **Third Why**: Why did that deeper cause occur? (root cause) -5. **Fourth Why**: Why does that root cause exist? (systemic cause) -6. **Fifth Why**: Why is that system in place? (organizational cause) - -**Documentation:** -- Record each level of analysis with evidence -- Document contributing factors at each level -- Identify prevention measures for each cause -- Propose systemic improvements to prevent recurrence -- Create action items for short-term and long-term fixes - -## Production Issue Handling (--prod) - -**Production-Specific Considerations:** -- **Minimal Disruption**: Prioritize system stability and user experience -- **Rollback Readiness**: Prepare immediate rollback options -- **Monitoring Integration**: Use existing monitoring and alerting systems -- **Communication**: Maintain stakeholder communication throughout -- **Documentation**: Record all changes and decisions for audit trail - -**Production Analysis:** -- **Deployment Correlation**: Correlate issues with recent deployments -- **Traffic Patterns**: Analyze user traffic and usage patterns -- **Configuration Changes**: Review recent configuration modifications -- **Resource Utilization**: Monitor system resource usage and limits -- **Service Dependencies**: Check health of dependent services - -**Safe Production Practices:** -- **Feature Flags**: Use feature toggles to isolate problematic features -- **Gradual Rollout**: Implement fixes gradually with monitoring -- **A/B Testing**: Compare fix effectiveness with control groups -- **Circuit Breakers**: Implement circuit breakers for failing services -- **Health Checks**: Continuous health monitoring during fixes - -## Investigation Tools and Techniques - -**Logging and Monitoring:** -- Centralized log aggregation and analysis -- Real-time monitoring dashboards and alerts -- Distributed tracing for microservices -- Application performance monitoring (APM) -- Custom metrics and business intelligence - -**Debugging Tools:** -- Interactive debuggers and IDE integration -- Remote debugging capabilities -- Memory profilers and leak detectors -- Performance profiling tools -- Network traffic analyzers - -**Testing and Validation:** -- Unit test creation for bug reproduction -- Integration testing for component interactions -- Load testing for performance issues -- Security testing for vulnerability assessment -- Chaos engineering for resilience testing +@include shared/quality-patterns.yml#Root_Cause_Analysis ## Deliverables -- **Investigation Report**: Comprehensive analysis of issue and findings -- **Root Cause Analysis**: Detailed five-whys analysis with evidence -- **Solution Documentation**: Fix implementation with rationale -- **Prevention Plan**: Measures to prevent similar issues -- **Monitoring Enhancements**: Improved detection and alerting -- **Lessons Learned**: Knowledge base updates and team learnings -## Output Locations -- **Incident Reports**: `.claudedocs/incidents/rca-{issue}-{timestamp}.md` -- **Investigation Logs**: `.claudedocs/reports/troubleshoot-{timestamp}.md` -- **Solution Documentation**: `.claudedocs/summaries/fix-{issue}-{timestamp}.md` +**Root Cause Report:** Issue description | Evidence collected | Analysis process | Root cause identified | Fix implemented -## Research Requirements -External_Library_Research: - - Identify library/framework mentioned - - Context7 lookup for official documentation - - Verify API patterns and examples - - Check version compatibility - - Document findings in implementation -Pattern_Research: - - Search existing codebase for similar patterns - - Magic component search if UI-related - - WebSearch for official documentation - - Validate approach with Sequential thinking - - Document pattern choice rationale -API_Integration_Research: - - Official documentation lookup - - Authentication requirements - - Rate limiting and error handling - - SDK availability and examples - - Integration testing approach +**Fix Documentation:** What was broken | Why it broke | How it was fixed | Prevention measures | Test cases added -## Report Notifications -📄 Analysis report saved to: {path} -📊 Metrics updated: {path} -📋 Summary saved to: {path} -💾 Checkpoint created: {path} -📚 Documentation created: {path} -📁 Created directory: {path} -✅ {operation} completed successfully -❌ {operation} failed: {reason} -⚠ {operation} completed w/ warnings +**Knowledge Base:** Problem→Solution mapping | Troubleshooting guides | Common patterns | Prevention checklist -## Best Practices - -**Systematic Approach:** -- Follow structured troubleshooting methodology -- Document findings and decisions throughout process -- Maintain objectivity and avoid assumption-based debugging -- Use data and evidence to drive investigation -- Consider multiple hypotheses before settling on solutions - -**Collaboration and Communication:** -- Involve relevant team members and stakeholders -- Communicate status and findings regularly -- Share knowledge and learnings with team -- Document solutions for future reference -- Conduct post-incident reviews for improvement - -**Prevention Focus:** -- Address root causes, not just symptoms -- Implement monitoring and alerting improvements -- Update processes and procedures based on learnings -- Enhance testing and quality assurance practices -- Build resilience and error handling into systems - -## Common Error Scenarios - -### Database Connection Issues -```bash -/troubleshoot --investigate --dependencies "connection timeout" -# → Checks DB connectivity, credentials, network latency -# → Verifies connection pool settings and timeouts -# → Tests failover mechanisms and retry logic -``` - -### Memory Leaks & Performance -```bash -/troubleshoot --performance --logs --binary-search -# → Profiles memory usage patterns over time -# → Identifies allocation hotspots and retention issues -# → Implements heap dump analysis and GC tuning -``` - -### Production Emergencies -```bash -/troubleshoot --prod --investigate --timeline --critical -# → Creates incident timeline with system events -# → Preserves logs and state for post-mortem analysis -# → Implements safe rollback procedures if needed -``` - -### Integration & API Failures -```bash -/troubleshoot --dependencies --network --cross-env -# → Tests API endpoints and service dependencies -# → Validates authentication and authorization flows -# → Checks rate limiting and circuit breaker status -``` - -## Troubleshooting -- **Complex Issues**: Use `--ultrathink --five-whys` for comprehensive analysis -- **Production Emergencies**: Apply `--prod --investigate --timeline` for safe handling -- **Performance Problems**: Combine `--performance --logs --binary-search` -- **Integration Issues**: Use `--dependencies --network --cross-env` - -## Success Messages -✅ {operation} completed successfully -📝 Created: {file_path} -✏ Updated: {file_path} -✨ Task completed: {task_title} +@include shared/universal-constants.yml#Success_Messages \ No newline at end of file