kiro-kit 0.1.3 → 0.2.0

package/dist/presets/frontend/skills/claude-code/references/troubleshooting.md

@@ -0,0 +1,456 @@
+# Troubleshooting
+
+Common issues, debugging, and solutions for Claude Code.
+
+## Authentication Issues
+
+### API Key Not Recognized
+
+**Symptoms:**
+- "Invalid API key" errors
+- Authentication failures
+- 401 Unauthorized responses
+
+**Solutions:**
+
+```bash
+# Verify API key is set
+echo $ANTHROPIC_API_KEY
+
+# Re-login
+claude logout
+claude login
+
+# Check API key format (should start with sk-ant-)
+echo $ANTHROPIC_API_KEY | grep "^sk-ant-"
+
+# Test API key directly
+curl https://api.anthropic.com/v1/messages \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "content-type: application/json" \
+  -d '{"model":"claude-sonnet-4-5-20250929","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'
+```
+
+### Environment Variable Issues
+
+```bash
+# Add to shell profile
+echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.bashrc
+source ~/.bashrc
+
+# Or use .env file
+echo 'ANTHROPIC_API_KEY=sk-ant-xxxxx' > .kiro/.env
+
+# Verify it's loaded
+claude config get apiKey
+```
+
+## Installation Problems
+
+### npm Installation Failures
+
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Remove and reinstall
+npm uninstall -g @anthropic-ai/claude-code
+npm install -g @anthropic-ai/claude-code
+
+# Use specific version
+npm install -g @anthropic-ai/claude-code@1.0.0
+
+# Check installation
+which claude
+claude --version
+```
+
+### Permission Errors
+
+```bash
+# Fix permissions on Unix/Mac
+sudo chown -R $USER ~/.claude
+chmod -R 755 ~/.claude
+
+# Or install without sudo (using nvm)
+nvm install 18
+npm install -g @anthropic-ai/claude-code
+```
+
+### Python Installation Issues
+
+```bash
+# Upgrade pip
+pip install --upgrade pip
+
+# Install in virtual environment
+python -m venv claude-env
+source claude-env/bin/activate
+pip install claude-code
+
+# Install with --user flag
+pip install --user claude-code
+```
+
+## Connection & Network Issues
+
+### Proxy Configuration
+
+```bash
+# Set proxy environment variables
+export HTTP_PROXY=http://proxy.company.com:8080
+export HTTPS_PROXY=http://proxy.company.com:8080
+export NO_PROXY=localhost,127.0.0.1
+
+# Configure in settings
+claude config set proxy http://proxy.company.com:8080
+
+# Test connection
+curl -x $HTTP_PROXY https://api.anthropic.com
+```
+
+### SSL/TLS Errors
+
+```bash
+# Trust custom CA certificate
+export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.crt
+
+# Disable SSL verification (not recommended for production)
+export NODE_TLS_REJECT_UNAUTHORIZED=0
+
+# Update ca-certificates
+sudo update-ca-certificates  # Debian/Ubuntu
+sudo update-ca-trust         # RHEL/CentOS
+```
+
+### Firewall Issues
+
+```bash
+# Check connectivity to Anthropic API
+ping api.anthropic.com
+telnet api.anthropic.com 443
+
+# Test HTTPS connection
+curl -v https://api.anthropic.com
+
+# Check firewall rules
+sudo iptables -L  # Linux
+netsh advfirewall show allprofiles  # Windows
+```
+
+## MCP Server Problems
+
+### Server Not Starting
+
+```bash
+# Test MCP server command manually
+npx -y @modelcontextprotocol/server-filesystem /tmp
+
+# Check server logs
+cat ~/.kiro/logs/mcp-*.log
+
+# Verify environment variables
+echo $GITHUB_TOKEN  # For GitHub MCP
+
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector
+```
+
+### Connection Timeouts
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-example"],
+      "timeout": 30000,
+      "retries": 3
+    }
+  }
+}
+```
+
+### Permission Denied
+
+```bash
+# Check file permissions
+ls -la /path/to/mcp/server
+
+# Make executable
+chmod +x /path/to/mcp/server
+
+# Check directory access
+ls -ld /path/to/allowed/directory
+```
+
+## Performance Issues
+
+### Slow Responses
+
+**Check network latency:**
+```bash
+ping api.anthropic.com
+```
+
+**Use faster model:**
+```bash
+claude --model haiku "simple task"
+```
+
+**Reduce context:**
+```json
+{
+  "maxTokens": 4096,
+  "context": {
+    "autoTruncate": true
+  }
+}
+```
+
+**Enable caching:**
+```json
+{
+  "caching": {
+    "enabled": true
+  }
+}
+```
+
+### High Memory Usage
+
+```bash
+# Clear cache
+rm -rf ~/.kiro/cache/*
+
+# Limit context window
+claude config set maxTokens 8192
+
+# Disable memory
+claude config set memory.enabled false
+
+# Close unused sessions
+claude session list
+claude session close session-123
+```
+
+### Rate Limiting
+
+```bash
+# Check rate limits
+claude usage show
+
+# Wait and retry
+sleep 60
+claude "retry task"
+
+# Implement exponential backoff in scripts
+```
+
+## Tool Execution Errors
+
+### Bash Command Failures
+
+**Check sandboxing settings:**
+```json
+{
+  "sandboxing": {
+    "enabled": true,
+    "allowedPaths": ["/workspace", "/tmp"]
+  }
+}
+```
+
+**Verify command permissions:**
+```bash
+# Make script executable
+chmod +x script.sh
+
+# Check PATH
+echo $PATH
+which command-name
+```
+
+### File Access Denied
+
+```bash
+# Check file permissions
+ls -la file.txt
+
+# Change ownership
+sudo chown $USER file.txt
+
+# Grant read/write permissions
+chmod 644 file.txt
+```
+
+### Write Tool Failures
+
+```bash
+# Check disk space
+df -h
+
+# Verify directory exists
+mkdir -p /path/to/directory
+
+# Check write permissions
+touch /path/to/directory/test.txt
+rm /path/to/directory/test.txt
+```
+
+## Hook Errors
+
+### Hooks Not Running
+
+```bash
+# Verify hooks.json syntax
+cat .kiro/hooks.json | jq .
+
+# Check hook script permissions
+chmod +x .kiro/scripts/hook.sh
+
+# Test hook script manually
+.kiro/scripts/hook.sh
+
+# Check logs
+cat ~/.kiro/logs/hooks.log
+```
+
+### Hook Script Errors
+
+```bash
+# Add error handling to hooks
+#!/bin/bash
+set -e  # Exit on error
+set -u  # Exit on undefined variable
+
+# Debug hook execution
+#!/bin/bash
+set -x  # Print commands
+echo "Hook running: $TOOL_NAME"
+```
+
+## Debug Mode
+
+### Enable Debugging
+
+```bash
+# Set debug environment variable
+export CLAUDE_DEBUG=1
+export CLAUDE_LOG_LEVEL=debug
+
+# Run with debug flag
+claude --debug "task"
+
+# View debug logs
+tail -f ~/.kiro/logs/debug.log
+```
+
+### Verbose Output
+
+```bash
+# Enable verbose mode
+claude --verbose "task"
+
+# Show all tool calls
+claude --show-tools "task"
+
+# Display thinking process
+claude --show-thinking "task"
+```
+
+## Common Error Messages
+
+### "Model not found"
+
+```bash
+# Use correct model name
+claude --model claude-sonnet-4-5-20250929
+
+# Update claude-code
+npm update -g @anthropic-ai/claude-code
+```
+
+### "Rate limit exceeded"
+
+```bash
+# Wait and retry
+sleep 60
+
+# Check usage
+claude usage show
+
+# Implement rate limiting in code
+```
+
+### "Context length exceeded"
+
+```bash
+# Reduce context
+claude config set maxTokens 100000
+
+# Summarize long content
+claude "summarize this codebase"
+
+# Process in chunks
+claude "analyze first half of files"
+```
+
+### "Timeout waiting for response"
+
+```bash
+# Increase timeout
+claude config set timeout 300
+
+# Check network connection
+ping api.anthropic.com
+
+# Retry with smaller request
+```
+
+## Getting Help
+
+### Collect Diagnostic Info
+
+```bash
+# System info
+claude --version
+node --version
+npm --version
+
+# Configuration
+claude config list --all
+
+# Recent logs
+tail -n 100 ~/.kiro/logs/session.log
+
+# Environment
+env | grep CLAUDE
+env | grep ANTHROPIC
+```
+
+### Report Issues
+
+1. **Check existing issues**: https://github.com/anthropics/claude-code/issues
+2. **Gather diagnostic info**
+3. **Create minimal reproduction**
+4. **Submit issue** with:
+   - Claude Code version
+   - Operating system
+   - Error messages
+   - Steps to reproduce
+
+### Support Channels
+
+- **Documentation**: https://docs.claude.com/claude-code
+- **GitHub Issues**: https://github.com/anthropics/claude-code/issues
+- **Support Portal**: support.claude.com
+- **Community Discord**: discord.gg/anthropic
+
+## See Also
+
+- Installation guide: `references/getting-started.md`
+- Configuration: `references/configuration.md`
+- MCP setup: `references/mcp-integration.md`
+- Best practices: `references/best-practices.md`

package/dist/presets/frontend/skills/claude-code/skill.md

@@ -0,0 +1,194 @@
+---
+name: claude-code
+description: >-
+  Use when users ask about Claude Code features, setup, configuration,
+  troubleshooting, slash commands, MCP servers, Agent Skills, hooks, plugins,
+  CI/CD integration, or enterprise deployment. Activate for questions like 'How
+  do I use Claude Code?', 'What slash commands are available?', 'How to set up
+  MCP?', 'Create a skill', 'Fix Claude Code issues', or 'Deploy Claude Code in
+  enterprise'.
+---
+
+# Claude Code Expert
+
+Claude Code is Anthropic's agentic coding tool that lives in the terminal and helps turn ideas into code faster. It combines autonomous planning, execution, and validation with extensibility through skills, plugins, MCP servers, and hooks.
+
+## When to Use This Skill
+
+Use when users need help with:
+- Understanding Claude Code features and capabilities
+- Installation, setup, and authentication
+- Using slash commands for development workflows
+- Creating or managing Agent Skills
+- Configuring MCP servers for external tool integration
+- Setting up hooks and plugins
+- Troubleshooting Claude Code issues
+- Enterprise deployment (SSO, sandboxing, monitoring)
+- IDE integration (VS Code, JetBrains)
+- CI/CD integration (GitHub Actions, GitLab)
+- Advanced features (extended thinking, caching, checkpointing)
+- Cost tracking and optimization
+
+**Activation examples:**
+- "How do I use Claude Code?"
+- "What slash commands are available?"
+- "How to set up MCP servers?"
+- "Create a new skill for X"
+- "Fix Claude Code authentication issues"
+- "Deploy Claude Code in enterprise environment"
+
+## Core Architecture
+
+**Subagents**: Specialized AI agents (planner, code-reviewer, tester, debugger, docs-manager, ui-ux-designer, database-admin, etc.)
+
+**Agent Skills**: Modular capabilities with instructions, metadata, and resources that Claude uses automatically
+
+**Slash Commands**: User-defined operations in `.kiro/commands/` that expand to prompts
+
+**Hooks**: Shell commands executing in response to events (pre/post-tool, user-prompt-submit)
+
+**MCP Servers**: Model Context Protocol integrations connecting external tools and services
+
+**Plugins**: Packaged collections of commands, skills, hooks, and MCP servers
+
+## Quick Reference
+
+Load these references when needed for detailed guidance:
+
+### Getting Started
+- **Installation & Setup**: `references/getting-started.md`
+  - Prerequisites, installation methods, authentication, first run
+
+### Development Workflows
+- **Slash Commands**: `references/slash-commands.md`
+  - Complete command catalog: /cook, /plan, /debug, /test, /fix:*, /docs:*, /git:*, /design:*, /content:*
+
+- **Agent Skills**: `references/agent-skills.md`
+  - Creating skills, skill.json format, best practices, API usage
+
+### Integration & Extension
+- **MCP Integration**: `references/mcp-integration.md`
+  - Configuration, common servers, remote servers
+
+- **Hooks & Plugins**: `references/hooks-and-plugins.md`
+  - Hook types, configuration, environment variables, plugin structure, installation
+
+### Configuration & Settings
+- **Configuration**: `references/configuration.md`
+  - Settings hierarchy, key settings, model configuration, output styles
+
+### Enterprise & Production
+- **Enterprise Features**: `references/enterprise-features.md`
+  - IAM, SSO, RBAC, sandboxing, audit logging, deployment options, monitoring
+
+- **IDE Integration**: `references/ide-integration.md`
+  - VS Code extension, JetBrains plugin setup and features
+
+- **CI/CD Integration**: `references/cicd-integration.md`
+  - GitHub Actions, GitLab CI/CD workflow examples
+
+### Advanced Usage
+- **Advanced Features**: `references/advanced-features.md`
+  - Extended thinking, prompt caching, checkpointing, memory management
+
+- **Troubleshooting**: `references/troubleshooting.md`
+  - Common issues, authentication failures, MCP problems, performance, debug mode
+
+- **API Reference**: `references/api-reference.md`
+  - Admin API, Messages API, Files API, Models API, Skills API
+
+- **Best Practices**: `references/best-practices.md`
+  - Project organization, security, performance, team collaboration, cost management
+
+## Common Workflows
+
+### Feature Implementation
+```bash
+/cook implement user authentication with JWT
+# Or plan first
+/plan implement payment integration with Stripe
+```
+
+### Bug Fixing
+```bash
+/fix:fast the login button is not working
+/debug the API returns 500 errors intermittently
+/fix:types  # Fix TypeScript errors
+```
+
+### Code Review & Testing
+```bash
+claude "review my latest commit"
+/test
+/fix:test the user service tests are failing
+```
+
+### Documentation
+```bash
+/docs:init      # Create initial documentation
+/docs:update    # Update existing docs
+/docs:summarize # Summarize changes
+```
+
+### Git Operations
+```bash
+/git:cm                    # Stage and commit
+/git:cp                    # Stage, commit, and push
+/git:pr feature-branch main  # Create pull request
+```
+
+### Design & Content
+```bash
+/design:fast create landing page for SaaS product
+/content:good write product description for new feature
+```
+
+## Instructions for Claude
+
+When responding to Claude Code questions:
+
+1. **Identify the topic** from the user's question
+2. **Load relevant references** from the Quick Reference section above
+3. **Provide specific guidance** using information from loaded references
+4. **Include examples** when helpful
+
+**Loading references:**
+- Read reference files only when needed for the specific question
+- Multiple references can be loaded for complex queries
+- Use grep patterns if searching within references
+
+**For setup/installation questions:** Load `references/getting-started.md`
+
+**For slash command questions:** Load `references/slash-commands.md`
+
+**For skill creation:** Load `references/agent-skills.md`
+
+**For MCP questions:** Load `references/mcp-integration.md`
+
+**For hooks/plugins:** Load `references/hooks-and-plugins.md`
+
+**For configuration:** Load `references/configuration.md`
+
+**For enterprise deployment:** Load `references/enterprise-features.md`
+
+**For IDE integration:** Load `references/ide-integration.md`
+
+**For CI/CD:** Load `references/cicd-integration.md`
+
+**For advanced features:** Load `references/advanced-features.md`
+
+**For troubleshooting:** Load `references/troubleshooting.md`
+
+**For API usage:** Load `references/api-reference.md`
+
+**For best practices:** Load `references/best-practices.md`
+
+**Documentation links:**
+- llms.txt: https://context7.com/websites/claude_en_claude-code/llms.txt?tokens=10000
+  - Search for specific topics: `https://context7.com/websites/claude_en_claude-code/llms.txt?topic=<topic>&tokens=5000`
+  - Eg. Search for "subagent": `https://context7.com/websites/claude_en_claude-code/llms.txt?topic=subagent&tokens=5000`
+- Main docs: https://docs.claude.com/en/docs/claude-code/
+- GitHub: https://github.com/anthropics/claude-code
+- Support: support.claude.com
+
+Provide accurate, actionable guidance based on the loaded references and official documentation.