464 lines
11 KiB
Markdown
464 lines
11 KiB
Markdown
# Quick Start Guide
|
|
|
|
Get started with the Cross-Iteration Pattern Synthesis System in 5 minutes.
|
|
|
|
## Prerequisites
|
|
|
|
```bash
|
|
# Install jq (JSON processor for validation)
|
|
sudo apt-get install jq # Ubuntu/Debian
|
|
brew install jq # macOS
|
|
choco install jq # Windows
|
|
```
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Clone this repository
|
|
git clone <repo-url> pattern-synthesis
|
|
cd pattern-synthesis
|
|
|
|
# Make validator executable
|
|
chmod +x validators/check_patterns.sh
|
|
|
|
# Verify installation
|
|
./validators/check_patterns.sh pattern_library_template.json
|
|
```
|
|
|
|
## First Generation (3 Minutes)
|
|
|
|
### Step 1: Start Claude Code
|
|
|
|
```bash
|
|
claude
|
|
```
|
|
|
|
### Step 2: Generate First 5 Iterations
|
|
|
|
```bash
|
|
/project:infinite-synthesis specs/example_spec.md output 5
|
|
```
|
|
|
|
**What happens**:
|
|
- Wave 1 generates 5 unique visualizations
|
|
- Pattern library automatically created
|
|
- Takes ~2-3 minutes
|
|
|
|
### Step 3: View Results
|
|
|
|
```bash
|
|
# Check generated files
|
|
ls output/
|
|
# Output: visualization_1.html ... visualization_5.html
|
|
|
|
# Check pattern library
|
|
cat pattern_library/patterns.json | jq '.patterns | keys'
|
|
# Output: ["structural", "content", "innovation", "quality"]
|
|
```
|
|
|
|
### Step 4: Validate Patterns
|
|
|
|
```bash
|
|
./validators/check_patterns.sh pattern_library/patterns.json
|
|
```
|
|
|
|
**Expected output**:
|
|
```
|
|
✓ Valid JSON
|
|
✓ All required fields present
|
|
✓ Pattern categories complete
|
|
Version: 1.0
|
|
Total patterns: 12
|
|
Quality score: 95% complete
|
|
```
|
|
|
|
## Second Generation (Pattern-Guided)
|
|
|
|
### Step 5: Generate 5 More Iterations
|
|
|
|
```bash
|
|
/project:infinite-synthesis specs/example_spec.md output 10
|
|
```
|
|
|
|
**What happens**:
|
|
- Wave 2 generates iterations 6-10
|
|
- Sub-agents receive pattern library as examples
|
|
- Quality improves (~15-20%)
|
|
- Pattern library updates to v1.1
|
|
|
|
### Step 6: Analyze Improvement
|
|
|
|
```bash
|
|
/project:analyze-patterns pattern_library/patterns.json output
|
|
```
|
|
|
|
**Expected results**:
|
|
```
|
|
Pattern Adoption Rate: 80%
|
|
Quality Improvement: +18%
|
|
Consistency Improvement: +42%
|
|
```
|
|
|
|
## View Your Visualizations
|
|
|
|
Open any generated HTML file in a browser:
|
|
|
|
```bash
|
|
# macOS
|
|
open output/visualization_6.html
|
|
|
|
# Linux
|
|
xdg-open output/visualization_6.html
|
|
|
|
# Windows
|
|
start output/visualization_6.html
|
|
```
|
|
|
|
Compare iteration 1 (no patterns) with iteration 6 (pattern-guided). Notice:
|
|
- More consistent code organization
|
|
- Better documentation
|
|
- Similar architectural patterns
|
|
- Still unique and creative!
|
|
|
|
## Next Steps
|
|
|
|
### Continue Generation
|
|
|
|
```bash
|
|
# Generate 10 more iterations (total: 20)
|
|
/project:infinite-synthesis specs/example_spec.md output 20
|
|
```
|
|
|
|
### Try Infinite Mode
|
|
|
|
```bash
|
|
# Continuous generation until context limit
|
|
/project:infinite-synthesis specs/example_spec.md output infinite
|
|
```
|
|
|
|
### Create Custom Specification
|
|
|
|
```bash
|
|
# Copy example spec
|
|
cp specs/example_spec.md specs/my_spec.md
|
|
|
|
# Edit with your requirements
|
|
nano specs/my_spec.md
|
|
|
|
# Generate from your spec
|
|
/project:infinite-synthesis specs/my_spec.md my_output 10
|
|
```
|
|
|
|
### View Pattern Details
|
|
|
|
```bash
|
|
# See all structural patterns
|
|
cat pattern_library/patterns.json | jq '.patterns.structural'
|
|
|
|
# View specific pattern
|
|
cat pattern_library/patterns.json | jq '.patterns.structural[0]'
|
|
|
|
# Check pattern adoption
|
|
cat pattern_library/patterns.json | jq '.metadata.avg_quality_score'
|
|
```
|
|
|
|
## Common Tasks
|
|
|
|
### Extract Patterns from Existing Code
|
|
|
|
```bash
|
|
# Analyze existing project
|
|
/project:extract-patterns /path/to/existing/code pattern_library/extracted.json
|
|
|
|
# Use those patterns for new generation
|
|
/project:infinite-synthesis specs/new_spec.md new_output 10 pattern_library/extracted.json
|
|
```
|
|
|
|
### Compare Pattern Libraries
|
|
|
|
```bash
|
|
# After generating 10 iterations
|
|
cp pattern_library/patterns.json pattern_library/wave2.json
|
|
|
|
# Generate 10 more (total: 20)
|
|
/project:infinite-synthesis specs/example_spec.md output 20
|
|
|
|
# Compare versions
|
|
diff <(jq '.patterns.structural' pattern_library/wave2.json) \
|
|
<(jq '.patterns.structural' pattern_library/patterns.json)
|
|
```
|
|
|
|
### Validate Before Using
|
|
|
|
```bash
|
|
# Always validate pattern library before generation
|
|
./validators/check_patterns.sh pattern_library/patterns.json
|
|
|
|
# Fix any issues reported
|
|
# Then proceed with generation
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Issue: "jq: command not found"
|
|
|
|
**Solution**: Install jq (see Prerequisites)
|
|
|
|
### Issue: Pattern library not being used
|
|
|
|
**Check**:
|
|
```bash
|
|
# Verify pattern library exists
|
|
test -f pattern_library/patterns.json && echo "Exists" || echo "Missing"
|
|
|
|
# Verify it's valid
|
|
./validators/check_patterns.sh pattern_library/patterns.json
|
|
```
|
|
|
|
**Solution**: Re-run pattern extraction
|
|
```bash
|
|
/project:extract-patterns output pattern_library/patterns.json
|
|
```
|
|
|
|
### Issue: Quality not improving
|
|
|
|
**Check**:
|
|
```bash
|
|
# View pattern count
|
|
cat pattern_library/patterns.json | jq '.patterns.structural | length'
|
|
# Should be 3-5
|
|
|
|
# Check for success metrics
|
|
cat pattern_library/patterns.json | jq '.patterns.structural[0].success_metrics'
|
|
# Should not be empty
|
|
```
|
|
|
|
**Solution**: Re-extract with deep analysis
|
|
```bash
|
|
/project:extract-patterns output pattern_library/patterns.json deep
|
|
```
|
|
|
|
### Issue: Iterations too similar
|
|
|
|
**Solution**: Emphasize uniqueness in spec
|
|
|
|
Edit your spec file to add:
|
|
```markdown
|
|
## Uniqueness Requirements (CRITICAL)
|
|
|
|
Each iteration MUST differ in:
|
|
1. Data domain (different subject matter)
|
|
2. Visualization type (different chart type)
|
|
3. Visual style (different colors, layout)
|
|
4. Interaction model (different user interactions)
|
|
5. Technical approach (different implementation)
|
|
|
|
Similarity > 50% to any existing iteration = FAILURE
|
|
```
|
|
|
|
## Understanding the Output
|
|
|
|
### Iteration Files
|
|
|
|
```html
|
|
<!-- Each iteration is a self-contained HTML file -->
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<title>Visualization Title</title>
|
|
<!-- Embedded CSS -->
|
|
<style>...</style>
|
|
</head>
|
|
<body>
|
|
<!-- Visualization content -->
|
|
<div id="container"></div>
|
|
|
|
<!-- Embedded JavaScript -->
|
|
<script>
|
|
// Notice patterns from pattern library:
|
|
// - Modular structure (data/view/controller)
|
|
// - Progressive documentation
|
|
// - Defensive error handling
|
|
// - Novel innovation unique to this iteration
|
|
</script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
### Pattern Library Structure
|
|
|
|
```json
|
|
{
|
|
"version": "1.1",
|
|
"patterns": {
|
|
"structural": [
|
|
{
|
|
"name": "Pattern name",
|
|
"description": "What it does",
|
|
"example_file": "output/visualization_3.html",
|
|
"key_characteristics": ["trait1", "trait2"],
|
|
"success_metrics": "Why it works",
|
|
"code_snippet": "// Example code..."
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Analysis Report
|
|
|
|
```markdown
|
|
# Pattern Library Effectiveness Report
|
|
|
|
## Key Findings
|
|
- Pattern Adoption: 80% (8/10 iterations use patterns)
|
|
- Quality Improvement: +18%
|
|
- Consistency: Variance reduced 42%
|
|
|
|
## Top Patterns
|
|
1. Modular Three-Layer Architecture (80% adoption)
|
|
2. Progressive Disclosure Documentation (60% adoption)
|
|
3. Guard Clause Error Handling (50% adoption)
|
|
```
|
|
|
|
## Tips for Success
|
|
|
|
### 1. Start Small
|
|
Begin with 5-10 iterations to establish patterns before scaling up.
|
|
|
|
### 2. Validate Early
|
|
Run the validator after first pattern extraction to catch issues early.
|
|
|
|
### 3. Review Patterns
|
|
Look at extracted patterns to understand what the system learned:
|
|
```bash
|
|
cat pattern_library/patterns.json | jq '.patterns.structural[0]' | less
|
|
```
|
|
|
|
### 4. Iterate on Specs
|
|
If patterns aren't what you want, refine your specification and regenerate.
|
|
|
|
### 5. Monitor Quality
|
|
Use the analysis command to track improvement:
|
|
```bash
|
|
/project:analyze-patterns pattern_library/patterns.json output
|
|
```
|
|
|
|
### 6. Preserve Innovation
|
|
If iterations become too similar, reduce pattern count:
|
|
```bash
|
|
# Use "quick" mode for 3 patterns per category instead of 5
|
|
/project:extract-patterns output pattern_library/patterns.json quick
|
|
```
|
|
|
|
## Example Session
|
|
|
|
Here's a complete session from start to finish:
|
|
|
|
```bash
|
|
# Session start
|
|
claude
|
|
|
|
# Generate Wave 1 (cold start)
|
|
/project:infinite-synthesis specs/example_spec.md viz 5
|
|
# → Creates viz/visualization_1.html through visualization_5.html
|
|
# → Creates pattern_library/patterns.json v1.0
|
|
|
|
# Validate patterns
|
|
./validators/check_patterns.sh pattern_library/patterns.json
|
|
# → ✓ Valid JSON, 12 patterns extracted
|
|
|
|
# Review extracted patterns
|
|
cat pattern_library/patterns.json | jq '.patterns.structural[0].name'
|
|
# → "Modular Three-Layer Architecture"
|
|
|
|
# Generate Wave 2 (pattern-guided)
|
|
/project:infinite-synthesis specs/example_spec.md viz 10
|
|
# → Creates visualization_6.html through visualization_10.html
|
|
# → Updates pattern_library/patterns.json to v1.1
|
|
|
|
# Analyze effectiveness
|
|
/project:analyze-patterns pattern_library/patterns.json viz
|
|
# → Pattern Adoption: 80%
|
|
# → Quality Improvement: +18%
|
|
|
|
# View a visualization
|
|
open viz/visualization_7.html
|
|
|
|
# Continue with Wave 3
|
|
/project:infinite-synthesis specs/example_spec.md viz 15
|
|
# → visualization_11.html through visualization_15.html
|
|
# → pattern_library/patterns.json v1.2
|
|
|
|
# Final analysis
|
|
/project:analyze-patterns pattern_library/patterns.json viz
|
|
# → Pattern Adoption: 90%
|
|
# → Quality Improvement: +22%
|
|
# → Consistency: Variance reduced 58%
|
|
|
|
# Success! 15 high-quality visualizations with consistent patterns
|
|
```
|
|
|
|
## What's Next?
|
|
|
|
### Learn More
|
|
- Read [README.md](README.md) for comprehensive overview
|
|
- Read [EXAMPLES.md](EXAMPLES.md) for real-world use cases
|
|
- Read [ARCHITECTURE.md](ARCHITECTURE.md) for technical details
|
|
|
|
### Customize
|
|
- Edit `specs/example_spec.md` to create custom specifications
|
|
- Modify `pattern_library_template.json` to add new pattern categories
|
|
- Extend `.claude/commands/` for custom workflows
|
|
|
|
### Share
|
|
- Export your pattern library: `cp pattern_library/patterns.json my_patterns.json`
|
|
- Share with team: Pattern libraries are reusable across projects
|
|
- Contribute: Add your patterns to community collections
|
|
|
|
## Getting Help
|
|
|
|
### Check Documentation
|
|
- **README.md**: Overview and features
|
|
- **EXAMPLES.md**: Real-world examples
|
|
- **ARCHITECTURE.md**: Technical deep dive
|
|
- **CLAUDE.md**: Agent instructions (for Claude Code)
|
|
|
|
### Common Questions
|
|
|
|
**Q: How many iterations before patterns emerge?**
|
|
A: Typically 5-10 iterations. Quality improvement visible after 10-15.
|
|
|
|
**Q: Can I use my own pattern library?**
|
|
A: Yes! Extract from any codebase or manually create one.
|
|
|
|
**Q: Will patterns reduce creativity?**
|
|
A: No. Patterns provide foundation. Innovation metrics show creativity remains high.
|
|
|
|
**Q: How do I stop infinite mode?**
|
|
A: It stops automatically at 80% context budget or when quality plateaus.
|
|
|
|
**Q: Can I edit patterns manually?**
|
|
A: Yes. Edit the JSON, then validate with `check_patterns.sh`.
|
|
|
|
## Success Criteria
|
|
|
|
You're successful when you see:
|
|
|
|
✓ Pattern adoption rate >70%
|
|
✓ Quality improvement >15%
|
|
✓ Consistency improvement >40%
|
|
✓ Innovation preservation (still unique iterations)
|
|
✓ Pattern library validates without errors
|
|
✓ Generated output meets your spec requirements
|
|
|
|
Congratulations! You're now using cumulative learning to generate progressively better iterations.
|
|
|
|
---
|
|
|
|
**Time to first results**: 3 minutes
|
|
**Time to see improvement**: 5 minutes
|
|
**Time to mastery**: 30 minutes
|
|
|
|
Start now: `/project:infinite-synthesis specs/example_spec.md output 5`
|