jeffemmett
/
infinite-agents-public
mirror of https://github.com/Jeff-Emmett/infinite-agents-public.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
infinite-agents-public/infinite_variants/infinite_variant_6/CLAUDE.md

11 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code when working with the Stateful Infinite Loop variant.

Project Overview

This is a variant of the Infinite Agentic Loop pattern that adds robust state management with self-consistency validation. The system enables resumable, auditable, and deduplication-guaranteed infinite loop execution.

Key Innovation

Applies self-consistency prompting (multiple sampling + majority voting) to state validation:

  • 6 independent validation checks verify state integrity
  • Majority voting produces consistency score (0.0-1.0)
  • High-confidence validation even if individual checks have edge cases
  • Proven AI technique adapted to state management

Key Commands

Running Stateful Infinite Loops

claude

Then use these commands:

/infinite-stateful

Main orchestration command with state management.

# Basic usage
/infinite-stateful <spec_path> <output_dir> <count> [url_strategy] [run_id]

# Examples:
/infinite-stateful specs/example_spec.md outputs 5
/infinite-stateful specs/example_spec.md outputs 10 specs/urls.json
/infinite-stateful specs/example_spec.md outputs infinite specs/urls.json
/infinite-stateful specs/example_spec.md outputs infinite specs/urls.json run_20250310_143022

Features:

  • Persistent state in .claude/state/run_*.json
  • Automatic URL deduplication
  • Self-consistency validation
  • Graceful interruption handling
  • Resume capability

/status

View run status and validate consistency.

# List all runs
/status

# Detailed status for specific run
/status run_20250310_143022

Output:

  • Run information (spec, progress, timing)
  • Self-consistency validation (6 checks + score)
  • Recent iterations
  • Resumability status
  • URL usage summary

/resume

Resume interrupted run.

/resume <run_id>

Process:

  1. Validates state consistency
  2. Loads original parameters
  3. Continues from last completed iteration
  4. No duplicate URLs or iterations

/reset-state

State management utilities.

# Verify state integrity
/reset-state <run_id>

# Rebuild state from files
/reset-state <run_id> --rebuild

# Delete state (with backup)
/reset-state <run_id> --delete

Architecture & Structure

Command System

.claude/commands/:

  • infinite-stateful.md - Main orchestration with state management
  • resume.md - Resume interrupted runs
  • status.md - View and validate run status
  • reset-state.md - State management utilities

.claude/settings.json:

  • Permissions: Write, Edit, Read, Bash, Task, WebFetch, WebSearch
  • Custom instructions for state management

State Management

.claude/state/:

  • run_*.json - Individual run state files
  • README.md - State system documentation

State File Structure:

{
  "run_id": "run_YYYYMMDD_HHMMSS",
  "spec_path": "specs/example_spec.md",
  "output_dir": "outputs",
  "total_count": 10,
  "status": "in_progress",
  "completed_iterations": 3,
  "iterations": [...],
  "used_urls": [...],
  "validation": {
    "consistency_score": 1.0,
    "issues": []
  }
}

Specification System

specs/:

  • example_spec.md - Example specification with state integration
  • Custom specs can be added

Spec Requirements:

  • Output file naming pattern
  • Content structure
  • Quality standards
  • Web learning integration
  • Metadata embedding (required for state tracking)

Utility Files

  • state_manager.py - Python utilities for state operations
  • validators/check_state_consistency.sh - Bash validation script
  • templates/ - State, URL tracker, and iteration templates
  • docs/state_management_guide.md - Complete usage guide

State Management Principles

1. Single Source of Truth

State file is authoritative:

  • File system is secondary
  • State determines what exists
  • Validation checks consistency

2. Self-Consistency Validation

6 independent checks with majority voting:

  1. Schema validation
  2. File count matching
  3. Iteration record consistency
  4. URL uniqueness
  5. File existence
  6. Timestamp validity

Consistency Score = (passed checks) / 6

  • ≥0.8: State is reliable
  • 0.5-0.79: Warnings
  • <0.5: Corrupted

3. Deduplication Guarantee

  • All URLs tracked in used_urls
  • URL strategy filtered against used URLs
  • Fallback to web search for new URLs
  • Iteration numbers never collide

4. Resumability

  • Any run can resume by run_id
  • State tracks exact progress point
  • Graceful handling of interruptions
  • No re-generation of completed iterations

5. Atomicity

  • State updates are atomic (temp + rename)
  • Prevents corruption from partial writes
  • Safe concurrent reads
  • Single writer at a time

6. Auditability

  • Complete iteration history
  • Timestamped state changes
  • URL tracking
  • Validation results

Implementation Details

State Updates

After each batch completion:

  1. Load current state
  2. Add iteration records
  3. Update completion counters
  4. Add URLs to used list
  5. Update timestamp
  6. Save atomically (temp + rename)

Self-Consistency Validation

Between batches and at resume:

  1. Run 6 independent checks
  2. Each check returns pass/fail
  3. Compute consistency score
  4. If score < 0.8, pause and report
  5. User decides: continue, fix, or abort

URL Deduplication

For each iteration:

  1. Load URL strategy
  2. Filter out URLs in state.used_urls
  3. Select next available URL
  4. If exhausted, fallback to web search
  5. Add used URL to state

Resume Process

  1. Locate state file by run_id
  2. Validate state consistency (pre-check)
  3. Extract original parameters
  4. Determine next iteration number
  5. Continue generation
  6. Validate state consistency (post-check)

Rebuild Process

When state corrupted:

  1. Scan output directory
  2. Extract iteration numbers from filenames
  3. Read metadata from files (if embedded)
  4. Reconstruct iteration records
  5. Compute file hashes
  6. Deduplicate URLs
  7. Create new state file
  8. Validate rebuilt state

Usage Patterns

Pattern 1: Long-Running Generation

# Start
/infinite-stateful specs/viz.md outputs 100

# ... interrupted after 47 ...
# State auto-saved

# Resume
/resume run_20250310_143022
# Continues from 48

Pattern 2: Infinite Mode

# Start infinite
/infinite-stateful specs/viz.md outputs infinite specs/urls.json

# ... hits context limit ...
# State saved

# New session
/resume run_20250310_143022
# Continues indefinitely

Pattern 3: State Recovery

# Check
/status run_20250310_143022
# Score: 0.67 (WARNING)

# Rebuild
/reset-state run_20250310_143022 --rebuild

# Verify
/status run_20250310_143022
# Score: 1.00 (CONSISTENT)

Best Practices

For Claude Code Users

State Management:

  • Let system manage state automatically
  • Use /status to check consistency regularly
  • Resume interrupted runs rather than restart
  • Trust self-consistency validation

Resumability:

  • Use consistent spec and output_dir
  • Preserve output directory between sessions
  • Check state before resuming
  • Let system determine next iteration

URL Deduplication:

  • Use URL strategy files
  • Let state track URLs automatically
  • Trust deduplication system
  • Provide fallback search terms

Validation:

  • Run validation before critical operations
  • Investigate low consistency scores
  • Use multiple validation approaches
  • Trust majority voting results

For Spec Authors

Required Metadata:

Specs MUST require embedded metadata in outputs:

<div id="metadata" style="display:none;">
{
  "iteration": 1,
  "web_source": "https://example.com/tutorial",
  "techniques_learned": ["technique1", "technique2"],
  "created": "2025-03-10T14:30:00Z"
}
</div>

This enables:

  • State reconstruction from files
  • URL deduplication
  • Quality validation
  • Learning tracking

For Command Authors

State-Aware Commands:

New commands should:

  • Load state from .claude/state/
  • Validate consistency before operations
  • Update state atomically
  • Document state changes

Example:

from state_manager import StateManager

sm = StateManager()
state = sm.load_state(run_id)

# Validate
score, checks = sm.validate_consistency(state)
if score < 0.8:
    # Handle low consistency

# Operate on state
# ...

# Save atomically
sm.save_state(state)

Troubleshooting

Common Issues

Low Consistency Score:

  • Run /status <run_id> for details
  • Use /reset-state <run_id> --rebuild to fix
  • Investigate specific failed checks

Cannot Resume:

  • Verify state file exists: ls .claude/state/
  • Use /status to list available runs
  • Check state consistency before resume

Duplicate URLs:

  • Run /status <run_id> to check uniqueness
  • Rebuild state: /reset-state <run_id> --rebuild
  • Verify URL strategy has unique URLs

Missing Files:

  • Files manually deleted after generation
  • Rebuild state: /reset-state <run_id> --rebuild
  • Or accept loss and continue

Validation Tools

Bash Validator:

./validators/check_state_consistency.sh run_20250310_143022

Python Utilities:

python state_manager.py list
python state_manager.py validate run_20250310_143022
python state_manager.py info run_20250310_143022

Web Learning Integration

This variant demonstrates learning from self-consistency prompting research:

Source Concept: Self-consistency improves AI reliability by:

  1. Generating multiple independent reasoning paths
  2. Analyzing consistency across paths
  3. Using majority voting to select consensus answer

Applied Here: State validation uses:

  1. Multiple independent validation checks (6 different approaches)
  2. Consistency analysis (pass/fail for each check)
  3. Majority voting (consistency score from passed/total)

Result: High-confidence state validation even if individual checks have edge cases or limitations.

Extension Points

Add Custom Commands

Create new commands in .claude/commands/:

  • Analysis commands
  • Export commands
  • Reporting commands
  • Integration commands

Add Custom Validation

Extend state_manager.py:

def validate_custom(state):
    # Domain-specific checks
    pass

Add State Metadata

Extend state schema:

def add_metadata(state, key, value):
    if 'metadata' not in state:
        state['metadata'] = {}
    state['metadata'][key] = value

Integrate External Systems

Export state:

from state_manager import StateManager

sm = StateManager()
state = sm.load_state('run_20250310_143022')

# Export to external system
send_to_external(state)

Success Criteria

A successful stateful run:

  1. Completes Reliably: Handles interruptions gracefully
  2. Maintains Consistency: Validation score ≥0.8
  3. Deduplicates URLs: No duplicate web sources
  4. Resumes Correctly: Exact continuation from interrupt point
  5. Provides Audit Trail: Complete iteration history
  6. Recovers from Errors: Rebuild capability for corruption

Documentation

  • README.md: Overview and quick start
  • docs/state_management_guide.md: Complete usage guide
  • .claude/state/README.md: State system reference
  • This file (CLAUDE.md): Project instructions

Notes

  • State files are JSON for human readability
  • Atomic writes prevent corruption
  • Multiple validation approaches ensure reliability
  • Self-consistency principle proven in AI research
  • System designed for production use cases

When working with this project, prioritize state integrity and trust the self-consistency validation system.