# CLAUDE.md - Project Instructions for Claude Code

**Auto-Generated**: 2025-10-10
**System Version**: 1.0.0

## Project Overview

This is **Infinite Loop Variant 7**: A meta-level self-improvement system that can analyze its own performance, improve its commands, generate new specifications, and evolve its orchestration strategy using meta-prompting principles from [promptingguide.ai](https://www.promptingguide.ai/techniques/meta-prompting).

## Key Differentiator from Other Variants

While other infinite loop variants generate content, this variant has **meta-level awareness**:

- **Self-Analysis** - Examines its own processes and performance
- **Self-Modification** - Can improve its own commands (safely)
- **Self-Generation** - Creates new specs from discovered patterns
- **Self-Testing** - Validates its own functionality
- **Self-Documentation** - Updates its own docs (including this file)
- **Recursive Improvement** - Can improve the improvement process

## Quick Start for Claude Code

### Primary Commands (all in `.claude/commands/`)

```bash
# Main orchestration with self-improvement
/infinite-meta <spec> <output> <count|infinite> [evolve]

# Self-improvement utilities
/improve-self [target] [depth]
/generate-spec [source] [focus] [name]
/evolve-strategy [metric] [type]
/self-test [scope] [depth]
/self-document [scope] [detail]
```

### Typical Usage Patterns

**Pattern 1: Basic Generation with Improvement**
```bash
/infinite-meta specs/example_spec.md output/ 20 evolve
```
System generates in waves, improving strategy between each wave.

**Pattern 2: Deep System Improvement**
```bash
/improve-self all deep         # Analyze everything
/evolve-strategy all incremental  # Apply improvements
/self-test all standard        # Validate changes
/self-document all standard    # Update docs
```

**Pattern 3: Create New Capability**
```bash
/generate-spec patterns novel custom_domain  # Auto-generate spec
/infinite-meta specs/custom_domain.md output/ 10 evolve  # Test it
/self-test generation standard  # Validate quality
```

## Directory Structure

```
.
├── .claude/
│   ├── commands/              # All slash commands
│   │   ├── infinite-meta.md   # Main orchestrator with self-improvement
│   │   ├── improve-self.md    # Self-improvement analyzer
│   │   ├── generate-spec.md   # Auto-spec generator
│   │   ├── evolve-strategy.md # Strategy evolver
│   │   ├── self-test.md       # System validator
│   │   └── self-document.md   # Auto-documentation
│   └── settings.json          # Permissions (Write, Edit, Bash, etc.)
├── specs/                     # Specifications (generation templates)
│   ├── example_spec.md        # Example meta-aware spec
│   └── auto_generated_spec.md # Template for auto-gen
├── improvement_log/           # Evolution history (created at runtime)
│   ├── wave_N_reflection.md   # Self-reflection per wave
│   ├── wave_N_proposals.md    # Improvement proposals
│   ├── evolved_strategy_*.md  # Strategy evolution docs
│   ├── test_report_*.md       # Test results
│   └── system_health.json     # Current metrics
├── meta_prompts/              # Pattern library (created at runtime)
│   ├── command_improver.md    # Patterns for command improvement
│   ├── spec_generator.md      # Patterns for spec generation
│   └── orchestration_strategy.md  # Strategy patterns
├── docs/                      # Documentation
│   └── self_improvement_guide.md
├── README.md                  # User documentation (auto-maintained)
└── CLAUDE.md                  # This file (auto-maintained)
```

## Architecture and Principles

### Meta-Prompting Foundation

Based on principles from https://www.promptingguide.ai/techniques/meta-prompting:

**1. Structure-Oriented**
- Focus on patterns and frameworks, not specific examples
- Define "how to think" rather than "what to create"
- Enable generalization across contexts

**2. Abstract Frameworks**
- Use generalizable templates
- Principle-based reasoning
- Minimal example dependency

**3. Efficient Reasoning**
- Reduced token usage through structural focus
- Pattern recognition over memorization
- Meta-level optimization

**4. Self-Improvement**
- Recursive enhancement capability
- Can improve the improvement process
- Meta-awareness throughout

### Three-Layer Architecture

```
┌───────────────────────────────────────┐
│  Meta-Level Control Layer             │
│  - Self-analysis                      │
│  - Strategy evolution                 │
│  - Recursive improvement              │
└─────────────┬─────────────────────────┘
              │
┌─────────────┴─────────────────────────┐
│  Command Layer                        │
│  - /infinite-meta (orchestrator)      │
│  - /improve-self (analyzer)           │
│  - /generate-spec (creator)           │
│  - /evolve-strategy (evolver)         │
│  - /self-test (validator)             │
│  - /self-document (documenter)        │
└─────────────┬─────────────────────────┘
              │
┌─────────────┴─────────────────────────┐
│  Data Layer                           │
│  - Specs (templates)                  │
│  - Improvement logs (history)         │
│  - Meta-prompts (patterns)            │
│  - Generated content (outputs)        │
└───────────────────────────────────────┘
```

## Command Responsibilities

### `/infinite-meta` - Main Orchestrator

**Role:** Generate content while continuously improving itself

**Key Actions:**
- Reads specification
- Analyzes existing iterations for context
- Deploys parallel sub-agents with unique creative directions
- Collects meta-feedback from sub-agents
- Logs performance metrics
- Evolves strategy between waves (if evolve mode enabled)

**Integration:** Works with all other commands; uses specs from `/generate-spec`; applies strategy from `/evolve-strategy`; documented by `/self-document`

### `/improve-self` - Self-Improvement Analyzer

**Role:** Analyze system and propose concrete improvements

**Key Actions:**
- Reviews performance metrics from `improvement_log/`
- Identifies bottlenecks and inefficiencies
- Applies meta-prompting analysis
- Generates actionable improvement proposals
- Creates risk assessments and rollback plans

**Integration:** Feeds into `/evolve-strategy`; validated by `/self-test`; documented by `/self-document`

### `/generate-spec` - Auto-Spec Creator

**Role:** Create new specifications from discovered patterns

**Key Actions:**
- Analyzes patterns across iterations
- Extracts structural frameworks
- Synthesizes new specifications
- Validates through test generation
- Updates pattern library

**Integration:** Creates specs for `/infinite-meta`; uses insights from `/improve-self`; tested by `/self-test`

### `/evolve-strategy` - Strategy Evolver

**Role:** Evolve orchestration strategy for better performance

**Key Actions:**
- Analyzes strategy effectiveness
- Applies meta-prompting to strategy design
- Creates evolved orchestration approaches
- Includes validation and rollback procedures
- Updates meta-prompts library

**Integration:** Uses analysis from `/improve-self`; applied in `/infinite-meta`; validated by `/self-test`

### `/self-test` - System Validator

**Role:** Validate system capabilities and detect regressions

**Key Actions:**
- Tests all commands functionality
- Validates generation quality
- Checks improvement loop effectiveness
- Detects regressions vs. baseline
- Generates detailed test reports

**Integration:** Validates all commands; uses specs from `/generate-spec`; reports inform `/improve-self`

### `/self-document` - Auto-Documenter

**Role:** Generate and maintain documentation

**Key Actions:**
- Scans all system components
- Analyzes current state and capabilities
- Generates/updates README.md and CLAUDE.md
- Documents evolution history
- Reflects meta-level capabilities

**Integration:** Documents all commands; uses data from `improvement_log/`; updates itself!

## Meta-Level Capabilities

### 1. Self-Analysis
- Tracks performance metrics automatically
- Identifies patterns in successes/failures
- Extracts meta-level insights
- Builds performance baselines

### 2. Self-Modification (with safety)
- Can improve command definitions
- Evolves orchestration strategies
- Refines specifications
- All changes logged and reversible

### 3. Self-Generation
- Creates new specs from patterns
- Generates improvement proposals
- Synthesizes evolved strategies
- Produces test cases

### 4. Self-Testing
- Automated validation suites
- Regression detection
- Integration testing
- Performance benchmarking

### 5. Self-Documentation
- Auto-updates README.md
- Maintains this CLAUDE.md file
- Generates architecture docs
- Tracks evolution history

### 6. Recursive Improvement
- Can improve /improve-self itself
- Meta-meta-prompting capability
- Improvements that improve improvements
- Continuous meta-level enhancement

## Safety Guardrails

### Self-Modification Safety

The system CAN modify itself, but with strict safeguards:

**Required Before Modification:**
- ✓ Complete analysis in `/improve-self`
- ✓ Backup of original version
- ✓ Clear rollback procedure
- ✓ Risk assessment
- ✓ Validation plan

**Automatic Safety Features:**
- All changes logged in `improvement_log/`
- Original versions preserved in `backups/`
- Rollback triggered if metrics regress >15%
- `/self-test` required before applying improvements
- Health monitoring in `system_health.json`

**Never Allowed:**
- Modifying core command structure without validation
- Applying high-risk changes without testing
- Skipping safety checks
- Deleting logs or backups
- Disabling health monitoring

### Testing and Validation

**Test Levels:**
- **Smoke** (5 min): Quick health check, critical paths only
- **Standard** (15-30 min): Full functionality validation
- **Comprehensive** (45-90 min): Deep validation with benchmarks

**When to Test:**
- After any command modification
- Before applying strategy evolution
- After every 10 waves in infinite mode
- When metrics show unexpected changes
- Before committing improvements

## Performance Metrics

### Tracked Continuously

```json
{
  "quality_avg": 8.0,        // Target: ≥8.0
  "efficiency": 0.85,         // Target: ≥0.85
  "diversity": 0.90,          // Target: ≥0.90
  "meta_awareness": 0.75,     // Target: ≥0.75
  "improvement_rate": 0.05    // Target: ≥5% per cycle
}
```

### Monitoring Location

Check `improvement_log/system_health.json` for current status:
- Overall health: healthy/degraded/critical
- Trend: improving/stable/declining
- Recent improvements applied
- Known issues
- Next recommended action

## Working with This System

### For Content Generation

```bash
# Use /infinite-meta with evolve mode
/infinite-meta specs/example_spec.md output/ 20 evolve
```

**What happens:**
1. Wave 1: Generate 5 iterations, collect metrics
2. Analyze: Review quality, identify patterns
3. Evolve: Improve strategy for wave 2
4. Wave 2: Generate 5 better iterations
5. Repeat: Continue improving through 4 waves

### For System Improvement

```bash
# Complete improvement cycle
/improve-self all deep              # Analyze deeply
/evolve-strategy quality incremental  # Apply improvements
/self-test all standard             # Validate changes
/self-document all standard         # Update docs
```

**What happens:**
1. Deep analysis of all components
2. Concrete improvement proposals generated
3. Strategy evolved incrementally
4. All changes validated through testing
5. Documentation updated to reflect new state

### For Creating New Capabilities

```bash
# Auto-generate new spec from patterns
/generate-spec patterns novel domain_name

# Test with small batch
/infinite-meta specs/domain_name.md test/ 5

# If good, run full batch
/infinite-meta specs/domain_name.md output/ 20 evolve
```

**What happens:**
1. System analyzes existing patterns
2. Synthesizes new specification
3. Creates companion files (guide, examples)
4. Tests with small generation batch
5. Validates and refines if needed

## Common Tasks

### Check System Health

```bash
/self-test all smoke  # 5-minute quick check
cat improvement_log/system_health.json  # View metrics
```

### Fix Quality Issues

```bash
/improve-self all standard
/evolve-strategy quality incremental
/self-test generation standard
```

### Update Documentation

```bash
/self-document all comprehensive  # Regenerate everything
```

### Add New Command

1. Create `.claude/commands/new-command.md`
2. Follow meta-prompting principles (structure-oriented)
3. Add self-improvement hooks
4. Include meta-awareness capabilities
5. Test: `/self-test commands standard`
6. Document: `/self-document commands standard`

## Advanced Features

### Pattern Library Evolution

`meta_prompts/` directory evolves automatically:
- Successful patterns added after each wave
- Ineffective patterns removed
- Abstract frameworks refined
- Meta-level insights accumulated

### Adaptive Optimization

System dynamically adjusts:
- Batch sizes based on context availability
- Strategy based on performance trends
- Quality thresholds based on domain
- Meta-awareness level based on complexity

### Recursive Self-Improvement

The system can improve itself recursively:
1. `/improve-self` analyzes the system
2. It can analyze `/improve-self` itself
3. Generates improvements to the analyzer
4. Applies those to make better analysis
5. Meta-meta-improvement achieved!

## Troubleshooting

### Quality Declining

**Symptoms:** Lower quality scores, more failures

**Diagnosis:**
```bash
/self-test generation standard
cat improvement_log/system_health.json
```

**Fix:**
```bash
/improve-self quality deep
/evolve-strategy quality incremental
/self-test all standard
```

### Documentation Outdated

**Symptoms:** README doesn't match current capabilities

**Fix:**
```bash
/self-document all comprehensive
```

### Command Not Working

**Symptoms:** Errors when running commands

**Diagnosis:**
```bash
/self-test commands comprehensive
```

**Fix:** Review test report in `improvement_log/test_report_*.md`

### Metrics Regressing

**Symptoms:** Performance worse than before

**Diagnosis:**
```bash
/self-test all standard
# Check for regression details
```

**Fix:**
```bash
# Rollback to previous strategy
# (instructions in improvement_log/evolved_strategy_*.md)
```

## Integration with Main Project

This variant can be:
- Used standalone for meta-aware generation
- Combined with other variants for enhanced capabilities
- Applied to improve other infinite loop systems
- Used as a meta-layer for any generation system

## References

- **Meta-Prompting Guide**: https://www.promptingguide.ai/techniques/meta-prompting
- **User Documentation**: README.md (auto-maintained)
- **Architecture Guide**: docs/self_improvement_guide.md
- **Improvement History**: improvement_log/
- **Pattern Library**: meta_prompts/

## Evolution Roadmap

**Current (v1.0.0):**
- All six core commands
- Basic meta-prompting
- Self-improvement loop
- Safety guardrails

**Near Future:**
- Enhanced pattern recognition
- Multi-domain learning
- Advanced meta-meta-prompting
- Autonomous goal setting

**Long Term:**
- ML-based pattern discovery
- Multi-agent meta-collaboration
- Self-optimizing context management
- Cross-system improvement propagation

---

*This CLAUDE.md file is auto-maintained by `/self-document`. It reflects the current system state and will be updated as the system evolves.*

**Meta-Note:** This file demonstrates meta-awareness by documenting its own auto-maintenance. When outdated, run `/self-document all comprehensive`.

**Last Updated:** 2025-10-10
**System Version:** 1.0.0
**Maintained By:** /self-document command