# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is the **Claude Code Development Kit** - a comprehensive automation framework that transforms Claude Code from a helpful tool into a reliable development partner. The kit includes n8n documentation, command orchestration templates, intelligent hooks, and a 3-tier AI-optimized documentation system.

- **Vision:** Provide automated context injection, security scanning, and documentation maintenance for AI-assisted development
- **Current Phase:** Production-ready framework (v4.0.0) with complete n8n API integration and lifecycle automation
- **Key Architecture:** Shell-based automation framework with markdown-based command orchestration
- **Development Strategy:** Token-efficient AI context management with cross-platform compatibility

## Project Structure

**⚠️ CRITICAL: AI agents MUST read the [Project Structure documentation](/docs/ai-context/project-structure.md) before attempting any task to understand the complete technology stack, file tree and project organization.**

This is a development toolkit, not a traditional codebase. The framework uses shell scripts, markdown templates, and JSON configuration to orchestrate AI workflows. For the complete structure, see [docs/ai-context/project-structure.md](/docs/ai-context/project-structure.md).

## Common Commands

### Framework Operations

- **Install framework**: `curl -sSL https://raw.githubusercontent.com/your-repo/install.sh | bash`
- **Setup locally**: `./setup.sh` (interactive configuration)
- **Test hooks**: `.claude/hooks/notify.sh input` and `.claude/hooks/notify.sh complete`
- **View logs**: `tail -f .claude/logs/context-injection.log` and `tail -f .claude/logs/security-scan.log`

### Command Templates (used as Claude Code slash commands)

- `/full-context` - Comprehensive context gathering and analysis
- `/code-review` - Multi-perspective code quality analysis
- `/update-docs` - Synchronize documentation with code changes
- `/create-docs` - Generate initial documentation structure
- `/refactor` - Intelligent code restructuring
- `/handoff` - Session continuity and context preservation

### n8n Workflow Development Suite (9 Commands, 4,500+ Lines)

#### Core Development Commands

- `/n8n-workflow` - Design and build n8n workflows with AI assistance
- `/n8n-debug` - Diagnose and troubleshoot n8n workflow issues
- `/n8n-optimize` - Analyze and optimize n8n workflow performance
- `/n8n-integrate` - Design secure integrations with external services
- `/n8n-deploy` - Plan and execute production deployment strategies

#### Quality Assurance & Operations

- `/n8n-validate` - Comprehensive workflow validation and compliance checking
- `/n8n-test` - Automated testing framework with CI/CD integration
- `/n8n-monitor` - Real-time monitoring and operational intelligence

#### API Integration & Deployment

- `/n8n-deploy-api` - Direct workflow deployment to n8n instances via REST API

### Hook Verification

- `/hook-setup` - Comprehensive setup verification and testing (multi-agent orchestration)
- `chmod +x hooks/*.sh` - Ensure hook scripts are executable
- `tail -f .claude/logs/n8n-context-injection.log` - Monitor n8n context loading behavior

### n8n Framework Operations

- **Topic-specific context**: `@docs/n8n-topics/{topic}.md` for targeted documentation
- **Intelligent context loading**: Automatic detection and loading of relevant n8n topics
- **Enhanced settings**: Use `hooks/setup/settings-n8n.json.template` for n8n-optimized configuration
- **Query optimization**: Use compound keywords for better topic detection (e.g., "workflow deployment", "API integration")

### n8n API Integration & Deployment

- **Direct Deployment**: `./scripts/deploy-workflow.py workflow.json` for API-based deployment
- **Interactive Setup**: `./scripts/setup-n8n-api.sh setup` for environment configuration
- **Environment Management**: Support for dev/staging/production environments
- **Automated Testing**: Post-deployment validation and health checks
- **CI/CD Integration**: GitHub Actions workflows for automated deployment pipelines

## Core Architecture

### Hook System (`hooks/`)

Lifecycle automation that executes at specific Claude Code events:

- **Context Injection**: Automatically includes project docs in sub-agents and Gemini consultations
- **n8n Intelligence**: `n8n-context-injector.sh` with query analysis and smart topic loading
- **Security Scanning**: Prevents accidental exposure of secrets in MCP calls
- **Audio Notifications**: Cross-platform audio feedback for task completion and input needs
- **Session Continuity**: Maintains context between development sessions

### Command System (`commands/`)

Markdown-based orchestration templates that coordinate multi-agent workflows:

- Auto-load appropriate documentation tiers
- Spawn specialized agents based on complexity
- Integrate MCP servers when external expertise helps
- Scale from simple analysis to sophisticated multi-agent coordination
- **n8n-Specific Commands**: 9 specialized templates for complete n8n development lifecycle with API integration

### Documentation System (`docs/`)

3-tier AI-optimized structure:

- **Tier 1 (Foundation)**: System-wide stable documentation (`/docs/ai-context/`)
- **Tier 2 (Component)**: Architectural charters for major components
- **Tier 3 (Feature)**: Granular docs co-located with code

### n8n Framework Integration

- **Intelligent Documentation System**: 12 specialized topic chunks with automatic context injection
- **Smart Context Loading**: Query analysis determines optimal documentation context (50-200KB vs 2.5MB+)
- **Topic-Based Organization**: Core concepts, workflows, integrations, API, hosting, and advanced features
- **Automatic Detection**: `n8n-context-injector.sh` hook intelligently loads relevant topics based on queries

## Multi-Agent Workflows & Context Injection

### Automatic Context Injection for Sub-Agents

When using the Task tool to spawn sub-agents, core project context (CLAUDE.md, project-structure.md, docs-overview.md) is automatically injected via the subagent-context-injector hook. This ensures consistent knowledge across all AI agents without manual specification.

### Context Efficiency

- Uses `@` references for documentation loading instead of content duplication
- Token-efficient design for large codebases
- Maintains context across sessions through handoff documentation

## MCP Server Integrations

### Gemini Consultation Server

**Automatic Context Injection:**

- `/docs/ai-context/project-structure.md` - Complete project structure and tech stack
- `/MCP-ASSISTANT-RULES.md` - Project-specific coding standards

**Usage for complex problems:**

```python
mcp__gemini__consult_gemini(
    specific_question="How should I optimize this framework?",
    problem_description="Need to reduce token usage in context injection",
    code_context="Current injection includes full documentation...",
    attached_files=["hooks/subagent-context-injector.sh"],
    preferred_approach="optimize"
)
```

### Context7 Documentation Server

**Usage for external library documentation:**

```python
mcp__context7__resolve_library_id(libraryName="n8n")
mcp__context7__get_library_docs(
    context7CompatibleLibraryID="/n8n-io/n8n",
    topic="workflows",
    tokens=8000
)
```

## Security & Configuration

### Hook Security Model

- All MCP calls are scanned for sensitive data before execution
- Pattern-based detection for API keys, passwords, and secrets
- Configurable via `hooks/config/sensitive-patterns.json`
- Comprehensive logging to `.claude/logs/`

### Configuration Management

- Template-based configuration in `hooks/setup/settings.json.template`
- Environment variable substitution with `${WORKSPACE}` references
- Cross-platform compatibility (macOS, Linux, Windows)

## Framework-Specific Guidelines

### Working with the Kit

- **Documentation Updates**: Use `/update-docs` after modifying templates or hooks
- **Hook Development**: Test hooks individually before integration
- **Command Customization**: Modify markdown templates in `commands/` directory
- **Context Management**: Leverage automatic injection rather than manual context specification

### Installation Patterns

1. **Remote Installation**: curl-based download → extract → setup
2. **Local Setup**: Interactive configuration → copy files → set permissions
3. **Conflict Resolution**: User choice for existing files → consistent application
4. **Component Selection**: Optional MCP servers → notifications → appropriate hooks

### File Organization Standards

- Keep shell scripts under 200 lines when possible
- Single responsibility per hook with clear purpose
- Markdown templates should be self-contained and reusable
- JSON configuration should be environment-agnostic with variable substitution

## Development Workflow

### Typical Framework Development

```bash
# Understand current state
/full-context "analyze hook system performance"

# Implement changes to hooks or commands
# ... modify files ...

# Verify security and functionality
/code-review "review hook modifications"

# Update documentation
/update-docs "document hook improvements"

# Test installation
./setup.sh  # or use the hooks test commands

# Preserve context
/handoff "completed hook optimization"
```

### n8n Framework Development

```bash
# Design new n8n workflows
/n8n-workflow "create customer onboarding automation"
# Auto-loads: workflows.md + nodes-integrations.md + code-development.md

# Debug workflow issues
/n8n-debug "workflow failing at HTTP node with 401 error"
# Auto-loads: advanced.md + workflows.md + nodes-integrations.md

# Optimize workflow performance
/n8n-optimize "reduce execution time for large dataset processing"
# Auto-loads: advanced.md + hosting-deployment.md + workflows.md

# Build external integrations
/n8n-integrate "connect to Salesforce CRM with OAuth"
# Auto-loads: nodes-integrations.md + data-management.md + api.md

# Deploy to production
/n8n-deploy "production deployment on AWS with high availability"
# Auto-loads: hosting-deployment.md + user-management.md + advanced.md

# Validate workflow quality
/n8n-validate "check workflow for security and performance compliance"
# Auto-loads: workflows.md + advanced.md + data-management.md

# Test workflow thoroughly
/n8n-test "create comprehensive test suite for workflow"
# Auto-loads: workflows.md + code-development.md + api.md

# Monitor workflow operations
/n8n-monitor "setup real-time monitoring and alerting"
# Auto-loads: hosting-deployment.md + advanced.md + workflows.md

# Deploy via API
/n8n-deploy-api "deploy workflow directly to n8n instance"
# Auto-loads: api.md + hosting-deployment.md + workflows.md

# General n8n analysis
/full-context "analyze n8n integration architecture"
# Auto-loads: core.md + workflows.md + hosting-deployment.md

# Update documentation after changes
/update-docs "document new n8n workflow capabilities"

# Preserve context for future sessions
/handoff "completed n8n workflow development with specialized commands"
```

### Command Template Development

1. Copy existing template from `commands/`
2. Modify orchestration logic and agent strategies
3. Test with `/command-name` in Claude Code
4. Update documentation tier references as needed
5. Verify context injection works correctly

## Important Constraints

- **Read-only for most operations**: This is a framework, not executable code
- **Shell script execution**: Hooks run with user permissions
- **Cross-platform compatibility**: All scripts must work on macOS, Linux, and Windows
- **Token efficiency**: Prioritize @ references over content duplication
- **Security first**: All external AI calls must pass security scanning

## n8n Framework Integration

### Intelligent Documentation System

The framework includes a sophisticated n8n documentation system with automatic context injection:

- **12 Topic Chunks**: Comprehensive n8n knowledge split from 84,849-line compiled documentation
- **Smart Context Loading**: Automatic detection and loading of relevant topics (typically 50-200KB vs 2.5MB+)
- **Query Intelligence**: Keyword analysis determines optimal documentation context
- **Efficient Token Usage**: 95%+ reduction in typical context loading for n8n queries

### n8n Documentation Topics

- `core.md` - Fundamental concepts and glossary (416 lines)
- `workflows.md` - Workflow creation and management (982 lines)
- `nodes-integrations.md` - All available nodes and integrations (58,090 lines - largest)
- `code-development.md` - Python/JS/AI development patterns (4,096 lines)
- `api.md` - REST API and programmatic access (279 lines)
- `hosting-deployment.md` - Infrastructure and deployment (5,749 lines)
- `data-management.md` - Credentials and data handling (982 lines)
- `user-management.md` - Users, permissions, security (978 lines)
- `cloud-features.md` - n8n Cloud specific features (1,608 lines)
- `learning.md` - Tutorials and educational content (4,041 lines)
- `advanced.md` - Error handling and troubleshooting (12,137 lines)
- `getting-started.md` - Setup and migration (205 lines)

### Automatic Context Loading Examples

```bash
# User query: "How do I create a workflow with API calls?"
# System detects: "workflow" + "api" keywords
# Auto-loads: workflows.md + api.md + nodes-integrations.md

# User query: "Deploy n8n with Docker"
# System detects: "deploy" + "docker" keywords
# Auto-loads: hosting-deployment.md + getting-started.md
```

### Manual Context Loading for Complex Tasks

```markdown
# Load specific topics for comprehensive analysis:
@docs/n8n-topics/index.md           # Topic overview first
@docs/n8n-topics/workflows.md       # Workflow development
@docs/n8n-topics/code-development.md # Code integration

# For deployment-focused tasks:
@docs/n8n-topics/hosting-deployment.md
@docs/n8n-topics/user-management.md
@docs/n8n-topics/advanced.md
```

### Framework Configuration

To enable the enhanced n8n framework:

1. **Enhanced Settings**: Copy `hooks/setup/settings-n8n.json.template` to `.claude/settings.json`
2. **Topic Verification**: Ensure all 12 topic files exist in `docs/n8n-topics/`
3. **Hook Integration**: Verify `n8n-context-injector.sh` is executable and properly configured
4. **Logging Setup**: Monitor `.claude/logs/n8n-context-injection.log` for system behavior
5. **Topic Mapping**: Reference `docs/n8n-topics/topic-map.json` for keyword-to-topic relationships

When working with n8n:

- Leverage automatic context injection for most queries
- Use Context7 MCP for up-to-date n8n API documentation beyond the framework
- Follow n8n 1.0+ patterns (depth-first execution, Python Code node support)
- Combine framework intelligence with deployment automation hooks