feat: add ClaudeKit configuration

Add agent definitions, slash commands, hooks, and settings for
Claude Code project tooling.

.claude/commands/spec/validate.md

@@ -0,0 +1,187 @@
+---
+allowed-tools: Task, Read, Grep
+description: Analyzes a specification document to determine if it has enough detail for autonomous implementation
+category: validation
+argument-hint: "<path-to-spec-file>"
+---
+
+# Specification Completeness Check
+
+Analyze the specification at: $ARGUMENTS
+
+## Analysis Framework
+
+This command will analyze the provided specification document to determine if it contains sufficient detail for successful autonomous implementation, while also identifying overengineering and non-essential complexity that should be removed or deferred.
+
+### Domain Expert Consultation
+
+When analyzing specifications that involve specific technical domains:
+- **Use specialized subagents** when analysis involves specific domains (TypeScript, React, testing, databases, etc.)
+- Run `claudekit list agents` to see available specialized experts
+- Match specification domains to expert knowledge for thorough validation
+- Use general-purpose approach only when no specialized expert fits
+
+### What This Check Evaluates:
+
+The analysis evaluates three fundamental aspects, each with specific criteria:
+
+#### 1. **WHY - Intent and Purpose**
+- Background/Problem Statement clarity
+- Goals and Non-Goals definition
+- User value/benefit explanation
+- Justification vs alternatives
+- Success criteria
+
+#### 2. **WHAT - Scope and Requirements**
+- Features and functionality definition
+- Expected deliverables
+- API contracts and interfaces
+- Data models and structures
+- Integration requirements:
+  - External system interactions?
+  - Authentication mechanisms?
+  - Communication protocols?
+- Performance requirements
+- Security requirements
+
+#### 3. **HOW - Implementation Details**
+- Architecture and design patterns
+- Implementation phases/roadmap
+- Technical approach:
+  - Core logic and algorithms
+  - All functions and methods fully specified?
+  - Execution flow clearly defined?
+- Error handling:
+  - All failure modes identified?
+  - Recovery behavior specified?
+  - Edge cases documented?
+- Platform considerations:
+  - Cross-platform compatibility?
+  - Platform-specific implementations?
+  - Required dependencies per platform?
+- Resource management:
+  - Performance constraints defined?
+  - Resource limits specified?
+  - Cleanup procedures documented?
+- Testing strategy:
+  - Test purpose documentation (each test explains why it exists)
+  - Meaningful tests that can fail to reveal real issues
+  - Edge case coverage and failure scenarios
+  - Follows project testing philosophy: "When tests fail, fix the code, not the test"
+- Deployment considerations
+
+### Additional Quality Checks:
+
+**Completeness Assessment**
+- Missing critical sections
+- Unresolved decisions
+- Open questions
+
+**Clarity Assessment**  
+- Ambiguous statements
+- Assumed knowledge
+- Inconsistencies
+
+**Overengineering Assessment**
+- Features not aligned with core user needs
+- Premature optimizations
+- Unnecessary complexity patterns
+
+### Overengineering Detection:
+
+**Core Value Alignment Analysis**
+Evaluate whether features directly serve the core user need:
+- Does this feature solve a real, immediate problem?
+- Is it being used frequently enough to justify complexity?
+- Would a simpler solution work for 80% of use cases?
+
+**YAGNI Principle (You Aren't Gonna Need It)**
+Be aggressive about cutting features:
+- If unsure whether it's needed → Cut it
+- If it's for "future flexibility" → Cut it
+- If only 20% of users need it → Cut it
+- If it adds any complexity → Question it, probably cut it
+
+**Common Overengineering Patterns to Detect:**
+
+1. **Premature Optimization**
+   - Caching for rarely accessed data
+   - Performance optimizations without benchmarks
+   - Complex algorithms for small datasets
+   - Micro-optimizations before profiling
+
+2. **Feature Creep**
+   - "Nice to have" features (cut them)
+   - Edge case handling for unlikely scenarios (cut them)
+   - Multiple ways to do the same thing (keep only one)
+   - Features that "might be useful someday" (definitely cut)
+
+3. **Over-abstraction**
+   - Generic solutions for specific problems
+   - Too many configuration options
+   - Unnecessary plugin/extension systems
+   - Abstract classes with single implementations
+
+4. **Infrastructure Overhead**
+   - Complex build pipelines for simple tools
+   - Multiple deployment environments for internal tools
+   - Extensive monitoring for non-critical features
+   - Database clustering for low-traffic applications
+
+5. **Testing Extremism**
+   - 100% coverage requirements
+   - Testing implementation details
+   - Mocking everything
+   - Edge case tests for prototype features
+
+**Simplification Recommendations:**
+- Identify features to cut from the spec entirely
+- Suggest simpler alternatives
+- Highlight unnecessary complexity
+- Recommend aggressive scope reduction to core essentials
+
+### Output Format:
+
+The analysis will provide:
+- **Summary**: Overall readiness assessment (Ready/Not Ready)
+- **Critical Gaps**: Must-fix issues blocking implementation
+- **Missing Details**: Specific areas needing clarification
+- **Risk Areas**: Potential implementation challenges
+- **Overengineering Analysis**: 
+  - Non-core features that should be removed entirely
+  - Complexity that doesn't align with usage patterns
+  - Suggested simplifications or complete removal
+- **Features to Cut**: Specific items to remove from the spec
+- **Essential Scope**: Absolute minimum needed to solve the core problem
+- **Recommendations**: Next steps to improve the spec
+
+### Example Overengineering Detection:
+
+When analyzing a specification, the validator might identify patterns like:
+
+**Example 1: Unnecessary Caching**
+- Spec includes: "Cache user preferences with Redis"
+- Analysis: User preferences accessed once per session
+- Recommendation: Use in-memory storage or browser localStorage for MVP
+
+**Example 2: Premature Edge Cases**
+- Spec includes: "Handle 10,000+ concurrent connections"
+- Analysis: Expected usage is <100 concurrent users
+- Recommendation: Cut this entirely - let it fail at scale if needed
+
+**Example 3: Over-abstracted Architecture**
+- Spec includes: "Plugin system for custom validators"
+- Analysis: Only 3 validators needed, all known upfront
+- Recommendation: Implement validators directly, no plugin system needed
+
+**Example 4: Excessive Testing Requirements**
+- Spec includes: "100% code coverage with mutation testing"
+- Analysis: Tool used occasionally, not mission-critical
+- Recommendation: Focus on core functionality tests (70% coverage)
+
+**Example 5: Feature Creep**
+- Spec includes: "Support 5 export formats (JSON, CSV, XML, YAML, TOML)"
+- Analysis: 95% of users only need JSON
+- Recommendation: Cut all formats except JSON - YAGNI (You Aren't Gonna Need It)
+
+This comprehensive analysis helps ensure specifications are implementation-ready while keeping scope focused on core user needs, reducing both ambiguity and unnecessary complexity.