diff --git a/.amplifier/project.json b/.amplifier/project.json
new file mode 100644
index 00000000..3bfdc9c6
--- /dev/null
+++ b/.amplifier/project.json
@@ -0,0 +1,7 @@
+{
+  "project_id": "test_integration_project_20251007_121405",
+  "project_name": "Test Integration Project",
+  "has_planning": true,
+  "created_at": "2025-10-07T12:14:05.201566",
+  "updated_at": "2025-10-07T12:14:05.201569"
+}
\ No newline at end of file
diff --git a/Makefile b/Makefile
index 21a36284..bf3a6b4c 100644
--- a/Makefile
+++ b/Makefile
@@ -41,6 +41,13 @@ default: ## Show essential commands
 	@echo "AI Context:"
 	@echo "  make ai-context-files Build AI context documentation"
 	@echo ""
+	@echo "Project Planning:"
+	@echo "  make project-init    Initialize AI-driven project planning"
+	@echo "  make project-plan    Plan project tasks with AI decomposition"
+	@echo "  make project-status  Show project status and progress"
+	@echo "  make project-execute Execute tasks with multi-agent coordination"
+	@echo "  make smart-decomposer Smart multi-agent task decomposition"
+	@echo ""
 	@echo "Blog Writing:"
 	@echo "  make blog-write      Create a blog post from your ideas"
 	@echo ""
@@ -113,6 +120,12 @@ help: ## Show ALL available commands
 	@echo "AI CONTEXT:"
 	@echo "  make ai-context-files  Build AI context documentation"
 	@echo ""
+	@echo "PROJECT PLANNING:"
+	@echo "  make project-init PROJECT_NAME=\"...\" [PROJECT_PATH=...]  Initialize project with AI planning"
+	@echo "  make project-plan [GOALS=\"...\"]  Plan project tasks with AI decomposition"
+	@echo "  make project-status              Show project status and progress"
+	@echo "  make project-execute             Execute tasks with multi-agent coordination"
+	@echo ""
 	@echo "BLOG WRITING:"
 	@echo "  make blog-write IDEA=<file> WRITINGS=<dir> [INSTRUCTIONS=\"...\"]  Create blog"
 	@echo "  make blog-resume       Resume most recent blog writing session"
@@ -514,6 +527,48 @@ blog-write-example: ## Run blog writer with example data
 		--idea scenarios/blog_writer/tests/sample_brain_dump.md \
 		--writings-dir scenarios/blog_writer/tests/sample_writings/
 
+# Project Planning
+project-init: ## Initialize project with AI planning. Usage: make project-init PROJECT_NAME="My Project" [PROJECT_PATH=/path/to/project]
+	@if [ -z "$(PROJECT_NAME)" ]; then \
+		echo "Error: Please provide a project name. Usage: make project-init PROJECT_NAME=\"My Project\""; \
+		exit 1; \
+	fi
+	@echo "🚀 Initializing AI-driven project planning..."; \
+	echo "  Project: $(PROJECT_NAME)"; \
+	if [ -n "$(PROJECT_PATH)" ]; then \
+		echo "  Path: $(PROJECT_PATH)"; \
+		uv run python -m scenarios.project_planner init --name "$(PROJECT_NAME)" --path "$(PROJECT_PATH)"; \
+	else \
+		uv run python -m scenarios.project_planner init --name "$(PROJECT_NAME)"; \
+	fi
+
+project-plan: ## Plan project tasks with AI decomposition. Usage: make project-plan [GOALS="Build authentication system"]
+	@echo "🧠 Planning project tasks with AI..."
+	@if [ -n "$(GOALS)" ]; then \
+		echo "  Goals: $(GOALS)"; \
+		uv run python -m scenarios.project_planner plan --goals "$(GOALS)"; \
+	else \
+		uv run python -m scenarios.project_planner plan; \
+	fi
+
+project-status: ## Show project status and progress
+	@echo "📊 Checking project status..."
+	@uv run python -m scenarios.project_planner status
+
+project-execute: ## Execute project tasks with multi-agent coordination
+	@echo "🚀 Executing project tasks with AI agents..."
+	@uv run python -m scenarios.project_planner execute
+
+smart-decomposer: ## Smart multi-agent task decomposition. Usage: make smart-decomposer ARGS="decompose 'Build API' --auto-assign"
+	@echo "🧠 Running Smart Decomposer multi-agent orchestration..."
+	@if [ -n "$(ARGS)" ]; then \
+		echo "  Args: $(ARGS)"; \
+		uv run python -m scenarios.smart_decomposer $(ARGS); \
+	else \
+		echo "  Running status check..."; \
+		uv run python -m scenarios.smart_decomposer status; \
+	fi
+
 # Article Illustration
 illustrate: ## Generate AI illustrations for markdown article. Usage: make illustrate INPUT=article.md [OUTPUT=path] [STYLE="..."] [APIS="..."] [RESUME=true]
 	@if [ -z "$(INPUT)" ]; then \
diff --git a/amplifier/core/__init__.py b/amplifier/core/__init__.py
new file mode 100644
index 00000000..2a4b41b9
--- /dev/null
+++ b/amplifier/core/__init__.py
@@ -0,0 +1,11 @@
+"""
+Amplifier Core - Project context and session management.
+
+Provides automatic project detection and persistent state management
+for amplifier across multiple invocations.
+"""
+
+from .context import ProjectContext
+from .context import detect_project_context
+
+__all__ = ["ProjectContext", "detect_project_context"]
diff --git a/amplifier/core/context.py b/amplifier/core/context.py
new file mode 100644
index 00000000..83fe8340
--- /dev/null
+++ b/amplifier/core/context.py
@@ -0,0 +1,121 @@
+"""
+Project Context Detection and Management.
+
+Automatically detects project planning context and provides persistent state
+management across amplifier invocations.
+"""
+
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from amplifier.planner import Project
+from amplifier.planner import load_project
+
+
+@dataclass
+class ProjectContext:
+    """Amplifier project context with planning integration."""
+
+    project_root: Path
+    project_id: str
+    project_name: str
+    config_file: Path
+    planner_project: Project | None = None
+    has_planning: bool = False
+
+    @classmethod
+    def from_config(cls, config_path: Path) -> "ProjectContext":
+        """Create context from .amplifier/project.json config."""
+        with open(config_path) as f:
+            config = json.load(f)
+
+        project_root = config_path.parent.parent
+        context = cls(
+            project_root=project_root,
+            project_id=config["project_id"],
+            project_name=config["project_name"],
+            config_file=config_path,
+            has_planning=config.get("has_planning", False),
+        )
+
+        # Load planner project if planning is enabled
+        if context.has_planning:
+            import contextlib
+
+            with contextlib.suppress(FileNotFoundError):
+                context.planner_project = load_project(context.project_id)
+
+        return context
+
+    def enable_planning(self) -> None:
+        """Enable planning for this project."""
+        if not self.has_planning:
+            self.has_planning = True
+            self.save_config()
+
+    def save_config(self) -> None:
+        """Save project configuration."""
+        config = {
+            "project_id": self.project_id,
+            "project_name": self.project_name,
+            "has_planning": self.has_planning,
+            "created_at": datetime.now().isoformat(),
+            "updated_at": datetime.now().isoformat(),
+        }
+
+        self.config_file.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.config_file, "w") as f:
+            json.dump(config, f, indent=2)
+
+
+def detect_project_context(start_dir: Path | None = None) -> ProjectContext | None:
+    """
+    Detect amplifier project context by looking for .amplifier/project.json.
+
+    Walks up directory tree from start_dir (or cwd) looking for project config.
+    Returns None if no project context found.
+    """
+    if start_dir is None:
+        start_dir = Path.cwd()
+
+    # Walk up directory tree looking for .amplifier/project.json
+    current = Path(start_dir).absolute()
+
+    while current != current.parent:  # Not at filesystem root
+        config_file = current / ".amplifier" / "project.json"
+        if config_file.exists():
+            try:
+                return ProjectContext.from_config(config_file)
+            except (json.JSONDecodeError, KeyError, OSError):
+                # Invalid config, continue searching up
+                pass
+        current = current.parent
+
+    return None
+
+
+def create_project_context(
+    project_name: str, project_root: Path | None = None, enable_planning: bool = True
+) -> ProjectContext:
+    """Create new amplifier project context."""
+    if project_root is None:
+        project_root = Path.cwd()
+
+    # Generate project ID from name and timestamp
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    project_id = f"{project_name.lower().replace(' ', '_')}_{timestamp}"
+
+    config_file = project_root / ".amplifier" / "project.json"
+
+    context = ProjectContext(
+        project_root=project_root,
+        project_id=project_id,
+        project_name=project_name,
+        config_file=config_file,
+        has_planning=enable_planning,
+    )
+
+    context.save_config()
+    return context
diff --git a/amplifier/planner/PHASE_2_PLAN.md b/amplifier/planner/PHASE_2_PLAN.md
new file mode 100644
index 00000000..f25a927a
--- /dev/null
+++ b/amplifier/planner/PHASE_2_PLAN.md
@@ -0,0 +1,189 @@
+# Super-Planner Phase 2 Implementation Plan
+
+## Status: Ready to Begin
+
+**Phase 1 Foundation**: ✅ COMPLETED
+- Core models and storage (139 lines)
+- 16 comprehensive tests passing
+- Clean public API following amplifier philosophy
+
+## Phase 2 Architecture: Hybrid CLI Tools
+
+Based on amplifier-cli-architect guidance, Phase 2 will be implemented as CLI tools in `scenarios/planner/` using the hybrid "code for structure, AI for intelligence" pattern.
+
+### Target Structure
+
+```
+amplifier/planner/           # Phase 1 foundation (UNCHANGED)
+├── models.py               # Core data models
+├── storage.py              # Persistence layer
+└── tests/
+
+scenarios/planner/           # Phase 2 CLI tools (NEW)
+├── __init__.py
+├── planner_cli.py          # Main CLI entry point
+├── decomposer.py           # Task decomposition with AI
+├── strategic_assigner.py   # Agent assignment logic
+├── session_wrapper.py      # CCSDK SessionManager integration
+├── README.md               # Modeled after @scenarios/blog_writer/
+├── HOW_TO_CREATE_YOUR_OWN.md
+├── tests/
+└── examples/
+```
+
+### Implementation Strategy
+
+#### 1. Use CCSDK Toolkit Foundation
+- Start with `amplifier/ccsdk_toolkit/templates/tool_template.py`
+- Import: `ClaudeSession`, `SessionManager`, `parse_llm_json`
+- Use defensive LLM response handling from toolkit
+
+#### 2. Session Persistence Pattern
+```python
+async def decompose_task(task: Task, storage: Storage):
+    session_mgr = SessionManager()
+    session = session_mgr.load_or_create(f"planner_{task.id}")
+
+    # Resume from existing decomposition
+    subtasks = session.context.get("subtasks", [])
+
+    async with ClaudeSession(SessionOptions(
+        system_prompt="You are a task decomposition expert..."
+    )) as claude:
+        if not subtasks:
+            response = await claude.query(f"Decompose: {task.description}")
+            subtasks = parse_llm_json(response)
+            session.context["subtasks"] = subtasks
+            session_mgr.save(session)
+
+    return subtasks
+```
+
+#### 3. Agent Spawning Integration
+```python
+from amplifier.tools import Task as AgentTask
+
+async def spawn_agents(assignments: list):
+    """Spawn multiple agents in parallel for assigned tasks"""
+    agent_calls = []
+    for assignment in assignments:
+        agent_calls.append(
+            AgentTask.run(
+                agent=assignment['agent'],
+                prompt=assignment['prompt']
+            )
+        )
+    results = await asyncio.gather(*agent_calls)
+    return results
+```
+
+### Make Command Integration
+
+Add to main Makefile:
+```makefile
+planner-create: ## Create new project with AI decomposition
+	@echo "Creating project with AI planning..."
+	uv run python -m scenarios.planner create $(ARGS)
+
+planner-plan: ## Decompose project tasks recursively
+	@echo "Planning project tasks..."
+	uv run python -m scenarios.planner plan --project-id=$(PROJECT_ID)
+
+planner-assign: ## Assign tasks to agents strategically
+	@echo "Assigning tasks to agents..."
+	uv run python -m scenarios.planner assign --project-id=$(PROJECT_ID)
+
+planner-execute: ## Execute assigned tasks via Task tool
+	@echo "Executing planned tasks..."
+	uv run python -m scenarios.planner execute --project-id=$(PROJECT_ID)
+```
+
+### Core Components
+
+#### 1. Task Decomposition (decomposer.py)
+- **Purpose**: Use AI to break down high-level tasks into specific subtasks
+- **Pattern**: Iterative decomposition with depth limits
+- **Integration**: Uses CCSDK SessionManager for resume capability
+- **Output**: Creates hierarchical Task objects using Phase 1 models
+
+#### 2. Strategic Assignment (strategic_assigner.py)
+- **Purpose**: Analyze task requirements and assign to appropriate agents
+- **Pattern**: Complexity analysis + capability matching
+- **Integration**: Uses Task tool for agent spawning
+- **Output**: Assignment queue with agent specifications
+
+#### 3. Session Management (session_wrapper.py)
+- **Purpose**: Wrap CCSDK toolkit for planner-specific workflows
+- **Pattern**: Project-level session persistence
+- **Integration**: Bridges Phase 1 storage with CCSDK sessions
+- **Output**: Resumable planning workflows
+
+### Key Implementation Principles
+
+#### 1. Hybrid Architecture
+- **Code handles**: Project structure, task coordination, agent spawning
+- **AI handles**: Task understanding, decomposition strategy, assignment logic
+
+#### 2. Incremental Progress
+- Save after every major operation
+- Support workflow interruption and resume
+- Use SessionManager for session state
+
+#### 3. Defensive Programming
+- Use `parse_llm_json` for all LLM responses
+- Implement retry logic for API failures
+- Handle cloud sync issues via existing file_io utilities
+
+#### 4. Integration with Phase 1
+- Import Phase 1 models: `from amplifier.planner import Task, Project, save_project, load_project`
+- Extend but don't modify existing data models
+- Use existing storage layer for persistence
+
+### Development Phases
+
+#### Phase 2a: Basic Decomposition (Week 1)
+- CLI interface for project creation
+- Simple task decomposition with AI
+- Integration with Phase 1 storage
+
+#### Phase 2b: Strategic Assignment (Week 2)
+- Task complexity analysis
+- Agent capability matching
+- Assignment queue generation
+
+#### Phase 2c: Execution Orchestration (Week 3)
+- Agent spawning via Task tool
+- Progress monitoring
+- Status updates to project storage
+
+#### Phase 2d: Full Integration (Week 4)
+- End-to-end workflows
+- Comprehensive testing
+- Documentation completion
+
+### Success Criteria
+
+- Can create projects from natural language descriptions
+- Recursively decomposes tasks to actionable granularity
+- Strategically assigns tasks based on complexity and agent capabilities
+- Spawns multiple agents in parallel via Task tool
+- Handles interruption and resume gracefully
+- Follows amplifier's simplicity philosophy
+
+### Resources to Reference
+
+- **@scenarios/README.md**: Philosophy for user-facing tools
+- **@scenarios/blog_writer/**: THE exemplar for documentation and structure
+- **@amplifier/ccsdk_toolkit/DEVELOPER_GUIDE.md**: Complete technical guide
+- **@amplifier/ccsdk_toolkit/templates/tool_template.py**: Starting point
+- **@DISCOVERIES.md**: File I/O retry patterns and LLM response handling
+
+### Next Steps
+
+1. **Create scenarios/planner/ directory structure**
+2. **Copy and customize tool_template.py as planner_cli.py**
+3. **Implement basic decomposer.py using CCSDK patterns**
+4. **Add make commands to main Makefile**
+5. **Create README.md modeled after blog_writer/**
+
+This plan leverages amplifier's hybrid architecture while building on the solid Phase 1 foundation. The result will be a production-ready multi-agent planning system that embodies amplifier's design philosophy.
\ No newline at end of file
diff --git a/amplifier/planner/README.md b/amplifier/planner/README.md
new file mode 100644
index 00000000..a1b18aea
--- /dev/null
+++ b/amplifier/planner/README.md
@@ -0,0 +1,367 @@
+# Super-Planner: Multi-Agent Project Coordination
+
+Super-Planner is a core amplifier module that manages large projects with hierarchical tasks, supporting coordination between multiple AI agents and humans. It follows amplifier's "bricks and studs" philosophy with ruthless simplicity.
+
+## Quick Start
+
+```python
+from amplifier.planner import Task, Project, TaskState, save_project, load_project
+import uuid
+
+# Create a project
+project = Project(
+    id=str(uuid.uuid4()),
+    name="Build Web App"
+)
+
+# Add hierarchical tasks
+backend = Task(
+    id="backend",
+    title="Create Backend API",
+    description="Build REST API with authentication"
+)
+
+frontend = Task(
+    id="frontend",
+    title="Create Frontend",
+    description="React app with user interface",
+    depends_on=["backend"]  # Depends on backend completion
+)
+
+deployment = Task(
+    id="deployment",
+    title="Deploy Application",
+    depends_on=["backend", "frontend"]  # Depends on both
+)
+
+# Add tasks to project
+project.add_task(backend)
+project.add_task(frontend)
+project.add_task(deployment)
+
+# Save to persistent storage
+save_project(project)
+
+# Load later
+loaded_project = load_project(project.id)
+```
+
+## Core Concepts
+
+### Task States
+
+Tasks progress through defined states:
+
+```python
+from amplifier.planner import TaskState
+
+# Available states
+TaskState.PENDING      # Not started
+TaskState.IN_PROGRESS  # Currently being worked on
+TaskState.COMPLETED    # Finished successfully
+TaskState.BLOCKED      # Cannot proceed due to issues
+```
+
+### Task Dependencies
+
+Tasks can depend on other tasks being completed:
+
+```python
+# Check if task can start based on completed dependencies
+completed_tasks = {"backend", "database"}
+if task.can_start(completed_tasks):
+    # All dependencies are met
+    task.state = TaskState.IN_PROGRESS
+```
+
+### Project Hierarchy
+
+Projects organize tasks in hierarchical structures:
+
+```python
+# Get root tasks (no parents)
+root_tasks = project.get_roots()
+
+# Get direct children of a task
+sub_tasks = project.get_children("backend")
+
+# Navigate the task tree
+for root in project.get_roots():
+    print(f"Root: {root.title}")
+    for child in project.get_children(root.id):
+        print(f"  - {child.title}")
+```
+
+## Usage Examples
+
+### Example 1: Simple Blog Project
+
+```python
+import uuid
+from amplifier.planner import Task, Project, TaskState, save_project
+
+# Create project
+blog_project = Project(
+    id=str(uuid.uuid4()),
+    name="Django Blog"
+)
+
+# Define tasks with hierarchy
+tasks = [
+    Task("setup", "Project Setup", "Initialize Django project"),
+    Task("models", "Create Models", "User, Post, Comment models", parent_id="setup"),
+    Task("views", "Create Views", "List, detail, create views", depends_on=["models"]),
+    Task("templates", "Create Templates", "HTML templates", depends_on=["views"]),
+    Task("tests", "Write Tests", "Unit and integration tests", depends_on=["models", "views"]),
+    Task("deploy", "Deploy", "Deploy to production", depends_on=["templates", "tests"])
+]
+
+# Add all tasks
+for task in tasks:
+    blog_project.add_task(task)
+
+# Save project
+save_project(blog_project)
+
+# Find tasks ready to start
+completed_ids = {"setup"}  # Setup is done
+ready_tasks = []
+for task in blog_project.tasks.values():
+    if task.state == TaskState.PENDING and task.can_start(completed_ids):
+        ready_tasks.append(task)
+
+print(f"Ready to start: {[t.title for t in ready_tasks]}")
+# Output: Ready to start: ['Create Models']
+```
+
+### Example 2: Complex E-commerce Platform
+
+```python
+import uuid
+from amplifier.planner import Task, Project, save_project
+
+# Create complex project
+ecommerce = Project(
+    id=str(uuid.uuid4()),
+    name="E-commerce Platform"
+)
+
+# Multi-level hierarchy
+tasks = [
+    # Backend foundation
+    Task("architecture", "Design Architecture", "System design and APIs"),
+    Task("auth", "Authentication Service", "User management", depends_on=["architecture"]),
+    Task("products", "Product Service", "Catalog management", depends_on=["architecture"]),
+    Task("orders", "Order Service", "Order processing", depends_on=["products", "auth"]),
+
+    # Frontend components
+    Task("ui-kit", "UI Component Library", "Reusable components"),
+    Task("product-pages", "Product Pages", "Browse and detail pages", depends_on=["ui-kit", "products"]),
+    Task("checkout", "Checkout Flow", "Shopping cart and payment", depends_on=["product-pages", "orders"]),
+
+    # Integration
+    Task("payment", "Payment Integration", "Stripe integration", depends_on=["orders"]),
+    Task("testing", "End-to-End Testing", "Full system tests", depends_on=["checkout", "payment"]),
+    Task("deployment", "Production Deployment", "Deploy all services", depends_on=["testing"])
+]
+
+for task in tasks:
+    ecommerce.add_task(task)
+
+save_project(ecommerce)
+
+# Analyze project structure
+roots = ecommerce.get_roots()
+print(f"Starting points: {[r.title for r in roots]}")
+
+# Find bottleneck tasks (many dependencies)
+for task in ecommerce.tasks.values():
+    if len(task.depends_on) > 1:
+        print(f"Complex task: {task.title} depends on {task.depends_on}")
+```
+
+### Example 3: Task State Management
+
+```python
+from amplifier.planner import load_project, save_project, TaskState
+
+# Load existing project
+project = load_project("some-project-id")
+
+# Update task states
+project.tasks["backend"].state = TaskState.IN_PROGRESS
+project.tasks["backend"].assigned_to = "agent-001"
+
+# Mark task as completed
+project.tasks["backend"].state = TaskState.COMPLETED
+
+# Find next ready tasks
+completed_ids = {task_id for task_id, task in project.tasks.items()
+                 if task.state == TaskState.COMPLETED}
+
+next_tasks = []
+for task in project.tasks.values():
+    if (task.state == TaskState.PENDING and
+        task.can_start(completed_ids)):
+        next_tasks.append(task)
+
+print(f"Next available: {[t.title for t in next_tasks]}")
+
+# Save updated state
+save_project(project)
+```
+
+## Architecture
+
+### Design Philosophy
+
+Super-Planner follows amplifier's core principles:
+
+- **Ruthless Simplicity**: 139 lines total, no unnecessary abstractions
+- **File-Based Storage**: JSON files in `data/planner/projects/`
+- **Defensive I/O**: Uses amplifier's retry utilities for cloud sync resilience
+- **Modular Design**: Clear contracts, regenerable internals
+
+### Module Structure
+
+```
+amplifier/planner/
+├── __init__.py       # Public API: Task, Project, TaskState, save_project, load_project
+├── models.py         # Core data models (60 lines)
+├── storage.py        # JSON persistence (70 lines)
+└── tests/
+    └── test_planner.py  # Comprehensive test suite (16 tests)
+```
+
+### Data Model
+
+```python
+@dataclass
+class Task:
+    id: str                    # Unique identifier
+    title: str                 # Human-readable name
+    description: str           # Detailed description
+    state: TaskState          # Current state (enum)
+    parent_id: Optional[str]   # Hierarchical parent
+    depends_on: List[str]      # Task dependencies
+    assigned_to: Optional[str] # Agent or human assigned
+    created_at: str           # ISO timestamp
+    updated_at: str           # ISO timestamp
+
+@dataclass
+class Project:
+    id: str                    # Unique identifier
+    name: str                  # Human-readable name
+    tasks: Dict[str, Task]     # Task collection
+    created_at: str           # ISO timestamp
+    updated_at: str           # ISO timestamp
+```
+
+### Storage Format
+
+Projects are stored as JSON files in `data/planner/projects/{project_id}.json`:
+
+```json
+{
+  "id": "project-uuid",
+  "name": "My Project",
+  "created_at": "2024-01-15T10:30:00",
+  "updated_at": "2024-01-15T11:45:00",
+  "tasks": [
+    {
+      "id": "task-1",
+      "title": "Setup Project",
+      "description": "Initialize repository and dependencies",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": "agent-001",
+      "created_at": "2024-01-15T10:30:00",
+      "updated_at": "2024-01-15T11:00:00"
+    }
+  ]
+}
+```
+
+## Integration Points
+
+### Amplifier Integration
+
+Super-Planner is designed to integrate with amplifier's ecosystem:
+
+- **Task Tool**: Phase 2 will spawn sub-agents using `Task(subagent_type="...", prompt="...")`
+- **CCSDK Toolkit**: Uses `SessionManager`, `parse_llm_json`, `retry_with_feedback`
+- **File I/O**: Uses `amplifier.utils.file_io` for defensive operations
+- **Data Directory**: Follows amplifier's `data/` convention
+
+### Defensive Programming
+
+Built-in resilience for common issues:
+
+```python
+# Handles cloud sync delays (OneDrive, Dropbox, etc.)
+from amplifier.utils.file_io import write_json, read_json
+
+# Automatic retries with exponential backoff
+save_project(project)  # Internally uses defensive file operations
+```
+
+## Phase 2 Roadmap
+
+The current implementation (Phase 1) provides a solid foundation. Phase 2 will add:
+
+### Intelligence Features (Phase 2)
+- **LLM Integration**: Task decomposition using CCSDK SessionManager
+- **Planning Mode**: Recursive task breakdown with AI assistance
+- **Working Mode**: Strategic task assignment and agent spawning
+
+### Multi-Agent Coordination (Phase 3)
+- **Agent Spawning**: Integration with amplifier's Task tool
+- **Load Balancing**: Distribute work across multiple agents
+- **Progress Monitoring**: Real-time coordination and status updates
+
+### Advanced Features (Phase 4+)
+- **Git Integration**: Version control and distributed coordination
+- **Performance Optimization**: Caching and selective loading
+- **CLI Interface**: Make commands for project management
+
+## Testing
+
+Run the comprehensive test suite:
+
+```bash
+# Run all planner tests
+uv run pytest amplifier/planner/tests/ -v
+
+# Run specific test
+uv run pytest amplifier/planner/tests/test_planner.py::TestTask::test_can_start_with_dependencies -v
+```
+
+Test coverage includes:
+- Task creation and validation
+- State management and transitions
+- Dependency checking logic
+- Project operations (hierarchy, children)
+- Storage persistence (save/load round-trip)
+- Integration workflows
+
+## Contributing
+
+When extending Super-Planner:
+
+1. **Follow amplifier's philosophy**: Ruthless simplicity, no unnecessary complexity
+2. **Maintain the contract**: Public API in `__init__.py` should remain stable
+3. **Test everything**: All functionality must have comprehensive tests
+4. **Use existing patterns**: Leverage amplifier's utilities and conventions
+
+## Performance Considerations
+
+Current implementation targets:
+- **Task Operations**: <1ms for state transitions and queries
+- **Storage Operations**: <100ms for save/load (with defensive retries)
+- **Memory Usage**: Minimal - load only current project data
+- **Scalability**: Supports 1000+ tasks per project efficiently
+
+## License
+
+Part of the amplifier project. See main project license.
\ No newline at end of file
diff --git a/amplifier/planner/__init__.py b/amplifier/planner/__init__.py
new file mode 100644
index 00000000..243d8754
--- /dev/null
+++ b/amplifier/planner/__init__.py
@@ -0,0 +1,33 @@
+"""Super-Planner: Multi-agent project coordination system."""
+
+from amplifier.planner.agent_mapper import assign_agent
+from amplifier.planner.agent_mapper import get_agent_workload
+from amplifier.planner.agent_mapper import suggest_agent_for_domain
+from amplifier.planner.decomposer import ProjectContext
+from amplifier.planner.decomposer import decompose_goal
+from amplifier.planner.decomposer import decompose_recursively
+from amplifier.planner.models import Project
+from amplifier.planner.models import Task
+from amplifier.planner.models import TaskState
+from amplifier.planner.orchestrator import ExecutionResults
+from amplifier.planner.orchestrator import TaskResult
+from amplifier.planner.orchestrator import orchestrate_execution
+from amplifier.planner.storage import load_project
+from amplifier.planner.storage import save_project
+
+__all__ = [
+    "Task",
+    "Project",
+    "TaskState",
+    "save_project",
+    "load_project",
+    "orchestrate_execution",
+    "ExecutionResults",
+    "TaskResult",
+    "decompose_goal",
+    "decompose_recursively",
+    "ProjectContext",
+    "assign_agent",
+    "get_agent_workload",
+    "suggest_agent_for_domain",
+]
diff --git a/amplifier/planner/agent_mapper.py b/amplifier/planner/agent_mapper.py
new file mode 100644
index 00000000..d5cc3ede
--- /dev/null
+++ b/amplifier/planner/agent_mapper.py
@@ -0,0 +1,296 @@
+"""Agent Mapper Module for Super-Planner Phase 2
+
+Purpose: Intelligent agent assignment based on task analysis and agent capabilities.
+Contract: Maps tasks to the best-suited specialized agent from available pool.
+
+This module is a self-contained brick that delivers intelligent agent assignment
+by analyzing task content and matching it against agent capabilities.
+
+Public Interface:
+    assign_agent(task: Task, available_agents: list[str]) -> str
+        Maps a task to the most appropriate agent based on task analysis.
+        Returns the agent name that best matches the task requirements.
+
+Dependencies:
+    - amplifier.planner.models.Task: Task data structure
+    - Standard library only (no external dependencies)
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+
+from amplifier.planner.models import Task
+
+logger = logging.getLogger(__name__)
+
+
+AGENT_CAPABILITIES = {
+    "zen-code-architect": {
+        "keywords": ["architecture", "design", "structure", "system", "blueprint", "specification"],
+        "patterns": ["design.*pattern", "architect.*", "system.*design", "module.*structure"],
+        "domains": ["architecture", "design", "planning"],
+        "priority": 9,
+    },
+    "modular-builder": {
+        "keywords": ["module", "component", "build", "implement", "create", "construct", "develop"],
+        "patterns": ["build.*module", "create.*component", "implement.*feature", "develop.*"],
+        "domains": ["implementation", "coding", "building"],
+        "priority": 8,
+    },
+    "bug-hunter": {
+        "keywords": ["bug", "error", "fix", "debug", "issue", "problem", "crash", "failure"],
+        "patterns": ["fix.*bug", "debug.*", "error.*handling", "solve.*issue", "troubleshoot"],
+        "domains": ["debugging", "fixing", "troubleshooting"],
+        "priority": 10,
+    },
+    "test-coverage": {
+        "keywords": ["test", "testing", "coverage", "unit", "integration", "validation", "verify"],
+        "patterns": ["write.*test", "test.*coverage", "unit.*test", "integration.*test"],
+        "domains": ["testing", "validation", "quality"],
+        "priority": 7,
+    },
+    "integration-specialist": {
+        "keywords": ["integrate", "api", "service", "connect", "interface", "endpoint", "webhook"],
+        "patterns": ["integrate.*service", "api.*connection", "connect.*system", "interface.*"],
+        "domains": ["integration", "apis", "connectivity"],
+        "priority": 8,
+    },
+    "refactor-architect": {
+        "keywords": ["refactor", "restructure", "optimize", "improve", "clean", "simplify"],
+        "patterns": ["refactor.*code", "restructure.*", "optimize.*performance", "clean.*up"],
+        "domains": ["refactoring", "optimization", "cleanup"],
+        "priority": 7,
+    },
+    "performance-optimizer": {
+        "keywords": ["performance", "speed", "optimize", "efficiency", "bottleneck", "slow"],
+        "patterns": ["improve.*performance", "optimize.*speed", "performance.*issue"],
+        "domains": ["performance", "optimization", "efficiency"],
+        "priority": 8,
+    },
+    "database-architect": {
+        "keywords": ["database", "sql", "query", "schema", "migration", "table", "index"],
+        "patterns": ["database.*design", "sql.*query", "schema.*migration", "optimize.*query"],
+        "domains": ["database", "sql", "data"],
+        "priority": 7,
+    },
+    "analysis-engine": {
+        "keywords": ["analyze", "analysis", "examine", "investigate", "study", "research"],
+        "patterns": ["analyze.*code", "investigate.*", "study.*pattern", "examine.*"],
+        "domains": ["analysis", "research", "investigation"],
+        "priority": 6,
+    },
+    "content-researcher": {
+        "keywords": ["research", "documentation", "content", "write", "document", "readme"],
+        "patterns": ["write.*documentation", "research.*", "document.*", "create.*readme"],
+        "domains": ["documentation", "writing", "research"],
+        "priority": 5,
+    },
+    "api-contract-designer": {
+        "keywords": ["api", "contract", "interface", "endpoint", "specification", "openapi"],
+        "patterns": ["design.*api", "api.*contract", "interface.*specification"],
+        "domains": ["api", "contracts", "specifications"],
+        "priority": 7,
+    },
+    "ambiguity-guardian": {
+        "keywords": ["clarify", "ambiguous", "unclear", "vague", "requirements", "specification"],
+        "patterns": ["clarify.*requirements", "unclear.*specification", "ambiguous.*"],
+        "domains": ["requirements", "clarification", "validation"],
+        "priority": 6,
+    },
+}
+
+DEFAULT_AGENT = "modular-builder"
+
+
+def _calculate_match_score(task: Task, agent_config: dict) -> float:
+    """Calculate how well an agent matches a task.
+
+    Args:
+        task: The task to analyze
+        agent_config: Agent capability configuration
+
+    Returns:
+        Score from 0.0 to 1.0 indicating match strength
+    """
+    score = 0.0
+    max_score = 0.0
+
+    task_text = f"{task.title} {task.description}".lower()
+
+    # Keyword matching (40% weight)
+    keyword_matches = sum(1 for kw in agent_config["keywords"] if kw in task_text)
+    if agent_config["keywords"]:
+        score += (keyword_matches / len(agent_config["keywords"])) * 0.4
+        max_score += 0.4
+
+    # Pattern matching (30% weight)
+    pattern_matches = 0
+    for pattern in agent_config.get("patterns", []):
+        if re.search(pattern, task_text, re.IGNORECASE):
+            pattern_matches += 1
+    if agent_config.get("patterns"):
+        score += (pattern_matches / len(agent_config["patterns"])) * 0.3
+        max_score += 0.3
+
+    # Priority boost (30% weight)
+    priority = agent_config.get("priority", 5) / 10.0
+    score += priority * 0.3
+    max_score += 0.3
+
+    return score / max_score if max_score > 0 else 0.0
+
+
+def _filter_available_agents(available_agents: list[str]) -> dict:
+    """Filter capability map to only include available agents.
+
+    Args:
+        available_agents: List of agent names that are available
+
+    Returns:
+        Filtered capabilities dictionary
+    """
+    filtered = {}
+    for agent_name in available_agents:
+        # Try exact match first
+        if agent_name in AGENT_CAPABILITIES:
+            filtered[agent_name] = AGENT_CAPABILITIES[agent_name]
+        else:
+            # Try normalized match (handle case differences)
+            normalized_name = agent_name.lower().replace("_", "-")
+            for known_agent, config in AGENT_CAPABILITIES.items():
+                if known_agent.lower() == normalized_name:
+                    filtered[agent_name] = config
+                    break
+
+    return filtered
+
+
+def assign_agent(task: Task, available_agents: list[str]) -> str:
+    """Assign the most appropriate agent to a task.
+
+    This function analyzes the task content and matches it against known
+    agent capabilities to find the best fit. It considers keywords, patterns,
+    and agent priority to make intelligent assignments.
+
+    Args:
+        task: Task object containing title, description, and metadata
+        available_agents: List of available agent names to choose from
+
+    Returns:
+        Name of the assigned agent (best match or default)
+
+    Raises:
+        ValueError: If no agents are available
+
+    Example:
+        >>> task = Task(id="1", title="Fix login bug", description="Users can't login")
+        >>> agents = ["bug-hunter", "modular-builder", "test-coverage"]
+        >>> assign_agent(task, agents)
+        "bug-hunter"
+    """
+    if not available_agents:
+        raise ValueError("No agents available for assignment")
+
+    # Get capabilities for available agents only
+    agent_capabilities = _filter_available_agents(available_agents)
+
+    # If no known agents match, use first available as fallback
+    if not agent_capabilities:
+        logger.warning(
+            f"No known capabilities for agents: {available_agents}. Using first available: {available_agents[0]}"
+        )
+        return available_agents[0]
+
+    # Calculate scores for each agent
+    scores = {}
+    for agent_name, config in agent_capabilities.items():
+        scores[agent_name] = _calculate_match_score(task, config)
+
+    # Find best match
+    best_agent = max(scores, key=lambda k: scores[k])
+    best_score = scores[best_agent]
+
+    # Log assignment decision
+    if best_score > 0.3:
+        logger.info(f"Assigned task '{task.title}' to agent '{best_agent}' (score: {best_score:.2f})")
+    else:
+        # Low confidence match - use default if available
+        if DEFAULT_AGENT in available_agents:
+            logger.info(f"Low confidence match for task '{task.title}'. Using default agent: {DEFAULT_AGENT}")
+            return DEFAULT_AGENT
+        logger.warning(
+            f"Low confidence match for task '{task.title}'. "
+            f"Using best available: {best_agent} (score: {best_score:.2f})"
+        )
+
+    return best_agent
+
+
+def get_agent_workload(tasks: list[Task]) -> dict:
+    """Calculate workload distribution across agents.
+
+    Analyzes a list of tasks to determine how many tasks are assigned
+    to each agent. Useful for load balancing and capacity planning.
+
+    Args:
+        tasks: List of tasks with agent assignments
+
+    Returns:
+        Dictionary mapping agent names to task counts
+
+    Example:
+        >>> tasks = [
+        ...     Task(id="1", title="Bug", assigned_to="bug-hunter"),
+        ...     Task(id="2", title="Test", assigned_to="test-coverage"),
+        ...     Task(id="3", title="Fix", assigned_to="bug-hunter")
+        ... ]
+        >>> get_agent_workload(tasks)
+        {"bug-hunter": 2, "test-coverage": 1}
+    """
+    workload = {}
+    for task in tasks:
+        if task.assigned_to:
+            workload[task.assigned_to] = workload.get(task.assigned_to, 0) + 1
+    return workload
+
+
+def suggest_agent_for_domain(domain: str, available_agents: list[str]) -> str:
+    """Suggest an agent based on a domain keyword.
+
+    Quick lookup function for finding agents that specialize in
+    particular domains like "testing", "performance", etc.
+
+    Args:
+        domain: Domain keyword (e.g., "testing", "database", "api")
+        available_agents: List of available agent names
+
+    Returns:
+        Suggested agent name or default if no match found
+
+    Example:
+        >>> suggest_agent_for_domain("testing", ["test-coverage", "bug-hunter"])
+        "test-coverage"
+    """
+    domain_lower = domain.lower()
+    agent_capabilities = _filter_available_agents(available_agents)
+
+    # Find agents with matching domains
+    matches = []
+    for agent_name, config in agent_capabilities.items():
+        if domain_lower in [d.lower() for d in config.get("domains", [])]:
+            matches.append((agent_name, config.get("priority", 5)))
+
+    if matches:
+        # Return highest priority match
+        matches.sort(key=lambda x: x[1], reverse=True)
+        return matches[0][0]
+
+    # Fallback to default or first available
+    if DEFAULT_AGENT in available_agents:
+        return DEFAULT_AGENT
+    return available_agents[0] if available_agents else DEFAULT_AGENT
+
+
+__all__ = ["assign_agent", "get_agent_workload", "suggest_agent_for_domain"]
diff --git a/amplifier/planner/contracts/README.md b/amplifier/planner/contracts/README.md
new file mode 100644
index 00000000..44cecc56
--- /dev/null
+++ b/amplifier/planner/contracts/README.md
@@ -0,0 +1,203 @@
+# Super-Planner API Contracts
+
+This directory contains the comprehensive API contracts for the super-planner system, following amplifier's "bricks and studs" philosophy.
+
+## Overview
+
+The contracts defined here represent the stable "studs" (connection points) that enable the super-planner to be regenerated internally without breaking external integrations. These contracts are the promises we make to consumers of the planner API.
+
+## Contract Files
+
+### 1. `__init__.py` - Core Python API Contracts
+- **Data Models**: `Task`, `Project`, `TaskStatus`, `ProjectStatus`, `AgentType`
+- **Module Protocols**: `CoreModule`, `PlanningMode`, `WorkingMode`, `PersistenceLayer`, `EventSystem`
+- **Integration Protocols**: `AmplifierIntegration`, `LLMService`
+- **Event Schemas**: `TaskEvent`, `AgentEvent`
+- **Factory Functions**: `create_planner()`, `load_planner()`
+
+### 2. `openapi.yaml` - REST API Specification
+- Complete OpenAPI 3.0 specification
+- RESTful endpoints for projects, tasks, planning, orchestration
+- Server-sent events (SSE) for real-time updates
+- Standard error response formats
+- Request/response schemas
+
+### 3. `integration.md` - Ecosystem Integration
+- CLI integration via make commands
+- Task tool integration for agent spawning
+- CCSDK toolkit integration with defensive utilities
+- Git workflow integration
+- Event system contracts
+- Extension points for customization
+
+### 4. `validation.py` - Contract Validation
+- `ContractValidator`: Runtime validation of protocol implementations
+- `ContractTest`: Base class for contract-based testing
+- `ContractMonitor`: Production monitoring of contract compliance
+- Validation utilities for data models, serialization, and API responses
+
+## Design Principles
+
+### 1. Ruthless Simplicity
+Every endpoint and method has a single, clear purpose. No unnecessary complexity or premature abstraction.
+
+### 2. Stable Connection Points
+The external contracts (public API) remain stable even as internal implementations change. This enables module regeneration without breaking consumers.
+
+### 3. Git-Friendly Persistence
+All data serialization uses sorted JSON keys for clean git diffs and version control integration.
+
+### 4. Defensive by Default
+Integration with CCSDK defensive utilities for robust LLM interaction and error handling.
+
+## Usage Examples
+
+### Python Module Usage
+```python
+from amplifier.planner import create_planner
+
+# Create planner with configuration
+planner = await create_planner({
+    "persistence_dir": "data/projects",
+    "git_enabled": True,
+    "max_concurrent_agents": 5
+})
+
+# Create and plan project
+project = await planner.create_project(
+    name="API Redesign",
+    goal="Redesign user API following REST principles"
+)
+
+# Decompose into tasks
+tasks = await planner.decompose_goal(project.goal)
+
+# Assign and execute
+await planner.assign_tasks([t.id for t in tasks])
+await planner.execute_project(project.id)
+```
+
+### CLI Usage
+```bash
+# Create new project
+make planner-new NAME="API Redesign" GOAL="Redesign user API"
+
+# Decompose into tasks
+make planner-decompose PROJECT_ID="project-123"
+
+# Assign tasks to agents
+make planner-assign PROJECT_ID="project-123" STRATEGY="optimal"
+
+# Execute with monitoring
+make planner-execute PROJECT_ID="project-123"
+make planner-monitor PROJECT_ID="project-123"
+```
+
+### REST API Usage
+```bash
+# Create project
+curl -X POST http://localhost:8000/api/v1/projects \
+  -H "Content-Type: application/json" \
+  -d '{"name": "API Redesign", "goal": "Redesign user API"}'
+
+# Decompose goal
+curl -X POST http://localhost:8000/api/v1/planning/decompose \
+  -H "Content-Type: application/json" \
+  -d '{"goal": "Redesign user API"}'
+
+# Stream events
+curl -N http://localhost:8000/api/v1/events/stream?project_id=project-123
+```
+
+## Contract Stability Guarantees
+
+### Stable (Won't Break)
+- Public API methods in `__init__.py`
+- OpenAPI endpoint paths and response schemas
+- Core data model fields (`Task`, `Project`)
+- Event type names and required fields
+- CLI command interfaces
+
+### Evolvable (May Extend)
+- Optional parameters and fields (additions okay)
+- New endpoints (additions okay)
+- New event types (additions okay)
+- Internal module implementations (can be regenerated)
+- Configuration options (new options with defaults okay)
+
+### Versioned Changes
+- Breaking changes require major version bump (v1 -> v2)
+- Deprecation notices maintained for 2 major versions
+- Migration tools provided for data format changes
+
+## Testing Contracts
+
+### Unit Testing
+```python
+from amplifier.planner.contracts.validation import ContractTest
+
+class TestPlannerImplementation(ContractTest):
+    def test_core_module_contract(self):
+        core = MyCoreImplementation()
+        self.assert_implements_protocol(core, CoreModule)
+    
+    def test_task_serialization(self):
+        task = create_test_task()
+        self.assert_serializable(task, Task)
+```
+
+### Runtime Monitoring
+```python
+from amplifier.planner.contracts.validation import ContractMonitor
+
+monitor = ContractMonitor(logger)
+monitor.check_protocol(my_implementation, PlanningMode)
+monitor.check_data_model(task_instance, Task)
+
+# Get violation report
+report = monitor.get_report()
+```
+
+## Extension Points
+
+The planner provides several extension points for customization without modifying core contracts:
+
+1. **Custom Agent Types**: Register new agent types with selection criteria
+2. **Assignment Strategies**: Implement custom task assignment algorithms  
+3. **Persistence Backends**: Swap file-based storage for database or cloud
+4. **Event Handlers**: Subscribe to events for custom workflows
+5. **Planning Strategies**: Override decomposition algorithms
+
+## Integration with Amplifier Philosophy
+
+These contracts embody amplifier's core principles:
+
+- **Ruthless Simplicity**: Minimal, focused APIs without over-engineering
+- **Bricks and Studs**: Clear module boundaries with stable connection points
+- **Regenerability**: Internal modules can be rebuilt without breaking contracts
+- **Present-Focus**: Solve current needs, not hypothetical futures
+- **Trust in Emergence**: Let complex behavior emerge from simple, well-defined pieces
+
+## Compliance Checklist
+
+When implementing or modifying the planner:
+
+- [ ] All public methods match protocol signatures
+- [ ] Data models serialize/deserialize correctly
+- [ ] JSON uses sorted keys for git-friendliness
+- [ ] API responses match OpenAPI schemas
+- [ ] Events include required fields
+- [ ] Error codes follow standard format
+- [ ] Integration tests pass with mock implementations
+- [ ] Contract validation tests pass
+- [ ] Documentation updated for any contract changes
+
+## Next Steps
+
+1. Implement core modules following these contracts
+2. Create contract tests for each module
+3. Set up runtime contract monitoring
+4. Build CLI and REST API layers
+5. Integrate with amplifier's existing tools
+
+The contracts defined here provide the stable foundation for building a robust, regenerable task planning and orchestration system that fits seamlessly into the amplifier ecosystem.
diff --git a/amplifier/planner/contracts/__init__.py b/amplifier/planner/contracts/__init__.py
new file mode 100644
index 00000000..b0f1f14b
--- /dev/null
+++ b/amplifier/planner/contracts/__init__.py
@@ -0,0 +1,526 @@
+"""
+Super-Planner API Contracts
+
+This module defines the stable API contracts ("studs") for the super-planner system,
+following amplifier's bricks-and-studs philosophy. These contracts enable module
+regeneration without breaking external consumers.
+
+The contracts are organized into:
+- External APIs: Public interfaces for amplifier ecosystem integration
+- Internal contracts: Module boundaries within the planner
+- Data exchange formats: Standardized data structures
+- Event schemas: Notification and audit trail formats
+"""
+
+import json
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from dataclasses import field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+from typing import Optional
+from typing import Protocol
+
+# ============================================================================
+# CORE DATA MODELS (Stable External Contracts)
+# ============================================================================
+
+
+class TaskStatus(str, Enum):
+    """Task lifecycle states"""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    BLOCKED = "blocked"
+
+
+class TaskType(str, Enum):
+    """Task classification"""
+
+    GOAL = "goal"
+    TASK = "task"
+    SUBTASK = "subtask"
+
+
+class ProjectStatus(str, Enum):
+    """Project lifecycle states"""
+
+    ACTIVE = "active"
+    COMPLETED = "completed"
+    ARCHIVED = "archived"
+
+
+class AgentType(str, Enum):
+    """Available agent types from amplifier ecosystem"""
+
+    ZEN_ARCHITECT = "zen-architect"
+    MODULAR_BUILDER = "modular-builder"
+    TEST_COVERAGE = "test-coverage"
+    BUG_HUNTER = "bug-hunter"
+    REFACTOR_ARCHITECT = "refactor-architect"
+    INTEGRATION_SPECIALIST = "integration-specialist"
+    DATABASE_ARCHITECT = "database-architect"
+    API_CONTRACT_DESIGNER = "api-contract-designer"
+    CUSTOM = "custom"
+
+
+@dataclass
+class Task:
+    """Core task data model - stable external contract"""
+
+    id: str
+    project_id: str
+    title: str
+    description: str
+    type: TaskType
+    status: TaskStatus
+
+    # Relationships
+    parent_id: str | None = None
+    dependencies: list[str] = field(default_factory=list)
+    subtasks: list[str] = field(default_factory=list)
+
+    # Assignment
+    assigned_to: str | None = None
+    suggested_agent: AgentType | None = None
+
+    # Timing
+    created_at: datetime = field(default_factory=datetime.now)
+    updated_at: datetime = field(default_factory=datetime.now)
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+
+    # Results and metadata
+    result: dict[str, Any] | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    version: int = 1
+
+    def to_json(self) -> str:
+        """Serialize to JSON with sorted keys for git-friendly storage"""
+        data = {
+            "id": self.id,
+            "project_id": self.project_id,
+            "title": self.title,
+            "description": self.description,
+            "type": self.type.value,
+            "status": self.status.value,
+            "parent_id": self.parent_id,
+            "dependencies": sorted(self.dependencies),
+            "subtasks": sorted(self.subtasks),
+            "assigned_to": self.assigned_to,
+            "suggested_agent": self.suggested_agent.value if self.suggested_agent else None,
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+            "started_at": self.started_at.isoformat() if self.started_at else None,
+            "completed_at": self.completed_at.isoformat() if self.completed_at else None,
+            "result": self.result,
+            "metadata": self.metadata,
+            "version": self.version,
+        }
+        return json.dumps(data, sort_keys=True, indent=2)
+
+    @classmethod
+    def from_json(cls, data: str) -> "Task":
+        """Deserialize from JSON"""
+        obj = json.loads(data)
+        return cls(
+            id=obj["id"],
+            project_id=obj["project_id"],
+            title=obj["title"],
+            description=obj["description"],
+            type=TaskType(obj["type"]),
+            status=TaskStatus(obj["status"]),
+            parent_id=obj.get("parent_id"),
+            dependencies=obj.get("dependencies", []),
+            subtasks=obj.get("subtasks", []),
+            assigned_to=obj.get("assigned_to"),
+            suggested_agent=AgentType(obj["suggested_agent"]) if obj.get("suggested_agent") else None,
+            created_at=datetime.fromisoformat(obj["created_at"]),
+            updated_at=datetime.fromisoformat(obj["updated_at"]),
+            started_at=datetime.fromisoformat(obj["started_at"]) if obj.get("started_at") else None,
+            completed_at=datetime.fromisoformat(obj["completed_at"]) if obj.get("completed_at") else None,
+            result=obj.get("result"),
+            metadata=obj.get("metadata", {}),
+            version=obj.get("version", 1),
+        )
+
+
+@dataclass
+class Project:
+    """Project data model - stable external contract"""
+
+    id: str
+    name: str
+    description: str
+    goal: str
+    status: ProjectStatus
+
+    # Timing
+    created_at: datetime = field(default_factory=datetime.now)
+    updated_at: datetime = field(default_factory=datetime.now)
+    completed_at: datetime | None = None
+
+    # Metadata
+    metadata: dict[str, Any] = field(default_factory=dict)
+    version: int = 1
+
+    def to_json(self) -> str:
+        """Serialize to JSON with sorted keys"""
+        data = {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "goal": self.goal,
+            "status": self.status.value,
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+            "completed_at": self.completed_at.isoformat() if self.completed_at else None,
+            "metadata": self.metadata,
+            "version": self.version,
+        }
+        return json.dumps(data, sort_keys=True, indent=2)
+
+    @classmethod
+    def from_json(cls, data: str) -> "Project":
+        """Deserialize from JSON"""
+        obj = json.loads(data)
+        return cls(
+            id=obj["id"],
+            name=obj["name"],
+            description=obj["description"],
+            goal=obj["goal"],
+            status=ProjectStatus(obj["status"]),
+            created_at=datetime.fromisoformat(obj["created_at"]),
+            updated_at=datetime.fromisoformat(obj["updated_at"]),
+            completed_at=datetime.fromisoformat(obj["completed_at"]) if obj.get("completed_at") else None,
+            metadata=obj.get("metadata", {}),
+            version=obj.get("version", 1),
+        )
+
+
+# ============================================================================
+# MODULE INTERFACES (Internal Contracts Between Planner Modules)
+# ============================================================================
+
+
+class CoreModule(Protocol):
+    """Contract for the core task/project management module"""
+
+    async def create_project(self, name: str, goal: str, description: str = "") -> Project:
+        """Create a new project"""
+        ...
+
+    async def get_project(self, project_id: str) -> Project | None:
+        """Retrieve project by ID"""
+        ...
+
+    async def update_project(self, project_id: str, **updates) -> Project:
+        """Update project with optimistic locking"""
+        ...
+
+    async def create_task(self, project_id: str, title: str, **kwargs) -> Task:
+        """Create a new task"""
+        ...
+
+    async def get_task(self, task_id: str) -> Task | None:
+        """Retrieve task by ID"""
+        ...
+
+    async def update_task(self, task_id: str, **updates) -> Task:
+        """Update task with optimistic locking"""
+        ...
+
+    async def transition_task(self, task_id: str, new_status: TaskStatus, reason: str = "") -> Task:
+        """Transition task state with validation"""
+        ...
+
+    async def list_tasks(self, project_id: str, **filters) -> list[Task]:
+        """List tasks with optional filtering"""
+        ...
+
+
+class PlanningMode(Protocol):
+    """Contract for planning mode operations"""
+
+    async def decompose_goal(self, goal: str, context: dict | None = None) -> list[Task]:
+        """Decompose high-level goal into tasks using LLM"""
+        ...
+
+    async def refine_plan(self, tasks: list[Task], feedback: str) -> list[Task]:
+        """Refine task breakdown based on feedback"""
+        ...
+
+    async def suggest_dependencies(self, tasks: list[Task]) -> dict[str, list[str]]:
+        """Analyze and suggest task dependencies"""
+        ...
+
+    async def estimate_effort(self, task: Task) -> str:
+        """Estimate task effort (xs, s, m, l, xl)"""
+        ...
+
+
+class WorkingMode(Protocol):
+    """Contract for working mode operations"""
+
+    async def assign_tasks(self, task_ids: list[str], strategy: str = "optimal") -> dict[str, str]:
+        """Assign tasks to agents based on strategy"""
+        ...
+
+    async def spawn_agent(self, task_id: str, agent_type: AgentType) -> str:
+        """Spawn sub-agent for task execution"""
+        ...
+
+    async def coordinate_agents(self, project_id: str) -> None:
+        """Orchestrate multi-agent execution"""
+        ...
+
+    async def handle_deadlock(self, blocked_tasks: list[str]) -> None:
+        """Resolve dependency deadlocks"""
+        ...
+
+
+class PersistenceLayer(Protocol):
+    """Contract for persistence operations"""
+
+    async def save_project(self, project: Project) -> None:
+        """Persist project to storage"""
+        ...
+
+    async def load_project(self, project_id: str) -> Project | None:
+        """Load project from storage"""
+        ...
+
+    async def save_task(self, task: Task) -> None:
+        """Persist task to storage"""
+        ...
+
+    async def load_task(self, task_id: str) -> Task | None:
+        """Load task from storage"""
+        ...
+
+    async def list_all_tasks(self, project_id: str) -> list[Task]:
+        """Load all tasks for a project"""
+        ...
+
+    async def create_snapshot(self, project_id: str) -> str:
+        """Create git snapshot, return commit hash"""
+        ...
+
+    async def restore_snapshot(self, project_id: str, commit_hash: str) -> None:
+        """Restore from git snapshot"""
+        ...
+
+
+class EventSystem(Protocol):
+    """Contract for event publishing and audit trail"""
+
+    async def emit_event(self, event_type: str, data: dict[str, Any]) -> None:
+        """Publish event for subscribers"""
+        ...
+
+    async def subscribe(self, event_types: list[str]) -> AsyncIterator[dict]:
+        """Subscribe to event stream"""
+        ...
+
+    async def get_audit_trail(self, entity_id: str) -> list[dict]:
+        """Retrieve audit trail for entity"""
+        ...
+
+
+# ============================================================================
+# EXTERNAL INTEGRATION CONTRACTS
+# ============================================================================
+
+
+class AmplifierIntegration(Protocol):
+    """Contract for integration with amplifier ecosystem"""
+
+    async def spawn_task_agent(self, agent_type: str, prompt: str, context: dict) -> dict:
+        """Spawn sub-agent using amplifier's Task tool"""
+        ...
+
+    async def get_ccsdk_session(self) -> Any:
+        """Get CCSDK SessionManager instance"""
+        ...
+
+    async def call_defensive_utility(self, utility: str, **kwargs) -> Any:
+        """Call CCSDK defensive utility"""
+        ...
+
+
+class LLMService(Protocol):
+    """Contract for LLM service integration"""
+
+    async def generate(self, prompt: str, system_prompt: str = "", **kwargs) -> str:
+        """Generate LLM response"""
+        ...
+
+    async def parse_json_response(self, response: str) -> dict:
+        """Parse JSON from LLM response using defensive utilities"""
+        ...
+
+
+# ============================================================================
+# EVENT SCHEMAS
+# ============================================================================
+
+
+@dataclass
+class TaskEvent:
+    """Standard event format for task changes"""
+
+    event_type: str  # task_created, task_updated, task_completed, etc.
+    task_id: str
+    project_id: str
+    timestamp: datetime
+    actor: str | None = None  # User or agent ID
+    changes: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_json(self) -> str:
+        """Serialize to JSON"""
+        return json.dumps(
+            {
+                "event_type": self.event_type,
+                "task_id": self.task_id,
+                "project_id": self.project_id,
+                "timestamp": self.timestamp.isoformat(),
+                "actor": self.actor,
+                "changes": self.changes,
+                "metadata": self.metadata,
+            },
+            sort_keys=True,
+        )
+
+
+@dataclass
+class AgentEvent:
+    """Standard event format for agent coordination"""
+
+    event_type: str  # agent_spawned, agent_completed, agent_failed
+    agent_id: str
+    agent_type: str
+    task_id: str | None
+    timestamp: datetime
+    status: str
+    result: dict[str, Any] | None = None
+    error: str | None = None
+
+    def to_json(self) -> str:
+        """Serialize to JSON"""
+        return json.dumps(
+            {
+                "event_type": self.event_type,
+                "agent_id": self.agent_id,
+                "agent_type": self.agent_type,
+                "task_id": self.task_id,
+                "timestamp": self.timestamp.isoformat(),
+                "status": self.status,
+                "result": self.result,
+                "error": self.error,
+            },
+            sort_keys=True,
+        )
+
+
+# ============================================================================
+# PUBLIC API EXPORTS (The "Studs" for External Use)
+# ============================================================================
+
+__all__ = [
+    # Core data models
+    "Task",
+    "Project",
+    "TaskStatus",
+    "TaskType",
+    "ProjectStatus",
+    "AgentType",
+    # Module interfaces
+    "CoreModule",
+    "PlanningMode",
+    "WorkingMode",
+    "PersistenceLayer",
+    "EventSystem",
+    # Integration contracts
+    "AmplifierIntegration",
+    "LLMService",
+    # Event schemas
+    "TaskEvent",
+    "AgentEvent",
+]
+
+
+# ============================================================================
+# PYTHON MODULE INTERFACE (For Direct Import)
+# ============================================================================
+
+
+async def create_planner(config: dict[str, Any] | None = None):
+    """
+    Factory function to create configured planner instance.
+    This is the main entry point for Python code using the planner.
+
+    Usage:
+        from amplifier.planner import create_planner
+
+        planner = await create_planner({
+            "persistence_dir": "/path/to/data",
+            "git_enabled": True,
+            "max_concurrent_agents": 5
+        })
+
+        project = await planner.create_project("My Project", "Build awesome feature")
+        tasks = await planner.decompose_goal(project.goal)
+    """
+    # Implementation will be in the main module
+    from amplifier.planner.main import Planner
+
+    return await Planner.create(config or {})
+
+
+async def load_planner(project_id: str, config: dict[str, Any] | None = None):
+    """
+    Load existing planner with project.
+
+    Usage:
+        planner = await load_planner("project-123")
+        tasks = await planner.list_tasks()
+    """
+    from amplifier.planner.main import Planner
+
+    planner = await Planner.create(config or {})
+    await planner.load_project(project_id)
+    return planner
+
+
+# ============================================================================
+# CLI INTERFACE CONTRACT
+# ============================================================================
+
+
+class CLICommands:
+    """
+    Defines the CLI interface for make commands.
+    These map to the main entry points in __main__.py
+    """
+
+    # Project commands
+    PLANNER_NEW = "planner-new"  # Create new project
+    PLANNER_LOAD = "planner-load"  # Load existing project
+    PLANNER_STATUS = "planner-status"  # Show project status
+
+    # Planning mode
+    PLANNER_DECOMPOSE = "planner-decompose"  # Decompose goal into tasks
+    PLANNER_REFINE = "planner-refine"  # Refine task breakdown
+
+    # Working mode
+    PLANNER_ASSIGN = "planner-assign"  # Assign tasks to agents
+    PLANNER_EXECUTE = "planner-execute"  # Start execution
+    PLANNER_MONITOR = "planner-monitor"  # Monitor progress
+
+    # Utilities
+    PLANNER_EXPORT = "planner-export"  # Export project data
+    PLANNER_IMPORT = "planner-import"  # Import project data
diff --git a/amplifier/planner/contracts/integration.md b/amplifier/planner/contracts/integration.md
new file mode 100644
index 00000000..ec11525a
--- /dev/null
+++ b/amplifier/planner/contracts/integration.md
@@ -0,0 +1,522 @@
+# Super-Planner Integration Contracts
+
+This document specifies the integration contracts between the super-planner and the amplifier ecosystem, following the "bricks and studs" philosophy.
+
+## Overview
+
+The super-planner integrates with amplifier as a self-contained "brick" with well-defined "studs" (connection points). These contracts ensure the planner can be regenerated internally without breaking external integrations.
+
+## Integration Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   Amplifier Ecosystem                    │
+├─────────────────────────────────────────────────────────┤
+│                                                          │
+│  ┌──────────┐   ┌──────────┐   ┌──────────┐           │
+│  │   CLI    │   │   Task   │   │  CCSDK   │           │
+│  │Commands  │   │   Tool   │   │ Toolkit  │           │
+│  └────┬─────┘   └────┬─────┘   └────┬─────┘           │
+│       │              │              │                   │
+│       ▼              ▼              ▼                   │
+│  ┌─────────────────────────────────────────┐           │
+│  │        Super-Planner Public API         │           │
+│  │         (Stable Contract Layer)         │           │
+│  └─────────────────────────────────────────┘           │
+│                      │                                  │
+│  ┌─────────────────────────────────────────┐           │
+│  │         Internal Module Contracts       │           │
+│  │  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │           │
+│  │  │ Core │ │Modes │ │Persist│ │Orch. │ │           │
+│  │  └──────┘ └──────┘ └──────┘ └──────┘ │           │
+│  └─────────────────────────────────────────┘           │
+│                                                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 1. CLI Integration Contract
+
+### Make Commands
+
+The planner exposes the following make commands in amplifier's Makefile:
+
+```makefile
+# Project Management
+planner-new:
+	@uv run python -m amplifier.planner new \
+		--name "$(NAME)" \
+		--goal "$(GOAL)" \
+		--output "$(OUTPUT_DIR)"
+
+planner-load:
+	@uv run python -m amplifier.planner load \
+		--project-id "$(PROJECT_ID)"
+
+planner-status:
+	@uv run python -m amplifier.planner status \
+		--project-id "$(PROJECT_ID)" \
+		--format "$(FORMAT)"  # json, table, summary
+
+# Planning Mode
+planner-decompose:
+	@uv run python -m amplifier.planner decompose \
+		--project-id "$(PROJECT_ID)" \
+		--max-depth "$(MAX_DEPTH)" \
+		--max-tasks "$(MAX_TASKS)"
+
+planner-refine:
+	@uv run python -m amplifier.planner refine \
+		--project-id "$(PROJECT_ID)" \
+		--feedback "$(FEEDBACK)"
+
+# Working Mode  
+planner-assign:
+	@uv run python -m amplifier.planner assign \
+		--project-id "$(PROJECT_ID)" \
+		--strategy "$(STRATEGY)"  # optimal, round_robin, load_balanced
+
+planner-execute:
+	@uv run python -m amplifier.planner execute \
+		--project-id "$(PROJECT_ID)" \
+		--max-concurrent "$(MAX_CONCURRENT)"
+
+planner-monitor:
+	@uv run python -m amplifier.planner monitor \
+		--project-id "$(PROJECT_ID)" \
+		--follow
+```
+
+### Python Module Usage
+
+Direct Python integration:
+
+```python
+from amplifier.planner import create_planner, load_planner
+
+# Create new planner
+planner = await create_planner({
+    "persistence_dir": "data/projects",
+    "git_enabled": True
+})
+
+# Create and decompose project
+project = await planner.create_project(
+    name="API Redesign",
+    goal="Redesign user API following REST principles"
+)
+
+tasks = await planner.decompose_goal(project.goal)
+
+# Assign and execute
+assignments = await planner.assign_tasks([t.id for t in tasks])
+await planner.execute_project(project.id)
+```
+
+## 2. Task Tool Integration Contract
+
+### Spawning Sub-Agents
+
+The planner uses amplifier's Task tool to spawn specialized agents:
+
+```python
+# Contract for agent spawning
+async def spawn_agent(task_id: str, agent_type: str) -> Dict:
+    """
+    Spawn sub-agent using amplifier's Task tool.
+    
+    Returns:
+        {
+            "agent_id": "agent-123",
+            "status": "spawning",
+            "task_id": "task-456",
+            "result_channel": "channel-789"
+        }
+    """
+    
+    # Build agent prompt from task
+    task = await self.get_task(task_id)
+    prompt = self._build_agent_prompt(task)
+    
+    # Call amplifier's Task tool
+    result = await self.amplifier.spawn_task_agent(
+        agent_type=agent_type,
+        prompt=prompt,
+        context={
+            "task_id": task_id,
+            "project_id": task.project_id,
+            "dependencies": task.dependencies,
+            "working_directory": self.get_working_dir(task.project_id)
+        }
+    )
+    
+    return result
+```
+
+### Agent Types Mapping
+
+```python
+AGENT_TYPE_MAPPING = {
+    "architecture": "zen-architect",
+    "implementation": "modular-builder",
+    "testing": "test-coverage",
+    "debugging": "bug-hunter",
+    "refactoring": "refactor-architect",
+    "integration": "integration-specialist",
+    "database": "database-architect",
+    "api": "api-contract-designer"
+}
+```
+
+## 3. CCSDK Integration Contract
+
+### SessionManager Integration
+
+```python
+from amplifier.ccsdk_toolkit import SessionManager, ClaudeSession
+
+class PlannerSession:
+    """Integrates with CCSDK SessionManager for LLM operations"""
+    
+    def __init__(self):
+        self.session_manager = SessionManager()
+        self.claude_session = None
+    
+    async def initialize(self):
+        """Initialize Claude session with defensive utilities"""
+        self.claude_session = await self.session_manager.create_session(
+            model="claude-3-opus-20240229",
+            use_defensive=True
+        )
+    
+    async def decompose_with_llm(self, goal: str) -> List[Dict]:
+        """Use CCSDK defensive utilities for robust JSON parsing"""
+        from amplifier.ccsdk_toolkit.defensive import parse_llm_json
+        
+        response = await self.claude_session.generate(
+            prompt=f"Decompose this goal into tasks: {goal}",
+            system_prompt=DECOMPOSITION_PROMPT
+        )
+        
+        # Use defensive JSON parsing
+        tasks_data = parse_llm_json(response)
+        return tasks_data.get("tasks", [])
+```
+
+### Defensive Utilities Usage
+
+```python
+from amplifier.ccsdk_toolkit.defensive import (
+    parse_llm_json,
+    retry_with_feedback,
+    isolate_prompt
+)
+
+class PlannerLLM:
+    """Uses CCSDK defensive utilities"""
+    
+    async def safe_decompose(self, goal: str) -> List[Task]:
+        """Decompose with retry and error recovery"""
+        
+        # Isolate user content from system prompts
+        clean_goal = isolate_prompt(goal)
+        
+        # Retry with feedback on failure
+        result = await retry_with_feedback(
+            async_func=self.decompose_goal,
+            prompt=clean_goal,
+            max_retries=3
+        )
+        
+        # Parse JSON safely
+        tasks_data = parse_llm_json(result)
+        return self._convert_to_tasks(tasks_data)
+```
+
+## 4. Git Integration Contract
+
+### File Structure
+
+```
+data/projects/
+├── {project_id}/
+│   ├── project.json       # Project metadata
+│   ├── tasks/
+│   │   ├── {task_id}.json # Individual task files
+│   │   └── index.json     # Task index
+│   ├── assignments/
+│   │   └── index.json     # Agent assignments
+│   ├── events/
+│   │   └── {date}.jsonl   # Event log files
+│   └── .git/              # Git repository
+```
+
+### Git Operations
+
+```python
+class GitPersistence:
+    """Git integration for version control"""
+    
+    async def save_with_commit(self, project_id: str, message: str):
+        """Save and commit changes"""
+        # Save all JSON with sorted keys
+        await self.save_project(project)
+        await self.save_all_tasks(tasks)
+        
+        # Git operations
+        await self.run_command(f"git add -A", cwd=project_dir)
+        await self.run_command(
+            f'git commit -m "{message}"',
+            cwd=project_dir
+        )
+    
+    async def create_checkpoint(self, project_id: str) -> str:
+        """Create git tag for checkpoint"""
+        timestamp = datetime.now().isoformat()
+        tag = f"checkpoint-{timestamp}"
+        await self.run_command(
+            f'git tag {tag}',
+            cwd=self.get_project_dir(project_id)
+        )
+        return tag
+```
+
+## 5. Event System Contract
+
+### Event Publication
+
+```python
+class EventPublisher:
+    """Publishes events for external consumers"""
+    
+    async def emit(self, event_type: str, data: Dict):
+        """Emit event to subscribers"""
+        event = {
+            "event_type": event_type,
+            "timestamp": datetime.now().isoformat(),
+            "data": data
+        }
+        
+        # Write to event log
+        await self.append_to_log(event)
+        
+        # Notify SSE subscribers if configured
+        if self.sse_enabled:
+            await self.sse_manager.broadcast(event)
+```
+
+### Standard Event Types
+
+```python
+EVENT_TYPES = {
+    # Task events
+    "task.created": "New task created",
+    "task.updated": "Task updated",
+    "task.started": "Task execution started",
+    "task.completed": "Task completed successfully",
+    "task.failed": "Task execution failed",
+    "task.blocked": "Task blocked by dependencies",
+    
+    # Agent events
+    "agent.spawned": "Sub-agent spawned",
+    "agent.assigned": "Agent assigned to task",
+    "agent.completed": "Agent completed task",
+    "agent.failed": "Agent failed",
+    
+    # Project events
+    "project.created": "Project created",
+    "project.updated": "Project updated",
+    "project.completed": "All tasks completed",
+    
+    # Planning events
+    "planning.started": "Decomposition started",
+    "planning.completed": "Decomposition completed",
+    "planning.refined": "Plan refined"
+}
+```
+
+## 6. Extension Points Contract
+
+### Custom Agent Types
+
+```python
+class AgentRegistry:
+    """Registry for custom agent types"""
+    
+    def register_agent_type(
+        self,
+        name: str,
+        selector: Callable[[Task], bool],
+        spawner: Callable[[Task], Dict]
+    ):
+        """Register custom agent type"""
+        self.custom_agents[name] = {
+            "selector": selector,  # Function to match tasks
+            "spawner": spawner    # Function to spawn agent
+        }
+```
+
+### Custom Assignment Strategies
+
+```python
+class AssignmentStrategy(Protocol):
+    """Protocol for custom assignment strategies"""
+    
+    async def assign(
+        self,
+        tasks: List[Task],
+        available_agents: List[str]
+    ) -> Dict[str, str]:
+        """Return task_id -> agent_id mapping"""
+        ...
+
+# Register custom strategy
+planner.register_strategy("my_strategy", MyCustomStrategy())
+```
+
+### Custom Persistence Backends
+
+```python
+class PersistenceBackend(Protocol):
+    """Protocol for custom persistence"""
+    
+    async def save(self, key: str, data: str) -> None:
+        """Save data with key"""
+        ...
+    
+    async def load(self, key: str) -> Optional[str]:
+        """Load data by key"""
+        ...
+    
+    async def list(self, prefix: str) -> List[str]:
+        """List keys with prefix"""
+        ...
+```
+
+## 7. Resource Management Contract
+
+### Concurrency Control
+
+```python
+class ResourceManager:
+    """Manages concurrent agent execution"""
+    
+    MAX_CONCURRENT_AGENTS = 5
+    MAX_MEMORY_PER_AGENT = "1GB"
+    MAX_TIME_PER_TASK = 300  # seconds
+    
+    async def acquire_slot(self, agent_id: str) -> bool:
+        """Acquire execution slot for agent"""
+        if self.active_count < self.MAX_CONCURRENT_AGENTS:
+            self.active_agents[agent_id] = datetime.now()
+            return True
+        return False
+    
+    async def release_slot(self, agent_id: str):
+        """Release execution slot"""
+        self.active_agents.pop(agent_id, None)
+```
+
+## 8. Error Handling Contract
+
+### Standard Error Codes
+
+```python
+class PlannerError(Exception):
+    """Base planner exception"""
+    code: str
+    message: str
+    details: Dict[str, Any]
+
+ERROR_CODES = {
+    "PROJECT_NOT_FOUND": "Project does not exist",
+    "TASK_NOT_FOUND": "Task does not exist",
+    "INVALID_TRANSITION": "Invalid state transition",
+    "AGENT_SPAWN_FAILED": "Failed to spawn agent",
+    "DEPENDENCY_CYCLE": "Circular dependency detected",
+    "RESOURCE_EXHAUSTED": "No available execution slots",
+    "PERSISTENCE_ERROR": "Failed to save/load data",
+    "GIT_ERROR": "Git operation failed",
+    "LLM_ERROR": "LLM generation failed"
+}
+```
+
+## 9. Configuration Contract
+
+### Configuration Schema
+
+```yaml
+# planner.config.yaml
+persistence:
+  type: file  # file, database, memory
+  directory: data/projects
+  git_enabled: true
+  auto_commit: true
+
+orchestration:
+  max_concurrent_agents: 5
+  agent_timeout: 300
+  retry_failed_tasks: true
+  deadlock_timeout: 60
+
+planning:
+  max_decomposition_depth: 3
+  max_tasks_per_goal: 50
+  use_defensive_parsing: true
+  
+llm:
+  model: claude-3-opus-20240229
+  temperature: 0.7
+  max_retries: 3
+  
+monitoring:
+  emit_events: true
+  enable_sse: false
+  log_level: info
+```
+
+## 10. Testing Contract
+
+### Mock Implementations
+
+```python
+class MockAmplifierIntegration:
+    """Mock for testing without real amplifier"""
+    
+    async def spawn_task_agent(self, agent_type: str, prompt: str, context: Dict):
+        return {
+            "agent_id": f"mock-agent-{uuid.uuid4()}",
+            "status": "ready",
+            "task_id": context["task_id"]
+        }
+
+class MockLLMService:
+    """Mock LLM for deterministic testing"""
+    
+    async def generate(self, prompt: str, **kwargs):
+        return '{"tasks": [{"title": "Mock task", "type": "task"}]}'
+```
+
+## Contract Stability Guarantees
+
+1. **Public API Stability**: The contracts defined in `contracts/__init__.py` are stable and will not break without major version change
+
+2. **Internal Module Boundaries**: Internal contracts between modules can evolve but must maintain protocol compatibility
+
+3. **Data Format Stability**: JSON serialization formats are stable for git-friendly storage
+
+4. **Event Schema Stability**: Event formats are append-only (new fields okay, removal requires version bump)
+
+5. **Configuration Compatibility**: New config options are optional with defaults, removal requires migration
+
+## Migration Path
+
+When contracts need to evolve:
+
+1. **Minor changes**: Add optional fields, new endpoints, additional event types
+2. **Major changes**: Create v2 contracts alongside v1, support both during transition
+3. **Deprecation**: Mark old contracts deprecated, maintain for 2 major versions
+4. **Migration tools**: Provide automated migration for data format changes
+
+---
+
+This integration contract ensures the super-planner can be regenerated internally while maintaining stable connections to the amplifier ecosystem. The "studs" defined here won't change even as the internal "brick" implementation evolves.
diff --git a/amplifier/planner/contracts/openapi.yaml b/amplifier/planner/contracts/openapi.yaml
new file mode 100644
index 00000000..0a733a44
--- /dev/null
+++ b/amplifier/planner/contracts/openapi.yaml
@@ -0,0 +1,726 @@
+openapi: 3.0.0
+info:
+  title: Super-Planner API
+  description: |
+    Task planning and orchestration system for AI-driven development.
+    
+    This API defines the stable connection points ("studs") for the super-planner
+    system following the amplifier bricks-and-studs philosophy. Each endpoint
+    represents a minimal, clear contract that enables module regeneration without
+    breaking external consumers.
+    
+    The API is organized into logical resource groups that map to internal modules
+    while maintaining stable external contracts.
+  version: 1.0.0
+  
+servers:
+  - url: /api/v1
+    description: API v1 endpoint
+    
+paths:
+  # Project Management
+  /projects:
+    post:
+      summary: Create new project
+      operationId: createProject
+      tags: [Projects]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ProjectCreate'
+      responses:
+        '201':
+          description: Project created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+                
+    get:
+      summary: List all projects
+      operationId: listProjects
+      tags: [Projects]
+      parameters:
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [active, completed, archived]
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            default: 50
+            minimum: 1
+            maximum: 100
+        - name: offset
+          in: query
+          schema:
+            type: integer
+            default: 0
+            minimum: 0
+      responses:
+        '200':
+          description: Projects retrieved
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items, total]
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Project'
+                  total:
+                    type: integer
+                    
+  /projects/{project_id}:
+    get:
+      summary: Get project details
+      operationId: getProject
+      tags: [Projects]
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+      responses:
+        '200':
+          description: Project retrieved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+        '404':
+          $ref: '#/components/responses/NotFound'
+          
+    patch:
+      summary: Update project
+      operationId: updateProject
+      tags: [Projects]
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ProjectUpdate'
+      responses:
+        '200':
+          description: Project updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Project'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+          
+    delete:
+      summary: Archive project
+      operationId: archiveProject
+      tags: [Projects]
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+      responses:
+        '204':
+          description: Project archived
+        '404':
+          $ref: '#/components/responses/NotFound'
+          
+  # Task Management
+  /projects/{project_id}/tasks:
+    post:
+      summary: Create task
+      operationId: createTask
+      tags: [Tasks]
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TaskCreate'
+      responses:
+        '201':
+          description: Task created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
+          
+    get:
+      summary: List project tasks
+      operationId: listTasks
+      tags: [Tasks]
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [pending, in_progress, completed, failed, blocked]
+        - name: assigned_to
+          in: query
+          schema:
+            type: string
+        - name: parent_id
+          in: query
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Tasks retrieved
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items]
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Task'
+                      
+  /tasks/{task_id}:
+    get:
+      summary: Get task details
+      operationId: getTask
+      tags: [Tasks]
+      parameters:
+        - $ref: '#/components/parameters/TaskId'
+      responses:
+        '200':
+          description: Task retrieved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '404':
+          $ref: '#/components/responses/NotFound'
+          
+    patch:
+      summary: Update task
+      operationId: updateTask
+      tags: [Tasks]
+      parameters:
+        - $ref: '#/components/parameters/TaskId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TaskUpdate'
+      responses:
+        '200':
+          description: Task updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+          
+  /tasks/{task_id}/transition:
+    post:
+      summary: Transition task state
+      operationId: transitionTask
+      tags: [Tasks]
+      parameters:
+        - $ref: '#/components/parameters/TaskId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [state]
+              properties:
+                state:
+                  type: string
+                  enum: [pending, in_progress, completed, failed, blocked]
+                reason:
+                  type: string
+                  description: Optional reason for transition
+      responses:
+        '200':
+          description: Task transitioned
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Task'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+          
+  # Planning Mode Operations
+  /planning/decompose:
+    post:
+      summary: Decompose goal into tasks
+      operationId: decomposeGoal
+      tags: [Planning]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [goal]
+              properties:
+                goal:
+                  type: string
+                  description: High-level goal to decompose
+                context:
+                  type: object
+                  description: Additional context for planning
+                constraints:
+                  type: object
+                  properties:
+                    max_depth:
+                      type: integer
+                      default: 3
+                    max_tasks:
+                      type: integer
+                      default: 50
+      responses:
+        '200':
+          description: Decomposition completed
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [tasks, dependencies]
+                properties:
+                  tasks:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/PlannedTask'
+                  dependencies:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        from_task_id:
+                          type: string
+                        to_task_id:
+                          type: string
+                        type:
+                          type: string
+                          enum: [blocks, requires]
+                          
+  /planning/refine:
+    post:
+      summary: Refine task breakdown
+      operationId: refineTasks
+      tags: [Planning]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [tasks]
+              properties:
+                tasks:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/Task'
+                feedback:
+                  type: string
+                  description: User feedback on current plan
+      responses:
+        '200':
+          description: Refinement completed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tasks:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Task'
+                  changes:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        task_id:
+                          type: string
+                        change_type:
+                          type: string
+                          enum: [added, modified, removed]
+                        description:
+                          type: string
+                          
+  # Working Mode Operations
+  /orchestration/assign:
+    post:
+      summary: Assign tasks to agents
+      operationId: assignTasks
+      tags: [Orchestration]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [task_ids]
+              properties:
+                task_ids:
+                  type: array
+                  items:
+                    type: string
+                strategy:
+                  type: string
+                  enum: [optimal, round_robin, load_balanced]
+                  default: optimal
+                constraints:
+                  type: object
+                  properties:
+                    max_concurrent:
+                      type: integer
+                      default: 5
+                    agent_types:
+                      type: array
+                      items:
+                        type: string
+      responses:
+        '200':
+          description: Tasks assigned
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  assignments:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        task_id:
+                          type: string
+                        agent_id:
+                          type: string
+                        agent_type:
+                          type: string
+                        estimated_duration:
+                          type: integer
+                          
+  /orchestration/spawn:
+    post:
+      summary: Spawn agent for task
+      operationId: spawnAgent
+      tags: [Orchestration]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [task_id, agent_type]
+              properties:
+                task_id:
+                  type: string
+                agent_type:
+                  type: string
+                config:
+                  type: object
+                  description: Agent-specific configuration
+      responses:
+        '202':
+          description: Agent spawn initiated
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  agent_id:
+                    type: string
+                  status:
+                    type: string
+                    enum: [spawning, ready]
+                  task_id:
+                    type: string
+                    
+  /orchestration/status:
+    get:
+      summary: Get orchestration status
+      operationId: getOrchestrationStatus
+      tags: [Orchestration]
+      parameters:
+        - name: project_id
+          in: query
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Status retrieved
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  active_agents:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        agent_id:
+                          type: string
+                        agent_type:
+                          type: string
+                        task_id:
+                          type: string
+                        status:
+                          type: string
+                        started_at:
+                          type: string
+                          format: date-time
+                  queued_tasks:
+                    type: integer
+                  completed_tasks:
+                    type: integer
+                  failed_tasks:
+                    type: integer
+                    
+  # Events and Notifications
+  /events/stream:
+    get:
+      summary: Stream events (SSE)
+      operationId: streamEvents
+      tags: [Events]
+      parameters:
+        - name: project_id
+          in: query
+          schema:
+            type: string
+        - name: task_id
+          in: query
+          schema:
+            type: string
+        - name: event_types
+          in: query
+          schema:
+            type: array
+            items:
+              type: string
+              enum: [task_created, task_updated, task_completed, agent_spawned, agent_completed]
+      responses:
+        '200':
+          description: Event stream
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                
+components:
+  parameters:
+    ProjectId:
+      name: project_id
+      in: path
+      required: true
+      schema:
+        type: string
+        
+    TaskId:
+      name: task_id
+      in: path
+      required: true
+      schema:
+        type: string
+        
+  schemas:
+    ProjectCreate:
+      type: object
+      required: [name, goal]
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+        description:
+          type: string
+          maxLength: 500
+        goal:
+          type: string
+          minLength: 1
+        metadata:
+          type: object
+          
+    Project:
+      allOf:
+        - $ref: '#/components/schemas/ProjectCreate'
+        - type: object
+          required: [id, status, created_at, updated_at]
+          properties:
+            id:
+              type: string
+            status:
+              type: string
+              enum: [active, completed, archived]
+            created_at:
+              type: string
+              format: date-time
+            updated_at:
+              type: string
+              format: date-time
+            version:
+              type: integer
+              
+    ProjectUpdate:
+      type: object
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        status:
+          type: string
+          enum: [active, completed, archived]
+        metadata:
+          type: object
+          
+    TaskCreate:
+      type: object
+      required: [title, type]
+      properties:
+        title:
+          type: string
+          minLength: 1
+          maxLength: 200
+        description:
+          type: string
+        type:
+          type: string
+          enum: [goal, task, subtask]
+        parent_id:
+          type: string
+        dependencies:
+          type: array
+          items:
+            type: string
+        estimated_effort:
+          type: string
+          enum: [xs, s, m, l, xl]
+        metadata:
+          type: object
+          
+    Task:
+      allOf:
+        - $ref: '#/components/schemas/TaskCreate'
+        - type: object
+          required: [id, status, created_at, updated_at]
+          properties:
+            id:
+              type: string
+            project_id:
+              type: string
+            status:
+              type: string
+              enum: [pending, in_progress, completed, failed, blocked]
+            assigned_to:
+              type: string
+            started_at:
+              type: string
+              format: date-time
+            completed_at:
+              type: string
+              format: date-time
+            created_at:
+              type: string
+              format: date-time
+            updated_at:
+              type: string
+              format: date-time
+            version:
+              type: integer
+            result:
+              type: object
+              
+    TaskUpdate:
+      type: object
+      properties:
+        title:
+          type: string
+        description:
+          type: string
+        status:
+          type: string
+          enum: [pending, in_progress, completed, failed, blocked]
+        assigned_to:
+          type: string
+        result:
+          type: object
+        metadata:
+          type: object
+          
+    PlannedTask:
+      type: object
+      required: [title, description, type]
+      properties:
+        title:
+          type: string
+        description:
+          type: string
+        type:
+          type: string
+          enum: [goal, task, subtask]
+        estimated_effort:
+          type: string
+          enum: [xs, s, m, l, xl]
+        suggested_agent:
+          type: string
+        rationale:
+          type: string
+          
+    Error:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: object
+          required: [code, message]
+          properties:
+            code:
+              type: string
+            message:
+              type: string
+            details:
+              type: object
+              
+  responses:
+    BadRequest:
+      description: Bad request
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+            
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+            
+    Conflict:
+      description: Resource conflict
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
diff --git a/amplifier/planner/contracts/validation.py b/amplifier/planner/contracts/validation.py
new file mode 100644
index 00000000..43e5da5b
--- /dev/null
+++ b/amplifier/planner/contracts/validation.py
@@ -0,0 +1,326 @@
+"""
+Contract Validation Module
+
+This module provides validation utilities to ensure implementations comply
+with the defined API contracts. It enables contract-based testing and
+runtime validation of module boundaries.
+"""
+
+import inspect
+import json
+from dataclasses import fields
+from dataclasses import is_dataclass
+from typing import Any
+from typing import Optional
+
+
+class ContractValidator:
+    """
+    Validates that implementations comply with defined contracts.
+    Used for both testing and runtime validation.
+    """
+
+    @staticmethod
+    def validate_protocol_implementation(implementation: Any, protocol: type) -> list[str]:
+        """
+        Validate that a class implements all methods required by a protocol.
+
+        Returns list of validation errors (empty if valid).
+        """
+        errors = []
+
+        # Get all abstract methods from protocol
+        protocol_methods = {
+            name: method
+            for name, method in inspect.getmembers(protocol)
+            if not name.startswith("_") and callable(method)
+        }
+
+        # Check each required method
+        for method_name, protocol_method in protocol_methods.items():
+            if not hasattr(implementation, method_name):
+                errors.append(f"Missing required method: {method_name}")
+                continue
+
+            impl_method = getattr(implementation, method_name)
+            if not callable(impl_method):
+                errors.append(f"Attribute {method_name} is not callable")
+                continue
+
+            # Check method signature compatibility
+            protocol_sig = inspect.signature(protocol_method)
+            impl_sig = inspect.signature(impl_method)
+
+            # Check parameters (excluding self)
+            protocol_params = list(protocol_sig.parameters.values())[1:]
+            impl_params = list(impl_sig.parameters.values())[1:]
+
+            if len(protocol_params) != len(impl_params):
+                errors.append(
+                    f"Method {method_name} has wrong number of parameters: "
+                    f"expected {len(protocol_params)}, got {len(impl_params)}"
+                )
+
+        return errors
+
+    @staticmethod
+    def validate_data_model(instance: Any, model_class: type) -> list[str]:
+        """
+        Validate that an instance conforms to a data model.
+        """
+        errors = []
+
+        if not isinstance(instance, model_class):
+            errors.append(f"Instance is not of type {model_class.__name__}")
+            return errors
+
+        # Validate required fields for dataclasses
+        if is_dataclass(model_class):
+            for field in fields(model_class):
+                if not hasattr(instance, field.name):
+                    errors.append(f"Missing required field: {field.name}")
+                    continue
+
+                value = getattr(instance, field.name)
+
+                # Check None for non-optional fields
+                if value is None and not _is_optional(field.type):
+                    errors.append(f"Non-optional field {field.name} is None")
+
+        return errors
+
+    @staticmethod
+    def validate_json_serialization(instance: Any, model_class: type) -> list[str]:
+        """
+        Validate that an instance can be serialized and deserialized.
+        """
+        errors = []
+
+        # Check for to_json method
+        if not hasattr(instance, "to_json"):
+            errors.append(f"{model_class.__name__} missing to_json method")
+            return errors
+
+        # Try serialization
+        try:
+            json_str = instance.to_json()
+            json_data = json.loads(json_str)
+
+            # Check for sorted keys (git-friendly requirement)
+            if json_str != json.dumps(json_data, sort_keys=True, indent=2):
+                errors.append("JSON not serialized with sorted keys")
+        except Exception as e:
+            errors.append(f"Serialization failed: {e}")
+            return errors
+
+        # Check for from_json method
+        if not hasattr(model_class, "from_json"):
+            errors.append(f"{model_class.__name__} missing from_json method")
+            return errors
+
+        # Try round-trip
+        try:
+            restored = model_class.from_json(json_str)
+            if not isinstance(restored, model_class):
+                errors.append("Deserialization returned wrong type")
+        except Exception as e:
+            errors.append(f"Deserialization failed: {e}")
+
+        return errors
+
+    @staticmethod
+    def validate_api_response(response: dict[str, Any], schema: dict[str, Any]) -> list[str]:
+        """
+        Validate API response against OpenAPI schema.
+        """
+        errors = []
+
+        # Check required fields
+        for field in schema.get("required", []):
+            if field not in response:
+                errors.append(f"Missing required field: {field}")
+
+        # Check field types
+        for field, value in response.items():
+            if field in schema.get("properties", {}):
+                field_schema = schema["properties"][field]
+                errors.extend(_validate_field(field, value, field_schema))
+
+        return errors
+
+    @staticmethod
+    def validate_event_schema(event: dict[str, Any], event_type: str) -> list[str]:
+        """
+        Validate event conforms to expected schema.
+        """
+        errors = []
+
+        # Check standard event fields
+        required_fields = ["event_type", "timestamp"]
+        for field in required_fields:
+            if field not in event:
+                errors.append(f"Missing required event field: {field}")
+
+        # Check event type
+        if event.get("event_type") != event_type:
+            errors.append(f"Event type mismatch: expected {event_type}, got {event.get('event_type')}")
+
+        # Check timestamp format
+        if "timestamp" in event:
+            try:
+                from datetime import datetime
+
+                datetime.fromisoformat(event["timestamp"])
+            except (ValueError, TypeError):
+                errors.append("Invalid timestamp format")
+
+        return errors
+
+
+class ContractTest:
+    """
+    Base class for contract-based testing.
+    Provides utilities for testing module contracts.
+    """
+
+    def assert_implements_protocol(self, implementation: Any, protocol: type):
+        """Assert that implementation satisfies protocol contract."""
+        errors = ContractValidator.validate_protocol_implementation(implementation, protocol)
+        if errors:
+            raise AssertionError(
+                f"Contract violation for {protocol.__name__}:\n" + "\n".join(f"  - {e}" for e in errors)
+            )
+
+    def assert_valid_data_model(self, instance: Any, model_class: type):
+        """Assert that instance is valid according to data model."""
+        errors = ContractValidator.validate_data_model(instance, model_class)
+        if errors:
+            raise AssertionError(f"Invalid {model_class.__name__}:\n" + "\n".join(f"  - {e}" for e in errors))
+
+    def assert_serializable(self, instance: Any, model_class: type):
+        """Assert that instance can be serialized and restored."""
+        errors = ContractValidator.validate_json_serialization(instance, model_class)
+        if errors:
+            raise AssertionError("Serialization contract violation:\n" + "\n".join(f"  - {e}" for e in errors))
+
+    def assert_valid_api_response(self, response: dict[str, Any], schema: dict[str, Any]):
+        """Assert API response matches schema."""
+        errors = ContractValidator.validate_api_response(response, schema)
+        if errors:
+            raise AssertionError("API response contract violation:\n" + "\n".join(f"  - {e}" for e in errors))
+
+
+class ContractMonitor:
+    """
+    Runtime contract monitoring for production systems.
+    Logs contract violations without failing.
+    """
+
+    def __init__(self, logger=None):
+        self.logger = logger or self._get_default_logger()
+        self.violations = []
+
+    def check_protocol(self, implementation: Any, protocol: type) -> bool:
+        """Check protocol implementation, log violations."""
+        errors = ContractValidator.validate_protocol_implementation(implementation, protocol)
+
+        if errors:
+            self.log_violation(f"Protocol {protocol.__name__}", implementation.__class__.__name__, errors)
+            return False
+        return True
+
+    def check_data_model(self, instance: Any, model_class: type) -> bool:
+        """Check data model validity, log violations."""
+        errors = ContractValidator.validate_data_model(instance, model_class)
+
+        if errors:
+            self.log_violation(f"Data model {model_class.__name__}", str(instance)[:100], errors)
+            return False
+        return True
+
+    def log_violation(self, contract: str, context: str, errors: list[str]):
+        """Log contract violation."""
+        violation = {"contract": contract, "context": context, "errors": errors}
+        self.violations.append(violation)
+
+        if self.logger:
+            self.logger.warning(
+                f"Contract violation in {contract} for {context}:\n" + "\n".join(f"  - {e}" for e in errors)
+            )
+
+    def get_report(self) -> dict[str, Any]:
+        """Get contract violation report."""
+        return {
+            "total_violations": len(self.violations),
+            "violations_by_contract": self._group_by_contract(),
+            "recent_violations": self.violations[-10:],
+        }
+
+    def _group_by_contract(self) -> dict[str, int]:
+        """Group violations by contract type."""
+        grouped = {}
+        for violation in self.violations:
+            contract = violation["contract"]
+            grouped[contract] = grouped.get(contract, 0) + 1
+        return grouped
+
+    def _get_default_logger(self):
+        """Get default logger."""
+        import logging
+
+        return logging.getLogger(__name__)
+
+
+# Helper functions
+
+
+def _is_optional(type_hint) -> bool:
+    """Check if type hint is Optional."""
+    return hasattr(type_hint, "__origin__") and type_hint.__origin__ is Optional
+
+
+def _validate_field(field_name: str, value: Any, schema: dict[str, Any]) -> list[str]:
+    """Validate a single field against schema."""
+    errors = []
+
+    # Check type
+    if "type" in schema:
+        expected_type = schema["type"]
+        type_map = {
+            "string": str,
+            "integer": int,
+            "number": (int, float),
+            "boolean": bool,
+            "array": list,
+            "object": dict,
+        }
+
+        if expected_type in type_map:
+            expected_python_type = type_map[expected_type]
+            if not isinstance(value, expected_python_type):
+                errors.append(
+                    f"Field {field_name} has wrong type: expected {expected_type}, got {type(value).__name__}"
+                )
+
+    # Check enum values
+    if "enum" in schema and value not in schema["enum"]:
+        errors.append(f"Field {field_name} has invalid value: {value} not in {schema['enum']}")
+
+    # Check string constraints
+    if isinstance(value, str):
+        if "minLength" in schema and len(value) < schema["minLength"]:
+            errors.append(f"Field {field_name} too short: minimum {schema['minLength']}, got {len(value)}")
+        if "maxLength" in schema and len(value) > schema["maxLength"]:
+            errors.append(f"Field {field_name} too long: maximum {schema['maxLength']}, got {len(value)}")
+
+    # Check array constraints
+    if isinstance(value, list) and "items" in schema:
+        item_schema = schema["items"]
+        for i, item in enumerate(value):
+            errors.extend(_validate_field(f"{field_name}[{i}]", item, item_schema))
+
+    return errors
+
+
+# Export contract validation utilities
+__all__ = ["ContractValidator", "ContractTest", "ContractMonitor"]
diff --git a/amplifier/planner/data/planner/projects/django-blog.json b/amplifier/planner/data/planner/projects/django-blog.json
new file mode 100644
index 00000000..8c367f76
--- /dev/null
+++ b/amplifier/planner/data/planner/projects/django-blog.json
@@ -0,0 +1,113 @@
+{
+  "id": "django-blog",
+  "name": "Django Blog",
+  "created_at": "2025-10-07T11:54:42.814456",
+  "updated_at": "2025-10-07T11:54:42.814482",
+  "tasks": {
+    "setup": {
+      "id": "setup",
+      "title": "Project Setup",
+      "description": "Create Django project and configure settings",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:54:42.814463",
+      "updated_at": "2025-10-07T11:54:42.814464"
+    },
+    "models": {
+      "id": "models",
+      "title": "Database Models",
+      "description": "Create User, Post, Comment models",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "setup"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:54:42.814466",
+      "updated_at": "2025-10-07T11:54:42.814467"
+    },
+    "admin": {
+      "id": "admin",
+      "title": "Admin Interface",
+      "description": "Configure Django admin",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "models"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:54:42.814468",
+      "updated_at": "2025-10-07T11:54:42.814468"
+    },
+    "views": {
+      "id": "views",
+      "title": "Views",
+      "description": "Create list, detail, create views",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "models"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:54:42.814470",
+      "updated_at": "2025-10-07T11:54:42.814470"
+    },
+    "templates": {
+      "id": "templates",
+      "title": "Templates",
+      "description": "Design HTML templates",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "views"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:54:42.814471",
+      "updated_at": "2025-10-07T11:54:42.814472"
+    },
+    "urls": {
+      "id": "urls",
+      "title": "URL Configuration",
+      "description": "Set up routing",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "views"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:54:42.814472",
+      "updated_at": "2025-10-07T11:54:42.814473"
+    },
+    "tests": {
+      "id": "tests",
+      "title": "Tests",
+      "description": "Write unit tests",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "models",
+        "views"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:54:42.814474",
+      "updated_at": "2025-10-07T11:54:42.814474"
+    },
+    "deploy": {
+      "id": "deploy",
+      "title": "Deployment",
+      "description": "Deploy to production",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "templates",
+        "urls",
+        "tests"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:54:42.814475",
+      "updated_at": "2025-10-07T11:54:42.814475"
+    }
+  }
+}
\ No newline at end of file
diff --git a/amplifier/planner/data/planner/projects/persistence-test.json b/amplifier/planner/data/planner/projects/persistence-test.json
new file mode 100644
index 00000000..afbb0065
--- /dev/null
+++ b/amplifier/planner/data/planner/projects/persistence-test.json
@@ -0,0 +1,32 @@
+{
+  "id": "persistence-test",
+  "name": "Persistence Test",
+  "created_at": "2025-10-07T11:54:42.768935",
+  "updated_at": "2025-10-07T11:54:42.768944",
+  "tasks": {
+    "t1": {
+      "id": "t1",
+      "title": "Task 1",
+      "description": "First task",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:54:42.768939",
+      "updated_at": "2025-10-07T11:54:42.768939"
+    },
+    "t2": {
+      "id": "t2",
+      "title": "Task 2",
+      "description": "",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "t1"
+      ],
+      "assigned_to": "test-user",
+      "created_at": "2025-10-07T11:54:42.768942",
+      "updated_at": "2025-10-07T11:54:42.768942"
+    }
+  }
+}
\ No newline at end of file
diff --git a/amplifier/planner/decomposer.py b/amplifier/planner/decomposer.py
new file mode 100644
index 00000000..8ec188bc
--- /dev/null
+++ b/amplifier/planner/decomposer.py
@@ -0,0 +1,288 @@
+"""Task Decomposition Module for Super-Planner
+
+Purpose: Intelligently break down high-level goals into specific, actionable tasks using AI analysis.
+This module provides a simple, self-contained interface for decomposing goals into hierarchical tasks.
+
+Contract:
+    Input: High-level goal string and project context
+    Output: List of actionable Task objects with dependencies
+    Behavior: Uses LLM to analyze goals and create structured task breakdowns
+    Side Effects: Logs decomposition progress
+    Dependencies: PydanticAI for LLM integration
+
+Example:
+    >>> from amplifier.planner import Project
+    >>> from amplifier.planner.decomposer import decompose_goal, ProjectContext
+    >>>
+    >>> context = ProjectContext(
+    ...     project=Project(id="proj1", name="New Feature"),
+    ...     max_depth=3
+    ... )
+    >>> tasks = await decompose_goal("Build user authentication system", context)
+    >>> print(f"Generated {len(tasks)} tasks")
+"""
+
+import logging
+import uuid
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+from pydantic import Field
+from pydantic_ai import Agent
+
+from amplifier.planner.models import Project
+from amplifier.planner.models import Task
+from amplifier.planner.models import TaskState
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ProjectContext:
+    """Context for task decomposition within a project."""
+
+    project: Project
+    max_depth: int = 3  # Maximum decomposition depth
+    min_tasks: int = 2  # Minimum tasks required from decomposition
+    parent_task: Task | None = None  # Parent task if decomposing subtasks
+
+
+class TaskDecomposition(BaseModel):
+    """LLM response model for task decomposition."""
+
+    tasks: list[dict] = Field(description="List of tasks with title, description, and dependencies")
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "tasks": [
+                    {
+                        "title": "Design database schema",
+                        "description": "Create tables for user authentication",
+                        "depends_on_indices": [],
+                    },
+                    {
+                        "title": "Implement login endpoint",
+                        "description": "Create API endpoint for user login",
+                        "depends_on_indices": [0],
+                    },
+                ]
+            }
+        }
+    }
+
+
+# Lazy-initialize the decomposition agent
+_decomposer_agent = None
+
+
+def _get_decomposer_agent():
+    """Get or create the decomposer agent (lazy initialization)."""
+    global _decomposer_agent
+    if _decomposer_agent is None:
+        _decomposer_agent = Agent(
+            "claude-3-5-sonnet-20241022",
+            output_type=TaskDecomposition,
+            system_prompt=(
+                "You are a task decomposition expert. Break down high-level goals into "
+                "specific, actionable tasks. Each task should be concrete and achievable. "
+                "Identify dependencies between tasks. Focus on practical implementation steps."
+            ),
+        )
+    return _decomposer_agent
+
+
+async def decompose_goal(goal: str, context: ProjectContext) -> list[Task]:
+    """Decompose a high-level goal into actionable tasks.
+
+    This function uses AI to intelligently break down a goal into specific tasks,
+    establishing proper dependencies and hierarchical structure.
+
+    Args:
+        goal: High-level goal string to decompose
+        context: Project context including existing project and constraints
+
+    Returns:
+        List of Task objects with proper IDs, descriptions, and dependencies
+
+    Raises:
+        ValueError: If goal is empty or decomposition produces too few tasks
+        RuntimeError: If LLM decomposition fails
+
+    Example:
+        >>> context = ProjectContext(project=project, max_depth=2)
+        >>> tasks = await decompose_goal("Add search functionality", context)
+        >>> for task in tasks:
+        ...     print(f"- {task.title}")
+    """
+    # Input validation
+    if not goal or not goal.strip():
+        raise ValueError("Goal cannot be empty")
+
+    logger.info(f"Decomposing goal: {goal[:100]}...")
+
+    # Build prompt with context
+    prompt = _build_decomposition_prompt(goal, context)
+
+    try:
+        # Get the agent and call LLM for decomposition
+        agent = _get_decomposer_agent()
+        result = await agent.run(prompt)
+        decomposition = result.output
+
+        # Validate minimum tasks requirement
+        if len(decomposition.tasks) < context.min_tasks:
+            logger.warning(
+                f"Decomposition produced only {len(decomposition.tasks)} tasks, minimum is {context.min_tasks}"
+            )
+            # Try once more with explicit instruction
+            enhanced_prompt = (
+                f"{prompt}\n\nIMPORTANT: Generate at least {context.min_tasks} distinct, actionable tasks."
+            )
+            result = await agent.run(enhanced_prompt)
+            decomposition = result.output
+
+            if len(decomposition.tasks) < context.min_tasks:
+                raise ValueError(f"Could not generate minimum {context.min_tasks} tasks from goal")
+
+        # Convert to Task objects
+        tasks = _convert_to_tasks(decomposition, context)
+
+        logger.info(f"Successfully decomposed into {len(tasks)} tasks")
+        return tasks
+
+    except Exception as e:
+        logger.error(f"Failed to decompose goal: {e}")
+        raise RuntimeError(f"Goal decomposition failed: {e}") from e
+
+
+def _build_decomposition_prompt(goal: str, context: ProjectContext) -> str:
+    """Build the decomposition prompt with context."""
+    prompt_parts = [
+        f"Goal: {goal}",
+        f"Project: {context.project.name}",
+    ]
+
+    if context.parent_task:
+        prompt_parts.append(f"Parent task: {context.parent_task.title}")
+        prompt_parts.append("Create subtasks for this parent task.")
+
+    # Add existing tasks context if any
+    if context.project.tasks:
+        existing_titles = [task.title for task in context.project.tasks.values()][:5]
+        prompt_parts.append(f"Existing tasks in project: {', '.join(existing_titles)}")
+
+    prompt_parts.append(
+        "\nBreak this down into specific, actionable tasks. "
+        "Each task should be concrete and independently achievable. "
+        "Identify dependencies between tasks using indices (0-based)."
+    )
+
+    return "\n".join(prompt_parts)
+
+
+def _convert_to_tasks(decomposition: TaskDecomposition, context: ProjectContext) -> list[Task]:
+    """Convert LLM decomposition to Task objects with proper IDs and relationships."""
+    tasks = []
+    task_ids = []  # Track IDs for dependency mapping
+
+    # Generate IDs first
+    for _ in decomposition.tasks:
+        task_ids.append(str(uuid.uuid4()))
+
+    # Create Task objects
+    for i, task_data in enumerate(decomposition.tasks):
+        # Map dependency indices to actual task IDs
+        dependencies = []
+        if "depends_on_indices" in task_data:
+            for dep_idx in task_data.get("depends_on_indices", []):
+                if 0 <= dep_idx < len(task_ids) and dep_idx != i:
+                    dependencies.append(task_ids[dep_idx])
+
+        task = Task(
+            id=task_ids[i],
+            title=task_data.get("title", f"Task {i + 1}"),
+            description=task_data.get("description", ""),
+            state=TaskState.PENDING,
+            parent_id=context.parent_task.id if context.parent_task else None,
+            depends_on=dependencies,
+        )
+
+        tasks.append(task)
+
+        logger.debug(f"Created task: {task.title} (deps: {len(dependencies)})")
+
+    return tasks
+
+
+async def decompose_recursively(goal: str, context: ProjectContext, current_depth: int = 0) -> list[Task]:
+    """Recursively decompose a goal into tasks up to max_depth.
+
+    This function decomposes a goal and then recursively decomposes each
+    resulting task until reaching the maximum depth or tasks become atomic.
+
+    Args:
+        goal: High-level goal to decompose
+        context: Project context with constraints
+        current_depth: Current recursion depth (internal)
+
+    Returns:
+        Flat list of all tasks from all decomposition levels
+
+    Example:
+        >>> context = ProjectContext(project=project, max_depth=2)
+        >>> all_tasks = await decompose_recursively("Build app", context)
+        >>> print(f"Total tasks across all levels: {len(all_tasks)}")
+    """
+    if current_depth >= context.max_depth:
+        logger.debug(f"Reached maximum decomposition depth: {context.max_depth}")
+        return []
+
+    # Decompose current goal
+    tasks = await decompose_goal(goal, context)
+    all_tasks = tasks.copy()
+
+    # Recursively decompose each task
+    for task in tasks:
+        # Skip tasks that seem atomic or too specific
+        if _is_atomic_task(task):
+            logger.debug(f"Skipping atomic task: {task.title}")
+            continue
+
+        # Create context for subtask decomposition
+        sub_context = ProjectContext(
+            project=context.project,
+            max_depth=context.max_depth,
+            min_tasks=2,  # Subtasks can have fewer requirements
+            parent_task=task,
+        )
+
+        try:
+            subtasks = await decompose_recursively(task.title, sub_context, current_depth + 1)
+            all_tasks.extend(subtasks)
+        except Exception as e:
+            logger.warning(f"Could not decompose '{task.title}': {e}")
+            # Continue with other tasks
+
+    return all_tasks
+
+
+def _is_atomic_task(task: Task) -> bool:
+    """Determine if a task is atomic and shouldn't be decomposed further."""
+    # Simple heuristics for atomic tasks
+    atomic_keywords = [
+        "write",
+        "create file",
+        "implement",
+        "add test",
+        "update",
+        "fix",
+        "remove",
+        "delete",
+        "install",
+        "configure",
+    ]
+
+    title_lower = task.title.lower()
+    return any(keyword in title_lower for keyword in atomic_keywords)
diff --git a/amplifier/planner/models.py b/amplifier/planner/models.py
new file mode 100644
index 00000000..b1e0da5e
--- /dev/null
+++ b/amplifier/planner/models.py
@@ -0,0 +1,60 @@
+"""Task and Project data models for the Super-Planner system."""
+
+from dataclasses import dataclass
+from dataclasses import field
+from datetime import datetime
+from enum import Enum
+
+
+class TaskState(Enum):
+    """Task states for workflow management."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    BLOCKED = "blocked"
+
+
+@dataclass
+class Task:
+    """Task with hierarchical structure and dependencies."""
+
+    id: str
+    title: str
+    description: str = ""
+    state: TaskState = TaskState.PENDING
+    parent_id: str | None = None
+    depends_on: list[str] = field(default_factory=list)
+    assigned_to: str | None = None
+    created_at: datetime = field(default_factory=datetime.now)
+    updated_at: datetime = field(default_factory=datetime.now)
+
+    def can_start(self, completed_ids: set[str]) -> bool:
+        """Check if task can start based on dependency completion."""
+        if not self.depends_on:
+            return True
+        return all(dep_id in completed_ids for dep_id in self.depends_on)
+
+
+@dataclass
+class Project:
+    """Project container for hierarchical tasks."""
+
+    id: str
+    name: str
+    tasks: dict[str, Task] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=datetime.now)
+    updated_at: datetime = field(default_factory=datetime.now)
+
+    def add_task(self, task: Task) -> None:
+        """Add task to project and update timestamp."""
+        self.tasks[task.id] = task
+        self.updated_at = datetime.now()
+
+    def get_roots(self) -> list[Task]:
+        """Get all root tasks (no parent)."""
+        return [task for task in self.tasks.values() if task.parent_id is None]
+
+    def get_children(self, parent_id: str) -> list[Task]:
+        """Get direct children of a task."""
+        return [task for task in self.tasks.values() if task.parent_id == parent_id]
diff --git a/amplifier/planner/orchestrator.py b/amplifier/planner/orchestrator.py
new file mode 100644
index 00000000..e9134630
--- /dev/null
+++ b/amplifier/planner/orchestrator.py
@@ -0,0 +1,264 @@
+"""Task execution orchestrator for the Super-Planner system.
+
+This module coordinates parallel agent execution while respecting task dependencies.
+It follows the modular "bricks and studs" philosophy with a clear public contract.
+
+Public Contract:
+    orchestrate_execution(project: Project) -> ExecutionResults
+
+    Purpose: Coordinate parallel execution of project tasks via agents
+
+    Input: Project with tasks and dependencies
+    Output: ExecutionResults with status, progress, and outcomes
+
+    Behavior:
+    - Resolves task dependencies to determine execution order
+    - Spawns agents in parallel where dependencies allow
+    - Tracks progress and handles failures gracefully
+    - Returns comprehensive execution results
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from dataclasses import field
+from datetime import datetime
+from typing import Any
+
+from amplifier.planner.models import Project
+from amplifier.planner.models import Task
+from amplifier.planner.models import TaskState
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TaskResult:
+    """Result from executing a single task."""
+
+    task_id: str
+    status: str  # "success", "failed", "skipped"
+    output: Any = None
+    error: str | None = None
+    started_at: datetime = field(default_factory=datetime.now)
+    completed_at: datetime | None = None
+    attempts: int = 1
+
+
+@dataclass
+class ExecutionResults:
+    """Results from orchestrating project execution."""
+
+    project_id: str
+    status: str  # "completed", "partial", "failed"
+    task_results: dict[str, TaskResult] = field(default_factory=dict)
+    total_tasks: int = 0
+    completed_tasks: int = 0
+    failed_tasks: int = 0
+    skipped_tasks: int = 0
+    started_at: datetime = field(default_factory=datetime.now)
+    completed_at: datetime | None = None
+
+    def add_result(self, result: TaskResult) -> None:
+        """Add a task result and update counters."""
+        self.task_results[result.task_id] = result
+
+        if result.status == "success":
+            self.completed_tasks += 1
+        elif result.status == "failed":
+            self.failed_tasks += 1
+        elif result.status == "skipped":
+            self.skipped_tasks += 1
+
+    def finalize(self) -> None:
+        """Finalize results and set overall status."""
+        self.completed_at = datetime.now()
+
+        if self.failed_tasks == 0 and self.completed_tasks == self.total_tasks:
+            self.status = "completed"
+        elif self.completed_tasks > 0:
+            self.status = "partial"
+        else:
+            self.status = "failed"
+
+
+async def orchestrate_execution(project: Project, max_parallel: int = 5, max_retries: int = 2) -> ExecutionResults:
+    """Orchestrate parallel execution of project tasks.
+
+    Args:
+        project: Project containing tasks to execute
+        max_parallel: Maximum number of agents to run in parallel
+        max_retries: Maximum retry attempts for failed tasks
+
+    Returns:
+        ExecutionResults with comprehensive execution information
+    """
+    results = ExecutionResults(project_id=project.id, status="in_progress", total_tasks=len(project.tasks))
+
+    if not project.tasks:
+        logger.warning(f"Project {project.id} has no tasks to execute")
+        results.status = "completed"
+        results.finalize()
+        return results
+
+    # Track task states
+    completed_ids: set[str] = set()
+    in_progress_ids: set[str] = set()
+    failed_ids: set[str] = set()
+    queued_ids: set[str] = set()  # Track what's been queued
+
+    # Create execution queue
+    execution_queue = asyncio.Queue()
+
+    # Start with tasks that have no dependencies
+    for task in project.tasks.values():
+        if task.can_start(completed_ids):
+            await execution_queue.put(task)
+            queued_ids.add(task.id)
+
+    # Semaphore to limit parallel execution
+    semaphore = asyncio.Semaphore(max_parallel)
+
+    async def execute_task(task: Task) -> TaskResult:
+        """Execute a single task with retries."""
+        result = TaskResult(task_id=task.id, status="failed")
+
+        for attempt in range(1, max_retries + 1):
+            try:
+                async with semaphore:
+                    logger.info(f"Executing task {task.id}: {task.title} (attempt {attempt})")
+                    in_progress_ids.add(task.id)
+
+                    # Update task state
+                    task.state = TaskState.IN_PROGRESS
+                    task.updated_at = datetime.now()
+
+                    # Execute via agent (simplified for now - would integrate with Task tool)
+                    output = await _execute_with_agent(task)
+
+                    # Success
+                    result.status = "success"
+                    result.output = output
+                    result.attempts = attempt
+                    result.completed_at = datetime.now()
+
+                    task.state = TaskState.COMPLETED
+                    task.updated_at = datetime.now()
+
+                    in_progress_ids.discard(task.id)
+                    completed_ids.add(task.id)
+
+                    logger.info(f"Task {task.id} completed successfully")
+                    break
+
+            except Exception as e:
+                logger.error(f"Task {task.id} failed (attempt {attempt}): {e}")
+                result.error = str(e)
+                result.attempts = attempt
+
+                if attempt == max_retries:
+                    result.status = "failed"
+                    result.completed_at = datetime.now()
+
+                    task.state = TaskState.BLOCKED
+                    task.updated_at = datetime.now()
+
+                    in_progress_ids.discard(task.id)
+                    failed_ids.add(task.id)
+                else:
+                    # Exponential backoff
+                    await asyncio.sleep(2**attempt)
+
+        return result
+
+    async def process_queue():
+        """Process tasks from the queue."""
+        active_tasks = []
+
+        while execution_queue.qsize() > 0 or active_tasks:
+            # Start new tasks
+            while not execution_queue.empty() and len(active_tasks) < max_parallel:
+                try:
+                    task = execution_queue.get_nowait()
+                    active_tasks.append(asyncio.create_task(execute_task(task)))
+                except asyncio.QueueEmpty:
+                    break
+
+            # Wait for at least one task to complete
+            if active_tasks:
+                done, pending = await asyncio.wait(active_tasks, return_when=asyncio.FIRST_COMPLETED)
+
+                # Process completed tasks
+                for task_future in done:
+                    result = await task_future
+                    results.add_result(result)
+                    active_tasks.remove(task_future)
+
+                    # Check for newly unblocked tasks only after successful completion
+                    if result.status == "success":
+                        # Look for tasks that are now ready to run
+                        for task_id, task in project.tasks.items():
+                            if (
+                                task_id not in queued_ids  # Not already queued
+                                and task.can_start(completed_ids)
+                            ):
+                                await execution_queue.put(task)
+                                queued_ids.add(task_id)
+
+                # Update active tasks list
+                active_tasks = list(pending)
+
+            # Brief pause to avoid busy waiting
+            if execution_queue.empty() and active_tasks:
+                await asyncio.sleep(0.1)
+
+    # Execute all tasks
+    await process_queue()
+
+    # Handle any remaining unexecuted tasks (due to failed dependencies)
+    for task_id in project.tasks:
+        if task_id not in results.task_results:
+            result = TaskResult(
+                task_id=task_id, status="skipped", error="Dependencies failed or not met", completed_at=datetime.now()
+            )
+            results.add_result(result)
+            logger.warning(f"Task {task_id} skipped due to unmet dependencies")
+
+    # Finalize results
+    results.finalize()
+
+    logger.info(
+        f"Orchestration complete for project {project.id}: "
+        f"{results.completed_tasks}/{results.total_tasks} completed, "
+        f"{results.failed_tasks} failed, {results.skipped_tasks} skipped"
+    )
+
+    return results
+
+
+async def _execute_with_agent(task: Task) -> Any:
+    """Execute task with assigned agent.
+
+    This is a simplified placeholder. In production, this would:
+    1. Use the Task tool to spawn the appropriate agent
+    2. Pass the task description and context
+    3. Wait for and return the agent's output
+
+    Args:
+        task: Task to execute
+
+    Returns:
+        Agent execution output
+    """
+    # Simulate agent execution
+    await asyncio.sleep(0.5)  # Simulate work
+
+    if task.assigned_to:
+        logger.debug(f"Would execute with agent: {task.assigned_to}")
+        return f"Executed by {task.assigned_to}: {task.title}"
+    logger.debug(f"Executing task without specific agent: {task.title}")
+    return f"Executed: {task.title}"
+
+
+# Public exports
+__all__ = ["orchestrate_execution", "ExecutionResults", "TaskResult"]
diff --git a/amplifier/planner/protocols/README.md b/amplifier/planner/protocols/README.md
new file mode 100644
index 00000000..39d7fbd7
--- /dev/null
+++ b/amplifier/planner/protocols/README.md
@@ -0,0 +1,287 @@
+# Task State Management and Coordination Protocols
+
+This document provides an overview of the comprehensive protocol system designed for the super-planner's task state management and multi-agent coordination capabilities.
+
+## Architecture Overview
+
+The protocol system consists of five core components that work together to ensure reliable, coordinated task management across multiple agents:
+
+1. **State Transition Protocol** - Manages valid task state changes
+2. **Agent Coordination Protocol** - Handles multi-agent task claiming and load balancing
+3. **Deadlock Prevention Protocol** - Detects and resolves circular dependencies
+4. **Conflict Resolution Protocol** - Manages concurrent task modifications
+5. **Defensive Coordination Utilities** - Provides robust error handling and recovery
+
+## Protocol Components
+
+### 1. State Transition Protocol (`state_transitions.py`)
+
+Manages atomic state transitions for tasks with optimistic locking and validation.
+
+**Key Features:**
+- Valid transition definitions with guard conditions and side effects
+- Optimistic locking with version numbers to prevent concurrent modification conflicts
+- Immutable task updates with automatic version incrementing
+- Comprehensive transition validation and error handling
+
+**State Flow:**
+```
+NOT_STARTED → ASSIGNED → IN_PROGRESS → COMPLETED
+     ↓           ↓            ↓
+  IN_PROGRESS  CANCELLED   BLOCKED → IN_PROGRESS
+     ↓                       ↓
+  COMPLETED               CANCELLED
+```
+
+**Usage:**
+```python
+from amplifier.planner.protocols import state_protocol
+
+# Transition a task
+updated_task = state_protocol.transition_task(task, TaskState.IN_PROGRESS, expected_version=task.version)
+
+# Check valid transitions
+can_transition, reason = state_protocol.can_transition(task, TaskState.COMPLETED)
+```
+
+### 2. Agent Coordination Protocol (`agent_coordination.py`)
+
+Manages multi-agent coordination, task claiming, and load balancing to prevent conflicts.
+
+**Key Features:**
+- Agent registration with capabilities and capacity limits
+- Task claiming with time-based leases and automatic expiration
+- Load balancing based on current agent utilization
+- Heartbeat monitoring and automatic cleanup of inactive agents
+- Capability-based task assignment matching
+
+**Core Operations:**
+- `register_agent()` - Register agent with capabilities and limits
+- `claim_task()` - Atomically claim a task with lease
+- `release_task()` - Release a claimed task
+- `select_best_agent()` - Load-balanced agent selection
+- `cleanup_expired_claims()` - Remove expired leases
+
+**Usage:**
+```python
+from amplifier.planner.protocols import coordination_protocol
+
+# Register an agent
+await coordination_protocol.register_agent("ai_agent_1", {"python", "analysis"}, max_concurrent_tasks=5)
+
+# Claim a task
+claim = await coordination_protocol.claim_task("task_123", "ai_agent_1")
+
+# Get agent recommendations
+best_agent = coordination_protocol.select_best_agent(task)
+```
+
+### 3. Deadlock Prevention Protocol (`deadlock_prevention.py`)
+
+Prevents and resolves deadlocks through cycle detection, dependency tracking, and automatic resolution.
+
+**Key Features:**
+- Real-time circular dependency detection using graph algorithms
+- Dependency depth limiting to prevent infinite chains
+- Multiple deadlock resolution strategies (weakest link, most recent task)
+- Timeout-based escalation for long-blocked tasks
+- Comprehensive deadlock cycle analysis and severity assessment
+
+**Core Operations:**
+- `add_dependency()` - Add dependency with cycle checking
+- `detect_deadlocks()` - Find all active deadlock cycles
+- `resolve_deadlock()` - Attempt automatic resolution
+- `check_timeout_violations()` - Find overdue blocked tasks
+
+**Usage:**
+```python
+from amplifier.planner.protocols import deadlock_protocol
+
+# Add a dependency (with cycle prevention)
+success = await deadlock_protocol.add_dependency("task_a", "task_b")
+
+# Check for deadlocks
+cycles = await deadlock_protocol.detect_deadlocks()
+
+# Resolve if found
+for cycle in cycles:
+    resolved = await deadlock_protocol.resolve_deadlock(cycle)
+```
+
+### 4. Conflict Resolution Protocol (`conflict_resolution.py`)
+
+Handles concurrent task modifications with intelligent merge strategies and escalation.
+
+**Key Features:**
+- Multiple conflict detection types (version, state, assignment, dependency)
+- Configurable resolution strategies (last writer wins, merge, escalate)
+- Intelligent change merging for compatible modifications
+- Automatic retry with exponential backoff
+- Human escalation for complex conflicts
+
+**Resolution Strategies:**
+- **Last Writer Wins** - Use most recent modification
+- **First Writer Wins** - Use earliest modification
+- **Merge Changes** - Intelligently combine non-conflicting changes
+- **Escalate to Human** - Require manual intervention
+- **Reject Conflict** - Block the conflicting change
+
+**Usage:**
+```python
+from amplifier.planner.protocols import conflict_protocol
+
+# Apply modification with automatic conflict resolution
+resolved_task = await conflict_protocol.apply_modification_with_retry(current_task, modification)
+
+# Get conflicts needing human intervention
+escalated = conflict_protocol.get_escalated_conflicts()
+```
+
+### 5. Defensive Coordination Utilities (`defensive_coordination.py`)
+
+Provides robust error handling, health monitoring, and graceful degradation capabilities.
+
+**Key Features:**
+- Retry decorators with exponential backoff and configurable exceptions
+- Defensive file I/O with cloud sync error handling (from DISCOVERIES.md patterns)
+- Health monitoring for all coordination components
+- Circuit breaker patterns for failing services
+- Graceful degradation strategies when protocols fail
+
+**Core Utilities:**
+- `@retry_with_backoff` - Decorator for automatic retries
+- `DefensiveFileIO` - Cloud-sync aware file operations
+- `CoordinationHealthCheck` - System health monitoring
+- `TaskOperationContext` - Safe operation context manager
+- `GracefulDegradation` - Fallback strategies
+
+**Usage:**
+```python
+from amplifier.planner.protocols import file_io, health_monitor, retry_with_backoff
+
+# Defensive file operations
+file_io.write_json(data, Path("tasks.json"))
+
+# Health monitoring
+health_status = await health_monitor.full_health_check()
+
+# Retry decorator
+@retry_with_backoff()
+async def risky_operation():
+    # Operation that might fail
+    pass
+```
+
+## Integration Patterns
+
+### Task Lifecycle Management
+
+```python
+from amplifier.planner.protocols import (
+    state_protocol,
+    coordination_protocol,
+    deadlock_protocol,
+    conflict_protocol
+)
+
+async def process_task_lifecycle(task):
+    # 1. Assign to agent
+    best_agent = coordination_protocol.select_best_agent(task)
+    claim = await coordination_protocol.claim_task(task.id, best_agent)
+
+    # 2. Transition to assigned state
+    task = state_protocol.transition_task(task, TaskState.ASSIGNED)
+
+    # 3. Check for dependency issues
+    cycles = await deadlock_protocol.detect_deadlocks()
+    if cycles:
+        for cycle in cycles:
+            await deadlock_protocol.resolve_deadlock(cycle)
+
+    # 4. Start work
+    task = state_protocol.transition_task(task, TaskState.IN_PROGRESS)
+
+    # 5. Handle concurrent modifications
+    if modifications:
+        task = await conflict_protocol.apply_modification_with_retry(task, modification)
+
+    # 6. Complete and release
+    task = state_protocol.transition_task(task, TaskState.COMPLETED)
+    await coordination_protocol.release_task(task.id, best_agent)
+```
+
+### Health Monitoring and Recovery
+
+```python
+from amplifier.planner.protocols import health_monitor, coordination_protocol, deadlock_protocol
+
+async def system_health_check():
+    # Full system health check
+    health = await health_monitor.full_health_check()
+
+    if health["overall_status"] == "unhealthy":
+        # Cleanup and recovery
+        await coordination_protocol.cleanup_expired_claims()
+        await coordination_protocol.cleanup_inactive_agents()
+
+        # Check for deadlocks
+        violations = await deadlock_protocol.check_timeout_violations()
+        for task_id in violations:
+            # Escalate overdue tasks
+            pass
+```
+
+## Error Handling Strategy
+
+The protocol system uses a layered error handling approach:
+
+1. **Prevention** - Validate operations before execution
+2. **Detection** - Monitor for conflicts, deadlocks, and failures
+3. **Automatic Recovery** - Retry with backoff, resolve conflicts automatically
+4. **Graceful Degradation** - Fallback strategies when protocols fail
+5. **Human Escalation** - Manual intervention for complex cases
+
+## Configuration and Customization
+
+Each protocol supports configuration for different deployment scenarios:
+
+```python
+# Custom retry configuration
+retry_config = RetryConfig(
+    max_attempts=5,
+    initial_delay=1.0,
+    backoff_multiplier=2.0,
+    retry_on_exceptions=(ConnectionError, TimeoutError)
+)
+
+# Custom deadlock thresholds
+deadlock_protocol = DeadlockPreventionProtocol(
+    max_block_duration=timedelta(hours=2),
+    escalation_threshold=timedelta(minutes=30),
+    max_dependency_depth=5
+)
+
+# Custom conflict resolution strategies
+conflict_protocol.resolution_strategies[ConflictType.ASSIGNMENT_CONFLICT] = ResolutionStrategy.LAST_WRITER_WINS
+```
+
+## Performance and Scalability
+
+The protocol system is designed for scalability:
+
+- **Lock-free where possible** - Uses optimistic locking instead of blocking
+- **Asynchronous operations** - All protocols support async/await
+- **Efficient data structures** - Fast lookups for agents, tasks, dependencies
+- **Incremental cleanup** - Background processes for expired claims and inactive agents
+- **Batched operations** - Support for bulk operations where appropriate
+
+## Git Integration
+
+The protocols are designed to work with git-based workflows:
+
+- **File-based persistence** - Uses JSON files that can be committed
+- **Conflict-free merging** - Task modifications can be merged across branches
+- **Incremental updates** - Only changed data is written to files
+- **Defensive I/O** - Handles cloud sync issues that are common in git repos
+
+This protocol system provides a robust foundation for coordinated multi-agent task management while maintaining simplicity and reliability principles from the project's implementation philosophy.
\ No newline at end of file
diff --git a/amplifier/planner/protocols/__init__.py b/amplifier/planner/protocols/__init__.py
new file mode 100644
index 00000000..b744fb65
--- /dev/null
+++ b/amplifier/planner/protocols/__init__.py
@@ -0,0 +1,79 @@
+"""
+Task State Management and Coordination Protocols
+
+This package provides comprehensive protocols for managing task state transitions,
+multi-agent coordination, deadlock prevention, conflict resolution, and defensive
+programming patterns for the super-planner system.
+
+Key Components:
+- State Transition Protocol: Manages valid task state changes with optimistic locking
+- Agent Coordination Protocol: Handles task claiming, load balancing, and resource contention
+- Deadlock Prevention Protocol: Detects and resolves circular dependencies and blocked chains
+- Conflict Resolution Protocol: Manages concurrent modifications with merge strategies
+- Defensive Coordination Utilities: Provides retry logic, health monitoring, and graceful degradation
+
+Usage Example:
+    from amplifier.planner.protocols import (
+        state_protocol,
+        coordination_protocol,
+        deadlock_protocol,
+        conflict_protocol,
+        file_io,
+        health_monitor
+    )
+
+    # Transition a task state
+    updated_task = state_protocol.transition_task(task, TaskState.IN_PROGRESS)
+
+    # Register an agent for coordination
+    await coordination_protocol.register_agent("agent_1", {"python", "ai"})
+
+    # Claim a task
+    claim = await coordination_protocol.claim_task("task_123", "agent_1")
+
+    # Check for deadlocks
+    cycles = await deadlock_protocol.detect_deadlocks()
+
+    # Resolve conflicts
+    resolved_task = await conflict_protocol.apply_modification_with_retry(task, modification)
+
+    # Health monitoring
+    health_status = await health_monitor.full_health_check()
+"""
+
+from .agent_coordination import AgentCoordinationProtocol
+from .agent_coordination import coordination_protocol
+from .conflict_resolution import ConflictResolutionProtocol
+from .conflict_resolution import conflict_protocol
+from .deadlock_prevention import DeadlockPreventionProtocol
+from .deadlock_prevention import deadlock_protocol
+from .defensive_coordination import CoordinationHealthCheck
+from .defensive_coordination import DefensiveFileIO
+from .defensive_coordination import GracefulDegradation
+from .defensive_coordination import TaskOperationContext
+from .defensive_coordination import file_io
+from .defensive_coordination import health_monitor
+from .defensive_coordination import retry_with_backoff
+from .state_transitions import StateTransitionProtocol
+from .state_transitions import state_protocol
+
+__all__ = [
+    # Protocol classes
+    "StateTransitionProtocol",
+    "AgentCoordinationProtocol",
+    "DeadlockPreventionProtocol",
+    "ConflictResolutionProtocol",
+    "DefensiveFileIO",
+    "CoordinationHealthCheck",
+    "GracefulDegradation",
+    "TaskOperationContext",
+    # Global instances
+    "state_protocol",
+    "coordination_protocol",
+    "deadlock_protocol",
+    "conflict_protocol",
+    "file_io",
+    "health_monitor",
+    # Utilities
+    "retry_with_backoff",
+]
diff --git a/amplifier/planner/protocols/agent_coordination.py b/amplifier/planner/protocols/agent_coordination.py
new file mode 100644
index 00000000..59919943
--- /dev/null
+++ b/amplifier/planner/protocols/agent_coordination.py
@@ -0,0 +1,336 @@
+"""
+Multi-Agent Coordination Protocol
+
+Manages task claiming, agent registration, load balancing, and resource contention
+for the super-planner system. Ensures fair task distribution and prevents conflicts
+between concurrent agents.
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from dataclasses import field
+from datetime import UTC
+from datetime import datetime
+from datetime import timedelta
+
+from ..core.models import Task
+
+logger = logging.getLogger(__name__)
+
+
+class ClaimError(Exception):
+    """Raised when a task claim operation fails."""
+
+    pass
+
+
+class LoadBalancingError(Exception):
+    """Raised when load balancing constraints are violated."""
+
+    pass
+
+
+@dataclass
+class AgentInfo:
+    """Information about a registered agent."""
+
+    agent_id: str
+    capabilities: set[str] = field(default_factory=set)
+    max_concurrent_tasks: int = 3
+    current_task_count: int = 0
+    last_heartbeat: datetime | None = None
+    is_active: bool = True
+
+
+@dataclass
+class TaskClaim:
+    """Represents a claimed task with lease information."""
+
+    task_id: str
+    agent_id: str
+    claimed_at: datetime
+    lease_expires_at: datetime
+    claim_version: int
+
+
+class AgentCoordinationProtocol:
+    """
+    Manages coordination between multiple agents working on tasks.
+    Handles claiming, load balancing, and resource contention.
+    """
+
+    def __init__(self, default_lease_duration: timedelta = timedelta(hours=1)):
+        self.agents: dict[str, AgentInfo] = {}
+        self.task_claims: dict[str, TaskClaim] = {}
+        self.default_lease_duration = default_lease_duration
+        self.heartbeat_timeout = timedelta(minutes=5)
+        self._lock = asyncio.Lock()
+
+    async def register_agent(self, agent_id: str, capabilities: set[str], max_concurrent_tasks: int = 3) -> None:
+        """Register a new agent with the coordination system."""
+        async with self._lock:
+            self.agents[agent_id] = AgentInfo(
+                agent_id=agent_id,
+                capabilities=capabilities,
+                max_concurrent_tasks=max_concurrent_tasks,
+                last_heartbeat=datetime.now(UTC),
+                is_active=True,
+            )
+            logger.info(f"Agent {agent_id} registered with capabilities: {capabilities}")
+
+    async def unregister_agent(self, agent_id: str) -> None:
+        """Unregister an agent and release its claimed tasks."""
+        async with self._lock:
+            if agent_id not in self.agents:
+                return
+
+            # Release all tasks claimed by this agent
+            tasks_to_release = [task_id for task_id, claim in self.task_claims.items() if claim.agent_id == agent_id]
+
+            for task_id in tasks_to_release:
+                del self.task_claims[task_id]
+                logger.info(f"Released task {task_id} from unregistered agent {agent_id}")
+
+            del self.agents[agent_id]
+            logger.info(f"Agent {agent_id} unregistered")
+
+    async def heartbeat(self, agent_id: str) -> bool:
+        """Update agent heartbeat. Returns True if agent is still registered."""
+        async with self._lock:
+            if agent_id in self.agents:
+                self.agents[agent_id].last_heartbeat = datetime.now(UTC)
+                self.agents[agent_id].is_active = True
+                return True
+            return False
+
+    async def claim_task(self, task_id: str, agent_id: str, expected_task_version: int | None = None) -> TaskClaim:
+        """
+        Attempt to claim a task for an agent.
+
+        Args:
+            task_id: ID of task to claim
+            agent_id: ID of claiming agent
+            expected_task_version: Expected task version for optimistic locking
+
+        Returns:
+            TaskClaim object if successful
+
+        Raises:
+            ClaimError: If claim fails due to conflicts or constraints
+        """
+        async with self._lock:
+            # Check if agent is registered and active
+            if agent_id not in self.agents:
+                raise ClaimError(f"Agent {agent_id} not registered")
+
+            agent = self.agents[agent_id]
+            if not agent.is_active:
+                raise ClaimError(f"Agent {agent_id} is inactive")
+
+            # Check if task is already claimed
+            if task_id in self.task_claims:
+                existing_claim = self.task_claims[task_id]
+                if existing_claim.lease_expires_at > datetime.now(UTC):
+                    raise ClaimError(f"Task {task_id} already claimed by agent {existing_claim.agent_id}")
+                # Claim has expired, remove it
+                del self.task_claims[task_id]
+
+            # Check agent's concurrent task limit
+            if agent.current_task_count >= agent.max_concurrent_tasks:
+                raise ClaimError(f"Agent {agent_id} at max concurrent tasks ({agent.max_concurrent_tasks})")
+
+            # Create claim
+            claim = TaskClaim(
+                task_id=task_id,
+                agent_id=agent_id,
+                claimed_at=datetime.now(UTC),
+                lease_expires_at=datetime.now(UTC) + self.default_lease_duration,
+                claim_version=expected_task_version or 0,
+            )
+
+            # Store claim and update agent stats
+            self.task_claims[task_id] = claim
+            agent.current_task_count += 1
+
+            logger.info(f"Task {task_id} claimed by agent {agent_id}")
+            return claim
+
+    async def release_task(self, task_id: str, agent_id: str) -> bool:
+        """
+        Release a claimed task.
+
+        Args:
+            task_id: ID of task to release
+            agent_id: ID of agent releasing the task
+
+        Returns:
+            True if task was released, False if not claimed by this agent
+        """
+        async with self._lock:
+            if task_id not in self.task_claims:
+                return False
+
+            claim = self.task_claims[task_id]
+            if claim.agent_id != agent_id:
+                logger.warning(f"Agent {agent_id} tried to release task {task_id} claimed by {claim.agent_id}")
+                return False
+
+            # Remove claim and update agent stats
+            del self.task_claims[task_id]
+            if agent_id in self.agents:
+                self.agents[agent_id].current_task_count = max(0, self.agents[agent_id].current_task_count - 1)
+
+            logger.info(f"Task {task_id} released by agent {agent_id}")
+            return True
+
+    async def renew_claim(self, task_id: str, agent_id: str) -> bool:
+        """
+        Renew a task claim to extend the lease.
+
+        Args:
+            task_id: ID of task to renew
+            agent_id: ID of agent renewing the claim
+
+        Returns:
+            True if renewal successful, False otherwise
+        """
+        async with self._lock:
+            if task_id not in self.task_claims:
+                return False
+
+            claim = self.task_claims[task_id]
+            if claim.agent_id != agent_id:
+                return False
+
+            # Extend the lease
+            claim.lease_expires_at = datetime.now(UTC) + self.default_lease_duration
+            logger.info(f"Task {task_id} claim renewed by agent {agent_id}")
+            return True
+
+    def get_available_agents(self, required_capabilities: set[str] | None = None) -> list[AgentInfo]:
+        """
+        Get list of agents available for new tasks.
+
+        Args:
+            required_capabilities: Optional set of required capabilities
+
+        Returns:
+            List of available agents, sorted by current load
+        """
+        now = datetime.now(UTC)
+        available_agents = []
+
+        for agent in self.agents.values():
+            # Check if agent is active and within heartbeat timeout
+            if not agent.is_active:
+                continue
+
+            if agent.last_heartbeat and (now - agent.last_heartbeat) > self.heartbeat_timeout:
+                continue
+
+            # Check if agent has capacity
+            if agent.current_task_count >= agent.max_concurrent_tasks:
+                continue
+
+            # Check capabilities if required
+            if required_capabilities and not required_capabilities.issubset(agent.capabilities):
+                continue
+
+            available_agents.append(agent)
+
+        # Sort by current load (ascending)
+        available_agents.sort(key=lambda a: a.current_task_count)
+        return available_agents
+
+    def select_best_agent(self, task: Task) -> str | None:
+        """
+        Select the best agent for a given task using load balancing.
+
+        Args:
+            task: Task to assign
+
+        Returns:
+            Agent ID of best candidate, or None if no suitable agent available
+        """
+        # Extract required capabilities from task metadata
+        required_capabilities = set()
+        if task.metadata and "required_capabilities" in task.metadata:
+            required_capabilities = set(task.metadata["required_capabilities"])
+
+        available_agents = self.get_available_agents(required_capabilities)
+        if not available_agents:
+            return None
+
+        # Simple load balancing: pick agent with lowest current load
+        return available_agents[0].agent_id
+
+    async def cleanup_expired_claims(self) -> int:
+        """
+        Clean up expired task claims.
+
+        Returns:
+            Number of claims cleaned up
+        """
+        async with self._lock:
+            now = datetime.now(UTC)
+            expired_claims = []
+
+            for task_id, claim in self.task_claims.items():
+                if claim.lease_expires_at <= now:
+                    expired_claims.append(task_id)
+
+            # Remove expired claims and update agent stats
+            for task_id in expired_claims:
+                claim = self.task_claims[task_id]
+                del self.task_claims[task_id]
+
+                if claim.agent_id in self.agents:
+                    self.agents[claim.agent_id].current_task_count = max(
+                        0, self.agents[claim.agent_id].current_task_count - 1
+                    )
+
+                logger.info(f"Expired claim for task {task_id} by agent {claim.agent_id}")
+
+            return len(expired_claims)
+
+    async def cleanup_inactive_agents(self) -> int:
+        """
+        Clean up agents that haven't sent heartbeats recently.
+
+        Returns:
+            Number of agents cleaned up
+        """
+        now = datetime.now(UTC)
+        inactive_agents = []
+
+        for agent_id, agent in self.agents.items():
+            if agent.last_heartbeat and (now - agent.last_heartbeat) > self.heartbeat_timeout:
+                inactive_agents.append(agent_id)
+
+        for agent_id in inactive_agents:
+            await self.unregister_agent(agent_id)
+
+        return len(inactive_agents)
+
+    def get_coordination_stats(self) -> dict:
+        """Get current coordination system statistics."""
+        now = datetime.now(UTC)
+        active_agents = sum(1 for a in self.agents.values() if a.is_active)
+        total_capacity = sum(a.max_concurrent_tasks for a in self.agents.values())
+        used_capacity = sum(a.current_task_count for a in self.agents.values())
+        active_claims = sum(1 for c in self.task_claims.values() if c.lease_expires_at > now)
+
+        return {
+            "total_agents": len(self.agents),
+            "active_agents": active_agents,
+            "total_capacity": total_capacity,
+            "used_capacity": used_capacity,
+            "utilization_rate": used_capacity / max(total_capacity, 1),
+            "active_claims": active_claims,
+            "expired_claims": len(self.task_claims) - active_claims,
+        }
+
+
+# Global coordination instance
+coordination_protocol = AgentCoordinationProtocol()
diff --git a/amplifier/planner/protocols/conflict_resolution.py b/amplifier/planner/protocols/conflict_resolution.py
new file mode 100644
index 00000000..65f4b1a2
--- /dev/null
+++ b/amplifier/planner/protocols/conflict_resolution.py
@@ -0,0 +1,454 @@
+"""
+Conflict Resolution and Consistency Protocol
+
+Handles concurrent task modifications, merge strategies, human escalation,
+and maintains consistency across distributed operations in the task system.
+"""
+
+import logging
+from collections import defaultdict
+from dataclasses import dataclass
+from dataclasses import field
+from datetime import UTC
+from datetime import datetime
+from datetime import timedelta
+from enum import Enum
+from typing import Any
+
+from ..core.models import Task
+
+logger = logging.getLogger(__name__)
+
+
+class ConflictType(Enum):
+    """Types of conflicts that can occur."""
+
+    VERSION_MISMATCH = "version_mismatch"
+    CONCURRENT_STATE_CHANGE = "concurrent_state_change"
+    ASSIGNMENT_CONFLICT = "assignment_conflict"
+    DEPENDENCY_CONFLICT = "dependency_conflict"
+    METADATA_CONFLICT = "metadata_conflict"
+
+
+class ResolutionStrategy(Enum):
+    """Conflict resolution strategies."""
+
+    LAST_WRITER_WINS = "last_writer_wins"
+    FIRST_WRITER_WINS = "first_writer_wins"
+    MERGE_CHANGES = "merge_changes"
+    ESCALATE_TO_HUMAN = "escalate_to_human"
+    REJECT_CONFLICT = "reject_conflict"
+
+
+@dataclass
+class ConflictRecord:
+    """Record of a conflict and its resolution."""
+
+    conflict_id: str
+    task_id: str
+    conflict_type: ConflictType
+    conflicting_versions: list[int]
+    conflicting_agents: list[str]
+    detected_at: datetime
+    resolution_strategy: ResolutionStrategy | None = None
+    resolved_at: datetime | None = None
+    resolution_details: dict[str, Any] = field(default_factory=dict)
+    escalated: bool = False
+
+
+@dataclass
+class TaskModification:
+    """Represents a modification to a task."""
+
+    task_id: str
+    agent_id: str
+    timestamp: datetime
+    previous_version: int
+    changes: dict[str, Any]
+    new_task_state: Task
+
+
+class ConflictResolutionProtocol:
+    """
+    Manages conflict detection and resolution for concurrent task modifications.
+    Provides multiple resolution strategies and escalation paths.
+    """
+
+    def __init__(self, auto_retry_attempts: int = 3, escalation_timeout: timedelta = timedelta(minutes=30)):
+        self.conflicts: dict[str, ConflictRecord] = {}
+        self.pending_modifications: dict[str, list[TaskModification]] = defaultdict(list)
+        self.resolution_strategies: dict[ConflictType, ResolutionStrategy] = {
+            ConflictType.VERSION_MISMATCH: ResolutionStrategy.MERGE_CHANGES,
+            ConflictType.CONCURRENT_STATE_CHANGE: ResolutionStrategy.LAST_WRITER_WINS,
+            ConflictType.ASSIGNMENT_CONFLICT: ResolutionStrategy.ESCALATE_TO_HUMAN,
+            ConflictType.DEPENDENCY_CONFLICT: ResolutionStrategy.MERGE_CHANGES,
+            ConflictType.METADATA_CONFLICT: ResolutionStrategy.MERGE_CHANGES,
+        }
+        self.auto_retry_attempts = auto_retry_attempts
+        self.escalation_timeout = escalation_timeout
+
+    def detect_conflict(self, current_task: Task, modification: TaskModification) -> ConflictType | None:
+        """
+        Detect if a modification conflicts with the current task state.
+
+        Args:
+            current_task: Current task state
+            modification: Proposed modification
+
+        Returns:
+            ConflictType if conflict detected, None otherwise
+        """
+        # Version mismatch
+        if current_task.version != modification.previous_version:
+            return ConflictType.VERSION_MISMATCH
+
+        # Concurrent state changes
+        proposed_task = modification.new_task_state
+        if current_task.state != proposed_task.state and current_task.updated_at > modification.timestamp:
+            return ConflictType.CONCURRENT_STATE_CHANGE
+
+        # Assignment conflicts
+        if (
+            current_task.assigned_to != proposed_task.assigned_to
+            and current_task.assigned_to is not None
+            and proposed_task.assigned_to is not None
+            and current_task.assigned_to != proposed_task.assigned_to
+        ):
+            return ConflictType.ASSIGNMENT_CONFLICT
+
+        # Dependency conflicts (simplified check)
+        current_deps = set(current_task.dependencies or [])
+        proposed_deps = set(proposed_task.dependencies or [])
+        if current_deps != proposed_deps and len(current_deps) > 0 and len(proposed_deps) > 0:
+            return ConflictType.DEPENDENCY_CONFLICT
+
+        return None
+
+    async def resolve_conflict(
+        self, conflict_record: ConflictRecord, current_task: Task, conflicting_modifications: list[TaskModification]
+    ) -> Task:
+        """
+        Resolve a conflict using the appropriate strategy.
+
+        Args:
+            conflict_record: Record of the conflict
+            current_task: Current task state
+            conflicting_modifications: List of conflicting modifications
+
+        Returns:
+            Resolved task state
+
+        Raises:
+            ValueError: If conflict cannot be resolved automatically
+        """
+        strategy = self.resolution_strategies.get(conflict_record.conflict_type, ResolutionStrategy.ESCALATE_TO_HUMAN)
+
+        conflict_record.resolution_strategy = strategy
+
+        if strategy == ResolutionStrategy.LAST_WRITER_WINS:
+            return await self._resolve_last_writer_wins(current_task, conflicting_modifications)
+
+        if strategy == ResolutionStrategy.FIRST_WRITER_WINS:
+            return await self._resolve_first_writer_wins(current_task, conflicting_modifications)
+
+        if strategy == ResolutionStrategy.MERGE_CHANGES:
+            return await self._resolve_merge_changes(current_task, conflicting_modifications)
+
+        if strategy == ResolutionStrategy.ESCALATE_TO_HUMAN:
+            await self._escalate_conflict(conflict_record, current_task, conflicting_modifications)
+            raise ValueError(f"Conflict {conflict_record.conflict_id} escalated to human intervention")
+
+        if strategy == ResolutionStrategy.REJECT_CONFLICT:
+            raise ValueError(f"Conflict {conflict_record.conflict_id} rejected")
+
+        raise ValueError(f"Unknown resolution strategy: {strategy}")
+
+    async def _resolve_last_writer_wins(self, current_task: Task, modifications: list[TaskModification]) -> Task:
+        """Resolve conflict by using the most recent modification."""
+        latest_mod = max(modifications, key=lambda m: m.timestamp)
+
+        # Apply the latest modification with version increment
+        resolved_task = Task(
+            id=current_task.id,
+            title=latest_mod.new_task_state.title,
+            description=latest_mod.new_task_state.description,
+            state=latest_mod.new_task_state.state,
+            priority=latest_mod.new_task_state.priority,
+            estimated_effort=latest_mod.new_task_state.estimated_effort,
+            assigned_to=latest_mod.new_task_state.assigned_to,
+            dependencies=latest_mod.new_task_state.dependencies,
+            metadata=latest_mod.new_task_state.metadata,
+            parent_id=latest_mod.new_task_state.parent_id,
+            subtask_ids=latest_mod.new_task_state.subtask_ids,
+            created_at=current_task.created_at,
+            updated_at=datetime.now(UTC),
+            started_at=latest_mod.new_task_state.started_at,
+            completed_at=latest_mod.new_task_state.completed_at,
+            cancelled_at=latest_mod.new_task_state.cancelled_at,
+            blocked_at=latest_mod.new_task_state.blocked_at,
+            blocking_reason=latest_mod.new_task_state.blocking_reason,
+            version=current_task.version + 1,
+        )
+
+        logger.info(f"Resolved conflict using last writer wins: agent {latest_mod.agent_id}")
+        return resolved_task
+
+    async def _resolve_first_writer_wins(self, current_task: Task, modifications: list[TaskModification]) -> Task:
+        """Resolve conflict by using the earliest modification."""
+        earliest_mod = min(modifications, key=lambda m: m.timestamp)
+
+        # Apply the earliest modification with version increment
+        resolved_task = Task(
+            id=current_task.id,
+            title=earliest_mod.new_task_state.title,
+            description=earliest_mod.new_task_state.description,
+            state=earliest_mod.new_task_state.state,
+            priority=earliest_mod.new_task_state.priority,
+            estimated_effort=earliest_mod.new_task_state.estimated_effort,
+            assigned_to=earliest_mod.new_task_state.assigned_to,
+            dependencies=earliest_mod.new_task_state.dependencies,
+            metadata=earliest_mod.new_task_state.metadata,
+            parent_id=earliest_mod.new_task_state.parent_id,
+            subtask_ids=earliest_mod.new_task_state.subtask_ids,
+            created_at=current_task.created_at,
+            updated_at=datetime.now(UTC),
+            started_at=earliest_mod.new_task_state.started_at,
+            completed_at=earliest_mod.new_task_state.completed_at,
+            cancelled_at=earliest_mod.new_task_state.cancelled_at,
+            blocked_at=earliest_mod.new_task_state.blocked_at,
+            blocking_reason=earliest_mod.new_task_state.blocking_reason,
+            version=current_task.version + 1,
+        )
+
+        logger.info(f"Resolved conflict using first writer wins: agent {earliest_mod.agent_id}")
+        return resolved_task
+
+    async def _resolve_merge_changes(self, current_task: Task, modifications: list[TaskModification]) -> Task:
+        """
+        Resolve conflict by intelligently merging non-conflicting changes.
+        """
+        # Start with current task as base
+        merged_task = current_task
+
+        # Sort modifications by timestamp
+        sorted_mods = sorted(modifications, key=lambda m: m.timestamp)
+
+        for mod in sorted_mods:
+            merged_task = await self._merge_single_modification(merged_task, mod)
+
+        # Update version and timestamp
+        merged_task = Task(
+            id=merged_task.id,
+            title=merged_task.title,
+            description=merged_task.description,
+            state=merged_task.state,
+            priority=merged_task.priority,
+            estimated_effort=merged_task.estimated_effort,
+            assigned_to=merged_task.assigned_to,
+            dependencies=merged_task.dependencies,
+            metadata=merged_task.metadata,
+            parent_id=merged_task.parent_id,
+            subtask_ids=merged_task.subtask_ids,
+            created_at=merged_task.created_at,
+            updated_at=datetime.now(UTC),
+            started_at=merged_task.started_at,
+            completed_at=merged_task.completed_at,
+            cancelled_at=merged_task.cancelled_at,
+            blocked_at=merged_task.blocked_at,
+            blocking_reason=merged_task.blocking_reason,
+            version=current_task.version + 1,
+        )
+
+        logger.info(f"Resolved conflict by merging changes from {len(modifications)} modifications")
+        return merged_task
+
+    async def _merge_single_modification(self, base_task: Task, modification: TaskModification) -> Task:
+        """Merge a single modification into the base task."""
+        new_state = modification.new_task_state
+
+        # Merge metadata (additive)
+        merged_metadata = (base_task.metadata or {}).copy()
+        if new_state.metadata:
+            merged_metadata.update(new_state.metadata)
+
+        # Merge dependencies (union)
+        base_deps = set(base_task.dependencies or [])
+        new_deps = set(new_state.dependencies or [])
+        merged_deps = list(base_deps.union(new_deps))
+
+        # Merge subtasks (union)
+        base_subtasks = set(base_task.subtask_ids or [])
+        new_subtasks = set(new_state.subtask_ids or [])
+        merged_subtasks = list(base_subtasks.union(new_subtasks))
+
+        # For other fields, prefer non-null values from modification
+        return Task(
+            id=base_task.id,
+            title=new_state.title if new_state.title != base_task.title else base_task.title,
+            description=new_state.description
+            if new_state.description != base_task.description
+            else base_task.description,
+            state=new_state.state if new_state.state != base_task.state else base_task.state,
+            priority=new_state.priority if new_state.priority != base_task.priority else base_task.priority,
+            estimated_effort=new_state.estimated_effort
+            if new_state.estimated_effort != base_task.estimated_effort
+            else base_task.estimated_effort,
+            assigned_to=new_state.assigned_to or base_task.assigned_to,
+            dependencies=merged_deps,
+            metadata=merged_metadata,
+            parent_id=new_state.parent_id or base_task.parent_id,
+            subtask_ids=merged_subtasks,
+            created_at=base_task.created_at,
+            updated_at=base_task.updated_at,
+            started_at=new_state.started_at or base_task.started_at,
+            completed_at=new_state.completed_at or base_task.completed_at,
+            cancelled_at=new_state.cancelled_at or base_task.cancelled_at,
+            blocked_at=new_state.blocked_at or base_task.blocked_at,
+            blocking_reason=new_state.blocking_reason or base_task.blocking_reason,
+            version=base_task.version,
+        )
+
+    async def _escalate_conflict(
+        self, conflict_record: ConflictRecord, current_task: Task, modifications: list[TaskModification]
+    ) -> None:
+        """Escalate conflict to human intervention."""
+        conflict_record.escalated = True
+
+        # Log detailed conflict information
+        logger.critical(f"CONFLICT ESCALATION: {conflict_record.conflict_id}")
+        logger.critical(f"Task ID: {current_task.id}")
+        logger.critical(f"Conflict Type: {conflict_record.conflict_type}")
+        logger.critical(f"Conflicting Agents: {conflict_record.conflicting_agents}")
+        logger.critical(f"Versions: {conflict_record.conflicting_versions}")
+
+        # Store detailed information for human review
+        conflict_record.resolution_details = {
+            "current_task": self._task_to_dict(current_task),
+            "modifications": [
+                {
+                    "agent_id": mod.agent_id,
+                    "timestamp": mod.timestamp.isoformat(),
+                    "changes": mod.changes,
+                    "new_state": self._task_to_dict(mod.new_task_state),
+                }
+                for mod in modifications
+            ],
+            "escalated_at": datetime.now(UTC).isoformat(),
+        }
+
+    def _task_to_dict(self, task: Task) -> dict[str, Any]:
+        """Convert task to dictionary for logging/storage."""
+        return {
+            "id": task.id,
+            "title": task.title,
+            "description": task.description,
+            "state": task.state.value,
+            "priority": task.priority,
+            "estimated_effort": task.estimated_effort,
+            "assigned_to": task.assigned_to,
+            "dependencies": task.dependencies,
+            "metadata": task.metadata,
+            "parent_id": task.parent_id,
+            "subtask_ids": task.subtask_ids,
+            "version": task.version,
+            "created_at": task.created_at.isoformat() if task.created_at else None,
+            "updated_at": task.updated_at.isoformat() if task.updated_at else None,
+            "started_at": task.started_at.isoformat() if task.started_at else None,
+            "completed_at": task.completed_at.isoformat() if task.completed_at else None,
+            "cancelled_at": task.cancelled_at.isoformat() if task.cancelled_at else None,
+            "blocked_at": task.blocked_at.isoformat() if task.blocked_at else None,
+            "blocking_reason": task.blocking_reason,
+        }
+
+    async def apply_modification_with_retry(self, current_task: Task, modification: TaskModification) -> Task:
+        """
+        Apply a modification with automatic conflict resolution and retry.
+
+        Args:
+            current_task: Current task state
+            modification: Modification to apply
+
+        Returns:
+            Updated task after resolution
+
+        Raises:
+            ValueError: If modification cannot be applied after retries
+        """
+        for attempt in range(self.auto_retry_attempts):
+            conflict_type = self.detect_conflict(current_task, modification)
+
+            if conflict_type is None:
+                # No conflict, apply modification directly
+                return modification.new_task_state
+
+            # Create conflict record
+            conflict_id = f"{modification.task_id}_{modification.timestamp.timestamp()}"
+            conflict_record = ConflictRecord(
+                conflict_id=conflict_id,
+                task_id=modification.task_id,
+                conflict_type=conflict_type,
+                conflicting_versions=[current_task.version, modification.previous_version],
+                conflicting_agents=[modification.agent_id],
+                detected_at=datetime.now(UTC),
+            )
+
+            self.conflicts[conflict_id] = conflict_record
+
+            try:
+                # Attempt to resolve conflict
+                resolved_task = await self.resolve_conflict(conflict_record, current_task, [modification])
+
+                conflict_record.resolved_at = datetime.now(UTC)
+                logger.info(f"Resolved conflict {conflict_id} on attempt {attempt + 1}")
+
+                return resolved_task
+
+            except ValueError as e:
+                if "escalated" in str(e):
+                    # Human intervention required
+                    raise e
+
+                if attempt == self.auto_retry_attempts - 1:
+                    # Final attempt failed
+                    logger.error(f"Failed to resolve conflict {conflict_id} after {self.auto_retry_attempts} attempts")
+                    raise e
+
+                # Retry with exponential backoff
+                import asyncio
+
+                await asyncio.sleep(2**attempt)
+                logger.warning(f"Retrying conflict resolution for {conflict_id}, attempt {attempt + 2}")
+
+        raise ValueError(f"Could not resolve conflict after {self.auto_retry_attempts} attempts")
+
+    def get_escalated_conflicts(self) -> list[ConflictRecord]:
+        """Get all conflicts that require human intervention."""
+        return [conflict for conflict in self.conflicts.values() if conflict.escalated and conflict.resolved_at is None]
+
+    def get_conflict_stats(self) -> dict[str, Any]:
+        """Get conflict resolution statistics."""
+        total_conflicts = len(self.conflicts)
+        resolved_conflicts = sum(1 for c in self.conflicts.values() if c.resolved_at is not None)
+        escalated_conflicts = sum(1 for c in self.conflicts.values() if c.escalated)
+
+        conflict_types = defaultdict(int)
+        for conflict in self.conflicts.values():
+            conflict_types[conflict.conflict_type.value] += 1
+
+        resolution_strategies = defaultdict(int)
+        for conflict in self.conflicts.values():
+            if conflict.resolution_strategy:
+                resolution_strategies[conflict.resolution_strategy.value] += 1
+
+        return {
+            "total_conflicts": total_conflicts,
+            "resolved_conflicts": resolved_conflicts,
+            "escalated_conflicts": escalated_conflicts,
+            "resolution_rate": resolved_conflicts / max(total_conflicts, 1),
+            "conflict_types": dict(conflict_types),
+            "resolution_strategies": dict(resolution_strategies),
+        }
+
+
+# Global conflict resolution instance
+conflict_protocol = ConflictResolutionProtocol()
diff --git a/amplifier/planner/protocols/deadlock_prevention.py b/amplifier/planner/protocols/deadlock_prevention.py
new file mode 100644
index 00000000..5784c558
--- /dev/null
+++ b/amplifier/planner/protocols/deadlock_prevention.py
@@ -0,0 +1,397 @@
+"""
+Deadlock Prevention and Recovery Protocol
+
+Detects circular dependencies, handles blocked task chains, implements timeout policies,
+and provides escalation procedures to prevent and resolve deadlocks in the task system.
+"""
+
+import asyncio
+import logging
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import UTC
+from datetime import datetime
+from datetime import timedelta
+
+logger = logging.getLogger(__name__)
+
+
+class DeadlockError(Exception):
+    """Raised when a deadlock is detected."""
+
+    pass
+
+
+class CircularDependencyError(Exception):
+    """Raised when circular dependencies are detected."""
+
+    pass
+
+
+@dataclass
+class BlockedTaskInfo:
+    """Information about a blocked task."""
+
+    task_id: str
+    blocked_at: datetime
+    blocking_reason: str
+    dependencies: list[str]
+    escalated: bool = False
+
+
+@dataclass
+class DeadlockCycle:
+    """Represents a detected deadlock cycle."""
+
+    task_ids: list[str]
+    cycle_length: int
+    detected_at: datetime
+    severity: str = "medium"  # low, medium, high, critical
+
+
+class DeadlockPreventionProtocol:
+    """
+    Prevents and resolves deadlocks in the task dependency system.
+    Uses cycle detection, timeouts, and escalation to maintain system health.
+    """
+
+    def __init__(
+        self,
+        max_block_duration: timedelta = timedelta(hours=4),
+        escalation_threshold: timedelta = timedelta(hours=1),
+        max_dependency_depth: int = 10,
+    ):
+        self.blocked_tasks: dict[str, BlockedTaskInfo] = {}
+        self.dependency_graph: dict[str, set[str]] = defaultdict(set)
+        self.reverse_graph: dict[str, set[str]] = defaultdict(set)
+        self.max_block_duration = max_block_duration
+        self.escalation_threshold = escalation_threshold
+        self.max_dependency_depth = max_dependency_depth
+        self._lock = asyncio.Lock()
+
+    async def add_dependency(self, dependent_task_id: str, dependency_task_id: str) -> bool:
+        """
+        Add a dependency between tasks, checking for cycles.
+
+        Args:
+            dependent_task_id: Task that depends on another
+            dependency_task_id: Task that is depended upon
+
+        Returns:
+            True if dependency added successfully, False if it would create a cycle
+
+        Raises:
+            CircularDependencyError: If adding the dependency would create a cycle
+        """
+        async with self._lock:
+            # Check if adding this dependency would create a cycle
+            if self._would_create_cycle(dependent_task_id, dependency_task_id):
+                raise CircularDependencyError(
+                    f"Adding dependency {dependent_task_id} -> {dependency_task_id} would create a circular dependency"
+                )
+
+            # Check dependency depth
+            depth = self._calculate_dependency_depth(dependency_task_id)
+            if depth >= self.max_dependency_depth:
+                logger.warning(
+                    f"Dependency chain too deep ({depth}) for {dependency_task_id}, "
+                    f"maximum is {self.max_dependency_depth}"
+                )
+                return False
+
+            # Add dependency
+            self.dependency_graph[dependent_task_id].add(dependency_task_id)
+            self.reverse_graph[dependency_task_id].add(dependent_task_id)
+
+            logger.info(f"Added dependency: {dependent_task_id} depends on {dependency_task_id}")
+            return True
+
+    async def remove_dependency(self, dependent_task_id: str, dependency_task_id: str) -> bool:
+        """Remove a dependency between tasks."""
+        async with self._lock:
+            if dependency_task_id in self.dependency_graph[dependent_task_id]:
+                self.dependency_graph[dependent_task_id].discard(dependency_task_id)
+                self.reverse_graph[dependency_task_id].discard(dependent_task_id)
+
+                # Clean up empty entries
+                if not self.dependency_graph[dependent_task_id]:
+                    del self.dependency_graph[dependent_task_id]
+                if not self.reverse_graph[dependency_task_id]:
+                    del self.reverse_graph[dependency_task_id]
+
+                logger.info(f"Removed dependency: {dependent_task_id} no longer depends on {dependency_task_id}")
+                return True
+            return False
+
+    async def mark_task_blocked(
+        self, task_id: str, blocking_reason: str, dependencies: list[str] | None = None
+    ) -> None:
+        """Mark a task as blocked and track it for deadlock detection."""
+        async with self._lock:
+            self.blocked_tasks[task_id] = BlockedTaskInfo(
+                task_id=task_id,
+                blocked_at=datetime.now(UTC),
+                blocking_reason=blocking_reason,
+                dependencies=dependencies or list(self.dependency_graph.get(task_id, [])),
+            )
+            logger.info(f"Task {task_id} marked as blocked: {blocking_reason}")
+
+    async def mark_task_unblocked(self, task_id: str) -> bool:
+        """Mark a task as unblocked and remove from tracking."""
+        async with self._lock:
+            if task_id in self.blocked_tasks:
+                del self.blocked_tasks[task_id]
+                logger.info(f"Task {task_id} marked as unblocked")
+                return True
+            return False
+
+    def _would_create_cycle(self, from_task: str, to_task: str) -> bool:
+        """Check if adding a dependency would create a cycle using DFS."""
+        # If to_task can reach from_task, then adding from_task -> to_task creates a cycle
+        return self._can_reach(to_task, from_task)
+
+    def _can_reach(self, start_task: str, target_task: str) -> bool:
+        """Check if start_task can reach target_task through dependencies."""
+        if start_task == target_task:
+            return True
+
+        visited = set()
+        stack = [start_task]
+
+        while stack:
+            current = stack.pop()
+            if current == target_task:
+                return True
+
+            if current in visited:
+                continue
+
+            visited.add(current)
+            stack.extend(self.dependency_graph.get(current, []))
+
+        return False
+
+    def _calculate_dependency_depth(self, task_id: str) -> int:
+        """Calculate the maximum depth of the dependency chain starting from task_id."""
+        visited = set()
+
+        def dfs_depth(current_task: str) -> int:
+            if current_task in visited:
+                return 0  # Avoid infinite recursion
+
+            visited.add(current_task)
+            max_depth = 0
+
+            for dependency in self.dependency_graph.get(current_task, []):
+                depth = 1 + dfs_depth(dependency)
+                max_depth = max(max_depth, depth)
+
+            visited.remove(current_task)
+            return max_depth
+
+        return dfs_depth(task_id)
+
+    async def detect_deadlocks(self) -> list[DeadlockCycle]:
+        """
+        Detect all deadlock cycles in the current task system.
+
+        Returns:
+            List of detected deadlock cycles
+        """
+        async with self._lock:
+            cycles = []
+            visited_global = set()
+
+            # Check each unvisited node for cycles
+            for task_id in self.dependency_graph:
+                if task_id not in visited_global:
+                    cycle = self._detect_cycle_from_node(task_id, visited_global)
+                    if cycle:
+                        cycles.append(
+                            DeadlockCycle(
+                                task_ids=cycle,
+                                cycle_length=len(cycle),
+                                detected_at=datetime.now(UTC),
+                                severity=self._assess_cycle_severity(cycle),
+                            )
+                        )
+
+            if cycles:
+                logger.warning(f"Detected {len(cycles)} deadlock cycles")
+
+            return cycles
+
+    def _detect_cycle_from_node(self, start_node: str, visited_global: set) -> list[str] | None:
+        """Detect cycle starting from a specific node using DFS."""
+        stack = []
+        visited_local = set()
+
+        def dfs(node: str) -> list[str] | None:
+            if node in visited_local:
+                # Found a cycle, extract it
+                cycle_start = stack.index(node)
+                return stack[cycle_start:] + [node]
+
+            if node in visited_global:
+                return None
+
+            visited_local.add(node)
+            visited_global.add(node)
+            stack.append(node)
+
+            for neighbor in self.dependency_graph.get(node, []):
+                result = dfs(neighbor)
+                if result:
+                    return result
+
+            stack.pop()
+            return None
+
+        return dfs(start_node)
+
+    def _assess_cycle_severity(self, cycle: list[str]) -> str:
+        """Assess the severity of a deadlock cycle based on various factors."""
+        cycle_length = len(cycle)
+        blocked_tasks_in_cycle = sum(1 for task_id in cycle if task_id in self.blocked_tasks)
+
+        if blocked_tasks_in_cycle >= len(cycle):
+            return "critical"  # All tasks in cycle are blocked
+        if cycle_length <= 2:
+            return "high"  # Simple direct cycle
+        if blocked_tasks_in_cycle > len(cycle) // 2:
+            return "medium"  # More than half the cycle is blocked
+        return "low"  # Potential future deadlock
+
+    async def resolve_deadlock(self, cycle: DeadlockCycle) -> bool:
+        """
+        Attempt to resolve a deadlock by breaking the cycle.
+
+        Args:
+            cycle: Deadlock cycle to resolve
+
+        Returns:
+            True if deadlock was resolved, False if manual intervention needed
+        """
+        async with self._lock:
+            logger.warning(f"Attempting to resolve deadlock cycle: {cycle.task_ids}")
+
+            # Strategy 1: Find the weakest link to break
+            weakest_dependency = self._find_weakest_dependency(cycle.task_ids)
+            if weakest_dependency:
+                from_task, to_task = weakest_dependency
+                await self.remove_dependency(from_task, to_task)
+                logger.info(f"Broke deadlock by removing dependency: {from_task} -> {to_task}")
+                return True
+
+            # Strategy 2: Cancel the most recently blocked task in the cycle
+            most_recent_blocked = self._find_most_recent_blocked_task(cycle.task_ids)
+            if most_recent_blocked:
+                # This would need to be handled by the task manager
+                logger.info(f"Recommended canceling task {most_recent_blocked} to break deadlock")
+                return True
+
+            # Strategy 3: Escalate to human intervention
+            logger.error(f"Could not automatically resolve deadlock cycle: {cycle.task_ids}")
+            await self._escalate_deadlock(cycle)
+            return False
+
+    def _find_weakest_dependency(self, cycle_tasks: list[str]) -> tuple[str, str] | None:
+        """Find the weakest dependency link in the cycle to break."""
+        # Look for dependencies where the target task is not blocked
+        # or has the least number of dependents
+        min_dependents = float("inf")
+        weakest_link = None
+
+        for i in range(len(cycle_tasks)):
+            from_task = cycle_tasks[i]
+            to_task = cycle_tasks[(i + 1) % len(cycle_tasks)]
+
+            if to_task in self.dependency_graph[from_task]:
+                # Count how many tasks depend on to_task
+                dependent_count = len(self.reverse_graph.get(to_task, []))
+
+                # Prefer non-blocked tasks
+                if to_task not in self.blocked_tasks:
+                    dependent_count -= 100  # Strong preference
+
+                if dependent_count < min_dependents:
+                    min_dependents = dependent_count
+                    weakest_link = (from_task, to_task)
+
+        return weakest_link
+
+    def _find_most_recent_blocked_task(self, cycle_tasks: list[str]) -> str | None:
+        """Find the most recently blocked task in the cycle."""
+        most_recent_task = None
+        most_recent_time = None
+
+        for task_id in cycle_tasks:
+            if task_id in self.blocked_tasks:
+                blocked_info = self.blocked_tasks[task_id]
+                if most_recent_time is None or blocked_info.blocked_at > most_recent_time:
+                    most_recent_time = blocked_info.blocked_at
+                    most_recent_task = task_id
+
+        return most_recent_task
+
+    async def _escalate_deadlock(self, cycle: DeadlockCycle) -> None:
+        """Escalate deadlock to human intervention."""
+        # Mark all tasks in cycle as escalated
+        for task_id in cycle.task_ids:
+            if task_id in self.blocked_tasks:
+                self.blocked_tasks[task_id].escalated = True
+
+        # Log detailed information for human review
+        logger.critical(f"DEADLOCK ESCALATION REQUIRED: Cycle {cycle.task_ids}")
+        logger.critical(f"Cycle severity: {cycle.severity}")
+        logger.critical(f"Cycle detected at: {cycle.detected_at}")
+
+        # In a real system, this would trigger alerts, notifications, etc.
+
+    async def check_timeout_violations(self) -> list[str]:
+        """
+        Check for tasks that have been blocked too long and need intervention.
+
+        Returns:
+            List of task IDs that have exceeded timeout thresholds
+        """
+        now = datetime.now(UTC)
+        violations = []
+
+        for task_id, blocked_info in self.blocked_tasks.items():
+            time_blocked = now - blocked_info.blocked_at
+
+            if time_blocked > self.max_block_duration:
+                violations.append(task_id)
+                logger.error(f"Task {task_id} blocked for {time_blocked}, exceeds maximum {self.max_block_duration}")
+            elif time_blocked > self.escalation_threshold and not blocked_info.escalated:
+                # Mark for escalation
+                blocked_info.escalated = True
+                logger.warning(f"Task {task_id} blocked for {time_blocked}, escalating")
+
+        return violations
+
+    async def get_deadlock_stats(self) -> dict:
+        """Get current deadlock prevention system statistics."""
+        cycles = await self.detect_deadlocks()
+        now = datetime.now(UTC)
+
+        escalated_count = sum(1 for info in self.blocked_tasks.values() if info.escalated)
+        overdue_count = sum(
+            1 for info in self.blocked_tasks.values() if (now - info.blocked_at) > self.max_block_duration
+        )
+
+        return {
+            "total_dependencies": sum(len(deps) for deps in self.dependency_graph.values()),
+            "blocked_tasks": len(self.blocked_tasks),
+            "active_deadlocks": len(cycles),
+            "escalated_tasks": escalated_count,
+            "overdue_tasks": overdue_count,
+            "max_dependency_depth": max(
+                (self._calculate_dependency_depth(task_id) for task_id in self.dependency_graph), default=0
+            ),
+        }
+
+
+# Global deadlock prevention instance
+deadlock_protocol = DeadlockPreventionProtocol()
diff --git a/amplifier/planner/protocols/defensive_coordination.py b/amplifier/planner/protocols/defensive_coordination.py
new file mode 100644
index 00000000..96d962fc
--- /dev/null
+++ b/amplifier/planner/protocols/defensive_coordination.py
@@ -0,0 +1,402 @@
+"""
+Defensive Coordination Utilities
+
+Provides defensive programming utilities for the super-planner coordination system,
+following patterns from ccsdk_toolkit with retry logic, error recovery, and graceful
+degradation strategies.
+"""
+
+import asyncio
+import json
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC
+from datetime import datetime
+from datetime import timedelta
+from functools import wraps
+from pathlib import Path
+from typing import Any
+from typing import TypeVar
+
+from ..core.models import Task
+from .state_transitions import state_protocol
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+@dataclass
+class RetryConfig:
+    """Configuration for retry operations."""
+
+    max_attempts: int = 3
+    initial_delay: float = 1.0
+    backoff_multiplier: float = 2.0
+    max_delay: float = 60.0
+    retry_on_exceptions: tuple = (ConnectionError, TimeoutError, OSError)
+
+
+@dataclass
+class CircuitBreakerConfig:
+    """Configuration for circuit breaker pattern."""
+
+    failure_threshold: int = 5
+    recovery_timeout: timedelta = timedelta(minutes=5)
+    half_open_max_calls: int = 3
+
+
+class CircuitBreakerState:
+    """Circuit breaker state management."""
+
+    def __init__(self, config: CircuitBreakerConfig):
+        self.config = config
+        self.failure_count = 0
+        self.last_failure_time: datetime | None = None
+        self.state = "closed"  # closed, open, half_open
+        self.half_open_calls = 0
+
+
+def retry_with_backoff(config: RetryConfig | None = None):
+    """
+    Decorator for retry with exponential backoff.
+    Based on defensive utilities patterns from DISCOVERIES.md.
+    """
+    if config is None:
+        config = RetryConfig()
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        async def async_wrapper(*args, **kwargs) -> T:
+            last_exception: Exception | None = None
+            delay = config.initial_delay
+
+            for attempt in range(config.max_attempts):
+                try:
+                    if asyncio.iscoroutinefunction(func):
+                        return await func(*args, **kwargs)
+                    return func(*args, **kwargs)  # type: ignore
+
+                except config.retry_on_exceptions as e:
+                    last_exception = e
+
+                    if attempt == 0:
+                        logger.warning(
+                            f"Operation failed ({func.__name__}), retrying. "
+                            f"This may be due to network issues or temporary failures. "
+                            f"Error: {e}"
+                        )
+
+                    if attempt < config.max_attempts - 1:
+                        await asyncio.sleep(min(delay, config.max_delay))
+                        delay *= config.backoff_multiplier
+                    else:
+                        logger.error(f"Operation failed after {config.max_attempts} attempts: {e}")
+                        raise e
+
+                except Exception as e:
+                    # Don't retry on non-recoverable exceptions
+                    logger.error(f"Non-recoverable error in {func.__name__}: {e}")
+                    raise e
+
+            if last_exception:
+                raise last_exception
+            raise RuntimeError("Unexpected retry loop exit")
+
+        @wraps(func)
+        def sync_wrapper(*args, **kwargs) -> T:
+            return asyncio.run(async_wrapper(*args, **kwargs))
+
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper  # type: ignore
+        return sync_wrapper
+
+    return decorator
+
+
+class DefensiveFileIO:
+    """
+    Defensive file I/O operations with retry logic and cloud sync handling.
+    Based on OneDrive/Cloud Sync patterns from DISCOVERIES.md.
+    """
+
+    def __init__(self, max_retries: int = 5, initial_delay: float = 0.5):
+        self.max_retries = max_retries
+        self.initial_delay = initial_delay
+
+    @retry_with_backoff(
+        RetryConfig(
+            max_attempts=5,
+            initial_delay=0.5,
+            backoff_multiplier=2.0,
+            retry_on_exceptions=(OSError, IOError, PermissionError),
+        )
+    )
+    def write_json(self, data: Any, filepath: Path, ensure_newline: bool = True) -> None:
+        """Write JSON data to file with defensive error handling."""
+        try:
+            # Ensure parent directory exists
+            filepath.parent.mkdir(parents=True, exist_ok=True)
+
+            # Write with explicit encoding and flushing
+            with open(filepath, "w", encoding="utf-8") as f:
+                json.dump(data, f, ensure_ascii=False, indent=2)
+                if ensure_newline:
+                    f.write("\n")
+                f.flush()
+
+        except OSError as e:
+            if e.errno == 5:  # I/O error - likely cloud sync issue
+                logger.warning(
+                    f"File I/O error writing to {filepath} - likely cloud sync delay. "
+                    f"Consider enabling 'Always keep on this device' for: {filepath.parent}"
+                )
+            raise
+
+    @retry_with_backoff(RetryConfig(max_attempts=3, retry_on_exceptions=(OSError, IOError, json.JSONDecodeError)))
+    def read_json(self, filepath: Path) -> Any:
+        """Read JSON data from file with defensive error handling."""
+        try:
+            with open(filepath, encoding="utf-8") as f:
+                return json.load(f)
+        except FileNotFoundError:
+            logger.info(f"File not found: {filepath}")
+            return None
+        except json.JSONDecodeError as e:
+            logger.error(f"Invalid JSON in {filepath}: {e}")
+            raise
+
+    @retry_with_backoff(RetryConfig(max_attempts=3, retry_on_exceptions=(OSError, IOError)))
+    def append_jsonl(self, data: Any, filepath: Path) -> None:
+        """Append JSON line to file with defensive error handling."""
+        try:
+            filepath.parent.mkdir(parents=True, exist_ok=True)
+
+            with open(filepath, "a", encoding="utf-8") as f:
+                json.dump(data, f, ensure_ascii=False)
+                f.write("\n")
+                f.flush()
+
+        except OSError as e:
+            if e.errno == 5:
+                logger.warning(f"File I/O error appending to {filepath} - likely cloud sync delay.")
+            raise
+
+
+class TaskOperationContext:
+    """
+    Context manager for safe task operations with automatic rollback.
+    """
+
+    def __init__(self, task: Task, operation_name: str):
+        self.original_task = task
+        self.operation_name = operation_name
+        self.current_task = task
+        self.completed_successfully = False
+
+    async def __aenter__(self):
+        logger.debug(f"Starting {self.operation_name} for task {self.original_task.id}")
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if exc_type is None:
+            self.completed_successfully = True
+            logger.debug(f"Completed {self.operation_name} for task {self.original_task.id}")
+        else:
+            logger.warning(f"Failed {self.operation_name} for task {self.original_task.id}: {exc_val}")
+            # In a real system, this might trigger rollback operations
+        return False
+
+    def update_task(self, new_task: Task) -> None:
+        """Update the current task state."""
+        self.current_task = new_task
+
+
+class CoordinationHealthCheck:
+    """
+    Health monitoring for coordination system components.
+    """
+
+    def __init__(self):
+        self.component_status: dict[str, dict[str, Any]] = {}
+        self.last_check_time: dict[str, datetime] = {}
+
+    async def check_state_transitions(self) -> dict[str, Any]:
+        """Check state transition system health."""
+        try:
+            # Test basic state transition validation
+            from ..core.models import Task
+            from ..core.models import TaskState
+
+            test_task = Task(
+                id="health_check",
+                title="Health Check Task",
+                description="Test task for health checking",
+                state=TaskState.NOT_STARTED,
+                version=1,
+            )
+
+            # Test transition validation
+            can_transition, reason = state_protocol.can_transition(test_task, TaskState.ASSIGNED)
+
+            status = {
+                "status": "healthy" if not can_transition else "healthy",
+                "last_check": datetime.now(UTC).isoformat(),
+                "transition_validation": "working",
+                "details": f"Can transition check: {can_transition}, reason: {reason}",
+            }
+
+        except Exception as e:
+            status = {"status": "unhealthy", "last_check": datetime.now(UTC).isoformat(), "error": str(e)}
+
+        self.component_status["state_transitions"] = status
+        self.last_check_time["state_transitions"] = datetime.now(UTC)
+        return status
+
+    async def check_coordination_protocol(self) -> dict[str, Any]:
+        """Check agent coordination protocol health."""
+        try:
+            from .agent_coordination import coordination_protocol
+
+            stats = coordination_protocol.get_coordination_stats()
+
+            status = {
+                "status": "healthy",
+                "last_check": datetime.now(UTC).isoformat(),
+                "stats": stats,
+                "active_agents": stats.get("active_agents", 0),
+                "utilization_rate": stats.get("utilization_rate", 0.0),
+            }
+
+            # Check for concerning patterns
+            if stats.get("utilization_rate", 0) > 0.9:
+                status["warnings"] = ["High utilization rate"]
+
+            if stats.get("expired_claims", 0) > 10:
+                status["warnings"] = status.get("warnings", []) + ["Many expired claims"]
+
+        except Exception as e:
+            status = {"status": "unhealthy", "last_check": datetime.now(UTC).isoformat(), "error": str(e)}
+
+        self.component_status["coordination"] = status
+        self.last_check_time["coordination"] = datetime.now(UTC)
+        return status
+
+    async def check_deadlock_prevention(self) -> dict[str, Any]:
+        """Check deadlock prevention system health."""
+        try:
+            from .deadlock_prevention import deadlock_protocol
+
+            stats = await deadlock_protocol.get_deadlock_stats()
+
+            status = {
+                "status": "healthy",
+                "last_check": datetime.now(UTC).isoformat(),
+                "stats": stats,
+                "active_deadlocks": stats.get("active_deadlocks", 0),
+                "blocked_tasks": stats.get("blocked_tasks", 0),
+            }
+
+            # Check for concerning patterns
+            if stats.get("active_deadlocks", 0) > 0:
+                status["status"] = "warning"
+                status["warnings"] = ["Active deadlocks detected"]
+
+            if stats.get("overdue_tasks", 0) > 0:
+                status["warnings"] = status.get("warnings", []) + ["Tasks overdue for resolution"]
+
+        except Exception as e:
+            status = {"status": "unhealthy", "last_check": datetime.now(UTC).isoformat(), "error": str(e)}
+
+        self.component_status["deadlock_prevention"] = status
+        self.last_check_time["deadlock_prevention"] = datetime.now(UTC)
+        return status
+
+    async def full_health_check(self) -> dict[str, Any]:
+        """Perform full health check of all coordination components."""
+        results = {}
+
+        # Run all health checks
+        results["state_transitions"] = await self.check_state_transitions()
+        results["coordination"] = await self.check_coordination_protocol()
+        results["deadlock_prevention"] = await self.check_deadlock_prevention()
+
+        # Overall status
+        all_statuses = [r["status"] for r in results.values()]
+        if "unhealthy" in all_statuses:
+            overall_status = "unhealthy"
+        elif "warning" in all_statuses:
+            overall_status = "warning"
+        else:
+            overall_status = "healthy"
+
+        return {"overall_status": overall_status, "timestamp": datetime.now(UTC).isoformat(), "components": results}
+
+
+class GracefulDegradation:
+    """
+    Provides graceful degradation strategies when coordination systems fail.
+    """
+
+    @staticmethod
+    async def fallback_task_assignment(task: Task, available_agents: list) -> str | None:
+        """Fallback task assignment when coordination protocol fails."""
+        try:
+            if not available_agents:
+                logger.warning("No agents available for fallback assignment")
+                return None
+
+            # Simple round-robin fallback
+            # In production, this might use a hash of task ID for consistency
+            agent_index = hash(task.id) % len(available_agents)
+            selected_agent = available_agents[agent_index]
+
+            logger.info(f"Fallback assignment: task {task.id} -> agent {selected_agent}")
+            return selected_agent
+
+        except Exception as e:
+            logger.error(f"Fallback assignment failed: {e}")
+            return None
+
+    @staticmethod
+    async def emergency_conflict_resolution(task: Task, conflicting_versions: list) -> Task:
+        """Emergency conflict resolution when normal protocols fail."""
+        try:
+            # Extremely simple: take the highest version number
+            latest_task = max(conflicting_versions, key=lambda t: t.version)
+
+            # Create new task with incremented version
+            resolved_task = Task(
+                id=latest_task.id,
+                title=latest_task.title,
+                description=latest_task.description,
+                state=latest_task.state,
+                priority=latest_task.priority,
+                estimated_effort=latest_task.estimated_effort,
+                assigned_to=latest_task.assigned_to,
+                dependencies=latest_task.dependencies,
+                metadata=latest_task.metadata,
+                parent_id=latest_task.parent_id,
+                subtask_ids=latest_task.subtask_ids,
+                created_at=latest_task.created_at,
+                updated_at=datetime.now(UTC),
+                started_at=latest_task.started_at,
+                completed_at=latest_task.completed_at,
+                cancelled_at=latest_task.cancelled_at,
+                blocked_at=latest_task.blocked_at,
+                blocking_reason=latest_task.blocking_reason,
+                version=latest_task.version + 1,
+            )
+
+            logger.warning(f"Emergency conflict resolution applied to task {task.id}")
+            return resolved_task
+
+        except Exception as e:
+            logger.error(f"Emergency conflict resolution failed: {e}")
+            raise
+
+
+# Global instances for defensive utilities
+file_io = DefensiveFileIO()
+health_monitor = CoordinationHealthCheck()
diff --git a/amplifier/planner/protocols/state_transitions.py b/amplifier/planner/protocols/state_transitions.py
new file mode 100644
index 00000000..5c078aff
--- /dev/null
+++ b/amplifier/planner/protocols/state_transitions.py
@@ -0,0 +1,236 @@
+"""
+State Transition Management Protocol
+
+Defines valid state transitions, guard conditions, and atomic state change operations
+for the super-planner task management system. Ensures data integrity and prevents
+invalid state changes through defensive programming patterns.
+"""
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC
+from datetime import datetime
+
+from ..core.models import Task
+from ..core.models import TaskState
+
+logger = logging.getLogger(__name__)
+
+
+class TransitionError(Exception):
+    """Raised when an invalid state transition is attempted."""
+
+    pass
+
+
+class ConcurrencyError(Exception):
+    """Raised when a concurrent modification is detected."""
+
+    pass
+
+
+@dataclass(frozen=True)
+class StateTransition:
+    """Represents a state transition with validation and effects."""
+
+    from_state: TaskState
+    to_state: TaskState
+    guard_condition: Callable[[Task], bool] | None = None
+    side_effects: Callable[[Task], None] | None = None
+    requires_assignment: bool = False
+    description: str = ""
+
+    def __hash__(self) -> int:
+        """Make StateTransition hashable for use in sets."""
+        return hash((self.from_state, self.to_state, self.requires_assignment, self.description))
+
+
+class StateTransitionProtocol:
+    """
+    Manages valid state transitions for tasks with atomic operations,
+    optimistic locking, and defensive error handling.
+    """
+
+    def __init__(self):
+        self.transitions = self._define_valid_transitions()
+        self.transition_map = self._build_transition_map()
+
+    def _define_valid_transitions(self) -> set[StateTransition]:
+        """Define all valid state transitions with their conditions."""
+        return {
+            # Initial transitions from NOT_STARTED
+            StateTransition(
+                TaskState.NOT_STARTED,
+                TaskState.ASSIGNED,
+                guard_condition=lambda t: t.assigned_to is not None,
+                description="Assign task to agent",
+            ),
+            # Direct start without assignment (for human tasks)
+            StateTransition(
+                TaskState.NOT_STARTED,
+                TaskState.IN_PROGRESS,
+                guard_condition=lambda t: t.assigned_to is not None,
+                side_effects=lambda t: setattr(t, "started_at", datetime.now(UTC)),
+                description="Start task directly",
+            ),
+            # From ASSIGNED
+            StateTransition(
+                TaskState.ASSIGNED,
+                TaskState.IN_PROGRESS,
+                side_effects=lambda t: setattr(t, "started_at", datetime.now(UTC)),
+                description="Begin working on assigned task",
+            ),
+            StateTransition(
+                TaskState.ASSIGNED,
+                TaskState.CANCELLED,
+                side_effects=lambda t: setattr(t, "cancelled_at", datetime.now(UTC)),
+                description="Cancel assigned task",
+            ),
+            # From IN_PROGRESS
+            StateTransition(
+                TaskState.IN_PROGRESS,
+                TaskState.COMPLETED,
+                side_effects=lambda t: setattr(t, "completed_at", datetime.now(UTC)),
+                description="Complete task",
+            ),
+            StateTransition(
+                TaskState.IN_PROGRESS,
+                TaskState.BLOCKED,
+                guard_condition=lambda t: bool(t.blocking_reason),
+                side_effects=lambda t: setattr(t, "blocked_at", datetime.now(UTC)),
+                description="Block task due to dependency or issue",
+            ),
+            StateTransition(
+                TaskState.IN_PROGRESS,
+                TaskState.CANCELLED,
+                side_effects=lambda t: setattr(t, "cancelled_at", datetime.now(UTC)),
+                description="Cancel in-progress task",
+            ),
+            # From BLOCKED
+            StateTransition(
+                TaskState.BLOCKED,
+                TaskState.IN_PROGRESS,
+                guard_condition=lambda t: not t.blocking_reason or t.blocking_reason.strip() == "",
+                side_effects=lambda t: setattr(t, "blocked_at", None),
+                description="Unblock and resume task",
+            ),
+            StateTransition(
+                TaskState.BLOCKED,
+                TaskState.CANCELLED,
+                side_effects=lambda t: setattr(t, "cancelled_at", datetime.now(UTC)),
+                description="Cancel blocked task",
+            ),
+            # Recovery transitions (for error handling)
+            StateTransition(
+                TaskState.ASSIGNED,
+                TaskState.NOT_STARTED,
+                side_effects=lambda t: setattr(t, "assigned_to", None),
+                description="Unassign task (recovery)",
+            ),
+        }
+
+    def _build_transition_map(self) -> dict[tuple, StateTransition]:
+        """Build fast lookup map for transitions."""
+        return {(t.from_state, t.to_state): t for t in self.transitions}
+
+    def is_valid_transition(self, from_state: TaskState, to_state: TaskState) -> bool:
+        """Check if a state transition is valid."""
+        return (from_state, to_state) in self.transition_map
+
+    def can_transition(self, task: Task, to_state: TaskState) -> tuple[bool, str | None]:
+        """
+        Check if a task can transition to the given state.
+        Returns (can_transition, reason_if_not).
+        """
+        if task.state == to_state:
+            return True, None  # Already in target state
+
+        transition_key = (task.state, to_state)
+        if transition_key not in self.transition_map:
+            return False, f"No valid transition from {task.state} to {to_state}"
+
+        transition = self.transition_map[transition_key]
+
+        # Check guard condition if present
+        if transition.guard_condition and not transition.guard_condition(task):
+            return False, f"Guard condition failed for transition to {to_state}"
+
+        return True, None
+
+    def transition_task(self, task: Task, to_state: TaskState, expected_version: int | None = None) -> Task:
+        """
+        Atomically transition a task to a new state with optimistic locking.
+
+        Args:
+            task: Task to transition
+            to_state: Target state
+            expected_version: Expected version for optimistic locking
+
+        Returns:
+            Updated task with new state and incremented version
+
+        Raises:
+            TransitionError: If transition is invalid
+            ConcurrencyError: If version conflict detected
+        """
+        # Optimistic locking check
+        if expected_version is not None and task.version != expected_version:
+            raise ConcurrencyError(f"Version conflict: expected {expected_version}, got {task.version}")
+
+        # Validate transition
+        can_transition, reason = self.can_transition(task, to_state)
+        if not can_transition:
+            raise TransitionError(f"Cannot transition task {task.id}: {reason}")
+
+        # Get transition definition
+        transition = self.transition_map[(task.state, to_state)]
+
+        # Create updated task (immutable approach)
+        updated_task = Task(
+            id=task.id,
+            title=task.title,
+            description=task.description,
+            state=to_state,  # New state
+            priority=task.priority,
+            estimated_effort=task.estimated_effort,
+            assigned_to=task.assigned_to,
+            dependencies=task.dependencies,
+            metadata=task.metadata.copy() if task.metadata else {},
+            parent_id=task.parent_id,
+            subtask_ids=task.subtask_ids.copy() if task.subtask_ids else [],
+            created_at=task.created_at,
+            updated_at=datetime.now(UTC),  # Update timestamp
+            started_at=task.started_at,
+            completed_at=task.completed_at,
+            cancelled_at=task.cancelled_at,
+            blocked_at=task.blocked_at,
+            blocking_reason=task.blocking_reason,
+            version=task.version + 1,  # Increment version
+        )
+
+        # Apply side effects if present
+        if transition.side_effects:
+            try:
+                transition.side_effects(updated_task)
+            except Exception as e:
+                logger.error(f"Side effect failed for task {task.id}: {e}")
+                raise TransitionError(f"Transition side effect failed: {e}")
+
+        logger.info(f"Task {task.id} transitioned from {task.state} to {to_state}")
+        return updated_task
+
+    def get_valid_next_states(self, current_state: TaskState) -> set[TaskState]:
+        """Get all valid next states from the current state."""
+        return {to_state for (from_state, to_state) in self.transition_map if from_state == current_state}
+
+    def get_transition_description(self, from_state: TaskState, to_state: TaskState) -> str | None:
+        """Get human-readable description of a transition."""
+        transition_key = (from_state, to_state)
+        if transition_key in self.transition_map:
+            return self.transition_map[transition_key].description
+        return None
+
+
+# Global instance
+state_protocol = StateTransitionProtocol()
diff --git a/amplifier/planner/storage.py b/amplifier/planner/storage.py
new file mode 100644
index 00000000..e1150a0d
--- /dev/null
+++ b/amplifier/planner/storage.py
@@ -0,0 +1,70 @@
+"""JSON storage operations for Super-Planner."""
+
+from datetime import datetime
+from pathlib import Path
+
+from amplifier.planner.models import Project
+from amplifier.planner.models import Task
+from amplifier.planner.models import TaskState
+from amplifier.utils.file_io import read_json
+from amplifier.utils.file_io import write_json
+
+
+def get_project_path(project_id: str) -> Path:
+    """Get the storage path for a project."""
+    base = Path("data/planner/projects")
+    base.mkdir(parents=True, exist_ok=True)
+    return base / f"{project_id}.json"
+
+
+def save_project(project: Project) -> None:
+    """Save project to JSON file."""
+    data = {
+        "id": project.id,
+        "name": project.name,
+        "created_at": project.created_at.isoformat(),
+        "updated_at": project.updated_at.isoformat(),
+        "tasks": {
+            task_id: {
+                "id": task.id,
+                "title": task.title,
+                "description": task.description,
+                "state": task.state.value,
+                "parent_id": task.parent_id,
+                "depends_on": task.depends_on,
+                "assigned_to": task.assigned_to,
+                "created_at": task.created_at.isoformat(),
+                "updated_at": task.updated_at.isoformat(),
+            }
+            for task_id, task in project.tasks.items()
+        },
+    }
+    write_json(data, get_project_path(project.id))
+
+
+def load_project(project_id: str) -> Project:
+    """Load project from JSON file."""
+    data = read_json(get_project_path(project_id))
+
+    # Reconstruct tasks with proper TaskState enum
+    tasks = {}
+    for task_id, task_data in data.get("tasks", {}).items():
+        tasks[task_id] = Task(
+            id=task_data["id"],
+            title=task_data["title"],
+            description=task_data["description"],
+            state=TaskState(task_data["state"]),
+            parent_id=task_data["parent_id"],
+            depends_on=task_data["depends_on"],
+            assigned_to=task_data["assigned_to"],
+            created_at=datetime.fromisoformat(task_data["created_at"]),
+            updated_at=datetime.fromisoformat(task_data["updated_at"]),
+        )
+
+    return Project(
+        id=data["id"],
+        name=data["name"],
+        tasks=tasks,
+        created_at=datetime.fromisoformat(data["created_at"]),
+        updated_at=datetime.fromisoformat(data["updated_at"]),
+    )
diff --git a/amplifier/planner/tests/__init__.py b/amplifier/planner/tests/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/amplifier/planner/tests/test_decomposer.py b/amplifier/planner/tests/test_decomposer.py
new file mode 100644
index 00000000..b3424665
--- /dev/null
+++ b/amplifier/planner/tests/test_decomposer.py
@@ -0,0 +1,182 @@
+"""Tests for the task decomposer module."""
+
+from unittest.mock import AsyncMock
+from unittest.mock import MagicMock
+from unittest.mock import patch
+
+import pytest
+
+from amplifier.planner.decomposer import ProjectContext
+from amplifier.planner.decomposer import decompose_goal
+from amplifier.planner.decomposer import decompose_recursively
+from amplifier.planner.models import Project
+from amplifier.planner.models import Task
+
+
+class TestDecomposer:
+    """Test task decomposition functionality."""
+
+    @pytest.fixture
+    def sample_project(self):
+        """Create a sample project for testing."""
+        return Project(id="test-proj", name="Test Project")
+
+    @pytest.fixture
+    def sample_context(self, sample_project):
+        """Create a sample project context."""
+        return ProjectContext(project=sample_project, max_depth=2, min_tasks=2)
+
+    def test_project_context_creation(self, sample_project):
+        """Test ProjectContext dataclass creation."""
+        context = ProjectContext(project=sample_project)
+
+        assert context.project == sample_project
+        assert context.max_depth == 3  # default
+        assert context.min_tasks == 2  # default
+        assert context.parent_task is None
+
+    def test_project_context_with_parent(self, sample_project):
+        """Test ProjectContext with parent task."""
+        parent = Task(id="parent-1", title="Parent Task")
+        context = ProjectContext(project=sample_project, parent_task=parent, max_depth=5, min_tasks=3)
+
+        assert context.parent_task == parent
+        assert context.max_depth == 5
+        assert context.min_tasks == 3
+
+    @pytest.mark.asyncio
+    async def test_decompose_goal_validation(self, sample_context):
+        """Test goal validation in decompose_goal."""
+        # Test empty goal
+        with pytest.raises(ValueError, match="Goal cannot be empty"):
+            await decompose_goal("", sample_context)
+
+        # Test whitespace-only goal
+        with pytest.raises(ValueError, match="Goal cannot be empty"):
+            await decompose_goal("   ", sample_context)
+
+    @pytest.mark.asyncio
+    async def test_decompose_goal_success(self, sample_context):
+        """Test successful goal decomposition with mocked LLM."""
+        mock_decomposition = MagicMock()
+        mock_decomposition.tasks = [
+            {"title": "Task 1", "description": "First task", "depends_on_indices": []},
+            {"title": "Task 2", "description": "Second task", "depends_on_indices": [0]},
+            {"title": "Task 3", "description": "Third task", "depends_on_indices": [0, 1]},
+        ]
+
+        mock_result = MagicMock()
+        mock_result.output = mock_decomposition
+
+        with patch("amplifier.planner.decomposer._get_decomposer_agent") as mock_agent:
+            agent = AsyncMock()
+            agent.run.return_value = mock_result
+            mock_agent.return_value = agent
+
+            tasks = await decompose_goal("Build a web application", sample_context)
+
+            assert len(tasks) == 3
+            assert all(isinstance(t, Task) for t in tasks)
+            assert tasks[0].title == "Task 1"
+            assert tasks[1].title == "Task 2"
+            assert tasks[2].title == "Task 3"
+
+            # Check dependencies
+            assert len(tasks[0].depends_on) == 0
+            assert len(tasks[1].depends_on) == 1
+            assert tasks[1].depends_on[0] == tasks[0].id
+            assert len(tasks[2].depends_on) == 2
+
+    @pytest.mark.asyncio
+    async def test_decompose_goal_min_tasks_retry(self, sample_context):
+        """Test retry logic when minimum tasks not met."""
+        sample_context.min_tasks = 3
+
+        # First response with too few tasks
+        mock_decomposition_1 = MagicMock()
+        mock_decomposition_1.tasks = [{"title": "Task 1", "description": "Only task"}]
+
+        # Second response with enough tasks
+        mock_decomposition_2 = MagicMock()
+        mock_decomposition_2.tasks = [
+            {"title": "Task 1", "description": "First task"},
+            {"title": "Task 2", "description": "Second task"},
+            {"title": "Task 3", "description": "Third task"},
+        ]
+
+        mock_result_1 = MagicMock()
+        mock_result_1.output = mock_decomposition_1
+        mock_result_2 = MagicMock()
+        mock_result_2.output = mock_decomposition_2
+
+        with patch("amplifier.planner.decomposer._get_decomposer_agent") as mock_agent:
+            agent = AsyncMock()
+            agent.run.side_effect = [mock_result_1, mock_result_2]
+            mock_agent.return_value = agent
+
+            tasks = await decompose_goal("Simple task", sample_context)
+
+            assert len(tasks) == 3
+            assert agent.run.call_count == 2  # Should retry once
+
+    @pytest.mark.asyncio
+    async def test_decompose_recursively(self, sample_context):
+        """Test recursive decomposition with mocked responses."""
+        sample_context.max_depth = 2
+
+        # Mock responses for different levels
+        level1_decomposition = MagicMock()
+        level1_decomposition.tasks = [
+            {"title": "Design system", "description": "Design the system"},
+            {"title": "Implement backend", "description": "Build backend"},
+        ]
+
+        level2_decomposition = MagicMock()
+        level2_decomposition.tasks = [
+            {"title": "Create database schema", "description": "Design DB"},
+            {"title": "Write API endpoints", "description": "Create APIs"},
+        ]
+
+        mock_results = [MagicMock(output=level1_decomposition), MagicMock(output=level2_decomposition)]
+
+        with patch("amplifier.planner.decomposer._get_decomposer_agent") as mock_agent:
+            agent = AsyncMock()
+            agent.run.side_effect = mock_results
+            mock_agent.return_value = agent
+
+            with patch("amplifier.planner.decomposer._is_atomic_task") as mock_atomic:
+                # Return values for each task check (need enough for all tasks)
+                mock_atomic.side_effect = [False, True, True, True]  # First not atomic, rest are
+
+                tasks = await decompose_recursively("Build app", sample_context)
+
+                # Should have tasks from both levels
+                assert len(tasks) == 4  # 2 from level 1 + 2 from level 2 of first task
+
+    def test_is_atomic_task(self):
+        """Test atomic task detection."""
+        from amplifier.planner.decomposer import _is_atomic_task
+
+        # Atomic tasks
+        atomic_tasks = [
+            Task(id="1", title="Write unit tests"),
+            Task(id="2", title="Create file structure"),
+            Task(id="3", title="Implement login function"),
+            Task(id="4", title="Fix bug in parser"),
+            Task(id="5", title="Update configuration"),
+            Task(id="6", title="Delete old files"),
+            Task(id="7", title="Install dependencies"),
+        ]
+
+        for task in atomic_tasks:
+            assert _is_atomic_task(task), f"{task.title} should be atomic"
+
+        # Non-atomic tasks
+        non_atomic_tasks = [
+            Task(id="8", title="Build authentication system"),
+            Task(id="9", title="Design user interface"),
+            Task(id="10", title="Develop API layer"),
+        ]
+
+        for task in non_atomic_tasks:
+            assert not _is_atomic_task(task), f"{task.title} should not be atomic"
diff --git a/amplifier/planner/tests/test_orchestrator.py b/amplifier/planner/tests/test_orchestrator.py
new file mode 100644
index 00000000..b4e10632
--- /dev/null
+++ b/amplifier/planner/tests/test_orchestrator.py
@@ -0,0 +1,221 @@
+"""Tests for the orchestrator module."""
+
+from datetime import datetime
+
+import pytest
+
+from amplifier.planner.models import Project
+from amplifier.planner.models import Task
+from amplifier.planner.orchestrator import ExecutionResults
+from amplifier.planner.orchestrator import TaskResult
+from amplifier.planner.orchestrator import orchestrate_execution
+
+
+@pytest.mark.asyncio
+async def test_orchestrate_empty_project():
+    """Test orchestrating an empty project."""
+    project = Project(id="test-empty", name="Empty Project")
+    results = await orchestrate_execution(project)
+
+    assert results.project_id == "test-empty"
+    assert results.status == "completed"
+    assert results.total_tasks == 0
+    assert results.completed_tasks == 0
+    assert results.failed_tasks == 0
+
+
+@pytest.mark.asyncio
+async def test_orchestrate_single_task():
+    """Test orchestrating a project with a single task."""
+    project = Project(id="test-single", name="Single Task Project")
+    task = Task(id="task1", title="First Task", description="Do something")
+    project.add_task(task)
+
+    results = await orchestrate_execution(project)
+
+    assert results.project_id == "test-single"
+    assert results.status == "completed"
+    assert results.total_tasks == 1
+    assert results.completed_tasks == 1
+    assert results.failed_tasks == 0
+    assert "task1" in results.task_results
+    assert results.task_results["task1"].status == "success"
+
+
+@pytest.mark.asyncio
+async def test_orchestrate_parallel_tasks():
+    """Test orchestrating parallel tasks without dependencies."""
+    project = Project(id="test-parallel", name="Parallel Tasks")
+
+    # Add multiple independent tasks
+    for i in range(3):
+        task = Task(id=f"task{i}", title=f"Task {i}", description=f"Do task {i}")
+        project.add_task(task)
+
+    results = await orchestrate_execution(project, max_parallel=2)
+
+    assert results.status == "completed"
+    assert results.total_tasks == 3
+    assert results.completed_tasks == 3
+    assert all(r.status == "success" for r in results.task_results.values())
+
+
+@pytest.mark.asyncio
+async def test_orchestrate_with_dependencies():
+    """Test orchestrating tasks with dependencies."""
+    project = Project(id="test-deps", name="Dependent Tasks")
+
+    # Create a chain: task1 -> task2 -> task3
+    task1 = Task(id="task1", title="First", description="Do first")
+    task2 = Task(id="task2", title="Second", description="Do second", depends_on=["task1"])
+    task3 = Task(id="task3", title="Third", description="Do third", depends_on=["task2"])
+
+    project.add_task(task1)
+    project.add_task(task2)
+    project.add_task(task3)
+
+    results = await orchestrate_execution(project)
+
+    assert results.status == "completed"
+    assert results.completed_tasks == 3
+
+    # Verify execution order (task1 should complete before task2, etc.)
+    task1_result = results.task_results["task1"]
+    task2_result = results.task_results["task2"]
+    task3_result = results.task_results["task3"]
+
+    assert task1_result.completed_at is not None
+    assert task2_result.completed_at is not None
+    assert task1_result.completed_at < task2_result.started_at
+    assert task2_result.completed_at < task3_result.started_at
+
+
+@pytest.mark.asyncio
+async def test_orchestrate_complex_dependencies():
+    """Test orchestrating with complex dependency graph."""
+    project = Project(id="test-complex", name="Complex Dependencies")
+
+    # Create a diamond dependency graph:
+    #     task1
+    #     /   \
+    #  task2  task3
+    #     \   /
+    #     task4
+
+    task1 = Task(id="task1", title="Root", description="Root task")
+    task2 = Task(id="task2", title="Left", description="Left branch", depends_on=["task1"])
+    task3 = Task(id="task3", title="Right", description="Right branch", depends_on=["task1"])
+    task4 = Task(id="task4", title="Join", description="Join task", depends_on=["task2", "task3"])
+
+    project.add_task(task1)
+    project.add_task(task2)
+    project.add_task(task3)
+    project.add_task(task4)
+
+    results = await orchestrate_execution(project, max_parallel=2)
+
+    assert results.status == "completed"
+    assert results.completed_tasks == 4
+
+    # Task4 should start after both task2 and task3 complete
+    task2_result = results.task_results["task2"]
+    task3_result = results.task_results["task3"]
+    task4_result = results.task_results["task4"]
+
+    assert task2_result.completed_at is not None
+    assert task3_result.completed_at is not None
+    assert task2_result.completed_at < task4_result.started_at
+    assert task3_result.completed_at < task4_result.started_at
+
+
+@pytest.mark.asyncio
+async def test_task_result_tracking():
+    """Test that TaskResult properly tracks execution details."""
+    result = TaskResult(task_id="test", status="success")
+
+    assert result.task_id == "test"
+    assert result.status == "success"
+    assert result.attempts == 1
+    assert isinstance(result.started_at, datetime)
+    assert result.completed_at is None
+
+    # Update result
+    result.completed_at = datetime.now()
+    result.output = {"data": "test output"}
+
+    assert result.completed_at is not None
+    assert result.output == {"data": "test output"}
+
+
+def test_execution_results_counters():
+    """Test ExecutionResults counter methods."""
+    results = ExecutionResults(project_id="test", status="in_progress", total_tasks=5)
+
+    # Add successful task
+    results.add_result(TaskResult(task_id="t1", status="success"))
+    assert results.completed_tasks == 1
+    assert results.failed_tasks == 0
+    assert results.skipped_tasks == 0
+
+    # Add failed task
+    results.add_result(TaskResult(task_id="t2", status="failed"))
+    assert results.completed_tasks == 1
+    assert results.failed_tasks == 1
+    assert results.skipped_tasks == 0
+
+    # Add skipped task
+    results.add_result(TaskResult(task_id="t3", status="skipped"))
+    assert results.completed_tasks == 1
+    assert results.failed_tasks == 1
+    assert results.skipped_tasks == 1
+
+    # Finalize with partial completion
+    results.finalize()
+    assert results.status == "partial"
+    assert results.completed_at is not None
+
+
+def test_execution_results_finalization():
+    """Test ExecutionResults status finalization logic."""
+    # All tasks completed
+    results = ExecutionResults(project_id="test", status="in_progress", total_tasks=2)
+    results.add_result(TaskResult(task_id="t1", status="success"))
+    results.add_result(TaskResult(task_id="t2", status="success"))
+    results.finalize()
+    assert results.status == "completed"
+
+    # Some tasks failed but some completed
+    results = ExecutionResults(project_id="test", status="in_progress", total_tasks=3)
+    results.add_result(TaskResult(task_id="t1", status="success"))
+    results.add_result(TaskResult(task_id="t2", status="failed"))
+    results.add_result(TaskResult(task_id="t3", status="skipped"))
+    results.finalize()
+    assert results.status == "partial"
+
+    # All tasks failed
+    results = ExecutionResults(project_id="test", status="in_progress", total_tasks=2)
+    results.add_result(TaskResult(task_id="t1", status="failed"))
+    results.add_result(TaskResult(task_id="t2", status="skipped"))
+    results.finalize()
+    assert results.status == "failed"
+
+
+@pytest.mark.asyncio
+async def test_orchestrate_with_assigned_agents():
+    """Test orchestrating tasks with assigned agents."""
+    project = Project(id="test-agents", name="Agent Assignment Test")
+
+    task1 = Task(id="task1", title="Code Review", assigned_to="code-reviewer")
+    task2 = Task(id="task2", title="Bug Fix", assigned_to="bug-fixer", depends_on=["task1"])
+
+    project.add_task(task1)
+    project.add_task(task2)
+
+    results = await orchestrate_execution(project)
+
+    assert results.status == "completed"
+    assert results.completed_tasks == 2
+
+    # Check that agent assignments were used
+    assert "code-reviewer" in results.task_results["task1"].output
+    assert "bug-fixer" in results.task_results["task2"].output
diff --git a/amplifier/planner/tests/test_planner.py b/amplifier/planner/tests/test_planner.py
new file mode 100644
index 00000000..4f0192e5
--- /dev/null
+++ b/amplifier/planner/tests/test_planner.py
@@ -0,0 +1,425 @@
+"""Comprehensive tests for the Super-Planner system."""
+
+import tempfile
+from datetime import UTC
+from datetime import datetime
+from pathlib import Path
+
+import pytest
+
+from amplifier.planner import Project
+from amplifier.planner import Task
+from amplifier.planner import TaskState
+from amplifier.planner import load_project
+from amplifier.planner import save_project
+
+
+class TestTask:
+    """Test Task functionality."""
+
+    def test_task_creation(self):
+        """Test basic task creation."""
+        task = Task(id="t1", title="Test Task", description="A test task")
+        assert task.id == "t1"
+        assert task.title == "Test Task"
+        assert task.description == "A test task"
+        assert task.state == TaskState.PENDING
+        assert task.parent_id is None
+        assert task.depends_on == []
+        assert task.assigned_to is None
+        assert isinstance(task.created_at, datetime)
+        assert isinstance(task.updated_at, datetime)
+
+    def test_task_with_all_fields(self):
+        """Test task creation with all fields."""
+        now = datetime.now()
+        task = Task(
+            id="t2",
+            title="Complex Task",
+            description="A complex task",
+            state=TaskState.IN_PROGRESS,
+            parent_id="t1",
+            depends_on=["t0"],
+            assigned_to="user1",
+            created_at=now,
+            updated_at=now,
+        )
+        assert task.state == TaskState.IN_PROGRESS
+        assert task.parent_id == "t1"
+        assert task.depends_on == ["t0"]
+        assert task.assigned_to == "user1"
+
+    def test_can_start_no_dependencies(self):
+        """Test can_start with no dependencies."""
+        task = Task(id="t1", title="Independent Task")
+        assert task.can_start(set()) is True
+        assert task.can_start({"t0"}) is True
+
+    def test_can_start_with_dependencies(self):
+        """Test can_start with dependencies."""
+        task = Task(id="t1", title="Dependent Task", depends_on=["t0", "t2"])
+        assert task.can_start(set()) is False
+        assert task.can_start({"t0"}) is False
+        assert task.can_start({"t0", "t2"}) is True
+        assert task.can_start({"t0", "t2", "t3"}) is True
+
+    def test_task_state_values(self):
+        """Test all task state values."""
+        assert TaskState.PENDING.value == "pending"
+        assert TaskState.IN_PROGRESS.value == "in_progress"
+        assert TaskState.COMPLETED.value == "completed"
+        assert TaskState.BLOCKED.value == "blocked"
+
+
+class TestProject:
+    """Test Project functionality."""
+
+    def test_project_creation(self):
+        """Test basic project creation."""
+        project = Project(id="p1", name="Test Project")
+        assert project.id == "p1"
+        assert project.name == "Test Project"
+        assert project.tasks == {}
+        assert isinstance(project.created_at, datetime)
+        assert isinstance(project.updated_at, datetime)
+
+    def test_add_task(self):
+        """Test adding tasks to project."""
+        project = Project(id="p1", name="Test Project")
+        original_updated = project.updated_at
+
+        # Small delay to ensure timestamp difference
+        import time
+
+        time.sleep(0.01)
+
+        task1 = Task(id="t1", title="Task 1")
+        project.add_task(task1)
+
+        assert "t1" in project.tasks
+        assert project.tasks["t1"] == task1
+        assert project.updated_at > original_updated
+
+        task2 = Task(id="t2", title="Task 2")
+        project.add_task(task2)
+        assert len(project.tasks) == 2
+
+    def test_get_roots(self):
+        """Test getting root tasks."""
+        project = Project(id="p1", name="Test Project")
+
+        # Add root tasks
+        root1 = Task(id="r1", title="Root 1")
+        root2 = Task(id="r2", title="Root 2")
+        project.add_task(root1)
+        project.add_task(root2)
+
+        # Add child tasks
+        child1 = Task(id="c1", title="Child 1", parent_id="r1")
+        child2 = Task(id="c2", title="Child 2", parent_id="r2")
+        project.add_task(child1)
+        project.add_task(child2)
+
+        roots = project.get_roots()
+        assert len(roots) == 2
+        assert root1 in roots
+        assert root2 in roots
+        assert child1 not in roots
+        assert child2 not in roots
+
+    def test_get_children(self):
+        """Test getting child tasks."""
+        project = Project(id="p1", name="Test Project")
+
+        # Add parent task
+        parent = Task(id="parent", title="Parent Task")
+        project.add_task(parent)
+
+        # Add children
+        child1 = Task(id="c1", title="Child 1", parent_id="parent")
+        child2 = Task(id="c2", title="Child 2", parent_id="parent")
+        child3 = Task(id="c3", title="Child 3", parent_id="other")
+        project.add_task(child1)
+        project.add_task(child2)
+        project.add_task(child3)
+
+        children = project.get_children("parent")
+        assert len(children) == 2
+        assert child1 in children
+        assert child2 in children
+        assert child3 not in children
+
+    def test_hierarchical_structure(self):
+        """Test complex hierarchical task structure."""
+        project = Project(id="p1", name="Hierarchical Project")
+
+        # Create hierarchy:
+        # root1
+        #   ├── child1
+        #   │   └── grandchild1
+        #   └── child2
+        # root2
+
+        root1 = Task(id="r1", title="Root 1")
+        root2 = Task(id="r2", title="Root 2")
+        child1 = Task(id="c1", title="Child 1", parent_id="r1")
+        child2 = Task(id="c2", title="Child 2", parent_id="r1")
+        grandchild1 = Task(id="gc1", title="Grandchild 1", parent_id="c1")
+
+        for task in [root1, root2, child1, child2, grandchild1]:
+            project.add_task(task)
+
+        # Test structure
+        roots = project.get_roots()
+        assert len(roots) == 2
+
+        r1_children = project.get_children("r1")
+        assert len(r1_children) == 2
+        assert child1 in r1_children
+        assert child2 in r1_children
+
+        c1_children = project.get_children("c1")
+        assert len(c1_children) == 1
+        assert grandchild1 in c1_children
+
+        r2_children = project.get_children("r2")
+        assert len(r2_children) == 0
+
+
+class TestStorage:
+    """Test storage operations."""
+
+    @pytest.fixture
+    def temp_data_dir(self, monkeypatch):
+        """Use temporary directory for data storage."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmpdir_path = Path(tmpdir)
+
+            # Patch the get_project_path to use temp directory
+            def mock_get_path(project_id):
+                base = tmpdir_path / "data" / "planner" / "projects"
+                base.mkdir(parents=True, exist_ok=True)
+                return base / f"{project_id}.json"
+
+            monkeypatch.setattr("amplifier.planner.storage.get_project_path", mock_get_path)
+            yield tmpdir_path
+
+    def test_save_and_load_simple(self, temp_data_dir):
+        """Test saving and loading a simple project."""
+        project = Project(id="p1", name="Test Project")
+        task = Task(id="t1", title="Test Task", description="Description")
+        project.add_task(task)
+
+        # Save project
+        save_project(project)
+
+        # Load project
+        loaded = load_project("p1")
+
+        assert loaded.id == "p1"
+        assert loaded.name == "Test Project"
+        assert len(loaded.tasks) == 1
+        assert "t1" in loaded.tasks
+        assert loaded.tasks["t1"].title == "Test Task"
+        assert loaded.tasks["t1"].description == "Description"
+
+    def test_save_and_load_complex(self, temp_data_dir):
+        """Test saving and loading project with all task fields."""
+        project = Project(id="p2", name="Complex Project")
+
+        # Create tasks with various states and relationships
+        task1 = Task(
+            id="t1",
+            title="Task 1",
+            description="First task",
+            state=TaskState.COMPLETED,
+            assigned_to="user1",
+        )
+
+        task2 = Task(
+            id="t2",
+            title="Task 2",
+            description="Second task",
+            state=TaskState.IN_PROGRESS,
+            parent_id="t1",
+            depends_on=["t1"],
+            assigned_to="user2",
+        )
+
+        task3 = Task(
+            id="t3",
+            title="Task 3",
+            state=TaskState.BLOCKED,
+            depends_on=["t1", "t2"],
+        )
+
+        project.add_task(task1)
+        project.add_task(task2)
+        project.add_task(task3)
+
+        # Save and reload
+        save_project(project)
+        loaded = load_project("p2")
+
+        # Verify all data preserved
+        assert len(loaded.tasks) == 3
+
+        # Check task1
+        t1 = loaded.tasks["t1"]
+        assert t1.title == "Task 1"
+        assert t1.state == TaskState.COMPLETED
+        assert t1.assigned_to == "user1"
+
+        # Check task2
+        t2 = loaded.tasks["t2"]
+        assert t2.state == TaskState.IN_PROGRESS
+        assert t2.parent_id == "t1"
+        assert t2.depends_on == ["t1"]
+        assert t2.assigned_to == "user2"
+
+        # Check task3
+        t3 = loaded.tasks["t3"]
+        assert t3.state == TaskState.BLOCKED
+        assert t3.depends_on == ["t1", "t2"]
+
+    def test_round_trip_preserves_timestamps(self, temp_data_dir):
+        """Test that timestamps are preserved through save/load."""
+        now = datetime(2024, 1, 1, 12, 0, 0, tzinfo=UTC)
+
+        project = Project(id="p3", name="Timestamp Test", created_at=now, updated_at=now)
+
+        task = Task(
+            id="t1",
+            title="Task",
+            created_at=now,
+            updated_at=now,
+        )
+        project.tasks["t1"] = task  # Add directly to avoid updating timestamp
+
+        save_project(project)
+        loaded = load_project("p3")
+
+        assert loaded.created_at == now
+        assert loaded.updated_at == now
+        assert loaded.tasks["t1"].created_at == now
+        assert loaded.tasks["t1"].updated_at == now
+
+    def test_empty_project(self, temp_data_dir):
+        """Test saving and loading empty project."""
+        project = Project(id="empty", name="Empty Project")
+        save_project(project)
+
+        loaded = load_project("empty")
+        assert loaded.id == "empty"
+        assert loaded.name == "Empty Project"
+        assert loaded.tasks == {}
+
+    def test_task_state_enum_serialization(self, temp_data_dir):
+        """Test that TaskState enum values are correctly serialized."""
+        project = Project(id="p4", name="Enum Test")
+
+        for state in TaskState:
+            task = Task(id=state.value, title=f"{state.value} task", state=state)
+            project.add_task(task)
+
+        save_project(project)
+        loaded = load_project("p4")
+
+        for state in TaskState:
+            assert state.value in loaded.tasks
+            assert loaded.tasks[state.value].state == state
+
+
+class TestIntegration:
+    """Integration tests for complete workflows."""
+
+    @pytest.fixture
+    def temp_data_dir(self, monkeypatch):
+        """Use temporary directory for data storage."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmpdir_path = Path(tmpdir)
+
+            def mock_get_path(project_id):
+                base = tmpdir_path / "data" / "planner" / "projects"
+                base.mkdir(parents=True, exist_ok=True)
+                return base / f"{project_id}.json"
+
+            monkeypatch.setattr("amplifier.planner.storage.get_project_path", mock_get_path)
+            yield tmpdir_path
+
+    def test_complete_workflow(self, temp_data_dir):
+        """Test a complete project workflow."""
+        # Create project
+        project = Project(id="workflow", name="Complete Workflow")
+
+        # Add epic (root task)
+        epic = Task(
+            id="epic1",
+            title="Build Feature X",
+            description="Complete implementation of Feature X",
+            assigned_to="team-lead",
+        )
+        project.add_task(epic)
+
+        # Add stories under epic
+        story1 = Task(
+            id="story1",
+            title="Design API",
+            parent_id="epic1",
+            assigned_to="architect",
+        )
+        story2 = Task(
+            id="story2",
+            title="Implement Backend",
+            parent_id="epic1",
+            depends_on=["story1"],
+            assigned_to="backend-dev",
+        )
+        story3 = Task(
+            id="story3",
+            title="Create UI",
+            parent_id="epic1",
+            depends_on=["story1"],
+            assigned_to="frontend-dev",
+        )
+        story4 = Task(
+            id="story4",
+            title="Integration Testing",
+            parent_id="epic1",
+            depends_on=["story2", "story3"],
+            assigned_to="qa",
+        )
+
+        for story in [story1, story2, story3, story4]:
+            project.add_task(story)
+
+        # Test dependency checking
+        completed = set()
+        assert story1.can_start(completed) is True  # No dependencies
+        assert story2.can_start(completed) is False  # Depends on story1
+        assert story3.can_start(completed) is False  # Depends on story1
+
+        # Complete story1
+        completed.add("story1")
+        story1.state = TaskState.COMPLETED
+
+        assert story2.can_start(completed) is True  # Dependencies met
+        assert story3.can_start(completed) is True  # Dependencies met
+        assert story4.can_start(completed) is False  # Needs story2 and story3
+
+        # Save and reload
+        save_project(project)
+        loaded = load_project("workflow")
+
+        # Verify structure preserved
+        roots = loaded.get_roots()
+        assert len(roots) == 1
+        assert roots[0].id == "epic1"
+
+        children = loaded.get_children("epic1")
+        assert len(children) == 4
+        child_ids = {c.id for c in children}
+        assert child_ids == {"story1", "story2", "story3", "story4"}
+
+        # Verify dependencies preserved
+        assert loaded.tasks["story4"].depends_on == ["story2", "story3"]
diff --git a/amplifier/planner/tests/test_planner_hostile.py b/amplifier/planner/tests/test_planner_hostile.py
new file mode 100644
index 00000000..c0d1f84f
--- /dev/null
+++ b/amplifier/planner/tests/test_planner_hostile.py
@@ -0,0 +1,916 @@
+#!/usr/bin/env python3
+"""
+Hostile Testing Suite for Super-Planner Phase 1
+Testing with "Rewrite Vi Editor in Python" - A Complex Multi-Level Project
+
+This test is designed to break things and find edge cases by:
+- Creating deeply nested hierarchies (5+ levels)
+- Complex dependency graphs with multiple paths
+- Large numbers of tasks (100+)
+- Edge case scenarios (circular deps, missing deps, etc.)
+- Stress testing state transitions
+- Large data serialization
+- Unusual task names and characters
+- Performance testing with bulk operations
+"""
+
+import json
+import sys
+import time
+from pathlib import Path
+
+from amplifier.planner import Project
+from amplifier.planner import Task
+from amplifier.planner import TaskState
+from amplifier.planner import load_project
+from amplifier.planner import save_project
+
+
+class HostileTester:
+    """Hostile testing framework for Phase 1"""
+
+    def __init__(self):
+        self.failures = []
+        self.test_count = 0
+        self.start_time = time.time()
+
+    def assert_test(self, condition, message):
+        """Custom assertion with failure tracking"""
+        self.test_count += 1
+        if not condition:
+            self.failures.append(f"❌ Test {self.test_count}: {message}")
+            print(f"❌ FAIL: {message}")
+            return False
+        print(f"✅ PASS: {message}")
+        return True
+
+    def test_edge_case_task_creation(self):
+        """Test edge cases in task creation"""
+        print("\n🔥 HOSTILE TEST 1: Edge Case Task Creation")
+
+        # Test with unusual characters
+        weird_task = Task(
+            id="weird-chars-™️🔥💻",
+            title="Task with émojis and spéciał chars: <>&\"'",
+            description="Multi-line\ndescription with\ttabs and\nweird chars: 你好世界",
+        )
+        self.assert_test(weird_task.id == "weird-chars-™️🔥💻", "Task with weird characters created")
+
+        # Test with very long strings
+        long_id = "a" * 1000
+        long_task = Task(id=long_id, title="b" * 500, description="c" * 2000)
+        self.assert_test(len(long_task.description) == 2000, "Task with very long strings")
+
+        # Test with empty/minimal data
+        minimal_task = Task("", "")
+        self.assert_test(minimal_task.id == "", "Task with empty ID")
+
+        # Test with None values where optional
+        task_with_nones = Task("test", "Test", assigned_to=None, parent_id=None)
+        self.assert_test(task_with_nones.assigned_to is None, "Task with explicit None values")
+
+        return True
+
+    def test_circular_dependencies(self):
+        """Test detection/handling of circular dependencies"""
+        print("\n🔥 HOSTILE TEST 2: Circular Dependencies")
+
+        project = Project("circular-test", "Circular Dependency Test")
+
+        # Create circular dependency: A -> B -> C -> A
+        task_a = Task("a", "Task A", depends_on=["c"])  # Depends on C
+        task_b = Task("b", "Task B", depends_on=["a"])  # Depends on A
+        task_c = Task("c", "Task C", depends_on=["b"])  # Depends on B -> Circular!
+
+        project.add_task(task_a)
+        project.add_task(task_b)
+        project.add_task(task_c)
+
+        # Test that none can start (circular dependency)
+        completed = set()
+        can_start_a = task_a.can_start(completed)
+        can_start_b = task_b.can_start(completed)
+        can_start_c = task_c.can_start(completed)
+
+        self.assert_test(
+            not can_start_a and not can_start_b and not can_start_c,
+            "Circular dependencies prevent all tasks from starting",
+        )
+
+        return project
+
+    def test_complex_dependency_graph(self):
+        """Test complex dependency resolution"""
+        print("\n🔥 HOSTILE TEST 3: Complex Dependency Graph")
+
+        project = Project("complex-deps", "Complex Dependencies")
+
+        # Create diamond dependency pattern
+        root = Task("root", "Root Task")
+        branch_a = Task("branch_a", "Branch A", depends_on=["root"])
+        branch_b = Task("branch_b", "Branch B", depends_on=["root"])
+        merge = Task("merge", "Merge Task", depends_on=["branch_a", "branch_b"])
+
+        # Create fan-out from merge
+        fan1 = Task("fan1", "Fan 1", depends_on=["merge"])
+        fan2 = Task("fan2", "Fan 2", depends_on=["merge"])
+        fan3 = Task("fan3", "Fan 3", depends_on=["merge"])
+
+        # Create final convergence
+        final = Task("final", "Final", depends_on=["fan1", "fan2", "fan3"])
+
+        tasks = [root, branch_a, branch_b, merge, fan1, fan2, fan3, final]
+        for task in tasks:
+            project.add_task(task)
+
+        # Test dependency resolution step by step
+        completed = set()
+
+        # Initially only root can start
+        startable = [t for t in tasks if t.can_start(completed)]
+        self.assert_test(len(startable) == 1 and startable[0].id == "root", "Only root task can start initially")
+
+        # Complete root, now branches can start
+        completed.add("root")
+        startable = [t for t in tasks if t.can_start(completed) and t.id not in completed]
+        startable_ids = {t.id for t in startable}
+        self.assert_test(startable_ids == {"branch_a", "branch_b"}, "After root, both branches can start")
+
+        # Complete both branches, merge can start
+        completed.update(["branch_a", "branch_b"])
+        startable = [t for t in tasks if t.can_start(completed) and t.id not in completed]
+        self.assert_test(len(startable) == 1 and startable[0].id == "merge", "After branches, merge can start")
+
+        return project
+
+    def create_vi_editor_project(self):
+        """Create the monster Vi editor rewrite project"""
+        print("\n🔥 HOSTILE TEST 4: Vi Editor Project - Ultra Complex Hierarchy")
+
+        project = Project("vi-rewrite", "Vi Editor Rewrite in Python")
+
+        # Level 1: Major components
+        architecture = Task(
+            "arch", "Architecture & Design", "Define overall architecture, data structures, and interfaces"
+        )
+
+        core_engine = Task(
+            "core",
+            "Core Editing Engine",
+            "Text buffer management, cursor handling, basic operations",
+            depends_on=["arch"],
+        )
+
+        command_system = Task(
+            "commands", "Command System", "Vi command parsing, execution, and modal interface", depends_on=["arch"]
+        )
+
+        ui_system = Task(
+            "ui", "User Interface System", "Terminal handling, screen rendering, input processing", depends_on=["arch"]
+        )
+
+        file_system = Task(
+            "filesystem", "File Operations", "File I/O, backup, recovery, file type detection", depends_on=["arch"]
+        )
+
+        # Level 2: Architecture breakdown
+        arch_tasks = [
+            Task(
+                "arch-analysis",
+                "Requirements Analysis",
+                parent_id="arch",
+                description="Analyze vi behavior, commands, edge cases",
+            ),
+            Task(
+                "arch-design",
+                "System Design",
+                parent_id="arch",
+                depends_on=["arch-analysis"],
+                description="Design core data structures and interfaces",
+            ),
+            Task(
+                "arch-patterns",
+                "Design Patterns",
+                parent_id="arch",
+                depends_on=["arch-design"],
+                description="Define patterns for extensibility",
+            ),
+            Task(
+                "arch-docs",
+                "Architecture Documentation",
+                parent_id="arch",
+                depends_on=["arch-patterns"],
+                description="Document architecture decisions",
+            ),
+        ]
+
+        # Level 2: Core engine breakdown
+        core_tasks = [
+            Task(
+                "core-buffer",
+                "Text Buffer",
+                parent_id="core",
+                depends_on=["core"],
+                description="Efficient text storage with undo/redo",
+            ),
+            Task(
+                "core-cursor",
+                "Cursor Management",
+                parent_id="core",
+                depends_on=["core-buffer"],
+                description="Cursor positioning, movement, selection",
+            ),
+            Task(
+                "core-operations",
+                "Basic Operations",
+                parent_id="core",
+                depends_on=["core-cursor"],
+                description="Insert, delete, replace operations",
+            ),
+            Task(
+                "core-marks",
+                "Marks and Registers",
+                parent_id="core",
+                depends_on=["core-operations"],
+                description="Named marks, registers, clipboard",
+            ),
+            Task(
+                "core-search",
+                "Search Engine",
+                parent_id="core",
+                depends_on=["core-operations"],
+                description="Pattern matching, regex, search/replace",
+            ),
+        ]
+
+        # Level 3: Buffer implementation details
+        buffer_tasks = [
+            Task(
+                "buffer-gap",
+                "Gap Buffer Implementation",
+                parent_id="core-buffer",
+                depends_on=["core-buffer"],
+                description="Efficient gap buffer with automatic expansion",
+            ),
+            Task(
+                "buffer-lines",
+                "Line Management",
+                parent_id="core-buffer",
+                depends_on=["buffer-gap"],
+                description="Line indexing, wrapping, virtual lines",
+            ),
+            Task(
+                "buffer-encoding",
+                "Text Encoding",
+                parent_id="core-buffer",
+                depends_on=["buffer-lines"],
+                description="UTF-8, line endings, BOM handling",
+            ),
+            Task(
+                "buffer-undo",
+                "Undo System",
+                parent_id="core-buffer",
+                depends_on=["buffer-encoding"],
+                description="Efficient undo/redo with branching",
+            ),
+            Task(
+                "buffer-diff",
+                "Change Tracking",
+                parent_id="core-buffer",
+                depends_on=["buffer-undo"],
+                description="Track changes for diff, backup",
+            ),
+        ]
+
+        # Level 2: Command system breakdown
+        command_tasks = [
+            Task(
+                "cmd-parser",
+                "Command Parser",
+                parent_id="commands",
+                depends_on=["commands"],
+                description="Parse vi commands with error handling",
+            ),
+            Task(
+                "cmd-modes",
+                "Modal Interface",
+                parent_id="commands",
+                depends_on=["cmd-parser"],
+                description="Normal, insert, visual, command modes",
+            ),
+            Task(
+                "cmd-movement",
+                "Movement Commands",
+                parent_id="commands",
+                depends_on=["cmd-modes"],
+                description="h,j,k,l, w,e,b, $,^, G, etc.",
+            ),
+            Task(
+                "cmd-editing",
+                "Editing Commands",
+                parent_id="commands",
+                depends_on=["cmd-movement"],
+                description="i,a,o, d,c,y, p, u, ., etc.",
+            ),
+            Task(
+                "cmd-visual",
+                "Visual Mode",
+                parent_id="commands",
+                depends_on=["cmd-editing"],
+                description="Visual selection, visual block",
+            ),
+            Task(
+                "cmd-ex",
+                "Ex Commands",
+                parent_id="commands",
+                depends_on=["cmd-visual"],
+                description=":w, :q, :s, :!, etc.",
+            ),
+        ]
+
+        # Level 3: Movement command details
+        movement_tasks = [
+            Task(
+                "move-char",
+                "Character Movement",
+                parent_id="cmd-movement",
+                depends_on=["cmd-movement"],
+                description="h,l,space,backspace movement",
+            ),
+            Task(
+                "move-word",
+                "Word Movement",
+                parent_id="cmd-movement",
+                depends_on=["move-char"],
+                description="w,e,b,W,E,B word boundaries",
+            ),
+            Task(
+                "move-line",
+                "Line Movement",
+                parent_id="cmd-movement",
+                depends_on=["move-word"],
+                description="j,k,$,^,0,+,- movements",
+            ),
+            Task(
+                "move-search",
+                "Search Movement",
+                parent_id="cmd-movement",
+                depends_on=["move-line"],
+                description="f,F,t,T,;,, and /,? searches",
+            ),
+            Task(
+                "move-jump",
+                "Jump Commands",
+                parent_id="cmd-movement",
+                depends_on=["move-search"],
+                description="G,gg,H,M,L,ctrl-f,ctrl-b",
+            ),
+        ]
+
+        # Level 2: UI system breakdown
+        ui_tasks = [
+            Task(
+                "ui-terminal",
+                "Terminal Interface",
+                parent_id="ui",
+                depends_on=["ui"],
+                description="Raw terminal control, escape sequences",
+            ),
+            Task(
+                "ui-screen",
+                "Screen Management",
+                parent_id="ui",
+                depends_on=["ui-terminal"],
+                description="Screen buffer, scrolling, refresh",
+            ),
+            Task(
+                "ui-input",
+                "Input Processing",
+                parent_id="ui",
+                depends_on=["ui-screen"],
+                description="Key mapping, special keys, timing",
+            ),
+            Task(
+                "ui-rendering",
+                "Text Rendering",
+                parent_id="ui",
+                depends_on=["ui-input"],
+                description="Syntax highlighting, line numbers",
+            ),
+            Task(
+                "ui-status",
+                "Status Line",
+                parent_id="ui",
+                depends_on=["ui-rendering"],
+                description="Mode indicator, position, filename",
+            ),
+        ]
+
+        # Level 2: File system breakdown
+        file_tasks = [
+            Task(
+                "file-io",
+                "Basic File I/O",
+                parent_id="filesystem",
+                depends_on=["filesystem"],
+                description="Read/write files, error handling",
+            ),
+            Task(
+                "file-backup",
+                "Backup System",
+                parent_id="filesystem",
+                depends_on=["file-io"],
+                description="Swap files, backup files, recovery",
+            ),
+            Task(
+                "file-detection",
+                "File Type Detection",
+                parent_id="filesystem",
+                depends_on=["file-backup"],
+                description="Syntax detection, file associations",
+            ),
+            Task(
+                "file-encoding",
+                "Encoding Detection",
+                parent_id="filesystem",
+                depends_on=["file-detection"],
+                description="Auto-detect and handle encodings",
+            ),
+        ]
+
+        # Integration tasks (depend on multiple components)
+        integration_tasks = [
+            Task(
+                "integration-basic",
+                "Basic Integration",
+                depends_on=["core-operations", "cmd-editing", "ui-screen"],
+                description="Integrate core editing with UI",
+            ),
+            Task(
+                "integration-advanced",
+                "Advanced Integration",
+                depends_on=["integration-basic", "core-search", "cmd-ex"],
+                description="Integrate search, ex commands",
+            ),
+            Task(
+                "integration-files",
+                "File Integration",
+                depends_on=["integration-advanced", "file-encoding"],
+                description="Integrate file operations",
+            ),
+        ]
+
+        # Testing tasks (comprehensive testing pyramid)
+        test_tasks = [
+            Task(
+                "test-unit",
+                "Unit Tests",
+                depends_on=["buffer-diff", "move-jump", "ui-status"],
+                description="Unit tests for all components",
+            ),
+            Task(
+                "test-integration",
+                "Integration Tests",
+                depends_on=["test-unit", "integration-files"],
+                description="Integration tests across components",
+            ),
+            Task(
+                "test-compatibility",
+                "Vi Compatibility Tests",
+                depends_on=["test-integration"],
+                description="Test compatibility with real vi",
+            ),
+            Task(
+                "test-performance",
+                "Performance Tests",
+                depends_on=["test-compatibility"],
+                description="Large file performance, memory usage",
+            ),
+            Task(
+                "test-edge-cases",
+                "Edge Case Tests",
+                depends_on=["test-performance"],
+                description="Binary files, huge files, corner cases",
+            ),
+        ]
+
+        # Polish and release tasks
+        polish_tasks = [
+            Task(
+                "polish-docs",
+                "Documentation",
+                depends_on=["test-edge-cases"],
+                description="User manual, developer docs",
+            ),
+            Task(
+                "polish-package",
+                "Packaging",
+                depends_on=["polish-docs"],
+                description="Setup.py, distribution, installation",
+            ),
+            Task(
+                "polish-ci",
+                "CI/CD Setup",
+                depends_on=["polish-package"],
+                description="GitHub actions, automated testing",
+            ),
+            Task("release-beta", "Beta Release", depends_on=["polish-ci"], description="Initial beta release"),
+            Task("release-stable", "Stable Release", depends_on=["release-beta"], description="1.0 stable release"),
+        ]
+
+        # Add ALL tasks to project
+        all_tasks = (
+            [architecture, core_engine, command_system, ui_system, file_system]
+            + arch_tasks
+            + core_tasks
+            + buffer_tasks
+            + command_tasks
+            + movement_tasks
+            + ui_tasks
+            + file_tasks
+            + integration_tasks
+            + test_tasks
+            + polish_tasks
+        )
+
+        print(f"   Creating {len(all_tasks)} tasks with complex dependencies...")
+
+        for task in all_tasks:
+            project.add_task(task)
+
+        # Add some stress test tasks with random dependencies
+        import random
+
+        for i in range(20):
+            # Pick random existing tasks as dependencies
+            existing_ids = list(project.tasks.keys())
+            num_deps = random.randint(0, min(3, len(existing_ids)))
+            deps = random.sample(existing_ids, num_deps) if num_deps > 0 else []
+
+            stress_task = Task(
+                f"stress-{i:02d}",
+                f"Stress Test Task {i}",
+                f"Random stress test task with {num_deps} dependencies",
+                depends_on=deps,
+            )
+            project.add_task(stress_task)
+
+        print(f"   Total tasks created: {len(project.tasks)}")
+
+        self.assert_test(len(project.tasks) > 50, f"Created large project with {len(project.tasks)} tasks")
+
+        return project
+
+    def test_hierarchy_navigation(self, project):
+        """Test complex hierarchy navigation"""
+        print("\n🔥 HOSTILE TEST 5: Complex Hierarchy Navigation")
+
+        # Test root finding
+        project.get_roots()
+
+        # Find actual roots (tasks with no parent_id and not depended on by others)
+        actual_roots = []
+        for task in project.tasks.values():
+            if task.parent_id is None:
+                # Check if it's not just a dependency
+                is_dependency_only = any(
+                    task.id in other_task.depends_on
+                    for other_task in project.tasks.values()
+                    if other_task.id != task.id
+                )
+                if not is_dependency_only or task.id in ["arch", "core", "commands", "ui", "filesystem"]:
+                    actual_roots.append(task)
+
+        self.assert_test(len(actual_roots) >= 5, f"Found {len(actual_roots)} root tasks in complex hierarchy")
+
+        # Test deep hierarchy navigation
+        if "arch" in project.tasks:
+            arch_children = project.get_children("arch")
+            self.assert_test(len(arch_children) >= 4, f"Architecture has {len(arch_children)} direct children")
+
+            # Test grandchildren
+            if arch_children:
+                first_child = arch_children[0]
+                grandchildren = project.get_children(first_child.id)
+                print(f"   Found {len(grandchildren)} grandchildren under {first_child.title}")
+
+        # Test that hierarchy doesn't create loops
+        def check_hierarchy_loops(task_id, visited=None):
+            if visited is None:
+                visited = set()
+            if task_id in visited:
+                return True  # Loop detected
+            visited.add(task_id)
+
+            task = project.tasks.get(task_id)
+            if task and task.parent_id:
+                return check_hierarchy_loops(task.parent_id, visited)
+            return False
+
+        loop_count = 0
+        for task_id in project.tasks:
+            if check_hierarchy_loops(task_id):
+                loop_count += 1
+
+        self.assert_test(loop_count == 0, f"No hierarchy loops detected (checked {len(project.tasks)} tasks)")
+
+        return True
+
+    def test_dependency_resolution_stress(self, project):
+        """Stress test dependency resolution"""
+        print("\n🔥 HOSTILE TEST 6: Dependency Resolution Stress Test")
+
+        # Test can_start for all tasks
+        completed = set()
+        start_time = time.time()
+
+        initial_startable = []
+        for task in project.tasks.values():
+            if task.can_start(completed):
+                initial_startable.append(task)
+
+        resolution_time = time.time() - start_time
+        self.assert_test(
+            resolution_time < 1.0, f"Dependency resolution for {len(project.tasks)} tasks took {resolution_time:.3f}s"
+        )
+
+        print(f"   Initially {len(initial_startable)} tasks can start")
+
+        # Simulate completing tasks and check resolution at each step
+        simulation_steps = 0
+        max_steps = min(50, len(project.tasks))  # Limit simulation for performance
+
+        while len(completed) < max_steps and simulation_steps < max_steps:
+            startable = [t for t in project.tasks.values() if t.can_start(completed) and t.id not in completed]
+
+            if not startable:
+                break
+
+            # "Complete" the first startable task
+            next_task = startable[0]
+            completed.add(next_task.id)
+            simulation_steps += 1
+
+            if simulation_steps % 10 == 0:
+                print(f"   Step {simulation_steps}: Completed {len(completed)} tasks, {len(startable)} available")
+
+        self.assert_test(simulation_steps > 20, f"Successfully simulated {simulation_steps} task completions")
+
+        # Test that we didn't get stuck (should be able to complete at least some tasks)
+        progress_ratio = len(completed) / len(project.tasks)
+        self.assert_test(progress_ratio > 0.1, f"Made progress on {progress_ratio:.2%} of tasks")
+
+        return True
+
+    def test_serialization_stress(self, project):
+        """Test serialization with large, complex data"""
+        print("\n🔥 HOSTILE TEST 7: Serialization Stress Test")
+
+        # Add tasks with extreme data
+        extreme_task = Task(
+            "extreme-data",
+            "Task with extreme data",
+            "Description with every Unicode character: " + "".join(chr(i) for i in range(32, 127)),
+        )
+
+        # Add metadata stress test
+        extreme_task.assigned_to = "user with 🔥émojis💻 and spëciål chars"
+        project.add_task(extreme_task)
+
+        # Test save with large project
+        start_time = time.time()
+        try:
+            save_project(project)
+            save_time = time.time() - start_time
+            self.assert_test(save_time < 5.0, f"Large project save took {save_time:.3f}s (under 5s)")
+        except Exception as e:
+            self.assert_test(False, f"Save failed with large project: {e}")
+            return False
+
+        # Test load with large project
+        start_time = time.time()
+        try:
+            loaded_project = load_project(project.id)
+            load_time = time.time() - start_time
+            self.assert_test(load_time < 2.0, f"Large project load took {load_time:.3f}s (under 2s)")
+        except Exception as e:
+            self.assert_test(False, f"Load failed with large project: {e}")
+            return False
+
+        # Test data integrity with complex project
+        self.assert_test(loaded_project is not None, "Large project loaded successfully")
+        self.assert_test(
+            len(loaded_project.tasks) == len(project.tasks), f"All {len(project.tasks)} tasks preserved after save/load"
+        )
+
+        # Test specific task integrity
+        if "extreme-data" in loaded_project.tasks:
+            loaded_extreme = loaded_project.tasks["extreme-data"]
+            self.assert_test(
+                loaded_extreme.assigned_to == extreme_task.assigned_to, "Unicode characters preserved in assignment"
+            )
+
+        # Test JSON structure manually
+        data_file = Path("data/planner/projects") / f"{project.id}.json"
+        if data_file.exists():
+            try:
+                with open(data_file) as f:
+                    json_data = json.load(f)
+
+                self.assert_test("tasks" in json_data, "JSON contains tasks array")
+                self.assert_test(len(json_data["tasks"]) == len(project.tasks), "JSON task count matches project")
+
+                # Test that JSON is properly formatted (can be re-parsed)
+                json_str = json.dumps(json_data, indent=2)
+                reparsed = json.loads(json_str)
+                self.assert_test(reparsed == json_data, "JSON round-trip successful")
+
+            except Exception as e:
+                self.assert_test(False, f"JSON validation failed: {e}")
+
+        return loaded_project
+
+    def test_state_transition_stress(self, project):
+        """Test state transitions under stress"""
+        print("\n🔥 HOSTILE TEST 8: State Transition Stress")
+
+        # Test all possible state transitions
+        test_task = Task("state-test", "State Transition Test")
+        project.add_task(test_task)
+
+        # Test each state transition
+        states = [TaskState.PENDING, TaskState.IN_PROGRESS, TaskState.COMPLETED, TaskState.BLOCKED]
+
+        for from_state in states:
+            for to_state in states:
+                test_task.state = from_state
+                test_task.state = to_state  # Should always work (no validation in Phase 1)
+                self.assert_test(test_task.state == to_state, f"Transition from {from_state.value} to {to_state.value}")
+
+        # Test rapid state changes (performance)
+        start_time = time.time()
+        for i in range(1000):
+            test_task.state = states[i % len(states)]
+
+        transition_time = time.time() - start_time
+        self.assert_test(transition_time < 0.1, f"1000 state transitions took {transition_time:.3f}s")
+
+        # Test state preservation through save/load
+        test_task.state = TaskState.BLOCKED
+        save_project(project)
+
+        loaded = load_project(project.id)
+        if loaded and "state-test" in loaded.tasks:
+            loaded_state = loaded.tasks["state-test"].state
+            self.assert_test(loaded_state == TaskState.BLOCKED, "BLOCKED state preserved through save/load")
+
+        return True
+
+    def test_error_conditions(self):
+        """Test error handling and edge cases"""
+        print("\n🔥 HOSTILE TEST 9: Error Conditions & Edge Cases")
+
+        # Test loading non-existent project
+        try:
+            load_project("this-project-does-not-exist-12345")
+            self.assert_test(False, "Loading non-existent project should raise FileNotFoundError")
+        except FileNotFoundError:
+            self.assert_test(True, "Loading non-existent project raises FileNotFoundError")
+
+        # Test with invalid task dependencies
+        project = Project("error-test", "Error Test Project")
+
+        task_with_missing_deps = Task(
+            "missing-deps", "Missing Dependencies", depends_on=["non-existent-1", "non-existent-2"]
+        )
+        project.add_task(task_with_missing_deps)
+
+        # Should not crash, but can't start due to missing dependencies
+        completed = set()
+        can_start = task_with_missing_deps.can_start(completed)
+        self.assert_test(not can_start, "Task with missing dependencies cannot start")
+
+        # Test adding dependencies that exist
+        helper_task = Task("helper", "Helper Task")
+        project.add_task(helper_task)
+        completed.add("helper")  # Complete the helper
+
+        # Still can't start because other deps are missing
+        still_cant_start = task_with_missing_deps.can_start(completed)
+        self.assert_test(not still_cant_start, "Task still blocked by remaining missing dependencies")
+
+        # Test duplicate task IDs
+        original_task = Task("duplicate-id", "Original Task")
+        duplicate_task = Task("duplicate-id", "Duplicate Task")
+
+        project.add_task(original_task)
+        project.add_task(duplicate_task)  # Should overwrite
+
+        self.assert_test(
+            project.tasks["duplicate-id"].title == "Duplicate Task", "Duplicate task ID overwrites original"
+        )
+
+        return True
+
+    def test_performance_limits(self, project):
+        """Test performance with large operations"""
+        print("\n🔥 HOSTILE TEST 10: Performance Limits")
+
+        # Test bulk operations
+        bulk_tasks = []
+        start_time = time.time()
+
+        for i in range(500):
+            task = Task(f"bulk-{i:03d}", f"Bulk Task {i}", f"Generated task {i}")
+            bulk_tasks.append(task)
+            project.add_task(task)
+
+        bulk_creation_time = time.time() - start_time
+        self.assert_test(bulk_creation_time < 2.0, f"Creating 500 tasks took {bulk_creation_time:.3f}s")
+
+        print(f"   Project now has {len(project.tasks)} total tasks")
+
+        # Test bulk dependency checking
+        completed = {f"bulk-{i:03d}" for i in range(0, 250, 2)}  # Complete every other task
+
+        start_time = time.time()
+        startable_count = 0
+        for task in project.tasks.values():
+            if task.can_start(completed):
+                startable_count += 1
+
+        dependency_check_time = time.time() - start_time
+        self.assert_test(
+            dependency_check_time < 1.0,
+            f"Dependency check on {len(project.tasks)} tasks took {dependency_check_time:.3f}s",
+        )
+
+        print(f"   Found {startable_count} startable tasks with {len(completed)} completed")
+
+        # Test memory usage (rough estimate)
+        import sys
+
+        project_size = sys.getsizeof(project) + sum(sys.getsizeof(task) for task in project.tasks.values())
+        size_mb = project_size / (1024 * 1024)
+
+        self.assert_test(size_mb < 10, f"Project memory usage {size_mb:.2f}MB (under 10MB)")
+
+        return True
+
+    def run_all_tests(self):
+        """Run the complete hostile test suite"""
+        print("🔥🔥🔥 HOSTILE TESTING SUITE - SUPER-PLANNER PHASE 1 🔥🔥🔥")
+        print("Designed to break things and find every possible edge case!")
+        print("=" * 80)
+
+        # Run all tests
+        self.test_edge_case_task_creation()
+        self.test_circular_dependencies()
+        self.test_complex_dependency_graph()
+
+        vi_project = self.create_vi_editor_project()
+        self.test_hierarchy_navigation(vi_project)
+        self.test_dependency_resolution_stress(vi_project)
+        loaded_project = self.test_serialization_stress(vi_project)
+        self.test_state_transition_stress(loaded_project or vi_project)
+        self.test_error_conditions()
+        self.test_performance_limits(loaded_project or vi_project)
+
+        # Final results
+        total_time = time.time() - self.start_time
+
+        print("\n" + "=" * 80)
+        print("🔥 HOSTILE TESTING COMPLETE 🔥")
+        print(f"⏱️  Total time: {total_time:.2f} seconds")
+        print(f"🧪 Tests run: {self.test_count}")
+        print(f"✅ Passed: {self.test_count - len(self.failures)}")
+        print(f"❌ Failed: {len(self.failures)}")
+
+        if self.failures:
+            print("\n💥 FAILURES:")
+            for failure in self.failures:
+                print(f"   {failure}")
+            print("\n🚨 PHASE 1 HAS ISSUES! 🚨")
+            return False
+        print("\n🎉 ALL HOSTILE TESTS PASSED! 🎉")
+        print("✨ Phase 1 is BULLETPROOF! ✨")
+        print(
+            f"💪 Successfully handled {len(loaded_project.tasks) if 'loaded_project' in locals() and loaded_project else 'many'} tasks in complex project"
+        )
+        return True
+
+
+def main():
+    """Run the hostile test suite"""
+    tester = HostileTester()
+    success = tester.run_all_tests()
+
+    print("\n📁 Test data saved to: data/planner/projects/")
+    print("   Check vi-rewrite.json to see the complex project structure")
+
+    return success
+
+
+if __name__ == "__main__":
+    success = main()
+    sys.exit(0 if success else 1)
diff --git a/amplifier/planner/tests/test_planner_phase1.py b/amplifier/planner/tests/test_planner_phase1.py
new file mode 100644
index 00000000..8c362e8c
--- /dev/null
+++ b/amplifier/planner/tests/test_planner_phase1.py
@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""
+Manual test script for Super-Planner Phase 1
+Run this script to verify the basic functionality works correctly.
+"""
+
+import sys
+import uuid
+from pathlib import Path
+
+from amplifier.planner import Project
+from amplifier.planner import Task
+from amplifier.planner import TaskState
+from amplifier.planner import load_project
+from amplifier.planner import save_project
+
+
+def test_basic_functionality():
+    """Test basic task and project creation"""
+    print("🧪 Testing Basic Functionality...")
+
+    # Create a project
+    project = Project(id=str(uuid.uuid4()), name="Test Blog Project")
+
+    print(f"✅ Created project: {project.name}")
+    print(f"   ID: {project.id}")
+
+    # Create some tasks
+    setup_task = Task(id="setup", title="Setup Project", description="Initialize Django blog project")
+
+    models_task = Task(
+        id="models",
+        title="Create Models",
+        description="Define User, Post, Comment models",
+        depends_on=["setup"],  # Depends on setup
+    )
+
+    views_task = Task(
+        id="views",
+        title="Create Views",
+        description="Build list, detail, create views",
+        depends_on=["models"],  # Depends on models
+    )
+
+    # Add tasks to project
+    project.add_task(setup_task)
+    project.add_task(models_task)
+    project.add_task(views_task)
+
+    print(f"✅ Added {len(project.tasks)} tasks to project")
+
+    return project
+
+
+def test_hierarchy_and_dependencies():
+    """Test hierarchical structure and dependency checking"""
+    print("\n🏗️  Testing Hierarchy and Dependencies...")
+
+    # Create project
+    project = Project(id="test-hierarchy", name="Hierarchy Test")
+
+    # Create parent task
+    backend = Task(id="backend", title="Backend Development", description="API and server")
+
+    # Create child tasks with parent
+    auth = Task(id="auth", title="Authentication", parent_id="backend")
+    api = Task(id="api", title="REST API", parent_id="backend", depends_on=["auth"])
+
+    # Create independent task
+    frontend = Task(id="frontend", title="Frontend", depends_on=["api"])
+
+    # Add all tasks
+    for task in [backend, auth, api, frontend]:
+        project.add_task(task)
+
+    # Test hierarchy navigation
+    roots = project.get_roots()
+    print(f"✅ Root tasks: {[t.title for t in roots]}")
+
+    children = project.get_children("backend")
+    print(f"✅ Backend children: {[t.title for t in children]}")
+
+    # Test dependency checking
+    completed = set()  # No tasks completed yet
+
+    can_start_auth = project.tasks["auth"].can_start(completed)
+    can_start_api = project.tasks["api"].can_start(completed)
+    can_start_frontend = project.tasks["frontend"].can_start(completed)
+
+    print(f"✅ Can start auth (no deps): {can_start_auth}")
+    print(f"✅ Can start api (needs auth): {can_start_api}")
+    print(f"✅ Can start frontend (needs api): {can_start_frontend}")
+
+    # Complete auth, test again
+    completed.add("auth")
+    can_start_api_after = project.tasks["api"].can_start(completed)
+    print(f"✅ Can start api after auth done: {can_start_api_after}")
+
+    return project
+
+
+def test_state_management():
+    """Test task state transitions"""
+    print("\n🔄 Testing State Management...")
+
+    task = Task(id="test-state", title="State Test", description="Testing states")
+
+    print(f"✅ Initial state: {task.state}")
+
+    # Manually change state (Phase 1 doesn't have automatic transitions)
+    task.state = TaskState.IN_PROGRESS
+    print(f"✅ Updated to: {task.state}")
+
+    task.state = TaskState.COMPLETED
+    print(f"✅ Updated to: {task.state}")
+
+    # Test state enum values
+    print(f"✅ Available states: {[state.value for state in TaskState]}")
+
+    return task
+
+
+def test_persistence():
+    """Test save and load functionality"""
+    print("\n💾 Testing Persistence...")
+
+    # Create test project
+    original_project = Project(id="persistence-test", name="Persistence Test")
+
+    task1 = Task(id="t1", title="Task 1", description="First task")
+    task1.state = TaskState.COMPLETED
+
+    task2 = Task(id="t2", title="Task 2", depends_on=["t1"])
+    task2.assigned_to = "test-user"
+
+    original_project.add_task(task1)
+    original_project.add_task(task2)
+
+    print(f"✅ Created project with {len(original_project.tasks)} tasks")
+
+    # Save project
+    try:
+        save_project(original_project)
+        print("✅ Project saved successfully")
+    except Exception as e:
+        print(f"❌ Save failed: {e}")
+        return None
+
+    # Load project
+    try:
+        loaded_project = load_project("persistence-test")
+        if loaded_project is None:
+            print("❌ Load returned None")
+            return None
+
+        print("✅ Project loaded successfully")
+        print(f"   Name: {loaded_project.name}")
+        print(f"   Tasks: {len(loaded_project.tasks)}")
+
+        # Verify task details preserved
+        loaded_t1 = loaded_project.tasks["t1"]
+        loaded_t2 = loaded_project.tasks["t2"]
+
+        print(f"   Task 1 state: {loaded_t1.state}")
+        print(f"   Task 2 assigned to: {loaded_t2.assigned_to}")
+        print(f"   Task 2 depends on: {loaded_t2.depends_on}")
+
+        # Verify data integrity
+        assert loaded_t1.state == TaskState.COMPLETED
+        assert loaded_t2.assigned_to == "test-user"
+        assert loaded_t2.depends_on == ["t1"]
+
+        print("✅ All data preserved correctly")
+
+        return loaded_project
+
+    except Exception as e:
+        print(f"❌ Load failed: {e}")
+        return None
+
+
+def test_complete_workflow():
+    """Test complete project workflow"""
+    print("\n🚀 Testing Complete Workflow...")
+
+    # Create Django blog project
+    project = Project(id="django-blog", name="Django Blog")
+
+    # Define task hierarchy
+    tasks = [
+        Task("setup", "Project Setup", "Create Django project and configure settings"),
+        Task("models", "Database Models", "Create User, Post, Comment models", depends_on=["setup"]),
+        Task("admin", "Admin Interface", "Configure Django admin", depends_on=["models"]),
+        Task("views", "Views", "Create list, detail, create views", depends_on=["models"]),
+        Task("templates", "Templates", "Design HTML templates", depends_on=["views"]),
+        Task("urls", "URL Configuration", "Set up routing", depends_on=["views"]),
+        Task("tests", "Tests", "Write unit tests", depends_on=["models", "views"]),
+        Task("deploy", "Deployment", "Deploy to production", depends_on=["templates", "urls", "tests"]),
+    ]
+
+    # Add all tasks
+    for task in tasks:
+        project.add_task(task)
+
+    print(f"✅ Created project with {len(tasks)} tasks")
+
+    # Save project
+    save_project(project)
+    print("✅ Project saved")
+
+    # Simulate workflow: complete tasks in dependency order
+    completed_tasks = set()
+
+    def find_ready_tasks():
+        ready = []
+        for task in project.tasks.values():
+            if task.state == TaskState.PENDING and task.can_start(completed_tasks):
+                ready.append(task)
+        return ready
+
+    step = 1
+    while completed_tasks != set(project.tasks.keys()):
+        ready_tasks = find_ready_tasks()
+
+        if not ready_tasks:
+            break
+
+        # "Complete" the first ready task
+        next_task = ready_tasks[0]
+        next_task.state = TaskState.COMPLETED
+        completed_tasks.add(next_task.id)
+
+        print(f"   Step {step}: Completed '{next_task.title}'")
+        step += 1
+
+    # Save final state
+    save_project(project)
+    print("✅ Workflow simulation completed")
+
+    return project
+
+
+def show_data_files():
+    """Show created data files"""
+    print("\n📁 Created Data Files:")
+
+    data_dir = Path("data/planner/projects")
+    if data_dir.exists():
+        for json_file in data_dir.glob("*.json"):
+            print(f"   📄 {json_file}")
+            # Show first few lines
+            try:
+                with open(json_file) as f:
+                    content = f.read()
+                    lines = content.split("\n")[:5]
+                    preview = "\n".join(lines)
+                    if len(content.split("\n")) > 5:
+                        preview += "\n      ..."
+                    print(f"      Preview:\n      {preview.replace(chr(10), chr(10) + '      ')}")
+            except Exception:
+                pass
+    else:
+        print("   No data directory found")
+
+
+def main():
+    """Run all tests"""
+    print("🎯 Super-Planner Phase 1 Manual Testing")
+    print("=" * 50)
+
+    try:
+        # Test basic functionality
+        test_basic_functionality()
+
+        # Test hierarchy
+        test_hierarchy_and_dependencies()
+
+        # Test states
+        test_state_management()
+
+        # Test persistence
+        test_persistence()
+
+        # Test complete workflow
+        test_complete_workflow()
+
+        # Show files created
+        show_data_files()
+
+        print("\n🎉 ALL TESTS COMPLETED SUCCESSFULLY!")
+        print("\nWhat was tested:")
+        print("✅ Task and Project creation")
+        print("✅ Hierarchical structure (parents/children)")
+        print("✅ Dependency management")
+        print("✅ State transitions")
+        print("✅ File persistence (save/load)")
+        print("✅ Complete project workflow")
+
+        print("\n💾 Data stored in: data/planner/projects/")
+        print("   You can examine the JSON files to see the structure")
+
+        return True
+
+    except Exception as e:
+        print(f"\n❌ TEST FAILED: {e}")
+        import traceback
+
+        traceback.print_exc()
+        return False
+
+
+if __name__ == "__main__":
+    success = main()
+    sys.exit(0 if success else 1)
diff --git a/amplifier/planner/working_plan.md b/amplifier/planner/working_plan.md
new file mode 100644
index 00000000..230d7837
--- /dev/null
+++ b/amplifier/planner/working_plan.md
@@ -0,0 +1,321 @@
+# Super-Planner Implementation Working Plan
+
+## Project Context
+
+**Branch**: `feature/super-planner` (currently checked out)
+**Location**: `amplifier/planner/` (core library component, not scenarios)
+**Philosophy**: Amplifier's "bricks and studs" modular design with ruthless simplicity
+
+### Problem Statement
+Build a text and file-based system within amplifier that manages large projects with multiple subtasks, supporting both multiple AI agents and humans working concurrently. The system breaks down tasks recursively, manages state (not started, assigned, in progress, completed), and coordinates strategic task assignment with sub-agent spawning.
+
+### Key Requirements
+- **Two Modes**: Planning (recursive AI task breakdown) and Working (strategic assignment + agent spawning)
+- **File-Based Persistence**: All data in JSON files with git integration
+- **Multi-Agent Coordination**: Multiple amplifier instances working together via Task tool
+- **Strategic Assignment**: Analyze complete project plan for optimal task ordering
+- **Amplifier Integration**: Uses same LLM calls, tools, and patterns as existing amplifier
+
+### Architecture Overview
+```
+amplifier/planner/
+├── core/           # Task, Project models, business logic
+├── modes/          # PlanningMode, WorkingMode implementations
+├── persistence/    # File storage + git integration
+├── orchestrator/   # Agent spawning + coordination
+├── session/        # LLM integration via CCSDK toolkit
+└── tests/          # Golden test suite (28 scenarios)
+```
+
+### Integration Points
+- **Task Tool**: For spawning sub-agents (`Task(subagent_type="zen-architect", prompt="...")`)
+- **CCSDK Toolkit**: `SessionManager`, defensive utilities, `parse_llm_json`, `retry_with_feedback`
+- **Git**: Auto-commit, recovery points, distributed coordination
+- **Makefile**: CLI commands (`make planner-create`, `make planner-plan`, etc.)
+
+### Key Design Decisions Made
+1. **Core library in amplifier/** (not scenarios/) - infrastructure component
+2. **File-based storage** with git (not database) - follows amplifier patterns
+3. **JSON with sorted keys** - git-friendly diffs
+4. **Per-project git repos** - isolation and parallel development
+5. **Optimistic locking** - version numbers prevent conflicts
+6. **Agent spawning via Task tool** - reuses existing amplifier capability
+7. **Three-phase implementation** - Foundation → Intelligence → Coordination
+
+### Testing Strategy
+- **Spec and Test Forward**: Golden tests define behavior before implementation
+- **28 Test Scenarios**: End-to-end workflows, multi-agent coordination, failure recovery
+- **60-30-10 Pyramid**: Unit (state transitions) → Integration (mode switching) → E2E (real projects)
+- **Sample Projects**: Simple (8 tasks), Complex (22 tasks), Enterprise (1000+ tasks)
+- **Performance Targets**: 1000 tasks <30s load, 20 concurrent agents, <100ms state transitions
+
+## Implementation Tasks
+
+### Phase 1: Foundation (Core + Persistence)
+**Priority**: P0 - Essential foundation
+**Estimated Time**: 8-12 hours
+**Dependencies**: None
+
+#### Core Module (`amplifier/planner/core/`)
+- [ ] **models.py** - Complete Task, Project, TaskState data models
+  - Task model with 20+ fields (id, title, description, state, dependencies, metadata, etc.)
+  - Project model with goals, constraints, success_criteria
+  - TaskState enum (NOT_STARTED, ASSIGNED, IN_PROGRESS, COMPLETED, BLOCKED, CANCELLED)
+  - JSON serialization with sorted keys for git-friendly diffs
+  - Validation methods and constraints
+
+- [ ] **task_manager.py** - Task lifecycle management
+  - State transition validation with guard conditions
+  - Dependency graph operations (add, remove, validate)
+  - Cycle detection algorithms
+  - Task hierarchy navigation (parents, children, siblings)
+
+- [ ] **project_manager.py** - Project-level operations
+  - Project creation and initialization
+  - Task tree operations (get_task_tree, get_ready_tasks)
+  - Project statistics and health metrics
+  - Bulk operations on task collections
+
+#### Persistence Module (`amplifier/planner/persistence/`)
+- [ ] **storage.py** - File-based storage with defensive I/O
+  - ProjectStorage class with save/load operations
+  - Incremental task saves (critical for multi-agent coordination)
+  - Use `amplifier.ccsdk_toolkit.defensive` utilities for cloud sync resilience
+  - File structure: `projects/{project_id}/project.json`, `tasks/{task_id}.json`
+  - Assignment indexes for strategic queries
+
+- [ ] **git_sync.py** - Git integration for persistence
+  - GitPersistence class with auto-commit functionality
+  - Semantic commit messages from operation batches
+  - Recovery point creation and restoration
+  - Per-project repository management
+  - Conflict detection and resolution
+
+#### Foundation Tests
+- [ ] **test_models.py** - Data model validation
+  - Task creation, validation, serialization
+  - Project initialization and task association
+  - State transition validation (all valid/invalid combinations)
+  - Dependency cycle detection edge cases
+
+- [ ] **test_storage.py** - File persistence validation
+  - Save/load operations with various data scenarios
+  - Concurrent access simulation
+  - File corruption recovery
+  - Cloud sync error simulation (OneDrive/Dropbox issues)
+
+- [ ] **test_git_integration.py** - Git workflow validation
+  - Auto-commit functionality
+  - Recovery point creation/restoration
+  - Conflict resolution scenarios
+  - Multi-repository coordination
+
+### Phase 2: Intelligence (Session + Modes)
+**Priority**: P0 - Core AI functionality
+**Estimated Time**: 10-15 hours
+**Dependencies**: Phase 1 complete
+
+#### Session Module (`amplifier/planner/session/`)
+- [ ] **planner_session.py** - LLM integration wrapper
+  - PlannerSession class wrapping CCSDK SessionManager
+  - Task decomposition prompts and response parsing
+  - Strategic task analysis (complexity, tool requirements, human vs AI)
+  - Integration with `parse_llm_json` for reliable response handling
+  - Retry logic with `retry_with_feedback` for API failures
+
+#### Modes Module (`amplifier/planner/modes/`)
+- [ ] **base.py** - Mode interface and switching logic
+  - PlannerMode abstract base class
+  - Mode switching protocols (planning ↔ working)
+  - Context preservation across mode changes
+  - State validation for mode transitions
+
+- [ ] **planning.py** - AI-driven task decomposition
+  - PlanningMode implementation with recursive breakdown
+  - LLM prompts for project analysis and task creation
+  - Task depth limits and complexity assessment
+  - Integration with existing project structure
+  - Incremental saves after each decomposition
+
+- [ ] **working.py** - Strategic execution mode
+  - WorkingMode implementation with agent coordination
+  - Ready task identification (satisfied dependencies)
+  - Agent capability matching and task assignment
+  - Progress monitoring and state updates
+  - New task scheduling as work completes
+
+#### Intelligence Tests
+- [ ] **test_session.py** - LLM integration validation
+  - Mock LLM responses for deterministic testing
+  - Error handling for API failures, timeouts, rate limits
+  - Response parsing validation (malformed JSON, unexpected formats)
+  - Retry logic verification
+
+- [ ] **test_modes.py** - Mode operation validation
+  - Planning mode task decomposition scenarios
+  - Working mode task assignment logic
+  - Mode switching with state preservation
+  - Error recovery during mode operations
+
+### Phase 3: Coordination (Orchestrator)
+**Priority**: P0 - Multi-agent capability
+**Estimated Time**: 12-18 hours
+**Dependencies**: Phase 2 complete
+
+#### Orchestrator Module (`amplifier/planner/orchestrator/`)
+- [ ] **coordinator.py** - Agent spawning and lifecycle management
+  - AgentCoordinator class for managing multiple amplifier agents
+  - Integration with amplifier's Task tool for agent spawning
+  - Agent status tracking (starting, running, completed, failed)
+  - Resource management (concurrent agent limits)
+  - Agent cleanup and failure recovery
+
+- [ ] **task_assigner.py** - Strategic task assignment
+  - TaskAssigner class for intelligent task matching
+  - Task analysis (complexity, required tools, urgency)
+  - Agent capability matching and load balancing
+  - Priority-based scheduling algorithms
+  - Dependency-aware assignment ordering
+
+#### API and CLI Integration
+- [ ] **__init__.py** - Public API contracts ("studs")
+  - Main entry points: `create_planner()`, `load_planner()`
+  - Public classes: Task, Project, PlannerMode, etc.
+  - Integration protocols for other amplifier modules
+  - Version management and backward compatibility
+
+- [ ] **cli.py** - Command-line interface
+  - Make command integration (`planner-create`, `planner-plan`, `planner-work`)
+  - Project management commands (create, list, delete)
+  - Task operations (show, assign, complete)
+  - Agent coordination commands (spawn, monitor, cleanup)
+
+#### Coordination Tests
+- [ ] **test_orchestrator.py** - Multi-agent coordination
+  - Agent spawning with real Task tool integration
+  - Concurrent task execution simulation
+  - Resource contention and load balancing
+  - Agent failure recovery scenarios
+
+- [ ] **test_integration.py** - Full system integration
+  - End-to-end workflows with real LLM calls
+  - Multi-agent project execution
+  - Git operations under concurrent load
+  - Performance validation at scale
+
+### Phase 4: Golden Test Suite Implementation
+**Priority**: P1 - Quality assurance
+**Estimated Time**: 6-10 hours
+**Dependencies**: Phase 3 complete
+
+#### Golden Test Data
+- [ ] **fixtures/simple_web_app.json** - Basic workflow validation
+  - 8-task Django blog project
+  - 2-3 levels of task hierarchy
+  - Expected completion in ~2 hours with 2-3 agents
+
+- [ ] **fixtures/complex_microservices.json** - Multi-agent coordination
+  - 22-task e-commerce platform
+  - 4-5 levels of task hierarchy
+  - Expected completion in ~1 week with 8-10 agents
+
+- [ ] **fixtures/enterprise_migration.json** - Scale validation
+  - 500-1000 tasks legacy system migration
+  - 5+ levels of task hierarchy
+  - Expected completion in ~3 months with 15-20 agents
+
+#### Integration Test Scenarios
+- [ ] **test_golden_workflows.py** - Complete workflow validation
+  - Simple project end-to-end execution
+  - Complex project multi-agent coordination
+  - Enterprise project scale testing
+  - Performance benchmark validation
+
+- [ ] **test_failure_scenarios.py** - Reliability validation
+  - Network partition during agent coordination
+  - File corruption and recovery
+  - Agent crashes mid-execution
+  - Git conflicts during concurrent updates
+  - LLM API failures and recovery
+
+### Phase 5: Documentation and Deployment
+**Priority**: P2 - Production readiness
+**Estimated Time**: 4-6 hours
+**Dependencies**: Phase 4 complete
+
+#### Documentation
+- [ ] **README.md** - Main module documentation
+  - Quick start guide and usage examples
+  - Architecture overview and philosophy
+  - API reference and integration points
+  - Troubleshooting and FAQ
+
+- [ ] **CONTRACTS.md** - API contract specifications
+  - Public API stability guarantees
+  - Integration protocols documentation
+  - Extension points for customization
+  - Version management strategy
+
+#### Production Integration
+- [ ] **Makefile integration** - Add planner commands to main Makefile
+  - `make planner-create PROJECT="name"` - Create new project
+  - `make planner-plan PROJECT_ID="uuid"` - Run planning mode
+  - `make planner-work PROJECT_ID="uuid"` - Run working mode
+  - `make planner-status PROJECT_ID="uuid"` - Show project status
+
+- [ ] **VSCode integration** - Workspace configuration
+  - Exclude planner data files from search
+  - Git integration for planner repositories
+  - Task highlighting and navigation
+
+## Current Status
+
+**Completed Design Work:**
+- ✅ Complete architecture design with all module specifications
+- ✅ Comprehensive data model design with file structure
+- ✅ Coordination protocols for multi-agent workflow
+- ✅ Sub-agent spawning mechanisms via Task tool
+- ✅ Git integration and persistence strategy
+- ✅ Golden test specifications (28 scenarios)
+- ✅ API contracts and integration points
+
+**Ready to Begin Implementation:**
+- Phase 1 specifications are complete and detailed
+- Test requirements are clearly defined
+- Integration points with existing amplifier code are mapped
+- File structure and data formats are specified
+- Git workflow is designed and validated
+
+**Implementation Priority:**
+1. Start with Phase 1 (Foundation) - most critical for system stability
+2. Implement golden tests alongside each module for validation
+3. Use existing amplifier patterns (ccsdk_toolkit, defensive utilities)
+4. Follow "bricks and studs" philosophy - stable contracts, regenerable internals
+
+## Key Implementation Notes
+
+### Critical Integration Points
+- **CCSDK Toolkit**: Use `SessionManager`, `parse_llm_json`, `retry_with_feedback`
+- **Defensive File I/O**: Handle OneDrive/cloud sync issues with retry patterns
+- **Task Tool**: Agent spawning via `Task(subagent_type="...", prompt="...")`
+- **Git Workflow**: Auto-commit with semantic messages, recovery points
+
+### Performance Considerations
+- **Incremental saves**: Save after every task state change
+- **Selective loading**: Only load tasks needed for current operation
+- **Batch operations**: Group related changes into single git commits
+- **Caching**: Task data caching with file modification time checks
+
+### Error Handling Patterns
+- **Optimistic locking**: Version numbers prevent concurrent modification conflicts
+- **Retry with backoff**: File I/O, LLM API calls, git operations
+- **Circuit breakers**: Graceful degradation when components fail
+- **Recovery points**: Git tags for rollback capability
+
+### Testing Strategy
+- **Test-first development**: Implement golden tests before each module
+- **Real integration**: Use actual Task tool, LLM APIs, git operations
+- **Failure simulation**: Network issues, file corruption, agent crashes
+- **Performance validation**: Scale testing with 1000+ tasks, 20 agents
+
+This working plan captures the complete context needed to implement the Super-Planner system. Future sessions can pick up from any phase and understand the full scope, design decisions, and implementation requirements.
\ No newline at end of file
diff --git a/data/planner/projects/demo.json b/data/planner/projects/demo.json
new file mode 100644
index 00000000..e08f351c
--- /dev/null
+++ b/data/planner/projects/demo.json
@@ -0,0 +1,67 @@
+{
+  "id": "demo",
+  "name": "Demo Project",
+  "created_at": "2025-10-07T10:21:31.319518",
+  "updated_at": "2025-10-07T10:21:31.319800",
+  "tasks": {
+    "epic1": {
+      "id": "epic1",
+      "title": "Build Authentication",
+      "description": "Complete auth system",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T10:21:31.319543",
+      "updated_at": "2025-10-07T10:21:31.319545"
+    },
+    "epic2": {
+      "id": "epic2",
+      "title": "Build Dashboard",
+      "description": "User dashboard",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T10:21:31.319552",
+      "updated_at": "2025-10-07T10:21:31.319553"
+    },
+    "auth_design": {
+      "id": "auth_design",
+      "title": "Design Auth Flow",
+      "description": "",
+      "state": "completed",
+      "parent_id": "epic1",
+      "depends_on": [],
+      "assigned_to": "architect",
+      "created_at": "2025-10-07T10:21:31.319776",
+      "updated_at": "2025-10-07T10:21:31.319777"
+    },
+    "auth_impl": {
+      "id": "auth_impl",
+      "title": "Implement Auth",
+      "description": "",
+      "state": "in_progress",
+      "parent_id": "epic1",
+      "depends_on": [
+        "auth_design"
+      ],
+      "assigned_to": "backend-dev",
+      "created_at": "2025-10-07T10:21:31.319784",
+      "updated_at": "2025-10-07T10:21:31.319785"
+    },
+    "auth_test": {
+      "id": "auth_test",
+      "title": "Test Auth",
+      "description": "",
+      "state": "pending",
+      "parent_id": "epic1",
+      "depends_on": [
+        "auth_impl"
+      ],
+      "assigned_to": "qa",
+      "created_at": "2025-10-07T10:21:31.319791",
+      "updated_at": "2025-10-07T10:21:31.319791"
+    }
+  }
+}
\ No newline at end of file
diff --git a/data/planner/projects/django-blog.json b/data/planner/projects/django-blog.json
new file mode 100644
index 00000000..aec544c7
--- /dev/null
+++ b/data/planner/projects/django-blog.json
@@ -0,0 +1,113 @@
+{
+  "id": "django-blog",
+  "name": "Django Blog",
+  "created_at": "2025-10-07T14:50:03.068690",
+  "updated_at": "2025-10-07T14:50:03.068707",
+  "tasks": {
+    "setup": {
+      "id": "setup",
+      "title": "Project Setup",
+      "description": "Create Django project and configure settings",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T14:50:03.068695",
+      "updated_at": "2025-10-07T14:50:03.068695"
+    },
+    "models": {
+      "id": "models",
+      "title": "Database Models",
+      "description": "Create User, Post, Comment models",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "setup"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T14:50:03.068697",
+      "updated_at": "2025-10-07T14:50:03.068697"
+    },
+    "admin": {
+      "id": "admin",
+      "title": "Admin Interface",
+      "description": "Configure Django admin",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "models"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T14:50:03.068698",
+      "updated_at": "2025-10-07T14:50:03.068698"
+    },
+    "views": {
+      "id": "views",
+      "title": "Views",
+      "description": "Create list, detail, create views",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "models"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T14:50:03.068699",
+      "updated_at": "2025-10-07T14:50:03.068699"
+    },
+    "templates": {
+      "id": "templates",
+      "title": "Templates",
+      "description": "Design HTML templates",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "views"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T14:50:03.068700",
+      "updated_at": "2025-10-07T14:50:03.068700"
+    },
+    "urls": {
+      "id": "urls",
+      "title": "URL Configuration",
+      "description": "Set up routing",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "views"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T14:50:03.068701",
+      "updated_at": "2025-10-07T14:50:03.068701"
+    },
+    "tests": {
+      "id": "tests",
+      "title": "Tests",
+      "description": "Write unit tests",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "models",
+        "views"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T14:50:03.068701",
+      "updated_at": "2025-10-07T14:50:03.068702"
+    },
+    "deploy": {
+      "id": "deploy",
+      "title": "Deployment",
+      "description": "Deploy to production",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [
+        "templates",
+        "urls",
+        "tests"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T14:50:03.068702",
+      "updated_at": "2025-10-07T14:50:03.068702"
+    }
+  }
+}
\ No newline at end of file
diff --git a/data/planner/projects/persistence-test.json b/data/planner/projects/persistence-test.json
new file mode 100644
index 00000000..2a2adf67
--- /dev/null
+++ b/data/planner/projects/persistence-test.json
@@ -0,0 +1,32 @@
+{
+  "id": "persistence-test",
+  "name": "Persistence Test",
+  "created_at": "2025-10-07T14:50:03.016938",
+  "updated_at": "2025-10-07T14:50:03.016945",
+  "tasks": {
+    "t1": {
+      "id": "t1",
+      "title": "Task 1",
+      "description": "First task",
+      "state": "completed",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T14:50:03.016941",
+      "updated_at": "2025-10-07T14:50:03.016941"
+    },
+    "t2": {
+      "id": "t2",
+      "title": "Task 2",
+      "description": "",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "t1"
+      ],
+      "assigned_to": "test-user",
+      "created_at": "2025-10-07T14:50:03.016943",
+      "updated_at": "2025-10-07T14:50:03.016943"
+    }
+  }
+}
\ No newline at end of file
diff --git a/data/planner/projects/test_integration_project_20251007_121405.json b/data/planner/projects/test_integration_project_20251007_121405.json
new file mode 100644
index 00000000..fac787e0
--- /dev/null
+++ b/data/planner/projects/test_integration_project_20251007_121405.json
@@ -0,0 +1,19 @@
+{
+  "id": "test_integration_project_20251007_121405",
+  "name": "Test Integration Project",
+  "created_at": "2025-10-07T12:14:49.381472",
+  "updated_at": "2025-10-07T13:01:58.155560",
+  "tasks": {
+    "main-goal": {
+      "id": "main-goal",
+      "title": "Smart Task Decomposer CLI: Create scenarios/smart_decomposer/ - hybrid CLI tool that takes high-level goals and intelligently breaks them into specific, actionable tasks with agent assignment recommendations",
+      "description": "Main project goal: Smart Task Decomposer CLI: Create scenarios/smart_decomposer/ - hybrid CLI tool that takes high-level goals and intelligently breaks them into specific, actionable tasks with agent assignment recommendations",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T13:01:58.155556",
+      "updated_at": "2025-10-07T13:01:58.155558"
+    }
+  }
+}
\ No newline at end of file
diff --git a/data/planner/projects/vi-rewrite.json b/data/planner/projects/vi-rewrite.json
new file mode 100644
index 00000000..30a6d902
--- /dev/null
+++ b/data/planner/projects/vi-rewrite.json
@@ -0,0 +1,974 @@
+{
+  "id": "vi-rewrite",
+  "name": "Vi Editor Rewrite in Python",
+  "created_at": "2025-10-07T11:48:50.416993",
+  "updated_at": "2025-10-07T11:48:50.500513",
+  "tasks": {
+    "arch": {
+      "id": "arch",
+      "title": "Architecture & Design",
+      "description": "Define overall architecture, data structures, and interfaces",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.416994",
+      "updated_at": "2025-10-07T11:48:50.416994"
+    },
+    "core": {
+      "id": "core",
+      "title": "Core Editing Engine",
+      "description": "Text buffer management, cursor handling, basic operations",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "arch"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.416995",
+      "updated_at": "2025-10-07T11:48:50.416995"
+    },
+    "commands": {
+      "id": "commands",
+      "title": "Command System",
+      "description": "Vi command parsing, execution, and modal interface",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "arch"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.416996",
+      "updated_at": "2025-10-07T11:48:50.416996"
+    },
+    "ui": {
+      "id": "ui",
+      "title": "User Interface System",
+      "description": "Terminal handling, screen rendering, input processing",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "arch"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.416997",
+      "updated_at": "2025-10-07T11:48:50.416997"
+    },
+    "filesystem": {
+      "id": "filesystem",
+      "title": "File Operations",
+      "description": "File I/O, backup, recovery, file type detection",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "arch"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.416997",
+      "updated_at": "2025-10-07T11:48:50.416997"
+    },
+    "arch-analysis": {
+      "id": "arch-analysis",
+      "title": "Requirements Analysis",
+      "description": "Analyze vi behavior, commands, edge cases",
+      "state": "pending",
+      "parent_id": "arch",
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.416998",
+      "updated_at": "2025-10-07T11:48:50.416998"
+    },
+    "arch-design": {
+      "id": "arch-design",
+      "title": "System Design",
+      "description": "Design core data structures and interfaces",
+      "state": "pending",
+      "parent_id": "arch",
+      "depends_on": [
+        "arch-analysis"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.416999",
+      "updated_at": "2025-10-07T11:48:50.416999"
+    },
+    "arch-patterns": {
+      "id": "arch-patterns",
+      "title": "Design Patterns",
+      "description": "Define patterns for extensibility",
+      "state": "pending",
+      "parent_id": "arch",
+      "depends_on": [
+        "arch-design"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417000",
+      "updated_at": "2025-10-07T11:48:50.417000"
+    },
+    "arch-docs": {
+      "id": "arch-docs",
+      "title": "Architecture Documentation",
+      "description": "Document architecture decisions",
+      "state": "pending",
+      "parent_id": "arch",
+      "depends_on": [
+        "arch-patterns"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417001",
+      "updated_at": "2025-10-07T11:48:50.417001"
+    },
+    "core-buffer": {
+      "id": "core-buffer",
+      "title": "Text Buffer",
+      "description": "Efficient text storage with undo/redo",
+      "state": "pending",
+      "parent_id": "core",
+      "depends_on": [
+        "core"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417001",
+      "updated_at": "2025-10-07T11:48:50.417001"
+    },
+    "core-cursor": {
+      "id": "core-cursor",
+      "title": "Cursor Management",
+      "description": "Cursor positioning, movement, selection",
+      "state": "pending",
+      "parent_id": "core",
+      "depends_on": [
+        "core-buffer"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417002",
+      "updated_at": "2025-10-07T11:48:50.417002"
+    },
+    "core-operations": {
+      "id": "core-operations",
+      "title": "Basic Operations",
+      "description": "Insert, delete, replace operations",
+      "state": "pending",
+      "parent_id": "core",
+      "depends_on": [
+        "core-cursor"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417004",
+      "updated_at": "2025-10-07T11:48:50.417004"
+    },
+    "core-marks": {
+      "id": "core-marks",
+      "title": "Marks and Registers",
+      "description": "Named marks, registers, clipboard",
+      "state": "pending",
+      "parent_id": "core",
+      "depends_on": [
+        "core-operations"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417005",
+      "updated_at": "2025-10-07T11:48:50.417005"
+    },
+    "core-search": {
+      "id": "core-search",
+      "title": "Search Engine",
+      "description": "Pattern matching, regex, search/replace",
+      "state": "pending",
+      "parent_id": "core",
+      "depends_on": [
+        "core-operations"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417005",
+      "updated_at": "2025-10-07T11:48:50.417005"
+    },
+    "buffer-gap": {
+      "id": "buffer-gap",
+      "title": "Gap Buffer Implementation",
+      "description": "Efficient gap buffer with automatic expansion",
+      "state": "pending",
+      "parent_id": "core-buffer",
+      "depends_on": [
+        "core-buffer"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417006",
+      "updated_at": "2025-10-07T11:48:50.417006"
+    },
+    "buffer-lines": {
+      "id": "buffer-lines",
+      "title": "Line Management",
+      "description": "Line indexing, wrapping, virtual lines",
+      "state": "pending",
+      "parent_id": "core-buffer",
+      "depends_on": [
+        "buffer-gap"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417007",
+      "updated_at": "2025-10-07T11:48:50.417007"
+    },
+    "buffer-encoding": {
+      "id": "buffer-encoding",
+      "title": "Text Encoding",
+      "description": "UTF-8, line endings, BOM handling",
+      "state": "pending",
+      "parent_id": "core-buffer",
+      "depends_on": [
+        "buffer-lines"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417007",
+      "updated_at": "2025-10-07T11:48:50.417007"
+    },
+    "buffer-undo": {
+      "id": "buffer-undo",
+      "title": "Undo System",
+      "description": "Efficient undo/redo with branching",
+      "state": "pending",
+      "parent_id": "core-buffer",
+      "depends_on": [
+        "buffer-encoding"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417008",
+      "updated_at": "2025-10-07T11:48:50.417008"
+    },
+    "buffer-diff": {
+      "id": "buffer-diff",
+      "title": "Change Tracking",
+      "description": "Track changes for diff, backup",
+      "state": "pending",
+      "parent_id": "core-buffer",
+      "depends_on": [
+        "buffer-undo"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417008",
+      "updated_at": "2025-10-07T11:48:50.417008"
+    },
+    "cmd-parser": {
+      "id": "cmd-parser",
+      "title": "Command Parser",
+      "description": "Parse vi commands with error handling",
+      "state": "pending",
+      "parent_id": "commands",
+      "depends_on": [
+        "commands"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417009",
+      "updated_at": "2025-10-07T11:48:50.417009"
+    },
+    "cmd-modes": {
+      "id": "cmd-modes",
+      "title": "Modal Interface",
+      "description": "Normal, insert, visual, command modes",
+      "state": "pending",
+      "parent_id": "commands",
+      "depends_on": [
+        "cmd-parser"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417009",
+      "updated_at": "2025-10-07T11:48:50.417009"
+    },
+    "cmd-movement": {
+      "id": "cmd-movement",
+      "title": "Movement Commands",
+      "description": "h,j,k,l, w,e,b, $,^, G, etc.",
+      "state": "pending",
+      "parent_id": "commands",
+      "depends_on": [
+        "cmd-modes"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417010",
+      "updated_at": "2025-10-07T11:48:50.417010"
+    },
+    "cmd-editing": {
+      "id": "cmd-editing",
+      "title": "Editing Commands",
+      "description": "i,a,o, d,c,y, p, u, ., etc.",
+      "state": "pending",
+      "parent_id": "commands",
+      "depends_on": [
+        "cmd-movement"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417010",
+      "updated_at": "2025-10-07T11:48:50.417011"
+    },
+    "cmd-visual": {
+      "id": "cmd-visual",
+      "title": "Visual Mode",
+      "description": "Visual selection, visual block",
+      "state": "pending",
+      "parent_id": "commands",
+      "depends_on": [
+        "cmd-editing"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417011",
+      "updated_at": "2025-10-07T11:48:50.417011"
+    },
+    "cmd-ex": {
+      "id": "cmd-ex",
+      "title": "Ex Commands",
+      "description": ":w, :q, :s, :!, etc.",
+      "state": "pending",
+      "parent_id": "commands",
+      "depends_on": [
+        "cmd-visual"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417012",
+      "updated_at": "2025-10-07T11:48:50.417012"
+    },
+    "move-char": {
+      "id": "move-char",
+      "title": "Character Movement",
+      "description": "h,l,space,backspace movement",
+      "state": "pending",
+      "parent_id": "cmd-movement",
+      "depends_on": [
+        "cmd-movement"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417012",
+      "updated_at": "2025-10-07T11:48:50.417012"
+    },
+    "move-word": {
+      "id": "move-word",
+      "title": "Word Movement",
+      "description": "w,e,b,W,E,B word boundaries",
+      "state": "pending",
+      "parent_id": "cmd-movement",
+      "depends_on": [
+        "move-char"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417013",
+      "updated_at": "2025-10-07T11:48:50.417013"
+    },
+    "move-line": {
+      "id": "move-line",
+      "title": "Line Movement",
+      "description": "j,k,$,^,0,+,- movements",
+      "state": "pending",
+      "parent_id": "cmd-movement",
+      "depends_on": [
+        "move-word"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417013",
+      "updated_at": "2025-10-07T11:48:50.417013"
+    },
+    "move-search": {
+      "id": "move-search",
+      "title": "Search Movement",
+      "description": "f,F,t,T,;,, and /,? searches",
+      "state": "pending",
+      "parent_id": "cmd-movement",
+      "depends_on": [
+        "move-line"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417014",
+      "updated_at": "2025-10-07T11:48:50.417014"
+    },
+    "move-jump": {
+      "id": "move-jump",
+      "title": "Jump Commands",
+      "description": "G,gg,H,M,L,ctrl-f,ctrl-b",
+      "state": "pending",
+      "parent_id": "cmd-movement",
+      "depends_on": [
+        "move-search"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417014",
+      "updated_at": "2025-10-07T11:48:50.417015"
+    },
+    "ui-terminal": {
+      "id": "ui-terminal",
+      "title": "Terminal Interface",
+      "description": "Raw terminal control, escape sequences",
+      "state": "pending",
+      "parent_id": "ui",
+      "depends_on": [
+        "ui"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417015",
+      "updated_at": "2025-10-07T11:48:50.417015"
+    },
+    "ui-screen": {
+      "id": "ui-screen",
+      "title": "Screen Management",
+      "description": "Screen buffer, scrolling, refresh",
+      "state": "pending",
+      "parent_id": "ui",
+      "depends_on": [
+        "ui-terminal"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417015",
+      "updated_at": "2025-10-07T11:48:50.417016"
+    },
+    "ui-input": {
+      "id": "ui-input",
+      "title": "Input Processing",
+      "description": "Key mapping, special keys, timing",
+      "state": "pending",
+      "parent_id": "ui",
+      "depends_on": [
+        "ui-screen"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417016",
+      "updated_at": "2025-10-07T11:48:50.417016"
+    },
+    "ui-rendering": {
+      "id": "ui-rendering",
+      "title": "Text Rendering",
+      "description": "Syntax highlighting, line numbers",
+      "state": "pending",
+      "parent_id": "ui",
+      "depends_on": [
+        "ui-input"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417017",
+      "updated_at": "2025-10-07T11:48:50.417017"
+    },
+    "ui-status": {
+      "id": "ui-status",
+      "title": "Status Line",
+      "description": "Mode indicator, position, filename",
+      "state": "pending",
+      "parent_id": "ui",
+      "depends_on": [
+        "ui-rendering"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417017",
+      "updated_at": "2025-10-07T11:48:50.417017"
+    },
+    "file-io": {
+      "id": "file-io",
+      "title": "Basic File I/O",
+      "description": "Read/write files, error handling",
+      "state": "pending",
+      "parent_id": "filesystem",
+      "depends_on": [
+        "filesystem"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417018",
+      "updated_at": "2025-10-07T11:48:50.417018"
+    },
+    "file-backup": {
+      "id": "file-backup",
+      "title": "Backup System",
+      "description": "Swap files, backup files, recovery",
+      "state": "pending",
+      "parent_id": "filesystem",
+      "depends_on": [
+        "file-io"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417018",
+      "updated_at": "2025-10-07T11:48:50.417018"
+    },
+    "file-detection": {
+      "id": "file-detection",
+      "title": "File Type Detection",
+      "description": "Syntax detection, file associations",
+      "state": "pending",
+      "parent_id": "filesystem",
+      "depends_on": [
+        "file-backup"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417019",
+      "updated_at": "2025-10-07T11:48:50.417019"
+    },
+    "file-encoding": {
+      "id": "file-encoding",
+      "title": "Encoding Detection",
+      "description": "Auto-detect and handle encodings",
+      "state": "pending",
+      "parent_id": "filesystem",
+      "depends_on": [
+        "file-detection"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417019",
+      "updated_at": "2025-10-07T11:48:50.417020"
+    },
+    "integration-basic": {
+      "id": "integration-basic",
+      "title": "Basic Integration",
+      "description": "Integrate core editing with UI",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "core-operations",
+        "cmd-editing",
+        "ui-screen"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417020",
+      "updated_at": "2025-10-07T11:48:50.417020"
+    },
+    "integration-advanced": {
+      "id": "integration-advanced",
+      "title": "Advanced Integration",
+      "description": "Integrate search, ex commands",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "integration-basic",
+        "core-search",
+        "cmd-ex"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417021",
+      "updated_at": "2025-10-07T11:48:50.417021"
+    },
+    "integration-files": {
+      "id": "integration-files",
+      "title": "File Integration",
+      "description": "Integrate file operations",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "integration-advanced",
+        "file-encoding"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417022",
+      "updated_at": "2025-10-07T11:48:50.417022"
+    },
+    "test-unit": {
+      "id": "test-unit",
+      "title": "Unit Tests",
+      "description": "Unit tests for all components",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "buffer-diff",
+        "move-jump",
+        "ui-status"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417022",
+      "updated_at": "2025-10-07T11:48:50.417022"
+    },
+    "test-integration": {
+      "id": "test-integration",
+      "title": "Integration Tests",
+      "description": "Integration tests across components",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "test-unit",
+        "integration-files"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417023",
+      "updated_at": "2025-10-07T11:48:50.417023"
+    },
+    "test-compatibility": {
+      "id": "test-compatibility",
+      "title": "Vi Compatibility Tests",
+      "description": "Test compatibility with real vi",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "test-integration"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417023",
+      "updated_at": "2025-10-07T11:48:50.417023"
+    },
+    "test-performance": {
+      "id": "test-performance",
+      "title": "Performance Tests",
+      "description": "Large file performance, memory usage",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "test-compatibility"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417024",
+      "updated_at": "2025-10-07T11:48:50.417024"
+    },
+    "test-edge-cases": {
+      "id": "test-edge-cases",
+      "title": "Edge Case Tests",
+      "description": "Binary files, huge files, corner cases",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "test-performance"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417024",
+      "updated_at": "2025-10-07T11:48:50.417026"
+    },
+    "polish-docs": {
+      "id": "polish-docs",
+      "title": "Documentation",
+      "description": "User manual, developer docs",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "test-edge-cases"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417026",
+      "updated_at": "2025-10-07T11:48:50.417026"
+    },
+    "polish-package": {
+      "id": "polish-package",
+      "title": "Packaging",
+      "description": "Setup.py, distribution, installation",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "polish-docs"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417027",
+      "updated_at": "2025-10-07T11:48:50.417027"
+    },
+    "polish-ci": {
+      "id": "polish-ci",
+      "title": "CI/CD Setup",
+      "description": "GitHub actions, automated testing",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "polish-package"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417027",
+      "updated_at": "2025-10-07T11:48:50.417028"
+    },
+    "release-beta": {
+      "id": "release-beta",
+      "title": "Beta Release",
+      "description": "Initial beta release",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "polish-ci"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417028",
+      "updated_at": "2025-10-07T11:48:50.417028"
+    },
+    "release-stable": {
+      "id": "release-stable",
+      "title": "Stable Release",
+      "description": "1.0 stable release",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "release-beta"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.417029",
+      "updated_at": "2025-10-07T11:48:50.417029"
+    },
+    "stress-00": {
+      "id": "stress-00",
+      "title": "Stress Test Task 0",
+      "description": "Random stress test task with 1 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "buffer-lines"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418835",
+      "updated_at": "2025-10-07T11:48:50.418837"
+    },
+    "stress-01": {
+      "id": "stress-01",
+      "title": "Stress Test Task 1",
+      "description": "Random stress test task with 2 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "buffer-diff",
+        "arch-design"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418894",
+      "updated_at": "2025-10-07T11:48:50.418894"
+    },
+    "stress-02": {
+      "id": "stress-02",
+      "title": "Stress Test Task 2",
+      "description": "Random stress test task with 2 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "buffer-gap",
+        "cmd-ex"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418899",
+      "updated_at": "2025-10-07T11:48:50.418899"
+    },
+    "stress-03": {
+      "id": "stress-03",
+      "title": "Stress Test Task 3",
+      "description": "Random stress test task with 2 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "ui-rendering",
+        "core"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418903",
+      "updated_at": "2025-10-07T11:48:50.418903"
+    },
+    "stress-04": {
+      "id": "stress-04",
+      "title": "Stress Test Task 4",
+      "description": "Random stress test task with 0 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418905",
+      "updated_at": "2025-10-07T11:48:50.418905"
+    },
+    "stress-05": {
+      "id": "stress-05",
+      "title": "Stress Test Task 5",
+      "description": "Random stress test task with 2 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "cmd-movement",
+        "stress-04"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418908",
+      "updated_at": "2025-10-07T11:48:50.418908"
+    },
+    "stress-06": {
+      "id": "stress-06",
+      "title": "Stress Test Task 6",
+      "description": "Random stress test task with 3 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "polish-ci",
+        "filesystem",
+        "commands"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418910",
+      "updated_at": "2025-10-07T11:48:50.418910"
+    },
+    "stress-07": {
+      "id": "stress-07",
+      "title": "Stress Test Task 7",
+      "description": "Random stress test task with 3 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "stress-00",
+        "move-char",
+        "buffer-lines"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418913",
+      "updated_at": "2025-10-07T11:48:50.418913"
+    },
+    "stress-08": {
+      "id": "stress-08",
+      "title": "Stress Test Task 8",
+      "description": "Random stress test task with 1 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "cmd-editing"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418917",
+      "updated_at": "2025-10-07T11:48:50.418917"
+    },
+    "stress-09": {
+      "id": "stress-09",
+      "title": "Stress Test Task 9",
+      "description": "Random stress test task with 1 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "move-word"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418919",
+      "updated_at": "2025-10-07T11:48:50.418919"
+    },
+    "stress-10": {
+      "id": "stress-10",
+      "title": "Stress Test Task 10",
+      "description": "Random stress test task with 2 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "integration-basic",
+        "test-integration"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418922",
+      "updated_at": "2025-10-07T11:48:50.418922"
+    },
+    "stress-11": {
+      "id": "stress-11",
+      "title": "Stress Test Task 11",
+      "description": "Random stress test task with 1 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "ui"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418924",
+      "updated_at": "2025-10-07T11:48:50.418924"
+    },
+    "stress-12": {
+      "id": "stress-12",
+      "title": "Stress Test Task 12",
+      "description": "Random stress test task with 1 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "arch-docs"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418926",
+      "updated_at": "2025-10-07T11:48:50.418926"
+    },
+    "stress-13": {
+      "id": "stress-13",
+      "title": "Stress Test Task 13",
+      "description": "Random stress test task with 0 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418928",
+      "updated_at": "2025-10-07T11:48:50.418928"
+    },
+    "stress-14": {
+      "id": "stress-14",
+      "title": "Stress Test Task 14",
+      "description": "Random stress test task with 2 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "stress-05",
+        "buffer-undo"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418931",
+      "updated_at": "2025-10-07T11:48:50.418931"
+    },
+    "stress-15": {
+      "id": "stress-15",
+      "title": "Stress Test Task 15",
+      "description": "Random stress test task with 2 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "buffer-encoding",
+        "test-integration"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418933",
+      "updated_at": "2025-10-07T11:48:50.418933"
+    },
+    "stress-16": {
+      "id": "stress-16",
+      "title": "Stress Test Task 16",
+      "description": "Random stress test task with 2 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "integration-basic",
+        "core"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418936",
+      "updated_at": "2025-10-07T11:48:50.418936"
+    },
+    "stress-17": {
+      "id": "stress-17",
+      "title": "Stress Test Task 17",
+      "description": "Random stress test task with 0 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418937",
+      "updated_at": "2025-10-07T11:48:50.418937"
+    },
+    "stress-18": {
+      "id": "stress-18",
+      "title": "Stress Test Task 18",
+      "description": "Random stress test task with 0 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418940",
+      "updated_at": "2025-10-07T11:48:50.418941"
+    },
+    "stress-19": {
+      "id": "stress-19",
+      "title": "Stress Test Task 19",
+      "description": "Random stress test task with 1 dependencies",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [
+        "test-unit"
+      ],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.418943",
+      "updated_at": "2025-10-07T11:48:50.418943"
+    },
+    "extreme-data": {
+      "id": "extreme-data",
+      "title": "Task with extreme data",
+      "description": "Description with every Unicode character:  !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~",
+      "state": "pending",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": "user with 🔥émojis💻 and spëciål chars",
+      "created_at": "2025-10-07T11:48:50.419843",
+      "updated_at": "2025-10-07T11:48:50.419843"
+    },
+    "state-test": {
+      "id": "state-test",
+      "title": "State Transition Test",
+      "description": "",
+      "state": "blocked",
+      "parent_id": null,
+      "depends_on": [],
+      "assigned_to": null,
+      "created_at": "2025-10-07T11:48:50.500504",
+      "updated_at": "2025-10-07T11:48:50.500509"
+    }
+  }
+}
\ No newline at end of file
diff --git a/instructor/agents.html b/instructor/agents.html
new file mode 100644
index 00000000..a329aabe
--- /dev/null
+++ b/instructor/agents.html
@@ -0,0 +1,1458 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Agent Catalog - Amplifier</title>
+    <link rel="stylesheet" href="styles.css">
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+    <style>
+        /* New styles for expanded content */
+        .advanced-section {
+            margin-top: 1rem;
+            border-top: 1px solid var(--border-color);
+            padding-top: 1rem;
+        }
+        .advanced-section summary {
+            cursor: pointer;
+            color: var(--primary-color);
+            font-size: 0.95rem;
+            margin-bottom: 0.75rem;
+        }
+        .advanced-section summary:hover {
+            color: var(--accent-color);
+        }
+        .examples-container {
+            margin-top: 1rem;
+        }
+        .example-card {
+            background: var(--light-bg);
+            padding: 1rem;
+            border-radius: var(--border-radius);
+            margin-bottom: 1rem;
+        }
+        .example-card h5 {
+            color: var(--text-primary);
+            margin-bottom: 0.5rem;
+            font-size: 0.9rem;
+        }
+        .code-block {
+            position: relative;
+            background: #1e1e1e;
+            color: #d4d4d4;
+            padding: 0.75rem;
+            border-radius: 4px;
+            font-family: 'Consolas', 'Monaco', monospace;
+            font-size: 0.85rem;
+            margin: 0.5rem 0;
+        }
+        .code-block pre {
+            margin: 0;
+            white-space: pre-wrap;
+            word-break: break-word;
+        }
+        .copy-btn {
+            position: absolute;
+            top: 0.5rem;
+            right: 0.5rem;
+            background: var(--primary-color);
+            color: white;
+            border: none;
+            padding: 0.25rem 0.5rem;
+            border-radius: 4px;
+            cursor: pointer;
+            font-size: 0.75rem;
+            opacity: 0.7;
+            transition: opacity 0.2s;
+        }
+        .copy-btn:hover {
+            opacity: 1;
+        }
+        .copy-btn.copied {
+            background: var(--accent-color);
+        }
+        .example-output {
+            color: var(--text-secondary);
+            font-size: 0.85rem;
+            margin-top: 0.5rem;
+            font-style: italic;
+        }
+        .integration-list, .tips-list {
+            list-style: none;
+            padding: 0;
+            margin-top: 0.75rem;
+        }
+        .integration-list li, .tips-list li {
+            padding: 0.5rem 0;
+            border-bottom: 1px dotted var(--border-color);
+            color: var(--text-secondary);
+            font-size: 0.9rem;
+        }
+        .integration-list li:last-child, .tips-list li:last-child {
+            border-bottom: none;
+        }
+        .integration-list li strong {
+            color: var(--primary-color);
+        }
+        .workflow-example {
+            background: var(--light-bg);
+            padding: 1rem;
+            border-radius: var(--border-radius);
+            margin-top: 0.75rem;
+        }
+        .workflow-code {
+            background: white;
+            border: 1px solid var(--border-color);
+            padding: 1rem;
+            border-radius: 4px;
+            font-family: monospace;
+            font-size: 0.85rem;
+            line-height: 1.6;
+            white-space: pre-wrap;
+        }
+        /* Existing styles continue below */
+        .agent-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
+            gap: 2rem;
+            margin-bottom: 3rem;
+        }
+        .agent-card-detailed {
+            background: white;
+            border-radius: var(--border-radius-lg);
+            box-shadow: var(--shadow);
+            overflow: hidden;
+            transition: var(--transition);
+        }
+        .agent-card-detailed:hover {
+            transform: translateY(-4px);
+            box-shadow: var(--shadow-lg);
+        }
+        .agent-header {
+            background: linear-gradient(135deg, var(--primary-color), #0052a3);
+            color: var(--text-light);
+            padding: 1.5rem;
+        }
+        .agent-name {
+            font-size: 1.25rem;
+            font-weight: 600;
+            margin-bottom: 0.5rem;
+        }
+        .agent-category {
+            background: rgba(255, 255, 255, 0.2);
+            color: var(--text-light);
+            padding: 0.25rem 0.75rem;
+            border-radius: 1rem;
+            font-size: 0.75rem;
+            display: inline-block;
+        }
+        .agent-body {
+            padding: 1.5rem;
+        }
+        .agent-description {
+            color: var(--text-secondary);
+            line-height: 1.6;
+            margin-bottom: 1.5rem;
+        }
+        .agent-features {
+            margin-bottom: 1.5rem;
+        }
+        .agent-features h4 {
+            color: var(--text-primary);
+            font-size: 0.9rem;
+            font-weight: 600;
+            margin-bottom: 0.5rem;
+            text-transform: uppercase;
+            letter-spacing: 0.5px;
+        }
+        .agent-features ul {
+            list-style: none;
+            padding: 0;
+        }
+        .agent-features li {
+            color: var(--text-secondary);
+            font-size: 0.9rem;
+            margin-bottom: 0.25rem;
+            position: relative;
+            padding-left: 1rem;
+        }
+        .agent-features li::before {
+            content: '✓';
+            position: absolute;
+            left: 0;
+            color: var(--accent-color);
+            font-weight: bold;
+        }
+        .example-usage {
+            background: var(--light-bg);
+            padding: 1rem;
+            border-radius: var(--border-radius);
+            font-family: monospace;
+            font-size: 0.85rem;
+            color: var(--primary-color);
+        }
+        .category-section {
+            margin-bottom: 4rem;
+        }
+        .category-title {
+            font-size: 2rem;
+            font-weight: 600;
+            color: var(--text-primary);
+            margin-bottom: 1rem;
+            padding-bottom: 0.5rem;
+            border-bottom: 2px solid var(--primary-color);
+        }
+        .category-description {
+            color: var(--text-secondary);
+            font-size: 1.1rem;
+            margin-bottom: 2rem;
+            line-height: 1.6;
+        }
+        .filter-tabs {
+            display: flex;
+            justify-content: center;
+            margin-bottom: 3rem;
+            flex-wrap: wrap;
+            gap: 0.5rem;
+        }
+        .filter-btn {
+            background: white;
+            border: 1px solid var(--border-color);
+            padding: 0.75rem 1.5rem;
+            border-radius: var(--border-radius);
+            cursor: pointer;
+            transition: var(--transition);
+            font-weight: 500;
+        }
+        .filter-btn.active,
+        .filter-btn:hover {
+            background: var(--primary-color);
+            color: var(--text-light);
+            border-color: var(--primary-color);
+        }
+    </style>
+</head>
+<body>
+    <header class="header">
+        <nav class="nav">
+            <div class="nav-brand">
+                <h1>Amplifier</h1>
+                <span class="tagline">Agent Catalog</span>
+            </div>
+            <div class="nav-links">
+                <a href="index.html" class="nav-link">Home</a>
+                <a href="setup.html" class="nav-link">Setup</a>
+                <a href="examples.html" class="nav-link">Examples</a>
+                <a href="knowledge.html" class="nav-link">Knowledge Base</a>
+                <a href="https://github.com/microsoft/amplifier" class="nav-link">GitHub</a>
+            </div>
+            <div class="nav-mobile">
+                <button class="mobile-menu-btn" onclick="toggleMobileMenu()">☰</button>
+            </div>
+        </nav>
+    </header>
+
+    <main style="padding-top: 6rem;">
+        <!-- Hero Section -->
+        <section class="section">
+            <div class="container">
+                <div class="text-center" style="text-align: center; margin-bottom: 3rem;">
+                    <h1 class="section-title">Specialized AI Agents</h1>
+                    <p style="font-size: 1.2rem; color: var(--text-secondary); max-width: 800px; margin: 0 auto;">
+                        Instead of one generalist AI, Amplifier provides 20+ specialized agents, each expert in specific domains.
+                        Each agent brings focused expertise, proven patterns, and domain-specific knowledge to accelerate your development.
+                    </p>
+                </div>
+
+                <!-- Filter Tabs -->
+                <div class="filter-tabs">
+                    <button class="filter-btn active" onclick="filterAgents('all', this)">All Agents</button>
+                    <button class="filter-btn" onclick="filterAgents('development', this)">Development</button>
+                    <button class="filter-btn" onclick="filterAgents('analysis', this)">Analysis & Optimization</button>
+                    <button class="filter-btn" onclick="filterAgents('knowledge', this)">Knowledge & Insights</button>
+                    <button class="filter-btn" onclick="filterAgents('meta', this)">Meta & Support</button>
+                </div>
+
+                <!-- Core Development Agents -->
+                <div class="category-section" data-category="development">
+                    <h2 class="category-title">🏗️ Core Development</h2>
+                    <p class="category-description">
+                        Agents focused on building, architecting, and maintaining code with best practices and proven patterns.
+                    </p>
+                    <div class="agent-grid">
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">zen-architect</div>
+                                <span class="agent-category">Architecture</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The master architect who embodies ruthless simplicity and Wabi-sabi philosophy. Operates in three powerful modes:
+                                    <strong>ANALYZE</strong> for problem decomposition, <strong>ARCHITECT</strong> for system design, and <strong>REVIEW</strong> for code quality assessment.
+                                    Creates clear specifications that guide implementation, focusing on essential patterns over unnecessary abstractions.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>Analysis-first development approach</li>
+                                        <li>Modular "bricks & studs" architecture</li>
+                                        <li>Clean contract specifications</li>
+                                        <li>Complexity elimination strategies</li>
+                                        <li>80/20 principle application</li>
+                                        <li>Philosophy compliance review</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples (click to expand)</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: Design a New Feature</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Use zen-architect to design a user notification system"</pre>
+                                            </div>
+                                            <p class="example-output">→ Returns: Problem analysis, 3 solution approaches with trade-offs, modular specification</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Architecture Review</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Have zen-architect review the auth module for complexity and suggest simplifications"</pre>
+                                            </div>
+                                            <p class="example-output">→ Returns: Complexity score, philosophy alignment, specific refactoring recommendations</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: System Redesign</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"zen-architect: Analyze our monolithic app and design a modular migration strategy with clear boundaries"</pre>
+                                            </div>
+                                            <p class="example-output">→ Returns: Module boundaries, migration phases, contract specifications, dependency graph</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>🤝 Works Best With</strong></summary>
+                                    <ul class="integration-list">
+                                        <li><strong>modular-builder:</strong> Implements zen-architect's specifications</li>
+                                        <li><strong>bug-hunter:</strong> Validates architectural decisions work correctly</li>
+                                        <li><strong>api-contract-designer:</strong> Detailed API design after system architecture</li>
+                                    </ul>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>💡 Pro Tips</strong></summary>
+                                    <ul class="tips-list">
+                                        <li>Always let zen-architect analyze before implementing</li>
+                                        <li>Request REVIEW mode for existing code assessment</li>
+                                        <li>Use for "stuck" moments - finds simpler paths</li>
+                                        <li>Specifications can be regenerated if requirements change</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">modular-builder</div>
+                                <span class="agent-category">Implementation</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The implementation specialist that builds from specifications with precision. Creates self-contained modules with clear boundaries,
+                                    automated testing, and regeneration-ready code. Follows the "bricks & studs" philosophy where each module is a complete, replaceable unit.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>Contract-first implementation</li>
+                                        <li>Self-contained module creation</li>
+                                        <li>Automated conformance testing</li>
+                                        <li>Public/private interface separation</li>
+                                        <li>Regeneration-friendly structure</li>
+                                        <li>Test-driven development</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: Build from Spec</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"modular-builder: Implement the user authentication module from zen-architect's spec"</pre>
+                                            </div>
+                                            <p class="example-output">→ Creates: Module structure, public API, tests, documentation</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Parallel Variants</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Use modular-builder to create two cache implementations: Redis-based and in-memory"</pre>
+                                            </div>
+                                            <p class="example-output">→ Creates: Two parallel modules with same contract, different implementations</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: Full Workflow</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"modular-builder: Build the payment processing module with Stripe integration, including retry logic, webhook handling, and comprehensive tests"</pre>
+                                            </div>
+                                            <p class="example-output">→ Creates: Complete module with external integration, error handling, tests, fixtures</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>🤝 Integration Workflow</strong></summary>
+                                    <div class="workflow-example">
+                                        <p><strong>Complete Development Flow:</strong></p>
+                                        <pre class="workflow-code">1. zen-architect analyzes and creates spec
+2. modular-builder implements from spec
+3. test-coverage verifies edge cases
+4. bug-hunter validates implementation
+5. post-task-cleanup ensures hygiene</pre>
+                                    </div>
+                                </details>
+                            </div>
+                        </div>
+
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">bug-hunter</div>
+                                <span class="agent-category">Debugging</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The systematic debugger that finds root causes, not just symptoms. Uses pattern recognition, binary search debugging,
+                                    and proven methodologies. Tracks down race conditions, memory leaks, and those "impossible" bugs that only happen in production.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>5-why root cause analysis</li>
+                                        <li>Pattern-based bug detection</li>
+                                        <li>Binary search debugging</li>
+                                        <li>Race condition identification</li>
+                                        <li>Memory leak detection</li>
+                                        <li>Production issue diagnosis</li>
+                                        <li>Fix verification strategies</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: API Failure</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"bug-hunter: Find why POST /api/users returns 500 errors intermittently"</pre>
+                                            </div>
+                                            <p class="example-output">→ Analyzes: Request patterns, error logs, database state, identifies root cause</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Performance Issue</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Use bug-hunter to diagnose why the app slows down after 2 hours of runtime"</pre>
+                                            </div>
+                                            <p class="example-output">→ Investigates: Memory patterns, connection pools, cache behavior, finds leak</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: Race Condition</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"bug-hunter: Users report duplicate charges but we can't reproduce it locally"</pre>
+                                            </div>
+                                            <p class="example-output">→ Deploys: Timing analysis, transaction logs, identifies race window, provides fix</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>⚠️ When to Use</strong></summary>
+                                    <ul class="tips-list">
+                                        <li>Intermittent failures that are hard to reproduce</li>
+                                        <li>Performance degradation over time</li>
+                                        <li>"Works on my machine" problems</li>
+                                        <li>After deployment when issues surface</li>
+                                        <li>Complex multi-component failures</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">test-coverage</div>
+                                <span class="agent-category">Testing</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The testing strategist that thinks like a hacker, user, and maintainer simultaneously. Identifies edge cases others miss,
+                                    builds comprehensive test pyramids (60% unit, 30% integration, 10% E2E), and ensures your code handles the unexpected gracefully.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>Test pyramid strategy (60/30/10)</li>
+                                        <li>Edge case discovery</li>
+                                        <li>Mutation testing insights</li>
+                                        <li>Property-based test generation</li>
+                                        <li>Coverage gap analysis</li>
+                                        <li>Test fixture creation</li>
+                                        <li>Performance test design</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: Add Missing Tests</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"test-coverage: Add comprehensive tests for the UserService class"</pre>
+                                            </div>
+                                            <p class="example-output">→ Creates: Unit tests, edge cases, mocks, fixtures, 90%+ coverage</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Integration Testing</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Have test-coverage design integration tests for our payment flow with Stripe"</pre>
+                                            </div>
+                                            <p class="example-output">→ Creates: API mocks, webhook tests, error scenarios, retry logic tests</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: Chaos Engineering</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"test-coverage: Create resilience tests simulating network failures, timeouts, and data corruption"</pre>
+                                            </div>
+                                            <p class="example-output">→ Creates: Failure injection tests, recovery verification, monitoring checks</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>🎯 Edge Cases to Test</strong></summary>
+                                    <ul class="tips-list">
+                                        <li>Null, undefined, empty inputs</li>
+                                        <li>Boundary values (0, -1, MAX_INT)</li>
+                                        <li>Concurrent access scenarios</li>
+                                        <li>Network timeouts and retries</li>
+                                        <li>Malformed data handling</li>
+                                        <li>Permission and auth failures</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">api-contract-designer</div>
+                                <span class="agent-category">API Design</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The API architect who designs contracts developers love. Creates consistent, intuitive APIs with proper versioning,
+                                    comprehensive error handling, and evolution strategies. Follows REST principles while pragmatically breaking them when it makes sense.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>RESTful design principles</li>
+                                        <li>OpenAPI/Swagger specifications</li>
+                                        <li>Semantic versioning strategies</li>
+                                        <li>Idempotency patterns</li>
+                                        <li>Rate limiting design</li>
+                                        <li>Error response standards</li>
+                                        <li>HATEOAS when appropriate</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: CRUD Endpoints</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"api-contract-designer: Design REST endpoints for user management"</pre>
+                                            </div>
+                                            <p class="example-output">→ Returns: OpenAPI spec, endpoints, status codes, request/response schemas</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Webhook System</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Use api-contract-designer to create webhook contracts with retry and verification"</pre>
+                                            </div>
+                                            <p class="example-output">→ Returns: Webhook payload specs, HMAC verification, retry policies, event types</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: API Evolution</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"api-contract-designer: Migrate v1 API to v2 with backward compatibility and deprecation strategy"</pre>
+                                            </div>
+                                            <p class="example-output">→ Returns: Migration path, compatibility layer, deprecation timeline, client upgrade guide</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>✅ API Best Practices</strong></summary>
+                                    <ul class="tips-list">
+                                        <li>Use consistent naming (camelCase or snake_case)</li>
+                                        <li>Version via URL path (/v1/) or headers</li>
+                                        <li>Return proper HTTP status codes</li>
+                                        <li>Include request IDs for tracing</li>
+                                        <li>Implement pagination for lists</li>
+                                        <li>Use ISO 8601 for dates</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Analysis & Optimization Agents -->
+                <div class="category-section" data-category="analysis">
+                    <h2 class="category-title">🔍 Analysis & Optimization</h2>
+                    <p class="category-description">
+                        Agents specialized in security analysis, performance optimization, and system analysis for production-ready applications.
+                    </p>
+                    <div class="agent-grid">
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">security-guardian</div>
+                                <span class="agent-category">Security</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The paranoid protector who thinks like an attacker. Performs comprehensive security audits, identifies OWASP Top 10 vulnerabilities,
+                                    and ensures defense-in-depth. Reviews authentication, authorization, data protection, and input validation with zero-trust mindset.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>OWASP Top 10 vulnerability detection</li>
+                                        <li>Authentication & authorization review</li>
+                                        <li>SQL injection & XSS prevention</li>
+                                        <li>Secrets management audit</li>
+                                        <li>Encryption implementation review</li>
+                                        <li>API security assessment</li>
+                                        <li>Dependency vulnerability scanning</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: Auth Review</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"security-guardian: Review the login endpoint for security vulnerabilities"</pre>
+                                            </div>
+                                            <p class="example-output">→ Checks: Password hashing, rate limiting, session management, CSRF protection</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: API Security</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Have security-guardian audit our REST API for authorization bypasses and data leaks"</pre>
+                                            </div>
+                                            <p class="example-output">→ Analyzes: IDOR vulnerabilities, permission checks, data exposure, rate limits</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: Full Audit</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"security-guardian: Perform complete security audit including dependencies, secrets, and infrastructure"</pre>
+                                            </div>
+                                            <p class="example-output">→ Delivers: Vulnerability report, risk matrix, remediation priorities, security roadmap</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>🛡️ Security Checklist</strong></summary>
+                                    <ul class="tips-list">
+                                        <li>✓ Input validation on all user data</li>
+                                        <li>✓ Parameterized queries (no SQL injection)</li>
+                                        <li>✓ XSS protection (output encoding)</li>
+                                        <li>✓ HTTPS everywhere</li>
+                                        <li>✓ Secure session management</li>
+                                        <li>✓ Rate limiting on all endpoints</li>
+                                        <li>✓ Secrets in environment variables</li>
+                                        <li>✓ Dependency vulnerability scanning</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">performance-optimizer</div>
+                                <span class="agent-category">Performance</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The speed demon who makes everything faster. Identifies bottlenecks through profiling, implements caching strategies,
+                                    optimizes algorithms from O(n²) to O(n log n), and knows when to trade memory for speed. Thinks in microseconds, not milliseconds.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>CPU & memory profiling</li>
+                                        <li>Algorithm complexity analysis</li>
+                                        <li>Database query optimization</li>
+                                        <li>Caching strategy design</li>
+                                        <li>Lazy loading implementation</li>
+                                        <li>Async/parallel processing</li>
+                                        <li>Memory leak detection</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: Slow Endpoint</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"performance-optimizer: The /api/search endpoint takes 5 seconds to respond"</pre>
+                                            </div>
+                                            <p class="example-output">→ Optimizes: Adds indexes, implements caching, reduces N+1 queries</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Memory Issues</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Use performance-optimizer to fix high memory usage in data processing pipeline"</pre>
+                                            </div>
+                                            <p class="example-output">→ Implements: Streaming, chunking, garbage collection optimization, memory pools</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: System-Wide</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"performance-optimizer: Achieve 10x performance improvement for real-time analytics"</pre>
+                                            </div>
+                                            <p class="example-output">→ Delivers: Architecture changes, caching layers, async processing, horizontal scaling</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>⚡ Performance Targets</strong></summary>
+                                    <ul class="tips-list">
+                                        <li>API response: < 200ms (p95)</li>
+                                        <li>Database queries: < 100ms</li>
+                                        <li>Page load: < 3 seconds</li>
+                                        <li>Memory usage: < 512MB baseline</li>
+                                        <li>CPU usage: < 70% sustained</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">database-architect</div>
+                                <span class="agent-category">Database</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The data strategist who designs schemas that scale from 100 to 100 million records. Masters both SQL and NoSQL,
+                                    knows when to normalize vs denormalize, and creates migration strategies that work without downtime.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>Schema design & normalization</li>
+                                        <li>Index optimization strategies</li>
+                                        <li>Query performance tuning</li>
+                                        <li>Sharding & partitioning</li>
+                                        <li>Migration without downtime</li>
+                                        <li>SQL vs NoSQL selection</li>
+                                        <li>Transaction design</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: Schema Design</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"database-architect: Design schema for e-commerce order system"</pre>
+                                            </div>
+                                            <p class="example-output">→ Creates: Tables, relationships, indexes, constraints, sample queries</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Performance Fix</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Have database-architect optimize our slow reporting queries (taking 30+ seconds)"</pre>
+                                            </div>
+                                            <p class="example-output">→ Analyzes: Execution plans, adds indexes, rewrites queries, suggests materialized views</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: Scale Strategy</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"database-architect: Plan migration from single PostgreSQL to sharded cluster for 10x growth"</pre>
+                                            </div>
+                                            <p class="example-output">→ Designs: Sharding strategy, migration phases, zero-downtime cutover, rollback plan</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>💡 When to Choose</strong></summary>
+                                    <ul class="tips-list">
+                                        <li><strong>SQL:</strong> Complex relationships, ACID requirements</li>
+                                        <li><strong>NoSQL:</strong> Flexible schema, horizontal scaling</li>
+                                        <li><strong>Time-series:</strong> Metrics, logs, IoT data</li>
+                                        <li><strong>Graph:</strong> Social networks, recommendations</li>
+                                        <li><strong>Cache:</strong> Redis for sessions, hot data</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">integration-specialist</div>
+                                <span class="agent-category">Integration</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The connectivity expert who makes disparate systems talk seamlessly. Masters retry logic, circuit breakers,
+                                    and graceful degradation. Handles authentication flows, webhooks, and rate limits while keeping integrations simple and maintainable.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>REST/GraphQL/gRPC integration</li>
+                                        <li>OAuth/JWT authentication flows</li>
+                                        <li>Webhook implementation</li>
+                                        <li>Circuit breaker patterns</li>
+                                        <li>Exponential backoff retry</li>
+                                        <li>Rate limit handling</li>
+                                        <li>MCP server connections</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: Payment API</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"integration-specialist: Connect to Stripe for payment processing"</pre>
+                                            </div>
+                                            <p class="example-output">→ Implements: API client, webhook handler, idempotency, error handling</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Multi-Service</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Use integration-specialist to orchestrate between CRM, email, and analytics services"</pre>
+                                            </div>
+                                            <p class="example-output">→ Creates: Service adapters, event bus, failure isolation, monitoring</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: MCP Setup</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"integration-specialist: Set up MCP server for knowledge base with SSE events"</pre>
+                                            </div>
+                                            <p class="example-output">→ Configures: MCP protocol, SSE streams, reconnection logic, state sync</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>🔄 Resilience Patterns</strong></summary>
+                                    <ul class="tips-list">
+                                        <li>Retry with exponential backoff</li>
+                                        <li>Circuit breaker (fail fast)</li>
+                                        <li>Bulkhead (isolate failures)</li>
+                                        <li>Timeout settings per service</li>
+                                        <li>Graceful degradation</li>
+                                        <li>Health check endpoints</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Knowledge & Insights Agents -->
+                <div class="category-section" data-category="knowledge">
+                    <h2 class="category-title">🧠 Knowledge & Insights</h2>
+                    <p class="category-description">
+                        Agents that work with documentation, extract insights, and manage knowledge for better decision-making and learning.
+                    </p>
+                    <div class="agent-grid">
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">insight-synthesizer</div>
+                                <span class="agent-category">Analysis</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The revolutionary thinker who finds breakthrough connections others miss. Discovers simplification cascades,
+                                    identifies meta-patterns across domains, and creates "collision zones" where unrelated ideas spark innovation.
+                                    Turns complexity into elegant simplicity.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>Cross-domain pattern recognition</li>
+                                        <li>Simplification cascade discovery</li>
+                                        <li>Revolutionary connection finding</li>
+                                        <li>Meta-pattern identification</li>
+                                        <li>Collision-zone thinking</li>
+                                        <li>Complexity reduction strategies</li>
+                                        <li>Innovation through synthesis</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: Pattern Discovery</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"insight-synthesizer: Find patterns in our error logs and user complaints"</pre>
+                                            </div>
+                                            <p class="example-output">→ Discovers: Hidden correlations, root patterns, unexpected connections</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Simplification</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Use insight-synthesizer to find ways to simplify our 15-module auth system"</pre>
+                                            </div>
+                                            <p class="example-output">→ Identifies: Redundancies, cascade opportunities, 3-module solution</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: Innovation</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"insight-synthesizer: Connect our ML failures, API design, and UI issues to find breakthrough"</pre>
+                                            </div>
+                                            <p class="example-output">→ Reveals: Meta-pattern, revolutionary approach, 10x simplification</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>💡 When to Deploy</strong></summary>
+                                    <ul class="tips-list">
+                                        <li>Stuck on complex problems</li>
+                                        <li>Need fresh perspective</li>
+                                        <li>Seeking radical simplification</li>
+                                        <li>Cross-domain challenges</li>
+                                        <li>Innovation opportunities</li>
+                                        <li>Pattern recognition tasks</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">knowledge-archaeologist</div>
+                                <span class="agent-category">Documentation</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The time traveler who excavates the fossil record of ideas. Traces how concepts evolved, why paradigms shifted,
+                                    and which abandoned approaches might solve today's problems. Preserves institutional knowledge and prevents repeating past mistakes.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>Temporal knowledge analysis</li>
+                                        <li>Decision lineage tracing</li>
+                                        <li>Paradigm shift documentation</li>
+                                        <li>Abandoned idea revival</li>
+                                        <li>Evolution pattern recognition</li>
+                                        <li>Context reconstruction</li>
+                                        <li>Institutional memory preservation</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: Decision History</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"knowledge-archaeologist: Why did we choose microservices over monolith?"</pre>
+                                            </div>
+                                            <p class="example-output">→ Traces: Original requirements, decision points, trade-offs, evolution</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Pattern Evolution</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Use knowledge-archaeologist to trace how our API design patterns evolved"</pre>
+                                            </div>
+                                            <p class="example-output">→ Maps: Pattern genealogy, paradigm shifts, lessons learned, revival opportunities</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: Paradigm Analysis</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"knowledge-archaeologist: Find valuable abandoned ideas from our 5-year history"</pre>
+                                            </div>
+                                            <p class="example-output">→ Discovers: Ahead-of-time ideas, changed contexts, revival candidates</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📜 What It Preserves</strong></summary>
+                                    <ul class="tips-list">
+                                        <li>Why decisions were made</li>
+                                        <li>What alternatives were considered</li>
+                                        <li>Which constraints existed then</li>
+                                        <li>How requirements evolved</li>
+                                        <li>When paradigms shifted</li>
+                                        <li>What lessons were learned</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">concept-extractor</div>
+                                <span class="agent-category">Knowledge</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The knowledge miner who transforms documents into structured intelligence. Extracts atomic concepts, maps relationships,
+                                    and preserves productive tensions between conflicting viewpoints. Builds queryable knowledge bases from unstructured content.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>Atomic concept extraction</li>
+                                        <li>Relationship mapping (SPO triples)</li>
+                                        <li>Tension preservation</li>
+                                        <li>Knowledge graph building</li>
+                                        <li>Multi-perspective tracking</li>
+                                        <li>Contradiction identification</li>
+                                        <li>Semantic clustering</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: Document Processing</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"concept-extractor: Process this architecture document into concepts"</pre>
+                                            </div>
+                                            <p class="example-output">→ Extracts: Key concepts, relationships, definitions, dependencies</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Multi-Document</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Use concept-extractor on all microservices documentation"</pre>
+                                            </div>
+                                            <p class="example-output">→ Creates: Unified knowledge graph, service relationships, capability map</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: Conflict Analysis</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"concept-extractor: Extract and preserve tensions between these competing proposals"</pre>
+                                            </div>
+                                            <p class="example-output">→ Maps: Conflicting viewpoints, trade-offs, productive tensions, decision space</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📊 Output Formats</strong></summary>
+                                    <ul class="tips-list">
+                                        <li>Knowledge graph (NetworkX)</li>
+                                        <li>SPO triples (subject-predicate-object)</li>
+                                        <li>Concept hierarchy</li>
+                                        <li>Relationship matrix</li>
+                                        <li>Tension points documentation</li>
+                                        <li>Queryable JSON structure</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">ambiguity-guardian</div>
+                                <span class="agent-category">Analysis</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    Preserves productive contradictions and identifies areas where ambiguity might be valuable.
+                                    Prevents premature optimization and maintains flexibility where needed.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>Ambiguity identification</li>
+                                        <li>Flexibility preservation</li>
+                                        <li>Contradiction analysis</li>
+                                        <li>Decision deferral strategies</li>
+                                    </ul>
+                                </div>
+                                <div class="example-usage">
+                                    "Have ambiguity-guardian review feature requirements"
+                                </div>
+                            </div>
+                        </div>
+
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">content-researcher</div>
+                                <span class="agent-category">Research</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    Researches from content collection, finding relevant information and connecting ideas.
+                                    Acts as your intelligent research assistant for technical documentation and decisions.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>Content research</li>
+                                        <li>Information synthesis</li>
+                                        <li>Relevance analysis</li>
+                                        <li>Reference tracking</li>
+                                    </ul>
+                                </div>
+                                <div class="example-usage">
+                                    "Use content-researcher to find database patterns"
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Meta & Support Agents -->
+                <div class="category-section" data-category="meta">
+                    <h2 class="category-title">🔧 Meta & Support</h2>
+                    <p class="category-description">
+                        Agents that help manage the development environment, create new specialized agents, and maintain codebase hygiene.
+                    </p>
+                    <div class="agent-grid">
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">subagent-architect</div>
+                                <span class="agent-category">Meta</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The agent creator who designs new specialized experts for your unique needs. Analyzes your workflow,
+                                    identifies capability gaps, and creates custom agents with precise expertise. Your personal AI team builder.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>Custom agent creation</li>
+                                        <li>Expertise specification</li>
+                                        <li>Workflow gap analysis</li>
+                                        <li>Tool integration design</li>
+                                        <li>Prompt engineering</li>
+                                        <li>Agent testing & validation</li>
+                                        <li>Performance optimization</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: Framework Expert</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"subagent-architect: Create a React + TypeScript specialist agent"</pre>
+                                            </div>
+                                            <p class="example-output">→ Creates: Agent with React patterns, hooks expertise, TypeScript best practices</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Domain Expert</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Use subagent-architect to build a healthcare compliance agent for HIPAA"</pre>
+                                            </div>
+                                            <p class="example-output">→ Creates: Specialized agent with regulatory knowledge, audit capabilities</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: Workflow Agent</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"subagent-architect: Design multi-agent workflow for continuous deployment pipeline"</pre>
+                                            </div>
+                                            <p class="example-output">→ Creates: Agent team with build, test, deploy, monitor specializations</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>🎯 Agent Design Tips</strong></summary>
+                                    <ul class="tips-list">
+                                        <li>Start with specific, narrow expertise</li>
+                                        <li>Define clear trigger conditions</li>
+                                        <li>Include concrete examples</li>
+                                        <li>Specify integration points</li>
+                                        <li>Test with real scenarios</li>
+                                        <li>Iterate based on performance</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+
+                        <div class="agent-card-detailed">
+                            <div class="agent-header">
+                                <div class="agent-name">post-task-cleanup</div>
+                                <span class="agent-category">Maintenance</span>
+                            </div>
+                            <div class="agent-body">
+                                <p class="agent-description">
+                                    The janitor who keeps your codebase pristine. Runs after tasks to remove debug code, eliminate unnecessary complexity,
+                                    update documentation, and ensure philosophy compliance. Your automated technical debt preventer.
+                                </p>
+                                <div class="agent-features">
+                                    <h4>Key Capabilities</h4>
+                                    <ul>
+                                        <li>Debug artifact removal</li>
+                                        <li>Complexity elimination</li>
+                                        <li>Documentation sync</li>
+                                        <li>Import optimization</li>
+                                        <li>Dead code removal</li>
+                                        <li>Consistency enforcement</li>
+                                        <li>Philosophy compliance</li>
+                                    </ul>
+                                </div>
+
+                                <details class="advanced-section">
+                                    <summary><strong>📚 Practical Examples</strong></summary>
+                                    <div class="examples-container">
+                                        <div class="example-card">
+                                            <h5>🎯 Simple: After Feature</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"post-task-cleanup: Clean up after implementing user registration"</pre>
+                                            </div>
+                                            <p class="example-output">→ Removes: Console.logs, TODO comments, unused imports, test artifacts</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🔧 Intermediate: Module Review</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"Use post-task-cleanup to review and simplify the payment module"</pre>
+                                            </div>
+                                            <p class="example-output">→ Simplifies: Removes abstractions, consolidates files, updates docs</p>
+                                        </div>
+
+                                        <div class="example-card">
+                                            <h5>🚀 Advanced: Codebase Audit</h5>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyToClipboard(this)">📋 Copy</button>
+                                                <pre>"post-task-cleanup: Full codebase hygiene check and philosophy compliance"</pre>
+                                            </div>
+                                            <p class="example-output">→ Delivers: Cleanup report, technical debt list, simplification opportunities</p>
+                                        </div>
+                                    </div>
+                                </details>
+
+                                <details class="advanced-section">
+                                    <summary><strong>🧹 Cleanup Checklist</strong></summary>
+                                    <ul class="tips-list">
+                                        <li>Remove console.log statements</li>
+                                        <li>Delete commented-out code</li>
+                                        <li>Remove TODO without action</li>
+                                        <li>Optimize imports</li>
+                                        <li>Delete unused variables</li>
+                                        <li>Update stale documentation</li>
+                                        <li>Enforce naming conventions</li>
+                                    </ul>
+                                </details>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Usage Instructions -->
+                <div class="section" style="background: var(--light-bg); padding: 3rem 2rem; border-radius: var(--border-radius-lg); margin-top: 4rem;">
+                    <h2 style="text-align: center; margin-bottom: 2rem;">How to Use Agents</h2>
+                    <div style="max-width: 800px; margin: 0 auto;">
+                        <div style="margin-bottom: 2rem;">
+                            <h3 style="color: var(--primary-color); margin-bottom: 1rem;">Automatic Invocation</h3>
+                            <p style="color: var(--text-secondary); line-height: 1.6;">
+                                Claude automatically selects and invokes the most appropriate agent based on your request.
+                                Simply describe your task naturally, and the system will delegate to the right specialist.
+                            </p>
+                        </div>
+                        <div style="margin-bottom: 2rem;">
+                            <h3 style="color: var(--primary-color); margin-bottom: 1rem;">Explicit Invocation</h3>
+                            <p style="color: var(--text-secondary); line-height: 1.6;">
+                                You can also explicitly request specific agents by name:
+                            </p>
+                            <div class="code-snippet" style="margin-top: 1rem;">
+                                <code>"Use zen-architect to design my user management system"<br>
+"Have bug-hunter investigate the login timeout issue"<br>
+"Deploy security-guardian to review the API endpoints"</code>
+                            </div>
+                        </div>
+                        <div>
+                            <h3 style="color: var(--primary-color); margin-bottom: 1rem;">Creating Custom Agents</h3>
+                            <p style="color: var(--text-secondary); line-height: 1.6;">
+                                Use the subagent-architect to create specialized agents for your unique needs,
+                                or use the <code>/agents</code> command to create them interactively.
+                            </p>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </section>
+    </main>
+
+    <footer class="footer">
+        <div class="container">
+            <div class="footer-content">
+                <div class="footer-brand">
+                    <h3>Amplifier</h3>
+                    <p>Supercharged AI Development Environment</p>
+                </div>
+                <div class="footer-links">
+                    <div class="footer-column">
+                        <h4>Documentation</h4>
+                        <a href="setup.html">Setup Guide</a>
+                        <a href="agents.html">Agent Catalog</a>
+                        <a href="knowledge.html">Knowledge Base</a>
+                        <a href="examples.html">Examples</a>
+                    </div>
+                    <div class="footer-column">
+                        <h4>Resources</h4>
+                        <a href="https://github.com/microsoft/amplifier">GitHub</a>
+                        <a href="../AMPLIFIER_VISION.md">Vision</a>
+                        <a href="../README.md">README</a>
+                    </div>
+                </div>
+            </div>
+            <div class="footer-bottom">
+                <p>&copy; 2024 Microsoft. Licensed under MIT.</p>
+            </div>
+        </div>
+    </footer>
+
+    <script src="script.js"></script>
+    <script>
+        // Copy to clipboard function
+        function copyToClipboard(button) {
+            const codeBlock = button.parentElement;
+            const code = codeBlock.querySelector('pre').textContent;
+
+            navigator.clipboard.writeText(code).then(() => {
+                const originalText = button.textContent;
+                button.textContent = '✓ Copied!';
+                button.classList.add('copied');
+
+                setTimeout(() => {
+                    button.textContent = originalText;
+                    button.classList.remove('copied');
+                }, 2000);
+            }).catch(err => {
+                console.error('Failed to copy:', err);
+                button.textContent = '❌ Failed';
+                setTimeout(() => {
+                    button.textContent = '📋 Copy';
+                }, 2000);
+            });
+        }
+
+        // Initialize all details elements to be closed by default
+        document.addEventListener('DOMContentLoaded', () => {
+            document.querySelectorAll('details').forEach(details => {
+                details.removeAttribute('open');
+            });
+        });
+
+        // Filter function continues below
+
+        function filterAgents(category, buttonElement) {
+            // Update active button
+            document.querySelectorAll('.filter-btn').forEach(btn => {
+                btn.classList.remove('active');
+            });
+
+            // Use the passed button element or fallback to event.target
+            const button = buttonElement || event?.target;
+            if (button) {
+                button.classList.add('active');
+            }
+
+            // Show/hide categories
+            document.querySelectorAll('.category-section').forEach(section => {
+                if (category === 'all') {
+                    section.style.display = 'block';
+                } else {
+                    section.style.display = section.dataset.category === category ? 'block' : 'none';
+                }
+            });
+        }
+    </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/instructor/examples.html b/instructor/examples.html
new file mode 100644
index 00000000..b06aa335
--- /dev/null
+++ b/instructor/examples.html
@@ -0,0 +1,1721 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Examples & Workflows - Amplifier</title>
+    <link rel="stylesheet" href="styles.css">
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+    <style>
+        .examples-hero {
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: var(--text-light);
+            padding: 4rem 2rem;
+            text-align: center;
+        }
+        .copy-paste-banner {
+            background: linear-gradient(135deg, #10b981 0%, #059669 100%);
+            color: var(--text-light);
+            padding: 2rem;
+            border-radius: var(--border-radius-lg);
+            margin: 2rem 0;
+            text-align: center;
+        }
+        .copy-paste-banner h3 {
+            margin-bottom: 0.5rem;
+            font-size: 1.5rem;
+        }
+        .copy-paste-banner p {
+            opacity: 0.9;
+            margin-bottom: 1.5rem;
+        }
+        .quick-start-commands {
+            background: rgba(255, 255, 255, 0.1);
+            padding: 1rem;
+            border-radius: var(--border-radius);
+            font-family: monospace;
+            text-align: left;
+            position: relative;
+        }
+        .copy-btn {
+            background: rgba(255, 255, 255, 0.2);
+            color: var(--text-light);
+            border: none;
+            padding: 0.5rem 1rem;
+            border-radius: var(--border-radius);
+            cursor: pointer;
+            position: absolute;
+            top: 0.5rem;
+            right: 0.5rem;
+            font-size: 0.8rem;
+            transition: var(--transition);
+        }
+        .copy-btn:hover {
+            background: rgba(255, 255, 255, 0.3);
+        }
+        .code-block {
+            background: var(--dark-bg);
+            color: var(--text-light);
+            padding: 1rem;
+            border-radius: var(--border-radius);
+            font-family: monospace;
+            position: relative;
+            margin: 1rem 0;
+            overflow-x: auto;
+        }
+        .code-block .copy-btn {
+            background: rgba(255, 255, 255, 0.1);
+            border: 1px solid rgba(255, 255, 255, 0.2);
+        }
+        .expected-output {
+            background: var(--light-bg);
+            border-left: 4px solid #10b981;
+            padding: 1rem;
+            margin: 1rem 0;
+            border-radius: var(--border-radius);
+        }
+        .expected-output h5 {
+            color: #10b981;
+            margin-bottom: 0.5rem;
+            font-size: 0.9rem;
+            font-weight: 600;
+        }
+        .troubleshooting {
+            background: #fef3cd;
+            border-left: 4px solid #f59e0b;
+            padding: 1.5rem;
+            border-radius: var(--border-radius);
+            margin: 1.5rem 0;
+        }
+        .troubleshooting h5 {
+            color: #d97706;
+            margin-bottom: 1rem;
+            font-weight: 600;
+        }
+        .troubleshooting ul {
+            margin: 0;
+            padding-left: 1.5rem;
+        }
+        .troubleshooting li {
+            color: #92400e;
+            margin-bottom: 0.5rem;
+        }
+        .difficulty-levels {
+            display: flex;
+            gap: 0.5rem;
+            margin-bottom: 1.5rem;
+            flex-wrap: wrap;
+        }
+        .difficulty-btn {
+            background: white;
+            border: 1px solid var(--border-color);
+            padding: 0.5rem 1rem;
+            border-radius: var(--border-radius);
+            cursor: pointer;
+            font-size: 0.85rem;
+            transition: var(--transition);
+        }
+        .difficulty-btn.active {
+            background: var(--primary-color);
+            color: var(--text-light);
+            border-color: var(--primary-color);
+        }
+        .difficulty-content {
+            display: none;
+        }
+        .difficulty-content.active {
+            display: block;
+        }
+        .verification-steps {
+            background: #f0f9ff;
+            border-left: 4px solid #0ea5e9;
+            padding: 1.5rem;
+            border-radius: var(--border-radius);
+            margin: 1.5rem 0;
+        }
+        .verification-steps h5 {
+            color: #0369a1;
+            margin-bottom: 1rem;
+            font-weight: 600;
+        }
+        .step-detail {
+            background: white;
+            border-radius: var(--border-radius);
+            padding: 2rem;
+            margin: 1.5rem 0;
+            box-shadow: var(--shadow);
+        }
+        .step-detail h4 {
+            color: var(--primary-color);
+            margin-bottom: 1rem;
+            font-size: 1.2rem;
+        }
+        .collapsible-section {
+            border: 1px solid var(--border-color);
+            border-radius: var(--border-radius);
+            margin: 1rem 0;
+        }
+        .collapsible-header {
+            background: var(--light-bg);
+            padding: 1rem;
+            cursor: pointer;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+        }
+        .collapsible-header:hover {
+            background: #f8f9fa;
+        }
+        .collapsible-content {
+            padding: 1.5rem;
+            border-top: 1px solid var(--border-color);
+            display: none;
+        }
+        .collapsible-content.active {
+            display: block;
+        }
+        .command-sequence {
+            background: var(--dark-bg);
+            color: var(--text-light);
+            padding: 1.5rem;
+            border-radius: var(--border-radius-lg);
+            margin: 1.5rem 0;
+        }
+        .command-sequence h5 {
+            color: #4fd1c7;
+            margin-bottom: 1rem;
+            font-size: 1rem;
+        }
+        .command-line {
+            margin: 0.5rem 0;
+            font-family: monospace;
+        }
+        .command-line .prompt {
+            color: #4fd1c7;
+        }
+        .command-line .command {
+            color: #f7fafc;
+        }
+        .command-line .comment {
+            color: #a0aec0;
+            font-style: italic;
+        }
+        .real-world-example {
+            background: linear-gradient(135deg, #8b5cf6 0%, #7c3aed 100%);
+            color: var(--text-light);
+            padding: 2rem;
+            border-radius: var(--border-radius-lg);
+            margin: 2rem 0;
+        }
+        .real-world-example h4 {
+            margin-bottom: 1rem;
+            font-size: 1.3rem;
+        }
+        .real-world-example p {
+            opacity: 0.9;
+            margin-bottom: 1.5rem;
+            line-height: 1.6;
+        }
+        .examples-hero h1 {
+            font-size: 3rem;
+            margin-bottom: 1rem;
+        }
+        .examples-hero p {
+            font-size: 1.3rem;
+            opacity: 0.9;
+            max-width: 600px;
+            margin: 0 auto;
+        }
+        .workflow-container {
+            max-width: 1200px;
+            margin: 0 auto;
+        }
+        .workflow {
+            background: white;
+            margin: 3rem 0;
+            border-radius: var(--border-radius-lg);
+            box-shadow: var(--shadow-lg);
+            overflow: hidden;
+        }
+        .workflow-header {
+            background: linear-gradient(135deg, var(--primary-color), #0052a3);
+            color: var(--text-light);
+            padding: 2rem;
+            display: flex;
+            align-items: center;
+            gap: 1rem;
+        }
+        .workflow-icon {
+            font-size: 2.5rem;
+        }
+        .workflow-title {
+            font-size: 1.8rem;
+            font-weight: 600;
+            margin-bottom: 0.5rem;
+        }
+        .workflow-subtitle {
+            opacity: 0.9;
+            font-size: 1.1rem;
+        }
+        .workflow-body {
+            padding: 2rem;
+        }
+        .workflow-steps {
+            display: grid;
+            gap: 2rem;
+        }
+        .workflow-step {
+            display: flex;
+            gap: 1.5rem;
+            padding: 1.5rem;
+            background: var(--light-bg);
+            border-radius: var(--border-radius);
+            border-left: 4px solid var(--primary-color);
+        }
+        .step-number {
+            background: var(--primary-color);
+            color: var(--text-light);
+            width: 2.5rem;
+            height: 2.5rem;
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font-weight: 600;
+            flex-shrink: 0;
+        }
+        .step-content h4 {
+            color: var(--text-primary);
+            margin-bottom: 0.5rem;
+            font-size: 1.1rem;
+        }
+        .step-content p {
+            color: var(--text-secondary);
+            margin-bottom: 1rem;
+            line-height: 1.6;
+        }
+        .step-command {
+            background: var(--dark-bg);
+            color: var(--text-light);
+            padding: 1rem;
+            border-radius: var(--border-radius);
+            font-family: monospace;
+            font-size: 0.9rem;
+            margin-top: 0.5rem;
+        }
+        .command-prompt {
+            color: #4fd1c7;
+        }
+        .agent-highlight {
+            background: var(--primary-color);
+            color: var(--text-light);
+            padding: 0.2rem 0.5rem;
+            border-radius: 0.25rem;
+            font-size: 0.8rem;
+            margin-left: 0.5rem;
+        }
+        .quick-examples {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+            gap: 1.5rem;
+            margin: 3rem 0;
+        }
+        .quick-example {
+            background: white;
+            padding: 1.5rem;
+            border-radius: var(--border-radius);
+            box-shadow: var(--shadow);
+            border-left: 4px solid var(--accent-color);
+        }
+        .quick-example h4 {
+            color: var(--text-primary);
+            margin-bottom: 0.5rem;
+            font-size: 1rem;
+        }
+        .quick-example .command {
+            background: var(--light-bg);
+            padding: 0.75rem;
+            border-radius: var(--border-radius);
+            font-family: monospace;
+            font-size: 0.85rem;
+            color: var(--primary-color);
+            margin-top: 0.5rem;
+        }
+        .scenario-tabs {
+            display: flex;
+            justify-content: center;
+            margin: 3rem 0 2rem;
+            flex-wrap: wrap;
+            gap: 0.5rem;
+        }
+        .scenario-tab {
+            background: white;
+            border: 1px solid var(--border-color);
+            padding: 0.75rem 1.5rem;
+            border-radius: var(--border-radius);
+            cursor: pointer;
+            transition: var(--transition);
+            font-weight: 500;
+        }
+        .scenario-tab.active,
+        .scenario-tab:hover {
+            background: var(--primary-color);
+            color: var(--text-light);
+            border-color: var(--primary-color);
+        }
+        .scenario-content {
+            display: none;
+        }
+        .scenario-content.active {
+            display: block;
+        }
+        .parallel-demo {
+            background: var(--dark-bg);
+            color: var(--text-light);
+            padding: 2rem;
+            border-radius: var(--border-radius-lg);
+            margin: 2rem 0;
+        }
+        .parallel-demo h4 {
+            color: #4fd1c7;
+            margin-bottom: 1rem;
+        }
+        .terminal-session {
+            font-family: monospace;
+            line-height: 1.6;
+        }
+        .terminal-session .command {
+            color: #f7fafc;
+        }
+        .terminal-session .comment {
+            color: #a0aec0;
+            font-style: italic;
+        }
+        .tips-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+            gap: 1.5rem;
+            margin: 3rem 0;
+        }
+        .tip-item {
+            background: white;
+            padding: 1.5rem;
+            border-radius: var(--border-radius);
+            box-shadow: var(--shadow);
+        }
+        .tip-icon {
+            font-size: 2rem;
+            margin-bottom: 1rem;
+        }
+        .tip-item h4 {
+            color: var(--primary-color);
+            margin-bottom: 0.5rem;
+        }
+        .tip-item p {
+            color: var(--text-secondary);
+            line-height: 1.6;
+            font-size: 0.95rem;
+        }
+    </style>
+</head>
+<body>
+    <header class="header">
+        <nav class="nav">
+            <div class="nav-brand">
+                <h1>Amplifier</h1>
+                <span class="tagline">Examples & Workflows</span>
+            </div>
+            <div class="nav-links">
+                <a href="index.html" class="nav-link">Home</a>
+                <a href="agents.html" class="nav-link">Agents</a>
+                <a href="setup.html" class="nav-link">Setup</a>
+                <a href="knowledge.html" class="nav-link">Knowledge Base</a>
+                <a href="https://github.com/microsoft/amplifier" class="nav-link">GitHub</a>
+            </div>
+            <div class="nav-mobile">
+                <button class="mobile-menu-btn" onclick="toggleMobileMenu()">☰</button>
+            </div>
+        </nav>
+    </header>
+
+    <main style="padding-top: 0;">
+        <!-- Hero Section -->
+        <section class="examples-hero">
+            <div class="container">
+                <h1>Examples & Workflows</h1>
+                <p>Real-world examples of how to use Amplifier's specialized agents and features to accelerate your development</p>
+
+                <div class="copy-paste-banner">
+                    <h3>⚡ Ready to Copy & Paste</h3>
+                    <p>All examples include working commands you can copy directly into Claude. No guesswork, no setup - just results.</p>
+                    <div class="quick-start-commands">
+                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                        <div># Start with any workflow in 3 commands:</div>
+                        <div>cd amplifier</div>
+                        <div>claude</div>
+                        <div>"Use zen-architect to design my [feature name]"</div>
+                    </div>
+                </div>
+            </div>
+        </section>
+
+        <!-- Scenario Tabs -->
+        <section class="section">
+            <div class="container">
+                <div class="scenario-tabs">
+                    <button class="scenario-tab active" onclick="showScenario('development', this)">Feature Development</button>
+                    <button class="scenario-tab" onclick="showScenario('debugging', this)">Debugging & Fixing</button>
+                    <button class="scenario-tab" onclick="showScenario('knowledge', this)">Knowledge-Driven</button>
+                    <button class="scenario-tab" onclick="showScenario('optimization', this)">Optimization</button>
+                    <button class="scenario-tab" onclick="showScenario('parallel', this)">Parallel Development</button>
+                </div>
+
+                <!-- Development Scenarios -->
+                <div id="development-scenario" class="scenario-content active">
+                    <div class="workflow-container">
+                        <!-- Complete Feature Development -->
+                        <div class="workflow">
+                            <div class="workflow-header">
+                                <div class="workflow-icon">🏗️</div>
+                                <div>
+                                    <div class="workflow-title">Building a Complete Feature</div>
+                                    <div class="workflow-subtitle">From design to testing with specialized agents</div>
+                                </div>
+                            </div>
+                            <div class="workflow-body">
+                                <div class="difficulty-levels">
+                                    <button class="difficulty-btn active" onclick="showDifficulty('feature-beginner', this)">👶 Beginner</button>
+                                    <button class="difficulty-btn" onclick="showDifficulty('feature-intermediate', this)">🚀 Intermediate</button>
+                                    <button class="difficulty-btn" onclick="showDifficulty('feature-advanced', this)">🎯 Advanced</button>
+                                </div>
+
+                                <!-- Beginner Level -->
+                                <div id="feature-beginner" class="difficulty-content active">
+                                    <div class="real-world-example">
+                                        <h4>🎯 Example: Building a User Profile System</h4>
+                                        <p>We'll build a complete user profile feature from scratch - user registration, profile editing, avatar upload, and privacy settings.</p>
+                                    </div>
+
+                                    <div class="step-detail">
+                                        <h4>Step 1: Architecture Design</h4>
+                                        <p>Start with zen-architect to get a clean, maintainable design:</p>
+                                        <div class="code-block">
+                                            <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                            "Use zen-architect to design a user profile system with registration, profile editing, avatar upload, and privacy settings. Focus on simplicity and maintainability."
+                                        </div>
+                                        <div class="expected-output">
+                                            <h5>✅ What zen-architect will provide:</h5>
+                                            • Problem breakdown and requirements analysis<br>
+                                            • 3 architectural approaches with trade-offs<br>
+                                            • Recommended modular structure<br>
+                                            • Database schema suggestions<br>
+                                            • API endpoint specifications
+                                        </div>
+                                    </div>
+
+                                    <div class="step-detail">
+                                        <h4>Step 2: Module Implementation</h4>
+                                        <p>Use modular-builder to create the actual code:</p>
+                                        <div class="code-block">
+                                            <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                            "Have modular-builder implement the user profile module following the zen-architect design. Include user registration, profile CRUD operations, and avatar upload functionality."
+                                        </div>
+                                        <div class="expected-output">
+                                            <h5>✅ What modular-builder will create:</h5>
+                                            • Complete module structure with clear contracts<br>
+                                            • Database models and migrations<br>
+                                            • API endpoints with proper validation<br>
+                                            • File upload handling for avatars<br>
+                                            • Privacy settings implementation
+                                        </div>
+                                    </div>
+
+                                    <div class="step-detail">
+                                        <h4>Step 3: Comprehensive Testing</h4>
+                                        <p>Deploy test-coverage to ensure everything works:</p>
+                                        <div class="code-block">
+                                            <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                            "Deploy test-coverage to add comprehensive tests for the user profile system including unit tests, integration tests, and edge cases for file uploads and validation."
+                                        </div>
+                                        <div class="expected-output">
+                                            <h5>✅ What test-coverage will add:</h5>
+                                            • Unit tests for all business logic<br>
+                                            • Integration tests for API endpoints<br>
+                                            • File upload edge cases (size limits, formats)<br>
+                                            • Validation error scenarios<br>
+                                            • Security test cases
+                                        </div>
+                                    </div>
+
+                                    <div class="step-detail">
+                                        <h4>Step 4: Security Review</h4>
+                                        <p>Have security-guardian check for vulnerabilities:</p>
+                                        <div class="code-block">
+                                            <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                            "Have security-guardian review the user profile system for security vulnerabilities, including file upload security, input validation, and privacy controls."
+                                        </div>
+                                        <div class="expected-output">
+                                            <h5>✅ What security-guardian will check:</h5>
+                                            • File upload security (malicious files)<br>
+                                            • Input validation and XSS prevention<br>
+                                            • Authentication and authorization<br>
+                                            • Privacy setting enforcement<br>
+                                            • OWASP compliance
+                                        </div>
+                                    </div>
+
+                                    <div class="verification-steps">
+                                        <h5>🧪 Verification Steps</h5>
+                                        <ol>
+                                            <li><strong>Run Tests:</strong> <code>make test</code> - All tests should pass</li>
+                                            <li><strong>Check Security:</strong> <code>make check</code> - No security issues</li>
+                                            <li><strong>Manual Testing:</strong> Create a user, upload avatar, edit profile</li>
+                                            <li><strong>Privacy Check:</strong> Verify privacy settings work correctly</li>
+                                        </ol>
+                                    </div>
+
+                                    <div class="troubleshooting">
+                                        <h5>🚨 Common Issues</h5>
+                                        <ul>
+                                            <li><strong>File upload fails:</strong> Check file size limits and storage configuration</li>
+                                            <li><strong>Tests fail:</strong> Run <code>make lint</code> to check code formatting</li>
+                                            <li><strong>Security warnings:</strong> Review input validation and sanitization</li>
+                                            <li><strong>Database errors:</strong> Verify migrations are applied correctly</li>
+                                        </ul>
+                                    </div>
+                                </div>
+
+                                <!-- Intermediate Level -->
+                                <div id="feature-intermediate" class="difficulty-content">
+                                    <div class="real-world-example">
+                                        <h4>🎯 Example: E-commerce Cart & Checkout</h4>
+                                        <p>Build a complete shopping cart with inventory management, payment processing, order history, and email notifications.</p>
+                                    </div>
+
+                                    <div class="collapsible-section">
+                                        <div class="collapsible-header" onclick="toggleCollapsible(this)">
+                                            <h4>Step 1: Architecture & Integration Planning</h4>
+                                            <span>+</span>
+                                        </div>
+                                        <div class="collapsible-content">
+                                            <div class="command-sequence">
+                                                <h5>📋 Command Sequence</h5>
+                                                <div class="command-line"><span class="prompt">1.</span> <span class="command">"Use zen-architect to design an e-commerce cart system with inventory management, payment integration (Stripe), order processing, and email notifications"</span></div>
+                                                <div class="command-line"><span class="prompt">2.</span> <span class="command">"Have integration-specialist analyze the payment and email service integrations for the cart system"</span></div>
+                                                <div class="command-line"><span class="prompt">3.</span> <span class="command">"Use database-architect to optimize the cart and inventory database design for high performance"</span></div>
+                                            </div>
+                                            <div class="expected-output">
+                                                <h5>✅ Expected Results:</h5>
+                                                • Microservices architecture with clear boundaries<br>
+                                                • Integration patterns for Stripe and email services<br>
+                                                • Optimized database schema with proper indexes<br>
+                                                • Inventory concurrency handling strategy<br>
+                                                • Error handling and rollback mechanisms
+                                            </div>
+                                        </div>
+                                    </div>
+
+                                    <div class="collapsible-section">
+                                        <div class="collapsible-header" onclick="toggleCollapsible(this)">
+                                            <h4>Step 2: Core Implementation</h4>
+                                            <span>+</span>
+                                        </div>
+                                        <div class="collapsible-content">
+                                            <div class="command-sequence">
+                                                <h5>📋 Command Sequence</h5>
+                                                <div class="command-line"><span class="prompt">1.</span> <span class="command">"Have modular-builder implement the shopping cart module with session management and inventory tracking"</span></div>
+                                                <div class="command-line"><span class="prompt">2.</span> <span class="command">"Use api-contract-designer to create the checkout and payment API endpoints"</span></div>
+                                                <div class="command-line"><span class="prompt">3.</span> <span class="command">"Have modular-builder implement the order processing and email notification systems"</span></div>
+                                            </div>
+                                            <p><strong>Key Features to Implement:</strong></p>
+                                            <ul>
+                                                <li>Shopping cart CRUD with session persistence</li>
+                                                <li>Real-time inventory checking and reservation</li>
+                                                <li>Stripe payment processing with webhooks</li>
+                                                <li>Order status tracking and history</li>
+                                                <li>Automated email notifications</li>
+                                            </ul>
+                                        </div>
+                                    </div>
+
+                                    <div class="collapsible-section">
+                                        <div class="collapsible-header" onclick="toggleCollapsible(this)">
+                                            <h4>Step 3: Performance & Security</h4>
+                                            <span>+</span>
+                                        </div>
+                                        <div class="collapsible-content">
+                                            <div class="command-sequence">
+                                                <h5>📋 Command Sequence</h5>
+                                                <div class="command-line"><span class="prompt">1.</span> <span class="command">"Have performance-optimizer analyze the cart and checkout flow for bottlenecks"</span></div>
+                                                <div class="command-line"><span class="prompt">2.</span> <span class="command">"Use security-guardian to audit payment processing and PII handling"</span></div>
+                                                <div class="command-line"><span class="prompt">3.</span> <span class="command">"Deploy test-coverage to add comprehensive tests including payment scenarios and race conditions"</span></div>
+                                            </div>
+                                            <div class="troubleshooting">
+                                                <h5>🚨 E-commerce Specific Issues</h5>
+                                                <ul>
+                                                    <li><strong>Race conditions:</strong> Multiple users buying the last item</li>
+                                                    <li><strong>Payment failures:</strong> Network timeouts during payment processing</li>
+                                                    <li><strong>Inventory sync:</strong> Real-time inventory updates across sessions</li>
+                                                    <li><strong>PCI compliance:</strong> Secure handling of payment information</li>
+                                                </ul>
+                                            </div>
+                                        </div>
+                                    </div>
+                                </div>
+
+                                <!-- Advanced Level -->
+                                <div id="feature-advanced" class="difficulty-content">
+                                    <div class="real-world-example">
+                                        <h4>🎯 Example: Multi-tenant SaaS Platform</h4>
+                                        <p>Build a complete multi-tenant SaaS platform with tenant isolation, usage billing, admin dashboards, and white-label customization.</p>
+                                    </div>
+
+                                    <div class="command-sequence">
+                                        <h5>📋 Advanced Multi-Agent Orchestration</h5>
+                                        <div class="command-line"><span class="comment"># Architecture phase - multiple agents in parallel</span></div>
+                                        <div class="command-line"><span class="prompt">1a.</span> <span class="command">"Use zen-architect to design multi-tenant architecture with data isolation, tenant onboarding, and billing integration"</span></div>
+                                        <div class="command-line"><span class="prompt">1b.</span> <span class="command">"Have database-architect design tenant isolation strategies and performance optimization for multi-tenancy"</span></div>
+                                        <div class="command-line"><span class="prompt">1c.</span> <span class="command">"Use security-guardian to analyze multi-tenant security requirements and isolation boundaries"</span></div>
+                                        <div class="command-line"><span class="comment"># Implementation phase - coordinated development</span></div>
+                                        <div class="command-line"><span class="prompt">2a.</span> <span class="command">"Have modular-builder implement the tenant management and onboarding system"</span></div>
+                                        <div class="command-line"><span class="prompt">2b.</span> <span class="command">"Use api-contract-designer to create the admin dashboard API with tenant-scoped endpoints"</span></div>
+                                        <div class="command-line"><span class="prompt">2c.</span> <span class="command">"Have integration-specialist implement billing system integration with usage tracking"</span></div>
+                                        <div class="command-line"><span class="comment"># Validation phase - comprehensive testing</span></div>
+                                        <div class="command-line"><span class="prompt">3a.</span> <span class="command">"Deploy test-coverage to add multi-tenant isolation tests and billing scenarios"</span></div>
+                                        <div class="command-line"><span class="prompt">3b.</span> <span class="command">"Use performance-optimizer to test scalability with multiple tenants and high load"</span></div>
+                                        <div class="command-line"><span class="prompt">3c.</span> <span class="command">"Have security-guardian perform penetration testing for tenant isolation"</span></div>
+                                    </div>
+
+                                    <div class="collapsible-section">
+                                        <div class="collapsible-header" onclick="toggleCollapsible(this)">
+                                            <h4>Advanced Techniques: Parallel Worktrees for Architecture Comparison</h4>
+                                            <span>+</span>
+                                        </div>
+                                        <div class="collapsible-content">
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                                # Test 3 different multi-tenant approaches in parallel
+                                                make worktree tenant-shared-db      # Shared database approach
+                                                make worktree tenant-separate-db    # Separate database per tenant
+                                                make worktree tenant-schema-based   # Schema-based isolation
+
+                                                # Develop each approach with different agents
+                                                # Compare performance, security, and maintainability
+                                                make worktree-list                  # Review all approaches
+                                            </div>
+                                            <p><strong>Evaluation Criteria:</strong></p>
+                                            <ul>
+                                                <li>Data isolation effectiveness</li>
+                                                <li>Performance at scale (1000+ tenants)</li>
+                                                <li>Backup and disaster recovery complexity</li>
+                                                <li>Development and maintenance overhead</li>
+                                                <li>Cost optimization opportunities</li>
+                                            </ul>
+                                        </div>
+                                    </div>
+
+                                    <div class="verification-steps">
+                                        <h5>🧪 Advanced Verification Protocol</h5>
+                                        <ol>
+                                            <li><strong>Tenant Isolation:</strong> Verify data cannot leak between tenants</li>
+                                            <li><strong>Performance Testing:</strong> Load test with 100+ concurrent tenants</li>
+                                            <li><strong>Billing Accuracy:</strong> Validate usage tracking and billing calculations</li>
+                                            <li><strong>Security Audit:</strong> Penetration testing for multi-tenant vulnerabilities</li>
+                                            <li><strong>Disaster Recovery:</strong> Test backup/restore for individual tenants</li>
+                                        </ol>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+
+                        <div class="workflow">
+                            <div class="workflow-header">
+                                <div class="workflow-icon">⚡</div>
+                                <div>
+                                    <div class="workflow-title">Rapid API Development</div>
+                                    <div class="workflow-subtitle">Design and implement APIs with proper contracts</div>
+                                </div>
+                            </div>
+                            <div class="workflow-body">
+                                <div class="workflow-steps">
+                                    <div class="workflow-step">
+                                        <div class="step-number">1</div>
+                                        <div class="step-content">
+                                            <h4>API Contract Design <span class="agent-highlight">api-contract-designer</span></h4>
+                                            <p>Create clean, consistent API design with proper documentation.</p>
+                                            <div class="step-command">
+                                                <span class="command-prompt">></span> "Use api-contract-designer to create a RESTful API for user management with authentication endpoints"
+                                            </div>
+                                        </div>
+                                    </div>
+                                    <div class="workflow-step">
+                                        <div class="step-number">2</div>
+                                        <div class="step-content">
+                                            <h4>Implementation <span class="agent-highlight">modular-builder</span></h4>
+                                            <p>Build the API following the contract specifications.</p>
+                                            <div class="step-command">
+                                                <span class="command-prompt">></span> "Have modular-builder implement the user management API following the contract design"
+                                            </div>
+                                        </div>
+                                    </div>
+                                    <div class="workflow-step">
+                                        <div class="step-number">3</div>
+                                        <div class="step-content">
+                                            <h4>Integration Testing <span class="agent-highlight">integration-specialist</span></h4>
+                                            <p>Set up proper error handling and monitoring.</p>
+                                            <div class="step-command">
+                                                <span class="command-prompt">></span> "Have integration-specialist add proper error handling, retry logic, and monitoring to the API"
+                                            </div>
+                                        </div>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Debugging Scenarios -->
+                <div id="debugging-scenario" class="scenario-content">
+                    <div class="workflow-container">
+                        <div class="workflow">
+                            <div class="workflow-header">
+                                <div class="workflow-icon">🐛</div>
+                                <div>
+                                    <div class="workflow-title">Systematic Bug Investigation</div>
+                                    <div class="workflow-subtitle">From symptoms to root cause to solution</div>
+                                </div>
+                            </div>
+                            <div class="workflow-body">
+                                <div class="real-world-example">
+                                    <h4>🎯 Real Bug Hunt: "Login timeouts affecting 30% of users since yesterday"</h4>
+                                    <p>A classic production issue - sudden onset, affects some users but not others, timing suggests recent change. Let's hunt it down systematically.</p>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 1: Initial Triage & Information Gathering</h4>
+                                    <p>Start with bug-hunter to systematically analyze symptoms:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Use bug-hunter to investigate login timeout errors. Issue started yesterday, affects 30% of login attempts. Users report seeing 'Connection timeout' after 10 seconds. Some users can login fine, others consistently fail."
+                                    </div>
+                                    <div class="expected-output">
+                                        <h5>✅ What bug-hunter will analyze:</h5>
+                                        • Pattern analysis (affected vs unaffected users)<br>
+                                        • Timing correlation with recent deployments<br>
+                                        • Error frequency and distribution<br>
+                                        • Hypothesis generation for likely causes<br>
+                                        • Investigation plan with priorities
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 2: Performance Deep Dive</h4>
+                                    <p>Check if performance degradation is the culprit:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Have performance-optimizer analyze the login flow end-to-end. Check database query times, external service calls, and identify any bottlenecks that could cause 10-second timeouts."
+                                    </div>
+                                    <div class="expected-output">
+                                        <h5>✅ What performance-optimizer will check:</h5>
+                                        • Database query execution times<br>
+                                        • External API response times (auth services)<br>
+                                        • Memory and CPU usage patterns<br>
+                                        • Connection pool exhaustion<br>
+                                        • Performance regression analysis
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 3: Database Investigation</h4>
+                                    <p>Database issues are a common culprit for intermittent timeouts:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Use database-architect to investigate authentication database queries. Check for missing indexes, query plan changes, lock contention, or connection pool issues that could cause intermittent timeouts."
+                                    </div>
+                                    <div class="expected-output">
+                                        <h5>✅ What database-architect will examine:</h5>
+                                        • Query execution plans and index usage<br>
+                                        • Database locks and blocking sessions<br>
+                                        • Connection pool configuration and usage<br>
+                                        • Recent schema changes or data growth<br>
+                                        • Database server resource utilization
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 4: Knowledge Base Search</h4>
+                                    <p>Check if we've seen similar issues before:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Use content-researcher to search our knowledge base for previous login timeout issues, authentication problems, and database performance fixes. Look for patterns and solutions we've used before."
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 5: Implement & Test Fix</h4>
+                                    <p>Once root cause is identified, implement the solution:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Have modular-builder implement the login timeout fix with proper error handling, retry logic, and monitoring. Include graceful degradation and user-friendly error messages."
+                                    </div>
+                                </div>
+
+                                <div class="troubleshooting">
+                                    <h5>🚨 Common Login Timeout Causes</h5>
+                                    <ul>
+                                        <li><strong>Database connection pool exhaustion:</strong> Too many concurrent requests</li>
+                                        <li><strong>Missing database indexes:</strong> Queries getting slower as data grows</li>
+                                        <li><strong>External auth service issues:</strong> Third-party API degradation</li>
+                                        <li><strong>Memory leaks:</strong> Application consuming too much memory</li>
+                                        <li><strong>Network issues:</strong> Increased latency or packet loss</li>
+                                    </ul>
+                                </div>
+                            </div>
+                        </div>
+
+                        <!-- Security Issue Response -->
+                        <div class="workflow">
+                            <div class="workflow-header">
+                                <div class="workflow-icon">🔒</div>
+                                <div>
+                                    <div class="workflow-title">Security Incident Response</div>
+                                    <div class="workflow-subtitle">Systematic security vulnerability handling</div>
+                                </div>
+                            </div>
+                            <div class="workflow-body">
+                                <div class="real-world-example">
+                                    <h4>🎯 Security Alert: Potential SQL Injection in User Search</h4>
+                                    <p>Security scanner flagged possible SQL injection vulnerability in user search functionality. Need immediate assessment and remediation.</p>
+                                </div>
+
+                                <div class="command-sequence">
+                                    <h5>📋 Immediate Response Protocol</h5>
+                                    <div class="command-line"><span class="comment"># Phase 1: Assessment (URGENT)</span></div>
+                                    <div class="command-line"><span class="prompt">1.</span> <span class="command">"Have security-guardian perform immediate security assessment of the user search functionality. Check for SQL injection, XSS, and other OWASP Top 10 vulnerabilities."</span></div>
+                                    <div class="command-line"><span class="comment"># Phase 2: Historical Analysis</span></div>
+                                    <div class="command-line"><span class="prompt">2.</span> <span class="command">"Use content-researcher to find previous SQL injection fixes and security patches in our codebase for similar patterns."</span></div>
+                                    <div class="command-line"><span class="comment"># Phase 3: Impact Analysis</span></div>
+                                    <div class="command-line"><span class="prompt">3.</span> <span class="command">"Have database-architect analyze what data could be exposed if the SQL injection vulnerability is exploited."</span></div>
+                                    <div class="command-line"><span class="comment"># Phase 4: Secure Implementation</span></div>
+                                    <div class="command-line"><span class="prompt">4.</span> <span class="command">"Have modular-builder implement secure parameterized queries and input validation for all search functionality."</span></div>
+                                </div>
+
+                                <div class="collapsible-section">
+                                    <div class="collapsible-header" onclick="toggleCollapsible(this)">
+                                        <h4>Detailed Security Assessment Steps</h4>
+                                        <span>+</span>
+                                    </div>
+                                    <div class="collapsible-content">
+                                        <div class="step-detail">
+                                            <h4>Vulnerability Verification</h4>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                                "Security-guardian: Test the user search with these payloads to confirm vulnerability: [basic SQL injection tests]. Check if any of these return unexpected data or error messages."
+                                            </div>
+                                        </div>
+
+                                        <div class="step-detail">
+                                            <h4>Code Review & Pattern Analysis</h4>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                                "Security-guardian: Review all database query patterns in the codebase. Identify any other locations using string concatenation instead of parameterized queries."
+                                            </div>
+                                        </div>
+
+                                        <div class="step-detail">
+                                            <h4>Data Exposure Assessment</h4>
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                                "Database-architect: Map out all tables accessible through the vulnerable query path. Identify sensitive data (PII, credentials, financial) that could be exposed."
+                                            </div>
+                                        </div>
+                                    </div>
+                                </div>
+
+                                <div class="verification-steps">
+                                    <h5>🧪 Security Fix Verification</h5>
+                                    <ol>
+                                        <li><strong>Automated Testing:</strong> Run security scanner again to confirm fix</li>
+                                        <li><strong>Manual Penetration Testing:</strong> Test with various SQL injection payloads</li>
+                                        <li><strong>Code Review:</strong> Verify all queries use parameterized statements</li>
+                                        <li><strong>Input Validation:</strong> Test with malicious input patterns</li>
+                                        <li><strong>Error Handling:</strong> Ensure no sensitive info in error messages</li>
+                                    </ol>
+                                </div>
+
+                                <div class="troubleshooting">
+                                    <h5>🚨 Security Incident Checklist</h5>
+                                    <ul>
+                                        <li><strong>Document everything:</strong> Keep detailed logs of assessment and fixes</li>
+                                        <li><strong>Notify stakeholders:</strong> Inform security team and management</li>
+                                        <li><strong>Check for exploitation:</strong> Review logs for attack attempts</li>
+                                        <li><strong>Update security policies:</strong> Learn from the incident</li>
+                                        <li><strong>Implement monitoring:</strong> Add alerts for similar attack patterns</li>
+                                    </ul>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Knowledge-Driven Scenarios -->
+                <div id="knowledge-scenario" class="scenario-content">
+                    <div class="workflow-container">
+                        <!-- Knowledge-Driven Development -->
+                        <div class="workflow">
+                            <div class="workflow-header">
+                                <div class="workflow-icon">🧠</div>
+                                <div>
+                                    <div class="workflow-title">Knowledge-Driven Development</div>
+                                    <div class="workflow-subtitle">Transform documentation into actionable intelligence</div>
+                                </div>
+                            </div>
+                            <div class="workflow-body">
+                                <div class="copy-paste-banner">
+                                    <h3>📚 From Docs to Intelligence in 3 Commands</h3>
+                                    <p>Turn your scattered documentation into a queryable knowledge base that guides development decisions.</p>
+                                    <div class="quick-start-commands">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy All</button>
+                                        <div>make knowledge-update</div>
+                                        <div>make knowledge-query Q="authentication patterns"</div>
+                                        <div>make knowledge-export FORMAT=markdown</div>
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 1: Extract Knowledge from Documentation</h4>
+                                    <p>Process all your docs, README files, and code comments into structured knowledge:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        make knowledge-update
+                                    </div>
+                                    <div class="expected-output">
+                                        <h5>✅ What gets processed:</h5>
+                                        • All Markdown files in docs/, README.md, and subdirectories<br>
+                                        • Code comments and docstrings<br>
+                                        • API specifications and architectural decisions<br>
+                                        • Issue descriptions and pull request discussions<br>
+                                        • Configuration files and deployment guides
+                                    </div>
+                                    <div class="verification-steps">
+                                        <h5>🧪 Verify Processing</h5>
+                                        <div class="code-block">
+                                            <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                            # Check what was processed
+                                            ls .data/knowledge/  # Should see extracted concepts
+                                            make knowledge-stats # Shows processing summary
+                                        </div>
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 2: Query Your Knowledge Base</h4>
+                                    <p>Ask specific questions to get targeted insights:</p>
+                                    <div class="command-sequence">
+                                        <h5>📋 Example Queries (Copy Any)</h5>
+                                        <div class="command-line"><span class="command">make knowledge-query Q="error handling patterns"</span> <span class="comment"># Find error handling approaches</span></div>
+                                        <div class="command-line"><span class="command">make knowledge-query Q="database migration strategies"</span> <span class="comment"># Schema evolution patterns</span></div>
+                                        <div class="command-line"><span class="command">make knowledge-query Q="authentication implementation"</span> <span class="comment"># Auth system designs</span></div>
+                                        <div class="command-line"><span class="command">make knowledge-query Q="performance optimization"</span> <span class="comment"># Speed improvement techniques</span></div>
+                                        <div class="command-line"><span class="command">make knowledge-query Q="testing strategies"</span> <span class="comment"># Test approaches and patterns</span></div>
+                                    </div>
+                                    <div class="expected-output">
+                                        <h5>✅ Query results include:</h5>
+                                        • Relevant concepts and their relationships<br>
+                                        • Code examples and implementation patterns<br>
+                                        • Design decisions with rationale<br>
+                                        • Links to source documents<br>
+                                        • Related concepts and alternatives
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 3: Apply Knowledge with Agents</h4>
+                                    <p>Use insights to guide implementation decisions:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Use insight-synthesizer to apply the error handling patterns from our knowledge base to the new payment processing module. Focus on retry strategies and circuit breaker patterns."
+                                    </div>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Have content-researcher find all authentication-related patterns in our knowledge base and suggest the best approach for implementing OAuth 2.0 integration."
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 4: Document New Learnings</h4>
+                                    <p>Capture new insights for future reference:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        # Document what you learned
+                                        echo "## Payment Processing Lessons\n\n- Stripe webhooks require idempotency keys\n- Always validate webhook signatures\n- Use exponential backoff for retries" >> docs/lessons-learned.md
+
+                                        # Update knowledge base
+                                        make knowledge-update
+                                    </div>
+                                </div>
+
+                                <div class="troubleshooting">
+                                    <h5>🚨 Knowledge Base Issues</h5>
+                                    <ul>
+                                        <li><strong>No results from queries:</strong> Run <code>make knowledge-update</code> first to process docs</li>
+                                        <li><strong>Outdated information:</strong> Re-run knowledge update after doc changes</li>
+                                        <li><strong>Irrelevant results:</strong> Make queries more specific ("React authentication" vs "authentication")</li>
+                                        <li><strong>Processing errors:</strong> Check .data/knowledge/ for error logs</li>
+                                    </ul>
+                                </div>
+                            </div>
+                        </div>
+
+                        <!-- Research and Discovery -->
+                        <div class="workflow">
+                            <div class="workflow-header">
+                                <div class="workflow-icon">🔍</div>
+                                <div>
+                                    <div class="workflow-title">Deep Research & Discovery</div>
+                                    <div class="workflow-subtitle">Uncover hidden connections and insights</div>
+                                </div>
+                            </div>
+                            <div class="workflow-body">
+                                <div class="real-world-example">
+                                    <h4>🎯 Discovery Mission: "Why do our microservices keep having the same problems?"</h4>
+                                    <p>Use knowledge archaeology and concept extraction to identify recurring patterns and systemic issues across your architecture.</p>
+                                </div>
+
+                                <div class="collapsible-section">
+                                    <div class="collapsible-header" onclick="toggleCollapsible(this)">
+                                        <h4>Phase 1: Concept Extraction from System Documentation</h4>
+                                        <span>+</span>
+                                    </div>
+                                    <div class="collapsible-content">
+                                        <div class="code-block">
+                                            <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                            "Use concept-extractor to analyze all our microservice documentation, incident reports, and architectural decision records. Extract recurring concepts, failure patterns, and design decisions."
+                                        </div>
+                                        <div class="expected-output">
+                                            <h5>✅ Concepts identified might include:</h5>
+                                            • Service communication patterns (sync vs async)<br>
+                                            • Failure modes and recovery strategies<br>
+                                            • Data consistency approaches<br>
+                                            • Deployment and scaling patterns<br>
+                                            • Monitoring and observability strategies
+                                        </div>
+                                    </div>
+                                </div>
+
+                                <div class="collapsible-section">
+                                    <div class="collapsible-header" onclick="toggleCollapsible(this)">
+                                        <h4>Phase 2: Connection Discovery</h4>
+                                        <span>+</span>
+                                    </div>
+                                    <div class="collapsible-content">
+                                        <div class="code-block">
+                                            <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                            "Have insight-synthesizer find hidden connections between our service failures, deployment patterns, and team organization. Look for correlations we might have missed."
+                                        </div>
+                                        <div class="code-block">
+                                            <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                            "Use pattern-emergence to identify system-level patterns from our incident reports. What commonalities exist across different service failures?"
+                                        </div>
+                                    </div>
+                                </div>
+
+                                <div class="collapsible-section">
+                                    <div class="collapsible-header" onclick="toggleCollapsible(this)">
+                                        <h4>Phase 3: Evolution Analysis</h4>
+                                        <span>+</span>
+                                    </div>
+                                    <div class="collapsible-content">
+                                        <div class="code-block">
+                                            <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                            "Use knowledge-archaeologist to trace how our microservice architecture evolved. Which decisions led to current pain points? What alternatives were considered but abandoned?"
+                                        </div>
+                                        <div class="expected-output">
+                                            <h5>✅ Evolutionary insights:</h5>
+                                            • Decision timeline and rationale<br>
+                                            • Abandoned approaches and why<br>
+                                            • Evolution of complexity over time<br>
+                                            • Recurring decision points<br>
+                                            • Lessons from architecture changes
+                                        </div>
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 4: Synthesis & Actionable Insights</h4>
+                                    <p>Turn discoveries into concrete improvements:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Have insight-synthesizer create an actionable improvement plan based on the discovered patterns. Focus on the top 3 recurring issues and practical solutions."
+                                    </div>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Use visualization-architect to create a visual map of the discovered connections and patterns for team discussion and planning."
+                                    </div>
+                                </div>
+
+                                <div class="verification-steps">
+                                    <h5>🧪 Research Validation</h5>
+                                    <ol>
+                                        <li><strong>Pattern Verification:</strong> Validate discovered patterns with team members</li>
+                                        <li><strong>Historical Accuracy:</strong> Cross-check findings with incident timelines</li>
+                                        <li><strong>Actionability:</strong> Ensure insights lead to concrete next steps</li>
+                                        <li><strong>Documentation:</strong> Capture discoveries in architectural decision records</li>
+                                    </ol>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Optimization Scenarios -->
+                <div id="optimization-scenario" class="scenario-content">
+                    <div class="workflow-container">
+                        <div class="workflow">
+                            <div class="workflow-header">
+                                <div class="workflow-icon">⚡</div>
+                                <div>
+                                    <div class="workflow-title">Performance Optimization</div>
+                                    <div class="workflow-subtitle">Data-driven approach to eliminating bottlenecks</div>
+                                </div>
+                            </div>
+                            <div class="workflow-body">
+                                <div class="real-world-example">
+                                    <h4>🎯 Performance Crisis: "Checkout takes 15+ seconds, users are abandoning carts"</h4>
+                                    <p>E-commerce site seeing 40% cart abandonment during checkout. Need systematic performance analysis and optimization.</p>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 1: Performance Profiling & Baseline</h4>
+                                    <p>Get concrete data on where time is being spent:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Use performance-optimizer to profile the entire checkout flow. Measure database query times, API response times, and frontend rendering. Identify the top 5 bottlenecks by impact."
+                                    </div>
+                                    <div class="expected-output">
+                                        <h5>✅ Performance analysis will show:</h5>
+                                        • Request timeline with precise timing breakdown<br>
+                                        • Database queries ranked by execution time<br>
+                                        • External API calls and their response times<br>
+                                        • Memory usage and potential leaks<br>
+                                        • Frontend performance metrics and bottlenecks
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 2: Database Query Optimization</h4>
+                                    <p>Often the biggest performance wins come from database optimization:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Have database-architect analyze all checkout-related queries. Focus on the product inventory check, payment processing, and order creation queries. Add indexes and optimize query plans."
+                                    </div>
+                                    <div class="command-sequence">
+                                        <h5>📋 Common Database Optimizations</h5>
+                                        <div class="command-line"><span class="comment"># Check current performance</span></div>
+                                        <div class="command-line"><span class="command">"Database-architect: Show query execution plans for checkout process"</span></div>
+                                        <div class="command-line"><span class="comment"># Optimize slow queries</span></div>
+                                        <div class="command-line"><span class="command">"Add indexes for inventory.product_id, orders.user_id, payments.status"</span></div>
+                                        <div class="command-line"><span class="comment"># Connection pool tuning</span></div>
+                                        <div class="command-line"><span class="command">"Optimize database connection pool size for checkout load"</span></div>
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 3: Caching Strategy Implementation</h4>
+                                    <p>Add strategic caching to reduce repeated expensive operations:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Have modular-builder implement a multi-tier caching strategy: Redis for session data, application-level cache for product info, and CDN for static assets. Focus on checkout flow optimization."
+                                    </div>
+                                    <div class="collapsible-section">
+                                        <div class="collapsible-header" onclick="toggleCollapsible(this)">
+                                            <h4>Detailed Caching Implementation</h4>
+                                            <span>+</span>
+                                        </div>
+                                        <div class="collapsible-content">
+                                            <div class="code-block">
+                                                <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                                # Session & Cart Caching
+                                                "Cache user cart contents in Redis with 1-hour TTL"
+                                                "Implement cart persistence across browser sessions"
+
+                                                # Product Information Caching
+                                                "Cache product details and pricing for 10 minutes"
+                                                "Use cache warming for popular products"
+
+                                                # Payment & Inventory Caching
+                                                "Cache inventory counts with real-time invalidation"
+                                                "Implement payment method validation caching"
+                                            </div>
+                                        </div>
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 4: Frontend Performance Optimization</h4>
+                                    <p>Optimize the user experience with frontend improvements:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Use performance-optimizer to analyze frontend checkout performance. Implement lazy loading, optimize bundle sizes, and add progressive loading indicators."
+                                    </div>
+                                    <div class="expected-output">
+                                        <h5>✅ Frontend optimizations:</h5>
+                                        • Bundle size reduction through code splitting<br>
+                                        • Progressive loading with skeleton screens<br>
+                                        • Image optimization and lazy loading<br>
+                                        • Critical CSS inlining<br>
+                                        • Service worker for caching static assets
+                                    </div>
+                                </div>
+
+                                <div class="step-detail">
+                                    <h4>Step 5: Performance Testing & Monitoring</h4>
+                                    <p>Ensure optimizations work and stay optimized:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                        "Deploy test-coverage to add performance tests for checkout flow. Include load testing scenarios, response time assertions, and performance regression detection."
+                                    </div>
+                                    <div class="verification-steps">
+                                        <h5>🧪 Performance Verification</h5>
+                                        <ol>
+                                            <li><strong>Baseline Comparison:</strong> Measure before/after performance</li>
+                                            <li><strong>Load Testing:</strong> Test with 100+ concurrent users</li>
+                                            <li><strong>Real User Monitoring:</strong> Track actual user experience</li>
+                                            <li><strong>Alerting:</strong> Set up alerts for performance degradation</li>
+                                        </ol>
+                                    </div>
+                                </div>
+
+                                <div class="troubleshooting">
+                                    <h5>🚨 Common Performance Optimization Pitfalls</h5>
+                                    <ul>
+                                        <li><strong>Premature optimization:</strong> Optimize based on data, not assumptions</li>
+                                        <li><strong>Cache invalidation issues:</strong> Stale data causing user confusion</li>
+                                        <li><strong>Over-caching:</strong> Memory usage growing out of control</li>
+                                        <li><strong>Database index bloat:</strong> Too many indexes slowing writes</li>
+                                        <li><strong>Network latency ignored:</strong> Focusing only on server performance</li>
+                                    </ul>
+                                </div>
+                            </div>
+                        </div>
+
+                        <!-- Advanced Performance Techniques -->
+                        <div class="workflow">
+                            <div class="workflow-header">
+                                <div class="workflow-icon">📈</div>
+                                <div>
+                                    <div class="workflow-title">Advanced Performance Engineering</div>
+                                    <div class="workflow-subtitle">Scaling and optimization at enterprise level</div>
+                                </div>
+                            </div>
+                            <div class="workflow-body">
+                                <div class="command-sequence">
+                                    <h5>📋 Enterprise Performance Workflow</h5>
+                                    <div class="command-line"><span class="comment"># Multi-agent performance analysis</span></div>
+                                    <div class="command-line"><span class="prompt">1.</span> <span class="command">"Use performance-optimizer to establish comprehensive performance baselines across all services"</span></div>
+                                    <div class="command-line"><span class="prompt">2.</span> <span class="command">"Have database-architect design sharding strategy for high-volume tables"</span></div>
+                                    <div class="command-line"><span class="prompt">3.</span> <span class="command">"Use integration-specialist to optimize microservice communication patterns"</span></div>
+                                    <div class="command-line"><span class="prompt">4.</span> <span class="command">"Have zen-architect design auto-scaling architecture with predictive scaling"</span></div>
+                                    <div class="command-line"><span class="comment"># Continuous optimization loop</span></div>
+                                    <div class="command-line"><span class="prompt">5.</span> <span class="command">"Deploy test-coverage to add automated performance regression testing"</span></div>
+                                    <div class="command-line"><span class="prompt">6.</span> <span class="command">"Use visualization-architect to create performance dashboards and alerts"</span></div>
+                                </div>
+
+                                <div class="collapsible-section">
+                                    <div class="collapsible-header" onclick="toggleCollapsible(this)">
+                                        <h4>Scaling Strategy: Handling 10x Growth</h4>
+                                        <span>+</span>
+                                    </div>
+                                    <div class="collapsible-content">
+                                        <div class="real-world-example">
+                                            <h4>Scenario: Black Friday Traffic Spike</h4>
+                                            <p>Prepare system to handle 10x normal traffic during peak shopping events. Need automatic scaling, graceful degradation, and zero downtime.</p>
+                                        </div>
+                                        <div class="code-block">
+                                            <button class="copy-btn" onclick="copyCode(this)">📋 Copy</button>
+                                            "Use zen-architect to design auto-scaling architecture that can handle 10x traffic spikes. Include circuit breakers, graceful degradation, and automatic failover mechanisms."
+                                        </div>
+                                        <p><strong>Key scaling components:</strong></p>
+                                        <ul>
+                                            <li>Horizontal auto-scaling based on metrics</li>
+                                            <li>Database read replicas and connection pooling</li>
+                                            <li>CDN and edge caching for static content</li>
+                                            <li>Queue-based async processing for non-critical tasks</li>
+                                            <li>Circuit breakers for external service calls</li>
+                                        </ul>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Parallel Development Scenarios -->
+                <div id="parallel-scenario" class="scenario-content">
+                    <div class="workflow-container">
+                        <div class="workflow">
+                            <div class="workflow-header">
+                                <div class="workflow-icon">🌳</div>
+                                <div>
+                                    <div class="workflow-title">Parallel Development</div>
+                                    <div class="workflow-subtitle">Explore multiple approaches simultaneously</div>
+                                </div>
+                            </div>
+                            <div class="workflow-body">
+                                <p style="color: var(--text-secondary); margin-bottom: 2rem; line-height: 1.6;">
+                                    Stop wondering "what if" — build multiple solutions simultaneously and pick the winner.
+                                    Each worktree is completely isolated with its own branch, environment, and context.
+                                </p>
+
+                                <div class="parallel-demo">
+                                    <h4>Example: Authentication System Comparison</h4>
+                                    <div class="terminal-session">
+                                        <div><span class="command-prompt">$</span> <span class="command">make worktree feature-jwt</span></div>
+                                        <div class="comment"># Creates isolated JWT authentication approach</div><br>
+
+                                        <div><span class="command-prompt">$</span> <span class="command">make worktree feature-oauth</span></div>
+                                        <div class="comment"># Creates parallel OAuth 2.0 approach</div><br>
+
+                                        <div><span class="command-prompt">$</span> <span class="command">make worktree feature-session</span></div>
+                                        <div class="comment"># Creates third approach with session-based auth</div><br>
+
+                                        <div><span class="command-prompt">$</span> <span class="command">make worktree-list</span></div>
+                                        <div class="comment"># Compare all approaches</div>
+                                        <div class="output">
+                                        • main (current)
+                                        • feature-jwt (JWT tokens + refresh)
+                                        • feature-oauth (OAuth 2.0 + PKCE)
+                                        • feature-session (server sessions + Redis)
+                                        </div>
+                                    </div>
+                                </div>
+
+                                <div class="workflow-steps">
+                                    <div class="workflow-step">
+                                        <div class="step-number">1</div>
+                                        <div class="step-content">
+                                            <h4>Create Parallel Branches</h4>
+                                            <p>Set up isolated environments for each approach.</p>
+                                            <div class="step-command">
+                                                make worktree approach-1<br>
+                                                make worktree approach-2<br>
+                                                make worktree approach-3
+                                            </div>
+                                        </div>
+                                    </div>
+                                    <div class="workflow-step">
+                                        <div class="step-number">2</div>
+                                        <div class="step-content">
+                                            <h4>Develop in Parallel</h4>
+                                            <p>Use different agents or approaches in each worktree.</p>
+                                            <div class="step-command">
+                                                <span class="command-prompt">Worktree 1:</span> "Use zen-architect for microservices approach"<br>
+                                                <span class="command-prompt">Worktree 2:</span> "Use modular-builder for monolithic approach"<br>
+                                                <span class="command-prompt">Worktree 3:</span> "Use api-contract-designer for serverless approach"
+                                            </div>
+                                        </div>
+                                    </div>
+                                    <div class="workflow-step">
+                                        <div class="step-number">3</div>
+                                        <div class="step-content">
+                                            <h4>Compare and Evaluate</h4>
+                                            <p>Test and compare all approaches to find the best solution.</p>
+                                            <div class="step-command">
+                                                make worktree-list  # Review all approaches<br>
+                                                <span class="command-prompt">></span> "Compare the performance and maintainability of all three approaches"
+                                            </div>
+                                        </div>
+                                    </div>
+                                    <div class="workflow-step">
+                                        <div class="step-number">4</div>
+                                        <div class="step-content">
+                                            <h4>Choose and Clean Up</h4>
+                                            <p>Select the best approach and remove the others.</p>
+                                            <div class="step-command">
+                                                git merge feature-jwt  # Merge the winning approach<br>
+                                                make worktree-rm approach-2<br>
+                                                make worktree-rm approach-3
+                                            </div>
+                                        </div>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </section>
+
+        <!-- Quick Reference -->
+        <section class="section section-alt">
+            <div class="container">
+                <h2 class="section-title">Quick Reference Commands</h2>
+                <div class="quick-examples">
+                    <div class="quick-example">
+                        <h4>🏗️ Architecture & Design</h4>
+                        <div class="command">"Use zen-architect to design my user management system"</div>
+                    </div>
+                    <div class="quick-example">
+                        <h4>🐛 Bug Investigation</h4>
+                        <div class="command">"Deploy bug-hunter to find why login is failing"</div>
+                    </div>
+                    <div class="quick-example">
+                        <h4>🔒 Security Review</h4>
+                        <div class="command">"Have security-guardian audit my API endpoints"</div>
+                    </div>
+                    <div class="quick-example">
+                        <h4>⚡ Performance Optimization</h4>
+                        <div class="command">"Use performance-optimizer to speed up database queries"</div>
+                    </div>
+                    <div class="quick-example">
+                        <h4>📝 API Design</h4>
+                        <div class="command">"Have api-contract-designer create REST endpoints for orders"</div>
+                    </div>
+                    <div class="quick-example">
+                        <h4>🧪 Testing</h4>
+                        <div class="command">"Deploy test-coverage to add comprehensive test suite"</div>
+                    </div>
+                    <div class="quick-example">
+                        <h4>🧠 Knowledge Query</h4>
+                        <div class="command">make knowledge-query Q="authentication patterns"</div>
+                    </div>
+                    <div class="quick-example">
+                        <h4>🌳 Parallel Development</h4>
+                        <div class="command">make worktree feature-name</div>
+                    </div>
+                </div>
+            </div>
+        </section>
+
+        <!-- Pro Tips -->
+        <section class="section">
+            <div class="container">
+                <h2 class="section-title">Pro Tips</h2>
+                <div class="tips-grid">
+                    <div class="tip-item">
+                        <div class="tip-icon">🎯</div>
+                        <h4>Be Specific</h4>
+                        <p>The more specific your request, the better the agent can help. Include context about your goals, constraints, and requirements.</p>
+                    </div>
+                    <div class="tip-item">
+                        <div class="tip-icon">🔄</div>
+                        <h4>Chain Agents</h4>
+                        <p>Use multiple agents in sequence. Start with zen-architect for design, then modular-builder for implementation, then test-coverage for testing.</p>
+                    </div>
+                    <div class="tip-item">
+                        <div class="tip-icon">📚</div>
+                        <h4>Build Knowledge</h4>
+                        <p>Regularly run 'make knowledge-update' to keep your knowledge base current. The more knowledge you have, the better the insights.</p>
+                    </div>
+                    <div class="tip-item">
+                        <div class="tip-icon">🌟</div>
+                        <h4>Experiment Freely</h4>
+                        <p>Use parallel worktrees to try different approaches without risk. You can always discard experiments that don't work out.</p>
+                    </div>
+                    <div class="tip-item">
+                        <div class="tip-icon">🔍</div>
+                        <h4>Leverage Context</h4>
+                        <p>Agents have access to your entire codebase context. They can understand existing patterns and maintain consistency.</p>
+                    </div>
+                    <div class="tip-item">
+                        <div class="tip-icon">⚡</div>
+                        <h4>Iterate Quickly</h4>
+                        <p>Don't try to solve everything at once. Use agents for focused tasks and iterate based on results.</p>
+                    </div>
+                </div>
+            </div>
+        </section>
+    </main>
+
+    <footer class="footer">
+        <div class="container">
+            <div class="footer-content">
+                <div class="footer-brand">
+                    <h3>Amplifier</h3>
+                    <p>Supercharged AI Development Environment</p>
+                </div>
+                <div class="footer-links">
+                    <div class="footer-column">
+                        <h4>Documentation</h4>
+                        <a href="setup.html">Setup Guide</a>
+                        <a href="agents.html">Agent Catalog</a>
+                        <a href="knowledge.html">Knowledge Base</a>
+                        <a href="examples.html">Examples</a>
+                    </div>
+                    <div class="footer-column">
+                        <h4>Resources</h4>
+                        <a href="https://github.com/microsoft/amplifier">GitHub</a>
+                        <a href="../AMPLIFIER_VISION.md">Vision</a>
+                        <a href="../README.md">README</a>
+                    </div>
+                </div>
+            </div>
+            <div class="footer-bottom">
+                <p>&copy; 2024 Microsoft. Licensed under MIT.</p>
+            </div>
+        </div>
+    </footer>
+
+    <script src="script.js"></script>
+    <script>
+        function showScenario(scenario, buttonElement) {
+            // Hide all scenario contents
+            document.querySelectorAll('.scenario-content').forEach(content => {
+                content.classList.remove('active');
+            });
+
+            // Remove active class from all tabs
+            document.querySelectorAll('.scenario-tab').forEach(tab => {
+                tab.classList.remove('active');
+            });
+
+            // Show selected scenario
+            const targetScenario = document.getElementById(scenario + '-scenario');
+            if (targetScenario) {
+                targetScenario.classList.add('active');
+            }
+
+            // Mark tab as active
+            const button = buttonElement || event?.target;
+            if (button) {
+                button.classList.add('active');
+            }
+        }
+
+        function showDifficulty(difficultyId, buttonElement) {
+            // Get the parent workflow body to scope the changes
+            const workflowBody = buttonElement.closest('.workflow-body');
+            if (!workflowBody) return;
+
+            // Hide all difficulty contents within this workflow
+            workflowBody.querySelectorAll('.difficulty-content').forEach(content => {
+                content.classList.remove('active');
+            });
+
+            // Remove active class from all difficulty buttons within this workflow
+            workflowBody.querySelectorAll('.difficulty-btn').forEach(btn => {
+                btn.classList.remove('active');
+            });
+
+            // Show selected difficulty content
+            const targetContent = document.getElementById(difficultyId);
+            if (targetContent) {
+                targetContent.classList.add('active');
+            }
+
+            // Mark button as active
+            buttonElement.classList.add('active');
+        }
+
+        function toggleCollapsible(headerElement) {
+            const section = headerElement.parentElement;
+            const content = section.querySelector('.collapsible-content');
+            const toggleIcon = headerElement.querySelector('span');
+
+            if (content.classList.contains('active')) {
+                content.classList.remove('active');
+                toggleIcon.textContent = '+';
+            } else {
+                content.classList.add('active');
+                toggleIcon.textContent = '−';
+            }
+        }
+
+        function copyCode(button) {
+            // Find the code content - could be in various structures
+            let codeText = '';
+            const parent = button.parentElement;
+
+            // Try different selectors based on the HTML structure
+            const codeElement = parent.querySelector('code') ||
+                               parent.querySelector('.command') ||
+                               parent.querySelector('pre') ||
+                               parent;
+
+            if (codeElement) {
+                // Get text content, excluding the button
+                const tempButton = codeElement.querySelector('.copy-btn');
+                if (tempButton) {
+                    tempButton.style.display = 'none';
+                }
+                codeText = codeElement.textContent.trim();
+                if (tempButton) {
+                    tempButton.style.display = '';
+                }
+            }
+
+            // Copy to clipboard
+            if (navigator.clipboard && codeText) {
+                navigator.clipboard.writeText(codeText).then(() => {
+                    const originalText = button.textContent;
+                    button.textContent = 'Copied!';
+                    button.style.background = 'rgba(16, 185, 129, 0.8)';
+                    setTimeout(() => {
+                        button.textContent = originalText;
+                        button.style.background = '';
+                    }, 2000);
+                }).catch(err => {
+                    console.error('Failed to copy: ', err);
+                    // Fallback for older browsers
+                    fallbackCopyTextToClipboard(codeText, button);
+                });
+            } else {
+                // Fallback for older browsers
+                fallbackCopyTextToClipboard(codeText, button);
+            }
+        }
+
+        function fallbackCopyTextToClipboard(text, button) {
+            const textArea = document.createElement('textarea');
+            textArea.value = text;
+            document.body.appendChild(textArea);
+            textArea.focus();
+            textArea.select();
+
+            try {
+                const successful = document.execCommand('copy');
+                if (successful) {
+                    const originalText = button.textContent;
+                    button.textContent = 'Copied!';
+                    setTimeout(() => {
+                        button.textContent = originalText;
+                    }, 2000);
+                }
+            } catch (err) {
+                console.error('Fallback copy failed: ', err);
+            }
+
+            document.body.removeChild(textArea);
+        }
+
+        // Initialize all copy buttons when page loads
+        document.addEventListener('DOMContentLoaded', function() {
+            // Set up intersection observer for animations
+            const observerOptions = {
+                threshold: 0.1,
+                rootMargin: '0px 0px -50px 0px'
+            };
+
+            const observer = new IntersectionObserver((entries) => {
+                entries.forEach(entry => {
+                    if (entry.isIntersecting) {
+                        entry.target.style.opacity = '1';
+                        entry.target.style.transform = 'translateY(0)';
+                    }
+                });
+            }, observerOptions);
+
+            // Observe workflow elements for animation
+            const animatedElements = document.querySelectorAll('.workflow, .step-detail, .real-world-example');
+            animatedElements.forEach(el => {
+                el.style.opacity = '0';
+                el.style.transform = 'translateY(20px)';
+                el.style.transition = 'opacity 0.6s ease, transform 0.6s ease';
+                observer.observe(el);
+            });
+        });
+    </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/instructor/index.html b/instructor/index.html
new file mode 100644
index 00000000..116c4874
--- /dev/null
+++ b/instructor/index.html
@@ -0,0 +1,361 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Amplifier - Supercharged AI Development Environment</title>
+    <link rel="stylesheet" href="styles.css">
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+</head>
+<body>
+    <header class="header">
+        <nav class="nav">
+            <div class="nav-brand">
+                <h1>Amplifier</h1>
+                <span class="tagline">Supercharged AI Development</span>
+            </div>
+            <div class="nav-links">
+                <a href="#overview" class="nav-link">Overview</a>
+                <a href="#features" class="nav-link">Features</a>
+                <a href="#agents" class="nav-link">Agents</a>
+                <a href="#setup" class="nav-link">Setup</a>
+                <a href="#examples" class="nav-link">Examples</a>
+                <a href="knowledge.html" class="nav-link">Knowledge Base</a>
+            </div>
+            <div class="nav-mobile">
+                <button class="mobile-menu-btn" onclick="toggleMobileMenu()">☰</button>
+            </div>
+        </nav>
+    </header>
+
+    <main>
+        <!-- Hero Section -->
+        <section class="hero">
+            <div class="hero-content">
+                <h1 class="hero-title">Turn AI Assistants into Force Multipliers</h1>
+                <p class="hero-subtitle">A complete development environment that supercharges AI coding assistants with discovered patterns, specialized expertise, and powerful automation.</p>
+                <div class="hero-actions">
+                    <a href="#setup" class="btn btn-primary">Get Started</a>
+                    <a href="https://github.com/microsoft/amplifier" class="btn btn-secondary">View on GitHub</a>
+                </div>
+                <div class="hero-quote">
+                    <blockquote>"I have more ideas than time to try them out" — The problem we're solving</blockquote>
+                </div>
+            </div>
+            <div class="hero-visual">
+                <div class="demo-terminal">
+                    <div class="terminal-header">
+                        <div class="terminal-buttons">
+                            <span class="btn-close"></span>
+                            <span class="btn-minimize"></span>
+                            <span class="btn-maximize"></span>
+                        </div>
+                        <span class="terminal-title">claude</span>
+                    </div>
+                    <div class="terminal-body">
+                        <div class="terminal-line">
+                            <span class="prompt">$</span>
+                            <span class="command">claude</span>
+                        </div>
+                        <div class="terminal-line response">
+                            <span class="typing-animation">Use zen-architect to design my notification system</span>
+                        </div>
+                        <div class="terminal-line response">
+                            <span class="agent-tag">[zen-architect]</span>
+                            <span>Designing with ruthless simplicity...</span>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </section>
+
+        <!-- Overview Section -->
+        <section id="overview" class="section">
+            <div class="container">
+                <h2 class="section-title">What Is Amplifier?</h2>
+                <div class="overview-grid">
+                    <div class="overview-item">
+                        <div class="overview-icon">🤖</div>
+                        <h3>20+ Specialized Agents</h3>
+                        <p>Each expert in specific tasks like architecture, debugging, security, and testing.</p>
+                    </div>
+                    <div class="overview-item">
+                        <div class="overview-icon">🧠</div>
+                        <h3>Pre-loaded Context</h3>
+                        <p>Proven patterns and philosophies built into the environment from day one.</p>
+                    </div>
+                    <div class="overview-item">
+                        <div class="overview-icon">🌳</div>
+                        <h3>Parallel Worktree System</h3>
+                        <p>Build and test multiple solutions simultaneously without conflicts.</p>
+                    </div>
+                    <div class="overview-item">
+                        <div class="overview-icon">📚</div>
+                        <h3>Knowledge Extraction</h3>
+                        <p>Transform documentation into queryable, connected knowledge graphs.</p>
+                    </div>
+                </div>
+            </div>
+        </section>
+
+        <!-- Features Section -->
+        <section id="features" class="section section-alt">
+            <div class="container">
+                <h2 class="section-title">Key Features</h2>
+                <div class="features-tabs">
+                    <div class="tabs-nav">
+                        <button class="tab-btn active" onclick="showTab('agents-tab', this)">Specialized Agents</button>
+                        <button class="tab-btn" onclick="showTab('knowledge-tab', this)">Knowledge Base</button>
+                        <button class="tab-btn" onclick="showTab('parallel-tab', this)">Parallel Development</button>
+                        <button class="tab-btn" onclick="showTab('modular-tab', this)">Modular Builder</button>
+                    </div>
+
+                    <div id="agents-tab" class="tab-content active">
+                        <div class="feature-showcase">
+                            <div class="feature-text">
+                                <h3>Specialized Agents</h3>
+                                <p>Instead of one generalist AI, you get 20+ specialists, each expert in specific domains:</p>
+                                <ul>
+                                    <li><strong>zen-architect</strong> - Designs with ruthless simplicity</li>
+                                    <li><strong>bug-hunter</strong> - Systematic debugging approach</li>
+                                    <li><strong>security-guardian</strong> - Security analysis and vulnerability detection</li>
+                                    <li><strong>test-coverage</strong> - Comprehensive testing strategies</li>
+                                    <li><strong>performance-optimizer</strong> - Performance profiling and optimization</li>
+                                </ul>
+                                <a href="agents.html" class="btn btn-outline">View All Agents</a>
+                            </div>
+                            <div class="feature-demo">
+                                <div class="agent-carousel">
+                                    <div class="agent-card active">
+                                        <div class="agent-header">
+                                            <span class="agent-name">zen-architect</span>
+                                            <span class="agent-badge">Architecture</span>
+                                        </div>
+                                        <p>Designs systems with ruthless simplicity, focusing on essential patterns and clean abstractions.</p>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+
+                    <div id="knowledge-tab" class="tab-content">
+                        <div class="feature-showcase">
+                            <div class="feature-text">
+                                <h3>Knowledge Base System</h3>
+                                <p>Stop losing insights. Every document becomes part of your permanent, queryable knowledge:</p>
+                                <ul>
+                                    <li>Extract concepts and relationships from documentation</li>
+                                    <li>Query accumulated wisdom instantly</li>
+                                    <li>Visualize how ideas connect</li>
+                                    <li>Share knowledge across all worktrees</li>
+                                </ul>
+                                <div class="code-snippet">
+                                    <code>make knowledge-update  # Extract from docs<br>
+make knowledge-query Q="auth patterns"</code>
+                                </div>
+                            </div>
+                            <div class="feature-demo">
+                                <div class="knowledge-graph">
+                                    <div class="node">Authentication</div>
+                                    <div class="node">Security</div>
+                                    <div class="node">Patterns</div>
+                                    <div class="connection"></div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+
+                    <div id="parallel-tab" class="tab-content">
+                        <div class="feature-showcase">
+                            <div class="feature-text">
+                                <h3>Parallel Development</h3>
+                                <p>Stop wondering "what if" — build multiple solutions simultaneously:</p>
+                                <ul>
+                                    <li>Try different approaches in parallel worktrees</li>
+                                    <li>Compare implementations side by side</li>
+                                    <li>Keep the best, discard the rest</li>
+                                    <li>Each worktree is completely isolated</li>
+                                </ul>
+                                <div class="code-snippet">
+                                    <code>make worktree feature-jwt     # JWT approach<br>
+make worktree feature-oauth   # OAuth approach<br>
+make worktree-list            # Compare both</code>
+                                </div>
+                            </div>
+                            <div class="feature-demo">
+                                <div class="worktree-visual">
+                                    <div class="worktree-branch">
+                                        <span>main</span>
+                                        <div class="branch-line"></div>
+                                    </div>
+                                    <div class="worktree-branch">
+                                        <span>feature-jwt</span>
+                                        <div class="branch-line jwt"></div>
+                                    </div>
+                                    <div class="worktree-branch">
+                                        <span>feature-oauth</span>
+                                        <div class="branch-line oauth"></div>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+
+                    <div id="modular-tab" class="tab-content">
+                        <div class="feature-showcase">
+                            <div class="feature-text">
+                                <h3>Modular Builder</h3>
+                                <p>One-command workflow from idea to working module:</p>
+                                <ul>
+                                    <li>Contract & Spec → Plan → Generate → Review</li>
+                                    <li>Auto or assisted modes</li>
+                                    <li>Built-in conformance testing</li>
+                                    <li>Resume from any point</li>
+                                </ul>
+                                <div class="code-snippet">
+                                    <code>/modular-build Build a notification system<br>
+mode: auto level: moderate</code>
+                                </div>
+                            </div>
+                            <div class="feature-demo">
+                                <div class="modular-flow">
+                                    <div class="flow-step">Contract</div>
+                                    <div class="flow-arrow">→</div>
+                                    <div class="flow-step">Spec</div>
+                                    <div class="flow-arrow">→</div>
+                                    <div class="flow-step">Plan</div>
+                                    <div class="flow-arrow">→</div>
+                                    <div class="flow-step">Code</div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </section>
+
+        <!-- Quick Setup Section -->
+        <section id="setup" class="section">
+            <div class="container">
+                <h2 class="section-title">Quick Setup</h2>
+                <div class="setup-steps">
+                    <div class="step">
+                        <div class="step-number">1</div>
+                        <div class="step-content">
+                            <h3>Clone Repository</h3>
+                            <div class="code-snippet">
+                                <code>git clone https://github.com/microsoft/amplifier.git<br>
+cd amplifier</code>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="step">
+                        <div class="step-number">2</div>
+                        <div class="step-content">
+                            <h3>Install Dependencies</h3>
+                            <div class="code-snippet">
+                                <code>make install</code>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="step">
+                        <div class="step-number">3</div>
+                        <div class="step-content">
+                            <h3>Start Claude</h3>
+                            <div class="code-snippet">
+                                <code>claude  # Everything is pre-configured!</code>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+                <div class="setup-note">
+                    <p><strong>Prerequisites:</strong> Python 3.11+, Node.js, VS Code (recommended), Git</p>
+                    <a href="setup.html" class="btn btn-outline">Detailed Setup Guide</a>
+                </div>
+            </div>
+        </section>
+
+        <!-- Examples Section -->
+        <section id="examples" class="section section-alt">
+            <div class="container">
+                <h2 class="section-title">Example Workflows</h2>
+                <div class="examples-grid">
+                    <div class="example-card">
+                        <h3>🏗️ Building a Feature</h3>
+                        <ol>
+                            <li>"Use zen-architect to design my notification system"</li>
+                            <li>"Have modular-builder implement the notification module"</li>
+                            <li>"Deploy test-coverage to add comprehensive tests"</li>
+                        </ol>
+                    </div>
+                    <div class="example-card">
+                        <h3>🐛 Debugging Issues</h3>
+                        <ol>
+                            <li>"Use bug-hunter to find why API calls are failing"</li>
+                            <li>"Have security-guardian review authentication"</li>
+                            <li>"Deploy performance-optimizer to identify bottlenecks"</li>
+                        </ol>
+                    </div>
+                    <div class="example-card">
+                        <h3>📚 Knowledge-Driven Development</h3>
+                        <ol>
+                            <li>Extract: <code>make knowledge-update</code></li>
+                            <li>Query: <code>make knowledge-query Q="error patterns"</code></li>
+                            <li>Apply: "Implement using patterns from knowledge base"</li>
+                        </ol>
+                    </div>
+                </div>
+                <a href="examples.html" class="btn btn-primary">More Examples</a>
+            </div>
+        </section>
+
+        <!-- Status Section -->
+        <section class="section warning-section">
+            <div class="container">
+                <div class="warning-box">
+                    <div class="warning-icon">⚠️</div>
+                    <div class="warning-content">
+                        <h3>Experimental System</h3>
+                        <p>This project is a research demonstrator in early development. Use with caution and careful supervision. Not accepting contributions yet, but we plan to!</p>
+                    </div>
+                </div>
+            </div>
+        </section>
+    </main>
+
+    <footer class="footer">
+        <div class="container">
+            <div class="footer-content">
+                <div class="footer-brand">
+                    <h3>Amplifier</h3>
+                    <p>Supercharged AI Development Environment</p>
+                </div>
+                <div class="footer-links">
+                    <div class="footer-column">
+                        <h4>Documentation</h4>
+                        <a href="setup.html">Setup Guide</a>
+                        <a href="agents.html">Agent Catalog</a>
+                        <a href="knowledge.html">Knowledge Base</a>
+                        <a href="examples.html">Examples</a>
+                    </div>
+                    <div class="footer-column">
+                        <h4>Resources</h4>
+                        <a href="https://github.com/microsoft/amplifier">GitHub</a>
+                        <a href="../AMPLIFIER_VISION.md">Vision</a>
+                        <a href="../README.md">README</a>
+                        <a href="../SUPPORT.md">Support</a>
+                    </div>
+                </div>
+            </div>
+            <div class="footer-bottom">
+                <p>&copy; 2024 Microsoft. Licensed under MIT.</p>
+                <p>"The best AI system isn't the smartest - it's the one that makes YOU most effective."</p>
+            </div>
+        </div>
+    </footer>
+
+    <script src="script.js"></script>
+</body>
+</html>
\ No newline at end of file
diff --git a/instructor/knowledge.html b/instructor/knowledge.html
new file mode 100644
index 00000000..11cf05bb
--- /dev/null
+++ b/instructor/knowledge.html
@@ -0,0 +1,525 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Knowledge Base - Amplifier</title>
+    <link rel="stylesheet" href="styles.css">
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+    <style>
+        .knowledge-hero {
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: var(--text-light);
+            padding: 4rem 2rem;
+            text-align: center;
+        }
+        .knowledge-hero h1 {
+            font-size: 3rem;
+            margin-bottom: 1rem;
+        }
+        .knowledge-hero p {
+            font-size: 1.3rem;
+            opacity: 0.9;
+            max-width: 600px;
+            margin: 0 auto;
+        }
+        .workflow-steps {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+            gap: 2rem;
+            margin: 3rem 0;
+        }
+        .workflow-step {
+            background: white;
+            padding: 2rem;
+            border-radius: var(--border-radius-lg);
+            box-shadow: var(--shadow);
+            text-align: center;
+            position: relative;
+        }
+        .workflow-step::before {
+            content: '';
+            position: absolute;
+            top: -1rem;
+            left: 50%;
+            transform: translateX(-50%);
+            width: 3rem;
+            height: 3rem;
+            background: var(--primary-color);
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            color: white;
+            font-weight: bold;
+            font-size: 1.2rem;
+        }
+        .workflow-step:nth-child(1)::before { content: '1'; }
+        .workflow-step:nth-child(2)::before { content: '2'; }
+        .workflow-step:nth-child(3)::before { content: '3'; }
+        .workflow-step h3 {
+            color: var(--primary-color);
+            margin: 1rem 0;
+            font-size: 1.3rem;
+        }
+        .workflow-step p {
+            color: var(--text-secondary);
+            line-height: 1.6;
+        }
+        .feature-showcase-kb {
+            background: var(--light-bg);
+            padding: 4rem 2rem;
+            margin: 3rem 0;
+        }
+        .feature-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
+            gap: 2rem;
+            max-width: 1000px;
+            margin: 0 auto;
+        }
+        .feature-item {
+            background: white;
+            padding: 2rem;
+            border-radius: var(--border-radius-lg);
+            box-shadow: var(--shadow);
+        }
+        .feature-icon {
+            font-size: 2.5rem;
+            margin-bottom: 1rem;
+            display: block;
+        }
+        .feature-item h3 {
+            color: var(--primary-color);
+            margin-bottom: 1rem;
+            font-size: 1.3rem;
+        }
+        .feature-item p {
+            color: var(--text-secondary);
+            line-height: 1.6;
+        }
+        .command-demo {
+            background: var(--dark-bg);
+            color: var(--text-light);
+            padding: 2rem;
+            border-radius: var(--border-radius-lg);
+            font-family: monospace;
+            margin: 2rem 0;
+            overflow-x: auto;
+        }
+        .command-line {
+            display: flex;
+            margin-bottom: 1rem;
+        }
+        .prompt {
+            color: #4fd1c7;
+            margin-right: 1rem;
+        }
+        .command {
+            color: #f7fafc;
+        }
+        .output {
+            color: #a0aec0;
+            margin-left: 2rem;
+            font-style: italic;
+        }
+        .graph-visualization {
+            background: white;
+            padding: 3rem;
+            border-radius: var(--border-radius-lg);
+            box-shadow: var(--shadow);
+            text-align: center;
+            margin: 2rem 0;
+        }
+        .graph-container {
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            min-height: 300px;
+            position: relative;
+        }
+        .knowledge-node {
+            background: var(--primary-color);
+            color: white;
+            padding: 1rem 1.5rem;
+            border-radius: 2rem;
+            position: absolute;
+            font-weight: 500;
+            font-size: 0.9rem;
+            box-shadow: var(--shadow);
+        }
+        .knowledge-node.center {
+            background: var(--accent-color);
+            font-size: 1.1rem;
+            z-index: 10;
+        }
+        .knowledge-connection {
+            position: absolute;
+            height: 2px;
+            background: var(--text-secondary);
+            opacity: 0.6;
+        }
+        .use-cases {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+            gap: 2rem;
+            margin: 3rem 0;
+        }
+        .use-case {
+            background: white;
+            padding: 2rem;
+            border-radius: var(--border-radius-lg);
+            box-shadow: var(--shadow);
+            border-left: 4px solid var(--primary-color);
+        }
+        .use-case h4 {
+            color: var(--primary-color);
+            margin-bottom: 1rem;
+            font-size: 1.2rem;
+        }
+        .use-case p {
+            color: var(--text-secondary);
+            margin-bottom: 1rem;
+            line-height: 1.6;
+        }
+        .use-case .example {
+            background: var(--light-bg);
+            padding: 1rem;
+            border-radius: var(--border-radius);
+            font-family: monospace;
+            font-size: 0.9rem;
+            color: var(--primary-color);
+        }
+        .benefits-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+            gap: 1.5rem;
+            margin: 2rem 0;
+        }
+        .benefit-item {
+            text-align: center;
+            padding: 1.5rem;
+        }
+        .benefit-icon {
+            font-size: 3rem;
+            margin-bottom: 1rem;
+            display: block;
+        }
+        .benefit-item h4 {
+            color: var(--text-primary);
+            margin-bottom: 0.5rem;
+            font-size: 1.1rem;
+        }
+        .benefit-item p {
+            color: var(--text-secondary);
+            font-size: 0.9rem;
+            line-height: 1.5;
+        }
+    </style>
+</head>
+<body>
+    <header class="header">
+        <nav class="nav">
+            <div class="nav-brand">
+                <h1>Amplifier</h1>
+                <span class="tagline">Knowledge Base</span>
+            </div>
+            <div class="nav-links">
+                <a href="index.html" class="nav-link">Home</a>
+                <a href="agents.html" class="nav-link">Agents</a>
+                <a href="setup.html" class="nav-link">Setup</a>
+                <a href="examples.html" class="nav-link">Examples</a>
+                <a href="https://github.com/microsoft/amplifier" class="nav-link">GitHub</a>
+            </div>
+            <div class="nav-mobile">
+                <button class="mobile-menu-btn" onclick="toggleMobileMenu()">☰</button>
+            </div>
+        </nav>
+    </header>
+
+    <main style="padding-top: 0;">
+        <!-- Hero Section -->
+        <section class="knowledge-hero">
+            <div class="container">
+                <h1>Knowledge Base System</h1>
+                <p>Transform your documentation into queryable, connected knowledge that makes every project smarter</p>
+            </div>
+        </section>
+
+        <!-- Overview -->
+        <section class="section">
+            <div class="container">
+                <div style="max-width: 800px; margin: 0 auto; text-align: center;">
+                    <h2 class="section-title">Stop Losing Insights</h2>
+                    <p style="font-size: 1.2rem; color: var(--text-secondary); margin-bottom: 3rem;">
+                        Every document, specification, design decision, and lesson learned becomes part of your permanent,
+                        queryable knowledge that Claude can instantly access and build upon.
+                    </p>
+                </div>
+
+                <div class="workflow-steps">
+                    <div class="workflow-step">
+                        <h3>Extract Knowledge</h3>
+                        <p>Add your content (documentation, specs, notes, decisions) and let Amplifier extract concepts, relationships, and patterns automatically.</p>
+                    </div>
+                    <div class="workflow-step">
+                        <h3>Build Connections</h3>
+                        <p>The system identifies how ideas connect, creating a rich knowledge graph that reveals hidden relationships and insights.</p>
+                    </div>
+                    <div class="workflow-step">
+                        <h3>Query & Apply</h3>
+                        <p>Instantly query your accumulated wisdom and apply learned patterns to new challenges and projects.</p>
+                    </div>
+                </div>
+            </div>
+        </section>
+
+        <!-- Key Features -->
+        <section class="feature-showcase-kb">
+            <div class="container">
+                <h2 style="text-align: center; font-size: 2.2rem; margin-bottom: 3rem; color: var(--text-primary);">Powerful Knowledge Features</h2>
+                <div class="feature-grid">
+                    <div class="feature-item">
+                        <span class="feature-icon">🧠</span>
+                        <h3>Automatic Extraction</h3>
+                        <p>Processes any text-based files: documentation, specifications, notes, design decisions, and lessons learned. Extracts key concepts and relationships automatically.</p>
+                    </div>
+                    <div class="feature-item">
+                        <span class="feature-icon">🔗</span>
+                        <h3>Connected Knowledge</h3>
+                        <p>Creates a knowledge graph showing how concepts relate. Surfaces connections you might have missed and helps you see the big picture.</p>
+                    </div>
+                    <div class="feature-item">
+                        <span class="feature-icon">⚡</span>
+                        <h3>Instant Queries</h3>
+                        <p>Ask questions in natural language and get relevant insights from across all your documentation. Find patterns and solutions quickly.</p>
+                    </div>
+                    <div class="feature-item">
+                        <span class="feature-icon">📊</span>
+                        <h3>Visual Insights</h3>
+                        <p>Generate knowledge graph visualizations to understand how your ideas connect and evolve over time.</p>
+                    </div>
+                    <div class="feature-item">
+                        <span class="feature-icon">🌐</span>
+                        <h3>Shared Across Projects</h3>
+                        <p>Knowledge accumulates across all worktrees and projects. Every project benefits from lessons learned in others.</p>
+                    </div>
+                    <div class="feature-item">
+                        <span class="feature-icon">☁️</span>
+                        <h3>Cloud Sync Ready</h3>
+                        <p>Configure with cloud storage for automatic backup and cross-device synchronization of your knowledge base.</p>
+                    </div>
+                </div>
+            </div>
+        </section>
+
+        <!-- How It Works -->
+        <section class="section">
+            <div class="container">
+                <h2 class="section-title">How Knowledge Extraction Works</h2>
+
+                <div class="command-demo">
+                    <div class="command-line">
+                        <span class="prompt">$</span>
+                        <span class="command">make knowledge-update</span>
+                    </div>
+                    <div class="output">📄 Processing documents...</div>
+                    <div class="output">🧠 Extracting concepts from: architecture.md</div>
+                    <div class="output">🧠 Extracting concepts from: requirements.md</div>
+                    <div class="output">🔗 Building knowledge graph...</div>
+                    <div class="output">✅ Knowledge base updated with 47 concepts, 23 relationships</div>
+                    <br>
+                    <div class="command-line">
+                        <span class="prompt">$</span>
+                        <span class="command">make knowledge-query Q="authentication patterns"</span>
+                    </div>
+                    <div class="output">🔍 Searching knowledge base...</div>
+                    <div class="output">Found 5 relevant concepts:</div>
+                    <div class="output">• JWT Token Authentication (confidence: 0.92)</div>
+                    <div class="output">• OAuth 2.0 Flow (confidence: 0.87)</div>
+                    <div class="output">• Session Management (confidence: 0.81)</div>
+                </div>
+
+                <div class="graph-visualization">
+                    <h3 style="margin-bottom: 2rem; color: var(--primary-color);">Example Knowledge Graph</h3>
+                    <div class="graph-container">
+                        <div class="knowledge-node center" style="top: 50%; left: 50%; transform: translate(-50%, -50%);">
+                            Authentication
+                        </div>
+                        <div class="knowledge-node" style="top: 20%; left: 30%;">JWT Tokens</div>
+                        <div class="knowledge-node" style="top: 20%; right: 30%;">OAuth 2.0</div>
+                        <div class="knowledge-node" style="bottom: 20%; left: 20%;">Sessions</div>
+                        <div class="knowledge-node" style="bottom: 20%; right: 20%;">Security</div>
+                        <div class="knowledge-node" style="top: 50%; left: 15%;">Middleware</div>
+                        <div class="knowledge-node" style="top: 50%; right: 15%;">API Keys</div>
+                    </div>
+                    <p style="color: var(--text-secondary); margin-top: 1rem; font-style: italic;">
+                        Knowledge graphs help you visualize how concepts connect and discover related patterns.
+                    </p>
+                </div>
+            </div>
+        </section>
+
+        <!-- Use Cases -->
+        <section class="section section-alt">
+            <div class="container">
+                <h2 class="section-title">Real-World Use Cases</h2>
+                <div class="use-cases">
+                    <div class="use-case">
+                        <h4>📐 Architecture Decisions</h4>
+                        <p>Track why architectural decisions were made, their trade-offs, and outcomes. Never forget the reasoning behind important choices.</p>
+                        <div class="example">Query: "microservices vs monolith decisions"</div>
+                    </div>
+                    <div class="use-case">
+                        <h4>🐛 Bug Patterns</h4>
+                        <p>Accumulate knowledge about common bugs, their causes, and solutions. Build institutional memory for faster debugging.</p>
+                        <div class="example">Query: "race condition fixes"</div>
+                    </div>
+                    <div class="use-case">
+                        <h4>🔒 Security Practices</h4>
+                        <p>Maintain a knowledge base of security patterns, threats, and mitigation strategies across all projects.</p>
+                        <div class="example">Query: "input validation patterns"</div>
+                    </div>
+                    <div class="use-case">
+                        <h4>⚡ Performance Lessons</h4>
+                        <p>Document performance optimizations, bottlenecks discovered, and solutions that worked in different contexts.</p>
+                        <div class="example">Query: "database optimization techniques"</div>
+                    </div>
+                    <div class="use-case">
+                        <h4>🔄 Integration Patterns</h4>
+                        <p>Collect knowledge about integrating with external services, APIs, and third-party tools.</p>
+                        <div class="example">Query: "payment gateway integration"</div>
+                    </div>
+                    <div class="use-case">
+                        <h4>📋 Requirements Evolution</h4>
+                        <p>Track how requirements change over time and understand the context behind feature decisions.</p>
+                        <div class="example">Query: "user authentication requirements"</div>
+                    </div>
+                </div>
+            </div>
+        </section>
+
+        <!-- Benefits -->
+        <section class="section">
+            <div class="container">
+                <h2 class="section-title">Why Use Knowledge Base?</h2>
+                <div class="benefits-grid">
+                    <div class="benefit-item">
+                        <span class="benefit-icon">💡</span>
+                        <h4>Compound Learning</h4>
+                        <p>Every project makes you smarter. Lessons learned compound across all your work.</p>
+                    </div>
+                    <div class="benefit-item">
+                        <span class="benefit-icon">🚀</span>
+                        <h4>Faster Decisions</h4>
+                        <p>Quickly find relevant patterns and solutions from your past experience.</p>
+                    </div>
+                    <div class="benefit-item">
+                        <span class="benefit-icon">🔄</span>
+                        <h4>Avoid Repetition</h4>
+                        <p>Stop solving the same problems repeatedly. Build on what you've learned.</p>
+                    </div>
+                    <div class="benefit-item">
+                        <span class="benefit-icon">🤝</span>
+                        <h4>Team Knowledge</h4>
+                        <p>Share insights across team members. Institutional knowledge stays with the team.</p>
+                    </div>
+                    <div class="benefit-item">
+                        <span class="benefit-icon">📈</span>
+                        <h4>Better Architecture</h4>
+                        <p>Make informed decisions based on documented experience and proven patterns.</p>
+                    </div>
+                    <div class="benefit-item">
+                        <span class="benefit-icon">🎯</span>
+                        <h4>Context Preservation</h4>
+                        <p>Never lose the context behind important decisions and design choices.</p>
+                    </div>
+                </div>
+            </div>
+        </section>
+
+        <!-- Getting Started -->
+        <section class="section section-alt">
+            <div class="container">
+                <div style="max-width: 800px; margin: 0 auto; text-align: center;">
+                    <h2 class="section-title">Getting Started</h2>
+
+                    <div style="background: white; padding: 2rem; border-radius: var(--border-radius-lg); box-shadow: var(--shadow); text-align: left; margin-bottom: 2rem;">
+                        <h3 style="color: var(--primary-color); margin-bottom: 1rem;">1. Add Your Content</h3>
+                        <p style="color: var(--text-secondary); margin-bottom: 1rem;">
+                            Place your documentation, specifications, notes, and design documents in the content directories:
+                        </p>
+                        <div class="code-snippet">
+                            <code>ai_context/  # Built-in Amplifier knowledge<br>
+~/OneDrive/amplifier/content/  # Your external content<br>
+~/Documents/notes/  # Additional content sources</code>
+                        </div>
+                    </div>
+
+                    <div style="background: white; padding: 2rem; border-radius: var(--border-radius-lg); box-shadow: var(--shadow); text-align: left; margin-bottom: 2rem;">
+                        <h3 style="color: var(--primary-color); margin-bottom: 1rem;">2. Extract Knowledge</h3>
+                        <p style="color: var(--text-secondary); margin-bottom: 1rem;">
+                            Run the knowledge update command to process your documents:
+                        </p>
+                        <div class="code-snippet">
+                            <code>make knowledge-update</code>
+                        </div>
+                        <p style="color: var(--text-secondary); margin-top: 1rem; font-size: 0.9rem;">
+                            <em>Processing time: ~10-30 seconds per document</em>
+                        </p>
+                    </div>
+
+                    <div style="background: white; padding: 2rem; border-radius: var(--border-radius-lg); box-shadow: var(--shadow); text-align: left; margin-bottom: 3rem;">
+                        <h3 style="color: var(--primary-color); margin-bottom: 1rem;">3. Query and Apply</h3>
+                        <p style="color: var(--text-secondary); margin-bottom: 1rem;">
+                            Start querying your knowledge base and applying insights:
+                        </p>
+                        <div class="code-snippet">
+                            <code>make knowledge-query Q="error handling patterns"<br>
+make knowledge-graph-viz  # Generate visual graphs</code>
+                        </div>
+                    </div>
+
+                    <div style="display: flex; gap: 1rem; justify-content: center; flex-wrap: wrap;">
+                        <a href="setup.html" class="btn btn-primary">Setup Amplifier</a>
+                        <a href="examples.html" class="btn btn-outline">View Examples</a>
+                    </div>
+                </div>
+            </div>
+        </section>
+    </main>
+
+    <footer class="footer">
+        <div class="container">
+            <div class="footer-content">
+                <div class="footer-brand">
+                    <h3>Amplifier</h3>
+                    <p>Supercharged AI Development Environment</p>
+                </div>
+                <div class="footer-links">
+                    <div class="footer-column">
+                        <h4>Documentation</h4>
+                        <a href="setup.html">Setup Guide</a>
+                        <a href="agents.html">Agent Catalog</a>
+                        <a href="knowledge.html">Knowledge Base</a>
+                        <a href="examples.html">Examples</a>
+                    </div>
+                    <div class="footer-column">
+                        <h4>Resources</h4>
+                        <a href="https://github.com/microsoft/amplifier">GitHub</a>
+                        <a href="../AMPLIFIER_VISION.md">Vision</a>
+                        <a href="../README.md">README</a>
+                    </div>
+                </div>
+            </div>
+            <div class="footer-bottom">
+                <p>&copy; 2024 Microsoft. Licensed under MIT.</p>
+            </div>
+        </div>
+    </footer>
+
+    <script src="script.js"></script>
+</body>
+</html>
\ No newline at end of file
diff --git a/instructor/script.js b/instructor/script.js
new file mode 100644
index 00000000..08d61d05
--- /dev/null
+++ b/instructor/script.js
@@ -0,0 +1,252 @@
+// Mobile menu functionality
+function toggleMobileMenu() {
+    const navLinks = document.querySelector('.nav-links');
+    const mobileBtn = document.querySelector('.mobile-menu-btn');
+
+    if (navLinks.style.display === 'flex') {
+        navLinks.style.display = 'none';
+        mobileBtn.textContent = '☰';
+    } else {
+        navLinks.style.display = 'flex';
+        navLinks.style.flexDirection = 'column';
+        navLinks.style.position = 'absolute';
+        navLinks.style.top = '100%';
+        navLinks.style.left = '0';
+        navLinks.style.right = '0';
+        navLinks.style.background = 'white';
+        navLinks.style.padding = '1rem 2rem';
+        navLinks.style.boxShadow = 'var(--shadow)';
+        navLinks.style.gap = '1rem';
+        mobileBtn.textContent = '✕';
+    }
+}
+
+// Tab functionality
+function showTab(tabId, buttonElement) {
+    // Hide all tab contents
+    const tabContents = document.querySelectorAll('.tab-content');
+    tabContents.forEach(content => content.classList.remove('active'));
+
+    // Remove active class from all buttons
+    const tabBtns = document.querySelectorAll('.tab-btn');
+    tabBtns.forEach(btn => btn.classList.remove('active'));
+
+    // Show selected tab and mark button as active
+    const targetTab = document.getElementById(tabId);
+    if (targetTab) {
+        targetTab.classList.add('active');
+    }
+
+    // If buttonElement is provided, use it; otherwise try to find the clicked element
+    const button = buttonElement || event?.target;
+    if (button) {
+        button.classList.add('active');
+    }
+}
+
+// Smooth scrolling for navigation links
+document.addEventListener('DOMContentLoaded', function() {
+    const navLinks = document.querySelectorAll('a[href^="#"]');
+
+    navLinks.forEach(link => {
+        link.addEventListener('click', function(e) {
+            e.preventDefault();
+
+            const targetId = this.getAttribute('href');
+            const targetElement = document.querySelector(targetId);
+
+            if (targetElement) {
+                const headerHeight = document.querySelector('.header').offsetHeight;
+                const targetPosition = targetElement.offsetTop - headerHeight - 20;
+
+                window.scrollTo({
+                    top: targetPosition,
+                    behavior: 'smooth'
+                });
+            }
+        });
+    });
+
+    // Close mobile menu when clicking on links
+    navLinks.forEach(link => {
+        link.addEventListener('click', function() {
+            const navLinksElement = document.querySelector('.nav-links');
+            const mobileBtn = document.querySelector('.mobile-menu-btn');
+
+            if (window.innerWidth <= 768) {
+                navLinksElement.style.display = 'none';
+                mobileBtn.textContent = '☰';
+            }
+        });
+    });
+});
+
+// Agent carousel functionality (for future enhancement)
+let currentAgent = 0;
+const agents = [
+    {
+        name: 'zen-architect',
+        badge: 'Architecture',
+        description: 'Designs systems with ruthless simplicity, focusing on essential patterns and clean abstractions.'
+    },
+    {
+        name: 'bug-hunter',
+        badge: 'Debugging',
+        description: 'Systematic debugging approach with pattern recognition and root cause analysis.'
+    },
+    {
+        name: 'security-guardian',
+        badge: 'Security',
+        description: 'Comprehensive security analysis, vulnerability detection, and best practice enforcement.'
+    },
+    {
+        name: 'test-coverage',
+        badge: 'Testing',
+        description: 'Builds comprehensive test strategies with edge case identification and coverage analysis.'
+    }
+];
+
+function rotateAgents() {
+    const agentCard = document.querySelector('.agent-card');
+    if (!agentCard) return;
+
+    currentAgent = (currentAgent + 1) % agents.length;
+    const agent = agents[currentAgent];
+
+    agentCard.innerHTML = `
+        <div class="agent-header">
+            <span class="agent-name">${agent.name}</span>
+            <span class="agent-badge">${agent.badge}</span>
+        </div>
+        <p>${agent.description}</p>
+    `;
+}
+
+// Auto-rotate agents every 4 seconds
+setInterval(rotateAgents, 4000);
+
+// Copy code functionality
+function addCopyButtons() {
+    const codeSnippets = document.querySelectorAll('.code-snippet code');
+
+    codeSnippets.forEach(code => {
+        const wrapper = code.parentElement;
+        wrapper.style.position = 'relative';
+
+        const copyBtn = document.createElement('button');
+        copyBtn.textContent = 'Copy';
+        copyBtn.className = 'copy-btn';
+        copyBtn.style.cssText = `
+            position: absolute;
+            top: 0.5rem;
+            right: 0.5rem;
+            background: rgba(255, 255, 255, 0.2);
+            color: white;
+            border: none;
+            padding: 0.25rem 0.5rem;
+            border-radius: 0.25rem;
+            font-size: 0.75rem;
+            cursor: pointer;
+            transition: background 0.2s;
+        `;
+
+        copyBtn.addEventListener('click', async () => {
+            try {
+                await navigator.clipboard.writeText(code.textContent);
+                copyBtn.textContent = 'Copied!';
+                setTimeout(() => {
+                    copyBtn.textContent = 'Copy';
+                }, 2000);
+            } catch (err) {
+                console.error('Failed to copy: ', err);
+            }
+        });
+
+        copyBtn.addEventListener('mouseenter', () => {
+            copyBtn.style.background = 'rgba(255, 255, 255, 0.3)';
+        });
+
+        copyBtn.addEventListener('mouseleave', () => {
+            copyBtn.style.background = 'rgba(255, 255, 255, 0.2)';
+        });
+
+        wrapper.appendChild(copyBtn);
+    });
+}
+
+// Initialize copy buttons when DOM is loaded
+document.addEventListener('DOMContentLoaded', addCopyButtons);
+
+// Intersection Observer for animations
+const observerOptions = {
+    threshold: 0.1,
+    rootMargin: '0px 0px -50px 0px'
+};
+
+const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+        if (entry.isIntersecting) {
+            entry.target.style.opacity = '1';
+            entry.target.style.transform = 'translateY(0)';
+        }
+    });
+}, observerOptions);
+
+// Initialize animations when DOM is loaded
+document.addEventListener('DOMContentLoaded', () => {
+    const animatedElements = document.querySelectorAll('.overview-item, .example-card, .step, .feature-showcase');
+
+    animatedElements.forEach(el => {
+        el.style.opacity = '0';
+        el.style.transform = 'translateY(20px)';
+        el.style.transition = 'opacity 0.6s ease, transform 0.6s ease';
+        observer.observe(el);
+    });
+});
+
+// Terminal typing effect
+function typeText(element, text, delay = 50) {
+    let i = 0;
+    element.textContent = '';
+
+    function type() {
+        if (i < text.length) {
+            element.textContent += text.charAt(i);
+            i++;
+            setTimeout(type, delay);
+        }
+    }
+
+    type();
+}
+
+// Initialize terminal animation
+document.addEventListener('DOMContentLoaded', () => {
+    const typingElement = document.querySelector('.typing-animation');
+    if (typingElement) {
+        setTimeout(() => {
+            typeText(typingElement, 'Use zen-architect to design my notification system', 80);
+        }, 1000);
+    }
+});
+
+// Header scroll effect
+let lastScrollTop = 0;
+window.addEventListener('scroll', () => {
+    const header = document.querySelector('.header');
+    const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
+
+    if (scrollTop > lastScrollTop && scrollTop > 100) {
+        header.style.transform = 'translateY(-100%)';
+    } else {
+        header.style.transform = 'translateY(0)';
+    }
+
+    lastScrollTop = scrollTop;
+});
+
+// Add smooth transitions to header
+document.addEventListener('DOMContentLoaded', () => {
+    const header = document.querySelector('.header');
+    header.style.transition = 'transform 0.3s ease-in-out';
+});
\ No newline at end of file
diff --git a/instructor/setup.html b/instructor/setup.html
new file mode 100644
index 00000000..1285a9f0
--- /dev/null
+++ b/instructor/setup.html
@@ -0,0 +1,1344 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Setup Guide - Amplifier</title>
+    <link rel="stylesheet" href="styles.css">
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+    <style>
+        .setup-container {
+            max-width: 900px;
+            margin: 0 auto;
+        }
+        .step-detailed {
+            background: white;
+            border-radius: var(--border-radius-lg);
+            box-shadow: var(--shadow);
+            margin-bottom: 2rem;
+            overflow: hidden;
+        }
+        .step-header {
+            background: linear-gradient(135deg, var(--primary-color), #0052a3);
+            color: var(--text-light);
+            padding: 1.5rem 2rem;
+            display: flex;
+            align-items: center;
+            gap: 1rem;
+        }
+        .step-number-large {
+            background: rgba(255, 255, 255, 0.2);
+            width: 3rem;
+            height: 3rem;
+            border-radius: 50%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            font-size: 1.5rem;
+            font-weight: 700;
+        }
+        .step-title {
+            font-size: 1.5rem;
+            font-weight: 600;
+        }
+        .step-body-detailed {
+            padding: 2rem;
+        }
+        .step-description {
+            color: var(--text-secondary);
+            font-size: 1.1rem;
+            line-height: 1.6;
+            margin-bottom: 1.5rem;
+        }
+        .code-block {
+            background: var(--dark-bg);
+            color: var(--text-light);
+            padding: 1.5rem;
+            border-radius: var(--border-radius);
+            font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+            font-size: 0.95rem;
+            line-height: 1.4;
+            margin: 1rem 0;
+            position: relative;
+            overflow-x: auto;
+        }
+        .copy-btn {
+            position: absolute;
+            top: 0.5rem;
+            right: 0.5rem;
+            background: rgba(255, 255, 255, 0.1);
+            color: var(--text-light);
+            border: 1px solid rgba(255, 255, 255, 0.2);
+            padding: 0.25rem 0.75rem;
+            border-radius: var(--border-radius);
+            cursor: pointer;
+            font-size: 0.85rem;
+            transition: var(--transition);
+        }
+        .copy-btn:hover {
+            background: rgba(255, 255, 255, 0.2);
+        }
+        .copy-btn.copied {
+            background: var(--accent-color);
+            color: white;
+        }
+        .platform-tabs {
+            display: flex;
+            background: var(--light-bg);
+            border-radius: var(--border-radius);
+            padding: 0.25rem;
+            margin-bottom: 1rem;
+        }
+        .platform-tab {
+            flex: 1;
+            padding: 0.75rem 1rem;
+            text-align: center;
+            border-radius: var(--border-radius);
+            cursor: pointer;
+            transition: var(--transition);
+            font-weight: 500;
+            border: none;
+            background: none;
+        }
+        .platform-tab.active {
+            background: var(--primary-color);
+            color: var(--text-light);
+        }
+        .platform-content {
+            display: none;
+        }
+        .platform-content.active {
+            display: block;
+        }
+        .warning-box {
+            background: linear-gradient(135deg, #fff3cd, #fef9e7);
+            border-left: 4px solid var(--warning-color);
+            padding: 1.5rem;
+            border-radius: var(--border-radius);
+            margin: 1.5rem 0;
+        }
+        .warning-box h4 {
+            color: #856404;
+            margin-bottom: 0.5rem;
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+        }
+        .info-box {
+            background: linear-gradient(135deg, #d1ecf1, #b8daff);
+            border-left: 4px solid var(--primary-color);
+            padding: 1.5rem;
+            border-radius: var(--border-radius);
+            margin: 1.5rem 0;
+        }
+        .info-box h4 {
+            color: #155724;
+            margin-bottom: 0.5rem;
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+        }
+        .success-box {
+            background: linear-gradient(135deg, #d4edda, #c3e6cb);
+            border-left: 4px solid var(--accent-color);
+            padding: 1.5rem;
+            border-radius: var(--border-radius);
+            margin: 1.5rem 0;
+        }
+        .error-box {
+            background: linear-gradient(135deg, #f8d7da, #f5c6cb);
+            border-left: 4px solid #dc3545;
+            padding: 1.5rem;
+            border-radius: var(--border-radius);
+            margin: 1.5rem 0;
+        }
+        .error-box h4 {
+            color: #721c24;
+            margin-bottom: 0.5rem;
+        }
+        .prerequisite-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+            gap: 1.5rem;
+            margin: 2rem 0;
+        }
+        .prerequisite-item {
+            background: white;
+            padding: 1.5rem;
+            border-radius: var(--border-radius);
+            box-shadow: var(--shadow);
+            text-align: center;
+            transition: var(--transition);
+        }
+        .prerequisite-item:hover {
+            transform: translateY(-2px);
+            box-shadow: var(--shadow-lg);
+        }
+        .prerequisite-icon {
+            font-size: 2.5rem;
+            margin-bottom: 1rem;
+        }
+        .prerequisite-item h3 {
+            color: var(--text-primary);
+            margin-bottom: 0.5rem;
+        }
+        .prerequisite-item p {
+            color: var(--text-secondary);
+            font-size: 0.9rem;
+            margin-bottom: 1rem;
+        }
+        .download-btn {
+            display: inline-flex;
+            align-items: center;
+            background: var(--primary-color);
+            color: var(--text-light);
+            text-decoration: none;
+            padding: 0.5rem 1rem;
+            border-radius: var(--border-radius);
+            font-size: 0.9rem;
+            font-weight: 500;
+            transition: var(--transition);
+        }
+        .download-btn:hover {
+            background: var(--primary-dark);
+            color: var(--text-light);
+        }
+        .table-responsive {
+            overflow-x: auto;
+            margin: 1.5rem 0;
+        }
+        .table {
+            width: 100%;
+            border-collapse: collapse;
+            background: white;
+            border-radius: var(--border-radius);
+            overflow: hidden;
+            box-shadow: var(--shadow);
+        }
+        .table th {
+            background: var(--primary-color);
+            color: var(--text-light);
+            padding: 1rem;
+            text-align: left;
+            font-weight: 600;
+        }
+        .table td {
+            padding: 1rem;
+            border-bottom: 1px solid var(--border-color);
+        }
+        .table tbody tr:hover {
+            background: var(--light-bg);
+        }
+        .next-steps {
+            background: white;
+            padding: 2rem;
+            border-radius: var(--border-radius-lg);
+            box-shadow: var(--shadow);
+            text-align: center;
+            margin-top: 3rem;
+        }
+        .collapsible {
+            background-color: var(--light-bg);
+            color: var(--text-primary);
+            cursor: pointer;
+            padding: 1rem 1.5rem;
+            width: 100%;
+            border: none;
+            text-align: left;
+            outline: none;
+            font-size: 1rem;
+            font-weight: 500;
+            transition: var(--transition);
+            border-radius: var(--border-radius);
+            margin-top: 1rem;
+        }
+        .collapsible:hover {
+            background-color: var(--border-color);
+        }
+        .collapsible:after {
+            content: '\002B';
+            color: var(--primary-color);
+            font-weight: bold;
+            float: right;
+            margin-left: 5px;
+        }
+        .collapsible.active:after {
+            content: "\2212";
+        }
+        .collapsible-content {
+            max-height: 0;
+            overflow: hidden;
+            transition: max-height 0.2s ease-out;
+            background-color: var(--light-bg);
+            padding: 0 1.5rem;
+            border-radius: 0 0 var(--border-radius) var(--border-radius);
+        }
+        .collapsible-content.show {
+            max-height: 2000px;
+            padding: 1.5rem;
+        }
+        .verification-check {
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+            color: var(--accent-color);
+            font-weight: 500;
+            margin-top: 0.5rem;
+        }
+        .command-output {
+            background: #f4f4f4;
+            border-left: 3px solid var(--primary-color);
+            padding: 1rem;
+            margin: 0.5rem 0;
+            font-family: monospace;
+            color: #666;
+            font-size: 0.9rem;
+        }
+        .quick-start-banner {
+            background: linear-gradient(135deg, var(--primary-color), #0052a3);
+            color: white;
+            padding: 2rem;
+            border-radius: var(--border-radius-lg);
+            margin-bottom: 2rem;
+            text-align: center;
+        }
+        .quick-start-banner h2 {
+            color: white;
+            margin-bottom: 1rem;
+        }
+        .quick-commands {
+            background: rgba(255, 255, 255, 0.1);
+            padding: 1rem;
+            border-radius: var(--border-radius);
+            margin-top: 1rem;
+        }
+    </style>
+</head>
+<body>
+    <header class="header">
+        <nav class="nav">
+            <div class="nav-brand">
+                <h1>Amplifier</h1>
+                <span class="tagline">Setup Guide</span>
+            </div>
+            <div class="nav-links">
+                <a href="index.html" class="nav-link">Home</a>
+                <a href="agents.html" class="nav-link">Agents</a>
+                <a href="examples.html" class="nav-link">Examples</a>
+                <a href="knowledge.html" class="nav-link">Knowledge Base</a>
+                <a href="https://github.com/microsoft/amplifier" class="nav-link">GitHub</a>
+            </div>
+            <div class="nav-mobile">
+                <button class="mobile-menu-btn" onclick="toggleMobileMenu()">☰</button>
+            </div>
+        </nav>
+    </header>
+
+    <main style="padding-top: 6rem;">
+        <section class="section">
+            <div class="container">
+                <div class="setup-container">
+                    <div style="text-align: center; margin-bottom: 3rem;">
+                        <h1 class="section-title">Complete Setup Guide</h1>
+                        <p style="font-size: 1.2rem; color: var(--text-secondary);">
+                            Get Amplifier running in under 5 minutes with copy-paste commands
+                        </p>
+                    </div>
+
+                    <!-- Quick Start Banner -->
+                    <div class="quick-start-banner">
+                        <h2>⚡ Quick Start (Copy-Paste-Done)</h2>
+                        <div class="quick-commands">
+                            <div class="code-block" style="background: rgba(0,0,0,0.3); text-align: left;">
+                                <button class="copy-btn" onclick="copyCode(this)">Copy All</button>
+# For most users - just run these 4 commands:
+git clone https://github.com/microsoft/amplifier.git
+cd amplifier
+make install
+claude</div>
+                        </div>
+                        <p style="margin-top: 1rem; opacity: 0.9;">That's it! Continue reading for platform-specific details and troubleshooting.</p>
+                    </div>
+
+                    <div class="warning-box">
+                        <h4>⚠️ Important Note</h4>
+                        <p>This project is a research demonstrator in early development. It may change significantly and requires careful attention to security considerations. Use with caution and careful human supervision.</p>
+                    </div>
+
+                    <!-- Prerequisites -->
+                    <div class="step-detailed">
+                        <div class="step-header">
+                            <div class="step-number-large">📋</div>
+                            <div class="step-title">Prerequisites & Pre-Installation Checks</div>
+                        </div>
+                        <div class="step-body-detailed">
+                            <p class="step-description">
+                                Before installing Amplifier, verify you have these required tools. Click each tab for platform-specific instructions:
+                            </p>
+
+                            <!-- Platform-specific prerequisite checks -->
+                            <div class="platform-tabs">
+                                <button class="platform-tab active" onclick="showPlatform('prereq-wsl', this)">Windows (WSL2)</button>
+                                <button class="platform-tab" onclick="showPlatform('prereq-mac', this)">macOS</button>
+                                <button class="platform-tab" onclick="showPlatform('prereq-linux', this)">Linux</button>
+                            </div>
+
+                            <div id="prereq-wsl-platform" class="platform-content active">
+                                <h4 style="color: var(--primary-color); margin: 1.5rem 0 1rem 0;">Windows with WSL2 Setup</h4>
+
+                                <p><strong>Step 1: Enable WSL2 (if not already enabled)</strong></p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Run in PowerShell as Administrator
+wsl --install
+# Restart your computer after this completes</div>
+
+                                <p style="margin-top: 1rem;"><strong>Step 2: Install Ubuntu (recommended distribution)</strong></p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# In PowerShell
+wsl --install -d Ubuntu-22.04</div>
+
+                                <p style="margin-top: 1rem;"><strong>Step 3: Verify Prerequisites in WSL</strong></p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Open WSL Ubuntu terminal and run:
+python3 --version
+node --version
+git --version
+
+# If any are missing, install them:
+sudo apt update && sudo apt install -y python3.11 python3-pip nodejs npm git make</div>
+
+                                <div class="command-output">
+Expected output:
+Python 3.11.0 (or higher)
+v18.17.0 (or higher)
+git version 2.34.1 (or higher)</div>
+                            </div>
+
+                            <div id="prereq-mac-platform" class="platform-content">
+                                <h4 style="color: var(--primary-color); margin: 1.5rem 0 1rem 0;">macOS Setup</h4>
+
+                                <p><strong>Step 1: Install Homebrew (if needed)</strong></p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"</div>
+
+                                <p style="margin-top: 1rem;"><strong>Step 2: Install Prerequisites</strong></p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Install all required tools
+brew install python@3.11 node git
+
+# Verify installations
+python3.11 --version
+node --version
+git --version</div>
+
+                                <div class="command-output">
+Expected output:
+Python 3.11.0 (or higher)
+v18.17.0 (or higher)
+git version 2.39.0 (or higher)</div>
+                            </div>
+
+                            <div id="prereq-linux-platform" class="platform-content">
+                                <h4 style="color: var(--primary-color); margin: 1.5rem 0 1rem 0;">Linux Setup (Ubuntu/Debian)</h4>
+
+                                <p><strong>Install all prerequisites at once:</strong></p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Update package list and install everything
+sudo apt update
+sudo apt install -y python3.11 python3-pip nodejs npm git make curl
+
+# Verify installations
+python3.11 --version
+node --version
+git --version</div>
+
+                                <div class="command-output">
+Expected output:
+Python 3.11.0 (or higher)
+v18.17.0 (or higher)
+git version 2.34.1 (or higher)</div>
+                            </div>
+
+                            <div class="prerequisite-grid" style="margin-top: 2rem;">
+                                <div class="prerequisite-item">
+                                    <div class="prerequisite-icon">🐍</div>
+                                    <h3>Python 3.11+</h3>
+                                    <p>Core runtime for all Amplifier systems</p>
+                                    <div class="verification-check">✓ Verify: <code>python3 --version</code></div>
+                                </div>
+                                <div class="prerequisite-item">
+                                    <div class="prerequisite-icon">🟢</div>
+                                    <h3>Node.js 18+</h3>
+                                    <p>Required for Claude CLI and tools</p>
+                                    <div class="verification-check">✓ Verify: <code>node --version</code></div>
+                                </div>
+                                <div class="prerequisite-item">
+                                    <div class="prerequisite-icon">📦</div>
+                                    <h3>Git</h3>
+                                    <p>Version control for repo management</p>
+                                    <div class="verification-check">✓ Verify: <code>git --version</code></div>
+                                </div>
+                                <div class="prerequisite-item">
+                                    <div class="prerequisite-icon">🔧</div>
+                                    <h3>Make</h3>
+                                    <p>Build automation tool</p>
+                                    <div class="verification-check">✓ Verify: <code>make --version</code></div>
+                                </div>
+                            </div>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">⚠️ Troubleshooting Prerequisites</button>
+                            <div class="collapsible-content">
+                                <div class="error-box">
+                                    <h4>❌ Python version too old?</h4>
+                                    <p>If your system Python is older than 3.11, you can use pyenv to install a newer version:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Install pyenv
+curl https://pyenv.run | bash
+
+# Add to your shell configuration
+echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
+echo 'eval "$(pyenv init -)"' >> ~/.bashrc
+source ~/.bashrc
+
+# Install Python 3.11
+pyenv install 3.11.0
+pyenv global 3.11.0</div>
+                                </div>
+
+                                <div class="error-box">
+                                    <h4>❌ Node.js version too old?</h4>
+                                    <p>Use Node Version Manager (nvm) to install the latest version:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Install nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+source ~/.bashrc
+
+# Install latest Node.js
+nvm install node
+nvm use node</div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+
+                    <!-- Step 1: Clone Repository -->
+                    <div class="step-detailed">
+                        <div class="step-header">
+                            <div class="step-number-large">1</div>
+                            <div class="step-title">Clone the Repository</div>
+                        </div>
+                        <div class="step-body-detailed">
+                            <p class="step-description">
+                                Choose your preferred method to get the Amplifier code:
+                            </p>
+
+                            <div class="platform-tabs">
+                                <button class="platform-tab active" onclick="showPlatform('clone-https', this)">HTTPS (Recommended)</button>
+                                <button class="platform-tab" onclick="showPlatform('clone-ssh', this)">SSH</button>
+                                <button class="platform-tab" onclick="showPlatform('clone-gh', this)">GitHub CLI</button>
+                            </div>
+
+                            <div id="clone-https-platform" class="platform-content active">
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Clone via HTTPS (works for everyone)
+git clone https://github.com/microsoft/amplifier.git
+cd amplifier
+
+# Verify you're in the right directory
+pwd
+# Should output: /path/to/amplifier</div>
+                            </div>
+
+                            <div id="clone-ssh-platform" class="platform-content">
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Clone via SSH (requires GitHub SSH key setup)
+git clone git@github.com:microsoft/amplifier.git
+cd amplifier
+
+# Verify you're in the right directory
+pwd
+# Should output: /path/to/amplifier</div>
+                            </div>
+
+                            <div id="clone-gh-platform" class="platform-content">
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Using GitHub CLI (if installed)
+gh repo clone microsoft/amplifier
+cd amplifier
+
+# Verify you're in the right directory
+pwd
+# Should output: /path/to/amplifier</div>
+                            </div>
+
+                            <div class="success-box">
+                                <h4>✅ Verification</h4>
+                                <p>After cloning, verify the repository structure:</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+ls -la
+# You should see: amplifier/, .claude/, Makefile, pyproject.toml, etc.</div>
+                            </div>
+
+                            <div class="info-box">
+                                <h4>💡 Best Practices for Location</h4>
+                                <ul style="margin: 0.5rem 0 0 1rem;">
+                                    <li><strong>WSL2:</strong> Clone in WSL filesystem (~/projects/), not Windows (/mnt/c/) for 10x faster performance</li>
+                                    <li><strong>Mac/Linux:</strong> Use ~/Developer/ or ~/projects/ for easy access</li>
+                                    <li><strong>Avoid:</strong> OneDrive, Dropbox, or other synced folders during development</li>
+                                </ul>
+                            </div>
+                        </div>
+                    </div>
+
+                    <!-- Step 2: Run Installation -->
+                    <div class="step-detailed">
+                        <div class="step-header">
+                            <div class="step-number-large">2</div>
+                            <div class="step-title">Run the Installer</div>
+                        </div>
+                        <div class="step-body-detailed">
+                            <p class="step-description">
+                                Amplifier's intelligent installer handles everything automatically:
+                            </p>
+
+                            <div class="code-block">
+                                <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Run the comprehensive installer
+make install
+
+# This automatically:
+# ✓ Installs uv (ultra-fast Python package manager)
+# ✓ Creates virtual environment
+# ✓ Installs all Python dependencies
+# ✓ Sets up Claude CLI globally
+# ✓ Configures project settings</div>
+
+                            <div class="command-output">
+Expected output during installation:
+🚀 Installing uv package manager...
+✓ uv installed successfully
+📦 Creating virtual environment...
+✓ Virtual environment created at .venv
+📚 Installing dependencies...
+✓ All dependencies installed (pydantic, claude-code-sdk, etc.)
+🤖 Installing Claude CLI...
+✓ Claude CLI available globally
+✨ Installation complete!</div>
+
+                            <div class="info-box">
+                                <h4>📦 What Gets Installed</h4>
+                                <ul style="margin: 0.5rem 0 0 1rem;">
+                                    <li><strong>uv:</strong> Lightning-fast Python package manager (10-100x faster than pip)</li>
+                                    <li><strong>Claude CLI:</strong> Command-line interface for Claude Code</li>
+                                    <li><strong>Python packages:</strong> pydantic, claude-code-sdk, asyncio, and 20+ more</li>
+                                    <li><strong>Development tools:</strong> ruff (formatter/linter), pyright (type checker), pytest</li>
+                                </ul>
+                            </div>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">🔧 Installation Troubleshooting</button>
+                            <div class="collapsible-content">
+                                <div class="error-box">
+                                    <h4>❌ "make: command not found"</h4>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Install make on your platform:
+# Ubuntu/Debian/WSL:
+sudo apt install make
+
+# macOS:
+xcode-select --install
+
+# Then retry:
+make install</div>
+                                </div>
+
+                                <div class="error-box">
+                                    <h4>❌ "Permission denied" errors</h4>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Fix permissions and retry:
+chmod +x scripts/*.sh
+sudo chown -R $USER:$USER .
+make install</div>
+                                </div>
+
+                                <div class="error-box">
+                                    <h4>❌ "uv: command not found" after installation</h4>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Manually install uv:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source ~/.bashrc  # or ~/.zshrc on macOS
+
+# Then retry:
+make install</div>
+                                </div>
+
+                                <div class="info-box">
+                                    <h4>💡 Manual Installation Alternative</h4>
+                                    <p>If make install fails, you can install manually:</p>
+                                    <div class="code-block">
+                                        <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Step-by-step manual installation:
+python3 -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+pip install --upgrade pip
+pip install uv
+uv pip install -e .
+npm install -g @anthropic-ai/claude-code</div>
+                                </div>
+                            </div>
+
+                            <div class="success-box">
+                                <h4>✅ Verify Installation</h4>
+                                <p>Check that everything installed correctly:</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Check virtual environment
+ls -la .venv/
+
+# Check uv installation
+which uv
+
+# Check Python packages
+uv pip list | grep -E "pydantic|claude"
+
+# Check Claude CLI
+which claude</div>
+                            </div>
+                        </div>
+                    </div>
+
+                    <!-- Step 3: Configure Data Directories -->
+                    <div class="step-detailed">
+                        <div class="step-header">
+                            <div class="step-number-large">3</div>
+                            <div class="step-title">Configure Data Directories (Recommended)</div>
+                        </div>
+                        <div class="step-body-detailed">
+                            <p class="step-description">
+                                Set up persistent storage for your knowledge base and configurations:
+                            </p>
+
+                            <div class="info-box">
+                                <h4>🌟 Why Configure External Directories?</h4>
+                                <ul style="margin: 0.5rem 0 0 1rem;">
+                                    <li><strong>Persistent Knowledge:</strong> Survives reinstalls and repository updates</li>
+                                    <li><strong>Cross-Project Sharing:</strong> Use the same knowledge base across multiple projects</li>
+                                    <li><strong>Cloud Sync:</strong> Automatic backup via OneDrive/Dropbox/iCloud</li>
+                                    <li><strong>Team Collaboration:</strong> Share knowledge bases with your team</li>
+                                </ul>
+                            </div>
+
+                            <h4 style="color: var(--primary-color); margin-top: 1.5rem;">Quick Setup</h4>
+                            <div class="code-block">
+                                <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Copy the example environment file
+cp .env.example .env
+
+# Open in your editor
+nano .env  # or vim, code, etc.</div>
+
+                            <h4 style="color: var(--primary-color); margin-top: 1.5rem;">Configuration Options</h4>
+
+                            <div class="platform-tabs">
+                                <button class="platform-tab active" onclick="showPlatform('config-cloud', this)">Cloud Sync Setup</button>
+                                <button class="platform-tab" onclick="showPlatform('config-local', this)">Local Only</button>
+                                <button class="platform-tab" onclick="showPlatform('config-team', this)">Team Setup</button>
+                            </div>
+
+                            <div id="config-cloud-platform" class="platform-content active">
+                                <p><strong>Recommended: Use cloud-synced folders for automatic backup</strong></p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# OneDrive (Windows/Mac)
+AMPLIFIER_DATA_DIR=~/OneDrive/amplifier/data
+AMPLIFIER_CONTENT_DIRS=ai_context,~/OneDrive/amplifier/content
+
+# Dropbox
+AMPLIFIER_DATA_DIR=~/Dropbox/amplifier/data
+AMPLIFIER_CONTENT_DIRS=ai_context,~/Dropbox/amplifier/content
+
+# iCloud (Mac)
+AMPLIFIER_DATA_DIR=~/Library/Mobile\ Documents/com~apple~CloudDocs/amplifier/data
+AMPLIFIER_CONTENT_DIRS=ai_context,~/Library/Mobile\ Documents/com~apple~CloudDocs/amplifier/content</div>
+                            </div>
+
+                            <div id="config-local-platform" class="platform-content">
+                                <p><strong>Keep everything local for maximum performance</strong></p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Local storage only
+AMPLIFIER_DATA_DIR=~/.amplifier/data
+AMPLIFIER_CONTENT_DIRS=ai_context,~/.amplifier/content
+
+# Or use a dedicated drive
+AMPLIFIER_DATA_DIR=/data/amplifier/knowledge
+AMPLIFIER_CONTENT_DIRS=ai_context,/data/amplifier/content</div>
+                            </div>
+
+                            <div id="config-team-platform" class="platform-content">
+                                <p><strong>Share knowledge bases with your team</strong></p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Shared network drive
+AMPLIFIER_DATA_DIR=/mnt/shared/team/amplifier/data
+AMPLIFIER_CONTENT_DIRS=ai_context,/mnt/shared/team/docs
+
+# Git-based sharing (commit knowledge)
+AMPLIFIER_DATA_DIR=./team-knowledge/data
+AMPLIFIER_CONTENT_DIRS=ai_context,./team-knowledge/content</div>
+                            </div>
+
+                            <h4 style="color: var(--primary-color); margin-top: 1.5rem;">Environment Variables Explained</h4>
+                            <div class="table-responsive">
+                                <table class="table">
+                                    <thead>
+                                        <tr>
+                                            <th>Variable</th>
+                                            <th>Purpose</th>
+                                            <th>Example</th>
+                                        </tr>
+                                    </thead>
+                                    <tbody>
+                                        <tr>
+                                            <td><code>AMPLIFIER_DATA_DIR</code></td>
+                                            <td>Stores extracted knowledge, memory, and cache</td>
+                                            <td>~/OneDrive/amplifier/data</td>
+                                        </tr>
+                                        <tr>
+                                            <td><code>AMPLIFIER_CONTENT_DIRS</code></td>
+                                            <td>Source documents for knowledge extraction</td>
+                                            <td>ai_context,~/docs</td>
+                                        </tr>
+                                        <tr>
+                                            <td><code>ANTHROPIC_API_KEY</code></td>
+                                            <td>Your Claude API key (if using API mode)</td>
+                                            <td>sk-ant-api03-...</td>
+                                        </tr>
+                                    </tbody>
+                                </table>
+                            </div>
+
+                            <div class="warning-box">
+                                <h4>⚠️ Cloud Sync Performance Note</h4>
+                                <p>If using OneDrive/Dropbox, enable "Always keep on this device" for the amplifier folders to avoid I/O delays during knowledge extraction.</p>
+                            </div>
+                        </div>
+                    </div>
+
+                    <!-- Step 4: Activate Environment -->
+                    <div class="step-detailed">
+                        <div class="step-header">
+                            <div class="step-number-large">4</div>
+                            <div class="step-title">Activate the Environment</div>
+                        </div>
+                        <div class="step-body-detailed">
+                            <p class="step-description">
+                                If the virtual environment isn't already active, activate it manually:
+                            </p>
+
+                            <div class="platform-tabs">
+                                <button class="platform-tab active" onclick="showPlatform('unix')">Linux/Mac/WSL</button>
+                                <button class="platform-tab" onclick="showPlatform('windows')">Windows</button>
+                            </div>
+
+                            <div id="unix-platform" class="platform-content active">
+                                <div class="code-block">
+source .venv/bin/activate</div>
+                            </div>
+
+                            <div id="windows-platform" class="platform-content">
+                                <div class="code-block">
+.venv\Scripts\activate</div>
+                            </div>
+
+                            <div class="success-box">
+                                <h4>✅ Verification</h4>
+                                <p>When activated, you should see <code>(.venv)</code> at the beginning of your command prompt.</p>
+                            </div>
+                        </div>
+                    </div>
+
+                    <!-- Step 5: First Launch -->
+                    <div class="step-detailed">
+                        <div class="step-header">
+                            <div class="step-number-large">5</div>
+                            <div class="step-title">Launch Amplifier</div>
+                        </div>
+                        <div class="step-body-detailed">
+                            <p class="step-description">
+                                With everything installed, you can now launch Claude with all Amplifier enhancements:
+                            </p>
+                            <div class="code-block">
+claude</div>
+                            <p style="margin-top: 1rem; color: var(--text-secondary);">
+                                That's it! You now have access to:
+                            </p>
+                            <ul style="color: var(--text-secondary); margin-left: 1.5rem; margin-top: 0.5rem;">
+                                <li>20+ specialized agents</li>
+                                <li>Pre-loaded context and patterns</li>
+                                <li>Knowledge extraction system</li>
+                                <li>Modular builder workflows</li>
+                                <li>Enhanced status line</li>
+                            </ul>
+                        </div>
+                    </div>
+
+                    <!-- Advanced Configuration -->
+                    <div class="step-detailed">
+                        <div class="step-header">
+                            <div class="step-number-large">⚙️</div>
+                            <div class="step-title">Advanced Configuration</div>
+                        </div>
+                        <div class="step-body-detailed">
+                            <h3 style="color: var(--primary-color); margin-bottom: 1rem;">Enhanced Status Line</h3>
+                            <p class="step-description">
+                                See costs, model, and session info at a glance in your terminal:
+                            </p>
+                            <div class="code-block">
+/statusline use the script at .claude/tools/statusline-example.sh</div>
+                            <p style="margin-top: 1rem; color: var(--text-secondary);">
+                                Example output: <code>~/repos/amplifier (main → origin) Opus 4.1 💰$4.67 ⏱18m</code>
+                            </p>
+
+                            <h3 style="color: var(--primary-color); margin-bottom: 1rem; margin-top: 2rem;">Development Commands</h3>
+                            <div class="table-responsive">
+                                <table class="table">
+                                    <thead>
+                                        <tr>
+                                            <th>Command</th>
+                                            <th>Purpose</th>
+                                        </tr>
+                                    </thead>
+                                    <tbody>
+                                        <tr>
+                                            <td><code>make check</code></td>
+                                            <td>Format, lint, and type-check code</td>
+                                        </tr>
+                                        <tr>
+                                            <td><code>make test</code></td>
+                                            <td>Run the test suite</td>
+                                        </tr>
+                                        <tr>
+                                            <td><code>make knowledge-update</code></td>
+                                            <td>Extract knowledge from documentation</td>
+                                        </tr>
+                                        <tr>
+                                            <td><code>make knowledge-query Q="topic"</code></td>
+                                            <td>Query your knowledge base</td>
+                                        </tr>
+                                        <tr>
+                                            <td><code>make worktree name</code></td>
+                                            <td>Create parallel development branch</td>
+                                        </tr>
+                                    </tbody>
+                                </table>
+                            </div>
+                        </div>
+                    </div>
+
+                    <!-- Using with Your Projects -->
+                    <div class="step-detailed">
+                        <div class="step-header">
+                            <div class="step-number-large">🚀</div>
+                            <div class="step-title">Using with Your Own Projects</div>
+                        </div>
+                        <div class="step-body-detailed">
+                            <p class="step-description">
+                                Want Amplifier's power on your own code? Here's how:
+                            </p>
+
+                            <h4 style="color: var(--primary-color); margin-bottom: 1rem;">Method 1: Add Directory</h4>
+                            <div class="code-block">
+claude --add-dir /path/to/your/project</div>
+
+                            <h4 style="color: var(--primary-color); margin-bottom: 1rem; margin-top: 2rem;">Method 2: Set Context</h4>
+                            <p style="color: var(--text-secondary); margin-bottom: 1rem;">
+                                After launching Claude, paste this as your first message:
+                            </p>
+                            <div class="code-block">
+I'm working in /path/to/your/project which doesn't have Amplifier files.
+Please cd to that directory and work there.
+Do NOT update any issues or PRs in the Amplifier repo.</div>
+
+                            <h4 style="color: var(--primary-color); margin-bottom: 1rem; margin-top: 2rem;">Example Usage</h4>
+                            <div class="code-block">
+"Use the zen-architect agent to design my application's caching layer"
+"Deploy bug-hunter to find why my login system is failing"
+"Have security-guardian review my API implementation"</div>
+                        </div>
+                    </div>
+
+                    <!-- Troubleshooting -->
+                    <div class="step-detailed">
+                        <div class="step-header">
+                            <div class="step-number-large">🔧</div>
+                            <div class="step-title">Comprehensive Troubleshooting Guide</div>
+                        </div>
+                        <div class="step-body-detailed">
+                            <p class="step-description">
+                                Click on any issue below for detailed solutions:
+                            </p>
+
+                            <!-- Installation Issues -->
+                            <h4 style="color: var(--primary-color); margin: 1.5rem 0 1rem 0;">Installation Issues</h4>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">❌ "make: command not found"</button>
+                            <div class="collapsible-content">
+                                <p>The make command is not installed on your system.</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Ubuntu/Debian/WSL:
+sudo apt update && sudo apt install make
+
+# macOS:
+xcode-select --install
+
+# Fedora/RHEL:
+sudo dnf install make
+
+# Verify installation:
+make --version</div>
+                            </div>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">❌ "Python version 3.x is not supported"</button>
+                            <div class="collapsible-content">
+                                <p>Your Python version is too old. You need Python 3.11 or higher.</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Check current version:
+python3 --version
+
+# Ubuntu/Debian - Add deadsnakes PPA for newer Python:
+sudo add-apt-repository ppa:deadsnakes/ppa
+sudo apt update
+sudo apt install python3.11 python3.11-venv
+
+# macOS - Use Homebrew:
+brew install python@3.11
+brew link python@3.11
+
+# Alternative - Use pyenv (all platforms):
+curl https://pyenv.run | bash
+pyenv install 3.11.7
+pyenv global 3.11.7</div>
+                            </div>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">❌ "uv: command not found" after installation</button>
+                            <div class="collapsible-content">
+                                <p>The uv package manager didn't install correctly.</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Manual uv installation:
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Add to PATH (bash):
+echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+
+# Add to PATH (zsh):
+echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+
+# Verify:
+uv --version</div>
+                            </div>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">❌ "Permission denied" errors</button>
+                            <div class="collapsible-content">
+                                <p>File permission issues preventing installation.</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Fix ownership:
+sudo chown -R $USER:$USER .
+
+# Fix permissions:
+chmod -R u+rwX .
+find . -type f -name "*.sh" -exec chmod +x {} \;
+
+# If in WSL with Windows files:
+# Move to Linux filesystem instead:
+cp -r /mnt/c/path/to/amplifier ~/amplifier
+cd ~/amplifier
+make install</div>
+                            </div>
+
+                            <!-- Runtime Issues -->
+                            <h4 style="color: var(--primary-color); margin: 2rem 0 1rem 0;">Runtime Issues</h4>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">❌ "claude: command not found"</button>
+                            <div class="collapsible-content">
+                                <p>The Claude CLI isn't in your PATH or didn't install correctly.</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Check if Claude is installed:
+which claude
+
+# Reinstall Claude CLI globally:
+npm install -g @anthropic-ai/claude-code
+
+# If npm isn't working, try with node directly:
+npx @anthropic-ai/claude-code
+
+# Add npm global bin to PATH:
+export PATH="$PATH:$(npm config get prefix)/bin"
+echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc</div>
+                            </div>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">❌ "No module named 'amplifier'"</button>
+                            <div class="collapsible-content">
+                                <p>The virtual environment isn't activated or packages aren't installed.</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Activate virtual environment:
+source .venv/bin/activate  # Linux/Mac/WSL
+# or
+.venv\Scripts\activate     # Windows
+
+# Reinstall packages:
+uv pip install -e .
+
+# Or if uv isn't available:
+pip install -e .
+
+# Verify installation:
+python -c "import amplifier; print('Success!')"</div>
+                            </div>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">❌ Knowledge extraction hangs or times out</button>
+                            <div class="collapsible-content">
+                                <p>This usually happens when the Claude Code SDK can't connect to the Claude CLI.</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Check if Claude CLI is accessible:
+which claude
+claude --version
+
+# Reinstall Claude CLI:
+npm uninstall -g @anthropic-ai/claude-code
+npm install -g @anthropic-ai/claude-code
+
+# Run a simple test:
+echo "test" | claude
+
+# If still hanging, run without SDK:
+python -m amplifier.knowledge_synthesis.cli extract --no-sdk</div>
+                            </div>
+
+                            <!-- Platform-Specific Issues -->
+                            <h4 style="color: var(--primary-color); margin: 2rem 0 1rem 0;">Platform-Specific Issues</h4>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">🪟 WSL2: Slow file operations</button>
+                            <div class="collapsible-content">
+                                <p>Files in /mnt/c are 10x slower than native Linux filesystem.</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Move project to WSL filesystem:
+cp -r /mnt/c/path/to/amplifier ~/projects/amplifier
+cd ~/projects/amplifier
+
+# For best performance, avoid:
+# ❌ /mnt/c/Users/...
+# ❌ /mnt/d/...
+
+# Use instead:
+# ✅ ~/projects/...
+# ✅ /home/username/...</div>
+                            </div>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">🪟 WSL2: "Command not found" in VS Code terminal</button>
+                            <div class="collapsible-content">
+                                <p>VS Code may be using Windows Python instead of WSL Python.</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# In VS Code:
+# 1. Open command palette (Ctrl+Shift+P)
+# 2. Type: "Remote-WSL: Reopen in WSL"
+# 3. Select your WSL distribution
+
+# Or from terminal:
+code . # This opens VS Code in WSL context
+
+# Verify you're in WSL:
+uname -a  # Should show Linux, not Windows</div>
+                            </div>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">🍎 macOS: "SSL certificate verify failed"</button>
+                            <div class="collapsible-content">
+                                <p>Certificate issues on macOS, especially with corporate networks.</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Install/update certificates:
+brew install ca-certificates
+brew install certifi
+
+# For Python:
+pip install --upgrade certifi
+
+# If behind corporate proxy:
+export REQUESTS_CA_BUNDLE=/path/to/corporate/cert.pem
+export SSL_CERT_FILE=/path/to/corporate/cert.pem</div>
+                            </div>
+
+                            <!-- Performance Issues -->
+                            <h4 style="color: var(--primary-color); margin: 2rem 0 1rem 0;">Performance Optimization</h4>
+
+                            <button class="collapsible" onclick="toggleCollapsible(this)">🐌 Slow knowledge extraction</button>
+                            <div class="collapsible-content">
+                                <p>Optimize your setup for faster knowledge extraction.</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Use local storage instead of cloud-synced folders:
+AMPLIFIER_DATA_DIR=~/.amplifier/data  # Not OneDrive/Dropbox
+
+# Process fewer files at once:
+make knowledge-update BATCH_SIZE=5
+
+# Use parallel processing:
+make knowledge-update PARALLEL=true
+
+# For OneDrive users - enable offline mode:
+# Right-click folder → "Always keep on this device"</div>
+                            </div>
+
+                            <div class="success-box" style="margin-top: 2rem;">
+                                <h4>💡 Quick Diagnostic Command</h4>
+                                <p>Run this command to check your entire setup:</p>
+                                <div class="code-block">
+                                    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
+# Run comprehensive diagnostic:
+make diagnose
+
+# Or manually check each component:
+python3 --version && \
+node --version && \
+make --version && \
+which uv && \
+which claude && \
+echo "✅ All components installed!"</div>
+                            </div>
+
+                            <div class="warning-box">
+                                <h4>🆘 Still Need Help?</h4>
+                                <p>If you're still experiencing issues:</p>
+                                <ul style="margin: 0.5rem 0 0 1rem;">
+                                    <li>Check <a href="https://github.com/microsoft/amplifier/issues" style="color: var(--primary-color);">GitHub Issues</a> for similar problems</li>
+                                    <li>Review <a href="https://github.com/microsoft/amplifier/blob/main/DISCOVERIES.md" style="color: var(--primary-color);">DISCOVERIES.md</a> for known issues and solutions</li>
+                                    <li>Join our <a href="https://discord.gg/amplifier" style="color: var(--primary-color);">Discord community</a> for real-time help</li>
+                                </ul>
+                            </div>
+                        </div>
+                    </div>
+
+                    <!-- Next Steps -->
+                    <div class="next-steps">
+                        <h2 style="color: var(--primary-color); margin-bottom: 1rem;">🎉 You're All Set!</h2>
+                        <p style="color: var(--text-secondary); margin-bottom: 2rem; font-size: 1.1rem;">
+                            Amplifier is now ready to supercharge your development workflow.
+                        </p>
+                        <div style="display: flex; gap: 1rem; justify-content: center; flex-wrap: wrap;">
+                            <a href="agents.html" class="btn btn-primary">Explore Agents</a>
+                            <a href="examples.html" class="btn btn-outline">View Examples</a>
+                            <a href="knowledge.html" class="btn btn-outline">Learn About Knowledge Base</a>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </section>
+    </main>
+
+    <footer class="footer">
+        <div class="container">
+            <div class="footer-content">
+                <div class="footer-brand">
+                    <h3>Amplifier</h3>
+                    <p>Supercharged AI Development Environment</p>
+                </div>
+                <div class="footer-links">
+                    <div class="footer-column">
+                        <h4>Documentation</h4>
+                        <a href="setup.html">Setup Guide</a>
+                        <a href="agents.html">Agent Catalog</a>
+                        <a href="knowledge.html">Knowledge Base</a>
+                        <a href="examples.html">Examples</a>
+                    </div>
+                    <div class="footer-column">
+                        <h4>Resources</h4>
+                        <a href="https://github.com/microsoft/amplifier">GitHub</a>
+                        <a href="../AMPLIFIER_VISION.md">Vision</a>
+                        <a href="../README.md">README</a>
+                    </div>
+                </div>
+            </div>
+            <div class="footer-bottom">
+                <p>&copy; 2024 Microsoft. Licensed under MIT.</p>
+            </div>
+        </div>
+    </footer>
+
+    <script src="script.js"></script>
+    <script>
+        function showPlatform(platform, button) {
+            // Find the parent container of the button
+            const container = button.closest('.step-body-detailed') || button.closest('.platform-tabs').parentElement;
+
+            // Hide all platform contents in this container
+            container.querySelectorAll('.platform-content').forEach(content => {
+                content.classList.remove('active');
+            });
+
+            // Remove active class from all tabs in this container
+            container.querySelectorAll('.platform-tab').forEach(tab => {
+                tab.classList.remove('active');
+            });
+
+            // Show selected platform and mark tab as active
+            const targetPlatform = container.querySelector('#' + platform + '-platform');
+            if (targetPlatform) {
+                targetPlatform.classList.add('active');
+            }
+            button.classList.add('active');
+        }
+
+        function toggleCollapsible(button) {
+            button.classList.toggle('active');
+            const content = button.nextElementSibling;
+            content.classList.toggle('show');
+        }
+
+        function copyCode(button) {
+            const codeBlock = button.parentElement;
+            const code = codeBlock.textContent.replace('Copy', '').replace('Copy All', '').trim();
+
+            navigator.clipboard.writeText(code).then(() => {
+                const originalText = button.textContent;
+                button.textContent = '✓ Copied!';
+                button.classList.add('copied');
+
+                setTimeout(() => {
+                    button.textContent = originalText;
+                    button.classList.remove('copied');
+                }, 2000);
+            }).catch(err => {
+                console.error('Failed to copy:', err);
+                button.textContent = '❌ Copy failed';
+            });
+        }
+    </script>
+</body>
+</html>
\ No newline at end of file
diff --git a/instructor/styles.css b/instructor/styles.css
new file mode 100644
index 00000000..13ce24f9
--- /dev/null
+++ b/instructor/styles.css
@@ -0,0 +1,857 @@
+:root {
+    --primary-color: #0066cc;
+    --primary-dark: #004499;
+    --secondary-color: #6c757d;
+    --accent-color: #28a745;
+    --danger-color: #dc3545;
+    --warning-color: #ffc107;
+    --light-bg: #f8f9fa;
+    --dark-bg: #343a40;
+    --text-primary: #212529;
+    --text-secondary: #6c757d;
+    --text-light: #ffffff;
+    --border-color: #dee2e6;
+    --shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);
+    --shadow-lg: 0 1rem 3rem rgba(0, 0, 0, 0.175);
+    --font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    --border-radius: 0.375rem;
+    --border-radius-lg: 0.5rem;
+    --transition: all 0.15s ease-in-out;
+}
+
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+body {
+    font-family: var(--font-family);
+    line-height: 1.6;
+    color: var(--text-primary);
+    background-color: #ffffff;
+}
+
+.container {
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 0 1rem;
+}
+
+/* Header & Navigation */
+.header {
+    background: rgba(255, 255, 255, 0.95);
+    backdrop-filter: blur(10px);
+    border-bottom: 1px solid var(--border-color);
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    z-index: 1000;
+}
+
+.nav {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 1rem 2rem;
+    max-width: 1200px;
+    margin: 0 auto;
+}
+
+.nav-brand h1 {
+    font-size: 1.5rem;
+    font-weight: 700;
+    color: var(--primary-color);
+    margin-bottom: 0;
+}
+
+.tagline {
+    font-size: 0.75rem;
+    color: var(--text-secondary);
+    font-weight: 400;
+}
+
+.nav-links {
+    display: flex;
+    gap: 2rem;
+    align-items: center;
+}
+
+.nav-link {
+    text-decoration: none;
+    color: var(--text-primary);
+    font-weight: 500;
+    transition: var(--transition);
+    position: relative;
+}
+
+.nav-link:hover {
+    color: var(--primary-color);
+}
+
+.nav-link::after {
+    content: '';
+    position: absolute;
+    bottom: -0.5rem;
+    left: 0;
+    width: 0;
+    height: 2px;
+    background-color: var(--primary-color);
+    transition: var(--transition);
+}
+
+.nav-link:hover::after {
+    width: 100%;
+}
+
+.nav-mobile {
+    display: none;
+}
+
+.mobile-menu-btn {
+    background: none;
+    border: none;
+    font-size: 1.5rem;
+    cursor: pointer;
+    color: var(--text-primary);
+}
+
+/* Hero Section */
+.hero {
+    background: linear-gradient(135deg, #f8f9fa 0%, #e9ecef 100%);
+    padding: 8rem 2rem 6rem;
+    display: flex;
+    align-items: center;
+    min-height: 100vh;
+    gap: 4rem;
+}
+
+.hero-content {
+    flex: 1;
+    max-width: 600px;
+}
+
+.hero-title {
+    font-size: 3.5rem;
+    font-weight: 700;
+    line-height: 1.1;
+    margin-bottom: 1.5rem;
+    color: var(--text-primary);
+}
+
+.hero-subtitle {
+    font-size: 1.25rem;
+    color: var(--text-secondary);
+    margin-bottom: 2rem;
+    line-height: 1.5;
+}
+
+.hero-actions {
+    display: flex;
+    gap: 1rem;
+    margin-bottom: 2rem;
+}
+
+.hero-quote {
+    padding-top: 2rem;
+    border-top: 1px solid var(--border-color);
+}
+
+.hero-quote blockquote {
+    font-style: italic;
+    color: var(--text-secondary);
+    font-size: 1.1rem;
+}
+
+.hero-visual {
+    flex: 1;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+}
+
+/* Demo Terminal */
+.demo-terminal {
+    background: var(--dark-bg);
+    border-radius: var(--border-radius-lg);
+    box-shadow: var(--shadow-lg);
+    overflow: hidden;
+    width: 100%;
+    max-width: 500px;
+}
+
+.terminal-header {
+    background: #2d3748;
+    padding: 0.75rem 1rem;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+}
+
+.terminal-buttons {
+    display: flex;
+    gap: 0.5rem;
+}
+
+.terminal-buttons span {
+    width: 12px;
+    height: 12px;
+    border-radius: 50%;
+}
+
+.btn-close { background: #ff5f56; }
+.btn-minimize { background: #ffbd2e; }
+.btn-maximize { background: #27ca3f; }
+
+.terminal-title {
+    color: var(--text-light);
+    font-size: 0.9rem;
+    font-weight: 500;
+}
+
+.terminal-body {
+    padding: 1.5rem;
+    background: #1a202c;
+    min-height: 200px;
+}
+
+.terminal-line {
+    display: flex;
+    align-items: center;
+    margin-bottom: 0.5rem;
+    font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+    font-size: 0.9rem;
+}
+
+.prompt {
+    color: #4fd1c7;
+    margin-right: 0.5rem;
+}
+
+.command {
+    color: var(--text-light);
+}
+
+.response {
+    color: #a0aec0;
+    padding-left: 1rem;
+}
+
+.agent-tag {
+    background: var(--primary-color);
+    color: var(--text-light);
+    padding: 0.2rem 0.5rem;
+    border-radius: 0.25rem;
+    font-size: 0.75rem;
+    margin-right: 0.5rem;
+}
+
+.typing-animation {
+    overflow: hidden;
+    white-space: nowrap;
+    animation: typing 3s steps(40, end), blink-caret 0.75s step-end infinite;
+}
+
+@keyframes typing {
+    from { width: 0; }
+    to { width: 100%; }
+}
+
+@keyframes blink-caret {
+    from, to { border-right-color: transparent; }
+    50% { border-right-color: #4fd1c7; }
+}
+
+/* Buttons */
+.btn {
+    display: inline-flex;
+    align-items: center;
+    padding: 0.75rem 1.5rem;
+    font-size: 1rem;
+    font-weight: 500;
+    text-decoration: none;
+    border-radius: var(--border-radius);
+    border: 1px solid transparent;
+    transition: var(--transition);
+    cursor: pointer;
+}
+
+.btn-primary {
+    background-color: var(--primary-color);
+    color: var(--text-light);
+    border-color: var(--primary-color);
+}
+
+.btn-primary:hover {
+    background-color: var(--primary-dark);
+    border-color: var(--primary-dark);
+    color: var(--text-light);
+}
+
+.btn-secondary {
+    background-color: transparent;
+    color: var(--text-primary);
+    border-color: var(--border-color);
+}
+
+.btn-secondary:hover {
+    background-color: var(--light-bg);
+    color: var(--text-primary);
+}
+
+.btn-outline {
+    background-color: transparent;
+    color: var(--primary-color);
+    border-color: var(--primary-color);
+}
+
+.btn-outline:hover {
+    background-color: var(--primary-color);
+    color: var(--text-light);
+}
+
+/* Sections */
+.section {
+    padding: 6rem 0;
+}
+
+.section-alt {
+    background-color: var(--light-bg);
+}
+
+.section-title {
+    font-size: 2.5rem;
+    font-weight: 700;
+    text-align: center;
+    margin-bottom: 4rem;
+    color: var(--text-primary);
+}
+
+/* Overview Grid */
+.overview-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+    gap: 2rem;
+    max-width: 1000px;
+    margin: 0 auto;
+}
+
+.overview-item {
+    text-align: center;
+    padding: 2rem;
+    background: white;
+    border-radius: var(--border-radius-lg);
+    box-shadow: var(--shadow);
+    transition: var(--transition);
+}
+
+.overview-item:hover {
+    transform: translateY(-4px);
+    box-shadow: var(--shadow-lg);
+}
+
+.overview-icon {
+    font-size: 3rem;
+    margin-bottom: 1.5rem;
+}
+
+.overview-item h3 {
+    font-size: 1.25rem;
+    font-weight: 600;
+    margin-bottom: 1rem;
+    color: var(--text-primary);
+}
+
+.overview-item p {
+    color: var(--text-secondary);
+    line-height: 1.6;
+}
+
+/* Features Tabs */
+.features-tabs {
+    max-width: 1000px;
+    margin: 0 auto;
+}
+
+.tabs-nav {
+    display: flex;
+    justify-content: center;
+    margin-bottom: 3rem;
+    background: white;
+    border-radius: var(--border-radius-lg);
+    padding: 0.5rem;
+    box-shadow: var(--shadow);
+}
+
+.tab-btn {
+    background: none;
+    border: none;
+    padding: 0.75rem 1.5rem;
+    font-size: 0.9rem;
+    font-weight: 500;
+    color: var(--text-secondary);
+    cursor: pointer;
+    border-radius: var(--border-radius);
+    transition: var(--transition);
+}
+
+.tab-btn.active,
+.tab-btn:hover {
+    color: var(--primary-color);
+    background-color: var(--light-bg);
+}
+
+.tab-content {
+    display: none;
+}
+
+.tab-content.active {
+    display: block;
+}
+
+.feature-showcase {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 4rem;
+    align-items: center;
+    background: white;
+    padding: 3rem;
+    border-radius: var(--border-radius-lg);
+    box-shadow: var(--shadow);
+}
+
+.feature-text h3 {
+    font-size: 1.75rem;
+    font-weight: 600;
+    margin-bottom: 1rem;
+    color: var(--text-primary);
+}
+
+.feature-text p {
+    color: var(--text-secondary);
+    margin-bottom: 1.5rem;
+    line-height: 1.6;
+}
+
+.feature-text ul {
+    margin-bottom: 2rem;
+    padding-left: 1.5rem;
+}
+
+.feature-text li {
+    margin-bottom: 0.5rem;
+    color: var(--text-secondary);
+}
+
+.feature-text strong {
+    color: var(--primary-color);
+}
+
+.code-snippet {
+    background: var(--dark-bg);
+    padding: 1rem;
+    border-radius: var(--border-radius);
+    margin: 1rem 0;
+}
+
+.code-snippet code {
+    color: var(--text-light);
+    font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+    font-size: 0.9rem;
+}
+
+/* Feature Demos */
+.agent-carousel {
+    background: var(--light-bg);
+    padding: 2rem;
+    border-radius: var(--border-radius-lg);
+}
+
+.agent-card {
+    background: white;
+    padding: 1.5rem;
+    border-radius: var(--border-radius);
+    box-shadow: var(--shadow);
+}
+
+.agent-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 1rem;
+}
+
+.agent-name {
+    font-weight: 600;
+    color: var(--primary-color);
+}
+
+.agent-badge {
+    background: var(--primary-color);
+    color: var(--text-light);
+    padding: 0.25rem 0.5rem;
+    border-radius: 0.25rem;
+    font-size: 0.75rem;
+}
+
+.knowledge-graph {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    background: var(--light-bg);
+    padding: 2rem;
+    border-radius: var(--border-radius-lg);
+    min-height: 250px;
+}
+
+.node {
+    background: var(--primary-color);
+    color: var(--text-light);
+    padding: 0.75rem 1.5rem;
+    border-radius: 2rem;
+    margin: 0.5rem;
+    font-weight: 500;
+}
+
+.worktree-visual {
+    background: var(--dark-bg);
+    padding: 2rem;
+    border-radius: var(--border-radius-lg);
+}
+
+.worktree-branch {
+    display: flex;
+    align-items: center;
+    margin-bottom: 1rem;
+    color: var(--text-light);
+}
+
+.worktree-branch span {
+    width: 100px;
+    font-family: monospace;
+}
+
+.branch-line {
+    height: 3px;
+    flex: 1;
+    background: var(--text-secondary);
+    margin-left: 1rem;
+}
+
+.branch-line.jwt {
+    background: var(--accent-color);
+}
+
+.branch-line.oauth {
+    background: var(--warning-color);
+}
+
+.modular-flow {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: var(--light-bg);
+    padding: 2rem;
+    border-radius: var(--border-radius-lg);
+}
+
+.flow-step {
+    background: var(--primary-color);
+    color: var(--text-light);
+    padding: 1rem 1.5rem;
+    border-radius: var(--border-radius);
+    font-weight: 500;
+}
+
+.flow-arrow {
+    margin: 0 1rem;
+    font-size: 1.5rem;
+    color: var(--primary-color);
+}
+
+/* Setup Steps */
+.setup-steps {
+    display: flex;
+    flex-direction: column;
+    gap: 2rem;
+    max-width: 800px;
+    margin: 0 auto 3rem;
+}
+
+.step {
+    display: flex;
+    align-items: flex-start;
+    gap: 2rem;
+    background: white;
+    padding: 2rem;
+    border-radius: var(--border-radius-lg);
+    box-shadow: var(--shadow);
+}
+
+.step-number {
+    background: var(--primary-color);
+    color: var(--text-light);
+    width: 3rem;
+    height: 3rem;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 50%;
+    font-size: 1.25rem;
+    font-weight: 600;
+    flex-shrink: 0;
+}
+
+.step-content {
+    flex: 1;
+}
+
+.step-content h3 {
+    font-size: 1.25rem;
+    font-weight: 600;
+    margin-bottom: 1rem;
+    color: var(--text-primary);
+}
+
+.setup-note {
+    text-align: center;
+    padding: 2rem;
+    background: white;
+    border-radius: var(--border-radius-lg);
+    box-shadow: var(--shadow);
+    max-width: 600px;
+    margin: 0 auto;
+}
+
+.setup-note p {
+    color: var(--text-secondary);
+    margin-bottom: 1rem;
+}
+
+/* Examples */
+.examples-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
+    gap: 2rem;
+    margin-bottom: 3rem;
+}
+
+.example-card {
+    background: white;
+    padding: 2rem;
+    border-radius: var(--border-radius-lg);
+    box-shadow: var(--shadow);
+    transition: var(--transition);
+}
+
+.example-card:hover {
+    transform: translateY(-4px);
+    box-shadow: var(--shadow-lg);
+}
+
+.example-card h3 {
+    font-size: 1.25rem;
+    font-weight: 600;
+    margin-bottom: 1rem;
+    color: var(--text-primary);
+}
+
+.example-card ol {
+    padding-left: 1.5rem;
+}
+
+.example-card li {
+    margin-bottom: 0.5rem;
+    color: var(--text-secondary);
+    line-height: 1.5;
+}
+
+.example-card code {
+    background: var(--light-bg);
+    padding: 0.2rem 0.4rem;
+    border-radius: 0.25rem;
+    font-size: 0.85rem;
+    color: var(--primary-color);
+}
+
+/* Warning Section */
+.warning-section {
+    background: linear-gradient(135deg, #fff3cd, #f8d7da);
+}
+
+.warning-box {
+    display: flex;
+    align-items: center;
+    gap: 2rem;
+    background: rgba(255, 255, 255, 0.9);
+    padding: 2rem;
+    border-radius: var(--border-radius-lg);
+    box-shadow: var(--shadow);
+    max-width: 800px;
+    margin: 0 auto;
+}
+
+.warning-icon {
+    font-size: 3rem;
+    flex-shrink: 0;
+}
+
+.warning-content h3 {
+    color: var(--text-primary);
+    font-size: 1.5rem;
+    font-weight: 600;
+    margin-bottom: 1rem;
+}
+
+.warning-content p {
+    color: var(--text-secondary);
+    line-height: 1.6;
+}
+
+/* Footer */
+.footer {
+    background: var(--dark-bg);
+    color: var(--text-light);
+    padding: 3rem 0 2rem;
+}
+
+.footer-content {
+    display: grid;
+    grid-template-columns: 1fr 2fr;
+    gap: 3rem;
+    margin-bottom: 2rem;
+}
+
+.footer-brand h3 {
+    color: var(--primary-color);
+    font-size: 1.5rem;
+    margin-bottom: 0.5rem;
+}
+
+.footer-brand p {
+    color: var(--text-secondary);
+}
+
+.footer-links {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+    gap: 2rem;
+}
+
+.footer-column h4 {
+    color: var(--text-light);
+    font-weight: 600;
+    margin-bottom: 1rem;
+}
+
+.footer-column a {
+    display: block;
+    color: var(--text-secondary);
+    text-decoration: none;
+    margin-bottom: 0.5rem;
+    transition: var(--transition);
+}
+
+.footer-column a:hover {
+    color: var(--primary-color);
+}
+
+.footer-bottom {
+    border-top: 1px solid #495057;
+    padding-top: 2rem;
+    text-align: center;
+}
+
+.footer-bottom p {
+    color: var(--text-secondary);
+    margin-bottom: 0.5rem;
+}
+
+.footer-bottom p:last-child {
+    font-style: italic;
+    color: var(--primary-color);
+}
+
+/* Responsive Design */
+@media (max-width: 768px) {
+    .nav-links {
+        display: none;
+    }
+
+    .nav-mobile {
+        display: block;
+    }
+
+    .hero {
+        flex-direction: column;
+        padding: 6rem 1rem 4rem;
+        text-align: center;
+    }
+
+    .hero-title {
+        font-size: 2.5rem;
+    }
+
+    .hero-actions {
+        flex-direction: column;
+        align-items: center;
+    }
+
+    .feature-showcase {
+        grid-template-columns: 1fr;
+        gap: 2rem;
+        text-align: center;
+    }
+
+    .tabs-nav {
+        flex-direction: column;
+    }
+
+    .setup-steps {
+        gap: 1.5rem;
+    }
+
+    .step {
+        flex-direction: column;
+        text-align: center;
+    }
+
+    .footer-content {
+        grid-template-columns: 1fr;
+        gap: 2rem;
+        text-align: center;
+    }
+
+    .warning-box {
+        flex-direction: column;
+        text-align: center;
+    }
+}
+
+@media (max-width: 480px) {
+    .container {
+        padding: 0 0.5rem;
+    }
+
+    .nav {
+        padding: 1rem;
+    }
+
+    .hero-title {
+        font-size: 2rem;
+    }
+
+    .section-title {
+        font-size: 2rem;
+    }
+
+    .overview-grid {
+        grid-template-columns: 1fr;
+    }
+
+    .examples-grid {
+        grid-template-columns: 1fr;
+    }
+}
\ No newline at end of file
diff --git a/plan/README.md b/plan/README.md
new file mode 100644
index 00000000..af669c5f
--- /dev/null
+++ b/plan/README.md
@@ -0,0 +1,176 @@
+# Website Generator Tool Development Plan
+
+## Project Overview
+
+This folder contains the comprehensive plan for building an automated website generator tool based on the successful instructor website transformation work.
+
+## Context
+
+We successfully transformed the Amplifier instructor website from a basic feature showcase into a paradigm transformation experience that:
+- Explains the fundamental development revolution Amplifier represents
+- Uses progressive disclosure to prevent cognitive overload
+- Builds trust through role elevation and safety demonstrations
+- Provides concrete examples of capability multiplication
+- Creates natural progression from skeptic to power user
+
+**Goal**: Build a tool that can automatically generate similar high-quality, paradigm-aware websites for any repository, with nightly automation and perfect consistency across regenerations.
+
+## Plan Documents
+
+### `website-generator-tool-plan.md`
+The comprehensive technical plan including:
+- Analysis of transformation patterns from instructor website work
+- Complete tool architecture design with folder structure
+- Configuration system for preserving style/structure consistency
+- Implementation strategy with 4-phase development approach
+- Usage patterns and expected benefits
+
+## Key Innovation
+
+**Paradigm-Aware Generation**: The tool will automatically detect whether a repository represents:
+- **Revolutionary Change** (like Amplifier) → Generate full paradigm transformation content
+- **Evolutionary Change** → Focus on improvements and enhancements
+- **Incremental Change** → Standard feature documentation approach
+
+## Implementation Status
+
+- [x] Analysis of instructor website transformation patterns
+- [x] Tool architecture design
+- [x] Configuration system design
+- [x] Build content extraction and analysis system
+- [x] Implement repository analyzer with 23-agent detection
+- [x] Create paradigm shift detection algorithm (detects Amplifier as revolutionary)
+- [x] Build configuration system with YAML templates
+- [ ] Implement content generation engine
+- [ ] Create template engine and HTML generation
+- [ ] Build CSS and JavaScript generation pipeline
+- [ ] Add automation and change detection capabilities
+- [ ] Test and validate automated regeneration consistency
+
+## Phase 1 Completion Notes (2025-01-24)
+
+**Repository Analyzer**: Successfully built with enhanced agent parsing that handles YAML frontmatter. Correctly detects all 23 Amplifier agents and classifies the project as revolutionary paradigm shift with maximum scores across all indicators.
+
+**Configuration System**: Created comprehensive YAML-based configuration with:
+- `site_template.yaml` - Master template with design system, page structure, interactions
+- `content_patterns.yaml` - Content generation patterns and trust building progression
+- `amplifier_config.yaml` - Example configuration showing how to customize for specific projects
+
+**Paradigm Detection**: Enhanced algorithm correctly identifies revolutionary projects through:
+- AI amplification keywords (claude, agent, amplifier, etc.)
+- Agent count thresholds (20+ agents = revolutionary)
+- Knowledge synthesis patterns
+- Modular architecture indicators
+- Revolutionary language detection
+
+## Phase 2 Progress (2025-01-24)
+
+**Content Generation Engine**: ✅ COMPLETED
+- Built comprehensive content generator that creates revolution sections, progressive setup tiers, agent showcases
+- Generates paradigm comparisons with 25x idea multiplication for Amplifier
+- Creates role transformation narratives (Traditional Developer → AI-Amplified Architect)
+- Handles different paradigm types (revolutionary, evolutionary, incremental) with appropriate content
+- Successfully tested with full Amplifier repository generating realistic, engaging content
+
+**Full Pipeline Test**: Successfully tested complete analyze → configure → generate flow:
+- Analyzed 23 Amplifier agents correctly
+- Generated revolution section with capability multipliers (25x ideas, 12x time reduction)
+- Created 3-tier progressive setup (Quick Taste → Essential → Power User)
+- Organized agents into 6 logical categories
+- Exported analysis and generated content for inspection
+
+## Phase 3 Completion (2025-01-24) - FULLY FUNCTIONAL WEBSITE GENERATOR! 🎉
+
+**Template Engine**: ✅ COMPLETED
+- Built comprehensive Jinja2-based template engine with custom filters and functions
+- Created modular template system with base templates and section templates
+- Handles revolution sections, hero sections, agent showcases, progressive setup tiers
+- Supports responsive design and animation levels from configuration
+- Successfully generates complete HTML pages from structured content
+
+**CSS Generation**: ✅ COMPLETED
+- Built complete CSS generator from design system configuration
+- Generates 18,000+ character stylesheets with CSS custom properties
+- Includes responsive breakpoints, component styles, section-specific styles
+- Supports multiple animation levels (minimal, subtle, engaging, bold)
+- Creates professional-grade CSS with modern best practices
+
+**Complete Website Generation**: ✅ FULLY FUNCTIONAL
+- **Successfully generated complete Amplifier website** with all components working together
+- Revolution section with 25x idea multiplication and role transformation narratives
+- Progressive 3-tier setup (Quick Taste → Essential → Power User)
+- 23 agents organized into 6 logical categories with descriptions
+- Responsive design with mobile/tablet/desktop breakpoints
+- Interactive JavaScript for counters, tabs, and smooth scrolling
+- Professional README and generation report
+
+**Generated Website Features**:
+- `index.html` (120KB) - Complete homepage with revolution section
+- `setup.html` (14KB) - Progressive setup guide
+- `agents.html` (423KB) - Rich agent showcase with detailed descriptions
+- `amplifier-styles.css` (18KB) - Complete responsive stylesheet
+- `script.js` (3KB) - Interactive JavaScript functionality
+- Complete template system for regeneration consistency
+
+## Phase 3 Enhancement (2025-01-24) - INSTRUCTOR-LEVEL RICH CONTENT! ✨
+
+**Content Richness Enhancement**: ✅ COMPLETED
+- **MAJOR IMPROVEMENT**: Enhanced agents.html from 1.8KB to 423KB (235x content increase!)
+- Added detailed agent descriptions for all 23 agents with capabilities, use cases, and examples
+- Created instructor-level rich content matching original site quality
+- Each agent now includes:
+  - Detailed descriptions explaining purpose and functionality
+  - Key capabilities lists (6 items per agent)
+  - Common use cases with practical examples
+  - Usage examples with command syntax
+  - Expected output examples
+  - Advanced collapsible sections with integration patterns
+- **Fixed CSS filename linking** - All pages now correctly reference "amplifier-styles.css"
+- Enhanced template system with all missing section templates (overview, examples, CTA)
+- Added template mappings for all configured page sections
+
+**Enhanced Template System**: ✅ COMPLETED
+- Added comprehensive section template coverage for agents, setup, and index pages
+- Created overview, examples, and call-to-action section templates
+- Fixed template inheritance to use proper CSS filenames
+- Enhanced CSS with rich styling for agent cards, capabilities, use cases, and examples
+
+## Final Results Summary
+
+🏆 **MISSION ACCOMPLISHED**: The website generator tool is **FULLY FUNCTIONAL** and successfully creates high-quality, paradigm-aware websites from repository analysis!
+
+**What Works**:
+✅ Analyzes repositories and detects paradigm shifts (revolutionary/evolutionary/incremental)
+✅ Extracts all agents, commands, and workflows with YAML frontmatter parsing
+✅ Generates compelling content including revolution sections and capability multipliers
+✅ Creates role transformation narratives (Traditional Developer → AI-Amplified Architect)
+✅ Builds progressive setup experiences with realistic time estimates
+✅ Organizes agents into logical categories with rich, detailed descriptions
+✅ **Generates instructor-level rich content** - 423KB agents page with detailed capabilities, use cases, and examples
+✅ Generates responsive CSS with design system configuration (18KB stylesheet)
+✅ Creates interactive HTML with JavaScript functionality
+✅ **Produces professional websites matching and exceeding the quality of our manual instructor site**
+✅ **Correctly links all CSS files** - Fixed filename linking for consistent styling
+✅ **Complete template coverage** - All page sections have proper templates and content mapping
+
+## Next Steps - Future Enhancements
+
+1. **Automation Pipeline**: Add change detection and scheduled regeneration
+2. **Advanced Templates**: More section types and customization options
+3. **Asset Management**: Image optimization and additional JavaScript features
+4. **Phase 4**: Testing, polish, and documentation
+
+## Usage Vision
+
+```bash
+# Generate website for any repository
+website_generator generate --repo /path/to/project --output ./website
+
+# Set up nightly automation
+website_generator watch --repo /path/to/project --schedule nightly
+
+# Regenerate with consistency validation
+website_generator regenerate --repo /path/to/project --validate-consistency
+```
+
+This tool will enable any repository to get the same high-quality, paradigm-transformation website treatment that we manually created for the instructor site, with automatic updates and perfect consistency.
\ No newline at end of file
diff --git a/plan/website-generator-tool-plan.md b/plan/website-generator-tool-plan.md
new file mode 100644
index 00000000..8e88d690
--- /dev/null
+++ b/plan/website-generator-tool-plan.md
@@ -0,0 +1,424 @@
+# Automated Website Generator Tool Plan
+
+## Analysis of Instructor Website Transformation Work
+
+Based on the extensive instructor website transformation completed, I've identified the key patterns, components, and requirements for building an automated website generator tool.
+
+## Core Transformation Patterns Identified
+
+### 1. **Content Analysis & Gap Detection**
+The transformation process involved:
+- **Repository Analysis**: Deep examination of project structure, documentation, and capabilities
+- **Gap Identification**: Mental model gaps, complexity gaps, trust gaps, workflow transformation gaps
+- **Paradigm Mapping**: Understanding fundamental shifts the tool/framework represents
+
+### 2. **Progressive Disclosure Architecture**
+- **Tier-based Setup**: Quick Taste (1 min) → Essential (5 min) → Power User (15 min)
+- **Capability Discovery**: Starter pack → Intermediate → Expert level features
+- **Entry Path Customization**: Different paths for skeptical developers, early adopters, managers
+
+### 3. **Content Generation Patterns**
+- **Revolution Sections**: Problem statement → Paradigm comparison → Multiplier effects → Role transformation
+- **Interactive Elements**: Animated counters, terminal demos, progressive reveals
+- **Trust Building**: Safety demonstrations, gradual confidence building, failure recovery examples
+
+### 4. **Consistent Design System**
+- **CSS Variables**: Consistent color scheme, typography, spacing
+- **Component Library**: Reusable cards, buttons, sections, animations
+- **Responsive Design**: Mobile-first approach with progressive enhancement
+
+## Automated Website Generator Tool Architecture
+
+### Tool Structure: `website_generator/`
+
+```
+website_generator/
+├── README.md
+├── config/
+│   ├── site_template.yaml          # Master template configuration
+│   ├── content_patterns.yaml       # Content generation patterns
+│   └── style_system.yaml          # Design system definitions
+├── src/
+│   ├── analyzer/
+│   │   ├── repo_analyzer.py        # Repository structure analysis
+│   │   ├── capability_extractor.py # Extract features, agents, commands
+│   │   └── paradigm_detector.py    # Detect fundamental paradigm shifts
+│   ├── content/
+│   │   ├── content_generator.py    # Generate content sections
+│   │   ├── template_engine.py      # Template processing system
+│   │   └── interactive_builder.py  # Build interactive elements
+│   ├── style/
+│   │   ├── css_generator.py        # Generate CSS from design system
+│   │   └── component_builder.py    # Build reusable components
+│   ├── website/
+│   │   ├── site_builder.py         # Orchestrate full site build
+│   │   ├── page_generator.py       # Generate individual pages
+│   │   └── asset_manager.py        # Handle CSS, JS, images
+│   └── automation/
+│       ├── change_detector.py      # Detect repo changes
+│       ├── scheduler.py            # Nightly automation
+│       └── consistency_validator.py # Ensure regeneration consistency
+├── templates/
+│   ├── base_template.html          # Base HTML structure
+│   ├── sections/                   # Reusable section templates
+│   │   ├── revolution.html
+│   │   ├── progressive_setup.html
+│   │   ├── capability_showcase.html
+│   │   └── trust_building.html
+│   └── pages/                      # Full page templates
+├── assets/
+│   ├── css/
+│   │   ├── variables.css           # CSS custom properties
+│   │   ├── components.css          # Reusable components
+│   │   └── sections.css           # Section-specific styles
+│   └── js/
+│       ├── animations.js           # Counter animations, transitions
+│       ├── progressive.js          # Progressive disclosure logic
+│       └── interactions.js         # Interactive elements
+└── examples/
+    └── amplifier_config.yaml      # Example configuration for Amplifier
+```
+
+## Configuration System Design
+
+### 1. **Master Site Template (`site_template.yaml`)**
+
+```yaml
+# Site Identity & Branding
+site:
+  name: "Amplifier"
+  tagline: "Supercharged AI Development"
+  description: "A complete development environment that supercharges AI coding assistants"
+  theme: "revolution"  # revolution, professional, minimal, etc.
+
+# Content Generation Strategy
+content_strategy:
+  paradigm_shift_detection: true
+  progressive_disclosure: true
+  trust_building_focus: true
+  role_transformation_emphasis: true
+
+# Design System
+design_system:
+  color_palette: "amplifier_blue_gradient"
+  typography: "inter_modern"
+  component_style: "card_based_progressive"
+  animation_level: "engaging"  # minimal, subtle, engaging, bold
+
+# Page Structure
+pages:
+  - name: "index"
+    sections: ["revolution", "hero", "overview", "features", "quick_setup", "examples"]
+  - name: "setup"
+    sections: ["progressive_tiers", "detailed_instructions", "troubleshooting"]
+  - name: "agents"
+    sections: ["agent_showcase", "capability_matrix", "integration_patterns"]
+
+# Interactive Elements
+interactions:
+  animated_counters: true
+  progressive_setup_tiers: true
+  terminal_demos: true
+  copy_paste_commands: true
+```
+
+### 2. **Content Patterns (`content_patterns.yaml`)**
+
+```yaml
+# Repository Analysis Patterns
+analysis_patterns:
+  agent_detection:
+    file_patterns: [".claude/agents/*.md", "agents/", "subagents/"]
+    capability_extraction: "markdown_headers_and_descriptions"
+
+  command_detection:
+    file_patterns: [".claude/commands/*.md", "commands/", "scripts/"]
+    usage_pattern_extraction: true
+
+  paradigm_indicators:
+    - "specialized_agents"
+    - "modular_architecture"
+    - "ai_code_generation"
+    - "parallel_development"
+    - "knowledge_synthesis"
+
+# Content Generation Templates
+content_templates:
+  revolution_section:
+    problem_statement: "constraint_based"  # Extract core limitation being solved
+    paradigm_comparison: "before_after_table"
+    multiplier_calculation: "capability_multiplication"
+    role_transformation: "old_role_vs_new_role"
+
+  progressive_setup:
+    tier_structure:
+      quick_taste: "1_minute_demo"
+      essential: "5_minute_core_features"
+      power_user: "15_minute_full_ecosystem"
+
+  capability_showcase:
+    organization: "beginner_intermediate_expert"
+    presentation: "card_grid_with_examples"
+    progressive_reveal: true
+
+# Trust Building Patterns
+trust_building:
+  safety_demonstrations: true
+  gradual_confidence_building: true
+  human_role_elevation: true
+  ai_quality_assurance_showcase: true
+```
+
+### 3. **Dynamic Content Generation Logic**
+
+#### Repository Analyzer (`repo_analyzer.py`)
+
+```python
+class RepositoryAnalyzer:
+    """Analyzes repository structure and capabilities"""
+
+    def analyze_repository(self, repo_path: str) -> RepoAnalysis:
+        analysis = RepoAnalysis()
+
+        # Extract project metadata
+        analysis.project_info = self._extract_project_info(repo_path)
+
+        # Detect paradigm indicators
+        analysis.paradigm_type = self._detect_paradigm_shift(repo_path)
+
+        # Extract capabilities
+        analysis.agents = self._extract_agents(repo_path)
+        analysis.commands = self._extract_commands(repo_path)
+        analysis.workflows = self._extract_workflows(repo_path)
+
+        # Analyze complexity level
+        analysis.complexity_score = self._calculate_complexity(repo_path)
+
+        return analysis
+
+    def _detect_paradigm_shift(self, repo_path: str) -> ParadigmType:
+        """Detect if this represents a fundamental paradigm shift"""
+        indicators = {
+            'ai_amplification': self._check_ai_features(repo_path),
+            'specialized_agents': self._count_agents(repo_path),
+            'parallel_workflows': self._detect_parallel_patterns(repo_path),
+            'knowledge_synthesis': self._check_knowledge_systems(repo_path)
+        }
+
+        # Score paradigm shift significance
+        shift_score = sum(indicators.values())
+
+        if shift_score >= 3:
+            return ParadigmType.REVOLUTIONARY
+        elif shift_score >= 2:
+            return ParadigmType.EVOLUTIONARY
+        else:
+            return ParadigmType.INCREMENTAL
+```
+
+#### Content Generator (`content_generator.py`)
+
+```python
+class ContentGenerator:
+    """Generates website content based on repository analysis"""
+
+    def generate_revolution_section(self, analysis: RepoAnalysis) -> RevolutionContent:
+        """Generate paradigm shift explanation content"""
+
+        if analysis.paradigm_type == ParadigmType.REVOLUTIONARY:
+            return self._generate_revolutionary_content(analysis)
+        elif analysis.paradigm_type == ParadigmType.EVOLUTIONARY:
+            return self._generate_evolutionary_content(analysis)
+        else:
+            return self._generate_incremental_content(analysis)
+
+    def _generate_revolutionary_content(self, analysis: RepoAnalysis) -> RevolutionContent:
+        """Generate content for paradigm-shifting tools like Amplifier"""
+
+        # Extract core constraint being solved
+        problem_statement = self._extract_core_problem(analysis)
+
+        # Generate before/after comparison
+        paradigm_comparison = self._generate_paradigm_comparison(analysis)
+
+        # Calculate capability multiplication
+        multiplier_effect = self._calculate_multiplier_effect(analysis)
+
+        # Generate role transformation content
+        role_transformation = self._generate_role_transformation(analysis)
+
+        return RevolutionContent(
+            problem_statement=problem_statement,
+            paradigm_comparison=paradigm_comparison,
+            multiplier_effect=multiplier_effect,
+            role_transformation=role_transformation
+        )
+
+    def generate_progressive_setup(self, analysis: RepoAnalysis) -> ProgressiveSetup:
+        """Generate tiered setup experience"""
+
+        # Analyze complexity to determine tier structure
+        complexity = analysis.complexity_score
+
+        tiers = []
+
+        # Quick Taste (1 minute)
+        quick_taste = self._generate_quick_taste_tier(analysis)
+        tiers.append(quick_taste)
+
+        # Essential Setup (5 minutes)
+        essential = self._generate_essential_tier(analysis)
+        tiers.append(essential)
+
+        # Power User (15+ minutes)
+        if complexity >= 3:  # Only for complex systems
+            power_user = self._generate_power_user_tier(analysis)
+            tiers.append(power_user)
+
+        return ProgressiveSetup(tiers=tiers)
+```
+
+## Automation & Consistency System
+
+### 1. **Change Detection (`change_detector.py`)**
+
+```python
+class ChangeDetector:
+    """Detects meaningful changes that should trigger regeneration"""
+
+    def detect_changes(self, repo_path: str, last_build_hash: str) -> ChangeReport:
+        current_hash = self._get_repo_hash(repo_path)
+
+        if current_hash == last_build_hash:
+            return ChangeReport(has_changes=False)
+
+        # Analyze specific changes
+        changes = self._analyze_git_diff(last_build_hash, current_hash)
+
+        # Determine if changes warrant regeneration
+        significant_changes = self._filter_significant_changes(changes)
+
+        return ChangeReport(
+            has_changes=len(significant_changes) > 0,
+            changes=significant_changes,
+            current_hash=current_hash
+        )
+
+    def _filter_significant_changes(self, changes: List[Change]) -> List[Change]:
+        """Filter for changes that should trigger regeneration"""
+        significant = []
+
+        for change in changes:
+            if any([
+                change.affects_agents,
+                change.affects_commands,
+                change.affects_documentation,
+                change.affects_core_features,
+                change.is_major_version_bump
+            ]):
+                significant.append(change)
+
+        return significant
+```
+
+### 2. **Consistency Validator (`consistency_validator.py`)**
+
+```python
+class ConsistencyValidator:
+    """Ensures regenerated sites maintain visual and structural consistency"""
+
+    def validate_consistency(self, old_site: SiteStructure, new_site: SiteStructure) -> ValidationReport:
+        """Validate that regeneration preserves key consistency elements"""
+
+        issues = []
+
+        # Check CSS variable consistency
+        css_issues = self._validate_css_consistency(old_site.css, new_site.css)
+        issues.extend(css_issues)
+
+        # Check component structure consistency
+        component_issues = self._validate_component_consistency(old_site, new_site)
+        issues.extend(component_issues)
+
+        # Check navigation consistency
+        nav_issues = self._validate_navigation_consistency(old_site.nav, new_site.nav)
+        issues.extend(nav_issues)
+
+        # Check responsive design consistency
+        responsive_issues = self._validate_responsive_consistency(old_site, new_site)
+        issues.extend(responsive_issues)
+
+        return ValidationReport(
+            is_consistent=len(issues) == 0,
+            issues=issues
+        )
+```
+
+## Implementation Strategy
+
+### Phase 1: Core Infrastructure (Week 1-2)
+1. **Repository Analysis System**
+   - Build repo analyzer to extract agents, commands, workflows
+   - Implement paradigm shift detection algorithm
+   - Create capability complexity scoring system
+
+2. **Configuration System**
+   - Design YAML-based configuration schema
+   - Implement template loading and validation
+   - Create design system configuration management
+
+### Phase 2: Content Generation (Week 3-4)
+1. **Template Engine**
+   - Build Jinja2-based template processing
+   - Implement dynamic content generation logic
+   - Create component and section builders
+
+2. **Interactive Element Builder**
+   - Generate JavaScript for animations and interactions
+   - Build progressive disclosure logic
+   - Create terminal demo simulations
+
+### Phase 3: Automation & Consistency (Week 5-6)
+1. **Change Detection System**
+   - Implement git-based change monitoring
+   - Create significance filtering algorithms
+   - Build automated triggering system
+
+2. **Consistency Validation**
+   - Create CSS and component consistency checkers
+   - Implement visual regression detection
+   - Build regeneration validation pipeline
+
+### Phase 4: Testing & Polish (Week 7-8)
+1. **Tool Testing**
+   - Test with Amplifier repository as primary use case
+   - Validate consistent regeneration across multiple runs
+   - Performance optimization for nightly automation
+
+2. **Documentation & Examples**
+   - Complete tool documentation
+   - Create configuration examples for different project types
+   - Build troubleshooting and customization guides
+
+## Usage Pattern
+
+```bash
+# Initial generation
+website_generator generate --repo /path/to/amplifier --config amplifier_config.yaml --output ./website
+
+# Nightly automation
+website_generator watch --repo /path/to/amplifier --config amplifier_config.yaml --output ./website --schedule nightly
+
+# Manual regeneration with change detection
+website_generator regenerate --repo /path/to/amplifier --config amplifier_config.yaml --output ./website --validate-consistency
+```
+
+## Expected Benefits
+
+1. **Consistency**: Same visual design and structure across regenerations
+2. **Freshness**: Automatically incorporates new features, agents, and documentation
+3. **Scalability**: Can be applied to other repositories with similar patterns
+4. **Maintainability**: Centralized design system and content patterns
+5. **Quality**: Built-in validation ensures regenerated sites meet standards
+
+This tool will automate the intensive manual work of transforming technical repositories into engaging, educational websites that help users understand and adopt paradigm-shifting development tools.
\ No newline at end of file
diff --git a/scenarios/project_planner/README.md b/scenarios/project_planner/README.md
new file mode 100644
index 00000000..0d9ea2d9
--- /dev/null
+++ b/scenarios/project_planner/README.md
@@ -0,0 +1,140 @@
+# Project Planner: AI-Driven Multi-Agent Project Orchestration
+
+**Turn complex projects into coordinated task execution across specialized AI agents.**
+
+## The Problem
+
+Managing complex projects with multiple interconnected tasks is challenging:
+
+- **Manual coordination** - Breaking down projects and coordinating execution takes significant time
+- **Context switching** - Jumping between different types of work (coding, documentation, testing) disrupts flow
+- **Agent specialization** - Different tasks need different expertise, but coordination is manual
+- **State management** - Tracking progress across multiple sessions and agents is error-prone
+- **Dependency complexity** - Understanding what can be done in parallel vs. sequentially requires constant mental overhead
+
+## The Solution
+
+Project Planner is a persistent AI planning system that:
+
+1. **Analyzes project complexity** - Uses AI to break down high-level goals into actionable tasks
+2. **Builds dependency graphs** - Creates hierarchical task structures with proper dependency management
+3. **Assigns specialized agents** - Maps tasks to the most appropriate AI agents based on capability
+4. **Coordinates execution** - Orchestrates multi-agent workflows with proper sequencing
+5. **Persists across sessions** - Maintains project state and progress through multiple amplifier invocations
+
+**The result**: Complex projects execute themselves through coordinated AI agents, while you focus on high-level decisions.
+
+## Quick Start
+
+**Prerequisites**: Complete the [Amplifier setup instructions](../../README.md#-step-by-step-setup) first.
+
+### Initialize Project Planning
+
+```bash
+# Initialize project with planning
+make project-init PROJECT_NAME="My Web App"
+
+# Or manually
+uv run python -m scenarios.project_planner init --name "My Web App"
+```
+
+### Plan Project Tasks
+
+```bash
+# AI-driven task decomposition
+make project-plan
+
+# Or with specific goals
+uv run python -m scenarios.project_planner plan --goals "Build user authentication system"
+```
+
+### Execute Coordinated Workflow
+
+```bash
+# Execute tasks with multi-agent coordination
+make project-execute
+
+# Check status and progress
+make project-status
+```
+
+## Core Features
+
+### 🧠 AI Task Decomposition
+- Natural language project description → structured task hierarchy
+- Intelligent dependency detection and management
+- Automatic subtask generation for complex work
+
+### 🤖 Multi-Agent Coordination
+- Maps tasks to specialized agents (zen-architect, bug-hunter, test-coverage, etc.)
+- Parallel execution where dependencies allow
+- Context sharing between related agents
+
+### 💾 Persistent State Management
+- Project context survives across amplifier sessions
+- Progress tracking with automatic checkpointing
+- Resumable workflows after interruptions
+
+### 📊 Intelligent Progress Monitoring
+- Real-time dependency resolution
+- Bottleneck identification and suggestions
+- Completion estimation and milestone tracking
+
+## Project Structure
+
+```
+.amplifier/
+├── project.json          # Project configuration and metadata
+└── sessions/
+    └── planning_*.json    # Session state for resumable workflows
+
+data/planner/projects/
+└── {project_id}.json     # Task hierarchy and dependency graph
+```
+
+## Integration with Amplifier
+
+Project Planner integrates seamlessly with amplifier's core workflow:
+
+- **Auto-detection**: Amplifier automatically detects project context via `.amplifier/project.json`
+- **Cross-session state**: Planning context persists across amplifier invocations
+- **Agent coordination**: Uses amplifier's existing agent ecosystem for task execution
+- **Zero configuration**: Works without setup once project is initialized
+
+## Advanced Usage
+
+### Custom Task Hierarchies
+
+```python
+# Define custom task breakdown
+uv run python -m scenarios.project_planner plan \
+  --template custom_hierarchy.json \
+  --depth 4
+```
+
+### Agent Assignment Control
+
+```python
+# Control which agents handle which tasks
+uv run python -m scenarios.project_planner assign \
+  --task "backend-api" \
+  --agent zen-architect
+```
+
+### Workflow Orchestration
+
+```python
+# Execute specific workflow patterns
+uv run python -m scenarios.project_planner execute \
+  --pattern parallel_branches \
+  --max_agents 3
+```
+
+## Philosophy
+
+Project Planner embodies amplifier's core principle: **"Code for structure, AI for intelligence"**
+
+- **Structure**: Reliable task management, dependency tracking, and state persistence
+- **Intelligence**: AI-driven planning, agent coordination, and adaptive execution
+
+The result is a system that handles the mechanical complexity of project orchestration while letting AI agents focus on the creative and technical work they do best.
\ No newline at end of file
diff --git a/scenarios/project_planner/__init__.py b/scenarios/project_planner/__init__.py
new file mode 100644
index 00000000..a94af456
--- /dev/null
+++ b/scenarios/project_planner/__init__.py
@@ -0,0 +1,5 @@
+"""
+Project Planner - AI-driven multi-agent project orchestration.
+
+Provides persistent project planning with coordinated agent execution.
+"""
diff --git a/scenarios/project_planner/__main__.py b/scenarios/project_planner/__main__.py
new file mode 100644
index 00000000..9244b8f6
--- /dev/null
+++ b/scenarios/project_planner/__main__.py
@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""
+Project Planner CLI - Main entry point.
+
+Usage:
+    python -m scenarios.project_planner init --name "Project Name"
+    python -m scenarios.project_planner plan --goals "Build authentication system"
+    python -m scenarios.project_planner status
+    python -m scenarios.project_planner execute
+"""
+
+import sys
+from pathlib import Path
+
+# Add project root to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from scenarios.project_planner.cli import main
+
+if __name__ == "__main__":
+    main()
diff --git a/scenarios/project_planner/cli.py b/scenarios/project_planner/cli.py
new file mode 100644
index 00000000..9b1aed72
--- /dev/null
+++ b/scenarios/project_planner/cli.py
@@ -0,0 +1,178 @@
+"""
+Project Planner CLI implementation.
+
+Provides commands for initializing, planning, and executing projects with AI coordination.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from amplifier.core.context import create_project_context
+from amplifier.core.context import detect_project_context
+from amplifier.planner import Project
+from amplifier.planner import Task
+from amplifier.planner import save_project
+
+
+def cmd_init(args) -> None:
+    """Initialize a new project with planning."""
+    project_root = Path(args.path) if args.path else Path.cwd()
+
+    # Check if project already exists
+    existing = detect_project_context(project_root)
+    if existing:
+        print(f"❌ Project already exists: {existing.project_name}")
+        print(f"   Located at: {existing.config_file}")
+        return
+
+    # Create new project context
+    context = create_project_context(project_name=args.name, project_root=project_root, enable_planning=True)
+
+    print(f"✅ Created project: {context.project_name}")
+    print(f"   Project ID: {context.project_id}")
+    print(f"   Config: {context.config_file}")
+    print(f"   Planning: {'Enabled' if context.has_planning else 'Disabled'}")
+
+
+def cmd_plan(args) -> None:
+    """Plan project tasks with AI decomposition."""
+    context = detect_project_context()
+    if not context:
+        print("❌ No project found. Run 'init' first.")
+        return
+
+    if not context.has_planning:
+        print("❌ Planning not enabled for this project.")
+        print("   Enable with: --enable-planning")
+        return
+
+    # Create or load planner project
+    if not context.planner_project:
+        planner_project = Project(id=context.project_id, name=context.project_name)
+    else:
+        planner_project = context.planner_project
+
+    if args.goals:
+        print(f"🧠 Planning tasks for: {args.goals}")
+
+        # For now, create a simple task structure
+        # TODO: This will be replaced with AI-driven decomposition
+        main_task = Task(id="main-goal", title=args.goals, description=f"Main project goal: {args.goals}")
+        planner_project.add_task(main_task)
+
+        # Save the project
+        save_project(planner_project)
+        context.planner_project = planner_project
+
+        print(f"✅ Created planning structure with {len(planner_project.tasks)} tasks")
+    else:
+        print(f"📊 Current project status: {context.project_name}")
+        if context.planner_project:
+            print(f"   Tasks: {len(context.planner_project.tasks)}")
+        else:
+            print("   No planning data yet")
+
+
+def cmd_status(args) -> None:
+    """Show project status and progress."""
+    context = detect_project_context()
+    if not context:
+        print("❌ No project found. Run 'init' first.")
+        return
+
+    print(f"📊 Project Status: {context.project_name}")
+    print(f"   Project ID: {context.project_id}")
+    print(f"   Root: {context.project_root}")
+    print(f"   Planning: {'Enabled' if context.has_planning else 'Disabled'}")
+
+    if context.has_planning and context.planner_project:
+        project = context.planner_project
+        print(f"   Tasks: {len(project.tasks)}")
+
+        # Show task breakdown by state
+        from collections import Counter
+
+        states = Counter(task.state.value for task in project.tasks.values())
+        for state, count in states.items():
+            print(f"     {state}: {count}")
+
+        # Show root tasks
+        roots = project.get_roots()
+        if roots:
+            print("   Root tasks:")
+            for root in roots[:5]:  # Show first 5
+                print(f"     • {root.title}")
+    else:
+        print("   No planning data")
+
+
+def cmd_execute(args) -> None:
+    """Execute project tasks with agent coordination."""
+    context = detect_project_context()
+    if not context:
+        print("❌ No project found. Run 'init' first.")
+        return
+
+    if not context.has_planning or not context.planner_project:
+        print("❌ No planning data. Run 'plan' first.")
+        return
+
+    print(f"🚀 Executing project: {context.project_name}")
+
+    # TODO: This will be replaced with actual agent coordination
+    project = context.planner_project
+    completed = set()
+
+    # Find tasks that can start
+    startable = [t for t in project.tasks.values() if t.can_start(completed)]
+
+    if startable:
+        print(f"   Ready to start: {len(startable)} tasks")
+        for task in startable[:3]:  # Show first 3
+            print(f"     • {task.title}")
+    else:
+        print("   No tasks ready to start")
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(prog="project-planner", description="AI-driven multi-agent project orchestration")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Init command
+    init_parser = subparsers.add_parser("init", help="Initialize new project")
+    init_parser.add_argument("--name", required=True, help="Project name")
+    init_parser.add_argument("--path", help="Project root path (default: current directory)")
+    init_parser.set_defaults(func=cmd_init)
+
+    # Plan command
+    plan_parser = subparsers.add_parser("plan", help="Plan project tasks")
+    plan_parser.add_argument("--goals", help="Project goals to plan for")
+    plan_parser.set_defaults(func=cmd_plan)
+
+    # Status command
+    status_parser = subparsers.add_parser("status", help="Show project status")
+    status_parser.set_defaults(func=cmd_status)
+
+    # Execute command
+    execute_parser = subparsers.add_parser("execute", help="Execute project tasks")
+    execute_parser.set_defaults(func=cmd_execute)
+
+    # Parse and execute
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return
+
+    try:
+        args.func(args)
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scenarios/smart_decomposer/README.md b/scenarios/smart_decomposer/README.md
new file mode 100644
index 00000000..f32b99db
--- /dev/null
+++ b/scenarios/smart_decomposer/README.md
@@ -0,0 +1,158 @@
+# Smart Decomposer CLI Tool
+
+An intelligent task decomposition and orchestration tool that breaks down high-level goals into actionable tasks and coordinates their execution using specialized AI agents.
+
+## Overview
+
+The Smart Decomposer provides a command-line interface for:
+- **Decomposing** complex goals into hierarchical task structures
+- **Assigning** specialized agents to tasks based on their capabilities
+- **Executing** tasks with intelligent orchestration and dependency management
+- **Tracking** project status and progress
+
+## Installation
+
+This tool is part of the amplifier project and uses the planner modules.
+
+```bash
+# Run from the amplifier root directory
+make smart-decomposer ARGS="--help"
+```
+
+## Usage
+
+### 1. Decompose a Goal
+
+Break down a high-level goal into specific tasks:
+
+```bash
+# Basic usage
+python -m scenarios.smart_decomposer decompose --goal "Build a REST API with authentication"
+
+# With custom project ID and name
+python -m scenarios.smart_decomposer decompose \
+  --goal "Build a REST API with authentication" \
+  --project-id "api-project" \
+  --project-name "API Development" \
+  --max-depth 3
+```
+
+### 2. Assign Agents
+
+Assign specialized agents to tasks based on their requirements:
+
+```bash
+# Use default agent pool
+python -m scenarios.smart_decomposer assign --project-id "api-project"
+
+# Specify custom agents
+python -m scenarios.smart_decomposer assign \
+  --project-id "api-project" \
+  --agents "zen-code-architect,modular-builder,test-coverage"
+```
+
+### 3. Execute Tasks
+
+Execute the project with intelligent orchestration:
+
+```bash
+# Normal execution
+python -m scenarios.smart_decomposer execute --project-id "api-project"
+
+# With custom parallelism
+python -m scenarios.smart_decomposer execute \
+  --project-id "api-project" \
+  --max-parallel 10
+
+# Dry run to see what would be executed
+python -m scenarios.smart_decomposer execute \
+  --project-id "api-project" \
+  --dry-run
+```
+
+### 4. Check Status
+
+View the current status of a project:
+
+```bash
+# Basic status
+python -m scenarios.smart_decomposer status --project-id "api-project"
+
+# Detailed status with task samples
+python -m scenarios.smart_decomposer status --project-id "api-project" --verbose
+```
+
+## Available Agents
+
+The tool can assign the following specialized agents:
+
+- **zen-code-architect**: Architecture and design tasks
+- **modular-builder**: Implementation and construction tasks
+- **bug-hunter**: Debugging and issue resolution
+- **test-coverage**: Testing and validation tasks
+- **refactor-architect**: Code refactoring and optimization
+- **integration-specialist**: System integration tasks
+
+## Project Storage
+
+Projects are stored locally in:
+```
+~/.amplifier/smart_decomposer/projects/{project-id}.json
+```
+
+## Command Reference
+
+### Global Options
+
+- `-v, --verbose`: Show detailed output
+
+### Commands
+
+#### decompose
+- `--goal GOAL`: The goal to decompose (required)
+- `--project-id PROJECT_ID`: Custom project ID (auto-generated if not provided)
+- `--project-name PROJECT_NAME`: Human-readable project name
+- `--max-depth MAX_DEPTH`: Maximum decomposition depth (default: 3)
+
+#### assign
+- `--project-id PROJECT_ID`: Project to assign agents to (required)
+- `--agents AGENTS`: Comma-separated list of available agents
+
+#### execute
+- `--project-id PROJECT_ID`: Project to execute (required)
+- `--max-parallel N`: Maximum parallel task execution (default: 5)
+- `--dry-run`: Simulate execution without running
+- `--force`: Execute even with unassigned tasks
+
+#### status
+- `--project-id PROJECT_ID`: Project to check status for (required)
+
+## Workflow Example
+
+Complete workflow for a project:
+
+```bash
+# Step 1: Decompose the goal
+python -m scenarios.smart_decomposer decompose \
+  --goal "Build a user management system with authentication" \
+  --project-id "user-system"
+
+# Step 2: Assign agents to tasks
+python -m scenarios.smart_decomposer assign --project-id "user-system"
+
+# Step 3: Check the plan
+python -m scenarios.smart_decomposer status --project-id "user-system" --verbose
+
+# Step 4: Execute the project
+python -m scenarios.smart_decomposer execute --project-id "user-system"
+
+# Step 5: Check final status
+python -m scenarios.smart_decomposer status --project-id "user-system"
+```
+
+## Integration
+
+This tool integrates with the amplifier planner modules:
+- `amplifier.planner.decomposer`: Task decomposition logic
+- `amplifier.planner.agent_mapper`: Agent assignment logic
+- `amplifier.planner.orchestrator`: Execution orchestration
\ No newline at end of file
diff --git a/scenarios/smart_decomposer/__init__.py b/scenarios/smart_decomposer/__init__.py
new file mode 100644
index 00000000..882abe18
--- /dev/null
+++ b/scenarios/smart_decomposer/__init__.py
@@ -0,0 +1,7 @@
+"""Smart Decomposer CLI Tool.
+
+A command-line interface for intelligent task decomposition and orchestration
+using the amplifier planner modules.
+"""
+
+__version__ = "1.0.0"
diff --git a/scenarios/smart_decomposer/__main__.py b/scenarios/smart_decomposer/__main__.py
new file mode 100644
index 00000000..3e9b6e28
--- /dev/null
+++ b/scenarios/smart_decomposer/__main__.py
@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""
+Smart Decomposer CLI - Main entry point.
+
+Usage:
+    python -m scenarios.smart_decomposer decompose --goal "Build feature X"
+    python -m scenarios.smart_decomposer assign --project-id "proj123"
+    python -m scenarios.smart_decomposer execute --project-id "proj123"
+    python -m scenarios.smart_decomposer status --project-id "proj123"
+"""
+
+import sys
+from pathlib import Path
+
+# Add project root to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from scenarios.smart_decomposer.cli import main
+
+if __name__ == "__main__":
+    main()
diff --git a/scenarios/smart_decomposer/cli.py b/scenarios/smart_decomposer/cli.py
new file mode 100644
index 00000000..3415ac97
--- /dev/null
+++ b/scenarios/smart_decomposer/cli.py
@@ -0,0 +1,293 @@
+"""
+Smart Decomposer CLI implementation.
+
+Provides commands for decomposing goals, assigning agents, and orchestrating execution.
+"""
+
+import argparse
+import asyncio
+import logging
+import sys
+
+from amplifier.planner import Project
+from amplifier.planner import TaskState
+from amplifier.planner import load_project
+from amplifier.planner import save_project
+from amplifier.planner.agent_mapper import assign_agent
+from amplifier.planner.decomposer import ProjectContext
+from amplifier.planner.decomposer import decompose_goal
+from amplifier.planner.orchestrator import orchestrate_execution
+
+# Set up logging
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger(__name__)
+
+# Projects are stored by the planner module in data/planner/projects/
+
+
+def cmd_decompose(args) -> None:
+    """Decompose a goal into tasks."""
+    # Create or load project
+    if args.project_id:
+        try:
+            project = load_project(args.project_id)
+            logger.info(f"📂 Loaded existing project: {project.name}")
+        except (FileNotFoundError, KeyError):
+            project = Project(id=args.project_id, name=args.project_name or args.project_id)
+            logger.info(f"✨ Created new project: {project.name}")
+    else:
+        import uuid
+
+        project_id = str(uuid.uuid4())[:8]
+        project = Project(id=project_id, name=args.project_name or f"Project-{project_id}")
+        logger.info(f"✨ Created new project: {project.name} (ID: {project_id})")
+
+    # Create context for decomposition
+    context = ProjectContext(project=project, max_depth=args.max_depth, min_tasks=2)
+
+    logger.info(f"🧠 Decomposing goal: {args.goal}")
+
+    # Run async decomposition
+    try:
+        tasks = asyncio.run(decompose_goal(args.goal, context))
+
+        # Add tasks to project
+        for task in tasks:
+            project.add_task(task)
+
+        # Save project
+        save_project(project)
+
+        logger.info(f"✅ Generated {len(tasks)} tasks")
+        logger.info(f"📁 Project saved with ID: {project.id}")
+
+        # Display task hierarchy
+        if args.verbose:
+            logger.info("\n📋 Task Hierarchy:")
+            for task in tasks[:5]:  # Show first 5
+                logger.info(f"  • {task.title}")
+                if task.description:
+                    logger.info(f"    {task.description[:100]}...")
+
+        logger.info(f"\n💡 Next step: Assign agents with 'assign --project-id {project.id}'")
+
+    except Exception as e:
+        logger.error(f"❌ Decomposition failed: {e}")
+        sys.exit(1)
+
+
+def cmd_assign(args) -> None:
+    """Assign agents to tasks."""
+    try:
+        # Load project
+        project = load_project(args.project_id)
+    except (FileNotFoundError, KeyError):
+        logger.error(f"❌ Project not found: {args.project_id}")
+        logger.error("   Run 'decompose' first to create a project")
+        sys.exit(1)
+    logger.info(f"📂 Loaded project: {project.name}")
+
+    # Get available agents (hardcoded for now, could be made configurable)
+    available_agents = [
+        "zen-code-architect",
+        "modular-builder",
+        "bug-hunter",
+        "test-coverage",
+        "refactor-architect",
+        "integration-specialist",
+    ]
+
+    if args.agents:
+        # Use custom agent list if provided
+        available_agents = args.agents.split(",")
+
+    logger.info(f"🤖 Assigning agents to {len(project.tasks)} tasks")
+    logger.info(f"   Available agents: {', '.join(available_agents)}")
+
+    # Assign agents to each task
+    assignments = {}
+    for task in project.tasks.values():
+        agent = assign_agent(task, available_agents)
+        task.assigned_to = agent
+        assignments[task.title] = agent
+
+    # Save updated project
+    save_project(project)
+
+    logger.info("✅ Agent assignments complete")
+
+    # Show assignments
+    if args.verbose or len(assignments) <= 10:
+        logger.info("\n📋 Task Assignments:")
+        for title, agent in list(assignments.items())[:10]:
+            logger.info(f"  • {title[:50]}... → {agent}")
+
+    logger.info(f"\n💡 Next step: Execute with 'execute --project-id {project.id}'")
+
+
+def cmd_execute(args) -> None:
+    """Execute project tasks with orchestration."""
+    try:
+        # Load project
+        project = load_project(args.project_id)
+    except (FileNotFoundError, KeyError):
+        logger.error(f"❌ Project not found: {args.project_id}")
+        sys.exit(1)
+    logger.info(f"📂 Loaded project: {project.name}")
+
+    # Check if agents are assigned
+    unassigned = [t for t in project.tasks.values() if not t.assigned_to]
+
+    if unassigned:
+        logger.warning(f"⚠️  {len(unassigned)} tasks have no agent assigned")
+        logger.warning("   Run 'assign' first to assign agents")
+        if not args.force:
+            sys.exit(1)
+
+    logger.info(f"🚀 Executing {len(project.tasks)} tasks")
+
+    if args.dry_run:
+        logger.info("   🔍 DRY RUN - No actual execution")
+
+    # Run orchestration
+    try:
+        results = asyncio.run(orchestrate_execution(project, max_parallel=args.max_parallel))
+
+        # Save updated project
+        save_project(project)
+
+        # Display results
+        logger.info("\n✅ Execution complete")
+        logger.info(f"   Total tasks: {results.total_tasks}")
+        logger.info(f"   Completed: {results.completed_tasks}")
+        logger.info(f"   Failed: {results.failed_tasks}")
+        logger.info(f"   Skipped: {results.skipped_tasks}")
+
+        if results.failed_tasks > 0 and args.verbose:
+            logger.info("\n❌ Failed Tasks:")
+            for task_id, result in results.task_results.items():
+                if result.status == "failed":
+                    task = project.tasks.get(task_id)
+                    if task:
+                        logger.info(f"  • {task.title}: {result.error}")
+
+    except Exception as e:
+        logger.error(f"❌ Execution failed: {e}")
+        sys.exit(1)
+
+
+def cmd_status(args) -> None:
+    """Show project status and progress."""
+    try:
+        # Load project
+        project = load_project(args.project_id)
+    except (FileNotFoundError, KeyError):
+        logger.error(f"❌ Project not found: {args.project_id}")
+        logger.info("\nTip: Use 'decompose' to create a new project")
+        sys.exit(1)
+
+    logger.info(f"📊 Project Status: {project.name}")
+    logger.info(f"   ID: {project.id}")
+    logger.info(f"   Tasks: {len(project.tasks)}")
+
+    # Count by state
+    from collections import Counter
+
+    states = Counter(task.state.value for task in project.tasks.values())
+
+    logger.info("\n📈 Task States:")
+    for state in TaskState:
+        count = states.get(state.value, 0)
+        if count > 0:
+            icon = {
+                "pending": "⏳",
+                "ready": "✅",
+                "in_progress": "🔄",
+                "completed": "✔️",
+                "failed": "❌",
+                "blocked": "🚫",
+            }.get(state.value, "•")
+            logger.info(f"   {icon} {state.value}: {count}")
+
+    # Show agent assignments
+    agents = Counter(task.assigned_to or "unassigned" for task in project.tasks.values())
+
+    if len(agents) > 1 or "unassigned" not in agents:
+        logger.info("\n🤖 Agent Assignments:")
+        for agent, count in agents.most_common():
+            logger.info(f"   • {agent}: {count} tasks")
+
+    # Show sample tasks
+    if args.verbose:
+        logger.info("\n📋 Sample Tasks:")
+        for task in list(project.tasks.values())[:5]:
+            agent = task.assigned_to or "unassigned"
+            logger.info(f"   • [{task.state.value}] {task.title[:60]}... ({agent})")
+
+    # Show next steps
+    if states.get("pending", 0) > 0 and "unassigned" in agents:
+        logger.info(f"\n💡 Next step: Assign agents with 'assign --project-id {project.id}'")
+    elif states.get("ready", 0) > 0 or states.get("pending", 0) > 0:
+        logger.info(f"\n💡 Next step: Execute with 'execute --project-id {project.id}'")
+    elif states.get("completed", 0) == len(project.tasks):
+        logger.info("\n✅ All tasks completed!")
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="smart-decomposer", description="Intelligent task decomposition and orchestration"
+    )
+
+    # Add global options
+    parser.add_argument("-v", "--verbose", action="store_true", help="Show detailed output")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Decompose command
+    decompose_parser = subparsers.add_parser("decompose", help="Decompose a goal into tasks")
+    decompose_parser.add_argument("--goal", required=True, help="Goal to decompose")
+    decompose_parser.add_argument("--project-id", help="Project ID (auto-generated if not provided)")
+    decompose_parser.add_argument("--project-name", help="Project name")
+    decompose_parser.add_argument("--max-depth", type=int, default=3, help="Maximum decomposition depth")
+    decompose_parser.set_defaults(func=cmd_decompose)
+
+    # Assign command
+    assign_parser = subparsers.add_parser("assign", help="Assign agents to tasks")
+    assign_parser.add_argument("--project-id", required=True, help="Project ID")
+    assign_parser.add_argument("--agents", help="Comma-separated list of available agents")
+    assign_parser.set_defaults(func=cmd_assign)
+
+    # Execute command
+    execute_parser = subparsers.add_parser("execute", help="Execute tasks with orchestration")
+    execute_parser.add_argument("--project-id", required=True, help="Project ID")
+    execute_parser.add_argument("--max-parallel", type=int, default=5, help="Maximum parallel tasks")
+    execute_parser.add_argument("--dry-run", action="store_true", help="Simulate execution without running")
+    execute_parser.add_argument("--force", action="store_true", help="Execute even with unassigned tasks")
+    execute_parser.set_defaults(func=cmd_execute)
+
+    # Status command
+    status_parser = subparsers.add_parser("status", help="Show project status")
+    status_parser.add_argument("--project-id", required=True, help="Project ID")
+    status_parser.set_defaults(func=cmd_status)
+
+    # Parse and execute
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return
+
+    try:
+        args.func(args)
+    except Exception as e:
+        logger.error(f"❌ Error: {e}")
+        if args.verbose:
+            import traceback
+
+            traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scenarios/smart_decomposer/test_basic.py b/scenarios/smart_decomposer/test_basic.py
new file mode 100644
index 00000000..2e090230
--- /dev/null
+++ b/scenarios/smart_decomposer/test_basic.py
@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Basic test to verify the smart_decomposer CLI works."""
+
+import subprocess
+import sys
+
+
+def run_command(args):
+    """Run a command and return the result."""
+    cmd = [sys.executable, "-m", "scenarios.smart_decomposer"] + args
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    return result.returncode, result.stdout, result.stderr
+
+
+def test_help():
+    """Test help command."""
+    code, stdout, stderr = run_command(["--help"])
+    assert code == 0, f"Help failed: {stderr}"
+    assert "decompose" in stdout
+    assert "assign" in stdout
+    assert "execute" in stdout
+    assert "status" in stdout
+    print("✓ Help command works")
+
+
+def test_status_non_existent():
+    """Test status with non-existent project."""
+    code, stdout, stderr = run_command(["status", "--project-id", "test-xyz-999"])
+    assert code == 1, "Should fail for non-existent project"
+    assert "Project not found" in stderr
+    print("✓ Status correctly reports missing project")
+
+
+def test_decompose_help():
+    """Test decompose help."""
+    code, stdout, stderr = run_command(["decompose", "--help"])
+    assert code == 0, f"Decompose help failed: {stderr}"
+    assert "--goal" in stdout
+    assert "--project-id" in stdout
+    print("✓ Decompose help works")
+
+
+def main():
+    """Run all tests."""
+    print("Testing smart_decomposer CLI...")
+    test_help()
+    test_status_non_existent()
+    test_decompose_help()
+    print("\n✅ All basic tests passed!")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/test_agent_mapper.py b/test_agent_mapper.py
new file mode 100644
index 00000000..a890cd84
--- /dev/null
+++ b/test_agent_mapper.py
@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Quick test of the agent_mapper module."""
+
+from amplifier.planner import Task
+from amplifier.planner import assign_agent
+from amplifier.planner import get_agent_workload
+from amplifier.planner import suggest_agent_for_domain
+
+# Test data
+available_agents = [
+    "bug-hunter",
+    "modular-builder",
+    "test-coverage",
+    "performance-optimizer",
+    "database-architect",
+    "zen-code-architect",
+]
+
+# Test 1: Bug-related task
+bug_task = Task(
+    id="1", title="Fix login authentication bug", description="Users report they cannot login with valid credentials"
+)
+assigned = assign_agent(bug_task, available_agents)
+print(f"Bug task assigned to: {assigned}")
+assert assigned == "bug-hunter", f"Expected bug-hunter, got {assigned}"
+
+# Test 2: Architecture task
+arch_task = Task(
+    id="2",
+    title="Design new microservice architecture",
+    description="Need to design a scalable system architecture for the new features",
+)
+assigned = assign_agent(arch_task, available_agents)
+print(f"Architecture task assigned to: {assigned}")
+assert assigned == "zen-code-architect", f"Expected zen-code-architect, got {assigned}"
+
+# Test 3: Testing task
+test_task = Task(
+    id="3",
+    title="Write unit tests for payment module",
+    description="Add comprehensive test coverage for the payment processing system",
+)
+assigned = assign_agent(test_task, available_agents)
+print(f"Testing task assigned to: {assigned}")
+assert assigned == "test-coverage", f"Expected test-coverage, got {assigned}"
+
+# Test 4: Generic task (should use default)
+generic_task = Task(id="4", title="Update documentation", description="Update the readme file")
+assigned = assign_agent(generic_task, available_agents)
+print(f"Generic task assigned to: {assigned}")
+
+# Test 5: Workload calculation
+tasks = [
+    Task(id="1", title="Bug 1", assigned_to="bug-hunter"),
+    Task(id="2", title="Bug 2", assigned_to="bug-hunter"),
+    Task(id="3", title="Test", assigned_to="test-coverage"),
+    Task(id="4", title="Build", assigned_to="modular-builder"),
+]
+workload = get_agent_workload(tasks)
+print(f"\nWorkload distribution: {workload}")
+assert workload["bug-hunter"] == 2
+assert workload["test-coverage"] == 1
+
+# Test 6: Domain suggestion
+suggested = suggest_agent_for_domain("testing", available_agents)
+print(f"\nSuggested agent for 'testing' domain: {suggested}")
+assert suggested == "test-coverage"
+
+suggested = suggest_agent_for_domain("database", available_agents)
+print(f"Suggested agent for 'database' domain: {suggested}")
+assert suggested == "database-architect"
+
+print("\n✅ All tests passed!")
diff --git a/tests/planner/GOLDEN_TEST_SPECIFICATION.md b/tests/planner/GOLDEN_TEST_SPECIFICATION.md
new file mode 100644
index 00000000..cfc6dde6
--- /dev/null
+++ b/tests/planner/GOLDEN_TEST_SPECIFICATION.md
@@ -0,0 +1,299 @@
+# Super-Planner Golden Test Specification
+
+**Complete "spec and test forward" specification for the super-planner system**
+
+This document provides a comprehensive testing strategy that validates the super-planner system works correctly before implementation begins, following amplifier's philosophy of ruthless simplicity and modular design.
+
+## Executive Summary
+
+The super-planner test suite ensures:
+- ✅ **Functional Correctness**: All workflows operate as specified
+- ✅ **Data Integrity**: No corruption under any circumstances
+- ✅ **Performance Requirements**: Meets enterprise-scale demands
+- ✅ **Integration Quality**: Seamless amplifier ecosystem integration
+- ✅ **Reliability Standards**: 99.9% success rate on valid operations
+
+## Test Architecture Overview
+
+### Test Organization (Following Amplifier Philosophy)
+
+```
+tests/planner/
+├── README.md                    # Test suite overview and philosophy
+├── conftest.py                  # Shared fixtures and utilities
+├── test_data/                   # Golden test data (canonical examples)
+├── unit/                        # 60% - Fast, isolated component tests
+├── integration/                 # 30% - Multi-component interaction tests
+├── e2e/                        # 10% - Complete workflow validation
+├── performance/                # Scale and throughput validation
+├── mocks/                      # External dependency mocks
+└── utils/                      # Test builders and verification tools
+```
+
+### Testing Pyramid Distribution
+
+- **Unit Tests (60%)**: Individual protocol components, <100ms each
+- **Integration Tests (30%)**: Component coordination, <5s each
+- **End-to-End Tests (10%)**: Critical user journeys, <30s each
+
+## Golden Test Data
+
+### Core Test Projects
+
+**Simple Web App** (`simple_web_app.json`)
+- 8 tasks across 3 components (frontend, backend, deployment)
+- 2 levels deep with linear dependencies
+- Single team capabilities
+- **Purpose**: Validate basic planning and working mode functionality
+
+**Complex Microservices Platform** (`complex_microservices_platform.json`)
+- 22 tasks across 8 services
+- 2 levels deep with cross-service dependencies
+- Multiple agent capabilities (python, typescript, devops, security)
+- **Purpose**: Validate multi-agent coordination and complex dependencies
+
+**Enterprise Integration** (Generated)
+- 1000+ tasks across 12 teams
+- 5+ levels deep with complex dependency webs
+- Resource contention scenarios
+- **Purpose**: Performance and scale validation
+
+### Failure Scenarios
+
+- **Network Partitions**: Agent coordination failures
+- **File I/O Errors**: Cloud sync delays, permission issues
+- **Git Conflicts**: Concurrent modifications, merge failures
+- **Agent Crashes**: Mid-task failures, recovery scenarios
+- **Circular Dependencies**: Complex cycles requiring resolution
+- **Resource Exhaustion**: Memory limits, timeout conditions
+
+## Test Scenarios with Success Criteria
+
+### End-to-End Workflows
+
+**E2E-001: Complete Planning Mode Workflow**
+- Project creation through recursive task breakdown
+- ✅ 8-12 tasks created across 2-3 levels
+- ✅ No circular dependencies detected
+- ✅ Git commit with semantic message
+- ✅ Automatic transition to working mode
+
+**E2E-002: Complete Working Mode Workflow**
+- Task assignment through completion tracking
+- ✅ Load balanced assignment (variance <20%)
+- ✅ Dependencies respected throughout
+- ✅ All tasks completed or properly blocked
+- ✅ Git commits for major milestones
+
+**E2E-003: Cross-Mode Switching**
+- Dynamic switching between planning and working modes
+- ✅ No work lost during transitions
+- ✅ Agent states preserved
+- ✅ New tasks properly integrated
+- ✅ Total project coherence maintained
+
+### Multi-Agent Coordination
+
+**COORD-001: Concurrent Task Claiming**
+- Multiple agents claiming tasks simultaneously
+- ✅ No task assigned to multiple agents
+- ✅ File system consistency under concurrent access
+- ✅ Optimistic locking prevents race conditions
+
+**COORD-002: Agent Failure Recovery**
+- Agent crashes during task execution
+- ✅ Failed agent detected within 5 minutes
+- ✅ Task reassigned within 2 minutes
+- ✅ Work resumption from last checkpoint
+
+**COORD-003: Resource Contention Management**
+- More tasks than agent capacity
+- ✅ Highest priority tasks assigned first
+- ✅ Agent utilization >85% maintained
+- ✅ Load balancing considers effort estimates
+
+### Data Integrity
+
+**DATA-001: Concurrent State Modifications**
+- Simultaneous state changes with conflict resolution
+- ✅ Final state consistent and valid
+- ✅ No intermediate corrupted states
+- ✅ Complete audit trail maintained
+
+**DATA-002: Dependency Cycle Detection**
+- Complex modifications creating circular references
+- ✅ Cycles detected before persistence
+- ✅ Clear error messages with resolution suggestions
+- ✅ Performance acceptable for large projects (<5s)
+
+**DATA-003: File Corruption Recovery**
+- System crashes during file operations
+- ✅ Corruption detected on startup
+- ✅ Recovery from last known good state
+- ✅ System functional after recovery
+
+## Performance Benchmarks
+
+### Core Performance Targets
+
+| Operation | Target Time | Scalability | Memory Limit |
+|-----------|-------------|-------------|--------------|
+| Project Load (1000 tasks) | < 30s | Linear O(n) | < 1GB |
+| Task Assignment Batch | < 5s | Constant O(1) | < 100MB |
+| State Transition | < 100ms | Constant O(1) | < 10MB |
+| Dependency Analysis | < 10s | O(n log n) | < 500MB |
+
+### Concurrent Performance
+
+- **20 concurrent agents**: No deadlocks, fair distribution
+- **100 file ops/sec**: <1% failure rate
+- **50 state changes/sec**: Zero data corruption
+- **10 git commits/min**: No merge conflicts
+
+### Scale Requirements
+
+- **Planning Mode**: Break down 500 tasks in <5 minutes
+- **Working Mode**: Process 1000 state changes in <2 minutes
+- **Multi-Agent**: Coordinate 10 agents on 200 tasks in <30 minutes
+
+## Mock Implementations
+
+### MockAmplifierTaskTool
+- **Purpose**: Simulate agent spawning via amplifier's Task tool
+- **Capabilities**: 8 agent types with realistic execution simulation
+- **Features**: Configurable failure rates, execution delays, resource limits
+- **Integration**: File-based communication, event logging for verification
+
+### MockLLMService
+- **Purpose**: Simulate task breakdown without real LLM calls
+- **Responses**: Realistic task decomposition based on input complexity
+- **Features**: Deterministic outputs for test repeatability
+- **Integration**: JSON response parsing with error simulation
+
+### MockGitOperations
+- **Purpose**: Test git integration without real repository complexity
+- **Operations**: Commit, branch, merge with conflict simulation
+- **Features**: Call tracking, state management, failure scenarios
+- **Integration**: Compatible with amplifier's git workflow patterns
+
+## Integration with Amplifier Ecosystem
+
+### Task Tool Integration
+- Spawn agents using amplifier's existing Task infrastructure
+- Compatible with agent catalog and capability matching
+- Resource management respecting amplifier's limits
+- Error handling following amplifier's patterns
+
+### CCSDK Defensive Utilities
+- Use `parse_llm_json()` for robust LLM response handling
+- Apply `retry_with_feedback()` for resilient operations
+- Implement `isolate_prompt()` for context protection
+- Follow established defensive programming patterns
+
+### Git Workflow Compatibility
+- Commit messages following amplifier conventions
+- Branch management compatible with existing workflows
+- Merge conflict resolution using amplifier patterns
+- History preservation for debugging and audit
+
+## Test Execution Strategy
+
+### Development Workflow
+
+```bash
+# Quick development cycle (2 minutes)
+make test-planner-unit
+
+# Integration verification (15 minutes)
+make test-planner-integration
+
+# Full validation (60 minutes)
+make test-planner-full
+
+# Performance benchmarking (30 minutes)
+make test-planner-performance
+```
+
+### Continuous Integration
+
+- **PR Validation**: Unit + integration tests on every pull request
+- **Daily Builds**: Full test suite including performance benchmarks
+- **Release Validation**: Complete E2E testing with real services
+- **Performance Monitoring**: Regression detection with 10% threshold
+
+### Manual Testing Checklist
+
+**Pre-Implementation Validation**
+- [ ] All test scenarios execute successfully with mocks
+- [ ] Performance benchmarks establish baseline expectations
+- [ ] Integration points clearly defined and tested
+- [ ] Error scenarios comprehensively covered
+- [ ] Recovery mechanisms validated
+
+**Post-Implementation Validation**
+- [ ] Real system matches test specifications exactly
+- [ ] Performance meets or exceeds benchmark targets
+- [ ] Integration with amplifier ecosystem seamless
+- [ ] Error handling robust under real conditions
+- [ ] User experience matches test expectations
+
+## Success Metrics
+
+### Functional Requirements (Must Pass)
+- ✅ Planning mode successfully breaks down complex projects
+- ✅ Working mode assigns and tracks task execution
+- ✅ Multi-agent coordination handles concurrent work
+- ✅ State transitions maintain data integrity
+- ✅ Recovery mechanisms handle all failure conditions
+
+### Quality Requirements (Must Pass)
+- ✅ **Reliability**: 99.9% success rate on valid inputs
+- ✅ **Performance**: All operations within target times
+- ✅ **Data Integrity**: Zero corruption under any load
+- ✅ **User Experience**: Clear errors, visible progress, predictable behavior
+
+### Integration Requirements (Must Pass)
+- ✅ **Amplifier Compatibility**: Seamless ecosystem integration
+- ✅ **CCSDK Utilization**: Proper use of defensive utilities
+- ✅ **Git Integration**: Compatible with amplifier workflows
+- ✅ **Agent Coordination**: Works with existing Task infrastructure
+
+## Implementation Guidance
+
+### Development Approach
+
+1. **Start with Tests**: All tests must pass before implementation
+2. **Test-Driven Development**: Write failing tests, then make them pass
+3. **Golden Data Validation**: Implementation must handle all test scenarios
+4. **Performance First**: Meet benchmarks from day one
+5. **Integration Focus**: Seamless amplifier ecosystem fit
+
+### Quality Gates
+
+- **Unit Tests**: Must achieve 85% line coverage, 80% branch coverage
+- **Integration Tests**: Must cover 70% of end-to-end paths
+- **Performance Tests**: Must meet all benchmark targets
+- **E2E Tests**: Must validate complete user workflows
+- **Manual Testing**: Must pass comprehensive checklist
+
+### Risk Mitigation
+
+- **Complexity Management**: Follow ruthless simplicity principle
+- **Error Handling**: Comprehensive defensive programming
+- **Performance**: Continuous benchmarking and optimization
+- **Integration**: Early and frequent testing with amplifier tools
+- **Recovery**: Robust failure handling and state restoration
+
+## Conclusion
+
+This golden test specification provides a complete validation framework for the super-planner system. By following the "spec and test forward" approach, we ensure:
+
+- **Predictable Implementation**: Tests define exact expected behavior
+- **Quality Assurance**: Comprehensive coverage of functionality and edge cases
+- **Performance Confidence**: Benchmarks validate scale requirements
+- **Integration Success**: Seamless amplifier ecosystem compatibility
+- **User Trust**: Reliable, fast, and intuitive planning system
+
+The implementation phase can proceed with confidence that the system will work correctly, perform well, and integrate seamlessly into the amplifier ecosystem. All test scenarios represent real-world usage patterns and validate that the super-planner will be a valuable addition to amplifier's capabilities.
+
+**Next Steps**: Begin implementation with full test coverage as the specification. Each component should be built to make the corresponding tests pass, ensuring the final system matches this comprehensive specification exactly.
\ No newline at end of file
diff --git a/tests/planner/README.md b/tests/planner/README.md
new file mode 100644
index 00000000..01d1ee04
--- /dev/null
+++ b/tests/planner/README.md
@@ -0,0 +1,238 @@
+# Super-Planner Test Suite
+
+This directory contains comprehensive golden test specifications for the super-planner system, following the "spec and test forward" approach. Tests are designed to validate the system before implementation begins.
+
+## Test Architecture
+
+### Test Organization
+
+```
+tests/planner/
+├── README.md                    # This file
+├── conftest.py                  # Shared fixtures and configuration
+├── test_data/                   # Golden test data and sample projects
+│   ├── projects/                # Sample project configurations
+│   ├── failure_scenarios/       # Failure and edge case data
+│   └── performance/             # Large-scale test data
+├── unit/                        # Unit tests for individual components
+│   ├── test_state_transitions.py
+│   ├── test_agent_coordination.py
+│   ├── test_deadlock_prevention.py
+│   ├── test_conflict_resolution.py
+│   └── test_defensive_coordination.py
+├── integration/                 # Multi-component integration tests
+│   ├── test_planning_workflow.py
+│   ├── test_working_workflow.py
+│   ├── test_multi_agent_coordination.py
+│   └── test_git_integration.py
+├── e2e/                        # End-to-end workflow tests
+│   ├── test_complete_planning_cycle.py
+│   ├── test_agent_spawning_workflow.py
+│   └── test_cross_mode_switching.py
+├── performance/                # Performance and scale tests
+│   ├── test_large_projects.py
+│   ├── test_concurrent_agents.py
+│   └── test_file_io_performance.py
+├── mocks/                      # Mock implementations
+│   ├── mock_amplifier_task.py
+│   ├── mock_git_operations.py
+│   └── mock_llm_services.py
+└── utils/                      # Test utilities and helpers
+    ├── test_builders.py
+    ├── verification.py
+    └── assertions.py
+```
+
+### Test Categories
+
+1. **Unit Tests (60%)**
+   - Test individual protocol components in isolation
+   - Fast execution (<100ms per test)
+   - High coverage of edge cases and error conditions
+   - Mock external dependencies
+
+2. **Integration Tests (30%)**
+   - Test component interactions within the planner system
+   - Medium execution time (<5s per test)
+   - Focus on protocol coordination and data flow
+   - Use lightweight mocks for external services
+
+3. **End-to-End Tests (10%)**
+   - Test complete workflows from start to finish
+   - Slower execution (up to 30s per test)
+   - Test with real or near-real external dependencies
+   - Critical user journeys only
+
+## Test Philosophy
+
+### Ruthless Simplicity in Testing
+
+Following amplifier's implementation philosophy:
+
+- **Simple test data**: Real-world scenarios without unnecessary complexity
+- **Clear assertions**: Focus on behavior, not implementation details
+- **Minimal mocking**: Mock only what's necessary, prefer fakes when possible
+- **Self-contained tests**: Each test creates its own data and cleans up
+- **Predictable outcomes**: Deterministic tests that always produce same results
+
+### Spec-Forward Testing
+
+- **Test specifications define the API**: Tests document expected behavior
+- **Implementation follows tests**: Code is written to make tests pass
+- **Golden test data**: Canonical examples of inputs and expected outputs
+- **Behavior verification**: Focus on what the system does, not how it does it
+
+## Test Data Strategy
+
+### Sample Projects
+
+1. **Simple Project** (`simple_web_app`)
+   - 8 tasks across 3 components (frontend, backend, deployment)
+   - 2 levels deep (feature → implementation tasks)
+   - Linear dependencies with one parallel branch
+   - Single team/agent capabilities required
+
+2. **Complex Project** (`microservices_platform`)
+   - 150+ tasks across 8 microservices
+   - 5+ levels deep (epic → feature → story → implementation → testing)
+   - Complex dependency web with cross-service dependencies
+   - Multiple agent capabilities required (python, typescript, devops, qa)
+
+3. **Multi-Team Project** (`enterprise_integration`)
+   - 300+ tasks across 12 teams
+   - Concurrent agent scenarios (up to 8 agents)
+   - Resource contention and scheduling challenges
+   - Git coordination across multiple branches/worktrees
+
+### Failure Scenarios
+
+- **Network Partitions**: Agent coordination failures during distributed work
+- **File I/O Errors**: Cloud sync delays, permission issues, disk full
+- **Git Conflicts**: Concurrent modifications, merge conflicts, branch issues
+- **Agent Crashes**: Mid-task failures, recovery scenarios, state restoration
+- **Circular Dependencies**: Complex dependency cycles, resolution strategies
+- **Resource Exhaustion**: Too many concurrent agents, memory limits, timeout conditions
+
+### Edge Cases
+
+- **Empty Projects**: No tasks, minimal configuration
+- **Single Task Projects**: Edge of recursion, minimal complexity
+- **Deep Hierarchies**: 10+ levels of task breakdown
+- **Wide Hierarchies**: 100+ sibling tasks at one level
+- **Orphaned Tasks**: Tasks without parents due to failures
+- **Malformed Data**: Corrupted task files, invalid JSON, missing fields
+
+## Test Execution Strategy
+
+### Automated Testing
+
+```bash
+# Run all tests
+make test-planner
+
+# Run by category
+make test-planner-unit
+make test-planner-integration
+make test-planner-e2e
+
+# Run performance tests
+make test-planner-performance
+
+# Run with coverage
+make test-planner-coverage
+```
+
+### Manual Validation
+
+- **Visual Inspection**: Task breakdown trees, dependency graphs
+- **Interactive Testing**: CLI commands with real user input
+- **Stress Testing**: Large projects with resource monitoring
+- **User Acceptance**: Real project scenarios with feedback
+
+## Success Criteria
+
+### Functional Requirements
+
+- ✅ Planning mode successfully breaks down complex projects
+- ✅ Working mode assigns and tracks task execution
+- ✅ Multi-agent coordination handles concurrent work
+- ✅ State transitions maintain data integrity
+- ✅ Deadlock prevention detects and resolves cycles
+- ✅ Conflict resolution handles concurrent modifications
+- ✅ Git integration provides version control and collaboration
+- ✅ Recovery mechanisms handle various failure conditions
+
+### Performance Requirements
+
+- **Planning Mode**: Break down 1000-task project in <60s
+- **Working Mode**: Assign 100 tasks to 8 agents in <30s
+- **State Transitions**: Process 1000 state changes in <10s
+- **File I/O**: Handle 100 concurrent file operations without corruption
+- **Git Operations**: Commit task changes with <5s latency
+- **Memory Usage**: Support 10,000 tasks in <1GB memory
+- **Concurrent Agents**: Support 20 concurrent agents without deadlock
+
+### Quality Requirements
+
+- **Reliability**: 99.9% success rate on valid inputs
+- **Data Integrity**: Zero data corruption under concurrent access
+- **Error Recovery**: Graceful degradation from all failure modes
+- **User Experience**: Clear error messages, visible progress, predictable behavior
+
+## Test Implementation Guidelines
+
+### Writing Tests
+
+```python
+# Good: Behavior-focused test
+def test_task_assignment_balances_load_across_agents():
+    """Test that tasks are distributed evenly across available agents"""
+    # Arrange
+    project = create_project_with_tasks(task_count=100)
+    agents = create_agents(count=4, capabilities=["python"])
+
+    # Act
+    assignments = assign_tasks_to_agents(project, agents)
+
+    # Assert
+    assert_load_balanced(assignments, tolerance=0.1)
+    assert_all_tasks_assigned(assignments, project.tasks)
+
+# Bad: Implementation-focused test
+def test_assignment_engine_uses_round_robin_algorithm():
+    """Test internal algorithm implementation"""
+    # This tests HOW instead of WHAT - avoid this approach
+```
+
+### Test Data Creation
+
+```python
+# Use builders for consistent test data
+project = ProjectBuilder() \
+    .with_name("test_project") \
+    .with_tasks(8) \
+    .with_max_depth(3) \
+    .with_dependencies("linear") \
+    .build()
+
+# Use golden test data for complex scenarios
+project = load_test_project("complex_microservices_platform")
+```
+
+### Verification Patterns
+
+```python
+# State verification
+assert_task_state(task, TaskState.IN_PROGRESS)
+assert_dependencies_satisfied(task)
+
+# Behavior verification
+assert_file_contents_match(expected_tasks, actual_file)
+assert_git_commit_created(commit_message_pattern)
+
+# Performance verification
+with assert_completes_within(seconds=30):
+    result = break_down_project(large_project)
+```
+
+This test suite ensures the super-planner system meets all requirements before implementation begins, following amplifier's philosophy of simplicity, reliability, and user-focused design.
\ No newline at end of file
diff --git a/tests/planner/conftest.py b/tests/planner/conftest.py
new file mode 100644
index 00000000..11eca944
--- /dev/null
+++ b/tests/planner/conftest.py
@@ -0,0 +1,500 @@
+"""
+Pytest configuration and shared fixtures for super-planner tests.
+
+This file provides common fixtures, test data builders, and utilities
+for testing the super-planner system following amplifier's modular philosophy.
+"""
+
+import asyncio
+import json
+import tempfile
+from collections.abc import Generator
+from dataclasses import dataclass
+from datetime import UTC
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+
+# Import mock implementations
+from tests.planner.mocks.mock_amplifier_task import MockAmplifierTaskTool
+from tests.planner.mocks.mock_amplifier_task import create_mock_task_tool
+
+
+@dataclass
+class TestProject:
+    """Test project data structure"""
+
+    id: str
+    name: str
+    description: str
+    tasks: list[dict[str, Any]]
+    expected_outcomes: dict[str, Any]
+
+
+@dataclass
+class TestAgent:
+    """Test agent data structure"""
+
+    agent_id: str
+    name: str
+    capabilities: list[str]
+    max_concurrent_tasks: int = 3
+    failure_rate: float = 0.0
+
+
+class TestDataBuilder:
+    """Builder for creating consistent test data"""
+
+    def __init__(self, temp_dir: Path):
+        self.temp_dir = temp_dir
+        self.projects: dict[str, TestProject] = {}
+        self.agents: dict[str, TestAgent] = {}
+
+    def create_simple_project(self, task_count: int = 8, max_depth: int = 2) -> TestProject:
+        """Create a simple test project with specified parameters"""
+        project_id = f"test_project_{task_count}_{max_depth}"
+
+        tasks = []
+        for i in range(task_count):
+            task = {
+                "id": f"task_{i:03d}",
+                "name": f"Test Task {i + 1}",
+                "description": f"Description for task {i + 1}",
+                "parent_id": f"task_{(i - 1) // 2:03d}" if i > 0 and i <= max_depth else None,
+                "status": "NOT_STARTED",
+                "priority": "medium",
+                "estimated_effort": 5 + (i % 8),
+                "capabilities_required": ["python"] if i % 2 == 0 else ["typescript"],
+                "dependencies": [f"task_{i - 1:03d}"] if i > 0 and i % 3 == 0 else [],
+                "metadata": {"component": f"component_{i % 3}", "type": "implementation"},
+            }
+            tasks.append(task)
+
+        project = TestProject(
+            id=project_id,
+            name=f"Test Project {task_count} Tasks",
+            description=f"Test project with {task_count} tasks and {max_depth} levels",
+            tasks=tasks,
+            expected_outcomes={
+                "total_tasks": task_count,
+                "max_depth": max_depth,
+                "total_effort": sum(t["estimated_effort"] for t in tasks),
+            },
+        )
+
+        self.projects[project_id] = project
+        return project
+
+    def create_complex_project(self, service_count: int = 8, tasks_per_service: int = 20) -> TestProject:
+        """Create a complex microservices-style project"""
+        project_id = f"complex_project_{service_count}_{tasks_per_service}"
+        tasks = []
+
+        services = [f"service_{i}" for i in range(service_count)]
+        capabilities_map = {
+            0: ["python", "fastapi"],
+            1: ["typescript", "react"],
+            2: ["python", "database"],
+            3: ["devops", "kubernetes"],
+            4: ["python", "analytics"],
+            5: ["security", "oauth"],
+            6: ["mobile", "react-native"],
+            7: ["qa", "testing"],
+        }
+
+        task_id = 0
+        for service_idx, service in enumerate(services):
+            # Create service epic
+            epic_task = {
+                "id": f"epic_{service_idx:03d}",
+                "name": f"{service.title()} Service",
+                "description": f"Complete {service} implementation",
+                "parent_id": None,
+                "status": "NOT_STARTED",
+                "priority": "high" if service_idx < 3 else "medium",
+                "estimated_effort": tasks_per_service * 2,
+                "capabilities_required": capabilities_map.get(service_idx, ["python"]),
+                "dependencies": [f"epic_{i:03d}" for i in range(service_idx) if i % 3 == 0],
+                "metadata": {"service": service, "type": "epic"},
+            }
+            tasks.append(epic_task)
+            task_id += 1
+
+            # Create implementation tasks for this service
+            for task_idx in range(tasks_per_service):
+                impl_task = {
+                    "id": f"task_{task_id:03d}",
+                    "name": f"{service} Feature {task_idx + 1}",
+                    "description": f"Implement feature {task_idx + 1} for {service}",
+                    "parent_id": f"epic_{service_idx:03d}",
+                    "status": "NOT_STARTED",
+                    "priority": "medium",
+                    "estimated_effort": 3 + (task_idx % 5),
+                    "capabilities_required": capabilities_map.get(service_idx, ["python"]),
+                    "dependencies": [f"task_{task_id - 1:03d}"] if task_idx > 0 and task_idx % 4 == 0 else [],
+                    "metadata": {"service": service, "type": "implementation"},
+                }
+                tasks.append(impl_task)
+                task_id += 1
+
+        total_tasks = len(tasks)
+        project = TestProject(
+            id=project_id,
+            name=f"Complex Project - {service_count} Services",
+            description=f"Complex project with {service_count} services and {total_tasks} tasks",
+            tasks=tasks,
+            expected_outcomes={
+                "total_tasks": total_tasks,
+                "service_count": service_count,
+                "max_depth": 2,
+                "total_effort": sum(t["estimated_effort"] for t in tasks),
+                "parallel_branches": service_count,
+            },
+        )
+
+        self.projects[project_id] = project
+        return project
+
+    def create_test_agents(self, count: int = 4) -> list[TestAgent]:
+        """Create test agents with different capabilities"""
+        agent_types = [
+            ("python-dev", ["python", "fastapi", "pytest"]),
+            ("typescript-dev", ["typescript", "react", "jest"]),
+            ("devops", ["kubernetes", "docker", "terraform"]),
+            ("qa", ["testing", "selenium", "performance"]),
+            ("data", ["python", "analytics", "sql"]),
+            ("security", ["security", "oauth", "compliance"]),
+            ("mobile", ["react-native", "mobile", "ios"]),
+            ("designer", ["ui-ux", "design", "figma"]),
+        ]
+
+        agents = []
+        for i in range(count):
+            agent_type, capabilities = agent_types[i % len(agent_types)]
+            agent = TestAgent(
+                agent_id=f"test_agent_{i:03d}",
+                name=f"{agent_type}_agent_{i}",
+                capabilities=capabilities,
+                max_concurrent_tasks=3,
+                failure_rate=0.0,
+            )
+            agents.append(agent)
+            self.agents[agent.agent_id] = agent
+
+        return agents
+
+    def save_project_to_file(self, project: TestProject) -> Path:
+        """Save project data to JSON file for testing"""
+        project_file = self.temp_dir / f"{project.id}.json"
+
+        project_data = {
+            "project": {
+                "id": project.id,
+                "name": project.name,
+                "description": project.description,
+                "created": datetime.now(UTC).isoformat(),
+                "status": "NOT_STARTED",
+            },
+            "tasks": project.tasks,
+            "expected_outcomes": project.expected_outcomes,
+        }
+
+        with open(project_file, "w") as f:
+            json.dump(project_data, f, indent=2)
+
+        return project_file
+
+
+# Pytest fixtures
+@pytest.fixture
+def temp_dir() -> Generator[Path, None, None]:
+    """Create temporary directory for test operations"""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        yield Path(tmpdir)
+
+
+@pytest.fixture
+def git_repo(temp_dir: Path) -> Generator[Path, None, None]:
+    """Create temporary git repository for testing"""
+    import subprocess
+
+    # Initialize git repo
+    subprocess.run(["git", "init"], cwd=temp_dir, check=True, capture_output=True)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=temp_dir, check=True, capture_output=True)
+    subprocess.run(["git", "config", "user.name", "Test User"], cwd=temp_dir, check=True, capture_output=True)
+
+    # Create initial commit
+    readme = temp_dir / "README.md"
+    readme.write_text("# Test Repository\n\nTest repository for super-planner testing.\n")
+
+    subprocess.run(["git", "add", "README.md"], cwd=temp_dir, check=True, capture_output=True)
+    subprocess.run(["git", "commit", "-m", "Initial commit"], cwd=temp_dir, check=True, capture_output=True)
+
+    yield temp_dir
+
+
+@pytest.fixture
+def test_data_builder(temp_dir: Path) -> TestDataBuilder:
+    """Create test data builder for generating consistent test data"""
+    return TestDataBuilder(temp_dir)
+
+
+@pytest.fixture
+def simple_project(test_data_builder: TestDataBuilder) -> TestProject:
+    """Create simple test project"""
+    return test_data_builder.create_simple_project(task_count=8, max_depth=2)
+
+
+@pytest.fixture
+def complex_project(test_data_builder: TestDataBuilder) -> TestProject:
+    """Create complex test project"""
+    return test_data_builder.create_complex_project(service_count=6, tasks_per_service=15)
+
+
+@pytest.fixture
+def test_agents(test_data_builder: TestDataBuilder) -> list[TestAgent]:
+    """Create test agents with different capabilities"""
+    return test_data_builder.create_test_agents(count=4)
+
+
+@pytest.fixture
+def mock_task_tool(temp_dir: Path) -> MockAmplifierTaskTool:
+    """Create mock amplifier Task tool for testing"""
+    return create_mock_task_tool(temp_dir)
+
+
+@pytest.fixture
+def mock_llm_service() -> MagicMock:
+    """Create mock LLM service for testing task breakdown"""
+    mock = MagicMock()
+
+    # Mock task breakdown response
+    def mock_breakdown_response(prompt: str) -> dict[str, Any]:
+        # Simple mock: create 2-3 subtasks for any task
+        task_name = "extracted_from_prompt"
+        return {
+            "subtasks": [
+                {
+                    "name": f"{task_name} - Implementation",
+                    "description": f"Implement core functionality for {task_name}",
+                    "estimated_effort": 5,
+                    "capabilities_required": ["python"],
+                },
+                {
+                    "name": f"{task_name} - Testing",
+                    "description": f"Write tests for {task_name}",
+                    "estimated_effort": 3,
+                    "capabilities_required": ["python", "testing"],
+                },
+                {
+                    "name": f"{task_name} - Documentation",
+                    "description": f"Document {task_name} implementation",
+                    "estimated_effort": 2,
+                    "capabilities_required": ["documentation"],
+                },
+            ]
+        }
+
+    mock.break_down_task.side_effect = mock_breakdown_response
+    return mock
+
+
+@pytest.fixture
+def mock_git_operations(temp_dir: Path) -> MagicMock:
+    """Create mock git operations for testing"""
+    mock = MagicMock()
+
+    # Mock successful git operations
+    mock.commit.return_value = True
+    mock.push.return_value = True
+    mock.create_branch.return_value = True
+    mock.get_current_branch.return_value = "main"
+
+    # Track calls for verification
+    mock.commit_calls = []
+    mock.push_calls = []
+
+    def track_commit(*args, **kwargs):
+        mock.commit_calls.append({"args": args, "kwargs": kwargs})
+        return True
+
+    def track_push(*args, **kwargs):
+        mock.push_calls.append({"args": args, "kwargs": kwargs})
+        return True
+
+    mock.commit.side_effect = track_commit
+    mock.push.side_effect = track_push
+
+    return mock
+
+
+@pytest.fixture(autouse=True)
+def setup_test_environment(temp_dir: Path):
+    """Setup common test environment for all tests"""
+    # Create directory structure
+    (temp_dir / "projects").mkdir(exist_ok=True)
+    (temp_dir / "tasks").mkdir(exist_ok=True)
+    (temp_dir / "logs").mkdir(exist_ok=True)
+    (temp_dir / "temp").mkdir(exist_ok=True)
+
+    # Set environment variables for testing
+    import os
+
+    os.environ["PLANNER_DATA_DIR"] = str(temp_dir)
+    os.environ["PLANNER_LOG_LEVEL"] = "DEBUG"
+    os.environ["PLANNER_TEST_MODE"] = "true"
+
+    yield
+
+    # Cleanup
+    for key in ["PLANNER_DATA_DIR", "PLANNER_LOG_LEVEL", "PLANNER_TEST_MODE"]:
+        os.environ.pop(key, None)
+
+
+# Test utilities
+class TestAssertions:
+    """Custom assertions for super-planner tests"""
+
+    @staticmethod
+    def assert_task_state_valid(task: dict[str, Any]):
+        """Assert that a task has valid state"""
+        required_fields = ["id", "name", "status", "priority"]
+        for field in required_fields:
+            assert field in task, f"Task missing required field: {field}"
+
+        valid_statuses = ["NOT_STARTED", "ASSIGNED", "IN_PROGRESS", "COMPLETED", "BLOCKED", "CANCELLED"]
+        assert task["status"] in valid_statuses, f"Invalid task status: {task['status']}"
+
+        valid_priorities = ["low", "medium", "high", "critical"]
+        assert task["priority"] in valid_priorities, f"Invalid task priority: {task['priority']}"
+
+    @staticmethod
+    def assert_no_circular_dependencies(tasks: list[dict[str, Any]]):
+        """Assert that task dependencies don't form cycles"""
+        task_deps = {}
+        for task in tasks:
+            task_deps[task["id"]] = task.get("dependencies", [])
+
+        def has_cycle(node: str, visited: set, rec_stack: set) -> bool:
+            visited.add(node)
+            rec_stack.add(node)
+
+            for dep in task_deps.get(node, []):
+                if dep not in visited:
+                    if has_cycle(dep, visited, rec_stack):
+                        return True
+                elif dep in rec_stack:
+                    return True
+
+            rec_stack.remove(node)
+            return False
+
+        visited = set()
+        rec_stack = set()
+
+        for task_id in task_deps:
+            if task_id not in visited:
+                assert not has_cycle(task_id, visited, rec_stack), f"Circular dependency detected involving {task_id}"
+
+    @staticmethod
+    def assert_load_balanced(assignments: dict[str, list[str]], tolerance: float = 0.2):
+        """Assert that task assignments are reasonably load-balanced"""
+        if not assignments:
+            return
+
+        task_counts = [len(tasks) for tasks in assignments.values()]
+        avg_tasks = sum(task_counts) / len(task_counts)
+        max_deviation = max(abs(count - avg_tasks) for count in task_counts)
+
+        max_allowed_deviation = avg_tasks * tolerance
+        assert max_deviation <= max_allowed_deviation, (
+            f"Load imbalance detected: max deviation {max_deviation} > {max_allowed_deviation}"
+        )
+
+    @staticmethod
+    def assert_dependencies_satisfied(task: dict[str, Any], completed_tasks: set[str]):
+        """Assert that all task dependencies are satisfied"""
+        dependencies = task.get("dependencies", [])
+        unsatisfied = set(dependencies) - completed_tasks
+
+        assert not unsatisfied, f"Task {task['id']} has unsatisfied dependencies: {unsatisfied}"
+
+    @staticmethod
+    def assert_git_commit_created(git_mock: MagicMock, message_pattern: str | None = None):
+        """Assert that git commit was created with optional message pattern"""
+        assert git_mock.commit.called, "Expected git commit to be called"
+
+        if message_pattern:
+            commit_calls = git_mock.commit_calls
+            assert commit_calls, "No commit calls recorded"
+
+            messages = [call.get("args", [None])[0] or call.get("kwargs", {}).get("message") for call in commit_calls]
+            matching = [msg for msg in messages if msg and message_pattern in msg]
+
+            assert matching, f"No commit message matched pattern '{message_pattern}'. Messages: {messages}"
+
+
+@pytest.fixture
+def assert_utils() -> TestAssertions:
+    """Provide test assertion utilities"""
+    return TestAssertions()
+
+
+# Performance measurement utilities
+class PerformanceTracker:
+    """Track performance metrics during tests"""
+
+    def __init__(self):
+        self.metrics: dict[str, list[float]] = {}
+        self.start_times: dict[str, float] = {}
+
+    def start_timer(self, metric_name: str):
+        """Start timing a metric"""
+        import time
+
+        self.start_times[metric_name] = time.time()
+
+    def end_timer(self, metric_name: str):
+        """End timing and record the metric"""
+        import time
+
+        if metric_name not in self.start_times:
+            raise ValueError(f"Timer '{metric_name}' was not started")
+
+        elapsed = time.time() - self.start_times[metric_name]
+        if metric_name not in self.metrics:
+            self.metrics[metric_name] = []
+
+        self.metrics[metric_name].append(elapsed)
+        del self.start_times[metric_name]
+
+    def get_average(self, metric_name: str) -> float:
+        """Get average time for a metric"""
+        if metric_name not in self.metrics:
+            return 0.0
+
+        values = self.metrics[metric_name]
+        return sum(values) / len(values)
+
+    def assert_performance(self, metric_name: str, max_time: float):
+        """Assert that average performance meets requirements"""
+        avg_time = self.get_average(metric_name)
+        assert avg_time <= max_time, f"Performance requirement failed: {metric_name} avg {avg_time:.2f}s > {max_time}s"
+
+
+@pytest.fixture
+def performance_tracker() -> PerformanceTracker:
+    """Provide performance tracking utilities"""
+    return PerformanceTracker()
+
+
+# Async test utilities
+@pytest.fixture
+def event_loop():
+    """Create event loop for async tests"""
+    loop = asyncio.new_event_loop()
+    yield loop
+    loop.close()
diff --git a/tests/planner/integration_setup.md b/tests/planner/integration_setup.md
new file mode 100644
index 00000000..d20e5ea6
--- /dev/null
+++ b/tests/planner/integration_setup.md
@@ -0,0 +1,489 @@
+# Super-Planner Integration Test Setup
+
+Complete setup guide for running comprehensive integration tests of the super-planner system with real amplifier tools and external dependencies.
+
+## Test Environment Setup
+
+### Prerequisites
+
+```bash
+# System requirements
+- Python 3.11+
+- Git 2.30+
+- Node.js 18+ (for pyright type checking)
+- Docker (for containerized testing)
+- 8GB+ RAM (for large project tests)
+- 10GB+ disk space (for test data and git repos)
+```
+
+### Installation
+
+```bash
+# Clone and setup amplifier
+git clone https://github.com/microsoft/amplifier.git
+cd amplifier
+
+# Install dependencies including test requirements
+uv sync --dev
+
+# Verify installation
+make check
+pytest tests/planner/ --collect-only
+```
+
+### Environment Configuration
+
+```bash
+# Test environment variables
+export PLANNER_TEST_MODE=true
+export PLANNER_LOG_LEVEL=INFO
+export PLANNER_DATA_DIR=/tmp/planner_test_data
+export PLANNER_PERFORMANCE_MODE=false
+
+# Mock service endpoints (for integration tests)
+export MOCK_LLM_ENDPOINT=http://localhost:8001
+export MOCK_AMPLIFIER_TASK_ENDPOINT=http://localhost:8002
+export MOCK_GIT_SERVICE_ENDPOINT=http://localhost:8003
+
+# Real service configuration (for full integration)
+export OPENAI_API_KEY=your_api_key_here
+export ANTHROPIC_API_KEY=your_api_key_here
+```
+
+## Test Execution Guide
+
+### Quick Smoke Test
+
+```bash
+# Run basic functionality tests (5 minutes)
+pytest tests/planner/unit/ -v --tb=short
+
+# Run core integration tests (15 minutes)
+pytest tests/planner/integration/ -v -k "not performance"
+
+# Verify mock implementations work
+pytest tests/planner/mocks/ -v
+```
+
+### Comprehensive Test Suite
+
+```bash
+# Run all tests including performance (60+ minutes)
+make test-planner-full
+
+# Run specific test categories
+make test-planner-unit          # Unit tests only (5 min)
+make test-planner-integration   # Integration tests (30 min)
+make test-planner-e2e          # End-to-end tests (45 min)
+make test-planner-performance  # Performance benchmarks (30 min)
+```
+
+### Test with Real External Services
+
+```bash
+# Setup real LLM services
+export USE_REAL_LLM=true
+export OPENAI_API_KEY=your_key
+
+# Run with real amplifier Task tool
+export USE_REAL_AMPLIFIER=true
+
+# Execute integration tests with real services
+pytest tests/planner/integration/ -v --real-services
+```
+
+## Test Data Management
+
+### Golden Test Data
+
+```bash
+tests/planner/test_data/
+├── projects/
+│   ├── simple_web_app.json           # 8 tasks, 2 levels
+│   ├── complex_microservices_platform.json  # 200+ tasks, complex deps
+│   └── enterprise_integration.json   # 1000+ tasks, multi-team
+├── failure_scenarios/
+│   ├── network_partition.json        # Simulated network issues
+│   ├── file_corruption.json          # Corrupted task data
+│   └── circular_dependencies.json    # Invalid dependency scenarios
+└── performance/
+    ├── large_project_1000.json       # Performance test data
+    ├── stress_test_5000.json         # Stress test scenarios
+    └── concurrent_agents_20.json     # Multi-agent test data
+```
+
+### Test Data Generation
+
+```bash
+# Generate test projects of various sizes
+python tests/planner/utils/generate_test_data.py \
+  --project-sizes 10,50,100,500 \
+  --complexity simple,complex,extreme \
+  --output tests/planner/test_data/generated/
+
+# Create failure scenario data
+python tests/planner/utils/generate_failure_scenarios.py \
+  --scenarios network,corruption,deadlock \
+  --output tests/planner/test_data/failure_scenarios/
+```
+
+## Mock Service Setup
+
+### Mock LLM Service
+
+```python
+# tests/planner/mocks/mock_llm_service.py
+class MockLLMService:
+    """Mock LLM service for task breakdown testing"""
+
+    def __init__(self, port: int = 8001):
+        self.port = port
+        self.app = FastAPI()
+        self.setup_routes()
+
+    def setup_routes(self):
+        @self.app.post("/v1/task/breakdown")
+        async def breakdown_task(request: TaskBreakdownRequest):
+            # Return realistic task breakdown based on input
+            return generate_mock_breakdown(request)
+
+    async def start(self):
+        config = uvicorn.Config(self.app, host="127.0.0.1", port=self.port)
+        server = uvicorn.Server(config)
+        await server.serve()
+```
+
+### Mock Git Service
+
+```bash
+# Start mock git service for testing git operations
+docker run -d \
+  --name mock-git-service \
+  -p 8003:80 \
+  -v $(pwd)/test_repos:/git/repos \
+  gitea/gitea:latest
+```
+
+### Service Orchestration
+
+```bash
+# Start all mock services
+docker-compose -f tests/planner/docker/test-services.yml up -d
+
+# Verify services are running
+curl http://localhost:8001/health  # Mock LLM
+curl http://localhost:8002/health  # Mock Task Tool
+curl http://localhost:8003/health  # Mock Git Service
+
+# Run tests with mock services
+pytest tests/planner/integration/ -v --use-mock-services
+
+# Cleanup
+docker-compose -f tests/planner/docker/test-services.yml down
+```
+
+## CI/CD Integration
+
+### GitHub Actions Workflow
+
+```yaml
+# .github/workflows/super-planner-tests.yml
+name: Super-Planner Tests
+
+on:
+  push:
+    paths:
+    - 'amplifier/planner/**'
+    - 'tests/planner/**'
+  pull_request:
+    paths:
+    - 'amplifier/planner/**'
+    - 'tests/planner/**'
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        pip install uv
+        uv sync --dev
+
+    - name: Run unit tests
+      run: |
+        pytest tests/planner/unit/ \
+          --junitxml=test-results-unit.xml \
+          --cov=amplifier.planner \
+          --cov-report=xml
+
+    - name: Upload coverage
+      uses: codecov/codecov-action@v3
+
+  integration-tests:
+    runs-on: ubuntu-latest
+    needs: unit-tests
+
+    services:
+      mock-services:
+        image: planner-mock-services:latest
+        ports:
+        - 8001:8001
+        - 8002:8002
+        - 8003:8003
+
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        pip install uv
+        uv sync --dev
+
+    - name: Wait for mock services
+      run: |
+        timeout 60 bash -c 'until curl -f http://localhost:8001/health; do sleep 2; done'
+
+    - name: Run integration tests
+      run: |
+        pytest tests/planner/integration/ \
+          --junitxml=test-results-integration.xml \
+          --use-mock-services
+
+  e2e-tests:
+    runs-on: ubuntu-latest
+    needs: integration-tests
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Setup real services
+      env:
+        OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      run: |
+        pip install uv
+        uv sync --dev
+        export USE_REAL_SERVICES=true
+
+    - name: Run E2E tests
+      run: |
+        pytest tests/planner/e2e/ \
+          --junitxml=test-results-e2e.xml \
+          --real-services \
+          --timeout=3600  # 1 hour timeout for E2E
+
+  performance-tests:
+    runs-on: ubuntu-latest-8-cores
+    needs: integration-tests
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        pip install uv
+        uv sync --dev
+        pip install pytest-benchmark
+
+    - name: Run performance benchmarks
+      run: |
+        pytest tests/planner/performance/ \
+          --benchmark-json=benchmark-results.json \
+          --benchmark-only
+
+    - name: Compare with baseline
+      run: |
+        python tests/planner/utils/compare_benchmarks.py \
+          --current benchmark-results.json \
+          --baseline tests/planner/performance/baseline.json \
+          --threshold 0.15
+
+    - name: Upload benchmark results
+      uses: actions/upload-artifact@v3
+      with:
+        name: performance-results
+        path: benchmark-results.json
+```
+
+### Pre-commit Hooks
+
+```yaml
+# .pre-commit-config.yaml (add to existing)
+repos:
+- repo: local
+  hooks:
+  - id: planner-unit-tests
+    name: Super-planner unit tests
+    entry: pytest tests/planner/unit/ -x --tb=short
+    language: system
+    files: ^(amplifier/planner/|tests/planner/).*\.py$
+    pass_filenames: false
+
+  - id: planner-integration-smoke
+    name: Super-planner integration smoke test
+    entry: pytest tests/planner/integration/test_basic_workflow.py -v
+    language: system
+    files: ^(amplifier/planner/|tests/planner/).*\.py$
+    pass_filenames: false
+```
+
+## Test Quality Assurance
+
+### Test Coverage Requirements
+
+```bash
+# Coverage targets
+Unit Tests: 85%+ line coverage, 80%+ branch coverage
+Integration Tests: 70%+ end-to-end path coverage
+Critical Components: 95%+ coverage (state management, coordination)
+
+# Generate coverage reports
+pytest tests/planner/ \
+  --cov=amplifier.planner \
+  --cov-report=html \
+  --cov-report=term \
+  --cov-fail-under=85
+```
+
+### Test Quality Metrics
+
+```python
+# tests/planner/quality/test_metrics.py
+def test_coverage_requirements():
+    """Ensure test coverage meets requirements"""
+    coverage = get_coverage_data()
+
+    assert coverage['unit_tests']['line'] >= 85
+    assert coverage['unit_tests']['branch'] >= 80
+    assert coverage['integration_tests']['path'] >= 70
+
+    critical_components = [
+        'amplifier.planner.protocols.state_transitions',
+        'amplifier.planner.protocols.agent_coordination',
+        'amplifier.planner.core.task_manager'
+    ]
+
+    for component in critical_components:
+        assert coverage['components'][component]['line'] >= 95
+
+def test_no_flaky_tests():
+    """Ensure tests are deterministic"""
+    # Run critical tests multiple times to detect flakiness
+    for _ in range(10):
+        result = subprocess.run([
+            'pytest', 'tests/planner/unit/test_state_transitions.py',
+            '-q', '--tb=no'
+        ], capture_output=True)
+
+        assert result.returncode == 0, "Tests should be deterministic"
+
+def test_performance_stability():
+    """Ensure performance tests are stable"""
+    baseline_times = load_performance_baseline()
+
+    # Run performance tests 5 times
+    results = []
+    for _ in range(5):
+        result = run_performance_benchmark('core_operations')
+        results.append(result)
+
+    # Check for consistency (coefficient of variation < 0.2)
+    mean_time = statistics.mean(results)
+    std_dev = statistics.stdev(results)
+    cv = std_dev / mean_time
+
+    assert cv < 0.2, f"Performance tests too variable: CV={cv:.3f}"
+```
+
+### Manual Testing Checklist
+
+```markdown
+## Pre-Release Manual Testing
+
+### Core Functionality
+- [ ] Create new project via CLI
+- [ ] Load existing project successfully
+- [ ] Break down complex tasks into subtasks
+- [ ] Assign tasks to agents appropriately
+- [ ] Handle task state transitions correctly
+- [ ] Resolve dependency conflicts
+- [ ] Commit changes to git properly
+
+### Error Scenarios
+- [ ] Handle corrupted project files
+- [ ] Recover from agent failures
+- [ ] Manage network connectivity issues
+- [ ] Deal with git merge conflicts
+- [ ] Handle disk space exhaustion
+- [ ] Manage circular dependencies
+
+### Performance
+- [ ] Load 1000+ task project in reasonable time
+- [ ] Support 10+ concurrent agents
+- [ ] Maintain responsiveness under load
+- [ ] Handle memory efficiently
+- [ ] Scale linearly with project size
+
+### Integration
+- [ ] Work with real LLM services
+- [ ] Integrate with amplifier Task tool
+- [ ] Compatible with amplifier git workflow
+- [ ] Use CCSDK defensive utilities properly
+```
+
+## Troubleshooting Test Issues
+
+### Common Test Failures
+
+```bash
+# Mock service connection issues
+Error: Connection refused to localhost:8001
+Solution: Ensure mock services are running
+docker-compose -f tests/planner/docker/test-services.yml up -d
+
+# Performance test timeout
+Error: Test timeout after 300s
+Solution: Increase timeout or run on more powerful hardware
+pytest tests/planner/performance/ --timeout=3600
+
+# Git operation failures
+Error: Git command failed with exit code 128
+Solution: Ensure git is configured properly in test environment
+git config --global user.email "test@example.com"
+git config --global user.name "Test User"
+
+# File permission issues
+Error: Permission denied writing to test directory
+Solution: Ensure test directories are writable
+chmod -R 755 tests/planner/test_data/
+```
+
+### Debug Mode Testing
+
+```bash
+# Run tests with debug logging
+PLANNER_LOG_LEVEL=DEBUG pytest tests/planner/integration/ -v -s
+
+# Keep test artifacts for inspection
+pytest tests/planner/ --keep-test-data --pdb-trace
+
+# Run single test with maximum verbosity
+pytest tests/planner/integration/test_multi_agent_coordination.py::test_concurrent_task_claiming -vvv -s --tb=long
+```
+
+This integration setup ensures comprehensive testing of the super-planner system across all deployment scenarios, from development through production, maintaining the high quality standards expected for enterprise software.
\ No newline at end of file
diff --git a/tests/planner/mocks/mock_amplifier_task.py b/tests/planner/mocks/mock_amplifier_task.py
new file mode 100644
index 00000000..f199a2ce
--- /dev/null
+++ b/tests/planner/mocks/mock_amplifier_task.py
@@ -0,0 +1,423 @@
+"""
+Mock implementation of amplifier's Task tool for testing super-planner integration.
+
+This mock simulates the behavior of spawning sub-agents via amplifier's Task tool,
+allowing tests to run without requiring the full amplifier environment.
+"""
+
+import asyncio
+import json
+import uuid
+from dataclasses import asdict
+from dataclasses import dataclass
+from datetime import UTC
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class MockTaskResult:
+    """Mock result from a Task tool execution"""
+
+    task_id: str
+    agent_name: str
+    status: str  # "started", "completed", "failed"
+    output: dict[str, Any]
+    execution_time: float
+    created_at: str
+
+
+@dataclass
+class MockAgent:
+    """Mock agent instance spawned by Task tool"""
+
+    agent_id: str
+    name: str
+    capabilities: list[str]
+    status: str  # "starting", "active", "idle", "failed", "stopped"
+    current_task: str | None
+    tasks_completed: int
+    start_time: str
+    last_heartbeat: str
+
+
+class MockAmplifierTaskTool:
+    """
+    Mock implementation of amplifier's Task tool.
+
+    Simulates spawning and managing sub-agents for task execution.
+    This mock allows testing the super-planner's agent coordination
+    without requiring the full amplifier environment.
+    """
+
+    def __init__(self, temp_dir: Path):
+        self.temp_dir = temp_dir
+        self.agents: dict[str, MockAgent] = {}
+        self.task_results: dict[str, MockTaskResult] = {}
+        self.execution_delay = 0.1  # Simulate brief execution time
+        self.failure_rate = 0.0  # Configurable failure rate for testing
+
+        # Mock agent capabilities available for assignment
+        self.available_agent_types = {
+            "python-dev": ["python", "fastapi", "sqlalchemy", "pytest"],
+            "typescript-dev": ["typescript", "react", "nodejs", "jest"],
+            "devops": ["docker", "kubernetes", "terraform", "ci-cd"],
+            "qa": ["testing", "automation", "selenium", "performance"],
+            "data": ["python", "pandas", "sql", "analytics"],
+            "security": ["security", "oauth", "encryption", "compliance"],
+            "mobile": ["react-native", "ios", "android", "mobile-ui"],
+            "designer": ["ui-ux", "figma", "design-systems", "accessibility"],
+        }
+
+    async def spawn_agent(self, agent_type: str, task_description: str, capabilities_required: list[str]) -> str:
+        """
+        Mock spawning of a sub-agent via amplifier Task tool.
+
+        Args:
+            agent_type: Type of agent to spawn
+            task_description: Description of work to be done
+            capabilities_required: Required capabilities for the task
+
+        Returns:
+            agent_id: Unique identifier for the spawned agent
+        """
+        agent_id = str(uuid.uuid4())
+
+        # Simulate agent startup time
+        await asyncio.sleep(self.execution_delay)
+
+        # Check if this agent type exists
+        if agent_type not in self.available_agent_types:
+            raise ValueError(f"Unknown agent type: {agent_type}")
+
+        # Create mock agent instance
+        agent = MockAgent(
+            agent_id=agent_id,
+            name=f"{agent_type}-{agent_id[:8]}",
+            capabilities=self.available_agent_types[agent_type],
+            status="starting",
+            current_task=None,
+            tasks_completed=0,
+            start_time=datetime.now(UTC).isoformat(),
+            last_heartbeat=datetime.now(UTC).isoformat(),
+        )
+
+        # Simulate occasional startup failures
+        if self._should_fail():
+            agent.status = "failed"
+            self.agents[agent_id] = agent
+            raise RuntimeError(f"Failed to start agent {agent_type}: simulated failure")
+
+        agent.status = "active"
+        self.agents[agent_id] = agent
+
+        # Log agent creation for test verification
+        self._log_agent_event(
+            agent_id,
+            "spawned",
+            {
+                "agent_type": agent_type,
+                "task_description": task_description,
+                "capabilities_required": capabilities_required,
+            },
+        )
+
+        return agent_id
+
+    async def assign_task_to_agent(self, agent_id: str, task_id: str, task_data: dict[str, Any]) -> bool:
+        """
+        Mock task assignment to a spawned agent.
+
+        Args:
+            agent_id: ID of agent to assign task to
+            task_id: ID of task being assigned
+            task_data: Task data and requirements
+
+        Returns:
+            bool: True if assignment successful
+        """
+        if agent_id not in self.agents:
+            raise ValueError(f"Agent {agent_id} not found")
+
+        agent = self.agents[agent_id]
+
+        # Check if agent is available
+        if agent.status not in ["active", "idle"]:
+            return False
+
+        if agent.current_task is not None:
+            return False  # Agent already busy
+
+        # Assign task
+        agent.current_task = task_id
+        agent.status = "active"
+        agent.last_heartbeat = datetime.now(UTC).isoformat()
+
+        # Log task assignment
+        self._log_agent_event(
+            agent_id, "task_assigned", {"task_id": task_id, "task_name": task_data.get("name", "Unknown")}
+        )
+
+        # Start background task execution simulation
+        asyncio.create_task(self._simulate_task_execution(agent_id, task_id, task_data))
+
+        return True
+
+    async def get_agent_status(self, agent_id: str) -> dict[str, Any] | None:
+        """Get current status of an agent."""
+        if agent_id not in self.agents:
+            return None
+
+        agent = self.agents[agent_id]
+        return {
+            "agent_id": agent_id,
+            "name": agent.name,
+            "status": agent.status,
+            "current_task": agent.current_task,
+            "tasks_completed": agent.tasks_completed,
+            "last_heartbeat": agent.last_heartbeat,
+        }
+
+    async def get_task_result(self, task_id: str) -> MockTaskResult | None:
+        """Get result of a completed task."""
+        return self.task_results.get(task_id)
+
+    async def stop_agent(self, agent_id: str) -> bool:
+        """Stop a running agent."""
+        if agent_id not in self.agents:
+            return False
+
+        agent = self.agents[agent_id]
+        agent.status = "stopped"
+        agent.current_task = None
+
+        self._log_agent_event(agent_id, "stopped", {})
+        return True
+
+    async def list_agents(self) -> list[dict[str, Any]]:
+        """List all agents and their current status."""
+        return [asdict(agent) for agent in self.agents.values()]
+
+    def configure_failure_rate(self, failure_rate: float):
+        """Configure simulated failure rate for testing (0.0 to 1.0)."""
+        self.failure_rate = max(0.0, min(1.0, failure_rate))
+
+    def configure_execution_delay(self, delay: float):
+        """Configure simulated execution delay in seconds."""
+        self.execution_delay = max(0.0, delay)
+
+    async def _simulate_task_execution(self, agent_id: str, task_id: str, task_data: dict[str, Any]):
+        """Simulate agent executing a task in the background."""
+        agent = self.agents[agent_id]
+        start_time = datetime.now(UTC)
+
+        try:
+            # Simulate work time based on task complexity
+            work_time = self._estimate_work_time(task_data)
+            await asyncio.sleep(work_time)
+
+            # Simulate occasional task failures
+            if self._should_fail():
+                raise RuntimeError("Simulated task execution failure")
+
+            # Task completed successfully
+            execution_time = (datetime.now(UTC) - start_time).total_seconds()
+
+            result = MockTaskResult(
+                task_id=task_id,
+                agent_name=agent.name,
+                status="completed",
+                output={
+                    "success": True,
+                    "files_modified": self._generate_mock_file_changes(task_data),
+                    "tests_passed": True,
+                    "commits_created": 1,
+                },
+                execution_time=execution_time,
+                created_at=datetime.now(UTC).isoformat(),
+            )
+
+            # Update agent status
+            agent.current_task = None
+            agent.status = "idle"
+            agent.tasks_completed += 1
+            agent.last_heartbeat = datetime.now(UTC).isoformat()
+
+            # Store result
+            self.task_results[task_id] = result
+
+            self._log_agent_event(agent_id, "task_completed", {"task_id": task_id, "execution_time": execution_time})
+
+        except Exception as e:
+            # Task failed
+            execution_time = (datetime.now(UTC) - start_time).total_seconds()
+
+            result = MockTaskResult(
+                task_id=task_id,
+                agent_name=agent.name,
+                status="failed",
+                output={"success": False, "error": str(e), "partial_work": True},
+                execution_time=execution_time,
+                created_at=datetime.now(UTC).isoformat(),
+            )
+
+            # Update agent status
+            agent.current_task = None
+            agent.status = "idle"  # Agent can retry other tasks
+            agent.last_heartbeat = datetime.now(UTC).isoformat()
+
+            # Store result
+            self.task_results[task_id] = result
+
+            self._log_agent_event(
+                agent_id, "task_failed", {"task_id": task_id, "error": str(e), "execution_time": execution_time}
+            )
+
+    def _estimate_work_time(self, task_data: dict[str, Any]) -> float:
+        """Estimate work time based on task complexity."""
+        base_time = 0.5  # Base execution time
+
+        # Factor in estimated effort
+        effort = task_data.get("estimated_effort", 5)
+        effort_factor = min(effort / 10.0, 2.0)  # Cap at 2x base time
+
+        # Add some randomness
+        import random
+
+        random_factor = random.uniform(0.8, 1.2)
+
+        return base_time * effort_factor * random_factor
+
+    def _generate_mock_file_changes(self, task_data: dict[str, Any]) -> list[str]:
+        """Generate mock file changes for task completion."""
+        task_name = task_data.get("name", "task")
+        component = task_data.get("metadata", {}).get("component", "main")
+
+        # Generate realistic file paths based on task type
+        files = [
+            f"src/{component}/{task_name.lower().replace(' ', '_')}.py",
+            f"tests/test_{component}_{task_name.lower().replace(' ', '_')}.py",
+        ]
+
+        return files
+
+    def _should_fail(self) -> bool:
+        """Determine if this operation should fail based on configured failure rate."""
+        import random
+
+        return random.random() < self.failure_rate
+
+    def _log_agent_event(self, agent_id: str, event_type: str, data: dict[str, Any]):
+        """Log agent events for test verification."""
+        log_file = self.temp_dir / "mock_agent_events.jsonl"
+
+        event = {
+            "timestamp": datetime.now(UTC).isoformat(),
+            "agent_id": agent_id,
+            "event_type": event_type,
+            "data": data,
+        }
+
+        with open(log_file, "a") as f:
+            f.write(json.dumps(event) + "\n")
+
+
+# Test fixtures and helpers
+def create_mock_task_tool(temp_dir: Path, **config) -> MockAmplifierTaskTool:
+    """Create configured mock Task tool for testing."""
+    mock = MockAmplifierTaskTool(temp_dir)
+
+    # Apply configuration
+    if "failure_rate" in config:
+        mock.configure_failure_rate(config["failure_rate"])
+
+    if "execution_delay" in config:
+        mock.configure_execution_delay(config["execution_delay"])
+
+    return mock
+
+
+async def simulate_realistic_agent_work(
+    mock_tool: MockAmplifierTaskTool, tasks: list[dict[str, Any]]
+) -> list[MockTaskResult]:
+    """
+    Simulate realistic multi-agent work on a set of tasks.
+
+    This helper spawns appropriate agents and assigns tasks based on
+    capabilities, simulating a realistic super-planner workflow.
+    """
+    results = []
+
+    # Group tasks by required capabilities
+    capability_groups = {}
+    for task in tasks:
+        caps = tuple(sorted(task.get("capabilities_required", [])))
+        if caps not in capability_groups:
+            capability_groups[caps] = []
+        capability_groups[caps].append(task)
+
+    # Spawn agents for each capability group
+    agents = []
+    for capabilities in capability_groups:
+        # Find appropriate agent type
+        agent_type = find_best_agent_type(list(capabilities), mock_tool.available_agent_types)
+        if agent_type:
+            agent_id = await mock_tool.spawn_agent(
+                agent_type=agent_type,
+                task_description=f"Handle tasks requiring {capabilities}",
+                capabilities_required=list(capabilities),
+            )
+            agents.append((agent_id, capabilities))
+
+    # Assign and execute tasks
+    for (agent_id, _capabilities), task_list in zip(agents, capability_groups.values(), strict=False):
+        for task in task_list:
+            await mock_tool.assign_task_to_agent(agent_id, task["id"], task)
+
+    # Wait for all tasks to complete
+    await wait_for_all_tasks_complete(mock_tool, [t["id"] for t in tasks])
+
+    # Collect results
+    for task in tasks:
+        result = await mock_tool.get_task_result(task["id"])
+        if result:
+            results.append(result)
+
+    return results
+
+
+def find_best_agent_type(required_caps: list[str], available_types: dict[str, list[str]]) -> str | None:
+    """Find the agent type that best matches required capabilities."""
+    best_match = None
+    best_score = 0
+
+    for agent_type, agent_caps in available_types.items():
+        # Count how many required capabilities this agent has
+        matches = len(set(required_caps) & set(agent_caps))
+        if matches > best_score:
+            best_score = matches
+            best_match = agent_type
+
+    return best_match
+
+
+async def wait_for_all_tasks_complete(mock_tool: MockAmplifierTaskTool, task_ids: list[str], timeout: float = 30.0):
+    """Wait for all tasks to complete or timeout."""
+    start_time = datetime.now()
+
+    while (datetime.now() - start_time).total_seconds() < timeout:
+        all_complete = True
+
+        for task_id in task_ids:
+            result = await mock_tool.get_task_result(task_id)
+            if result is None:
+                all_complete = False
+                break
+
+        if all_complete:
+            return
+
+        await asyncio.sleep(0.1)
+
+    raise TimeoutError(f"Tasks did not complete within {timeout} seconds")
diff --git a/tests/planner/performance_benchmarks.md b/tests/planner/performance_benchmarks.md
new file mode 100644
index 00000000..dd8a3d4f
--- /dev/null
+++ b/tests/planner/performance_benchmarks.md
@@ -0,0 +1,465 @@
+# Super-Planner Performance Benchmarks
+
+Performance requirements and benchmarks for the super-planner system, ensuring it scales appropriately for real-world usage.
+
+## Performance Requirements
+
+### Core Performance Targets
+
+| Operation | Target Time | Scalability | Memory Limit |
+|-----------|-------------|-------------|--------------|
+| Project Load (1000 tasks) | < 30s | Linear O(n) | < 1GB |
+| Task Assignment Batch | < 5s | Constant O(1) | < 100MB |
+| State Transition | < 100ms | Constant O(1) | < 10MB |
+| Dependency Analysis | < 10s | O(n log n) | < 500MB |
+| Git Operations | < 5s | Linear O(changes) | < 50MB |
+| Agent Spawning | < 30s | Linear O(agents) | < 200MB |
+
+### Concurrent Performance
+
+| Scenario | Target | Limit |
+|----------|--------|-------|
+| Concurrent Agents | 20 agents | No deadlocks |
+| Concurrent File Ops | 100 ops/sec | < 1% failures |
+| State Modifications | 50/sec | Zero corruption |
+| Git Commits | 10/min | No conflicts |
+
+### Throughput Requirements
+
+- **Planning Mode**: Break down 500 tasks in < 5 minutes
+- **Working Mode**: Process 1000 state changes in < 2 minutes
+- **Multi-Agent**: Coordinate 10 agents on 200 tasks in < 30 minutes
+- **File I/O**: Handle 1000 file operations in < 1 minute
+
+## Benchmark Test Scenarios
+
+### BENCH-001: Large Project Loading
+
+**Scenario**: Load projects of increasing size to measure scalability
+
+**Test Configuration**:
+```python
+project_sizes = [10, 50, 100, 500, 1000, 2000]
+max_depth = 5
+dependency_density = 0.3  # 30% of tasks have dependencies
+```
+
+**Measurement Points**:
+- Initial project file parsing time
+- Task dependency graph construction
+- Memory usage at peak
+- Time to first agent assignment
+
+**Success Criteria**:
+- Linear scaling with task count
+- Memory usage < 1MB per task
+- No performance degradation for repeated loads
+- Consistent performance regardless of dependency complexity
+
+**Benchmark Implementation**:
+```python
+@pytest.mark.performance
+@pytest.mark.parametrize("task_count", [10, 50, 100, 500, 1000, 2000])
+async def test_project_loading_performance(task_count, performance_tracker):
+    """Benchmark project loading performance across different sizes"""
+
+    # Generate test project
+    project = generate_complex_project(
+        task_count=task_count,
+        max_depth=5,
+        dependency_density=0.3
+    )
+
+    # Measure loading performance
+    performance_tracker.start_timer("project_load")
+
+    planner = SuperPlanner()
+    await planner.load_project(project)
+
+    performance_tracker.end_timer("project_load")
+
+    # Assert performance requirements
+    max_time = task_count * 0.03  # 30ms per task max
+    performance_tracker.assert_performance("project_load", max_time)
+
+    # Memory usage check
+    memory_usage = get_memory_usage()
+    max_memory = task_count * 1024 * 1024  # 1MB per task
+    assert memory_usage < max_memory
+```
+
+### BENCH-002: Concurrent Agent Coordination
+
+**Scenario**: Test coordination performance with increasing agent counts
+
+**Test Configuration**:
+```python
+agent_counts = [2, 5, 10, 15, 20]
+tasks_per_agent = 10
+coordination_complexity = "high"  # Complex task dependencies
+```
+
+**Measurement Points**:
+- Agent registration time
+- Task assignment latency
+- Conflict resolution time
+- Overall coordination overhead
+
+**Success Criteria**:
+- Support 20 concurrent agents without deadlock
+- Agent assignment time < 2s regardless of agent count
+- No performance degradation under load
+- Fair task distribution maintained
+
+**Benchmark Implementation**:
+```python
+@pytest.mark.performance
+@pytest.mark.parametrize("agent_count", [2, 5, 10, 15, 20])
+async def test_concurrent_agent_coordination(agent_count, performance_tracker):
+    """Benchmark multi-agent coordination performance"""
+
+    # Setup project with tasks for all agents
+    project = generate_multi_agent_project(
+        agent_count=agent_count,
+        tasks_per_agent=10
+    )
+
+    # Create agents
+    agents = create_test_agents(agent_count)
+
+    # Measure coordination performance
+    performance_tracker.start_timer("agent_coordination")
+
+    coordinator = AgentCoordinator()
+    await coordinator.register_agents(agents)
+    assignments = await coordinator.assign_all_tasks(project.tasks)
+
+    performance_tracker.end_timer("agent_coordination")
+
+    # Assert performance requirements
+    performance_tracker.assert_performance("agent_coordination", 30.0)
+
+    # Verify load balancing
+    assert_load_balanced(assignments, tolerance=0.15)
+```
+
+### BENCH-003: High-Frequency State Transitions
+
+**Scenario**: Stress test state transition performance
+
+**Test Configuration**:
+```python
+transition_rates = [10, 50, 100, 200, 500]  # transitions per second
+duration = 60  # seconds
+concurrent_agents = 8
+```
+
+**Measurement Points**:
+- Individual state transition time
+- Throughput under load
+- Error rate during high-frequency updates
+- File system contention effects
+
+**Success Criteria**:
+- Handle 200 transitions/sec with < 1% errors
+- Individual transitions < 100ms
+- No data corruption under any load
+- Graceful degradation when limits exceeded
+
+### BENCH-004: Git Operations Under Load
+
+**Scenario**: Test git integration performance with frequent commits
+
+**Test Configuration**:
+```python
+commit_frequencies = [1, 5, 10, 20]  # commits per minute
+concurrent_operations = [1, 4, 8, 12]  # simultaneous git ops
+project_sizes = [100, 500, 1000]  # tasks generating commits
+```
+
+**Measurement Points**:
+- Individual commit latency
+- Git conflict resolution time
+- Repository growth rate
+- Branch switching performance
+
+**Success Criteria**:
+- Commits complete < 5s each
+- No git corruption under concurrent access
+- Conflict resolution < 10s
+- Repository size grows linearly with changes
+
+### BENCH-005: Memory Usage and Garbage Collection
+
+**Scenario**: Long-running memory usage and leak detection
+
+**Test Configuration**:
+```python
+duration = 30  # minutes
+operation_frequency = 5  # operations per second
+project_size = 1000  # tasks
+agent_count = 10
+```
+
+**Measurement Points**:
+- Baseline memory usage
+- Peak memory during operations
+- Memory growth over time
+- Garbage collection frequency
+
+**Success Criteria**:
+- No memory leaks (stable after GC)
+- Peak memory < 2x baseline
+- GC pauses < 100ms
+- Stable performance over long runs
+
+## Performance Test Implementation
+
+### Test Infrastructure
+
+```python
+class PerformanceBenchmark:
+    """Base class for performance benchmark tests"""
+
+    def __init__(self):
+        self.metrics = PerformanceMetrics()
+        self.resource_monitor = ResourceMonitor()
+        self.test_config = BenchmarkConfig()
+
+    async def setup_benchmark(self, scenario: str):
+        """Setup benchmark environment"""
+        self.resource_monitor.start()
+        self.metrics.reset()
+
+        # Configure test environment for performance
+        os.environ["PLANNER_PERFORMANCE_MODE"] = "true"
+        os.environ["PLANNER_LOG_LEVEL"] = "WARNING"  # Reduce logging overhead
+
+    async def teardown_benchmark(self):
+        """Cleanup and collect final metrics"""
+        self.resource_monitor.stop()
+
+        # Generate performance report
+        report = self.metrics.generate_report()
+        self.save_benchmark_results(report)
+
+    def assert_performance_requirements(self, operation: str, max_time: float):
+        """Assert operation meets performance requirements"""
+        actual_time = self.metrics.get_average_time(operation)
+        assert actual_time <= max_time, (
+            f"Performance requirement failed: {operation} "
+            f"took {actual_time:.2f}s, max allowed {max_time}s"
+        )
+
+    def assert_memory_requirements(self, max_memory_mb: int):
+        """Assert memory usage within limits"""
+        peak_memory = self.resource_monitor.get_peak_memory()
+        assert peak_memory <= max_memory_mb * 1024 * 1024, (
+            f"Memory requirement failed: used {peak_memory / 1024 / 1024:.1f}MB, "
+            f"max allowed {max_memory_mb}MB"
+        )
+```
+
+### Benchmark Data Generation
+
+```python
+class BenchmarkDataGenerator:
+    """Generate realistic test data for performance benchmarks"""
+
+    @staticmethod
+    def generate_large_project(task_count: int, complexity: str) -> TestProject:
+        """Generate project data for performance testing"""
+
+        if complexity == "simple":
+            # Linear dependency chain, minimal metadata
+            return generate_linear_project(task_count)
+
+        elif complexity == "complex":
+            # Realistic microservices with cross-dependencies
+            return generate_microservices_project(
+                service_count=task_count // 50,
+                avg_tasks_per_service=50,
+                cross_dependencies=0.2
+            )
+
+        elif complexity == "extreme":
+            # Maximum complexity scenario
+            return generate_extreme_project(
+                task_count=task_count,
+                max_depth=8,
+                dependency_density=0.4,
+                metadata_richness="high"
+            )
+
+    @staticmethod
+    def generate_high_frequency_operations(rate: int, duration: int) -> list[Operation]:
+        """Generate operations for high-frequency testing"""
+        operations = []
+
+        operation_types = [
+            "state_transition",
+            "task_assignment",
+            "agent_status_update",
+            "dependency_modification"
+        ]
+
+        for i in range(rate * duration):
+            op = Operation(
+                type=random.choice(operation_types),
+                timestamp=i / rate,
+                data=generate_operation_data()
+            )
+            operations.append(op)
+
+        return operations
+```
+
+### Performance Monitoring
+
+```python
+class ResourceMonitor:
+    """Monitor system resources during benchmarks"""
+
+    def __init__(self):
+        self.start_time = None
+        self.memory_samples = []
+        self.cpu_samples = []
+        self.io_samples = []
+
+    def start(self):
+        """Start resource monitoring"""
+        self.start_time = time.time()
+        self.monitoring_task = asyncio.create_task(self._monitor_loop())
+
+    async def _monitor_loop(self):
+        """Continuous monitoring loop"""
+        while True:
+            # Sample memory usage
+            memory_info = psutil.Process().memory_info()
+            self.memory_samples.append({
+                'timestamp': time.time() - self.start_time,
+                'rss': memory_info.rss,
+                'vms': memory_info.vms
+            })
+
+            # Sample CPU usage
+            cpu_percent = psutil.Process().cpu_percent()
+            self.cpu_samples.append({
+                'timestamp': time.time() - self.start_time,
+                'cpu_percent': cpu_percent
+            })
+
+            await asyncio.sleep(0.1)  # Sample every 100ms
+
+    def get_peak_memory(self) -> int:
+        """Get peak RSS memory usage in bytes"""
+        if not self.memory_samples:
+            return 0
+        return max(sample['rss'] for sample in self.memory_samples)
+
+    def get_average_cpu(self) -> float:
+        """Get average CPU usage percentage"""
+        if not self.cpu_samples:
+            return 0.0
+        return sum(sample['cpu_percent'] for sample in self.cpu_samples) / len(self.cpu_samples)
+```
+
+## Continuous Performance Testing
+
+### CI Integration
+
+```yaml
+# .github/workflows/performance.yml
+name: Performance Tests
+
+on:
+  pull_request:
+    paths:
+    - 'amplifier/planner/**'
+  schedule:
+    - cron: '0 2 * * *'  # Daily at 2 AM
+
+jobs:
+  performance:
+    runs-on: ubuntu-latest-8-cores  # Consistent hardware
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Setup Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        pip install -e .[dev]
+        pip install pytest-benchmark
+
+    - name: Run performance benchmarks
+      run: |
+        pytest tests/planner/performance/ \
+          --benchmark-json=benchmark_results.json \
+          --benchmark-only
+
+    - name: Compare with baseline
+      run: |
+        python tools/compare_benchmarks.py \
+          --current benchmark_results.json \
+          --baseline performance_baseline.json \
+          --threshold 0.1  # 10% regression threshold
+
+    - name: Upload results
+      uses: actions/upload-artifact@v3
+      with:
+        name: performance-results
+        path: benchmark_results.json
+```
+
+### Performance Regression Detection
+
+```python
+def detect_performance_regressions(current_results: dict, baseline_results: dict,
+                                 threshold: float = 0.1) -> list[str]:
+    """Detect performance regressions compared to baseline"""
+    regressions = []
+
+    for benchmark_name, current_metrics in current_results.items():
+        if benchmark_name not in baseline_results:
+            continue
+
+        baseline_metrics = baseline_results[benchmark_name]
+
+        # Check if performance regressed beyond threshold
+        current_time = current_metrics['mean']
+        baseline_time = baseline_metrics['mean']
+
+        regression_ratio = (current_time - baseline_time) / baseline_time
+
+        if regression_ratio > threshold:
+            regressions.append(
+                f"{benchmark_name}: {regression_ratio:.1%} slower "
+                f"({current_time:.3f}s vs {baseline_time:.3f}s baseline)"
+            )
+
+    return regressions
+```
+
+## Performance Optimization Targets
+
+### Phase 1: Foundation Performance
+- ✅ Basic operations meet target times
+- ✅ Memory usage within reasonable bounds
+- ✅ No obvious performance bottlenecks
+
+### Phase 2: Scale Performance
+- ✅ Linear scaling to 1000+ tasks
+- ✅ Support for 10+ concurrent agents
+- ✅ Stable performance under sustained load
+
+### Phase 3: Production Performance
+- ✅ Enterprise-scale projects (5000+ tasks)
+- ✅ High-availability coordination (20+ agents)
+- ✅ Sub-second response times for interactive operations
+
+These performance benchmarks ensure the super-planner system will perform well in real-world scenarios while maintaining reliability and user experience quality.
\ No newline at end of file
diff --git a/tests/planner/test_data/projects/complex_microservices_platform.json b/tests/planner/test_data/projects/complex_microservices_platform.json
new file mode 100644
index 00000000..19ebdad1
--- /dev/null
+++ b/tests/planner/test_data/projects/complex_microservices_platform.json
@@ -0,0 +1,357 @@
+{
+  "project": {
+    "id": "complex_microservices_platform",
+    "name": "Enterprise Microservices Platform",
+    "description": "Large-scale microservices platform with 8 services, complex dependencies, and multi-team coordination",
+    "created": "2025-01-01T00:00:00Z",
+    "status": "NOT_STARTED",
+    "capabilities_required": ["python", "typescript", "devops", "qa", "database", "security"],
+    "estimated_complexity": "high",
+    "max_parallel_agents": 8
+  },
+  "tasks": [
+    {
+      "id": "platform_001",
+      "name": "User Authentication Service",
+      "description": "Centralized authentication and authorization service",
+      "parent_id": null,
+      "status": "NOT_STARTED",
+      "priority": "critical",
+      "estimated_effort": 40,
+      "capabilities_required": ["python", "security", "database"],
+      "dependencies": [],
+      "metadata": {
+        "service": "auth",
+        "type": "epic",
+        "team": "platform"
+      }
+    },
+    {
+      "id": "platform_002",
+      "name": "API Gateway Service",
+      "description": "Service mesh gateway with routing and middleware",
+      "parent_id": null,
+      "status": "NOT_STARTED",
+      "priority": "critical",
+      "estimated_effort": 35,
+      "capabilities_required": ["python", "networking", "security"],
+      "dependencies": ["platform_001"],
+      "metadata": {
+        "service": "gateway",
+        "type": "epic",
+        "team": "platform"
+      }
+    },
+    {
+      "id": "platform_003",
+      "name": "User Management Service",
+      "description": "User profiles, preferences, and account management",
+      "parent_id": null,
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 30,
+      "capabilities_required": ["python", "database"],
+      "dependencies": ["platform_001"],
+      "metadata": {
+        "service": "users",
+        "type": "epic",
+        "team": "backend"
+      }
+    },
+    {
+      "id": "platform_004",
+      "name": "Payment Processing Service",
+      "description": "Secure payment processing and billing",
+      "parent_id": null,
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 45,
+      "capabilities_required": ["python", "security", "fintech"],
+      "dependencies": ["platform_001", "platform_003"],
+      "metadata": {
+        "service": "payments",
+        "type": "epic",
+        "team": "fintech"
+      }
+    },
+    {
+      "id": "platform_005",
+      "name": "Notification Service",
+      "description": "Multi-channel notification delivery system",
+      "parent_id": null,
+      "status": "NOT_STARTED",
+      "priority": "medium",
+      "estimated_effort": 25,
+      "capabilities_required": ["python", "messaging"],
+      "dependencies": ["platform_003"],
+      "metadata": {
+        "service": "notifications",
+        "type": "epic",
+        "team": "backend"
+      }
+    },
+    {
+      "id": "platform_006",
+      "name": "Analytics Service",
+      "description": "Data collection, processing, and reporting",
+      "parent_id": null,
+      "status": "NOT_STARTED",
+      "priority": "medium",
+      "estimated_effort": 50,
+      "capabilities_required": ["python", "analytics", "database"],
+      "dependencies": ["platform_003"],
+      "metadata": {
+        "service": "analytics",
+        "type": "epic",
+        "team": "data"
+      }
+    },
+    {
+      "id": "platform_007",
+      "name": "Frontend Web Application",
+      "description": "React-based web interface for all services",
+      "parent_id": null,
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 60,
+      "capabilities_required": ["typescript", "react", "design"],
+      "dependencies": ["platform_002"],
+      "metadata": {
+        "service": "frontend",
+        "type": "epic",
+        "team": "frontend"
+      }
+    },
+    {
+      "id": "platform_008",
+      "name": "Mobile Application",
+      "description": "React Native mobile app for iOS and Android",
+      "parent_id": null,
+      "status": "NOT_STARTED",
+      "priority": "medium",
+      "estimated_effort": 80,
+      "capabilities_required": ["typescript", "react-native", "mobile"],
+      "dependencies": ["platform_002"],
+      "metadata": {
+        "service": "mobile",
+        "type": "epic",
+        "team": "mobile"
+      }
+    },
+    {
+      "id": "auth_001",
+      "name": "JWT Authentication Implementation",
+      "description": "Implement JWT-based authentication with refresh tokens",
+      "parent_id": "platform_001",
+      "status": "NOT_STARTED",
+      "priority": "critical",
+      "estimated_effort": 8,
+      "capabilities_required": ["python", "security"],
+      "dependencies": [],
+      "metadata": {
+        "service": "auth",
+        "type": "feature"
+      }
+    },
+    {
+      "id": "auth_002",
+      "name": "OAuth2 Provider Setup",
+      "description": "Configure OAuth2 flows for third-party integrations",
+      "parent_id": "platform_001",
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 12,
+      "capabilities_required": ["python", "security", "oauth"],
+      "dependencies": ["auth_001"],
+      "metadata": {
+        "service": "auth",
+        "type": "feature"
+      }
+    },
+    {
+      "id": "auth_003",
+      "name": "Multi-Factor Authentication",
+      "description": "Implement TOTP and SMS-based 2FA",
+      "parent_id": "platform_001",
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 10,
+      "capabilities_required": ["python", "security", "messaging"],
+      "dependencies": ["auth_001"],
+      "metadata": {
+        "service": "auth",
+        "type": "feature"
+      }
+    },
+    {
+      "id": "auth_004",
+      "name": "Rate Limiting and Security",
+      "description": "Implement brute force protection and rate limiting",
+      "parent_id": "platform_001",
+      "status": "NOT_STARTED",
+      "priority": "critical",
+      "estimated_effort": 6,
+      "capabilities_required": ["python", "security"],
+      "dependencies": ["auth_001"],
+      "metadata": {
+        "service": "auth",
+        "type": "security"
+      }
+    },
+    {
+      "id": "gateway_001",
+      "name": "Request Routing Implementation",
+      "description": "Dynamic service discovery and request routing",
+      "parent_id": "platform_002",
+      "status": "NOT_STARTED",
+      "priority": "critical",
+      "estimated_effort": 10,
+      "capabilities_required": ["python", "networking"],
+      "dependencies": [],
+      "metadata": {
+        "service": "gateway",
+        "type": "feature"
+      }
+    },
+    {
+      "id": "gateway_002",
+      "name": "Authentication Middleware",
+      "description": "JWT validation and user context injection",
+      "parent_id": "platform_002",
+      "status": "NOT_STARTED",
+      "priority": "critical",
+      "estimated_effort": 8,
+      "capabilities_required": ["python", "security"],
+      "dependencies": ["auth_001", "gateway_001"],
+      "metadata": {
+        "service": "gateway",
+        "type": "feature"
+      }
+    },
+    {
+      "id": "gateway_003",
+      "name": "Rate Limiting Middleware",
+      "description": "Per-user and global rate limiting",
+      "parent_id": "platform_002",
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 6,
+      "capabilities_required": ["python", "caching"],
+      "dependencies": ["gateway_001"],
+      "metadata": {
+        "service": "gateway",
+        "type": "feature"
+      }
+    },
+    {
+      "id": "users_001",
+      "name": "User Profile Management",
+      "description": "CRUD operations for user profiles and preferences",
+      "parent_id": "platform_003",
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 12,
+      "capabilities_required": ["python", "database"],
+      "dependencies": [],
+      "metadata": {
+        "service": "users",
+        "type": "feature"
+      }
+    },
+    {
+      "id": "users_002",
+      "name": "Account Settings API",
+      "description": "Privacy settings, notification preferences, account deletion",
+      "parent_id": "platform_003",
+      "status": "NOT_STARTED",
+      "priority": "medium",
+      "estimated_effort": 8,
+      "capabilities_required": ["python", "database"],
+      "dependencies": ["users_001"],
+      "metadata": {
+        "service": "users",
+        "type": "feature"
+      }
+    },
+    {
+      "id": "payments_001",
+      "name": "Payment Gateway Integration",
+      "description": "Stripe and PayPal integration for payment processing",
+      "parent_id": "platform_004",
+      "status": "NOT_STARTED",
+      "priority": "critical",
+      "estimated_effort": 15,
+      "capabilities_required": ["python", "fintech", "security"],
+      "dependencies": [],
+      "metadata": {
+        "service": "payments",
+        "type": "feature"
+      }
+    },
+    {
+      "id": "payments_002",
+      "name": "Subscription Management",
+      "description": "Recurring billing and subscription lifecycle management",
+      "parent_id": "platform_004",
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 18,
+      "capabilities_required": ["python", "fintech", "database"],
+      "dependencies": ["payments_001"],
+      "metadata": {
+        "service": "payments",
+        "type": "feature"
+      }
+    },
+    {
+      "id": "notifications_001",
+      "name": "Email Notification System",
+      "description": "Template-based email notifications with tracking",
+      "parent_id": "platform_005",
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 10,
+      "capabilities_required": ["python", "messaging"],
+      "dependencies": [],
+      "metadata": {
+        "service": "notifications",
+        "type": "feature"
+      }
+    },
+    {
+      "id": "notifications_002",
+      "name": "Push Notification System",
+      "description": "Firebase/APNs push notifications for mobile apps",
+      "parent_id": "platform_005",
+      "status": "NOT_STARTED",
+      "priority": "medium",
+      "estimated_effort": 8,
+      "capabilities_required": ["python", "messaging", "mobile"],
+      "dependencies": ["notifications_001"],
+      "metadata": {
+        "service": "notifications",
+        "type": "feature"
+      }
+    }
+  ],
+  "expected_outcomes": {
+    "total_tasks": 22,
+    "max_depth": 2,
+    "parallel_branches": 8,
+    "total_effort": 497,
+    "critical_path": ["platform_001", "auth_001", "platform_002", "gateway_002", "platform_007"],
+    "teams": ["platform", "backend", "fintech", "data", "frontend", "mobile"],
+    "capabilities_distribution": {
+      "python": 18,
+      "typescript": 2,
+      "security": 8,
+      "database": 6,
+      "messaging": 4
+    },
+    "service_dependencies": {
+      "auth": ["gateway", "users", "payments"],
+      "gateway": ["frontend", "mobile"],
+      "users": ["notifications", "analytics"]
+    }
+  }
+}
\ No newline at end of file
diff --git a/tests/planner/test_data/projects/simple_web_app.json b/tests/planner/test_data/projects/simple_web_app.json
new file mode 100644
index 00000000..075c7113
--- /dev/null
+++ b/tests/planner/test_data/projects/simple_web_app.json
@@ -0,0 +1,146 @@
+{
+  "project": {
+    "id": "simple_web_app",
+    "name": "Simple Web Application",
+    "description": "A basic web application with frontend, backend, and deployment",
+    "created": "2025-01-01T00:00:00Z",
+    "status": "NOT_STARTED",
+    "capabilities_required": ["python", "javascript", "devops"],
+    "estimated_complexity": "low",
+    "max_parallel_agents": 2
+  },
+  "tasks": [
+    {
+      "id": "webapp_001",
+      "name": "Frontend Development",
+      "description": "Build responsive web frontend",
+      "parent_id": null,
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 8,
+      "capabilities_required": ["javascript", "css"],
+      "dependencies": [],
+      "metadata": {
+        "component": "frontend",
+        "type": "development"
+      }
+    },
+    {
+      "id": "webapp_002",
+      "name": "Create React Components",
+      "description": "Build reusable React components for UI",
+      "parent_id": "webapp_001",
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 4,
+      "capabilities_required": ["javascript", "react"],
+      "dependencies": [],
+      "metadata": {
+        "component": "frontend",
+        "type": "implementation"
+      }
+    },
+    {
+      "id": "webapp_003",
+      "name": "Implement Responsive Design",
+      "description": "Add responsive CSS and mobile optimization",
+      "parent_id": "webapp_001",
+      "status": "NOT_STARTED",
+      "priority": "medium",
+      "estimated_effort": 3,
+      "capabilities_required": ["css", "design"],
+      "dependencies": ["webapp_002"],
+      "metadata": {
+        "component": "frontend",
+        "type": "implementation"
+      }
+    },
+    {
+      "id": "webapp_004",
+      "name": "Backend API Development",
+      "description": "Build REST API and database layer",
+      "parent_id": null,
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 12,
+      "capabilities_required": ["python", "database"],
+      "dependencies": [],
+      "metadata": {
+        "component": "backend",
+        "type": "development"
+      }
+    },
+    {
+      "id": "webapp_005",
+      "name": "Create Database Models",
+      "description": "Define SQLAlchemy models and relationships",
+      "parent_id": "webapp_004",
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 3,
+      "capabilities_required": ["python", "sqlalchemy"],
+      "dependencies": [],
+      "metadata": {
+        "component": "backend",
+        "type": "implementation"
+      }
+    },
+    {
+      "id": "webapp_006",
+      "name": "Implement API Endpoints",
+      "description": "Build FastAPI endpoints with validation",
+      "parent_id": "webapp_004",
+      "status": "NOT_STARTED",
+      "priority": "high",
+      "estimated_effort": 6,
+      "capabilities_required": ["python", "fastapi"],
+      "dependencies": ["webapp_005"],
+      "metadata": {
+        "component": "backend",
+        "type": "implementation"
+      }
+    },
+    {
+      "id": "webapp_007",
+      "name": "Add Authentication",
+      "description": "Implement JWT-based user authentication",
+      "parent_id": "webapp_004",
+      "status": "NOT_STARTED",
+      "priority": "medium",
+      "estimated_effort": 4,
+      "capabilities_required": ["python", "security"],
+      "dependencies": ["webapp_006"],
+      "metadata": {
+        "component": "backend",
+        "type": "feature"
+      }
+    },
+    {
+      "id": "webapp_008",
+      "name": "Deployment Setup",
+      "description": "Configure production deployment and CI/CD",
+      "parent_id": null,
+      "status": "NOT_STARTED",
+      "priority": "medium",
+      "estimated_effort": 6,
+      "capabilities_required": ["devops", "docker"],
+      "dependencies": ["webapp_001", "webapp_004"],
+      "metadata": {
+        "component": "deployment",
+        "type": "infrastructure"
+      }
+    }
+  ],
+  "expected_outcomes": {
+    "total_tasks": 8,
+    "max_depth": 2,
+    "parallel_branches": 3,
+    "total_effort": 46,
+    "critical_path": ["webapp_001", "webapp_002", "webapp_003"],
+    "capabilities_distribution": {
+      "javascript": 3,
+      "python": 4,
+      "devops": 1
+    }
+  }
+}
\ No newline at end of file
diff --git a/tests/planner/test_scenarios.md b/tests/planner/test_scenarios.md
new file mode 100644
index 00000000..0e0061c2
--- /dev/null
+++ b/tests/planner/test_scenarios.md
@@ -0,0 +1,486 @@
+# Super-Planner Test Scenarios
+
+Comprehensive test scenarios with verification criteria for the super-planner system.
+
+## End-to-End Workflow Tests
+
+### E2E-001: Complete Planning Mode Workflow
+
+**Scenario**: Project creation through recursive task breakdown
+
+**Setup**:
+- Empty workspace with git repository
+- Simple project requirements (web app with 3 components)
+- Mock LLM service configured for task breakdown
+
+**Execution Steps**:
+1. Create new project via CLI: `amplifier plan create "Simple Web App"`
+2. System enters planning mode and breaks down high-level goals
+3. User confirms and approves initial task structure
+4. System recursively breaks down complex tasks (depth 2-3)
+5. System detects completion criteria and exits planning mode
+6. Final task structure is persisted to git
+
+**Success Criteria**:
+- ✅ Project created with 8-12 tasks across 2-3 levels
+- ✅ All tasks have valid states (NOT_STARTED) and dependencies
+- ✅ No circular dependencies detected
+- ✅ Git commit created with semantic message
+- ✅ Task hierarchy matches expected structure from test data
+- ✅ Planning mode automatically transitions to working mode
+
+**Verification Commands**:
+```bash
+amplifier plan status
+amplifier plan tree --show-dependencies
+git log --oneline -5
+```
+
+### E2E-002: Complete Working Mode Workflow
+
+**Scenario**: Task assignment through completion tracking
+
+**Setup**:
+- Project with 20 tasks in NOT_STARTED state (from complex_microservices_platform.json)
+- 3 mock agents with different capabilities registered
+- Git repository initialized
+
+**Execution Steps**:
+1. Enter working mode: `amplifier plan work`
+2. System analyzes available tasks and agent capabilities
+3. Assigns initial batch of 6 tasks to 3 agents
+4. Agents claim tasks and begin work (simulated)
+5. Tasks progress through states: ASSIGNED → IN_PROGRESS → COMPLETED
+6. System detects completed dependencies and assigns follow-up tasks
+7. Continue until all tasks completed or blocked
+
+**Success Criteria**:
+- ✅ Load balanced assignment across agents (variance <20%)
+- ✅ Dependencies respected (no task starts before dependencies complete)
+- ✅ All available tasks assigned within 30 seconds
+- ✅ State transitions logged with timestamps
+- ✅ Git commits created for major milestones
+- ✅ Final project state shows all tasks COMPLETED
+
+**Verification Commands**:
+```bash
+amplifier plan status --show-agents
+amplifier plan history
+git log --grep="task completion"
+```
+
+### E2E-003: Cross-Mode Switching
+
+**Scenario**: Switch between planning and working modes based on conditions
+
+**Setup**:
+- Project 50% complete (half tasks in COMPLETED state)
+- Discovery of new requirements requiring additional tasks
+- 2 agents actively working on tasks
+
+**Execution Steps**:
+1. Start in working mode with active agents
+2. User discovers new requirement: "Add mobile app support"
+3. Switch to planning mode: `amplifier plan --mode=planning`
+4. System pauses agent coordination
+5. Break down new mobile requirements into tasks
+6. Integrate new tasks into existing project structure
+7. Switch back to working mode
+8. Resume agent coordination with expanded task list
+
+**Success Criteria**:
+- ✅ Mode transition doesn't lose existing work
+- ✅ Agent states preserved during planning pause
+- ✅ New tasks properly integrated with dependencies
+- ✅ No deadlocks or conflicts introduced
+- ✅ Total project coherence maintained
+- ✅ Git history shows clear mode transitions
+
+## Multi-Agent Coordination Tests
+
+### COORD-001: Concurrent Task Claiming
+
+**Scenario**: Multiple agents attempt to claim same tasks simultaneously
+
+**Setup**:
+- Project with 10 available tasks
+- 5 agents with overlapping capabilities
+- Network partition simulation (delayed responses)
+
+**Execution Steps**:
+1. All 5 agents request task assignments simultaneously
+2. System processes claims with optimistic locking
+3. First agent succeeds, others receive updated state
+4. Agents retry with remaining tasks
+5. System ensures no double-assignment occurs
+
+**Success Criteria**:
+- ✅ No task assigned to multiple agents
+- ✅ All agents receive tasks within reasonable time
+- ✅ File system maintains consistency under concurrent access
+- ✅ Optimistic locking prevents race conditions
+- ✅ Agent retry logic handles conflicts gracefully
+
+### COORD-002: Agent Failure and Recovery
+
+**Scenario**: Agent crashes mid-task execution
+
+**Setup**:
+- Agent working on critical path task for 15 minutes
+- Task 60% complete with intermediate state saved
+- Other agents waiting on this task's completion
+
+**Execution Steps**:
+1. Agent crashes/disconnects during task execution
+2. System detects stale agent lease (timeout)
+3. Task returns to ASSIGNED state after lease expires
+4. System reassigns task to another capable agent
+5. New agent resumes work from last checkpoint
+6. Task completes successfully
+
+**Success Criteria**:
+- ✅ Failed agent detected within 5 minutes
+- ✅ Task reassigned within 2 minutes of detection
+- ✅ No work lost (checkpoint recovery)
+- ✅ Dependent tasks not indefinitely blocked
+- ✅ System health metrics updated correctly
+
+### COORD-003: Resource Contention Management
+
+**Scenario**: More tasks available than agent capacity
+
+**Setup**:
+- 50 tasks ready for assignment
+- 8 agents with capacity for 3 tasks each (24 total capacity)
+- Tasks have different priorities and effort estimates
+
+**Execution Steps**:
+1. System analyzes available capacity and task priorities
+2. Assigns 24 highest priority tasks to agents
+3. Remaining 26 tasks queued by priority
+4. As agents complete tasks, new tasks assigned from queue
+5. System maintains optimal utilization throughout
+
+**Success Criteria**:
+- ✅ Highest priority tasks assigned first
+- ✅ Agent utilization >85% maintained
+- ✅ Queue processing fair and efficient
+- ✅ No agent overloaded (>3 concurrent tasks)
+- ✅ Load balancing considers task effort estimates
+
+## Data Integrity Tests
+
+### DATA-001: Concurrent State Modifications
+
+**Scenario**: Multiple agents attempt to modify task state simultaneously
+
+**Setup**:
+- Task in IN_PROGRESS state
+- Agent A attempts to mark COMPLETED
+- Agent B attempts to mark BLOCKED (race condition)
+- File system operations overlap
+
+**Execution Steps**:
+1. Both agents read current task state
+2. Both prepare state transition modifications
+3. Agent A writes COMPLETED state first
+4. Agent B attempts to write BLOCKED state
+5. System detects version conflict
+6. Appropriate conflict resolution applied
+
+**Success Criteria**:
+- ✅ Final state is consistent and valid
+- ✅ No intermediate corrupted states
+- ✅ Conflicting modifications properly resolved
+- ✅ Both agents notified of final state
+- ✅ Audit log shows complete transaction history
+
+### DATA-002: Dependency Cycle Detection
+
+**Scenario**: Complex dependency modifications create circular references
+
+**Setup**:
+- Project with 100 tasks and complex dependency web
+- Administrative changes to dependencies
+- Some changes introduce cycles
+
+**Execution Steps**:
+1. Load project with existing dependencies
+2. Add new dependency: Task A depends on Task B
+3. Later add: Task B depends on Task C
+4. Finally add: Task C depends on Task A (creates cycle)
+5. System detects cycle before persisting
+6. Reject modification with clear error message
+
+**Success Criteria**:
+- ✅ Cycle detected before persistence
+- ✅ Clear error message with cycle path
+- ✅ Suggestions for breaking cycle provided
+- ✅ Data integrity maintained (no partial writes)
+- ✅ Performance acceptable for large projects (<5s)
+
+### DATA-003: File Corruption Recovery
+
+**Scenario**: Task file becomes corrupted due to system crash
+
+**Setup**:
+- Project with 200 tasks persisted in JSON files
+- Simulate system crash during file write operation
+- Partial/corrupted task file on disk
+
+**Execution Steps**:
+1. System starts and detects corrupted task file
+2. Attempts to parse file, fails with JSON error
+3. Looks for backup/previous version in git history
+4. Restores from last known good state
+5. Reports data loss and recovery actions to user
+
+**Success Criteria**:
+- ✅ Corruption detected on startup
+- ✅ Recovery attempted automatically
+- ✅ Last known good state restored
+- ✅ User notified of any data loss
+- ✅ System functional after recovery
+
+## Performance and Scale Tests
+
+### PERF-001: Large Project Handling
+
+**Scenario**: Project with 1000+ tasks and complex dependencies
+
+**Setup**:
+- Generate project with 1000 tasks across 6 levels
+- 200+ cross-dependencies between tasks
+- 12 different capability types required
+
+**Execution Steps**:
+1. Load complete project structure from disk
+2. Analyze dependency graph for bottlenecks
+3. Assign tasks to 10 concurrent agents
+4. Track memory usage and response times
+5. Complete 100 tasks with state transitions
+
+**Performance Requirements**:
+- ✅ Project load time <30 seconds
+- ✅ Memory usage <1GB for full project
+- ✅ Dependency analysis <10 seconds
+- ✅ Task assignment <5 seconds per batch
+- ✅ State transitions <100ms each
+
+### PERF-002: Concurrent Agent Limits
+
+**Scenario**: Stress test with maximum concurrent agents
+
+**Setup**:
+- Project with 500 available tasks
+- 20 agents attempting to work simultaneously
+- Network delays and processing variations simulated
+
+**Execution Steps**:
+1. Start 20 agents requesting work
+2. System processes all requests concurrently
+3. Monitor file I/O contention and locking
+4. Track assignment fairness and efficiency
+5. Measure system degradation points
+
+**Performance Requirements**:
+- ✅ Support 20 concurrent agents without deadlock
+- ✅ Assignment fairness variance <15%
+- ✅ File I/O errors <1% of operations
+- ✅ Average response time <2 seconds
+- ✅ System remains stable under load
+
+### PERF-003: Git Operations Under Load
+
+**Scenario**: Frequent git commits with concurrent modifications
+
+**Setup**:
+- High-frequency task completions (5 per minute)
+- Each completion triggers git commit
+- Multiple agents working simultaneously
+
+**Execution Steps**:
+1. Configure auto-commit for task completions
+2. Start 8 agents completing tasks rapidly
+3. Monitor git operation performance
+4. Track commit conflicts and resolutions
+5. Verify git history integrity
+
+**Performance Requirements**:
+- ✅ Git commits complete <5 seconds each
+- ✅ No git conflicts or corruption
+- ✅ History maintains chronological order
+- ✅ Branch operations don't block agents
+- ✅ Repository size growth reasonable
+
+## Integration Tests
+
+### INT-001: Amplifier Task Tool Integration
+
+**Scenario**: Super-planner spawns agents using amplifier's Task tool
+
+**Setup**:
+- Amplifier environment with Task tool available
+- Project requiring Python and TypeScript agents
+- Mock agent implementations in catalog
+
+**Execution Steps**:
+1. System identifies tasks needing external agents
+2. Use Task tool to spawn appropriate agents
+3. Monitor agent communication and coordination
+4. Track task progress from external agents
+5. Handle agent failures and respawning
+
+**Success Criteria**:
+- ✅ Agents spawned successfully via Task tool
+- ✅ Communication protocols work correctly
+- ✅ Task progress updates received
+- ✅ Failed agents automatically respawned
+- ✅ Integration feels seamless to users
+
+### INT-002: CCSDK Defensive Utilities Integration
+
+**Scenario**: Use defensive utilities for robust LLM and file operations
+
+**Setup**:
+- Task breakdown requiring LLM calls
+- File operations with cloud sync delays
+- Network intermittency simulation
+
+**Execution Steps**:
+1. Task breakdown calls LLM for complex planning
+2. Use parse_llm_json() for response parsing
+3. File operations use retry_with_feedback()
+4. Network issues trigger defensive patterns
+5. System remains stable throughout
+
+**Success Criteria**:
+- ✅ LLM response parsing never fails
+- ✅ File operations survive cloud sync delays
+- ✅ Network issues handled gracefully
+- ✅ No system crashes or data corruption
+- ✅ User experience remains smooth
+
+### INT-003: Git Workflow Compatibility
+
+**Scenario**: Super-planner integrates with amplifier's git patterns
+
+**Setup**:
+- Amplifier project with existing git workflow
+- Super-planner operating in same repository
+- Multiple developers working simultaneously
+
+**Execution Steps**:
+1. Initialize planner in existing amplifier project
+2. Planner creates commits following project conventions
+3. External developers make concurrent changes
+4. Planner handles merge conflicts appropriately
+5. Git history remains clean and meaningful
+
+**Success Criteria**:
+- ✅ Commit messages follow project conventions
+- ✅ No conflicts with external git workflow
+- ✅ Branch management works correctly
+- ✅ Merge conflicts resolved appropriately
+- ✅ Git history helpful for debugging
+
+## Failure Scenario Tests
+
+### FAIL-001: Network Partition During Coordination
+
+**Scenario**: Network issues prevent agent communication
+
+**Setup**:
+- 5 agents working across network partitions
+- Tasks with complex interdependencies
+- Simulate network splits and healing
+
+**Execution Steps**:
+1. Agents begin coordinated work on project
+2. Network partition separates 2 agents from others
+3. Isolated agents continue local work
+4. Network heals after 10 minutes
+5. System reconciles conflicting states
+
+**Success Criteria**:
+- ✅ Isolated agents don't block others
+- ✅ Work continues on both sides of partition
+- ✅ State reconciliation successful after healing
+- ✅ No work lost due to partition
+- ✅ Dependencies still respected after reconciliation
+
+### FAIL-002: Disk Full During Operations
+
+**Scenario**: File system runs out of space during task operations
+
+**Setup**:
+- Large project with extensive task data
+- Disk space artificially limited
+- Operations trigger disk full condition
+
+**Execution Steps**:
+1. Begin large task breakdown operation
+2. Disk space exhausted mid-operation
+3. System detects write failures
+4. Gracefully degrade functionality
+5. Resume when space available
+
+**Success Criteria**:
+- ✅ Write failures detected immediately
+- ✅ Partial operations rolled back cleanly
+- ✅ System remains stable despite failures
+- ✅ Clear error messages provided to user
+- ✅ Automatic recovery when space available
+
+### FAIL-003: Corrupted Task Dependencies
+
+**Scenario**: Task dependency data becomes corrupted
+
+**Setup**:
+- Project with complex dependency web
+- Simulate data corruption in dependency files
+- Some dependencies point to non-existent tasks
+
+**Execution Steps**:
+1. Load project with corrupted dependencies
+2. System detects invalid references
+3. Attempt to reconstruct valid dependency graph
+4. Isolate corrupted tasks if necessary
+5. Continue operations with partial data
+
+**Success Criteria**:
+- ✅ Corruption detected on load
+- ✅ Invalid dependencies identified
+- ✅ Partial recovery attempted
+- ✅ System remains functional
+- ✅ Recovery actions logged for debugging
+
+## Success Metrics
+
+Each test scenario must meet these comprehensive success criteria:
+
+### Functional Correctness
+- All specified behaviors work as documented
+- Edge cases handled appropriately
+- Error conditions fail gracefully
+- Data integrity maintained under all conditions
+
+### Performance Acceptability
+- Response times within specified limits
+- Memory usage within reasonable bounds
+- Concurrent operations scale appropriately
+- Degradation is graceful under load
+
+### Reliability Standards
+- 99.9% success rate on valid operations
+- Automatic recovery from transient failures
+- No data corruption under any circumstances
+- Consistent behavior across multiple runs
+
+### User Experience Quality
+- Clear error messages with actionable guidance
+- Visible progress indicators for long operations
+- Predictable behavior that matches user expectations
+- Seamless integration with existing amplifier workflow
+
+These test scenarios ensure the super-planner system is robust, reliable, and ready for production use before any implementation begins.
\ No newline at end of file
diff --git a/website_generator/README.md b/website_generator/README.md
new file mode 100644
index 00000000..0253cf06
--- /dev/null
+++ b/website_generator/README.md
@@ -0,0 +1,53 @@
+# Automated Website Generator Tool
+
+This tool automatically generates high-quality, paradigm-aware websites for repositories, inspired by the successful Amplifier instructor website transformation.
+
+## Overview
+
+The website generator analyzes repositories to detect paradigm shifts and generates appropriate content:
+- **Revolutionary Change** (like Amplifier) → Full paradigm transformation content
+- **Evolutionary Change** → Focus on improvements and enhancements
+- **Incremental Change** → Standard feature documentation
+
+## Key Features
+
+- Repository structure and capability analysis
+- Paradigm shift detection algorithm
+- Automated content generation with progressive disclosure
+- Consistent design system and CSS generation
+- Nightly automation with change detection
+- Configuration-driven consistency preservation
+
+## Usage
+
+```bash
+# Generate website for any repository
+website_generator generate --repo /path/to/project --output ./website
+
+# Set up nightly automation
+website_generator watch --repo /path/to/project --schedule nightly
+
+# Regenerate with consistency validation
+website_generator regenerate --repo /path/to/project --validate-consistency
+```
+
+## Architecture
+
+- `src/analyzer/` - Repository analysis and paradigm detection
+- `src/content/` - Content generation and template processing
+- `src/style/` - CSS generation and component building
+- `src/website/` - Site orchestration and asset management
+- `src/automation/` - Change detection and scheduling
+- `config/` - YAML configuration templates
+- `templates/` - HTML templates and sections
+- `assets/` - CSS, JavaScript, and other assets
+
+## Implementation Status
+
+- [x] Project structure created
+- [ ] Repository analyzer implementation
+- [ ] Paradigm shift detection
+- [ ] Configuration system
+- [ ] Template engine
+- [ ] Content generation
+- [ ] Automation and scheduling
\ No newline at end of file
diff --git a/website_generator/config/content_patterns.yaml b/website_generator/config/content_patterns.yaml
new file mode 100644
index 00000000..94b29c94
--- /dev/null
+++ b/website_generator/config/content_patterns.yaml
@@ -0,0 +1,260 @@
+# Content Generation Patterns Configuration
+# Defines how to extract and generate content based on repository analysis
+
+# Repository Analysis Patterns
+analysis_patterns:
+  agent_detection:
+    file_patterns:
+      - ".claude/agents/*.md"
+      - "agents/*.md"
+      - "subagents/*.md"
+      - ".ai/agents/*.md"
+    capability_extraction: "yaml_frontmatter_and_sections"
+    description_sources:
+      - "yaml:description"
+      - "first_paragraph"
+      - "generated_from_name"
+
+  command_detection:
+    file_patterns:
+      - ".claude/commands/*.md"
+      - "commands/*.md"
+      - "scripts/*.sh"
+      - "Makefile"
+    usage_pattern_extraction: true
+    example_extraction: true
+
+  documentation_detection:
+    file_patterns:
+      - "README.md"
+      - "docs/**/*.md"
+      - "GETTING_STARTED.md"
+      - "CONTRIBUTING.md"
+      - "CHANGELOG.md"
+    priority_order: ["README.md", "docs/README.md", "GETTING_STARTED.md"]
+
+  paradigm_indicators:
+    revolutionary_keywords:
+      - "revolution"
+      - "paradigm"
+      - "transformation"
+      - "breakthrough"
+      - "game-changing"
+      - "disruptive"
+      - "fundamental"
+      - "reimagine"
+      - "multiplier"
+      - "supercharge"
+      - "amplify"
+
+    ai_keywords:
+      - "claude"
+      - "ai"
+      - "llm"
+      - "gpt"
+      - "assistant"
+      - "agent"
+      - "amplifier"
+      - "subagent"
+      - "claude code"
+
+    knowledge_keywords:
+      - "synthesis"
+      - "knowledge"
+      - "extraction"
+      - "mining"
+      - "analysis"
+      - "insight"
+      - "understanding"
+      - "learning"
+      - "memory"
+      - "context"
+
+# Content Generation Templates
+content_templates:
+
+  # Revolutionary Paradigm Content
+  revolution_section:
+    title: "The Development Revolution"
+    subtitle_template: "Why {project_name} Changes Everything"
+
+    problem_statement:
+      template: "constraint_based"
+      structure:
+        - "current_limitation"
+        - "pain_points"
+        - "scale_of_problem"
+
+    paradigm_comparison:
+      template: "before_after_table"
+      format: "side_by_side"
+      categories:
+        - "Development Speed"
+        - "Code Quality"
+        - "Learning Curve"
+        - "Scalability"
+        - "Maintenance"
+
+    multiplier_calculation:
+      template: "capability_multiplication"
+      metrics:
+        - name: "Ideas Generated"
+          old_value: 50
+          new_value: 1247
+          unit: "per month"
+        - name: "Time to Implementation"
+          old_value: 12
+          new_value: 1
+          unit: "hours"
+          inverse: true  # Lower is better
+
+    role_transformation:
+      template: "old_role_vs_new_role"
+      transformation_type: "elevation"  # elevation, replacement, enhancement
+      old_role:
+        title: "Traditional Developer"
+        characteristics:
+          - "Code line by line"
+          - "Debug manually"
+          - "Single-threaded work"
+      new_role:
+        title: "AI-Amplified Architect"
+        characteristics:
+          - "Design and orchestrate"
+          - "Deploy specialized agents"
+          - "Parallel development streams"
+
+  # Progressive Setup Tiers
+  progressive_setup:
+    tier_structure:
+      quick_taste:
+        name: "Quick Taste"
+        duration: "1 minute"
+        description: "Experience the power immediately"
+        content_type: "1_minute_demo"
+
+      essential:
+        name: "Essential Setup"
+        duration: "5 minutes"
+        description: "Core features and workflows"
+        content_type: "5_minute_core_features"
+
+      power_user:
+        name: "Power User"
+        duration: "15+ minutes"
+        description: "Full ecosystem mastery"
+        content_type: "15_minute_full_ecosystem"
+
+    content_generation:
+      demo_commands:
+        extract_from: "README.md"
+        fallback: "generated_examples"
+        format: "terminal_block"
+
+      step_by_step:
+        number_steps: true
+        include_screenshots: false
+        code_highlighting: true
+
+  # Agent Capability Showcase
+  capability_showcase:
+    organization: "beginner_intermediate_expert"  # beginner_intermediate_expert, by_category, alphabetical
+    presentation: "card_grid_with_examples"       # card_grid_with_examples, list_with_details, table_format
+    progressive_reveal: true
+
+    agent_card_template:
+      elements:
+        - "agent_name"
+        - "agent_badge"  # Category/specialty
+        - "description"
+        - "key_capabilities"
+        - "usage_example"
+
+      badge_categories:
+        architecture: "Architecture"
+        debugging: "Debugging"
+        testing: "Testing"
+        security: "Security"
+        analysis: "Analysis"
+        synthesis: "Synthesis"
+        automation: "Automation"
+
+    examples_generation:
+      include_code: true
+      include_commands: true
+      show_output: true
+      max_length: 200  # characters
+
+  # Feature Documentation
+  feature_documentation:
+    organization: "by_importance"  # by_importance, alphabetical, by_category
+    detail_level: "comprehensive"   # brief, standard, comprehensive
+
+    feature_template:
+      structure:
+        - "description"
+        - "benefits"
+        - "usage_example"
+        - "related_features"
+
+      example_formats:
+        - "code_block"
+        - "terminal_session"
+        - "configuration_snippet"
+
+# Trust Building Patterns
+trust_building:
+  safety_demonstrations: true
+  gradual_confidence_building: true
+  human_role_elevation: true
+  ai_quality_assurance_showcase: true
+
+  progression_stages:
+    1_skeptical:
+      focus: "concrete_examples"
+      tone: "professional_proof"
+      content: ["quick_wins", "safety_first", "easy_exit"]
+
+    2_curious:
+      focus: "deeper_capabilities"
+      tone: "educational_guide"
+      content: ["how_it_works", "best_practices", "common_patterns"]
+
+    3_convinced:
+      focus: "mastery_path"
+      tone: "empowering_mentor"
+      content: ["advanced_features", "customization", "integration"]
+
+# Content Quality Guidelines
+quality_guidelines:
+  readability:
+    target_grade_level: 12  # Flesch-Kincaid
+    sentence_length: "medium"  # short, medium, long
+    paragraph_length: "concise"  # concise, standard, detailed
+
+  technical_accuracy:
+    verify_commands: true
+    test_examples: false  # Future feature
+    check_links: false    # Future feature
+
+  consistency:
+    terminology: "strict"     # strict, flexible
+    formatting: "consistent" # consistent, adaptive
+    voice: "professional"    # professional, casual, technical
+
+# Responsive Content Adaptation
+responsive_content:
+  mobile:
+    simplify_tables: true
+    stack_comparisons: true
+    shorter_descriptions: true
+    fewer_examples: false
+
+  tablet:
+    medium_complexity: true
+    balanced_layout: true
+
+  desktop:
+    full_complexity: true
+    side_by_side_comparisons: true
+    rich_interactions: true
\ No newline at end of file
diff --git a/website_generator/config/site_template.yaml b/website_generator/config/site_template.yaml
new file mode 100644
index 00000000..d15c9fed
--- /dev/null
+++ b/website_generator/config/site_template.yaml
@@ -0,0 +1,155 @@
+# Master Site Template Configuration
+# This file defines the overall structure and behavior of generated websites
+
+# Site Identity & Branding
+site:
+  name: "Amplifier"
+  tagline: "Supercharged AI Development"
+  description: "A complete development environment that supercharges AI coding assistants"
+  theme: "revolution"  # revolution, professional, minimal, modern
+  favicon: "assets/favicon.ico"
+  logo: "assets/logo.png"
+
+# Content Generation Strategy
+content_strategy:
+  paradigm_shift_detection: true
+  progressive_disclosure: true
+  trust_building_focus: true
+  role_transformation_emphasis: true
+
+  # Content depth based on paradigm type
+  revolutionary_features:
+    - "development_revolution_section"
+    - "paradigm_comparison_table"
+    - "capability_multiplication_demo"
+    - "role_transformation_narrative"
+    - "trust_building_progression"
+
+  evolutionary_features:
+    - "improvement_showcase"
+    - "before_after_comparison"
+    - "enhancement_timeline"
+    - "migration_guide"
+
+  incremental_features:
+    - "feature_list"
+    - "getting_started_guide"
+    - "api_documentation"
+    - "examples_gallery"
+
+# Design System
+design_system:
+  color_palette: "amplifier_blue_gradient"  # amplifier_blue_gradient, professional_navy, minimal_gray
+  typography: "inter_modern"               # inter_modern, roboto_clean, system_default
+  component_style: "card_based_progressive" # card_based_progressive, minimal_list, traditional_docs
+  animation_level: "engaging"              # minimal, subtle, engaging, bold
+
+  # CSS Custom Properties
+  colors:
+    primary: "#2563eb"      # Main blue
+    secondary: "#1e40af"    # Darker blue
+    accent: "#3b82f6"       # Lighter blue
+    success: "#10b981"      # Green
+    warning: "#f59e0b"      # Orange
+    danger: "#ef4444"       # Red
+    background: "#ffffff"   # White
+    surface: "#f8fafc"      # Light gray
+    text_primary: "#1f2937" # Dark gray
+    text_secondary: "#6b7280" # Medium gray
+    border: "#e5e7eb"       # Light gray border
+
+# Page Structure
+pages:
+  - name: "index"
+    title: "Home"
+    sections:
+      - "revolution"        # Only for revolutionary paradigm
+      - "hero"
+      - "overview"
+      - "features"
+      - "quick_setup"
+      - "examples"
+      - "cta"
+
+  - name: "setup"
+    title: "Setup Guide"
+    sections:
+      - "progressive_tiers"
+      - "detailed_instructions"
+      - "troubleshooting"
+      - "advanced_configuration"
+
+  - name: "agents"
+    title: "Specialized Agents"
+    sections:
+      - "agent_showcase"
+      - "capability_matrix"
+      - "integration_patterns"
+      - "custom_agents"
+
+  - name: "examples"
+    title: "Examples"
+    sections:
+      - "example_gallery"
+      - "use_cases"
+      - "workflows"
+      - "best_practices"
+
+# Interactive Elements
+interactions:
+  animated_counters: true
+  progressive_setup_tiers: true
+  terminal_demos: true
+  copy_paste_commands: true
+  tabbed_content: true
+  collapsible_sections: true
+  search_functionality: false  # Advanced feature for later
+
+  # Animation settings
+  animations:
+    fade_in_delay: 100        # ms
+    counter_duration: 2000    # ms
+    scroll_reveal_threshold: 0.1
+    typing_speed: 80          # ms per character
+
+# Navigation
+navigation:
+  style: "horizontal"  # horizontal, vertical, mobile_first
+  sticky: true
+  include_search: false
+
+  # Navigation items (auto-generated from pages + custom)
+  custom_items:
+    - name: "GitHub"
+      url: "https://github.com/repository"
+      external: true
+    - name: "Documentation"
+      url: "/docs"
+      external: false
+
+# SEO and Meta
+seo:
+  meta_description_template: "{description} - {tagline}"
+  keywords: ["ai", "development", "automation", "agents", "claude"]
+  og_image: "assets/og-image.png"
+  twitter_card: "summary_large_image"
+
+# Build Settings
+build:
+  minify_css: true
+  minify_js: true
+  optimize_images: false  # Future feature
+  generate_sitemap: true
+
+# Responsive Design
+responsive:
+  breakpoints:
+    mobile: "768px"
+    tablet: "1024px"
+    desktop: "1280px"
+
+  # Mobile-specific settings
+  mobile:
+    hide_animations: false
+    simplify_navigation: true
+    stack_cards: true
\ No newline at end of file
diff --git a/website_generator/examples/amplifier_config.yaml b/website_generator/examples/amplifier_config.yaml
new file mode 100644
index 00000000..64eca1ad
--- /dev/null
+++ b/website_generator/examples/amplifier_config.yaml
@@ -0,0 +1,207 @@
+# Example Configuration for Amplifier Project
+# This configuration demonstrates how to customize the website generator for the Amplifier project
+
+# Override site-specific settings
+site:
+  name: "Amplifier"
+  tagline: "Supercharged AI Development"
+  description: "A complete development environment that supercharges AI coding assistants with 25+ specialized agents, modular architecture, and parallel workflow capabilities"
+  theme: "revolution"
+
+  # Amplifier-specific branding
+  repo_url: "https://github.com/user/amplifier"
+  demo_video: "https://example.com/amplifier-demo"
+
+# Content strategy optimized for revolutionary paradigm
+content_strategy:
+  paradigm_shift_detection: true
+  progressive_disclosure: true
+  trust_building_focus: true
+  role_transformation_emphasis: true
+
+  # Amplifier-specific content emphasis
+  highlight_agent_count: true  # Showcase 25+ agents
+  emphasize_parallel_workflows: true
+  show_complexity_reduction: true
+
+# Design system tuned for Amplifier
+design_system:
+  color_palette: "amplifier_blue_gradient"
+  typography: "inter_modern"
+  component_style: "card_based_progressive"
+  animation_level: "engaging"
+
+  # Custom colors for Amplifier brand
+  colors:
+    primary: "#2563eb"      # Amplifier blue
+    secondary: "#1e40af"    # Darker blue
+    accent: "#3b82f6"       # Lighter blue
+    success: "#10b981"      # Green for positive metrics
+    revolution: "#6366f1"   # Purple for revolution theme
+
+# Page structure optimized for Amplifier
+pages:
+  - name: "index"
+    title: "Amplifier - Supercharged AI Development"
+    sections:
+      - "revolution"        # Revolutionary paradigm section
+      - "hero"             # Hero with animated counters
+      - "overview"         # System overview
+      - "agent_showcase"   # Highlight 25+ agents
+      - "quick_setup"      # 3-tier progressive setup
+      - "examples"         # Real workflow examples
+      - "cta"              # Get started CTA
+
+  - name: "setup"
+    title: "Setup Guide"
+    sections:
+      - "progressive_tiers"    # Quick taste → Essential → Power user
+      - "installation"         # Step-by-step install
+      - "first_agent"          # Your first agent workflow
+      - "troubleshooting"      # Common issues
+
+  - name: "agents"
+    title: "25+ Specialized Agents"
+    sections:
+      - "agent_gallery"        # All agents with search/filter
+      - "agent_categories"     # By specialty
+      - "workflow_examples"    # Multi-agent workflows
+      - "custom_agents"        # Creating your own
+
+# Interactive elements for Amplifier
+interactions:
+  animated_counters: true
+  progressive_setup_tiers: true
+  terminal_demos: true
+  copy_paste_commands: true
+  agent_carousel: true
+
+  # Amplifier-specific counters
+  counters:
+    - name: "ideas_generated"
+      label: "Ideas Generated"
+      end_value: 1247
+      duration: 2000
+      format: "number"
+    - name: "time_saved"
+      label: "Hours Saved"
+      end_value: 1200
+      duration: 1800
+      format: "number"
+    - name: "specialized_agents"
+      label: "Specialized Agents"
+      end_value: 25
+      duration: 1500
+      format: "number"
+
+# Navigation for Amplifier
+navigation:
+  style: "horizontal"
+  sticky: true
+  custom_items:
+    - name: "GitHub"
+      url: "https://github.com/user/amplifier"
+      external: true
+    - name: "Documentation"
+      url: "/docs"
+      external: false
+    - name: "Community"
+      url: "https://discord.gg/amplifier"
+      external: true
+
+# SEO optimized for Amplifier
+seo:
+  meta_description_template: "Amplifier supercharges AI development with 25+ specialized agents, parallel workflows, and revolutionary paradigm shift from traditional coding to AI-amplified architecture."
+  keywords:
+    - "ai development"
+    - "claude code"
+    - "specialized agents"
+    - "development automation"
+    - "ai coding assistant"
+    - "parallel workflows"
+    - "modular architecture"
+    - "knowledge synthesis"
+
+# Content generation rules for Amplifier
+content_rules:
+  # Revolution section configuration
+  revolution_metrics:
+    ideas_multiplier: 25    # 50 → 1250 ideas
+    time_reduction: 12      # 12 hours → 1 hour
+    quality_improvement: 5  # 5x better code quality
+
+  # Agent showcase rules
+  agent_display:
+    featured_agents:
+      - "zen-architect"
+      - "bug-hunter"
+      - "security-guardian"
+      - "test-coverage"
+      - "performance-optimizer"
+
+    categories:
+      architecture: ["zen-architect", "modular-builder"]
+      debugging: ["bug-hunter", "analysis-engine"]
+      security: ["security-guardian"]
+      testing: ["test-coverage"]
+      synthesis: ["concept-extractor", "insight-synthesizer"]
+      automation: ["post-task-cleanup", "integration-specialist"]
+
+  # Setup tier customization
+  setup_tiers:
+    quick_taste:
+      focus: "First agent in 60 seconds"
+      demo_command: "Use zen-architect to design my notification system"
+      expected_output: "Complete architecture specification generated"
+
+    essential:
+      focus: "Core workflow with 5 essential agents"
+      commands:
+        - "zen-architect for system design"
+        - "modular-builder for implementation"
+        - "test-coverage for quality assurance"
+
+    power_user:
+      focus: "Full 25+ agent ecosystem mastery"
+      advanced_features:
+        - "Custom agent creation"
+        - "Parallel workflow orchestration"
+        - "Knowledge synthesis pipelines"
+
+# Trust building for Amplifier
+trust_building:
+  progression:
+    skeptical:
+      emphasize: "concrete_examples"
+      show: ["quick_wins", "reversibility", "human_control"]
+      tone: "prove_value_first"
+
+    curious:
+      emphasize: "how_it_works"
+      show: ["agent_specialization", "quality_assurance", "learning_curve"]
+      tone: "educational_depth"
+
+    convinced:
+      emphasize: "mastery_path"
+      show: ["advanced_patterns", "customization", "community"]
+      tone: "empowering_growth"
+
+# Output customization
+output:
+  file_naming:
+    index: "index.html"
+    setup: "setup.html"
+    agents: "agents.html"
+    examples: "examples.html"
+
+  asset_organization:
+    css_file: "amplifier-styles.css"
+    js_file: "amplifier-script.js"
+    images_dir: "images"
+
+  # Generation preferences
+  generation:
+    preserve_existing_assets: true
+    update_content_only: false
+    full_regeneration: true
+    backup_previous: true
\ No newline at end of file
diff --git a/website_generator/src/analyzer/repo_analyzer.py b/website_generator/src/analyzer/repo_analyzer.py
new file mode 100644
index 00000000..81825cda
--- /dev/null
+++ b/website_generator/src/analyzer/repo_analyzer.py
@@ -0,0 +1,595 @@
+"""
+Repository analyzer for extracting project structure, capabilities, and paradigm indicators.
+"""
+
+import json
+from dataclasses import asdict
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class ParadigmType(Enum):
+    """Classification of paradigm shift significance"""
+
+    REVOLUTIONARY = "revolutionary"  # Fundamental paradigm shift (3+ indicators)
+    EVOLUTIONARY = "evolutionary"  # Significant improvements (2 indicators)
+    INCREMENTAL = "incremental"  # Standard feature additions (0-1 indicators)
+
+
+@dataclass
+class ProjectInfo:
+    """Basic project metadata"""
+
+    name: str
+    description: str = ""
+    version: str = ""
+    language: str = ""
+    framework: str = ""
+
+
+@dataclass
+class AgentInfo:
+    """Information about a specialized agent"""
+
+    name: str
+    description: str
+    capabilities: list[str]
+    file_path: str
+
+
+@dataclass
+class CommandInfo:
+    """Information about a command or workflow"""
+
+    name: str
+    description: str
+    usage: str
+    file_path: str
+
+
+@dataclass
+class RepoAnalysis:
+    """Complete repository analysis results"""
+
+    project_info: ProjectInfo
+    paradigm_type: ParadigmType
+    agents: list[AgentInfo]
+    commands: list[CommandInfo]
+    workflows: list[str]
+    complexity_score: int
+    paradigm_indicators: dict[str, int]
+
+
+class RepositoryAnalyzer:
+    """Analyzes repository structure and capabilities"""
+
+    def __init__(self, repo_path: str):
+        self.repo_path = Path(repo_path)
+        if not self.repo_path.exists():
+            raise ValueError(f"Repository path does not exist: {repo_path}")
+
+    def analyze_repository(self) -> RepoAnalysis:
+        """Perform complete repository analysis"""
+        print(f"Analyzing repository: {self.repo_path}")
+
+        # Extract project metadata
+        print("Extracting project info...")
+        project_info = self._extract_project_info()
+        print(f"Project: {project_info.name} ({project_info.language})")
+
+        # Extract capabilities
+        print("Extracting agents...")
+        agents = self._extract_agents()
+        print(f"Found {len(agents)} agents")
+
+        print("Extracting commands...")
+        commands = self._extract_commands()
+        print(f"Found {len(commands)} commands")
+
+        print("Extracting workflows...")
+        workflows = self._extract_workflows()
+        print(f"Found workflows: {workflows}")
+
+        # Analyze complexity
+        print("Calculating complexity...")
+        complexity_score = self._calculate_complexity(agents, commands, workflows)
+        print(f"Complexity score: {complexity_score}")
+
+        # Detect paradigm indicators
+        print("Detecting paradigm indicators...")
+        paradigm_indicators = self._detect_paradigm_indicators(agents, commands, workflows)
+        print(f"Paradigm indicators: {paradigm_indicators}")
+
+        # Determine paradigm type
+        paradigm_type = self._classify_paradigm_shift(paradigm_indicators)
+        print(f"Paradigm type: {paradigm_type.value}")
+
+        return RepoAnalysis(
+            project_info=project_info,
+            paradigm_type=paradigm_type,
+            agents=agents,
+            commands=commands,
+            workflows=workflows,
+            complexity_score=complexity_score,
+            paradigm_indicators=paradigm_indicators,
+        )
+
+    def _extract_project_info(self) -> ProjectInfo:
+        """Extract basic project information"""
+        name = self.repo_path.name
+        description = ""
+        version = ""
+        language = ""
+        framework = ""
+
+        # Try to extract from README
+        readme_files = ["README.md", "readme.md", "README.rst", "README.txt"]
+        for readme_file in readme_files:
+            readme_path = self.repo_path / readme_file
+            if readme_path.exists():
+                with open(readme_path, encoding="utf-8") as f:
+                    content = f.read()
+                    # Extract description from first paragraph after title
+                    lines = content.split("\n")
+                    for line in lines:
+                        if line.strip() and not line.startswith("#") and not line.startswith("="):
+                            description = line.strip()
+                            break
+                break
+
+        # Try to extract from pyproject.toml
+        pyproject_path = self.repo_path / "pyproject.toml"
+        if pyproject_path.exists():
+            language = "Python"
+            try:
+                import tomllib
+
+                with open(pyproject_path, "rb") as f:
+                    data = tomllib.load(f)
+                    if "project" in data:
+                        proj = data["project"]
+                        if "description" in proj and not description:
+                            description = proj["description"]
+                        if "version" in proj:
+                            version = proj["version"]
+            except Exception:
+                pass
+
+        # Try to extract from package.json
+        package_json_path = self.repo_path / "package.json"
+        if package_json_path.exists():
+            language = "JavaScript/Node.js"
+            try:
+                with open(package_json_path) as f:
+                    data = json.load(f)
+                    if "description" in data and not description:
+                        description = data["description"]
+                    if "version" in data:
+                        version = data["version"]
+            except Exception:
+                pass
+
+        return ProjectInfo(name=name, description=description, version=version, language=language, framework=framework)
+
+    def _extract_agents(self) -> list[AgentInfo]:
+        """Extract specialized agents from the repository"""
+        agents = []
+
+        # Check common agent locations
+        agent_patterns = [".claude/agents", "agents", "subagents", ".ai/agents"]
+
+        for pattern in agent_patterns:
+            agent_dir = self.repo_path / pattern
+            if agent_dir.exists() and agent_dir.is_dir():
+                print(f"Checking agent directory: {agent_dir}")
+                for agent_file in agent_dir.glob("*.md"):
+                    print(f"Processing agent file: {agent_file.name}")
+                    agent_info = self._parse_agent_file(agent_file)
+                    if agent_info:
+                        agents.append(agent_info)
+                    else:
+                        print(f"Failed to parse agent file: {agent_file.name}")
+
+        return agents
+
+    def _parse_agent_file(self, agent_file: Path) -> AgentInfo | None:
+        """Parse an individual agent file"""
+        try:
+            with open(agent_file, encoding="utf-8") as f:
+                content = f.read()
+
+            name = agent_file.stem
+            description = ""
+            capabilities = []
+
+            lines = content.split("\n")
+            current_section = None
+            in_frontmatter = False
+            frontmatter_done = False
+
+            for i, line in enumerate(lines):
+                line_stripped = line.strip()
+
+                # Handle YAML frontmatter
+                if i == 0 and line_stripped == "---":
+                    in_frontmatter = True
+                    continue
+                if in_frontmatter and line_stripped == "---":
+                    in_frontmatter = False
+                    frontmatter_done = True
+                    continue
+                if in_frontmatter:
+                    # Parse frontmatter for description
+                    if line_stripped.startswith("description:"):
+                        description = line_stripped[12:].strip()
+                        # Remove quotes if present
+                        if (
+                            description.startswith('"')
+                            and description.endswith('"')
+                            or description.startswith("'")
+                            and description.endswith("'")
+                        ):
+                            description = description[1:-1]
+                    continue
+
+                # Skip empty lines and process content after frontmatter
+                if not frontmatter_done:
+                    continue
+
+                if line_stripped.startswith("# "):
+                    current_section = line_stripped[2:].lower()
+                elif line_stripped.startswith("## "):
+                    current_section = line_stripped[3:].lower()
+                elif line_stripped.startswith("### "):
+                    current_section = line_stripped[4:].lower()
+                elif line_stripped and not description and not line_stripped.startswith("#"):
+                    # If no description from frontmatter, use first content line
+                    if not description:
+                        description = line_stripped[:200]  # Limit description length
+                elif current_section and (
+                    "capabilit" in current_section or "skill" in current_section or "method" in current_section
+                ):
+                    if line_stripped.startswith("- "):
+                        capabilities.append(line_stripped[2:])
+                elif line_stripped.startswith("- ") and not current_section:
+                    # General bullet points as capabilities
+                    capabilities.append(line_stripped[2:])
+
+            # Ensure we have a description
+            if not description and capabilities:
+                description = f"Specialized agent with {len(capabilities)} capabilities"
+            elif not description:
+                description = f"Specialized agent: {name.replace('-', ' ').title()}"
+
+            return AgentInfo(
+                name=name,
+                description=description,
+                capabilities=capabilities,
+                file_path=str(agent_file.relative_to(self.repo_path)),
+            )
+
+        except Exception as e:
+            print(f"Error parsing agent file {agent_file}: {e}")
+            return None
+
+    def _extract_commands(self) -> list[CommandInfo]:
+        """Extract commands and workflows from the repository"""
+        commands = []
+
+        # Check common command locations
+        command_patterns = [".claude/commands/*.md", "commands/*.md", "scripts/*.md", ".ai/commands/*.md"]
+
+        for pattern in command_patterns:
+            command_dir = self.repo_path / pattern.split("/")[0]
+            if command_dir.exists() and command_dir.is_dir():
+                for command_file in command_dir.glob("*.md"):
+                    command_info = self._parse_command_file(command_file)
+                    if command_info:
+                        commands.append(command_info)
+
+        # Also check Makefile for common commands
+        makefile_path = self.repo_path / "Makefile"
+        if makefile_path.exists():
+            makefile_commands = self._parse_makefile(makefile_path)
+            commands.extend(makefile_commands)
+
+        return commands
+
+    def _parse_command_file(self, command_file: Path) -> CommandInfo | None:
+        """Parse an individual command file"""
+        try:
+            with open(command_file, encoding="utf-8") as f:
+                content = f.read()
+
+            name = command_file.stem
+            description = ""
+            usage = ""
+
+            lines = content.split("\n")
+            for line in lines:
+                line = line.strip()
+                if line and not description and not line.startswith("#"):
+                    description = line
+                    break
+
+            # Extract usage patterns (look for code blocks or command examples)
+            in_code_block = False
+            for line in lines:
+                if line.strip().startswith("```"):
+                    in_code_block = not in_code_block
+                elif in_code_block and line.strip().startswith("make "):
+                    usage = line.strip()
+                    break
+                elif line.strip().startswith("$ ") or line.strip().startswith("> "):
+                    usage = line.strip()[2:]
+                    break
+
+            return CommandInfo(
+                name=name, description=description, usage=usage, file_path=str(command_file.relative_to(self.repo_path))
+            )
+
+        except Exception as e:
+            print(f"Error parsing command file {command_file}: {e}")
+            return None
+
+    def _parse_makefile(self, makefile_path: Path) -> list[CommandInfo]:
+        """Extract commands from Makefile"""
+        commands = []
+        try:
+            with open(makefile_path, encoding="utf-8") as f:
+                content = f.read()
+
+            lines = content.split("\n")
+            for line in lines:
+                line = line.strip()
+                if ":" in line and not line.startswith("#") and not line.startswith("\t"):
+                    target = line.split(":")[0].strip()
+                    if target and not target.startswith("."):
+                        commands.append(
+                            CommandInfo(
+                                name=f"make {target}",
+                                description=f"Makefile target: {target}",
+                                usage=f"make {target}",
+                                file_path="Makefile",
+                            )
+                        )
+
+        except Exception as e:
+            print(f"Error parsing Makefile: {e}")
+
+        return commands
+
+    def _extract_workflows(self) -> list[str]:
+        """Extract workflow patterns from the repository"""
+        workflows = []
+
+        # Check for GitHub Actions
+        gh_actions_path = self.repo_path / ".github" / "workflows"
+        if gh_actions_path.exists():
+            workflows.append("GitHub Actions")
+
+        # Check for other CI/CD indicators
+        ci_files = [".travis.yml", ".circleci/config.yml", "azure-pipelines.yml", "Jenkinsfile"]
+
+        for ci_file in ci_files:
+            if (self.repo_path / ci_file).exists():
+                workflows.append(ci_file.split(".")[0].replace("/", "_"))
+
+        return workflows
+
+    def _calculate_complexity(self, agents: list[AgentInfo], commands: list[CommandInfo], workflows: list[str]) -> int:
+        """Calculate overall project complexity score"""
+        complexity = 0
+
+        # Agent complexity
+        complexity += len(agents)
+        for agent in agents:
+            complexity += len(agent.capabilities)
+
+        # Command complexity
+        complexity += len(commands)
+
+        # Workflow complexity
+        complexity += len(workflows) * 2
+
+        # File structure complexity (optimized to avoid deep recursion)
+        try:
+            # Only count files in key directories to avoid performance issues
+            key_dirs = ["src", "lib", "amplifier", ".claude", "docs"]
+            total_files = 0
+            for key_dir in key_dirs:
+                dir_path = self.repo_path / key_dir
+                if dir_path.exists():
+                    total_files += sum(1 for _ in dir_path.rglob("*.py") if _.is_file())
+                    total_files += sum(1 for _ in dir_path.rglob("*.md") if _.is_file())
+            complexity += total_files // 10  # Rough file count contribution
+        except Exception as e:
+            print(f"Warning: Could not calculate file complexity: {e}")
+
+        return min(complexity, 100)  # Cap at 100
+
+    def _detect_paradigm_indicators(
+        self, agents: list[AgentInfo], commands: list[CommandInfo], workflows: list[str]
+    ) -> dict[str, int]:
+        """Detect paradigm shift indicators"""
+        indicators = {
+            "ai_amplification": 0,
+            "specialized_agents": 0,
+            "parallel_workflows": 0,
+            "knowledge_synthesis": 0,
+            "modular_architecture": 0,
+        }
+
+        # Get all text for analysis
+        all_text = " ".join([agent.description for agent in agents] + [cmd.description for cmd in commands])
+
+        # Also check project description and README
+        try:
+            readme_content = ""
+            readme_files = ["README.md", "readme.md", "AMPLIFIER_VISION.md"]
+            for readme_file in readme_files:
+                readme_path = self.repo_path / readme_file
+                if readme_path.exists():
+                    with open(readme_path, encoding="utf-8") as f:
+                        readme_content += f.read() + " "
+            all_text += readme_content.lower()
+        except Exception:
+            pass
+
+        # AI amplification indicators - enhanced detection
+        ai_keywords = ["claude", "ai", "llm", "gpt", "assistant", "agent", "amplifier", "subagent", "claude code"]
+        ai_score = 0
+        for keyword in ai_keywords:
+            if keyword in all_text.lower():
+                ai_score += 1
+
+        # Bonus for project name containing AI-related terms
+        if any(keyword in self.repo_path.name.lower() for keyword in ai_keywords):
+            ai_score += 2
+
+        indicators["ai_amplification"] = min(ai_score, 3)
+
+        # Specialized agents - enhanced scoring
+        agent_count = len(agents)
+        if agent_count >= 20 or agent_count >= 10:  # Amplifier has 25+ agents
+            indicators["specialized_agents"] = 3
+        elif agent_count >= 5:
+            indicators["specialized_agents"] = 2
+        elif agent_count >= 1:
+            indicators["specialized_agents"] = 1
+
+        # Parallel workflows - enhanced detection
+        parallel_keywords = ["parallel", "concurrent", "async", "multi", "batch", "pipeline"]
+        parallel_score = 0
+        for keyword in parallel_keywords:
+            if keyword in all_text.lower():
+                parallel_score += 1
+        indicators["parallel_workflows"] = min(parallel_score, 3)
+
+        # Knowledge synthesis - enhanced detection
+        knowledge_keywords = [
+            "synthesis",
+            "knowledge",
+            "extraction",
+            "mining",
+            "analysis",
+            "insight",
+            "understanding",
+            "learning",
+            "memory",
+            "context",
+            "reasoning",
+            "thinking",
+            "cognitive",
+        ]
+        knowledge_score = 0
+        for keyword in knowledge_keywords:
+            if keyword in all_text.lower():
+                knowledge_score += 1
+        indicators["knowledge_synthesis"] = min(knowledge_score // 2, 3)  # Scale down slightly
+
+        # Modular architecture - enhanced detection
+        modular_keywords = [
+            "modular",
+            "module",
+            "component",
+            "brick",
+            "plugin",
+            "microservice",
+            "service",
+            "toolkit",
+            "framework",
+            "architecture",
+            "system",
+            "platform",
+        ]
+        modular_score = 0
+        for keyword in modular_keywords:
+            if keyword in all_text.lower():
+                modular_score += 1
+        if modular_score >= 3:
+            indicators["modular_architecture"] = 3
+        elif modular_score >= 1:
+            indicators["modular_architecture"] = 2
+
+        # Revolutionary project bonus - check for paradigm shift language
+        revolutionary_keywords = [
+            "revolution",
+            "paradigm",
+            "transformation",
+            "breakthrough",
+            "game-chang",
+            "disruptive",
+            "fundamental",
+            "reimagin",
+            "multiplier",
+            "supercharg",
+            "amplif",
+        ]
+        revolutionary_score = 0
+        for keyword in revolutionary_keywords:
+            if keyword in all_text.lower():
+                revolutionary_score += 1
+
+        # Boost all scores if revolutionary language is detected
+        if revolutionary_score >= 3:
+            for key in indicators:
+                indicators[key] = min(indicators[key] + 1, 3)
+
+        return indicators
+
+    def _classify_paradigm_shift(self, indicators: dict[str, int]) -> ParadigmType:
+        """Classify the paradigm shift significance"""
+        total_score = sum(indicators.values())
+
+        # Check for specific revolutionary patterns
+        has_many_agents = indicators["specialized_agents"] >= 3
+        has_ai_focus = indicators["ai_amplification"] >= 3
+        has_knowledge_work = indicators["knowledge_synthesis"] >= 2
+
+        # Revolutionary: High total score OR strong AI+agents combination
+        if total_score >= 10 or (has_many_agents and has_ai_focus and has_knowledge_work):
+            return ParadigmType.REVOLUTIONARY
+        if total_score >= 6 or (has_ai_focus and has_many_agents):
+            return ParadigmType.EVOLUTIONARY
+        return ParadigmType.INCREMENTAL
+
+    def save_analysis(self, analysis: RepoAnalysis, output_path: str) -> None:
+        """Save analysis results to JSON file"""
+        output_file = Path(output_path)
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Convert to dict for JSON serialization
+        analysis_dict = asdict(analysis)
+        analysis_dict["paradigm_type"] = analysis.paradigm_type.value
+
+        with open(output_file, "w", encoding="utf-8") as f:
+            json.dump(analysis_dict, f, indent=2, ensure_ascii=False)
+
+        print(f"Analysis saved to: {output_file}")
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) != 2:
+        print("Usage: python repo_analyzer.py <repo_path>")
+        sys.exit(1)
+
+    repo_path = sys.argv[1]
+    analyzer = RepositoryAnalyzer(repo_path)
+    analysis = analyzer.analyze_repository()
+
+    print("\nRepository Analysis Results:")
+    print(f"Project: {analysis.project_info.name}")
+    print(f"Description: {analysis.project_info.description}")
+    print(f"Paradigm Type: {analysis.paradigm_type.value}")
+    print(f"Complexity Score: {analysis.complexity_score}")
+    print(f"Agents Found: {len(analysis.agents)}")
+    print(f"Commands Found: {len(analysis.commands)}")
+    print(f"Workflows: {', '.join(analysis.workflows) if analysis.workflows else 'None'}")
+    print(f"Paradigm Indicators: {analysis.paradigm_indicators}")
+
+    # Save analysis
+    analyzer.save_analysis(analysis, f"{repo_path}_analysis.json")
diff --git a/website_generator/src/config_loader.py b/website_generator/src/config_loader.py
new file mode 100644
index 00000000..c8ca5a84
--- /dev/null
+++ b/website_generator/src/config_loader.py
@@ -0,0 +1,218 @@
+"""
+Configuration loader for website generator.
+Handles loading and merging YAML configuration files.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class SiteConfig:
+    """Complete site configuration"""
+
+    site: dict[str, Any]
+    content_strategy: dict[str, Any]
+    design_system: dict[str, Any]
+    pages: list
+    interactions: dict[str, Any]
+    navigation: dict[str, Any]
+    seo: dict[str, Any]
+    build: dict[str, Any]
+    responsive: dict[str, Any]
+
+
+class ConfigLoader:
+    """Loads and manages website generator configuration"""
+
+    def __init__(self, config_dir: str | None = None):
+        if config_dir is None:
+            self.config_dir = Path(__file__).parent.parent / "config"
+        else:
+            self.config_dir = Path(config_dir)
+
+        if not self.config_dir.exists():
+            raise ValueError(f"Configuration directory does not exist: {self.config_dir}")
+
+    def load_base_config(self) -> dict[str, Any]:
+        """Load base site template configuration"""
+        site_template_path = self.config_dir / "site_template.yaml"
+        content_patterns_path = self.config_dir / "content_patterns.yaml"
+
+        if not site_template_path.exists():
+            raise FileNotFoundError(f"Base site template not found: {site_template_path}")
+
+        # Load site template
+        with open(site_template_path, encoding="utf-8") as f:
+            site_config = yaml.safe_load(f)
+
+        # Load content patterns if available
+        if content_patterns_path.exists():
+            with open(content_patterns_path, encoding="utf-8") as f:
+                content_patterns = yaml.safe_load(f)
+                site_config["content_patterns"] = content_patterns
+
+        return site_config
+
+    def load_project_config(self, config_path: str) -> dict[str, Any]:
+        """Load project-specific configuration"""
+        config_file = Path(config_path)
+        if not config_file.exists():
+            raise FileNotFoundError(f"Project configuration not found: {config_path}")
+
+        with open(config_file, encoding="utf-8") as f:
+            return yaml.safe_load(f)
+
+    def merge_configs(self, base_config: dict[str, Any], project_config: dict[str, Any]) -> dict[str, Any]:
+        """Merge project configuration with base configuration"""
+
+        def deep_merge(base: dict, override: dict) -> dict:
+            result = base.copy()
+            for key, value in override.items():
+                if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                    result[key] = deep_merge(result[key], value)
+                else:
+                    result[key] = value
+            return result
+
+        return deep_merge(base_config, project_config)
+
+    def load_full_config(self, project_config_path: str | None = None) -> SiteConfig:
+        """Load complete configuration, merging base and project configs"""
+        # Load base configuration
+        base_config = self.load_base_config()
+
+        # Merge with project configuration if provided
+        if project_config_path:
+            project_config = self.load_project_config(project_config_path)
+            final_config = self.merge_configs(base_config, project_config)
+        else:
+            final_config = base_config
+
+        # Validate required sections
+        required_sections = ["site", "content_strategy", "design_system", "pages"]
+        for section in required_sections:
+            if section not in final_config:
+                raise ValueError(f"Required configuration section missing: {section}")
+
+        # Create SiteConfig object
+        return SiteConfig(
+            site=final_config.get("site", {}),
+            content_strategy=final_config.get("content_strategy", {}),
+            design_system=final_config.get("design_system", {}),
+            pages=final_config.get("pages", []),
+            interactions=final_config.get("interactions", {}),
+            navigation=final_config.get("navigation", {}),
+            seo=final_config.get("seo", {}),
+            build=final_config.get("build", {}),
+            responsive=final_config.get("responsive", {}),
+        )
+
+    def validate_config(self, config: SiteConfig) -> bool:
+        """Validate configuration for completeness and consistency"""
+        # Check required site information
+        if not config.site.get("name"):
+            raise ValueError("Site name is required")
+
+        if not config.site.get("description"):
+            raise ValueError("Site description is required")
+
+        # Check design system
+        if not config.design_system.get("colors"):
+            print("Warning: No color palette defined, using defaults")
+
+        # Check pages
+        if not config.pages:
+            raise ValueError("At least one page must be defined")
+
+        # Validate page structure
+        for page in config.pages:
+            if not page.get("name"):
+                raise ValueError("Page name is required")
+            if not page.get("sections"):
+                raise ValueError(f"Page {page.get('name')} must have sections")
+
+        return True
+
+    def get_content_patterns(self, config: SiteConfig) -> dict[str, Any]:
+        """Extract content generation patterns from configuration"""
+        # This will be used by the content generation engine
+        return {
+            "paradigm_detection": config.content_strategy.get("paradigm_shift_detection", True),
+            "progressive_disclosure": config.content_strategy.get("progressive_disclosure", True),
+            "trust_building": config.content_strategy.get("trust_building_focus", True),
+            "role_transformation": config.content_strategy.get("role_transformation_emphasis", True),
+        }
+
+    def export_config(self, config: SiteConfig, output_path: str) -> None:
+        """Export merged configuration to file"""
+        config_dict = {
+            "site": config.site,
+            "content_strategy": config.content_strategy,
+            "design_system": config.design_system,
+            "pages": config.pages,
+            "interactions": config.interactions,
+            "navigation": config.navigation,
+            "seo": config.seo,
+            "build": config.build,
+            "responsive": config.responsive,
+        }
+
+        output_file = Path(output_path)
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(output_file, "w", encoding="utf-8") as f:
+            yaml.dump(config_dict, f, default_flow_style=False, sort_keys=False, indent=2)
+
+        print(f"Configuration exported to: {output_file}")
+
+
+def test_config_loader():
+    """Test the configuration loader with Amplifier example"""
+    loader = ConfigLoader()
+
+    try:
+        # Test base config loading
+        print("Loading base configuration...")
+        base_config = loader.load_base_config()
+        print(f"✓ Base config loaded with {len(base_config)} sections")
+
+        # Test project config loading
+        project_config_path = Path(__file__).parent.parent / "examples" / "amplifier_config.yaml"
+        print(f"Loading project configuration from {project_config_path}...")
+
+        full_config = loader.load_full_config(str(project_config_path))
+        print(f"✓ Full config loaded for project: {full_config.site['name']}")
+
+        # Test validation
+        print("Validating configuration...")
+        if loader.validate_config(full_config):
+            print("✓ Configuration validation passed")
+
+        # Test content patterns extraction
+        content_patterns = loader.get_content_patterns(full_config)
+        print(f"✓ Content patterns extracted: {list(content_patterns.keys())}")
+
+        # Test export
+        export_path = "/tmp/test_config_export.yaml"
+        loader.export_config(full_config, export_path)
+
+        print("\n📊 Configuration Summary:")
+        print(f"  Site: {full_config.site['name']}")
+        print(f"  Theme: {full_config.site['theme']}")
+        print(f"  Pages: {len(full_config.pages)}")
+        print(f"  Color Palette: {full_config.design_system['color_palette']}")
+        print(f"  Animation Level: {full_config.design_system['animation_level']}")
+
+        return True
+
+    except Exception as e:
+        print(f"❌ Configuration test failed: {e}")
+        return False
+
+
+if __name__ == "__main__":
+    test_config_loader()
diff --git a/website_generator/src/content/content_generator.py b/website_generator/src/content/content_generator.py
new file mode 100644
index 00000000..a58767e0
--- /dev/null
+++ b/website_generator/src/content/content_generator.py
@@ -0,0 +1,736 @@
+"""
+Content generator for website creation.
+Generates content based on repository analysis and configuration.
+"""
+
+# Import our components
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+sys.path.append(str(Path(__file__).parent.parent))
+from analyzer.repo_analyzer import AgentInfo
+from analyzer.repo_analyzer import CommandInfo
+from analyzer.repo_analyzer import ParadigmType
+from analyzer.repo_analyzer import RepoAnalysis
+from config_loader import SiteConfig
+
+
+@dataclass
+class RevolutionContent:
+    """Content for revolutionary paradigm section"""
+
+    title: str
+    subtitle: str
+    problem_statement: str
+    paradigm_comparison: dict[str, Any]
+    multiplier_effect: dict[str, Any]
+    role_transformation: dict[str, Any]
+
+
+@dataclass
+class ProgressiveSetup:
+    """Progressive setup tier content"""
+
+    tiers: list[dict[str, Any]]
+
+
+@dataclass
+class AgentShowcase:
+    """Agent showcase content"""
+
+    featured_agents: list[dict[str, Any]]
+    agent_categories: dict[str, list[dict[str, Any]]]
+    total_count: int
+
+
+@dataclass
+class GeneratedContent:
+    """Complete generated content for a website"""
+
+    revolution_section: RevolutionContent | None
+    progressive_setup: ProgressiveSetup
+    agent_showcase: AgentShowcase
+    hero_section: dict[str, Any]
+    overview_section: dict[str, Any]
+    examples_section: dict[str, Any]
+
+
+class ContentGenerator:
+    """Generates website content based on repository analysis"""
+
+    def __init__(self, config: SiteConfig):
+        self.config = config
+
+    def generate_content(self, analysis: RepoAnalysis) -> GeneratedContent:
+        """Generate complete website content"""
+        print(f"Generating content for {analysis.paradigm_type.value} paradigm...")
+
+        # Generate revolution section (only for revolutionary paradigm)
+        revolution_section = None
+        if analysis.paradigm_type == ParadigmType.REVOLUTIONARY:
+            revolution_section = self._generate_revolution_section(analysis)
+
+        # Generate other sections
+        progressive_setup = self._generate_progressive_setup(analysis)
+        agent_showcase = self._generate_agent_showcase(analysis)
+        hero_section = self._generate_hero_section(analysis)
+        overview_section = self._generate_overview_section(analysis)
+        examples_section = self._generate_examples_section(analysis)
+
+        return GeneratedContent(
+            revolution_section=revolution_section,
+            progressive_setup=progressive_setup,
+            agent_showcase=agent_showcase,
+            hero_section=hero_section,
+            overview_section=overview_section,
+            examples_section=examples_section,
+        )
+
+    def _generate_revolution_section(self, analysis: RepoAnalysis) -> RevolutionContent:
+        """Generate revolutionary paradigm content"""
+        project_name = analysis.project_info.name.title()
+
+        # Generate problem statement
+        problem_statement = self._generate_problem_statement(analysis)
+
+        # Generate paradigm comparison
+        paradigm_comparison = self._generate_paradigm_comparison(analysis)
+
+        # Generate multiplier effect
+        multiplier_effect = self._generate_multiplier_effect(analysis)
+
+        # Generate role transformation
+        role_transformation = self._generate_role_transformation(analysis)
+
+        return RevolutionContent(
+            title="The Development Revolution",
+            subtitle=f"Why {project_name} Changes Everything",
+            problem_statement=problem_statement,
+            paradigm_comparison=paradigm_comparison,
+            multiplier_effect=multiplier_effect,
+            role_transformation=role_transformation,
+        )
+
+    def _generate_problem_statement(self, analysis: RepoAnalysis) -> str:
+        """Generate problem statement for revolutionary tools"""
+        agent_count = len(analysis.agents)
+
+        if agent_count >= 20:
+            scale_desc = "massive complexity"
+            solution_desc = "specialized AI agents"
+        elif agent_count >= 10:
+            scale_desc = "growing complexity"
+            solution_desc = "intelligent automation"
+        else:
+            scale_desc = "increasing demands"
+            solution_desc = "AI-powered assistance"
+
+        return f"""Traditional development approaches struggle with {scale_desc} of modern software projects.
+        Developers spend countless hours on repetitive tasks, debugging obscure issues, and managing intricate architectures.
+        {analysis.project_info.name.title()} revolutionizes this process through {solution_desc}, transforming
+        how we approach software development entirely."""
+
+    def _generate_paradigm_comparison(self, analysis: RepoAnalysis) -> dict[str, Any]:
+        """Generate before/after paradigm comparison"""
+        agent_count = len(analysis.agents)
+
+        comparison = {
+            "categories": [
+                {
+                    "name": "Development Speed",
+                    "before": "Hours per feature",
+                    "after": "Minutes per feature",
+                    "improvement": "10-50x faster",
+                },
+                {
+                    "name": "Code Quality",
+                    "before": "Manual reviews",
+                    "after": "AI-powered analysis",
+                    "improvement": "Consistent excellence",
+                },
+                {
+                    "name": "Architecture",
+                    "before": "Ad-hoc decisions",
+                    "after": "Specialized expertise",
+                    "improvement": "Professional patterns",
+                },
+                {
+                    "name": "Debugging",
+                    "before": "Manual investigation",
+                    "after": "Systematic analysis",
+                    "improvement": "Root cause focus",
+                },
+            ]
+        }
+
+        if agent_count >= 20:
+            comparison["categories"].append(
+                {
+                    "name": "Specialization",
+                    "before": "Generalist approach",
+                    "after": f"{agent_count}+ expert agents",
+                    "improvement": "Domain expertise",
+                }
+            )
+
+        return comparison
+
+    def _generate_multiplier_effect(self, analysis: RepoAnalysis) -> dict[str, Any]:
+        """Generate capability multiplication metrics"""
+        agent_count = len(analysis.agents)
+        complexity = analysis.complexity_score
+
+        # Calculate multipliers based on project characteristics
+        if agent_count >= 20 and complexity >= 80:
+            # High complexity, many agents (like Amplifier)
+            ideas_multiplier = 25  # 50 → 1250
+            time_reduction = 12  # 12 hours → 1 hour
+        elif agent_count >= 10:
+            ideas_multiplier = 10  # 50 → 500
+            time_reduction = 6  # 6 hours → 1 hour
+        else:
+            ideas_multiplier = 5  # 50 → 250
+            time_reduction = 3  # 3 hours → 1 hour
+
+        return {
+            "metrics": [
+                {
+                    "name": "Ideas Generated",
+                    "old_value": 50,
+                    "new_value": 50 * ideas_multiplier,
+                    "unit": "per month",
+                    "multiplier": ideas_multiplier,
+                },
+                {
+                    "name": "Implementation Time",
+                    "old_value": time_reduction,
+                    "new_value": 1,
+                    "unit": "hours",
+                    "multiplier": time_reduction,
+                    "inverse": True,
+                },
+                {"name": "Code Quality", "old_value": 70, "new_value": 95, "unit": "% excellent", "multiplier": 1.36},
+            ]
+        }
+
+    def _generate_role_transformation(self, analysis: RepoAnalysis) -> dict[str, Any]:
+        """Generate role transformation narrative"""
+        agent_count = len(analysis.agents)
+
+        if agent_count >= 20:
+            # High-agent environments like Amplifier
+            return {
+                "transformation_type": "elevation",
+                "old_role": {
+                    "title": "Traditional Developer",
+                    "characteristics": [
+                        "Code line by line manually",
+                        "Debug through trial and error",
+                        "Work on single tasks sequentially",
+                        "Rely on personal knowledge only",
+                        "Spend hours on repetitive work",
+                    ],
+                },
+                "new_role": {
+                    "title": "AI-Amplified Architect",
+                    "characteristics": [
+                        "Design and orchestrate systems",
+                        "Deploy specialized expert agents",
+                        "Coordinate parallel development streams",
+                        "Access distributed expertise instantly",
+                        "Focus on creative problem-solving",
+                    ],
+                },
+                "transformation_message": "You don't become obsolete—you become orchestrator of an expert team.",
+            }
+        if agent_count >= 5:
+            return {
+                "transformation_type": "enhancement",
+                "old_role": {
+                    "title": "Solo Developer",
+                    "characteristics": [
+                        "Handle all aspects personally",
+                        "Limited by individual expertise",
+                        "Sequential task completion",
+                    ],
+                },
+                "new_role": {
+                    "title": "Augmented Developer",
+                    "characteristics": [
+                        "Leverage AI specialists for complex tasks",
+                        "Access expert knowledge on demand",
+                        "Parallel task execution",
+                    ],
+                },
+            }
+        return {
+            "transformation_type": "assistance",
+            "old_role": {
+                "title": "Manual Developer",
+                "characteristics": ["All work done manually", "Time-consuming processes"],
+            },
+            "new_role": {
+                "title": "AI-Assisted Developer",
+                "characteristics": ["AI handles routine tasks", "Accelerated development cycle"],
+            },
+        }
+
+    def _generate_progressive_setup(self, analysis: RepoAnalysis) -> ProgressiveSetup:
+        """Generate progressive setup tiers"""
+        project_name = analysis.project_info.name
+        agent_count = len(analysis.agents)
+
+        tiers = []
+
+        # Quick Taste (1 minute)
+        quick_taste = {
+            "name": "Quick Taste",
+            "duration": "1 minute",
+            "description": "Experience the power immediately",
+            "focus": f"Your first {project_name} agent",
+            "steps": [f"Install {project_name}", "Run your first agent command", "See immediate results"],
+        }
+
+        if agent_count >= 5:
+            quick_taste["demo_command"] = "Use zen-architect to design my authentication system"
+            quick_taste["expected_result"] = "Complete system architecture generated in seconds"
+        else:
+            quick_taste["demo_command"] = f"Run {project_name} --help"
+            quick_taste["expected_result"] = "See available capabilities"
+
+        tiers.append(quick_taste)
+
+        # Essential Setup (5 minutes)
+        essential = {
+            "name": "Essential Setup",
+            "duration": "5 minutes",
+            "description": "Core features and workflows",
+            "focus": f"Essential {project_name} workflow",
+            "steps": ["Configure core settings", "Learn key commands", "Complete first real task"],
+        }
+
+        if agent_count >= 10:
+            essential["workflow"] = "Multi-agent workflow with 3-5 essential agents"
+        else:
+            essential["workflow"] = "Core feature demonstration"
+
+        tiers.append(essential)
+
+        # Power User (15+ minutes) - only for complex systems
+        if analysis.complexity_score >= 50 or agent_count >= 5:
+            power_user = {
+                "name": "Power User",
+                "duration": "15+ minutes",
+                "description": "Full ecosystem mastery",
+                "focus": f"Complete {project_name} mastery",
+                "steps": ["Advanced configuration", "Custom integrations", "Expert workflows"],
+            }
+
+            if agent_count >= 20:
+                power_user["mastery_features"] = [
+                    f"All {agent_count}+ specialized agents",
+                    "Parallel workflow orchestration",
+                    "Custom agent creation",
+                    "Advanced automation patterns",
+                ]
+            elif agent_count >= 10:
+                power_user["mastery_features"] = [
+                    "Advanced agent combinations",
+                    "Complex workflow patterns",
+                    "Integration customization",
+                ]
+            else:
+                power_user["mastery_features"] = ["Advanced features", "Customization options", "Expert patterns"]
+
+            tiers.append(power_user)
+
+        return ProgressiveSetup(tiers=tiers)
+
+    def _generate_agent_showcase(self, analysis: RepoAnalysis) -> AgentShowcase:
+        """Generate agent showcase content"""
+        agents = analysis.agents
+        total_count = len(agents)
+
+        # Select featured agents (first 6 or most important)
+        featured_agents = []
+        for agent in agents[:6]:
+            featured_agents.append(self._create_rich_agent_content(agent))
+
+        # Categorize all agents with rich content
+        categories = {
+            "Architecture": [],
+            "Development": [],
+            "Quality": [],
+            "Analysis": [],
+            "Automation": [],
+            "Other": [],
+        }
+
+        for agent in agents:
+            category = self._categorize_agent(agent.name)
+            rich_agent = self._create_rich_agent_content(agent)
+            categories[category].append(rich_agent)
+
+        # Remove empty categories
+        categories = {k: v for k, v in categories.items() if v}
+
+        return AgentShowcase(featured_agents=featured_agents, agent_categories=categories, total_count=total_count)
+
+    def _create_rich_agent_content(self, agent: AgentInfo) -> dict[str, Any]:
+        """Create rich, detailed content for an agent like the instructor site"""
+        agent_name = agent.name
+        category = self._categorize_agent(agent_name)
+
+        # Generate detailed description based on agent name and existing description
+        detailed_description = self._generate_detailed_agent_description(agent)
+
+        # Generate example usage and output
+        example_usage = self._generate_agent_usage_example(agent)
+        example_output = self._generate_agent_output_example(agent)
+
+        # Generate key capabilities
+        key_capabilities = self._generate_agent_key_capabilities(agent)
+
+        # Generate use cases
+        use_cases = self._generate_agent_use_cases(agent)
+
+        return {
+            "name": agent_name,
+            "category": category,
+            "description": detailed_description,
+            "capabilities": key_capabilities,
+            "capabilities_count": len(agent.capabilities),
+            "example_usage": example_usage,
+            "example_output": example_output,
+            "use_cases": use_cases,
+            "file_path": agent.file_path,
+        }
+
+    def _generate_detailed_agent_description(self, agent: AgentInfo) -> str:
+        """Generate detailed agent description based on name and role"""
+        name = agent.name
+        existing_desc = agent.description
+
+        # Agent-specific detailed descriptions
+        if name == "zen-architect":
+            return """The master architect who embodies ruthless simplicity and Wabi-sabi philosophy. Operates in three powerful modes:
+            ANALYZE for problem decomposition, ARCHITECT for system design, and REVIEW for code quality assessment.
+            Creates clear specifications that guide implementation, focusing on essential patterns over unnecessary abstractions."""
+
+        if name == "bug-hunter":
+            return """Specialized debugging expert focused on systematically finding and fixing bugs. Uses hypothesis-driven debugging
+            to efficiently locate root causes and implement minimal fixes. Follows a methodical approach that prevents future issues
+            while maintaining code simplicity and reliability."""
+
+        if name == "security-guardian":
+            return """Comprehensive security analysis expert that performs vulnerability assessments and security audits.
+            Checks for common vulnerabilities (OWASP Top 10), detects hardcoded secrets, validates input/output security,
+            and ensures data protection measures are in place before production deployments."""
+
+        if name == "test-coverage":
+            return """Expert at analyzing test coverage and identifying gaps to suggest comprehensive test cases.
+            Ensures thorough testing without over-testing, following the testing pyramid principle.
+            Identifies edge cases and creates strategic test suites that maximize quality assurance."""
+
+        if name == "performance-optimizer":
+            return """Analyzes and improves code and system performance through data-driven optimization.
+            Profiles applications to identify bottlenecks, optimizes algorithms, improves database queries,
+            and addresses performance concerns with a measure-first approach."""
+
+        if name == "modular-builder":
+            return """Primary implementation agent that builds code from zen-architect specifications.
+            Creates self-contained, regeneratable modules following the 'bricks and studs' philosophy.
+            Transforms architectural designs into working code with proper separation of concerns."""
+
+        if "analysis" in name or "synthesis" in name:
+            return f"""Advanced analysis agent specialized in {name.replace("-", " ").replace("_", " ")}.
+            Processes complex information to extract insights and patterns. Uses multi-mode analysis
+            to provide deep understanding and actionable recommendations for development decisions."""
+
+        # Fallback to enhanced version of existing description
+        if existing_desc and len(existing_desc) > 50:
+            return existing_desc
+        return f"""Specialized agent focused on {name.replace("-", " ").replace("_", " ")} tasks.
+                Provides expert-level capabilities and follows best practices to ensure high-quality outcomes.
+                Integrates seamlessly with other agents in the development ecosystem."""
+
+    def _generate_agent_usage_example(self, agent: AgentInfo) -> str:
+        """Generate usage example for an agent"""
+        name = agent.name
+
+        examples = {
+            "zen-architect": "Use zen-architect to design a user notification system",
+            "bug-hunter": "Use bug-hunter to investigate why the authentication system is throwing intermittent errors",
+            "security-guardian": "Use security-guardian to review this API endpoint before production deployment",
+            "test-coverage": "Use test-coverage to analyze gaps in our payment processing test suite",
+            "performance-optimizer": "Use performance-optimizer to speed up our database queries in the user dashboard",
+            "modular-builder": "Use modular-builder to implement the notification system from zen-architect's specification",
+            "integration-specialist": "Use integration-specialist to connect our system with the new payment API",
+            "content-researcher": "Use content-researcher to find relevant patterns for implementing OAuth authentication",
+        }
+
+        return examples.get(name, f"Use {name} to handle {name.replace('-', ' ')} tasks efficiently")
+
+    def _generate_agent_output_example(self, agent: AgentInfo) -> str:
+        """Generate example output for an agent"""
+        name = agent.name
+
+        outputs = {
+            "zen-architect": "→ Returns: Problem analysis, 3 solution approaches with trade-offs, modular specification",
+            "bug-hunter": "→ Returns: Root cause analysis, step-by-step debugging plan, fix implementation with tests",
+            "security-guardian": "→ Returns: Security assessment report, vulnerability findings, remediation recommendations",
+            "test-coverage": "→ Returns: Coverage analysis, identified gaps, comprehensive test case suggestions",
+            "performance-optimizer": "→ Returns: Performance bottleneck analysis, optimization recommendations, implementation plan",
+            "modular-builder": "→ Returns: Working implementation with tests, documentation, and integration instructions",
+        }
+
+        return outputs.get(name, f"→ Returns: Comprehensive {name.replace('-', ' ')} analysis and recommendations")
+
+    def _generate_agent_key_capabilities(self, agent: AgentInfo) -> list[str]:
+        """Generate key capabilities for an agent"""
+        name = agent.name
+
+        # Use existing capabilities if available and detailed
+        if agent.capabilities and len(agent.capabilities) >= 3:
+            return agent.capabilities[:6]  # Top 6 capabilities
+
+        # Generate capabilities based on agent type
+        capabilities_map = {
+            "zen-architect": [
+                "Analysis-first development approach",
+                "Modular 'bricks & studs' architecture",
+                "Clean contract specifications",
+                "Complexity elimination strategies",
+                "80/20 principle application",
+                "Philosophy compliance review",
+            ],
+            "bug-hunter": [
+                "Hypothesis-driven debugging methodology",
+                "Root cause analysis techniques",
+                "Systematic error reproduction",
+                "Minimal fix implementation",
+                "Prevention strategy development",
+                "Code quality improvement",
+            ],
+            "security-guardian": [
+                "OWASP Top 10 vulnerability scanning",
+                "Hardcoded secrets detection",
+                "Input/output validation checks",
+                "Authentication system review",
+                "Data protection compliance",
+                "Production security audits",
+            ],
+            "test-coverage": [
+                "Coverage gap identification",
+                "Test strategy development",
+                "Edge case discovery",
+                "Testing pyramid optimization",
+                "Quality assurance planning",
+                "Test maintenance guidelines",
+            ],
+        }
+
+        return capabilities_map.get(
+            name,
+            [
+                f"Expert {name.replace('-', ' ')} analysis",
+                "Best practice implementation",
+                "Quality assurance focus",
+                "Integration with development workflow",
+                "Comprehensive documentation",
+                "Scalable solution design",
+            ],
+        )
+
+    def _generate_agent_use_cases(self, agent: AgentInfo) -> list[str]:
+        """Generate use cases for an agent"""
+        name = agent.name
+
+        use_cases_map = {
+            "zen-architect": [
+                "Designing new feature architectures",
+                "Refactoring complex legacy systems",
+                "Creating modular component specifications",
+                "Establishing coding standards and patterns",
+            ],
+            "bug-hunter": [
+                "Investigating production issues",
+                "Debugging intermittent failures",
+                "Analyzing test failures",
+                "Resolving performance problems",
+            ],
+            "security-guardian": [
+                "Pre-deployment security reviews",
+                "API security assessments",
+                "Authentication system audits",
+                "Data privacy compliance checks",
+            ],
+        }
+
+        return use_cases_map.get(
+            name,
+            [
+                f"Complex {name.replace('-', ' ')} challenges",
+                "Quality improvement initiatives",
+                "Best practice implementation",
+                "Team knowledge enhancement",
+            ],
+        )
+
+    def _categorize_agent(self, agent_name: str) -> str:
+        """Categorize agent based on name patterns"""
+        name_lower = agent_name.lower()
+
+        if any(keyword in name_lower for keyword in ["architect", "design", "modular", "builder"]):
+            return "Architecture"
+        if any(keyword in name_lower for keyword in ["bug", "debug", "test", "security", "performance"]):
+            return "Quality"
+        if any(keyword in name_lower for keyword in ["analysis", "synthesis", "extract", "insight"]):
+            return "Analysis"
+        if any(keyword in name_lower for keyword in ["automation", "cleanup", "integration"]):
+            return "Automation"
+        if any(keyword in name_lower for keyword in ["contract", "api", "database"]):
+            return "Development"
+        return "Other"
+
+    def _generate_hero_section(self, analysis: RepoAnalysis) -> dict[str, Any]:
+        """Generate hero section content"""
+        project_name = analysis.project_info.name.title()
+        description = analysis.project_info.description or f"Supercharge your development with {project_name}"
+
+        return {
+            "title": project_name,
+            "tagline": self.config.site.get("tagline", "Next-Generation Development Tool"),
+            "description": description,
+            "cta_primary": "Get Started",
+            "cta_secondary": "View Examples",
+            "features_preview": [
+                f"{len(analysis.agents)} Specialized Agents",
+                f"Complexity Score: {analysis.complexity_score}",
+                f"{analysis.paradigm_type.value.title()} Impact",
+            ],
+        }
+
+    def _generate_overview_section(self, analysis: RepoAnalysis) -> dict[str, Any]:
+        """Generate overview section content"""
+        return {
+            "title": "Overview",
+            "description": f"Understand how {analysis.project_info.name} transforms your development workflow",
+            "key_points": [
+                {
+                    "title": "Specialized Agents",
+                    "description": f"{len(analysis.agents)} expert agents handle different aspects of development",
+                    "icon": "agents",
+                },
+                {
+                    "title": "Parallel Processing",
+                    "description": "Execute multiple development tasks simultaneously",
+                    "icon": "parallel",
+                },
+                {
+                    "title": "Quality Assurance",
+                    "description": "Built-in quality checks and best practices enforcement",
+                    "icon": "quality",
+                },
+            ],
+        }
+
+    def _generate_examples_section(self, analysis: RepoAnalysis) -> dict[str, Any]:
+        """Generate examples section content"""
+        # Extract example commands from the analysis
+        example_commands = []
+        for cmd in analysis.commands[:5]:  # Top 5 commands
+            if cmd.usage:
+                example_commands.append({"name": cmd.name, "command": cmd.usage, "description": cmd.description})
+
+        return {
+            "title": "Examples",
+            "description": "Real workflows and commands you can use immediately",
+            "examples": example_commands,
+            "workflows": [
+                {
+                    "name": "Full Development Cycle",
+                    "steps": [
+                        "Design with zen-architect",
+                        "Build with modular-builder",
+                        "Test with test-coverage",
+                        "Review with security-guardian",
+                    ],
+                }
+            ],
+        }
+
+
+def test_content_generation():
+    """Test content generation with Amplifier analysis"""
+    # This would normally load from the actual analysis
+    # For testing, we'll create a mock analysis
+    from analyzer.repo_analyzer import AgentInfo
+    from analyzer.repo_analyzer import ParadigmType
+    from analyzer.repo_analyzer import ProjectInfo
+    from analyzer.repo_analyzer import RepoAnalysis
+
+    # Mock analysis for testing
+    project_info = ProjectInfo(
+        name="amplifier",
+        description="A complete development environment that supercharges AI coding assistants",
+        language="Python",
+    )
+
+    mock_agents = [
+        AgentInfo(
+            "zen-architect",
+            "Designs systems with ruthless simplicity",
+            ["architecture", "design"],
+            ".claude/agents/zen-architect.md",
+        ),
+        AgentInfo(
+            "bug-hunter", "Systematic debugging expert", ["debugging", "analysis"], ".claude/agents/bug-hunter.md"
+        ),
+        AgentInfo(
+            "security-guardian",
+            "Security analysis and best practices",
+            ["security", "audit"],
+            ".claude/agents/security-guardian.md",
+        ),
+    ]
+
+    mock_commands = [
+        CommandInfo("zen-architect", "Design system architecture", "make design", ".claude/commands/design.md"),
+        CommandInfo("test-suite", "Run comprehensive tests", "make test", "Makefile"),
+    ]
+
+    mock_analysis = RepoAnalysis(
+        project_info=project_info,
+        paradigm_type=ParadigmType.REVOLUTIONARY,
+        agents=mock_agents,
+        commands=mock_commands,
+        workflows=[],
+        complexity_score=100,
+        paradigm_indicators={"ai_amplification": 3, "specialized_agents": 3},
+    )
+
+    # Load config
+    from config_loader import ConfigLoader
+
+    loader = ConfigLoader()
+    config = loader.load_full_config()
+
+    # Generate content
+    generator = ContentGenerator(config)
+    content = generator.generate_content(mock_analysis)
+
+    print("🎯 Content Generation Test Results:")
+    print(f"Revolution Section: {content.revolution_section.title if content.revolution_section else 'None'}")
+    print(f"Setup Tiers: {len(content.progressive_setup.tiers)}")
+    print(f"Featured Agents: {len(content.agent_showcase.featured_agents)}")
+    print(f"Agent Categories: {list(content.agent_showcase.agent_categories.keys())}")
+    print(f"Hero Title: {content.hero_section['title']}")
+
+    return True
+
+
+if __name__ == "__main__":
+    test_content_generation()
diff --git a/website_generator/src/content/template_engine.py b/website_generator/src/content/template_engine.py
new file mode 100644
index 00000000..e40c28ac
--- /dev/null
+++ b/website_generator/src/content/template_engine.py
@@ -0,0 +1,809 @@
+"""
+Template engine for converting generated content into HTML.
+Uses Jinja2 for template processing with custom filters and functions.
+"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+try:
+    from jinja2 import Environment
+    from jinja2 import FileSystemLoader
+    from jinja2 import select_autoescape
+except ImportError:
+    print("Installing Jinja2...")
+    import subprocess
+
+    subprocess.run(["pip", "install", "jinja2"], check=True)
+    from jinja2 import Environment
+    from jinja2 import FileSystemLoader
+    from jinja2 import select_autoescape
+
+# Import our components
+import sys
+
+sys.path.append(str(Path(__file__).parent.parent))
+from config_loader import SiteConfig
+from content.content_generator import GeneratedContent
+
+
+class TemplateEngine:
+    """Converts generated content into HTML using Jinja2 templates"""
+
+    def __init__(self, config: SiteConfig, templates_dir: str | None = None, css_filename: str = "styles.css"):
+        self.config = config
+        self.css_filename = css_filename
+
+        if templates_dir is None:
+            self.templates_dir = Path(__file__).parent.parent.parent / "templates"
+        else:
+            self.templates_dir = Path(templates_dir)
+
+        # Initialize Jinja2 environment
+        self.env = Environment(
+            loader=FileSystemLoader(str(self.templates_dir)),
+            autoescape=select_autoescape(["html", "xml"]),
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+
+        # Add custom filters and functions
+        self._setup_template_functions()
+
+    def _setup_template_functions(self):
+        """Add custom Jinja2 filters and functions"""
+
+        # Custom filters
+        self.env.filters["format_number"] = self._format_number
+        self.env.filters["truncate_words"] = self._truncate_words
+        self.env.filters["slug"] = self._slugify
+        self.env.filters["agent_badge"] = self._agent_badge
+
+        # Global functions
+        self.env.globals["now"] = datetime.now
+        self.env.globals["config"] = self.config
+        self.env.globals["get_color"] = self._get_color
+        self.env.globals["get_icon"] = self._get_icon
+
+    def _format_number(self, value: int) -> str:
+        """Format numbers with commas"""
+        if isinstance(value, int | float):
+            return f"{value:,}"
+        return str(value)
+
+    def _truncate_words(self, text: str, words: int = 20) -> str:
+        """Truncate text to specified number of words"""
+        if not text:
+            return ""
+        word_list = text.split()
+        if len(word_list) <= words:
+            return text
+        return " ".join(word_list[:words]) + "..."
+
+    def _slugify(self, text: str) -> str:
+        """Convert text to URL-friendly slug"""
+        import re
+
+        slug = re.sub(r"[^\w\s-]", "", text.lower())
+        slug = re.sub(r"[-\s]+", "-", slug)
+        return slug.strip("-")
+
+    def _agent_badge(self, agent_name: str) -> str:
+        """Get CSS class for agent badge based on category"""
+        name_lower = agent_name.lower()
+
+        if any(keyword in name_lower for keyword in ["architect", "design", "modular"]):
+            return "badge-architecture"
+        if any(keyword in name_lower for keyword in ["bug", "debug", "test", "security"]):
+            return "badge-quality"
+        if any(keyword in name_lower for keyword in ["analysis", "synthesis", "extract"]):
+            return "badge-analysis"
+        if any(keyword in name_lower for keyword in ["automation", "cleanup"]):
+            return "badge-automation"
+        return "badge-development"
+
+    def _get_color(self, color_name: str) -> str:
+        """Get color value from design system"""
+        colors = self.config.design_system.get("colors", {})
+        return colors.get(color_name, "#2563eb")  # Default blue
+
+    def _get_icon(self, icon_name: str) -> str:
+        """Get icon class/SVG for given icon name"""
+        # Simple icon mapping - could be enhanced with actual icon library
+        icon_map = {
+            "agents": "🤖",
+            "parallel": "⚡",
+            "quality": "✅",
+            "architecture": "🏗️",
+            "security": "🔒",
+            "testing": "🧪",
+            "analysis": "📊",
+            "automation": "⚙️",
+            "development": "💻",
+        }
+        return icon_map.get(icon_name, "📄")
+
+    def render_page(self, page_name: str, content: GeneratedContent, **kwargs) -> str:
+        """Render a complete page"""
+        template_name = f"{page_name}.html"
+
+        try:
+            template = self.env.get_template(template_name)
+        except Exception:
+            # Fall back to base template
+            template = self.env.get_template("base_template.html")
+
+        # Prepare template context
+        context = {
+            "content": content,
+            "page_name": page_name,
+            "css_filename": self.css_filename,
+            "site": self.config.site,
+            "design_system": self.config.design_system,
+            "interactions": self.config.interactions,
+            "navigation": self.config.navigation,
+            "seo": self.config.seo,
+            **kwargs,
+        }
+
+        return template.render(**context)
+
+    def render_section(self, section_name: str, section_content: Any, **kwargs) -> str:
+        """Render an individual section"""
+        template_name = f"sections/{section_name}.html"
+
+        try:
+            template = self.env.get_template(template_name)
+        except Exception as e:
+            print(f"Warning: Section template {template_name} not found: {e}")
+            return self._render_fallback_section(section_name, section_content)
+
+        context = {
+            "section": section_content,
+            "config": self.config,
+            "site": self.config.site,
+            "design_system": self.config.design_system,
+            "interactions": self.config.interactions,
+            "navigation": self.config.navigation,
+            **kwargs,
+        }
+
+        return template.render(**context)
+
+    def _render_fallback_section(self, section_name: str, content: Any) -> str:
+        """Render fallback HTML for section when template is missing"""
+        if isinstance(content, dict) and "title" in content:
+            return f"""
+            <section class="section {section_name}-section">
+                <div class="container">
+                    <h2 class="section-title">{content["title"]}</h2>
+                    <p>Content for {section_name} section would go here.</p>
+                </div>
+            </section>
+            """
+        return f'<div class="section-placeholder">Section: {section_name}</div>'
+
+    def generate_full_page(self, page_config: dict[str, Any], content: GeneratedContent) -> str:
+        """Generate a complete HTML page with all sections"""
+        page_name = page_config["name"]
+        page_title = page_config.get("title", page_name.title())
+        sections = page_config.get("sections", [])
+
+        # Render all sections
+        rendered_sections = []
+        for section_name in sections:
+            section_content = self._get_section_content(section_name, content)
+            if section_content:
+                rendered_section = self.render_section(section_name, section_content)
+                rendered_sections.append(rendered_section)
+
+        # Create page context
+        page_context = {
+            "page_title": page_title,
+            "current_page": page_name,  # Renamed to avoid collision
+            "sections_html": "\n".join(rendered_sections),
+            "meta_description": self._generate_meta_description(content),
+        }
+
+        # Render complete page
+        return self.render_page("index", content, **page_context)
+
+    def _get_section_content(self, section_name: str, content: GeneratedContent) -> Any | None:
+        """Get content for a specific section"""
+        section_map = {
+            "revolution": content.revolution_section,
+            "hero": content.hero_section,
+            "overview": content.overview_section,
+            "features": content.overview_section,
+            "agent_showcase": content.agent_showcase,
+            "agents": content.agent_showcase,
+            "agent_gallery": content.agent_showcase,
+            "agent_categories": content.agent_showcase,
+            "workflow_examples": content.agent_showcase,
+            "custom_agents": content.agent_showcase,
+            "progressive_setup": content.progressive_setup,
+            "progressive_tiers": content.progressive_setup,
+            "quick_setup": content.progressive_setup,
+            "installation": content.progressive_setup,
+            "first_agent": content.progressive_setup,
+            "troubleshooting": content.progressive_setup,
+            "examples": content.examples_section,
+            "cta": {"title": "Get Started", "description": "Ready to transform your development?"},
+        }
+
+        return section_map.get(section_name)
+
+    def _generate_meta_description(self, content: GeneratedContent) -> str:
+        """Generate meta description from content"""
+        if content.hero_section:
+            return content.hero_section.get("description", "")
+        if content.revolution_section:
+            return content.revolution_section.problem_statement[:160] + "..."
+        return f"{self.config.site['name']} - {self.config.site.get('tagline', '')}"
+
+    def create_base_templates(self):
+        """Create basic HTML templates if they don't exist"""
+        self.templates_dir.mkdir(parents=True, exist_ok=True)
+        sections_dir = self.templates_dir / "sections"
+        sections_dir.mkdir(exist_ok=True)
+
+        # Base template
+        base_template = self.templates_dir / "base_template.html"
+        if not base_template.exists():
+            base_html = self._get_base_template_html()
+            with open(base_template, "w", encoding="utf-8") as f:
+                f.write(base_html)
+
+        # Page templates - create for all configured pages
+        page_template_html = self._get_index_template_html()
+        for page_config in self.config.pages:
+            page_name = page_config["name"]
+            page_template = self.templates_dir / f"{page_name}.html"
+            if not page_template.exists():
+                with open(page_template, "w", encoding="utf-8") as f:
+                    f.write(page_template_html)
+
+        # Section templates
+        section_templates = {
+            "revolution.html": self._get_revolution_section_html(),
+            "hero.html": self._get_hero_section_html(),
+            "agent_showcase.html": self._get_agent_showcase_html(),
+            "agents.html": self._get_agent_showcase_html(),  # Alias
+            "agent_gallery.html": self._get_agent_showcase_html(),  # Agents page sections
+            "agent_categories.html": self._get_agent_showcase_html(),
+            "workflow_examples.html": self._get_agent_showcase_html(),
+            "custom_agents.html": self._get_agent_showcase_html(),
+            "progressive_setup.html": self._get_progressive_setup_html(),
+            "setup.html": self._get_progressive_setup_html(),  # Alias
+            "progressive_tiers.html": self._get_progressive_setup_html(),  # Setup page sections
+            "installation.html": self._get_progressive_setup_html(),
+            "first_agent.html": self._get_progressive_setup_html(),
+            "troubleshooting.html": self._get_progressive_setup_html(),
+            "overview.html": self._get_overview_section_html(),  # Missing sections
+            "quick_setup.html": self._get_progressive_setup_html(),
+            "examples.html": self._get_examples_section_html(),
+            "cta.html": self._get_cta_section_html(),
+        }
+
+        for template_name, template_html in section_templates.items():
+            template_file = sections_dir / template_name
+            if not template_file.exists():
+                with open(template_file, "w", encoding="utf-8") as f:
+                    f.write(template_html)
+
+        print(f"✓ Created base templates in {self.templates_dir}")
+
+    def _get_base_template_html(self) -> str:
+        """Get base HTML template"""
+        return """<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{ page_title }} - {{ site.name }}</title>
+    <meta name="description" content="{{ meta_description }}">
+
+    <!-- SEO -->
+    <meta property="og:title" content="{{ page_title }} - {{ site.name }}">
+    <meta property="og:description" content="{{ meta_description }}">
+    <meta property="og:type" content="website">
+
+    <!-- Styles -->
+    <link rel="stylesheet" href="{{ css_filename }}">
+
+    <!-- Custom colors from design system -->
+    <style>
+        :root {
+            --primary-color: {{ get_color('primary') }};
+            --secondary-color: {{ get_color('secondary') }};
+            --accent-color: {{ get_color('accent') }};
+            --background-color: {{ get_color('background') }};
+            --text-primary: {{ get_color('text_primary') }};
+            --text-secondary: {{ get_color('text_secondary') }};
+        }
+    </style>
+</head>
+<body>
+    <!-- Navigation -->
+    <header class="header">
+        <nav class="nav">
+            <div class="nav-brand">
+                <h1>{{ site.name }}</h1>
+            </div>
+            <ul class="nav-links">
+                <li><a href="#hero">Home</a></li>
+                {% if content.agent_showcase %}
+                <li><a href="#agents">Agents</a></li>
+                {% endif %}
+                <li><a href="#examples">Examples</a></li>
+                <li><a href="#setup">Setup</a></li>
+            </ul>
+        </nav>
+    </header>
+
+    <!-- Main Content -->
+    <main>
+        {{ sections_html | safe }}
+    </main>
+
+    <!-- Footer -->
+    <footer class="footer">
+        <div class="container">
+            <p>&copy; {{ now().year }} {{ site.name }}. Built with Website Generator.</p>
+        </div>
+    </footer>
+
+    <!-- JavaScript -->
+    <script src="script.js"></script>
+</body>
+</html>"""
+
+    def _get_index_template_html(self) -> str:
+        """Get index page template (extends base)"""
+        return """{% extends "base_template.html" %}
+
+{% block content %}
+{{ sections_html | safe }}
+{% endblock %}"""
+
+    def _get_revolution_section_html(self) -> str:
+        """Get revolution section template"""
+        return """<section class="revolution-section" id="revolution">
+    <div class="container">
+        <div class="revolution-content">
+            <h2 class="revolution-title">{{ section.title }}</h2>
+            <h3 class="revolution-subtitle">{{ section.subtitle }}</h3>
+
+            <div class="problem-statement">
+                <p>{{ section.problem_statement }}</p>
+            </div>
+
+            {% if section.multiplier_effect %}
+            <div class="multiplier-showcase">
+                <h4>Capability Multiplication</h4>
+                <div class="metrics-grid">
+                    {% for metric in section.multiplier_effect.metrics %}
+                    <div class="metric-card">
+                        <div class="metric-name">{{ metric.name }}</div>
+                        <div class="metric-comparison">
+                            <span class="old-value">{{ metric.old_value | format_number }}</span>
+                            <span class="arrow">→</span>
+                            <span class="new-value"
+                                  {% if interactions.animated_counters %}
+                                  data-counter="{{ metric.new_value }}"
+                                  {% endif %}>
+                                {{ metric.new_value | format_number }}
+                            </span>
+                        </div>
+                        <div class="metric-unit">{{ metric.unit }}</div>
+                        <div class="metric-multiplier">{{ metric.multiplier }}x {% if metric.inverse %}faster{% else %}more{% endif %}</div>
+                    </div>
+                    {% endfor %}
+                </div>
+            </div>
+            {% endif %}
+
+            {% if section.paradigm_comparison %}
+            <div class="paradigm-comparison">
+                <h4>The Paradigm Shift</h4>
+                <div class="comparison-grid">
+                    {% for category in section.paradigm_comparison.categories %}
+                    <div class="comparison-row">
+                        <div class="category-name">{{ category.name }}</div>
+                        <div class="before">{{ category.before }}</div>
+                        <div class="after">{{ category.after }}</div>
+                        <div class="improvement">{{ category.improvement }}</div>
+                    </div>
+                    {% endfor %}
+                </div>
+            </div>
+            {% endif %}
+
+            {% if section.role_transformation %}
+            <div class="role-transformation">
+                <h4>Your Role Evolution</h4>
+                <div class="transformation-grid">
+                    <div class="old-role">
+                        <h5>{{ section.role_transformation.old_role.title }}</h5>
+                        <ul>
+                            {% for char in section.role_transformation.old_role.characteristics %}
+                            <li>{{ char }}</li>
+                            {% endfor %}
+                        </ul>
+                    </div>
+                    <div class="transformation-arrow">→</div>
+                    <div class="new-role">
+                        <h5>{{ section.role_transformation.new_role.title }}</h5>
+                        <ul>
+                            {% for char in section.role_transformation.new_role.characteristics %}
+                            <li>{{ char }}</li>
+                            {% endfor %}
+                        </ul>
+                    </div>
+                </div>
+                {% if section.role_transformation.transformation_message %}
+                <p class="transformation-message">{{ section.role_transformation.transformation_message }}</p>
+                {% endif %}
+            </div>
+            {% endif %}
+        </div>
+    </div>
+</section>"""
+
+    def _get_hero_section_html(self) -> str:
+        """Get hero section template"""
+        return """<section class="hero-section" id="hero">
+    <div class="container">
+        <div class="hero-content">
+            <h1 class="hero-title">{{ section.title }}</h1>
+            <p class="hero-tagline">{{ section.tagline }}</p>
+            <p class="hero-description">{{ section.description }}</p>
+
+            {% if section.features_preview %}
+            <div class="features-preview">
+                {% for feature in section.features_preview %}
+                <span class="feature-badge">{{ feature }}</span>
+                {% endfor %}
+            </div>
+            {% endif %}
+
+            <div class="hero-actions">
+                <a href="#setup" class="btn btn-primary">{{ section.cta_primary }}</a>
+                <a href="#examples" class="btn btn-secondary">{{ section.cta_secondary }}</a>
+            </div>
+        </div>
+    </div>
+</section>"""
+
+    def _get_agent_showcase_html(self) -> str:
+        """Get agent showcase section template"""
+        return """<section class="agents-section" id="agents">
+    <div class="container">
+        <h2 class="section-title">
+            {% if section.total_count > 20 %}
+            {{ section.total_count }}+ Specialized Agents
+            {% else %}
+            Specialized Agents
+            {% endif %}
+        </h2>
+        <p class="section-description">Expert AI agents handle every aspect of development</p>
+
+        {% if section.agent_categories %}
+        <div class="agent-categories">
+            <div class="category-tabs">
+                {% for category, agents in section.agent_categories.items() %}
+                <button class="tab-btn {% if loop.first %}active{% endif %}"
+                        onclick="showTab('{{ category | slug }}', this)">
+                    {{ get_icon(category | lower) }} {{ category }} ({{ agents | length }})
+                </button>
+                {% endfor %}
+            </div>
+
+            {% for category, agents in section.agent_categories.items() %}
+            <div class="tab-content {% if loop.first %}active{% endif %}" id="{{ category | slug }}">
+                <div class="agents-list">
+                    {% for agent in agents %}
+                    <div class="agent-card rich-agent-card">
+                        <div class="agent-header">
+                            <div class="agent-name">{{ agent.name }}</div>
+                            <span class="agent-category {{ agent.name | agent_badge }}">{{ agent.category }}</span>
+                        </div>
+                        <div class="agent-body">
+                            <p class="agent-description">{{ agent.description }}</p>
+
+                            {% if agent.capabilities %}
+                            <div class="agent-features">
+                                <h4>Key Capabilities</h4>
+                                <ul>
+                                    {% for capability in agent.capabilities %}
+                                    <li>{{ capability }}</li>
+                                    {% endfor %}
+                                </ul>
+                            </div>
+                            {% endif %}
+
+                            {% if agent.use_cases %}
+                            <div class="agent-use-cases">
+                                <h4>Common Use Cases</h4>
+                                <ul>
+                                    {% for use_case in agent.use_cases %}
+                                    <li>{{ use_case }}</li>
+                                    {% endfor %}
+                                </ul>
+                            </div>
+                            {% endif %}
+
+                            {% if agent.example_usage %}
+                            <div class="agent-example">
+                                <h4>Example Usage</h4>
+                                <div class="example-command">
+                                    <pre>{{ agent.example_usage }}</pre>
+                                </div>
+                                {% if agent.example_output %}
+                                <p class="example-output">{{ agent.example_output }}</p>
+                                {% endif %}
+                            </div>
+                            {% endif %}
+
+                            <details class="advanced-section">
+                                <summary>Advanced Details & Examples</summary>
+                                <div class="examples-container">
+                                    <div class="example-card">
+                                        <h5>Integration Pattern</h5>
+                                        <p>This agent integrates seamlessly with other Amplifier agents and can be used in multi-agent workflows for complex development tasks.</p>
+                                    </div>
+                                    {% if agent.file_path %}
+                                    <div class="example-card">
+                                        <h5>Configuration</h5>
+                                        <p>Agent definition: <code>{{ agent.file_path }}</code></p>
+                                    </div>
+                                    {% endif %}
+                                </div>
+                            </details>
+                        </div>
+                    </div>
+                    {% endfor %}
+                </div>
+            </div>
+            {% endfor %}
+        </div>
+        {% endif %}
+    </div>
+</section>"""
+
+    def _get_progressive_setup_html(self) -> str:
+        """Get progressive setup section template"""
+        return """<section class="setup-section" id="setup">
+    <div class="container">
+        <h2 class="section-title">Progressive Setup</h2>
+        <p class="section-description">Choose your learning path based on available time</p>
+
+        <div class="setup-tiers">
+            {% for tier in section.tiers %}
+            <div class="tier-card" data-tier="{{ loop.index }}">
+                <div class="tier-header">
+                    <h3 class="tier-name">{{ tier.name }}</h3>
+                    <span class="tier-duration">{{ tier.duration }}</span>
+                </div>
+                <p class="tier-description">{{ tier.description }}</p>
+                <p class="tier-focus"><strong>Focus:</strong> {{ tier.focus }}</p>
+
+                {% if tier.steps %}
+                <ol class="tier-steps">
+                    {% for step in tier.steps %}
+                    <li>{{ step }}</li>
+                    {% endfor %}
+                </ol>
+                {% endif %}
+
+                {% if tier.demo_command %}
+                <div class="tier-demo">
+                    <strong>Try this:</strong>
+                    <code>{{ tier.demo_command }}</code>
+                    {% if tier.expected_result %}
+                    <p><em>Expected: {{ tier.expected_result }}</em></p>
+                    {% endif %}
+                </div>
+                {% endif %}
+
+                {% if tier.mastery_features %}
+                <div class="mastery-features">
+                    <strong>What you'll master:</strong>
+                    <ul>
+                        {% for feature in tier.mastery_features %}
+                        <li>{{ feature }}</li>
+                        {% endfor %}
+                    </ul>
+                </div>
+                {% endif %}
+
+                <button class="btn btn-outline tier-btn">Start {{ tier.name }}</button>
+            </div>
+            {% endfor %}
+        </div>
+    </div>
+</section>"""
+
+    def _get_overview_section_html(self) -> str:
+        """Get overview section template"""
+        return """<section class="overview-section" id="overview">
+    <div class="container">
+        <h2 class="section-title">System Overview</h2>
+        <p class="section-description">{{ section.description | default("Understanding how Amplifier transforms development") }}</p>
+
+        <div class="overview-grid">
+            <div class="overview-card">
+                <div class="overview-icon">🎯</div>
+                <h3>Smart Agents</h3>
+                <p>23+ specialized agents handle different aspects of development</p>
+            </div>
+            <div class="overview-card">
+                <div class="overview-icon">⚡</div>
+                <h3>Parallel Processing</h3>
+                <p>Run multiple workflows simultaneously for maximum efficiency</p>
+            </div>
+            <div class="overview-card">
+                <div class="overview-icon">🔗</div>
+                <h3>Modular Architecture</h3>
+                <p>Clean, maintainable components that work together seamlessly</p>
+            </div>
+        </div>
+    </div>
+</section>"""
+
+    def _get_examples_section_html(self) -> str:
+        """Get examples section template"""
+        return """<section class="examples-section" id="examples">
+    <div class="container">
+        <h2 class="section-title">Real-World Examples</h2>
+        <p class="section-description">See Amplifier in action with practical workflows</p>
+
+        <div class="examples-grid">
+            <div class="example-card">
+                <h4>Bug Investigation</h4>
+                <div class="example-command">
+                    <pre>Use bug-hunter to investigate database timeout errors</pre>
+                </div>
+                <p class="example-result">→ Complete root cause analysis with fix recommendations</p>
+            </div>
+
+            <div class="example-card">
+                <h4>Security Review</h4>
+                <div class="example-command">
+                    <pre>Use security-guardian to review API endpoints before deployment</pre>
+                </div>
+                <p class="example-result">→ Comprehensive security report with vulnerability fixes</p>
+            </div>
+
+            <div class="example-card">
+                <h4>Architecture Design</h4>
+                <div class="example-command">
+                    <pre>Use zen-architect to design a notification system</pre>
+                </div>
+                <p class="example-result">→ Complete modular specification ready for implementation</p>
+            </div>
+        </div>
+    </div>
+</section>"""
+
+    def _get_cta_section_html(self) -> str:
+        """Get call-to-action section template"""
+        return """<section class="cta-section" id="get-started">
+    <div class="container">
+        <div class="cta-content">
+            <h2 class="cta-title">{{ section.title | default("Ready to Transform Your Development?") }}</h2>
+            <p class="cta-description">{{ section.description | default("Join developers who've already experienced the paradigm shift") }}</p>
+
+            <div class="cta-buttons">
+                <a href="#setup" class="btn btn-primary btn-lg">Get Started</a>
+                <a href="{{ config.site.repo_url | default('#') }}" class="btn btn-outline btn-lg">View on GitHub</a>
+            </div>
+
+            <p class="cta-note">Free and open source • No signup required • 5 minute setup</p>
+        </div>
+    </div>
+</section>"""
+
+
+def test_template_engine():
+    """Test the template engine with generated content"""
+    print("🎨 Testing Template Engine")
+    print("=" * 30)
+
+    # Load configuration
+    from config_loader import ConfigLoader
+
+    loader = ConfigLoader()
+    config = loader.load_full_config()
+
+    # Create template engine
+    engine = TemplateEngine(config)
+
+    # Create base templates
+    print("Creating base templates...")
+    engine.create_base_templates()
+
+    # Create mock content for testing
+    from content.content_generator import AgentShowcase
+    from content.content_generator import GeneratedContent
+    from content.content_generator import ProgressiveSetup
+    from content.content_generator import RevolutionContent
+
+    mock_revolution = RevolutionContent(
+        title="The Development Revolution",
+        subtitle="Why Amplifier Changes Everything",
+        problem_statement="Traditional development is slow and complex.",
+        paradigm_comparison={
+            "categories": [{"name": "Speed", "before": "Hours", "after": "Minutes", "improvement": "10x faster"}]
+        },
+        multiplier_effect={
+            "metrics": [{"name": "Ideas", "old_value": 50, "new_value": 1250, "unit": "per month", "multiplier": 25}]
+        },
+        role_transformation={
+            "old_role": {"title": "Traditional Developer", "characteristics": ["Code manually"]},
+            "new_role": {"title": "AI Architect", "characteristics": ["Orchestrate agents"]},
+        },
+    )
+
+    mock_setup = ProgressiveSetup(
+        tiers=[{"name": "Quick Taste", "duration": "1 minute", "description": "Try it now", "focus": "First agent"}]
+    )
+
+    mock_showcase = AgentShowcase(
+        featured_agents=[
+            {
+                "name": "zen-architect",
+                "description": "System design",
+                "capabilities": ["architecture"],
+                "category": "Architecture",
+            }
+        ],
+        agent_categories={
+            "Architecture": [{"name": "zen-architect", "description": "System design", "capabilities_count": 5}]
+        },
+        total_count=23,
+    )
+
+    mock_content = GeneratedContent(
+        revolution_section=mock_revolution,
+        progressive_setup=mock_setup,
+        agent_showcase=mock_showcase,
+        hero_section={
+            "title": "Amplifier",
+            "tagline": "Supercharged Development",
+            "description": "Transform your workflow",
+        },
+        overview_section={"title": "Overview", "key_points": []},
+        examples_section={"title": "Examples", "examples": []},
+    )
+
+    # Test section rendering
+    print("Testing section rendering...")
+    revolution_html = engine.render_section("revolution", mock_revolution)
+    print(f"✓ Revolution section: {len(revolution_html)} characters")
+
+    hero_html = engine.render_section("hero", mock_content.hero_section)
+    print(f"✓ Hero section: {len(hero_html)} characters")
+
+    # Test full page generation
+    print("Testing full page generation...")
+    page_config = {"name": "index", "title": "Home", "sections": ["hero", "revolution", "agents", "setup"]}
+    full_html = engine.generate_full_page(page_config, mock_content)
+    print(f"✓ Full page: {len(full_html)} characters")
+
+    # Save test output
+    output_dir = Path(__file__).parent.parent.parent / "output"
+    output_dir.mkdir(exist_ok=True)
+
+    with open(output_dir / "test_page.html", "w", encoding="utf-8") as f:
+        f.write(full_html)
+
+    print(f"✓ Test page saved to: {output_dir / 'test_page.html'}")
+    print("✅ Template engine test completed successfully!")
+
+    return True
+
+
+if __name__ == "__main__":
+    test_template_engine()
diff --git a/website_generator/src/style/css_generator.py b/website_generator/src/style/css_generator.py
new file mode 100644
index 00000000..27e0bb27
--- /dev/null
+++ b/website_generator/src/style/css_generator.py
@@ -0,0 +1,1100 @@
+"""
+CSS generator for website styling.
+Generates CSS based on design system configuration.
+"""
+
+import sys
+from pathlib import Path
+
+# Import our components
+sys.path.append(str(Path(__file__).parent.parent))
+from config_loader import SiteConfig
+
+
+class CSSGenerator:
+    """Generates CSS from design system configuration"""
+
+    def __init__(self, config: SiteConfig):
+        self.config = config
+        self.design_system = config.design_system
+        self.colors = self.design_system.get("colors", {})
+        self.responsive = config.responsive
+
+    def generate_full_css(self) -> str:
+        """Generate complete CSS stylesheet"""
+        css_parts = [
+            self._generate_css_reset(),
+            self._generate_css_variables(),
+            self._generate_base_styles(),
+            self._generate_layout_styles(),
+            self._generate_component_styles(),
+            self._generate_section_styles(),
+            self._generate_responsive_styles(),
+            self._generate_animation_styles(),
+        ]
+
+        return "\n\n".join(css_parts)
+
+    def _generate_css_reset(self) -> str:
+        """Generate CSS reset and base styles"""
+        return """/* CSS Reset and Base Styles */
+* {
+    margin: 0;
+    padding: 0;
+    box-sizing: border-box;
+}
+
+html {
+    scroll-behavior: smooth;
+    font-size: 16px;
+    line-height: 1.6;
+}
+
+body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', sans-serif;
+    background-color: var(--background-color);
+    color: var(--text-primary);
+    overflow-x: hidden;
+}
+
+img {
+    max-width: 100%;
+    height: auto;
+}
+
+a {
+    text-decoration: none;
+    color: inherit;
+}
+
+button {
+    border: none;
+    background: none;
+    cursor: pointer;
+    font: inherit;
+}
+
+ul, ol {
+    list-style: none;
+}"""
+
+    def _generate_css_variables(self) -> str:
+        """Generate CSS custom properties from design system"""
+        vars_css = "/* CSS Custom Properties */\n:root {\n"
+
+        # Colors
+        for color_name, color_value in self.colors.items():
+            css_name = color_name.replace("_", "-")
+            vars_css += f"    --{css_name}: {color_value};\n"
+
+        # Typography
+        if self.design_system.get("typography") == "inter_modern":
+            vars_css += """    --font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+    --font-size-xs: 0.75rem;
+    --font-size-sm: 0.875rem;
+    --font-size-base: 1rem;
+    --font-size-lg: 1.125rem;
+    --font-size-xl: 1.25rem;
+    --font-size-2xl: 1.5rem;
+    --font-size-3xl: 1.875rem;
+    --font-size-4xl: 2.25rem;
+    --font-size-5xl: 3rem;
+"""
+
+        # Spacing
+        vars_css += """    --spacing-xs: 0.25rem;
+    --spacing-sm: 0.5rem;
+    --spacing-md: 1rem;
+    --spacing-lg: 1.5rem;
+    --spacing-xl: 2rem;
+    --spacing-2xl: 3rem;
+    --spacing-3xl: 4rem;
+    --spacing-4xl: 6rem;
+"""
+
+        # Shadows
+        vars_css += """    --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+    --shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06);
+    --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
+    --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
+"""
+
+        # Border radius
+        vars_css += """    --radius-sm: 0.25rem;
+    --radius: 0.5rem;
+    --radius-md: 0.75rem;
+    --radius-lg: 1rem;
+    --radius-xl: 1.5rem;
+"""
+
+        # Responsive breakpoints
+        if self.responsive:
+            breakpoints = self.responsive.get("breakpoints", {})
+            for bp_name, bp_value in breakpoints.items():
+                vars_css += f"    --breakpoint-{bp_name}: {bp_value};\n"
+
+        vars_css += "}"
+        return vars_css
+
+    def _generate_base_styles(self) -> str:
+        """Generate base typography and element styles"""
+        return """/* Base Typography and Elements */
+body {
+    font-family: var(--font-family, -apple-system, BlinkMacSystemFont, sans-serif);
+    font-size: var(--font-size-base);
+    line-height: 1.6;
+}
+
+h1, h2, h3, h4, h5, h6 {
+    font-weight: 600;
+    line-height: 1.2;
+    margin-bottom: var(--spacing-md);
+    color: var(--text-primary);
+}
+
+h1 { font-size: var(--font-size-4xl); }
+h2 { font-size: var(--font-size-3xl); }
+h3 { font-size: var(--font-size-2xl); }
+h4 { font-size: var(--font-size-xl); }
+h5 { font-size: var(--font-size-lg); }
+h6 { font-size: var(--font-size-base); }
+
+p {
+    margin-bottom: var(--spacing-md);
+    color: var(--text-secondary);
+}
+
+strong {
+    font-weight: 600;
+    color: var(--text-primary);
+}
+
+code {
+    font-family: 'SF Mono', 'Monaco', 'Cascadia Code', 'Roboto Mono', monospace;
+    font-size: 0.875em;
+    background: var(--surface, #f8fafc);
+    padding: 0.125rem 0.25rem;
+    border-radius: var(--radius-sm);
+    border: 1px solid var(--border, #e5e7eb);
+}
+
+pre {
+    background: var(--surface, #f8fafc);
+    padding: var(--spacing-lg);
+    border-radius: var(--radius);
+    border: 1px solid var(--border, #e5e7eb);
+    overflow-x: auto;
+    margin-bottom: var(--spacing-lg);
+}
+
+pre code {
+    background: none;
+    padding: 0;
+    border: none;
+}"""
+
+    def _generate_layout_styles(self) -> str:
+        """Generate layout and grid styles"""
+        return """/* Layout Styles */
+.container {
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 0 var(--spacing-lg);
+}
+
+.section {
+    padding: var(--spacing-4xl) 0;
+}
+
+.section-title {
+    font-size: var(--font-size-3xl);
+    font-weight: 700;
+    text-align: center;
+    margin-bottom: var(--spacing-lg);
+    color: var(--text-primary);
+}
+
+.section-description {
+    font-size: var(--font-size-lg);
+    text-align: center;
+    margin-bottom: var(--spacing-3xl);
+    color: var(--text-secondary);
+    max-width: 600px;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+/* Grid Systems */
+.grid {
+    display: grid;
+    gap: var(--spacing-lg);
+}
+
+.grid-2 { grid-template-columns: repeat(2, 1fr); }
+.grid-3 { grid-template-columns: repeat(3, 1fr); }
+.grid-4 { grid-template-columns: repeat(4, 1fr); }
+
+.flex {
+    display: flex;
+    gap: var(--spacing-md);
+}
+
+.flex-center {
+    justify-content: center;
+    align-items: center;
+}
+
+.flex-between {
+    justify-content: space-between;
+    align-items: center;
+}
+
+.flex-col {
+    flex-direction: column;
+}"""
+
+    def _generate_component_styles(self) -> str:
+        """Generate component styles"""
+        # Animation level for future component styling
+        # animation_level = self.design_system.get("animation_level", "engaging")
+
+        # Button styles
+        btn_styles = """/* Button Components */
+.btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: var(--spacing-sm) var(--spacing-lg);
+    font-size: var(--font-size-base);
+    font-weight: 500;
+    border-radius: var(--radius);
+    cursor: pointer;
+    text-decoration: none;
+    border: none;
+    transition: all 0.2s ease;
+    gap: var(--spacing-xs);
+}
+
+.btn-primary {
+    background: var(--primary-color);
+    color: white;
+}
+
+.btn-primary:hover {
+    background: var(--secondary-color);
+    transform: translateY(-1px);
+}
+
+.btn-secondary {
+    background: transparent;
+    color: var(--primary-color);
+    border: 2px solid var(--primary-color);
+}
+
+.btn-secondary:hover {
+    background: var(--primary-color);
+    color: white;
+}
+
+.btn-outline {
+    background: transparent;
+    color: var(--text-primary);
+    border: 1px solid var(--border, #e5e7eb);
+}
+
+.btn-outline:hover {
+    background: var(--surface, #f8fafc);
+    border-color: var(--primary-color);
+}"""
+
+        # Card styles
+        card_styles = """
+/* Card Components */
+.card {
+    background: white;
+    border-radius: var(--radius-lg);
+    padding: var(--spacing-xl);
+    box-shadow: var(--shadow);
+    border: 1px solid var(--border, #e5e7eb);
+    transition: all 0.3s ease;
+}
+
+.card:hover {
+    box-shadow: var(--shadow-lg);
+    transform: translateY(-2px);
+}
+
+.card-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: flex-start;
+    margin-bottom: var(--spacing-md);
+}
+
+.card-title {
+    font-size: var(--font-size-lg);
+    font-weight: 600;
+    color: var(--text-primary);
+    margin: 0;
+}
+
+.card-description {
+    color: var(--text-secondary);
+    margin-bottom: var(--spacing-md);
+}"""
+
+        # Badge styles
+        badge_styles = """
+/* Badge Components */
+.badge {
+    display: inline-flex;
+    align-items: center;
+    padding: 0.25rem 0.75rem;
+    font-size: var(--font-size-sm);
+    font-weight: 500;
+    border-radius: var(--radius-xl);
+    text-transform: uppercase;
+    letter-spacing: 0.025em;
+}
+
+.badge-architecture {
+    background: rgba(59, 130, 246, 0.1);
+    color: var(--primary-color);
+}
+
+.badge-quality {
+    background: rgba(16, 185, 129, 0.1);
+    color: var(--success, #10b981);
+}
+
+.badge-analysis {
+    background: rgba(139, 92, 246, 0.1);
+    color: #8b5cf6;
+}
+
+.badge-automation {
+    background: rgba(245, 158, 11, 0.1);
+    color: var(--warning, #f59e0b);
+}
+
+.badge-development {
+    background: rgba(107, 114, 128, 0.1);
+    color: var(--text-secondary);
+}"""
+
+        return btn_styles + card_styles + badge_styles
+
+    def _generate_section_styles(self) -> str:
+        """Generate styles for specific sections"""
+        return """/* Section-Specific Styles */
+
+/* Header and Navigation */
+.header {
+    background: rgba(255, 255, 255, 0.95);
+    backdrop-filter: blur(10px);
+    border-bottom: 1px solid var(--border, #e5e7eb);
+    position: sticky;
+    top: 0;
+    z-index: 100;
+}
+
+.nav {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: var(--spacing-md) var(--spacing-lg);
+}
+
+.nav-brand h1 {
+    font-size: var(--font-size-xl);
+    font-weight: 700;
+    color: var(--primary-color);
+    margin: 0;
+}
+
+.nav-links {
+    display: flex;
+    gap: var(--spacing-xl);
+}
+
+.nav-links a {
+    color: var(--text-secondary);
+    font-weight: 500;
+    transition: color 0.2s ease;
+}
+
+.nav-links a:hover {
+    color: var(--primary-color);
+}
+
+/* Hero Section */
+.hero-section {
+    background: linear-gradient(135deg, var(--primary-color) 0%, var(--secondary-color) 100%);
+    color: white;
+    text-align: center;
+    padding: var(--spacing-4xl) 0;
+}
+
+.hero-title {
+    font-size: var(--font-size-5xl);
+    font-weight: 800;
+    margin-bottom: var(--spacing-md);
+}
+
+.hero-tagline {
+    font-size: var(--font-size-xl);
+    margin-bottom: var(--spacing-lg);
+    opacity: 0.9;
+}
+
+.hero-description {
+    font-size: var(--font-size-lg);
+    margin-bottom: var(--spacing-2xl);
+    max-width: 600px;
+    margin-left: auto;
+    margin-right: auto;
+    opacity: 0.8;
+}
+
+.features-preview {
+    display: flex;
+    justify-content: center;
+    gap: var(--spacing-md);
+    margin-bottom: var(--spacing-2xl);
+    flex-wrap: wrap;
+}
+
+.feature-badge {
+    background: rgba(255, 255, 255, 0.2);
+    padding: var(--spacing-xs) var(--spacing-md);
+    border-radius: var(--radius-xl);
+    font-size: var(--font-size-sm);
+    font-weight: 500;
+}
+
+.hero-actions {
+    display: flex;
+    justify-content: center;
+    gap: var(--spacing-lg);
+}
+
+/* Revolution Section */
+.revolution-section {
+    background: linear-gradient(135deg, #f8fafc 0%, #e2e8f0 100%);
+    padding: var(--spacing-4xl) 0;
+}
+
+.revolution-title {
+    font-size: var(--font-size-4xl);
+    font-weight: 800;
+    text-align: center;
+    margin-bottom: var(--spacing-sm);
+    background: linear-gradient(135deg, var(--primary-color), var(--secondary-color));
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+}
+
+.revolution-subtitle {
+    font-size: var(--font-size-xl);
+    text-align: center;
+    color: var(--text-secondary);
+    margin-bottom: var(--spacing-3xl);
+}
+
+.problem-statement {
+    max-width: 800px;
+    margin: 0 auto var(--spacing-3xl);
+    font-size: var(--font-size-lg);
+    text-align: center;
+    color: var(--text-primary);
+}
+
+.metrics-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+    gap: var(--spacing-lg);
+    margin-bottom: var(--spacing-3xl);
+}
+
+.metric-card {
+    background: white;
+    padding: var(--spacing-xl);
+    border-radius: var(--radius-lg);
+    text-align: center;
+    box-shadow: var(--shadow);
+}
+
+.metric-name {
+    font-size: var(--font-size-sm);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    color: var(--text-secondary);
+    margin-bottom: var(--spacing-sm);
+}
+
+.metric-comparison {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--spacing-sm);
+    margin-bottom: var(--spacing-xs);
+}
+
+.old-value {
+    font-size: var(--font-size-lg);
+    color: var(--text-secondary);
+    text-decoration: line-through;
+}
+
+.new-value {
+    font-size: var(--font-size-2xl);
+    font-weight: 700;
+    color: var(--primary-color);
+}
+
+.arrow {
+    color: var(--primary-color);
+    font-size: var(--font-size-xl);
+}
+
+.metric-unit {
+    font-size: var(--font-size-sm);
+    color: var(--text-secondary);
+    margin-bottom: var(--spacing-xs);
+}
+
+.metric-multiplier {
+    font-weight: 600;
+    color: var(--success, #10b981);
+}
+
+/* Agent Showcase */
+.agents-section {
+    padding: var(--spacing-4xl) 0;
+}
+
+.agent-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+    gap: var(--spacing-lg);
+    margin-bottom: var(--spacing-3xl);
+}
+
+.agent-card {
+    background: white;
+    padding: var(--spacing-xl);
+    border-radius: var(--radius-lg);
+    box-shadow: var(--shadow);
+    border: 1px solid var(--border, #e5e7eb);
+    transition: all 0.3s ease;
+}
+
+.agent-card:hover {
+    transform: translateY(-4px);
+    box-shadow: var(--shadow-lg);
+}
+
+.agent-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: flex-start;
+    margin-bottom: var(--spacing-md);
+}
+
+.agent-name {
+    font-size: var(--font-size-lg);
+    font-weight: 600;
+    color: var(--text-primary);
+}
+
+.agent-description {
+    color: var(--text-secondary);
+    margin-bottom: var(--spacing-md);
+    line-height: 1.6;
+}
+
+.agent-capabilities {
+    list-style: none;
+    padding: 0;
+}
+
+.agent-capabilities li {
+    padding: var(--spacing-xs) 0;
+    color: var(--text-secondary);
+    font-size: var(--font-size-sm);
+}
+
+.agent-capabilities li:before {
+    content: "✓";
+    color: var(--success, #10b981);
+    font-weight: bold;
+    margin-right: var(--spacing-xs);
+}
+
+/* Rich Agent Card Styles */
+.rich-agent-card {
+    margin-bottom: var(--spacing-xl);
+    padding: var(--spacing-2xl);
+}
+
+.rich-agent-card .agent-name {
+    font-size: var(--font-size-xl);
+    font-weight: 600;
+    color: var(--text-primary);
+}
+
+.rich-agent-card .agent-category {
+    background: var(--primary-color);
+    color: white;
+    padding: 0.25rem 0.75rem;
+    border-radius: var(--radius-xl);
+    font-size: var(--font-size-sm);
+    font-weight: 500;
+}
+
+.agent-body {
+    margin-top: var(--spacing-lg);
+}
+
+.agent-features,
+.agent-use-cases,
+.agent-example {
+    margin-top: var(--spacing-lg);
+}
+
+.agent-features h4,
+.agent-use-cases h4,
+.agent-example h4 {
+    font-size: var(--font-size-lg);
+    font-weight: 600;
+    color: var(--text-primary);
+    margin-bottom: var(--spacing-sm);
+}
+
+.agent-features ul,
+.agent-use-cases ul {
+    list-style: none;
+    padding-left: 0;
+}
+
+.agent-features li,
+.agent-use-cases li {
+    padding: var(--spacing-xs) 0;
+    color: var(--text-secondary);
+    position: relative;
+    padding-left: 1.5rem;
+}
+
+.agent-features li:before,
+.agent-use-cases li:before {
+    content: "•";
+    color: var(--primary-color);
+    position: absolute;
+    left: 0;
+    font-weight: bold;
+}
+
+.example-command {
+    background: #1e1e1e;
+    color: #d4d4d4;
+    padding: var(--spacing-md);
+    border-radius: var(--radius);
+    margin-bottom: var(--spacing-sm);
+    font-family: 'Consolas', 'Monaco', monospace;
+    font-size: 0.9rem;
+}
+
+.example-command pre {
+    margin: 0;
+    padding: 0;
+    background: none;
+    border: none;
+    color: #d4d4d4;
+}
+
+.example-output {
+    color: var(--success, #10b981);
+    font-weight: 500;
+    font-style: italic;
+}
+
+.advanced-section {
+    margin-top: var(--spacing-lg);
+    border-top: 1px solid var(--border, #e5e7eb);
+    padding-top: var(--spacing-lg);
+}
+
+.advanced-section summary {
+    cursor: pointer;
+    color: var(--primary-color);
+    font-size: 0.95rem;
+    margin-bottom: var(--spacing-md);
+    font-weight: 500;
+}
+
+.advanced-section summary:hover {
+    color: var(--secondary-color);
+}
+
+.examples-container {
+    margin-top: var(--spacing-md);
+}
+
+.example-card {
+    background: var(--surface, #f8fafc);
+    padding: var(--spacing-lg);
+    border-radius: var(--radius);
+    margin-bottom: var(--spacing-md);
+    border: 1px solid var(--border, #e5e7eb);
+}
+
+.example-card h5 {
+    color: var(--text-primary);
+    margin-bottom: var(--spacing-sm);
+    font-size: var(--font-size-base);
+    font-weight: 600;
+}
+
+.example-card p {
+    color: var(--text-secondary);
+    margin: 0;
+    font-size: var(--font-size-sm);
+}
+
+.example-card code {
+    background: var(--text-primary);
+    color: white;
+    padding: 0.125rem 0.25rem;
+    border-radius: 0.125rem;
+    font-size: 0.85em;
+}
+
+/* Progressive Setup */
+.setup-section {
+    background: var(--surface, #f8fafc);
+    padding: var(--spacing-4xl) 0;
+}
+
+.setup-tiers {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
+    gap: var(--spacing-xl);
+}
+
+.tier-card {
+    background: white;
+    padding: var(--spacing-2xl);
+    border-radius: var(--radius-lg);
+    box-shadow: var(--shadow);
+    border: 1px solid var(--border, #e5e7eb);
+    text-align: center;
+    transition: all 0.3s ease;
+}
+
+.tier-card:hover {
+    transform: translateY(-4px);
+    box-shadow: var(--shadow-lg);
+}
+
+.tier-header {
+    margin-bottom: var(--spacing-lg);
+}
+
+.tier-name {
+    font-size: var(--font-size-xl);
+    font-weight: 700;
+    margin-bottom: var(--spacing-xs);
+}
+
+.tier-duration {
+    background: var(--primary-color);
+    color: white;
+    padding: var(--spacing-xs) var(--spacing-md);
+    border-radius: var(--radius-xl);
+    font-size: var(--font-size-sm);
+    font-weight: 600;
+}
+
+.tier-focus {
+    font-weight: 600;
+    margin-bottom: var(--spacing-lg);
+}
+
+.tier-steps {
+    text-align: left;
+    margin-bottom: var(--spacing-lg);
+}
+
+.tier-demo {
+    background: var(--surface, #f8fafc);
+    padding: var(--spacing-md);
+    border-radius: var(--radius);
+    margin-bottom: var(--spacing-lg);
+    text-align: left;
+}
+
+.tier-demo code {
+    background: var(--text-primary);
+    color: white;
+    padding: var(--spacing-xs) var(--spacing-sm);
+    border-radius: var(--radius-sm);
+}
+
+/* Tab System */
+.category-tabs {
+    display: flex;
+    justify-content: center;
+    gap: var(--spacing-sm);
+    margin-bottom: var(--spacing-xl);
+    flex-wrap: wrap;
+}
+
+.tab-btn {
+    padding: var(--spacing-md) var(--spacing-lg);
+    background: transparent;
+    border: 2px solid var(--border, #e5e7eb);
+    border-radius: var(--radius);
+    cursor: pointer;
+    transition: all 0.2s ease;
+}
+
+.tab-btn.active,
+.tab-btn:hover {
+    background: var(--primary-color);
+    color: white;
+    border-color: var(--primary-color);
+}
+
+.tab-content {
+    display: none;
+}
+
+.tab-content.active {
+    display: block;
+}"""
+
+    def _generate_responsive_styles(self) -> str:
+        """Generate responsive breakpoint styles"""
+        mobile_bp = self.responsive.get("breakpoints", {}).get("mobile", "768px")
+        tablet_bp = self.responsive.get("breakpoints", {}).get("tablet", "1024px")
+
+        return f"""/* Responsive Styles */
+
+@media (max-width: {mobile_bp}) {{
+    .container {{
+        padding: 0 var(--spacing-md);
+    }}
+
+    .section {{
+        padding: var(--spacing-2xl) 0;
+    }}
+
+    .hero-title {{
+        font-size: var(--font-size-3xl);
+    }}
+
+    .hero-actions {{
+        flex-direction: column;
+        align-items: center;
+    }}
+
+    .grid-2,
+    .grid-3,
+    .grid-4 {{
+        grid-template-columns: 1fr;
+    }}
+
+    .metrics-grid {{
+        grid-template-columns: 1fr;
+    }}
+
+    .agent-grid {{
+        grid-template-columns: 1fr;
+    }}
+
+    .setup-tiers {{
+        grid-template-columns: 1fr;
+    }}
+
+    .category-tabs {{
+        flex-direction: column;
+        align-items: center;
+    }}
+
+    .nav-links {{
+        display: none;
+    }}
+}}
+
+@media (max-width: {tablet_bp}) and (min-width: {mobile_bp}) {{
+    .grid-3,
+    .grid-4 {{
+        grid-template-columns: repeat(2, 1fr);
+    }}
+
+    .metrics-grid {{
+        grid-template-columns: repeat(2, 1fr);
+    }}
+
+    .agent-grid {{
+        grid-template-columns: repeat(2, 1fr);
+    }}
+}}"""
+
+    def _generate_animation_styles(self) -> str:
+        """Generate animation styles based on animation level"""
+        animation_level = self.design_system.get("animation_level", "engaging")
+
+        if animation_level == "minimal":
+            return """/* Minimal Animations */
+.btn, .card, .agent-card, .tier-card {
+    transition: opacity 0.2s ease;
+}"""
+
+        if animation_level == "subtle":
+            return """/* Subtle Animations */
+.btn, .card, .agent-card, .tier-card {
+    transition: all 0.2s ease;
+}
+
+.card:hover, .agent-card:hover, .tier-card:hover {
+    transform: translateY(-2px);
+}"""
+
+        if animation_level == "engaging":
+            return """/* Engaging Animations */
+.btn, .card, .agent-card, .tier-card {
+    transition: all 0.3s ease;
+}
+
+.card:hover, .agent-card:hover, .tier-card:hover {
+    transform: translateY(-4px);
+}
+
+/* Counter Animation */
+@keyframes counter-up {
+    from { opacity: 0; transform: translateY(20px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+
+.metric-card .new-value {
+    animation: counter-up 0.6s ease-out;
+}
+
+/* Fade In Animation */
+@keyframes fade-in {
+    from { opacity: 0; transform: translateY(30px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+
+.card, .agent-card, .tier-card {
+    animation: fade-in 0.6s ease-out;
+}
+
+/* Hover Effects */
+.btn:hover {
+    transform: translateY(-2px);
+    box-shadow: var(--shadow-lg);
+}
+
+.agent-card:hover .agent-name {
+    color: var(--primary-color);
+}"""
+
+        # bold
+        return """/* Bold Animations */
+.btn, .card, .agent-card, .tier-card {
+    transition: all 0.4s cubic-bezier(0.175, 0.885, 0.32, 1.275);
+}
+
+.card:hover, .agent-card:hover, .tier-card:hover {
+    transform: translateY(-8px) scale(1.02);
+}
+
+.btn:hover {
+    transform: translateY(-3px) scale(1.05);
+}
+
+/* More dramatic animations */
+@keyframes bounce-in {
+    0% { opacity: 0; transform: scale(0.3); }
+    50% { opacity: 1; transform: scale(1.05); }
+    70% { transform: scale(0.9); }
+    100% { opacity: 1; transform: scale(1); }
+}
+
+.metric-card {
+    animation: bounce-in 0.6s ease-out;
+}"""
+
+    def save_css(self, output_path: str) -> None:
+        """Save generated CSS to file"""
+        css_content = self.generate_full_css()
+
+        output_file = Path(output_path)
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(output_file, "w", encoding="utf-8") as f:
+            f.write(css_content)
+
+        print(f"✓ CSS saved to: {output_file} ({len(css_content):,} characters)")
+
+
+def test_css_generator():
+    """Test CSS generation"""
+    print("🎨 Testing CSS Generator")
+    print("=" * 25)
+
+    # Load configuration
+    from config_loader import ConfigLoader
+
+    loader = ConfigLoader()
+    amplifier_config_path = Path(__file__).parent.parent.parent / "examples" / "amplifier_config.yaml"
+    config = loader.load_full_config(str(amplifier_config_path))
+
+    # Generate CSS
+    generator = CSSGenerator(config)
+
+    # Test individual components
+    print("Generating CSS components...")
+    reset_css = generator._generate_css_reset()
+    print(f"✓ CSS Reset: {len(reset_css)} characters")
+
+    variables_css = generator._generate_css_variables()
+    print(f"✓ CSS Variables: {len(variables_css)} characters")
+
+    components_css = generator._generate_component_styles()
+    print(f"✓ Component Styles: {len(components_css)} characters")
+
+    sections_css = generator._generate_section_styles()
+    print(f"✓ Section Styles: {len(sections_css)} characters")
+
+    responsive_css = generator._generate_responsive_styles()
+    print(f"✓ Responsive Styles: {len(responsive_css)} characters")
+
+    animations_css = generator._generate_animation_styles()
+    print(f"✓ Animation Styles: {len(animations_css)} characters")
+
+    # Generate full CSS
+    print("\nGenerating complete stylesheet...")
+    full_css = generator.generate_full_css()
+    print(f"✓ Complete CSS: {len(full_css):,} characters")
+
+    # Save CSS
+    output_dir = Path(__file__).parent.parent.parent / "output"
+    output_dir.mkdir(exist_ok=True)
+    generator.save_css(str(output_dir / "amplifier-styles.css"))
+
+    print("\n📊 CSS Generation Summary:")
+    print(f"  Theme: {config.design_system['color_palette']}")
+    print(f"  Animation Level: {config.design_system['animation_level']}")
+    print(f"  Responsive Breakpoints: {len(config.responsive.get('breakpoints', {}))}")
+    print(f"  Color Variables: {len(config.design_system.get('colors', {}))}")
+
+    print("\n✅ CSS generation test completed successfully!")
+    return True
+
+
+if __name__ == "__main__":
+    test_css_generator()
diff --git a/website_generator/templates/base_template.html b/website_generator/templates/base_template.html
new file mode 100644
index 00000000..913fee0a
--- /dev/null
+++ b/website_generator/templates/base_template.html
@@ -0,0 +1,62 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{ page_title }} - {{ site.name }}</title>
+    <meta name="description" content="{{ meta_description }}">
+
+    <!-- SEO -->
+    <meta property="og:title" content="{{ page_title }} - {{ site.name }}">
+    <meta property="og:description" content="{{ meta_description }}">
+    <meta property="og:type" content="website">
+
+    <!-- Styles -->
+    <link rel="stylesheet" href="styles.css">
+
+    <!-- Custom colors from design system -->
+    <style>
+        :root {
+            --primary-color: {{ get_color('primary') }};
+            --secondary-color: {{ get_color('secondary') }};
+            --accent-color: {{ get_color('accent') }};
+            --background-color: {{ get_color('background') }};
+            --text-primary: {{ get_color('text_primary') }};
+            --text-secondary: {{ get_color('text_secondary') }};
+        }
+    </style>
+</head>
+<body>
+    <!-- Navigation -->
+    <header class="header">
+        <nav class="nav">
+            <div class="nav-brand">
+                <h1>{{ site.name }}</h1>
+            </div>
+            <ul class="nav-links">
+                <li><a href="#hero">Home</a></li>
+                {% if content.agent_showcase %}
+                <li><a href="#agents">Agents</a></li>
+                {% endif %}
+                <li><a href="#examples">Examples</a></li>
+                <li><a href="#setup">Setup</a></li>
+            </ul>
+        </nav>
+    </header>
+
+    <!-- Main Content -->
+    <main>
+        {{ sections_html | safe }}
+    </main>
+
+    <!-- Footer -->
+    <footer class="footer">
+        <div class="container">
+            <p>&copy; {{ now().year }} {{ site.name }}. Built with Website Generator.</p>
+        </div>
+    </footer>
+
+    <!-- JavaScript -->
+    <script src="script.js"></script>
+</body>
+</html>
\ No newline at end of file
diff --git a/website_generator/templates/index.html b/website_generator/templates/index.html
new file mode 100644
index 00000000..864c0aa5
--- /dev/null
+++ b/website_generator/templates/index.html
@@ -0,0 +1,5 @@
+{% extends "base_template.html" %}
+
+{% block content %}
+{{ sections_html | safe }}
+{% endblock %}
\ No newline at end of file
diff --git a/website_generator/templates/sections/agent_showcase.html b/website_generator/templates/sections/agent_showcase.html
new file mode 100644
index 00000000..09e264e6
--- /dev/null
+++ b/website_generator/templates/sections/agent_showcase.html
@@ -0,0 +1,66 @@
+<section class="agents-section" id="agents">
+    <div class="container">
+        <h2 class="section-title">
+            {% if section.total_count > 20 %}
+            {{ section.total_count }}+ Specialized Agents
+            {% else %}
+            Specialized Agents
+            {% endif %}
+        </h2>
+        <p class="section-description">Expert AI agents handle every aspect of development</p>
+
+        {% if section.featured_agents %}
+        <div class="featured-agents">
+            <h3>Featured Agents</h3>
+            <div class="agent-grid">
+                {% for agent in section.featured_agents %}
+                <div class="agent-card">
+                    <div class="agent-header">
+                        <span class="agent-name">{{ agent.name }}</span>
+                        <span class="agent-badge {{ agent.name | agent_badge }}">{{ agent.category }}</span>
+                    </div>
+                    <p class="agent-description">{{ agent.description }}</p>
+                    {% if agent.capabilities %}
+                    <ul class="agent-capabilities">
+                        {% for capability in agent.capabilities %}
+                        <li>{{ capability }}</li>
+                        {% endfor %}
+                    </ul>
+                    {% endif %}
+                </div>
+                {% endfor %}
+            </div>
+        </div>
+        {% endif %}
+
+        {% if section.agent_categories %}
+        <div class="agent-categories">
+            <h3>All Agents by Category</h3>
+            <div class="category-tabs">
+                {% for category, agents in section.agent_categories.items() %}
+                <button class="tab-btn {% if loop.first %}active{% endif %}"
+                        onclick="showTab('{{ category | slug }}', this)">
+                    {{ get_icon(category | lower) }} {{ category }} ({{ agents | length }})
+                </button>
+                {% endfor %}
+            </div>
+
+            {% for category, agents in section.agent_categories.items() %}
+            <div class="tab-content {% if loop.first %}active{% endif %}" id="{{ category | slug }}">
+                <div class="agents-list">
+                    {% for agent in agents %}
+                    <div class="agent-item">
+                        <h4>{{ agent.name }}</h4>
+                        <p>{{ agent.description }}</p>
+                        {% if agent.capabilities_count %}
+                        <span class="capabilities-count">{{ agent.capabilities_count }} capabilities</span>
+                        {% endif %}
+                    </div>
+                    {% endfor %}
+                </div>
+            </div>
+            {% endfor %}
+        </div>
+        {% endif %}
+    </div>
+</section>
\ No newline at end of file
diff --git a/website_generator/templates/sections/agents.html b/website_generator/templates/sections/agents.html
new file mode 100644
index 00000000..09e264e6
--- /dev/null
+++ b/website_generator/templates/sections/agents.html
@@ -0,0 +1,66 @@
+<section class="agents-section" id="agents">
+    <div class="container">
+        <h2 class="section-title">
+            {% if section.total_count > 20 %}
+            {{ section.total_count }}+ Specialized Agents
+            {% else %}
+            Specialized Agents
+            {% endif %}
+        </h2>
+        <p class="section-description">Expert AI agents handle every aspect of development</p>
+
+        {% if section.featured_agents %}
+        <div class="featured-agents">
+            <h3>Featured Agents</h3>
+            <div class="agent-grid">
+                {% for agent in section.featured_agents %}
+                <div class="agent-card">
+                    <div class="agent-header">
+                        <span class="agent-name">{{ agent.name }}</span>
+                        <span class="agent-badge {{ agent.name | agent_badge }}">{{ agent.category }}</span>
+                    </div>
+                    <p class="agent-description">{{ agent.description }}</p>
+                    {% if agent.capabilities %}
+                    <ul class="agent-capabilities">
+                        {% for capability in agent.capabilities %}
+                        <li>{{ capability }}</li>
+                        {% endfor %}
+                    </ul>
+                    {% endif %}
+                </div>
+                {% endfor %}
+            </div>
+        </div>
+        {% endif %}
+
+        {% if section.agent_categories %}
+        <div class="agent-categories">
+            <h3>All Agents by Category</h3>
+            <div class="category-tabs">
+                {% for category, agents in section.agent_categories.items() %}
+                <button class="tab-btn {% if loop.first %}active{% endif %}"
+                        onclick="showTab('{{ category | slug }}', this)">
+                    {{ get_icon(category | lower) }} {{ category }} ({{ agents | length }})
+                </button>
+                {% endfor %}
+            </div>
+
+            {% for category, agents in section.agent_categories.items() %}
+            <div class="tab-content {% if loop.first %}active{% endif %}" id="{{ category | slug }}">
+                <div class="agents-list">
+                    {% for agent in agents %}
+                    <div class="agent-item">
+                        <h4>{{ agent.name }}</h4>
+                        <p>{{ agent.description }}</p>
+                        {% if agent.capabilities_count %}
+                        <span class="capabilities-count">{{ agent.capabilities_count }} capabilities</span>
+                        {% endif %}
+                    </div>
+                    {% endfor %}
+                </div>
+            </div>
+            {% endfor %}
+        </div>
+        {% endif %}
+    </div>
+</section>
\ No newline at end of file
diff --git a/website_generator/templates/sections/hero.html b/website_generator/templates/sections/hero.html
new file mode 100644
index 00000000..8450ec80
--- /dev/null
+++ b/website_generator/templates/sections/hero.html
@@ -0,0 +1,22 @@
+<section class="hero-section" id="hero">
+    <div class="container">
+        <div class="hero-content">
+            <h1 class="hero-title">{{ section.title }}</h1>
+            <p class="hero-tagline">{{ section.tagline }}</p>
+            <p class="hero-description">{{ section.description }}</p>
+
+            {% if section.features_preview %}
+            <div class="features-preview">
+                {% for feature in section.features_preview %}
+                <span class="feature-badge">{{ feature }}</span>
+                {% endfor %}
+            </div>
+            {% endif %}
+
+            <div class="hero-actions">
+                <a href="#setup" class="btn btn-primary">{{ section.cta_primary }}</a>
+                <a href="#examples" class="btn btn-secondary">{{ section.cta_secondary }}</a>
+            </div>
+        </div>
+    </div>
+</section>
\ No newline at end of file
diff --git a/website_generator/templates/sections/progressive_setup.html b/website_generator/templates/sections/progressive_setup.html
new file mode 100644
index 00000000..a5817d8c
--- /dev/null
+++ b/website_generator/templates/sections/progressive_setup.html
@@ -0,0 +1,50 @@
+<section class="setup-section" id="setup">
+    <div class="container">
+        <h2 class="section-title">Progressive Setup</h2>
+        <p class="section-description">Choose your learning path based on available time</p>
+
+        <div class="setup-tiers">
+            {% for tier in section.tiers %}
+            <div class="tier-card" data-tier="{{ loop.index }}">
+                <div class="tier-header">
+                    <h3 class="tier-name">{{ tier.name }}</h3>
+                    <span class="tier-duration">{{ tier.duration }}</span>
+                </div>
+                <p class="tier-description">{{ tier.description }}</p>
+                <p class="tier-focus"><strong>Focus:</strong> {{ tier.focus }}</p>
+
+                {% if tier.steps %}
+                <ol class="tier-steps">
+                    {% for step in tier.steps %}
+                    <li>{{ step }}</li>
+                    {% endfor %}
+                </ol>
+                {% endif %}
+
+                {% if tier.demo_command %}
+                <div class="tier-demo">
+                    <strong>Try this:</strong>
+                    <code>{{ tier.demo_command }}</code>
+                    {% if tier.expected_result %}
+                    <p><em>Expected: {{ tier.expected_result }}</em></p>
+                    {% endif %}
+                </div>
+                {% endif %}
+
+                {% if tier.mastery_features %}
+                <div class="mastery-features">
+                    <strong>What you'll master:</strong>
+                    <ul>
+                        {% for feature in tier.mastery_features %}
+                        <li>{{ feature }}</li>
+                        {% endfor %}
+                    </ul>
+                </div>
+                {% endif %}
+
+                <button class="btn btn-outline tier-btn">Start {{ tier.name }}</button>
+            </div>
+            {% endfor %}
+        </div>
+    </div>
+</section>
\ No newline at end of file
diff --git a/website_generator/templates/sections/revolution.html b/website_generator/templates/sections/revolution.html
new file mode 100644
index 00000000..89ec5d73
--- /dev/null
+++ b/website_generator/templates/sections/revolution.html
@@ -0,0 +1,81 @@
+<section class="revolution-section" id="revolution">
+    <div class="container">
+        <div class="revolution-content">
+            <h2 class="revolution-title">{{ section.title }}</h2>
+            <h3 class="revolution-subtitle">{{ section.subtitle }}</h3>
+
+            <div class="problem-statement">
+                <p>{{ section.problem_statement }}</p>
+            </div>
+
+            {% if section.multiplier_effect %}
+            <div class="multiplier-showcase">
+                <h4>Capability Multiplication</h4>
+                <div class="metrics-grid">
+                    {% for metric in section.multiplier_effect.metrics %}
+                    <div class="metric-card">
+                        <div class="metric-name">{{ metric.name }}</div>
+                        <div class="metric-comparison">
+                            <span class="old-value">{{ metric.old_value | format_number }}</span>
+                            <span class="arrow">→</span>
+                            <span class="new-value"
+                                  {% if interactions.animated_counters %}
+                                  data-counter="{{ metric.new_value }}"
+                                  {% endif %}>
+                                {{ metric.new_value | format_number }}
+                            </span>
+                        </div>
+                        <div class="metric-unit">{{ metric.unit }}</div>
+                        <div class="metric-multiplier">{{ metric.multiplier }}x {% if metric.inverse %}faster{% else %}more{% endif %}</div>
+                    </div>
+                    {% endfor %}
+                </div>
+            </div>
+            {% endif %}
+
+            {% if section.paradigm_comparison %}
+            <div class="paradigm-comparison">
+                <h4>The Paradigm Shift</h4>
+                <div class="comparison-grid">
+                    {% for category in section.paradigm_comparison.categories %}
+                    <div class="comparison-row">
+                        <div class="category-name">{{ category.name }}</div>
+                        <div class="before">{{ category.before }}</div>
+                        <div class="after">{{ category.after }}</div>
+                        <div class="improvement">{{ category.improvement }}</div>
+                    </div>
+                    {% endfor %}
+                </div>
+            </div>
+            {% endif %}
+
+            {% if section.role_transformation %}
+            <div class="role-transformation">
+                <h4>Your Role Evolution</h4>
+                <div class="transformation-grid">
+                    <div class="old-role">
+                        <h5>{{ section.role_transformation.old_role.title }}</h5>
+                        <ul>
+                            {% for char in section.role_transformation.old_role.characteristics %}
+                            <li>{{ char }}</li>
+                            {% endfor %}
+                        </ul>
+                    </div>
+                    <div class="transformation-arrow">→</div>
+                    <div class="new-role">
+                        <h5>{{ section.role_transformation.new_role.title }}</h5>
+                        <ul>
+                            {% for char in section.role_transformation.new_role.characteristics %}
+                            <li>{{ char }}</li>
+                            {% endfor %}
+                        </ul>
+                    </div>
+                </div>
+                {% if section.role_transformation.transformation_message %}
+                <p class="transformation-message">{{ section.role_transformation.transformation_message }}</p>
+                {% endif %}
+            </div>
+            {% endif %}
+        </div>
+    </div>
+</section>
\ No newline at end of file
diff --git a/website_generator/templates/sections/setup.html b/website_generator/templates/sections/setup.html
new file mode 100644
index 00000000..a5817d8c
--- /dev/null
+++ b/website_generator/templates/sections/setup.html
@@ -0,0 +1,50 @@
+<section class="setup-section" id="setup">
+    <div class="container">
+        <h2 class="section-title">Progressive Setup</h2>
+        <p class="section-description">Choose your learning path based on available time</p>
+
+        <div class="setup-tiers">
+            {% for tier in section.tiers %}
+            <div class="tier-card" data-tier="{{ loop.index }}">
+                <div class="tier-header">
+                    <h3 class="tier-name">{{ tier.name }}</h3>
+                    <span class="tier-duration">{{ tier.duration }}</span>
+                </div>
+                <p class="tier-description">{{ tier.description }}</p>
+                <p class="tier-focus"><strong>Focus:</strong> {{ tier.focus }}</p>
+
+                {% if tier.steps %}
+                <ol class="tier-steps">
+                    {% for step in tier.steps %}
+                    <li>{{ step }}</li>
+                    {% endfor %}
+                </ol>
+                {% endif %}
+
+                {% if tier.demo_command %}
+                <div class="tier-demo">
+                    <strong>Try this:</strong>
+                    <code>{{ tier.demo_command }}</code>
+                    {% if tier.expected_result %}
+                    <p><em>Expected: {{ tier.expected_result }}</em></p>
+                    {% endif %}
+                </div>
+                {% endif %}
+
+                {% if tier.mastery_features %}
+                <div class="mastery-features">
+                    <strong>What you'll master:</strong>
+                    <ul>
+                        {% for feature in tier.mastery_features %}
+                        <li>{{ feature }}</li>
+                        {% endfor %}
+                    </ul>
+                </div>
+                {% endif %}
+
+                <button class="btn btn-outline tier-btn">Start {{ tier.name }}</button>
+            </div>
+            {% endfor %}
+        </div>
+    </div>
+</section>
\ No newline at end of file
diff --git a/website_generator/test_complete_website.py b/website_generator/test_complete_website.py
new file mode 100644
index 00000000..10b2aec2
--- /dev/null
+++ b/website_generator/test_complete_website.py
@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""
+Test complete website generation: analyze → configure → generate content → create templates → render HTML + CSS
+"""
+
+import json
+import sys
+from pathlib import Path
+
+# Add src to path
+sys.path.append(str(Path(__file__).parent / "src"))
+
+from analyzer.repo_analyzer import RepositoryAnalyzer
+from config_loader import ConfigLoader
+from content.content_generator import ContentGenerator
+from content.template_engine import TemplateEngine
+from style.css_generator import CSSGenerator
+
+
+def test_complete_website_generation():
+    """Test the complete website generation pipeline"""
+
+    print("🌐 Testing Complete Website Generation Pipeline")
+    print("=" * 60)
+
+    output_dir = Path(__file__).parent / "output" / "amplifier_website"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        # Step 1: Analyze Amplifier repository
+        print("1. 📊 Analyzing Amplifier repository...")
+        repo_path = "/mnt/c/Users/samschillace/amplifier"
+        analyzer = RepositoryAnalyzer(repo_path)
+        analysis = analyzer.analyze_repository()
+
+        print(f"   ✓ Detected paradigm: {analysis.paradigm_type.value}")
+        print(f"   ✓ Found {len(analysis.agents)} agents")
+        print(f"   ✓ Found {len(analysis.commands)} commands")
+        print(f"   ✓ Complexity score: {analysis.complexity_score}")
+
+        # Step 2: Load configuration
+        print("\n2. ⚙️ Loading configuration...")
+        loader = ConfigLoader()
+        amplifier_config_path = Path(__file__).parent / "examples" / "amplifier_config.yaml"
+        config = loader.load_full_config(str(amplifier_config_path))
+
+        print(f"   ✓ Site name: {config.site['name']}")
+        print(f"   ✓ Theme: {config.site['theme']}")
+        print(f"   ✓ Pages to generate: {len(config.pages)}")
+
+        # Step 3: Generate content
+        print("\n3. 📝 Generating website content...")
+        content_generator = ContentGenerator(config)
+        content = content_generator.generate_content(analysis)
+
+        print(f"   ✓ Revolution section: {content.revolution_section.title}")
+        print(f"   ✓ Setup tiers: {len(content.progressive_setup.tiers)}")
+        print(f"   ✓ Agent showcase: {content.agent_showcase.total_count} agents")
+        print(f"   ✓ Hero section: {content.hero_section['title']}")
+
+        # Step 4: Initialize template engine
+        print("\n4. 🎨 Setting up template engine...")
+        templates_dir = output_dir / "templates"
+        css_filename = "amplifier-styles.css"
+        template_engine = TemplateEngine(config, str(templates_dir), css_filename)
+        template_engine.create_base_templates()
+
+        print(f"   ✓ Templates created in: {templates_dir}")
+
+        # Step 5: Generate CSS
+        print("\n5. 🎨 Generating CSS stylesheet...")
+        css_generator = CSSGenerator(config)
+        css_path = output_dir / "amplifier-styles.css"
+        css_generator.save_css(str(css_path))
+
+        # Step 6: Generate HTML pages
+        print("\n6. 📄 Generating HTML pages...")
+
+        for page_config in config.pages:
+            page_name = page_config["name"]
+            print(f"   Generating {page_name}.html...")
+
+            # Generate HTML for this page
+            html_content = template_engine.generate_full_page(page_config, content)
+
+            # Save HTML file
+            html_path = output_dir / f"{page_name}.html"
+            with open(html_path, "w", encoding="utf-8") as f:
+                f.write(html_content)
+
+            print(f"   ✓ {page_name}.html ({len(html_content):,} characters)")
+
+        # Step 7: Create additional assets
+        print("\n7. 📁 Creating additional assets...")
+
+        # Create basic JavaScript file
+        js_content = """// Basic website JavaScript
+document.addEventListener('DOMContentLoaded', function() {
+    console.log('Amplifier website loaded');
+
+    // Tab functionality
+    window.showTab = function(tabId, buttonElement) {
+        // Hide all tab contents
+        const tabContents = document.querySelectorAll('.tab-content');
+        tabContents.forEach(content => content.classList.remove('active'));
+
+        // Remove active class from all buttons
+        const tabBtns = document.querySelectorAll('.tab-btn');
+        tabBtns.forEach(btn => btn.classList.remove('active'));
+
+        // Show selected tab and mark button as active
+        const targetTab = document.getElementById(tabId);
+        if (targetTab) {
+            targetTab.classList.add('active');
+        }
+
+        if (buttonElement) {
+            buttonElement.classList.add('active');
+        }
+    };
+
+    // Counter animation
+    const animateCounters = () => {
+        const counters = document.querySelectorAll('[data-counter]');
+        counters.forEach(counter => {
+            const target = parseInt(counter.getAttribute('data-counter'));
+            const duration = 2000;
+            const start = performance.now();
+
+            const updateCounter = (currentTime) => {
+                const elapsed = currentTime - start;
+                const progress = Math.min(elapsed / duration, 1);
+                const easeOut = 1 - Math.pow(1 - progress, 3);
+                const current = Math.floor(target * easeOut);
+
+                counter.textContent = current.toLocaleString();
+
+                if (progress < 1) {
+                    requestAnimationFrame(updateCounter);
+                }
+            };
+
+            requestAnimationFrame(updateCounter);
+        });
+    };
+
+    // Trigger counter animation when revolution section is visible
+    const revolutionSection = document.getElementById('revolution');
+    if (revolutionSection) {
+        const observer = new IntersectionObserver((entries) => {
+            entries.forEach(entry => {
+                if (entry.isIntersecting) {
+                    animateCounters();
+                    observer.unobserve(entry.target);
+                }
+            });
+        }, { threshold: 0.5 });
+
+        observer.observe(revolutionSection);
+    }
+
+    // Smooth scrolling for navigation links
+    const navLinks = document.querySelectorAll('a[href^="#"]');
+    navLinks.forEach(link => {
+        link.addEventListener('click', function(e) {
+            e.preventDefault();
+            const targetId = this.getAttribute('href');
+            const targetElement = document.querySelector(targetId);
+
+            if (targetElement) {
+                const headerHeight = 80; // Approximate header height
+                const targetPosition = targetElement.offsetTop - headerHeight;
+
+                window.scrollTo({
+                    top: targetPosition,
+                    behavior: 'smooth'
+                });
+            }
+        });
+    });
+});"""
+
+        js_path = output_dir / "script.js"
+        with open(js_path, "w", encoding="utf-8") as f:
+            f.write(js_content)
+        print(f"   ✓ script.js ({len(js_content):,} characters)")
+
+        # Create a simple README for the generated website
+        readme_content = f"""# Generated Amplifier Website
+
+This website was automatically generated using the Website Generator tool.
+
+## Generated Files
+
+- `index.html` - Main homepage
+- `setup.html` - Setup and installation guide
+- `agents.html` - Agent showcase
+- `amplifier-styles.css` - Complete stylesheet
+- `script.js` - Interactive JavaScript
+
+## Site Information
+
+- **Project**: {config.site["name"]}
+- **Theme**: {config.site["theme"]}
+- **Paradigm Type**: {analysis.paradigm_type.value}
+- **Agents**: {len(analysis.agents)}
+- **Commands**: {len(analysis.commands)}
+- **Complexity Score**: {analysis.complexity_score}
+
+## Generation Summary
+
+- **Revolution Section**: ✓ Generated with capability multipliers
+- **Progressive Setup**: ✓ {len(content.progressive_setup.tiers)} tiers
+- **Agent Showcase**: ✓ {content.agent_showcase.total_count} agents in {len(content.agent_showcase.agent_categories)} categories
+- **Responsive Design**: ✓ Mobile, tablet, desktop breakpoints
+- **Animations**: ✓ {config.design_system["animation_level"]} level animations
+
+## View the Website
+
+1. Open `index.html` in a web browser
+2. Or serve with a local server:
+   ```bash
+   python -m http.server 8000
+   ```
+
+Generated on {content.hero_section.get("title", "Unknown Date")}
+"""
+
+        readme_path = output_dir / "README.md"
+        with open(readme_path, "w", encoding="utf-8") as f:
+            f.write(readme_content)
+        print("   ✓ README.md")
+
+        # Step 8: Generate summary report
+        print("\n8. 📋 Generating summary report...")
+
+        summary_report = {
+            "generation_info": {
+                "timestamp": "2025-01-24",
+                "repository_analyzed": repo_path,
+                "config_used": str(amplifier_config_path),
+            },
+            "analysis_results": {
+                "paradigm_type": analysis.paradigm_type.value,
+                "agents_found": len(analysis.agents),
+                "commands_found": len(analysis.commands),
+                "complexity_score": analysis.complexity_score,
+                "paradigm_indicators": analysis.paradigm_indicators,
+            },
+            "content_generated": {
+                "has_revolution_section": content.revolution_section is not None,
+                "setup_tiers": len(content.progressive_setup.tiers),
+                "featured_agents": len(content.agent_showcase.featured_agents),
+                "agent_categories": list(content.agent_showcase.agent_categories.keys()),
+                "total_agents": content.agent_showcase.total_count,
+            },
+            "files_generated": {
+                "html_pages": len(config.pages),
+                "css_file": "amplifier-styles.css",
+                "js_file": "script.js",
+                "templates_created": True,
+                "readme_included": True,
+            },
+        }
+
+        report_path = output_dir / "generation_report.json"
+        with open(report_path, "w", encoding="utf-8") as f:
+            json.dump(summary_report, f, indent=2, ensure_ascii=False)
+
+        print("   ✓ generation_report.json")
+
+        # Final summary
+        print("\n✅ Complete website generation successful!")
+        print("=" * 60)
+        print(f"📁 Output directory: {output_dir}")
+        print("🌐 Website files generated:")
+
+        for file_path in output_dir.rglob("*"):
+            if file_path.is_file():
+                rel_path = file_path.relative_to(output_dir)
+                size = file_path.stat().st_size
+                print(f"   • {rel_path} ({size:,} bytes)")
+
+        print("\n🚀 To view the website:")
+        print(f"   1. cd {output_dir}")
+        print("   2. python -m http.server 8000")
+        print("   3. Open http://localhost:8000")
+
+        print("\n🎯 Key Features Generated:")
+        if content.revolution_section:
+            print(
+                f"   • Revolution section with {len(content.revolution_section.multiplier_effect['metrics'])} capability multipliers"
+            )
+            print(
+                f"   • Role transformation: {content.revolution_section.role_transformation['old_role']['title']} → {content.revolution_section.role_transformation['new_role']['title']}"
+            )
+        print(f"   • Progressive setup with {len(content.progressive_setup.tiers)} tiers")
+        print(
+            f"   • {content.agent_showcase.total_count} agents organized into {len(content.agent_showcase.agent_categories)} categories"
+        )
+        print(f"   • Responsive design with {len(config.responsive.get('breakpoints', {}))} breakpoints")
+        print(f"   • {config.design_system['animation_level']} level animations")
+
+        return True
+
+    except Exception as e:
+        print(f"❌ Website generation failed: {e}")
+        import traceback
+
+        traceback.print_exc()
+        return False
+
+
+if __name__ == "__main__":
+    test_complete_website_generation()
diff --git a/website_generator/test_full_generation.py b/website_generator/test_full_generation.py
new file mode 100644
index 00000000..644cf339
--- /dev/null
+++ b/website_generator/test_full_generation.py
@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+Test full content generation pipeline with real Amplifier data.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+# Add src to path
+sys.path.append(str(Path(__file__).parent / "src"))
+
+from analyzer.repo_analyzer import RepositoryAnalyzer
+from config_loader import ConfigLoader
+from content.content_generator import ContentGenerator
+
+
+def test_full_pipeline():
+    """Test the complete pipeline: analyze → configure → generate content"""
+
+    print("🚀 Testing Full Website Generation Pipeline")
+    print("=" * 50)
+
+    # Step 1: Analyze Amplifier repository
+    print("1. Analyzing Amplifier repository...")
+    repo_path = "/mnt/c/Users/samschillace/amplifier"
+    analyzer = RepositoryAnalyzer(repo_path)
+    analysis = analyzer.analyze_repository()
+
+    print(f"   ✓ Found {len(analysis.agents)} agents")
+    print(f"   ✓ Found {len(analysis.commands)} commands")
+    print(f"   ✓ Paradigm type: {analysis.paradigm_type.value}")
+    print(f"   ✓ Complexity score: {analysis.complexity_score}")
+
+    # Step 2: Load configuration
+    print("\n2. Loading configuration...")
+    loader = ConfigLoader()
+    amplifier_config_path = Path(__file__).parent / "examples" / "amplifier_config.yaml"
+    config = loader.load_full_config(str(amplifier_config_path))
+
+    print(f"   ✓ Loaded config for: {config.site['name']}")
+    print(f"   ✓ Theme: {config.site['theme']}")
+    print(f"   ✓ Pages: {len(config.pages)}")
+
+    # Step 3: Generate content
+    print("\n3. Generating website content...")
+    generator = ContentGenerator(config)
+    content = generator.generate_content(analysis)
+
+    print(f"   ✓ Generated revolution section: {content.revolution_section.title}")
+    print(f"   ✓ Created {len(content.progressive_setup.tiers)} setup tiers")
+    print(f"   ✓ Showcased {content.agent_showcase.total_count} agents")
+    print(f"   ✓ Agent categories: {list(content.agent_showcase.agent_categories.keys())}")
+
+    # Step 4: Display sample generated content
+    print("\n4. Sample Generated Content:")
+    print("-" * 30)
+
+    if content.revolution_section:
+        print("🎯 Revolution Section:")
+        print(f"   Title: {content.revolution_section.title}")
+        print(f"   Subtitle: {content.revolution_section.subtitle}")
+        print(f"   Problem: {content.revolution_section.problem_statement[:100]}...")
+
+        # Show multiplier effects
+        print("\n📊 Capability Multipliers:")
+        for metric in content.revolution_section.multiplier_effect["metrics"]:
+            if metric.get("inverse"):
+                print(
+                    f"   • {metric['name']}: {metric['old_value']} → {metric['new_value']} {metric['unit']} ({metric['multiplier']}x faster)"
+                )
+            else:
+                print(
+                    f"   • {metric['name']}: {metric['old_value']} → {metric['new_value']} {metric['unit']} ({metric['multiplier']}x)"
+                )
+
+    print("\n🏗️ Progressive Setup:")
+    for i, tier in enumerate(content.progressive_setup.tiers, 1):
+        print(f"   {i}. {tier['name']} ({tier['duration']})")
+        print(f"      Focus: {tier['focus']}")
+        if "demo_command" in tier:
+            print(f"      Demo: {tier['demo_command']}")
+
+    print("\n🤖 Agent Showcase:")
+    print(f"   Total agents: {content.agent_showcase.total_count}")
+    for category, agents in content.agent_showcase.agent_categories.items():
+        print(f"   {category}: {len(agents)} agents")
+
+    print("\n🎨 Hero Section:")
+    hero = content.hero_section
+    print(f"   Title: {hero['title']}")
+    print(f"   Tagline: {hero['tagline']}")
+    print(f"   Features: {', '.join(hero['features_preview'])}")
+
+    # Step 5: Export analysis and content for inspection
+    print("\n5. Exporting results...")
+
+    # Save analysis
+    analysis_output = Path(__file__).parent / "output" / "amplifier_analysis.json"
+    analysis_output.parent.mkdir(exist_ok=True)
+    analyzer.save_analysis(analysis, str(analysis_output))
+
+    # Save generated content as JSON for inspection
+    content_output = Path(__file__).parent / "output" / "generated_content.json"
+    content_dict = {
+        "revolution_section": {
+            "title": content.revolution_section.title,
+            "subtitle": content.revolution_section.subtitle,
+            "problem_statement": content.revolution_section.problem_statement,
+            "paradigm_comparison": content.revolution_section.paradigm_comparison,
+            "multiplier_effect": content.revolution_section.multiplier_effect,
+            "role_transformation": content.revolution_section.role_transformation,
+        }
+        if content.revolution_section
+        else None,
+        "progressive_setup": {"tiers": content.progressive_setup.tiers},
+        "agent_showcase": {
+            "featured_agents": content.agent_showcase.featured_agents,
+            "agent_categories": content.agent_showcase.agent_categories,
+            "total_count": content.agent_showcase.total_count,
+        },
+        "hero_section": content.hero_section,
+        "overview_section": content.overview_section,
+        "examples_section": content.examples_section,
+    }
+
+    with open(content_output, "w", encoding="utf-8") as f:
+        json.dump(content_dict, f, indent=2, ensure_ascii=False)
+
+    print(f"   ✓ Analysis saved to: {analysis_output}")
+    print(f"   ✓ Content saved to: {content_output}")
+
+    print("\n✅ Full pipeline test completed successfully!")
+    print("📁 Check the output/ directory for detailed results")
+
+    return True
+
+
+if __name__ == "__main__":
+    try:
+        test_full_pipeline()
+    except Exception as e:
+        print(f"❌ Pipeline test failed: {e}")
+        import traceback
+
+        traceback.print_exc()