# CLAUDE.md

Project instructions for Claude Code when working in this repository.

## Project Overview

This is the **Cross-Iteration Pattern Synthesis System** - an infinite loop variant that implements cumulative learning across peer iterations using multi-shot prompting principles.

**Core Innovation**: After each wave of generation, the system extracts successful patterns from top iterations and uses them as concrete examples (multi-shot prompts) to guide subsequent waves. This creates a feedback loop where quality and consistency improve over time while preserving innovation.

## Primary Commands

### Generate Iterations with Pattern Synthesis

```bash
/project:infinite-synthesis <spec_file> <output_dir> <count|infinite> [pattern_library_path]
```

**Purpose**: Generate iterations using cumulative pattern learning from successful examples.

**Examples**:
```bash
# Generate 5 iterations
/project:infinite-synthesis specs/example_spec.md output 5

# Continuous generation
/project:infinite-synthesis specs/example_spec.md output infinite

# Use custom pattern library
/project:infinite-synthesis specs/example_spec.md output 10 pattern_library/custom.json
```

**How it works**:
1. Wave 1: Generate 5 iterations without pattern library (cold start)
2. Extract patterns from Wave 1 (top 20% become examples)
3. Wave 2: Generate 5 iterations WITH pattern library context
4. Extract patterns from all iterations, refine library
5. Repeat: Each wave improves based on cumulative learning

### Extract Patterns from Iterations

```bash
/project:extract-patterns <iterations_dir> <pattern_library_path> [analysis_depth]
```

**Purpose**: Analyze iterations to extract successful patterns for the pattern library.

**What it extracts**:
- **Structural patterns**: Architecture, organization, naming conventions
- **Content patterns**: Documentation, clarity, readability approaches
- **Innovation patterns**: Creative solutions, novel techniques
- **Quality patterns**: Error handling, validation, robustness

**Analysis depth**:
- `quick`: Top 3 patterns per category
- `deep`: Top 5 patterns per category (default)

### Analyze Pattern Effectiveness

```bash
/project:analyze-patterns <pattern_library_path> <iterations_dir>
```

**Purpose**: Measure how well the pattern library improves iteration quality.

**Metrics generated**:
- Pattern adoption rate (% using 1+ patterns)
- Quality improvement (pre-pattern vs post-pattern)
- Pattern effectiveness ranking
- Innovation preservation score

## Pattern Library

### Structure

Pattern library is a JSON file with this schema:

```json
{
  "version": "1.0",
  "last_updated": "2025-10-10T12:00:00Z",
  "total_iterations_analyzed": 10,
  "patterns": {
    "structural": [/* 3-5 patterns */],
    "content": [/* 3-5 patterns */],
    "innovation": [/* 3-5 patterns */],
    "quality": [/* 3-5 patterns */]
  },
  "metadata": {
    "extraction_date": "2025-10-10T12:00:00Z",
    "source_directory": "output/",
    "patterns_extracted": 12,
    "avg_quality_score": 8.4
  }
}
```

Each pattern contains:
- `name`: Short, descriptive name
- `description`: What the pattern achieves
- `example_file`: Path to iteration exemplifying this pattern
- `key_characteristics`: Array of 3-5 defining traits
- `success_metrics`: Why this pattern works
- `code_snippet`: Representative code example (5-15 lines)

### Pattern Quality Criteria

Patterns must be:
1. **Exemplary**: From top 20% of iterations by quality score
2. **Diverse**: Represent different approaches, not just variations
3. **Transferable**: Applicable to future iterations
4. **Clear**: Easy to understand and replicate
5. **Documented**: Include context about success factors

### Multi-Shot Prompting Integration

Based on [Anthropic's multi-shot prompting guide](https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/multishot-prompting):

- **3-5 Examples**: Each category maintains optimal example count
- **Consistency**: Examples demonstrate uniform structure and style
- **Edge Cases**: Innovation patterns cover unusual but effective approaches
- **Diversity**: Patterns prevent overfitting to single approach
- **Quality**: Only top 20% iterations become examples

## Validation

### Check Pattern Library

```bash
./validators/check_patterns.sh pattern_library/patterns.json
```

**Validates**:
- JSON syntax correctness
- Required fields present
- Pattern object structure
- Pattern count (3-5 per category)
- Code snippet coverage
- Success metrics completeness

### Expected Validation Output

```
Pattern Library Validation Script
==================================
✓ Valid JSON
✓ All required fields present
✓ Pattern categories complete
✓ Pattern objects valid
✓ High quality pattern library

Version: 1.2
Total patterns: 14
Quality score: 95% complete
```

## Quick Start Guide

### First-Time Usage

```bash
# 1. Generate initial iterations (Wave 1)
/project:infinite-synthesis specs/example_spec.md output 5

# 2. Pattern library is automatically created at pattern_library/patterns.json

# 3. View extracted patterns
cat pattern_library/patterns.json | jq '.patterns | keys'

# 4. Validate pattern library
./validators/check_patterns.sh pattern_library/patterns.json

# 5. Generate more iterations (Wave 2) - will use patterns from Wave 1
/project:infinite-synthesis specs/example_spec.md output 10

# 6. Analyze improvement
/project:analyze-patterns pattern_library/patterns.json output
```

### Continuing with Existing Pattern Library

```bash
# Use existing patterns to guide new generation
/project:infinite-synthesis specs/new_spec.md new_output 15

# Pattern library at pattern_library/patterns.json will be used
# Library will be updated with new patterns discovered
```

## Example Specification

See `specs/example_spec.md` for a complete specification demonstrating:
- How to structure requirements for pattern synthesis
- Example patterns that might be extracted
- Quality standards across waves
- Expected progression from Wave 1 to Wave 3+

The example generates interactive data visualizations showing pattern emergence across:
- Code organization (structural)
- Documentation approaches (content)
- Creative techniques (innovation)
- Error handling (quality)

## Key Principles

### When Working as Orchestrator Agent

You are managing the infinite synthesis loop. Follow these principles:

1. **Wave-Based Generation**
   - Wave 1: Generate without pattern library (cold start exploration)
   - Wave 2+: Include pattern library in sub-agent context

2. **Pattern Extraction After Each Wave**
   - Analyze ALL iterations (old + new)
   - Keep top 20% as exemplars
   - Maintain 3-5 patterns per category
   - Update library version

3. **Sub-Agent Context**
   - Provide 3-5 most relevant patterns from library
   - Include spec requirements
   - List existing iterations (avoid duplication)
   - Emphasize: patterns are examples, not constraints

4. **Quality Tracking**
   - Score each iteration (0-10 scale)
   - Track metrics: functionality, visual appeal, code quality, innovation, pattern adoption
   - Compare pre-pattern vs post-pattern averages

### When Working as Pattern Extraction Agent

You are extracting patterns from iterations. Follow these principles:

1. **Top 20% Only**
   - Score all iterations across multiple dimensions
   - Extract patterns only from highest-scoring iterations
   - Quality bar > quantity

2. **Diversity Over Similarity**
   - Choose patterns representing different approaches
   - Avoid multiple patterns that are slight variations
   - Cover structural, content, innovation, quality dimensions

3. **Concrete Examples**
   - Include actual code snippets (5-15 lines)
   - Reference specific iteration files
   - Provide measurable success metrics
   - List clear characteristics

4. **Library Curation**
   - Remove obsolete patterns when better ones emerge
   - Keep exactly 3-5 patterns per category
   - Increment version number
   - Update metadata

### When Working as Sub-Agent (Generating Iteration)

You are generating a single iteration with pattern library context. Follow these principles:

1. **Study Pattern Examples**
   - Review 3-5 patterns provided in your context
   - Understand WHY they work (success metrics)
   - Note key characteristics

2. **Apply Patterns Thoughtfully**
   - Don't copy verbatim - understand the principle
   - Adapt patterns to current specification
   - Combine multiple patterns where appropriate

3. **Add Novel Innovation**
   - Patterns are foundation, not ceiling
   - Introduce new ideas beyond pattern library
   - Your innovations may become patterns for next wave

4. **Maintain Quality Bar**
   - Pattern library sets minimum quality standard
   - Match or exceed quality of pattern examples
   - Ensure robustness, clarity, and functionality

## Expected Outcomes

### After 10 Iterations (2 Waves)
- Pattern library v1.1 created
- Quality improvement: +15-20%
- Consistency improvement: Variance reduced by ~40%
- Pattern adoption: 70-80%

### After 20 Iterations (4 Waves)
- Pattern library v1.3 refined
- Quality improvement: +20-25%
- Consistency improvement: Variance reduced by ~60%
- Pattern adoption: 85-90%
- Stable "house style" emerges

### After 50+ Iterations (10+ Waves)
- Pattern library v2.0+ mature
- Quality plateau at high level (8.5-9.0/10)
- Consistency: <10% variance
- Pattern adoption: 90%+
- Innovation: Still 3-5 new patterns per wave

## Comparison with Other Infinite Loops

### Base Infinite Loop
- **Strengths**: High diversity, exploration, creativity
- **Weaknesses**: Inconsistent quality, no learning between iterations
- **Use Case**: Initial exploration, maximum diversity

### Web-Enhanced Infinite Loop
- **Strengths**: Learns from external sources, web knowledge integration
- **Weaknesses**: Variable quality (depends on URLs), higher context usage
- **Use Case**: Learning new techniques, integrating web knowledge

### Pattern Synthesis Loop (This Variant)
- **Strengths**: Cumulative learning, improving consistency, efficient context usage
- **Weaknesses**: Requires minimum iterations for patterns (5+), potential convergence
- **Use Case**: Production-quality generation, consistent style, progressive improvement

## Advanced Usage

### Custom Pattern Libraries by Domain

Maintain separate pattern libraries for different content types:

```bash
# UI components
/project:infinite-synthesis specs/ui.md ui/ 10 patterns/ui_patterns.json

# Visualizations
/project:infinite-synthesis specs/viz.md viz/ 10 patterns/viz_patterns.json

# API endpoints
/project:infinite-synthesis specs/api.md api/ 10 patterns/api_patterns.json
```

### Learning from Existing Code

Extract patterns from existing codebase without generating new iterations:

```bash
# Extract patterns from legacy code
/project:extract-patterns legacy_code/ patterns/legacy_patterns.json deep

# Use those patterns for new generation
/project:infinite-synthesis specs/modernized.md new_code/ 15 patterns/legacy_patterns.json
```

### Manual Pattern Refinement

While patterns are auto-extracted, you can manually curate:

1. Generate and auto-extract patterns
2. Edit `pattern_library/patterns.json`:
   - Remove less effective patterns
   - Add custom patterns from other sources
   - Refine success metrics
   - Improve code snippets
3. Validate: `./validators/check_patterns.sh pattern_library/patterns.json`
4. Use refined library for next wave

## Troubleshooting

### Pattern Library Not Being Used

**Symptoms**: Iterations don't show pattern adoption, quality not improving

**Solutions**:
- Check pattern library path is correct
- Validate library: `./validators/check_patterns.sh`
- Ensure patterns have code snippets and clear characteristics
- Verify sub-agents receive pattern context

### Quality Not Improving

**Symptoms**: Post-pattern iterations score similar to pre-pattern

**Solutions**:
- Check pattern extraction is finding top 20% (not random)
- Ensure success metrics are clear and actionable
- Increase pattern count to 5 per category (deep analysis)
- Verify patterns are diverse and high-quality

### Pattern Library Too Large

**Symptoms**: Context budget filling up, slower generation

**Solutions**:
- Reduce to 3 patterns per category (quick analysis)
- Remove patterns with low adoption rates
- Keep only most effective patterns
- Archive old pattern versions

### Iterations Becoming Too Similar

**Symptoms**: Convergence, loss of creativity, repetitive outputs

**Solutions**:
- Emphasize innovation requirement in spec
- Include "anti-similarity" requirement
- Track unique innovations as separate metric
- Periodically inject random iterations without pattern context

## Files and Directories

```
.
├── .claude/
│   ├── commands/
│   │   ├── infinite-synthesis.md   # Main orchestrator (IMPORTANT)
│   │   ├── extract-patterns.md     # Pattern extraction logic
│   │   └── analyze-patterns.md     # Effectiveness analysis
│   └── settings.json               # Permissions
├── specs/
│   └── example_spec.md             # Example specification with pattern examples
├── validators/
│   └── check_patterns.sh           # Pattern library validator (executable)
├── pattern_library/
│   └── (patterns.json files generated here)
├── pattern_library_template.json   # Template + schema documentation
├── README.md                       # User-facing documentation
└── CLAUDE.md                       # This file - agent instructions
```

## Important Notes

### Context Management
- Pattern library adds ~2-3K tokens per wave
- Sub-agents receive filtered subset (3-5 most relevant patterns)
- Library size capped at 5 patterns/category to prevent bloat
- Infinite mode supports ~30+ waves before context limits

### Pattern Selection
- Only top 20% of iterations should become pattern examples
- Diversity > similarity when choosing patterns
- Success metrics must be specific and measurable
- Code snippets should be representative (not complete files)

### Quality vs Creativity Balance
- Patterns provide consistency, not constraints
- Innovation category explicitly rewards novelty
- Sub-agents should extend patterns, not just copy them
- Track innovation metrics to ensure creativity isn't suppressed

## Resources

- **Multi-Shot Prompting Guide**: https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/multishot-prompting
- **Pattern Template**: `pattern_library_template.json`
- **Example Spec**: `specs/example_spec.md`
- **Validation Script**: `validators/check_patterns.sh`

## Summary for Claude Code Agents

When working in this repository:

1. **Use `/project:infinite-synthesis`** to generate iterations with cumulative learning
2. **Patterns = Multi-shot examples** from top 20% of previous iterations
3. **3-5 patterns per category** is optimal (per research)
4. **Quality improves with each wave** through pattern guidance
5. **Innovation preserved** - patterns are foundation, not limitation
6. **Validate patterns** with `./validators/check_patterns.sh`
7. **Track effectiveness** with `/project:analyze-patterns`

**Core Principle**: The best teacher is a curated set of excellent examples from your own past work.