# Configuration Guide

Complete reference for the Configuration-Driven Infinite Loop Orchestration system.

## Table of Contents

1. [Introduction](#introduction)
2. [Configuration Architecture](#configuration-architecture)
3. [Configuration Sections Reference](#configuration-sections-reference)
4. [Profiles](#profiles)
5. [Chain Prompting Configuration](#chain-prompting-configuration)
6. [Validation](#validation)
7. [Examples](#examples)
8. [Best Practices](#best-practices)
9. [Troubleshooting](#troubleshooting)

## Introduction

The configuration system externalizes all orchestration parameters to JSON files, enabling:

- **Reproducibility**: Save and share configurations for consistent results
- **Flexibility**: Adjust any parameter without code changes
- **Quality**: Multi-stage validation ensures correctness
- **Scalability**: Different profiles optimize for different scales
- **Collaboration**: Team members can share and compare configurations

### Configuration Flow

```
User Command
    ↓
Load defaults.json
    ↓
Merge profile.json (if specified)
    ↓
Merge custom config (if provided)
    ↓
Apply inline overrides (if provided)
    ↓
Validate against schema
    ↓
Validate semantics
    ↓
Cross-field validation
    ↓
Execute with final config
```

## Configuration Architecture

### Hierarchical Merging

Configurations merge in this order (later overrides earlier):

1. **Defaults** (`.claude/config/defaults.json`)
   - Base configuration
   - Balanced settings for general use
   - All required fields present

2. **Profile** (`.claude/config/profiles/{profile}.json`)
   - Optional profile override
   - Optimized for specific use case
   - Only overrides necessary fields

3. **Custom File** (path provided in command)
   - User-specific configuration
   - Can override any field
   - Validated before merge

4. **Inline Overrides** (JSON string in command)
   - Runtime parameter changes
   - Highest priority
   - Useful for one-off adjustments

### Deep Merge Strategy

The merge is **deep** (property-level), not shallow (object-level):

```json
// Base
{
  "orchestration": {
    "max_parallel_agents": 3,
    "batch_size": 5
  }
}

// Override
{
  "orchestration": {
    "max_parallel_agents": 8
  }
}

// Result (max_parallel_agents overridden, batch_size preserved)
{
  "orchestration": {
    "max_parallel_agents": 8,
    "batch_size": 5
  }
}
```

## Configuration Sections Reference

### orchestration

Controls parallel execution and agent coordination.

```json
{
  "orchestration": {
    "max_parallel_agents": 3,
    "batch_size": 5,
    "infinite_mode_wave_size": 5,
    "context_budget_per_agent": 50000,
    "agent_timeout_ms": 300000,
    "enable_progressive_sophistication": true
  }
}
```

#### max_parallel_agents
- **Type**: integer
- **Range**: 1-10
- **Default**: 3
- **Description**: Maximum number of sub-agents running simultaneously
- **Impact**:
  - Higher = faster execution but more context usage
  - Lower = slower but more careful generation
- **Recommendations**:
  - Development: 2-3
  - Production: 5-8
  - Research: 3-4

#### batch_size
- **Type**: integer
- **Range**: 1-50
- **Default**: 5
- **Description**: Number of iterations per generation batch
- **Impact**:
  - Higher = fewer waves, more efficient
  - Lower = more waves, better control
- **Recommendations**:
  - Testing: 3-5
  - Production: 10-20
  - Large batches: 20-50

#### infinite_mode_wave_size
- **Type**: integer
- **Range**: 1-20
- **Default**: 5
- **Description**: Iterations per wave in infinite mode
- **Impact**: Controls wave boundaries for progressive sophistication
- **Recommendations**:
  - Should be multiple of max_parallel_agents for efficiency
  - Typical: 5-10

#### context_budget_per_agent
- **Type**: integer
- **Range**: 10000-200000
- **Default**: 50000
- **Description**: Token budget allocated to each sub-agent
- **Impact**:
  - Higher = more room for context, web content, examples
  - Lower = risk of context exhaustion
- **Recommendations**:
  - Simple tasks: 30000-50000
  - Complex tasks: 60000-100000
  - Web-enhanced: 80000-120000

#### agent_timeout_ms
- **Type**: integer
- **Range**: 30000-600000 (30 seconds to 10 minutes)
- **Default**: 300000 (5 minutes)
- **Description**: Maximum execution time for each agent
- **Impact**: Prevents stuck agents from blocking execution
- **Recommendations**:
  - Simple generation: 120000-180000 (2-3 minutes)
  - Complex generation: 300000-420000 (5-7 minutes)
  - With review stage: 420000-600000 (7-10 minutes)

#### enable_progressive_sophistication
- **Type**: boolean
- **Default**: true
- **Description**: Increase complexity and sophistication in later waves
- **Impact**: Creates learning curve in infinite mode
- **Use when**: Running infinite mode for progressive improvement

### generation

Controls output file creation and formatting.

```json
{
  "generation": {
    "output_directory": "output",
    "naming_pattern": "{theme}_{iteration:03d}_{variant}.html",
    "file_format": "html",
    "include_metadata": true,
    "metadata_format": "html_comment"
  }
}
```

#### output_directory
- **Type**: string
- **Default**: "output"
- **Description**: Directory for generated files (relative to project root)
- **Examples**: "output", "output_dev", "visualizations", "generated/batch1"

#### naming_pattern
- **Type**: string
- **Default**: "{theme}_{iteration:03d}_{variant}.html"
- **Description**: File naming pattern with placeholders
- **Placeholders**:
  - `{theme}` - Content theme (from spec or agent)
  - `{iteration}` - Iteration number
  - `{iteration:03d}` - Zero-padded to 3 digits (001, 002, etc.)
  - `{iteration:04d}` - Zero-padded to 4 digits (0001, 0002, etc.)
  - `{variant}` - Variant descriptor
  - `{timestamp}` - ISO timestamp
- **Examples**:
  - `viz_{iteration:04d}.html` → viz_0001.html, viz_0002.html
  - `{theme}_{timestamp}.html` → climate_2025-10-10T14:30:00Z.html
  - `output_{iteration}.html` → output_1.html, output_2.html

#### file_format
- **Type**: string
- **Enum**: html, markdown, json, text
- **Default**: html
- **Description**: Output file format
- **Impact**: Determines file extension and content structure

#### include_metadata
- **Type**: boolean
- **Default**: true
- **Description**: Embed generation metadata in output files
- **Impact**: Adds comments with iteration info, web sources, techniques used

#### metadata_format
- **Type**: string
- **Enum**: html_comment, yaml_frontmatter, json_header
- **Default**: html_comment
- **Description**: Format for embedded metadata
- **Examples**:
  - `html_comment`: `<!-- Metadata: ... -->`
  - `yaml_frontmatter`: `---\nkey: value\n---`
  - `json_header`: `/* { "key": "value" } */`

### quality

Controls quality standards and validation.

```json
{
  "quality": {
    "min_uniqueness_threshold": 0.85,
    "enable_validation": true,
    "enable_review_stage": false,
    "max_retry_attempts": 2,
    "require_spec_compliance_check": true
  }
}
```

#### min_uniqueness_threshold
- **Type**: number
- **Range**: 0.0-1.0
- **Default**: 0.85
- **Description**: Minimum required uniqueness score (0=identical, 1=completely unique)
- **Impact**: Controls iteration diversity
- **Recommendations**:
  - Permissive: 0.5-0.7 (allows similar variations)
  - Moderate: 0.7-0.85 (balanced uniqueness)
  - Strict: 0.85-0.95 (very unique)
  - Extreme: 0.95-1.0 (maximally unique)

#### enable_validation
- **Type**: boolean
- **Default**: true
- **Description**: Validate generated outputs against spec and config
- **Impact**: Catches errors, enforces quality, but adds execution time
- **Use when**: Quality is important, willing to trade time for correctness

#### enable_review_stage
- **Type**: boolean
- **Default**: false
- **Description**: Add chain prompting review stage after generation
- **Impact**:
  - Significantly improves quality (review + refine)
  - Increases execution time by 30-50%
  - Enables self-correction loops
- **Use when**: Maximum quality needed, time is not critical

#### max_retry_attempts
- **Type**: integer
- **Range**: 0-5
- **Default**: 2
- **Description**: Maximum retries for failed generations
- **Impact**: Improves success rate but increases total time
- **Recommendations**:
  - No retries: 0 (fail fast)
  - Normal: 2-3
  - Persistent: 4-5

#### require_spec_compliance_check
- **Type**: boolean
- **Default**: true
- **Description**: Validate outputs match specification requirements
- **Impact**: Ensures spec adherence, catches structural errors
- **Use when**: Spec has strict requirements

### web_enhancement

Controls web-based learning and content fetching.

```json
{
  "web_enhancement": {
    "enabled": false,
    "initial_priming_urls": 3,
    "urls_per_iteration": 1,
    "progressive_difficulty": true,
    "enable_web_search_fallback": true,
    "cache_web_content": false,
    "web_fetch_timeout_ms": 30000
  }
}
```

#### enabled
- **Type**: boolean
- **Default**: false
- **Description**: Enable web-enhanced generation with URL fetching
- **Impact**: Agents fetch web resources to inform generation
- **Use when**: Want to incorporate web knowledge, documentation, tutorials

#### initial_priming_urls
- **Type**: integer
- **Range**: 0-10
- **Default**: 3
- **Description**: Number of URLs to fetch during initial priming phase
- **Impact**: Builds foundational knowledge before generation starts
- **Recommendations**:
  - Quick start: 2-3
  - Moderate: 3-5
  - Comprehensive: 5-8
  - Maximum: 8-10

#### urls_per_iteration
- **Type**: integer
- **Range**: 0-5
- **Default**: 1
- **Description**: URLs to fetch per iteration during generation
- **Impact**: More URLs = more diverse learning but slower execution
- **Recommendations**:
  - Focused: 1
  - Balanced: 2
  - Diverse: 3-5

#### progressive_difficulty
- **Type**: boolean
- **Default**: true
- **Description**: Use progressive URL difficulty (foundation → expert)
- **Impact**: Early iterations use basic resources, later use advanced
- **Use when**: Want learning curve in generated content

#### enable_web_search_fallback
- **Type**: boolean
- **Default**: true
- **Description**: Use web search when pre-defined URLs exhausted
- **Impact**: Ensures continuous web learning in large batches
- **Use when**: Running many iterations, may exhaust URL list

#### cache_web_content
- **Type**: boolean
- **Default**: false
- **Description**: Cache fetched web content for reuse
- **Impact**:
  - Faster execution (no re-fetching)
  - Lower network usage
  - But may miss updated content
- **Use when**: Development, testing, same URLs used repeatedly

#### web_fetch_timeout_ms
- **Type**: integer
- **Range**: 5000-60000 (5-60 seconds)
- **Default**: 30000 (30 seconds)
- **Description**: Timeout for web fetch operations
- **Impact**: Prevents slow fetches from blocking execution
- **Recommendations**:
  - Fast resources: 10000-20000
  - Normal: 20000-30000
  - Slow/complex pages: 30000-45000

### logging

Controls logging verbosity and output.

```json
{
  "logging": {
    "level": "info",
    "log_agent_outputs": true,
    "log_web_fetches": true,
    "log_config_loading": true,
    "verbose": false
  }
}
```

#### level
- **Type**: string
- **Enum**: debug, info, warn, error
- **Default**: info
- **Description**: Minimum logging level
- **Levels**:
  - `debug`: All messages (very detailed)
  - `info`: Informational messages and above
  - `warn`: Warnings and errors only
  - `error`: Errors only
- **Recommendations**:
  - Development: debug
  - Testing: info
  - Production: warn or error

#### log_agent_outputs
- **Type**: boolean
- **Default**: true
- **Description**: Log what each sub-agent generates
- **Impact**: Useful for debugging but produces significant output
- **Use when**: Need to understand what agents are producing

#### log_web_fetches
- **Type**: boolean
- **Default**: true
- **Description**: Log web fetch operations and URLs
- **Impact**: Tracks web learning sources
- **Use when**: Need to audit web sources or debug fetch issues

#### log_config_loading
- **Type**: boolean
- **Default**: true
- **Description**: Log configuration loading and merging process
- **Impact**: Shows which configs loaded and how they merged
- **Use when**: Debugging configuration issues

#### verbose
- **Type**: boolean
- **Default**: false
- **Description**: Maximum verbosity (overrides level to debug)
- **Impact**: Extremely detailed output, use only for debugging
- **Use when**: Debugging complex issues, understanding system behavior

### chain_prompting

Controls chain prompting workflow execution.

```json
{
  "chain_prompting": {
    "enabled": true,
    "stages": [
      "load_config",
      "validate_config",
      "merge_config",
      "analyze_spec",
      "plan_execution",
      "execute_generation",
      "validate_output"
    ],
    "enable_self_correction": true,
    "pass_state_via_xml": true
  }
}
```

#### enabled
- **Type**: boolean
- **Default**: true
- **Description**: Enable chain prompting workflow
- **Impact**: Decomposes execution into focused stages
- **Recommendation**: Keep enabled for quality and traceability

#### stages
- **Type**: array of strings
- **Default**: 7 standard stages (see above)
- **Description**: Ordered list of workflow stages to execute
- **Customization**: Can add, remove, or reorder stages
- **Standard stages**:
  - `load_config` - Load configuration sources
  - `validate_config` - Validate against schema
  - `merge_config` - Merge configurations
  - `analyze_spec` - Analyze specification
  - `plan_execution` - Plan agent deployment
  - `execute_generation` - Run generation
  - `validate_output` - Validate results
- **Optional stages**:
  - `review_output` - Review generated content
  - `refine_output` - Refine based on review
  - `research_existing` - Research existing iterations
  - `analyze_results` - Analyze generation results

#### enable_self_correction
- **Type**: boolean
- **Default**: true
- **Description**: Enable self-correction loops when validation fails
- **Impact**: Improves quality through automatic retry and refinement
- **Use when**: Quality is priority, have retry budget

#### pass_state_via_xml
- **Type**: boolean
- **Default**: true
- **Description**: Pass state between stages using XML tags
- **Impact**: Provides clear state visibility and traceability
- **Recommendation**: Keep enabled for transparency

### features

Feature flags for optional capabilities.

```json
{
  "features": {
    "enable_url_strategy": true,
    "enable_theme_evolution": true,
    "enable_cross_iteration_learning": false,
    "enable_automatic_indexing": false
  }
}
```

#### enable_url_strategy
- **Type**: boolean
- **Default**: true
- **Description**: Support URL strategy JSON files for progressive web learning
- **Use when**: Using web enhancement with structured URL progression

#### enable_theme_evolution
- **Type**: boolean
- **Default**: true
- **Description**: Evolve themes and concepts across iterations
- **Impact**: Later iterations build on earlier themes
- **Use when**: Want thematic progression

#### enable_cross_iteration_learning
- **Type**: boolean
- **Default**: false
- **Description**: Enable learning from previous iterations' outputs
- **Impact**:
  - Improves quality through learning
  - Increases context usage
  - Slower execution
- **Use when**: Quality priority, have context budget

#### enable_automatic_indexing
- **Type**: boolean
- **Default**: false
- **Description**: Auto-generate index.html after each wave
- **Impact**: Creates navigation for generated files
- **Use when**: Want easy browsing of outputs

### limits

Safety limits to prevent runaway execution.

```json
{
  "limits": {
    "max_iterations": 100,
    "max_file_size_kb": 500,
    "max_total_output_mb": 50,
    "warn_at_iteration": 50
  }
}
```

#### max_iterations
- **Type**: integer
- **Minimum**: 1
- **Default**: 100
- **Description**: Maximum iterations before automatic stop
- **Impact**: Prevents infinite runaway in infinite mode
- **Recommendations**:
  - Testing: 10-20
  - Development: 20-50
  - Production: 100-1000
  - Research: 50-100

#### max_file_size_kb
- **Type**: integer
- **Minimum**: 10
- **Default**: 500
- **Description**: Maximum size per output file (KB)
- **Impact**: Catches unexpectedly large files
- **Recommendations**:
  - Simple HTML: 100-300 KB
  - Complex visualizations: 300-500 KB
  - Large datasets: 500-1000 KB

#### max_total_output_mb
- **Type**: integer
- **Minimum**: 1
- **Default**: 50
- **Description**: Maximum total output directory size (MB)
- **Impact**: Prevents disk space exhaustion
- **Recommendations**:
  - Testing: 10 MB
  - Development: 20-50 MB
  - Production: 50-200 MB

#### warn_at_iteration
- **Type**: integer
- **Minimum**: 1
- **Default**: 50
- **Description**: Show warning to user at this iteration number
- **Impact**: Prompts user to check progress
- **Use when**: Long-running batches, want checkpoints

## Profiles

### Development Profile

**File**: `.claude/config/profiles/development.json`

**Purpose**: Testing, debugging, learning

**Key Settings**:
- Small batches (3)
- Fewer agents (2)
- Verbose logging
- Review stage enabled
- Lower uniqueness (0.7)
- Conservative limits

**Use Cases**:
- Testing new specifications
- Debugging issues
- Learning system behavior
- Validating configurations

**Trade-offs**:
- Slower execution
- More detailed output
- Better for understanding
- Not efficient for scale

### Production Profile

**File**: `.claude/config/profiles/production.json`

**Purpose**: Scale, efficiency, throughput

**Key Settings**:
- Large batches (10)
- More agents (5)
- Minimal logging (warn)
- Review stage disabled
- High uniqueness (0.9)
- Generous limits (1000 iterations)

**Use Cases**:
- Production deployments
- Large batch generation
- Performance-critical tasks
- Well-tested specifications

**Trade-offs**:
- Less visibility
- Faster execution
- Assumes specs are correct
- May miss edge cases

### Research Profile

**File**: `.claude/config/profiles/research.json`

**Purpose**: Quality, exploration, experimentation

**Key Settings**:
- Medium batches (5)
- Moderate agents (3)
- Maximum logging (debug, verbose)
- Review stage enabled
- Very high uniqueness (0.95)
- Extended chain prompting (11 stages)
- Extensive web priming (8 URLs)

**Use Cases**:
- Exploring new domains
- Quality-critical work
- Understanding techniques
- Experimentation

**Trade-offs**:
- Slower execution
- Higher context usage
- Maximum quality
- Comprehensive analysis

## Chain Prompting Configuration

### Standard Workflow (7 Stages)

```json
{
  "chain_prompting": {
    "stages": [
      "load_config",
      "validate_config",
      "merge_config",
      "analyze_spec",
      "plan_execution",
      "execute_generation",
      "validate_output"
    ]
  }
}
```

**Execution Flow**:
1. Load all config sources
2. Validate against schema
3. Merge hierarchically
4. Analyze specification
5. Plan agent deployment
6. Execute generation
7. Validate outputs

**When to Use**: Default for most use cases

### Extended Workflow (With Review)

```json
{
  "chain_prompting": {
    "stages": [
      "load_config",
      "validate_config",
      "merge_config",
      "analyze_spec",
      "plan_execution",
      "execute_generation",
      "review_output",        // Added
      "validate_output"
    ]
  }
}
```

**Adds**: Review stage between generation and validation

**When to Use**: When quality > speed, have time/context budget

### Research Workflow (11 Stages)

```json
{
  "chain_prompting": {
    "stages": [
      "load_config",
      "validate_config",
      "merge_config",
      "analyze_spec",
      "research_existing",    // Added
      "plan_execution",
      "execute_generation",
      "review_output",        // Added
      "refine_output",        // Added
      "validate_output",
      "analyze_results"       // Added
    ]
  }
}
```

**Adds**: Research, review, refinement, analysis stages

**When to Use**: Maximum quality, understanding, experimentation

### Minimal Workflow (Speed)

```json
{
  "chain_prompting": {
    "stages": [
      "load_config",
      "merge_config",        // Skip validation
      "analyze_spec",
      "execute_generation"   // Skip planning, validation
    ]
  }
}
```

**Removes**: Validation, planning, output validation stages

**When to Use**: Trusted configs, maximum speed, disposable outputs

**Warning**: Less safe, may produce errors

## Validation

Configuration validation happens in three stages:

### 1. Schema Validation

Validates against `.claude/config/schema.json`:
- Type checking (string, integer, boolean, etc.)
- Required fields present
- Value constraints (min/max, enums)
- String patterns (regex)

**Example Errors**:
```
ERROR: orchestration.max_parallel_agents
  Expected: integer between 1 and 10
  Actual: 15
  Fix: Reduce to 10 or below
```

### 2. Semantic Validation

Validates logical consistency:
- `batch_size` <= `max_iterations`
- `agent_timeout_ms` > `web_fetch_timeout_ms`
- `context_budget_per_agent` reasonable
- Output paths valid

**Example Warnings**:
```
WARNING: orchestration.max_parallel_agents = 10
  Impact: Very high parallelism may cause performance issues
  Recommendation: Consider 5-8 for better stability
```

### 3. Cross-Field Validation

Validates relationships between sections:
- Orchestration vs Quality (review stage vs timeout)
- Orchestration vs Limits (wave size vs max iterations)
- Web Enhancement vs Orchestration (URLs vs timeout)
- Logging vs Performance (verbose + large batch)

**Example Issues**:
```
WARNING: Cross-field issue
  Fields: orchestration.max_parallel_agents (5)
          orchestration.infinite_mode_wave_size (20)
          limits.max_iterations (50)
  Issue: May exceed max_iterations in 3 waves
  Recommendation: Reduce wave_size to 10
```

### Validation Commands

**Validate Configuration**:
```bash
/project:validate-config [config_path] [profile]
```

**Examples**:
```bash
# Validate defaults
/project:validate-config

# Validate profile
/project:validate-config development

# Validate custom config
/project:validate-config examples/custom_config.json

# Validate merged config (development + custom)
/project:validate-config examples/custom_config.json development
```

## Examples

### Example 1: Simple Override

Start with defaults, change one parameter:

```bash
/project:infinite-config specs/example_spec.md output 5 '{"orchestration":{"max_parallel_agents":6}}'
```

**Result**: Uses defaults except `max_parallel_agents = 6`

### Example 2: Profile + Override

Use production profile, add verbose logging:

```bash
/project:infinite-config specs/example_spec.md output 20 production '{"logging":{"verbose":true}}'
```

**Result**: Production settings + verbose logging

### Example 3: Custom Config File

Create `my_config.json`:
```json
{
  "orchestration": {
    "max_parallel_agents": 4,
    "batch_size": 8
  },
  "quality": {
    "min_uniqueness_threshold": 0.88,
    "enable_review_stage": true
  },
  "web_enhancement": {
    "enabled": true,
    "initial_priming_urls": 5
  }
}
```

Use it:
```bash
/project:infinite-config specs/example_spec.md output 20 custom my_config.json
```

### Example 4: Development → Production

Test with development:
```bash
/project:infinite-config specs/example_spec.md test 5 development
```

Verify quality, then scale with production:
```bash
/project:infinite-config specs/example_spec.md prod 100 production
```

### Example 5: Speed Optimization

Create speed config:
```json
{
  "orchestration": {
    "max_parallel_agents": 10,
    "batch_size": 50
  },
  "quality": {
    "enable_validation": false,
    "enable_review_stage": false
  },
  "logging": {
    "level": "error"
  },
  "web_enhancement": {
    "enabled": false
  }
}
```

Or use command:
```bash
/project:configure optimize speed
```

### Example 6: Quality Optimization

Create quality config:
```json
{
  "orchestration": {
    "max_parallel_agents": 2
  },
  "quality": {
    "min_uniqueness_threshold": 0.95,
    "enable_validation": true,
    "enable_review_stage": true,
    "max_retry_attempts": 5
  },
  "web_enhancement": {
    "enabled": true,
    "initial_priming_urls": 8,
    "urls_per_iteration": 3
  },
  "logging": {
    "level": "debug",
    "verbose": true
  },
  "chain_prompting": {
    "stages": [
      "load_config",
      "validate_config",
      "merge_config",
      "analyze_spec",
      "research_existing",
      "plan_execution",
      "execute_generation",
      "review_output",
      "refine_output",
      "validate_output"
    ]
  }
}
```

Or use command:
```bash
/project:configure optimize quality
```

## Best Practices

### 1. Start with Profiles

Don't create configs from scratch. Use profiles as base:
- Development for testing
- Production for scale
- Research for quality

Then customize with overrides or custom files.

### 2. Validate Before Running

Always validate configurations:
```bash
/project:validate-config my_config.json
```

Fix errors before executing generations.

### 3. Test Small, Scale Up

Test with small batches first:
```bash
# Test with 3 iterations
/project:infinite-config specs/spec.md test 3 my_config.json

# If good, scale up
/project:infinite-config specs/spec.md prod 50 my_config.json
```

### 4. Use Inline Overrides for One-Off Changes

Don't create new config file for single parameter:
```bash
# Good: inline override
/project:infinite-config specs/spec.md output 5 production '{"logging":{"verbose":true}}'

# Less good: new config file for one change
```

### 5. Document Custom Configs

Add comments (not in JSON, but in adjacent README):
```
my_config.json - Custom config for D3 visualizations
  - 4 parallel agents for balance
  - 0.88 uniqueness for moderate diversity
  - Review stage enabled for quality
  - 5 priming URLs for D3 techniques
```

### 6. Version Control Configs

Keep configurations in version control:
```bash
git add .claude/config/profiles/
git add examples/custom_configs/
git commit -m "Add custom D3 visualization config"
```

### 7. Compare Configs Before Changing

When modifying configs, compare first:
```bash
/project:configure compare current.json proposed.json
```

Understand differences before switching.

### 8. Monitor Resource Usage

Watch these metrics:
- Context budget consumption
- Output directory size
- Execution time
- Success/failure rate

Adjust config if issues arise.

### 9. Profile by Use Case

Create profiles for common scenarios:
- `d3_viz_config.json` - D3 visualizations
- `network_graph_config.json` - Network graphs
- `quick_test_config.json` - Fast testing
- `max_quality_config.json` - Quality-critical

### 10. Set Appropriate Limits

Configure limits based on use case:

**Testing**:
- `max_iterations`: 10-20
- `max_total_output_mb`: 10 MB
- `warn_at_iteration`: 5

**Production**:
- `max_iterations`: 100-1000
- `max_total_output_mb`: 50-100 MB
- `warn_at_iteration`: 100

**Research**:
- `max_iterations`: 50-100
- `max_total_output_mb`: 50 MB
- `warn_at_iteration`: 25

## Troubleshooting

### Problem: Configuration validation fails

**Symptoms**: Errors when running `/project:validate-config`

**Solutions**:
1. Check error messages for specific field issues
2. Compare to working profile configurations
3. Verify values against schema.json
4. Use `/project:configure edit` to fix interactively

**Example**:
```
ERROR: orchestration.max_parallel_agents: 15 exceeds maximum (10)
Fix: Change to 10 or below
```

### Problem: Execution too slow

**Symptoms**: Generations take too long

**Solutions**:
1. Increase `max_parallel_agents` (up to 10)
2. Disable `enable_review_stage`
3. Reduce `logging.level` to `warn` or `error`
4. Disable `web_enhancement` if not needed
5. Increase `batch_size`

**Speed Config**:
```json
{
  "orchestration": {"max_parallel_agents": 10, "batch_size": 20},
  "quality": {"enable_review_stage": false},
  "logging": {"level": "warn"},
  "web_enhancement": {"enabled": false}
}
```

### Problem: Outputs too similar

**Symptoms**: Iterations not unique enough

**Solutions**:
1. Increase `quality.min_uniqueness_threshold`
2. Enable `features.enable_theme_evolution`
3. Check spec for diversity requirements
4. Review existing iterations for patterns

**Example**:
```json
{
  "quality": {
    "min_uniqueness_threshold": 0.9
  },
  "features": {
    "enable_theme_evolution": true
  }
}
```

### Problem: Web fetches failing

**Symptoms**: Web enhancement not working

**Solutions**:
1. Increase `web_enhancement.web_fetch_timeout_ms`
2. Enable `web_enhancement.enable_web_search_fallback`
3. Reduce `web_enhancement.urls_per_iteration`
4. Enable `web_enhancement.cache_web_content`
5. Check URLs are accessible

**Example**:
```json
{
  "web_enhancement": {
    "web_fetch_timeout_ms": 45000,
    "enable_web_search_fallback": true,
    "cache_web_content": true
  }
}
```

### Problem: Context budget exhaustion

**Symptoms**: Agents running out of context

**Solutions**:
1. Increase `orchestration.context_budget_per_agent`
2. Reduce `web_enhancement.initial_priming_urls`
3. Reduce `web_enhancement.urls_per_iteration`
4. Disable `features.enable_cross_iteration_learning`
5. Reduce number of chain prompting stages

**Example**:
```json
{
  "orchestration": {
    "context_budget_per_agent": 100000
  },
  "web_enhancement": {
    "initial_priming_urls": 2,
    "urls_per_iteration": 1
  }
}
```

### Problem: Quality issues

**Symptoms**: Outputs don't meet standards

**Solutions**:
1. Enable `quality.enable_review_stage`
2. Increase `quality.min_uniqueness_threshold`
3. Enable `quality.require_spec_compliance_check`
4. Increase `quality.max_retry_attempts`
5. Use research profile
6. Add review/refine stages to chain prompting

**Quality Config**:
```json
{
  "quality": {
    "min_uniqueness_threshold": 0.95,
    "enable_validation": true,
    "enable_review_stage": true,
    "max_retry_attempts": 5
  },
  "chain_prompting": {
    "stages": [
      "load_config", "validate_config", "merge_config",
      "analyze_spec", "plan_execution", "execute_generation",
      "review_output", "refine_output", "validate_output"
    ]
  }
}
```

### Problem: File size issues

**Symptoms**: Files too large or hitting limits

**Solutions**:
1. Adjust `limits.max_file_size_kb`
2. Check spec requirements
3. Review generated files
4. Modify spec to constrain size

**Example**:
```json
{
  "limits": {
    "max_file_size_kb": 1000,
    "max_total_output_mb": 100
  }
}
```

## Advanced Topics

### Custom Chain Prompting Stages

Add custom stages to workflow:

```json
{
  "chain_prompting": {
    "stages": [
      "load_config",
      "validate_config",
      "merge_config",
      "analyze_spec",
      "research_domain",        // Custom: research domain knowledge
      "plan_execution",
      "execute_generation",
      "peer_review",            // Custom: peer review between agents
      "validate_output",
      "generate_report"         // Custom: generate analysis report
    ]
  }
}
```

### Progressive Sophistication Curves

Configure sophistication progression:

```json
{
  "orchestration": {
    "enable_progressive_sophistication": true,
    "infinite_mode_wave_size": 10
  },
  "progressive_curves": {
    "wave_1": "basic",       // Iterations 1-10
    "wave_2": "intermediate", // Iterations 11-20
    "wave_3": "advanced",    // Iterations 21-30
    "wave_4": "expert"       // Iterations 31+
  }
}
```

### Dynamic Configuration Adjustment

Adjust configuration based on execution metrics:

```json
{
  "adaptive": {
    "enabled": true,
    "adjust_parallel_agents_based_on_success_rate": true,
    "reduce_batch_size_on_timeout": true,
    "increase_retries_on_quality_issues": true
  }
}
```

### Multi-Spec Orchestration

Run multiple specs with shared config:

```json
{
  "multi_spec": {
    "enabled": true,
    "specs": [
      "specs/d3_viz.md",
      "specs/network_graph.md",
      "specs/timeline.md"
    ],
    "output_directories": [
      "output/d3",
      "output/network",
      "output/timeline"
    ]
  }
}
```

## Conclusion

The configuration system provides complete control over infinite loop orchestration:

1. **Use profiles** as starting points
2. **Validate configurations** before running
3. **Test small** before scaling up
4. **Monitor resources** during execution
5. **Document custom configs** for reproducibility
6. **Version control** configurations
7. **Optimize** for your specific use case

For more information:
- See `README.md` for overview
- See `CLAUDE.md` for usage instructions
- See command documentation in `.claude/commands/`
- See schema reference in `.claude/config/schema.json`