claude-code-toolkit 1.0.11 → 1.0.13

package/templates/AGENTS.md

@@ -1,127 +1,141 @@
-# Project Agents Configuration
-
-This file defines the autonomous agents available in this project workspace.
-
-## Code Review Agent
-
-**Name**: code-reviewer
-**Description**: Specialized agent for conducting thorough code reviews, identifying bugs, security issues, and suggesting improvements
-**Tools**:
-- file-read
-- grep-search
-- run-terminal (for linting/checking)
-- git-commands
-
-**Permissions**: read-only
-**Triggers**: When user asks for code review or mentions "review this code"
-
-**Instructions**:
-- Focus on code quality, security, and best practices
-- Provide specific, actionable feedback
-- Suggest concrete improvements with code examples
-- Check for common vulnerabilities and anti-patterns
-- Consider performance implications
-
-## Documentation Agent
-
-**Name**: doc-writer
-**Description**: Creates comprehensive documentation including READMEs, API docs, and user guides
-**Tools**:
-- file-read
-- file-write
-- run-terminal (for generating docs)
-- web-search (for research)
-
-**Permissions**: write
-**Triggers**: When user asks to create or update documentation
-
-**Instructions**:
-- Use the professional-documentation-writer skill
-- Create clear, comprehensive documentation
-- Include practical examples and code snippets
-- Follow project documentation standards
-- Update table of contents automatically
-
-## Testing Agent
-
-**Name**: test-generator
-**Description**: Generates comprehensive test suites and ensures code coverage
-**Tools**:
-- file-read
-- file-write
-- run-terminal (for running tests)
-- grep-search
-
-**Permissions**: write
-**Triggers**: When user asks to add tests or mentions testing
-
-**Instructions**:
-- Generate unit tests for new functions
-- Create integration tests for APIs
-- Ensure adequate code coverage (>80%)
-- Follow project's testing framework and conventions
-- Add edge cases and error handling tests
-
-## Debugging Agent
-
-**Name**: debugger
-**Description**: Helps identify and fix bugs through systematic debugging approaches
-**Tools**:
-- file-read
-- run-terminal (for debugging commands)
-- grep-search
-- git-commands (for checking history)
-
-**Permissions**: read-only
-**Triggers**: When user reports bugs or asks for debugging help
-
-**Instructions**:
-- Use systematic debugging approaches
-- Check logs and error messages
-- Reproduce issues step by step
-- Suggest fixes with explanations
-- Help implement fixes when approved
-
-## Research Agent
-
-**Name**: researcher
-**Description**: Conducts technical research and provides insights on technologies and best practices
-**Tools**:
-- web-search
-- file-read
-- run-terminal (for research tools)
-
-**Permissions**: read-only
-**Triggers**: When user asks for research or technical information
-
-**Instructions**:
-- Provide accurate, up-to-date information
-- Cite sources and provide links
-- Compare different approaches/options
-- Consider project context and constraints
-- Suggest practical implementations
-
-## Mobile UI/UX Agent
-
-**Name**: mobile-ui-specialist
-**Description**: Specialized agent for creating professional, mobile-optimized UI/UX that eliminates layout inconsistencies, card height issues, text overflow problems, and responsive design flaws
-**Tools**:
-- file-read
-- file-write
-- run-terminal (for design tools)
-- web-search (for design research)
-
-**Permissions**: write
-**Triggers**: When user asks for mobile UI, responsive design, card layouts, or mentions UI/UX issues
-
-**Instructions**:
-- Use the mobile-ui-ux-master skill for all mobile UI work
-- Enforce equal card heights in horizontal grids
-- Prevent text overflow from breaking layouts
-- Ensure touch targets meet minimum 44px requirements
-- Implement mobile-first responsive design
-- Use CSS Grid/Flexbox for consistent layouts
-- Apply proper text containment (line-clamp, ellipsis)
-- Test designs across multiple screen sizes
-- Follow the mobile UX checklist for quality assurance
-- Never create amateur-looking mobile interfaces
+# Project Agents
+
+This project uses specialized AI agents for automated development workflows. Agent configurations are stored in `.claude/agents/`.
+
+## Active Agents
+
+### code-reviewer
+**Purpose**: Automated code quality and security analysis
+
+**Triggers**: "review", "check code", "security", "find bugs", "analyze"
+
+**What it does**:
+- Analyzes code for bugs and anti-patterns
+- Checks for OWASP Top 10 vulnerabilities
+- Identifies performance issues
+- Suggests improvements with code examples
+- Verifies error handling and input validation
+
+**Config**: `.claude/agents/code-reviewer.json`
+
+---
+
+### doc-writer
+**Purpose**: Professional documentation generation
+
+**Triggers**: "document", "readme", "api docs", "write docs"
+
+**What it does**:
+- Creates comprehensive documentation
+- Generates API references
+- Writes README files
+- Adds code examples
+- Maintains table of contents
+
+**Uses Skill**: documentation-writer
+**Config**: `.claude/agents/doc-writer.json`
+
+---
+
+### test-generator
+**Purpose**: Comprehensive test suite creation
+
+**Triggers**: "test", "write tests", "coverage", "unit test"
+
+**What it does**:
+- Generates unit tests for functions
+- Creates integration tests for APIs
+- Includes edge cases and error scenarios
+- Aims for >80% coverage
+- Follows project testing conventions
+
+**Frameworks**: Jest, Vitest, Pytest (auto-detected)
+**Config**: `.claude/agents/test-generator.json`
+
+---
+
+### debugger
+**Purpose**: Systematic debugging and issue resolution
+
+**Triggers**: "debug", "fix", "error", "not working", "failing", "bug"
+
+**What it does**:
+- Reproduces issues step by step
+- Analyzes error messages and stack traces
+- Checks recent code changes
+- Identifies root causes
+- Suggests fixes with explanations
+
+**Config**: `.claude/agents/debugger.json`
+
+---
+
+### researcher
+**Purpose**: Technical research and best practices
+
+**Triggers**: "research", "how to", "best practice", "compare", "recommend"
+
+**What it does**:
+- Provides accurate technical information
+- Compares different approaches
+- Evaluates trade-offs
+- Cites sources and documentation
+- Logs findings to memory system
+
+**Config**: `.claude/agents/researcher.json`
+
+---
+
+### mobile-ui-specialist
+**Purpose**: Professional mobile UI/UX optimization
+
+**Triggers**: "mobile", "responsive", "layout", "card height", "ui", "ux"
+
+**What it does**:
+- Enforces consistent card heights
+- Prevents text overflow issues
+- Ensures 44px+ touch targets
+- Implements mobile-first design
+- Applies proper text containment
+
+**Uses Skill**: mobile-ui-ux-master
+**Config**: `.claude/agents/mobile-ui-specialist.json`
+
+---
+
+## Agent Orchestration
+
+The orchestrator coordinates agents based on task type:
+
+| Task Type | Agents Used |
+|-----------|-------------|
+| Code changes | code-reviewer, test-generator |
+| New features | code-reviewer, doc-writer, test-generator |
+| UI work | mobile-ui-specialist, code-reviewer |
+| Bug fixing | debugger, test-generator |
+| Research | researcher |
+
+## Hook Integration
+
+Agents are triggered automatically by git hooks:
+
+| Git Event | Agent |
+|-----------|-------|
+| Pre-commit | code-reviewer |
+| Post-commit | doc-writer |
+| Pre-push | test-generator, code-reviewer |
+
+## Memory Integration
+
+All agents log their actions to the memory system:
+- Decisions -> .claude/memory/decisions.md
+- Learnings -> .claude/memory/learnings.md
+- Patterns -> .claude/memory/patterns.md
+
+## Customization
+
+Edit agent configurations in .claude/agents/{agent-name}.json to:
+- Modify trigger phrases
+- Adjust instructions
+- Change output formats
+- Add/remove tools

package/templates/CLAUDE.md

@@ -1,101 +1,128 @@
-# Claude Code Global Configuration
+# Claude Code Project Configuration
 
-This file contains global settings, prompts, and preferences for Claude Code in this workspace.
+This project uses the Claude Code Toolkit with integrated agents, skills, and automation.
 
-## Model Configuration
+## Agent System
 
-**Default Model**: sonnet
-**Fallback Model**: opus (for complex reasoning tasks)
-**Auto-switch to Opus for**:
-- Complex architectural decisions
-- Multi-file refactoring
-- Performance-critical code
-- Security-sensitive changes
+This project has specialized agents configured in `.claude/agents/`. **You MUST use these agents when handling user requests.**
 
-## Global Prompts
+### Agent Routing
 
-### Code Style Guidelines
-```
-- Use TypeScript for new projects unless JavaScript is specifically required
-- Follow functional programming principles where appropriate
-- Write self-documenting code with clear variable names
-- Add JSDoc/TSDoc comments for public APIs
-- Use async/await over Promises for better readability
-- Implement proper error handling with try/catch blocks
-- Follow consistent naming conventions (camelCase for variables/functions, PascalCase for classes/types)
-```
+When the user makes a request, determine which agent(s) to activate based on these triggers:
 
-### Project Structure
-```
-- Keep components small and focused (single responsibility)
-- Use barrel exports (index.ts) for clean imports
-- Separate business logic from UI components
-- Implement proper separation of concerns
-- Use environment variables for configuration
-- Follow 12-factor app principles
-```
+| Agent | Activate When User Says |
+|-------|------------------------|
+| **code-reviewer** | "review", "check code", "security", "find bugs", "analyze" |
+| **doc-writer** | "document", "readme", "api docs", "write docs" |
+| **test-generator** | "test", "write tests", "coverage", "unit test" |
+| **debugger** | "debug", "fix", "error", "not working", "failing", "bug" |
+| **researcher** | "research", "how to", "best practice", "compare", "recommend" |
+| **mobile-ui-specialist** | "mobile", "responsive", "layout", "card height", "ui", "ux" |
+
+### Agent Execution Protocol
+
+When activating an agent:
+
+1. **Load the agent config**: Read `.claude/agents/{agent-name}.json`
+2. **Follow agent instructions**: Execute each instruction in the config
+3. **Use specified tools only**: Respect the agent's tool permissions
+4. **Apply output format**: Follow the agent's output format specification
+5. **Log to memory**: Record decisions/learnings to `.claude/memory/`
+
+### Multi-Agent Coordination
+
+For complex tasks, multiple agents may be needed:
+- **Code changes** → code-reviewer + test-generator
+- **New features** → code-reviewer + doc-writer + test-generator
+- **UI work** → mobile-ui-specialist + code-reviewer
+- **Bug fixing** → debugger + test-generator
+
+## Skills Integration
+
+Load and apply skills from `.claude/skills/` when relevant:
+
+| Skill | Use For |
+|-------|---------|
+| **mobile-ui-ux-master** | All mobile/responsive UI work |
+| **documentation-writer** | All documentation tasks |
+| **hooks-master** | Automation and workflow setup |
+| **memory-system** | Knowledge management |
+
+## Memory System
+
+**ALWAYS check memory before making decisions:**
 
-### Testing Standards
 ```
-- Write tests for all public functions and components
-- Aim for >80% code coverage
-- Use descriptive test names that explain the behavior
-- Test both happy path and error scenarios
-- Mock external dependencies appropriately
-- Include integration tests for critical paths
+.claude/memory/
+├── context.md      # Current project state - READ FIRST
+├── decisions.md    # Past decisions - CHECK before architecture choices
+├── learnings.md    # Insights - APPLY relevant learnings
+├── patterns.md     # Code patterns - USE established patterns
+└── preferences.md  # User preferences - RESPECT these
 ```
 
-## Tool Allowlist
+**ALWAYS update memory after significant actions:**
+- New architectural decisions → Add to `decisions.md`
+- Discovered insights → Add to `learnings.md`
+- New patterns used → Add to `patterns.md`
+
+## Hooks Integration
+
+Hooks in `.claude/hooks/` trigger agents automatically:
+
+| Hook | Triggered Agents |
+|------|-----------------|
+| pre-commit | code-reviewer |
+| post-commit | doc-writer |
+| pre-push | test-generator, code-reviewer |
+
+## Code Standards
+
+### Style
+- TypeScript preferred for new code
+- Functional programming principles
+- Self-documenting variable names
+- JSDoc for public APIs
+- async/await over raw Promises
+- Proper error handling
+
+### Structure
+- Small, focused components
+- Barrel exports (index.ts)
+- Separate business logic from UI
+- Environment variables for config
+
+### Testing
+- Tests for all public functions
+- >80% coverage target
+- Descriptive test names
+- Happy path + error scenarios
+- Mock external dependencies
+
+## Tool Permissions
 
 ### Always Allowed
-- file-read
-- file-write
-- grep-search
-- run-terminal (basic commands)
-- git-commands
-
-### Require Approval
-- run-terminal (network commands, installations)
-- web-search (for research tasks)
-- shell-execution (for complex scripts)
-
-### Never Allowed
-- rm/delete commands without confirmation
-- Production database modifications
-- Network requests to external APIs without review
-
-## Context Management
-
-### File References
-Use `@filename` syntax to include relevant files in context:
-- `@src/components/` - Include component directory
-- `@package.json` - Include project dependencies
-- `@README.md` - Include project documentation
-- `@.claude/` - Include Claude-specific configuration
-
-### Memory Integration
-- Always check existing memory files before making decisions
-- Update memory files when learning new patterns or making important decisions
-- Use `/memory` commands to track project evolution
-
-## Best Practices
-
-### Development Workflow
-1. Always run tests before committing
-2. Use descriptive commit messages
-3. Keep pull requests focused and reviewable
-4. Document breaking changes
-5. Update documentation when changing APIs
-
-### Code Quality
-- Run linters before committing
-- Address all warnings and errors
-- Review code for security vulnerabilities
-- Consider performance implications
-- Ensure accessibility compliance
-
-### Communication
-- Explain complex decisions clearly
-- Provide context for changes
-- Ask clarifying questions when uncertain
-- Document assumptions and constraints
+- Read, Glob, Grep (file operations)
+- Bash (basic commands)
+- Git operations
+- LSP operations
+
+### Require Caution
+- Write (verify before writing)
+- Bash (network/install commands)
+- WebSearch, WebFetch
+
+### Never Without Confirmation
+- Destructive operations (rm, delete)
+- Production modifications
+- External API calls with side effects
+
+## Response Protocol
+
+1. **Identify relevant agent(s)** from user request
+2. **Load agent configuration** from `.claude/agents/`
+3. **Check memory** for context and past decisions
+4. **Execute agent instructions** systematically
+5. **Apply relevant skills** when specified
+6. **Update memory** with new decisions/learnings
+7. **Follow output format** specified by agent