@stella-studio/ck 1.0.0

package/README.md

@@ -0,0 +1,602 @@
+# Claude Code Boilerplate
+
+A comprehensive boilerplate template for building professional software projects with **CLI Coding Agents** (**Claude Code** and **Open Code**). This template provides a complete development environment with AI-powered agent orchestration, automated workflows, and intelligent project management.
+
+## What is Claude Code?
+
+**Claude Code** is Anthropic's official CLI tool that brings AI-powered development assistance directly to your terminal. It enables natural language interaction with your codebase and provides intelligent automation for common development tasks.
+
+- [Claude Code](https://claude.com/product/claude-code)
+- [Docs](https://docs.claude.com/en/docs/claude-code/overview)
+
+**Open Code CLI Coding Agents** extend Claude Code with specialized AI agents that handle specific aspects of software development - from planning and research to testing and documentation. This creates a collaborative AI development team that works alongside human developers.
+
+- [Open Code](https://opencode.ai/)
+- [Docs](https://opencode.ai/docs)
+
+## Related Projects & Directories
+
+- `claudekit` - Website of ClaudeKit
+  - Directory: `../claudekit`
+  - Repo: https://github.com/claudekit/claudekit
+- `claudekit-marketing` - Marketing Kit repository
+  - Directory: `../claudekit-marketing`
+  - Repo: https://github.com/claudekit/claudekit-marketing
+- `claudekit-cli` - CLI tool for quick project setup
+  - Directory: `../claudekit-cli`
+  - Repo: https://github.com/mrgoonie/claudekit-cli
+- `claudekit-docs` - Public documentation repository: https://docs.claudekit.cc
+  - Directory: `../claudekit-docs`
+  - Repo: https://github.com/claudekit/claudekit-docs
+
+## Key Benefits
+
+### 🚀 Accelerated Development
+- **AI-Powered Planning**: Automated technical planning and architecture design
+- **Intelligent Code Generation**: Context-aware code creation and modification
+- **Automated Testing**: Comprehensive test generation and execution
+- **Smart Documentation**: Synchronized docs that evolve with your code
+
+### 🎯 Enhanced Quality
+- **Multi-Agent Code Review**: Specialized agents for security, performance, and standards
+- **Automated Quality Assurance**: Continuous testing and validation
+- **Best Practices Enforcement**: Built-in adherence to coding standards
+- **Security-First Development**: Proactive security analysis and recommendations
+
+### 🏗️ Structured Workflow
+- **Agent Orchestration**: Coordinated AI agents working in parallel and sequential workflows
+- **Task Management**: Automated project tracking and progress monitoring
+- **Documentation Sync**: Always up-to-date technical documentation
+- **Clean Git Workflow**: Professional commit messages and branch management
+
+## Documentation
+
+### 📚 Core Documentation
+- **[Project Overview & PDR](./docs/project-overview-pdr.md)** - Comprehensive project overview, goals, features, and product development requirements
+- **[Codebase Summary](./docs/codebase-summary.md)** - High-level overview of project structure, technologies, and components
+- **[Code Standards](./docs/code-standards.md)** - Coding standards, naming conventions, and best practices
+- **[System Architecture](./docs/system-architecture.md)** - Detailed architecture documentation, component interactions, and data flow
+- **[Commands Reference](./guide/COMMANDS.md)** - Complete guide to all available slash commands
+
+### 📖 Additional Resources
+- **[CLAUDE.md](./CLAUDE.md)** - Development instructions and workflows for AI agents
+- **[CHANGELOG.md](./CHANGELOG.md)** - Version history and release notes
+- **[Windows Statusline Support](./docs/statusline-windows-support.md)** - Windows compatibility guide for Claude Code statusline
+- **[Statusline Architecture](./docs/statusline-architecture.md)** - Technical documentation for statusline implementation
+
+## Quick Start
+
+### Prerequisites
+- [Claude Code](https://code.claude.com/docs/en/setup) installed and configured
+- Git for version control
+- Node.js 18+ (or your preferred runtime)
+- Operating Systems: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (with WSL 1, WSL 2, or Git for Windows)
+- Hardware: 4GB+ RAM
+
+### Setup your new project with ClaudeKit
+
+1. **Install ClaudeKit CLI**:
+   ```bash
+   npm install -g claudekit-cli
+   ```
+
+2. **Create your new project with ClaudeKit framework**:
+   ```bash
+   mkdir my-project
+   ck new --dir my-project --kit engineer
+   ```
+
+   **Note:** If you want to use the kit with your existing project:
+   ```bash
+   cd /path/to/project
+   ck init --kit engineer
+   ```
+
+3. **Start development**:
+   ```bash
+   # Begin with Claude Code
+   claude
+   # [YOLO mode - not recommended]
+   # claude --dangerously-skip-permissions
+
+   # now you can use these specific commands
+   /plan "implement user authentication"
+   /cook "add database integration"
+   ```
+
+📖 **Learn more from our docs:** [https://docs.claudekit.cc](https://docs.claudekit.cc)
+
+## Project Structure
+
+```
+├── .claude/                 # Claude Code configuration
+│   ├── agents/             # Claude Code agents
+│   ├── commands/           # Claude Code commands
+│   ├── hooks/              # Claude Code hooks
+│   │   └── notifications/  # Multi-provider notification system
+│   ├── skills/             # Claude Code skills
+│   └── CLAUDE.md           # Global development instructions
+├── docs/                   # Project documentation
+│   ├── codebase-summary.md # Auto-generated codebase overview
+│   ├── code-standards.md   # Development standards
+│   ├── project-overview-pdr.md # Product requirements
+│   └── development-roadmap.md  # Project roadmap
+├── plans/                  # Implementation plans and reports
+│   ├── templates/          # Plan templates
+│   └── reports/            # Agent-to-agent communication
+├── CLAUDE.md              # Project-specific Claude instructions
+├── AGENTS.md              # Agent coordination guidelines
+└── README.md              # This file
+```
+
+## The AI Agent Team
+
+This boilerplate includes 17+ specialized AI agents that work together to deliver high-quality software. Agents coordinate through file-based communication, enabling sequential chaining and parallel execution patterns.
+
+### 🎯 Core Development Agents
+
+#### **Planner Agent**
+- Researches technical approaches and best practices
+- Creates comprehensive implementation plans
+- Analyzes architectural trade-offs
+- Spawns multiple researcher agents for parallel investigation
+
+#### **Researcher Agent**
+- Investigates specific technologies and frameworks
+- Analyzes existing solutions and patterns
+- Provides technical recommendations
+- Supports the planner with detailed findings
+
+#### **Tester Agent**
+- Generates comprehensive test suites
+- Validates functionality and performance
+- Ensures cross-platform compatibility
+- Reports on test coverage and quality metrics
+
+### 🔍 Quality Assurance Agents
+
+#### **Code Reviewer Agent**
+- Performs automated code quality analysis
+- Enforces coding standards and conventions
+- Identifies security vulnerabilities
+- Provides improvement recommendations
+
+#### **Debugger Agent**
+- Analyzes application logs and error reports
+- Diagnoses performance bottlenecks
+- Investigates CI/CD pipeline issues
+- Provides root cause analysis
+
+### 📚 Documentation & Management Agents
+
+#### **Docs Manager Agent**
+- Maintains synchronized technical documentation
+- Updates API documentation automatically
+- Ensures documentation accuracy
+- Manages codebase summaries with repomix
+
+#### **Git Manager Agent**
+- Creates clean, conventional commit messages
+- Manages branching and merge strategies
+- Handles version control workflows
+- Ensures professional git history
+
+#### **Project Manager Agent**
+- Tracks development progress and milestones
+- Updates project roadmaps and timelines
+- Manages task completion verification
+- Maintains project health metrics
+
+### 🎨 Design & Content Agents
+
+#### **UI/UX Designer Agent**
+- Creates design specifications and prototypes
+- Develops visual components
+- Ensures design system consistency
+- Performs user experience analysis
+
+#### **Copywriter Agent**
+- Creates marketing and technical content
+- Optimizes copy for conversion
+- Develops documentation narratives
+- Enhances content clarity
+
+### 🔎 Specialized Agents
+
+#### **Scout Agent**
+- Performs parallel codebase exploration
+- Analyzes code patterns and structure
+- Identifies optimization opportunities
+- Maps component relationships
+
+#### **Database Admin Agent**
+- Manages database operations
+- Performs migrations and optimization
+- Ensures data integrity
+- Designs schema patterns
+
+#### **Journal Writer Agent**
+- Documents development decisions
+- Tracks technical explorations
+- Records lessons learned
+- Maintains decision history
+
+## Agent Orchestration Patterns
+
+### Sequential Chaining
+Use when tasks have dependencies:
+```bash
+# Planning → Implementation → Testing → Review
+/plan "implement user dashboard"
+# Wait for plan completion, then:
+/code  # Executes the plan
+# After implementation:
+/test "validate dashboard functionality"
+# Finally:
+/review "ensure code quality standards"
+
+# Alternative: Use /cook for standalone implementation (plans internally)
+/cook "implement user dashboard"
+```
+
+### Parallel Execution
+Use for independent tasks:
+```bash
+# Multiple researchers exploring different approaches
+planner agent spawns:
+- researcher (database options)
+- researcher (authentication methods)
+- researcher (UI frameworks)
+# All report back to planner simultaneously
+```
+
+### Context Management
+- Agents communicate through file system reports
+- Context is preserved between agent handoffs
+- Fresh context prevents conversation degradation
+- Essential information is documented in markdown
+
+## Development Workflow
+
+### 1. Feature Development
+```bash
+# Start with planning
+/plan "add real-time notifications"
+
+# Research phase (automatic)
+# Multiple researcher agents investigate approaches
+
+# Implementation
+/cook "implement notification system"
+
+# Quality assurance
+/test
+/review
+
+# Documentation update
+/docs
+
+# Project tracking
+/watzup  # Check project status
+```
+
+### 2. Bug Fixing
+```bash
+# Analyze the issue
+/debug "investigate login failures"
+
+# Create fix plan
+/plan "resolve authentication bug"
+
+# Implement solution
+/fix "authentication issue"
+
+# Validate fix
+/test
+```
+
+### 3. Documentation Management
+```bash
+# Update documentation
+/docs
+
+# Generate codebase summary
+repomix  # Creates ./docs/codebase-summary.md
+
+# Review project status
+/watzup
+```
+
+## Configuration Files
+
+### CLAUDE.md
+Project-specific instructions for Claude Code. Customize this file to define:
+- Project architecture guidelines
+- Development standards and conventions
+- Agent coordination protocols
+- Specific workflows for your project
+
+### plans/templates/*.md
+Reusable templates for:
+- Feature implementation plans
+- Bug fix procedures
+- Refactoring strategies
+- Architecture decisions
+
+## Gemini Skills Configuration
+
+This project includes several Gemini-powered skills that require a Google Gemini API key:
+
+- **gemini-audio** - Audio analysis and speech generation
+- **gemini-video-understanding** - Video analysis and understanding
+- **gemini-document-processing** - PDF document processing
+- **gemini-image-gen** - AI image generation
+- **gemini-vision** - Image analysis and vision capabilities
+
+### API Key Setup
+
+The Gemini skills check for `GEMINI_API_KEY` in the following order (priority from highest to lowest):
+
+1. **Environment Variable** (Recommended for development)
+   ```bash
+   export GEMINI_API_KEY='your-api-key-here'
+   ```
+
+2. **Project Root `.env`** (Recommended for project-specific keys)
+   ```bash
+   # Create .env in project root
+   echo 'GEMINI_API_KEY=your-api-key-here' > .env
+   ```
+
+3. **`.claude/.env`** (For Claude-specific configuration)
+   ```bash
+   # Copy example and edit
+   cp .claude/.env.example .claude/.env
+   # Then edit .claude/.env and set your API key
+   ```
+
+4. **`.claude/skills/.env`** (For shared skills configuration)
+   ```bash
+   # Copy example and edit
+   cp .claude/skills/.env.example .claude/skills/.env
+   # Then edit .claude/skills/.env and set your API key
+   ```
+
+5. **Individual Skill Directory `.env`** (For skill-specific keys)
+   ```bash
+   # Example for gemini-audio skill
+   cp .claude/skills/gemini-audio/.env.example .claude/skills/gemini-audio/.env
+   # Then edit and set your API key
+   ```
+
+### Getting Your API Key
+
+Get your free Gemini API key at: https://aistudio.google.com/apikey
+
+### Vertex AI Support
+
+To use Vertex AI instead of Google AI Studio:
+
+```bash
+# Enable Vertex AI
+export GEMINI_USE_VERTEX=true
+export VERTEX_PROJECT_ID=your-gcp-project-id
+export VERTEX_LOCATION=us-central1  # Optional, defaults to us-central1
+```
+
+Or in `.env` file:
+```
+GEMINI_USE_VERTEX=true
+VERTEX_PROJECT_ID=your-gcp-project-id
+VERTEX_LOCATION=us-central1
+```
+
+### Usage Examples
+
+```bash
+# Audio analysis
+claude "Analyze this audio file and summarize the key points: audio.mp3"
+
+# Video understanding
+claude "Describe what happens in this video: video.mp4"
+
+# Document processing
+claude "Extract all tables from this PDF: document.pdf"
+
+# Image generation
+claude "Generate an image of a serene mountain landscape"
+
+# Image analysis
+claude "What objects are in this image: photo.jpg"
+```
+
+## Model Context Protocol (MCP)
+
+✍️ Please read [my technical blog article about MCP here](https://faafospecialist.substack.com/p/claude-code-solution-to-use-mcp-servers).
+
+### Pre-requisites
+
+In ClaudeKit, you need to setup the MCP servers in `.claude/.mcp.json` file.
+
+Copy the example file:
+```bash
+mv .claude/.mcp.json.example .claude/.mcp.json
+```
+
+Then add your MCP servers, below are some examples:
+
+### [Context7](https://github.com/upstash/context7)
+```json
+{
+   "mcpServers": {
+      "context7": {
+         "command": "npx",
+         "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"],
+      }
+   }
+}
+```
+
+### [Human MCP](https://github.com/mrgoonie/human-mcp/)
+
+```json
+{
+   "mcpServers": {
+      "human": {
+         "command": "npx",
+         "args": ["@goonnguyen/human-mcp@latest"],
+         "env": { "GOOGLE_GEMINI_API_KEY": "YOUR_API_KEY" }
+      }
+   }
+}
+```
+
+### [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)
+```json
+{
+   "mcpServers": {
+      "chrome-devtools": {
+         "command": "npx",
+         "args": ["-y", "chrome-devtools-mcp@latest"]
+      }
+   }
+}
+```
+
+## Best Practices
+
+### Development Principles
+- **YAGNI**: You Aren't Gonna Need It - avoid over-engineering
+- **KISS**: Keep It Simple, Stupid - prefer simple solutions
+- **DRY**: Don't Repeat Yourself - eliminate code duplication
+
+### Code Quality
+- All code changes go through automated review
+- Comprehensive testing is mandatory
+- Security considerations are built-in
+- Performance optimization is continuous
+
+### Documentation
+- Documentation evolves with code changes
+- API docs are automatically updated
+- Architecture decisions are recorded
+- Codebase summaries are regularly refreshed
+
+### Git Workflow
+- Clean, conventional commit messages
+- Professional git history
+- No AI attribution in commits
+- Focused, atomic commits
+
+## Usage Examples
+
+### Starting a New Feature
+```bash
+# Research and plan
+claude "I need to implement user authentication with OAuth2"
+# Planner agent creates comprehensive plan
+
+# Follow the plan
+claude "Implement the authentication plan"
+# Implementation follows the detailed plan
+
+# Ensure quality
+claude "Review and test the authentication system"
+# Testing and code review agents validate the implementation
+```
+
+### Debugging Issues
+```bash
+# Investigate problem
+claude "Debug the slow database queries"
+# Debugger agent analyzes logs and performance
+
+# Create solution
+claude "Optimize the identified query performance issues"
+# Implementation follows debugging recommendations
+
+# Validate fix
+claude "Test query performance improvements"
+# Tester agent validates the optimization
+```
+
+### Project Maintenance
+```bash
+# Check project health
+claude "What's the current project status?"
+# Project manager provides comprehensive status
+
+# Update documentation
+claude "Sync documentation with recent changes"
+# Docs manager updates all relevant documentation
+
+# Plan next sprint
+claude "Plan the next development phase"
+# Planner creates detailed roadmap for upcoming work
+```
+
+## Advanced Features
+
+### Multi-Project Support
+- Manage multiple repositories simultaneously
+- Shared agent configurations across projects
+- Consistent development patterns
+
+### Custom Agent Creation
+- Define project-specific agents
+- Extend existing agent capabilities
+- Create domain-specific expertise
+
+### Integration Capabilities
+- **Multi-provider notifications** (Telegram, Discord, Slack) with smart throttling
+- GitHub Actions integration
+- CI/CD pipeline enhancement
+
+See `.claude/hooks/notifications/docs/` for setup guides.
+
+## Customization Guide
+
+### 1. Project Setup
+- Update `CLAUDE.md` with your project specifics
+- Customize plan templates in `plans/templates/`
+
+### 2. Agent Specialization
+- Add domain-specific knowledge to agents
+- Create custom agents for unique requirements
+- Configure agent interaction patterns
+
+### 3. Workflow Optimization
+- Define project-specific commands
+- Create shortcuts for common tasks
+- Establish team coding standards
+
+## Contributing
+
+1. Fork this repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Follow the agent orchestration workflow
+4. Ensure all tests pass and documentation is updated
+5. Create a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Learn More
+
+### Claude Code Resources
+- [Claude Code Documentation](https://claude.ai/code)
+
+### Community
+- [ClaudeKit Community](https://claudekit.cc/discord)
+- [Discussion Forum](https://github.com/anthropic/claude-code/discussions)
+- [Example Projects](https://github.com/topics/claude-code)
+
+### Support
+- [Issue Tracker](https://github.com/anthropic/claude-code/issues)
+- [Feature Requests](https://github.com/anthropic/claude-code/discussions/categories/ideas)
+- [Documentation](https://docs.claude.ai/code)
+
+---
+
+**Start building with AI-powered development today!** This boilerplate provides everything you need to create professional software with intelligent agent assistance.