infinite-agents-public/infinite_variants/infinite_variant_3/README.md

# Infinite Loop Variant 3: Pluggable Agent Task Templates

A template-based infinite loop system that orchestrates parallel AI agents using reusable, parameterized task blueprints.

## Overview

This variant introduces **pluggable agent task templates** - a systematic approach to defining reusable agent behaviors through parameterized markdown blueprints. Instead of hardcoding agent instructions, this system loads templates, substitutes parameters, and deploys agents with complete, unambiguous instructions.

### Key Innovation

**Templates as Contracts:** Each template is a complete specification of how an agent should perform a specific type of task. The orchestrator loads the template, fills in parameters for each iteration, and deploys agents with fully instantiated instructions - treating each agent as a "brilliant but new employee" (following Anthropic's prompt engineering best practices).

## Quick Start

### 1. Web-Enhanced Generation (5 iterations)

```bash
/infinite-templated web-research-generator specs/example_spec.md viz_output 5 params/viz_params.json
```

Generates 5 visualizations, each learning from a different web resource.

### 2. Pure Code Generation (10 iterations)

```bash
/infinite-templated code-generator specs/example_spec.md viz_output 10
```

Generates 10 unique visualizations using creative variation without web research.

### 3. Infinite Mode (continuous until context limits)

```bash
/infinite-templated web-research-generator specs/example_spec.md viz_output infinite params/url_strategy.json
```

Runs in waves of 5 iterations until context budget exhausted.

### 4. Create Your Own Template

```bash
/create-template my-template-name generation "Description of what it does"
```

Interactive process guides you through creating a new template.

## System Architecture

### Directory Structure

```
infinite_variant_3/
├── .claude/
│   ├── commands/
│   │   ├── infinite-templated.md    # Main orchestrator command
│   │   └── create-template.md       # Template creation utility
│   ├── templates/
│   │   ├── base-template.md         # Template for making templates
│   │   ├── web-research-generator.md
│   │   ├── code-generator.md
│   │   ├── analyzer.md
│   │   └── validator.md
│   └── settings.json
├── specs/
│   ├── example_spec.md              # Example visualization spec
│   └── template_spec.md             # Spec for creating templates
├── docs/
│   └── template_guide.md            # How to create/use templates
├── examples/
│   └── template_usage.md            # Concrete usage examples
└── README.md
```

### Core Concepts

**1. Template System**
- Templates are markdown files in `.claude/templates/`
- Use `{{PARAMETER}}` placeholders for customization
- Follow strict structure (see `specs/template_spec.md`)
- Based on "be clear and direct" prompt engineering principles

**2. Parameter Substitution**
- Orchestrator loads template and spec
- For each iteration, creates parameter mapping
- Replaces all `{{PARAMETER}}` placeholders with values
- Result is complete, ready-to-execute agent task

**3. Parallel Agent Deployment**
- Each agent receives fully instantiated template
- Agents work independently (no inter-agent communication)
- Orchestrator manages coordination and batching
- Results collected after parallel execution

**4. Template Categories**
- **generation**: Create new artifacts
- **analysis**: Analyze and extract insights
- **quality-assurance**: Validate and verify
- **research**: Gather and apply information
- **testing**: Execute tests
- **documentation**: Create/update docs

## Available Templates

### web-research-generator

Fetches web resources, extracts techniques, applies learning to generate artifacts.

**Use Cases:**
- Progressive learning from documentation
- Tutorial-driven development
- Best practice implementation
- Technique discovery and application

**Key Parameters:**
- `WEB_URL`: URL to fetch and learn from
- `LEARNING_FOCUS`: What to extract from URL
- `MIN_TECHNIQUES`: Minimum techniques to apply
- `OUTPUT_DIR`: Where to write generated file

**Example:**
```json
{
  "WEB_URL": "https://d3js.org/d3-force",
  "LEARNING_FOCUS": "Force simulation physics",
  "MIN_TECHNIQUES": 2,
  "OUTPUT_DIR": "viz_output"
}
```

### code-generator

Pure code generation based on specifications without web dependencies.

**Use Cases:**
- Iteration-based variations
- Component creation
- Theme-based implementations
- Creative coding

**Key Parameters:**
- `THEME`: Unique theme for iteration
- `UNIQUE_FEATURES`: What makes this unique
- `OUTPUT_DIR`: Where to write file
- `SPEC_FILE`: Specification to follow

**Example:**
```json
{
  "THEME": "bioluminescent ocean",
  "UNIQUE_FEATURES": "Glow effects, wave animations",
  "OUTPUT_DIR": "components"
}
```

### analyzer

Analyzes artifacts to extract patterns, metrics, and insights.

**Use Cases:**
- Code quality analysis
- Pattern detection
- Performance assessment
- Trend identification

**Key Parameters:**
- `TARGET_PATTERN`: Files to analyze (glob)
- `CRITERIA_FILE`: Analysis criteria
- `METRICS`: Metrics to collect
- `OUTPUT_FILE`: Report destination

**Example:**
```json
{
  "TARGET_PATTERN": "viz_output/*.html",
  "METRICS": "LOC, complexity, uniqueness score",
  "OUTPUT_FILE": "reports/analysis.md"
}
```

### validator

Validates artifacts against requirements and standards.

**Use Cases:**
- Specification compliance checking
- Quality validation
- Standard adherence verification
- Pre-deployment checks

**Key Parameters:**
- `VALIDATION_SPEC`: Validation rules
- `TARGET_PATTERN`: Files to validate
- `CRITERIA_LIST`: Specific criteria
- `OUTPUT_FILE`: Report destination

**Example:**
```json
{
  "VALIDATION_SPEC": "specs/validation_rules.md",
  "TARGET_PATTERN": "viz_output/*.html",
  "OUTPUT_FILE": "reports/validation.md"
}
```

## How It Works

### Orchestration Flow

```
1. Load Template
   ↓
2. Load Specification
   ↓
3. Analyze Existing Iterations
   ↓
4. For Each Iteration:
   - Create parameter set
   - Substitute into template
   - Verify uniqueness
   ↓
5. Deploy Agents in Parallel
   ↓
6. Collect Results
   ↓
7. (If infinite) Launch Next Wave
```

### Parameter Substitution Example

**Template (excerpt):**
```markdown
### Step 1: Fetch Web Resource
Use WebFetch with URL: `{{WEB_URL}}`
Focus on: `{{LEARNING_FOCUS}}`
Extract minimum {{MIN_TECHNIQUES}} techniques.
```

**After Substitution:**
```markdown
### Step 1: Fetch Web Resource
Use WebFetch with URL: `https://d3js.org/d3-force`
Focus on: `Force simulation physics and node positioning`
Extract minimum 2 techniques.
```

## Creating Custom Templates

### Step 1: Use Template Creation Command

```bash
/create-template my-template category "Description"
```

The command guides you through:
1. Requirements gathering
2. Structure design
3. Parameter definition
4. Instruction writing
5. Documentation

### Step 2: Follow Template Spec

See `specs/template_spec.md` for complete requirements:
- Required sections (11 total)
- Parameter naming conventions
- Instruction writing guidelines
- Quality standards

### Step 3: Apply "Be Clear and Direct" Principles

Templates follow Anthropic's prompt engineering guidance:
- Provide complete context
- Use explicit, step-by-step instructions
- Define success criteria clearly
- Treat agent as capable but uninformed
- Show examples

### Step 4: Test and Iterate

- Mentally walk through as if you're the agent
- Verify no ambiguous instructions
- Check all parameters documented
- Test with actual execution

## Design Philosophy

### Based on Anthropic's "Be Clear and Direct"

This system embodies prompt engineering best practices:

1. **Contextual Clarity**
   - Templates explain task purpose
   - Define workflow position
   - Specify success criteria

2. **Explicit Instructions**
   - Numbered, sequential steps
   - Specific about outputs
   - Clear constraints

3. **New Employee Metaphor**
   - Explain norms and styles
   - Provide examples
   - Don't assume knowledge

4. **Precision**
   - Exact language
   - No ambiguity
   - All terms defined

### Template Benefits

**Reusability**: Write once, use for unlimited iterations
**Consistency**: All agents follow same structure
**Clarity**: No ambiguous instructions
**Flexibility**: Parameters enable wide variation
**Composability**: Templates can reference other templates
**Maintainability**: Update template, all uses improve

## Advanced Usage

### Custom Parameter Files

Create JSON file with parameters:

```json
{
  "PROJECT_NAME": "My Project",
  "PROJECT_DESCRIPTION": "Description here",
  "MIN_TECHNIQUES": 3,
  "URL_STRATEGY": {
    "foundation": ["url1", "url2"],
    "intermediate": ["url3", "url4"],
    "advanced": ["url5", "url6"]
  },
  "CUSTOM_PARAM": "value"
}
```

Use with command:
```bash
/infinite-templated template-name spec.md output_dir 10 params.json
```

### Template Composition

Templates can reference other templates:

```markdown
**Step 3:** Execute validation using validator template
See `.claude/templates/validator.md` for validation process.
```

### Progressive URL Strategy

For web-research-generator, provide URL progression:

```json
{
  "URL_STRATEGY": {
    "foundation": [
      "Getting started guides",
      "Basic tutorials"
    ],
    "intermediate": [
      "Advanced tutorials",
      "API documentation"
    ],
    "advanced": [
      "Techniques articles",
      "Performance guides"
    ],
    "expert": [
      "Advanced patterns",
      "Optimization guides"
    ]
  }
}
```

System assigns URLs based on iteration sophistication level.

## Examples

See `examples/template_usage.md` for detailed examples:
- Web-enhanced visualization generation
- Code-based component creation
- Quality analysis workflow
- Validation pipeline
- Custom template creation

## Documentation

- **README.md** (this file): System overview and quick start
- **CLAUDE.md**: Project instructions for Claude Code
- **docs/template_guide.md**: How to create and use templates
- **specs/example_spec.md**: Example specification
- **specs/template_spec.md**: Requirements for creating templates
- **examples/template_usage.md**: Concrete usage examples

## Key Features

✅ **Pluggable Templates**: Reusable task blueprints
✅ **Parameter Substitution**: Flexible customization
✅ **Parallel Execution**: Multiple agents simultaneously
✅ **Web Learning**: Progressive knowledge from web sources
✅ **Quality Assurance**: Built-in validation templates
✅ **Template Creation**: Tools to create new templates
✅ **Infinite Mode**: Continuous generation in waves
✅ **Clear Instructions**: Based on prompt engineering best practices

## Comparison with Other Variants

**vs. Original Infinite Loop:**
- Original: Hardcoded agent instructions
- This: Reusable template system

**vs. Web-Enhanced Loop:**
- Web-Enhanced: Web learning hardcoded into command
- This: Web learning as one template option

**vs. Pipeline Variant:**
- Pipeline: Sequential stages
- This: Parallel agents with flexible templates

**Unique Value:** Maximum flexibility through template pluggability while maintaining clarity through structured instructions.

## Contributing

To add new templates:
1. Use `/create-template` command
2. Follow `specs/template_spec.md`
3. Test with real execution
4. Document in `docs/template_guide.md`
5. Add example to `examples/template_usage.md`

## License

Part of the Infinite Agents experimental project.

---

**Web Source:** https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/be-clear-and-direct
**Learning Applied:**
1. **Clear role definitions** - Each template defines agent role explicitly
2. **Step-by-step instructions** - All templates use numbered, sequential steps
3. **Context provision** - Templates explain task purpose, workflow position, success criteria
4. **"New employee" approach** - Templates don't assume knowledge, explain everything
5. **Explicit outputs** - Every step specifies expected output

**Generated:** 2025-10-10
**Iteration:** 3 of Infinite Loop Variants