# WDMaker Terminology & Concepts Guide

**Purpose**: Define all key terms and concepts used throughout the project
**Audience**: New team members, anyone needing clarification
**Status**: Complete terminology reference

---

## Core Concepts

### Batch
**Definition**: A group of sites processed together as a unit

**In WDMaker context**:
- **Batch 001**: 517 sites (main batch)
- **Batch 010**: 1 site (final batch, 20241204.com)
- **Previous batches** (002-009): 48 sites already completed

**Why batches?**
- Simplifies tracking
- Enables staged processing
- Allows prioritization
- Improves error isolation

**Example**: "Batch 001 is 99% complete, ready for finalization"

---

### Wave
**Definition**: A subset of agents deployed simultaneously

**In WDMaker context**:
- **Wave 1-3**: Design phase (already run)
- **Wave 4-9**: Implementation phase (currently running)
- **25 agents per wave**: Concurrent processing capacity
- **Sequential waves**: Run one at a time

**Purpose**:
- Limit concurrent resource usage
- Enable graceful degradation
- Simplify monitoring and recovery

**Example**: "Wave 5 is currently processing 25 sites in parallel"

---

### Agent
**Definition**: An autonomous AI system that executes a specific task

**In WDMaker**:
- **Opus agents**: Used for complex tasks (design, implementation)
- **Haiku agents**: Used for orchestration (wave management)
- **1 agent per task**: Each site gets its own agent for implementation
- **Concurrent agents**: Multiple agents running simultaneously

**Responsibility**:
- Read specifications
- Generate output files
- Verify own work
- Update status when done

**Example**: "Agent 47 is implementing lotus.dev, should complete in 8 minutes"

---

### Status State
**Definition**: Current stage of a site in the processing pipeline

**WDMaker status states**:

| State | Symbol | Meaning | When | Next |
|-------|--------|---------|------|------|
| Unassigned | `-` | Not yet part of any batch | Beginning | Assign to batch |
| Designed | `D` | Design phase complete | After design | Open for implementation |
| Open | `O` | Ready for implementation | After design | In-progress (i) |
| In-Progress | `i` | Agent currently working | During implementation | Implemented (I) |
| Implemented | `I` | Files generated, ready to finalize | After implementation | Finalized (Q) |
| Finalized | `Q` | Officially complete | After finalization | Done |

**Flow**: `- → D → O → i → I → Q`

**Example**: "lotus.dev transitioned from O to i at 14:23, should reach I by 14:28"

---

### Registry
**Definition**: Central file tracking all sites and their statuses

**Technical details**:
- **File location**: `.smbatcher/REGISTRY.md`
- **Format**: Markdown table
- **Updated**: Every 30-60 seconds during execution
- **Atomic**: All updates are all-or-nothing

**Contains**:
- Site name (domain)
- Current status
- Batch assignment
- Last update timestamp

**Example row**:
```
| lotus.dev | I | 001 | 2026-03-24T14:23:45 |
```

**Why important**:
- Single source of truth
- Used for monitoring and recovery
- Enables coordination between agents

---

### Design Phase
**Definition**: Generation of detailed specifications for each site

**What happens**:
1. Input: Site metadata (domain, category)
2. Process: SDESIGN workflow (Opus agent)
3. Output: DESIGN.md file with specifications
4. Time: 5-10 minutes per site

**DESIGN.md contains**:
- Color palette
- Typography specifications
- Layout framework
- Interactive features
- Domain-specific requirements

**Why separate phase?**
- Enables parallel implementation
- Creates detailed specs upfront
- Allows verification against spec
- Reduces ambiguity

**Example**: "DESIGN.md specifies primary color #0066FF, which implementation must use"

---

### Implementation Phase
**Definition**: Actual code generation based on specifications

**What happens**:
1. Input: DESIGN.md specification
2. Process: SIMPLEMENT workflow (10-step Opus process)
3. Output: 3 files (index.html, styles.css, script.js)
4. Time: 5-10 minutes per site

**Files generated**:
- **index.html**: HTML structure
- **styles.css**: CSS styling
- **script.js**: JavaScript functionality

**Follows spec**:
- Colors from DESIGN.md
- Fonts from DESIGN.md
- Layout from DESIGN.md

**Example**: "Implementation generated valid HTML and applied colors from design"

---

### Finalization
**Definition**: Official completion, transitioning I → Q status

**What happens**:
1. Verify all sites at I
2. Update registry: I → Q
3. Record timestamp
4. Update batch count

**Duration**: < 1 minute

**Result**:
- Sites locked as "complete"
- Count toward project completion
- No further changes possible

**Why separate step?**
- Atomic operation (all-or-nothing)
- Clear completion point
- Enables next phase to start
- Provides final checkpoint

**Example**: "Finalization marked all 517 sites as Q at 22:00:15"

---

### Specification
**Definition**: Detailed requirements document for implementation

**In WDMaker**:
- Generated during design phase
- File: DESIGN.md
- Unambiguous and complete
- Agent-readable format

**Contains**:
- Design decisions
- Color specifications
- Typography rules
- Layout requirements
- Feature descriptions

**Why important**:
- Eliminates ambiguity
- Enables verification
- Guides implementation
- Serves as documentation

**Example**: "Specification calls for sans-serif font with 16px body size"

---

### Verification
**Definition**: Automated checks ensuring output meets specifications

**Checks performed**:
1. **File existence**: All 3 files exist
2. **Syntax validation**: HTML/CSS/JS valid
3. **Compliance**: Colors/fonts match spec
4. **Quality**: No obvious errors

**Deterministic**:
- Same spec = same result every time
- No human judgment required
- Can be automated
- Runs in parallel with implementation

**Outcome**:
- Pass: Output acceptable, moves to next phase
- Fail: Output rejected, needs rework or manual fix

**Example**: "Verification confirmed colors match spec, syntax valid, all files present"

---

## Technical Terms

### SDESIGN
**Definition**: Design phase Opus agent workflow

**Responsibilities**:
- Read site metadata
- Generate DESIGN.md
- Create specifications
- Ensure completeness

**Example**: "SDESIGN was deployed for batch 010 to generate design for 20241204.com"

---

### SIMPLEMENT
**Definition**: 10-step implementation workflow for Opus agents

**The 10 steps**:
1. Mark implementation start
2. Read DESIGN.md specification
3. Generate index.html
4. Generate styles.css
5. Generate script.js
6. Verify HTML syntax
7. Verify CSS syntax
8. Verify design compliance
9. Mark implementation complete
10. Report results

**Why 10 steps?**
- Clear checkpoints
- Enables monitoring
- Allows error recovery
- Provides audit trail

**Example**: "Site followed SIMPLEMENT workflow, completed all 10 steps successfully"

---

### MDESIGN
**Definition**: Design orchestrator (Haiku) for batch processing

**Responsibilities**:
- Deploy SDESIGN agents for batch
- Monitor design progress
- Aggregate completed designs
- Manage wave transitions

**Example**: "MDESIGN deployed Wave 1 (25 agents) to design batch 001"

---

### MIMPLEMENT_BG
**Definition**: Implementation orchestrator (Haiku) for background execution

**Responsibilities**:
- Deploy SIMPLEMENT agents in waves
- Manage concurrent processing
- Track implementation progress
- Handle failures and retries

**Example**: "MIMPLEMENT_BG deployed waves 4-9 (150 agents) for batch 001 implementation"

---

### Complete.sh
**Definition**: Utility script for atomic status updates

**Functionality**:
- Read current registry
- Update specific site status
- Write atomically
- Handle concurrent access
- Idempotent (safe to retry)

**Used by**: Agents to mark completion after work done

**Example**: "complete.sh updated lotus.dev from i to I status"

---

### Finish.sh
**Definition**: Batch finalization script

**Functionality**:
- Verify all sites at I
- Update all to Q status
- Record timestamp
- Report results

**Used by**: Operator to finalize batch when ready

**Example**: "finish.sh finalized batch 001, transitioning all 517 sites to Q"

---

## Organizational Concepts

### Autonomous Execution
**Definition**: Agents work independently without human intervention

**How it works**:
- Agents have complete specifications
- Each agent works on single item
- No agent-to-agent communication
- Shared state (registry) accessed atomically
- Results in linear scalability

**Benefit**:
- No bottlenecks
- Easy to add more agents
- Fault isolation

**Example**: "150 agents running autonomously, no manual intervention needed"

---

### Parallel Processing
**Definition**: Multiple agents working simultaneously on different items

**In WDMaker**:
- 25 agents per wave (concurrent)
- 9 waves sequential
- Can be adjusted: 50 agents/wave, run 3 waves in parallel
- Enables 3-10x speedup

**Constraint**: System resources
- Memory: Each agent uses ~100MB
- Disk: Continuous writes
- CPU: File generation/verification

**Example**: "25 agents processing 25 different sites in parallel"

---

### Fault Isolation
**Definition**: One failure doesn't cascade to others

**In WDMaker**:
- One agent fails: Only that site affected
- One wave fails: Other waves continue
- One file corruption: Only that site impacted

**Why important**:
- Resilient system
- Easy recovery (fix one site, not all)
- High completion rate

**Example**: "Site 47 failed, but 24 other sites in same wave completed successfully"

---

### Idempotent Operation
**Definition**: Doing something multiple times = doing it once

**Properties**:
- Safe to retry
- No side effects from failure
- Can't cause additional damage on retry
- Predictable outcome

**In WDMaker**:
- Registry updates: Idempotent
- Finalization: Idempotent
- Status transitions: Idempotent

**Example**: "finish.sh is idempotent, so if it fails, retry it safely"

---

## Project-Specific Terms

### Catalog
**Definition**: Complete list of all sites in the project

**Scope**: 570 sites total
- 568 in registry (registered)
- 2 historically problematic
- 48 previously completed (batches 002-009)
- 517 in batch 001 (main)
- 1 in batch 010 (final)

**Example**: "We're processing 568 of the 570 catalog sites"

---

### Coverage
**Definition**: Percentage of catalog sites completed

**Calculation**: (Finalized / Total) × 100%

**Goals**:
- Minimum: > 90% (but undesirable)
- Target: 99.6% (566/568)
- Optimal: 100% (all 568)

**Example**: "We achieved 99.6% coverage, finalizing 566 of 568 sites"

---

### Throughput
**Definition**: Sites completed per unit time

**Measurement**: Sites per minute

**In WDMaker**:
- **Baseline**: 1-2 sites/minute
- **Peak**: Could reach 3-5 sites/min with 50 agents
- **Slow**: < 0.5 sites/min indicates problem

**Example**: "We're achieving 1.5 sites per minute, on track for completion"

---

### SLA (Service Level Agreement)
**Definition**: Commitment to quality and timeline

**WDMaker SLA**:
- Completion: 99.6% (566+ sites)
- Timeline: 9 hours
- Quality: Design compliance > 90%
- Availability: 99%+ uptime

**Example**: "We're on track to meet SLA: 9 hours to 99.6% completion"

---

### Checkpoint
**Definition**: Milestone where progress is verified before proceeding

**WDMaker checkpoints**:
1. Batch 001 implementation complete (I-status = 517)
2. Batch 001 finalization complete (Q-status = 517)
3. Batch 010 finalization complete (20241204.com at Q)
4. Project completion verified (566+ sites at Q)

**Example**: "We've reached checkpoint 1: batch 001 implementation complete"

---

## Troubleshooting Terms

### Stalled
**Definition**: Progress stops, nothing changes for extended period

**Symptom**: I-status unchanged for 45+ minutes

**Common causes**:
- Agents crashed
- Resource exhaustion
- Network issue
- Lock/deadlock

**Response**: Diagnose, restart, or recover

**Example**: "Progress stalled at 250/517, agents may have crashed"

---

### Degraded
**Definition**: System functioning but at reduced capacity

**Symptom**:
- Throughput drops to 0.5/min (vs. normal 1-2/min)
- High CPU/memory usage
- Slight delays

**Common causes**:
- High resource usage
- Many agents waiting
- I/O bottleneck

**Response**: Monitor, may self-recover

**Example**: "System degraded due to high memory usage, still progressing"

---

### Corrupt
**Definition**: Data integrity violated, unrecoverable without backup

**Symptom**:
- Duplicate entries in registry
- Missing files
- Inconsistent state
- I-status decreases

**Common causes**:
- Concurrent write conflict
- Disk error
- Software bug

**Response**: Restore from backup, restart phase

**Example**: "Registry corruption detected, restoring from git backup"

---

## Conclusion

**Key takeaways**:
- ✅ Batch = unit of processing
- ✅ Wave = unit of parallelism
- ✅ Agent = worker (autonomous)
- ✅ Status = current state
- ✅ Registry = source of truth
- ✅ Design → Implement → Finalize = workflow

**All concepts build on each other** to create a cohesive system for large-scale automation.

---

*Terminology & Concepts Guide: 2026-03-24*
*Purpose: Define all key terms and concepts*
*Status: Complete reference for understanding WDMaker*