starter-pack

If you haven't read `.claude/docs/COMMIT_GUIDELINES.md` in this session, read it first.

First-principles debugging for complex issues

Delegate investigation and implementation to agents, keeping main context clean

Maintain documentation currency by analyzing recent changes and updating CLAUDE.md and .claude/docs/ files to reflect new patterns, lessons learned, and evolved practices.

Full workflow orchestration - analyze, implement, test, document, review

Validate technical feasibility before full implementation

If you haven't read `.claude/docs/SPEC_GUIDE.md` in this session, read it first.

Load essential project context (principles, architecture, agents)

Create QA test request documents

Use this agent to understand project structure, patterns, and conventions without loading extensive code into your main context. This agent should be used when you need to understand how the codebase is organized, find patterns across files, or locate implementations. Examples: <example>Context: User asks about implementing a new feature. user: 'I need to add a new payment processing module to my application' assistant: 'Let me use the codebase-analyzer agent to understand your current architecture and identify the best place to add this module.' <commentary>Since we need to understand the overall project structure and existing patterns before implementing, use the codebase-analyzer to explore without polluting main context.</commentary></example> <example>Context: User wants to follow existing patterns. user: 'How are services typically structured in this project?' assistant: 'I'll use the codebase-analyzer agent to identify the service patterns used throughout your codebase.' <commentary>Instead of loading multiple service files into context, the analyzer can identify patterns efficiently.</commentary></example> <example>Context: User needs to find where something is implemented. user: 'Where is the authentication logic handled in this project?' assistant: 'Let me use the codebase-analyzer agent to map out the authentication flow and locate all relevant files.' <commentary>The analyzer can trace through the codebase to find all auth-related code without loading everything.</commentary></example>

Use this agent to explore and understand documentation without loading it all into your context. This agent should be used when you need to understand APIs, libraries, frameworks, or project-specific documentation. Examples: <example>Context: User asks about using a specific library feature. user: 'How do I use the advanced caching features of this Redis client library?' assistant: 'Let me use the docs-explorer agent to research the Redis client library documentation for advanced caching features.' <commentary>Instead of loading entire library docs, the explorer agent can find and summarize relevant sections.</commentary></example> <example>Context: User needs to understand project conventions. user: 'What are the API design guidelines for this project?' assistant: 'I'll use the docs-explorer agent to review your API documentation and design guidelines.' <commentary>The agent can analyze project docs and extract key guidelines without cluttering main context.</commentary></example> <example>Context: User wants to understand configuration options. user: 'What environment variables does this application support?' assistant: 'Let me use the docs-explorer agent to scan the configuration documentation and README files.' <commentary>Documentation agent can comprehensively search all docs for configuration information.</commentary></example>

Use this agent to analyze and update project documentation based on code changes. This agent should be invoked when significant changes are made to architecture, patterns, or workflows. Examples: <example>Context: After implementing a new architectural pattern. user: 'We just added a new event-driven messaging system to the architecture' assistant: 'Let me use the docs-maintainer agent to update our architecture documentation with this new pattern.' <commentary>Since a new architectural pattern was introduced, the docs-maintainer should update relevant documentation.</commentary></example> <example>Context: After discovering and fixing a common bug pattern. user: 'We found that our async error handling was inconsistent across services' assistant: 'I'll use the docs-maintainer agent to document this pattern in our debugging guide.' <commentary>Learning from bugs should be captured in documentation for future reference.</commentary></example> <example>Context: After establishing new conventions. user: 'We decided to use factory patterns for all service instantiation' assistant: 'Let me use the docs-maintainer agent to update our guidelines with this new convention.' <commentary>New conventions should be documented to ensure consistency across the team.</commentary></example>

Use this agent to investigate complex issues, research implementations, or track down root causes while keeping the main context clean. The investigator does deep research but returns only essential findings. Examples: <example>Context: Debugging an intermittent error. user: 'Users are getting random 401 errors but only sometimes' assistant: 'Let me use the investigator agent to track down the root cause of these intermittent 401 errors.' <commentary>The investigator will follow the authentication flow, check token handling, examine race conditions, but return only the root cause and fix.</commentary></example> <example>Context: Researching API usage. user: 'How do we integrate with Stripe for subscription billing?' assistant: 'I'll use the investigator agent to research the Stripe API integration patterns for subscriptions.' <commentary>The investigator will read extensive API docs, check examples, find best practices, but return only the essential implementation approach.</commentary></example> <example>Context: Performance investigation. user: 'The checkout process has become really slow recently' assistant: 'Let me use the investigator agent to find what's causing the checkout performance degradation.' <commentary>The investigator will profile the code, trace database queries, check network calls, but return only the bottleneck and solution.</commentary></example>

Use this agent when you need expert-level technical guidance on complex software engineering challenges. Specifically invoke this agent for: architectural design reviews and planning, debugging complex issues that standard approaches haven't resolved, performance optimization and bottleneck analysis, security vulnerability assessments, database schema design and optimization, API design and REST/GraphQL architecture decisions, code quality reviews for critical systems, refactoring strategy for legacy codebases, technology stack selection and migration planning, or any scenario requiring deep technical expertise beyond routine implementation. Examples: <example>Context: User needs help with a complex performance issue in their application. user: "Our application is experiencing severe performance degradation when processing large datasets. We've tried basic optimizations but need expert guidance." assistant: "I'll use the senior-dev-consultant agent to analyze this performance issue and provide expert recommendations." <commentary>The user is facing a complex performance problem that requires senior-level expertise to diagnose and resolve.</commentary></example> <example>Context: User is planning a major architectural change. user: "We're considering migrating from a monolithic architecture to microservices. What are the key considerations?" assistant: "Let me engage the senior-dev-consultant agent to provide strategic guidance on this architectural transition." <commentary>This is a major architectural decision that requires senior-level expertise to evaluate trade-offs and implementation strategies.</commentary></example> <example>Context: User has a subtle bug that's hard to track down. user: "We have an intermittent race condition in our async code that only happens in production under load." assistant: "I'll use the senior-dev-consultant agent to help diagnose this complex concurrency issue." <commentary>Race conditions and production-only bugs require deep debugging expertise and systematic analysis.</commentary></example> <example>Context: User needs help with database optimization. user: "Our database queries are taking too long and causing timeouts. We need to optimize our schema and query patterns." assistant: "I'll use the senior-dev-consultant agent to analyze your database performance and provide optimization strategies." <commentary>Database optimization requires deep understanding of indexing strategies, query execution plans, and schema design.</commentary></example> <example>Context: User wants to improve their CI/CD pipeline. user: "Our deployment process is slow and error-prone. How can we improve our CI/CD pipeline?" assistant: "Let me use the senior-dev-consultant agent to evaluate your current pipeline and recommend improvements." <commentary>CI/CD optimization requires expertise in build systems, testing strategies, and deployment architectures.</commentary></example>

Use this agent when you need a senior developer to write production-quality code following all best practices. This agent IMPLEMENTS features with DRY/KISS principles, proper error handling, comprehensive testing, and clean architecture. Unlike the consultant who provides advice, this agent writes the actual code. Invoke for: complex feature implementations requiring senior-level quality, large refactoring maintaining functionality, API endpoint implementations with proper validation, database operations with transactions and data integrity, or any scenario requiring production-ready code with built-in quality standards. Examples: <example>Context: User needs a new data processing feature implemented. user: 'I need to implement a feature that processes user analytics data with proper aggregation and filtering' assistant: 'I'll use the senior-dev-implementer agent to build this feature with proper validation, efficient queries, and comprehensive tests.' <commentary>This requires senior-level implementation with data integrity, not just architectural guidance.</commentary></example> <example>Context: User needs to refactor a large module while maintaining functionality. user: 'The payment logic is spread across multiple files and duplicated - it needs proper refactoring' assistant: 'Let me use the senior-dev-implementer agent to refactor this into reusable, well-tested modules.' <commentary>This requires actual code implementation following DRY principles and maintaining test coverage.</commentary></example> <example>Context: User needs a new API endpoint with full validation and security. user: 'Add an endpoint for users to export their transaction history as CSV with date filtering' assistant: 'I'll use the senior-dev-implementer agent to implement this endpoint with input validation, auth checks, and proper error handling.' <commentary>This needs production-quality implementation with security and validation built-in from the start.</commentary></example>

Use this agent to create comprehensive, strategic plans for complex features or major undertakings. This agent should be used at the beginning of significant work to establish clear roadmaps, identify risks, and create actionable task breakdowns. Examples: <example>Context: Starting a major new feature. user: 'We need to build a real-time collaboration system for our application' assistant: 'Let me use the strategic-planner agent to create a comprehensive implementation plan for this feature.' <commentary>Complex features require thorough planning to identify dependencies, risks, and proper implementation sequence.</commentary></example> <example>Context: Major refactoring project. user: 'We need to migrate from REST to GraphQL across our entire API' assistant: 'I'll use the strategic-planner agent to develop a migration strategy with minimal disruption.' <commentary>Large-scale changes need strategic planning to ensure smooth transition and risk mitigation.</commentary></example> <example>Context: Architecture overhaul. user: 'Our monolith is becoming unmanageable, we need to move to microservices' assistant: 'Let me use the strategic-planner agent to create a phased migration plan from monolith to microservices.' <commentary>Architectural changes require careful planning of phases, dependencies, and rollback strategies.</commentary></example>

Use this agent when you need to verify that a development task has been truly completed before marking it as done. Examples: <example>Context: After implementing a new feature, user: 'I've finished implementing the new user authentication system with OAuth2 support' assistant: 'Let me use the task-completion-validator agent to thoroughly verify this implementation meets all requirements and quality standards before marking it complete'</example> <example>Context: After fixing a critical bug, user: 'Fixed the race condition in the async data processing pipeline' assistant: 'I'll use the task-completion-validator agent to ensure this bug fix is complete, doesn't introduce new issues, and properly handles all edge cases'</example> <example>Context: After adding new database migration, user: 'Added the new audit log table and migration scripts' assistant: 'Let me validate this database change with the task-completion-validator agent to ensure the migration is properly structured, applied correctly, and follows best practices'</example>

Use this agent to create focused, meaningful test suites. Use after implementing features when tests are needed.