diff --git a/.env.example b/.env.example
index d2c7200..f852d23 100644
--- a/.env.example
+++ b/.env.example
@@ -37,3 +37,7 @@ GIT_AUTO_PUSH=false  # Automatically push commits to remote
 MAX_CONCURRENT_REQUESTS=5
 STREAMING_ENABLED=false
 ENABLE_CHECKPOINTS=true
+
+# IRC Configuration
+NEXT_PUBLIC_IRC_WS_URL=ws://localhost:8080
+NEXT_PUBLIC_IRC_CHANNEL=#devussy-chat
diff --git a/.gitignore b/.gitignore
index f7e5023..021602a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -64,7 +64,6 @@ QUICK_SETUP.md
 START_HERE.txt
 
 # Generated project outputs (in root)
-/devplan.md
 /handoff_prompt.md
 /project_design.md
 /phase*.md
@@ -116,3 +115,4 @@ yarn-error.log*
 .yarn/
 dist/
 .vite/
+devussy-web/streaming_server/analytics.db
diff --git a/AGENTS.md b/AGENTS.md
index 3543a90..2bf7fcf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,6 +2,62 @@
 
 This file provides guidance to agents when working with code in this repository.
 
+## 🔗 CRITICAL: Anchor-Based Context Management
+
+> **⚠️ READ THIS FIRST - This is the most important pattern in this project.**
+
+Devussy uses **stable HTML comment anchors** for efficient context management and safe file updates. **All agents MUST use anchors** when reading/writing devplan, phase, and handoff files.
+
+### Required Anchors
+
+| File | Anchor | Purpose |
+|------|--------|---------|
+| devplan.md | `<!-- PROGRESS_LOG_START -->` / `<!-- PROGRESS_LOG_END -->` | Track completed work |
+| devplan.md | `<!-- NEXT_TASK_GROUP_START -->` / `<!-- NEXT_TASK_GROUP_END -->` | Current 3-5 tasks to execute |
+| phase*.md | `<!-- PHASE_TASKS_START -->` / `<!-- PHASE_TASKS_END -->` | Phase-specific tasks |
+| phase*.md | `<!-- PHASE_PROGRESS_START -->` / `<!-- PHASE_PROGRESS_END -->` | Outcomes and blockers |
+| handoff_prompt.md | `<!-- QUICK_STATUS_START -->` / `<!-- QUICK_STATUS_END -->` | Status snapshot |
+| handoff_prompt.md | `<!-- HANDOFF_NOTES_START -->` / `<!-- HANDOFF_NOTES_END -->` | Agent handoff notes |
+
+### How to Use Anchors
+
+**Reading (CORRECT):**
+```
+Read devplan.md lines between <!-- NEXT_TASK_GROUP_START --> and <!-- NEXT_TASK_GROUP_END -->
+# Result: ~100 tokens loaded
+```
+
+**Reading (WRONG):**
+```
+Read entire devplan.md
+# Result: ~3000 tokens wasted
+```
+
+**Writing:** Always use `safe_write_devplan()` from `src/file_manager.py`:
+- Creates `.bak` backup before writing
+- Validates anchors exist in new content
+- Refuses to overwrite if anchors missing (writes to `.tmp` instead)
+
+### Token Budget
+
+| File | Section | ~Tokens | When to Read |
+|------|---------|---------|--------------|
+| handoff.md | Progress Log | ~200 | Start of session |
+| devplan.md | NEXT_TASK_GROUP | ~100 | Every turn |
+| devplan.md | PROGRESS_LOG | ~100 | If needed |
+| phase*.md | PHASE_TASKS | ~80 | When working on phase |
+
+**Target: Stay under 500 tokens per turn by reading ONLY anchored sections.**
+
+### Validation
+
+`file_manager.py:_validate_devplan_content()` enforces:
+- Header: `# Development Plan` or `## 📋 Project Dashboard`
+- Phase table: `### 🚀 Phase Overview` with `| Phase |`
+- Anchors: `<!-- PROGRESS_LOG_START -->` and `<!-- NEXT_TASK_GROUP_START -->`
+
+---
+
 ## Critical Commands (Non-Obvious)
 - **Test single file**: `pytest tests/unit/test_cli.py::TestGenerateDesignCommand::test_generate_design_minimal_args -v`
 - **Run integration tests**: `pytest tests/integration/ -v`  
diff --git a/DevDocs/JINJA_DATA_SAMPLES/basic_devplan.jinja.json b/DevDocs/JINJA_DATA_SAMPLES/basic_devplan.jinja.json
index 62333c6..6bda84d 100644
--- a/DevDocs/JINJA_DATA_SAMPLES/basic_devplan.jinja.json
+++ b/DevDocs/JINJA_DATA_SAMPLES/basic_devplan.jinja.json
@@ -1,83 +1,33 @@
 {
-  "repo_context": {
-    "project_type": "python",
-    "structure": {
-      "source_dirs": [
-        "src"
-      ],
-      "test_dirs": [
-        "tests"
-      ],
-      "config_dirs": [
-        "config"
-      ],
-      "has_ci": true
-    },
-    "dependencies": {
-      "python": [
-        "fastapi",
-        "uvicorn"
-      ]
-    },
-    "metrics": {
-      "total_files": 42,
-      "total_lines": 1337
-    },
-    "patterns": {
-      "test_frameworks": [
-        "pytest"
-      ],
-      "build_tools": [
-        "poetry"
-      ]
-    },
-    "project_name": "ExistingApp",
-    "description": "An existing app",
-    "version": "1.0.0",
-    "author": "Dev"
-  },
   "project_design": {
-    "project_name": "SuperApp",
-    "languages": [
-      "Python",
-      "TypeScript"
-    ],
-    "frameworks": [
-      "FastAPI",
-      "React"
-    ],
-    "apis": [
-      "OpenAI",
-      "Stripe"
-    ],
-    "requirements": "Build a scalable web app.",
+    "project_name": "test-project",
     "objectives": [
-      "High performance",
-      "User friendly"
+      "Build web application",
+      "Create API"
     ],
     "tech_stack": [
-      "Python 3.11",
-      "React 18",
+      "Python",
+      "FastAPI",
       "PostgreSQL"
     ],
-    "architecture_overview": "Microservices architecture...",
+    "architecture_overview": "Test architecture overview",
     "dependencies": [
-      "sqlalchemy",
-      "pydantic"
+      "requests",
+      "pydantic",
+      "uvicorn"
     ],
     "challenges": [
-      "Concurrency",
-      "Data consistency"
+      "Performance optimization",
+      "Scalability"
     ],
     "mitigations": [
-      "Use async/await",
-      "Use transactions"
+      "Use caching",
+      "Load balancing"
     ],
-    "complexity": "Medium",
-    "estimated_phases": 5
+    "raw_llm_response": null,
+    "complexity": null,
+    "estimated_phases": null
   },
-  "code_samples": "def hello(): pass",
-  "interactive_session": {
-    "question_count": 5
-  }
+  "task_group_size": 3,
+  "detail_level": "normal"
 }
\ No newline at end of file
diff --git a/DevDocs/JINJA_DATA_SAMPLES/detailed_devplan.jinja.json b/DevDocs/JINJA_DATA_SAMPLES/detailed_devplan.jinja.json
index a4809ad..07e68dc 100644
--- a/DevDocs/JINJA_DATA_SAMPLES/detailed_devplan.jinja.json
+++ b/DevDocs/JINJA_DATA_SAMPLES/detailed_devplan.jinja.json
@@ -1,48 +1,9 @@
 {
-  "repo_context": {
-    "project_type": "python",
-    "structure": {
-      "source_dirs": [
-        "src"
-      ],
-      "test_dirs": [
-        "tests"
-      ],
-      "config_dirs": [
-        "config"
-      ],
-      "has_ci": true
-    },
-    "dependencies": {
-      "python": [
-        "fastapi",
-        "uvicorn"
-      ]
-    },
-    "metrics": {
-      "total_files": 42,
-      "total_lines": 1337
-    },
-    "patterns": {
-      "test_frameworks": [
-        "pytest"
-      ],
-      "build_tools": [
-        "poetry"
-      ]
-    },
-    "project_name": "ExistingApp",
-    "description": "An existing app",
-    "version": "1.0.0",
-    "author": "Dev"
-  },
-  "phase_number": 1,
-  "phase_title": "Setup",
-  "phase_description": "Initialize the project.",
-  "project_name": "SuperApp",
-  "tech_stack": [
-    "Python",
-    "Git"
-  ],
-  "code_samples": "print('hello')"
+  "phase_number": 3,
+  "phase_title": "Phase 3",
+  "phase_description": "",
+  "project_name": "test",
+  "tech_stack": [],
+  "task_group_size": 3,
+  "detail_level": "normal"
 }
\ No newline at end of file
diff --git a/DevDocs/JINJA_DATA_SAMPLES/handoff_prompt.jinja.json b/DevDocs/JINJA_DATA_SAMPLES/handoff_prompt.jinja.json
index dab14dd..e590681 100644
--- a/DevDocs/JINJA_DATA_SAMPLES/handoff_prompt.jinja.json
+++ b/DevDocs/JINJA_DATA_SAMPLES/handoff_prompt.jinja.json
@@ -1,45 +1,9 @@
 {
-  "project_name": "SuperApp",
-  "repo_context": {
-    "project_type": "python",
-    "structure": {
-      "source_dirs": [
-        "src"
-      ],
-      "test_dirs": [
-        "tests"
-      ],
-      "config_dirs": [
-        "config"
-      ],
-      "has_ci": true
-    },
-    "dependencies": {
-      "python": [
-        "fastapi",
-        "uvicorn"
-      ]
-    },
-    "metrics": {
-      "total_files": 42,
-      "total_lines": 1337
-    },
-    "patterns": {
-      "test_frameworks": [
-        "pytest"
-      ],
-      "build_tools": [
-        "poetry"
-      ]
-    },
-    "project_name": "ExistingApp",
-    "description": "An existing app",
-    "version": "1.0.0",
-    "author": "Dev"
-  },
-  "current_phase_number": 2,
-  "current_phase_name": "Core Logic",
-  "next_task_id": "2.1",
-  "next_task_description": "Implement auth",
-  "blockers": "None"
+  "project_name": "TestProject",
+  "current_phase_number": "None",
+  "current_phase_name": "No active phase",
+  "next_task_id": "1.1",
+  "next_task_description": "Initialize project",
+  "blockers": "None known",
+  "detail_level": "normal"
 }
\ No newline at end of file
diff --git a/DevDocs/JINJA_DATA_SAMPLES/project_design.jinja.json b/DevDocs/JINJA_DATA_SAMPLES/project_design.jinja.json
index 3965807..d605dc7 100644
--- a/DevDocs/JINJA_DATA_SAMPLES/project_design.jinja.json
+++ b/DevDocs/JINJA_DATA_SAMPLES/project_design.jinja.json
@@ -1,40 +1,14 @@
 {
-  "project_name": "SuperApp",
+  "project_name": "Test Project",
+  "requirements": [
+    "Req 1",
+    "Req 2"
+  ],
   "languages": [
-    "Python",
-    "TypeScript"
+    "Python"
   ],
   "frameworks": [
-    "FastAPI",
-    "React"
-  ],
-  "apis": [
-    "OpenAI",
-    "Stripe"
-  ],
-  "requirements": "Build a scalable web app.",
-  "objectives": [
-    "High performance",
-    "User friendly"
-  ],
-  "tech_stack": [
-    "Python 3.11",
-    "React 18",
-    "PostgreSQL"
-  ],
-  "architecture_overview": "Microservices architecture...",
-  "dependencies": [
-    "sqlalchemy",
-    "pydantic"
-  ],
-  "challenges": [
-    "Concurrency",
-    "Data consistency"
-  ],
-  "mitigations": [
-    "Use async/await",
-    "Use transactions"
+    "FastAPI"
   ],
-  "complexity": "Medium",
-  "estimated_phases": 5
+  "apis": []
 }
\ No newline at end of file
diff --git a/README.md b/README.md
index 40298a0..ccf3b4d 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,13 @@ Devussy turns a short project idea into a complete, actionable development plan.
 - New **Streaming Options** menu in Settings lets you toggle phases individually without touching config files.
 - Concurrency controls now live in Settings as well (max concurrent API requests / phases).
 
+**📊 Backend web analytics (server-side, opt-out supported)**
+
+- Added a lightweight **server-side analytics module** behind the FastAPI streaming server.
+- Tracks anonymized sessions (hashed IP + user-agent), API calls (endpoint, method, status, latency, sizes), and design inputs for the web UI.
+- All analytics are kept **on the server only** (SQLite), with a simple `/api/analytics/overview` endpoint for internal inspection.
+- Users can set a **“Disable anonymous usage analytics for this browser”** toggle in the Help window, which writes a `devussy_analytics_optout` cookie; when set, both the middleware and design endpoint completely skip analytics logging.
+
 **🧱 Under-the-hood fixes**
 
 - Hardened `LLMInterviewManager` to be explicitly mode-aware (`initial` vs `design_review`).
@@ -344,6 +351,70 @@ Legacy Devussy docs, handoff summaries, and helper scripts have been moved into
 - Code samples included for LLM context
 - Backward compatible (works without repo analysis)
 
+### Adaptive Complexity Pipeline ✅ (NEW)
+
+Devussy now includes an **adaptive complexity system** that intelligently scales output based on project requirements.
+
+**Complexity Analysis:**
+- Automatic project complexity scoring (0-20 scale)
+- Dynamic depth level detection (minimal/standard/detailed)
+- Phase count estimation (3-15 phases based on complexity)
+- Confidence scoring with follow-up question triggers
+- Supports both rule-based (testing) and LLM-driven (production) assessment
+
+**Design Validation System:**
+- 5 validation checks: consistency, completeness, scope alignment, hallucination detection, over-engineering detection
+- Rule-based validation for deterministic testing
+- LLM-powered semantic review for production
+- Auto-correctable issue identification
+- Detailed issue reports with suggestions
+
+**Correction Loop:**
+- Iterative design improvement (max 3 iterations)
+- Automatic correction of identified issues
+- Confidence threshold (0.8) for approval
+- Manual review escalation when needed
+- Full correction history tracking
+
+**Adaptive Output Generation:**
+- Template-based output scaling (minimal/standard/detailed)
+- Dynamic phase count based on complexity
+- Complexity-aware design generator
+- Per-depth-level devplan templates
+
+**Usage:**
+```bash
+# Run adaptive pipeline via CLI
+python -m src.cli run-adaptive-pipeline \
+  --name "My Project" \
+  --languages "Python,TypeScript" \
+  --requirements "Build a REST API" \
+  --validation \
+  --correction
+
+# Or use interview JSON
+python -m src.cli run-adaptive-pipeline \
+  --interview-file interview_data.json
+```
+
+**Web UI Components:**
+- `ComplexityAssessment` - Visual score gauge, depth indicator, phase estimate
+- `ValidationReport` - Issue display with severity, auto-fix badges, LLM review
+- `CorrectionTimeline` - Iteration history with progress tracking
+
+**Testing:**
+```bash
+# Backend adaptive pipeline tests
+pytest tests/integration/test_adaptive_pipeline_e2e.py -v
+pytest tests/integration/test_adaptive_pipeline_orchestrator.py -v
+
+# Frontend component tests
+cd devussy-web && npm test
+
+# Build Storybook for visual components
+cd devussy-web && npm run build-storybook
+```
+
 ### Terminal UI (Phases 4-5) ✅
 **Foundation (Phase 4):**
 - Responsive grid layout (5 cols / 3x2 / 1x5)
@@ -379,6 +450,27 @@ Legacy Devussy docs, handoff summaries, and helper scripts have been moved into
 - Integration tests for full workflows
 - Real-world validation with actual APIs
 
+## Documentation for Agents
+
+> **Important:** If you're an AI agent working on this codebase, read `AGENTS.md` first.
+
+### Anchor-Based Context Management
+
+Devussy uses **stable HTML comment anchors** to enable efficient circular development. All planning/handoff documents contain anchors like:
+
+```markdown
+<!-- PROGRESS_LOG_START -->
+... content ...
+<!-- PROGRESS_LOG_END -->
+```
+
+**Key rules for agents:**
+1. Read ONLY anchored sections, not entire files (saves 90%+ tokens)
+2. Use `safe_write_devplan()` from `src/file_manager.py` for writes (validates anchors, creates backups)
+3. Never remove or modify anchor comments themselves
+
+See `AGENTS.md`, `WARP.md`, and `handoff.md` for comprehensive anchor documentation.
+
 ## Troubleshooting
 - No output files? Ensure the appropriate provider key is set (OPENAI_API_KEY, AETHER_API_KEY, REQUESTY_API_KEY, AGENTROUTER_API_KEY, or GENERIC_API_KEY).
 - Status line missing? Make sure your terminal supports ANSI; non-TTY environments will still print stage lines and progress.
diff --git a/START_HERE.md b/START_HERE.md
index 4828b42..10c53bb 100644
--- a/START_HERE.md
+++ b/START_HERE.md
@@ -4,6 +4,19 @@
 
 ---
 
+## 🔗 CRITICAL: Anchor-Based Context Management
+
+> **⚠️ READ THIS FIRST** before diving into the codebase.
+
+Devussy uses **stable HTML comment anchors** for efficient context management. See `AGENTS.md` for the complete guide.
+
+**Quick rules:**
+1. Read ONLY anchored sections (e.g., `<!-- NEXT_TASK_GROUP_START -->` to `<!-- NEXT_TASK_GROUP_END -->`), not entire files
+2. Use `safe_write_devplan()` from `src/file_manager.py` for all devplan/phase file writes
+3. Never remove anchor comments - they're required for validation
+
+---
+
 ## 🎯 What You Need to Know
 
 ### Status: ✅ PRODUCTION READY
@@ -25,11 +38,11 @@ Polish the application and add remaining features (GitHub, download, persistence
 ### 1. **QUICK_START.md** (2 minutes)
 Start the application and verify it works.
 
-### 2. **HANDOFF_FOR_NEXT_AGENT.md** (15 minutes)
-Complete context on what was done and what needs doing.
+### 2. **handoff.md** (15 minutes)
+Complete context on what was done, adaptive pipeline implementation, and what needs doing.
 
-### 3. **DEVPLAN_FOR_NEXT_AGENT.md** (10 minutes)
-Detailed plan with 10 phases and time estimates.
+### 3. **devplan.md** (10 minutes)
+Detailed plan with phases, progress log, and next task group.
 
 ### 4. **README.md** (5 minutes)
 Project documentation and architecture.
@@ -97,8 +110,8 @@ http://localhost:3000
 ### Check These First
 - Browser console (F12)
 - Backend console
-- `SESSION_HANDOFF.md` - Detailed technical info
-- `HANDOFF_FOR_NEXT_AGENT.md` - Common issues
+- `handoff.md` - Detailed technical info and milestone progress
+- `AGENTS.md` - Anchor-based context management guide
 
 ### Key Files
 - `src/components/pipeline/ExecutionView.tsx` - Execution phase
@@ -127,8 +140,8 @@ Now make it shine! ✨
 ---
 
 **Next Steps**:
-1. Read HANDOFF_FOR_NEXT_AGENT.md
-2. Read DEVPLAN_FOR_NEXT_AGENT.md
-3. Start with Phase 1 (Code Cleanup)
+1. Read handoff.md (especially Milestone 5 for latest updates)
+2. Read devplan.md (check `<!-- NEXT_TASK_GROUP_START -->` section)
+3. Start with Frontend Phase 2 (ComplexityAssessment.tsx)
 
 **Good luck!** 🚀
diff --git a/adaptive_pipeline_llm_ideas.md b/adaptive_pipeline_llm_ideas.md
new file mode 100644
index 0000000..54c22f0
--- /dev/null
+++ b/adaptive_pipeline_llm_ideas.md
@@ -0,0 +1,455 @@
+# Adaptive Pipeline LLM Integration Ideas
+
+This document captures the intended **LLM-backed behavior** for each mocked component in the adaptive pipeline. Once the mock-only backend is stable and tested, this will be the source of truth for designing prompts, schemas, and API integration.
+
+> **IMPORTANT:** The current implementation uses static heuristics as a **testing scaffold**. The production system should use **LLM-driven dynamic assessment** that analyzes actual project requirements holistically rather than mapping to fixed buckets.
+
+---
+
+## Design Philosophy: Mock → LLM Transition
+
+### Why Start with Mocks?
+1. **Deterministic Testing:** Unit tests need predictable outputs
+2. **Fast Iteration:** No API latency during development
+3. **Cost Control:** Avoid token costs while iterating on logic
+4. **Schema Validation:** Prove the data structures work before LLM integration
+
+### Production LLM Behavior Goals
+1. **Holistic Analysis:** LLM considers full project context, not just keyword matching
+2. **Nuanced Scoring:** Complexity factors interact (e.g., "simple CRUD with ML" is more complex than either alone)
+3. **Hidden Complexity Detection:** LLM can identify compliance, security, or scaling requirements not explicitly stated
+4. **Adaptive Follow-Ups:** LLM generates targeted clarification questions based on gaps
+5. **Transparent Reasoning:** LLM explains its complexity assessment for user validation
+
+---
+
+## 1. Complexity Analyzer (`src/interview/complexity_analyzer.py`)
+
+### Current Mock Behavior
+
+- Pure-Python heuristics infer:
+  - `project_type_bucket` from `project_type` string (CLI, API, Web App, SaaS, etc.).
+  - `technical_complexity_bucket` from keywords in `requirements` / `frameworks`.
+  - `integration_bucket` from simple counts of `apis`.
+  - `team_size_bucket` from `team_size` string or number.
+- Computes `score`, `estimated_phase_count`, `depth_level`, and a simple `confidence`.
+
+### Future LLM-Powered Behavior (Production)
+
+The LLM should analyze projects **dynamically** rather than fitting into predefined buckets:
+
+#### Prompt Template (Complexity Assessment)
+```
+You are a senior software architect analyzing a project to determine appropriate development complexity and planning depth.
+
+## Project Information
+- **Project Name:** {project_name}
+- **Description:** {description}
+- **Project Type:** {project_type}
+- **Technical Requirements:** {requirements}
+- **Target Frameworks/Tech Stack:** {frameworks}
+- **External Integrations:** {apis}
+- **Team Size:** {team_size}
+- **Timeline Constraints:** {timeline}
+
+## Additional Context (if available)
+{repository_analysis_summary}
+
+## Your Task
+Analyze this project holistically and provide a complexity assessment. Consider:
+1. How the various complexity factors INTERACT (a simple CRUD + ML integration is more complex than either alone)
+2. Hidden complexity signals like compliance requirements, data sensitivity, or scaling needs
+3. Team experience implications (larger teams need more coordination overhead)
+4. Any unstated assumptions that add complexity
+
+Respond with ONLY valid JSON matching this schema:
+```json
+{
+  "complexity_score": <float 0-20>,
+  "estimated_phase_count": <int 3-15>,
+  "depth_level": "minimal" | "standard" | "detailed",
+  "confidence": <float 0-1>,
+  "rationale": "<markdown string explaining your reasoning>",
+  "complexity_factors": {
+    "project_scope": <1-5>,
+    "technical_depth": <1-5>,
+    "integration_complexity": <0-5>,
+    "team_coordination": <1-3>,
+    "hidden_complexity": <0-3>
+  },
+  "hidden_complexity_flags": ["<list of detected hidden factors>"],
+  "risk_factors": ["<list of identified risks>"],
+  "follow_up_questions": ["<questions to ask if confidence < 0.7>"]
+}
+```
+
+#### Validation Strategy
+```python
+def validate_llm_complexity(llm_result: dict, interview_data: dict) -> ComplexityProfile:
+    # Compute rule-based fallback
+    fallback = rule_based_complexity(interview_data)
+    
+    # Parse LLM result
+    llm_profile = parse_llm_response(llm_result)
+    
+    # Validate score is within reasonable bounds
+    if abs(llm_profile.score - fallback.score) > 3:
+        # Large divergence - flag for review but trust LLM with reduced confidence
+        llm_profile.confidence *= 0.7
+        llm_profile.rationale += "\n\n⚠️ Score differs significantly from heuristic estimate."
+    
+    # Clamp values to valid ranges
+    llm_profile.score = clamp(llm_profile.score, 0, 20)
+    llm_profile.estimated_phase_count = clamp(llm_profile.estimated_phase_count, 3, 15)
+    llm_profile.confidence = clamp(llm_profile.confidence, 0, 1)
+    
+    return llm_profile
+```
+
+---
+
+## 2. Interview Pipeline (`src/interview/interview_pipeline.py`)
+
+### Planned Mock Behavior
+
+- Orchestrator that:
+  - Accepts `LLMInterviewManager` outputs (either `extracted_data` or `to_generate_design_inputs()` result).
+  - Calls `ComplexityAnalyzer.analyze(...)`.
+  - Emits a consolidated object: `{ "inputs": ..., "complexity_profile": ... }`.
+- All data provided directly by tests; **no live LLM calls**.
+
+### Future LLM-Powered Behavior (Ideas)
+
+- Allow an LLM to:
+  - Post-process interview transcripts into a richer, normalized "project brief" before complexity analysis.
+  - Suggest **follow-up questions** when confidence is low or key fields are missing.
+- Prompt concepts:
+  - Given transcript + current `ComplexityProfile`, ask LLM to propose 3–5 targeted clarifying questions and a short explanation of why each matters.
+- Integration:
+  - Expose a `follow_up` mode on `LLMInterviewManager` that uses these questions to drive another micro-interview loop.
+
+---
+
+## 3. Design Validation System
+
+### 3.1 `src/pipeline/design_validator.py` (Rule-Based)
+
+#### Mock Behavior (Planned)
+
+- Deterministic checks only:
+  - Consistency, completeness, scope alignment, hallucination guard (basic string checks), over-engineering heuristics.
+- Returns a `ValidationReport` object with:
+  - `is_valid`, `auto_correctable`, per-check results, and a list of issues.
+
+#### Future LLM Ideas
+
+- Use LLM to:
+  - Classify each issue’s severity and suggest candidate fixes.
+  - Detect more subtle contradictions and missing requirements.
+- Prompt concepts:
+  - Provide design markdown + current issues; ask for a structured refinement plan.
+
+### 3.2 `src/pipeline/llm_sanity_reviewer.py`
+
+#### Mock Behavior (Planned)
+
+- Simple stub that:
+  - Returns a fixed `review_result` with configurable `confidence` and generic comments.
+
+#### Future LLM Ideas
+
+- Dedicated LLM reviewer prompt that:
+  - Scores design on axes (feasibility, consistency, scalability, risk) 0–1.
+  - Produces short bullet lists of **risks**, **assumptions**, and **questions**.
+- Output schema:
+  - `confidence`, `risk_flags`, `suggested_changes`, `notes`.
+
+### 3.3 `src/pipeline/design_correction_loop.py`
+
+#### Mock Behavior (Planned)
+
+- Pure loop that:
+  - Applies deterministic transformations (e.g., tweak text, inject placeholders) to simulate corrections.
+  - Stops after `MAX_ITERATIONS` or when validation + mock review meet thresholds.
+
+#### Future LLM Ideas
+
+- Use LLM to:
+  - Rewrite design sections in-place to resolve specific validation issues.
+  - Preserve structure while adjusting content (headings, phases, bullet lists).
+- Prompt concepts:
+  - "Here is the current design + structured issues; rewrite only the marked sections to address them." with strict JSON or markdown segment outputs.
+
+---
+
+## 4. Adaptive Generators
+
+### 4.1 `src/pipeline/design_generator.py`
+
+#### Mock Behavior (Planned)
+
+- Switches between template variants (minimal/standard/detailed) using stubbed data.
+- No real LLM; uses static fixtures or simple string composition.
+
+#### Future LLM Ideas
+
+- Prompt templates that:
+  - Include `ComplexityProfile`, validation feedback, and interview summary.
+  - Enforce word-count / detail targets per depth level.
+
+### 4.2 `src/pipeline/devplan_generator.py`
+
+#### Mock Behavior (Planned)
+
+- Uses `estimated_phase_count` and depth level to:
+  - Select phase templates.
+  - Generate deterministic placeholder devplans.
+
+#### Future LLM Ideas
+
+- LLM prompts tuned for:
+  - Phase count, per-phase granularity, and explicit assumptions.
+  - Output as structured markdown with anchors required by Devussy.
+
+---
+
+## 5. Main Pipeline Integration (`src/pipeline/main_pipeline.py`)
+
+### Mock Behavior (Planned)
+
+- Compose all pieces:
+  - Interview → Complexity → Design → Validation → Correction → Devplan.
+- All LLM steps replaced with:
+  - Stubs, fixtures, or deterministic generators.
+
+### Future LLM Ideas
+
+- Central configuration for:
+  - Per-stage models (design, devplan, validation/review).
+  - Temperature / max tokens tuned by complexity score.
+- Observability:
+  - Track token usage and latency per stage.
+  - Save raw prompts/responses for debugging (behind a flag).
+
+---
+
+## 6. Migration Strategy: Mock → LLM
+
+### Phase 1: Stabilize Mock Pipeline (CURRENT)
+- [x] All mock components implemented
+- [x] Unit tests passing for deterministic behavior
+- [x] Integration tests for full mock pipeline
+- [ ] Coverage > 85% for adaptive modules
+
+### Phase 2: LLM-Ready Interfaces
+- [ ] Add `LLMProvider` protocol to complexity analyzer
+- [ ] Create `use_llm: bool` flag in pipeline config
+- [ ] Implement fallback chain: LLM → Rule-Based → Error
+- [ ] Add structured logging for LLM responses
+
+### Phase 3: Complexity Analyzer LLM Integration
+- [ ] Create `templates/complexity/assessment_prompt.jinja2`
+- [ ] Implement `LLMComplexityAnalyzer` class
+- [ ] Add response schema validation with Pydantic
+- [ ] Wire to existing `ComplexityAnalyzer` as strategy pattern
+- [ ] A/B test: compare LLM vs heuristic scores on sample projects
+
+### Phase 4: Validation & Correction LLM Integration
+- [ ] Create `templates/validation/sanity_review_prompt.jinja2`
+- [ ] Implement `LLMSanityReviewer.review_with_llm()`
+- [ ] Create `templates/correction/fix_issues_prompt.jinja2`
+- [ ] Test correction loop convergence with real LLM
+
+### Phase 5: Generators LLM Integration
+- [ ] Enhance design generator prompts with complexity awareness
+- [ ] Enhance devplan generator prompts with dynamic phase targets
+- [ ] Add streaming support for real-time generation
+
+---
+
+## 7. LLM Configuration Recommendations
+
+### Model Selection by Stage
+```yaml
+# config/config.yaml additions
+adaptive_pipeline:
+  complexity_analysis:
+    model: "claude-sonnet-4-20250514"  # Fast, good at structured output
+    temperature: 0.3
+    max_tokens: 2000
+  
+  design_validation:
+    model: "claude-sonnet-4-20250514"  # Analytical tasks
+    temperature: 0.2
+    max_tokens: 3000
+  
+  design_correction:
+    model: "claude-sonnet-4-20250514"  # Creative rewriting
+    temperature: 0.5
+    max_tokens: 4000
+  
+  design_generation:
+    model: "claude-sonnet-4-20250514"  # Complex generation
+    temperature: 0.7
+    max_tokens: 8000
+```
+
+### Token Budget by Complexity
+```python
+def get_token_budget(complexity_score: float, stage: str) -> int:
+    """Scale token limits based on project complexity."""
+    base_budgets = {
+        "complexity_analysis": 1500,
+        "design_validation": 2000,
+        "design_generation": 4000,
+        "devplan_generation": 6000,
+    }
+    
+    # Scale up for complex projects
+    multiplier = 1.0 + (complexity_score / 20) * 0.5  # 1.0x - 1.5x
+    return int(base_budgets[stage] * multiplier)
+```
+
+---
+
+## 8. Testing Strategy for LLM Integration
+
+### Unit Tests (Mock LLM)
+```python
+@pytest.fixture
+def mock_llm_response():
+    return {
+        "complexity_score": 7.5,
+        "estimated_phase_count": 5,
+        "depth_level": "standard",
+        "confidence": 0.85,
+        "rationale": "Medium-complexity web app with auth..."
+    }
+
+def test_llm_complexity_parsing(mock_llm_response):
+    analyzer = LLMComplexityAnalyzer(llm_client=MockClient())
+    profile = analyzer.analyze(sample_interview_data)
+    assert profile.score == 7.5
+    assert profile.depth_level == "standard"
+```
+
+### Integration Tests (Real LLM, Limited)
+```python
+@pytest.mark.e2e
+@pytest.mark.slow
+def test_real_llm_complexity_analysis():
+    """Run with real LLM to validate prompt quality."""
+    analyzer = LLMComplexityAnalyzer(llm_client=RealClient())
+    profile = analyzer.analyze(SAMPLE_COMPLEX_PROJECT)
+    
+    # Validate structure, not exact values
+    assert 0 <= profile.score <= 20
+    assert 3 <= profile.estimated_phase_count <= 15
+    assert profile.confidence > 0.5
+    assert len(profile.rationale) > 100
+```
+
+### Golden Master Tests
+```python
+def test_llm_output_stability():
+    """Ensure LLM outputs don't regress in quality."""
+    profile = analyzer.analyze(GOLDEN_PROJECT_DATA)
+    
+    # Compare against saved golden output
+    with open("tests/golden/complex_project_profile.json") as f:
+        golden = json.load(f)
+    
+    # Allow some variance but flag large changes
+    assert abs(profile.score - golden["score"]) <= 2
+    assert profile.depth_level == golden["depth_level"]
+```
+
+---
+
+## 9. Error Handling & Fallbacks
+
+```python
+class AdaptiveComplexityAnalyzer:
+    """Combines LLM and rule-based analysis with fallback."""
+    
+    def __init__(self, llm_client, use_llm: bool = True):
+        self.llm_analyzer = LLMComplexityAnalyzer(llm_client)
+        self.rule_analyzer = ComplexityAnalyzer()  # Current implementation
+        self.use_llm = use_llm
+    
+    def analyze(self, interview_data: dict) -> ComplexityProfile:
+        if not self.use_llm:
+            return self.rule_analyzer.analyze(interview_data)
+        
+        try:
+            llm_profile = self.llm_analyzer.analyze(interview_data)
+            rule_profile = self.rule_analyzer.analyze(interview_data)
+            
+            # Validate LLM output against rules
+            return self._reconcile(llm_profile, rule_profile)
+        
+        except LLMError as e:
+            logger.warning(f"LLM analysis failed, using rule-based: {e}")
+            return self.rule_analyzer.analyze(interview_data)
+    
+    def _reconcile(self, llm: ComplexityProfile, rule: ComplexityProfile) -> ComplexityProfile:
+        """Reconcile LLM and rule-based results."""
+        score_diff = abs(llm.score - rule.score)
+        
+        if score_diff > 5:
+            # Major divergence - log and reduce confidence
+            logger.warning(f"LLM/rule score divergence: {score_diff}")
+            llm.confidence *= 0.5
+            llm.rationale += f"\n\n⚠️ Heuristic estimate: {rule.score:.1f}"
+        
+        return llm
+```
+
+---
+
+## 10. Observability & Debugging
+
+### Prompt Logging
+```python
+class ObservableLLMClient:
+    """Wrapper that logs all LLM interactions."""
+    
+    def generate(self, prompt: str, **kwargs) -> str:
+        request_id = uuid4()
+        
+        # Log request
+        self._log_request(request_id, prompt, kwargs)
+        
+        start = time.time()
+        response = self.inner_client.generate(prompt, **kwargs)
+        latency = time.time() - start
+        
+        # Log response
+        self._log_response(request_id, response, latency)
+        
+        return response
+```
+
+### Metrics to Track
+- Token usage per stage
+- LLM latency per stage
+- Rule vs LLM score divergence
+- Validation failure rates
+- Correction loop iteration counts
+- Confidence score distributions
+
+---
+
+## 11. How to Use This Doc
+
+When ready to integrate LLM:
+
+1. **Pick a module** (start with Complexity Analyzer)
+2. **Create prompt template** from the examples above
+3. **Implement LLM variant** alongside mock
+4. **Add feature flag** to toggle between them
+5. **Write tests** covering both paths
+6. **Run A/B comparison** on sample projects
+7. **Iterate on prompt** based on quality metrics
+8. **Repeat** for next module
+  - Generate a focused **devplan phase** for LLM integration using these sections as inputs.
diff --git a/adaptive_pipeline_progress.md b/adaptive_pipeline_progress.md
new file mode 100644
index 0000000..c306954
--- /dev/null
+++ b/adaptive_pipeline_progress.md
@@ -0,0 +1,77 @@
+# Adaptive Pipeline Backend Progress
+
+## Status Overview
+
+**Phase 1 (Backend): ✅ COMPLETE**  
+**Phase 2 (Frontend): 🔄 IN PROGRESS**
+
+All backend milestones complete. Frontend integration started with ComplexityAssessment component and FastAPI endpoints.
+
+## Milestone 1: Complexity Analysis System ✅
+
+- [x] `src/interview/complexity_analyzer.py` (pure-Python scoring + phase estimation)
+- [x] `tests/unit/test_complexity_analyzer.py` (rubric + scenario tests)
+- [x] `src/interview/interview_pipeline.py` (wire interview data into `ComplexityAnalyzer`)
+- [x] Integration tests: interview → complexity profile (mocked interview data)
+
+## Milestone 2: Design Validation System ✅
+
+- [x] `src/pipeline/design_validator.py` (rule-based checks, no LLM calls)
+- [x] `src/pipeline/llm_sanity_reviewer.py` (interface + mock implementation)
+- [x] `src/pipeline/design_correction_loop.py` (iterative correction orchestrator, mocked)
+- [x] `tests/unit/test_design_validator.py`
+- [x] `tests/unit/test_llm_sanity_reviewer.py`
+- [x] `tests/unit/test_design_correction_loop.py`
+- [x] Integration tests: validation → correction (all mocks)
+
+## Milestone 3: Adaptive Generators ✅
+
+- [x] `src/pipeline/design_generator.py` implemented with complexity-aware branching (mock + template modes)
+- [x] `src/pipeline/devplan_generator.py` implemented with dynamic phase count (mock + template modes)
+- [x] Template variants wired in (minimal / standard / detailed)
+  - `templates/devplan/phase_minimal.jinja2`
+  - `templates/devplan/phase_standard.jinja2`
+  - `templates/devplan/phase_detailed.jinja2`
+  - `templates/design/adaptive_design.jinja2`
+  - `templates/interview/follow_up_questions.jinja2`
+- [x] Unit tests for branching logic using stubbed data (`tests/unit/test_adaptive_design_generator.py`, `tests/unit/test_adaptive_devplan_generator.py`)
+- [x] Follow-up mode added to `src/llm_interview.py` (FOLLOW_UP_SYSTEM_PROMPT, switch_mode, set_follow_up_context, request_clarifications)
+
+## Milestone 4: Pipeline Integration ✅
+
+- [x] `src/pipeline/mock_adaptive_pipeline.py` implements end-to-end mock adaptive pipeline
+- [x] `tests/integration/test_mock_adaptive_pipeline.py` (full adaptive pipeline with mocks only)
+- [x] `tests/harness/pipeline_test_harness.py` and `tests/harness/test_pipeline_test_harness.py` (mock adaptive pipeline scenarios)
+- [x] Main pipeline refactored to integrate new stages (`src/pipeline/compose.py`)
+- [x] Checkpointing extended to new stages (complexity_profile, validation_report, correction_history)
+- [x] Streaming hooks added for new stages ([complexity], [validation], [correction] prefixes)
+- [x] JSON schemas created in `schemas/` directory
+
+## Milestone 5: CLI & E2E Testing ✅
+
+- [x] `run-adaptive-pipeline` CLI command in `src/cli.py`
+- [x] Comprehensive E2E tests in `tests/integration/test_adaptive_pipeline_e2e.py`
+- [x] 87% test coverage on core adaptive modules
+- [x] Real LLM E2E tests (3 passing tests in `TestAdaptivePipelineRealLLM`)
+
+## Milestone 6: Frontend Integration ✅ (Partial)
+
+- [x] `ComplexityAssessment.tsx` component created
+- [x] FastAPI SSE endpoints added to `streaming_server/app.py`:
+  - `POST /api/adaptive/complexity`
+  - `POST /api/adaptive/validate`
+  - `POST /api/adaptive/correct`
+  - `GET /api/adaptive/profile`
+- [ ] Wire ComplexityAssessment into pipeline flow
+- [ ] Create ValidationReport component
+- [ ] Create CorrectionTimeline component
+- [ ] Update frontend state management
+
+---
+
+## Next Steps (Priority Order)
+
+1. **Wire ComplexityAssessment into pipeline flow** - Add to DesignView or create dedicated step
+2. **Create ValidationReport component** - Display validation issues and auto-correction status
+3. **Create CorrectionTimeline component** - Show iteration history from correction loop
+4. **Update frontend state management** - Add complexity/validation stages to pipeline state
diff --git a/HANDOFF_FOR_NEXT_AGENT.md b/archive/HANDOFF_FOR_NEXT_AGENT.md
similarity index 93%
rename from HANDOFF_FOR_NEXT_AGENT.md
rename to archive/HANDOFF_FOR_NEXT_AGENT.md
index eaaf493..453f3f8 100644
--- a/HANDOFF_FOR_NEXT_AGENT.md
+++ b/archive/HANDOFF_FOR_NEXT_AGENT.md
@@ -1,6 +1,17 @@
 # Handoff for Next Agent
 
-## 🚀 Status Update
+## � CRITICAL: Anchor-Based Context Management
+
+> **⚠️ READ THIS FIRST** - This project uses **stable HTML comment anchors** for efficient context management.
+
+See `AGENTS.md` for the complete anchor reference. Key points:
+- Read ONLY anchored sections (e.g., `<!-- NEXT_TASK_GROUP_START -->` to `<!-- NEXT_TASK_GROUP_END -->`), not entire files
+- Use `safe_write_devplan()` from `src/file_manager.py` for writes - it validates anchors and creates backups
+- Target under 500 tokens per turn by reading only what's needed
+
+---
+
+## �🚀 Status Update
 **Current Version**: 0.3.0 (Commit Stage)
 **Branch**: `0.3`
 
diff --git a/archive/START_HERE.md b/archive/START_HERE.md
new file mode 100644
index 0000000..10c53bb
--- /dev/null
+++ b/archive/START_HERE.md
@@ -0,0 +1,147 @@
+# 👋 START HERE - Next Agent
+
+**Welcome!** You're inheriting a fully functional Devussy web frontend.
+
+---
+
+## 🔗 CRITICAL: Anchor-Based Context Management
+
+> **⚠️ READ THIS FIRST** before diving into the codebase.
+
+Devussy uses **stable HTML comment anchors** for efficient context management. See `AGENTS.md` for the complete guide.
+
+**Quick rules:**
+1. Read ONLY anchored sections (e.g., `<!-- NEXT_TASK_GROUP_START -->` to `<!-- NEXT_TASK_GROUP_END -->`), not entire files
+2. Use `safe_write_devplan()` from `src/file_manager.py` for all devplan/phase file writes
+3. Never remove anchor comments - they're required for validation
+
+---
+
+## 🎯 What You Need to Know
+
+### Status: ✅ PRODUCTION READY
+
+The application works end-to-end with real-time streaming. All critical bugs are fixed.
+
+### Your Mission
+
+Polish the application and add remaining features (GitHub, download, persistence).
+
+### Time Estimate
+
+2-5 days depending on scope.
+
+---
+
+## 📚 Read These Documents (In Order)
+
+### 1. **QUICK_START.md** (2 minutes)
+Start the application and verify it works.
+
+### 2. **handoff.md** (15 minutes)
+Complete context on what was done, adaptive pipeline implementation, and what needs doing.
+
+### 3. **devplan.md** (10 minutes)
+Detailed plan with phases, progress log, and next task group.
+
+### 4. **README.md** (5 minutes)
+Project documentation and architecture.
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# Terminal 1 - Backend
+python dev_server.py
+
+# Terminal 2 - Frontend
+cd devussy-web && npm run dev
+
+# Browser
+http://localhost:3000
+```
+
+---
+
+## ✅ What's Working
+
+- ✅ Interview → Design → Plan → Execute pipeline
+- ✅ Real-time SSE streaming
+- ✅ Multi-phase concurrent execution
+- ✅ Editable phase cards
+- ✅ Window management
+
+---
+
+## ⏳ What Needs Work
+
+1. Remove debug logging (1 hour)
+2. Test HandoffView (30 min)
+3. Add error recovery UI (3 hours)
+4. GitHub integration (4 hours)
+5. Download zip (2 hours)
+6. Project persistence (4 hours)
+
+---
+
+## 🎯 Recommended Approach
+
+### Day 1: Polish
+- Remove debug logging
+- Test HandoffView
+- Add error recovery
+- Improve UX
+
+### Day 2: Features
+- GitHub integration
+- Download zip
+- Start persistence
+
+### Day 3: Testing & Deploy
+- Comprehensive testing
+- Documentation updates
+- Deploy to production
+
+---
+
+## 📞 Need Help?
+
+### Check These First
+- Browser console (F12)
+- Backend console
+- `handoff.md` - Detailed technical info and milestone progress
+- `AGENTS.md` - Anchor-based context management guide
+
+### Key Files
+- `src/components/pipeline/ExecutionView.tsx` - Execution phase
+- `src/components/pipeline/PlanView.tsx` - Plan editing
+- `devussy-web/api/plan/detail.py` - Phase generation API
+- `src/pipeline/detailed_devplan.py` - Streaming implementation
+
+---
+
+## 💡 Pro Tips
+
+1. **Test after every change** - Run full pipeline
+2. **Don't break streaming** - It's the core feature
+3. **Use functional state updates** - `setState(prev => ...)`
+4. **Keep SSE format correct** - `\n\n` not `\\n\\n`
+5. **Check both consoles** - Browser and backend
+
+---
+
+## 🎉 You Got This!
+
+The hard work is done. The foundation is solid. Everything works.
+
+Now make it shine! ✨
+
+---
+
+**Next Steps**:
+1. Read handoff.md (especially Milestone 5 for latest updates)
+2. Read devplan.md (check `<!-- NEXT_TASK_GROUP_START -->` section)
+3. Start with Frontend Phase 2 (ComplexityAssessment.tsx)
+
+**Good luck!** 🚀
diff --git a/debug_irc.py b/debug_irc.py
new file mode 100644
index 0000000..94d4592
--- /dev/null
+++ b/debug_irc.py
@@ -0,0 +1,72 @@
+import socket
+import sys
+import time
+import argparse
+
+def debug_irc(host, port):
+    print(f"Connecting to {host}:{port}...")
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.settimeout(10)
+        s.connect((host, port))
+        print("Connected!")
+    except Exception as e:
+        print(f"Failed to connect: {e}")
+        return
+
+    # Send handshake
+    nick = "debug_user"
+    user = "debug_user"
+    realname = "Debug User"
+    
+    # Standard IRC handshake
+    # PASS is optional, but some servers require it. We'll skip it for now unless needed.
+    # s.sendall(b"PASS somepassword\r\n")
+    
+    print(f"Sending NICK {nick}")
+    s.sendall(f"NICK {nick}\r\n".encode('utf-8'))
+    
+    print(f"Sending USER {user} 0 * :{realname}")
+    s.sendall(f"USER {user} 0 * :{realname}\r\n".encode('utf-8'))
+
+    # Listen for response
+    buffer = b""
+    while True:
+        try:
+            data = s.recv(4096)
+            if not data:
+                print("Connection closed by server.")
+                break
+            
+            buffer += data
+            while b"\r\n" in buffer:
+                line, buffer = buffer.split(b"\r\n", 1)
+                decoded_line = line.decode('utf-8', errors='replace')
+                print(f"RECV: {decoded_line}")
+                
+                # Handle PING to keep connection alive if we get that far
+                if decoded_line.startswith("PING"):
+                    pong_response = decoded_line.replace("PING", "PONG", 1)
+                    print(f"SEND: {pong_response}")
+                    s.sendall(f"{pong_response}\r\n".encode('utf-8'))
+                    
+        except socket.timeout:
+            print("Timeout waiting for data.")
+            break
+        except KeyboardInterrupt:
+            print("\nStopping...")
+            break
+        except Exception as e:
+            print(f"Error: {e}")
+            break
+
+    s.close()
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description='Debug IRC connection.')
+    parser.add_argument('host', nargs='?', default='localhost', help='IRC server host')
+    parser.add_argument('port', nargs='?', default=6667, type=int, help='IRC server port')
+    
+    args = parser.parse_args()
+    
+    debug_irc(args.host, args.port)
diff --git a/devplan.md b/devplan.md
new file mode 100644
index 0000000..3bae65b
--- /dev/null
+++ b/devplan.md
@@ -0,0 +1,2016 @@
+# Devussy Adaptive Complexity Pipeline - Complete DevPlan
+
+**Project:** Devussy Adaptive Complexity Overhaul  
+**Version:** 2.0  
+**Generated:** 2025-11-25  
+**Scope:** Transform Devussy from static to adaptive complexity-driven pipeline
+
+---
+
+## 🔗 CRITICAL: Anchor-Based Context Management
+
+> **⚠️ ESSENTIAL RULE FOR ALL AGENTS:** This project uses **stable HTML comment anchors** to enable efficient context management. Agents MUST read ONLY the sections bounded by these anchors, NOT the entire file. This is critical for:
+> - Keeping context under 50k tokens
+> - Enabling circular development handoffs
+> - Preventing token overflow and hallucinations
+> - Allowing safe, deterministic file updates
+
+### Required Anchors (All files must preserve these)
+
+**devplan.md anchors:**
+```markdown
+<!-- PROGRESS_LOG_START -->
+... progress entries ...
+<!-- PROGRESS_LOG_END -->
+
+<!-- NEXT_TASK_GROUP_START -->
+... current 3-5 tasks to execute ...
+<!-- NEXT_TASK_GROUP_END -->
+```
+
+**phase*.md anchors:**
+```markdown
+<!-- PHASE_TASKS_START -->
+... phase-specific tasks ...
+<!-- PHASE_TASKS_END -->
+
+<!-- PHASE_PROGRESS_START -->
+... outcomes and blockers ...
+<!-- PHASE_PROGRESS_END -->
+```
+
+**handoff_prompt.md anchors:**
+```markdown
+<!-- QUICK_STATUS_START -->
+... current status snapshot ...
+<!-- QUICK_STATUS_END -->
+
+<!-- HANDOFF_NOTES_START -->
+... handoff-specific notes ...
+<!-- HANDOFF_NOTES_END -->
+```
+
+### How Agents Should Use Anchors
+
+1. **Reading Context:**
+   ```
+   ❌ WRONG: Read entire devplan.md (3000+ lines)
+   ✅ RIGHT: Read only between <!-- NEXT_TASK_GROUP_START --> and <!-- NEXT_TASK_GROUP_END --> (~100 tokens)
+   ```
+
+2. **Updating Files:**
+   - Use `safe_write_devplan()` in `src/file_manager.py` - it validates anchors exist before writing
+   - NEVER delete or modify anchor comments themselves
+   - Content BETWEEN anchors can be replaced freely
+
+3. **File Validation:**
+   - `file_manager.py:_validate_devplan_content()` enforces anchor presence
+   - Files without required anchors will be written to `.tmp` instead of overwriting
+   - Always check for validation failures in logs
+
+### Token Budget Reference
+
+| File | Section | Read Frequency | ~Tokens |
+|------|---------|----------------|---------|
+| devplan.md | NEXT_TASK_GROUP | Every turn | ~100 |
+| devplan.md | PROGRESS_LOG | If needed | ~100 |
+| phase*.md | PHASE_TASKS | When working on phase | ~80 |
+| handoff.md | Progress Log | Start of session | ~200 |
+
+**Target: Stay under 500 tokens per turn by reading ONLY anchored sections.**
+
+---
+
+## Executive Summary
+
+This devplan transforms Devussy from a static one-size-fits-all pipeline into an intelligent, adaptive system that:
+
+1. **Dynamically scales complexity** based on interview analysis
+2. **Performs intermediate reasoning** before generating designs
+3. **Self-validates** through sanity-check loops
+4. **Prevents hallucinations** and over-engineering
+5. **Adapts phase count** and granularity to project scope
+
+**Key Innovation:** Multi-stage interview with complexity assessment → adaptive design generation → sanity-check validation → scaled devplan output.
+
+---
+
+## Phase 1: Backend Workflow Overhaul (High Priority)
+
+**Objective:** Redesign the entire backend pipeline to be iterative, adaptive, and complexity-aware.
+
+### 1.1 Multi-Stage Interview Enhancements
+
+#### 1.1.1 Add Complexity Assessment Stage
+
+**Location:** `src/interview/complexity_analyzer.py` (new file)
+
+**Purpose:** Analyze interview JSON and determine project complexity before design generation.
+
+**Tasks:**
+- Create `ComplexityAnalyzer` class with methods:
+  - `analyze_interview_data(interview_json: dict) -> ComplexityProfile`
+  - `estimate_phase_count(profile: ComplexityProfile) -> int`
+  - `determine_depth_level(profile: ComplexityProfile) -> DepthLevel`
+  - `identify_missing_context() -> List[str]`
+  
+- Define complexity scoring rubric:
+  - **Project Type Score:** CLI tool (1), Library (2), API (3), Web app (4), SaaS (5)
+  - **Technical Complexity Score:** Simple CRUD (1), Auth+DB (2), Real-time (3), ML/AI (4), Multi-region (5)
+  - **Integration Score:** Standalone (0), 1-2 services (1), 3-5 services (2), 6+ services (3)
+  - **Team Size Factor:** Solo (0.5x), 2-3 (1x), 4-6 (1.2x), 7+ (1.5x)
+  
+- Calculate **total complexity score** = (type + technical + integration) × team_factor
+- Map score to phase count:
+  - 0-3: 3 phases (minimal)
+  - 4-7: 5 phases (standard)
+  - 8-12: 7 phases (complex)
+  - 13+: 9-11 phases (enterprise)
+
+**Schema:** `schemas/complexity_profile.json`
+```json
+{
+  "complexity_score": 8.5,
+  "estimated_phases": 7,
+  "depth_level": "detailed",
+  "project_scale": "medium-complex",
+  "risk_factors": ["multi-service", "auth-required"],
+  "recommended_follow_ups": ["clarify deployment strategy", "specify auth provider"],
+  "confidence": 0.85
+}
+```
+
+**Tests:**
+- Unit: `tests/unit/test_complexity_analyzer.py`
+- Integration: `tests/integration/test_interview_to_complexity.py`
+- Test cases: trivial project (score 2), moderate (score 6), complex (score 10)
+
+---
+
+#### 1.1.2 Extend Interview Manager for Follow-Up Questions
+
+**Location:** `src/interview/llm_interview_manager.py` (modify existing)
+
+**Purpose:** Add capability to ask clarifying questions when complexity analyzer detects ambiguity.
+
+**Tasks:**
+- Add new mode: `follow_up` (alongside existing `initial` and `design_review`)
+- Implement `request_clarifications(missing_context: List[str]) -> None`
+- Modify conversation flow:
+  ```python
+  if complexity_profile.confidence < 0.7:
+      manager.switch_mode('follow_up')
+      manager.request_clarifications(profile.recommended_follow_ups)
+  ```
+- Update prompt templates to include:
+  - "Based on your answers, I need clarification on..."
+  - Focused questions (not a full re-interview)
+  - Ability to skip if user says "proceed as-is"
+
+**Templates:** `templates/interview/follow_up_questions.jinja2`
+
+**Tests:**
+- Unit: verify mode switching
+- Integration: full interview → low confidence → follow-up → completion
+
+---
+
+#### 1.1.3 Interview-to-Complexity Pipeline Integration
+
+**Location:** `src/pipeline/interview_pipeline.py` (new file)
+
+**Purpose:** Orchestrate interview → complexity analysis → follow-ups flow.
+
+**Tasks:**
+- Create pipeline coordinator:
+  ```python
+  class InterviewComplexityPipeline:
+      async def run(self) -> ComplexityProfile:
+          interview_data = await self.interview_manager.conduct_interview()
+          profile = self.complexity_analyzer.analyze(interview_data)
+          
+          if profile.confidence < THRESHOLD:
+              clarifications = await self.interview_manager.follow_up(profile.recommended_follow_ups)
+              profile = self.complexity_analyzer.reanalyze(interview_data + clarifications)
+          
+          return profile
+  ```
+- Integrate with existing CLI `interactive` command
+- Save complexity profile to checkpoint: `checkpoints/<project>_complexity.json`
+
+**Tests:**
+- Integration: end-to-end interview with multiple complexity levels
+- Checkpoint persistence and resumability
+
+---
+
+### 1.2 Complexity-Driven Adaptive Pipeline
+
+#### 1.2.1 Adaptive Design Generator
+
+**Location:** `src/pipeline/design_generator.py` (modify existing)
+
+**Purpose:** Generate project designs scaled to complexity profile.
+
+**Tasks:**
+- Modify `generate_design()` to accept `complexity_profile: ComplexityProfile`
+- Update prompt template with complexity directives:
+  ```jinja2
+  {% if complexity_profile.depth_level == "minimal" %}
+  Provide a concise design focusing only on core architecture and critical decisions.
+  Avoid unnecessary detail. Target 500-800 words.
+  {% elif complexity_profile.depth_level == "standard" %}
+  Provide a balanced design covering architecture, tech stack, and key considerations.
+  Target 1000-1500 words.
+  {% elif complexity_profile.depth_level == "detailed" %}
+  Provide comprehensive design including architecture, patterns, deployment, testing strategy.
+  Target 2000-3000 words.
+  {% endif %}
+  
+  Recommended phase count: {{ complexity_profile.estimated_phases }}
+  Project scale: {{ complexity_profile.project_scale }}
+  ```
+- Implement dynamic section inclusion:
+  - Minimal: Architecture, Tech Stack, Core Features
+  - Standard: + Deployment, Testing Strategy, Dependencies
+  - Detailed: + Security, Scalability, Monitoring, CI/CD, Data Model
+  
+**Templates:** `templates/design/adaptive_design.jinja2`
+
+**Tests:**
+- Generate design for complexity scores 2, 6, 10
+- Verify word count and section count match expectations
+- Validate no unnecessary sections for trivial projects
+
+---
+
+#### 1.2.2 Adaptive DevPlan Generator
+
+**Location:** `src/pipeline/devplan_generator.py` (modify existing)
+
+**Purpose:** Generate devplans with phase count and granularity matching complexity.
+
+**Tasks:**
+- Modify `generate_devplan()` to use complexity profile
+- Dynamic phase generation:
+  ```python
+  phase_count = complexity_profile.estimated_phases
+  phases = self.generate_phase_structure(phase_count, complexity_profile.depth_level)
+  ```
+- Adjust task granularity per depth level:
+  - **Minimal:** High-level tasks, 3-5 per phase
+  - **Standard:** Moderate tasks, 5-8 per phase
+  - **Detailed:** Granular tasks, 8-12 per phase
+  
+- Phase naming conventions:
+  - 3 phases: Foundation → Implementation → Polish
+  - 5 phases: Foundation → Core → Integration → Testing → Deployment
+  - 7 phases: Planning → Foundation → Core → Features → Integration → Testing → Deployment
+  - 9+ phases: Add dedicated phases for Auth, Data Layer, API, Frontend, etc.
+
+**Templates:** `templates/devplan/adaptive_phases.jinja2`
+
+**Schema:** Dynamic phase structure based on count
+
+**Tests:**
+- Generate devplans for 3, 5, 7, 9 phase counts
+- Verify task count per phase matches depth level
+- Validate phase naming consistency
+
+---
+
+#### 1.2.3 Template Size Optimization
+
+**Location:** `templates/devplan/` (all phase templates)
+
+**Purpose:** Create size-variant templates for different complexity levels.
+
+**Tasks:**
+- Create template variants:
+  - `phase_minimal.jinja2` - bare essentials
+  - `phase_standard.jinja2` - current format
+  - `phase_detailed.jinja2` - comprehensive
+  
+- Add template selector logic:
+  ```python
+  template_name = f"phase_{complexity_profile.depth_level}.jinja2"
+  ```
+  
+- Minimal template structure:
+  ```jinja2
+  ## Phase {{ phase_number }}: {{ phase_name }}
+  
+  ### Tasks
+  {% for task in tasks %}
+  - {{ task.description }}
+  {% endfor %}
+  
+  ### Testing
+  - {{ test_strategy }}
+  ```
+  
+- Detailed template adds:
+  - Success Criteria
+  - Dependencies
+  - Estimated Time
+  - Risk Mitigation
+  - Code Samples
+  - Architecture Diagrams (when applicable)
+
+**Tests:**
+- Render all template variants
+- Verify size differences (minimal < standard < detailed)
+
+---
+
+### 1.3 Sanity Check Step Before DevPlan
+
+#### 1.3.1 Design Validation Engine
+
+**Location:** `src/pipeline/design_validator.py` (new file)
+
+**Purpose:** Perform automated sanity checks on generated designs before devplan creation.
+
+**Tasks:**
+- Create `DesignValidator` class with validation methods:
+  ```python
+  class DesignValidator:
+      def validate_design(self, design: str, complexity_profile: ComplexityProfile) -> ValidationReport:
+          checks = [
+              self.check_consistency(),
+              self.check_completeness(),
+              self.check_scope_alignment(),
+              self.check_hallucinations(),
+              self.check_over_engineering(),
+          ]
+          return ValidationReport(checks)
+  ```
+
+- **Consistency Check:**
+  - Tech stack matches requirements
+  - No contradicting statements
+  - Dependencies are compatible
+  - Architecture aligns with stated patterns
+
+- **Completeness Check:**
+  - All interview requirements addressed
+  - No missing critical components
+  - Deployment strategy present (if needed)
+  - Testing approach defined
+
+- **Scope Alignment Check:**
+  - Design complexity matches complexity profile
+  - Phase count is reasonable
+  - Not over-engineered for simple projects
+  - Not under-scoped for complex projects
+
+- **Hallucination Detection:**
+  - No invented APIs or libraries (cross-reference with known packages)
+  - No fictional frameworks
+  - Realistic timelines
+  - Achievable with stated tech stack
+
+- **Over-Engineering Detection:**
+  - Complexity score vs design complexity delta < threshold
+  - No unnecessary microservices for small apps
+  - No premature optimization patterns
+  - Appropriate abstractions for project scale
+
+**Schema:** `schemas/validation_report.json`
+```json
+{
+  "is_valid": true,
+  "confidence": 0.92,
+  "issues": [
+    {
+      "severity": "warning",
+      "type": "scope_alignment",
+      "message": "Design suggests 7 phases but complexity profile recommends 5",
+      "suggestion": "Consider reducing scope or clarifying complex requirements"
+    }
+  ],
+  "auto_correctable": true,
+  "corrections_applied": ["adjusted_phase_count_to_5"],
+  "requires_human_review": false
+}
+```
+
+**Tests:**
+- Unit: each validation method independently
+- Integration: full design validation with known-good and known-bad designs
+- Test cases: over-engineered design, missing components, hallucinated libraries
+
+---
+
+#### 1.3.2 LLM-Powered Sanity Reviewer
+
+**Location:** `src/pipeline/llm_sanity_reviewer.py` (new file)
+
+**Purpose:** Use LLM to perform deeper semantic validation of design quality.
+
+**Tasks:**
+- Create `LLMSanityReviewer` class:
+  ```python
+  async def review_design(self, design: str, interview_data: dict, complexity_profile: ComplexityProfile) -> ReviewResult:
+      prompt = self.build_review_prompt(design, interview_data, complexity_profile)
+      review = await self.llm_client.generate(prompt)
+      return self.parse_review_json(review)
+  ```
+
+- Review prompt structure:
+  ```
+  You are a senior software architect reviewing a project design for quality and appropriateness.
+  
+  Project Requirements: {interview_data}
+  Complexity Profile: {complexity_profile}
+  Proposed Design: {design}
+  
+  Evaluate:
+  1. Does design match project requirements? (yes/no + explanation)
+  2. Is complexity appropriate for project scale? (score 1-10)
+  3. Are there hallucinated or unrealistic components? (list)
+  4. Is architecture over-engineered? (yes/no + explanation)
+  5. Missing critical components? (list)
+  6. Recommended changes: (list)
+  
+  Output JSON only.
+  ```
+
+- Parse LLM response into structured `ReviewResult`
+- Support auto-correction for common issues:
+  - Phase count adjustment
+  - Remove unnecessary components
+  - Add missing sections
+
+**Templates:** `templates/validation/sanity_review_prompt.jinja2`
+
+**Tests:**
+- Mock LLM responses for various review scenarios
+- Validate JSON parsing robustness
+- Test auto-correction application
+
+---
+
+#### 1.3.3 Iterative Correction Loop
+
+**Location:** `src/pipeline/design_correction_loop.py` (new file)
+
+**Purpose:** Automatically iterate design until validation passes or max iterations reached.
+
+**Tasks:**
+- Create correction loop orchestrator:
+  ```python
+  class DesignCorrectionLoop:
+      MAX_ITERATIONS = 3
+      
+      async def run(self, initial_design: str, complexity_profile: ComplexityProfile) -> FinalDesign:
+          design = initial_design
+          iteration = 0
+          
+          while iteration < self.MAX_ITERATIONS:
+              validation = await self.validator.validate_design(design, complexity_profile)
+              review = await self.reviewer.review_design(design, self.interview_data, complexity_profile)
+              
+              if validation.is_valid and review.confidence > 0.8:
+                  return FinalDesign(design, validation, review)
+              
+              if validation.auto_correctable:
+                  design = self.apply_corrections(design, validation, review)
+              else:
+                  return FinalDesign(design, validation, review, requires_human=True)
+              
+              iteration += 1
+          
+          return FinalDesign(design, validation, review, max_iterations_reached=True)
+  ```
+
+- Correction strategies:
+  - **Phase count mismatch:** Regenerate design with correct target
+  - **Missing sections:** Add section prompts and regenerate
+  - **Over-engineering:** Simplify prompt and regenerate
+  - **Hallucinations:** Remove problematic components, regenerate
+
+- Save iteration history to checkpoint for transparency
+
+**Tests:**
+- Integration: run full correction loop with various design issues
+- Verify convergence within max iterations
+- Test fallback to human review when auto-correction fails
+
+---
+
+### 1.4 Iteration Loop Integration
+
+#### 1.4.1 Pipeline Orchestration Refactor
+
+**Location:** `src/pipeline/main_pipeline.py` (modify existing)
+
+**Purpose:** Integrate all new components into unified pipeline flow.
+
+**Tasks:**
+- Refactor pipeline to new flow:
+  ```python
+  async def run_adaptive_pipeline(self):
+      # Stage 1: Enhanced Interview
+      interview_data = await self.interview_manager.conduct_interview()
+      
+      # Stage 2: Complexity Analysis
+      complexity_profile = self.complexity_analyzer.analyze(interview_data)
+      if complexity_profile.confidence < 0.7:
+          clarifications = await self.interview_manager.follow_up(complexity_profile.recommended_follow_ups)
+          complexity_profile = self.complexity_analyzer.reanalyze(interview_data + clarifications)
+      
+      # Stage 3: Adaptive Design Generation
+      design = await self.design_generator.generate(complexity_profile)
+      
+      # Stage 4: Design Validation & Correction
+      final_design = await self.correction_loop.run(design, complexity_profile)
+      
+      if final_design.requires_human_review:
+          # Trigger interactive design review mode
+          final_design = await self.human_review_flow(final_design)
+      
+      # Stage 5: Adaptive DevPlan Generation
+      devplan = await self.devplan_generator.generate(final_design, complexity_profile)
+      
+      # Stage 6: Handoff
+      handoff = await self.handoff_generator.generate(devplan, complexity_profile)
+      
+      return PipelineResult(final_design, devplan, handoff)
+  ```
+
+- Update checkpoint system to save all intermediate stages
+- Add resume capability at any stage
+- Preserve iteration history for debugging
+
+**Tests:**
+- End-to-end pipeline test with mock LLM
+- Resume from each stage checkpoint
+- Verify all artifacts generated correctly
+
+---
+
+#### 1.4.2 Streaming Progress Updates
+
+**Location:** `src/pipeline/streaming.py` (modify existing)
+
+**Purpose:** Update streaming handlers to support new pipeline stages.
+
+**Tasks:**
+- Add streaming prefixes for new stages:
+  - `[complexity]` - complexity analysis
+  - `[validation]` - design validation
+  - `[correction]` - design correction iteration
+  
+- Update progress bar to show all stages:
+  ```
+  Progress: [Interview] [Complexity] [Design] [Validation] [DevPlan] [Handoff]
+            [====✓====] [====✓====] [========] [        ] [        ] [        ]
+  ```
+
+- Add iteration counter for correction loop:
+  ```
+  [correction] Iteration 1/3: Adjusting phase count...
+  [correction] Iteration 2/3: Removing over-engineered components...
+  [correction] ✓ Validation passed
+  ```
+
+**Tests:**
+- Verify streaming output for all new stages
+- Test progress bar updates
+- Validate iteration counter display
+
+---
+
+### 1.5 Testing Requirements
+
+#### 1.5.1 Unit Tests
+
+**Location:** `tests/unit/`
+
+**Coverage Requirements:** 85%+ for all new modules
+
+**Test Files:**
+- `test_complexity_analyzer.py` (30+ tests)
+  - Scoring algorithm accuracy
+  - Phase count estimation
+  - Edge cases (minimal/maximal complexity)
+  
+- `test_design_validator.py` (25+ tests)
+  - Each validation check independently
+  - Validation report generation
+  - Auto-correction logic
+  
+- `test_llm_sanity_reviewer.py` (15+ tests)
+  - Prompt generation
+  - JSON parsing robustness
+  - Review result interpretation
+  
+- `test_design_correction_loop.py` (20+ tests)
+  - Convergence behavior
+  - Max iteration handling
+  - Correction strategy application
+
+**Tasks:**
+- Write comprehensive unit tests for all new classes
+- Mock LLM responses for deterministic testing
+- Test edge cases and error conditions
+- Achieve 85%+ code coverage
+
+---
+
+#### 1.5.2 Integration Tests
+
+**Location:** `tests/integration/`
+
+**Test Files:**
+- `test_interview_to_complexity_flow.py`
+  - Full interview → complexity profile generation
+  - Follow-up question flow
+  - Low confidence handling
+  
+- `test_adaptive_design_generation.py`
+  - Design generation at each complexity level
+  - Validation that output matches complexity
+  
+- `test_validation_and_correction.py`
+  - Full validation → correction → validation cycle
+  - Multiple iteration scenarios
+  - Human review fallback
+  
+- `test_end_to_end_adaptive_pipeline.py`
+  - Complete pipeline run with real LLM (marked `@pytest.mark.e2e`)
+  - Trivial project (3 phases)
+  - Standard project (5 phases)
+  - Complex project (7+ phases)
+  
+**Tasks:**
+- Implement integration tests covering cross-module interactions
+- Use test fixtures for sample interview data at various complexity levels
+- Create golden master tests comparing output structure
+
+---
+
+#### 1.5.3 Pipeline Test Harness
+
+**Location:** `tests/harness/pipeline_test_harness.py` (new file)
+
+**Purpose:** Automated testing framework for validating pipeline behavior.
+
+**Tasks:**
+- Create test harness:
+  ```python
+  class PipelineTestHarness:
+      def run_test_suite(self, test_scenarios: List[TestScenario]) -> TestReport:
+          results = []
+          for scenario in test_scenarios:
+              result = self.run_scenario(scenario)
+              results.append(result)
+          return TestReport(results)
+      
+      def run_scenario(self, scenario: TestScenario) -> ScenarioResult:
+          # Run pipeline with scenario inputs
+          # Validate outputs against expected behavior
+          # Return pass/fail with details
+  ```
+
+- Test scenarios:
+  - **Trivial:** CLI tool with 3 commands, no database
+  - **Simple:** REST API with auth, single database
+  - **Medium:** Full-stack web app with React + API + DB
+  - **Complex:** Multi-service SaaS with auth, payments, analytics
+  - **Enterprise:** Multi-region platform with microservices
+
+- Validation checks:
+  - Phase count matches expected range
+  - Design complexity appropriate
+  - No hallucinations detected
+  - All requirements addressed
+  - Output structure valid
+
+**Output:** `test_reports/pipeline_validation_report.md`
+
+**Tests:**
+- Run test harness with all scenarios
+- Verify report generation
+- Validate pass/fail criteria
+
+---
+
+### 1.6 JSON Schemas & Data Models
+
+#### 1.6.1 Schema Definitions
+
+**Location:** `schemas/`
+
+**Files:**
+- `complexity_profile.json` - ComplexityProfile model
+- `validation_report.json` - ValidationReport model
+- `review_result.json` - ReviewResult from LLM reviewer
+- `final_design.json` - FinalDesign with metadata
+- `pipeline_checkpoint.json` - Enhanced checkpoint format
+
+**Tasks:**
+- Define strict JSON schemas for all data models
+- Add schema validation at pipeline boundaries
+- Use Pydantic models for runtime validation:
+  ```python
+  from pydantic import BaseModel, Field
+  
+  class ComplexityProfile(BaseModel):
+      complexity_score: float = Field(ge=0, le=20)
+      estimated_phases: int = Field(ge=3, le=15)
+      depth_level: Literal["minimal", "standard", "detailed"]
+      project_scale: str
+      risk_factors: List[str]
+      recommended_follow_ups: List[str]
+      confidence: float = Field(ge=0, le=1)
+  ```
+
+- Generate JSON schema files from Pydantic models
+- Add schema documentation in docstrings
+
+**Tests:**
+- Validate schema files are valid JSON Schema
+- Test Pydantic model validation with valid/invalid data
+- Verify schema documentation completeness
+
+---
+
+#### 1.6.2 Data Model Documentation
+
+**Location:** `docs/data_models.md` (new file)
+
+**Tasks:**
+- Document all data models with:
+  - Field descriptions
+  - Valid value ranges
+  - Usage examples
+  - Relationships between models
+  
+- Generate API documentation from schemas:
+  ```bash
+  npm install -g @apidevtools/json-schema-docs
+  json-schema-docs schemas/*.json -o docs/api/
+  ```
+
+- Include in main documentation
+
+---
+
+### 1.7 Output Format Standardization
+
+#### 1.7.1 Deterministic Markdown Generation
+
+**Location:** `src/pipeline/output_formatter.py` (new file)
+
+**Purpose:** Ensure consistent, deterministic markdown output across all complexity levels.
+
+**Tasks:**
+- Create `OutputFormatter` class:
+  - Standardized heading hierarchy
+  - Consistent list formatting
+  - Uniform code block syntax
+  - Deterministic whitespace
+  
+- Template compilation with strict formatting:
+  ```python
+  def format_devplan(self, devplan_data: dict, complexity_profile: ComplexityProfile) -> str:
+      template = self.load_template(complexity_profile.depth_level)
+      rendered = template.render(devplan_data)
+      return self.normalize_markdown(rendered)
+  ```
+
+- Normalization rules:
+  - Single blank line between sections
+  - Consistent indentation (2 spaces)
+  - Trailing newline at EOF
+  - No trailing whitespace
+
+**Tests:**
+- Generate same input multiple times, verify byte-identical output
+- Test across all complexity levels
+- Validate markdown syntax with linter
+
+---
+
+### 1.8 Phase Summary - Backend Overhaul
+
+**Deliverables:**
+- ✅ Multi-stage interview with complexity assessment
+- ✅ Follow-up question capability
+- ✅ Complexity-driven design generation
+- ✅ Complexity-driven devplan generation
+- ✅ Design validation engine
+- ✅ LLM sanity reviewer
+- ✅ Iterative correction loop
+- ✅ Refactored pipeline orchestration
+- ✅ Comprehensive test suite (85%+ coverage)
+- ✅ JSON schemas for all data models
+- ✅ Pipeline test harness
+- ✅ Deterministic output formatting
+
+**Current Implementation Status (2025-11-25, mock backend slice):**
+- Implemented (mock, LLM-free):
+  - Complexity analysis and `InterviewPipeline` for deriving `ComplexityProfile`.
+  - Design validation system (`DesignValidator`, `LLMSanityReviewer`, `DesignCorrectionLoop` with optional `ComplexityProfile`).
+  - Adaptive design/devplan generators and `MockAdaptivePipeline` wiring.
+  - `PipelineTestHarness` for exercising the mock adaptive pipeline.
+  - **NEW:** `follow_up` mode in `llm_interview.py` with:
+    - `FOLLOW_UP_SYSTEM_PROMPT` for clarification questions
+    - `switch_mode()` method for mode transitions
+    - `set_follow_up_context()` for setting complexity profile and questions
+    - `request_clarifications()` for generating follow-up prompts
+  - **NEW:** All template variants created:
+    - `templates/interview/follow_up_questions.jinja2`
+    - `templates/design/adaptive_design.jinja2`
+    - `templates/devplan/phase_minimal.jinja2`
+    - `templates/devplan/phase_standard.jinja2`
+    - `templates/devplan/phase_detailed.jinja2`
+  - **NEW:** Templates wired into generators:
+    - `design_generator.py` - `use_templates` flag, `_generate_from_template()` method
+    - `devplan_generator.py` - `use_templates` flag, `render_phase_markdown()` method
+- Not yet implemented:
+  - Main pipeline refactor to integrate new stages (complexity → validation → correction)
+  - JSON schemas in `schemas/` directory
+  - Output formatter for deterministic markdown
+  - Streaming hooks for new stages ([complexity], [validation], [correction])
+  - Extended checkpointing for new artifacts
+
+**Testing Milestones:**
+1. Unit tests pass for all new modules
+2. Integration tests validate cross-module behavior
+3. E2E tests with real LLM confirm quality at all complexity levels
+4. Pipeline test harness validates 5 standard scenarios
+5. Regression tests ensure backward compatibility
+
+**Success Criteria:**
+- Trivial projects produce 3-5 phase devplans (< 2000 words)
+- Standard projects produce 5-7 phase devplans (2000-4000 words)
+- Complex projects produce 7-11 phase devplans (4000-8000 words)
+- Validation catches 90%+ of over-engineering cases
+- Auto-correction succeeds 80%+ of the time
+- No hallucinated libraries in output
+- All tests pass with 85%+ coverage
+
+---
+
+## Phase 2: Frontend/UI Updates
+
+**Objective:** Update the web UI to support the new adaptive pipeline workflow.
+
+### 2.1 UI Architecture Updates
+
+#### 2.1.1 New Screen: Complexity Assessment
+
+**Location:** `devussy-web/app/components/ComplexityAssessment.tsx` (new file)
+
+**Purpose:** Display complexity analysis results and allow user confirmation/adjustment.
+
+**Tasks:**
+- Create complexity visualization component:
+  ```tsx
+  interface ComplexityAssessmentProps {
+    profile: ComplexityProfile;
+    onConfirm: (profile: ComplexityProfile) => void;
+    onAdjust: (adjustments: Partial<ComplexityProfile>) => void;
+  }
+  
+  export function ComplexityAssessment({ profile, onConfirm, onAdjust }: ComplexityAssessmentProps) {
+    return (
+      <Card>
+        <ComplexityGauge score={profile.complexity_score} />
+        <PhaseCountEstimate count={profile.estimated_phases} />
+        <ProjectScaleIndicator scale={profile.project_scale} />
+        <RiskFactorsList factors={profile.risk_factors} />
+        <ConfidenceIndicator confidence={profile.confidence} />
+        
+        {profile.recommended_follow_ups.length > 0 && (
+          <FollowUpSuggestions suggestions={profile.recommended_follow_ups} />
+        )}
+        
+        <ButtonGroup>
+          <Button onClick={() => onConfirm(profile)}>Proceed with Estimate</Button>
+          <Button variant="secondary" onClick={() => setShowAdjustments(true)}>Adjust</Button>
+        </ButtonGroup>
+      </Card>
+    );
+  }
+  ```
+
+- Visual elements:
+  - **Complexity Gauge:** Circular progress indicator (0-20 scale)
+  - **Phase Count:** Large number with "+/-" adjustment buttons
+  - **Project Scale:** Badge (trivial/simple/medium/complex/enterprise)
+  - **Risk Factors:** Tag list with icons
+  - **Confidence:** Progress bar with color coding (red < 0.5, yellow < 0.8, green >= 0.8)
+
+- Interactive adjustments:
+  - Manual phase count override
+  - Depth level selector (minimal/standard/detailed)
+  - "Proceed anyway" option if confidence low
+
+**Styling:** Follow existing Devussy design system with Tailwind + Shadcn
+
+**Tests:**
+- Component rendering with various complexity profiles
+- User interaction (adjust, confirm)
+- Edge cases (very low/high complexity)
+
+---
+
+#### 2.1.2 New Screen: Design Sanity Check
+
+**Location:** `devussy-web/app/components/DesignSanityCheck.tsx` (new file)
+
+**Purpose:** Display validation results and correction iterations.
+
+**Tasks:**
+- Create validation dashboard:
+  ```tsx
+  export function DesignSanityCheck({ validationReport, reviewResult, iterationHistory }: Props) {
+    return (
+      <div className="grid grid-cols-2 gap-4">
+        <ValidationStatus report={validationReport} />
+        <LLMReviewScore review={reviewResult} />
+        
+        <IssuesList issues={validationReport.issues} />
+        <CorrectionsApplied corrections={validationReport.corrections_applied} />
+        
+        {iterationHistory.length > 0 && (
+          <IterationTimeline history={iterationHistory} />
+        )}
+      </div>
+    );
+  }
+  ```
+
+- Components:
+  - **ValidationStatus:** Pass/fail indicator with issue count
+  - **LLMReviewScore:** Confidence score with breakdown
+  - **IssuesList:** Grouped by severity (error/warning/info)
+  - **CorrectionsApplied:** List of auto-corrections with diffs
+  - **IterationTimeline:** Visual timeline of correction attempts
+
+- Real-time updates during correction loop:
+  - SSE stream from backend
+  - Live iteration counter
+  - Progressive issue resolution
+
+**Tests:**
+- Render with passing validation
+- Render with multiple issues
+- Render iteration history (0, 1, 2, 3 iterations)
+
+---
+
+#### 2.1.3 New Screen: Iterative Approval Steps
+
+**Location:** `devussy-web/app/components/IterativeApproval.tsx` (new file)
+
+**Purpose:** Allow user to approve or request changes at each pipeline stage.
+
+**Tasks:**
+- Create approval interface:
+  ```tsx
+  export function IterativeApproval({ stage, content, onApprove, onReject, onRequestChanges }: Props) {
+    const [feedback, setFeedback] = useState('');
+    
+    return (
+      <div>
+        <StageHeader stage={stage} />
+        <ContentPreview content={content} />
+        
+        <ApprovalActions>
+          <Button onClick={onApprove} variant="primary">
+            Approve & Continue
+          </Button>
+          <Button onClick={() => setShowFeedback(true)} variant="secondary">
+            Request Changes
+          </Button>
+          <Button onClick={onReject} variant="danger">
+            Regenerate from Scratch
+          </Button>
+        </ApprovalActions>
+        
+        {showFeedback && (
+          <FeedbackInput
+            value={feedback}
+            onChange={setFeedback}
+            onSubmit={() => onRequestChanges(feedback)}
+          />
+        )}
+      </div>
+    );
+  }
+  ```
+
+- Approval stages:
+  1. Complexity Profile
+  2. Initial Design
+  3. Validated Design (after corrections)
+  4. DevPlan Preview
+  5. Final Handoff
+
+- Feedback mechanism:
+  - Free-text feedback textarea
+  - Suggested adjustments (checkboxes for common changes)
+  - Severity indicator (minor tweak vs major rework)
+
+**Tests:**
+- Approve flow
+- Request changes flow
+- Regenerate flow
+
+---
+
+#### 2.1.4 Enhanced Window Management
+
+**Location:** `devussy-web/app/components/WindowManager.tsx` (modify existing)
+
+**Purpose:** Add windows for new pipeline stages.
+
+**Tasks:**
+- Add new window types:
+  - `complexity-assessment`
+  - `design-validation`
+  - `correction-progress`
+  - `approval-gate`
+  
+- Update window spawning logic:
+  ```tsx
+  const windowConfigs = {
+    'complexity-assessment': {
+      defaultSize: { width: 600, height: 400 },
+      defaultPosition: { x: 100, y: 100 },
+      resizable: true,
+    },
+    'design-validation': {
+      defaultSize: { width: 800, height: 600 },
+      defaultPosition: { x: 200, y: 100 },
+      resizable: true,
+    },
+    // ...
+  };
+  ```
+
+- Window lifecycle:
+  - Auto-open at appropriate pipeline stage
+  - Auto-close when stage completes
+  - Manual minimize/maximize
+  - Position persistence in localStorage
+
+**Tests:**
+- Window spawning for each new type
+- Position and size persistence
+- Multi-window layout management
+
+---
+
+### 2.2 Pipeline Integration
+
+#### 2.2.1 Update Pipeline State Machine
+
+**Location:** `devussy-web/app/state/pipelineState.ts` (modify existing)
+
+**Purpose:** Add new pipeline stages to state management.
+
+**Tasks:**
+- Extend pipeline stages enum:
+  ```typescript
+  enum PipelineStage {
+    INTERVIEW = 'interview',
+    COMPLEXITY_ANALYSIS = 'complexity_analysis',
+    FOLLOW_UP = 'follow_up',
+    DESIGN_GENERATION = 'design_generation',
+    DESIGN_VALIDATION = 'design_validation',
+    DESIGN_CORRECTION = 'design_correction',
+    APPROVAL_DESIGN = 'approval_design',
+    DEVPLAN_GENERATION = 'devplan_generation',
+    APPROVAL_DEVPLAN = 'approval_devplan',
+    HANDOFF_GENERATION = 'handoff_generation',
+    COMPLETE = 'complete',
+  }
+  ```
+
+- State transitions:
+  ```typescript
+  const transitions = {
+    [PipelineStage.INTERVIEW]: PipelineStage.COMPLEXITY_ANALYSIS,
+    [PipelineStage.COMPLEXITY_ANALYSIS]: (state) => 
+      state.complexityProfile.confidence < 0.7 
+        ? PipelineStage.FOLLOW_UP 
+        : PipelineStage.DESIGN_GENERATION,
+    [PipelineStage.DESIGN_VALIDATION]: (state) =>
+      state.validationReport.is_valid
+        ? PipelineStage.APPROVAL_DESIGN
+        : PipelineStage.DESIGN_CORRECTION,
+    // ...
+  };
+  ```
+
+- Store new data:
+  - `complexityProfile: ComplexityProfile | null`
+  - `validationReport: ValidationReport | null`
+  - `reviewResult: ReviewResult | null`
+  - `correctionHistory: CorrectionIteration[]`
+
+**Tests:**
+- State transitions with various conditions
+- Data persistence across stages
+- Resumability from checkpoints
+
+---
+
+#### 2.2.2 SSE Endpoint Integration
+
+**Location:** `devussy-web/app/api/` (new endpoints)
+
+**Purpose:** Add API endpoints for new backend functionality.
+
+**Tasks:**
+- New endpoints:
+  ```typescript
+  // POST /api/complexity/analyze
+  // Body: { interview_data: InterviewData }
+  // Response: ComplexityProfile
+  
+  // POST /api/design/validate
+  // Body: { design: string, complexity_profile: ComplexityProfile }
+  // Response: ValidationReport
+  
+  // POST /api/design/correct (SSE)
+  // Body: { design: string, validation: ValidationReport }
+  // Stream: CorrectionIteration[]
+  
+  // POST /api/pipeline/approve
+  // Body: { stage: PipelineStage, approved: boolean, feedback?: string }
+  // Response: NextStageInfo
+  ```
+
+- SSE streaming for correction loop:
+  ```typescript
+  const eventSource = new EventSource('/api/design/correct');
+  eventSource.onmessage = (event) => {
+    const iteration: CorrectionIteration = JSON.parse(event.data);
+    updateCorrectionHistory(iteration);
+  };
+  ```
+
+- Error handling:
+  - Network failures
+  - Backend errors
+  - Timeout handling (30s per stage)
+
+**Tests:**
+- API integration tests for each endpoint
+- SSE stream handling
+- Error scenarios
+
+---
+
+### 2.3 UI/UX Enhancements
+
+#### 2.3.1 Complexity Visualization
+
+**Location:** `devussy-web/app/components/ComplexityGauge.tsx` (new file)
+
+**Purpose:** Create visual representation of project complexity.
+
+**Tasks:**
+- Radial gauge component:
+  ```tsx
+  export function ComplexityGauge({ score, maxScore = 20 }: Props) {
+    const percentage = (score / maxScore) * 100;
+    const color = getColorForScore(score);
+    
+    return (
+      <div className="relative w-48 h-48">
+        <svg viewBox="0 0 100 100">
+          <circle cx="50" cy="50" r="40" fill="none" stroke="#e5e7eb" strokeWidth="8" />
+          <circle
+            cx="50"
+            cy="50"
+            r="40"
+            fill="none"
+            stroke={color}
+            strokeWidth="8"
+            strokeDasharray={`${percentage * 2.51} 251`}
+            transform="rotate(-90 50 50)"
+          />
+        </svg>
+        <div className="absolute inset-0 flex flex-col items-center justify-center">
+          <span className="text-3xl font-bold">{score.toFixed(1)}</span>
+          <span className="text-sm text-gray-500">complexity</span>
+        </div>
+      </div>
+    );
+  }
+  ```
+
+- Color mapping:
+  - 0-3: Green (trivial)
+  - 4-7: Blue (simple)
+  - 8-12: Yellow (medium)
+  - 13-16: Orange (complex)
+  - 17+: Red (enterprise)
+
+**Tests:**
+- Render at various score levels
+- Color transitions
+- Accessibility (ARIA labels)
+
+---
+
+#### 2.3.2 Phase Count Estimator
+
+**Location:** `devussy-web/app/components/PhaseCountEstimate.tsx` (new file)
+
+**Purpose:** Show estimated phase count with visual breakdown.
+
+**Tasks:**
+- Phase preview component:
+  ```tsx
+  export function PhaseCountEstimate({ count, complexity }: Props) {
+    const phaseNames = getPhaseNamesForCount(count);
+    
+    return (
+      <div>
+        <div className="text-2xl font-semibold mb-4">
+          {count} Development Phases
+        </div>
+        <div className="grid grid-cols-1 gap-2">
+          {phaseNames.map((name, i) => (
+            <div key={i} className="flex items-center gap-2">
+              <Badge variant="outline">{i + 1}</Badge>
+              <span>{name}</span>
+            </div>
+          ))}
+        </div>
+        <AdjustmentControls
+          value={count}
+          onChange={handlePhaseCountChange}
+          min={3}
+          max={15}
+        />
+      </div>
+    );
+  }
+  ```
+
+- Interactive adjustment:
+  - +/- buttons
+  - Direct input
+  - Preview updates in real-time
+
+**Tests:**
+- Render for 3, 5, 7, 9, 11 phases
+- Adjustment interactions
+- Preview accuracy
+
+---
+
+#### 2.3.3 Validation Results Display
+
+**Location:** `devussy-web/app/components/ValidationResults.tsx` (new file)
+
+**Purpose:** Clear presentation of validation checks and issues.
+
+**Tasks:**
+- Results dashboard:
+  ```tsx
+  export function ValidationResults({ report }: { report: ValidationReport }) {
+    return (
+      <div>
+        <OverallStatus status={report.is_valid ? 'pass' : 'fail'} />
+        <ConfidenceScore confidence={report.confidence} />
+        
+        <IssueBreakdown issues={report.issues} />
+        
+        {report.auto_correctable && (
+          <AutoCorrectStatus corrections={report.corrections_applied} />
+        )}
+        
+        {report.requires_human_review && (
+          <HumanReviewAlert />
+        )}
+      </div>
+    );
+  }
+  ```
+
+- Issue grouping:
+  - By severity (errors → warnings → info)
+  - By type (consistency, completeness, scope, hallucination, over-engineering)
+  - Expandable details with suggestions
+
+- Visual indicators:
+  - ✅ Pass (green)
+  - ⚠️  Warnings (yellow)
+  - ❌ Fail (red)
+  - 🔄 Auto-corrected (blue)
+
+**Tests:**
+- Display with no issues
+- Display with warnings only
+- Display with errors
+- Display with auto-corrections
+
+---
+
+#### 2.3.4 Correction Iteration Timeline
+
+**Location:** `devussy-web/app/components/CorrectionTimeline.tsx` (new file)
+
+**Purpose:** Visualize correction loop iterations.
+
+**Tasks:**
+- Timeline component:
+  ```tsx
+  export function CorrectionTimeline({ history }: { history: CorrectionIteration[] }) {
+    return (
+      <div className="space-y-4">
+        {history.map((iteration, i) => (
+          <TimelineItem key={i} iteration={iteration} index={i} />
+        ))}
+      </div>
+    );
+  }
+  
+  function TimelineItem({ iteration, index }: Props) {
+    return (
+      <div className="flex gap-4">
+        <div className="flex flex-col items-center">
+          <Badge>{index + 1}</Badge>
+          {index < history.length - 1 && <div className="h-full w-0.5 bg-gray-300" />}
+        </div>
+        <div className="flex-1">
+          <div className="font-medium">{iteration.action}</div>
+          <div className="text-sm text-gray-600">{iteration.description}</div>
+          <IssuesDiff before={iteration.issues_before} after={iteration.issues_after} />
+        </div>
+      </div>
+    );
+  }
+  ```
+
+- Iteration data:
+  - Action taken
+  - Issues before/after
+  - Validation score before/after
+  - Timestamp
+
+**Tests:**
+- Render timeline with 0, 1, 2, 3 iterations
+- Issue diff visualization
+- Responsive layout
+
+---
+
+### 2.4 Download & Export Enhancements
+
+#### 2.4.1 Enhanced ZIP Generator
+
+**Location:** `devussy-web/app/utils/zipGenerator.ts` (modify existing)
+
+**Purpose:** Include all new artifacts in downloaded ZIP.
+
+**Tasks:**
+- Update ZIP structure:
+  ```
+  project-name.zip
+  ├── devplan.md (main devplan)
+  ├── design.md (final validated design)
+  ├── handoff.md (handoff document)
+  ├── complexity_profile.json
+  ├── validation_report.json
+  ├── phases/
+  │   ├── phase_1_foundation.md
+  │   ├── phase_2_core.md
+  │   └── ...
+  ├── prompts/
+  │   ├── design_prompt.txt
+  │   ├── validation_prompt.txt
+  │   └── devplan_prompt.txt
+  └── metadata/
+      ├── iteration_history.json
+      └── pipeline_config.json
+  ```
+
+- Add metadata files:
+  - Complexity profile
+  - Validation reports
+  - Iteration history
+  - Pipeline configuration used
+
+**Tests:**
+- Generate ZIP for various complexity levels
+- Verify file structure
+- Validate all files present
+
+---
+
+#### 2.4.2 "Run Again with Refinements" Feature
+
+**Location:** `devussy-web/app/components/RefineButton.tsx` (new file)
+
+**Purpose:** Allow users to restart pipeline with adjusted parameters.
+
+**Tasks:**
+- Refinement interface:
+  ```tsx
+  export function RefineButton({ currentProfile }: Props) {
+    const [refinements, setRefinements] = useState<Refinement[]>([]);
+    
+    return (
+      <Popover>
+        <PopoverTrigger>
+          <Button>🔄 Refine & Regenerate</Button>
+        </PopoverTrigger>
+        <PopoverContent>
+          <RefinementForm
+            profile={currentProfile}
+            onChange={setRefinements}
+          />
+          <Button onClick={() => handleRegenerate(refinements)}>
+            Regenerate
+          </Button>
+        </PopoverContent>
+      </Popover>
+    );
+  }
+  ```
+
+- Refinement options:
+  - Adjust complexity score (+/- 2 points)
+  - Change phase count (±2 phases)
+  - Switch depth level
+  - Add/remove requirements
+  - Modify tech stack
+
+- Behavior:
+  - Keep interview data
+  - Apply refinements to complexity profile
+  - Restart from design generation
+  - Show diff between old and new
+
+**Tests:**
+- Apply various refinements
+- Verify pipeline restarts correctly
+- Compare outputs
+
+---
+
+### 2.5 Transparency Mode
+
+#### 2.5.1 Model Reasoning Display
+
+**Location:** `devussy-web/app/components/ReasoningPanel.tsx` (new file)
+
+**Purpose:** Show LLM reasoning process when available.
+
+**Tasks:**
+- Reasoning viewer:
+  ```tsx
+  export function ReasoningPanel({ reasoning }: { reasoning: ModelReasoning }) {
+    return (
+      <Accordion type="single" collapsible>
+        <AccordionItem value="complexity">
+          <AccordionTrigger>Complexity Assessment Reasoning</AccordionTrigger>
+          <AccordionContent>
+            <pre>{reasoning.complexity_analysis}</pre>
+          </AccordionContent>
+        </AccordionItem>
+        
+        <AccordionItem value="design">
+          <AccordionTrigger>Design Generation Reasoning</AccordionTrigger>
+          <AccordionContent>
+            <pre>{reasoning.design_thinking}</pre>
+          </AccordionContent>
+        </AccordionItem>
+        
+        <AccordionItem value="validation">
+          <AccordionTrigger>Validation Reasoning</AccordionTrigger>
+          <AccordionContent>
+            <pre>{reasoning.validation_logic}</pre>
+          </AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    );
+  }
+  ```
+
+- Display:
+  - Complexity scoring breakdown
+  - Design decision rationale
+  - Validation check reasoning
+  - Correction strategy logic
+
+- Toggle in settings:
+  - "Show Model Reasoning" checkbox
+  - Persistent preference
+
+**Tests:**
+- Render with reasoning data
+- Toggle visibility
+- Accordion interactions
+
+---
+
+#### 2.5.2 Prompt Inspection
+
+**Location:** `devussy-web/app/components/PromptInspector.tsx` (new file)
+
+**Purpose:** Allow inspection of exact prompts sent to LLM.
+
+**Tasks:**
+- Prompt viewer:
+  ```tsx
+  export function PromptInspector({ prompts }: { prompts: PromptHistory[] }) {
+    return (
+      <div className="space-y-4">
+        {prompts.map((prompt, i) => (
+          <PromptCard key={i} prompt={prompt} />
+        ))}
+      </div>
+    );
+  }
+  
+  function PromptCard({ prompt }: Props) {
+    return (
+      <Card>
+        <CardHeader>
+          <Badge>{prompt.stage}</Badge>
+          <span className="text-sm text-gray-500">{prompt.timestamp}</span>
+        </CardHeader>
+        <CardContent>
+          <CodeBlock language="text">{prompt.content}</CodeBlock>
+          <div className="mt-2">
+            <span className="text-sm">Model: {prompt.model}</span>
+            <span className="text-sm ml-4">Tokens: {prompt.token_count}</span>
+          </div>
+        </CardContent>
+      </Card>
+    );
+  }
+  ```
+
+- Access control:
+  - Developer mode toggle in settings
+  - Not visible by default
+
+**Tests:**
+- Display prompt history
+- Code highlighting
+- Copy to clipboard
+
+---
+
+### 2.6 Reuse Existing Components
+
+#### 2.6.1 Component Inventory
+
+**Existing components to reuse:**
+- `WindowManager` - adapt for new window types
+- `StreamingOutput` - use for correction loop
+- `ProgressBar` - extend for new stages
+- `ModelSelector` - no changes needed
+- `SettingsPanel` - add new options
+- `HelpWindow` - update documentation
+
+**Tasks:**
+- Audit existing components for reusability
+- Create wrapper components where needed
+- Maintain design consistency
+- Document integration points
+
+---
+
+#### 2.6.2 Design System Consistency
+
+**Tasks:**
+- Use existing Tailwind config
+- Reuse Shadcn components:
+  - Badge, Button, Card, Dialog, Popover, Accordion, Tabs
+- Maintain color scheme
+- Follow spacing conventions
+- Preserve animation patterns
+
+**Tests:**
+- Visual regression tests
+- Design system compliance checks
+
+---
+
+### 2.7 Testing Requirements
+
+#### 2.7.1 Component Tests
+
+**Location:** `devussy-web/__tests__/components/`
+
+**Tasks:**
+- Unit tests for all new components:
+  - `ComplexityAssessment.test.tsx`
+  - `DesignSanityCheck.test.tsx`
+  - `IterativeApproval.test.tsx`
+  - `ComplexityGauge.test.tsx`
+  - `PhaseCountEstimate.test.tsx`
+  - `ValidationResults.test.tsx`
+  - `CorrectionTimeline.test.tsx`
+  - `ReasoningPanel.test.tsx`
+  - `PromptInspector.test.tsx`
+
+- Testing approach:
+  - React Testing Library
+  - User interaction tests
+  - Snapshot tests for stable components
+  - Accessibility tests (a11y)
+
+**Coverage target:** 80%+
+
+---
+
+#### 2.7.2 Integration Tests
+
+**Location:** `devussy-web/__tests__/integration/`
+
+**Tasks:**
+- E2E tests for new flows:
+  - Interview → Complexity → Design → Validation → DevPlan
+  - Complexity adjustment flow
+  - Approval/rejection flow
+  - Refinement and regeneration
+  - ZIP download with all artifacts
+
+- Tools:
+  - Playwright for E2E
+  - Mock backend responses
+  - Test different complexity scenarios
+
+**Coverage:**
+- Happy path (all approvals)
+- Rejection and regeneration
+- Low confidence follow-up
+- Multiple correction iterations
+
+---
+
+#### 2.7.3 Visual Regression Tests
+
+**Location:** `devussy-web/__tests__/visual/`
+
+**Tasks:**
+- Screenshot tests for:
+  - Complexity gauge at various scores
+  - Validation results (pass/warning/fail states)
+  - Correction timeline (0-3 iterations)
+  - Phase count estimator (3-11 phases)
+
+- Tools:
+  - Percy or Chromatic for visual diffing
+  - Baseline screenshots for reference
+
+---
+
+### 2.8 Phase Summary - Frontend Updates
+
+**Deliverables:**
+- ✅ Complexity Assessment screen
+- ✅ Design Sanity Check screen
+- ✅ Iterative Approval interface
+- ✅ Enhanced window management
+- ✅ Updated pipeline state machine
+- ✅ New SSE endpoints integrated
+- ✅ Complexity visualization components
+- ✅ Validation results display
+- ✅ Correction iteration timeline
+- ✅ Enhanced ZIP download
+- ✅ "Refine & Regenerate" feature
+- ✅ Transparency mode (reasoning + prompts)
+- ✅ Comprehensive test suite (80%+ coverage)
+
+**Testing Milestones:**
+1. Component tests pass for all new UI
+2. Integration tests validate full user flows
+3. Visual regression tests establish baselines
+4. E2E tests confirm backend integration
+5. Accessibility audit passes WCAG 2.1 AA
+
+**Success Criteria:**
+- All new screens render correctly on desktop and mobile
+- Real-time updates work smoothly during correction loop
+- User can adjust complexity and see live preview
+- ZIP download includes all artifacts and metadata
+- Transparency mode provides clear insight into LLM decisions
+- UI maintains Devussy design consistency
+- No visual regressions from baseline
+- 80%+ test coverage
+
+---
+
+## Handoff Document
+
+**See separate `handoff.md` file for complete circular development handoff.**
+
+---
+
+## Future Considerations & Ideas
+
+### Context Budget Optimization
+- Implement token-economy strategies to minimize API costs
+- Track token usage per stage and optimize prompts
+- Cache frequently used prompt segments
+- Implement prompt compression techniques
+- Dynamic context window management based on complexity
+
+### LLM-Agnostic Prompt Design
+- Create provider-agnostic prompt templates
+- Support for multiple LLM APIs (Anthropic, OpenAI, local models)
+- Automatic prompt adaptation based on model capabilities
+- Model-specific optimization strategies
+- Fallback chains for high-reliability scenarios
+
+### Modularizing Prompts to Reduce Redundancy
+- Extract common prompt segments into reusable modules
+- Create prompt library with versioning
+- Implement prompt composition system
+- Reduce duplication across design/devplan/handoff prompts
+- A/B test prompt variations for quality improvement
+
+### Stable Format Enforcement Using JSON Schemas
+- Enforce strict JSON output schemas for all LLM responses
+- Add JSON mode support for compatible models
+- Implement retry logic with schema validation
+- Generate TypeScript types from JSON schemas
+- Auto-repair malformed JSON responses
+
+### Improving Jinja Template Coverage
+- Create template variants for more project types
+- Add conditional sections based on tech stack
+- Implement template inheritance system
+- Template testing and validation framework
+- Community-contributed template marketplace
+
+### Adding Phase Summaries at Each Step
+- Generate executive summary after each phase
+- Progress tracking dashboard
+- Milestone celebration UI
+- Phase-to-phase diff visualization
+- Cumulative complexity tracking
+
+### Creating a Pipeline Test Harness
+- Automated regression testing for pipeline outputs
+- Golden master testing with reference projects
+- Performance benchmarking across complexity levels
+- Quality scoring system for generated devplans
+- Continuous integration for pipeline changes
+
+### Model Self-Verification Component
+- LLM verifies its own outputs for consistency
+- Confidence scoring for each generated section
+- Self-correction prompts for low-confidence outputs
+- Explanation generation for complex decisions
+- Metacognitive reasoning chains
+
+### Guardrails to Detect Hallucinated APIs or Libraries
+- Maintain verified package database
+- Cross-reference APIs against package registries (npm, PyPI, etc.)
+- Detect fictional framework names
+- Validate import statements against real packages
+- Flag deprecated or unmaintained dependencies
+- Suggest alternatives for hallucinated packages
+
+### Minimal-Debug Mode for Tiny Projects
+- Ultra-simplified prompts for trivial projects
+- Single-phase devplan option
+- README-only output for very simple tools
+- Quick-start templates for common patterns
+- "Just build it" mode with minimal planning
+
+### Maximal-Explain Mode for Teaching Junior Devs
+- Detailed explanations for every design decision
+- Code comments explaining patterns
+- Link to educational resources
+- Step-by-step implementation guides
+- Common pitfalls and gotchas highlighted
+- Quiz/checkpoint questions throughout devplan
+
+### Additional Suggestions
+
+**Collaborative Features:**
+- Multi-user design review mode
+- Comment and annotation system
+- Version control integration for devplans
+- Team consensus tracking
+
+**Advanced Analytics:**
+- Track which complexity profiles lead to successful projects
+- Measure accuracy of phase count estimates
+- Identify common validation failure patterns
+- Optimize prompts based on success metrics
+
+**Integration Enhancements:**
+- GitHub Issues generation from devplan phases
+- Jira/Linear task import/export
+- Notion/Confluence documentation sync
+- Code scaffolding from devplan
+
+**Quality Improvements:**
+- Automated code review integration
+- Security scanning for suggested dependencies
+- License compatibility checking
+- Cost estimation for cloud resources mentioned
+
+**Developer Experience:**
+- VS Code extension for inline devplan viewing
+- CLI command for phase-by-phase execution
+- Git hooks for devplan validation
+- IDE integration for "next task" suggestions
+
+---
+
+## Implementation Timeline
+
+**Phase 1 Backend: 3-4 weeks**
+- Week 1: Complexity analyzer + interview enhancements
+- Week 2: Design validation + correction loop
+- Week 3: Pipeline integration + testing
+- Week 4: Documentation + refinements
+
+**Phase 2 Frontend: 2-3 weeks**
+- Week 1: New screens + components
+- Week 2: Pipeline integration + state management
+- Week 3: Testing + polish
+
+**Total: 5-7 weeks end-to-end**
+
+---
+
+## Risk Mitigation
+
+**Technical Risks:**
+- LLM output quality variance → Solution: Multiple validation layers, correction loop
+- Over-correction causing quality degradation → Solution: Max iteration limit, human review fallback
+- Performance degradation from additional stages → Solution: Parallel execution, caching
+
+**User Experience Risks:**
+- Increased complexity in UI → Solution: Progressive disclosure, optional transparency mode
+- Longer pipeline runtime → Solution: Streaming updates, clear progress indicators
+- User confusion about new features → Solution: Onboarding tour, help documentation
+
+**Implementation Risks:**
+- Breaking backward compatibility → Solution: Feature flags, gradual rollout
+- Test coverage gaps → Solution: Strict coverage requirements, automated checks
+- Integration issues between backend/frontend → Solution: Contract testing, API mocks
+
+---
+
+## Success Metrics
+
+**Quantitative:**
+- 90%+ validation accuracy (catches over-engineering)
+- 80%+ auto-correction success rate
+- 3x reduction in devplan size for trivial projects
+- 85%+ test coverage across codebase
+- < 5% user-reported hallucinations
+
+**Qualitative:**
+- User satisfaction with devplan appropriateness
+- Reduced iteration time from feedback
+- Improved first-time implementation success rate
+- Developer confidence in generated plans
+
+---
+
+## 📋 Project Dashboard
+
+### 🚀 Phase Overview
+
+| Phase | Status | Description |
+|-------|--------|-------------|
+| Phase 1 | ✅ Complete | Backend Workflow Overhaul |
+| Phase 2 | 🔄 In Progress | Frontend/UI Updates |
+
+<!-- PROGRESS_LOG_START -->
+### Progress Log
+
+**2025-11-26 - Frontend & API Integration Agent**
+- Created `ComplexityAssessment.tsx` component in `devussy-web/src/components/pipeline/`:
+  - Visual score gauge with SVG animation
+  - Depth level indicator (minimal/standard/detailed with color coding)
+  - Estimated phase count display
+  - Confidence meter with icons
+  - `ComplexityBadge` compact variant
+- Added FastAPI adaptive endpoints in `devussy-web/streaming_server/app.py`:
+  - `POST /api/adaptive/complexity` - SSE stream for complexity analysis
+  - `POST /api/adaptive/validate` - SSE stream for design validation
+  - `POST /api/adaptive/correct` - SSE stream for correction loop
+  - `GET /api/adaptive/profile` - Synchronous profile lookup
+- Implemented real LLM E2E tests (3 passing tests):
+  - `test_real_minimal_pipeline` - CLI tools
+  - `test_real_standard_pipeline` - APIs/web apps
+  - `test_real_detailed_pipeline` - SaaS/enterprise
+
+**2025-11-26 - CLI & Testing Agent**
+- Added `run-adaptive-pipeline` CLI command to `src/cli.py`:
+  - Full adaptive pipeline with complexity analysis, validation, correction
+  - Supports `--interview-file` for JSON input or uses CLI args for complexity
+  - Displays complexity profile summary after completion
+- Created comprehensive E2E tests in `tests/integration/test_adaptive_pipeline_e2e.py`:
+  - Tests for minimal, standard, and detailed complexity levels
+  - Tests for validation and correction loop invocation
+  - Tests for artifact generation
+  - 8 passing, 3 skipped (real LLM tests)
+- Achieved 87% test coverage on core adaptive pipeline modules:
+  - `complexity_analyzer.py`: 89%
+  - `design_validator.py`: 96%
+  - `design_correction_loop.py`: 68%
+
+**2025-11-25 - Anchor Documentation Agent**
+- Added comprehensive anchor-based context management documentation to:
+  - `devplan.md` - New critical section at top
+  - `handoff.md` - New critical section at top  
+  - `AGENTS.md` - New critical section at top (moved to priority position)
+  - `README.md` - New "Documentation for Agents" section
+  - `START_HERE.md` - Added anchor warning
+  - `HANDOFF_FOR_NEXT_AGENT.md` - Added anchor warning
+- All entry-point documents now reference anchor system
+
+**2025-11-25 - Template & Interview Integration Agent**
+- Implemented `follow_up` mode in `src/llm_interview.py`
+- Created all template variants in `templates/`
+- Wired templates into generators
+
+**2025-11-25 - Adaptive Generators & Harness Agent**
+- Implemented `design_generator.py` and `devplan_generator.py`
+- Created pipeline test harness
+
+**2025-11-25 - Backend Mock Implementation Agent**
+- Implemented complexity analyzer, interview pipeline
+- Implemented validation and correction loop modules
+
+**2025-11-25 - Pipeline Integration Agent**
+- Refactored main pipeline (`compose.py`) with adaptive methods
+- Extended checkpoint system with complexity_profile, validation_report
+- Added streaming prefixes ([complexity], [validation], [correction])
+- Created JSON schemas in `schemas/` directory
+- Added 16 new tests (6 unit + 10 integration)
+- Wired ComplexityAssessment into DesignView with auto-analysis
+- Created ValidationReport.tsx component with issue cards and sanity review
+- Created CorrectionTimeline.tsx component with visual iteration history
+
+**2025-11-26 - Frontend Integration Agent**
+- Wired ValidationReport into DesignView design approval flow
+- Wired CorrectionTimeline with real-time iteration updates
+- Added validation state (report, sanity review, loading)
+- Added correction loop state (history, running, current iteration)
+- Auto-trigger validation after design generation completes
+- Block auto-advance when validation has issues
+- Added "Approve Anyway" option for manual override
+- Added show/hide toggles for complexity, validation, correction panels
+- Updated PipelineStage type with new stages (complexity, validation, correction)
+- Added icons and labels for new pipeline stages
+<!-- PROGRESS_LOG_END -->
+
+<!-- NEXT_TASK_GROUP_START -->
+### Next Task Group (Current Sprint)
+
+1. ✅ **Add CLI command for adaptive pipeline** - DONE: `run-adaptive-pipeline` command added
+2. ✅ **E2E tests with real LLM** - DONE: 11 tests total (8 mocked + 3 real LLM)
+3. ✅ **Increase test coverage** - DONE: 87% coverage achieved
+4. ✅ **Start Frontend Phase 2** - DONE: `ComplexityAssessment.tsx` component created
+5. ✅ **Wire frontend to adaptive endpoints** - DONE: FastAPI SSE endpoints added
+6. ✅ **Wire ComplexityAssessment into pipeline flow** - DONE: Integrated into DesignView
+7. ✅ **Create ValidationReport component** - DONE: Full validation display with LLM sanity review
+8. ✅ **Create CorrectionTimeline component** - DONE: Visual iteration history with progress
+9. ✅ **Wire ValidationReport into design approval flow** - DONE: Show validation before approve
+10. ✅ **Wire CorrectionTimeline into correction loop UI** - DONE: Real-time iteration updates
+11. ✅ **Update frontend state management** - DONE: Added complexity/validation stages to PipelineStage type
+12. ✅ **Add frontend component tests** - DONE: 72 Jest tests for ComplexityAssessment, ValidationReport, CorrectionTimeline
+13. ✅ **Add visual regression tests** - DONE: Storybook + Chromatic configured with component stories
+14. ✅ **Documentation updates** - DONE: README updated with Adaptive Pipeline section
+
+### Phase 2 Complete! 🎉
+
+All adaptive pipeline frontend work is complete. The system now has:
+- Full complexity analysis → validation → correction loop in UI
+- 72 component tests passing
+- Storybook stories for all adaptive components
+- Updated documentation
+
+**Next Sprint (Optional Enhancements):**
+1. Playwright E2E tests for full browser automation
+2. CI/CD integration for Chromatic visual regression
+3. Performance optimization for large designs
+<!-- NEXT_TASK_GROUP_END -->
+
+---
+
+## Conclusion
+
+This devplan transforms Devussy from a static, one-size-fits-all pipeline into an intelligent, adaptive system that scales complexity appropriately. By introducing intermediate reasoning, validation loops, and iterative correction, the system will produce higher quality, more appropriate devplans while preventing common issues like over-engineering and hallucinations.
+
+The two-phase approach ensures backend logic is solid before UI updates, minimizing rework. Comprehensive testing and circular development handoff enable confident, iterative development.
+
+**Next steps:** Review this devplan, provide feedback, then proceed to Phase 1 implementation with circular development methodology.
+"""
\ No newline at end of file
diff --git a/devussy-web/.gitignore b/devussy-web/.gitignore
index 5ef6a52..a46e550 100644
--- a/devussy-web/.gitignore
+++ b/devussy-web/.gitignore
@@ -39,3 +39,6 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+*storybook.log
+storybook-static
diff --git a/devussy-web/.storybook/main.ts b/devussy-web/.storybook/main.ts
new file mode 100644
index 0000000..5f110e9
--- /dev/null
+++ b/devussy-web/.storybook/main.ts
@@ -0,0 +1,23 @@
+import type { StorybookConfig } from '@storybook/nextjs';
+
+const config: StorybookConfig = {
+  "stories": [
+    "../src/**/*.mdx",
+    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"
+  ],
+  "addons": [
+    "@chromatic-com/storybook",
+    "@storybook/addon-docs",
+    "@storybook/addon-onboarding",
+    "@storybook/addon-a11y",
+    "@storybook/addon-vitest"
+  ],
+  "framework": {
+    "name": "@storybook/nextjs",
+    "options": {}
+  },
+  "staticDirs": [
+    "..\\public"
+  ]
+};
+export default config;
\ No newline at end of file
diff --git a/devussy-web/.storybook/preview.ts b/devussy-web/.storybook/preview.ts
new file mode 100644
index 0000000..73e6da9
--- /dev/null
+++ b/devussy-web/.storybook/preview.ts
@@ -0,0 +1,14 @@
+import type { Preview } from '@storybook/nextjs'
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+       color: /(background|color)$/i,
+       date: /Date$/i,
+      },
+    },
+  },
+};
+
+export default preview;
\ No newline at end of file
diff --git a/devussy-web/README.md b/devussy-web/README.md
index 943ac38..1f3f2f0 100644
--- a/devussy-web/README.md
+++ b/devussy-web/README.md
@@ -99,6 +99,19 @@ http://localhost:3000
 ### HiveMind Mode 🐝 NEW
 A multi-agent swarm generation system that provides diverse perspectives on any phase:
 
+### IRC Chat 💬 NEW
+Real-time collaboration directly within the Devussy interface:
+- **Native WebSocket Support**: Connects directly to InspIRCd via secure WebSocket.
+- **Multi-Channel Support**: Join multiple channels and private message users.
+- **Persistent State**: Remembers your nickname and recent messages.
+- **Auto-Retry**: Automatically handles nickname collisions and reconnections.
+- **Demo Mode**: Fallback mode for UI testing when server is unavailable.
+
+**How It Works:**
+- Click "IRC Chat" in the Taskbar or Start Menu.
+- Enter a nickname (or use the generated one).
+- Start chatting in `#devussy-chat`.
+
 **How It Works:**
 - Click "🐝 Hive Mode" on any phase card (available for all statuses)
 - Opens a 4-pane real-time streaming window:
diff --git a/devussy-web/debug_irc.py b/devussy-web/debug_irc.py
new file mode 100644
index 0000000..a4a8784
--- /dev/null
+++ b/devussy-web/debug_irc.py
@@ -0,0 +1,100 @@
+import subprocess
+import sys
+import json
+import time
+import socket
+
+def run_command(command):
+    try:
+        result = subprocess.run(command, shell=True, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        return result.stdout.strip()
+    except subprocess.CalledProcessError as e:
+        return f"ERROR: {e.stderr.strip()}"
+
+def check_container_status(container_name):
+    print(f"Checking status of {container_name}...")
+    status = run_command(f"sudo docker inspect -f '{{{{.State.Status}}}}' {container_name}")
+    print(f"  Status: {status}")
+    return status == "running"
+
+def get_container_ip(container_name):
+    ip = run_command(f"sudo docker inspect -f '{{{{range .NetworkSettings.Networks}}}}{{{{.IPAddress}}}}{{{{end}}}}' {container_name}")
+    print(f"  IP: {ip}")
+    return ip
+
+def test_connectivity_from_nginx(target_host, target_port):
+    print(f"Testing connectivity from Nginx to {target_host}:{target_port}...")
+    cmd = f"sudo docker-compose exec nginx nc -zv {target_host} {target_port}"
+    output = run_command(f"cd ~/devussy/devussy/devussy-web && {cmd}")
+    print(f"  Result: {output}")
+
+def test_dns_resolution_from_nginx(hostname):
+    print(f"Testing DNS resolution for {hostname} from Nginx...")
+    cmd = f"sudo docker-compose exec nginx getent hosts {hostname}"
+    output = run_command(f"cd ~/devussy/devussy/devussy-web && {cmd}")
+    print(f"  Result: {output}")
+
+def test_websocket_handshake(ip, port):
+    print(f"Testing WebSocket handshake to {ip}:{port} (from Host)...")
+    # Simple manual HTTP request to simulate upgrade
+    request = (
+        f"GET / HTTP/1.1\r\n"
+        f"Host: {ip}:{port}\r\n"
+        f"Upgrade: websocket\r\n"
+        f"Connection: Upgrade\r\n"
+        f"Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n"
+        f"Sec-WebSocket-Version: 13\r\n"
+        f"Origin: https://dev.ussy.host\r\n"
+        f"\r\n"
+    )
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.settimeout(5)
+        s.connect((ip, int(port)))
+        s.sendall(request.encode())
+        response = s.recv(4096).decode()
+        s.close()
+        print("  Response Headers:")
+        print(response)
+        if "101 Switching Protocols" in response:
+            print("  SUCCESS: WebSocket handshake accepted!")
+        else:
+            print("  FAILURE: WebSocket handshake rejected.")
+    except Exception as e:
+        print(f"  ERROR: {e}")
+
+def main():
+    print("=== Devussy IRC Debugger ===")
+    
+    # 1. Check Containers
+    if not check_container_status("devussy-ircd"):
+        print("FATAL: IRCd container is not running.")
+        return
+    if not check_container_status("devussy-web-nginx-1"):
+        print("FATAL: Nginx container is not running.")
+        return
+
+    # 2. Get IPs
+    ircd_ip = get_container_ip("devussy-ircd")
+    
+    # 3. Test Nginx -> IRCd (Hostname)
+    test_dns_resolution_from_nginx("devussy-ircd")
+    test_connectivity_from_nginx("devussy-ircd", "8080")
+    
+    # 4. Test Nginx -> IRCd (IP)
+    test_connectivity_from_nginx(ircd_ip, "8080")
+
+    # 5. Test Host -> IRCd (Port 8080 mapped?)
+    # Check if port is exposed
+    ports = run_command("sudo docker port devussy-ircd 8080")
+    print(f"  Host Port Mapping: {ports}")
+    
+    if ports and "0.0.0.0:8080" in ports:
+        test_websocket_handshake("127.0.0.1", "8080")
+    else:
+        print("  Skipping Host handshake test (port 8080 not mapped to host)")
+
+    print("\n=== End of Debug ===")
+
+if __name__ == "__main__":
+    main()
diff --git a/devussy-web/docker-compose.yml b/devussy-web/docker-compose.yml
index 0c0492d..a47d52f 100644
--- a/devussy-web/docker-compose.yml
+++ b/devussy-web/docker-compose.yml
@@ -4,12 +4,16 @@ services:
     build:
       context: .
       dockerfile: frontend.Dockerfile
+      args:
+        - NEXT_PUBLIC_IRC_WS_URL=${NEXT_PUBLIC_IRC_WS_URL:-ws://localhost:8080}
+        - NEXT_PUBLIC_IRC_CHANNEL=${NEXT_PUBLIC_IRC_CHANNEL:-#devussy-chat}
     working_dir: /app
     ports:
       - "3000:3000"
     environment:
       - NODE_ENV=production
       - USE_LOCAL_API=${USE_LOCAL_API:-false}
+      - NEXT_PUBLIC_IRC_CHANNEL=#devussy-chat
     depends_on:
       - streaming-server
 
@@ -28,15 +32,16 @@ services:
       - "8000:8000"
     environment:
       - REQUESTY_API_KEY=${REQUESTY_API_KEY}
-      - STREAMING_SECRET=${STREAMING_SECRET}
       - LLM_PROVIDER=requesty
       - PYTHONPATH=/app:/app/devussy-web
 
   nginx:
     image: nginx:stable-alpine
+    hostname: nginx
     volumes:
       - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
       - ./nginx/conf.d:/etc/nginx/conf.d:ro
+      - /etc/letsencrypt:/etc/letsencrypt:ro
     ports:
       - "80:80"
       - "443:443"
@@ -44,4 +49,16 @@ services:
       - frontend
       - streaming-server
 
+  ircd:
+    image: inspircd/inspircd-docker:latest
+    container_name: devussy-ircd
+    ports:
+      - "6667:6667"
+      - "8080:8080"
+    volumes:
+      - ./irc/conf/inspircd_v2.conf:/inspircd/conf/inspircd.conf
+      - ./irc/logs:/inspircd/logs
+      - ./irc/data:/inspircd/data
+    restart: unless-stopped
+
 # Note: this is a minimal template. For production, build optimized images and avoid mounting the whole source tree.
diff --git a/devussy-web/eslint.config.mjs b/devussy-web/eslint.config.mjs
index 05e726d..86783bd 100644
--- a/devussy-web/eslint.config.mjs
+++ b/devussy-web/eslint.config.mjs
@@ -1,3 +1,6 @@
+// For more info, see https://github.com/storybookjs/eslint-plugin-storybook#configuration-flat-config-format
+import storybook from "eslint-plugin-storybook";
+
 import { defineConfig, globalIgnores } from "eslint/config";
 import nextVitals from "eslint-config-next/core-web-vitals";
 import nextTs from "eslint-config-next/typescript";
diff --git a/devussy-web/frontend.Dockerfile b/devussy-web/frontend.Dockerfile
index 928e56c..dee5b99 100644
--- a/devussy-web/frontend.Dockerfile
+++ b/devussy-web/frontend.Dockerfile
@@ -7,6 +7,11 @@ RUN npm ci
 
 # Copy app source and build
 COPY . .
+
+# Build arguments
+ARG NEXT_PUBLIC_IRC_WS_URL
+ARG NEXT_PUBLIC_IRC_CHANNEL
+
 RUN npm run build
 
 FROM node:20-alpine AS runner
diff --git a/devussy-web/irc/README.md b/devussy-web/irc/README.md
new file mode 100644
index 0000000..3d175e2
--- /dev/null
+++ b/devussy-web/irc/README.md
@@ -0,0 +1,56 @@
+# Devussy IRC Add-on
+
+This directory contains the configuration and documentation for the Devussy IRC add-on.
+
+## Components
+
+1.  **IRC Server**: InspIRCd (Dockerized) running on port 6667 (internal) and 8080 (WebSocket).
+2.  **IRC Client**: A React component (`IrcClient.tsx`) integrated into the Devussy frontend.
+
+## Setup
+
+The IRC services are defined in `docker-compose.yml`. To start them:
+
+```bash
+docker-compose up -d ircd
+```
+
+Ensure your `.env` file (or environment) has the following variables for the frontend:
+
+```
+NEXT_PUBLIC_IRC_WS_URL=wss://dev.ussy.host/ws/irc/
+NEXT_PUBLIC_IRC_CHANNEL=#devussy-chat
+```
+
+## Configuration
+
+### InspIRCd (`conf/inspircd_v2.conf`)
+- **Modules**: Loads `m_websocket.so` and `m_sha1.so` (required for handshake).
+- **Ports**: Listens on 6667 (IRC) and 8080 (WebSocket).
+- **DNS**: DNS resolution is disabled to prevent issues with Docker hostnames.
+- **Ping Frequency**: Set to 15s to quickly detect and remove ghost connections.
+
+### Nginx Proxy
+- Proxies WebSocket connections from `/ws/irc/` to `ircd:8080`.
+- Handles SSL termination.
+
+## Usage
+
+1.  Open Devussy Studio.
+2.  Click "IRC Chat" in the Taskbar or Start Menu.
+3.  Enter a nickname if prompted (defaults to Guest).
+4.  Chat!
+
+### Demo Mode
+If the IRC server is unreachable, the client will automatically switch to "Demo Mode" after connection failures. This simulates a chat environment for UI testing.
+
+### Persistence
+- Nickname and the last 50 messages are saved in `localStorage`.
+
+## Troubleshooting
+
+- **Connection Refused**: Ensure `ircd` container is running and port 8080 is accessible.
+- **503 Service Unavailable**: Check Nginx logs. Ensure Nginx can resolve the `ircd` hostname.
+- **Nickname in Use**: The client automatically handles this by appending an underscore (`_`) to your nickname and retrying.
+- **Ghost Users**: If you reload the page, your previous session might stay active for ~15 seconds until the server times it out.
+
diff --git a/devussy-web/irc/conf/conf.d/connectban_relax.conf b/devussy-web/irc/conf/conf.d/connectban_relax.conf
new file mode 100644
index 0000000..ec6fb19
--- /dev/null
+++ b/devussy-web/irc/conf/conf.d/connectban_relax.conf
@@ -0,0 +1,4 @@
+# Relax connectban globally so it never Z-lines normal users in this private setup.
+# This effectively disables automatic connection-based bans.
+
+<connectban threshold="1000000" banduration="10s" ipv4cidr="32" ipv6cidr="128" bootwait="0" splitwait="0">
diff --git a/devussy-web/irc/conf/conf.d/gateway_connect.conf b/devussy-web/irc/conf/conf.d/gateway_connect.conf
new file mode 100644
index 0000000..04eda3d
--- /dev/null
+++ b/devussy-web/irc/conf/conf.d/gateway_connect.conf
@@ -0,0 +1,5 @@
+# Disable connectban for Docker internal network / gateway clients
+# This tells the connectban module not to apply to clients from 172.16.0.0/12
+# (which includes the 172.18.x.x Docker subnet used by irc-gateway).
+
+<connect name="gateway" allow="172.16.0.0/12" useconnectban="no" useident="no">
diff --git a/devussy-web/irc/conf/conf.d/gateway_webirc.conf b/devussy-web/irc/conf/conf.d/gateway_webirc.conf
new file mode 100644
index 0000000..5f0f3a0
--- /dev/null
+++ b/devussy-web/irc/conf/conf.d/gateway_webirc.conf
@@ -0,0 +1,8 @@
+# Allow the local WebIRC gateway (docker subnet) to use WEBIRC
+# Must match the `webirc` password in gateway.conf
+
+<cgiirc opernotice="no">
+
+# Treat any client from the Docker 172.16.0.0/12 network using WEBIRC
+# with the shared password `devussy_webirc_secret` as trusted.
+<cgihost type="webirc" mask="172.16.0.0/12" password="devussy_webirc_secret">
diff --git a/devussy-web/irc/conf/inspircd_v2.conf b/devussy-web/irc/conf/inspircd_v2.conf
new file mode 100644
index 0000000..9470e30
--- /dev/null
+++ b/devussy-web/irc/conf/inspircd_v2.conf
@@ -0,0 +1,60 @@
+
+<server
+    name="irc.devussy.local"
+    description="Devussy IRC Server"
+    network="DevussyNet">
+
+<admin
+    name="Devussy Admin"
+    nick="admin"
+    email="admin@devussy.local">
+
+<bind address="*" port="6667" type="clients">
+
+<log method="stderr" level="debug">
+
+<module name="sha1">
+<module name="sha256">
+<module name="websocket">
+<bind address="*" port="8080" type="clients" hook="websocket">
+
+<websocket defaultmode="text">
+
+<wsorigin allow="https://dev.ussy.host*">
+<wsorigin allow="https://*">
+<wsorigin allow="http://localhost:*">
+<wsorigin allow="http://127.0.0.1:*">
+
+
+
+
+<oper name="admin"
+      password="devussy_oper_secret"
+      host="*@*"
+      type="NetAdmin">
+
+<type name="NetAdmin" classes="Oper" modes="+o">
+<class name="Oper" commands="*" privs="*" usermodes="*" chanmodes="*">
+
+<connect name="gateway"
+         allow="172.16.0.0/12"
+         useconnectban="no"
+         useident="no"
+         resolvedns="no"
+         localmax="1000"
+         globalmax="1000"
+         limit="5000">
+
+<connect name="main"
+         allow="*"
+         timeout="300"
+         pingfreq="120"
+         hardsendq="1M"
+         softsendq="8192"
+         recvq="8192"
+         threshold="10"
+         limit="5000"
+         localmax="1000"
+         globalmax="1000"
+         useident="no"
+         resolvedns="no">
diff --git a/devussy-web/irc/data/.gitkeep b/devussy-web/irc/data/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/devussy-web/irc/gateway.conf b/devussy-web/irc/gateway.conf
new file mode 100644
index 0000000..307f657
--- /dev/null
+++ b/devussy-web/irc/gateway.conf
@@ -0,0 +1,57 @@
+logLevel = 3
+identd = false
+gateway_name = "devussy-gateway"
+secret = ""
+
+[verify]
+recaptcha_url = "https://www.google.com/recaptcha/api/siteverify"
+recaptcha_secret = ""
+recaptcha_key = ""
+required = false
+
+[clients]
+# username = "%i"
+# realname = "I am a webchat user"
+
+[server.1]
+bind = "0.0.0.0"
+port = 8080
+
+[fileserving]
+enabled = false
+webroot = www/
+
+[transports]
+websocket
+
+[allowed_origins]
+# No entries means any origin is allowed. For tighter security, list
+# origins like "*://dev.ussy.host".
+
+[reverse_proxies]
+127.0.0.0/8
+10.0.0.0/8
+172.16.0.0/12
+192.168.0.0/16
+"::1/128"
+"fd00::/8"
+
+[upstream.1]
+hostname = "ircd"
+port = 6667
+tls = false
+timeout = 30
+throttle = 0
+# No WebIRC password; connect as a normal IRC client to the default config
+webirc = ""
+serverpassword = ""
+protocol = tcp
+localaddr = ""
+
+[gateway]
+enabled = false
+timeout = 5
+throttle = 2
+protocol = tcp
+localaddr = ""
+
diff --git a/devussy-web/irc/ircd.conf b/devussy-web/irc/ircd.conf
new file mode 100644
index 0000000..dfbfee0
--- /dev/null
+++ b/devussy-web/irc/ircd.conf
@@ -0,0 +1,85 @@
+serverinfo {
+        name = "irc.devussy.local";
+        description = "Devussy IRC Server";
+        network_name = "DevussyNet";
+        network_desc = "Devussy Network";
+        hub = yes;
+};
+
+admin {
+        name = "Devussy Admin";
+        email = "admin@devussy.local";
+};
+
+listen {
+        port = 6667;
+};
+
+auth {
+        user = "*@*";
+        password = "";
+        class = "users";
+        flags = need_ident;
+};
+
+class "users" {
+        ping_time = 90 seconds;
+        number_per_ip = 5;
+        max_number = 100;
+        sendq = 100kb;
+};
+
+class "restricted" {
+        ping_time = 90 seconds;
+        number_per_ip = 1;
+        max_number = 10;
+        sendq = 10kb;
+};
+
+channel {
+        default_invite_only = no;
+        default_key = "";
+        default_limit = 0;
+        default_private = no;
+        default_secret = no;
+        default_topic_restricted = no;
+        default_private = no;
+        default_secret = no;
+        default_topic_restricted = no;
+        default_auto_limit = 0;
+        default_limit = 0;
+        default_auto_limit = 0;
+};
+
+log {
+        fname_userlog = "/var/log/ircd/user.log";
+        fname_operlog = "/var/log/ircd/oper.log";
+        fname_killlog = "/var/log/ircd/kill.log";
+        fname_klinelog = "/var/log/ircd/kline.log";
+        fname_operspylog = "/var/log/ircd/operspy.log";
+        fname_errorlog = "/var/log/ircd/error.log";
+};
+
+connect {
+        name = "services.irc.devussy.local";
+        host = "127.0.0.1";
+        send_password = "";
+        accept_password = "";
+        port = 6667;
+        hub_mask = "*";
+        class = "server";
+        flags = topicburst;
+};
+
+operator {
+        name = "admin";
+        user = "*@*";
+        password = "devussy_oper_secret";
+        class = "users";
+        flags = need_ident;
+};
+
+shared {
+        oper = "*@*";
+        flags = all;
+};
diff --git a/devussy-web/irc/ngircd.conf b/devussy-web/irc/ngircd.conf
new file mode 100644
index 0000000..c3c61b5
--- /dev/null
+++ b/devussy-web/irc/ngircd.conf
@@ -0,0 +1,44 @@
+[Global]
+        Name = irc.devussy.local
+        Info = Devussy IRC Server
+        AdminInfo1 = Devussy Admin
+        AdminInfo2 = admin@devussy.local
+        AdminEMail = admin@devussy.local
+        Ports = 6667
+        MotdFile = /config/ngircd.motd
+        MotdPhrase = Welcome to Devussy IRC!
+        ServerGID = 65534
+        ServerUID = 65534
+        Listen = 0.0.0.0
+        MaxConnectionsIP = 5
+        MaxConnections = 500
+        MaxJoins = 10
+        MaxNickLength = 9
+        MaxListSize = 100
+        PingTimeout = 120
+        PongTimeout = 20
+        ConnectRetry = 60
+        OperCanUseMode = yes
+        OperChanPAutoOp = yes
+        OperUserPAutoOp = yes
+        OperServerPAutoOp = yes
+        AllowRemoteOper = yes
+        PredefChannelsOnly = no
+        Name = irc.devussy.local
+        Password = 
+        PidFile = /config/ngircd.pid
+
+[Operator]
+        Name = admin
+        Password = devussy_oper_secret
+        Mask = *!*@*
+
+[Channel]
+        Name = #devussy-chat
+        Modes = +n
+        Topic = Devussy Development Chat
+
+[Channel]
+        Name = #general
+        Modes = +n
+        Topic = General Discussion
diff --git a/devussy-web/irc/soju.cfg b/devussy-web/irc/soju.cfg
new file mode 100644
index 0000000..cd9bb30
--- /dev/null
+++ b/devussy-web/irc/soju.cfg
@@ -0,0 +1,12 @@
+listen ircs://:6667
+
+hostname irc.devussy.local
+db sqlite3 /var/lib/soju/main.db
+
+log fs /var/log/soju.log
+
+auth local
+auth-pass password bcrypt
+
+http-origin *
+accept-proxy-ip 172.16.0.0/12
diff --git a/devussy-web/irc/webircgateway.Dockerfile b/devussy-web/irc/webircgateway.Dockerfile
new file mode 100644
index 0000000..2251421
--- /dev/null
+++ b/devussy-web/irc/webircgateway.Dockerfile
@@ -0,0 +1,20 @@
+FROM golang:1.22-alpine AS builder
+WORKDIR /app
+RUN apk add --no-cache git
+
+# Fetch WebIRC Gateway source
+RUN git clone https://github.com/kiwiirc/webircgateway.git .
+
+# Build the binary
+RUN go build -o webircgateway
+
+FROM alpine:3.19
+WORKDIR /app
+
+# Copy compiled gateway
+COPY --from=builder /app/webircgateway /usr/local/bin/webircgateway
+
+# Config will be mounted at /config/gateway.conf
+EXPOSE 8080
+
+CMD ["webircgateway", "--config=/config/gateway.conf"]
diff --git a/devussy-web/jest.config.js b/devussy-web/jest.config.js
new file mode 100644
index 0000000..415ba90
--- /dev/null
+++ b/devussy-web/jest.config.js
@@ -0,0 +1,24 @@
+const nextJest = require('next/jest');
+
+const createJestConfig = nextJest({
+  // Provide the path to your Next.js app to load next.config.js and .env files
+  dir: './',
+});
+
+// Add any custom config to be passed to Jest
+const customJestConfig = {
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
+  testEnvironment: 'jest-environment-jsdom',
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1',
+  },
+  testPathIgnorePatterns: ['<rootDir>/node_modules/', '<rootDir>/.next/'],
+  collectCoverageFrom: [
+    'src/**/*.{js,jsx,ts,tsx}',
+    '!src/**/*.d.ts',
+    '!src/**/index.ts',
+  ],
+};
+
+// createJestConfig is exported this way to ensure that next/jest can load the Next.js config which is async
+module.exports = createJestConfig(customJestConfig);
diff --git a/devussy-web/jest.setup.js b/devussy-web/jest.setup.js
new file mode 100644
index 0000000..b71b2aa
--- /dev/null
+++ b/devussy-web/jest.setup.js
@@ -0,0 +1,3 @@
+import '@testing-library/jest-dom';
+
+// Extend Jest matchers with DOM-specific assertions
diff --git a/devussy-web/nginx/nginx.conf b/devussy-web/nginx/nginx.conf
index 9399169..bca0600 100644
--- a/devussy-web/nginx/nginx.conf
+++ b/devussy-web/nginx/nginx.conf
@@ -11,6 +11,15 @@ http {
   sendfile        on;
   keepalive_timeout  65;
 
+  # Map for WebSocket upgrades
+  map $http_upgrade $connection_upgrade {
+    default upgrade;
+    '' close;
+  }
+
+  # Docker DNS resolver
+  resolver 127.0.0.11 valid=30s;
+
   server {
     listen 80 default_server;
     server_name _;
@@ -19,7 +28,7 @@ http {
   }
 
   server {
-    listen 443 ssl http2 default_server;
+    listen 443 ssl default_server;
     server_name _;
 
     # Note: In production, configure proper certs and SSL config
@@ -49,6 +58,23 @@ http {
       proxy_read_timeout 3600s;
     }
 
+    # IRC WebSocket (InspIRCd with m_websocket)
+    # External path:  wss://dev.ussy.host/ws/irc/
+    # Internal upstream:  http://ircd:8080/
+    location /ws/irc/ {
+      proxy_pass http://ircd:8080/;
+      proxy_connect_timeout 5s;
+      proxy_http_version 1.1;
+      proxy_set_header Upgrade $http_upgrade;
+      proxy_set_header Connection $connection_upgrade;
+      proxy_set_header Host $host;
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto $scheme;
+      proxy_read_timeout 86400s;
+      add_header X-Debug-Backend "ircd" always;
+    }
+
     location /api/ {
       proxy_pass http://streaming-server:8000/api/;
       proxy_set_header Host $host;
diff --git a/devussy-web/package.json b/devussy-web/package.json
index 338d166..c4d12c5 100644
--- a/devussy-web/package.json
+++ b/devussy-web/package.json
@@ -6,7 +6,13 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "eslint"
+    "lint": "eslint",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "chromatic": "chromatic --exit-zero-on-changes"
   },
   "dependencies": {
     "@radix-ui/react-dialog": "^1.1.15",
@@ -25,15 +31,31 @@
     "tailwind-merge": "^3.4.0"
   },
   "devDependencies": {
+    "@storybook/nextjs": "^10.0.8",
+    "@storybook/react": "^10.0.8",
     "@tailwindcss/postcss": "^4",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/jest": "^30.0.0",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "babel-plugin-react-compiler": "1.0.0",
+    "chromatic": "^13.3.4",
     "eslint": "^9",
     "eslint-config-next": "16.0.3",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "storybook": "^10.0.8",
     "tailwindcss": "^4",
     "tw-animate-css": "^1.4.0",
-    "typescript": "^5"
+    "typescript": "^5",
+    "@chromatic-com/storybook": "^4.1.3",
+    "@storybook/addon-docs": "^10.0.8",
+    "@storybook/addon-onboarding": "^10.0.8",
+    "eslint-plugin-storybook": "^10.0.8",
+    "@storybook/addon-a11y": "^10.0.8",
+    "@storybook/addon-vitest": "^10.0.8"
   }
 }
diff --git a/devussy-web/src/app/page.tsx b/devussy-web/src/app/page.tsx
index 2136386..266e59e 100644
--- a/devussy-web/src/app/page.tsx
+++ b/devussy-web/src/app/page.tsx
@@ -17,8 +17,9 @@ import { CheckpointManager } from "@/components/pipeline/CheckpointManager";
 import { Taskbar } from "@/components/window/Taskbar";
 import { ThemeToggle } from "@/components/theme/ThemeToggle";
 import { useTheme } from "@/components/theme/ThemeProvider";
+import IrcClient from '@/components/addons/irc/IrcClient';
 
-type WindowType = 'init' | 'interview' | 'design' | 'plan' | 'execute' | 'handoff' | 'help' | 'model-settings';
+type WindowType = 'init' | 'interview' | 'design' | 'plan' | 'execute' | 'handoff' | 'help' | 'model-settings' | 'irc';
 
 interface WindowState {
   id: string;
@@ -35,9 +36,9 @@ export default function Page() {
   const { theme } = useTheme();
   // Window State Management
   const [windows, setWindows] = useState<WindowState[]>([
-    { id: 'init-1', type: 'init', title: 'Devussy Studio', position: { x: 50, y: 50 }, zIndex: 10 }
+    { id: 'help-1', type: 'help', title: 'Devussy Studio Help', position: { x: 50, y: 50 }, zIndex: 10, size: { width: 700, height: 600 } }
   ]);
-  const [activeWindowId, setActiveWindowId] = useState<string>('init-1');
+  const [activeWindowId, setActiveWindowId] = useState<string>('help-1');
   const [nextZIndex, setNextZIndex] = useState(20);
 
   // Project State (Shared across windows)
@@ -58,6 +59,43 @@ export default function Page() {
     try { return localStorage.getItem('devussy_help_dismissed') === '1'; } catch (e) { return false; }
   });
 
+  const [analyticsOptOut, setAnalyticsOptOut] = useState<boolean>(false);
+
+  useEffect(() => {
+    try {
+      const cookies = document.cookie.split(';').map(c => c.trim());
+      const cookie = cookies.find(c => c.startsWith('devussy_analytics_optout='));
+      if (cookie) {
+        const value = (cookie.split('=')[1] || '').toLowerCase();
+        if (value === '1' || value === 'true' || value === 'yes') {
+          setAnalyticsOptOut(true);
+        }
+      }
+    } catch (e) { }
+  }, []);
+
+  // IRC nickname (from localStorage)
+  const [ircNick, setIrcNick] = useState<string>(() => {
+    try { return localStorage.getItem('devussy_irc_nick') || 'Guest'; } catch (e) { return 'Guest'; }
+  });
+
+  // Listen for IRC nick changes
+  useEffect(() => {
+    const handleStorage = () => {
+      try {
+        const nick = localStorage.getItem('devussy_irc_nick');
+        if (nick) setIrcNick(nick);
+      } catch (e) { }
+    };
+    window.addEventListener('storage', handleStorage);
+    // Also poll for changes since same-tab changes don't trigger storage event
+    const interval = setInterval(handleStorage, 1000);
+    return () => {
+      window.removeEventListener('storage', handleStorage);
+      clearInterval(interval);
+    };
+  }, []);
+
   // Model Configuration
   const [modelConfigs, setModelConfigs] = useState<ModelConfigs>({
     global: {
@@ -148,13 +186,15 @@ export default function Page() {
         return { width: 700, height: 600 };
       case 'model-settings':
         return { width: 500, height: 650 };
+      case 'irc':
+        return { width: 800, height: 600 };
       default:
         return { width: 600, height: 400 };
     }
   };
 
   // Window Management Functions
-  const spawnWindow = (type: WindowType, title: string, props?: Record<string, any>) => {
+  const spawnWindow = (type: WindowType, title: string, props?: Record<string, any>, options?: { isMinimized?: boolean }) => {
     const id = `${type}-${Date.now()}`;
     const offset = windows.length * 30;
     const size = getWindowSize(type);
@@ -164,13 +204,16 @@ export default function Page() {
       title,
       position: { x: 100 + offset, y: 100 + offset },
       zIndex: nextZIndex,
+      isMinimized: options?.isMinimized,
       props,
       size
     };
 
     setWindows(prev => [...prev, newWindow]);
     setNextZIndex(prev => prev + 1);
-    setActiveWindowId(id);
+    if (!options?.isMinimized) {
+      setActiveWindowId(id);
+    }
   };
 
   const closeWindow = (id: string) => {
@@ -300,23 +343,37 @@ export default function Page() {
     spawnWindow('model-settings', 'AI Model Settings');
   };
 
-  // Auto-open Help modal on the first visit (unless dismissed)
+  const handleOpenIrc = (options?: { isMinimized?: boolean }) => {
+    const existing = windows.find(w => w.type === 'irc');
+    if (existing) {
+      if (!options?.isMinimized) {
+        focusWindow(existing.id);
+        if (existing.isMinimized) {
+          toggleMinimize(existing.id);
+        }
+      }
+      return;
+    }
+    spawnWindow('irc', 'IRC Chat – #devussy-chat', undefined, options);
+  };
+
+  // Auto-launch IRC (always, minimized)
   useEffect(() => {
     try {
-      const dismissed = localStorage.getItem('devussy_help_dismissed');
-      const seen = localStorage.getItem('devussy_seen_help');
-      if (!dismissed && !seen) {
-        // Delay slightly to allow initial window to render
+      // Check preference, default to true if not set, or just always do it per requirements
+      const autoLaunch = localStorage.getItem('devussy_auto_launch_irc');
+      if (autoLaunch !== 'false') {
+        // Delay to let page load
         setTimeout(() => {
-          handleHelp();
-          try { localStorage.setItem('devussy_seen_help', '1'); } catch (e) { }
-        }, 300);
+          handleOpenIrc({ isMinimized: true });
+        }, 500);
       }
-    } catch (e) {
-      // localStorage might be unavailable; ignore silently
-    }
+    } catch (e) { }
   }, []);
 
+  // Help window is now shown by default on startup (init state changed above)
+  // This effect is no longer needed
+
   // Render Content based on Window Type
   const renderWindowContent = (window: WindowState) => {
     switch (window.type) {
@@ -489,6 +546,15 @@ export default function Page() {
               <li><strong>Execute</strong> - Generate code for each phase</li>
               <li><strong>Handoff</strong> - Export project and push to GitHub</li>
             </ol>
+
+            <h2 className="text-xl font-semibold mt-6 mb-3">IRC Chat Addon</h2>
+            <p>Devussy now includes a built-in IRC client accessible via the taskbar or desktop icon.</p>
+            <ul className="list-disc list-inside space-y-1">
+              <li>Join <code className="bg-gray-800 px-2 py-1 rounded">#devussy-chat</code> to chat with other users</li>
+              <li>Click on usernames to start private messages</li>
+              <li>Server logs are collected in the <strong>Status</strong> tab</li>
+              <li>Your IRC nickname is saved automatically</li>
+            </ul>
             <h2 className="text-xl font-semibold mt-6 mb-3">Circular Stateless Development</h2>
             <p>Devussy enables <strong>agent-agnostic, stateless development</strong> where any AI agent can pick up where another left off.</p>
 
@@ -512,7 +578,8 @@ export default function Page() {
               <li>Use <strong>checkpoints</strong> to save your progress at any stage</li>
               <li>Edit phases in the Plan view before execution</li>
               <li>Adjust <strong>concurrency</strong> in settings to control parallel execution</li>
-              <li>Windows can be minimized but not closed - find them in the taskbar</li>
+              <li>Windows can be minimized - find them in the taskbar</li>
+              <li>Use the <strong>Start Menu</strong> (Bliss theme) or taskbar to access all features</li>
             </ul>
             <h2 className="text-xl font-semibold mt-6 mb-3">Need More Help?</h2>
             <p>Check the <code className="bg-gray-800 px-2 py-1 rounded">handoff.md</code> file in your project for detailed technical documentation.</p>
@@ -521,18 +588,36 @@ export default function Page() {
             <p>Created by <strong>Kyle Durepos</strong>.</p>
 
             <div className="mt-6 flex items-center justify-between">
-              <label className="flex items-center gap-2 text-sm">
-                <input
-                  type="checkbox"
-                  checked={dontShowHelpAgain}
-                  onChange={(e) => {
-                    const v = e.target.checked;
-                    try { localStorage.setItem('devussy_help_dismissed', v ? '1' : '0'); } catch (err) { }
-                    setDontShowHelpAgain(v);
-                  }}
-                />
-                Don't show this again
-              </label>
+              <div className="flex flex-col gap-2">
+                <label className="flex items-center gap-2 text-sm">
+                  <input
+                    type="checkbox"
+                    checked={dontShowHelpAgain}
+                    onChange={(e) => {
+                      const v = e.target.checked;
+                      try { localStorage.setItem('devussy_help_dismissed', v ? '1' : '0'); } catch (err) { }
+                      setDontShowHelpAgain(v);
+                    }}
+                  />
+                  Don't show this again
+                </label>
+                <label className="flex items-center gap-2 text-xs text-muted-foreground">
+                  <input
+                    type="checkbox"
+                    checked={analyticsOptOut}
+                    onChange={(e) => {
+                      const v = e.target.checked;
+                      try {
+                        const expires = new Date();
+                        expires.setFullYear(expires.getFullYear() + 1);
+                        document.cookie = `devussy_analytics_optout=${v ? '1' : '0'}; path=/; expires=${expires.toUTCString()}; SameSite=Lax`;
+                      } catch (err) { }
+                      setAnalyticsOptOut(v);
+                    }}
+                  />
+                  Disable anonymous usage analytics for this browser
+                </label>
+              </div>
               <div>
                 <Button variant="secondary" onClick={() => closeWindow(window.id)}>
                   Close
@@ -541,13 +626,53 @@ export default function Page() {
             </div>
           </div>
         );
+      case 'irc':
+        return <IrcClient />;
       default:
         return null;
     }
   };
 
   return (
-    <main className="flex min-h-screen flex-col relative bg-transparent">
+    <main className="flex min-h-screen flex-col relative bg-transparent overflow-hidden">
+      {/* Desktop Icons */}
+      {theme === 'bliss' && (
+        <div className="absolute top-4 left-4 z-0 flex flex-col gap-6 p-4">
+          {/* My Computer */}
+          <button
+            className="group flex flex-col items-center w-[70px] gap-1 focus:outline-none"
+            onDoubleClick={handleNewProject}
+          >
+            <div className="w-12 h-12 relative">
+              <img src="/devussy_logo_minimal.png" className="w-full h-full object-contain drop-shadow-md" />
+            </div>
+            <span className="text-white text-xs font-medium px-1 rounded group-hover:bg-[#0B61DE] group-focus:bg-[#0B61DE] group-focus:border group-focus:border-dotted drop-shadow-md text-center leading-tight">
+              My Computer
+            </span>
+          </button>
+
+          {/* mIRC */}
+          <button
+            className="group flex flex-col items-center w-[70px] gap-1 focus:outline-none"
+            onDoubleClick={() => handleOpenIrc()}
+          >
+            <div className="w-12 h-12 relative bg-white/10 rounded-lg border border-white/20 flex items-center justify-center shadow-lg backdrop-blur-sm">
+              {/* Custom mIRC-like icon since we don't have the asset */}
+              <div className="relative w-8 h-8">
+                <div className="absolute inset-0 bg-red-500 rounded-full transform -rotate-12 opacity-80"></div>
+                <div className="absolute inset-0 flex items-center justify-center">
+                  <MessageSquare className="text-white w-5 h-5 transform rotate-12" fill="currentColor" />
+                </div>
+                <div className="absolute -bottom-1 -right-1 bg-green-500 w-3 h-3 rounded-full border-2 border-white"></div>
+              </div>
+            </div>
+            <span className="text-white text-xs font-medium px-1 rounded group-hover:bg-[#0B61DE] group-focus:bg-[#0B61DE] group-focus:border group-focus:border-dotted drop-shadow-md text-center leading-tight">
+              mIRC
+            </span>
+          </button>
+        </div>
+      )}
+
       {/* Global Header / Toolbar (Optional) */}
       {theme !== 'bliss' && (
         <div className="absolute top-4 right-4 z-50 flex items-center gap-2">
@@ -604,6 +729,7 @@ export default function Page() {
         onNewProject={handleNewProject}
         onHelp={handleHelp}
         onOpenModelSettings={handleOpenModelSettings}
+        onOpenIrc={() => handleOpenIrc()}
         currentState={{
           projectName,
           languages,
@@ -616,6 +742,7 @@ export default function Page() {
         modelConfigs={modelConfigs}
         onModelConfigsChange={setModelConfigs}
         activeStage={getActiveStage()}
+        ircNick={ircNick}
       />
     </main>
   );
diff --git a/devussy-web/src/components/addons/irc/IrcClient.tsx b/devussy-web/src/components/addons/irc/IrcClient.tsx
new file mode 100644
index 0000000..89ef443
--- /dev/null
+++ b/devussy-web/src/components/addons/irc/IrcClient.tsx
@@ -0,0 +1,818 @@
+'use client';
+
+import React, { useState, useEffect, useRef, useCallback } from 'react';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { ScrollArea } from '@/components/ui/scroll-area';
+import {
+    Dialog,
+    DialogContent,
+    DialogHeader,
+    DialogTitle,
+    DialogTrigger,
+    DialogFooter,
+} from '@/components/ui/dialog';
+import { X } from 'lucide-react';
+
+interface IrcMessage {
+    id: string;
+    timestamp: string;
+    prefix: string;
+    command: string;
+    params: string[];
+    raw: string;
+    type: 'message' | 'notice' | 'join' | 'part' | 'nick' | 'system' | 'error';
+    sender?: string;
+    content?: string;
+    target?: string; // Channel or Nick
+}
+
+interface IrcUser {
+    nick: string;
+    modes: string;
+}
+
+interface Conversation {
+    name: string;
+    type: 'channel' | 'pm';
+    messages: IrcMessage[];
+    users: IrcUser[]; // Only relevant for channels
+    unreadCount: number;
+}
+
+interface IrcClientProps {
+    initialNick?: string;
+    defaultChannel?: string;
+}
+
+const IRC_COLORS = [
+    'text-red-400',
+    'text-green-400',
+    'text-yellow-400',
+    'text-blue-400',
+    'text-purple-400',
+    'text-pink-400',
+    'text-cyan-400',
+    'text-orange-400',
+];
+
+const getUserColor = (nick: string) => {
+    let hash = 0;
+    for (let i = 0; i < nick.length; i++) {
+        hash = nick.charCodeAt(i) + ((hash << 5) - hash);
+    }
+    const index = Math.abs(hash) % IRC_COLORS.length;
+    return IRC_COLORS[index];
+};
+
+export default function IrcClient({
+    initialNick = 'Guest',
+    defaultChannel = process.env.NEXT_PUBLIC_IRC_CHANNEL || '#devussy-chat',
+}: IrcClientProps) {
+    const [ws, setWs] = useState<WebSocket | null>(null);
+    const [connected, setConnected] = useState(false);
+    const [demoMode, setDemoMode] = useState(false);
+
+    // Multi-conversation state
+    const STATUS_TAB = 'Status';
+    const [conversations, setConversations] = useState<Record<string, Conversation>>({});
+    const [activeTab, setActiveTab] = useState<string>(STATUS_TAB);
+
+    const [nick, setNick] = useState(initialNick);
+    const [inputValue, setInputValue] = useState('');
+    const [newNickInput, setNewNickInput] = useState(initialNick);
+    const [isNickDialogOpen, setIsNickDialogOpen] = useState(false);
+
+    const scrollRef = useRef<HTMLDivElement | null>(null);
+    const messagesEndRef = useRef<HTMLDivElement>(null);
+    const reconnectAttempts = useRef(0);
+    const maxReconnectAttempts = 3;
+
+    const wsUrl =
+        process.env.NEXT_PUBLIC_IRC_WS_URL ||
+        (typeof window !== 'undefined'
+            ? `${window.location.protocol === 'https:' ? 'wss' : 'ws'}://${window.location.host}/ws/irc/`
+            : 'ws://localhost:8080/webirc/websocket/');
+
+    // Ensure Status tab and default channel exist in state
+    useEffect(() => {
+        setConversations(prev => {
+            const needsStatus = !prev[STATUS_TAB];
+            const needsDefault = !prev[defaultChannel];
+
+            if (!needsStatus && !needsDefault) return prev;
+
+            const updates: Record<string, Conversation> = { ...prev };
+
+            if (needsStatus) {
+                updates[STATUS_TAB] = {
+                    name: STATUS_TAB,
+                    type: 'channel',
+                    messages: [],
+                    users: [],
+                    unreadCount: 0
+                };
+            }
+
+            if (needsDefault) {
+                updates[defaultChannel] = {
+                    name: defaultChannel,
+                    type: 'channel',
+                    messages: [],
+                    users: [],
+                    unreadCount: 0
+                };
+            }
+
+            return updates;
+        });
+    }, [defaultChannel, STATUS_TAB]);
+
+    // Auto-scroll logic
+    useEffect(() => {
+        const container = scrollRef.current;
+        if (!container || !messagesEndRef.current) return;
+
+        const distanceFromBottom =
+            container.scrollHeight - container.scrollTop - container.clientHeight;
+
+        if (distanceFromBottom < 80) {
+            messagesEndRef.current.scrollIntoView({ behavior: 'smooth' });
+        }
+    }, [conversations, activeTab]); // Trigger on msg updates
+
+    // Helper to add message to a specific conversation
+    const addMessage = useCallback((target: string, msg: IrcMessage) => {
+        setConversations(prev => {
+            const convName = target;
+            // Create if not exists (e.g. PM)
+            const existing = prev[convName] || {
+                name: convName,
+                type: target.startsWith('#') ? 'channel' : 'pm',
+                messages: [],
+                users: [],
+                unreadCount: 0
+            };
+
+            return {
+                ...prev,
+                [convName]: {
+                    ...existing,
+                    messages: [...existing.messages, msg],
+                    unreadCount: (target !== activeTab) ? existing.unreadCount + 1 : 0
+                }
+            };
+        });
+    }, [activeTab]);
+
+    // Helper to add system message to Status tab
+    const addSystemMessage = useCallback((content: string, type: IrcMessage['type'] = 'system') => {
+        setConversations(prev => {
+            const target = STATUS_TAB;
+            const existing = prev[target] || {
+                name: target,
+                type: 'channel',
+                messages: [],
+                users: [],
+                unreadCount: 0
+            };
+
+            return {
+                ...prev,
+                [target]: {
+                    ...existing,
+                    messages: [...existing.messages, {
+                        id: Math.random().toString(36).substr(2, 9),
+                        timestamp: new Date().toLocaleTimeString(),
+                        prefix: 'system',
+                        command: 'SYSTEM',
+                        params: [],
+                        raw: '',
+                        type,
+                        sender: 'System',
+                        content,
+                        target
+                    }]
+                }
+            };
+        });
+    }, [STATUS_TAB]);
+
+    // Parse IRC Message
+    const parseIrcMessage = (raw: string): IrcMessage => {
+        let str = raw.trim();
+        let prefix = '';
+        let command = '';
+        let params: string[] = [];
+
+        if (str.startsWith(':')) {
+            const spaceIdx = str.indexOf(' ');
+            if (spaceIdx !== -1) {
+                prefix = str.slice(1, spaceIdx);
+                str = str.slice(spaceIdx + 1);
+            }
+        }
+
+        const spaceIdx = str.indexOf(' ');
+        if (spaceIdx !== -1) {
+            command = str.slice(0, spaceIdx);
+            str = str.slice(spaceIdx + 1);
+        } else {
+            command = str;
+            str = '';
+        }
+
+        while (str) {
+            if (str.startsWith(':')) {
+                params.push(str.slice(1));
+                break;
+            }
+            const nextSpace = str.indexOf(' ');
+            if (nextSpace !== -1) {
+                params.push(str.slice(0, nextSpace));
+                str = str.slice(nextSpace + 1);
+            } else {
+                params.push(str);
+                break;
+            }
+        }
+
+        let type: IrcMessage['type'] = 'system';
+        let content = '';
+        let sender = prefix.split('!')[0] || prefix;
+        let target = '';
+
+        if (command === 'PRIVMSG') {
+            type = 'message';
+            target = params[0];
+            content = params[1] || '';
+        } else if (command === 'JOIN') {
+            type = 'join';
+            target = params[0].replace(/^:/, ''); // Should be channel
+            content = `${sender} joined ${target}`;
+        } else if (command === 'PART' || command === 'QUIT') {
+            type = 'part';
+            target = params[0]; // Often channel for PART
+            content = `${sender} left: ${params[1] || 'Quit'}`;
+        } else if (command === 'NICK') {
+            type = 'nick';
+            content = `${sender} is now known as ${params[0]}`;
+        } else if (command === 'NOTICE') {
+            type = 'notice';
+            target = params[0];
+            content = params[1] || '';
+        } else if (command === '433') {
+            type = 'error';
+            content = `Nickname ${params[1]} is already in use.`;
+        }
+
+        return {
+            id: Math.random().toString(36).substr(2, 9),
+            timestamp: new Date().toLocaleTimeString(),
+            prefix,
+            command,
+            params,
+            raw,
+            type,
+            sender,
+            content,
+            target
+        };
+    };
+
+    // Connect to IRC
+    const connect = useCallback(() => {
+        if (demoMode) return;
+
+        try {
+            const socket = new WebSocket(wsUrl);
+
+            socket.onopen = () => {
+                setConnected(true);
+                reconnectAttempts.current = 0;
+                addSystemMessage('Connected to IRC Gateway');
+
+                socket.send(`NICK ${nick}\r\n`);
+                socket.send(`USER ${nick} 0 * :${nick}\r\n`);
+            };
+
+            socket.onmessage = (event) => {
+                const lines = event.data.split('\r\n');
+                lines.forEach((line: string) => {
+                    if (!line) return;
+
+                    const msg = parseIrcMessage(line);
+
+                    // Handle server PING (with or without prefix)
+                    if (msg.command === 'PING') {
+                        const cookie = msg.params[0] ? `:${msg.params[0]}` : '';
+                        const response = `PONG ${cookie}\r\n`;
+                        socket.send(response);
+                        return;
+                    }
+
+                    // --- Logic for State Updates ---
+
+                    // 1. Numeric / System
+                    if (['001', '002', '003', '004', '005', '251', '252', '253', '254', '255', '366', '372', '376', '422'].includes(msg.command)) {
+                        // Capture Nick from 001
+                        if (msg.command === '001' && msg.params[0]) {
+                            const assignedNick = msg.params[0];
+                            if (assignedNick !== nick) {
+                                setNick(assignedNick);
+                                localStorage.setItem('devussy_irc_nick', assignedNick);
+                            }
+                        }
+
+                        // Just dump into Status tab
+                        if (msg.command === '376' || msg.command === '422') {
+                            // End of MOTD -> Auto Join
+                            socket.send(`JOIN ${defaultChannel}\r\n`);
+                        }
+                        // Add to Status tab to be visible
+                        addMessage(STATUS_TAB, { ...msg, type: 'system', content: msg.params.slice(1).join(' ') });
+                    }
+                    // 2. Names List (353)
+                    else if (msg.command === '353') {
+                        const channelName = msg.params[2];
+                        const names = msg.params[3].split(' ').filter(n => n).map(n => {
+                            let mode = '';
+                            let name = n;
+                            if (['@', '+', '%'].includes(n[0])) {
+                                mode = n[0];
+                                name = n.slice(1);
+                            }
+                            return { nick: name, modes: mode };
+                        });
+                        setConversations(prev => {
+                            const c = prev[channelName];
+                            if (!c) return prev;
+                            // Merge names
+                            const existing = new Set(c.users.map(u => u.nick));
+                            const newUsers = names.filter(u => !existing.has(u.nick));
+                            return { ...prev, [channelName]: { ...c, users: [...c.users, ...newUsers] } };
+                        });
+                    }
+                    // 3. JOIN
+                    else if (msg.command === 'JOIN') {
+                        const channelName = msg.target || msg.params[0];
+                        if (msg.sender === nick) {
+                            // We joined a channel -> Create tab if missing, clear users
+                            setConversations(prev => ({
+                                ...prev,
+                                [channelName]: {
+                                    name: channelName,
+                                    type: 'channel',
+                                    messages: [...(prev[channelName]?.messages || []), msg],
+                                    users: [], // Reset user list, wait for 353 or add self
+                                    unreadCount: 0
+                                }
+                            }));
+                            // Switch to it if we just joined? Maybe.
+                            setActiveTab(channelName);
+                        } else {
+                            // Someone else joined
+                            setConversations(prev => {
+                                const c = prev[channelName];
+                                if (!c) return prev;
+                                return {
+                                    ...prev,
+                                    [channelName]: {
+                                        ...c,
+                                        messages: [...c.messages, msg],
+                                        users: [...c.users, { nick: msg.sender || 'Unknown', modes: '' }]
+                                    }
+                                };
+                            });
+                        }
+                    }
+                    // 4. PART / QUIT
+                    else if (msg.command === 'PART') {
+                        const channelName = msg.target || msg.params[0];
+                        if (msg.sender === nick) {
+                            // We left? Close tab? Or just show we left.
+                            // For now just show message.
+                            addMessage(channelName, msg);
+                        } else {
+                            setConversations(prev => {
+                                const c = prev[channelName];
+                                if (!c) return prev;
+                                return {
+                                    ...prev,
+                                    [channelName]: {
+                                        ...c,
+                                        messages: [...c.messages, msg],
+                                        users: c.users.filter(u => u.nick !== msg.sender)
+                                    }
+                                };
+                            });
+                        }
+                    }
+                    else if (msg.command === 'QUIT') {
+                        // Remove from ALL channels
+                        setConversations(prev => {
+                            const next = { ...prev };
+                            Object.keys(next).forEach(k => {
+                                if (next[k].type === 'channel') {
+                                    const hasUser = next[k].users.some(u => u.nick === msg.sender);
+                                    if (hasUser) {
+                                        next[k] = {
+                                            ...next[k],
+                                            messages: [...next[k].messages, msg],
+                                            users: next[k].users.filter(u => u.nick !== msg.sender)
+                                        };
+                                    }
+                                }
+                            });
+                            return next;
+                        });
+                    }
+                    // 5. PRIVMSG
+                    else if (msg.command === 'PRIVMSG') {
+                        if (msg.target === nick) {
+                            // PM received -> Open tab for SENDER
+                            const pmPartner = msg.sender || 'Unknown';
+                            addMessage(pmPartner, msg);
+                        } else {
+                            // Channel message
+                            addMessage(msg.target || 'Unknown', msg);
+                        }
+                    }
+                    // 6. NICK
+                    else if (msg.command === 'NICK') {
+                        const oldNick = msg.sender;
+                        const newNickName = msg.params[0];
+
+                        if (oldNick === nick) {
+                            setNick(newNickName); // Update local state only when server confirms!
+                            localStorage.setItem('devussy_irc_nick', newNickName);
+                        }
+
+                        // Update in all channels
+                        setConversations(prev => {
+                            const next = { ...prev };
+                            Object.keys(next).forEach(k => {
+                                if (next[k].type === 'channel') {
+                                    const userIdx = next[k].users.findIndex(u => u.nick === oldNick);
+                                    if (userIdx !== -1) {
+                                        const newUsers = [...next[k].users];
+                                        newUsers[userIdx] = { ...newUsers[userIdx], nick: newNickName };
+                                        next[k] = {
+                                            ...next[k],
+                                            users: newUsers,
+                                            messages: [...next[k].messages, msg]
+                                        };
+                                    }
+                                } else if (k === oldNick) {
+                                    // Rename PM tab? Complex. For now just log.
+                                    next[k] = {
+                                        ...next[k],
+                                        messages: [...next[k].messages, msg]
+                                    };
+                                }
+                            });
+                            return next;
+                        });
+                    }
+                    // 7. Error
+                    else if (msg.type === 'error') {
+                        addSystemMessage(`Error: ${msg.content}`);
+
+                        // Auto-retry on Nickname In Use (433)
+                        if (msg.command === '433') {
+                            const newNick = nick + '_';
+                            // Update local state immediately so we don't loop forever on the same nick
+                            setNick(newNick);
+                            // Also update localStorage so next reload uses the working nick
+                            localStorage.setItem('devussy_irc_nick', newNick);
+
+                            socket.send(`NICK ${newNick}\r\n`);
+                            addSystemMessage(`Nickname taken, retrying as ${newNick}...`);
+                        }
+                    }
+                });
+            };
+
+            socket.onclose = () => {
+                console.log('IRC Disconnected');
+                setConnected(false);
+                addSystemMessage('Disconnected from server', 'error');
+
+                if (reconnectAttempts.current < maxReconnectAttempts) {
+                    reconnectAttempts.current++;
+                    addSystemMessage(`Reconnecting in 2s... (Attempt ${reconnectAttempts.current}/${maxReconnectAttempts})`);
+                    setTimeout(connect, 2000);
+                } else {
+                    addSystemMessage('Could not connect. Switching to Demo Mode.');
+                    setDemoMode(true);
+                }
+            };
+
+            socket.onerror = (err) => {
+                console.error("WebSocket error:", err);
+            };
+
+            setWs(socket);
+
+            return () => {
+                socket.close();
+            };
+        } catch (e) {
+            console.error("Connection failed", e);
+            setDemoMode(true);
+        }
+    }, [nick, defaultChannel, wsUrl, demoMode, addSystemMessage, addMessage, activeTab]); // activeTab dep is okay-ish for system msg
+
+    // Initial load
+    useEffect(() => {
+        const savedNick = localStorage.getItem('devussy_irc_nick');
+        if (savedNick) {
+            setNick(savedNick);
+            setNewNickInput(savedNick);
+        } else {
+            const randomNick = `Guest${Math.floor(1000 + Math.random() * 9000)}`;
+            setNick(randomNick);
+            setNewNickInput(randomNick);
+            localStorage.setItem('devussy_irc_nick', randomNick);
+        }
+    }, []);
+
+    const handleToggleConnection = () => {
+        if (connected) {
+            if (ws) {
+                ws.close();
+                setWs(null);
+            }
+            setConnected(false);
+            addSystemMessage('Disconnected from server (Manual)');
+        } else {
+            connect();
+        }
+    };
+
+    const handleSendMessage = (e?: React.FormEvent) => {
+        if (e) e.preventDefault();
+        if (!inputValue.trim()) return;
+
+        const currentTabType = conversations[activeTab]?.type || 'channel';
+
+        if (inputValue.startsWith('/')) {
+            const parts = inputValue.slice(1).split(' ');
+            const cmd = parts[0].toUpperCase();
+
+            if (cmd === 'NICK') {
+                ws?.send(`NICK ${parts[1]}\r\n`);
+            } else if (cmd === 'JOIN') {
+                const channel = parts[1];
+                if (channel) ws?.send(`JOIN ${channel}\r\n`);
+            } else if (cmd === 'PART') {
+                const target = parts[1] || activeTab;
+                ws?.send(`PART ${target}\r\n`);
+                // Optionally close tab locally
+                setConversations(prev => {
+                    const next = { ...prev };
+                    delete next[target];
+                    return next;
+                });
+                if (activeTab === target) setActiveTab(defaultChannel);
+            } else if (cmd === 'MSG' || cmd === 'QUERY') {
+                const target = parts[1];
+                const msg = parts.slice(2).join(' ');
+                if (target && msg) {
+                    ws?.send(`PRIVMSG ${target} :${msg}\r\n`);
+                    // Optimistically add to PM tab
+                    addMessage(target, {
+                        id: Date.now().toString(),
+                        timestamp: new Date().toLocaleTimeString(),
+                        prefix: `${nick}!me@here`,
+                        command: 'PRIVMSG',
+                        params: [target, msg],
+                        raw: '',
+                        type: 'message',
+                        sender: nick,
+                        content: msg,
+                        target
+                    });
+                    setActiveTab(target);
+                }
+            } else if (cmd === 'HELP') {
+                addSystemMessage(`Available commands:
+/NICK <newname> - Change nickname
+/JOIN <#channel> - Join a channel
+/PART [#channel] - Leave current or specific channel
+/MSG <nick> <message> - Send private message
+/ME <action> - Send action
+/HELP - Show this help`);
+            } else if (cmd === 'ME') {
+                ws?.send(`PRIVMSG ${activeTab} :\u0001ACTION ${parts.slice(1).join(' ')}\u0001\r\n`);
+                // Optimistic add?
+            } else {
+                addSystemMessage(`Unknown command: ${cmd}`);
+            }
+        } else {
+            if (ws && connected) {
+                ws.send(`PRIVMSG ${activeTab} :${inputValue}\r\n`);
+                // Optimistically add OWN message to current tab
+                addMessage(activeTab, {
+                    id: Date.now().toString(),
+                    timestamp: new Date().toLocaleTimeString(),
+                    prefix: `${nick}!me@host`, // Mock prefix
+                    command: 'PRIVMSG',
+                    params: [activeTab, inputValue],
+                    raw: '',
+                    type: 'message',
+                    sender: nick,
+                    content: inputValue,
+                    target: activeTab
+                });
+            }
+        }
+        setInputValue('');
+    };
+
+    const handleChangeNick = () => {
+        if (newNickInput && newNickInput !== nick) {
+            if (ws && connected) {
+                ws.send(`NICK ${newNickInput}\r\n`);
+                // Do NOT setNick here. Wait for server confirmation.
+            }
+            setIsNickDialogOpen(false);
+        }
+    };
+
+    const handleUserClick = (targetNick: string) => {
+        if (targetNick === nick) return;
+        setConversations(prev => {
+            if (prev[targetNick]) return prev;
+            return {
+                ...prev,
+                [targetNick]: {
+                    name: targetNick,
+                    type: 'pm',
+                    messages: [],
+                    users: [],
+                    unreadCount: 0
+                }
+            };
+        });
+        setActiveTab(targetNick);
+    };
+
+    const closeTab = (e: React.MouseEvent, tabName: string) => {
+        e.stopPropagation();
+        if (tabName === STATUS_TAB || tabName === defaultChannel) return; // Don't close Status or main
+
+        if (conversations[tabName]?.type === 'channel') {
+            ws?.send(`PART ${tabName}\r\n`);
+        }
+
+        setConversations(prev => {
+            const next = { ...prev };
+            delete next[tabName];
+            return next;
+        });
+        if (activeTab === tabName) setActiveTab(defaultChannel);
+    };
+
+    return (
+        <div className="flex h-full w-full bg-background text-foreground overflow-hidden">
+            {/* Main Chat Area */}
+            <div className="flex-1 flex flex-col min-w-0">
+                <div className="border-b bg-muted/20 flex flex-col">
+                    <div className="p-2 flex justify-between items-center border-b border-white/10">
+                        <div className="font-bold flex items-center gap-2">
+                            <span>Devussy IRC</span>
+                            {demoMode && <span className="text-xs bg-yellow-600 text-white px-1 rounded">DEMO</span>}
+                            <span className="text-xs text-muted-foreground ml-2">({nick})</span>
+                        </div>
+                        <div className="flex items-center gap-2">
+                            <Button
+                                variant={connected ? "destructive" : "default"}
+                                size="sm"
+                                className="h-7 text-xs"
+                                onClick={handleToggleConnection}
+                            >
+                                {connected ? "Disconnect" : "Connect"}
+                            </Button>
+                            <Dialog open={isNickDialogOpen} onOpenChange={setIsNickDialogOpen}>
+                                <DialogTrigger asChild>
+                                    <Button variant="outline" size="sm" className="h-7 text-xs">Change Nick</Button>
+                                </DialogTrigger>
+                                <DialogContent>
+                                    <DialogHeader>
+                                        <DialogTitle>Change Nickname</DialogTitle>
+                                    </DialogHeader>
+                                    <div className="py-4">
+                                        <Input
+                                            value={newNickInput}
+                                            onChange={(e) => setNewNickInput(e.target.value)}
+                                            placeholder="Enter new nickname"
+                                        />
+                                    </div>
+                                    <DialogFooter>
+                                        <Button onClick={handleChangeNick}>Save</Button>
+                                    </DialogFooter>
+                                </DialogContent>
+                            </Dialog>
+                        </div>
+                    </div>
+
+                    {/* Tabs */}
+                    <div className="flex items-center gap-1 px-2 pt-2 overflow-x-auto">
+                        {[STATUS_TAB, ...Object.keys(conversations).filter(k => k !== STATUS_TAB)]
+                            .filter(name => conversations[name]) // Only show tabs that exist
+                            .map(name => (
+                                <div
+                                    key={name}
+                                    onClick={() => setActiveTab(name)}
+                                    className={`
+                            group flex items-center gap-2 px-3 py-1.5 rounded-t-md cursor-pointer text-sm border-t border-l border-r select-none
+                            ${activeTab === name ? 'bg-background border-border font-bold' : 'bg-muted/50 border-transparent opacity-70 hover:opacity-100'}
+                        `}
+                                >
+                                    <span>{name}</span>
+                                    {conversations[name].unreadCount > 0 && (
+                                        <span className="bg-red-500 text-white text-[10px] px-1 rounded-full">{conversations[name].unreadCount}</span>
+                                    )}
+                                    {name !== STATUS_TAB && name !== defaultChannel && (
+                                        <X
+                                            className="h-3 w-3 opacity-0 group-hover:opacity-100 hover:bg-red-500 hover:text-white rounded"
+                                            onClick={(e) => closeTab(e, name)}
+                                        />
+                                    )}
+                                </div>
+                            ))}
+                    </div>
+                </div>
+
+                <div ref={scrollRef} className="flex-1 p-4 overflow-y-auto">
+                    <div className="space-y-1">
+                        {conversations[activeTab]?.messages.map((msg, i) => (
+                            <div key={i} className="text-sm break-words font-mono">
+                                <span className="text-muted-foreground text-xs mr-2">[{msg.timestamp}]</span>
+                                {msg.type === 'message' && (
+                                    <>
+                                        <span className={`font-bold mr-2 ${getUserColor(msg.sender || '')}`}>{msg.sender}:</span>
+                                        <span>{msg.content}</span>
+                                    </>
+                                )}
+                                {msg.type === 'join' && (
+                                    <span className="text-green-500 italic">→ {msg.content}</span>
+                                )}
+                                {msg.type === 'part' && (
+                                    <span className="text-red-500 italic">← {msg.content}</span>
+                                )}
+                                {msg.type === 'nick' && (
+                                    <span className="text-yellow-500 italic">• {msg.content}</span>
+                                )}
+                                {msg.type === 'system' && (
+                                    <span className="text-muted-foreground italic">* {msg.content}</span>
+                                )}
+                                {msg.type === 'error' && (
+                                    <span className="text-red-600 font-bold">! {msg.content}</span>
+                                )}
+                            </div>
+                        ))}
+                        <div ref={messagesEndRef} />
+                    </div>
+                </div>
+
+                <div className="p-2 border-t bg-muted/10">
+                    <form onSubmit={handleSendMessage} className="flex gap-2">
+                        <Input
+                            value={inputValue}
+                            onChange={(e) => setInputValue(e.target.value)}
+                            placeholder={`Message ${activeTab}...`}
+                            className="flex-1 font-mono"
+                        />
+                        <Button type="submit">Send</Button>
+                    </form>
+                </div>
+            </div>
+
+            {/* User List Sidebar (Only for channels) */}
+            {conversations[activeTab]?.type === 'channel' && (
+                <div className="w-48 border-l bg-muted/10 flex flex-col hidden md:flex">
+                    <div className="p-2 border-b font-semibold text-xs uppercase tracking-wider text-muted-foreground">
+                        Users ({conversations[activeTab]?.users.length || 0})
+                    </div>
+                    <ScrollArea className="flex-1 p-2">
+                        <div className="space-y-1">
+                            {conversations[activeTab]?.users.sort((a, b) => a.nick.localeCompare(b.nick)).map((user) => (
+                                <div
+                                    key={user.nick}
+                                    className="text-sm flex items-center gap-1 font-mono cursor-pointer hover:bg-white/10 p-0.5 rounded"
+                                    onClick={() => handleUserClick(user.nick)}
+                                >
+                                    <span className="text-muted-foreground w-3 text-center">{user.modes}</span>
+                                    <span className={getUserColor(user.nick)}>{user.nick}</span>
+                                </div>
+                            ))}
+                        </div>
+                    </ScrollArea>
+                </div>
+            )}
+        </div>
+    );
+}
diff --git a/devussy-web/src/components/pipeline/ComplexityAssessment.stories.tsx b/devussy-web/src/components/pipeline/ComplexityAssessment.stories.tsx
new file mode 100644
index 0000000..66035de
--- /dev/null
+++ b/devussy-web/src/components/pipeline/ComplexityAssessment.stories.tsx
@@ -0,0 +1,113 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ComplexityAssessment, ComplexityBadge, ComplexityProfile } from './ComplexityAssessment';
+
+const meta: Meta<typeof ComplexityAssessment> = {
+  title: 'Pipeline/ComplexityAssessment',
+  component: ComplexityAssessment,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof ComplexityAssessment>;
+
+const minimalProfile: ComplexityProfile = {
+  project_type_bucket: 'cli_tool',
+  technical_complexity_bucket: 'simple_crud',
+  integration_bucket: 'standalone',
+  team_size_bucket: 'solo',
+  score: 1.5,
+  estimated_phase_count: 3,
+  depth_level: 'minimal',
+  confidence: 0.95,
+};
+
+const standardProfile: ComplexityProfile = {
+  project_type_bucket: 'web_app',
+  technical_complexity_bucket: 'auth_db',
+  integration_bucket: '3_5_services',
+  team_size_bucket: '2_3',
+  score: 6.0,
+  estimated_phase_count: 5,
+  depth_level: 'standard',
+  confidence: 0.82,
+};
+
+const detailedProfile: ComplexityProfile = {
+  project_type_bucket: 'saas',
+  technical_complexity_bucket: 'multi_region',
+  integration_bucket: '6_plus_services',
+  team_size_bucket: '7_plus',
+  score: 18.0,
+  estimated_phase_count: 13,
+  depth_level: 'detailed',
+  confidence: 0.65,
+};
+
+export const Minimal: Story = {
+  args: {
+    profile: minimalProfile,
+    showDetails: true,
+  },
+};
+
+export const Standard: Story = {
+  args: {
+    profile: standardProfile,
+    showDetails: true,
+  },
+};
+
+export const Detailed: Story = {
+  args: {
+    profile: detailedProfile,
+    showDetails: true,
+  },
+};
+
+export const WithoutDetails: Story = {
+  args: {
+    profile: standardProfile,
+    showDetails: false,
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    profile: standardProfile,
+    isLoading: true,
+  },
+};
+
+export const WithRefresh: Story = {
+  args: {
+    profile: standardProfile,
+    showDetails: true,
+    onRefresh: () => console.log('Refresh clicked'),
+  },
+};
+
+export const LowConfidence: Story = {
+  args: {
+    profile: {
+      ...standardProfile,
+      confidence: 0.45,
+    },
+    showDetails: true,
+  },
+};
+
+// Badge stories
+export const MinimalBadge: StoryObj<typeof ComplexityBadge> = {
+  render: () => <ComplexityBadge profile={minimalProfile} />,
+};
+
+export const StandardBadge: StoryObj<typeof ComplexityBadge> = {
+  render: () => <ComplexityBadge profile={standardProfile} />,
+};
+
+export const DetailedBadge: StoryObj<typeof ComplexityBadge> = {
+  render: () => <ComplexityBadge profile={detailedProfile} />,
+};
diff --git a/devussy-web/src/components/pipeline/ComplexityAssessment.tsx b/devussy-web/src/components/pipeline/ComplexityAssessment.tsx
new file mode 100644
index 0000000..bc64434
--- /dev/null
+++ b/devussy-web/src/components/pipeline/ComplexityAssessment.tsx
@@ -0,0 +1,356 @@
+"use client";
+
+import React from 'react';
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+import { 
+    Gauge, 
+    Layers, 
+    Microscope, 
+    ShieldCheck, 
+    AlertTriangle,
+    CheckCircle2,
+    Clock,
+    Users,
+    Boxes
+} from "lucide-react";
+
+/**
+ * Complexity profile data structure matching backend ComplexityProfile
+ */
+export interface ComplexityProfile {
+    project_type_bucket: string;
+    technical_complexity_bucket: string;
+    integration_bucket: string;
+    team_size_bucket: string;
+    score: number;
+    estimated_phase_count: number;
+    depth_level: 'minimal' | 'standard' | 'detailed';
+    confidence: number;
+}
+
+interface ComplexityAssessmentProps {
+    profile: ComplexityProfile;
+    isLoading?: boolean;
+    showDetails?: boolean;
+    onRefresh?: () => void;
+}
+
+/**
+ * Visual mapping for depth levels
+ */
+const DEPTH_CONFIG = {
+    minimal: {
+        label: 'Minimal',
+        color: 'text-green-500',
+        bgColor: 'bg-green-500/10',
+        borderColor: 'border-green-500/30',
+        description: '3-5 phases, concise output'
+    },
+    standard: {
+        label: 'Standard',
+        color: 'text-blue-500',
+        bgColor: 'bg-blue-500/10',
+        borderColor: 'border-blue-500/30',
+        description: '5-7 phases, balanced detail'
+    },
+    detailed: {
+        label: 'Detailed',
+        color: 'text-purple-500',
+        bgColor: 'bg-purple-500/10',
+        borderColor: 'border-purple-500/30',
+        description: '7-11 phases, comprehensive'
+    }
+};
+
+/**
+ * Format bucket names for display
+ */
+function formatBucket(bucket: string): string {
+    return bucket
+        .replace(/_/g, ' ')
+        .replace(/\b\w/g, c => c.toUpperCase());
+}
+
+/**
+ * Get color class based on score (0-20 scale)
+ */
+function getScoreColor(score: number): string {
+    if (score <= 3) return 'text-green-500';
+    if (score <= 7) return 'text-blue-500';
+    if (score <= 12) return 'text-yellow-500';
+    if (score <= 16) return 'text-orange-500';
+    return 'text-red-500';
+}
+
+/**
+ * Get confidence indicator
+ */
+function getConfidenceIndicator(confidence: number): { icon: typeof CheckCircle2; color: string; label: string } {
+    if (confidence >= 0.8) {
+        return { icon: CheckCircle2, color: 'text-green-500', label: 'High' };
+    }
+    if (confidence >= 0.6) {
+        return { icon: ShieldCheck, color: 'text-yellow-500', label: 'Medium' };
+    }
+    return { icon: AlertTriangle, color: 'text-orange-500', label: 'Low' };
+}
+
+/**
+ * Complexity score gauge component
+ */
+function ScoreGauge({ score, maxScore = 20 }: { score: number; maxScore?: number }) {
+    const percentage = (score / maxScore) * 100;
+    const circumference = 2 * Math.PI * 40; // radius of 40
+    const strokeDashoffset = circumference - (percentage / 100) * circumference;
+
+    return (
+        <div className="relative w-28 h-28">
+            <svg className="w-full h-full transform -rotate-90" viewBox="0 0 100 100">
+                {/* Background circle */}
+                <circle
+                    cx="50"
+                    cy="50"
+                    r="40"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="8"
+                    className="text-muted/20"
+                />
+                {/* Progress circle */}
+                <circle
+                    cx="50"
+                    cy="50"
+                    r="40"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="8"
+                    strokeLinecap="round"
+                    strokeDasharray={circumference}
+                    strokeDashoffset={strokeDashoffset}
+                    className={getScoreColor(score)}
+                    style={{ transition: 'stroke-dashoffset 0.5s ease-in-out' }}
+                />
+            </svg>
+            <div className="absolute inset-0 flex flex-col items-center justify-center">
+                <span className={`text-2xl font-bold ${getScoreColor(score)}`}>
+                    {score.toFixed(1)}
+                </span>
+                <span className="text-xs text-muted-foreground">/ {maxScore}</span>
+            </div>
+        </div>
+    );
+}
+
+/**
+ * Metric card for individual complexity factors
+ */
+function MetricCard({ 
+    icon: Icon, 
+    label, 
+    value, 
+    subtext 
+}: { 
+    icon: typeof Boxes; 
+    label: string; 
+    value: string; 
+    subtext?: string 
+}) {
+    return (
+        <div className="flex items-center gap-3 p-3 rounded-lg bg-muted/30 border border-border/50">
+            <div className="p-2 rounded-md bg-primary/10">
+                <Icon className="h-4 w-4 text-primary" />
+            </div>
+            <div className="flex-1 min-w-0">
+                <p className="text-xs text-muted-foreground">{label}</p>
+                <p className="text-sm font-medium truncate">{value}</p>
+                {subtext && <p className="text-xs text-muted-foreground">{subtext}</p>}
+            </div>
+        </div>
+    );
+}
+
+/**
+ * ComplexityAssessment Component
+ * 
+ * Displays a visual representation of the project complexity profile
+ * including score gauge, depth level, phase count, and individual factors.
+ */
+export function ComplexityAssessment({ 
+    profile, 
+    isLoading = false, 
+    showDetails = true,
+    onRefresh 
+}: ComplexityAssessmentProps) {
+    const depthConfig = DEPTH_CONFIG[profile.depth_level];
+    const confidenceInfo = getConfidenceIndicator(profile.confidence);
+    const ConfidenceIcon = confidenceInfo.icon;
+
+    if (isLoading) {
+        return (
+            <Card className="animate-pulse">
+                <CardHeader>
+                    <div className="h-6 bg-muted rounded w-48" />
+                    <div className="h-4 bg-muted rounded w-64 mt-2" />
+                </CardHeader>
+                <CardContent>
+                    <div className="h-32 bg-muted rounded" />
+                </CardContent>
+            </Card>
+        );
+    }
+
+    return (
+        <Card className="overflow-hidden">
+            <CardHeader className="border-b border-border/50">
+                <div className="flex items-center justify-between">
+                    <div>
+                        <CardTitle className="flex items-center gap-2">
+                            <Gauge className="h-5 w-5 text-primary" />
+                            Complexity Assessment
+                        </CardTitle>
+                        <CardDescription>
+                            Adaptive pipeline configuration based on project analysis
+                        </CardDescription>
+                    </div>
+                    {onRefresh && (
+                        <button 
+                            onClick={onRefresh}
+                            className="text-sm text-primary hover:underline"
+                        >
+                            Refresh
+                        </button>
+                    )}
+                </div>
+            </CardHeader>
+
+            <CardContent className="pt-6">
+                {/* Main metrics row */}
+                <div className="flex items-start gap-8 mb-6">
+                    {/* Score gauge */}
+                    <div className="flex flex-col items-center">
+                        <ScoreGauge score={profile.score} />
+                        <p className="text-sm text-muted-foreground mt-2">Complexity Score</p>
+                    </div>
+
+                    {/* Key metrics */}
+                    <div className="flex-1 grid grid-cols-2 gap-4">
+                        {/* Depth Level */}
+                        <div className={`p-4 rounded-lg border ${depthConfig.borderColor} ${depthConfig.bgColor}`}>
+                            <div className="flex items-center gap-2 mb-1">
+                                <Microscope className={`h-4 w-4 ${depthConfig.color}`} />
+                                <span className="text-sm font-medium">Depth Level</span>
+                            </div>
+                            <p className={`text-lg font-bold ${depthConfig.color}`}>
+                                {depthConfig.label}
+                            </p>
+                            <p className="text-xs text-muted-foreground mt-1">
+                                {depthConfig.description}
+                            </p>
+                        </div>
+
+                        {/* Phase Count */}
+                        <div className="p-4 rounded-lg border border-border/50 bg-muted/20">
+                            <div className="flex items-center gap-2 mb-1">
+                                <Layers className="h-4 w-4 text-primary" />
+                                <span className="text-sm font-medium">Estimated Phases</span>
+                            </div>
+                            <p className="text-lg font-bold text-primary">
+                                {profile.estimated_phase_count}
+                            </p>
+                            <p className="text-xs text-muted-foreground mt-1">
+                                Development phases
+                            </p>
+                        </div>
+
+                        {/* Confidence */}
+                        <div className="p-4 rounded-lg border border-border/50 bg-muted/20">
+                            <div className="flex items-center gap-2 mb-1">
+                                <ConfidenceIcon className={`h-4 w-4 ${confidenceInfo.color}`} />
+                                <span className="text-sm font-medium">Confidence</span>
+                            </div>
+                            <p className={`text-lg font-bold ${confidenceInfo.color}`}>
+                                {(profile.confidence * 100).toFixed(0)}%
+                            </p>
+                            <p className="text-xs text-muted-foreground mt-1">
+                                {confidenceInfo.label} confidence
+                            </p>
+                        </div>
+
+                        {/* Timeline indicator */}
+                        <div className="p-4 rounded-lg border border-border/50 bg-muted/20">
+                            <div className="flex items-center gap-2 mb-1">
+                                <Clock className="h-4 w-4 text-muted-foreground" />
+                                <span className="text-sm font-medium">Scale</span>
+                            </div>
+                            <p className="text-lg font-bold">
+                                {profile.score <= 3 ? 'Simple' : 
+                                 profile.score <= 7 ? 'Moderate' :
+                                 profile.score <= 12 ? 'Complex' : 'Enterprise'}
+                            </p>
+                            <p className="text-xs text-muted-foreground mt-1">
+                                Project scale
+                            </p>
+                        </div>
+                    </div>
+                </div>
+
+                {/* Detailed breakdown */}
+                {showDetails && (
+                    <div className="border-t border-border/50 pt-4">
+                        <h4 className="text-sm font-medium mb-3 text-muted-foreground">
+                            Complexity Factors
+                        </h4>
+                        <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
+                            <MetricCard
+                                icon={Boxes}
+                                label="Project Type"
+                                value={formatBucket(profile.project_type_bucket)}
+                            />
+                            <MetricCard
+                                icon={Layers}
+                                label="Technical Complexity"
+                                value={formatBucket(profile.technical_complexity_bucket)}
+                            />
+                            <MetricCard
+                                icon={Boxes}
+                                label="Integrations"
+                                value={formatBucket(profile.integration_bucket)}
+                            />
+                            <MetricCard
+                                icon={Users}
+                                label="Team Size"
+                                value={formatBucket(profile.team_size_bucket)}
+                            />
+                        </div>
+                    </div>
+                )}
+            </CardContent>
+        </Card>
+    );
+}
+
+/**
+ * Compact version for embedding in other views
+ */
+export function ComplexityBadge({ profile }: { profile: ComplexityProfile }) {
+    const depthConfig = DEPTH_CONFIG[profile.depth_level];
+
+    return (
+        <div className={`inline-flex items-center gap-2 px-3 py-1.5 rounded-full text-sm ${depthConfig.bgColor} ${depthConfig.borderColor} border`}>
+            <Gauge className={`h-4 w-4 ${depthConfig.color}`} />
+            <span className={`font-medium ${depthConfig.color}`}>
+                {profile.score.toFixed(1)}
+            </span>
+            <span className="text-muted-foreground">|</span>
+            <span className="text-muted-foreground">
+                {profile.estimated_phase_count} phases
+            </span>
+            <span className="text-muted-foreground">|</span>
+            <span className={depthConfig.color}>
+                {depthConfig.label}
+            </span>
+        </div>
+    );
+}
+
+export default ComplexityAssessment;
diff --git a/devussy-web/src/components/pipeline/CorrectionTimeline.stories.tsx b/devussy-web/src/components/pipeline/CorrectionTimeline.stories.tsx
new file mode 100644
index 0000000..6f04b0c
--- /dev/null
+++ b/devussy-web/src/components/pipeline/CorrectionTimeline.stories.tsx
@@ -0,0 +1,177 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { CorrectionTimeline, CorrectionBadge, CorrectionHistory } from './CorrectionTimeline';
+
+const meta: Meta<typeof CorrectionTimeline> = {
+  title: 'Pipeline/CorrectionTimeline',
+  component: CorrectionTimeline,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof CorrectionTimeline>;
+
+const successHistory: CorrectionHistory = {
+  total_iterations: 2,
+  max_iterations: 3,
+  final_status: 'success',
+  iterations: [
+    {
+      iteration_number: 1,
+      timestamp: '2025-11-26T12:00:00Z',
+      issues_addressed: ['consistency', 'completeness'],
+      corrections_applied: [
+        'Resolved JWT vs session auth contradiction',
+        'Added deployment section with Docker configuration',
+      ],
+      validation_result: { is_valid: false, remaining_issues: 1 },
+      llm_review_confidence: 0.72,
+      duration_ms: 1500,
+    },
+    {
+      iteration_number: 2,
+      timestamp: '2025-11-26T12:00:02Z',
+      issues_addressed: ['scope_alignment'],
+      corrections_applied: ['Aligned architecture complexity with MVP scope'],
+      validation_result: { is_valid: true, remaining_issues: 0 },
+      llm_review_confidence: 0.95,
+      duration_ms: 1200,
+    },
+  ],
+  started_at: '2025-11-26T12:00:00Z',
+  completed_at: '2025-11-26T12:00:03Z',
+};
+
+const maxIterationsHistory: CorrectionHistory = {
+  total_iterations: 3,
+  max_iterations: 3,
+  final_status: 'max_iterations_reached',
+  iterations: [
+    {
+      iteration_number: 1,
+      issues_addressed: ['consistency'],
+      corrections_applied: ['Attempt to resolve auth contradiction'],
+      validation_result: { is_valid: false, remaining_issues: 2 },
+      llm_review_confidence: 0.5,
+      duration_ms: 1000,
+    },
+    {
+      iteration_number: 2,
+      issues_addressed: ['consistency', 'completeness'],
+      corrections_applied: ['Further refinement of auth section', 'Added basic deployment notes'],
+      validation_result: { is_valid: false, remaining_issues: 1 },
+      llm_review_confidence: 0.6,
+      duration_ms: 1100,
+    },
+    {
+      iteration_number: 3,
+      issues_addressed: ['scope_alignment'],
+      corrections_applied: ['Attempted scope reduction'],
+      validation_result: { is_valid: false, remaining_issues: 1 },
+      llm_review_confidence: 0.68,
+      duration_ms: 950,
+    },
+  ],
+};
+
+const manualReviewHistory: CorrectionHistory = {
+  total_iterations: 1,
+  max_iterations: 3,
+  final_status: 'manual_review_required',
+  iterations: [
+    {
+      iteration_number: 1,
+      issues_addressed: [],
+      corrections_applied: [],
+      validation_result: { is_valid: false, remaining_issues: 4 },
+      llm_review_confidence: 0.25,
+      duration_ms: 800,
+    },
+  ],
+};
+
+const inProgressHistory: CorrectionHistory = {
+  total_iterations: 1,
+  max_iterations: 3,
+  final_status: 'in_progress',
+  iterations: [
+    {
+      iteration_number: 1,
+      issues_addressed: ['consistency'],
+      corrections_applied: ['Resolved auth contradiction'],
+      validation_result: { is_valid: false, remaining_issues: 2 },
+      llm_review_confidence: 0.65,
+      duration_ms: 1200,
+    },
+  ],
+};
+
+const emptyHistory: CorrectionHistory = {
+  total_iterations: 0,
+  max_iterations: 3,
+  final_status: 'success',
+  iterations: [],
+};
+
+export const Success: Story = {
+  args: {
+    history: successHistory,
+    showDetails: true,
+  },
+};
+
+export const MaxIterationsReached: Story = {
+  args: {
+    history: maxIterationsHistory,
+    showDetails: true,
+  },
+};
+
+export const ManualReviewRequired: Story = {
+  args: {
+    history: manualReviewHistory,
+    showDetails: true,
+  },
+};
+
+export const InProgress: Story = {
+  args: {
+    history: inProgressHistory,
+    isRunning: true,
+    currentIteration: 2,
+    showDetails: true,
+  },
+};
+
+export const NoCorrectionsNeeded: Story = {
+  args: {
+    history: emptyHistory,
+    showDetails: true,
+  },
+};
+
+export const WithoutDetails: Story = {
+  args: {
+    history: successHistory,
+    showDetails: false,
+  },
+};
+
+// Badge stories
+export const SuccessBadge: StoryObj<typeof CorrectionBadge> = {
+  render: () => <CorrectionBadge history={successHistory} />,
+};
+
+export const MaxIterationsBadge: StoryObj<typeof CorrectionBadge> = {
+  render: () => <CorrectionBadge history={maxIterationsHistory} />,
+};
+
+export const ManualReviewBadge: StoryObj<typeof CorrectionBadge> = {
+  render: () => <CorrectionBadge history={manualReviewHistory} />,
+};
+
+export const InProgressBadge: StoryObj<typeof CorrectionBadge> = {
+  render: () => <CorrectionBadge history={inProgressHistory} isRunning={true} />,
+};
diff --git a/devussy-web/src/components/pipeline/CorrectionTimeline.tsx b/devussy-web/src/components/pipeline/CorrectionTimeline.tsx
new file mode 100644
index 0000000..6536adb
--- /dev/null
+++ b/devussy-web/src/components/pipeline/CorrectionTimeline.tsx
@@ -0,0 +1,357 @@
+"use client";
+
+import React from 'react';
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+import { 
+    History, 
+    CheckCircle2, 
+    XCircle, 
+    AlertTriangle,
+    ArrowRight,
+    RefreshCw,
+    Clock,
+    Wrench,
+    Target,
+    Loader2
+} from "lucide-react";
+
+/**
+ * Single correction iteration data
+ */
+export interface CorrectionIteration {
+    iteration_number: number;
+    timestamp?: string;
+    issues_addressed: string[];
+    corrections_applied: string[];
+    validation_result: {
+        is_valid: boolean;
+        remaining_issues: number;
+    };
+    llm_review_confidence?: number;
+    duration_ms?: number;
+}
+
+/**
+ * Full correction history from backend
+ */
+export interface CorrectionHistory {
+    total_iterations: number;
+    max_iterations: number;
+    final_status: 'success' | 'max_iterations_reached' | 'manual_review_required' | 'in_progress';
+    iterations: CorrectionIteration[];
+    started_at?: string;
+    completed_at?: string;
+}
+
+interface CorrectionTimelineProps {
+    history: CorrectionHistory;
+    isRunning?: boolean;
+    currentIteration?: number;
+    showDetails?: boolean;
+}
+
+/**
+ * Get status configuration
+ */
+function getStatusConfig(status: CorrectionHistory['final_status']) {
+    switch (status) {
+        case 'success':
+            return {
+                icon: CheckCircle2,
+                color: 'text-green-500',
+                bgColor: 'bg-green-500/10',
+                borderColor: 'border-green-500/30',
+                label: 'Completed Successfully'
+            };
+        case 'max_iterations_reached':
+            return {
+                icon: AlertTriangle,
+                color: 'text-yellow-500',
+                bgColor: 'bg-yellow-500/10',
+                borderColor: 'border-yellow-500/30',
+                label: 'Max Iterations Reached'
+            };
+        case 'manual_review_required':
+            return {
+                icon: XCircle,
+                color: 'text-orange-500',
+                bgColor: 'bg-orange-500/10',
+                borderColor: 'border-orange-500/30',
+                label: 'Manual Review Required'
+            };
+        case 'in_progress':
+            return {
+                icon: RefreshCw,
+                color: 'text-blue-500',
+                bgColor: 'bg-blue-500/10',
+                borderColor: 'border-blue-500/30',
+                label: 'In Progress'
+            };
+    }
+}
+
+/**
+ * Timeline node for an iteration
+ */
+function IterationNode({ 
+    iteration, 
+    isLast, 
+    isCurrent,
+    showDetails 
+}: { 
+    iteration: CorrectionIteration; 
+    isLast: boolean;
+    isCurrent: boolean;
+    showDetails: boolean;
+}) {
+    const isSuccess = iteration.validation_result.is_valid;
+    
+    return (
+        <div className="relative">
+            {/* Connector line */}
+            {!isLast && (
+                <div className="absolute left-4 top-10 w-0.5 h-full bg-border/50" />
+            )}
+            
+            <div className="flex items-start gap-4">
+                {/* Node indicator */}
+                <div className={`relative z-10 flex items-center justify-center w-8 h-8 rounded-full border-2 ${
+                    isCurrent 
+                        ? 'border-blue-500 bg-blue-500/20'
+                        : isSuccess 
+                            ? 'border-green-500 bg-green-500/20'
+                            : 'border-yellow-500 bg-yellow-500/20'
+                }`}>
+                    {isCurrent ? (
+                        <Loader2 className="h-4 w-4 text-blue-500 animate-spin" />
+                    ) : isSuccess ? (
+                        <CheckCircle2 className="h-4 w-4 text-green-500" />
+                    ) : (
+                        <RefreshCw className="h-4 w-4 text-yellow-500" />
+                    )}
+                </div>
+
+                {/* Content */}
+                <div className="flex-1 pb-8">
+                    <div className="flex items-center gap-3 mb-2">
+                        <h4 className="font-medium">
+                            Iteration {iteration.iteration_number}
+                        </h4>
+                        {iteration.duration_ms && (
+                            <span className="text-xs text-muted-foreground flex items-center gap-1">
+                                <Clock className="h-3 w-3" />
+                                {(iteration.duration_ms / 1000).toFixed(1)}s
+                            </span>
+                        )}
+                        {iteration.llm_review_confidence !== undefined && (
+                            <span className="text-xs px-2 py-0.5 bg-primary/10 text-primary rounded-full">
+                                {Math.round(iteration.llm_review_confidence * 100)}% confidence
+                            </span>
+                        )}
+                    </div>
+
+                    {showDetails && (
+                        <div className="space-y-3">
+                            {/* Issues addressed */}
+                            {iteration.issues_addressed.length > 0 && (
+                                <div>
+                                    <p className="text-xs font-medium text-muted-foreground mb-1">
+                                        Issues Addressed:
+                                    </p>
+                                    <div className="flex flex-wrap gap-1">
+                                        {iteration.issues_addressed.map((issue, i) => (
+                                            <span 
+                                                key={i}
+                                                className="text-xs px-2 py-0.5 bg-muted rounded-full"
+                                            >
+                                                {issue}
+                                            </span>
+                                        ))}
+                                    </div>
+                                </div>
+                            )}
+
+                            {/* Corrections applied */}
+                            {iteration.corrections_applied.length > 0 && (
+                                <div>
+                                    <p className="text-xs font-medium text-muted-foreground mb-1">
+                                        Corrections Applied:
+                                    </p>
+                                    <ul className="text-sm space-y-1">
+                                        {iteration.corrections_applied.map((correction, i) => (
+                                            <li key={i} className="flex items-start gap-2">
+                                                <Wrench className="h-3 w-3 mt-1 text-primary" />
+                                                <span className="text-muted-foreground">{correction}</span>
+                                            </li>
+                                        ))}
+                                    </ul>
+                                </div>
+                            )}
+
+                            {/* Result */}
+                            <div className={`inline-flex items-center gap-2 px-2 py-1 rounded-md text-xs ${
+                                isSuccess 
+                                    ? 'bg-green-500/10 text-green-500'
+                                    : 'bg-yellow-500/10 text-yellow-500'
+                            }`}>
+                                {isSuccess ? (
+                                    <>
+                                        <CheckCircle2 className="h-3 w-3" />
+                                        All checks passed
+                                    </>
+                                ) : (
+                                    <>
+                                        <AlertTriangle className="h-3 w-3" />
+                                        {iteration.validation_result.remaining_issues} issue(s) remaining
+                                    </>
+                                )}
+                            </div>
+                        </div>
+                    )}
+                </div>
+            </div>
+        </div>
+    );
+}
+
+/**
+ * CorrectionTimeline Component
+ * 
+ * Displays the history of correction loop iterations with visual timeline.
+ */
+export function CorrectionTimeline({ 
+    history, 
+    isRunning = false,
+    currentIteration,
+    showDetails = true
+}: CorrectionTimelineProps) {
+    const statusConfig = getStatusConfig(isRunning ? 'in_progress' : history.final_status);
+    const StatusIcon = statusConfig.icon;
+
+    return (
+        <Card className="overflow-hidden">
+            <CardHeader className="border-b border-border/50">
+                <div className="flex items-center justify-between">
+                    <div>
+                        <CardTitle className="flex items-center gap-2">
+                            <History className="h-5 w-5 text-primary" />
+                            Correction Timeline
+                        </CardTitle>
+                        <CardDescription>
+                            {history.total_iterations} of {history.max_iterations} iterations
+                        </CardDescription>
+                    </div>
+                    
+                    <div className={`flex items-center gap-2 px-3 py-1.5 rounded-lg ${statusConfig.bgColor} border ${statusConfig.borderColor}`}>
+                        <StatusIcon className={`h-4 w-4 ${statusConfig.color} ${isRunning ? 'animate-spin' : ''}`} />
+                        <span className={`text-sm font-medium ${statusConfig.color}`}>
+                            {statusConfig.label}
+                        </span>
+                    </div>
+                </div>
+            </CardHeader>
+
+            <CardContent className="pt-6">
+                {/* Progress bar */}
+                <div className="mb-6">
+                    <div className="flex items-center justify-between text-xs text-muted-foreground mb-2">
+                        <span>Progress</span>
+                        <span>{history.total_iterations} / {history.max_iterations}</span>
+                    </div>
+                    <div className="h-2 bg-muted rounded-full overflow-hidden">
+                        <div 
+                            className={`h-full rounded-full transition-all duration-500 ${
+                                history.final_status === 'success' 
+                                    ? 'bg-green-500'
+                                    : isRunning 
+                                        ? 'bg-blue-500'
+                                        : 'bg-yellow-500'
+                            }`}
+                            style={{ width: `${(history.total_iterations / history.max_iterations) * 100}%` }}
+                        />
+                    </div>
+                </div>
+
+                {/* Timeline */}
+                {history.iterations.length > 0 ? (
+                    <div className="relative">
+                        {history.iterations.map((iteration, index) => (
+                            <IterationNode
+                                key={iteration.iteration_number}
+                                iteration={iteration}
+                                isLast={index === history.iterations.length - 1}
+                                isCurrent={isRunning && currentIteration === iteration.iteration_number}
+                                showDetails={showDetails}
+                            />
+                        ))}
+                    </div>
+                ) : (
+                    <div className="text-center py-8 text-muted-foreground">
+                        <Target className="h-8 w-8 mx-auto mb-2 opacity-50" />
+                        <p>No corrections needed</p>
+                        <p className="text-xs">Design passed all validation checks</p>
+                    </div>
+                )}
+
+                {/* Summary */}
+                {history.total_iterations > 0 && (
+                    <div className="mt-6 pt-4 border-t border-border/50">
+                        <div className="grid grid-cols-3 gap-4 text-center">
+                            <div>
+                                <p className="text-2xl font-bold text-primary">
+                                    {history.total_iterations}
+                                </p>
+                                <p className="text-xs text-muted-foreground">Iterations</p>
+                            </div>
+                            <div>
+                                <p className="text-2xl font-bold text-primary">
+                                    {history.iterations.reduce(
+                                        (sum, it) => sum + it.corrections_applied.length, 
+                                        0
+                                    )}
+                                </p>
+                                <p className="text-xs text-muted-foreground">Corrections</p>
+                            </div>
+                            <div>
+                                <p className="text-2xl font-bold text-primary">
+                                    {history.iterations.length > 0 
+                                        ? Math.round(
+                                            (history.iterations[history.iterations.length - 1]
+                                                .llm_review_confidence ?? 0) * 100
+                                        )
+                                        : 0
+                                    }%
+                                </p>
+                                <p className="text-xs text-muted-foreground">Final Confidence</p>
+                            </div>
+                        </div>
+                    </div>
+                )}
+            </CardContent>
+        </Card>
+    );
+}
+
+/**
+ * Compact correction status badge
+ */
+export function CorrectionBadge({ history, isRunning }: { history: CorrectionHistory; isRunning?: boolean }) {
+    const status = isRunning ? 'in_progress' : history.final_status;
+    const config = getStatusConfig(status);
+    const Icon = config.icon;
+
+    return (
+        <div className={`inline-flex items-center gap-2 px-3 py-1.5 rounded-full text-sm ${config.bgColor} border ${config.borderColor}`}>
+            <Icon className={`h-4 w-4 ${config.color} ${isRunning ? 'animate-spin' : ''}`} />
+            <span className={config.color}>
+                {history.total_iterations}/{history.max_iterations}
+            </span>
+            <span className="text-muted-foreground">|</span>
+            <span className={config.color}>
+                {config.label.split(' ')[0]}
+            </span>
+        </div>
+    );
+}
+
+export default CorrectionTimeline;
diff --git a/devussy-web/src/components/pipeline/DesignView.tsx b/devussy-web/src/components/pipeline/DesignView.tsx
index 13a17c4..104c0e4 100644
--- a/devussy-web/src/components/pipeline/DesignView.tsx
+++ b/devussy-web/src/components/pipeline/DesignView.tsx
@@ -3,9 +3,12 @@
 import React, { useState, useEffect } from 'react';
 import { Button } from "@/components/ui/button";
 import { ScrollArea } from "@/components/ui/scroll-area";
-import { Loader2, Check, ArrowRight, FileCode, LayoutGrid, Edit2 } from "lucide-react";
+import { Loader2, Check, ArrowRight, FileCode, LayoutGrid, Edit2, Gauge, AlertCircle, Shield, History } from "lucide-react";
 import { ModelConfig } from './ModelSettings';
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { ComplexityAssessment, ComplexityProfile, ComplexityBadge } from './ComplexityAssessment';
+import { ValidationReport, ValidationReportData, SanityReviewResult, ValidationBadge } from './ValidationReport';
+import { CorrectionTimeline, CorrectionHistory, CorrectionBadge } from './CorrectionTimeline';
 
 interface DesignViewProps {
     projectName: string;
@@ -14,6 +17,7 @@ interface DesignViewProps {
     modelConfig: ModelConfig;
     onDesignComplete: (design: any) => void;
     autoRun?: boolean;
+    enableAdaptive?: boolean;  // Enable adaptive complexity analysis
 }
 
 export const DesignView = ({
@@ -22,7 +26,8 @@ export const DesignView = ({
     languages,
     modelConfig,
     onDesignComplete,
-    autoRun = false
+    autoRun = false,
+    enableAdaptive = true
 }: DesignViewProps) => {
     const [designContent, setDesignContent] = useState("");
     const [designData, setDesignData] = useState<any>(null);
@@ -30,11 +35,285 @@ export const DesignView = ({
     const [viewMode, setViewMode] = useState<'preview' | 'raw'>('preview');
     const [isEditing, setIsEditing] = useState(false);
     const [error, setError] = useState<string | null>(null);
+    
+    // Adaptive complexity state
+    const [complexityProfile, setComplexityProfile] = useState<ComplexityProfile | null>(null);
+    const [isAnalyzingComplexity, setIsAnalyzingComplexity] = useState(false);
+    const [showComplexity, setShowComplexity] = useState(true);
+    
+    // Validation state
+    const [validationReport, setValidationReport] = useState<ValidationReportData | null>(null);
+    const [sanityReview, setSanityReview] = useState<SanityReviewResult | null>(null);
+    const [isValidating, setIsValidating] = useState(false);
+    const [showValidation, setShowValidation] = useState(true);
+    
+    // Correction loop state
+    const [correctionHistory, setCorrectionHistory] = useState<CorrectionHistory | null>(null);
+    const [isCorrecting, setIsCorrecting] = useState(false);
+    const [currentCorrectionIteration, setCurrentCorrectionIteration] = useState(0);
+    const [showCorrection, setShowCorrection] = useState(true);
 
     // Ref to track the current abort controller
     const abortControllerRef = React.useRef<AbortController | null>(null);
     const isGeneratingRef = React.useRef(false);
 
+    // Analyze complexity before design generation
+    const analyzeComplexity = async () => {
+        if (!enableAdaptive) return null;
+        
+        setIsAnalyzingComplexity(true);
+        try {
+            // Build interview data from form inputs
+            const interviewData = {
+                project_name: projectName,
+                project_type: inferProjectType(requirements),
+                requirements: requirements,
+                languages: languages.join(', '),
+                team_size: '1', // Default for now
+                integrations: inferIntegrations(requirements),
+            };
+
+            const response = await fetch('/api/adaptive/complexity', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ interview_data: interviewData }),
+            });
+
+            if (!response.ok) {
+                console.warn('Complexity analysis failed, proceeding without adaptive scaling');
+                return null;
+            }
+
+            // Parse SSE stream for complexity profile
+            const reader = response.body?.getReader();
+            if (!reader) return null;
+
+            const decoder = new TextDecoder();
+            let buffer = "";
+            let profile: ComplexityProfile | null = null;
+
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+
+                const chunk = decoder.decode(value, { stream: true });
+                buffer += chunk;
+
+                const parts = buffer.split('\n\n');
+                buffer = parts.pop() || "";
+
+                for (const part of parts) {
+                    const line = part.trim();
+                    if (line.startsWith('data: ')) {
+                        try {
+                            const data = JSON.parse(line.slice(6));
+                            if (data.profile) {
+                                profile = data.profile;
+                                setComplexityProfile(profile);
+                            }
+                            if (data.done && data.profile) {
+                                profile = data.profile;
+                                setComplexityProfile(profile);
+                            }
+                        } catch (e) {
+                            // Ignore parse errors
+                        }
+                    }
+                }
+            }
+
+            return profile;
+        } catch (err) {
+            console.warn('Complexity analysis error:', err);
+            return null;
+        } finally {
+            setIsAnalyzingComplexity(false);
+        }
+    };
+
+    // Helper to infer project type from requirements
+    const inferProjectType = (reqs: string): string => {
+        const lower = reqs.toLowerCase();
+        if (lower.includes('cli') || lower.includes('command line') || lower.includes('script')) return 'cli_tool';
+        if (lower.includes('library') || lower.includes('package') || lower.includes('sdk')) return 'library';
+        if (lower.includes('saas') || lower.includes('subscription') || lower.includes('multi-tenant')) return 'saas';
+        if (lower.includes('api') || lower.includes('rest') || lower.includes('graphql')) return 'api';
+        if (lower.includes('web') || lower.includes('website') || lower.includes('app')) return 'web_app';
+        return 'web_app'; // Default
+    };
+
+    // Helper to infer integrations from requirements
+    const inferIntegrations = (reqs: string): string => {
+        const lower = reqs.toLowerCase();
+        const integrations: string[] = [];
+        if (lower.includes('stripe') || lower.includes('payment')) integrations.push('stripe');
+        if (lower.includes('auth') || lower.includes('login') || lower.includes('oauth')) integrations.push('auth');
+        if (lower.includes('database') || lower.includes('sql') || lower.includes('postgres')) integrations.push('database');
+        if (lower.includes('email') || lower.includes('mail') || lower.includes('smtp')) integrations.push('email');
+        if (lower.includes('s3') || lower.includes('storage') || lower.includes('upload')) integrations.push('storage');
+        return integrations.join(', ') || 'none';
+    };
+
+    // Validate design after generation
+    const validateDesign = async (design: string) => {
+        if (!enableAdaptive || !design) return null;
+        
+        setIsValidating(true);
+        setValidationReport(null);
+        setSanityReview(null);
+        
+        try {
+            const response = await fetch('/api/adaptive/validate', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ 
+                    design_text: design,
+                    complexity_profile: complexityProfile 
+                }),
+            });
+
+            if (!response.ok) {
+                console.warn('Validation failed, proceeding without validation');
+                return null;
+            }
+
+            // Parse SSE stream for validation results
+            const reader = response.body?.getReader();
+            if (!reader) return null;
+
+            const decoder = new TextDecoder();
+            let buffer = "";
+            let report: ValidationReportData | null = null;
+            let review: SanityReviewResult | null = null;
+
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+
+                const chunk = decoder.decode(value, { stream: true });
+                buffer += chunk;
+
+                const parts = buffer.split('\n\n');
+                buffer = parts.pop() || "";
+
+                for (const part of parts) {
+                    const line = part.trim();
+                    if (line.startsWith('data: ')) {
+                        try {
+                            const data = JSON.parse(line.slice(6));
+                            if (data.validation_report) {
+                                report = data.validation_report;
+                                setValidationReport(report);
+                            }
+                            if (data.sanity_review) {
+                                review = data.sanity_review;
+                                setSanityReview(review);
+                            }
+                            if (data.done) {
+                                if (data.validation_report) setValidationReport(data.validation_report);
+                                if (data.sanity_review) setSanityReview(data.sanity_review);
+                            }
+                        } catch (e) {
+                            // Ignore parse errors
+                        }
+                    }
+                }
+            }
+
+            return { report, review };
+        } catch (err) {
+            console.warn('Validation error:', err);
+            return null;
+        } finally {
+            setIsValidating(false);
+        }
+    };
+
+    // Run correction loop to auto-fix issues
+    const runCorrectionLoop = async () => {
+        if (!designContent || isCorrecting) return;
+        
+        setIsCorrecting(true);
+        setCurrentCorrectionIteration(0);
+        setCorrectionHistory({
+            total_iterations: 0,
+            max_iterations: 3,
+            final_status: 'in_progress',
+            iterations: []
+        });
+        
+        try {
+            const response = await fetch('/api/adaptive/correct', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ 
+                    design_text: designContent,
+                    validation_report: validationReport,
+                    complexity_profile: complexityProfile 
+                }),
+            });
+
+            if (!response.ok) {
+                console.warn('Correction loop failed');
+                return;
+            }
+
+            // Parse SSE stream for correction updates
+            const reader = response.body?.getReader();
+            if (!reader) return;
+
+            const decoder = new TextDecoder();
+            let buffer = "";
+
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+
+                const chunk = decoder.decode(value, { stream: true });
+                buffer += chunk;
+
+                const parts = buffer.split('\n\n');
+                buffer = parts.pop() || "";
+
+                for (const part of parts) {
+                    const line = part.trim();
+                    if (line.startsWith('data: ')) {
+                        try {
+                            const data = JSON.parse(line.slice(6));
+                            
+                            if (data.iteration) {
+                                setCurrentCorrectionIteration(data.iteration.iteration_number);
+                                setCorrectionHistory(prev => prev ? {
+                                    ...prev,
+                                    total_iterations: data.iteration.iteration_number,
+                                    iterations: [...prev.iterations, data.iteration]
+                                } : prev);
+                            }
+                            
+                            if (data.corrected_design) {
+                                setDesignContent(data.corrected_design);
+                            }
+                            
+                            if (data.done && data.history) {
+                                setCorrectionHistory(data.history);
+                                // Re-validate after corrections
+                                if (data.corrected_design) {
+                                    await validateDesign(data.corrected_design);
+                                }
+                            }
+                        } catch (e) {
+                            // Ignore parse errors
+                        }
+                    }
+                }
+            }
+        } catch (err) {
+            console.warn('Correction loop error:', err);
+        } finally {
+            setIsCorrecting(false);
+        }
+    };
+
     const generateDesign = async () => {
         if (isGeneratingRef.current) return;
 
@@ -55,7 +334,8 @@ export const DesignView = ({
                     projectName,
                     requirements,
                     languages,
-                    modelConfig
+                    modelConfig,
+                    complexityProfile  // Pass complexity profile to design endpoint
                 }),
                 signal: controller.signal
             });
@@ -119,10 +399,34 @@ export const DesignView = ({
         }
     };
 
+    // Start pipeline: analyze complexity first (if adaptive), then generate design, then validate
+    const startPipeline = async () => {
+        // Reset validation/correction state
+        setValidationReport(null);
+        setSanityReview(null);
+        setCorrectionHistory(null);
+        
+        if (enableAdaptive) {
+            await analyzeComplexity();
+        }
+        await generateDesign();
+    };
+    
+    // Trigger validation when design generation completes
+    useEffect(() => {
+        if (enableAdaptive && designContent && !isGenerating && !isValidating && !validationReport) {
+            // Small delay to let the UI settle
+            const timer = setTimeout(() => {
+                validateDesign(designContent);
+            }, 500);
+            return () => clearTimeout(timer);
+        }
+    }, [designContent, isGenerating, enableAdaptive]);
+
     // Auto-generate on mount
     useEffect(() => {
         const timeoutId = setTimeout(() => {
-            generateDesign();
+            startPipeline();
         }, 50);
 
         return () => {
@@ -135,30 +439,112 @@ export const DesignView = ({
 
     const hasAutoAdvanced = React.useRef(false);
 
-    // Auto-advance when complete
+    // Auto-advance when complete - include complexity profile and validation in design data
+    // Only auto-advance if validation passed (or validation is disabled)
     useEffect(() => {
-        if (autoRun && !isGenerating && designContent && !hasAutoAdvanced.current) {
+        const canAutoAdvance = autoRun && 
+            !isGenerating && 
+            !isAnalyzingComplexity && 
+            !isValidating &&
+            !isCorrecting &&
+            designContent && 
+            !hasAutoAdvanced.current &&
+            // Only auto-advance if validation passed or not running adaptive
+            (!enableAdaptive || (validationReport?.is_valid));
+            
+        if (canAutoAdvance) {
             const timer = setTimeout(() => {
                 hasAutoAdvanced.current = true;
-                // Pass the design data or construct it from content if structured data is missing
-                onDesignComplete(designData || { raw_llm_response: designContent, project_name: projectName });
+                handleApprove();
             }, 1500);
             return () => clearTimeout(timer);
         }
-    }, [autoRun, isGenerating, designContent, designData, onDesignComplete, projectName]);
+    }, [autoRun, isGenerating, isAnalyzingComplexity, isValidating, isCorrecting, designContent, validationReport, enableAdaptive]);
 
     const handleApprove = () => {
-        onDesignComplete(designData || { raw_llm_response: designContent, project_name: projectName });
+        const designWithMetadata = {
+            ...(designData || { raw_llm_response: designContent, project_name: projectName }),
+            complexity_profile: complexityProfile,
+            validation_report: validationReport,
+            sanity_review: sanityReview,
+            correction_history: correctionHistory
+        };
+        onDesignComplete(designWithMetadata);
     };
+    
+    // Check if approval should be blocked
+    const isApprovalBlocked = isGenerating || isAnalyzingComplexity || isValidating || isCorrecting || !designContent;
+    const hasValidationIssues = validationReport && !validationReport.is_valid;
 
     return (
         <div className="flex flex-col h-full">
             <div className="flex items-center justify-between p-4 border-b border-border bg-muted/20">
-                <h2 className="text-lg font-semibold flex items-center gap-2">
-                    <LayoutGrid className="h-5 w-5" />
-                    System Design
-                </h2>
+                <div className="flex items-center gap-4">
+                    <h2 className="text-lg font-semibold flex items-center gap-2">
+                        <LayoutGrid className="h-5 w-5" />
+                        System Design
+                    </h2>
+                    {/* Show badges in header when panels collapsed */}
+                    <div className="flex items-center gap-2">
+                        {complexityProfile && !showComplexity && (
+                            <button 
+                                onClick={() => setShowComplexity(true)}
+                                className="hover:opacity-80 transition-opacity"
+                            >
+                                <ComplexityBadge profile={complexityProfile} />
+                            </button>
+                        )}
+                        {validationReport && !showValidation && (
+                            <button 
+                                onClick={() => setShowValidation(true)}
+                                className="hover:opacity-80 transition-opacity"
+                            >
+                                <ValidationBadge report={validationReport} />
+                            </button>
+                        )}
+                        {correctionHistory && correctionHistory.total_iterations > 0 && !showCorrection && (
+                            <button 
+                                onClick={() => setShowCorrection(true)}
+                                className="hover:opacity-80 transition-opacity"
+                            >
+                                <CorrectionBadge history={correctionHistory} isRunning={isCorrecting} />
+                            </button>
+                        )}
+                    </div>
+                </div>
                 <div className="flex gap-2">
+                    {/* Toggle buttons for panels */}
+                    {complexityProfile && showComplexity && (
+                        <Button
+                            variant="ghost"
+                            size="sm"
+                            onClick={() => setShowComplexity(false)}
+                        >
+                            <Gauge className="h-4 w-4 mr-2" />
+                            Hide Complexity
+                        </Button>
+                    )}
+                    {validationReport && showValidation && (
+                        <Button
+                            variant="ghost"
+                            size="sm"
+                            onClick={() => setShowValidation(false)}
+                        >
+                            <Shield className="h-4 w-4 mr-2" />
+                            Hide Validation
+                        </Button>
+                    )}
+                    {correctionHistory && correctionHistory.total_iterations > 0 && showCorrection && (
+                        <Button
+                            variant="ghost"
+                            size="sm"
+                            onClick={() => setShowCorrection(false)}
+                        >
+                            <History className="h-4 w-4 mr-2" />
+                            Hide Corrections
+                        </Button>
+                    )}
+                    
                     {designContent && !isGenerating && (
                         <>
                             <Button
@@ -189,8 +575,8 @@ export const DesignView = ({
                     <Button
                         variant="outline"
                         size="sm"
-                        onClick={generateDesign}
-                        disabled={isGenerating}
+                        onClick={() => startPipeline()}
+                        disabled={isGenerating || isAnalyzingComplexity || isValidating || isCorrecting}
                     >
                         Regenerate
                     </Button>
@@ -198,22 +584,89 @@ export const DesignView = ({
                     <Button
                         size="sm"
                         onClick={handleApprove}
-                        disabled={isGenerating || !designContent}
+                        disabled={isApprovalBlocked}
+                        variant={hasValidationIssues ? "outline" : "default"}
                     >
                         <Check className="h-4 w-4 mr-2" />
-                        Approve Design
+                        {hasValidationIssues ? "Approve Anyway" : "Approve Design"}
                     </Button>
                 </div>
             </div>
 
             <ScrollArea className="flex-1 p-6">
+                {/* Complexity Assessment Panel */}
+                {enableAdaptive && showComplexity && (isAnalyzingComplexity || complexityProfile) && (
+                    <div className="mb-6">
+                        {isAnalyzingComplexity ? (
+                            <Card className="animate-pulse">
+                                <CardHeader>
+                                    <CardTitle className="flex items-center gap-2 text-base">
+                                        <Gauge className="h-5 w-5 text-primary animate-spin" />
+                                        Analyzing Project Complexity...
+                                    </CardTitle>
+                                </CardHeader>
+                                <CardContent>
+                                    <div className="h-24 bg-muted rounded" />
+                                </CardContent>
+                            </Card>
+                        ) : complexityProfile ? (
+                            <ComplexityAssessment 
+                                profile={complexityProfile}
+                                showDetails={true}
+                                onRefresh={() => analyzeComplexity()}
+                            />
+                        ) : null}
+                    </div>
+                )}
+
+                {/* Validation Report Panel */}
+                {enableAdaptive && showValidation && (isValidating || validationReport) && (
+                    <div className="mb-6">
+                        {isValidating ? (
+                            <Card className="animate-pulse">
+                                <CardHeader>
+                                    <CardTitle className="flex items-center gap-2 text-base">
+                                        <Shield className="h-5 w-5 text-primary animate-spin" />
+                                        Validating Design...
+                                    </CardTitle>
+                                </CardHeader>
+                                <CardContent>
+                                    <div className="h-24 bg-muted rounded" />
+                                </CardContent>
+                            </Card>
+                        ) : validationReport ? (
+                            <ValidationReport 
+                                report={validationReport}
+                                sanityReview={sanityReview}
+                                onRequestCorrection={validationReport.auto_correctable_count > 0 ? runCorrectionLoop : undefined}
+                                showDetails={true}
+                            />
+                        ) : null}
+                    </div>
+                )}
+
+                {/* Correction Timeline Panel */}
+                {enableAdaptive && showCorrection && (isCorrecting || (correctionHistory && correctionHistory.total_iterations > 0)) && (
+                    <div className="mb-6">
+                        {correctionHistory && (
+                            <CorrectionTimeline 
+                                history={correctionHistory}
+                                isRunning={isCorrecting}
+                                currentIteration={currentCorrectionIteration}
+                                showDetails={true}
+                            />
+                        )}
+                    </div>
+                )}
+
                 {isGenerating && !designContent ? (
-                    <div className="flex flex-col items-center justify-center h-full space-y-4 text-muted-foreground">
+                    <div className="flex flex-col items-center justify-center h-64 space-y-4 text-muted-foreground">
                         <Loader2 className="h-8 w-8 animate-spin text-primary" />
-                        <p>Architecting system solution...</p>
+                        <p>Architecting system solution{complexityProfile ? ` (${complexityProfile.depth_level} mode)` : ''}...</p>
                     </div>
                 ) : error ? (
-                    <div className="text-destructive p-4 border border-destructive/20 rounded-lg bg-destructive/10">
+                    <div className="text-destructive p-4 border border-destructive/20 rounded-lg bg-destructive/10 flex items-center gap-2">
+                        <AlertCircle className="h-5 w-5" />
                         Error: {error}
                     </div>
                 ) : (
diff --git a/devussy-web/src/components/pipeline/ModelSettings.tsx b/devussy-web/src/components/pipeline/ModelSettings.tsx
index f44ef66..28e4085 100644
--- a/devussy-web/src/components/pipeline/ModelSettings.tsx
+++ b/devussy-web/src/components/pipeline/ModelSettings.tsx
@@ -1,5 +1,5 @@
-import React, { useState, useEffect } from 'react';
-import { Settings, ChevronDown, Check, Loader2, Globe, Layers, GitBranch, Code2, ArrowRight, MessageSquare } from 'lucide-react';
+import React, { useState, useEffect } from 'react';
+import { Settings, ChevronDown, Check, Loader2, Globe, Layers, GitBranch, Code2, ArrowRight, MessageSquare, User, Gauge, Shield, History } from 'lucide-react';
 import { cn } from '@/utils';
 import { motion, AnimatePresence } from 'framer-motion';
 
@@ -10,7 +10,8 @@ export interface ModelConfig {
     concurrency?: number; // Number of concurrent phase executions (1-10)
 }
 
-export type PipelineStage = 'global' | 'interview' | 'design' | 'plan' | 'execute' | 'handoff';
+// Extended to include adaptive pipeline stages
+export type PipelineStage = 'global' | 'interview' | 'complexity' | 'design' | 'validation' | 'correction' | 'plan' | 'execute' | 'handoff';
 
 export type ModelConfigs = Record<PipelineStage, ModelConfig | null> & { global: ModelConfig };
 
@@ -31,7 +32,10 @@ interface ModelSettingsProps {
 const STAGE_ICONS: Record<PipelineStage, React.ElementType> = {
     global: Globe,
     interview: MessageSquare,
+    complexity: Gauge,
     design: Layers,
+    validation: Shield,
+    correction: History,
     plan: GitBranch,
     execute: Code2,
     handoff: ArrowRight,
@@ -40,7 +44,10 @@ const STAGE_ICONS: Record<PipelineStage, React.ElementType> = {
 const STAGE_LABELS: Record<PipelineStage, string> = {
     global: 'Global Default',
     interview: 'Interview',
+    complexity: 'Complexity Analysis',
     design: 'Design',
+    validation: 'Validation',
+    correction: 'Correction',
     plan: 'Plan',
     execute: 'Execute',
     handoff: 'Handoff',
@@ -53,6 +60,7 @@ export const ModelSettings: React.FC<ModelSettingsProps> = ({ configs, onConfigs
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState<string | null>(null);
     const [search, setSearch] = useState('');
+    const [ircNick, setIrcNick] = useState('');
 
     // Sync selected tab with active stage if provided and open
     useEffect(() => {
@@ -61,6 +69,18 @@ export const ModelSettings: React.FC<ModelSettingsProps> = ({ configs, onConfigs
         }
     }, [isOpen, isWindowMode, activeStage]);
 
+    // Load IRC Nick from localStorage
+    useEffect(() => {
+        const stored = localStorage.getItem('devussy_irc_nick');
+        if (stored) setIrcNick(stored);
+    }, []);
+
+    const handleIrcNickChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+        const val = e.target.value;
+        setIrcNick(val);
+        localStorage.setItem('devussy_irc_nick', val);
+    };
+
     useEffect(() => {
         const fetchModels = async () => {
             setLoading(true);
@@ -111,13 +131,158 @@ export const ModelSettings: React.FC<ModelSettingsProps> = ({ configs, onConfigs
         }
     };
 
-    // Helper to get display string for the button
-    const getButtonLabel = () => {
-        const activeConfig = activeStage ? (configs[activeStage] || configs.global) : configs.global;
-        return activeConfig.model.split('/').pop();
-    };
+    const renderContent = () => (
+        <div className="space-y-4">
+             {/* Header */}
+             <div className="flex items-center justify-between pb-2 border-b border-gray-300">
+                <h2 className="text-base font-bold text-gray-800 flex items-center gap-2">
+                    {React.createElement(STAGE_ICONS[selectedTab], { className: "w-5 h-5 text-blue-600" })}
+                    {STAGE_LABELS[selectedTab]} Configuration
+                </h2>
+                {selectedTab !== 'global' && (
+                    isOverride ? (
+                        <button
+                            onClick={handleClearOverride}
+                            className="text-xs text-red-600 hover:text-red-800 underline font-semibold"
+                        >
+                            Reset to Global
+                        </button>
+                    ) : (
+                        <button
+                            onClick={handleCreateOverride}
+                            className="text-xs text-blue-600 hover:text-blue-800 underline font-semibold"
+                        >
+                            Customize
+                        </button>
+                    )
+                )}
+            </div>
+
+            {/* Global Settings: IRC Identity */}
+            {selectedTab === 'global' && (
+                <div className="space-y-2 pt-2 border-b border-gray-300 pb-4">
+                    <h3 className="text-sm font-bold text-gray-800 flex items-center gap-2">
+                        <User className="w-4 h-4" />
+                        IRC Identity
+                    </h3>
+                    <div className="bg-white border border-gray-400 rounded p-3 space-y-2">
+                        <label className="text-xs text-gray-600 block">Persistent Nickname</label>
+                        <input 
+                            type="text"
+                            value={ircNick}
+                            onChange={handleIrcNickChange}
+                            placeholder="Enter IRC Nickname"
+                            className="w-full border border-gray-400 rounded px-2 py-1 text-sm focus:outline-none focus:border-blue-500"
+                        />
+                        <p className="text-[10px] text-gray-500">This nickname will be used across sessions.</p>
+                    </div>
+                </div>
+            )}
 
-    // If in window mode, render XP Control Panel style
+            {(!isOverride && selectedTab !== 'global') ? (
+                <div className="p-6 rounded bg-blue-50 border border-blue-200 text-center space-y-3">
+                    <p className="text-sm text-gray-700 font-semibold">Using Global Configuration</p>
+                    <div className="text-xs font-mono text-gray-600 bg-white p-2 rounded border border-gray-300">
+                        {configs.global.model}  Temperature: {configs.global.temperature}
+                    </div>
+                    <button
+                        onClick={handleCreateOverride}
+                        className="mt-2 px-4 py-2 bg-blue-500 hover:bg-blue-600 text-white rounded text-xs font-bold"
+                    >
+                        Customize for {STAGE_LABELS[selectedTab]}
+                    </button>
+                </div>
+            ) : (
+                <>
+                    {/* Model Selection */}
+                    <div className="space-y-2">
+                        <h3 className="text-sm font-bold text-gray-800">AI Model</h3>
+                        <div className="bg-white border border-gray-400 rounded p-3 space-y-2">
+                            <input
+                                type="text"
+                                placeholder="Search models..."
+                                value={search}
+                                onChange={(e) => setSearch(e.target.value)}
+                                className="w-full border border-gray-400 rounded px-2 py-1 text-sm focus:outline-none focus:border-blue-500"
+                            />
+                            <div className="max-h-40 overflow-y-auto space-y-1">
+                                {loading ? (
+                                    <div className="flex items-center justify-center py-4 text-gray-500">
+                                        <Loader2 className="w-4 h-4 animate-spin" />
+                                    </div>
+                                ) : error ? (
+                                    <div className="text-red-600 text-xs py-2">{error}</div>
+                                ) : (
+                                    filteredModels.map(model => (
+                                        <button
+                                            key={model.id}
+                                            onClick={() => handleConfigUpdate({ ...currentConfig, model: model.id })}
+                                            className={cn(
+                                                "w-full text-left px-2 py-1.5 rounded text-xs flex items-center justify-between hover:bg-blue-100",
+                                                currentConfig.model === model.id ? "bg-blue-500 text-white font-bold" : "text-gray-800"
+                                            )}
+                                        >
+                                            <span className="truncate pr-2">{model.id}</span>
+                                            {currentConfig.model === model.id && <Check className="w-3 h-3 flex-shrink-0" />}
+                                        </button>
+                                    ))
+                                )}
+                            </div>
+                        </div>
+                    </div>
+
+                    {/* Temperature */}
+                    <div className="space-y-2">
+                        <h3 className="text-sm font-bold text-gray-800">Temperature</h3>
+                        <div className="bg-white border border-gray-400 rounded p-3 space-y-2">
+                            <div className="flex items-center justify-between">
+                                <span className="text-xs text-gray-600">Current Value:</span>
+                                <span className="text-sm font-bold text-blue-600">{currentConfig.temperature}</span>
+                            </div>
+                            <input
+                                type="range"
+                                min="0"
+                                max="2"
+                                step="0.1"
+                                value={currentConfig.temperature}
+                                onChange={(e) => handleConfigUpdate({ ...currentConfig, temperature: parseFloat(e.target.value) })}
+                                className="w-full"
+                            />
+                            <div className="flex justify-between text-xs text-gray-600">
+                                <span>Precise</span>
+                                <span>Creative</span>
+                            </div>
+                        </div>
+                    </div>
+
+                    {/* Reasoning Effort */}
+                    <div className="space-y-2">
+                        <h3 className="text-sm font-bold text-gray-800">Reasoning Effort</h3>
+                        <div className="bg-white border border-gray-400 rounded p-3">
+                            <div className="grid grid-cols-4 gap-2">
+                                {[null, 'low', 'medium', 'high'].map((effort) => (
+                                    <button
+                                        key={String(effort)}
+                                        onClick={() => handleConfigUpdate({ ...currentConfig, reasoning_effort: effort as any })}
+                                        className={cn(
+                                            "px-2 py-1.5 rounded text-xs font-bold border transition-colors uppercase",
+                                            currentConfig.reasoning_effort === effort
+                                                ? "bg-blue-500 border-blue-700 text-white"
+                                                : "bg-gray-100 border-gray-400 text-gray-700 hover:bg-gray-200"
+                                        )}
+                                    >
+                                        {effort || 'None'}
+                                    </button>
+                                ))}
+                            </div>
+                        </div>
+                    </div>
+                </>
+            )}
+        </div>
+    );
+
+    // Window Mode Render
     if (isWindowMode) {
         return (
             <div className="h-full flex flex-col bg-transparent">
@@ -147,386 +312,56 @@ export const ModelSettings: React.FC<ModelSettingsProps> = ({ configs, onConfigs
                         );
                     })}
                 </div>
-
                 {/* XP Content Area */}
-                <div className="flex-1 overflow-auto p-4 space-y-4">
-                    {/* Header */}
-                    <div className="flex items-center justify-between pb-2 border-b border-gray-300">
-                        <h2 className="text-base font-bold text-gray-800 flex items-center gap-2">
-                            {React.createElement(STAGE_ICONS[selectedTab], { className: "w-5 h-5 text-blue-600" })}
-                            {STAGE_LABELS[selectedTab]} Configuration
-                        </h2>
-                        {selectedTab !== 'global' && (
-                            isOverride ? (
-                                <button
-                                    onClick={handleClearOverride}
-                                    className="text-xs text-red-600 hover:text-red-800 underline font-semibold"
-                                >
-                                    Reset to Global
-                                </button>
-                            ) : (
-                                <button
-                                    onClick={handleCreateOverride}
-                                    className="text-xs text-blue-600 hover:text-blue-800 underline font-semibold"
-                                >
-                                    Customize
-                                </button>
-                            )
-                        )}
-                    </div>
-
-                    {(!isOverride && selectedTab !== 'global') ? (
-                        <div className="p-6 rounded bg-blue-50 border border-blue-200 text-center space-y-3">
-                            <p className="text-sm text-gray-700 font-semibold">Using Global Configuration</p>
-                            <div className="text-xs font-mono text-gray-600 bg-white p-2 rounded border border-gray-300">
-                                {configs.global.model} • Temperature: {configs.global.temperature}
-                            </div>
-                            <button
-                                onClick={handleCreateOverride}
-                                className="mt-2 px-4 py-2 bg-blue-500 hover:bg-blue-600 text-white rounded text-xs font-bold"
-                            >
-                                Customize for {STAGE_LABELS[selectedTab]}
-                            </button>
-                        </div>
-                    ) : (
-                        <>
-                            {/* Model Selection - Category Style */}
-                            <div className="space-y-2">
-                                <h3 className="text-sm font-bold text-gray-800">AI Model</h3>
-                                <div className="bg-white border border-gray-400 rounded p-3 space-y-2">
-                                    <input
-                                        type="text"
-                                        placeholder="Search models..."
-                                        value={search}
-                                        onChange={(e) => setSearch(e.target.value)}
-                                        className="w-full border border-gray-400 rounded px-2 py-1 text-sm focus:outline-none focus:border-blue-500"
-                                    />
-                                    <div className="max-h-40 overflow-y-auto space-y-1">
-                                        {loading ? (
-                                            <div className="flex items-center justify-center py-4 text-gray-500">
-                                                <Loader2 className="w-4 h-4 animate-spin" />
-                                            </div>
-                                        ) : error ? (
-                                            <div className="text-red-600 text-xs py-2">{error}</div>
-                                        ) : (
-                                            filteredModels.map(model => (
-                                                <button
-                                                    key={model.id}
-                                                    onClick={() => handleConfigUpdate({ ...currentConfig, model: model.id })}
-                                                    className={cn(
-                                                        "w-full text-left px-2 py-1.5 rounded text-xs flex items-center justify-between hover:bg-blue-100",
-                                                        currentConfig.model === model.id ? "bg-blue-500 text-white font-bold" : "text-gray-800"
-                                                    )}
-                                                >
-                                                    <span className="truncate pr-2">{model.id}</span>
-                                                    {currentConfig.model === model.id && <Check className="w-3 h-3 flex-shrink-0" />}
-                                                </button>
-                                            ))
-                                        )}
-                                    </div>
-                                </div>
-                            </div>
-
-                            {/* Temperature */}
-                            <div className="space-y-2">
-                                <h3 className="text-sm font-bold text-gray-800">Temperature</h3>
-                                <div className="bg-white border border-gray-400 rounded p-3 space-y-2">
-                                    <div className="flex items-center justify-between">
-                                        <span className="text-xs text-gray-600">Current Value:</span>
-                                        <span className="text-sm font-bold text-blue-600">{currentConfig.temperature}</span>
-                                    </div>
-                                    <input
-                                        type="range"
-                                        min="0"
-                                        max="2"
-                                        step="0.1"
-                                        value={currentConfig.temperature}
-                                        onChange={(e) => handleConfigUpdate({ ...currentConfig, temperature: parseFloat(e.target.value) })}
-                                        className="w-full"
-                                    />
-                                    <div className="flex justify-between text-xs text-gray-600">
-                                        <span>Precise</span>
-                                        <span>Creative</span>
-                                    </div>
-                                </div>
-                            </div>
-
-                            {/* Reasoning Effort */}
-                            <div className="space-y-2">
-                                <h3 className="text-sm font-bold text-gray-800">Reasoning Effort</h3>
-                                <div className="bg-white border border-gray-400 rounded p-3">
-                                    <div className="grid grid-cols-4 gap-2">
-                                        {[null, 'low', 'medium', 'high'].map((effort) => (
-                                            <button
-                                                key={String(effort)}
-                                                onClick={() => handleConfigUpdate({ ...currentConfig, reasoning_effort: effort as any })}
-                                                className={cn(
-                                                    "px-2 py-1.5 rounded text-xs font-bold border transition-colors uppercase",
-                                                    currentConfig.reasoning_effort === effort
-                                                        ? "bg-blue-500 border-blue-700 text-white"
-                                                        : "bg-gray-100 border-gray-400 text-gray-700 hover:bg-gray-200"
-                                                )}
-                                            >
-                                                {effort || 'Off'}
-                                            </button>
-                                        ))}
-                                    </div>
-                                    <p className="text-xs text-gray-600 mt-2">
-                                        Only supported on reasoning models (e.g. o1, gpt-5-preview).
-                                    </p>
-                                </div>
-                            </div>
-
-                            {/* Concurrency */}
-                            {(selectedTab === 'global' || selectedTab === 'execute') && (
-                                <div className="space-y-2">
-                                    <h3 className="text-sm font-bold text-gray-800">Concurrent Phases</h3>
-                                    <div className="bg-white border border-gray-400 rounded p-3 space-y-2">
-                                        <div className="flex items-center justify-between">
-                                            <span className="text-xs text-gray-600">Parallel Execution:</span>
-                                            <span className="text-sm font-bold text-blue-600">{currentConfig.concurrency || 3}</span>
-                                        </div>
-                                        <input
-                                            type="range"
-                                            min="1"
-                                            max="10"
-                                            step="1"
-                                            value={currentConfig.concurrency || 3}
-                                            onChange={(e) => handleConfigUpdate({ ...currentConfig, concurrency: parseInt(e.target.value) })}
-                                            className="w-full"
-                                        />
-                                        <div className="flex justify-between text-xs text-gray-600">
-                                            <span>Sequential</span>
-                                            <span>Max Parallel</span>
-                                        </div>
-                                        <p className="text-xs text-gray-600">
-                                            Number of phases to generate simultaneously during execution.
-                                        </p>
-                                    </div>
-                                </div>
-                            )}
-                        </>
-                    )}
+                <div className="flex-1 overflow-auto p-4">
+                    {renderContent()}
                 </div>
             </div>
         );
     }
 
-    // Default dropdown mode
     return (
-        <div className="relative z-50">
-            <button
+        <div className="relative">
+             <button
                 onClick={() => setIsOpen(!isOpen)}
-                className={cn(
-                    "flex items-center gap-2 px-3 py-1.5 rounded-md text-xs font-mono transition-colors border",
-                    isOpen
-                        ? "bg-green-500/20 border-green-500/50 text-green-400"
-                        : "bg-black/40 border-white/10 text-white/60 hover:text-white hover:border-white/30"
-                )}
+                className="flex items-center gap-2 px-3 py-1.5 bg-white border border-gray-300 rounded shadow-sm hover:bg-gray-50 transition-colors"
             >
-                <Settings className="w-3.5 h-3.5" />
-                <span>{getButtonLabel()}</span>
-                {activeStage && activeStage !== 'global' && configs[activeStage] && (
-                    <span className="flex h-1.5 w-1.5 rounded-full bg-green-500" />
-                )}
+                <Settings className="w-4 h-4 text-gray-600" />
+                <span className="text-sm font-medium text-gray-700">
+                    {configs.global.model.split('/').pop()}
+                </span>
+                <ChevronDown className={cn("w-3 h-3 text-gray-500 transition-transform", isOpen && "rotate-180")} />
             </button>
 
             <AnimatePresence>
                 {isOpen && (
                     <>
-                        <div
-                            className="fixed inset-0 z-40"
-                            onClick={() => setIsOpen(false)}
-                        />
+                        <div className="fixed inset-0 z-40" onClick={() => setIsOpen(false)} />
                         <motion.div
                             initial={{ opacity: 0, y: 10, scale: 0.95 }}
                             animate={{ opacity: 1, y: 0, scale: 1 }}
                             exit={{ opacity: 0, y: 10, scale: 0.95 }}
-                            transition={{ duration: 0.1 }}
-                            className="absolute right-0 top-full mt-2 w-[400px] bg-[#0a0a0a] border border-white/10 rounded-lg shadow-2xl z-50 overflow-hidden backdrop-blur-xl flex flex-col"
+                            className="absolute right-0 mt-2 w-[400px] bg-white border border-gray-300 rounded-lg shadow-xl z-50 overflow-hidden flex flex-col max-h-[80vh]"
                         >
-                            {/* Tabs */}
-                            <div className="flex border-b border-white/10 bg-white/5">
-                                {(Object.keys(STAGE_LABELS) as PipelineStage[]).map((stage) => {
-                                    const Icon = STAGE_ICONS[stage];
-                                    const hasOverride = stage !== 'global' && configs[stage] !== null;
-                                    return (
-                                        <button
-                                            key={stage}
-                                            onClick={() => setSelectedTab(stage)}
-                                            className={cn(
-                                                "flex-1 flex items-center justify-center py-2.5 text-[10px] uppercase tracking-wider font-medium transition-colors relative",
-                                                selectedTab === stage
-                                                    ? "text-white bg-white/5"
-                                                    : "text-white/40 hover:text-white/70 hover:bg-white/5"
-                                            )}
-                                            title={STAGE_LABELS[stage]}
-                                        >
-                                            <Icon className="w-3.5 h-3.5" />
-                                            {hasOverride && (
-                                                <span className="absolute top-1.5 right-1.5 w-1 h-1 rounded-full bg-green-500" />
-                                            )}
-                                            {selectedTab === stage && (
-                                                <motion.div
-                                                    layoutId="activeTab"
-                                                    className="absolute bottom-0 left-0 right-0 h-0.5 bg-green-500"
-                                                />
-                                            )}
-                                        </button>
-                                    );
-                                })}
-                            </div>
-
-                            <div className="p-4 space-y-4">
-                                <div className="flex items-center justify-between mb-2">
-                                    <h3 className="text-sm font-medium text-white flex items-center gap-2">
-                                        {React.createElement(STAGE_ICONS[selectedTab], { className: "w-4 h-4 text-green-500" })}
-                                        {STAGE_LABELS[selectedTab]} Settings
-                                    </h3>
-
-                                    {selectedTab !== 'global' && (
-                                        isOverride ? (
-                                            <button
-                                                onClick={handleClearOverride}
-                                                className="text-[10px] text-red-400 hover:text-red-300 underline"
-                                            >
-                                                Reset to Global
-                                            </button>
-                                        ) : (
-                                            <button
-                                                onClick={handleCreateOverride}
-                                                className="text-[10px] text-green-400 hover:text-green-300 underline"
-                                            >
-                                                Override Global
-                                            </button>
-                                        )
-                                    )}
-                                </div>
-
-                                {(!isOverride && selectedTab !== 'global') ? (
-                                    <div className="p-4 rounded-lg border border-white/10 bg-white/5 text-center space-y-2">
-                                        <p className="text-xs text-white/60">Using Global Configuration</p>
-                                        <div className="text-xs font-mono text-white/40">
-                                            {configs.global.model} • T={configs.global.temperature}
-                                        </div>
-                                        <button
-                                            onClick={handleCreateOverride}
-                                            className="mt-2 px-3 py-1.5 bg-white/10 hover:bg-white/20 rounded text-xs text-white transition-colors"
-                                        >
-                                            Customize for {STAGE_LABELS[selectedTab]}
-                                        </button>
-                                    </div>
-                                ) : (
-                                    <>
-                                        {/* Model Selection */}
-                                        <div className="space-y-2">
-                                            <label className="text-xs font-mono text-white/50 uppercase tracking-wider">Model</label>
-                                            <div className="relative">
-                                                <input
-                                                    type="text"
-                                                    placeholder="Search models..."
-                                                    value={search}
-                                                    onChange={(e) => setSearch(e.target.value)}
-                                                    className="w-full bg-black/50 border border-white/10 rounded px-3 py-2 text-xs text-white focus:outline-none focus:border-green-500/50 mb-2"
-                                                />
-                                                <div className="max-h-40 overflow-y-auto space-y-1 custom-scrollbar">
-                                                    {loading ? (
-                                                        <div className="flex items-center justify-center py-4 text-white/30">
-                                                            <Loader2 className="w-4 h-4 animate-spin" />
-                                                        </div>
-                                                    ) : error ? (
-                                                        <div className="text-red-400 text-xs py-2">{error}</div>
-                                                    ) : (
-                                                        filteredModels.map(model => (
-                                                            <button
-                                                                key={model.id}
-                                                                onClick={() => handleConfigUpdate({ ...currentConfig, model: model.id })}
-                                                                className={cn(
-                                                                    "w-full text-left px-2 py-1.5 rounded text-xs flex items-center justify-between group hover:bg-white/5",
-                                                                    currentConfig.model === model.id ? "text-green-400 bg-green-500/10" : "text-white/70"
-                                                                )}
-                                                            >
-                                                                <span className="truncate pr-2">{model.id}</span>
-                                                                {currentConfig.model === model.id && <Check className="w-3 h-3 flex-shrink-0" />}
-                                                            </button>
-                                                        ))
-                                                    )}
-                                                </div>
-                                            </div>
-                                        </div>
-
-                                        {/* Temperature */}
-                                        <div className="space-y-2">
-                                            <div className="flex items-center justify-between">
-                                                <label className="text-xs font-mono text-white/50 uppercase tracking-wider">Temperature</label>
-                                                <span className="text-xs font-mono text-green-400">{currentConfig.temperature}</span>
-                                            </div>
-                                            <input
-                                                type="range"
-                                                min="0"
-                                                max="2"
-                                                step="0.1"
-                                                value={currentConfig.temperature}
-                                                onChange={(e) => handleConfigUpdate({ ...currentConfig, temperature: parseFloat(e.target.value) })}
-                                                className="w-full h-1 bg-white/10 rounded-lg appearance-none cursor-pointer [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-3 [&::-webkit-slider-thumb]:h-3 [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-green-500"
-                                            />
-                                            <div className="flex justify-between text-[10px] text-white/30 font-mono">
-                                                <span>Precise</span>
-                                                <span>Creative</span>
-                                            </div>
-                                        </div>
-
-                                        {/* Reasoning Effort */}
-                                        <div className="space-y-2">
-                                            <label className="text-xs font-mono text-white/50 uppercase tracking-wider">Reasoning Effort (Thinking)</label>
-                                            <div className="grid grid-cols-4 gap-2">
-                                                {[null, 'low', 'medium', 'high'].map((effort) => (
-                                                    <button
-                                                        key={String(effort)}
-                                                        onClick={() => handleConfigUpdate({ ...currentConfig, reasoning_effort: effort as any })}
-                                                        className={cn(
-                                                            "px-2 py-1.5 rounded text-[10px] font-mono border transition-colors uppercase",
-                                                            currentConfig.reasoning_effort === effort
-                                                                ? "bg-green-500/20 border-green-500/50 text-green-400"
-                                                                : "bg-black/40 border-white/10 text-white/50 hover:border-white/30"
-                                                        )}
-                                                    >
-                                                        {effort || 'Off'}
-                                                    </button>
-                                                ))}
-                                            </div>
-                                            <p className="text-[10px] text-white/30">
-                                                Only supported on reasoning models (e.g. o1, gpt-5-preview).
-                                            </p>
-                                        </div>
-
-                                        {/* Concurrency (show for global and execute stage) */}
-                                        {(selectedTab === 'global' || selectedTab === 'execute') && (
-                                            <div className="space-y-2">
-                                                <div className="flex items-center justify-between">
-                                                    <label className="text-xs font-mono text-white/50 uppercase tracking-wider">Concurrent Phases</label>
-                                                    <span className="text-xs font-mono text-green-400">{currentConfig.concurrency || 3}</span>
-                                                </div>
-                                                <input
-                                                    type="range"
-                                                    min="1"
-                                                    max="10"
-                                                    step="1"
-                                                    value={currentConfig.concurrency || 3}
-                                                    onChange={(e) => handleConfigUpdate({ ...currentConfig, concurrency: parseInt(e.target.value) })}
-                                                    className="w-full h-1 bg-white/10 rounded-lg appearance-none cursor-pointer [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-3 [&::-webkit-slider-thumb]:h-3 [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-green-500"
-                                                />
-                                                <div className="flex justify-between text-[10px] text-white/30 font-mono">
-                                                    <span>Sequential</span>
-                                                    <span>Max Parallel</span>
-                                                </div>
-                                                <p className="text-[10px] text-white/30">
-                                                    Number of phases to generate simultaneously during execution.
-                                                </p>
-                                            </div>
+                             {/* Tabs */}
+                             <div className="flex border-b border-gray-200 bg-gray-50 overflow-x-auto">
+                                {(Object.keys(STAGE_LABELS) as PipelineStage[]).map((stage) => (
+                                    <button
+                                        key={stage}
+                                        onClick={() => setSelectedTab(stage)}
+                                        className={cn(
+                                            "px-3 py-2 text-xs font-medium whitespace-nowrap border-b-2 transition-colors",
+                                            selectedTab === stage
+                                                ? "border-blue-500 text-blue-600 bg-white"
+                                                : "border-transparent text-gray-600 hover:bg-gray-100"
                                         )}
-                                    </>
-                                )}
+                                    >
+                                        {STAGE_LABELS[stage]}
+                                    </button>
+                                ))}
+                            </div>
+                            <div className="p-4 overflow-y-auto">
+                                {renderContent()}
                             </div>
                         </motion.div>
                     </>
diff --git a/devussy-web/src/components/pipeline/ValidationReport.stories.tsx b/devussy-web/src/components/pipeline/ValidationReport.stories.tsx
new file mode 100644
index 0000000..1db08ff
--- /dev/null
+++ b/devussy-web/src/components/pipeline/ValidationReport.stories.tsx
@@ -0,0 +1,175 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ValidationReport, ValidationBadge, ValidationReportData, SanityReviewResult } from './ValidationReport';
+
+const meta: Meta<typeof ValidationReport> = {
+  title: 'Pipeline/ValidationReport',
+  component: ValidationReport,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof ValidationReport>;
+
+const validReport: ValidationReportData = {
+  is_valid: true,
+  issues: [],
+  checks_passed: ['consistency', 'completeness', 'scope_alignment', 'hallucination_detection', 'over_engineering_detection'],
+  checks_failed: [],
+  auto_correctable_count: 0,
+  manual_review_required: false,
+  timestamp: '2025-11-26T12:00:00Z',
+};
+
+const invalidReport: ValidationReportData = {
+  is_valid: false,
+  issues: [
+    {
+      check_name: 'consistency',
+      severity: 'error',
+      message: 'Contradictory requirements detected in authentication section',
+      location: 'section 2.1',
+      suggestion: 'Clarify whether JWT or session-based auth should be used',
+      auto_correctable: true,
+    },
+    {
+      check_name: 'completeness',
+      severity: 'warning',
+      message: 'Missing deployment section for production environment',
+      auto_correctable: true,
+    },
+    {
+      check_name: 'scope_alignment',
+      severity: 'info',
+      message: 'Consider adding monitoring for production readiness',
+      auto_correctable: false,
+    },
+  ],
+  checks_passed: ['hallucination_detection', 'over_engineering_detection'],
+  checks_failed: ['consistency', 'completeness', 'scope_alignment'],
+  auto_correctable_count: 2,
+  manual_review_required: false,
+};
+
+const severeReport: ValidationReportData = {
+  is_valid: false,
+  issues: [
+    {
+      check_name: 'hallucination_detection',
+      severity: 'error',
+      message: 'Referenced non-existent package "react-super-auth-v5"',
+      suggestion: 'Use well-known package like "next-auth" or "passport"',
+      auto_correctable: false,
+    },
+    {
+      check_name: 'over_engineering_detection',
+      severity: 'error',
+      message: 'Microservices architecture is overkill for MVP scope',
+      suggestion: 'Start with monolith, split later if needed',
+      auto_correctable: false,
+    },
+    {
+      check_name: 'consistency',
+      severity: 'error',
+      message: 'TypeScript mentioned but JavaScript files in structure',
+      auto_correctable: true,
+    },
+  ],
+  checks_passed: ['completeness'],
+  checks_failed: ['consistency', 'hallucination_detection', 'over_engineering_detection', 'scope_alignment'],
+  auto_correctable_count: 1,
+  manual_review_required: true,
+};
+
+const sanityReview: SanityReviewResult = {
+  is_sane: true,
+  confidence: 0.85,
+  issues_found: ['Minor terminology inconsistency between sections'],
+  suggestions: ['Consider standardizing API naming conventions', 'Add error handling patterns'],
+  overall_assessment: 'The design is well-structured and appropriate for the project scope. Minor improvements suggested for consistency.',
+};
+
+const failedSanityReview: SanityReviewResult = {
+  is_sane: false,
+  confidence: 0.42,
+  issues_found: [
+    'Design complexity exceeds stated requirements',
+    'Multiple contradictory decisions in architecture section',
+    'Missing critical security considerations',
+  ],
+  suggestions: [
+    'Simplify the architecture to match MVP scope',
+    'Resolve auth method contradiction',
+    'Add security section covering data protection',
+  ],
+  overall_assessment: 'The design requires significant revision before proceeding. Multiple fundamental issues need resolution.',
+};
+
+export const Valid: Story = {
+  args: {
+    report: validReport,
+    showDetails: true,
+  },
+};
+
+export const Invalid: Story = {
+  args: {
+    report: invalidReport,
+    showDetails: true,
+    onRequestCorrection: () => console.log('Correction requested'),
+  },
+};
+
+export const SevereIssues: Story = {
+  args: {
+    report: severeReport,
+    showDetails: true,
+    onRequestCorrection: () => console.log('Correction requested'),
+  },
+};
+
+export const WithSanityReview: Story = {
+  args: {
+    report: validReport,
+    sanityReview: sanityReview,
+    showDetails: true,
+  },
+};
+
+export const WithFailedSanityReview: Story = {
+  args: {
+    report: invalidReport,
+    sanityReview: failedSanityReview,
+    showDetails: true,
+    onRequestCorrection: () => console.log('Correction requested'),
+  },
+};
+
+export const WithoutDetails: Story = {
+  args: {
+    report: invalidReport,
+    showDetails: false,
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    report: validReport,
+    isLoading: true,
+  },
+};
+
+// Badge stories
+export const ValidBadge: StoryObj<typeof ValidationBadge> = {
+  render: () => <ValidationBadge report={validReport} />,
+};
+
+export const InvalidBadge: StoryObj<typeof ValidationBadge> = {
+  render: () => <ValidationBadge report={invalidReport} />,
+};
+
+export const SevereBadge: StoryObj<typeof ValidationBadge> = {
+  render: () => <ValidationBadge report={severeReport} />,
+};
diff --git a/devussy-web/src/components/pipeline/ValidationReport.tsx b/devussy-web/src/components/pipeline/ValidationReport.tsx
new file mode 100644
index 0000000..e4ff93c
--- /dev/null
+++ b/devussy-web/src/components/pipeline/ValidationReport.tsx
@@ -0,0 +1,433 @@
+"use client";
+
+import React from 'react';
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+import { 
+    Shield, 
+    CheckCircle2, 
+    XCircle, 
+    AlertTriangle,
+    FileCheck,
+    Scale,
+    Search,
+    Lightbulb,
+    Target,
+    Wrench
+} from "lucide-react";
+
+/**
+ * Validation issue structure matching backend ValidationReport
+ */
+export interface ValidationIssue {
+    check_name: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    location?: string;
+    suggestion?: string;
+    auto_correctable: boolean;
+}
+
+/**
+ * Full validation report from backend
+ */
+export interface ValidationReportData {
+    is_valid: boolean;
+    issues: ValidationIssue[];
+    checks_passed: string[];
+    checks_failed: string[];
+    auto_correctable_count: number;
+    manual_review_required: boolean;
+    timestamp?: string;
+}
+
+/**
+ * LLM sanity review result
+ */
+export interface SanityReviewResult {
+    is_sane: boolean;
+    confidence: number;
+    issues_found: string[];
+    suggestions: string[];
+    overall_assessment: string;
+}
+
+interface ValidationReportProps {
+    report: ValidationReportData;
+    sanityReview?: SanityReviewResult | null;
+    isLoading?: boolean;
+    onRequestCorrection?: () => void;
+    showDetails?: boolean;
+}
+
+/**
+ * Get icon for check type
+ */
+function getCheckIcon(checkName: string) {
+    switch (checkName.toLowerCase()) {
+        case 'consistency': return FileCheck;
+        case 'completeness': return Target;
+        case 'scope_alignment': return Scale;
+        case 'hallucination_detection': return Search;
+        case 'over_engineering_detection': return Lightbulb;
+        default: return Shield;
+    }
+}
+
+/**
+ * Get severity styling
+ */
+function getSeverityConfig(severity: 'error' | 'warning' | 'info') {
+    switch (severity) {
+        case 'error':
+            return {
+                icon: XCircle,
+                color: 'text-red-500',
+                bgColor: 'bg-red-500/10',
+                borderColor: 'border-red-500/30',
+                label: 'Error'
+            };
+        case 'warning':
+            return {
+                icon: AlertTriangle,
+                color: 'text-yellow-500',
+                bgColor: 'bg-yellow-500/10',
+                borderColor: 'border-yellow-500/30',
+                label: 'Warning'
+            };
+        case 'info':
+            return {
+                icon: Lightbulb,
+                color: 'text-blue-500',
+                bgColor: 'bg-blue-500/10',
+                borderColor: 'border-blue-500/30',
+                label: 'Info'
+            };
+    }
+}
+
+/**
+ * Format check name for display
+ */
+function formatCheckName(name: string): string {
+    return name
+        .replace(/_/g, ' ')
+        .replace(/\b\w/g, c => c.toUpperCase());
+}
+
+/**
+ * Individual issue card
+ */
+function IssueCard({ issue }: { issue: ValidationIssue }) {
+    const config = getSeverityConfig(issue.severity);
+    const SeverityIcon = config.icon;
+    const CheckIcon = getCheckIcon(issue.check_name);
+
+    return (
+        <div className={`p-4 rounded-lg border ${config.borderColor} ${config.bgColor}`}>
+            <div className="flex items-start gap-3">
+                <SeverityIcon className={`h-5 w-5 mt-0.5 ${config.color}`} />
+                <div className="flex-1 min-w-0">
+                    <div className="flex items-center gap-2 mb-1">
+                        <CheckIcon className="h-4 w-4 text-muted-foreground" />
+                        <span className="text-sm font-medium">
+                            {formatCheckName(issue.check_name)}
+                        </span>
+                        {issue.auto_correctable && (
+                            <span className="text-xs px-2 py-0.5 bg-green-500/20 text-green-400 rounded-full flex items-center gap-1">
+                                <Wrench className="h-3 w-3" />
+                                Auto-fix
+                            </span>
+                        )}
+                    </div>
+                    <p className="text-sm">{issue.message}</p>
+                    {issue.location && (
+                        <p className="text-xs text-muted-foreground mt-1">
+                            Location: {issue.location}
+                        </p>
+                    )}
+                    {issue.suggestion && (
+                        <p className="text-xs text-muted-foreground mt-2 italic">
+                            💡 {issue.suggestion}
+                        </p>
+                    )}
+                </div>
+            </div>
+        </div>
+    );
+}
+
+/**
+ * Check result badge
+ */
+function CheckBadge({ name, passed }: { name: string; passed: boolean }) {
+    return (
+        <div className={`flex items-center gap-1.5 px-2 py-1 rounded-md text-xs font-medium ${
+            passed 
+                ? 'bg-green-500/10 text-green-500 border border-green-500/30'
+                : 'bg-red-500/10 text-red-500 border border-red-500/30'
+        }`}>
+            {passed ? (
+                <CheckCircle2 className="h-3 w-3" />
+            ) : (
+                <XCircle className="h-3 w-3" />
+            )}
+            {formatCheckName(name)}
+        </div>
+    );
+}
+
+/**
+ * Sanity Review Section
+ */
+function SanityReviewSection({ review }: { review: SanityReviewResult }) {
+    const confidencePercent = Math.round(review.confidence * 100);
+    const confidenceColor = review.confidence >= 0.8 
+        ? 'text-green-500' 
+        : review.confidence >= 0.6 
+            ? 'text-yellow-500' 
+            : 'text-red-500';
+
+    return (
+        <div className="mt-4 pt-4 border-t border-border/50">
+            <h4 className="text-sm font-medium mb-3 flex items-center gap-2">
+                <Search className="h-4 w-4 text-primary" />
+                LLM Sanity Review
+            </h4>
+            
+            <div className="grid grid-cols-2 gap-4 mb-4">
+                <div className="p-3 rounded-lg bg-muted/30 border border-border/50">
+                    <p className="text-xs text-muted-foreground mb-1">Status</p>
+                    <div className="flex items-center gap-2">
+                        {review.is_sane ? (
+                            <>
+                                <CheckCircle2 className="h-4 w-4 text-green-500" />
+                                <span className="font-medium text-green-500">Sane</span>
+                            </>
+                        ) : (
+                            <>
+                                <AlertTriangle className="h-4 w-4 text-yellow-500" />
+                                <span className="font-medium text-yellow-500">Needs Review</span>
+                            </>
+                        )}
+                    </div>
+                </div>
+                
+                <div className="p-3 rounded-lg bg-muted/30 border border-border/50">
+                    <p className="text-xs text-muted-foreground mb-1">Confidence</p>
+                    <p className={`font-bold ${confidenceColor}`}>
+                        {confidencePercent}%
+                    </p>
+                </div>
+            </div>
+
+            {review.overall_assessment && (
+                <p className="text-sm text-muted-foreground mb-3">
+                    {review.overall_assessment}
+                </p>
+            )}
+
+            {review.issues_found.length > 0 && (
+                <div className="mb-3">
+                    <p className="text-xs font-medium text-muted-foreground mb-2">Issues Found:</p>
+                    <ul className="text-sm space-y-1">
+                        {review.issues_found.map((issue, i) => (
+                            <li key={i} className="flex items-start gap-2">
+                                <AlertTriangle className="h-3 w-3 mt-1 text-yellow-500" />
+                                <span>{issue}</span>
+                            </li>
+                        ))}
+                    </ul>
+                </div>
+            )}
+
+            {review.suggestions.length > 0 && (
+                <div>
+                    <p className="text-xs font-medium text-muted-foreground mb-2">Suggestions:</p>
+                    <ul className="text-sm space-y-1">
+                        {review.suggestions.map((suggestion, i) => (
+                            <li key={i} className="flex items-start gap-2">
+                                <Lightbulb className="h-3 w-3 mt-1 text-blue-500" />
+                                <span>{suggestion}</span>
+                            </li>
+                        ))}
+                    </ul>
+                </div>
+            )}
+        </div>
+    );
+}
+
+/**
+ * ValidationReport Component
+ * 
+ * Displays validation results including rule-based checks and LLM sanity review.
+ */
+export function ValidationReport({ 
+    report, 
+    sanityReview,
+    isLoading = false,
+    onRequestCorrection,
+    showDetails = true
+}: ValidationReportProps) {
+    if (isLoading) {
+        return (
+            <Card className="animate-pulse">
+                <CardHeader>
+                    <div className="h-6 bg-muted rounded w-48" />
+                    <div className="h-4 bg-muted rounded w-64 mt-2" />
+                </CardHeader>
+                <CardContent>
+                    <div className="h-32 bg-muted rounded" />
+                </CardContent>
+            </Card>
+        );
+    }
+
+    const errorCount = report.issues.filter(i => i.severity === 'error').length;
+    const warningCount = report.issues.filter(i => i.severity === 'warning').length;
+    const infoCount = report.issues.filter(i => i.severity === 'info').length;
+
+    return (
+        <Card className="overflow-hidden">
+            <CardHeader className="border-b border-border/50">
+                <div className="flex items-center justify-between">
+                    <div>
+                        <CardTitle className="flex items-center gap-2">
+                            <Shield className={`h-5 w-5 ${report.is_valid ? 'text-green-500' : 'text-yellow-500'}`} />
+                            Design Validation
+                        </CardTitle>
+                        <CardDescription>
+                            {report.is_valid 
+                                ? 'All validation checks passed'
+                                : `${report.checks_failed.length} check(s) need attention`
+                            }
+                        </CardDescription>
+                    </div>
+                    
+                    {!report.is_valid && report.auto_correctable_count > 0 && onRequestCorrection && (
+                        <button 
+                            onClick={onRequestCorrection}
+                            className="flex items-center gap-2 px-3 py-1.5 text-sm bg-primary/10 hover:bg-primary/20 text-primary rounded-lg transition-colors"
+                        >
+                            <Wrench className="h-4 w-4" />
+                            Auto-correct ({report.auto_correctable_count})
+                        </button>
+                    )}
+                </div>
+            </CardHeader>
+
+            <CardContent className="pt-6">
+                {/* Summary row */}
+                <div className="flex items-center gap-4 mb-6">
+                    <div className={`flex items-center gap-2 px-3 py-2 rounded-lg ${
+                        report.is_valid 
+                            ? 'bg-green-500/10 border border-green-500/30' 
+                            : 'bg-yellow-500/10 border border-yellow-500/30'
+                    }`}>
+                        {report.is_valid ? (
+                            <CheckCircle2 className="h-5 w-5 text-green-500" />
+                        ) : (
+                            <AlertTriangle className="h-5 w-5 text-yellow-500" />
+                        )}
+                        <span className={`font-medium ${report.is_valid ? 'text-green-500' : 'text-yellow-500'}`}>
+                            {report.is_valid ? 'Valid' : 'Needs Review'}
+                        </span>
+                    </div>
+
+                    <div className="flex items-center gap-3 text-sm">
+                        {errorCount > 0 && (
+                            <span className="flex items-center gap-1 text-red-500">
+                                <XCircle className="h-4 w-4" />
+                                {errorCount} error{errorCount !== 1 ? 's' : ''}
+                            </span>
+                        )}
+                        {warningCount > 0 && (
+                            <span className="flex items-center gap-1 text-yellow-500">
+                                <AlertTriangle className="h-4 w-4" />
+                                {warningCount} warning{warningCount !== 1 ? 's' : ''}
+                            </span>
+                        )}
+                        {infoCount > 0 && (
+                            <span className="flex items-center gap-1 text-blue-500">
+                                <Lightbulb className="h-4 w-4" />
+                                {infoCount} info
+                            </span>
+                        )}
+                    </div>
+
+                    {report.manual_review_required && (
+                        <span className="ml-auto text-xs px-2 py-1 bg-orange-500/20 text-orange-400 rounded-full">
+                            Manual review required
+                        </span>
+                    )}
+                </div>
+
+                {/* Checks overview */}
+                <div className="mb-6">
+                    <h4 className="text-sm font-medium mb-3 text-muted-foreground">
+                        Validation Checks
+                    </h4>
+                    <div className="flex flex-wrap gap-2">
+                        {report.checks_passed.map(check => (
+                            <CheckBadge key={check} name={check} passed={true} />
+                        ))}
+                        {report.checks_failed.map(check => (
+                            <CheckBadge key={check} name={check} passed={false} />
+                        ))}
+                    </div>
+                </div>
+
+                {/* Issues list */}
+                {showDetails && report.issues.length > 0 && (
+                    <div className="space-y-3">
+                        <h4 className="text-sm font-medium text-muted-foreground">
+                            Issues ({report.issues.length})
+                        </h4>
+                        {report.issues.map((issue, index) => (
+                            <IssueCard key={index} issue={issue} />
+                        ))}
+                    </div>
+                )}
+
+                {/* LLM Sanity Review */}
+                {sanityReview && (
+                    <SanityReviewSection review={sanityReview} />
+                )}
+            </CardContent>
+        </Card>
+    );
+}
+
+/**
+ * Compact validation status badge
+ */
+export function ValidationBadge({ report }: { report: ValidationReportData }) {
+    const errorCount = report.issues.filter(i => i.severity === 'error').length;
+    const warningCount = report.issues.filter(i => i.severity === 'warning').length;
+
+    return (
+        <div className={`inline-flex items-center gap-2 px-3 py-1.5 rounded-full text-sm ${
+            report.is_valid 
+                ? 'bg-green-500/10 border border-green-500/30'
+                : 'bg-yellow-500/10 border border-yellow-500/30'
+        }`}>
+            {report.is_valid ? (
+                <CheckCircle2 className="h-4 w-4 text-green-500" />
+            ) : (
+                <AlertTriangle className="h-4 w-4 text-yellow-500" />
+            )}
+            <span className={report.is_valid ? 'text-green-500' : 'text-yellow-500'}>
+                {report.is_valid ? 'Valid' : 'Issues'}
+            </span>
+            {!report.is_valid && (
+                <>
+                    <span className="text-muted-foreground">|</span>
+                    {errorCount > 0 && <span className="text-red-500">{errorCount}E</span>}
+                    {warningCount > 0 && <span className="text-yellow-500">{warningCount}W</span>}
+                </>
+            )}
+        </div>
+    );
+}
+
+export default ValidationReport;
diff --git a/devussy-web/src/components/pipeline/__tests__/ComplexityAssessment.test.tsx b/devussy-web/src/components/pipeline/__tests__/ComplexityAssessment.test.tsx
new file mode 100644
index 0000000..0de3055
--- /dev/null
+++ b/devussy-web/src/components/pipeline/__tests__/ComplexityAssessment.test.tsx
@@ -0,0 +1,231 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import '@testing-library/jest-dom';
+import { ComplexityAssessment, ComplexityBadge, ComplexityProfile } from '../ComplexityAssessment';
+
+// Mock lucide-react icons
+jest.mock('lucide-react', () => ({
+  Gauge: () => <span data-testid="gauge-icon">Gauge</span>,
+  Layers: () => <span data-testid="layers-icon">Layers</span>,
+  Microscope: () => <span data-testid="microscope-icon">Microscope</span>,
+  ShieldCheck: () => <span data-testid="shield-check-icon">ShieldCheck</span>,
+  AlertTriangle: () => <span data-testid="alert-triangle-icon">AlertTriangle</span>,
+  CheckCircle2: () => <span data-testid="check-circle-icon">CheckCircle2</span>,
+  Clock: () => <span data-testid="clock-icon">Clock</span>,
+  Users: () => <span data-testid="users-icon">Users</span>,
+  Boxes: () => <span data-testid="boxes-icon">Boxes</span>,
+}));
+
+describe('ComplexityAssessment', () => {
+  const minimalProfile: ComplexityProfile = {
+    project_type_bucket: 'cli_tool',
+    technical_complexity_bucket: 'simple_crud',
+    integration_bucket: 'standalone',
+    team_size_bucket: 'solo',
+    score: 1.5,
+    estimated_phase_count: 3,
+    depth_level: 'minimal',
+    confidence: 0.95,
+  };
+
+  const standardProfile: ComplexityProfile = {
+    project_type_bucket: 'web_app',
+    technical_complexity_bucket: 'auth_db',
+    integration_bucket: '3_5_services',
+    team_size_bucket: '2_3',
+    score: 7.5,
+    estimated_phase_count: 7,
+    depth_level: 'standard',
+    confidence: 0.75,
+  };
+
+  const detailedProfile: ComplexityProfile = {
+    project_type_bucket: 'saas',
+    technical_complexity_bucket: 'multi_region',
+    integration_bucket: '6_plus_services',
+    team_size_bucket: '7_plus',
+    score: 18.0,
+    estimated_phase_count: 13,
+    depth_level: 'detailed',
+    confidence: 0.55,
+  };
+
+  describe('rendering', () => {
+    it('renders complexity score correctly for minimal profile', () => {
+      render(<ComplexityAssessment profile={minimalProfile} />);
+      
+      expect(screen.getByText('1.5')).toBeInTheDocument();
+      expect(screen.getByText('/ 20')).toBeInTheDocument();
+      expect(screen.getByText('Complexity Assessment')).toBeInTheDocument();
+    });
+
+    it('renders depth level correctly for each tier', () => {
+      const { rerender } = render(<ComplexityAssessment profile={minimalProfile} />);
+      expect(screen.getByText('Minimal')).toBeInTheDocument();
+      
+      rerender(<ComplexityAssessment profile={standardProfile} />);
+      expect(screen.getByText('Standard')).toBeInTheDocument();
+      
+      rerender(<ComplexityAssessment profile={detailedProfile} />);
+      expect(screen.getByText('Detailed')).toBeInTheDocument();
+    });
+
+    it('renders estimated phase count', () => {
+      render(<ComplexityAssessment profile={standardProfile} />);
+      expect(screen.getByText('7')).toBeInTheDocument();
+      expect(screen.getByText('Estimated Phases')).toBeInTheDocument();
+    });
+
+    it('renders confidence percentage', () => {
+      render(<ComplexityAssessment profile={standardProfile} />);
+      expect(screen.getByText('75%')).toBeInTheDocument();
+      expect(screen.getByText('Confidence')).toBeInTheDocument();
+    });
+
+    it('renders project scale based on score', () => {
+      const { rerender } = render(<ComplexityAssessment profile={minimalProfile} />);
+      expect(screen.getByText('Simple')).toBeInTheDocument();
+      
+      // Score 7.5 is in Complex range (> 7)
+      rerender(<ComplexityAssessment profile={standardProfile} />);
+      expect(screen.getByText('Complex')).toBeInTheDocument();
+      
+      // Score 5 is in Moderate range (> 3 and <= 7)
+      const moderateProfile = { ...standardProfile, score: 5 };
+      rerender(<ComplexityAssessment profile={moderateProfile} />);
+      expect(screen.getByText('Moderate')).toBeInTheDocument();
+      
+      rerender(<ComplexityAssessment profile={detailedProfile} />);
+      expect(screen.getByText('Enterprise')).toBeInTheDocument();
+    });
+  });
+
+  describe('details section', () => {
+    it('shows complexity factors when showDetails is true', () => {
+      render(<ComplexityAssessment profile={minimalProfile} showDetails={true} />);
+      
+      expect(screen.getByText('Complexity Factors')).toBeInTheDocument();
+      expect(screen.getByText('Cli Tool')).toBeInTheDocument();
+      expect(screen.getByText('Simple Crud')).toBeInTheDocument();
+      expect(screen.getByText('Standalone')).toBeInTheDocument();
+      expect(screen.getByText('Solo')).toBeInTheDocument();
+    });
+
+    it('hides complexity factors when showDetails is false', () => {
+      render(<ComplexityAssessment profile={minimalProfile} showDetails={false} />);
+      
+      expect(screen.queryByText('Complexity Factors')).not.toBeInTheDocument();
+    });
+
+    it('formats bucket names correctly', () => {
+      render(<ComplexityAssessment profile={standardProfile} showDetails={true} />);
+      
+      expect(screen.getByText('Web App')).toBeInTheDocument();
+      expect(screen.getByText('Auth Db')).toBeInTheDocument();
+      expect(screen.getByText('3 5 Services')).toBeInTheDocument();
+    });
+  });
+
+  describe('loading state', () => {
+    it('shows loading skeleton when isLoading is true', () => {
+      render(<ComplexityAssessment profile={minimalProfile} isLoading={true} />);
+      
+      // Should not show actual content
+      expect(screen.queryByText('1.5')).not.toBeInTheDocument();
+      expect(screen.queryByText('Complexity Assessment')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('refresh callback', () => {
+    it('shows refresh button when onRefresh is provided', () => {
+      const onRefresh = jest.fn();
+      render(<ComplexityAssessment profile={minimalProfile} onRefresh={onRefresh} />);
+      
+      expect(screen.getByText('Refresh')).toBeInTheDocument();
+    });
+
+    it('calls onRefresh when refresh button is clicked', async () => {
+      const user = userEvent.setup();
+      const onRefresh = jest.fn();
+      render(<ComplexityAssessment profile={minimalProfile} onRefresh={onRefresh} />);
+      
+      await user.click(screen.getByText('Refresh'));
+      expect(onRefresh).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not show refresh button when onRefresh is not provided', () => {
+      render(<ComplexityAssessment profile={minimalProfile} />);
+      
+      expect(screen.queryByText('Refresh')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('confidence indicators', () => {
+    it('shows high confidence indicator for >= 0.8', () => {
+      const highConfidenceProfile = { ...minimalProfile, confidence: 0.9 };
+      render(<ComplexityAssessment profile={highConfidenceProfile} />);
+      
+      expect(screen.getByText('High confidence')).toBeInTheDocument();
+    });
+
+    it('shows medium confidence indicator for >= 0.6', () => {
+      const mediumConfidenceProfile = { ...minimalProfile, confidence: 0.7 };
+      render(<ComplexityAssessment profile={mediumConfidenceProfile} />);
+      
+      expect(screen.getByText('Medium confidence')).toBeInTheDocument();
+    });
+
+    it('shows low confidence indicator for < 0.6', () => {
+      const lowConfidenceProfile = { ...minimalProfile, confidence: 0.4 };
+      render(<ComplexityAssessment profile={lowConfidenceProfile} />);
+      
+      expect(screen.getByText('Low confidence')).toBeInTheDocument();
+    });
+  });
+});
+
+describe('ComplexityBadge', () => {
+  const profile: ComplexityProfile = {
+    project_type_bucket: 'web_app',
+    technical_complexity_bucket: 'auth_db',
+    integration_bucket: '3_5_services',
+    team_size_bucket: '2_3',
+    score: 7.5,
+    estimated_phase_count: 7,
+    depth_level: 'standard',
+    confidence: 0.75,
+  };
+
+  it('renders score correctly', () => {
+    render(<ComplexityBadge profile={profile} />);
+    expect(screen.getByText('7.5')).toBeInTheDocument();
+  });
+
+  it('renders phase count', () => {
+    render(<ComplexityBadge profile={profile} />);
+    expect(screen.getByText('7 phases')).toBeInTheDocument();
+  });
+
+  it('renders depth level label', () => {
+    render(<ComplexityBadge profile={profile} />);
+    expect(screen.getByText('Standard')).toBeInTheDocument();
+  });
+
+  it('renders different styles for each depth level', () => {
+    const { rerender, container } = render(<ComplexityBadge profile={profile} />);
+    
+    // Standard should have blue styling
+    expect(container.firstChild).toHaveClass('bg-blue-500/10');
+    
+    // Minimal should have green styling
+    const minimalProfile = { ...profile, depth_level: 'minimal' as const };
+    rerender(<ComplexityBadge profile={minimalProfile} />);
+    expect(container.firstChild).toHaveClass('bg-green-500/10');
+    
+    // Detailed should have purple styling
+    const detailedProfile = { ...profile, depth_level: 'detailed' as const };
+    rerender(<ComplexityBadge profile={detailedProfile} />);
+    expect(container.firstChild).toHaveClass('bg-purple-500/10');
+  });
+});
diff --git a/devussy-web/src/components/pipeline/__tests__/CorrectionTimeline.test.tsx b/devussy-web/src/components/pipeline/__tests__/CorrectionTimeline.test.tsx
new file mode 100644
index 0000000..2e98243
--- /dev/null
+++ b/devussy-web/src/components/pipeline/__tests__/CorrectionTimeline.test.tsx
@@ -0,0 +1,291 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { 
+  CorrectionTimeline, 
+  CorrectionBadge, 
+  CorrectionHistory,
+  CorrectionIteration 
+} from '../CorrectionTimeline';
+
+// Mock lucide-react icons
+jest.mock('lucide-react', () => ({
+  History: () => <span data-testid="history-icon">History</span>,
+  CheckCircle2: () => <span data-testid="check-circle-icon">CheckCircle2</span>,
+  XCircle: () => <span data-testid="x-circle-icon">XCircle</span>,
+  AlertTriangle: () => <span data-testid="alert-triangle-icon">AlertTriangle</span>,
+  ArrowRight: () => <span data-testid="arrow-right-icon">ArrowRight</span>,
+  RefreshCw: () => <span data-testid="refresh-icon">RefreshCw</span>,
+  Clock: () => <span data-testid="clock-icon">Clock</span>,
+  Wrench: () => <span data-testid="wrench-icon">Wrench</span>,
+  Target: () => <span data-testid="target-icon">Target</span>,
+  Loader2: () => <span data-testid="loader-icon">Loader2</span>,
+}));
+
+describe('CorrectionTimeline', () => {
+  const successHistory: CorrectionHistory = {
+    total_iterations: 2,
+    max_iterations: 3,
+    final_status: 'success',
+    iterations: [
+      {
+        iteration_number: 1,
+        timestamp: '2025-11-26T12:00:00Z',
+        issues_addressed: ['consistency', 'completeness'],
+        corrections_applied: ['Fixed contradictory requirements', 'Added deployment section'],
+        validation_result: { is_valid: false, remaining_issues: 1 },
+        llm_review_confidence: 0.7,
+        duration_ms: 1500,
+      },
+      {
+        iteration_number: 2,
+        timestamp: '2025-11-26T12:00:02Z',
+        issues_addressed: ['scope_alignment'],
+        corrections_applied: ['Aligned scope with requirements'],
+        validation_result: { is_valid: true, remaining_issues: 0 },
+        llm_review_confidence: 0.95,
+        duration_ms: 1200,
+      },
+    ],
+    started_at: '2025-11-26T12:00:00Z',
+    completed_at: '2025-11-26T12:00:03Z',
+  };
+
+  const maxIterationsHistory: CorrectionHistory = {
+    total_iterations: 3,
+    max_iterations: 3,
+    final_status: 'max_iterations_reached',
+    iterations: [
+      {
+        iteration_number: 1,
+        issues_addressed: ['consistency'],
+        corrections_applied: ['Attempt 1'],
+        validation_result: { is_valid: false, remaining_issues: 2 },
+        llm_review_confidence: 0.5,
+        duration_ms: 1000,
+      },
+      {
+        iteration_number: 2,
+        issues_addressed: ['consistency'],
+        corrections_applied: ['Attempt 2'],
+        validation_result: { is_valid: false, remaining_issues: 1 },
+        llm_review_confidence: 0.6,
+        duration_ms: 1000,
+      },
+      {
+        iteration_number: 3,
+        issues_addressed: ['consistency'],
+        corrections_applied: ['Attempt 3'],
+        validation_result: { is_valid: false, remaining_issues: 1 },
+        llm_review_confidence: 0.65,
+        duration_ms: 1000,
+      },
+    ],
+  };
+
+  const manualReviewHistory: CorrectionHistory = {
+    total_iterations: 1,
+    max_iterations: 3,
+    final_status: 'manual_review_required',
+    iterations: [
+      {
+        iteration_number: 1,
+        issues_addressed: [],
+        corrections_applied: [],
+        validation_result: { is_valid: false, remaining_issues: 3 },
+        llm_review_confidence: 0.3,
+        duration_ms: 500,
+      },
+    ],
+  };
+
+  const emptyHistory: CorrectionHistory = {
+    total_iterations: 0,
+    max_iterations: 3,
+    final_status: 'success',
+    iterations: [],
+  };
+
+  describe('header rendering', () => {
+    it('renders correction timeline title', () => {
+      render(<CorrectionTimeline history={successHistory} />);
+      expect(screen.getByText('Correction Timeline')).toBeInTheDocument();
+    });
+
+    it('shows iteration count', () => {
+      render(<CorrectionTimeline history={successHistory} />);
+      expect(screen.getByText('2 of 3 iterations')).toBeInTheDocument();
+    });
+
+    it('shows success status', () => {
+      render(<CorrectionTimeline history={successHistory} />);
+      expect(screen.getByText('Completed Successfully')).toBeInTheDocument();
+    });
+
+    it('shows max iterations reached status', () => {
+      render(<CorrectionTimeline history={maxIterationsHistory} />);
+      expect(screen.getByText('Max Iterations Reached')).toBeInTheDocument();
+    });
+
+    it('shows manual review required status', () => {
+      render(<CorrectionTimeline history={manualReviewHistory} />);
+      expect(screen.getByText('Manual Review Required')).toBeInTheDocument();
+    });
+
+    it('shows in progress status when running', () => {
+      render(<CorrectionTimeline history={successHistory} isRunning={true} />);
+      expect(screen.getByText('In Progress')).toBeInTheDocument();
+    });
+  });
+
+  describe('progress bar', () => {
+    it('shows progress label', () => {
+      render(<CorrectionTimeline history={successHistory} />);
+      expect(screen.getByText('Progress')).toBeInTheDocument();
+    });
+
+    it('shows iteration count in progress', () => {
+      render(<CorrectionTimeline history={successHistory} />);
+      expect(screen.getByText('2 / 3')).toBeInTheDocument();
+    });
+  });
+
+  describe('iteration nodes', () => {
+    it('renders all iterations', () => {
+      render(<CorrectionTimeline history={successHistory} />);
+      expect(screen.getByText('Iteration 1')).toBeInTheDocument();
+      expect(screen.getByText('Iteration 2')).toBeInTheDocument();
+    });
+
+    it('shows duration for each iteration', () => {
+      render(<CorrectionTimeline history={successHistory} />);
+      expect(screen.getByText('1.5s')).toBeInTheDocument();
+      expect(screen.getByText('1.2s')).toBeInTheDocument();
+    });
+
+    it('shows confidence for each iteration', () => {
+      render(<CorrectionTimeline history={successHistory} />);
+      expect(screen.getByText('70% confidence')).toBeInTheDocument();
+      expect(screen.getByText('95% confidence')).toBeInTheDocument();
+    });
+
+    it('shows issues addressed when showDetails is true', () => {
+      render(<CorrectionTimeline history={successHistory} showDetails={true} />);
+      // Multiple "Issues Addressed:" labels exist (one per iteration)
+      expect(screen.getAllByText('Issues Addressed:').length).toBeGreaterThanOrEqual(1);
+      expect(screen.getByText('consistency')).toBeInTheDocument();
+      expect(screen.getByText('completeness')).toBeInTheDocument();
+    });
+
+    it('shows corrections applied when showDetails is true', () => {
+      render(<CorrectionTimeline history={successHistory} showDetails={true} />);
+      // Multiple "Corrections Applied:" labels exist (one per iteration)
+      expect(screen.getAllByText('Corrections Applied:').length).toBeGreaterThanOrEqual(1);
+      expect(screen.getByText('Fixed contradictory requirements')).toBeInTheDocument();
+      expect(screen.getByText('Added deployment section')).toBeInTheDocument();
+    });
+
+    it('shows validation result for each iteration', () => {
+      render(<CorrectionTimeline history={successHistory} showDetails={true} />);
+      expect(screen.getByText('1 issue(s) remaining')).toBeInTheDocument();
+      expect(screen.getByText('All checks passed')).toBeInTheDocument();
+    });
+  });
+
+  describe('empty state', () => {
+    it('shows no corrections needed message', () => {
+      render(<CorrectionTimeline history={emptyHistory} />);
+      expect(screen.getByText('No corrections needed')).toBeInTheDocument();
+      expect(screen.getByText('Design passed all validation checks')).toBeInTheDocument();
+    });
+  });
+
+  describe('summary section', () => {
+    it('shows total iterations', () => {
+      render(<CorrectionTimeline history={successHistory} />);
+      expect(screen.getByText('Iterations')).toBeInTheDocument();
+    });
+
+    it('shows total corrections count', () => {
+      render(<CorrectionTimeline history={successHistory} />);
+      expect(screen.getByText('Corrections')).toBeInTheDocument();
+    });
+
+    it('shows final confidence', () => {
+      render(<CorrectionTimeline history={successHistory} />);
+      expect(screen.getByText('Final Confidence')).toBeInTheDocument();
+    });
+  });
+
+  describe('running state', () => {
+    it('highlights current iteration when running', () => {
+      render(
+        <CorrectionTimeline 
+          history={successHistory} 
+          isRunning={true} 
+          currentIteration={1} 
+        />
+      );
+      // Should show loader for current iteration (tested via icon mock)
+      expect(screen.getByTestId('loader-icon')).toBeInTheDocument();
+    });
+  });
+});
+
+describe('CorrectionBadge', () => {
+  const successHistory: CorrectionHistory = {
+    total_iterations: 2,
+    max_iterations: 3,
+    final_status: 'success',
+    iterations: [],
+  };
+
+  const inProgressHistory: CorrectionHistory = {
+    total_iterations: 1,
+    max_iterations: 3,
+    final_status: 'in_progress',
+    iterations: [],
+  };
+
+  const maxIterationsHistory: CorrectionHistory = {
+    total_iterations: 3,
+    max_iterations: 3,
+    final_status: 'max_iterations_reached',
+    iterations: [],
+  };
+
+  it('shows iteration count', () => {
+    render(<CorrectionBadge history={successHistory} />);
+    expect(screen.getByText('2/3')).toBeInTheDocument();
+  });
+
+  it('shows completed status for success', () => {
+    render(<CorrectionBadge history={successHistory} />);
+    expect(screen.getByText('Completed')).toBeInTheDocument();
+  });
+
+  it('shows in progress status when running', () => {
+    render(<CorrectionBadge history={inProgressHistory} isRunning={true} />);
+    expect(screen.getByText('In')).toBeInTheDocument();
+  });
+
+  it('shows max status when max iterations reached', () => {
+    render(<CorrectionBadge history={maxIterationsHistory} />);
+    expect(screen.getByText('Max')).toBeInTheDocument();
+  });
+
+  it('applies success styling', () => {
+    const { container } = render(<CorrectionBadge history={successHistory} />);
+    expect(container.firstChild).toHaveClass('bg-green-500/10');
+  });
+
+  it('applies in progress styling when running', () => {
+    const { container } = render(<CorrectionBadge history={inProgressHistory} isRunning={true} />);
+    expect(container.firstChild).toHaveClass('bg-blue-500/10');
+  });
+
+  it('applies warning styling for max iterations', () => {
+    const { container } = render(<CorrectionBadge history={maxIterationsHistory} />);
+    expect(container.firstChild).toHaveClass('bg-yellow-500/10');
+  });
+});
diff --git a/devussy-web/src/components/pipeline/__tests__/ValidationReport.test.tsx b/devussy-web/src/components/pipeline/__tests__/ValidationReport.test.tsx
new file mode 100644
index 0000000..77a168b
--- /dev/null
+++ b/devussy-web/src/components/pipeline/__tests__/ValidationReport.test.tsx
@@ -0,0 +1,294 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import '@testing-library/jest-dom';
+import { 
+  ValidationReport, 
+  ValidationBadge, 
+  ValidationReportData, 
+  ValidationIssue,
+  SanityReviewResult 
+} from '../ValidationReport';
+
+// Mock lucide-react icons
+jest.mock('lucide-react', () => ({
+  Shield: () => <span data-testid="shield-icon">Shield</span>,
+  CheckCircle2: () => <span data-testid="check-circle-icon">CheckCircle2</span>,
+  XCircle: () => <span data-testid="x-circle-icon">XCircle</span>,
+  AlertTriangle: () => <span data-testid="alert-triangle-icon">AlertTriangle</span>,
+  FileCheck: () => <span data-testid="file-check-icon">FileCheck</span>,
+  Scale: () => <span data-testid="scale-icon">Scale</span>,
+  Search: () => <span data-testid="search-icon">Search</span>,
+  Lightbulb: () => <span data-testid="lightbulb-icon">Lightbulb</span>,
+  Target: () => <span data-testid="target-icon">Target</span>,
+  Wrench: () => <span data-testid="wrench-icon">Wrench</span>,
+}));
+
+describe('ValidationReport', () => {
+  const validReport: ValidationReportData = {
+    is_valid: true,
+    issues: [],
+    checks_passed: ['consistency', 'completeness', 'scope_alignment', 'hallucination_detection', 'over_engineering_detection'],
+    checks_failed: [],
+    auto_correctable_count: 0,
+    manual_review_required: false,
+    timestamp: '2025-11-26T12:00:00Z',
+  };
+
+  const invalidReport: ValidationReportData = {
+    is_valid: false,
+    issues: [
+      {
+        check_name: 'consistency',
+        severity: 'error',
+        message: 'Contradictory requirements detected',
+        location: 'section 2.1',
+        suggestion: 'Clarify the authentication requirements',
+        auto_correctable: true,
+      },
+      {
+        check_name: 'completeness',
+        severity: 'warning',
+        message: 'Missing deployment section',
+        auto_correctable: true,
+      },
+      {
+        check_name: 'scope_alignment',
+        severity: 'info',
+        message: 'Consider adding monitoring for production',
+        auto_correctable: false,
+      },
+    ],
+    checks_passed: ['hallucination_detection', 'over_engineering_detection'],
+    checks_failed: ['consistency', 'completeness', 'scope_alignment'],
+    auto_correctable_count: 2,
+    manual_review_required: false,
+  };
+
+  const sanityReview: SanityReviewResult = {
+    is_sane: true,
+    confidence: 0.85,
+    issues_found: ['Minor terminology inconsistency'],
+    suggestions: ['Consider standardizing API naming conventions'],
+    overall_assessment: 'The design is well-structured and appropriate for the project scope.',
+  };
+
+  describe('rendering valid report', () => {
+    it('shows valid status when report is valid', () => {
+      render(<ValidationReport report={validReport} />);
+      
+      expect(screen.getByText('Valid')).toBeInTheDocument();
+      expect(screen.getByText('All validation checks passed')).toBeInTheDocument();
+    });
+
+    it('shows all passed checks', () => {
+      render(<ValidationReport report={validReport} />);
+      
+      expect(screen.getByText('Consistency')).toBeInTheDocument();
+      expect(screen.getByText('Completeness')).toBeInTheDocument();
+      expect(screen.getByText('Scope Alignment')).toBeInTheDocument();
+      expect(screen.getByText('Hallucination Detection')).toBeInTheDocument();
+      expect(screen.getByText('Over Engineering Detection')).toBeInTheDocument();
+    });
+
+    it('does not show auto-correct button when report is valid', () => {
+      render(<ValidationReport report={validReport} onRequestCorrection={() => {}} />);
+      
+      expect(screen.queryByText(/Auto-correct/)).not.toBeInTheDocument();
+    });
+  });
+
+  describe('rendering invalid report', () => {
+    it('shows needs review status when report is invalid', () => {
+      render(<ValidationReport report={invalidReport} />);
+      
+      expect(screen.getByText('Needs Review')).toBeInTheDocument();
+      expect(screen.getByText('3 check(s) need attention')).toBeInTheDocument();
+    });
+
+    it('shows issue counts by severity', () => {
+      render(<ValidationReport report={invalidReport} />);
+      
+      expect(screen.getByText('1 error')).toBeInTheDocument();
+      expect(screen.getByText('1 warning')).toBeInTheDocument();
+      expect(screen.getByText('1 info')).toBeInTheDocument();
+    });
+
+    it('shows issue details when showDetails is true', () => {
+      render(<ValidationReport report={invalidReport} showDetails={true} />);
+      
+      expect(screen.getByText('Issues (3)')).toBeInTheDocument();
+      expect(screen.getByText('Contradictory requirements detected')).toBeInTheDocument();
+      expect(screen.getByText('Missing deployment section')).toBeInTheDocument();
+      expect(screen.getByText('Consider adding monitoring for production')).toBeInTheDocument();
+    });
+
+    it('shows issue location when provided', () => {
+      render(<ValidationReport report={invalidReport} showDetails={true} />);
+      
+      expect(screen.getByText('Location: section 2.1')).toBeInTheDocument();
+    });
+
+    it('shows suggestion when provided', () => {
+      render(<ValidationReport report={invalidReport} showDetails={true} />);
+      
+      expect(screen.getByText(/Clarify the authentication requirements/)).toBeInTheDocument();
+    });
+
+    it('shows auto-fix badge for auto-correctable issues', () => {
+      render(<ValidationReport report={invalidReport} showDetails={true} />);
+      
+      // Two issues are auto-correctable
+      const autoFixBadges = screen.getAllByText('Auto-fix');
+      expect(autoFixBadges).toHaveLength(2);
+    });
+
+    it('hides issue details when showDetails is false', () => {
+      render(<ValidationReport report={invalidReport} showDetails={false} />);
+      
+      expect(screen.queryByText('Issues (3)')).not.toBeInTheDocument();
+      expect(screen.queryByText('Contradictory requirements detected')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('auto-correct button', () => {
+    it('shows auto-correct button when issues are auto-correctable', () => {
+      render(<ValidationReport report={invalidReport} onRequestCorrection={() => {}} />);
+      
+      expect(screen.getByText('Auto-correct (2)')).toBeInTheDocument();
+    });
+
+    it('calls onRequestCorrection when clicked', async () => {
+      const user = userEvent.setup();
+      const onRequestCorrection = jest.fn();
+      render(<ValidationReport report={invalidReport} onRequestCorrection={onRequestCorrection} />);
+      
+      await user.click(screen.getByText('Auto-correct (2)'));
+      expect(onRequestCorrection).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not show when onRequestCorrection is not provided', () => {
+      render(<ValidationReport report={invalidReport} />);
+      
+      expect(screen.queryByText(/Auto-correct/)).not.toBeInTheDocument();
+    });
+  });
+
+  describe('manual review indicator', () => {
+    it('shows manual review badge when required', () => {
+      const manualReviewReport = { ...invalidReport, manual_review_required: true };
+      render(<ValidationReport report={manualReviewReport} />);
+      
+      expect(screen.getByText('Manual review required')).toBeInTheDocument();
+    });
+
+    it('does not show manual review badge when not required', () => {
+      render(<ValidationReport report={invalidReport} />);
+      
+      expect(screen.queryByText('Manual review required')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('loading state', () => {
+    it('shows loading skeleton when isLoading is true', () => {
+      render(<ValidationReport report={validReport} isLoading={true} />);
+      
+      expect(screen.queryByText('Design Validation')).not.toBeInTheDocument();
+      expect(screen.queryByText('Valid')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('LLM sanity review section', () => {
+    it('shows sanity review when provided', () => {
+      render(<ValidationReport report={validReport} sanityReview={sanityReview} />);
+      
+      expect(screen.getByText('LLM Sanity Review')).toBeInTheDocument();
+      expect(screen.getByText('Sane')).toBeInTheDocument();
+      expect(screen.getByText('85%')).toBeInTheDocument();
+    });
+
+    it('shows overall assessment', () => {
+      render(<ValidationReport report={validReport} sanityReview={sanityReview} />);
+      
+      expect(screen.getByText(sanityReview.overall_assessment)).toBeInTheDocument();
+    });
+
+    it('shows issues found', () => {
+      render(<ValidationReport report={validReport} sanityReview={sanityReview} />);
+      
+      expect(screen.getByText('Issues Found:')).toBeInTheDocument();
+      expect(screen.getByText('Minor terminology inconsistency')).toBeInTheDocument();
+    });
+
+    it('shows suggestions', () => {
+      render(<ValidationReport report={validReport} sanityReview={sanityReview} />);
+      
+      expect(screen.getByText('Suggestions:')).toBeInTheDocument();
+      expect(screen.getByText('Consider standardizing API naming conventions')).toBeInTheDocument();
+    });
+
+    it('shows needs review when sanity check fails', () => {
+      const failedSanityReview = { ...sanityReview, is_sane: false, confidence: 0.4 };
+      render(<ValidationReport report={validReport} sanityReview={failedSanityReview} />);
+      
+      expect(screen.getByText('Needs Review')).toBeInTheDocument();
+      expect(screen.getByText('40%')).toBeInTheDocument();
+    });
+
+    it('does not show sanity review when not provided', () => {
+      render(<ValidationReport report={validReport} />);
+      
+      expect(screen.queryByText('LLM Sanity Review')).not.toBeInTheDocument();
+    });
+  });
+});
+
+describe('ValidationBadge', () => {
+  const validReport: ValidationReportData = {
+    is_valid: true,
+    issues: [],
+    checks_passed: ['consistency', 'completeness'],
+    checks_failed: [],
+    auto_correctable_count: 0,
+    manual_review_required: false,
+  };
+
+  const invalidReport: ValidationReportData = {
+    is_valid: false,
+    issues: [
+      { check_name: 'consistency', severity: 'error', message: 'Error', auto_correctable: false },
+      { check_name: 'completeness', severity: 'error', message: 'Error', auto_correctable: false },
+      { check_name: 'scope', severity: 'warning', message: 'Warning', auto_correctable: false },
+    ],
+    checks_passed: [],
+    checks_failed: ['consistency', 'completeness', 'scope'],
+    auto_correctable_count: 0,
+    manual_review_required: false,
+  };
+
+  it('shows valid status for valid report', () => {
+    render(<ValidationBadge report={validReport} />);
+    expect(screen.getByText('Valid')).toBeInTheDocument();
+  });
+
+  it('shows issues status for invalid report', () => {
+    render(<ValidationBadge report={invalidReport} />);
+    expect(screen.getByText('Issues')).toBeInTheDocument();
+  });
+
+  it('shows error and warning counts for invalid report', () => {
+    render(<ValidationBadge report={invalidReport} />);
+    expect(screen.getByText('2E')).toBeInTheDocument();
+    expect(screen.getByText('1W')).toBeInTheDocument();
+  });
+
+  it('applies correct styling for valid report', () => {
+    const { container } = render(<ValidationBadge report={validReport} />);
+    expect(container.firstChild).toHaveClass('bg-green-500/10');
+  });
+
+  it('applies correct styling for invalid report', () => {
+    const { container } = render(<ValidationBadge report={invalidReport} />);
+    expect(container.firstChild).toHaveClass('bg-yellow-500/10');
+  });
+});
diff --git a/devussy-web/src/components/window/Taskbar.tsx b/devussy-web/src/components/window/Taskbar.tsx
index 3a9c375..6a9764b 100644
--- a/devussy-web/src/components/window/Taskbar.tsx
+++ b/devussy-web/src/components/window/Taskbar.tsx
@@ -2,7 +2,7 @@
 
 import React, { useState, useEffect, useRef } from 'react';
 import { cn } from "@/utils";
-import { Layout, HelpCircle, Plus, Power, Settings } from "lucide-react";
+import { Layout, HelpCircle, Plus, Power, Settings, MessageSquare } from "lucide-react";
 import { useTheme } from "@/components/theme/ThemeProvider";
 import { ThemeToggle } from "@/components/theme/ThemeToggle";
 import { CheckpointManager } from "@/components/pipeline/CheckpointManager";
@@ -16,12 +16,14 @@ interface TaskbarProps {
     onNewProject?: () => void;
     onHelp?: () => void;
     onOpenModelSettings?: () => void;
+    onOpenIrc?: () => void;
     // Props for Start Menu options
     currentState?: any;
     onLoadCheckpoint?: (data: any) => void;
     modelConfigs?: ModelConfigs;
     onModelConfigsChange?: (configs: ModelConfigs) => void;
     activeStage?: PipelineStage;
+    ircNick?: string;
 }
 
 export const Taskbar: React.FC<TaskbarProps> = ({
@@ -32,11 +34,13 @@ export const Taskbar: React.FC<TaskbarProps> = ({
     onNewProject,
     onHelp,
     onOpenModelSettings,
+    onOpenIrc,
     currentState,
     onLoadCheckpoint,
     modelConfigs,
     onModelConfigsChange,
-    activeStage
+    activeStage,
+    ircNick = 'Guest'
 }) => {
     const { theme } = useTheme();
     const [isStartMenuOpen, setIsStartMenuOpen] = useState(false);
@@ -90,7 +94,7 @@ export const Taskbar: React.FC<TaskbarProps> = ({
                             <div className="h-10 w-10 rounded-full bg-white border-2 border-white/40 overflow-hidden flex items-center justify-center">
                                 <img src="/devussy_logo_minimal.png" alt="User" className="h-8 w-8 object-contain" />
                             </div>
-                            <span className="text-white font-bold text-lg drop-shadow-md">Devussy User</span>
+                            <span className="text-white font-bold text-lg drop-shadow-md">{ircNick}</span>
                         </div>
 
                         {/* Body */}
@@ -115,6 +119,14 @@ export const Taskbar: React.FC<TaskbarProps> = ({
                                     </div>
                                 </button>
 
+                                <button onClick={() => { onOpenIrc?.(); setIsStartMenuOpen(false); }} className="flex items-center gap-2 p-2 hover:bg-[#316AC5] hover:text-white rounded group transition-colors text-left">
+                                    <MessageSquare className="h-8 w-8 text-green-600 group-hover:text-white" />
+                                    <div className="flex flex-col">
+                                        <span className="font-bold text-sm">IRC Chat</span>
+                                        <span className="text-[10px] text-gray-500 group-hover:text-white/80">Chat with #devussy</span>
+                                    </div>
+                                </button>
+
                                 <div className="mt-auto border-t border-gray-200 pt-2">
                                     <div className="text-xs text-gray-500 font-bold px-2 mb-1 uppercase tracking-wider">All Programs</div>
                                     <div className="flex items-center justify-center p-2 bg-blue-50 rounded border border-blue-100 text-blue-800 text-xs font-bold cursor-pointer hover:bg-blue-100">
@@ -259,6 +271,16 @@ export const Taskbar: React.FC<TaskbarProps> = ({
                 <span>Help</span>
             </button>
 
+            {/* IRC Button */}
+            <button
+                onClick={onOpenIrc}
+                className="flex items-center gap-2 px-3 py-2 rounded-lg text-sm font-medium transition-all text-muted-foreground hover:bg-white/5 hover:text-white"
+                title="IRC Chat"
+            >
+                <MessageSquare className="h-4 w-4" />
+                <span>Chat</span>
+            </button>
+
             {windows.length > 0 && (
                 <div className="h-6 w-px bg-white/10 mx-1" />
             )}
diff --git a/devussy-web/src/stories/Button.stories.ts b/devussy-web/src/stories/Button.stories.ts
new file mode 100644
index 0000000..7c193dd
--- /dev/null
+++ b/devussy-web/src/stories/Button.stories.ts
@@ -0,0 +1,54 @@
+import type { Meta, StoryObj } from '@storybook/nextjs';
+
+import { fn } from 'storybook/test';
+
+import { Button } from './Button';
+
+// More on how to set up stories at: https://storybook.js.org/docs/writing-stories#default-export
+const meta = {
+  title: 'Example/Button',
+  component: Button,
+  parameters: {
+    // Optional parameter to center the component in the Canvas. More info: https://storybook.js.org/docs/configure/story-layout
+    layout: 'centered',
+  },
+  // This component will have an automatically generated Autodocs entry: https://storybook.js.org/docs/writing-docs/autodocs
+  tags: ['autodocs'],
+  // More on argTypes: https://storybook.js.org/docs/api/argtypes
+  argTypes: {
+    backgroundColor: { control: 'color' },
+  },
+  // Use `fn` to spy on the onClick arg, which will appear in the actions panel once invoked: https://storybook.js.org/docs/essentials/actions#story-args
+  args: { onClick: fn() },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
+export const Primary: Story = {
+  args: {
+    primary: true,
+    label: 'Button',
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    label: 'Button',
+  },
+};
+
+export const Large: Story = {
+  args: {
+    size: 'large',
+    label: 'Button',
+  },
+};
+
+export const Small: Story = {
+  args: {
+    size: 'small',
+    label: 'Button',
+  },
+};
diff --git a/devussy-web/src/stories/Button.tsx b/devussy-web/src/stories/Button.tsx
new file mode 100644
index 0000000..d96916c
--- /dev/null
+++ b/devussy-web/src/stories/Button.tsx
@@ -0,0 +1,39 @@
+import './button.css';
+
+export interface ButtonProps {
+  /** Is this the principal call to action on the page? */
+  primary?: boolean;
+  /** What background color to use */
+  backgroundColor?: string;
+  /** How large should the button be? */
+  size?: 'small' | 'medium' | 'large';
+  /** Button contents */
+  label: string;
+  /** Optional click handler */
+  onClick?: () => void;
+}
+
+/** Primary UI component for user interaction */
+export const Button = ({
+  primary = false,
+  size = 'medium',
+  backgroundColor,
+  label,
+  ...props
+}: ButtonProps) => {
+  const mode = primary ? 'storybook-button--primary' : 'storybook-button--secondary';
+  return (
+    <button
+      type="button"
+      className={['storybook-button', `storybook-button--${size}`, mode].join(' ')}
+      {...props}
+    >
+      {label}
+      <style jsx>{`
+        button {
+          background-color: ${backgroundColor};
+        }
+      `}</style>
+    </button>
+  );
+};
diff --git a/devussy-web/src/stories/Configure.mdx b/devussy-web/src/stories/Configure.mdx
new file mode 100644
index 0000000..70fcc2a
--- /dev/null
+++ b/devussy-web/src/stories/Configure.mdx
@@ -0,0 +1,446 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import Image from "next/image";
+
+import Github from "./assets/github.svg";
+import Discord from "./assets/discord.svg";
+import Youtube from "./assets/youtube.svg";
+import Tutorials from "./assets/tutorials.svg";
+import Styling from "./assets/styling.png";
+import Context from "./assets/context.png";
+import Assets from "./assets/assets.png";
+import Docs from "./assets/docs.png";
+import Share from "./assets/share.png";
+import FigmaPlugin from "./assets/figma-plugin.png";
+import Testing from "./assets/testing.png";
+import Accessibility from "./assets/accessibility.png";
+import Theming from "./assets/theming.png";
+import AddonLibrary from "./assets/addon-library.png";
+
+export const RightArrow = () => <svg 
+    viewBox="0 0 14 14" 
+    width="8px" 
+    height="14px" 
+    style={{ 
+      marginLeft: '4px',
+      display: 'inline-block',
+      shapeRendering: 'inherit',
+      verticalAlign: 'middle',
+      fill: 'currentColor',
+      'path fill': 'currentColor'
+    }}
+>
+  <path d="m11.1 7.35-5.5 5.5a.5.5 0 0 1-.7-.7L10.04 7 4.9 1.85a.5.5 0 1 1 .7-.7l5.5 5.5c.2.2.2.5 0 .7Z" />
+</svg>
+
+<Meta title="Configure your project" />
+
+<div className="sb-container">
+  <div className='sb-section-title'>
+    # Configure your project
+
+    Because Storybook works separately from your app, you'll need to configure it for your specific stack and setup. Below, explore guides for configuring Storybook with popular frameworks and tools. If you get stuck, learn how you can ask for help from our community.
+  </div>
+  <div className="sb-section">
+    <div className="sb-section-item">
+      <Image
+        src={Styling}
+        alt="A wall of logos representing different styling technologies"
+        width={0}
+        height={0}
+        style={{ width: '100%', height: 'auto' }}
+      />
+      <h4 className="sb-section-item-heading">Add styling and CSS</h4>
+      <p className="sb-section-item-paragraph">Like with web applications, there are many ways to include CSS within Storybook. Learn more about setting up styling within Storybook.</p>
+      <a
+        href="https://storybook.js.org/docs/configure/styling-and-css/?renderer=react&ref=configure"
+        target="_blank"
+      >Learn more<RightArrow /></a>
+    </div>
+    <div className="sb-section-item">
+      <Image 
+        width={0}
+        height={0}
+        style={{ width: '100%', height: 'auto' }}
+        src={Context}
+        alt="An abstraction representing the composition of data for a component"
+      />
+      <h4 className="sb-section-item-heading">Provide context and mocking</h4>
+      <p className="sb-section-item-paragraph">Often when a story doesn't render, it's because your component is expecting a specific environment or context (like a theme provider) to be available.</p>
+      <a
+        href="https://storybook.js.org/docs/writing-stories/decorators/?renderer=react&ref=configure#context-for-mocking"
+        target="_blank"
+      >Learn more<RightArrow /></a>
+    </div>
+    <div className="sb-section-item">
+      <Image 
+        width={0}
+        height={0}
+        style={{ width: '100%', height: 'auto' }} 
+        src={Assets} 
+        alt="A representation of typography and image assets" 
+      />
+      <div>
+        <h4 className="sb-section-item-heading">Load assets and resources</h4>
+        <p className="sb-section-item-paragraph">To link static files (like fonts) to your projects and stories, use the
+        `staticDirs` configuration option to specify folders to load when
+        starting Storybook.</p>
+        <a
+          href="https://storybook.js.org/docs/configure/images-and-assets/?renderer=react&ref=configure"
+          target="_blank"
+        >Learn more<RightArrow /></a>
+      </div>
+    </div>
+  </div>
+</div>
+<div className="sb-container">
+  <div className='sb-section-title'>
+    # Do more with Storybook
+
+    Now that you know the basics, let's explore other parts of Storybook that will improve your experience. This list is just to get you started. You can customise Storybook in many ways to fit your needs.
+  </div>
+
+  <div className="sb-section">
+    <div className="sb-features-grid">
+      <div className="sb-grid-item">
+        <Image 
+          width={0}
+          height={0}
+          style={{ width: '100%', height: 'auto' }} 
+          src={Docs} 
+          alt="A screenshot showing the autodocs tag being set, pointing a docs page being generated" 
+        />
+        <h4 className="sb-section-item-heading">Autodocs</h4>
+        <p className="sb-section-item-paragraph">Auto-generate living,
+          interactive reference documentation from your components and stories.</p>
+        <a
+          href="https://storybook.js.org/docs/writing-docs/autodocs/?renderer=react&ref=configure"
+          target="_blank"
+        >Learn more<RightArrow /></a>
+      </div>
+      <div className="sb-grid-item">
+        <Image 
+          width={0}
+          height={0}
+          style={{ width: '100%', height: 'auto' }} 
+          src={Share} 
+          alt="A browser window showing a Storybook being published to a chromatic.com URL" 
+        />
+        <h4 className="sb-section-item-heading">Publish to Chromatic</h4>
+        <p className="sb-section-item-paragraph">Publish your Storybook to review and collaborate with your entire team.</p>
+        <a
+          href="https://storybook.js.org/docs/sharing/publish-storybook/?renderer=react&ref=configure#publish-storybook-with-chromatic"
+          target="_blank"
+        >Learn more<RightArrow /></a>
+      </div>
+      <div className="sb-grid-item">
+        <Image 
+          width={0}
+          height={0}
+          style={{ width: '100%', height: 'auto' }} 
+          src={FigmaPlugin} 
+          alt="Windows showing the Storybook plugin in Figma" 
+        />
+        <h4 className="sb-section-item-heading">Figma Plugin</h4>
+        <p className="sb-section-item-paragraph">Embed your stories into Figma to cross-reference the design and live
+          implementation in one place.</p>
+        <a
+          href="https://storybook.js.org/docs/sharing/design-integrations/?renderer=react&ref=configure#embed-storybook-in-figma-with-the-plugin"
+          target="_blank"
+        >Learn more<RightArrow /></a>
+      </div>
+      <div className="sb-grid-item">
+        <Image 
+          width={0}
+          height={0}
+          style={{ width: '100%', height: 'auto' }} 
+          src={Testing} 
+          alt="Screenshot of tests passing and failing" 
+        />
+        <h4 className="sb-section-item-heading">Testing</h4>
+        <p className="sb-section-item-paragraph">Use stories to test a component in all its variations, no matter how
+          complex.</p>
+        <a
+          href="https://storybook.js.org/docs/writing-tests/?renderer=react&ref=configure"
+          target="_blank"
+        >Learn more<RightArrow /></a>
+      </div>
+      <div className="sb-grid-item">
+        <Image 
+          width={0}
+          height={0}
+          style={{ width: '100%', height: 'auto' }} 
+          src={Accessibility} 
+          alt="Screenshot of accessibility tests passing and failing" 
+        />
+        <h4 className="sb-section-item-heading">Accessibility</h4>
+        <p className="sb-section-item-paragraph">Automatically test your components for a11y issues as you develop.</p>
+        <a
+          href="https://storybook.js.org/docs/writing-tests/accessibility-testing/?renderer=react&ref=configure"
+          target="_blank"
+        >Learn more<RightArrow /></a>
+      </div>
+      <div className="sb-grid-item">
+        <Image 
+          width={0}
+          height={0}
+          style={{ width: '100%', height: 'auto' }} 
+          src={Theming} 
+          alt="Screenshot of Storybook in light and dark mode" 
+        />
+        <h4 className="sb-section-item-heading">Theming</h4>
+        <p className="sb-section-item-paragraph">Theme Storybook's UI to personalize it to your project.</p>
+        <a
+          href="https://storybook.js.org/docs/configure/theming/?renderer=react&ref=configure"
+          target="_blank"
+        >Learn more<RightArrow /></a>
+      </div>
+    </div>
+  </div>
+</div>
+<div className='sb-addon'>
+  <div className='sb-addon-text'>
+    <h4>Addons</h4>
+    <p className="sb-section-item-paragraph">Integrate your tools with Storybook to connect workflows.</p>
+    <a
+        href="https://storybook.js.org/addons/?ref=configure"
+        target="_blank"
+      >Discover all addons<RightArrow /></a>
+  </div>
+  <div className='sb-addon-img'>
+    <Image 
+      width={650}
+      height={347}
+      src={AddonLibrary} 
+      alt="Integrate your tools with Storybook to connect workflows." 
+    />
+  </div>
+</div>
+
+<div className="sb-section sb-socials">
+    <div className="sb-section-item">
+      <Image 
+        width={32}
+        height={32}
+        layout="fixed"
+        src={Github} 
+        alt="Github logo" 
+        className="sb-explore-image"
+      />
+      Join our contributors building the future of UI development.
+
+      <a
+        href="https://github.com/storybookjs/storybook"
+        target="_blank"
+      >Star on GitHub<RightArrow /></a>
+    </div>
+    <div className="sb-section-item">
+      <Image 
+        width={33}
+        height={32}
+        layout="fixed"
+        src={Discord} 
+        alt="Discord logo" 
+        className="sb-explore-image"
+      />
+      <div>
+        Get support and chat with frontend developers.
+
+        <a
+          href="https://discord.gg/storybook"
+          target="_blank"
+        >Join Discord server<RightArrow /></a>
+      </div>
+    </div>
+    <div className="sb-section-item">
+      <Image 
+        width={32}
+        height={32}
+        layout="fixed"
+        src={Youtube} 
+        alt="Youtube logo" 
+        className="sb-explore-image"
+      />
+      <div>
+        Watch tutorials, feature previews and interviews.
+
+        <a
+          href="https://www.youtube.com/@chromaticui"
+          target="_blank"
+        >Watch on YouTube<RightArrow /></a>
+      </div>
+    </div>
+    <div className="sb-section-item">
+      <Image 
+        width={33}
+        height={32}
+        layout="fixed"
+        src={Tutorials} 
+        alt="A book" 
+        className="sb-explore-image"
+      />
+      <p>Follow guided walkthroughs on for key workflows.</p>
+
+      <a
+          href="https://storybook.js.org/tutorials/?ref=configure"
+          target="_blank"
+        >Discover tutorials<RightArrow /></a>
+    </div>
+</div>
+
+<style>
+  {`
+  .sb-container {
+    margin-bottom: 48px;
+  }
+
+  .sb-section {
+    width: 100%;
+    display: flex;
+    flex-direction: row;
+    gap: 20px;
+  }
+
+  img {
+    object-fit: cover;
+  }
+
+  .sb-section-title {
+    margin-bottom: 32px;
+  }
+
+  .sb-section a:not(h1 a, h2 a, h3 a) {
+    font-size: 14px;
+  }
+
+  .sb-section-item, .sb-grid-item {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .sb-section-item-heading {
+    padding-top: 20px !important;
+    padding-bottom: 5px !important;
+    margin: 0 !important;
+  }
+  .sb-section-item-paragraph {
+    margin: 0;
+    padding-bottom: 10px;
+  }
+
+  .sb-chevron {
+    margin-left: 5px;
+  }
+
+  .sb-features-grid {
+    display: grid;
+    grid-template-columns: repeat(2, 1fr);
+    grid-gap: 32px 20px;
+  }
+
+  .sb-socials {
+    display: grid;
+    grid-template-columns: repeat(4, 1fr);
+  }
+
+  .sb-socials p {
+    margin-bottom: 10px;
+  }
+
+  .sb-explore-image {
+    max-height: 32px;
+    align-self: flex-start;
+  }
+
+  .sb-addon {
+    width: 100%;
+    display: flex;
+    align-items: center;
+    position: relative;
+    background-color: #EEF3F8;
+    border-radius: 5px;
+    border: 1px solid rgba(0, 0, 0, 0.05);
+    background: #EEF3F8;
+    height: 180px;
+    margin-bottom: 48px;
+    overflow: hidden;
+  }
+
+  .sb-addon-text {
+    padding-left: 48px;
+    max-width: 240px;
+  }
+
+  .sb-addon-text h4 {
+    padding-top: 0px;
+  }
+
+  .sb-addon-img {
+    position: absolute;
+    left: 345px;
+    top: 0;
+    height: 100%;
+    width: 200%;
+    overflow: hidden;
+  }
+
+  .sb-addon-img img {
+    width: 650px;
+    transform: rotate(-15deg);
+    margin-left: 40px;
+    margin-top: -72px;
+    box-shadow: 0 0 1px rgba(255, 255, 255, 0);
+    backface-visibility: hidden;
+  }
+
+  @media screen and (max-width: 800px) {
+    .sb-addon-img {
+      left: 300px;
+    }
+  }
+
+  @media screen and (max-width: 600px) {
+    .sb-section {
+      flex-direction: column;
+    }
+
+    .sb-features-grid {
+      grid-template-columns: repeat(1, 1fr);
+    }
+
+    .sb-socials {
+      grid-template-columns: repeat(2, 1fr);
+    }
+
+    .sb-addon {
+      height: 280px;
+      align-items: flex-start;
+      padding-top: 32px;
+      overflow: hidden;
+    }
+
+    .sb-addon-text {
+      padding-left: 24px;
+    }
+
+    .sb-addon-img {
+      right: 0;
+      left: 0;
+      top: 130px;
+      bottom: 0;
+      overflow: hidden;
+      height: auto;
+      width: 124%;
+    }
+
+    .sb-addon-img img {
+      width: 1200px;
+      transform: rotate(-12deg);
+      margin-left: 0;
+      margin-top: 48px;
+      margin-bottom: -40px;
+      margin-left: -24px;
+    }
+  }
+  `}
+</style>
diff --git a/devussy-web/src/stories/Header.stories.ts b/devussy-web/src/stories/Header.stories.ts
new file mode 100644
index 0000000..56ed5e0
--- /dev/null
+++ b/devussy-web/src/stories/Header.stories.ts
@@ -0,0 +1,34 @@
+import type { Meta, StoryObj } from '@storybook/nextjs';
+
+import { fn } from 'storybook/test';
+
+import { Header } from './Header';
+
+const meta = {
+  title: 'Example/Header',
+  component: Header,
+  // This component will have an automatically generated Autodocs entry: https://storybook.js.org/docs/writing-docs/autodocs
+  tags: ['autodocs'],
+  parameters: {
+    // More on how to position stories at: https://storybook.js.org/docs/configure/story-layout
+    layout: 'fullscreen',
+  },
+  args: {
+    onLogin: fn(),
+    onLogout: fn(),
+    onCreateAccount: fn(),
+  },
+} satisfies Meta<typeof Header>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const LoggedIn: Story = {
+  args: {
+    user: {
+      name: 'Jane Doe',
+    },
+  },
+};
+
+export const LoggedOut: Story = {};
diff --git a/devussy-web/src/stories/Header.tsx b/devussy-web/src/stories/Header.tsx
new file mode 100644
index 0000000..d05ed4f
--- /dev/null
+++ b/devussy-web/src/stories/Header.tsx
@@ -0,0 +1,54 @@
+import { Button } from './Button';
+import './header.css';
+
+type User = {
+  name: string;
+};
+
+export interface HeaderProps {
+  user?: User;
+  onLogin?: () => void;
+  onLogout?: () => void;
+  onCreateAccount?: () => void;
+}
+
+export const Header = ({ user, onLogin, onLogout, onCreateAccount }: HeaderProps) => (
+  <header>
+    <div className="storybook-header">
+      <div>
+        <svg width="32" height="32" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
+          <g fill="none" fillRule="evenodd">
+            <path
+              d="M10 0h12a10 10 0 0110 10v12a10 10 0 01-10 10H10A10 10 0 010 22V10A10 10 0 0110 0z"
+              fill="#FFF"
+            />
+            <path
+              d="M5.3 10.6l10.4 6v11.1l-10.4-6v-11zm11.4-6.2l9.7 5.5-9.7 5.6V4.4z"
+              fill="#555AB9"
+            />
+            <path
+              d="M27.2 10.6v11.2l-10.5 6V16.5l10.5-6zM15.7 4.4v11L6 10l9.7-5.5z"
+              fill="#91BAF8"
+            />
+          </g>
+        </svg>
+        <h1>Acme</h1>
+      </div>
+      <div>
+        {user ? (
+          <>
+            <span className="welcome">
+              Welcome, <b>{user.name}</b>!
+            </span>
+            <Button size="small" onClick={onLogout} label="Log out" />
+          </>
+        ) : (
+          <>
+            <Button size="small" onClick={onLogin} label="Log in" />
+            <Button primary size="small" onClick={onCreateAccount} label="Sign up" />
+          </>
+        )}
+      </div>
+    </div>
+  </header>
+);
diff --git a/devussy-web/src/stories/Page.stories.ts b/devussy-web/src/stories/Page.stories.ts
new file mode 100644
index 0000000..46f09c0
--- /dev/null
+++ b/devussy-web/src/stories/Page.stories.ts
@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from '@storybook/nextjs';
+
+import { expect, userEvent, within } from 'storybook/test';
+
+import { Page } from './Page';
+
+const meta = {
+  title: 'Example/Page',
+  component: Page,
+  parameters: {
+    // More on how to position stories at: https://storybook.js.org/docs/configure/story-layout
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof Page>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const LoggedOut: Story = {};
+
+// More on component testing: https://storybook.js.org/docs/writing-tests/interaction-testing
+export const LoggedIn: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const loginButton = canvas.getByRole('button', { name: /Log in/i });
+    await expect(loginButton).toBeInTheDocument();
+    await userEvent.click(loginButton);
+    await expect(loginButton).not.toBeInTheDocument();
+
+    const logoutButton = canvas.getByRole('button', { name: /Log out/i });
+    await expect(logoutButton).toBeInTheDocument();
+  },
+};
diff --git a/devussy-web/src/stories/Page.tsx b/devussy-web/src/stories/Page.tsx
new file mode 100644
index 0000000..e117483
--- /dev/null
+++ b/devussy-web/src/stories/Page.tsx
@@ -0,0 +1,73 @@
+import React from 'react';
+
+import { Header } from './Header';
+import './page.css';
+
+type User = {
+  name: string;
+};
+
+export const Page: React.FC = () => {
+  const [user, setUser] = React.useState<User>();
+
+  return (
+    <article>
+      <Header
+        user={user}
+        onLogin={() => setUser({ name: 'Jane Doe' })}
+        onLogout={() => setUser(undefined)}
+        onCreateAccount={() => setUser({ name: 'Jane Doe' })}
+      />
+
+      <section className="storybook-page">
+        <h2>Pages in Storybook</h2>
+        <p>
+          We recommend building UIs with a{' '}
+          <a href="https://componentdriven.org" target="_blank" rel="noopener noreferrer">
+            <strong>component-driven</strong>
+          </a>{' '}
+          process starting with atomic components and ending with pages.
+        </p>
+        <p>
+          Render pages with mock data. This makes it easy to build and review page states without
+          needing to navigate to them in your app. Here are some handy patterns for managing page
+          data in Storybook:
+        </p>
+        <ul>
+          <li>
+            Use a higher-level connected component. Storybook helps you compose such data from the
+            "args" of child component stories
+          </li>
+          <li>
+            Assemble data in the page component from your services. You can mock these services out
+            using Storybook.
+          </li>
+        </ul>
+        <p>
+          Get a guided tutorial on component-driven development at{' '}
+          <a href="https://storybook.js.org/tutorials/" target="_blank" rel="noopener noreferrer">
+            Storybook tutorials
+          </a>
+          . Read more in the{' '}
+          <a href="https://storybook.js.org/docs" target="_blank" rel="noopener noreferrer">
+            docs
+          </a>
+          .
+        </p>
+        <div className="tip-wrapper">
+          <span className="tip">Tip</span> Adjust the width of the canvas with the{' '}
+          <svg width="10" height="10" viewBox="0 0 12 12" xmlns="http://www.w3.org/2000/svg">
+            <g fill="none" fillRule="evenodd">
+              <path
+                d="M1.5 5.2h4.8c.3 0 .5.2.5.4v5.1c-.1.2-.3.3-.4.3H1.4a.5.5 0 01-.5-.4V5.7c0-.3.2-.5.5-.5zm0-2.1h6.9c.3 0 .5.2.5.4v7a.5.5 0 01-1 0V4H1.5a.5.5 0 010-1zm0-2.1h9c.3 0 .5.2.5.4v9.1a.5.5 0 01-1 0V2H1.5a.5.5 0 010-1zm4.3 5.2H2V10h3.8V6.2z"
+                id="a"
+                fill="#999"
+              />
+            </g>
+          </svg>
+          Viewports addon in the toolbar
+        </div>
+      </section>
+    </article>
+  );
+};
diff --git a/devussy-web/src/stories/assets/accessibility.png b/devussy-web/src/stories/assets/accessibility.png
new file mode 100644
index 0000000..6ffe6fe
Binary files /dev/null and b/devussy-web/src/stories/assets/accessibility.png differ
diff --git a/devussy-web/src/stories/assets/accessibility.svg b/devussy-web/src/stories/assets/accessibility.svg
new file mode 100644
index 0000000..107e93f
--- /dev/null
+++ b/devussy-web/src/stories/assets/accessibility.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" fill="none" viewBox="0 0 48 48"><title>Accessibility</title><circle cx="24.334" cy="24" r="24" fill="#A849FF" fill-opacity=".3"/><path fill="#A470D5" fill-rule="evenodd" d="M27.8609 11.585C27.8609 9.59506 26.2497 7.99023 24.2519 7.99023C22.254 7.99023 20.6429 9.65925 20.6429 11.585C20.6429 13.575 22.254 15.1799 24.2519 15.1799C26.2497 15.1799 27.8609 13.575 27.8609 11.585ZM21.8922 22.6473C21.8467 23.9096 21.7901 25.4788 21.5897 26.2771C20.9853 29.0462 17.7348 36.3314 17.3325 37.2275C17.1891 37.4923 17.1077 37.7955 17.1077 38.1178C17.1077 39.1519 17.946 39.9902 18.9802 39.9902C19.6587 39.9902 20.253 39.6293 20.5814 39.0889L20.6429 38.9874L24.2841 31.22C24.2841 31.22 27.5529 37.9214 27.9238 38.6591C28.2948 39.3967 28.8709 39.9902 29.7168 39.9902C30.751 39.9902 31.5893 39.1519 31.5893 38.1178C31.5893 37.7951 31.3639 37.2265 31.3639 37.2265C30.9581 36.3258 27.698 29.0452 27.0938 26.2771C26.8975 25.4948 26.847 23.9722 26.8056 22.7236C26.7927 22.333 26.7806 21.9693 26.7653 21.6634C26.7008 21.214 27.0231 20.8289 27.4097 20.7005L35.3366 18.3253C36.3033 18.0685 36.8834 16.9773 36.6256 16.0144C36.3678 15.0515 35.2722 14.4737 34.3055 14.7305C34.3055 14.7305 26.8619 17.1057 24.2841 17.1057C21.7062 17.1057 14.456 14.7947 14.456 14.7947C13.4893 14.5379 12.3937 14.9873 12.0715 15.9502C11.7493 16.9131 12.3293 18.0044 13.3604 18.3253L21.2873 20.7005C21.674 20.8289 21.9318 21.214 21.9318 21.6634C21.9174 21.9493 21.9053 22.2857 21.8922 22.6473Z" clip-rule="evenodd"/></svg>
\ No newline at end of file
diff --git a/devussy-web/src/stories/assets/addon-library.png b/devussy-web/src/stories/assets/addon-library.png
new file mode 100644
index 0000000..95deb38
Binary files /dev/null and b/devussy-web/src/stories/assets/addon-library.png differ
diff --git a/devussy-web/src/stories/assets/assets.png b/devussy-web/src/stories/assets/assets.png
new file mode 100644
index 0000000..cfba681
Binary files /dev/null and b/devussy-web/src/stories/assets/assets.png differ
diff --git a/devussy-web/src/stories/assets/avif-test-image.avif b/devussy-web/src/stories/assets/avif-test-image.avif
new file mode 100644
index 0000000..530709b
Binary files /dev/null and b/devussy-web/src/stories/assets/avif-test-image.avif differ
diff --git a/devussy-web/src/stories/assets/context.png b/devussy-web/src/stories/assets/context.png
new file mode 100644
index 0000000..e5cd249
Binary files /dev/null and b/devussy-web/src/stories/assets/context.png differ
diff --git a/devussy-web/src/stories/assets/discord.svg b/devussy-web/src/stories/assets/discord.svg
new file mode 100644
index 0000000..d638958
--- /dev/null
+++ b/devussy-web/src/stories/assets/discord.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="33" height="32" fill="none" viewBox="0 0 33 32"><g clip-path="url(#clip0_10031_177575)"><mask id="mask0_10031_177575" style="mask-type:luminance" width="33" height="25" x="0" y="4" maskUnits="userSpaceOnUse"><path fill="#fff" d="M32.5034 4.00195H0.503906V28.7758H32.5034V4.00195Z"/></mask><g mask="url(#mask0_10031_177575)"><path fill="#5865F2" d="M27.5928 6.20817C25.5533 5.27289 23.3662 4.58382 21.0794 4.18916C21.0378 4.18154 20.9962 4.20057 20.9747 4.23864C20.6935 4.73863 20.3819 5.3909 20.1637 5.90358C17.7042 5.53558 15.2573 5.53558 12.8481 5.90358C12.6299 5.37951 12.307 4.73863 12.0245 4.23864C12.003 4.20184 11.9614 4.18281 11.9198 4.18916C9.63431 4.58255 7.44721 5.27163 5.40641 6.20817C5.38874 6.21578 5.3736 6.22848 5.36355 6.24497C1.21508 12.439 0.078646 18.4809 0.636144 24.4478C0.638667 24.477 0.655064 24.5049 0.677768 24.5227C3.41481 26.5315 6.06609 27.7511 8.66815 28.5594C8.70979 28.5721 8.75392 28.5569 8.78042 28.5226C9.39594 27.6826 9.94461 26.7968 10.4151 25.8653C10.4428 25.8107 10.4163 25.746 10.3596 25.7244C9.48927 25.3945 8.66058 24.9922 7.86343 24.5354C7.80038 24.4986 7.79533 24.4084 7.85333 24.3653C8.02108 24.2397 8.18888 24.109 8.34906 23.977C8.37804 23.9529 8.41842 23.9478 8.45249 23.963C13.6894 26.3526 19.359 26.3526 24.5341 23.963C24.5682 23.9465 24.6086 23.9516 24.6388 23.9757C24.799 24.1077 24.9668 24.2397 25.1358 24.3653C25.1938 24.4084 25.19 24.4986 25.127 24.5354C24.3298 25.0011 23.5011 25.3945 22.6296 25.7232C22.5728 25.7447 22.5476 25.8107 22.5754 25.8653C23.0559 26.7955 23.6046 27.6812 24.2087 28.5213C24.234 28.5569 24.2794 28.5721 24.321 28.5594C26.9357 27.7511 29.5869 26.5315 32.324 24.5227C32.348 24.5049 32.3631 24.4783 32.3656 24.4491C33.0328 17.5506 31.2481 11.5584 27.6344 6.24623C27.6256 6.22848 27.6105 6.21578 27.5928 6.20817ZM11.1971 20.8146C9.62043 20.8146 8.32129 19.3679 8.32129 17.5913C8.32129 15.8146 9.59523 14.368 11.1971 14.368C12.8115 14.368 14.0981 15.8273 14.0729 17.5913C14.0729 19.3679 12.7989 20.8146 11.1971 20.8146ZM21.8299 20.8146C20.2533 20.8146 18.9541 19.3679 18.9541 17.5913C18.9541 15.8146 20.228 14.368 21.8299 14.368C23.4444 14.368 24.7309 15.8273 24.7057 17.5913C24.7057 19.3679 23.4444 20.8146 21.8299 20.8146Z"/></g></g><defs><clipPath id="clip0_10031_177575"><rect width="32" height="32" fill="#fff" transform="translate(0.5)"/></clipPath></defs></svg>
\ No newline at end of file
diff --git a/devussy-web/src/stories/assets/docs.png b/devussy-web/src/stories/assets/docs.png
new file mode 100644
index 0000000..a749629
Binary files /dev/null and b/devussy-web/src/stories/assets/docs.png differ
diff --git a/devussy-web/src/stories/assets/figma-plugin.png b/devussy-web/src/stories/assets/figma-plugin.png
new file mode 100644
index 0000000..8f79b08
Binary files /dev/null and b/devussy-web/src/stories/assets/figma-plugin.png differ
diff --git a/devussy-web/src/stories/assets/github.svg b/devussy-web/src/stories/assets/github.svg
new file mode 100644
index 0000000..dc51352
--- /dev/null
+++ b/devussy-web/src/stories/assets/github.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" fill="none" viewBox="0 0 32 32"><path fill="#161614" d="M16.0001 0C7.16466 0 0 7.17472 0 16.0256C0 23.1061 4.58452 29.1131 10.9419 31.2322C11.7415 31.3805 12.0351 30.8845 12.0351 30.4613C12.0351 30.0791 12.0202 28.8167 12.0133 27.4776C7.56209 28.447 6.62283 25.5868 6.62283 25.5868C5.89499 23.7345 4.8463 23.2419 4.8463 23.2419C3.39461 22.2473 4.95573 22.2678 4.95573 22.2678C6.56242 22.3808 7.40842 23.9192 7.40842 23.9192C8.83547 26.3691 11.1514 25.6609 12.0645 25.2514C12.2081 24.2156 12.6227 23.5087 13.0803 23.1085C9.52648 22.7032 5.7906 21.3291 5.7906 15.1886C5.7906 13.4389 6.41563 12.0094 7.43916 10.8871C7.27303 10.4834 6.72537 8.85349 7.59415 6.64609C7.59415 6.64609 8.93774 6.21539 11.9953 8.28877C13.2716 7.9337 14.6404 7.75563 16.0001 7.74953C17.3599 7.75563 18.7297 7.9337 20.0084 8.28877C23.0623 6.21539 24.404 6.64609 24.404 6.64609C25.2749 8.85349 24.727 10.4834 24.5608 10.8871C25.5868 12.0094 26.2075 13.4389 26.2075 15.1886C26.2075 21.3437 22.4645 22.699 18.9017 23.0957C19.4756 23.593 19.9869 24.5683 19.9869 26.0634C19.9869 28.2077 19.9684 29.9334 19.9684 30.4613C19.9684 30.8877 20.2564 31.3874 21.0674 31.2301C27.4213 29.1086 32 23.1037 32 16.0256C32 7.17472 24.8364 0 16.0001 0ZM5.99257 22.8288C5.95733 22.9084 5.83227 22.9322 5.71834 22.8776C5.60229 22.8253 5.53711 22.7168 5.57474 22.6369C5.60918 22.5549 5.7345 22.5321 5.85029 22.587C5.9666 22.6393 6.03284 22.7489 5.99257 22.8288ZM6.7796 23.5321C6.70329 23.603 6.55412 23.5701 6.45291 23.4581C6.34825 23.3464 6.32864 23.197 6.40601 23.125C6.4847 23.0542 6.62937 23.0874 6.73429 23.1991C6.83895 23.3121 6.85935 23.4605 6.7796 23.5321ZM7.31953 24.4321C7.2215 24.5003 7.0612 24.4363 6.96211 24.2938C6.86407 24.1513 6.86407 23.9804 6.96422 23.9119C7.06358 23.8435 7.2215 23.905 7.32191 24.0465C7.41968 24.1914 7.41968 24.3623 7.31953 24.4321ZM8.23267 25.4743C8.14497 25.5712 7.95818 25.5452 7.82146 25.413C7.68156 25.2838 7.64261 25.1004 7.73058 25.0035C7.81934 24.9064 8.00719 24.9337 8.14497 25.0648C8.28381 25.1938 8.3262 25.3785 8.23267 25.4743ZM9.41281 25.8262C9.37413 25.9517 9.19423 26.0088 9.013 25.9554C8.83203 25.9005 8.7136 25.7535 8.75016 25.6266C8.78778 25.5003 8.96848 25.4408 9.15104 25.4979C9.33174 25.5526 9.45044 25.6985 9.41281 25.8262ZM10.7559 25.9754C10.7604 26.1076 10.6067 26.2172 10.4165 26.2196C10.2252 26.2238 10.0704 26.1169 10.0683 25.9868C10.0683 25.8534 10.2185 25.7448 10.4098 25.7416C10.6001 25.7379 10.7559 25.8441 10.7559 25.9754ZM12.0753 25.9248C12.0981 26.0537 11.9658 26.1862 11.7769 26.2215C11.5912 26.2554 11.4192 26.1758 11.3957 26.0479C11.3726 25.9157 11.5072 25.7833 11.6927 25.7491C11.8819 25.7162 12.0512 25.7937 12.0753 25.9248Z"/></svg>
\ No newline at end of file
diff --git a/devussy-web/src/stories/assets/share.png b/devussy-web/src/stories/assets/share.png
new file mode 100644
index 0000000..8097a37
Binary files /dev/null and b/devussy-web/src/stories/assets/share.png differ
diff --git a/devussy-web/src/stories/assets/styling.png b/devussy-web/src/stories/assets/styling.png
new file mode 100644
index 0000000..d341e82
Binary files /dev/null and b/devussy-web/src/stories/assets/styling.png differ
diff --git a/devussy-web/src/stories/assets/testing.png b/devussy-web/src/stories/assets/testing.png
new file mode 100644
index 0000000..d4ac39a
Binary files /dev/null and b/devussy-web/src/stories/assets/testing.png differ
diff --git a/devussy-web/src/stories/assets/theming.png b/devussy-web/src/stories/assets/theming.png
new file mode 100644
index 0000000..1535eb9
Binary files /dev/null and b/devussy-web/src/stories/assets/theming.png differ
diff --git a/devussy-web/src/stories/assets/tutorials.svg b/devussy-web/src/stories/assets/tutorials.svg
new file mode 100644
index 0000000..b492a9c
--- /dev/null
+++ b/devussy-web/src/stories/assets/tutorials.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="33" height="32" fill="none" viewBox="0 0 33 32"><g clip-path="url(#clip0_10031_177597)"><path fill="#B7F0EF" fill-rule="evenodd" d="M17 7.87059C17 6.48214 17.9812 5.28722 19.3431 5.01709L29.5249 2.99755C31.3238 2.64076 33 4.01717 33 5.85105V22.1344C33 23.5229 32.0188 24.7178 30.6569 24.9879L20.4751 27.0074C18.6762 27.3642 17 25.9878 17 24.1539L17 7.87059Z" clip-rule="evenodd" opacity=".7"/><path fill="#87E6E5" fill-rule="evenodd" d="M1 5.85245C1 4.01857 2.67623 2.64215 4.47507 2.99895L14.6569 5.01848C16.0188 5.28861 17 6.48354 17 7.87198V24.1553C17 25.9892 15.3238 27.3656 13.5249 27.0088L3.34311 24.9893C1.98119 24.7192 1 23.5242 1 22.1358V5.85245Z" clip-rule="evenodd"/><path fill="#61C1FD" fill-rule="evenodd" d="M15.543 5.71289C15.543 5.71289 16.8157 5.96289 17.4002 6.57653C17.9847 7.19016 18.4521 9.03107 18.4521 9.03107C18.4521 9.03107 18.4521 25.1106 18.4521 26.9629C18.4521 28.8152 19.3775 31.4174 19.3775 31.4174L17.4002 28.8947L16.2575 31.4174C16.2575 31.4174 15.543 29.0765 15.543 27.122C15.543 25.1674 15.543 5.71289 15.543 5.71289Z" clip-rule="evenodd"/></g><defs><clipPath id="clip0_10031_177597"><rect width="32" height="32" fill="#fff" transform="translate(0.5)"/></clipPath></defs></svg>
\ No newline at end of file
diff --git a/devussy-web/src/stories/assets/youtube.svg b/devussy-web/src/stories/assets/youtube.svg
new file mode 100644
index 0000000..a7515d7
--- /dev/null
+++ b/devussy-web/src/stories/assets/youtube.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" fill="none" viewBox="0 0 32 32"><path fill="#ED1D24" d="M31.3313 8.44657C30.9633 7.08998 29.8791 6.02172 28.5022 5.65916C26.0067 5.00026 16 5.00026 16 5.00026C16 5.00026 5.99333 5.00026 3.4978 5.65916C2.12102 6.02172 1.03665 7.08998 0.668678 8.44657C0 10.9053 0 16.0353 0 16.0353C0 16.0353 0 21.1652 0.668678 23.6242C1.03665 24.9806 2.12102 26.0489 3.4978 26.4116C5.99333 27.0703 16 27.0703 16 27.0703C16 27.0703 26.0067 27.0703 28.5022 26.4116C29.8791 26.0489 30.9633 24.9806 31.3313 23.6242C32 21.1652 32 16.0353 32 16.0353C32 16.0353 32 10.9053 31.3313 8.44657Z"/><path fill="#fff" d="M12.7266 20.6934L21.0902 16.036L12.7266 11.3781V20.6934Z"/></svg>
\ No newline at end of file
diff --git a/devussy-web/src/stories/button.css b/devussy-web/src/stories/button.css
new file mode 100644
index 0000000..4e3620b
--- /dev/null
+++ b/devussy-web/src/stories/button.css
@@ -0,0 +1,30 @@
+.storybook-button {
+  display: inline-block;
+  cursor: pointer;
+  border: 0;
+  border-radius: 3em;
+  font-weight: 700;
+  line-height: 1;
+  font-family: 'Nunito Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
+}
+.storybook-button--primary {
+  background-color: #555ab9;
+  color: white;
+}
+.storybook-button--secondary {
+  box-shadow: rgba(0, 0, 0, 0.15) 0px 0px 0px 1px inset;
+  background-color: transparent;
+  color: #333;
+}
+.storybook-button--small {
+  padding: 10px 16px;
+  font-size: 12px;
+}
+.storybook-button--medium {
+  padding: 11px 20px;
+  font-size: 14px;
+}
+.storybook-button--large {
+  padding: 12px 24px;
+  font-size: 16px;
+}
diff --git a/devussy-web/src/stories/header.css b/devussy-web/src/stories/header.css
new file mode 100644
index 0000000..5efd46c
--- /dev/null
+++ b/devussy-web/src/stories/header.css
@@ -0,0 +1,32 @@
+.storybook-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  border-bottom: 1px solid rgba(0, 0, 0, 0.1);
+  padding: 15px 20px;
+  font-family: 'Nunito Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
+}
+
+.storybook-header svg {
+  display: inline-block;
+  vertical-align: top;
+}
+
+.storybook-header h1 {
+  display: inline-block;
+  vertical-align: top;
+  margin: 6px 0 6px 10px;
+  font-weight: 700;
+  font-size: 20px;
+  line-height: 1;
+}
+
+.storybook-header button + button {
+  margin-left: 10px;
+}
+
+.storybook-header .welcome {
+  margin-right: 10px;
+  color: #333;
+  font-size: 14px;
+}
diff --git a/devussy-web/src/stories/page.css b/devussy-web/src/stories/page.css
new file mode 100644
index 0000000..77c81d2
--- /dev/null
+++ b/devussy-web/src/stories/page.css
@@ -0,0 +1,68 @@
+.storybook-page {
+  margin: 0 auto;
+  padding: 48px 20px;
+  max-width: 600px;
+  color: #333;
+  font-size: 14px;
+  line-height: 24px;
+  font-family: 'Nunito Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
+}
+
+.storybook-page h2 {
+  display: inline-block;
+  vertical-align: top;
+  margin: 0 0 4px;
+  font-weight: 700;
+  font-size: 32px;
+  line-height: 1;
+}
+
+.storybook-page p {
+  margin: 1em 0;
+}
+
+.storybook-page a {
+  color: inherit;
+}
+
+.storybook-page ul {
+  margin: 1em 0;
+  padding-left: 30px;
+}
+
+.storybook-page li {
+  margin-bottom: 8px;
+}
+
+.storybook-page .tip {
+  display: inline-block;
+  vertical-align: top;
+  margin-right: 10px;
+  border-radius: 1em;
+  background: #e7fdd8;
+  padding: 4px 12px;
+  color: #357a14;
+  font-weight: 700;
+  font-size: 11px;
+  line-height: 12px;
+}
+
+.storybook-page .tip-wrapper {
+  margin-top: 40px;
+  margin-bottom: 40px;
+  font-size: 13px;
+  line-height: 20px;
+}
+
+.storybook-page .tip-wrapper svg {
+  display: inline-block;
+  vertical-align: top;
+  margin-top: 3px;
+  margin-right: 4px;
+  width: 12px;
+  height: 12px;
+}
+
+.storybook-page .tip-wrapper svg path {
+  fill: #1ea7fd;
+}
diff --git a/devussy-web/streaming_server/analytics.py b/devussy-web/streaming_server/analytics.py
new file mode 100644
index 0000000..b0fdac9
--- /dev/null
+++ b/devussy-web/streaming_server/analytics.py
@@ -0,0 +1,156 @@
+import os
+import hashlib
+import json
+import time
+import sqlite3
+from typing import Optional, Dict, Any
+
+DB_PATH = os.getenv('DEVUSSY_ANALYTICS_DB', 'analytics.db')
+
+
+def get_connection():
+    conn = sqlite3.connect(DB_PATH)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def init_db():
+    conn = get_connection()
+    with conn:
+        conn.executescript('''
+        CREATE TABLE IF NOT EXISTS sessions (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            session_id TEXT UNIQUE NOT NULL,
+            ip_hash TEXT NOT NULL,
+            user_agent TEXT,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+        );
+        CREATE TABLE IF NOT EXISTS api_calls (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            session_id TEXT,
+            endpoint TEXT NOT NULL,
+            method TEXT NOT NULL,
+            status_code INTEGER,
+            duration_ms REAL,
+            request_size INTEGER,
+            response_size INTEGER,
+            model_used TEXT,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+        );
+        CREATE TABLE IF NOT EXISTS user_inputs (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            session_id TEXT,
+            input_type TEXT NOT NULL,
+            project_name TEXT,
+            sanitized_requirements TEXT,
+            languages TEXT,
+            created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+        );
+        ''')
+    conn.close()
+
+
+def hash_ip(ip: str) -> str:
+    return hashlib.sha256(ip.encode('utf-8')).hexdigest()
+
+
+def log_session(session_id: str, ip: str, user_agent: Optional[str] = None):
+    conn = get_connection()
+    with conn:
+        conn.execute(
+            "INSERT OR IGNORE INTO sessions (session_id, ip_hash, user_agent) VALUES (?, ?, ?)",
+            (session_id, hash_ip(ip), user_agent),
+        )
+    conn.close()
+
+
+def log_api_call(
+    session_id: str,
+    endpoint: str,
+    method: str,
+    status_code: int,
+    duration_ms: float,
+    request_size: int,
+    response_size: int,
+    model_used: Optional[str] = None,
+):
+    conn = get_connection()
+    with conn:
+        conn.execute(
+            "INSERT INTO api_calls (session_id, endpoint, method, status_code, duration_ms, request_size, response_size, model_used) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                session_id,
+                endpoint,
+                method,
+                status_code,
+                duration_ms,
+                request_size,
+                response_size,
+                model_used,
+            ),
+        )
+    conn.close()
+
+
+def sanitize_requirements(req: str) -> str:
+    # Simple redaction: remove any API keys or tokens patterns
+    # This is a placeholder; real implementation would use regexes for common patterns
+    return req.replace('API_KEY', '[REDACTED]').replace('TOKEN', '[REDACTED]')
+
+
+def log_user_input(
+    session_id: str,
+    input_type: str,
+    project_name: Optional[str] = None,
+    requirements: Optional[str] = None,
+    languages: Optional[str] = None,
+):
+    # Normalize languages to a string for SQLite storage
+    if languages is None:
+        normalized_languages = None
+    elif isinstance(languages, (list, tuple, set)):
+        try:
+            normalized_languages = ", ".join(str(lang) for lang in languages)
+        except Exception:
+            normalized_languages = str(languages)
+    else:
+        normalized_languages = str(languages)
+
+    conn = get_connection()
+    with conn:
+        conn.execute(
+            "INSERT INTO user_inputs (session_id, input_type, project_name, sanitized_requirements, languages) VALUES (?, ?, ?, ?, ?)",
+            (
+                session_id,
+                input_type,
+                project_name,
+                sanitize_requirements(requirements or ''),
+                normalized_languages,
+            ),
+        )
+    conn.close()
+
+
+def get_overview() -> Dict[str, Any]:
+    conn = get_connection()
+    cur = conn.cursor()
+    cur.execute('SELECT COUNT(*) FROM sessions')
+    total_sessions = cur.fetchone()[0]
+    cur.execute('SELECT COUNT(*) FROM api_calls')
+    total_calls = cur.fetchone()[0]
+    cur.execute('SELECT endpoint, COUNT(*) as cnt FROM api_calls GROUP BY endpoint ORDER BY cnt DESC LIMIT 5')
+    popular = [{"endpoint": row[0], "count": row[1]} for row in cur.fetchall()]
+    cur.execute('SELECT AVG(duration_ms) FROM api_calls')
+    avg_latency = cur.fetchone()[0]
+    cur.execute('SELECT model_used, COUNT(*) FROM api_calls WHERE model_used IS NOT NULL GROUP BY model_used')
+    model_usage = [{"model": row[0], "count": row[1]} for row in cur.fetchall()]
+    conn.close()
+    return {
+        "total_sessions": total_sessions,
+        "total_api_calls": total_calls,
+        "popular_endpoints": popular,
+        "average_latency_ms": avg_latency,
+        "model_usage": model_usage,
+    }
diff --git a/devussy-web/streaming_server/app.py b/devussy-web/streaming_server/app.py
index 7686a5d..c1e4275 100644
--- a/devussy-web/streaming_server/app.py
+++ b/devussy-web/streaming_server/app.py
@@ -6,7 +6,11 @@
 starting point and will need additional validation and tests.
 """
 
+import time
 from fastapi import FastAPI, Request, Header, HTTPException
+import uuid
+from starlette.middleware.base import BaseHTTPMiddleware
+from .analytics import init_db, log_session, log_api_call, log_user_input, get_overview
 from fastapi.responses import StreamingResponse, JSONResponse
 import json
 import tempfile
@@ -25,6 +29,10 @@
 from src.pipeline.detailed_devplan import DetailedDevPlanGenerator
 from src.pipeline.handoff_prompt import HandoffPromptGenerator
 from src.pipeline.hivemind import HiveMindManager
+from src.pipeline.design_validator import DesignValidator
+from src.pipeline.design_correction_loop import DesignCorrectionLoop
+from src.pipeline.llm_sanity_reviewer import LLMSanityReviewer
+from src.interview.complexity_analyzer import ComplexityAnalyzer, ComplexityProfile
 from src.models import ProjectDesign, DevPlan
 from src.concurrency import ConcurrencyManager
 import os
@@ -43,6 +51,60 @@ def _validate_incoming_request(x_streaming_proxy_key: str | None) -> None:
 
 app = FastAPI()
 
+# Initialize analytics DB on startup
+@app.on_event("startup")
+async def startup_event():
+    init_db()
+
+# Middleware to log each request and response
+class AnalyticsMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        analytics_opt_out = request.cookies.get("devussy_analytics_optout")
+        if analytics_opt_out and analytics_opt_out.lower() in ("1", "true", "yes"):
+            return await call_next(request)
+        # Session handling: use cookie or generate new
+        session_id = request.cookies.get("devussy_session_id")
+        if not session_id:
+            session_id = str(uuid.uuid4())
+        # Attach session to request state so route handlers can reuse it
+        request.state.session_id = session_id
+        # Log session (IP hashing)
+        client_ip = request.client.host if request.client else "0.0.0.0"
+        user_agent = request.headers.get("user-agent")
+        log_session(session_id, client_ip, user_agent)
+        # Record request details
+        start = time.time()
+        request_body = await request.body()
+        request_size = len(request_body)
+        # Process request
+        response = await call_next(request)
+        # Record response details (duration until response object is ready)
+        duration_ms = (time.time() - start) * 1000
+        # Try to infer response size from Content-Length header if present
+        content_length = response.headers.get("content-length")
+        try:
+            response_size = int(content_length) if content_length is not None else 0
+        except ValueError:
+            response_size = 0
+        # Determine model used from response header if provided
+        model_used = response.headers.get("x-model-used")
+        # Log API call
+        log_api_call(
+            session_id=session_id,
+            endpoint=str(request.url.path),
+            method=request.method,
+            status_code=response.status_code,
+            duration_ms=duration_ms,
+            request_size=request_size,
+            response_size=response_size,
+            model_used=model_used,
+        )
+        # Set session cookie in response
+        response.set_cookie(key="devussy_session_id", value=session_id, httponly=True, samesite="lax")
+        return response
+
+app.add_middleware(AnalyticsMiddleware)
+
 @app.post("/api/design/stream")
 async def design_stream(request: Request, x_streaming_proxy_key: str | None = Header(None)):
     _validate_incoming_request(x_streaming_proxy_key)
@@ -51,6 +113,21 @@ async def design_stream(request: Request, x_streaming_proxy_key: str | None = He
     project_name = body.get("projectName") or body.get("project_name") or "Unnamed"
     languages = body.get("languages", [])
     requirements = body.get("requirements") or body.get("description", "")
+    # Log user input for analytics
+    analytics_opt_out = request.cookies.get("devussy_analytics_optout")
+    if not (analytics_opt_out and analytics_opt_out.lower() in ("1", "true", "yes")):
+        session_id = getattr(
+            request.state,
+            "session_id",
+            request.cookies.get("devussy_session_id") or "unknown",
+        )
+        log_user_input(
+            session_id=session_id,
+            input_type="design_input",
+            project_name=project_name,
+            requirements=requirements,
+            languages=languages,
+        )
 
     # Load config
     config = load_config()
@@ -142,6 +219,11 @@ async def design_stream_alias(request: Request, x_streaming_proxy_key: str | Non
     _validate_incoming_request(x_streaming_proxy_key)
     return await design_stream(request, x_streaming_proxy_key)
 
+# Analytics overview endpoint
+@app.get("/api/analytics/overview")
+async def analytics_overview():
+    return get_overview()
+
 @app.post("/api/design/hivemind")
 async def design_hivemind(request: Request):
     _validate_incoming_request(request.headers.get('x-streaming-proxy-key'))
@@ -689,3 +771,245 @@ async def get_models():
         raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
+
+
+# =============================================================================
+# Adaptive Pipeline Endpoints
+# =============================================================================
+
+
+@app.post("/api/adaptive/complexity")
+async def complexity_analysis(request: Request):
+    """
+    Analyze project complexity from interview data.
+    Returns SSE stream with complexity profile.
+    
+    Input:
+    {
+        "interview_data": {
+            "project_type": "...",
+            "requirements": "...",
+            "team_size": "...",
+            "apis": [...],
+            "frameworks": "..."
+        }
+    }
+    """
+    data = await request.json()
+    interview_data = data.get('interview_data', {})
+
+    async def event_generator():
+        try:
+            # Send start event
+            yield f"data: {json.dumps({'type': 'analyzing', 'message': 'Starting complexity analysis...'})}\n\n"
+
+            # Run complexity analysis
+            analyzer = ComplexityAnalyzer()
+            profile = analyzer.analyze(interview_data)
+
+            # Send progress update
+            yield f"data: {json.dumps({'type': 'progress', 'message': f'Computed score: {profile.score:.1f}, depth: {profile.depth_level}'})}\n\n"
+
+            # Prepare result
+            result = {
+                "project_type_bucket": profile.project_type_bucket,
+                "technical_complexity_bucket": profile.technical_complexity_bucket,
+                "integration_bucket": profile.integration_bucket,
+                "team_size_bucket": profile.team_size_bucket,
+                "score": profile.score,
+                "estimated_phase_count": profile.estimated_phase_count,
+                "depth_level": profile.depth_level,
+                "confidence": profile.confidence
+            }
+
+            # Check if follow-up questions are needed (low confidence)
+            follow_up_questions = []
+            if profile.confidence < 0.7:
+                follow_up_questions = _generate_follow_up_questions(profile, interview_data)
+
+            # Send final result
+            yield f"data: {json.dumps({'type': 'result', 'profile': result, 'follow_up_questions': follow_up_questions, 'needs_clarification': len(follow_up_questions) > 0})}\n\n"
+            yield f"data: {json.dumps({'type': 'done', 'success': True})}\n\n"
+
+        except Exception as e:
+            yield f"data: {json.dumps({'type': 'error', 'message': str(e)})}\n\n"
+
+    return StreamingResponse(event_generator(), media_type='text/event-stream')
+
+
+def _generate_follow_up_questions(profile: ComplexityProfile, interview_data: dict) -> list:
+    """Generate follow-up questions based on low-confidence areas."""
+    questions = []
+
+    if not interview_data.get('team_size'):
+        questions.append("What is the expected team size for this project?")
+
+    if not interview_data.get('apis') and profile.score > 5:
+        questions.append("Will this project integrate with any external APIs or services?")
+
+    if profile.technical_complexity_bucket == "simple_crud" and profile.score > 7:
+        questions.append("Are there any advanced features like real-time updates, ML, or multi-region deployment?")
+
+    if not interview_data.get('frameworks'):
+        questions.append("What frameworks or libraries do you plan to use?")
+
+    return questions[:3]
+
+
+@app.post("/api/adaptive/validate")
+async def design_validation(request: Request):
+    """
+    Validate a design document against complexity profile.
+    Returns SSE stream with validation report.
+    
+    Input:
+    {
+        "design_content": "...",
+        "complexity_profile": {...}
+    }
+    """
+    data = await request.json()
+    design_content = data.get('design_content', '')
+    profile_data = data.get('complexity_profile', {})
+
+    async def event_generator():
+        try:
+            yield f"data: {json.dumps({'type': 'validating', 'message': 'Starting design validation...'})}\n\n"
+
+            # Build complexity profile from data
+            profile = ComplexityProfile(
+                project_type_bucket=profile_data.get('project_type_bucket', 'web_app'),
+                technical_complexity_bucket=profile_data.get('technical_complexity_bucket', 'simple_crud'),
+                integration_bucket=profile_data.get('integration_bucket', 'standalone'),
+                team_size_bucket=profile_data.get('team_size_bucket', 'solo'),
+                score=profile_data.get('score', 5.0),
+                estimated_phase_count=profile_data.get('estimated_phase_count', 5),
+                depth_level=profile_data.get('depth_level', 'standard'),
+                confidence=profile_data.get('confidence', 0.8)
+            )
+
+            # Run validation
+            validator = DesignValidator()
+            report = validator.validate(design_content, complexity_profile=profile)
+
+            # Send individual check results
+            for check_name, passed in report.checks.items():
+                yield f"data: {json.dumps({'type': 'check', 'check': check_name, 'passed': passed})}\n\n"
+
+            # Build issues list
+            issues = [
+                {
+                    "code": issue.code,
+                    "message": issue.message,
+                    "auto_correctable": issue.auto_correctable
+                }
+                for issue in report.issues
+            ]
+
+            result = {
+                "is_valid": report.is_valid,
+                "auto_correctable": report.auto_correctable,
+                "checks": report.checks,
+                "issues": issues
+            }
+
+            # Run LLM sanity review if available
+            try:
+                reviewer = LLMSanityReviewer()
+                review_result = reviewer.review(design_content, report)
+                result["review"] = {
+                    "confidence": review_result.confidence,
+                    "risks": review_result.risks,
+                    "notes": review_result.notes
+                }
+            except Exception as review_error:
+                print(f"LLM review skipped: {review_error}")
+
+            yield f"data: {json.dumps({'type': 'result', **result})}\n\n"
+            yield f"data: {json.dumps({'type': 'done', 'success': True})}\n\n"
+
+        except Exception as e:
+            yield f"data: {json.dumps({'type': 'error', 'message': str(e)})}\n\n"
+
+    return StreamingResponse(event_generator(), media_type='text/event-stream')
+
+
+@app.post("/api/adaptive/correct")
+async def design_correction(request: Request):
+    """
+    Run the design correction loop.
+    Returns SSE stream with corrected design.
+    
+    Input:
+    {
+        "design_content": "...",
+        "max_iterations": 3
+    }
+    """
+    data = await request.json()
+    design_content = data.get('design_content', '')
+    max_iterations = data.get('max_iterations', 3)
+
+    async def event_generator():
+        try:
+            yield f"data: {json.dumps({'type': 'correcting', 'message': 'Starting design correction loop...', 'max_iterations': max_iterations})}\n\n"
+
+            # Create and run correction loop
+            correction_loop = DesignCorrectionLoop(max_iterations=max_iterations)
+            result = await correction_loop.run(design_content)
+
+            # Send result
+            history = [
+                {
+                    "iteration": h.iteration,
+                    "changes_made": h.changes_made,
+                    "issues_resolved": h.issues_resolved
+                }
+                for h in result.history
+            ]
+
+            yield f"data: {json.dumps({'type': 'result', 'final_design': result.final_design, 'iterations': result.iterations, 'converged': result.converged, 'history': history})}\n\n"
+            yield f"data: {json.dumps({'type': 'done', 'success': True})}\n\n"
+
+        except Exception as e:
+            yield f"data: {json.dumps({'type': 'error', 'message': str(e)})}\n\n"
+
+    return StreamingResponse(event_generator(), media_type='text/event-stream')
+
+
+@app.get("/api/adaptive/profile")
+async def get_complexity_profile(request: Request):
+    """
+    Synchronous endpoint to get complexity profile (non-streaming).
+    Useful for quick lookups or when SSE is not needed.
+    
+    Query params: project_type, requirements, team_size, apis, frameworks
+    """
+    params = dict(request.query_params)
+    
+    interview_data = {
+        "project_type": params.get("project_type", ""),
+        "requirements": params.get("requirements", ""),
+        "team_size": params.get("team_size", ""),
+        "apis": params.get("apis", "").split(",") if params.get("apis") else [],
+        "frameworks": params.get("frameworks", ""),
+    }
+
+    try:
+        analyzer = ComplexityAnalyzer()
+        profile = analyzer.analyze(interview_data)
+
+        result = {
+            "project_type_bucket": profile.project_type_bucket,
+            "technical_complexity_bucket": profile.technical_complexity_bucket,
+            "integration_bucket": profile.integration_bucket,
+            "team_size_bucket": profile.team_size_bucket,
+            "score": profile.score,
+            "estimated_phase_count": profile.estimated_phase_count,
+            "depth_level": profile.depth_level,
+            "confidence": profile.confidence
+        }
+
+        return JSONResponse(status_code=200, content=result)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
diff --git a/handoff.md b/handoff.md
new file mode 100644
index 0000000..412ee17
--- /dev/null
+++ b/handoff.md
@@ -0,0 +1,1165 @@
+ """# Devussy Adaptive Pipeline - Circular Development Handoff
+
+**Date:** 2025-11-25  
+**From:** Design & Planning Agent  
+**To:** Implementation Agent  
+**Project:** Devussy Adaptive Complexity Overhaul v2.0  
+
+---
+
+## 🔗 CRITICAL: Anchor-Based Context Management
+
+> **⚠️ THIS IS THE MOST IMPORTANT SECTION OF THIS DOCUMENT.**
+> 
+> Devussy uses **stable HTML comment anchors** to enable efficient circular development. 
+> **All agents MUST use anchors** to minimize context loading and enable safe file updates.
+
+### Why Anchors Matter
+
+1. **Token Economy:** Reading full files wastes context budget. Anchored sections are ~100 tokens vs 3000+ for full files.
+2. **Safe Updates:** `file_manager.py` validates anchor presence before writes - prevents accidental data loss.
+3. **Circular Handoffs:** Each agent reads only what's needed, updates only the anchored sections, passes baton cleanly.
+4. **Deterministic Updates:** Anchors provide stable targets for regex-based updates.
+
+### Required Anchor Patterns
+
+All devplan/phase/handoff files MUST preserve these HTML comment anchors:
+
+```markdown
+<!-- SECTION_NAME_START -->
+content that can be safely replaced
+<!-- SECTION_NAME_END -->
+```
+
+**Core Anchors by File:**
+
+| File | Anchor | Purpose |
+|------|--------|---------|
+| devplan.md | `PROGRESS_LOG_START/END` | Track completed work |
+| devplan.md | `NEXT_TASK_GROUP_START/END` | Current tasks to execute |
+| phase*.md | `PHASE_TASKS_START/END` | Phase-specific tasks |
+| phase*.md | `PHASE_PROGRESS_START/END` | Outcomes and blockers |
+| handoff_prompt.md | `QUICK_STATUS_START/END` | Status snapshot |
+| handoff_prompt.md | `HANDOFF_NOTES_START/END` | Agent handoff notes |
+
+### How to Use Anchors (Required Reading for All Agents)
+
+**Reading Context:**
+```
+# CORRECT - Read only anchored section (~100 tokens)
+Read devplan.md lines between <!-- NEXT_TASK_GROUP_START --> and <!-- NEXT_TASK_GROUP_END -->
+
+# WRONG - Loads entire file (~3000 tokens)
+Read devplan.md
+```
+
+**Updating Files:**
+```python
+# The safe_write_devplan() function in src/file_manager.py:
+# 1. Creates .bak backup before any write
+# 2. Validates required anchors exist in new content
+# 3. Refuses to overwrite if anchors missing (writes to .tmp instead)
+
+from src.file_manager import FileManager
+fm = FileManager()
+success, path = fm.safe_write_devplan("docs/devplan.md", new_content)
+if not success:
+    # Content was written to .tmp - anchors were missing!
+    logger.error(f"Devplan write failed - check {path}")
+```
+
+**Adding New Anchors:**
+When creating new document types, follow the pattern:
+```markdown
+<!-- MY_SECTION_START -->
+This content can be replaced by agents
+<!-- MY_SECTION_END -->
+```
+
+### Token Budget Per Turn
+
+| File | Section | ~Tokens | When to Read |
+|------|---------|---------|--------------|
+| handoff.md | Progress Log | ~200 | Start of session |
+| devplan.md | NEXT_TASK_GROUP | ~100 | Every turn |
+| devplan.md | PROGRESS_LOG | ~100 | If needed |
+| phase*.md | PHASE_TASKS | ~80 | When working on phase |
+
+**Target: Stay under 500 tokens per turn by reading ONLY anchored sections.**
+
+### Validation Enforcement
+
+The `file_manager.py:_validate_devplan_content()` function enforces these invariants:
+- Must contain `# Development Plan` or `## 📋 Project Dashboard` header
+- Must contain `### 🚀 Phase Overview` with a table
+- Must contain `<!-- PROGRESS_LOG_START -->` anchor
+- Must contain `<!-- NEXT_TASK_GROUP_START -->` anchor
+
+Files failing validation are written to `.tmp` and the original is preserved.
+
+---
+
+## 🎯 Mission Statement
+
+Transform Devussy into an adaptive, complexity-aware development planning pipeline that dynamically scales output based on project complexity, validates designs through multi-stage checks, and prevents over-engineering through intelligent iteration.
+
+**Core Improvement:** Replace static pipeline with adaptive complexity assessment → validation loops → scaled output generation.
+
+---
+
+## 📋 What You're Receiving
+
+### Primary Artifacts
+1. **devplan.md** - Complete 2-phase implementation plan
+2. **handoff.md** - This document (circular development guide)
+
+### Context Already Established
+- Current Devussy architecture (see GitHub repo)
+- Problem analysis (static complexity, no validation, no reasoning)
+- Solution approach (multi-stage interview, validation, adaptive scaling)
+- Success metrics and testing requirements
+
+---
+
+## 🎯 Your Primary Objectives
+
+### Phase 1: Backend Workflow Overhaul (PRIORITY)
+
+**Goal:** Build the adaptive complexity engine and validation system.
+
+**What to build:**
+
+1. **Complexity Analyzer Module** (`src/interview/complexity_analyzer.py`)
+   - Analyze interview JSON → complexity score (0-20)
+   - Estimate phase count (3-15 phases)
+   - Determine depth level (minimal/standard/detailed)
+   - Calculate confidence score
+   - Generate follow-up questions if needed
+
+2. **Interview Enhancement** (`src/interview/llm_interview_manager.py` modifications)
+   - Add `follow_up` mode to existing interview manager
+   - Implement clarification request flow
+   - Integrate with complexity analyzer
+
+3. **Design Validation System** (new modules)
+   - `src/pipeline/design_validator.py` - Rule-based validation checks
+   - `src/pipeline/llm_sanity_reviewer.py` - LLM semantic review
+   - `src/pipeline/design_correction_loop.py` - Iterative correction orchestrator
+
+4. **Adaptive Generators** (modify existing)
+   - `src/pipeline/design_generator.py` - Scale output by complexity
+   - `src/pipeline/devplan_generator.py` - Dynamic phase count and granularity
+
+5. **Pipeline Orchestration** (`src/pipeline/main_pipeline.py` refactor)
+   - Integrate all new stages
+   - Implement checkpoint system for new stages
+   - Add streaming support for validation/correction
+
+**Testing Requirements:**
+- 85%+ code coverage for all new modules
+- Unit tests for each validation check
+- Integration tests for full pipeline flows
+- E2E tests with real LLM at 3 complexity levels
+
+---
+
+### Phase 2: Frontend/UI Updates (AFTER Phase 1 Complete)
+
+**Goal:** Expose adaptive pipeline features through web UI.
+
+**What to build:**
+
+1. **New Screens/Components** (in `devussy-web/app/components/`)
+   - `ComplexityAssessment.tsx` - Visual complexity profile
+   - `DesignSanityCheck.tsx` - Validation results dashboard
+   - `IterativeApproval.tsx` - Approval gates UI
+   - `CorrectionTimeline.tsx` - Iteration history visualization
+
+2. **State Management Updates** (`devussy-web/app/state/`)
+   - Extend pipeline stages enum
+   - Add new data models (ComplexityProfile, ValidationReport, etc.)
+   - Implement state transitions with conditions
+
+3. **API Integration** (`devussy-web/app/api/`)
+   - New SSE endpoints for validation/correction
+   - Real-time streaming for correction loop
+   - Checkpoint loading for new stages
+
+4. **Enhanced Downloads**
+   - Include complexity profile, validation reports in ZIP
+   - Add iteration history
+   - Include prompts used
+
+**Testing Requirements:**
+- 80%+ component test coverage
+- E2E tests for all new user flows
+- Visual regression tests
+- Accessibility compliance (WCAG 2.1 AA)
+
+---
+
+## 🔑 Critical Implementation Details
+
+### Complexity Assessment: Mock vs LLM-Driven (IMPORTANT)
+
+> **⚠️ KEY DISTINCTION:** The static scoring rubric below is a **testing scaffold** for deterministic unit tests and mock pipelines. The **production system** should use **LLM-driven dynamic complexity assessment** based on actual project requirements and context.
+
+#### Production Behavior (LLM-Driven)
+
+When integrated with real LLM:
+1. **Prompt the LLM** with full interview transcript + extracted data
+2. **LLM analyzes** project scope, technical requirements, team context holistically
+3. **LLM outputs** structured `ComplexityProfile` JSON with:
+   - `complexity_score` (0-20 scale)
+   - `estimated_phase_count` (3-15 phases)
+   - `depth_level` ("minimal" | "standard" | "detailed")
+   - `confidence` (0-1)
+   - `rationale` (markdown explanation of reasoning)
+4. **Validation layer** compares LLM output against rubric fallback; if divergence > 1 point, flag for review
+
+```python
+# LLM Prompt Shape (production)
+"""
+You are analyzing a software project to determine its complexity.
+
+Project Data:
+- Type: {project_type}
+- Requirements: {requirements}
+- Frameworks: {frameworks}
+- Integrations: {apis}
+- Team Size: {team_size}
+
+Based on this information, provide a complexity assessment as JSON:
+{
+  "complexity_score": <0-20>,
+  "estimated_phase_count": <3-15>,
+  "depth_level": "minimal" | "standard" | "detailed",
+  "confidence": <0-1>,
+  "rationale": "<markdown explanation>",
+  "hidden_complexity_flags": ["<compliance>", "<data_sensitivity>", etc.],
+  "follow_up_questions": ["<if confidence < 0.7>"]
+}
+"""
+```
+
+#### Mock/Testing Behavior (Static Rubric)
+
+For deterministic testing and development, use this static fallback rubric:
+
+```python
+# Static complexity scoring (TESTING SCAFFOLD ONLY)
+# Use for unit tests, mock pipelines, and development
+
+project_type_score = {
+    'cli_tool': 1,
+    'library': 2,
+    'api': 3,
+    'web_app': 4,
+    'saas': 5
+}
+
+technical_complexity_score = {
+    'simple_crud': 1,
+    'auth_db': 2,
+    'realtime': 3,
+    'ml_ai': 4,
+    'multi_region': 5
+}
+
+integration_score = {
+    'standalone': 0,
+    '1_2_services': 1,
+    '3_5_services': 2,
+    '6_plus_services': 3
+}
+
+team_size_multiplier = {
+    'solo': 0.5,
+    '2_3': 1.0,
+    '4_6': 1.2,
+    '7_plus': 1.5
+}
+
+# Fallback formula (used when LLM unavailable or for validation)
+total_complexity = (project_type + technical + integration) * team_multiplier
+```
+
+### Phase Count Mapping
+
+```python
+def estimate_phase_count(complexity_score: float) -> int:
+    """
+    Maps complexity score to phase count.
+    In production: LLM determines this based on project context.
+    In testing: Use this deterministic mapping for consistency.
+    """
+    if complexity_score <= 3:
+        return 3  # minimal
+    elif complexity_score <= 7:
+        return 5  # standard
+    elif complexity_score <= 12:
+        return 7  # complex
+    else:
+        return min(9 + (complexity_score - 12) // 2, 15)  # enterprise (cap at 15)
+```
+
+### Validation Checks (ALL REQUIRED)
+
+These validation checks have both **rule-based** (deterministic) and **LLM-powered** (semantic) implementations:
+
+| Check | Rule-Based (Mock) | LLM-Powered (Production) |
+|-------|-------------------|--------------------------|
+| **Consistency** | Keyword matching, contradiction detection | Semantic analysis of design coherence |
+| **Completeness** | Checklist of required sections | LLM verifies all requirements addressed |
+| **Scope Alignment** | Score delta comparison | LLM evaluates if design matches complexity |
+| **Hallucination Detection** | Package registry lookup | LLM cross-references known ecosystems |
+| **Over-Engineering Detection** | Heuristic pattern matching | LLM judges appropriateness for scale |
+
+**Rule-Based (for testing):** Fast, deterministic, good for CI/CD
+**LLM-Powered (production):** Deeper semantic understanding, catches subtle issues
+
+### Correction Loop Logic (MAX 3 ITERATIONS)
+
+```python
+MAX_ITERATIONS = 3
+CONFIDENCE_THRESHOLD = 0.8
+
+for iteration in range(MAX_ITERATIONS):
+    validation = validate_design(design)
+    review = llm_review_design(design)
+    
+    if validation.is_valid and review.confidence > CONFIDENCE_THRESHOLD:
+        return design  # SUCCESS
+    
+    if not validation.auto_correctable:
+        return design, requires_human_review=True
+    
+    design = apply_corrections(design, validation, review)
+
+return design, max_iterations_reached=True
+```
+
+---
+
+## 📁 File Structure Reference
+
+### New Files to Create
+
+```
+src/
+├── interview/
+│   ├── complexity_analyzer.py (NEW)
+│   └── interview_pipeline.py (NEW)
+├── pipeline/
+│   ├── design_validator.py (NEW)
+│   ├── llm_sanity_reviewer.py (NEW)
+│   ├── design_correction_loop.py (NEW)
+│   └── output_formatter.py (NEW)
+
+schemas/
+├── complexity_profile.json (NEW)
+├── validation_report.json (NEW)
+├── review_result.json (NEW)
+└── final_design.json (NEW)
+
+templates/
+├── interview/
+│   └── follow_up_questions.jinja2 (NEW)
+├── design/
+│   └── adaptive_design.jinja2 (NEW)
+├── devplan/
+│   ├── adaptive_phases.jinja2 (NEW)
+│   ├── phase_minimal.jinja2 (NEW)
+│   ├── phase_standard.jinja2 (NEW)
+│   └── phase_detailed.jinja2 (NEW)
+└── validation/
+    └── sanity_review_prompt.jinja2 (NEW)
+
+tests/
+├── unit/
+│   ├── test_complexity_analyzer.py (NEW)
+│   ├── test_design_validator.py (NEW)
+│   ├── test_llm_sanity_reviewer.py (NEW)
+│   └── test_design_correction_loop.py (NEW)
+├── integration/
+│   ├── test_interview_to_complexity_flow.py (NEW)
+│   ├── test_adaptive_design_generation.py (NEW)
+│   ├── test_validation_and_correction.py (NEW)
+│   └── test_end_to_end_adaptive_pipeline.py (NEW)
+└── harness/
+    └── pipeline_test_harness.py (NEW)
+
+devussy-web/
+└── app/
+    ├── components/
+    │   ├── ComplexityAssessment.tsx (NEW)
+    │   ├── DesignSanityCheck.tsx (NEW)
+    │   ├── IterativeApproval.tsx (NEW)
+    │   ├── ComplexityGauge.tsx (NEW)
+    │   ├── PhaseCountEstimate.tsx (NEW)
+    │   ├── ValidationResults.tsx (NEW)
+    │   ├── CorrectionTimeline.tsx (NEW)
+    │   ├── ReasoningPanel.tsx (NEW)
+    │   ├── PromptInspector.tsx (NEW)
+    │   └── RefineButton.tsx (NEW)
+    ├── state/
+    │   └── pipelineState.ts (MODIFY)
+    └── api/
+        └── (new endpoints) (NEW)
+```
+
+### Files to Modify
+
+```
+src/
+├── interview/
+│   └── llm_interview_manager.py (ADD follow_up mode)
+├── pipeline/
+│   ├── design_generator.py (ADD complexity awareness)
+│   ├── devplan_generator.py (ADD adaptive phase count)
+│   ├── main_pipeline.py (REFACTOR for new flow)
+│   └── streaming.py (ADD new stage prefixes)
+
+devussy-web/
+└── app/
+    ├── components/
+    │   └── WindowManager.tsx (ADD new window types)
+    └── utils/
+        └── zipGenerator.ts (INCLUDE new artifacts)
+```
+
+---
+
+## 🚨 Critical Rules for Circular Development
+
+### 1. Context Management (KEEP IT SMALL)
+
+**DO:**
+- ✅ Read ONLY the files relevant to current task
+- ✅ Use anchors to reference prior context (see devplan.md sections)
+- ✅ Keep active context under 50k tokens
+- ✅ Rely on this handoff for high-level flow
+
+**DON'T:**
+- ❌ Re-read entire repository
+- ❌ Re-explain problem statement
+- ❌ Duplicate context already in devplan.md
+- ❌ Load all files "just in case"
+
+### 2. Iteration Protocol
+
+**When starting work:**
+1. Read this handoff.md
+2. Read relevant section of devplan.md
+3. Read ONLY files you'll modify
+4. Implement task
+5. Write tests
+6. Update handoff with progress
+
+**When passing baton:**
+1. Update handoff.md with:
+   - What you completed
+   - What's next
+   - Any blockers or decisions needed
+   - Files modified (list)
+2. Commit changes
+3. Next agent reads handoff, continues
+
+### 3. Testing Before Proceeding
+
+**After each milestone:**
+- Run unit tests → must pass
+- Run integration tests → must pass
+- Update test coverage report
+- Don't proceed if tests failing
+
+**After each phase:**
+- Run full test suite
+- Run E2E tests
+- Validate against success criteria
+- Generate test report
+
+### 4. Hallucination Prevention
+
+**When generating code that references external packages:**
+1. Cross-reference against known registries (npm, PyPI)
+2. Check import paths match real packages
+3. Validate API methods exist in documentation
+4. Flag uncertain references for human review
+
+**When generating designs:**
+1. Use only tech stacks mentioned in interview
+2. Don't invent framework names
+3. Keep dependencies minimal and verified
+4. Flag experimental or uncommon choices
+
+### 5. Deterministic Output
+
+**Always:**
+- Use consistent formatting (black, prettier)
+- Generate same output for same input
+- Preserve existing file structure
+- Follow existing code style
+- Use templates consistently
+
+**Never:**
+- Randomize output
+- Change unrelated code
+- Reformat entire files
+- Introduce style inconsistencies
+
+---
+## 📊 Progress Tracking
+
+### Phase 1 Checklist
+
+**Milestone 1: Complexity Analysis System**
+ - [x] `complexity_analyzer.py` implemented
+ - [x] `interview_pipeline.py` implemented
+ - [x] Follow-up mode added to `llm_interview.py` (FOLLOW_UP_SYSTEM_PROMPT, switch_mode, request_clarifications)
+ - [ ] Unit tests passing (30+ tests)
+ - [x] Integration test: interview → complexity flow
+
+**Milestone 2: Design Validation System**
+ - [x] `design_validator.py` implemented
+ - [x] `llm_sanity_reviewer.py` implemented
+ - [x] `design_correction_loop.py` implemented
+ - [x] All 5 validation checks working (rule-based, mock-first)
+ - [ ] Unit tests passing (60+ tests)
+ - [x] Integration test: validation → correction flow
+
+**Milestone 3: Adaptive Generators**
+- [x] `design_generator.py` implemented with complexity awareness (mock + template modes)
+- [x] `devplan_generator.py` implemented with dynamic phases (mock + template modes)
+- [x] Template variants created (minimal/standard/detailed) in `templates/devplan/`
+- [x] Adaptive design template created (`templates/design/adaptive_design.jinja2`)
+- [x] Follow-up questions template created (`templates/interview/follow_up_questions.jinja2`)
+- [x] Unit tests passing for adaptive generators
+- [x] Output scales correctly at 3 complexity levels (minimal/standard/detailed)
+
+**Milestone 4: Pipeline Integration**
+ - [x] Mock adaptive backend pipeline implemented (`mock_adaptive_pipeline.py`)
+ - [x] Integration tests: end-to-end mock adaptive pipeline
+ - [x] Pipeline test harness implemented for mock adaptive pipeline (`tests/harness/pipeline_test_harness.py`)
+ - [x] Main pipeline refactored to integrate new stages (`run_adaptive_pipeline` method in compose.py)
+ - [x] Checkpoint system extended for complexity_profile, validation_report, correction_history
+ - [x] Streaming support added ([complexity], [validation], [correction] prefixes)
+ - [x] JSON schemas created (schemas/complexity_profile.json, validation_report.json, review_result.json, correction_history.json)
+ - [ ] E2E tests passing (3 complexity levels with real LLM)
+ - [ ] Test coverage ≥ 85%
+
+### Phase 2 Checklist
+
+**Milestone 5: Core UI Components**
+- [x] `ComplexityAssessment.tsx` implemented
+- [x] `ValidationReport.tsx` implemented  
+- [x] `CorrectionTimeline.tsx` implemented
+- [x] Wired into DesignView with auto-analysis
+
+---
+
+## 📝 Progress Log
+
+### 2025-11-25 - Initial Planning Agent
+**Completed:**
+- Full devplan.md creation (Phase 1 + Phase 2)
+- This handoff.md for circular development
+- Problem analysis and solution design
+- Success criteria definition
+- Testing strategy
+
+**Next Steps:**
+- Implementation Agent: Start Phase 1, Milestone 1 (Complexity Analysis System)
+- Begin with `src/interview/complexity_analyzer.py`
+
+**Blockers/Decisions Needed:**
+- None - ready for implementation
+
+---
+
+### 2025-11-25 - Backend Mock Implementation Agent
+**Completed:**
+- Implemented `src/interview/complexity_analyzer.py` and unit tests
+- Implemented `src/interview/interview_pipeline.py` and integration test
+- Implemented `src/pipeline/design_validator.py`, `llm_sanity_reviewer.py`, `design_correction_loop.py`
+- Added unit tests for validation and correction loop
+- Implemented `src/pipeline/mock_adaptive_pipeline.py` and integration test for full mock adaptive flow
+- Created tracking docs: `adaptive_pipeline_progress.md`, `adaptive_pipeline_llm_ideas.md`
+
+**Files Modified:**
+- `src/interview/complexity_analyzer.py`
+- `src/interview/interview_pipeline.py`
+- `src/pipeline/design_validator.py`
+- `src/pipeline/llm_sanity_reviewer.py`
+- `src/pipeline/design_correction_loop.py`
+- `src/pipeline/mock_adaptive_pipeline.py`
+- `tests/unit/test_complexity_analyzer.py`
+- `tests/unit/test_design_validator.py`
+- `tests/unit/test_llm_sanity_reviewer.py`
+- `tests/unit/test_design_correction_loop.py`
+- `tests/integration/test_interview_to_complexity_flow.py`
+- `tests/integration/test_validation_and_correction.py`
+- `tests/integration/test_mock_adaptive_pipeline.py`
+- `adaptive_pipeline_progress.md`
+- `adaptive_pipeline_llm_ideas.md`
+
+**Tests:**
+ - Unit tests: complexity analyzer, validation, sanity reviewer, correction loop
+ - Integration tests: interview → complexity, validation → correction, mock adaptive pipeline
+ - Coverage: not yet measured for this slice
+
+**How to run tests for this phase:**
+
+- Run unit tests for new backend modules:
+  - `pytest tests/unit/test_complexity_analyzer.py -v`
+  - `pytest tests/unit/test_design_validator.py -v`
+  - `pytest tests/unit/test_llm_sanity_reviewer.py -v`
+  - `pytest tests/unit/test_design_correction_loop.py -v`
+- Run integration tests for adaptive backend flow:
+  - `pytest tests/integration/test_interview_to_complexity_flow.py -v`
+  - `pytest tests/integration/test_validation_and_correction.py -v`
+  - `pytest tests/integration/test_mock_adaptive_pipeline.py -v`
+- Optional: run full coverage for this repo slice:
+  - `pytest --cov=src --cov-report=html`
+
+**Next backend phases after this slice:**
+
+- Implement `follow_up` mode and clarification flow in `llm_interview_manager.py`.
+- Add complexity-aware behavior to `design_generator` / `devplan_generator` (mock-first, no real LLM calls).
+- Use `adaptive_pipeline_llm_ideas.md` to design prompts, schemas, and validation for real LLM integration.
+
+### 2025-11-25 - Adaptive Generators & Harness Agent
+**Completed:**
+- Implemented `src/pipeline/design_generator.py` (AdaptiveDesignGenerator, mock complexity-aware design).
+- Implemented `src/pipeline/devplan_generator.py` (AdaptiveDevPlanGenerator, dynamic phase structure).
+- Wired adaptive generators into `src/pipeline/mock_adaptive_pipeline.py`.
+- Updated `src/pipeline/design_correction_loop.py` to accept optional `ComplexityProfile` for validation.
+- Added unit tests `tests/unit/test_adaptive_design_generator.py` and `tests/unit/test_adaptive_devplan_generator.py`.
+- Implemented `tests/harness/pipeline_test_harness.py` and `tests/harness/test_pipeline_test_harness.py` for mock adaptive scenarios.
+
+**Files Modified/Added:**
+- `src/pipeline/design_generator.py`
+- `src/pipeline/devplan_generator.py`
+- `src/pipeline/mock_adaptive_pipeline.py`
+- `src/pipeline/design_correction_loop.py`
+- `tests/unit/test_adaptive_design_generator.py`
+- `tests/unit/test_adaptive_devplan_generator.py`
+- `tests/harness/pipeline_test_harness.py`
+- `tests/harness/test_pipeline_test_harness.py`
+
+**Recommended Tests:**
+- `pytest tests/unit/test_adaptive_design_generator.py -v`
+- `pytest tests/unit/test_adaptive_devplan_generator.py -v`
+- `pytest tests/harness/test_pipeline_test_harness.py -v`
+- `pytest tests/integration/test_mock_adaptive_pipeline.py -v`
+
+### 2025-11-25 - Documentation & LLM Strategy Agent
+**Completed:**
+- Clarified Mock vs LLM-Driven distinction throughout documentation
+- Updated `handoff.md`:
+  - Added "Mock vs LLM-Driven" section explaining static scoring is for testing
+  - Added LLM prompt template example for production complexity assessment
+  - Updated validation checks table showing rule-based vs LLM-powered approaches
+- Expanded `adaptive_pipeline_llm_ideas.md`:
+  - Added "Design Philosophy: Mock → LLM Transition" section
+  - Added detailed LLM prompt template for complexity analysis
+  - Added "Migration Strategy: Mock → LLM" phased roadmap
+  - Added "LLM Configuration Recommendations" with per-stage model settings
+  - Added "Testing Strategy for LLM Integration" with examples
+  - Added "Error Handling & Fallbacks" with `AdaptiveComplexityAnalyzer` pattern
+  - Added "Observability & Debugging" section
+- Updated `src/interview/complexity_analyzer.py`:
+  - Added comprehensive docstring explaining role as testing scaffold
+  - Documented production LLM behavior expectations
+- Fixed 2 failing unit tests:
+  - `test_estimate_phase_count_thresholds`: Updated to match formula (score 20 → 13 phases, not 15)
+  - `test_design_validator_scope_alignment_for_complex_project`: Fixed design text to not contain "scalability"
+
+**Files Modified:**
+- `handoff.md`
+- `adaptive_pipeline_llm_ideas.md`
+- `src/interview/complexity_analyzer.py`
+- `tests/unit/test_complexity_analyzer.py`
+- `tests/unit/test_design_validator.py`
+
+**Tests:**
+- All 7 adaptive pipeline unit tests passing
+- Run: `.\.venv\Scripts\python.exe -m pytest tests/unit/test_complexity_analyzer.py tests/unit/test_design_validator.py -v`
+
+**Key Insight Documented:**
+> The static complexity scoring rubric (cli_tool=1, library=2, etc.) is a **testing scaffold** for deterministic unit tests. The **production system** should use **LLM-driven dynamic assessment** that analyzes full project context holistically rather than keyword matching into fixed buckets.
+
+---
+
+### 2025-11-25 - Template & Interview Integration Agent
+**Completed:**
+- Implemented `follow_up` mode in `src/llm_interview.py` with:
+  - `FOLLOW_UP_SYSTEM_PROMPT` for clarification questions
+  - `switch_mode()` method to change between initial/design_review/follow_up modes
+  - `set_follow_up_context()` for setting clarification questions and complexity profile
+  - `request_clarifications()` for generating follow-up prompts
+- Created all template variants in `templates/`:
+  - `templates/interview/follow_up_questions.jinja2` - Follow-up question prompts
+  - `templates/design/adaptive_design.jinja2` - Complexity-aware design template
+  - `templates/devplan/phase_minimal.jinja2` - Minimal phase template
+  - `templates/devplan/phase_standard.jinja2` - Standard phase template
+  - `templates/devplan/phase_detailed.jinja2` - Detailed phase template
+- Wired templates into generators:
+  - `design_generator.py` - `use_templates` flag, `_generate_from_template()` method
+  - `devplan_generator.py` - `use_templates` flag, `render_phase_markdown()` method
+
+**Files Modified/Added:**
+- `src/llm_interview.py` (follow_up mode additions)
+- `templates/interview/follow_up_questions.jinja2` (new)
+- `templates/design/adaptive_design.jinja2` (new)
+- `templates/devplan/phase_minimal.jinja2` (new)
+- `templates/devplan/phase_standard.jinja2` (new)
+- `templates/devplan/phase_detailed.jinja2` (new)
+- `src/pipeline/design_generator.py` (template integration)
+- `src/pipeline/devplan_generator.py` (template integration)
+
+**Next Steps (Priority Order):**
+1. **Refactor main pipeline** - Integrate complexity → validation → correction flow
+2. **Extend checkpoint system** - Add complexity_profile, validation_report, correction_history
+3. **Add streaming prefixes** - [complexity], [validation], [correction] in streaming.py
+4. **Create JSON schemas** - schemas/complexity_profile.json, validation_report.json, etc.
+5. **Add unit tests** - Test follow-up mode, template selection, streaming updates
+
+**Blockers/Decisions Needed:**
+- None - ready to proceed with main pipeline refactor
+
+---
+
+### 2025-11-25 - Pipeline Integration Agent
+**Completed:**
+- Refactored main pipeline to integrate adaptive complexity flow:
+  - Added `analyze_complexity()` method to PipelineOrchestrator
+  - Added `validate_design()` method for rule-based validation
+  - Added `review_design_with_llm()` method for semantic review
+  - Added `run_correction_loop()` method for iterative design correction
+  - Added `run_adaptive_pipeline()` async method for full adaptive flow
+- Extended checkpoint system with new stages:
+  - `complexity_analysis` stage with ComplexityProfile data
+  - `project_design` stage includes validation_report and correction_result
+- Added streaming prefixes for adaptive pipeline stages:
+  - `[complexity]`, `[validation]`, `[correction]`, `[follow_up]`
+  - New `create_stage_handler()` factory method in StreamingHandler
+- Created JSON schemas:
+  - `schemas/complexity_profile.json`
+  - `schemas/validation_report.json`
+  - `schemas/review_result.json`
+  - `schemas/correction_history.json`
+- Added comprehensive tests:
+  - 6 new streaming prefix unit tests
+  - 10 new adaptive pipeline orchestrator integration tests
+  - All 25 adaptive pipeline tests passing
+
+**Files Modified/Added:**
+- `src/pipeline/compose.py` (added adaptive pipeline methods)
+- `src/streaming.py` (added STREAMING_PREFIXES, StreamingStage, create_stage_handler)
+- `schemas/complexity_profile.json` (new)
+- `schemas/validation_report.json` (new)
+- `schemas/review_result.json` (new)
+- `schemas/correction_history.json` (new)
+- `tests/unit/test_streaming.py` (added TestStreamingPrefixes)
+- `tests/integration/test_adaptive_pipeline_orchestrator.py` (new)
+
+**How to run tests for this phase:**
+```bash
+pytest tests/unit/test_streaming.py::TestStreamingPrefixes -v
+pytest tests/integration/test_adaptive_pipeline_orchestrator.py -v
+pytest tests/unit/test_complexity_analyzer.py tests/unit/test_design_validator.py -v
+```
+
+**Next Steps (Priority Order):**
+1. ✅ **Add CLI command for adaptive pipeline** - DONE: `run-adaptive-pipeline` command in `src/cli.py`
+2. ✅ **E2E tests with real LLM** - DONE: 8 tests in `tests/integration/test_adaptive_pipeline_e2e.py`
+3. ✅ **Increase test coverage** - DONE: 87% coverage on core adaptive modules
+4. **Frontend work** - Start Phase 2 with ComplexityAssessment.tsx component
+5. **Wire frontend to adaptive endpoints** - Create SSE endpoints for complexity/validation stages
+
+**Blockers/Decisions Needed:**
+- None - Backend adaptive pipeline complete, ready for frontend integration
+
+---
+
+### Milestone 5: CLI & E2E Testing (2025-11-26) ✅
+
+**What was done:**
+
+1. **Added `run-adaptive-pipeline` CLI command** (`src/cli.py`):
+   - Full adaptive pipeline with complexity analysis, validation, correction loop
+   - Supports `--interview-file` for JSON input or uses CLI args for complexity analysis
+   - Options: `--validation/--no-validation`, `--correction/--no-correction`
+   - Displays complexity profile summary after completion
+   - Example: `devussy run-adaptive-pipeline --name "myapp" --languages "Python" --requirements "Build REST API"`
+
+2. **Created comprehensive E2E tests** (`tests/integration/test_adaptive_pipeline_e2e.py`):
+   - `TestAdaptivePipelineMinimalComplexity`: CLI tools, simple scripts (score ≤3)
+   - `TestAdaptivePipelineStandardComplexity`: APIs, web apps (score 4-7)
+   - `TestAdaptivePipelineDetailedComplexity`: SaaS, enterprise (score ≥8)
+   - `TestAdaptivePipelineValidationCorrection`: Correction loop invocation
+   - `TestAdaptivePipelineArtifacts`: Artifact generation verification
+   - 8 passing tests, 3 skipped (real LLM tests marked with `@pytest.mark.requires_api`)
+
+3. **Achieved 87% test coverage** on core adaptive pipeline modules:
+   - `complexity_analyzer.py`: 89%
+   - `design_validator.py`: 96%
+   - `design_correction_loop.py`: 68%
+
+**Files modified:**
+- `src/cli.py` - Added ~230 lines for `run_adaptive_pipeline` command
+- `tests/integration/test_adaptive_pipeline_e2e.py` - New file, ~640 lines
+
+**How to run:**
+```bash
+# CLI help
+python -m src.cli run-adaptive-pipeline --help
+
+# Run adaptive pipeline
+python -m src.cli run-adaptive-pipeline --name "myapp" --languages "Python,TypeScript" \
+    --requirements "Build a REST API with auth" --validation --correction
+
+# Run E2E tests
+pytest tests/integration/test_adaptive_pipeline_e2e.py -v
+
+# Check coverage
+pytest tests/integration/test_adaptive_pipeline_e2e.py tests/integration/test_adaptive_pipeline_orchestrator.py \
+    --cov=src.interview.complexity_analyzer --cov=src.pipeline.design_validator \
+    --cov=src.pipeline.design_correction_loop --cov-report=term-missing
+```
+
+**Next Steps (Priority Order):**
+1. ✅ **Start Frontend Phase 2** - DONE: `ComplexityAssessment.tsx` component created
+2. ✅ **Wire frontend to adaptive endpoints** - DONE: FastAPI SSE endpoints in `streaming_server/app.py`
+3. ✅ **Add real LLM E2E tests** - DONE: 3 passing tests in `TestAdaptivePipelineRealLLM`
+
+---
+
+### Milestone 6: Frontend Components & API Integration (2025-11-26) ✅
+
+**What was done:**
+
+1. **Created `ComplexityAssessment.tsx` component** (`devussy-web/src/components/pipeline/`):
+   - Visual score gauge (SVG circle with animated progress)
+   - Depth level indicator with color coding (minimal=green, standard=blue, detailed=purple)
+   - Estimated phase count display
+   - Confidence meter with icon indicators
+   - Detailed breakdown grid showing all complexity factors
+   - `ComplexityBadge` compact variant for embedding in other views
+   - Full TypeScript types matching backend `ComplexityProfile`
+
+2. **Added FastAPI adaptive pipeline endpoints** (`devussy-web/streaming_server/app.py`):
+   - `POST /api/adaptive/complexity` - SSE stream for complexity analysis
+   - `POST /api/adaptive/validate` - SSE stream for design validation with LLM sanity review
+   - `POST /api/adaptive/correct` - SSE stream for correction loop execution
+   - `GET /api/adaptive/profile` - Quick synchronous profile lookup (non-streaming)
+   - All endpoints return proper SSE format with typed events
+
+3. **Implemented real LLM E2E tests** (`tests/integration/test_adaptive_pipeline_e2e.py`):
+   - `TestAdaptivePipelineRealLLM` class with 3 passing tests
+   - `test_real_minimal_pipeline` - CLI tools (verifies score ≤4, depth=minimal)
+   - `test_real_standard_pipeline` - APIs/web apps (verifies score 4-12, depth=standard/detailed)
+   - `test_real_detailed_pipeline` - SaaS/enterprise (verifies score ≥8, depth=detailed)
+   - Proper env var handling for provider configuration
+
+**Files created/modified:**
+- `devussy-web/src/components/pipeline/ComplexityAssessment.tsx` - New, ~280 lines
+- `devussy-web/streaming_server/app.py` - Added ~180 lines for adaptive endpoints
+- `tests/integration/test_adaptive_pipeline_e2e.py` - Modified, added real LLM test implementations
+
+**How to run:**
+```bash
+# Run real LLM E2E tests
+LLM_PROVIDER=requesty pytest tests/integration/test_adaptive_pipeline_e2e.py::TestAdaptivePipelineRealLLM -v
+
+# Test adaptive endpoints (requires streaming server running)
+curl -X POST http://localhost:8000/api/adaptive/complexity \
+  -H "Content-Type: application/json" \
+  -d '{"interview_data": {"project_type": "cli_tool", "requirements": "simple script", "team_size": "1"}}'
+
+# Get profile synchronously
+curl "http://localhost:8000/api/adaptive/profile?project_type=web_app&requirements=REST+API&team_size=3"
+```
+
+---
+
+### Milestone 7: Frontend Component Wiring (2025-11-26) ✅
+
+**What was done:**
+
+1. **Wired ComplexityAssessment into DesignView** (`devussy-web/src/components/pipeline/DesignView.tsx`):
+   - Added `enableAdaptive` prop (default: true) to enable/disable complexity analysis
+   - Auto-analyzes complexity on component mount before design generation
+   - Shows ComplexityAssessment panel at top of design view with collapsible UI
+   - ComplexityBadge shown in header when panel collapsed
+   - Complexity profile passed through to design data on approval
+   - Helper functions to infer project type and integrations from requirements text
+
+2. **Created ValidationReport component** (`devussy-web/src/components/pipeline/ValidationReport.tsx`):
+   - Full validation issue display with severity indicators (error/warning/info)
+   - Check-specific icons (consistency, completeness, scope alignment, hallucination, over-engineering)
+   - Auto-correctable issue badges with wrench icon
+   - LLM sanity review section with confidence meter and suggestions
+   - ValidationBadge compact variant for embedding
+   - onRequestCorrection callback for triggering auto-correction
+
+3. **Created CorrectionTimeline component** (`devussy-web/src/components/pipeline/CorrectionTimeline.tsx`):
+   - Visual timeline with iteration nodes and connector lines
+   - Real-time progress bar showing iterations vs max
+   - Per-iteration details: issues addressed, corrections applied, validation result
+   - Duration and confidence display per iteration
+   - Status indicators (success, max iterations reached, manual review required)
+   - Summary stats: total iterations, corrections count, final confidence
+   - CorrectionBadge compact variant for embedding
+
+**Files created/modified:**
+- `devussy-web/src/components/pipeline/DesignView.tsx` - Modified, added complexity integration (~100 lines)
+- `devussy-web/src/components/pipeline/ValidationReport.tsx` - New, ~340 lines
+- `devussy-web/src/components/pipeline/CorrectionTimeline.tsx` - New, ~320 lines
+
+**Component API:**
+```tsx
+// ComplexityAssessment (already existed)
+<ComplexityAssessment profile={complexityProfile} showDetails={true} onRefresh={() => {}} />
+
+// ValidationReport
+<ValidationReport 
+  report={validationReport} 
+  sanityReview={sanityReviewResult}
+  onRequestCorrection={() => triggerCorrection()}
+  showDetails={true}
+/>
+
+// CorrectionTimeline
+<CorrectionTimeline 
+  history={correctionHistory}
+  isRunning={isCorrectingDesign}
+  currentIteration={currentIteration}
+  showDetails={true}
+/>
+```
+
+**Next Steps (Priority Order):**
+1. ✅ **Wire ValidationReport into design approval flow** - DONE
+2. ✅ **Wire CorrectionTimeline into correction loop UI** - DONE
+3. ✅ **Update frontend state management** - DONE: Added complexity/validation/correction stages
+4. **Add frontend tests** - React Testing Library for new components
+5. **Add visual regression tests** - Percy/Chromatic for component snapshots
+6. **Documentation updates** - Update README with adaptive pipeline features
+
+---
+
+### 2025-11-26 - Frontend Integration Agent
+**Completed:**
+- Wired ValidationReport into DesignView design approval flow:
+  - Added validation state (report, sanity review, isValidating)
+  - Added correction state (history, isCorrecting, currentIteration)
+  - Auto-trigger validation via `validateDesign()` after design generation
+  - Show ValidationReport panel after ComplexityAssessment
+  - Show CorrectionTimeline during/after correction loop
+  - Added `runCorrectionLoop()` to trigger auto-correction via API
+- Updated approval flow logic:
+  - Block auto-advance when validation has issues
+  - Show "Approve Anyway" button for manual override
+  - Pass full metadata (complexity, validation, sanity, corrections) to onDesignComplete
+- Added UI controls:
+  - Show/hide toggles for complexity, validation, correction panels
+  - Badges in header when panels collapsed (ValidationBadge, CorrectionBadge)
+  - Disable regenerate during validation/correction
+- Updated PipelineStage type with new adaptive stages:
+  - Added `complexity`, `validation`, `correction` stages
+  - Added icons (Gauge, Shield, History) and labels for new stages
+
+**Files Modified:**
+- `devussy-web/src/components/pipeline/DesignView.tsx` - Added ~200 lines for validation/correction integration
+- `devussy-web/src/components/pipeline/ModelSettings.tsx` - Added 3 new stages to PipelineStage type
+
+**How to verify:**
+```bash
+# Run frontend dev server
+cd devussy-web && npm run dev
+
+# In browser:
+# 1. Open design view with enableAdaptive=true (default)
+# 2. Complexity analysis runs first
+# 3. Design generation streams
+# 4. Validation runs automatically after design completes
+# 5. ValidationReport shows issues (if any) with Auto-correct button
+# 6. Click Auto-correct to run correction loop
+# 7. CorrectionTimeline shows iteration progress
+# 8. Approve (or Approve Anyway) to proceed
+```
+
+---
+
+### 2025-11-26 - Frontend Testing & Documentation Agent
+**Completed:**
+- Set up Jest + React Testing Library for frontend component tests:
+  - Added `jest.config.js` and `jest.setup.js` configuration
+  - Installed testing dependencies (@testing-library/react, jest, jest-environment-jsdom)
+- Created comprehensive test suites (72 tests total, all passing):
+  - `ComplexityAssessment.test.tsx` - 22 tests covering rendering, depth levels, confidence, loading, refresh
+  - `ValidationReport.test.tsx` - 29 tests covering valid/invalid reports, severity, auto-correct, sanity review
+  - `CorrectionTimeline.test.tsx` - 21 tests covering iterations, progress, status, badges
+- Set up Storybook for visual regression testing:
+  - Initialized Storybook 10.0.8 with Next.js adapter
+  - Added Chromatic for visual regression snapshots
+  - Created stories for all 3 adaptive pipeline components
+- Added Storybook stories for component variants:
+  - `ComplexityAssessment.stories.tsx` - Minimal, Standard, Detailed, Loading, LowConfidence variants
+  - `ValidationReport.stories.tsx` - Valid, Invalid, Severe, WithSanityReview variants
+  - `CorrectionTimeline.stories.tsx` - Success, MaxIterations, ManualReview, InProgress variants
+- Updated README with Adaptive Pipeline documentation:
+  - Added "Adaptive Complexity Pipeline" section to Complete Feature List
+  - Documented complexity analysis, validation, correction loop features
+  - Added CLI usage examples and test commands
+
+**Files Created:**
+- `devussy-web/jest.config.js`
+- `devussy-web/jest.setup.js`
+- `devussy-web/src/components/pipeline/__tests__/ComplexityAssessment.test.tsx`
+- `devussy-web/src/components/pipeline/__tests__/ValidationReport.test.tsx`
+- `devussy-web/src/components/pipeline/__tests__/CorrectionTimeline.test.tsx`
+- `devussy-web/src/components/pipeline/ComplexityAssessment.stories.tsx`
+- `devussy-web/src/components/pipeline/ValidationReport.stories.tsx`
+- `devussy-web/src/components/pipeline/CorrectionTimeline.stories.tsx`
+
+**Files Modified:**
+- `devussy-web/package.json` - Added test scripts (test, test:watch, test:coverage, chromatic)
+- `README.md` - Added Adaptive Pipeline documentation section
+
+**How to run tests:**
+```bash
+# Run all frontend component tests (72 tests)
+cd devussy-web && npm test
+
+# Run with coverage
+cd devussy-web && npm run test:coverage
+
+# Run Storybook for visual testing
+cd devussy-web && npm run storybook
+
+# Build Storybook for production
+cd devussy-web && npm run build-storybook
+```
+
+**Phase 2 Completion Status:**
+- [x] Core UI Components (ComplexityAssessment, ValidationReport, CorrectionTimeline)
+- [x] Wired components into DesignView pipeline flow
+- [x] Frontend state management updated with new stages
+- [x] React Testing Library tests (72 tests passing)
+- [x] Storybook stories for visual regression
+- [x] Documentation updates (README)
+
+**Remaining items (nice-to-have):**
+- Playwright E2E tests for full user flows
+- Percy/Chromatic CI integration (requires API keys)
+- Additional component tests for DesignView integration
+
+---
+
+### For Frontend Work
+
+**Reuse existing:**
+- Tailwind config and design tokens
+- Shadcn UI components
+- Window management patterns
+- Streaming handlers
+
+**State management:**
+- Use Zustand for global state
+- Add new pipeline stages to enum
+- Implement conditional transitions
+- Persist state in checkpoints
+
+**Testing approach:**
+- React Testing Library for component tests
+- Mock API responses with MSW
+- Playwright for E2E tests
+- Percy/Chromatic for visual regression
+
+---
+
+## 🚀 Quick Start Commands
+
+### Backend Development
+
+```bash
+# Setup
+cd devussy
+python -m venv venv
+source venv/bin/activate  # or venv\\Scripts\\activate on Windows
+pip install -e .
+
+# Run tests
+pytest tests/unit/test_complexity_analyzer.py -v
+pytest tests/integration/ -v
+pytest tests/ --cov=src --cov-report=html
+
+# Run pipeline
+python -m src.cli interactive
+```
+
+### Frontend Development
+
+```bash
+# Setup
+cd devussy-web
+npm install
+
+# Run dev server (backend must be running)
+npm run dev
+
+# Run tests
+npm test
+npm run test:e2e
+npm run test:visual
+```
+
+---
+
+## 📚 Reference Materials
+
+### Key Documentation
+- **Current Devussy README:** https://github.com/mojomast/devussy
+- **JSON Schema Spec:** https://json-schema.org/
+- **Pydantic Docs:** https://docs.pydantic.dev/
+- **Jinja2 Templates:** https://jinja.palletsprojects.com/
+- **React Testing Library:** https://testing-library.com/react
+- **Playwright:** https://playwright.dev/
+
+### Devussy-Specific
+- Current prompts: `src/prompts/`
+- Current templates: `templates/`
+- Existing tests: `tests/`
+- Web UI: `devussy-web/`
+
+---
+
+## 🎉 Final Notes
+
+**You have everything you need:**
+- Complete devplan with detailed tasks
+- This handoff with implementation guidance
+- Clear success criteria
+- Testing strategy
+- File structure
+
+**Remember:**
+- Keep context small (use anchors)
+- Test before proceeding
+- Update progress log
+- Pass clean baton to next agent
+
+**Questions?**
+- Refer to devplan.md for detailed specs
+- Check existing code for patterns
+- Flag uncertainties in progress log
+
+**Let's build something great! 🚀**
+
+---
+
+*End of Handoff Document*
+"""
\ No newline at end of file
diff --git a/DEVPLAN_FOR_NEXT_AGENT.md b/planning-archive/DEVPLAN_FOR_NEXT_AGENT.md
similarity index 100%
rename from DEVPLAN_FOR_NEXT_AGENT.md
rename to planning-archive/DEVPLAN_FOR_NEXT_AGENT.md
diff --git a/planning-archive/IRCPLAN.MD b/planning-archive/IRCPLAN.MD
new file mode 100644
index 0000000..9ea47c2
--- /dev/null
+++ b/planning-archive/IRCPLAN.MD
@@ -0,0 +1,383 @@
+DevPlan: Adding an IRC Add‑on to the Devussy Front‑end (devussy‑testing)
+Context
+
+The devussy‑testing branch of the Devussy project does not contain any IRC client or server integration. The front‑end window system currently defines window types such as 'init', 'interview', 'design', 'plan', 'execute', 'handoff', 'help' and 'model‑settings'
+raw.githubusercontent.com
+, and the size switch in getWindowSize lacks an 'irc' entry
+raw.githubusercontent.com
+. The docker‑compose.yml in this branch defines only the frontend, streaming‑server and nginx services
+raw.githubusercontent.com
+ without any IRC server or gateway containers. Therefore, an IRC add‑on must be implemented from scratch for this branch.
+
+Objectives
+
+Implement a React/Next.js IRC client as an add‑on window. The client must provide a chat interface, user list, nickname change, reconnection logic and a demo mode fallback.
+
+Containerize an IRC daemon and WebSocket gateway using Docker. The server will run InspIRCd with a WebIRC gateway (KiwiIRC’s webircgateway) to translate WebSocket messages to IRC. The services should be added to docker‑compose.yml alongside existing services.
+
+Integrate the IRC client into the Devussy front‑end by registering a new window type 'irc', adding an item to the taskbar/start menu, and optionally auto‑launching the chat window on page load.
+
+Provide configuration, documentation and tests to ensure maintainability and reproducibility.
+
+High‑Level Architecture
+Component	Purpose	Implementation
+IRC Client	A React functional component rendered inside a Devussy window. Connects via WebSocket to the IRC gateway, sends JSON commands (NICK, JOIN, PRIVMSG) and renders messages, join/part notices and system messages. Supports nickname changes, user list, reconnect logic and demo mode.	New file devussy-web/src/components/addons/irc/IrcClient.tsx using shadcn UI components.
+IRC Server (InspIRCd)	Provides IRC protocol implementation and manages channels, users and modes. Configuration stored in devussy-web/irc/conf/inspircd.conf.	Docker container inspircd/inspircd-docker:latest.
+WebIRC Gateway	Translates WebSocket connections to IRC commands and back. Reads configuration from gateway.conf defining the IRC server host and WebSocket listener.	Docker container kiwiirc/webircgateway:latest.
+Docker Compose	Orchestrates the front‑end, streaming server, nginx, IRC server and gateway. Adds new services for irc-server and irc-gateway with proper volumes and environment variables.	Update devussy-web/docker-compose.yml.
+Nginx Proxy	Optionally proxy WebSocket connections from /ws/irc to the irc-gateway service to expose a single HTTPS endpoint.	Update devussy-web/nginx/nginx.conf.
+Detailed Design
+1. Implementing the IRC Client
+
+New component – Create devussy-web/src/components/addons/irc/IrcClient.tsx. Use useState to track messages, users, nickname and connection state. Use useEffect to establish a WebSocket connection on mount and to perform cleanup on unmount. The connection URL should come from NEXT_PUBLIC_IRC_WS_URL with a sensible fallback such as wss://localhost:8080.
+
+Joining the channel – After the WebSocket connection is opened, send NICK <nickname> and JOIN <channel> commands encoded as JSON. Nicknames may come from local storage or be randomly generated. Support PRIVMSG for sending messages and handle incoming events such as PRIVMSG, JOIN, PART, NICK and 353 (name list).
+
+Demo mode – If the connection cannot be established within a timeout (e.g. 3 s), switch to a demo mode that generates simulated users and messages. Display a banner indicating the chat is in demo mode. This ensures the UI remains functional even when the IRC services are unavailable.
+
+User interface – Use shadcn components (Card, ScrollArea, Input, Button) to build the chat UI. Display messages with timestamps and differentiate join/part/system messages by colour. Include a user list sidebar and a nickname change dialog with validation (e.g. maximum 30 characters). The chat window should automatically scroll to the newest message.
+
+Reconnection logic – On disconnect, attempt to reconnect with exponential backoff, up to three attempts. After repeated failures, notify the user or switch to demo mode. Reconnect gracefully when the page regains focus or network connectivity.
+
+2. Front‑End Integration
+
+Window type – Add 'irc' to the WindowType union in src/app/page.tsx and update the getWindowSize switch to return a suitable default (e.g., { width: 800, height: 600 }) for 'irc'
+raw.githubusercontent.com
+.
+
+Spawning the window – Implement a handleOpenIrc function in page.tsx. It should:
+
+Check whether an IRC window already exists; if so, bring it to the front and optionally toggle minimization.
+
+If not, call spawnWindow('irc', 'IRC Chat – #devussy') to create a new window. The props can be used to pass configuration to the IRC client.
+
+Optionally minimize the window immediately after spawning to avoid disrupting the user experience.
+
+Taskbar and start menu – Add an option to open the IRC chat in the taskbar or start menu. For example, import MessageSquare icon and insert a button labelled “IRC Chat” that calls handleOpenIrc. Ensure the icon matches the theme.
+
+Auto‑launch (optional) – Use a useEffect hook to automatically spawn (and minimize) the IRC window after the page loads. Provide a user preference stored in localStorage (e.g., devussy_auto_launch_irc) to disable auto‑launch.
+
+Persistence – Store the current nickname and last 50 messages in localStorage so that the IRC state persists across page reloads. Clear the storage only when the user explicitly disconnects or leaves the channel.
+
+3. Containerizing the IRC Server and Gateway
+
+Directory structure – Create devussy-web/irc/ with subdirectories:
+
+conf/ – configuration files for InspIRCd, including inspircd.conf. Include modules m_webirc.so and m_cgiirc.so, define a <cgihost> entry for WebIRC and set a secure operator password. Document the meaning of each directive.
+
+logs/ – host volume for server logs.
+
+data/ – persistent storage for server state (e.g., certificates, user data).
+
+gateway.conf – configuration for KiwiIRC webircgateway. Define the IRC server host as irc-server, port 6667, and set the WebSocket listener on 0.0.0.0:8080. Tune heartbeat and nickname/channel length limits.
+
+docker‑compose changes – Extend devussy-web/docker-compose.yml by adding two new services:
+
+irc-server:
+  image: inspircd/inspircd-docker:latest
+  container_name: devussy-irc-server
+  ports:
+    - "6667:6667"  # plain IRC
+    - "6697:6697"  # TLS if enabled
+  volumes:
+    - ./irc/conf:/inspircd/conf
+    - ./irc/logs:/inspircd/logs
+    - ./irc/data:/inspircd/data
+  command: ["/inspircd/conf/inspircd.conf"]
+  restart: unless-stopped
+
+irc-gateway:
+  image: kiwiirc/webircgateway:latest
+  container_name: devussy-irc-gateway
+  ports:
+    - "8080:8080"
+  environment:
+    - GATEWAY_CONFIG=/kiwiirc/webircgateway.conf
+  volumes:
+    - ./irc/gateway.conf:/kiwiirc/webircgateway.conf
+  depends_on:
+    - irc-server
+  restart: unless-stopped
+
+
+These services do not exist in the current docker-compose.yml
+raw.githubusercontent.com
+ and must be added after the existing frontend and streaming-server definitions.
+
+Environment variables – Add NEXT_PUBLIC_IRC_WS_URL and NEXT_PUBLIC_IRC_CHANNEL to .env.example and document them. In frontend.Dockerfile, ensure these variables are passed into the container at runtime. In docker-compose.yml, set defaults such as:
+
+frontend:
+  environment:
+    - NEXT_PUBLIC_IRC_WS_URL=ws://localhost:8080
+    - NEXT_PUBLIC_IRC_CHANNEL=#devussy
+    ...
+
+
+Nginx reverse proxy (optional) – If you want to expose the gateway through nginx, add a location block to devussy-web/nginx/nginx.conf:
+
+location /ws/irc/ {
+  proxy_pass http://irc-gateway:8080/;
+  proxy_http_version 1.1;
+  proxy_set_header Upgrade $http_upgrade;
+  proxy_set_header Connection "Upgrade";
+  proxy_read_timeout 86400;
+}
+
+
+Then set NEXT_PUBLIC_IRC_WS_URL=wss://<your-domain>/ws/irc/ in .env.example for production.
+
+4. Configuration and Environment
+
+.env.example updates – Add placeholders for NEXT_PUBLIC_IRC_WS_URL and NEXT_PUBLIC_IRC_CHANNEL below the existing variables. Document that these variables configure the IRC client connection and default channel.
+
+frontend.Dockerfile – No changes are strictly required, but document that environment variables starting with NEXT_PUBLIC_ will be available to the client at build time. The docker-compose file should pass these variables when building/running the frontend service.
+
+Security considerations – Use a strong WEBIRC_PASSWORD (for the <cgihost> entry) and operator password in inspircd.conf. Avoid exposing the raw IRC ports publicly; rely on the gateway and nginx to handle WebSocket connections.
+
+5. Testing and Quality Assurance
+
+Unit tests – Create tests for parsing and handling IRC messages. Mock the WebSocket interface to simulate various server events (e.g., join, part, message, nick change). Use Jest for testing React hooks and state updates.
+
+Integration tests – Use Playwright or Cypress to start the docker compose stack and run a browser test: open Devussy, spawn the IRC window, send a message and assert that it appears in the chat. Simulate network failure to verify that demo mode activates.
+
+Manual QA – Validate dark/light theme support, responsiveness of the chat UI, nickname changes, user list updates and auto‑reconnect. Verify that the taskbar and start menu correctly open and focus the chat window.
+
+6. Documentation
+
+DevPlan: Adding an IRC Add‑on to the Devussy Front‑end (devussy‑testing)
+Context
+
+The devussy‑testing branch of the Devussy project does not contain any IRC client or server integration. The front‑end window system currently defines window types such as 'init', 'interview', 'design', 'plan', 'execute', 'handoff', 'help' and 'model‑settings'
+raw.githubusercontent.com
+, and the size switch in getWindowSize lacks an 'irc' entry
+raw.githubusercontent.com
+. The docker‑compose.yml in this branch defines only the frontend, streaming‑server and nginx services
+raw.githubusercontent.com
+ without any IRC server or gateway containers. Therefore, an IRC add‑on must be implemented from scratch for this branch.
+
+Objectives
+
+Implement a React/Next.js IRC client as an add‑on window. The client must provide a chat interface, user list, nickname change, reconnection logic and a demo mode fallback.
+
+Containerize an IRC daemon and WebSocket gateway using Docker. The server will run InspIRCd with a WebIRC gateway (KiwiIRC’s webircgateway) to translate WebSocket messages to IRC. The services should be added to docker‑compose.yml alongside existing services.
+
+Integrate the IRC client into the Devussy front‑end by registering a new window type 'irc', adding an item to the taskbar/start menu, and optionally auto‑launching the chat window on page load.
+
+Provide configuration, documentation and tests to ensure maintainability and reproducibility.
+
+High‑Level Architecture
+Component	Purpose	Implementation
+IRC Client	A React functional component rendered inside a Devussy window. Connects via WebSocket to the IRC gateway, sends JSON commands (NICK, JOIN, PRIVMSG) and renders messages, join/part notices and system messages. Supports nickname changes, user list, reconnect logic and demo mode.	New file devussy-web/src/components/addons/irc/IrcClient.tsx using shadcn UI components.
+IRC Server (InspIRCd)	Provides IRC protocol implementation and manages channels, users and modes. Configuration stored in devussy-web/irc/conf/inspircd.conf.	Docker container inspircd/inspircd-docker:latest.
+WebIRC Gateway	Translates WebSocket connections to IRC commands and back. Reads configuration from gateway.conf defining the IRC server host and WebSocket listener.	Docker container kiwiirc/webircgateway:latest.
+Docker Compose	Orchestrates the front‑end, streaming server, nginx, IRC server and gateway. Adds new services for irc-server and irc-gateway with proper volumes and environment variables.	Update devussy-web/docker-compose.yml.
+Nginx Proxy	Optionally proxy WebSocket connections from /ws/irc to the irc-gateway service to expose a single HTTPS endpoint.	Update devussy-web/nginx/nginx.conf.
+Detailed Design
+1. Implementing the IRC Client
+
+New component – Create devussy-web/src/components/addons/irc/IrcClient.tsx. Use useState to track messages, users, nickname and connection state. Use useEffect to establish a WebSocket connection on mount and to perform cleanup on unmount. The connection URL should come from NEXT_PUBLIC_IRC_WS_URL with a sensible fallback such as wss://localhost:8080.
+
+Joining the channel – After the WebSocket connection is opened, send NICK <nickname> and JOIN <channel> commands encoded as JSON. Nicknames may come from local storage or be randomly generated. Support PRIVMSG for sending messages and handle incoming events such as PRIVMSG, JOIN, PART, NICK and 353 (name list).
+
+Demo mode – If the connection cannot be established within a timeout (e.g. 3 s), switch to a demo mode that generates simulated users and messages. Display a banner indicating the chat is in demo mode. This ensures the UI remains functional even when the IRC services are unavailable.
+
+User interface – Use shadcn components (Card, ScrollArea, Input, Button) to build the chat UI. Display messages with timestamps and differentiate join/part/system messages by colour. Include a user list sidebar and a nickname change dialog with validation (e.g. maximum 30 characters). The chat window should automatically scroll to the newest message.
+
+Reconnection logic – On disconnect, attempt to reconnect with exponential backoff, up to three attempts. After repeated failures, notify the user or switch to demo mode. Reconnect gracefully when the page regains focus or network connectivity.
+
+2. Front‑End Integration
+
+Window type – Add 'irc' to the WindowType union in src/app/page.tsx and update the getWindowSize switch to return a suitable default (e.g., { width: 800, height: 600 }) for 'irc'
+raw.githubusercontent.com
+.
+
+Spawning the window – Implement a handleOpenIrc function in page.tsx. It should:
+
+Check whether an IRC window already exists; if so, bring it to the front and optionally toggle minimization.
+
+If not, call spawnWindow('irc', 'IRC Chat – #devussy') to create a new window. The props can be used to pass configuration to the IRC client.
+
+Optionally minimize the window immediately after spawning to avoid disrupting the user experience.
+
+Taskbar and start menu – Add an option to open the IRC chat in the taskbar or start menu. For example, import MessageSquare icon and insert a button labelled “IRC Chat” that calls handleOpenIrc. Ensure the icon matches the theme.
+
+Auto‑launch (optional) – Use a useEffect hook to automatically spawn (and minimize) the IRC window after the page loads. Provide a user preference stored in localStorage (e.g., devussy_auto_launch_irc) to disable auto‑launch.
+
+Persistence – Store the current nickname and last 50 messages in localStorage so that the IRC state persists across page reloads. Clear the storage only when the user explicitly disconnects or leaves the channel.
+
+3. Containerizing the IRC Server and Gateway
+
+Directory structure – Create devussy-web/irc/ with subdirectories:
+
+conf/ – configuration files for InspIRCd, including inspircd.conf. Include modules m_webirc.so and m_cgiirc.so, define a <cgihost> entry for WebIRC and set a secure operator password. Document the meaning of each directive.
+
+logs/ – host volume for server logs.
+
+data/ – persistent storage for server state (e.g., certificates, user data).
+
+gateway.conf – configuration for KiwiIRC webircgateway. Define the IRC server host as irc-server, port 6667, and set the WebSocket listener on 0.0.0.0:8080. Tune heartbeat and nickname/channel length limits.
+
+docker‑compose changes – Extend devussy-web/docker-compose.yml by adding two new services:
+
+irc-server:
+  image: inspircd/inspircd-docker:latest
+  container_name: devussy-irc-server
+  ports:
+    - "6667:6667"  # plain IRC
+    - "6697:6697"  # TLS if enabled
+  volumes:
+    - ./irc/conf:/inspircd/conf
+    - ./irc/logs:/inspircd/logs
+    - ./irc/data:/inspircd/data
+  command: ["/inspircd/conf/inspircd.conf"]
+  restart: unless-stopped
+
+irc-gateway:
+  image: kiwiirc/webircgateway:latest
+  container_name: devussy-irc-gateway
+  ports:
+    - "8080:8080"
+  environment:
+    - GATEWAY_CONFIG=/kiwiirc/webircgateway.conf
+  volumes:
+    - ./irc/gateway.conf:/kiwiirc/webircgateway.conf
+  depends_on:
+    - irc-server
+  restart: unless-stopped
+
+
+These services do not exist in the current docker-compose.yml
+raw.githubusercontent.com
+ and must be added after the existing frontend and streaming-server definitions.
+
+Environment variables – Add NEXT_PUBLIC_IRC_WS_URL and NEXT_PUBLIC_IRC_CHANNEL to .env.example and document them. In frontend.Dockerfile, ensure these variables are passed into the container at runtime. In docker-compose.yml, set defaults such as:
+
+frontend:
+  environment:
+    - NEXT_PUBLIC_IRC_WS_URL=ws://localhost:8080
+    - NEXT_PUBLIC_IRC_CHANNEL=#devussy
+    ...
+
+
+Nginx reverse proxy (optional) – If you want to expose the gateway through nginx, add a location block to devussy-web/nginx/nginx.conf:
+
+location /ws/irc/ {
+  proxy_pass http://irc-gateway:8080/;
+  proxy_http_version 1.1;
+  proxy_set_header Upgrade $http_upgrade;
+  proxy_set_header Connection "Upgrade";
+  proxy_read_timeout 86400;
+}
+
+
+Then set NEXT_PUBLIC_IRC_WS_URL=wss://<your-domain>/ws/irc/ in .env.example for production.
+
+4. Configuration and Environment
+
+.env.example updates – Add placeholders for NEXT_PUBLIC_IRC_WS_URL and NEXT_PUBLIC_IRC_CHANNEL below the existing variables. Document that these variables configure the IRC client connection and default channel.
+
+frontend.Dockerfile – No changes are strictly required, but document that environment variables starting with NEXT_PUBLIC_ will be available to the client at build time. The docker-compose file should pass these variables when building/running the frontend service.
+
+Security considerations – Use a strong WEBIRC_PASSWORD (for the <cgihost> entry) and operator password in inspircd.conf. Avoid exposing the raw IRC ports publicly; rely on the gateway and nginx to handle WebSocket connections.
+
+5. Testing and Quality Assurance
+
+Unit tests – Create tests for parsing and handling IRC messages. Mock the WebSocket interface to simulate various server events (e.g., join, part, message, nick change). Use Jest for testing React hooks and state updates.
+
+Integration tests – Use Playwright or Cypress to start the docker compose stack and run a browser test: open Devussy, spawn the IRC window, send a message and assert that it appears in the chat. Simulate network failure to verify that demo mode activates.
+
+Manual QA – Validate dark/light theme support, responsiveness of the chat UI, nickname changes, user list updates and auto‑reconnect. Verify that the taskbar and start menu correctly open and focus the chat window.
+
+6. Documentation
+
+README modifications – In the root README or a new devussy-web/addons/irc/README.md, explain how to enable the IRC add‑on. Provide instructions for starting the IRC services with Docker, configuring environment variables, and connecting to the chat from the Devussy UI.
+
+Configuration docs – Comment the inspircd.conf and gateway.conf files explaining each option (e.g., modules loaded, limits and passwords). Provide guidance on generating SSL certificates if TLS is enabled.
+
+User guide – Describe how to open the IRC chat from the taskbar/start menu, how to change nicknames, how to disable auto‑launch and how demo mode works.
+
+## Status: Completed ✅
+
+### Implementation Notes
+- **Architecture Change**: The separate `irc-gateway` container was removed in favor of InspIRCd's native WebSocket support (`m_websocket`). This simplifies the stack and reduces resource usage.
+- **DNS Issues**: Docker's internal DNS hostnames (e.g., `project_service_1`) caused issues with InspIRCd's reverse DNS lookups. This was resolved by disabling DNS resolution in InspIRCd and setting a specific hostname for the Nginx container.
+- **Ghost Connections**: `pingfreq` was reduced to 15s to quickly clean up dead connections from page reloads.
+- **Nick Collisions**: The client automatically handles 433 errors by appending an underscore to the nickname.
+
+### Completed Tasks
+
+#### 1. Implementing the IRC Client
+- [x] New component `IrcClient.tsx`
+- [x] WebSocket connection logic
+- [x] Message parsing (PRIVMSG, JOIN, PART, NICK, etc.)
+- [x] User interface with Shadcn UI
+- [x] Auto-reconnect logic
+- [x] Demo mode fallback
+- [x] Nickname collision handling (Auto-retry)
+
+#### 2. Front-End Integration
+- [x] Window type 'irc' added
+- [x] Taskbar/Start Menu integration
+- [x] Persistence (localStorage)
+
+#### 3. Containerizing the IRC Server
+- [x] `irc` directory structure created
+- [x] `inspircd_v2.conf` configured with WebSocket support
+- [x] `docker-compose.yml` updated (added `ircd`, removed `irc-gateway`)
+- [x] Environment variables configured
+
+#### 4. Configuration and Environment
+- [x] `.env.example` updated (implied)
+- [x] Nginx reverse proxy configured for WebSocket support (`/ws/irc/`)
+
+#### 5. Testing and Quality Assurance
+- [x] Manual QA (Connection, Messaging, Nick changes, Reloads)
+- [x] Debug script `debug_irc.py` created for VPS troubleshooting
+
+#### 6. Documentation
+- [x] `devussy-web/irc/README.md` updated
+- [x] `IRCPLAN.MD` updated
+
+Implementation Timeline
+
+The following phases assume a single developer or small team and should be adjusted based on resource availability:
+
+Scaffolding (≈1 day)
+
+Create irc directory structure and configuration files with secure defaults.
+
+Extend docker-compose.yml to include irc-server and irc-gateway services.
+
+Add environment variables to .env.example and update documentation accordingly.
+
+Build and run the stack locally using docker-compose up; verify that the IRC server accepts connections (e.g., via an external IRC client connecting to localhost:6667).
+
+Client development (≈2 days)
+
+Implement IrcClient.tsx with WebSocket connection, message handling, user list, nickname changes and demo mode.
+
+Add 'irc' to WindowType, update getWindowSize and implement handleOpenIrc in page.tsx.
+
+Modify the taskbar/start menu to include an “IRC Chat” launcher.
+
+Implement auto‑launch with a user preference and persist chat state in localStorage.
+
+Integration and testing (≈1 day)
+
+Integrate environment variables into the Next.js build and verify that the client connects to the gateway via the configured URL.
+
+Write Jest unit tests and at least one E2E test with Playwright/Cypress. Run tests in CI with the full docker stack.
+
+Adjust styling to match the Devussy design system and ensure accessibility (e.g., keyboard navigation and ARIA labels).
+
+Documentation and polish (≈½ day)
+
+Update README and configuration comments.
+
+Add screenshots or GIFs demonstrating the chat feature.
+
+Conduct final manual QA and fix any usability issues or bugs.
+
+Conclusion
+
+By following this plan, developers can introduce a fully functional IRC chat into the devussy‑testing branch without disrupting existing features. The plan covers creating the IRC server and WebSocket gateway, adding a comprehensive chat component, integrating the new window into the existing window manager, and updating configuration, documentation and tests. Once completed, users will be able to collaborate in real time while generating designs and plans within Devussy.
\ No newline at end of file
diff --git a/NEW-REPO-INSTRUCTIONS.md b/planning-archive/NEW-REPO-INSTRUCTIONS.md
similarity index 100%
rename from NEW-REPO-INSTRUCTIONS.md
rename to planning-archive/NEW-REPO-INSTRUCTIONS.md
diff --git a/QUICK-START-NEW-REPO.md b/planning-archive/QUICK-START-NEW-REPO.md
similarity index 100%
rename from QUICK-START-NEW-REPO.md
rename to planning-archive/QUICK-START-NEW-REPO.md
diff --git a/STREAMING_GUIDE.md b/planning-archive/STREAMING_GUIDE.md
similarity index 100%
rename from STREAMING_GUIDE.md
rename to planning-archive/STREAMING_GUIDE.md
diff --git a/frontend_implementation_plan.md b/planning-archive/frontend_implementation_plan.md
similarity index 100%
rename from frontend_implementation_plan.md
rename to planning-archive/frontend_implementation_plan.md
diff --git a/planning-archive/handoff_prompt.md b/planning-archive/handoff_prompt.md
new file mode 100644
index 0000000..823b071
--- /dev/null
+++ b/planning-archive/handoff_prompt.md
@@ -0,0 +1 @@
+Test handoff prompt content
\ No newline at end of file
diff --git a/hivemind_implementation_plan.md b/planning-archive/hivemind_implementation_plan.md
similarity index 100%
rename from hivemind_implementation_plan.md
rename to planning-archive/hivemind_implementation_plan.md
diff --git a/interviewfix.md b/planning-archive/interviewfix.md
similarity index 100%
rename from interviewfix.md
rename to planning-archive/interviewfix.md
diff --git a/jinja.md b/planning-archive/jinja.md
similarity index 100%
rename from jinja.md
rename to planning-archive/jinja.md
diff --git a/planning-archive/phase1.md b/planning-archive/phase1.md
new file mode 100644
index 0000000..b25beb1
--- /dev/null
+++ b/planning-archive/phase1.md
@@ -0,0 +1,51 @@
+# Phase 1: Setup Phase
+
+
+**Project**: Unknown Project
+
+**Total Steps**: 2
+
+
+## Tasks
+
+
+<!-- PHASE_TASKS_START -->
+
+- [ ] 1.1: Create project structure
+
+- [ ] 1.2: Set up development environment
+
+<!-- PHASE_TASKS_END -->
+
+
+## Context (Read Only When Blocked)
+
+
+<!-- PHASE_CONTEXT_START -->
+
+Initial project setup
+
+<!-- PHASE_CONTEXT_END -->
+
+
+## Outcomes
+
+
+<!-- PHASE_OUTCOMES_START -->
+
+<!-- Updates added as tasks complete -->
+
+<!-- PHASE_OUTCOMES_END -->
+
+
+## Progress (Legacy Anchor)
+
+
+<!-- PHASE_PROGRESS_START -->
+
+<!-- PHASE_PROGRESS_END -->
+
+
+*Generated: 2025-11-24 18:28:13*
+
+*Back to: [Main DevPlan](devplan.md)*
diff --git a/planning-archive/project_design.md b/planning-archive/project_design.md
new file mode 100644
index 0000000..e48e89b
--- /dev/null
+++ b/planning-archive/project_design.md
@@ -0,0 +1,32 @@
+# Project Design: no-repo-test
+
+## Architecture Overview
+
+Test architecture overview
+
+## Tech Stack
+
+- Python
+- FastAPI
+- PostgreSQL
+
+## Objectives
+
+- Build web application
+- Create API
+
+## Dependencies
+
+- requests
+- pydantic
+- uvicorn
+
+## Challenges
+
+- Performance optimization
+- Scalability
+
+## Mitigations
+
+- Use caching
+- Load balancing
\ No newline at end of file
diff --git a/streaming_analysis_report.md b/planning-archive/streaming_analysis_report.md
similarity index 100%
rename from streaming_analysis_report.md
rename to planning-archive/streaming_analysis_report.md
diff --git a/streaming_duplication_bug_fix_report.md b/planning-archive/streaming_duplication_bug_fix_report.md
similarity index 100%
rename from streaming_duplication_bug_fix_report.md
rename to planning-archive/streaming_duplication_bug_fix_report.md
diff --git a/schemas/complexity_profile.json b/schemas/complexity_profile.json
new file mode 100644
index 0000000..3be2590
--- /dev/null
+++ b/schemas/complexity_profile.json
@@ -0,0 +1,81 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devussy.dev/schemas/complexity_profile.json",
+  "title": "ComplexityProfile",
+  "description": "Complexity assessment profile for a software project, used to determine scaling of devplan output.",
+  "type": "object",
+  "required": [
+    "project_type_bucket",
+    "technical_complexity_bucket",
+    "integration_bucket",
+    "team_size_bucket",
+    "score",
+    "estimated_phase_count",
+    "depth_level",
+    "confidence"
+  ],
+  "properties": {
+    "project_type_bucket": {
+      "type": "string",
+      "enum": ["cli_tool", "library", "api", "web_app", "saas"],
+      "description": "Classification of project type affecting base complexity"
+    },
+    "technical_complexity_bucket": {
+      "type": "string",
+      "enum": ["simple_crud", "auth_db", "realtime", "ml_ai", "multi_region"],
+      "description": "Technical complexity classification based on requirements"
+    },
+    "integration_bucket": {
+      "type": "string",
+      "enum": ["standalone", "1_2_services", "3_5_services", "6_plus_services"],
+      "description": "External API/service integration complexity"
+    },
+    "team_size_bucket": {
+      "type": "string",
+      "enum": ["solo", "2_3", "4_6", "7_plus"],
+      "description": "Team size affecting coordination complexity multiplier"
+    },
+    "score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 30,
+      "description": "Calculated complexity score (0-20 typical range, higher with team multipliers)"
+    },
+    "estimated_phase_count": {
+      "type": "integer",
+      "minimum": 3,
+      "maximum": 15,
+      "description": "Recommended number of phases for the devplan"
+    },
+    "depth_level": {
+      "type": "string",
+      "enum": ["minimal", "standard", "detailed"],
+      "description": "Level of detail for generated artifacts"
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Confidence score for the complexity assessment (0.0-1.0)"
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Optional explanation of complexity assessment (from LLM-driven analysis)"
+    },
+    "hidden_complexity_flags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Optional flags for hidden complexity factors (compliance, security, etc.)"
+    },
+    "follow_up_questions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Optional follow-up questions if confidence is low"
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/schemas/correction_history.json b/schemas/correction_history.json
new file mode 100644
index 0000000..78fab4a
--- /dev/null
+++ b/schemas/correction_history.json
@@ -0,0 +1,91 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devussy.dev/schemas/correction_history.json",
+  "title": "CorrectionHistory",
+  "description": "History of design correction iterations.",
+  "type": "object",
+  "required": ["iterations", "final_design", "total_iterations", "success"],
+  "properties": {
+    "iterations": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/CorrectionIteration"
+      },
+      "description": "List of correction iterations performed"
+    },
+    "final_design": {
+      "type": "string",
+      "description": "The final corrected design text"
+    },
+    "total_iterations": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 10,
+      "description": "Total number of correction iterations performed"
+    },
+    "success": {
+      "type": "boolean",
+      "description": "Whether correction succeeded (passed validation)"
+    },
+    "requires_human_review": {
+      "type": "boolean",
+      "description": "Whether human review is needed for remaining issues"
+    },
+    "max_iterations_reached": {
+      "type": "boolean",
+      "description": "Whether max iteration limit was hit"
+    },
+    "started_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When correction started"
+    },
+    "completed_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When correction completed"
+    }
+  },
+  "definitions": {
+    "CorrectionIteration": {
+      "type": "object",
+      "required": ["iteration_number", "validation_passed", "review_confidence"],
+      "properties": {
+        "iteration_number": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based iteration number"
+        },
+        "validation_passed": {
+          "type": "boolean",
+          "description": "Whether validation passed in this iteration"
+        },
+        "review_confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "LLM review confidence score for this iteration"
+        },
+        "issues_fixed": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Issue codes that were fixed in this iteration"
+        },
+        "issues_remaining": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Issue codes still remaining after this iteration"
+        },
+        "design_snapshot": {
+          "type": "string",
+          "description": "Optional snapshot of design after this iteration"
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/schemas/review_result.json b/schemas/review_result.json
new file mode 100644
index 0000000..b0b93a3
--- /dev/null
+++ b/schemas/review_result.json
@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devussy.dev/schemas/review_result.json",
+  "title": "ReviewResult",
+  "description": "LLM sanity review result for a design document.",
+  "type": "object",
+  "required": ["is_acceptable", "confidence", "summary"],
+  "properties": {
+    "is_acceptable": {
+      "type": "boolean",
+      "description": "Whether the design is acceptable without major changes"
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Confidence score for the review assessment (0.0-1.0)"
+    },
+    "summary": {
+      "type": "string",
+      "description": "Brief summary of the review findings"
+    },
+    "issues": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of issues or concerns identified"
+    },
+    "suggestions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of improvement suggestions"
+    },
+    "strengths": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of design strengths identified"
+    },
+    "risk_areas": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Areas that may need additional attention or validation"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the review was performed"
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/schemas/validation_report.json b/schemas/validation_report.json
new file mode 100644
index 0000000..6568959
--- /dev/null
+++ b/schemas/validation_report.json
@@ -0,0 +1,75 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devussy.dev/schemas/validation_report.json",
+  "title": "ValidationReport",
+  "description": "Design validation report containing check results and issues found.",
+  "type": "object",
+  "required": ["is_valid", "auto_correctable", "issues", "checks"],
+  "properties": {
+    "is_valid": {
+      "type": "boolean",
+      "description": "Whether the design passed all validation checks"
+    },
+    "auto_correctable": {
+      "type": "boolean",
+      "description": "Whether all issues can be automatically corrected"
+    },
+    "issues": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ValidationIssue"
+      },
+      "description": "List of validation issues found"
+    },
+    "checks": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "boolean"
+      },
+      "description": "Map of check names to pass/fail status"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the validation was performed"
+    },
+    "validator_version": {
+      "type": "string",
+      "description": "Version of the validator used"
+    }
+  },
+  "definitions": {
+    "ValidationIssue": {
+      "type": "object",
+      "required": ["code", "message", "auto_correctable"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "description": "Machine-readable issue code (e.g., 'consistency.conflict_monolith_microservices')"
+        },
+        "message": {
+          "type": "string",
+          "description": "Human-readable description of the issue"
+        },
+        "auto_correctable": {
+          "type": "boolean",
+          "description": "Whether this issue can be automatically corrected"
+        },
+        "severity": {
+          "type": "string",
+          "enum": ["error", "warning", "info"],
+          "description": "Severity level of the issue"
+        },
+        "location": {
+          "type": "string",
+          "description": "Optional location/section where the issue was found"
+        },
+        "suggestion": {
+          "type": "string",
+          "description": "Optional suggested fix"
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/scripts/verify_irc.py b/scripts/verify_irc.py
new file mode 100644
index 0000000..3790e3b
--- /dev/null
+++ b/scripts/verify_irc.py
@@ -0,0 +1,49 @@
+import asyncio
+import websockets
+import sys
+
+async def test_irc_connection():
+    uri = "ws://localhost:8080"
+    print(f"Connecting to {uri}...")
+    
+    try:
+        async with websockets.connect(uri) as websocket:
+            print("Connected to WebSocket Gateway!")
+            
+            # Send IRC handshake
+            nick = "DevussyTester"
+            print(f"Sending NICK {nick}...")
+            await websocket.send(f"NICK {nick}\r\n")
+            await websocket.send(f"USER {nick} 0 * :Devussy Tester\r\n")
+            
+            # Wait for response
+            print("Waiting for response...")
+            try:
+                while True:
+                    message = await asyncio.wait_for(websocket.recv(), timeout=5.0)
+                    print(f"Received: {message.strip()}")
+                    
+                    # Check for welcome message (001) or any sign of life
+                    if "001" in message:
+                        print("\nSUCCESS: Received Welcome Message (RPL_WELCOME)!")
+                        return True
+                    if "433" in message:
+                         print("\nSUCCESS: Server responded (Nickname in use), connection is working.")
+                         return True
+                    if "PING" in message:
+                         await websocket.send(f"PONG {message.split()[1]}\r\n")
+            except asyncio.TimeoutError:
+                print("\nTimed out waiting for welcome message. Server might be slow or misconfigured.")
+                return False
+                
+    except ConnectionRefusedError:
+        print("\nERROR: Connection Refused. Is the Docker container running?")
+        print("Run: docker-compose up -d irc-server irc-gateway")
+        return False
+    except Exception as e:
+        print(f"\nERROR: {e}")
+        return False
+
+if __name__ == "__main__":
+    success = asyncio.run(test_irc_connection())
+    sys.exit(0 if success else 1)
diff --git a/src/cli.py b/src/cli.py
index d1199ef..2ddf951 100644
--- a/src/cli.py
+++ b/src/cli.py
@@ -1282,6 +1282,257 @@ def run_full_pipeline(
         raise typer.Exit(code=1)
 
 
+@app.command()
+def run_adaptive_pipeline(
+    project_name: Annotated[str, typer.Option("--name", help="Project name")],
+    languages: Annotated[
+        str,
+        typer.Option("--languages", help="Comma-separated programming languages"),
+    ],
+    requirements: Annotated[
+        str, typer.Option("--requirements", help="Project requirements")
+    ],
+    frameworks: Annotated[
+        Optional[str],
+        typer.Option("--frameworks", help="Comma-separated frameworks"),
+    ] = None,
+    apis: Annotated[
+        Optional[str], typer.Option("--apis", help="Comma-separated APIs")
+    ] = None,
+    config_path: Annotated[
+        Optional[str], typer.Option("--config", help="Path to config file")
+    ] = None,
+    provider: Annotated[
+        Optional[str], typer.Option("--provider", help="LLM provider override")
+    ] = None,
+    model: Annotated[
+        Optional[str], typer.Option("--model", help="Model override")
+    ] = None,
+    select_model: Annotated[
+        bool,
+        typer.Option(
+            "--select-model",
+            help="Interactively choose a Requesty model for this run",
+        ),
+    ] = False,
+    temperature: Annotated[
+        Optional[float],
+        typer.Option(
+            "--temperature",
+            help="Sampling temperature override for the active model",
+            min=0.0,
+            max=2.0,
+        ),
+    ] = None,
+    max_tokens: Annotated[
+        Optional[int],
+        typer.Option(
+            "--max-tokens",
+            help="Maximum tokens to request from the model",
+            min=1,
+        ),
+    ] = None,
+    output_dir: Annotated[
+        Optional[str], typer.Option("--output-dir", help="Output directory")
+    ] = None,
+    interview_file: Annotated[
+        Optional[str],
+        typer.Option(
+            "--interview-file",
+            help="Path to JSON file with interview data for complexity analysis",
+        ),
+    ] = None,
+    enable_validation: Annotated[
+        bool,
+        typer.Option(
+            "--validation/--no-validation",
+            help="Enable design validation after generation",
+        ),
+    ] = True,
+    enable_correction: Annotated[
+        bool,
+        typer.Option(
+            "--correction/--no-correction",
+            help="Enable iterative correction loop if validation fails",
+        ),
+    ] = True,
+    max_concurrent: Annotated[
+        Optional[int],
+        typer.Option("--max-concurrent", help="Maximum concurrent API requests"),
+    ] = None,
+    streaming: Annotated[
+        bool, typer.Option("--streaming", help="Enable token streaming")
+    ] = False,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", help="Enable verbose logging")
+    ] = False,
+    debug: Annotated[
+        bool, typer.Option("--debug", help="Enable debug mode with full tracebacks")
+    ] = False,
+) -> None:
+    """Run the adaptive pipeline with complexity analysis, validation, and correction.
+
+    This extends the standard pipeline with:
+    - Complexity analysis before design generation (scales output depth)
+    - Design validation after generation
+    - Iterative correction loop if issues found
+
+    Example:
+        devussy run-adaptive-pipeline --name "myapp" --languages "Python,TypeScript" \\
+            --requirements "Build a REST API with auth" --validation --correction
+    """
+    try:
+        # Validate required parameters
+        if not project_name or not project_name.strip():
+            typer.echo("Error: Project name is required", err=True, color=True)
+            raise typer.Exit(code=1)
+
+        if not languages or not languages.strip():
+            typer.echo(
+                "Error: At least one language must be specified", err=True, color=True
+            )
+            raise typer.Exit(code=1)
+
+        if not requirements or not requirements.strip():
+            typer.echo("Error: Project requirements are required", err=True, color=True)
+            raise typer.Exit(code=1)
+
+        # Load config
+        config = _load_app_config(
+            config_path,
+            provider,
+            model,
+            output_dir,
+            verbose,
+            temperature,
+            max_tokens,
+        )
+
+        if select_model:
+            _select_requesty_model_interactively(config)
+
+        if max_concurrent:
+            config.max_concurrent_requests = max_concurrent
+        if streaming:
+            config.streaming_enabled = True
+
+        # Parse lists
+        languages_list = [lang.strip() for lang in languages.split(",")]
+        frameworks_list = (
+            [fw.strip() for fw in frameworks.split(",")] if frameworks else None
+        )
+        apis_list = [api.strip() for api in apis.split(",")] if apis else None
+
+        # Load interview data if provided, otherwise create minimal interview data
+        if interview_file:
+            interview_file_path = Path(interview_file)
+            if not interview_file_path.exists():
+                typer.echo(
+                    f"Error: Interview file not found: {interview_file}",
+                    err=True,
+                    color=True,
+                )
+                raise typer.Exit(code=1)
+            with open(interview_file_path, "r", encoding="utf-8") as f:
+                interview_data = json.load(f)
+            typer.echo(f"[NOTE] Loaded interview data from: {interview_file}\n")
+        else:
+            # Create minimal interview data from CLI inputs for complexity analysis
+            interview_data = {
+                "project_name": project_name,
+                "languages": languages_list,
+                "requirements": requirements,
+                "frameworks": frameworks_list or [],
+                "apis": apis_list or [],
+                "team_size": "solo",  # Default assumption
+                "project_type": "api" if apis_list else "cli_tool",  # Heuristic
+            }
+            typer.echo("[NOTE] Using CLI inputs for complexity analysis\n")
+
+        # Create markdown output manager and initialize run directory
+        markdown_output_mgr = MarkdownOutputManager(base_output_dir="outputs")
+        run_dir = markdown_output_mgr.create_run_directory(project_name)
+        typer.echo(f"\n[NOTE] Saving all outputs to: {run_dir}\n")
+
+        # Save run metadata
+        markdown_output_mgr.save_run_metadata({
+            "project_name": project_name,
+            "languages": languages_list,
+            "requirements": requirements,
+            "frameworks": frameworks_list,
+            "apis": apis_list,
+            "config_path": config_path,
+            "provider": config.llm.provider,
+            "model": config.llm.model,
+            "pipeline_type": "adaptive",
+            "enable_validation": enable_validation,
+            "enable_correction": enable_correction,
+        })
+
+        # Create orchestrator with markdown output manager
+        orchestrator = _create_orchestrator(config, markdown_output_manager=markdown_output_mgr)
+
+        # Ensure output directory exists
+        config.output_dir.mkdir(parents=True, exist_ok=True)
+
+        typer.echo("\n" + "=" * 60)
+        typer.echo("[ROCKET] Starting Adaptive Pipeline")
+        typer.echo("=" * 60)
+        typer.echo(f"  Project: {project_name}")
+        typer.echo(f"  Validation: {'enabled' if enable_validation else 'disabled'}")
+        typer.echo(f"  Correction: {'enabled' if enable_correction else 'disabled'}")
+        typer.echo("=" * 60 + "\n")
+
+        # Run adaptive pipeline
+        logger.info(f"Starting adaptive pipeline for: {project_name}")
+
+        design, devplan, handoff, complexity_profile = asyncio.run(
+            orchestrator.run_adaptive_pipeline(
+                project_name=project_name,
+                languages=languages_list,
+                requirements=requirements,
+                interview_data=interview_data,
+                frameworks=frameworks_list,
+                apis=apis_list,
+                output_dir=str(config.output_dir),
+                save_artifacts=True,
+                enable_validation=enable_validation,
+                enable_correction=enable_correction,
+            )
+        )
+
+        # Display complexity profile summary
+        if complexity_profile:
+            typer.echo("\n" + "=" * 60)
+            typer.echo("[CHART] Complexity Analysis Results")
+            typer.echo("=" * 60)
+            typer.echo(f"  Project Type: {complexity_profile.project_type_bucket}")
+            typer.echo(f"  Technical Complexity: {complexity_profile.technical_complexity_bucket}")
+            typer.echo(f"  Integration Level: {complexity_profile.integration_bucket}")
+            typer.echo(f"  Team Size: {complexity_profile.team_size_bucket}")
+            typer.echo(f"  Complexity Score: {complexity_profile.score:.2f}")
+            typer.echo(f"  Depth Level: {complexity_profile.depth_level}")
+            typer.echo(f"  Estimated Phases: {complexity_profile.estimated_phase_count}")
+            typer.echo("=" * 60 + "\n")
+
+        logger.info("Adaptive pipeline completed successfully")
+        typer.echo("\n[OK] Adaptive pipeline completed successfully!\n")
+
+    except typer.Exit:
+        raise
+    except KeyboardInterrupt:
+        typer.echo("\n\n[WARN] Pipeline interrupted by user", err=True, color=True)
+        logger.warning("Pipeline interrupted by user")
+        raise typer.Exit(code=130)
+    except Exception as e:
+        typer.echo(f"\n[ERROR] Error: {str(e)}", err=True, color=True)
+        logger.error(f"Error running adaptive pipeline: {e}", exc_info=True)
+        if debug:
+            typer.echo("\nDebug traceback:", err=True)
+            typer.echo(traceback.format_exc(), err=True)
+        raise typer.Exit(code=1)
+
+
 @app.command()
 def init_repo(
     path: Annotated[
diff --git a/src/interview/complexity_analyzer.py b/src/interview/complexity_analyzer.py
new file mode 100644
index 0000000..65300ac
--- /dev/null
+++ b/src/interview/complexity_analyzer.py
@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+"""
+Complexity Analyzer - Testing Scaffold Implementation
+
+This module provides DETERMINISTIC, RULE-BASED complexity analysis for testing
+and development purposes. The static scoring rubric enables:
+- Predictable unit test outcomes
+- Fast iteration without API calls
+- Baseline comparison for LLM integration
+
+PRODUCTION BEHAVIOR (future):
+When integrated with LLM, the analyzer should dynamically assess complexity
+based on full project context rather than keyword matching. See:
+- adaptive_pipeline_llm_ideas.md (Section 1)
+- handoff.md (Complexity Assessment section)
+
+The LLM should:
+1. Analyze interview transcript holistically
+2. Consider how complexity factors interact
+3. Detect hidden complexity (compliance, security, scaling)
+4. Generate targeted follow-up questions
+5. Provide transparent reasoning for its assessment
+
+The rule-based implementation here serves as a FALLBACK when:
+- LLM is unavailable
+- Validating LLM output against heuristics
+- Running CI/CD tests deterministically
+"""
+
+from dataclasses import dataclass
+from typing import Literal, Mapping, Any
+
+
+ProjectTypeBucket = Literal["cli_tool", "library", "api", "web_app", "saas"]
+TechnicalComplexityBucket = Literal[
+    "simple_crud",
+    "auth_db",
+    "realtime",
+    "ml_ai",
+    "multi_region",
+]
+IntegrationBucket = Literal[
+    "standalone",
+    "1_2_services",
+    "3_5_services",
+    "6_plus_services",
+]
+TeamSizeBucket = Literal["solo", "2_3", "4_6", "7_plus"]
+DepthLevel = Literal["minimal", "standard", "detailed"]
+
+
+PROJECT_TYPE_SCORE: Mapping[ProjectTypeBucket, int] = {
+    "cli_tool": 1,
+    "library": 2,
+    "api": 3,
+    "web_app": 4,
+    "saas": 5,
+}
+
+TECHNICAL_COMPLEXITY_SCORE: Mapping[TechnicalComplexityBucket, int] = {
+    "simple_crud": 1,
+    "auth_db": 2,
+    "realtime": 3,
+    "ml_ai": 4,
+    "multi_region": 5,
+}
+
+INTEGRATION_SCORE: Mapping[IntegrationBucket, int] = {
+    "standalone": 0,
+    "1_2_services": 1,
+    "3_5_services": 2,
+    "6_plus_services": 3,
+}
+
+TEAM_SIZE_MULTIPLIER: Mapping[TeamSizeBucket, float] = {
+    "solo": 0.5,
+    "2_3": 1.0,
+    "4_6": 1.2,
+    "7_plus": 1.5,
+}
+
+
+@dataclass
+class ComplexityProfile:
+    project_type_bucket: ProjectTypeBucket
+    technical_complexity_bucket: TechnicalComplexityBucket
+    integration_bucket: IntegrationBucket
+    team_size_bucket: TeamSizeBucket
+
+    score: float
+    estimated_phase_count: int
+    depth_level: DepthLevel
+    confidence: float
+
+
+def estimate_phase_count(complexity_score: float) -> int:
+    if complexity_score <= 3:
+        return 3
+    if complexity_score <= 7:
+        return 5
+    if complexity_score <= 12:
+        return 7
+    return int(min(9 + (complexity_score - 12) // 2, 15))
+
+
+class ComplexityAnalyzer:
+    def analyze(self, interview_data: Mapping[str, Any]) -> ComplexityProfile:
+        project_type_bucket = self._infer_project_type_bucket(interview_data)
+        technical_complexity_bucket = self._infer_technical_complexity_bucket(
+            interview_data
+        )
+        integration_bucket = self._infer_integration_bucket(interview_data)
+        team_size_bucket = self._infer_team_size_bucket(interview_data)
+
+        base = (
+            PROJECT_TYPE_SCORE[project_type_bucket]
+            + TECHNICAL_COMPLEXITY_SCORE[technical_complexity_bucket]
+            + INTEGRATION_SCORE[integration_bucket]
+        )
+        multiplier = TEAM_SIZE_MULTIPLIER[team_size_bucket]
+        score = base * multiplier
+
+        estimated_phase_count = estimate_phase_count(score)
+        depth_level = self._derive_depth_level(score)
+        confidence = self._estimate_confidence(
+            project_type_bucket,
+            technical_complexity_bucket,
+            integration_bucket,
+            team_size_bucket,
+        )
+
+        return ComplexityProfile(
+            project_type_bucket=project_type_bucket,
+            technical_complexity_bucket=technical_complexity_bucket,
+            integration_bucket=integration_bucket,
+            team_size_bucket=team_size_bucket,
+            score=score,
+            estimated_phase_count=estimated_phase_count,
+            depth_level=depth_level,
+            confidence=confidence,
+        )
+
+    def _infer_project_type_bucket(self, interview_data: Mapping[str, Any]) -> ProjectTypeBucket:
+        project_type_raw = str(interview_data.get("project_type", "")).lower()
+        if "cli" in project_type_raw:
+            return "cli_tool"
+        if any(word in project_type_raw for word in ("library", "sdk")):
+            return "library"
+        if "api" in project_type_raw:
+            return "api"
+        if any(word in project_type_raw for word in ("web", "frontend", "spa")):
+            return "web_app"
+        if any(word in project_type_raw for word in ("saas", "platform", "multi-tenant")):
+            return "saas"
+        return "web_app"
+
+    def _infer_technical_complexity_bucket(
+        self, interview_data: Mapping[str, Any]
+    ) -> TechnicalComplexityBucket:
+        requirements = str(interview_data.get("requirements", "")).lower()
+        frameworks = str(interview_data.get("frameworks", "")).lower()
+
+        if any(keyword in requirements for keyword in ("machine learning", "ml", "ai")):
+            return "ml_ai"
+        if any(keyword in requirements for keyword in ("realtime", "real-time", "websocket", "streaming")):
+            return "realtime"
+        if any(keyword in requirements for keyword in ("multi region", "multi-region", "global")):
+            return "multi_region"
+        if any(keyword in requirements for keyword in ("auth", "authentication", "login")):
+            return "auth_db"
+
+        if any(keyword in frameworks for keyword in ("django", "rails", "laravel")):
+            return "auth_db"
+
+        return "simple_crud"
+
+    def _infer_integration_bucket(self, interview_data: Mapping[str, Any]) -> IntegrationBucket:
+        apis_raw = interview_data.get("apis")
+        if isinstance(apis_raw, str):
+            apis = [a for a in (p.strip() for p in apis_raw.split(",")) if a]
+        elif isinstance(apis_raw, list):
+            apis = [str(a).strip() for a in apis_raw if str(a).strip()]
+        else:
+            apis = []
+
+        count = len(apis)
+        if count == 0:
+            return "standalone"
+        if count <= 2:
+            return "1_2_services"
+        if count <= 5:
+            return "3_5_services"
+        return "6_plus_services"
+
+    def _infer_team_size_bucket(self, interview_data: Mapping[str, Any]) -> TeamSizeBucket:
+        raw = str(interview_data.get("team_size", "")).strip().lower()
+        if not raw:
+            return "solo"
+
+        if raw.isdigit():
+            size = int(raw)
+        else:
+            digits = [int(s) for s in raw.split("-") if s.isdigit()]
+            size = digits[-1] if digits else 1
+
+        if size <= 1:
+            return "solo"
+        if size <= 3:
+            return "2_3"
+        if size <= 6:
+            return "4_6"
+        return "7_plus"
+
+    def _derive_depth_level(self, score: float) -> DepthLevel:
+        if score <= 3:
+            return "minimal"
+        if score <= 7:
+            return "standard"
+        return "detailed"
+
+    def _estimate_confidence(
+        self,
+        project_type_bucket: ProjectTypeBucket,
+        technical_complexity_bucket: TechnicalComplexityBucket,
+        integration_bucket: IntegrationBucket,
+        team_size_bucket: TeamSizeBucket,
+    ) -> float:
+        buckets = [
+            project_type_bucket,
+            technical_complexity_bucket,
+            integration_bucket,
+            team_size_bucket,
+        ]
+        inferred_count = sum(1 for b in buckets if b is not None)
+        return max(0.5, min(1.0, 0.5 + 0.125 * inferred_count))
diff --git a/src/interview/interview_pipeline.py b/src/interview/interview_pipeline.py
new file mode 100644
index 0000000..0876480
--- /dev/null
+++ b/src/interview/interview_pipeline.py
@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from .complexity_analyzer import ComplexityAnalyzer, ComplexityProfile
+
+
+@dataclass
+class InterviewPipelineResult:
+    """Result of running the interview → complexity pipeline.
+
+    This is intentionally LLM-free and works purely on structured interview
+    data so that it can be fully tested with mocks.
+    """
+
+    inputs: dict[str, Any]
+    complexity_profile: ComplexityProfile
+
+
+class InterviewPipeline:
+    """Pure-Python adapter around the complexity analyzer.
+
+    In the current mock-first implementation this takes the structured
+    interview data (already extracted) and produces a `ComplexityProfile`.
+    Later, additional steps (follow-up questions, LLM-based normalization)
+    can be layered on top without changing this contract.
+    """
+
+    def __init__(self) -> None:
+        self._analyzer = ComplexityAnalyzer()
+
+    def run(self, interview_data: Mapping[str, Any]) -> InterviewPipelineResult:
+        """Run the interview → complexity pipeline on provided data.
+
+        Args:
+            interview_data: Mapping of fields gathered from the interview
+                step. This is expected to be compatible with the keys used
+                by `ComplexityAnalyzer` (e.g. project_type, requirements,
+                frameworks, apis, team_size).
+        """
+
+        normalized_inputs: dict[str, Any] = dict(interview_data)
+
+        profile = self._analyzer.analyze(normalized_inputs)
+
+        return InterviewPipelineResult(inputs=normalized_inputs, complexity_profile=profile)
diff --git a/src/llm_interview.py b/src/llm_interview.py
index 72abb20..7a67cc6 100644
--- a/src/llm_interview.py
+++ b/src/llm_interview.py
@@ -29,6 +29,7 @@
 from .ui.menu import run_menu, SessionSettings, apply_settings_to_config
 from .interview import RepoAnalysis
 from .interview.code_sample_extractor import CodeSampleExtractor, CodeSample
+from .interview.complexity_analyzer import ComplexityProfile
 from .markdown_output_manager import MarkdownOutputManager
 
 console = Console()
@@ -38,9 +39,10 @@
 class LLMInterviewManager:
     """Conducts conversational interviews using LLM.
 
-    The manager supports two modes:
+    The manager supports three modes:
     - ``"initial"`` (default): requirements-gathering interview
     - ``"design_review"``: focused review of an existing design/devplan
+    - ``"follow_up"``: clarification questions when complexity analysis has low confidence
     """
 
     SYSTEM_PROMPT = """You are a helpful development planning assistant for DevUssY, a circular development system. Your goal is to gather project requirements through natural conversation.
@@ -128,6 +130,33 @@ class LLMInterviewManager:
 }
 
 Always output that JSON block clearly (optionally inside ```json fences) once the review is complete.
+"""
+
+    # Follow-up mode system prompt for clarification questions
+    FOLLOW_UP_SYSTEM_PROMPT = """You are a helpful development planning assistant for DevUssY. The complexity analysis of the project has identified areas that need clarification.
+
+You have been given specific questions to ask the user. Your goal is to gather the missing information efficiently without re-doing the entire interview.
+
+GUIDELINES:
+- Ask the provided clarification questions one at a time
+- Be direct and specific - the user has already provided initial project information
+- Accept brief answers - you're filling in gaps, not gathering all requirements
+- If the user says "skip" or "proceed anyway", respect that and move to the next question
+- When all clarifications are gathered (or skipped), ask the user to type '/done'
+
+RESPONSE FORMAT:
+- Keep responses concise
+- Show which clarification you're asking about
+- Don't repeat questions the user has already answered
+
+When clarifications are complete, output a JSON block with the clarified data:
+{
+    "clarifications": {
+        "question_key": "user_answer",
+        ...
+    },
+    "confidence_boost": 0.1  // estimated improvement to confidence
+}
 """
 
     def __init__(
@@ -136,7 +165,7 @@ def __init__(
         verbose: bool = False,
         repo_analysis: "RepoAnalysis | None" = None,
         markdown_output_manager: "MarkdownOutputManager | None" = None,
-        mode: Literal["initial", "design_review"] = "initial",
+        mode: Literal["initial", "design_review", "follow_up"] = "initial",
     ):
         """Initialize with app config containing LLM settings.
 
@@ -147,14 +176,15 @@ def __init__(
                 conversation with concrete project context.
             markdown_output_manager: Optional markdown output manager for
                 saving responses.
-            mode: "initial" for requirements gathering, or "design_review" for
-                review of an existing design/devplan.
+            mode: "initial" for requirements gathering, "design_review" for
+                review of an existing design/devplan, or "follow_up" for
+                clarification questions.
         """
         self.config = config
         self.verbose = verbose
         self.repo_analysis = repo_analysis
         self.markdown_output_manager = markdown_output_manager
-        self.mode: Literal["initial", "design_review"] = mode
+        self.mode: Literal["initial", "design_review", "follow_up"] = mode
 
         self.llm_client = create_llm_client(config)
 
@@ -182,11 +212,17 @@ def __init__(
         # Add system prompt (core behavior), switched by mode
         if self.mode == "design_review":
             system_prompt = self.DESIGN_REVIEW_SYSTEM_PROMPT
+        elif self.mode == "follow_up":
+            system_prompt = self.FOLLOW_UP_SYSTEM_PROMPT
         else:
             system_prompt = self.SYSTEM_PROMPT
 
         self.conversation_history.append({"role": "system", "content": system_prompt})
 
+        # Store follow-up questions for follow_up mode
+        self._follow_up_questions: list[str] = []
+        self._complexity_profile: ComplexityProfile | None = None
+
         # If repository analysis is available, prepend a concise summary so the
         # interview is repo-aware without changing the primary instructions.
         if self.repo_analysis is not None:
@@ -256,6 +292,144 @@ def set_design_review_context(
 
         self._design_review_context_md = preamble + "".join(sections)
 
+    # ------------------------------------------------------------------
+    # Follow-up mode helpers (for complexity-driven clarifications)
+    # ------------------------------------------------------------------
+
+    def switch_mode(self, new_mode: Literal["initial", "design_review", "follow_up"]) -> None:
+        """Switch the interview mode and update the system prompt.
+
+        This allows transitioning from initial interview to follow-up mode
+        when the complexity analyzer detects low confidence and needs
+        clarification questions.
+
+        Args:
+            new_mode: The new mode to switch to.
+        """
+        if new_mode == self.mode:
+            return
+
+        self.mode = new_mode
+
+        # Select the appropriate system prompt
+        if new_mode == "design_review":
+            system_prompt = self.DESIGN_REVIEW_SYSTEM_PROMPT
+        elif new_mode == "follow_up":
+            system_prompt = self.FOLLOW_UP_SYSTEM_PROMPT
+        else:
+            system_prompt = self.SYSTEM_PROMPT
+
+        # Update the first system message in conversation history
+        for i, msg in enumerate(self.conversation_history):
+            if msg.get("role") == "system":
+                self.conversation_history[i] = {"role": "system", "content": system_prompt}
+                break
+
+        logger.info(f"Switched interview mode to: {new_mode}")
+
+    def set_follow_up_context(
+        self,
+        complexity_profile: ComplexityProfile,
+        follow_up_questions: list[str],
+        interview_data: Dict[str, Any] | None = None,
+    ) -> None:
+        """Set context for follow-up mode.
+
+        Args:
+            complexity_profile: The complexity profile with low confidence.
+            follow_up_questions: List of clarification questions to ask.
+            interview_data: Optional previous interview data for context.
+        """
+        self._complexity_profile = complexity_profile
+        self._follow_up_questions = follow_up_questions
+
+        # Build context message for the LLM
+        context_parts = [
+            "The complexity analysis has identified areas needing clarification.",
+            f"Current confidence: {complexity_profile.confidence:.2f}",
+            f"Complexity score: {complexity_profile.complexity_score}",
+            f"Estimated phases: {complexity_profile.estimated_phases}",
+            "",
+            "Please ask the following clarification questions:",
+        ]
+
+        for i, q in enumerate(follow_up_questions, 1):
+            context_parts.append(f"{i}. {q}")
+
+        if interview_data:
+            context_parts.append("")
+            context_parts.append("Previous interview data collected:")
+            for key, value in interview_data.items():
+                if value:
+                    context_parts.append(f"- {key}: {value}")
+
+        context_md = "\n".join(context_parts)
+
+        # Add as a system message for context
+        self.conversation_history.append({
+            "role": "system",
+            "content": context_md
+        })
+
+        logger.info(f"Set follow-up context with {len(follow_up_questions)} questions")
+
+    def request_clarifications(self, missing_context: list[str]) -> Dict[str, Any]:
+        """Request clarifications for missing context and return gathered data.
+
+        This is a simplified flow that asks follow-up questions and returns
+        the clarified data without running a full interactive loop.
+
+        Args:
+            missing_context: List of areas needing clarification.
+
+        Returns:
+            Dict with clarification responses.
+        """
+        if not missing_context:
+            return {}
+
+        self._follow_up_questions = missing_context
+        clarifications: Dict[str, Any] = {}
+
+        console.print(Panel.fit(
+            "[bold cyan]Clarification Questions[/bold cyan]\n"
+            "The complexity analysis needs more information.\n"
+            "[dim]Type 'skip' to proceed without answering.[/dim]",
+            border_style="cyan"
+        ))
+
+        for i, question in enumerate(missing_context, 1):
+            console.print(f"\n[yellow]Question {i}/{len(missing_context)}:[/yellow]")
+            console.print(f"[white]{question}[/white]")
+
+            try:
+                if sys.stdin.isatty() and sys.stdout.isatty():
+                    answer = pt_prompt("Your answer: ")
+                else:
+                    answer = Prompt.ask("Your answer", default="")
+            except Exception:
+                answer = Prompt.ask("Your answer", default="")
+
+            if answer.lower().strip() in ("skip", "proceed", "continue", ""):
+                logger.info(f"User skipped clarification question: {question}")
+                continue
+
+            # Store clarification with a key based on the question
+            key = self._question_to_key(question)
+            clarifications[key] = answer
+            logger.info(f"Collected clarification for '{key}': {answer[:50]}...")
+
+        return clarifications
+
+    def _question_to_key(self, question: str) -> str:
+        """Convert a question to a simple key for storage."""
+        # Extract key words and create a snake_case key
+        words = re.findall(r'\b\w+\b', question.lower())
+        # Take significant words, skip common ones
+        skip_words = {"what", "is", "the", "are", "how", "do", "you", "your", "a", "an", "to", "for", "of"}
+        key_words = [w for w in words if w not in skip_words][:3]
+        return "_".join(key_words) if key_words else "clarification"
+
     def _apply_client_debug(self, enabled: bool) -> None:
         """Best-effort propagation of a debug/verbose flag to the underlying LLM client.
 
diff --git a/src/pipeline/compose.py b/src/pipeline/compose.py
index b4086b5..83af513 100644
--- a/src/pipeline/compose.py
+++ b/src/pipeline/compose.py
@@ -2,8 +2,9 @@
 
 from __future__ import annotations
 
+from dataclasses import asdict
 from pathlib import Path
-from typing import Any, List, Optional, Tuple
+from typing import Any, List, Mapping, Optional, Tuple
 
 from ..clients.factory import create_llm_client
 from ..concurrency import ConcurrencyManager
@@ -16,10 +17,14 @@
 from ..progress_reporter import PipelineProgressReporter
 from ..state_manager import StateManager
 from ..markdown_output_manager import MarkdownOutputManager
+from ..interview.complexity_analyzer import ComplexityAnalyzer, ComplexityProfile
 from .basic_devplan import BasicDevPlanGenerator
+from .design_correction_loop import DesignCorrectionLoop, DesignCorrectionResult
+from .design_validator import DesignValidator, DesignValidationReport
 from .detailed_devplan import DetailedDevPlanGenerator, PhaseDetailResult
 from .handoff_prompt import HandoffPromptGenerator
 from .design_review import DesignReviewRefiner
+from .llm_sanity_reviewer import LLMSanityReviewer, LLMSanityReviewResult
 from .project_design import ProjectDesignGenerator
 
 logger = get_logger(__name__)
@@ -1407,3 +1412,537 @@ def _update_progress_tokens(self, llm_client: LLMClient) -> None:
                 self.progress_reporter.update_tokens(usage)
         except Exception as e:
             logger.debug(f"Could not update progress tokens: {e}")
+
+    # -------------------------------------------------------------------------
+    # Adaptive Pipeline Methods
+    # -------------------------------------------------------------------------
+
+    def analyze_complexity(
+        self,
+        interview_data: Mapping[str, Any],
+    ) -> ComplexityProfile:
+        """Analyze interview data to determine project complexity.
+
+        This uses the rule-based ComplexityAnalyzer for deterministic results.
+        In production with LLM integration, this would also incorporate
+        LLM-driven semantic analysis.
+
+        Args:
+            interview_data: Dictionary with project details from interview
+
+        Returns:
+            ComplexityProfile with score, phase count, and depth level
+        """
+        logger.info("Analyzing project complexity from interview data")
+        self.progress_reporter.start_stage("Complexity Analysis", 0)
+        
+        analyzer = ComplexityAnalyzer()
+        profile = analyzer.analyze(interview_data)
+        
+        logger.info(
+            f"Complexity analysis complete: score={profile.score:.1f}, "
+            f"phases={profile.estimated_phase_count}, depth={profile.depth_level}"
+        )
+        self.progress_reporter.end_stage("Complexity Analysis")
+        
+        return profile
+
+    def validate_design(
+        self,
+        design_text: str,
+        requirements_text: Optional[str] = None,
+        complexity_profile: Optional[ComplexityProfile] = None,
+    ) -> DesignValidationReport:
+        """Validate a design document against rule-based checks.
+
+        Args:
+            design_text: The design document text to validate
+            requirements_text: Optional requirements for scope alignment
+            complexity_profile: Optional complexity profile for scaling checks
+
+        Returns:
+            DesignValidationReport with issues and check results
+        """
+        logger.info("Validating design document")
+        self.progress_reporter.start_stage("Design Validation", 0)
+        
+        validator = DesignValidator()
+        report = validator.validate(
+            design_text,
+            requirements_text=requirements_text,
+            complexity_profile=complexity_profile,
+        )
+        
+        if report.is_valid:
+            logger.info("Design validation passed")
+        else:
+            logger.warning(
+                f"Design validation found {len(report.issues)} issues, "
+                f"auto_correctable={report.auto_correctable}"
+            )
+        
+        self.progress_reporter.end_stage("Design Validation")
+        return report
+
+    def review_design_with_llm(
+        self,
+        design_text: str,
+        validation_report: DesignValidationReport,
+    ) -> LLMSanityReviewResult:
+        """Perform LLM-based semantic review of a design.
+
+        Currently uses mock implementation. Will integrate with actual
+        LLM when real LLM review prompts are ready.
+
+        Args:
+            design_text: The design document text
+            validation_report: Results from rule-based validation
+
+        Returns:
+            LLMSanityReviewResult with confidence and risk assessment
+        """
+        logger.info("Performing LLM sanity review of design")
+        
+        reviewer = LLMSanityReviewer()
+        result = reviewer.review(design_text, validation_report)
+        
+        logger.info(f"LLM review complete: confidence={result.confidence:.2f}")
+        return result
+
+    def run_correction_loop(
+        self,
+        design_text: str,
+        complexity_profile: Optional[ComplexityProfile] = None,
+    ) -> DesignCorrectionResult:
+        """Run the iterative design correction loop.
+
+        Validates and reviews the design, applies corrections up to MAX_ITERATIONS
+        times until the design passes or requires human review.
+
+        Args:
+            design_text: Initial design document text
+            complexity_profile: Optional complexity profile for validation
+
+        Returns:
+            DesignCorrectionResult with final design and status
+        """
+        logger.info("Starting design correction loop")
+        self.progress_reporter.start_stage("Design Correction", 0)
+        
+        loop = DesignCorrectionLoop()
+        result = loop.run(design_text, complexity_profile=complexity_profile)
+        
+        if result.requires_human_review:
+            logger.warning("Correction loop requires human review")
+        elif result.max_iterations_reached:
+            logger.warning("Correction loop reached max iterations")
+        else:
+            logger.info("Correction loop completed successfully")
+        
+        self.progress_reporter.end_stage("Design Correction")
+        return result
+
+    async def run_adaptive_pipeline(
+        self,
+        project_name: str,
+        languages: List[str],
+        requirements: str,
+        interview_data: Mapping[str, Any],
+        frameworks: Optional[List[str]] = None,
+        apis: Optional[List[str]] = None,
+        output_dir: str = ".",
+        save_artifacts: bool = True,
+        enable_validation: bool = True,
+        enable_correction: bool = True,
+        **llm_kwargs: Any,
+    ) -> Tuple[ProjectDesign, DevPlan, HandoffPrompt, Optional[ComplexityProfile]]:
+        """Run the full adaptive pipeline with complexity analysis and validation.
+
+        This extends the standard pipeline with:
+        1. Complexity analysis before design generation
+        2. Design validation after generation
+        3. Iterative correction loop if issues found
+        4. Scaled output based on complexity profile
+
+        Args:
+            project_name: Name of the project
+            languages: Programming languages to use
+            requirements: Project requirements
+            interview_data: Full interview data for complexity analysis
+            frameworks: Optional frameworks
+            apis: Optional external APIs
+            output_dir: Directory to save artifacts
+            save_artifacts: Whether to save intermediate files
+            enable_validation: Whether to validate design
+            enable_correction: Whether to run correction loop
+            **llm_kwargs: Additional LLM parameters
+
+        Returns:
+            Tuple of (ProjectDesign, DevPlan, HandoffPrompt, ComplexityProfile)
+        """
+        logger.info(f"Starting adaptive pipeline for project: {project_name}")
+        
+        # Show pipeline start
+        self.progress_reporter.start_pipeline(project_name)
+        self.progress_reporter.start_status()
+
+        # Stage 0: Complexity Analysis
+        complexity_profile = self.analyze_complexity(interview_data)
+        
+        # Save checkpoint after complexity analysis
+        try:
+            self.state_manager.save_checkpoint(
+                checkpoint_key=f"{project_name}_adaptive_pipeline",
+                stage="complexity_analysis",
+                data={
+                    "complexity_profile": asdict(complexity_profile),
+                    "project_name": project_name,
+                    "languages": languages,
+                    "requirements": requirements,
+                    "frameworks": frameworks,
+                    "apis": apis,
+                    "interview_data": dict(interview_data),
+                },
+                metadata={
+                    "provider": self.get_current_provider(),
+                    "output_dir": output_dir,
+                    "enable_validation": enable_validation,
+                    "enable_correction": enable_correction,
+                },
+            )
+            logger.info("Saved checkpoint after complexity analysis")
+            self.progress_reporter.show_checkpoint_saved(
+                f"{project_name}_adaptive_pipeline", "complexity_analysis"
+            )
+        except Exception as e:
+            logger.warning(f"Failed to save checkpoint after complexity analysis: {e}")
+
+        # Save complexity profile artifact
+        if save_artifacts:
+            complexity_md = self._complexity_profile_to_markdown(complexity_profile)
+            self.file_manager.write_markdown(
+                f"{output_dir}/complexity_profile.md", complexity_md
+            )
+            logger.info("Saved complexity_profile.md")
+            self.progress_reporter.report_file_created(
+                f"{output_dir}/complexity_profile.md",
+                "Complexity Profile",
+                len(complexity_md),
+            )
+
+        # Stage 1: Generate project design (with complexity awareness)
+        self.progress_reporter.start_stage("Project Design", 1)
+        logger.info("Stage 1/5: Generating project design")
+        
+        with self.progress_reporter.create_spinner_context("Generating project design..."):
+            project_design = await self.project_design_gen.generate(
+                project_name=project_name,
+                languages=languages,
+                requirements=requirements,
+                frameworks=frameworks,
+                apis=apis,
+                **llm_kwargs,
+            )
+        
+        self._update_progress_tokens(self.design_client)
+        self.progress_reporter.end_stage("Project Design")
+
+        design_text = project_design.architecture_overview or ""
+
+        # Stage 2: Design Validation (if enabled)
+        validation_report: Optional[DesignValidationReport] = None
+        correction_result: Optional[DesignCorrectionResult] = None
+
+        if enable_validation:
+            self.progress_reporter.start_stage("Design Validation", 2)
+            validation_report = self.validate_design(
+                design_text,
+                requirements_text=requirements,
+                complexity_profile=complexity_profile,
+            )
+            self.progress_reporter.end_stage("Design Validation")
+
+            # Save validation report
+            if save_artifacts and validation_report:
+                validation_md = self._validation_report_to_markdown(validation_report)
+                self.file_manager.write_markdown(
+                    f"{output_dir}/validation_report.md", validation_md
+                )
+                self.progress_reporter.report_file_created(
+                    f"{output_dir}/validation_report.md",
+                    "Validation Report",
+                    len(validation_md),
+                )
+
+            # Stage 3: Correction Loop (if enabled and validation failed)
+            if enable_correction and validation_report and not validation_report.is_valid:
+                correction_result = self.run_correction_loop(
+                    design_text,
+                    complexity_profile=complexity_profile,
+                )
+                
+                # Update design with corrected version
+                if correction_result.design_text != design_text:
+                    # Update architecture overview with corrections
+                    project_design.architecture_overview = correction_result.design_text
+                    logger.info("Applied corrections to project design")
+                
+                # Save correction history
+                if save_artifacts:
+                    correction_md = self._correction_result_to_markdown(correction_result)
+                    self.file_manager.write_markdown(
+                        f"{output_dir}/correction_history.md", correction_md
+                    )
+                    self.progress_reporter.report_file_created(
+                        f"{output_dir}/correction_history.md",
+                        "Correction History",
+                        len(correction_md),
+                    )
+
+        # Save checkpoint after design stage
+        try:
+            checkpoint_data: dict[str, Any] = {
+                "complexity_profile": asdict(complexity_profile),
+                "project_design": project_design.model_dump(),
+                "project_name": project_name,
+                "languages": languages,
+                "requirements": requirements,
+                "frameworks": frameworks,
+                "apis": apis,
+            }
+            if validation_report:
+                checkpoint_data["validation_report"] = {
+                    "is_valid": validation_report.is_valid,
+                    "auto_correctable": validation_report.auto_correctable,
+                    "issues": [
+                        {"code": i.code, "message": i.message, "auto_correctable": i.auto_correctable}
+                        for i in validation_report.issues
+                    ],
+                    "checks": validation_report.checks,
+                }
+            if correction_result:
+                checkpoint_data["correction_result"] = {
+                    "requires_human_review": correction_result.requires_human_review,
+                    "max_iterations_reached": correction_result.max_iterations_reached,
+                }
+            
+            self.state_manager.save_checkpoint(
+                checkpoint_key=f"{project_name}_adaptive_pipeline",
+                stage="project_design",
+                data=checkpoint_data,
+                metadata={
+                    "provider": self.get_current_provider(),
+                    "output_dir": output_dir,
+                },
+            )
+            logger.info("Saved checkpoint after project design")
+        except Exception as e:
+            logger.warning(f"Failed to save checkpoint after project design: {e}")
+
+        if save_artifacts:
+            design_md_lines = [
+                f"# Project Design: {project_name}\n",
+                f"## Complexity: {complexity_profile.depth_level.capitalize()} ({complexity_profile.score:.1f})\n",
+                f"## Architecture Overview\n\n{project_design.architecture_overview or 'No design generated'}\n",
+                "## Tech Stack\n"
+            ]
+            for tech in project_design.tech_stack:
+                design_md_lines.append(f"- {tech}")
+            
+            if project_design.objectives:
+                design_md_lines.append("\n## Objectives\n")
+                for obj in project_design.objectives:
+                    design_md_lines.append(f"- {obj}")
+
+            design_content = "\n".join(design_md_lines)
+            self.file_manager.write_markdown(
+                f"{output_dir}/project_design.md", design_content
+            )
+            self.progress_reporter.report_file_created(
+                f"{output_dir}/project_design.md",
+                "Project Design",
+                len(design_content),
+            )
+
+        # Stage 4: Generate devplan (with complexity-aware phase count)
+        self.progress_reporter.start_stage("DevPlan Generation", 4)
+        logger.info(f"Stage 4/5: Generating devplan ({complexity_profile.estimated_phase_count} phases)")
+        
+        # Add code samples to kwargs if available
+        if self.code_samples:
+            llm_kwargs["code_samples"] = self.code_samples
+        
+        with self.progress_reporter.create_spinner_context("Creating basic development plan..."):
+            basic_devplan = await self.basic_devplan_gen.generate(
+                project_design,
+                repo_analysis=self.repo_analysis,
+                **llm_kwargs,
+            )
+        
+        self._update_progress_tokens(self.devplan_client)
+
+        # Generate detailed phases
+        total_phases = len({p.number for p in basic_devplan.phases})
+        self.progress_reporter.show_concurrent_phases(total_phases)
+        self.progress_reporter.start_phase_progress(total_phases, description="Generating detailed phases")
+        
+        def _handle_phase_complete(event: PhaseDetailResult) -> None:
+            try:
+                self.progress_reporter.advance_phase()
+                self.progress_reporter.report_phase_ready(
+                    phase_number=event.phase.number,
+                    steps=len(event.phase.steps),
+                    char_count=event.response_chars,
+                )
+            except Exception:
+                pass
+
+        with self.progress_reporter.create_spinner_context("Generating detailed phase plans..."):
+            detailed_devplan = await self.detailed_devplan_gen.generate(
+                basic_devplan,
+                project_name,
+                project_design.tech_stack,
+                repo_analysis=self.repo_analysis,
+                on_phase_complete=_handle_phase_complete,
+                **llm_kwargs,
+            )
+        
+        self.progress_reporter.stop_phase_progress()
+        self._update_progress_tokens(self.devplan_client)
+        self.progress_reporter.end_stage("DevPlan Generation")
+
+        # Save devplan checkpoint
+        try:
+            self.state_manager.save_checkpoint(
+                checkpoint_key=f"{project_name}_adaptive_pipeline",
+                stage="detailed_devplan",
+                data={
+                    "complexity_profile": asdict(complexity_profile),
+                    "project_design": project_design.model_dump(),
+                    "basic_devplan": basic_devplan.model_dump(),
+                    "detailed_devplan": detailed_devplan.model_dump(),
+                    "project_name": project_name,
+                },
+                metadata={
+                    "provider": self.get_current_provider(),
+                    "output_dir": output_dir,
+                },
+            )
+            logger.info("Saved checkpoint after detailed devplan")
+        except Exception as e:
+            logger.warning(f"Failed to save checkpoint: {e}")
+
+        if save_artifacts:
+            devplan_md = self._devplan_to_markdown(detailed_devplan)
+            ok, written_path = self.file_manager.safe_write_devplan(
+                f"{output_dir}/devplan.md", devplan_md
+            )
+            if ok:
+                self.progress_reporter.report_file_created(
+                    written_path, "DevPlan Dashboard", len(devplan_md)
+                )
+            
+            # Generate individual phase files
+            phase_files = self._generate_phase_files(detailed_devplan, output_dir)
+            logger.info(f"Generated {len(phase_files)} individual phase files")
+
+        # Stage 5: Generate handoff prompt
+        self.progress_reporter.start_stage("Handoff Prompt", 5)
+        logger.info("Stage 5/5: Generating handoff prompt")
+        
+        handoff_kwargs = {
+            "project_summary": detailed_devplan.summary or "",
+            "architecture_notes": project_design.architecture_overview or "",
+            "complexity_info": f"Complexity: {complexity_profile.depth_level} ({complexity_profile.score:.1f})",
+        }
+        if self.code_samples:
+            handoff_kwargs["code_samples"] = self.code_samples
+        
+        with self.progress_reporter.create_spinner_context("Composing handoff prompt..."):
+            handoff = self.handoff_gen.generate(
+                devplan=detailed_devplan,
+                project_name=project_name,
+                repo_analysis=self.repo_analysis,
+                **handoff_kwargs,
+            )
+        
+        self.progress_reporter.end_stage("Handoff Prompt")
+
+        if save_artifacts:
+            self.file_manager.write_markdown(
+                f"{output_dir}/handoff_prompt.md", handoff.content
+            )
+            self.progress_reporter.report_file_created(
+                f"{output_dir}/handoff_prompt.md",
+                "Handoff Prompt",
+                len(handoff.content),
+            )
+
+        logger.info("Adaptive pipeline complete!")
+        self.progress_reporter.display_summary()
+        
+        return project_design, detailed_devplan, handoff, complexity_profile
+
+    def _complexity_profile_to_markdown(self, profile: ComplexityProfile) -> str:
+        """Convert ComplexityProfile to markdown format."""
+        lines = [
+            "# Complexity Profile\n",
+            f"**Score**: {profile.score:.1f}/20\n",
+            f"**Depth Level**: {profile.depth_level}\n",
+            f"**Estimated Phases**: {profile.estimated_phase_count}\n",
+            f"**Confidence**: {profile.confidence:.0%}\n",
+            "\n## Buckets\n",
+            f"- **Project Type**: {profile.project_type_bucket}\n",
+            f"- **Technical Complexity**: {profile.technical_complexity_bucket}\n",
+            f"- **Integration**: {profile.integration_bucket}\n",
+            f"- **Team Size**: {profile.team_size_bucket}\n",
+            f"\n*Generated: {self._get_timestamp()}*\n",
+        ]
+        return "".join(lines)
+
+    def _validation_report_to_markdown(self, report: DesignValidationReport) -> str:
+        """Convert DesignValidationReport to markdown format."""
+        lines = [
+            "# Design Validation Report\n",
+            f"**Valid**: {'Yes' if report.is_valid else 'No'}\n",
+            f"**Auto-Correctable**: {'Yes' if report.auto_correctable else 'No'}\n",
+            "\n## Checks\n",
+        ]
+        for check_name, passed in report.checks.items():
+            status = "[PASS]" if passed else "[FAIL]"
+            lines.append(f"- {status} {check_name}\n")
+        
+        if report.issues:
+            lines.append("\n## Issues\n")
+            for issue in report.issues:
+                auto = "(auto-correctable)" if issue.auto_correctable else "(requires manual review)"
+                lines.append(f"- **{issue.code}** {auto}: {issue.message}\n")
+        
+        lines.append(f"\n*Generated: {self._get_timestamp()}*\n")
+        return "".join(lines)
+
+    def _correction_result_to_markdown(self, result: DesignCorrectionResult) -> str:
+        """Convert DesignCorrectionResult to markdown format."""
+        lines = [
+            "# Design Correction History\n",
+            f"**Final Status**: ",
+        ]
+        if result.requires_human_review:
+            lines.append("Requires Human Review\n")
+        elif result.max_iterations_reached:
+            lines.append("Max Iterations Reached\n")
+        else:
+            lines.append("Corrected Successfully\n")
+        
+        lines.extend([
+            f"\n**Final Validation**: {'Passed' if result.validation.is_valid else 'Failed'}\n",
+            f"**Review Confidence**: {result.review.confidence:.0%}\n",
+        ])
+        
+        if result.review.risks:
+            lines.append("\n## Remaining Risks\n")
+            for risk in result.review.risks:
+                lines.append(f"- {risk}\n")
+        
+        lines.append(f"\n*Generated: {self._get_timestamp()}*\n")
+        return "".join(lines)
diff --git a/src/pipeline/design_correction_loop.py b/src/pipeline/design_correction_loop.py
new file mode 100644
index 0000000..051bb68
--- /dev/null
+++ b/src/pipeline/design_correction_loop.py
@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Tuple
+
+from src.interview.complexity_analyzer import ComplexityProfile
+from .design_validator import DesignValidator, DesignValidationReport
+from .llm_sanity_reviewer import LLMSanityReviewer, LLMSanityReviewResult
+
+
+MAX_ITERATIONS = 3
+CONFIDENCE_THRESHOLD = 0.8
+
+
+@dataclass
+class DesignCorrectionResult:
+    design_text: str
+    validation: DesignValidationReport
+    review: LLMSanityReviewResult
+    requires_human_review: bool = False
+    max_iterations_reached: bool = False
+
+
+class DesignCorrectionLoop:
+    """Pure-Python implementation of the correction loop.
+
+    This mirrors the control flow from the handoff spec but uses a simple
+    deterministic "apply_corrections" step so that we can test convergence
+    behavior without hitting an LLM.
+    """
+
+    def __init__(self) -> None:
+        self._validator = DesignValidator()
+        self._reviewer = LLMSanityReviewer()
+
+    def run(
+        self,
+        design_text: str,
+        complexity_profile: ComplexityProfile | None = None,
+    ) -> DesignCorrectionResult:
+        current_design = design_text
+
+        for _ in range(MAX_ITERATIONS):
+            validation = self._validator.validate(
+                current_design,
+                complexity_profile=complexity_profile,
+            )
+            review = self._reviewer.review(current_design, validation)
+
+            if validation.is_valid and review.confidence > CONFIDENCE_THRESHOLD:
+                return DesignCorrectionResult(
+                    design_text=current_design,
+                    validation=validation,
+                    review=review,
+                )
+
+            if not validation.auto_correctable:
+                return DesignCorrectionResult(
+                    design_text=current_design,
+                    validation=validation,
+                    review=review,
+                    requires_human_review=True,
+                )
+
+            current_design = self._apply_corrections(current_design, validation, review)
+
+        # Max iterations reached
+        final_validation = self._validator.validate(
+            current_design,
+            complexity_profile=complexity_profile,
+        )
+        final_review = self._reviewer.review(current_design, final_validation)
+        return DesignCorrectionResult(
+            design_text=current_design,
+            validation=final_validation,
+            review=final_review,
+            max_iterations_reached=True,
+        )
+
+    def _apply_corrections(
+        self,
+        design_text: str,
+        validation: DesignValidationReport,
+        review: LLMSanityReviewResult,
+    ) -> str:
+        """Deterministic placeholder for design corrections.
+
+        For now, this simply appends a small "Corrections applied" footer so
+        we can observe that the loop made progress. Real implementations will
+        rewrite sections based on validation/report details.
+        """
+
+        footer_lines = ["\n\n---", "Corrections applied based on validation checks."]
+        for issue in validation.issues:
+            if issue.auto_correctable:
+                footer_lines.append(f"- Resolved: {issue.code}")
+
+        if review.risks:
+            footer_lines.append("- Remaining risks: " + ", ".join(review.risks))
+
+        return design_text + "\n" + "\n".join(footer_lines)
diff --git a/src/pipeline/design_generator.py b/src/pipeline/design_generator.py
new file mode 100644
index 0000000..aea6866
--- /dev/null
+++ b/src/pipeline/design_generator.py
@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader
+
+from src.interview.complexity_analyzer import ComplexityProfile
+
+
+def _get_templates_dir() -> Path:
+    """Get the templates directory path."""
+    return Path(__file__).resolve().parents[2] / "templates"
+
+
+class AdaptiveDesignGenerator:
+    """Adaptive design generator with complexity-aware output.
+
+    This implementation can operate in two modes:
+    1. Mock mode (default): Produces deterministic markdown without LLM calls
+    2. Template mode: Uses Jinja templates for structured output
+
+    The size and level of detail vary based on the provided ``ComplexityProfile``.
+    """
+
+    def __init__(self, use_templates: bool = False):
+        """Initialize the generator.
+
+        Args:
+            use_templates: If True, use Jinja templates for output generation.
+        """
+        self.use_templates = use_templates
+        if use_templates:
+            templates_dir = _get_templates_dir()
+            self._env = Environment(
+                loader=FileSystemLoader(str(templates_dir)),
+                autoescape=False,
+                trim_blocks=True,
+                lstrip_blocks=True,
+            )
+
+    def generate(
+        self,
+        profile: ComplexityProfile,
+        project_label: str = "project",
+        **context: Any,
+    ) -> str:
+        """Generate a design document for the given complexity profile.
+
+        Args:
+            profile: Complexity profile computed from interview data.
+            project_label: Human-readable label for the project.
+            **context: Additional context variables for template rendering.
+
+        Returns:
+            Markdown string describing the system design.
+        """
+        if self.use_templates:
+            return self._generate_from_template(profile, project_label, **context)
+        return self._generate_mock(profile, project_label)
+
+    def _generate_from_template(
+        self,
+        profile: ComplexityProfile,
+        project_label: str,
+        **context: Any,
+    ) -> str:
+        """Generate design using Jinja templates."""
+        template = self._env.get_template("design/adaptive_design.jinja2")
+
+        template_context = {
+            "complexity_profile": {
+                "complexity_score": profile.score,
+                "estimated_phases": profile.estimated_phase_count,
+                "depth_level": profile.depth_level,
+                "project_scale": self._get_project_scale(profile.score),
+                "risk_factors": getattr(profile, "risk_factors", []),
+                "confidence": profile.confidence,
+            },
+            "project_name": project_label,
+            **context,
+        }
+
+        return template.render(**template_context)
+
+    def _get_project_scale(self, score: float) -> str:
+        """Map complexity score to project scale label."""
+        if score <= 3:
+            return "trivial"
+        elif score <= 7:
+            return "simple"
+        elif score <= 12:
+            return "medium"
+        elif score <= 16:
+            return "complex"
+        else:
+            return "enterprise"
+
+    def _generate_mock(self, profile: ComplexityProfile, project_label: str) -> str:
+        """Generate a mock design document (original implementation).
+
+        Args:
+            profile: Complexity profile computed from interview data.
+            project_label: Human-readable label for the project.
+
+        Returns:
+            Markdown string describing a mock system design.
+        """
+        header = f"# Adaptive Design for {project_label}\n\n"
+
+        base_sections: list[str] = [
+            "## Architecture\n\n"
+            "High-level architecture for the project, focused on core components.",
+            "## Data Model\n\n"
+            "Overview of key entities and relationships.",
+            "## Testing\n\n"
+            "Strategy for unit and integration tests.",
+        ]
+
+        if profile.depth_level == "minimal":
+            body = "\n\n".join(base_sections)
+        elif profile.depth_level == "standard":
+            standard_sections: list[str] = base_sections + [
+                "## Deployment\n\n"
+                "Basic deployment approach and environments.",
+                "## Dependencies\n\n"
+                "Important libraries, services, and integration points.",
+            ]
+            body = "\n\n".join(standard_sections)
+        else:
+            detailed_sections: list[str] = base_sections + [
+                "## Deployment\n\n"
+                "Detailed deployment topology, environments, and rollout strategy.",
+                "## Security\n\n"
+                "Authentication, authorization, and data protection measures.",
+                "## Scalability & Reliability\n\n"
+                "Approach to horizontal scaling, resilience, and observability.",
+                "## CI/CD & Tooling\n\n"
+                "Pipelines, checks, and automation supporting the project.",
+            ]
+            body = "\n\n".join(detailed_sections)
+
+        footer = (
+            "\n\n---\n"
+            f"Complexity score: {profile.score:.1f} "
+            f"| Estimated phases: {profile.estimated_phase_count} "
+            f"| Depth: {profile.depth_level} "
+            f"| Confidence: {profile.confidence:.2f}\n"
+        )
+
+        return header + body + footer
diff --git a/src/pipeline/design_validator.py b/src/pipeline/design_validator.py
new file mode 100644
index 0000000..d018e23
--- /dev/null
+++ b/src/pipeline/design_validator.py
@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Dict, Any, Optional
+
+from src.interview.complexity_analyzer import ComplexityProfile
+
+
+@dataclass
+class DesignValidationIssue:
+    code: str
+    message: str
+    auto_correctable: bool = True
+
+
+@dataclass
+class DesignValidationReport:
+    is_valid: bool
+    auto_correctable: bool
+    issues: List[DesignValidationIssue]
+    checks: Dict[str, bool]
+
+
+class DesignValidator:
+    """Deterministic rule-based validation of a design document.
+
+    This mock-first implementation relies purely on string heuristics and
+    simple checks so it can be tested without any LLM calls.
+    """
+
+    def validate(
+        self,
+        design_text: str,
+        requirements_text: Optional[str] = None,
+        complexity_profile: Optional[ComplexityProfile] = None,
+    ) -> DesignValidationReport:
+        issues: List[DesignValidationIssue] = []
+        checks: Dict[str, bool] = {}
+
+        text = design_text.strip().lower()
+
+        # 1) Consistency check: ensure we do not see obvious contradictory phrases
+        inconsistent = "must be monolith" in text and "microservices" in text
+        checks["consistency"] = not inconsistent
+        if inconsistent:
+            issues.append(
+                DesignValidationIssue(
+                    code="consistency.conflict_monolith_microservices",
+                    message="Design mentions both strict monolith and microservices.",
+                    auto_correctable=False,
+                )
+            )
+
+        # 2) Completeness check: require at least minimal sections
+        has_arch = "architecture" in text or "architecture overview" in text
+        has_data = "data model" in text or "database" in text
+        has_testing = "testing" in text
+        checks["completeness"] = has_arch and has_data and has_testing
+        if not checks["completeness"]:
+            issues.append(
+                DesignValidationIssue(
+                    code="completeness.missing_sections",
+                    message="Design is missing architecture, data model, or testing details.",
+                    auto_correctable=True,
+                )
+            )
+
+        # 3) Scope alignment check: very rough heuristic with complexity_profile
+        if complexity_profile is not None:
+            # For high complexity scores, require mention of scalability or reliability
+            requires_scaling = complexity_profile.score >= 7
+            mentions_scaling = "scalab" in text or "high availability" in text
+            scope_ok = not requires_scaling or mentions_scaling
+            checks["scope_alignment"] = scope_ok
+            if not scope_ok:
+                issues.append(
+                    DesignValidationIssue(
+                        code="scope_alignment.missing_scalability",
+                        message="Complex project without scalability or reliability discussion.",
+                        auto_correctable=True,
+                    )
+                )
+        else:
+            checks["scope_alignment"] = True
+
+        # 4) Hallucination detection (very simple): flag TODO:API_NAME style markers
+        hallucinated = "FAKE_API" in design_text or "<fictional-api>" in design_text
+        checks["hallucination"] = not hallucinated
+        if hallucinated:
+            issues.append(
+                DesignValidationIssue(
+                    code="hallucination.suspect_api",
+                    message="Design appears to reference placeholder or fictional APIs.",
+                    auto_correctable=True,
+                )
+            )
+
+        # 5) Over-engineering detection: small projects using heavy patterns
+        over_engineered = False
+        if complexity_profile is not None:
+            if complexity_profile.score <= 3:
+                if "event sourcing" in text or "cqrs" in text or "microservices" in text:
+                    over_engineered = True
+        checks["over_engineering"] = not over_engineered
+        if over_engineered:
+            issues.append(
+                DesignValidationIssue(
+                    code="over_engineering.complex_patterns_for_simple_project",
+                    message="Trivial project uses heavy patterns like microservices/CQRS/event sourcing.",
+                    auto_correctable=True,
+                )
+            )
+
+        is_valid = all(checks.values())
+        auto_correctable = is_valid or all(issue.auto_correctable for issue in issues)
+
+        return DesignValidationReport(
+            is_valid=is_valid,
+            auto_correctable=auto_correctable,
+            issues=issues,
+            checks=checks,
+        )
diff --git a/src/pipeline/devplan_generator.py b/src/pipeline/devplan_generator.py
new file mode 100644
index 0000000..9227d9e
--- /dev/null
+++ b/src/pipeline/devplan_generator.py
@@ -0,0 +1,294 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, List
+
+from jinja2 import Environment, FileSystemLoader
+
+from src.interview.complexity_analyzer import ComplexityProfile
+from src.models import DevPlan, DevPlanPhase
+
+
+def _get_templates_dir() -> Path:
+    """Get the templates directory path."""
+    return Path(__file__).resolve().parents[2] / "templates"
+
+
+class AdaptiveDevPlanGenerator:
+    """Adaptive devplan generator with complexity-aware phase generation.
+
+    This generator creates a ``DevPlan`` from a ``ComplexityProfile``.
+    It supports both mock mode (deterministic output) and template mode
+    (Jinja templates for phase rendering).
+    """
+
+    def __init__(self, use_templates: bool = False):
+        """Initialize the generator.
+
+        Args:
+            use_templates: If True, use Jinja templates for phase rendering.
+        """
+        self.use_templates = use_templates
+        if use_templates:
+            templates_dir = _get_templates_dir()
+            self._env = Environment(
+                loader=FileSystemLoader(str(templates_dir)),
+                autoescape=False,
+                trim_blocks=True,
+                lstrip_blocks=True,
+            )
+
+    def generate(
+        self,
+        profile: ComplexityProfile,
+        project_label: str = "project",
+        **context: Any,
+    ) -> DevPlan:
+        """Generate a devplan based on the given profile.
+
+        Args:
+            profile: Complexity profile with phase count and depth.
+            project_label: Human-readable label for the project.
+            **context: Additional context variables for template rendering.
+
+        Returns:
+            ``DevPlan`` instance with phases.
+        """
+        phase_count = max(1, int(profile.estimated_phase_count or 1))
+        names = self._phase_names_for_count(phase_count)
+
+        phases: list[DevPlanPhase] = []
+        for idx, name in enumerate(names, start=1):
+            description = self._generate_phase_description(
+                phase_number=idx,
+                phase_name=name,
+                depth_level=profile.depth_level,
+                **context,
+            )
+            phases.append(
+                DevPlanPhase(
+                    number=idx,
+                    title=f"Phase {idx}: {name}",
+                    description=description,
+                    steps=[],
+                )
+            )
+
+        summary = (
+            f"Adaptive devplan for {project_label} with {phase_count} phases "
+            f"(depth={profile.depth_level})."
+        )
+        return DevPlan(phases=phases, summary=summary)
+
+    def _generate_phase_description(
+        self,
+        phase_number: int,
+        phase_name: str,
+        depth_level: str,
+        **context: Any,
+    ) -> str | None:
+        """Generate phase description based on depth level.
+
+        Args:
+            phase_number: The phase number (1-indexed).
+            phase_name: The name of the phase.
+            depth_level: "minimal", "standard", or "detailed".
+            **context: Additional context for template rendering.
+
+        Returns:
+            Phase description string, or None for minimal mock mode.
+        """
+        if not self.use_templates:
+            # Mock mode: minimal descriptions
+            if depth_level == "minimal":
+                return None
+            elif depth_level == "standard":
+                return f"Implement {phase_name.lower()} functionality."
+            else:
+                return (
+                    f"Comprehensive implementation of {phase_name.lower()} "
+                    f"with full testing, documentation, and quality checks."
+                )
+
+        # Template mode: use appropriate template
+        template_name = f"devplan/phase_{depth_level}.jinja2"
+        try:
+            template = self._env.get_template(template_name)
+        except Exception:
+            # Fall back to standard template
+            template = self._env.get_template("devplan/phase_standard.jinja2")
+
+        template_context = {
+            "phase_number": phase_number,
+            "phase_name": phase_name,
+            "phase_description": f"Implement {phase_name.lower()} functionality.",
+            "phase_goal": f"Complete all {phase_name.lower()} work items.",
+            "tasks": self._generate_tasks_for_phase(phase_name, depth_level),
+            "test_strategy": self._generate_test_strategy(depth_level),
+            "acceptance_criteria": self._generate_acceptance_criteria(phase_name),
+            **context,
+        }
+
+        return template.render(**template_context)
+
+    def _generate_tasks_for_phase(self, phase_name: str, depth_level: str) -> list[Any]:
+        """Generate task list for a phase based on depth level."""
+        base_tasks = [
+            f"Set up {phase_name.lower()} environment",
+            f"Implement core {phase_name.lower()} functionality",
+            f"Write tests for {phase_name.lower()}",
+        ]
+
+        if depth_level == "minimal":
+            return base_tasks[:2]
+        elif depth_level == "standard":
+            return base_tasks + [f"Document {phase_name.lower()} implementation"]
+        else:
+            return [
+                {
+                    "title": task,
+                    "description": f"Complete task: {task}",
+                    "subtasks": [
+                        f"Research best practices for {task.split()[-1]}",
+                        "Implement solution",
+                        "Write unit tests",
+                        "Update documentation",
+                    ],
+                }
+                for task in base_tasks
+            ] + [
+                {
+                    "title": f"Quality checks for {phase_name}",
+                    "description": "Run all quality checks and fix issues",
+                    "subtasks": [
+                        "Run linters (black, flake8)",
+                        "Run type checker (mypy)",
+                        "Verify test coverage >= 80%",
+                        "Review and address code review feedback",
+                    ],
+                }
+            ]
+
+    def _generate_test_strategy(self, depth_level: str) -> str:
+        """Generate testing strategy based on depth level."""
+        if depth_level == "minimal":
+            return "Verify functionality works as expected"
+        elif depth_level == "standard":
+            return (
+                "Write unit tests for core functionality. "
+                "Run integration tests for component interactions."
+            )
+        else:
+            return (
+                "Implement comprehensive testing:\n"
+                "- Unit tests for all functions and methods\n"
+                "- Integration tests for component interactions\n"
+                "- End-to-end tests for critical user flows\n"
+                "- Performance benchmarks for key operations\n"
+                "- Security testing for sensitive operations"
+            )
+
+    def _generate_acceptance_criteria(self, phase_name: str) -> list[str]:
+        """Generate acceptance criteria for a phase."""
+        return [
+            f"All {phase_name.lower()} tasks completed",
+            "Tests pass with acceptable coverage",
+            "Code reviewed and approved",
+            "Documentation updated",
+        ]
+
+    def _phase_names_for_count(self, phase_count: int) -> List[str]:
+        """Return human-friendly phase names for the requested count.
+
+        The mapping loosely follows the naming conventions in the devplan
+        but falls back to generic labels when the requested count does not
+        exactly match the canonical sets.
+        """
+        # Canonical sequences for common counts
+        if phase_count == 3:
+            base = ["Foundation", "Implementation", "Polish"]
+        elif phase_count == 5:
+            base = [
+                "Foundation",
+                "Core",
+                "Integration",
+                "Testing",
+                "Deployment",
+            ]
+        elif phase_count == 7:
+            base = [
+                "Planning",
+                "Foundation",
+                "Core",
+                "Features",
+                "Integration",
+                "Testing",
+                "Deployment",
+            ]
+        else:
+            base = [
+                "Planning",
+                "Foundation",
+                "Core",
+                "Auth & Security",
+                "Data Layer",
+                "API / Services",
+                "Frontend / UX",
+                "Integration & Hardening",
+                "Testing",
+                "Deployment",
+                "Monitoring",
+                "Polish",
+                "Post-Launch",
+                "Continuous Improvement",
+                "Operational Readiness",
+            ]
+
+        if phase_count <= len(base):
+            return base[:phase_count]
+
+        names = list(base)
+        generic_idx = 1
+        while len(names) < phase_count:
+            names.append(f"Additional Work {generic_idx}")
+            generic_idx += 1
+        return names
+
+    def render_phase_markdown(
+        self,
+        phase: DevPlanPhase,
+        depth_level: str = "standard",
+        **context: Any,
+    ) -> str:
+        """Render a single phase to markdown using templates.
+
+        Args:
+            phase: The phase to render.
+            depth_level: "minimal", "standard", or "detailed".
+            **context: Additional context for template rendering.
+
+        Returns:
+            Markdown string for the phase.
+        """
+        if not self.use_templates:
+            # Simple markdown fallback
+            lines = [f"## {phase.title}"]
+            if phase.description:
+                lines.append(f"\n{phase.description}")
+            return "\n".join(lines)
+
+        template_name = f"devplan/phase_{depth_level}.jinja2"
+        try:
+            template = self._env.get_template(template_name)
+        except Exception:
+            template = self._env.get_template("devplan/phase_standard.jinja2")
+
+        template_context = {
+            "phase_number": phase.number,
+            "phase_name": phase.title.replace(f"Phase {phase.number}: ", ""),
+            "phase_description": phase.description,
+            "tasks": [step.title if hasattr(step, "title") else str(step) for step in phase.steps],
+            **context,
+        }
+
+        return template.render(**template_context)
diff --git a/src/pipeline/llm_sanity_reviewer.py b/src/pipeline/llm_sanity_reviewer.py
new file mode 100644
index 0000000..47b8808
--- /dev/null
+++ b/src/pipeline/llm_sanity_reviewer.py
@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+from .design_validator import DesignValidationReport
+
+
+@dataclass
+class LLMSanityReviewResult:
+    confidence: float
+    notes: str
+    risks: List[str]
+
+
+class LLMSanityReviewer:
+    """Mock implementation of an LLM-based semantic reviewer.
+
+    This version does not call any external APIs. It derives a simple
+    confidence score and risk list from the validation report only, so it
+    can be exercised in unit and integration tests.
+    """
+
+    def review(self, design_text: str, validation_report: DesignValidationReport) -> LLMSanityReviewResult:
+        if validation_report.is_valid:
+            confidence = 0.9
+            notes = "Design passes all rule-based checks."
+            risks: List[str] = []
+        else:
+            # Lower confidence if we have non-auto-correctable issues
+            non_auto = [i for i in validation_report.issues if not i.auto_correctable]
+            if non_auto:
+                confidence = 0.5
+            else:
+                confidence = 0.7
+            notes = "Design has validation issues; manual review recommended."
+            risks = [issue.code for issue in validation_report.issues]
+
+        return LLMSanityReviewResult(confidence=confidence, notes=notes, risks=risks)
diff --git a/src/pipeline/mock_adaptive_pipeline.py b/src/pipeline/mock_adaptive_pipeline.py
new file mode 100644
index 0000000..b6a97ce
--- /dev/null
+++ b/src/pipeline/mock_adaptive_pipeline.py
@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from src.interview.interview_pipeline import InterviewPipeline, InterviewPipelineResult
+from src.pipeline.design_correction_loop import DesignCorrectionLoop, DesignCorrectionResult
+from src.pipeline.design_generator import AdaptiveDesignGenerator
+from src.pipeline.devplan_generator import AdaptiveDevPlanGenerator
+from src.models import DevPlan
+
+
+@dataclass
+class MockAdaptivePipelineResult:
+    interview: InterviewPipelineResult
+    devplan: DevPlan
+    correction: DesignCorrectionResult
+
+
+class MockAdaptivePipeline:
+    """End-to-end adaptive pipeline using only mock components.
+
+    This does NOT call any real LLM generators. It is intended for local
+    testing of control flow: interview → complexity → validation/correction →
+    synthetic devplan, all deterministic.
+    """
+
+    def __init__(self) -> None:
+        self._interview_pipeline = InterviewPipeline()
+        self._correction_loop = DesignCorrectionLoop()
+        self._design_generator = AdaptiveDesignGenerator()
+        self._devplan_generator = AdaptiveDevPlanGenerator()
+
+    def run(self, interview_data: Mapping[str, Any]) -> MockAdaptivePipelineResult:
+        interview_result = self._interview_pipeline.run(interview_data)
+        profile = interview_result.complexity_profile
+        project_label = str(interview_result.inputs.get("project_type") or "project")
+
+        design_text = self._design_generator.generate(profile, project_label=project_label)
+
+        devplan = self._devplan_generator.generate(profile, project_label=project_label)
+
+        correction = self._correction_loop.run(design_text, complexity_profile=profile)
+
+        return MockAdaptivePipelineResult(
+            interview=interview_result,
+            devplan=devplan,
+            correction=correction,
+        )
diff --git a/src/streaming.py b/src/streaming.py
index e0bf709..6b62688 100644
--- a/src/streaming.py
+++ b/src/streaming.py
@@ -11,7 +11,29 @@
 import sys
 import time
 from pathlib import Path
-from typing import Any, Callable, Optional, TextIO
+from typing import Any, Callable, Literal, Optional, TextIO
+
+
+# Predefined streaming prefixes for adaptive pipeline stages
+StreamingStage = Literal[
+    "design",
+    "devplan",
+    "handoff",
+    "complexity",
+    "validation",
+    "correction",
+    "follow_up",
+]
+
+STREAMING_PREFIXES: dict[StreamingStage, str] = {
+    "design": "[design] ",
+    "devplan": "[devplan] ",
+    "handoff": "[handoff] ",
+    "complexity": "[complexity] ",
+    "validation": "[validation] ",
+    "correction": "[correction] ",
+    "follow_up": "[follow_up] ",
+}
 
 
 class StreamingHandler:
@@ -185,6 +207,24 @@ def create_quiet_handler(cls, log_file: Path) -> StreamingHandler:
         """
         return cls(enable_console=False, log_file=log_file)
 
+    @classmethod
+    def create_stage_handler(
+        cls,
+        stage: StreamingStage,
+        log_file: Optional[Path] = None,
+    ) -> StreamingHandler:
+        """Create a handler with a predefined stage prefix.
+
+        Args:
+            stage: The pipeline stage (complexity, validation, correction, etc.)
+            log_file: Optional file path to log streaming output
+
+        Returns:
+            StreamingHandler configured for the specified stage
+        """
+        prefix = STREAMING_PREFIXES.get(stage, f"[{stage}] ")
+        return cls(enable_console=True, log_file=log_file, prefix=prefix)
+
 
 class StreamingSimulator:
     """Utility class to simulate streaming from non-streaming APIs.
diff --git a/templates/design/adaptive_design.jinja2 b/templates/design/adaptive_design.jinja2
new file mode 100644
index 0000000..0db0be5
--- /dev/null
+++ b/templates/design/adaptive_design.jinja2
@@ -0,0 +1,121 @@
+{# Adaptive Design Template - Scales output based on complexity profile #}
+{# Uses complexity_profile.depth_level to control verbosity #}
+
+You are an expert software architect creating a project design document.
+
+{% if complexity_profile %}
+## Complexity Context
+
+- **Complexity Score:** {{ complexity_profile.complexity_score }}/20
+- **Estimated Phases:** {{ complexity_profile.estimated_phases }}
+- **Depth Level:** {{ complexity_profile.depth_level }}
+- **Project Scale:** {{ complexity_profile.project_scale | default('standard') }}
+{% if complexity_profile.risk_factors %}
+- **Risk Factors:** {{ complexity_profile.risk_factors | join(', ') }}
+{% endif %}
+
+{% if complexity_profile.depth_level == "minimal" %}
+## Output Guidelines
+
+Provide a **concise design** focusing only on core architecture and critical decisions.
+- Target: 500-800 words
+- Focus on: Architecture overview, tech stack, core features
+- Skip: Detailed deployment, monitoring, extensive testing strategy
+- Keep sections brief and actionable
+
+{% elif complexity_profile.depth_level == "standard" %}
+## Output Guidelines
+
+Provide a **balanced design** covering architecture, tech stack, and key considerations.
+- Target: 1000-1500 words
+- Include: Architecture, tech stack, deployment approach, testing strategy, dependencies
+- Moderate detail on each section
+- Balance completeness with conciseness
+
+{% elif complexity_profile.depth_level == "detailed" %}
+## Output Guidelines
+
+Provide a **comprehensive design** including all aspects of the project.
+- Target: 2000-3000 words
+- Include: Architecture, patterns, deployment, testing strategy, security, scalability, monitoring, CI/CD, data models
+- Detailed rationale for key decisions
+- Address risks and mitigations
+- Include diagrams descriptions where helpful
+
+{% endif %}
+{% endif %}
+
+## Project Information
+
+**Project Name:** {{ project_name }}
+
+{% if requirements %}
+**Requirements:**
+{{ requirements }}
+{% endif %}
+
+{% if languages %}
+**Languages:** {{ languages | join(', ') if languages is iterable and languages is not string else languages }}
+{% endif %}
+
+{% if frameworks %}
+**Frameworks:** {{ frameworks | join(', ') if frameworks is iterable and frameworks is not string else frameworks }}
+{% endif %}
+
+{% if apis %}
+**External APIs:** {{ apis | join(', ') if apis is iterable and apis is not string else apis }}
+{% endif %}
+
+{% if database %}
+**Database:** {{ database }}
+{% endif %}
+
+{% if deployment_platform %}
+**Deployment:** {{ deployment_platform }}
+{% endif %}
+
+## Your Task
+
+Create a project design document that includes:
+
+{% if complexity_profile and complexity_profile.depth_level == "minimal" %}
+### Required Sections (Minimal)
+1. **Architecture Overview** - High-level system structure (1-2 paragraphs)
+2. **Technology Stack** - Languages, frameworks, key libraries
+3. **Core Features** - Main functionality to implement
+4. **Dependencies** - Critical external dependencies
+
+{% elif complexity_profile and complexity_profile.depth_level == "detailed" %}
+### Required Sections (Detailed)
+1. **Executive Summary** - Project overview and goals
+2. **Architecture Overview** - System structure with component descriptions
+3. **Component Details** - Each major component with responsibilities
+4. **Technology Stack** - Full tech stack with rationale
+5. **Data Model** - Key entities and relationships
+6. **API Design** - Endpoints and contracts (if applicable)
+7. **Security Considerations** - Auth, data protection, compliance
+8. **Scalability & Performance** - Capacity planning, optimization strategies
+9. **Testing Strategy** - Unit, integration, E2E approaches
+10. **Deployment & Operations** - Environments, CI/CD, monitoring
+11. **Dependencies** - External services and libraries
+12. **Risks & Mitigations** - Technical and operational risks
+13. **Success Criteria** - Measurable outcomes
+
+{% else %}
+### Required Sections (Standard)
+1. **Architecture Overview** - System structure and key components
+2. **Technology Stack** - Languages, frameworks, databases
+3. **Core Features** - Main functionality broken into phases
+4. **Deployment Strategy** - Basic deployment approach
+5. **Testing Approach** - Testing strategy overview
+6. **Dependencies** - Key external dependencies
+7. **Challenges & Mitigations** - Known challenges and solutions
+
+{% endif %}
+
+## Output Format
+
+Provide the design document in clean Markdown format with appropriate headings.
+Ensure all sections are addressed based on the depth level specified.
+
+Recommended phase count: {{ complexity_profile.estimated_phases if complexity_profile else '5-7' }}
diff --git a/templates/devplan/phase_detailed.jinja2 b/templates/devplan/phase_detailed.jinja2
new file mode 100644
index 0000000..bb7eada
--- /dev/null
+++ b/templates/devplan/phase_detailed.jinja2
@@ -0,0 +1,124 @@
+{# Phase Detailed Template - Comprehensive coverage for complex projects (complexity 8+) #}
+{# Target: 7-11 phases, granular tasks, full documentation #}
+
+## Phase {{ phase_number }}: {{ phase_name }}
+
+{{ phase_description | default('') }}
+
+{% if phase_goal %}
+### 🎯 Goal
+{{ phase_goal }}
+{% endif %}
+
+{% if rationale %}
+### 📋 Rationale
+{{ rationale }}
+{% endif %}
+
+### 📝 Tasks
+
+{% for task in tasks %}
+{% if task is mapping %}
+#### {{ phase_number }}.{{ loop.index }}: {{ task.title | default('Task ' ~ loop.index) }}
+
+{{ task.description | default('') }}
+
+{% if task.subtasks %}
+**Steps:**
+{% for subtask in task.subtasks %}
+- [ ] {{ subtask }}
+{% endfor %}
+{% endif %}
+
+{% if task.files %}
+**Files to create/modify:**
+{% for file in task.files %}
+- `{{ file }}`
+{% endfor %}
+{% endif %}
+
+{% if task.commands %}
+**Commands:**
+```bash
+{% for cmd in task.commands %}
+{{ cmd }}
+{% endfor %}
+```
+{% endif %}
+
+{% else %}
+- {{ task }}
+{% endif %}
+{% endfor %}
+
+{% if dependencies %}
+### 🔗 Dependencies
+
+**Phase Dependencies:**
+{% for dep in dependencies %}
+- Phase {{ dep }} must be complete
+{% endfor %}
+
+{% if external_dependencies %}
+**External Dependencies:**
+{% for ext_dep in external_dependencies %}
+- {{ ext_dep }}
+{% endfor %}
+{% endif %}
+{% endif %}
+
+### 🧪 Testing Strategy
+
+{{ test_strategy | default('Implement comprehensive testing:') }}
+
+{% if test_cases %}
+**Test Cases:**
+{% for test in test_cases %}
+- [ ] {{ test }}
+{% endfor %}
+{% endif %}
+
+{% if coverage_target %}
+**Coverage Target:** {{ coverage_target }}%
+{% endif %}
+
+### ✅ Acceptance Criteria
+
+{% if acceptance_criteria %}
+{% for criterion in acceptance_criteria %}
+- [ ] {{ criterion }}
+{% endfor %}
+{% else %}
+- [ ] All tasks completed and committed
+- [ ] Tests pass with acceptable coverage
+- [ ] Code reviewed and approved
+{% endif %}
+
+{% if risks %}
+### ⚠️ Risk Mitigation
+
+{% for risk in risks %}
+- **{{ risk.name | default('Risk') }}**: {{ risk.description }}
+  - *Mitigation*: {{ risk.mitigation | default('Monitor and address as needed') }}
+{% endfor %}
+{% endif %}
+
+{% if estimated_time %}
+### ⏱️ Estimated Time
+{{ estimated_time }}
+{% endif %}
+
+{% if code_samples %}
+### 💻 Code Samples
+
+```{{ code_language | default('python') }}
+{{ code_samples }}
+```
+{% endif %}
+
+{% if notes %}
+### 📌 Notes
+{{ notes }}
+{% endif %}
+
+---
diff --git a/templates/devplan/phase_minimal.jinja2 b/templates/devplan/phase_minimal.jinja2
new file mode 100644
index 0000000..afffb71
--- /dev/null
+++ b/templates/devplan/phase_minimal.jinja2
@@ -0,0 +1,21 @@
+{# Phase Minimal Template - Bare essentials for trivial projects (complexity 0-3) #}
+{# Target: 3-5 phases, concise output, no verbose sections #}
+
+## Phase {{ phase_number }}: {{ phase_name }}
+
+{{ phase_description | default('') }}
+
+### Tasks
+{% for task in tasks %}
+- {{ task.description | default(task) }}
+{% endfor %}
+
+### Testing
+- {{ test_strategy | default('Verify functionality works as expected') }}
+
+{% if acceptance_criteria %}
+### Done When
+{% for criterion in acceptance_criteria %}
+- {{ criterion }}
+{% endfor %}
+{% endif %}
diff --git a/templates/devplan/phase_standard.jinja2 b/templates/devplan/phase_standard.jinja2
new file mode 100644
index 0000000..8c0fe0a
--- /dev/null
+++ b/templates/devplan/phase_standard.jinja2
@@ -0,0 +1,48 @@
+{# Phase Standard Template - Balanced detail for typical projects (complexity 4-7) #}
+{# Target: 5-7 phases, moderate detail, includes testing and deployment #}
+
+## Phase {{ phase_number }}: {{ phase_name }}
+
+{{ phase_description | default('') }}
+
+{% if phase_goal %}
+**Goal:** {{ phase_goal }}
+{% endif %}
+
+### Tasks
+{% for task in tasks %}
+{% if task is mapping %}
+- **{{ task.title | default('Task ' ~ loop.index) }}**: {{ task.description }}
+  {% if task.subtasks %}
+  {% for subtask in task.subtasks %}
+  - {{ subtask }}
+  {% endfor %}
+  {% endif %}
+{% else %}
+- {{ task }}
+{% endif %}
+{% endfor %}
+
+{% if dependencies %}
+### Dependencies
+{% for dep in dependencies %}
+- {{ dep }}
+{% endfor %}
+{% endif %}
+
+### Testing Strategy
+{{ test_strategy | default('Write unit tests for core functionality. Run integration tests for component interactions.') }}
+
+{% if acceptance_criteria %}
+### Acceptance Criteria
+{% for criterion in acceptance_criteria %}
+- [ ] {{ criterion }}
+{% endfor %}
+{% endif %}
+
+{% if estimated_time %}
+### Estimated Time
+{{ estimated_time }}
+{% endif %}
+
+---
diff --git a/templates/interview/follow_up_questions.jinja2 b/templates/interview/follow_up_questions.jinja2
new file mode 100644
index 0000000..095f374
--- /dev/null
+++ b/templates/interview/follow_up_questions.jinja2
@@ -0,0 +1,34 @@
+{# Follow-up Questions Template for Complexity Analysis Clarifications #}
+{# Used when complexity analyzer has low confidence and needs more context #}
+
+Based on our initial conversation, I need some clarification to better understand your project's complexity.
+
+{% if complexity_profile %}
+**Current Assessment:**
+- Complexity Score: {{ complexity_profile.complexity_score }}/20
+- Estimated Phases: {{ complexity_profile.estimated_phases }}
+- Confidence: {{ (complexity_profile.confidence * 100) | round(1) }}%
+{% endif %}
+
+{% if follow_up_questions %}
+**Clarification Questions:**
+{% for question in follow_up_questions %}
+{{ loop.index }}. {{ question }}
+{% endfor %}
+{% endif %}
+
+---
+
+Please answer these questions to help refine the project complexity assessment. You can:
+- Answer each question directly
+- Type "skip" to proceed with the current assessment
+- Type "/done" when finished
+
+{% if interview_data %}
+**Previously Collected Information:**
+{% for key, value in interview_data.items() %}
+{% if value %}
+- **{{ key | replace('_', ' ') | title }}**: {{ value }}
+{% endif %}
+{% endfor %}
+{% endif %}
diff --git a/tests/fixtures/jinja/basic_devplan_context.json b/tests/fixtures/jinja/basic_devplan_context.json
new file mode 100644
index 0000000..5ce64a2
--- /dev/null
+++ b/tests/fixtures/jinja/basic_devplan_context.json
@@ -0,0 +1,84 @@
+{
+    "repo_context": {
+        "project_type": "python",
+        "structure": {
+            "source_dirs": [
+                "src"
+            ],
+            "test_dirs": [
+                "tests"
+            ],
+            "config_dirs": [
+                "config"
+            ],
+            "has_ci": true
+        },
+        "dependencies": {
+            "python": [
+                "fastapi",
+                "uvicorn"
+            ]
+        },
+        "metrics": {
+            "total_files": 42,
+            "total_lines": 1337
+        },
+        "patterns": {
+            "test_frameworks": [
+                "pytest"
+            ],
+            "build_tools": [
+                "poetry"
+            ]
+        },
+        "project_name": "TestApp",
+        "description": "A test application",
+        "version": "1.0.0",
+        "author": "Test Author"
+    },
+    "project_design": {
+        "project_name": "TestApp",
+        "languages": [
+            "Python",
+            "TypeScript"
+        ],
+        "frameworks": [
+            "FastAPI",
+            "React"
+        ],
+        "apis": [
+            "OpenAI",
+            "Stripe"
+        ],
+        "requirements": "Build a scalable web app.",
+        "objectives": [
+            "High performance",
+            "User friendly"
+        ],
+        "tech_stack": [
+            "Python 3.11",
+            "React 18",
+            "PostgreSQL"
+        ],
+        "architecture_overview": "Microservices architecture with API gateway.",
+        "dependencies": [
+            "sqlalchemy",
+            "pydantic"
+        ],
+        "challenges": [
+            "Concurrency",
+            "Data consistency"
+        ],
+        "mitigations": [
+            "Use async/await",
+            "Use transactions"
+        ],
+        "complexity": "Medium",
+        "estimated_phases": 5
+    },
+    "code_samples": "def hello_world():\n    print('Hello, World!')",
+    "interactive_session": {
+        "question_count": 5
+    },
+    "detail_level": "normal"
+}
\ No newline at end of file
diff --git a/tests/fixtures/jinja/basic_devplan_short_expected.md b/tests/fixtures/jinja/basic_devplan_short_expected.md
new file mode 100644
index 0000000..3d36b89
--- /dev/null
+++ b/tests/fixtures/jinja/basic_devplan_short_expected.md
@@ -0,0 +1,154 @@
+
+You are an expert project manager and software architect. You have been given a project design document and need to create a high-level development plan that breaks the project into logical phases.
+
+### Repository Context
+- **Type**: python
+- **Files**: 42
+- **Lines**: 1337
+- **Description**: A test application
+- **Version**: 1.0.0
+- **Author**: Test Author
+
+#### Dependencies
+- **python**: fastapi, uvicorn
+
+
+**Important:** Your devplan should respect the existing project structure, follow detected patterns, and integrate smoothly with the current codebase.
+
+
+### 📝 Code Samples from Repository
+
+The following code samples illustrate the existing architecture, patterns, and conventions:
+
+def hello_world():
+    print('Hello, World!')
+
+**Use these samples to:**
+- Understand the current code style and conventions
+- Identify existing patterns to follow
+- See how similar features are implemented
+- Ensure consistency with the existing codebase
+
+
+
+## 🎯 Interactive Session Context
+
+This project was defined through an interactive guided questionnaire. The user provided responses to targeted questions about their requirements, technology preferences, and project goals. This context should inform your development plan to ensure it aligns with their stated needs and experience level.
+
+**Session Details:**
+- Questions asked: 5
+- Project approach: Interactive, user-guided design
+
+## Project Design
+
+# Project: TestApp
+
+### Objectives
+- High performance
+- User friendly
+
+
+### Technology Stack
+- Python 3.11
+- React 18
+- PostgreSQL
+
+
+### Architecture Overview
+Microservices architecture with API gateway.
+
+### Key Dependencies
+- sqlalchemy
+- pydantic
+
+### Challenges & Mitigations
+- **Challenge**: Concurrency
+  - *Mitigation*: Use async/await
+- **Challenge**: Data consistency
+  - *Mitigation*: Use transactions
+
+
+### Complexity Assessment
+- **Rating**: Medium
+- **Estimated Phases**: 5
+
+## Your Task
+
+Create a high-level development plan that organizes the project implementation into **5 logical phases**. Each phase should represent a major milestone or functional area of the project.
+
+### Requirements
+
+1. **Phase Structure**: Each phase should have:
+   - A clear, descriptive title
+   - A brief summary of what will be accomplished
+   - 3-7 major components or work items
+
+2. **Logical Ordering**: Phases should be ordered such that:
+   - Dependencies are respected (foundational work comes first)
+   - Each phase builds on previous phases
+   - The project can be developed incrementally
+
+3. **Comprehensive Coverage**: The phases should cover:
+   - Project initialization and setup
+   - Interactive features (if building an interactive application)
+   - Core functionality implementation
+   - Testing and quality assurance
+   - Documentation
+   - Deployment and distribution (if applicable)
+
+4. **Scope**: Phases may vary in scope as needed—do not artificially balance their sizes. Prefer completeness and clarity over uniformity.
+
+5. **User Experience**: If the project involves user interaction (CLI, web, mobile), ensure phases include:
+   - Interactive UI/UX design and implementation
+   - User input validation and error handling
+   - Help text, examples, and guidance for users
+   - Session management (if applicable)
+
+### Example Structure (DO NOT COPY - adapt to the specific project)
+
+```
+Phase 1: Project Initialization
+- Set up version control repository
+- Configure development environment
+- Install dependencies and tools
+- Create basic project structure
+
+Phase 2: Core Data Models
+- Define data schemas
+- Implement data validation
+- Create database migrations
+- Build data access layer
+
+Phase 3: Business Logic
+- Implement core algorithms
+- Build service layer
+- Add error handling
+- Create utility functions
+
+... (continue with additional phases as needed)
+```
+
+## Output Format
+
+Please structure your response as a numbered list of phases. For each phase:
+
+1. Start with "**Phase N: [Phase Title]**"
+2. Add a brief description (1-2 sentences)
+3. List the major components as bullet points
+4. Keep descriptions clear and actionable
+
+Focus on creating a roadmap that a development team can follow to build the project systematically.
+
+---
+
+## Output Instructions
+
+Provide ONLY the numbered list of phases in the format specified above. Do not include:
+- Questions about proceeding to next steps
+- Execution workflow rituals or update instructions
+- Progress logs or task group planning
+- Handoff notes or status updates
+- References to updating devplan.md, phase files, or handoff prompts
+- Anchor markers or file update instructions
+
+Simply output the complete list of development phases for this project, then stop. Each phase should have a clear title, summary, and list of major components.
diff --git a/tests/fixtures/jinja/basic_devplan_verbose_expected.md b/tests/fixtures/jinja/basic_devplan_verbose_expected.md
new file mode 100644
index 0000000..3d36b89
--- /dev/null
+++ b/tests/fixtures/jinja/basic_devplan_verbose_expected.md
@@ -0,0 +1,154 @@
+
+You are an expert project manager and software architect. You have been given a project design document and need to create a high-level development plan that breaks the project into logical phases.
+
+### Repository Context
+- **Type**: python
+- **Files**: 42
+- **Lines**: 1337
+- **Description**: A test application
+- **Version**: 1.0.0
+- **Author**: Test Author
+
+#### Dependencies
+- **python**: fastapi, uvicorn
+
+
+**Important:** Your devplan should respect the existing project structure, follow detected patterns, and integrate smoothly with the current codebase.
+
+
+### 📝 Code Samples from Repository
+
+The following code samples illustrate the existing architecture, patterns, and conventions:
+
+def hello_world():
+    print('Hello, World!')
+
+**Use these samples to:**
+- Understand the current code style and conventions
+- Identify existing patterns to follow
+- See how similar features are implemented
+- Ensure consistency with the existing codebase
+
+
+
+## 🎯 Interactive Session Context
+
+This project was defined through an interactive guided questionnaire. The user provided responses to targeted questions about their requirements, technology preferences, and project goals. This context should inform your development plan to ensure it aligns with their stated needs and experience level.
+
+**Session Details:**
+- Questions asked: 5
+- Project approach: Interactive, user-guided design
+
+## Project Design
+
+# Project: TestApp
+
+### Objectives
+- High performance
+- User friendly
+
+
+### Technology Stack
+- Python 3.11
+- React 18
+- PostgreSQL
+
+
+### Architecture Overview
+Microservices architecture with API gateway.
+
+### Key Dependencies
+- sqlalchemy
+- pydantic
+
+### Challenges & Mitigations
+- **Challenge**: Concurrency
+  - *Mitigation*: Use async/await
+- **Challenge**: Data consistency
+  - *Mitigation*: Use transactions
+
+
+### Complexity Assessment
+- **Rating**: Medium
+- **Estimated Phases**: 5
+
+## Your Task
+
+Create a high-level development plan that organizes the project implementation into **5 logical phases**. Each phase should represent a major milestone or functional area of the project.
+
+### Requirements
+
+1. **Phase Structure**: Each phase should have:
+   - A clear, descriptive title
+   - A brief summary of what will be accomplished
+   - 3-7 major components or work items
+
+2. **Logical Ordering**: Phases should be ordered such that:
+   - Dependencies are respected (foundational work comes first)
+   - Each phase builds on previous phases
+   - The project can be developed incrementally
+
+3. **Comprehensive Coverage**: The phases should cover:
+   - Project initialization and setup
+   - Interactive features (if building an interactive application)
+   - Core functionality implementation
+   - Testing and quality assurance
+   - Documentation
+   - Deployment and distribution (if applicable)
+
+4. **Scope**: Phases may vary in scope as needed—do not artificially balance their sizes. Prefer completeness and clarity over uniformity.
+
+5. **User Experience**: If the project involves user interaction (CLI, web, mobile), ensure phases include:
+   - Interactive UI/UX design and implementation
+   - User input validation and error handling
+   - Help text, examples, and guidance for users
+   - Session management (if applicable)
+
+### Example Structure (DO NOT COPY - adapt to the specific project)
+
+```
+Phase 1: Project Initialization
+- Set up version control repository
+- Configure development environment
+- Install dependencies and tools
+- Create basic project structure
+
+Phase 2: Core Data Models
+- Define data schemas
+- Implement data validation
+- Create database migrations
+- Build data access layer
+
+Phase 3: Business Logic
+- Implement core algorithms
+- Build service layer
+- Add error handling
+- Create utility functions
+
+... (continue with additional phases as needed)
+```
+
+## Output Format
+
+Please structure your response as a numbered list of phases. For each phase:
+
+1. Start with "**Phase N: [Phase Title]**"
+2. Add a brief description (1-2 sentences)
+3. List the major components as bullet points
+4. Keep descriptions clear and actionable
+
+Focus on creating a roadmap that a development team can follow to build the project systematically.
+
+---
+
+## Output Instructions
+
+Provide ONLY the numbered list of phases in the format specified above. Do not include:
+- Questions about proceeding to next steps
+- Execution workflow rituals or update instructions
+- Progress logs or task group planning
+- Handoff notes or status updates
+- References to updating devplan.md, phase files, or handoff prompts
+- Anchor markers or file update instructions
+
+Simply output the complete list of development phases for this project, then stop. Each phase should have a clear title, summary, and list of major components.
diff --git a/tests/fixtures/jinja/detailed_devplan_context.json b/tests/fixtures/jinja/detailed_devplan_context.json
new file mode 100644
index 0000000..20e516a
--- /dev/null
+++ b/tests/fixtures/jinja/detailed_devplan_context.json
@@ -0,0 +1,143 @@
+{
+    "project_design": {
+        "project_name": "TestApp",
+        "languages": [
+            "Python",
+            "TypeScript"
+        ],
+        "frameworks": [
+            "FastAPI",
+            "React"
+        ],
+        "apis": [
+            "OpenAI",
+            "Stripe"
+        ],
+        "requirements": "Build a scalable web app.",
+        "objectives": [
+            "High performance",
+            "User friendly"
+        ],
+        "tech_stack": [
+            "Python 3.11",
+            "React 18",
+            "PostgreSQL"
+        ],
+        "architecture_overview": "Microservices architecture with API gateway.",
+        "dependencies": [
+            "sqlalchemy",
+            "pydantic"
+        ],
+        "challenges": [
+            "Concurrency",
+            "Data consistency"
+        ],
+        "mitigations": [
+            "Use async/await",
+            "Use transactions"
+        ],
+        "complexity": "Medium",
+        "estimated_phases": 5
+    },
+    "repo_context": {
+        "project_type": "python",
+        "structure": {
+            "source_dirs": [
+                "src"
+            ],
+            "test_dirs": [
+                "tests"
+            ],
+            "config_dirs": [
+                "config"
+            ],
+            "has_ci": true
+        },
+        "dependencies": {
+            "python": [
+                "fastapi",
+                "uvicorn"
+            ]
+        },
+        "metrics": {
+            "total_files": 42,
+            "total_lines": 1337
+        },
+        "patterns": {
+            "test_frameworks": [
+                "pytest"
+            ],
+            "build_tools": [
+                "poetry"
+            ]
+        },
+        "project_name": "TestApp",
+        "description": "A test application",
+        "version": "1.0.0",
+        "author": "Test Author"
+    },
+    "phases": [
+        {
+            "id": "setup",
+            "name": "Project Setup",
+            "goal": "Initialize the project structure and dependencies",
+            "steps": [
+                "Create virtual environment",
+                "Install dependencies",
+                "Set up project structure"
+            ],
+            "dependencies": [
+                "python3.11",
+                "poetry"
+            ],
+            "acceptance_criteria": [
+                "Project runs without errors",
+                "All dependencies installed"
+            ]
+        },
+        {
+            "id": "backend",
+            "name": "Backend Development",
+            "goal": "Implement FastAPI backend with database integration",
+            "steps": [
+                "Create database models",
+                "Implement API endpoints",
+                "Add authentication"
+            ],
+            "dependencies": [
+                "setup"
+            ],
+            "acceptance_criteria": [
+                "API endpoints functional",
+                "Database operations work"
+            ]
+        },
+        {
+            "id": "frontend",
+            "name": "Frontend Development",
+            "goal": "Build React frontend with TypeScript",
+            "steps": [
+                "Create React components",
+                "Implement API integration",
+                "Add styling"
+            ],
+            "dependencies": [
+                "backend"
+            ],
+            "acceptance_criteria": [
+                "UI renders correctly",
+                "API calls work"
+            ]
+        }
+    ],
+    "llm_config": {
+        "model": "gpt-4",
+        "temperature": 0.7,
+        "max_tokens": 4000
+    },
+    "runtime_config": {
+        "environment": "development",
+        "database_url": "postgresql://localhost/testapp"
+    },
+    "detail_level": "normal"
+}
\ No newline at end of file
diff --git a/tests/fixtures/jinja/detailed_devplan_short_expected.md b/tests/fixtures/jinja/detailed_devplan_short_expected.md
new file mode 100644
index 0000000..1be6993
--- /dev/null
+++ b/tests/fixtures/jinja/detailed_devplan_short_expected.md
@@ -0,0 +1,120 @@
+
+You are an expert software developer creating a detailed, step-by-step implementation plan. You have been given a high-level phase description and need to break it down into precise, numbered, actionable steps that a "lesser coding agent" (an AI with basic coding skills) can execute.
+
+### Repository Context
+- **Type**: python
+- **Files**: 42
+- **Lines**: 1337
+- **Description**: A test application
+- **Version**: 1.0.0
+- **Author**: Test Author
+
+#### Dependencies
+- **python**: fastapi, uvicorn
+
+
+Use existing patterns and directory structure in your implementation steps.
+
+
+
+
+## Phase to Detail
+
+**Phase : **
+
+
+## Project Context
+
+# Project: 
+### Technology Stack
+- None specified
+
+
+## Your Task
+
+Break this phase into **specific, numbered, actionable steps** using the format: `.X: [Action description]`
+
+### Requirements
+
+1. **Numbering**: Use the format `.1`, `.2`, etc.
+   - Each step should have a unique sub-number
+   - Steps should be ordered logically (dependencies first)
+
+2. **Actionability & Depth**: Each step must be:
+   - Clear and unambiguous
+   - Implementable by someone with basic coding skills
+   - Testable or verifiable
+   - Specific about what to create/modify
+   - Expanded with 3–10 sub-bullets ("- ") providing concrete details, file paths, CLI commands, and acceptance checks
+
+3. **Completeness**: Include steps for:
+   - Creating files/directories
+   - Implementing functions/classes
+   - Writing tests
+   - Running quality checks (linting, formatting)
+   - Git commits at logical milestones
+   - Documentation updates
+   - User-facing features (help text, examples, error messages if applicable)
+
+4. **Git Commits**: After significant sub-tasks, include a step like:
+   - `.X: Commit: git add [files] && git commit -m "[type]: [description]"`
+   - Use conventional commit types: `feat:`, `fix:`, `test:`, `docs:`, `chore:`
+
+5. **File Paths**: Be specific about file paths when creating or modifying files
+   - Example: "Create `src/models/user.py`" not "Create the user model"
+
+6. **Code Quality**: Include steps for:
+   - Running linters (e.g., `flake8 src/`)
+   - Running formatters (e.g., `black src/`)
+   - Running tests (e.g., `pytest tests/`)
+
+### Example Format (DO NOT COPY - adapt to your specific phase)
+
+```
+.1: Create the database schema file `src/db/schema.sql`
+- Define tables for users, posts, and comments
+- Include foreign key relationships
+- Add indexes for performance
+
+.2: Implement database connection manager in `src/db/connection.py`
+- Create `DatabaseManager` class with context manager support
+- Add methods: connect(), disconnect(), execute_query()
+- Handle connection pooling
+
+.3: Write unit tests in `tests/unit/test_database.py`
+- Test connection establishment
+- Test query execution
+- Test error handling
+
+.4: Run code quality checks
+- Execute: `black src/db/`
+- Execute: `flake8 src/db/`
+- Fix any issues found
+
+.5: Commit database infrastructure
+- Run: `git add src/db/ tests/unit/test_database.py`
+- Run: `git commit -m "feat: implement database connection manager"`
+```
+
+## Output Format
+
+Please provide a numbered list of steps in the format described above. Each step should:
+- Start with the step number: `.X:`
+- Have a clear action verb (Create, Implement, Add, Update, Test, Run, Commit)
+- Include specific details about what to build
+- MUST include sub-bullets with concrete instructions (at least 3), not placeholders
+
+Focus on making each step implementable and verifiable. The goal is that someone following these steps can build this phase successfully without needing to make significant architectural decisions.
+
+---
+
+## Output Instructions
+
+Provide ONLY the numbered list of implementation steps in the format specified above. Do not include:
+- Questions about proceeding to next steps
+- Requests for approval or confirmation
+- Progress update instructions
+- Handoff notes or status updates
+- References to updating devplan.md or phase files
+
+Simply output the complete list of steps for this phase, then stop. Each step should be actionable and include the required sub-bullets with concrete details.
diff --git a/tests/fixtures/jinja/detailed_devplan_verbose_expected.md b/tests/fixtures/jinja/detailed_devplan_verbose_expected.md
new file mode 100644
index 0000000..1be6993
--- /dev/null
+++ b/tests/fixtures/jinja/detailed_devplan_verbose_expected.md
@@ -0,0 +1,120 @@
+
+You are an expert software developer creating a detailed, step-by-step implementation plan. You have been given a high-level phase description and need to break it down into precise, numbered, actionable steps that a "lesser coding agent" (an AI with basic coding skills) can execute.
+
+### Repository Context
+- **Type**: python
+- **Files**: 42
+- **Lines**: 1337
+- **Description**: A test application
+- **Version**: 1.0.0
+- **Author**: Test Author
+
+#### Dependencies
+- **python**: fastapi, uvicorn
+
+
+Use existing patterns and directory structure in your implementation steps.
+
+
+
+
+## Phase to Detail
+
+**Phase : **
+
+
+## Project Context
+
+# Project: 
+### Technology Stack
+- None specified
+
+
+## Your Task
+
+Break this phase into **specific, numbered, actionable steps** using the format: `.X: [Action description]`
+
+### Requirements
+
+1. **Numbering**: Use the format `.1`, `.2`, etc.
+   - Each step should have a unique sub-number
+   - Steps should be ordered logically (dependencies first)
+
+2. **Actionability & Depth**: Each step must be:
+   - Clear and unambiguous
+   - Implementable by someone with basic coding skills
+   - Testable or verifiable
+   - Specific about what to create/modify
+   - Expanded with 3–10 sub-bullets ("- ") providing concrete details, file paths, CLI commands, and acceptance checks
+
+3. **Completeness**: Include steps for:
+   - Creating files/directories
+   - Implementing functions/classes
+   - Writing tests
+   - Running quality checks (linting, formatting)
+   - Git commits at logical milestones
+   - Documentation updates
+   - User-facing features (help text, examples, error messages if applicable)
+
+4. **Git Commits**: After significant sub-tasks, include a step like:
+   - `.X: Commit: git add [files] && git commit -m "[type]: [description]"`
+   - Use conventional commit types: `feat:`, `fix:`, `test:`, `docs:`, `chore:`
+
+5. **File Paths**: Be specific about file paths when creating or modifying files
+   - Example: "Create `src/models/user.py`" not "Create the user model"
+
+6. **Code Quality**: Include steps for:
+   - Running linters (e.g., `flake8 src/`)
+   - Running formatters (e.g., `black src/`)
+   - Running tests (e.g., `pytest tests/`)
+
+### Example Format (DO NOT COPY - adapt to your specific phase)
+
+```
+.1: Create the database schema file `src/db/schema.sql`
+- Define tables for users, posts, and comments
+- Include foreign key relationships
+- Add indexes for performance
+
+.2: Implement database connection manager in `src/db/connection.py`
+- Create `DatabaseManager` class with context manager support
+- Add methods: connect(), disconnect(), execute_query()
+- Handle connection pooling
+
+.3: Write unit tests in `tests/unit/test_database.py`
+- Test connection establishment
+- Test query execution
+- Test error handling
+
+.4: Run code quality checks
+- Execute: `black src/db/`
+- Execute: `flake8 src/db/`
+- Fix any issues found
+
+.5: Commit database infrastructure
+- Run: `git add src/db/ tests/unit/test_database.py`
+- Run: `git commit -m "feat: implement database connection manager"`
+```
+
+## Output Format
+
+Please provide a numbered list of steps in the format described above. Each step should:
+- Start with the step number: `.X:`
+- Have a clear action verb (Create, Implement, Add, Update, Test, Run, Commit)
+- Include specific details about what to build
+- MUST include sub-bullets with concrete instructions (at least 3), not placeholders
+
+Focus on making each step implementable and verifiable. The goal is that someone following these steps can build this phase successfully without needing to make significant architectural decisions.
+
+---
+
+## Output Instructions
+
+Provide ONLY the numbered list of implementation steps in the format specified above. Do not include:
+- Questions about proceeding to next steps
+- Requests for approval or confirmation
+- Progress update instructions
+- Handoff notes or status updates
+- References to updating devplan.md or phase files
+
+Simply output the complete list of steps for this phase, then stop. Each step should be actionable and include the required sub-bullets with concrete details.
diff --git a/tests/fixtures/jinja/handoff_prompt_context.json b/tests/fixtures/jinja/handoff_prompt_context.json
new file mode 100644
index 0000000..0f32af4
--- /dev/null
+++ b/tests/fixtures/jinja/handoff_prompt_context.json
@@ -0,0 +1,97 @@
+{
+    "project_design": {
+        "project_name": "TestApp",
+        "languages": [
+            "Python",
+            "TypeScript"
+        ],
+        "frameworks": [
+            "FastAPI",
+            "React"
+        ],
+        "apis": [
+            "OpenAI",
+            "Stripe"
+        ],
+        "requirements": "Build a scalable web app.",
+        "objectives": [
+            "High performance",
+            "User friendly"
+        ],
+        "tech_stack": [
+            "Python 3.11",
+            "React 18",
+            "PostgreSQL"
+        ],
+        "architecture_overview": "Microservices architecture with API gateway.",
+        "dependencies": [
+            "sqlalchemy",
+            "pydantic"
+        ],
+        "challenges": [
+            "Concurrency",
+            "Data consistency"
+        ],
+        "mitigations": [
+            "Use async/await",
+            "Use transactions"
+        ],
+        "complexity": "Medium",
+        "estimated_phases": 5
+    },
+    "repo_context": {
+        "project_type": "python",
+        "structure": {
+            "source_dirs": [
+                "src"
+            ],
+            "test_dirs": [
+                "tests"
+            ],
+            "config_dirs": [
+                "config"
+            ],
+            "has_ci": true
+        },
+        "dependencies": {
+            "python": [
+                "fastapi",
+                "uvicorn"
+            ]
+        },
+        "metrics": {
+            "total_files": 42,
+            "total_lines": 1337
+        },
+        "patterns": {
+            "test_frameworks": [
+                "pytest"
+            ],
+            "build_tools": [
+                "poetry"
+            ]
+        },
+        "project_name": "TestApp",
+        "description": "A test application",
+        "version": "1.0.0",
+        "author": "Test Author"
+    },
+    "links": {
+        "design_doc": "docs/design.md",
+        "devplan_doc": "docs/devplan.md"
+    },
+    "open_questions": [
+        "Should we use GraphQL or REST?",
+        "What authentication system to implement?"
+    ],
+    "llm_config": {
+        "model": "gpt-4",
+        "temperature": 0.7,
+        "max_tokens": 4000
+    },
+    "runtime_config": {
+        "environment": "development",
+        "database_url": "postgresql://localhost/testapp"
+    },
+    "detail_level": "normal"
+}
\ No newline at end of file
diff --git a/tests/fixtures/jinja/handoff_prompt_short_expected.md b/tests/fixtures/jinja/handoff_prompt_short_expected.md
new file mode 100644
index 0000000..9c33b0f
--- /dev/null
+++ b/tests/fixtures/jinja/handoff_prompt_short_expected.md
@@ -0,0 +1,64 @@
+# Handoff Prompt: 
+<!-- HANDOFF_VERSION: 2.0 -->
+
+> **QuickStart:** Read QUICK_STATUS → Read PHASE_TASKS → Execute → Update anchors → Handoff
+
+### Repository Context
+- **Type**: python
+- **Files**: 42
+- **Lines**: 1337
+- **Description**: A test application
+- **Version**: 1.0.0
+- **Author**: Test Author
+
+
+
+
+
+## Quick Status (Read This Always)
+<!-- QUICK_STATUS_START -->
+- Active Phase:  - 
+- Next Immediate Task:  - 
+- Blockers: None known
+<!-- QUICK_STATUS_END -->
+
+## How to Continue Development
+<!-- DEV_INSTRUCTIONS_START -->
+1. Read devplan.md between <!-- NEXT_TASK_GROUP_START --> and <!-- NEXT_TASK_GROUP_END --> only (~150 tokens).
+2. Open phase.md and read only <!-- PHASE_TASKS_START --> to <!-- PHASE_TASKS_END --> (~100 tokens).
+3. Execute the next group of steps in order (do not skip ahead).
+4. After completing the group, update:
+   - devplan.md: add one line to PROGRESS_LOG and refresh NEXT_TASK_GROUP.
+   - phase.md: add one line to PHASE_OUTCOMES (or legacy PHASE_PROGRESS).
+   - This file: update QUICK_STATUS only (3 lines, ~30 seconds).
+5. Stop after this group. Handoff if more work is needed.
+<!-- DEV_INSTRUCTIONS_END -->
+
+## Token Budget
+<!-- TOKEN_RULES_START -->
+**Stay under 500 tokens per turn by reading ONLY anchored sections:**
+
+| File | Section | Read? | Tokens |
+|------|---------|-------|--------|
+| devplan.md | NEXT_TASK_GROUP_START to END | ✅ | ~150 |
+| devplan.md | PROGRESS_LOG_START to END | ✅ if needed | ~100 |
+| phase.md | PHASE_TASKS_START to END | ✅ | ~100 |
+| phase.md | PHASE_OUTCOMES_START to END | ✅ if needed | ~50 |
+| handoff_prompt.md | QUICK_STATUS_START to END | ✅ | ~50 |
+| Everything else | (full files, verbose sections) | ❌ NEVER | - |
+
+**If you're reading more than 500 tokens, you're reading the wrong sections.**
+<!-- TOKEN_RULES_END -->
+
+## File References
+
+**For static or rarely-changing information, read these once and reference thereafter:**
+- project_design.md — Architecture, tech stack, core decisions.
+- README.md — Setup instructions, development workflow, code quality standards.
+- devplan.md — Main dashboard with all phases.
+
+---
+
+## Active Anchors
+<!-- HANDOFF_NOTES_START -->
+<!-- HANDOFF_NOTES_END -->
\ No newline at end of file
diff --git a/tests/fixtures/jinja/handoff_prompt_verbose_expected.md b/tests/fixtures/jinja/handoff_prompt_verbose_expected.md
new file mode 100644
index 0000000..9c33b0f
--- /dev/null
+++ b/tests/fixtures/jinja/handoff_prompt_verbose_expected.md
@@ -0,0 +1,64 @@
+# Handoff Prompt: 
+<!-- HANDOFF_VERSION: 2.0 -->
+
+> **QuickStart:** Read QUICK_STATUS → Read PHASE_TASKS → Execute → Update anchors → Handoff
+
+### Repository Context
+- **Type**: python
+- **Files**: 42
+- **Lines**: 1337
+- **Description**: A test application
+- **Version**: 1.0.0
+- **Author**: Test Author
+
+
+
+
+
+## Quick Status (Read This Always)
+<!-- QUICK_STATUS_START -->
+- Active Phase:  - 
+- Next Immediate Task:  - 
+- Blockers: None known
+<!-- QUICK_STATUS_END -->
+
+## How to Continue Development
+<!-- DEV_INSTRUCTIONS_START -->
+1. Read devplan.md between <!-- NEXT_TASK_GROUP_START --> and <!-- NEXT_TASK_GROUP_END --> only (~150 tokens).
+2. Open phase.md and read only <!-- PHASE_TASKS_START --> to <!-- PHASE_TASKS_END --> (~100 tokens).
+3. Execute the next group of steps in order (do not skip ahead).
+4. After completing the group, update:
+   - devplan.md: add one line to PROGRESS_LOG and refresh NEXT_TASK_GROUP.
+   - phase.md: add one line to PHASE_OUTCOMES (or legacy PHASE_PROGRESS).
+   - This file: update QUICK_STATUS only (3 lines, ~30 seconds).
+5. Stop after this group. Handoff if more work is needed.
+<!-- DEV_INSTRUCTIONS_END -->
+
+## Token Budget
+<!-- TOKEN_RULES_START -->
+**Stay under 500 tokens per turn by reading ONLY anchored sections:**
+
+| File | Section | Read? | Tokens |
+|------|---------|-------|--------|
+| devplan.md | NEXT_TASK_GROUP_START to END | ✅ | ~150 |
+| devplan.md | PROGRESS_LOG_START to END | ✅ if needed | ~100 |
+| phase.md | PHASE_TASKS_START to END | ✅ | ~100 |
+| phase.md | PHASE_OUTCOMES_START to END | ✅ if needed | ~50 |
+| handoff_prompt.md | QUICK_STATUS_START to END | ✅ | ~50 |
+| Everything else | (full files, verbose sections) | ❌ NEVER | - |
+
+**If you're reading more than 500 tokens, you're reading the wrong sections.**
+<!-- TOKEN_RULES_END -->
+
+## File References
+
+**For static or rarely-changing information, read these once and reference thereafter:**
+- project_design.md — Architecture, tech stack, core decisions.
+- README.md — Setup instructions, development workflow, code quality standards.
+- devplan.md — Main dashboard with all phases.
+
+---
+
+## Active Anchors
+<!-- HANDOFF_NOTES_START -->
+<!-- HANDOFF_NOTES_END -->
\ No newline at end of file
diff --git a/tests/harness/pipeline_test_harness.py b/tests/harness/pipeline_test_harness.py
new file mode 100644
index 0000000..bb57702
--- /dev/null
+++ b/tests/harness/pipeline_test_harness.py
@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, List, Mapping
+
+from src.pipeline.mock_adaptive_pipeline import MockAdaptivePipeline, MockAdaptivePipelineResult
+
+
+@dataclass
+class TestScenario:
+    name: str
+    interview_data: Mapping[str, Any]
+    min_phases: int
+    max_phases: int
+
+
+@dataclass
+class ScenarioResult:
+    scenario_name: str
+    passed: bool
+    messages: List[str]
+
+
+@dataclass
+class TestReport:
+    results: List[ScenarioResult]
+
+    @property
+    def all_passed(self) -> bool:
+        return all(r.passed for r in self.results)
+
+
+class PipelineTestHarness:
+    def run_scenario(self, scenario: TestScenario) -> ScenarioResult:
+        pipeline = MockAdaptivePipeline()
+        result: MockAdaptivePipelineResult = pipeline.run(scenario.interview_data)
+
+        profile = result.interview.complexity_profile
+        devplan = result.devplan
+
+        phase_count = len(devplan.phases)
+        messages: List[str] = []
+        passed = True
+
+        if not (scenario.min_phases <= phase_count <= scenario.max_phases):
+            passed = False
+            messages.append(
+                f"Phase count {phase_count} outside expected range "
+                f"[{scenario.min_phases}, {scenario.max_phases}]"
+            )
+
+        if phase_count != profile.estimated_phase_count:
+            passed = False
+            messages.append(
+                "Devplan phase count does not match estimated_phase_count "
+                f"({phase_count} != {profile.estimated_phase_count})"
+            )
+
+        if not devplan.summary:
+            passed = False
+            messages.append("Devplan summary is empty")
+
+        if not messages:
+            messages.append("OK")
+
+        return ScenarioResult(
+            scenario_name=scenario.name,
+            passed=passed,
+            messages=messages,
+        )
+
+    def run_test_suite(self, scenarios: List[TestScenario]) -> TestReport:
+        results = [self.run_scenario(s) for s in scenarios]
+        return TestReport(results=results)
diff --git a/tests/harness/test_pipeline_test_harness.py b/tests/harness/test_pipeline_test_harness.py
new file mode 100644
index 0000000..7a07079
--- /dev/null
+++ b/tests/harness/test_pipeline_test_harness.py
@@ -0,0 +1,40 @@
+from tests.harness.pipeline_test_harness import (
+    PipelineTestHarness,
+    TestScenario,
+)
+
+
+def _trivial_cli_scenario(min_phases: int, max_phases: int) -> TestScenario:
+    return TestScenario(
+        name="trivial_cli",
+        interview_data={
+            "project_type": "CLI Tool",
+            "requirements": "Tiny helper to manage local text files.",
+            "team_size": "1",
+        },
+        min_phases=min_phases,
+        max_phases=max_phases,
+    )
+
+
+def test_trivial_cli_with_wide_bounds_passes():
+    harness = PipelineTestHarness()
+    scenario = _trivial_cli_scenario(min_phases=1, max_phases=5)
+
+    report = harness.run_test_suite([scenario])
+
+    assert report.all_passed
+    assert len(report.results) == 1
+    assert report.results[0].passed
+
+
+def test_trivial_cli_with_too_strict_bounds_fails():
+    harness = PipelineTestHarness()
+    scenario = _trivial_cli_scenario(min_phases=5, max_phases=10)
+
+    report = harness.run_test_suite([scenario])
+
+    assert not report.all_passed
+    assert len(report.results) == 1
+    assert not report.results[0].passed
+    assert any("outside expected range" in msg for msg in report.results[0].messages)
diff --git a/tests/integration/test_adaptive_pipeline_e2e.py b/tests/integration/test_adaptive_pipeline_e2e.py
new file mode 100644
index 0000000..e91f6b5
--- /dev/null
+++ b/tests/integration/test_adaptive_pipeline_e2e.py
@@ -0,0 +1,747 @@
+"""End-to-end tests for adaptive pipeline with different complexity levels.
+
+These tests verify the full adaptive pipeline flow including:
+- Complexity analysis
+- Design generation
+- Validation
+- Correction loop (when enabled)
+
+Tests are marked with @pytest.mark.requires_api and @pytest.mark.slow.
+Skip with: pytest -m "not requires_api" or pytest -m "not slow"
+"""
+
+from __future__ import annotations
+
+import os
+import pytest
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from src.pipeline.compose import PipelineOrchestrator
+from src.interview.complexity_analyzer import ComplexityProfile
+from src.concurrency import ConcurrencyManager
+from src.models import ProjectDesign, DevPlan, DevPlanPhase, DevPlanStep
+
+
+# Skip all tests in this module if no API key is available
+pytestmark = [
+    pytest.mark.integration,
+    pytest.mark.slow,
+]
+
+
+class TestAdaptivePipelineMinimalComplexity:
+    """Tests for minimal complexity projects (CLI tools, simple scripts)."""
+
+    @pytest.fixture
+    def minimal_interview_data(self) -> dict:
+        """Interview data for a minimal complexity project."""
+        return {
+            "project_name": "file-renamer",
+            "project_type": "cli_tool",
+            "requirements": "Simple CLI to batch rename files with regex patterns",
+            "languages": ["Python"],
+            "frameworks": [],
+            "apis": "",
+            "team_size": "solo",
+        }
+
+    def test_minimal_complexity_detection(
+        self,
+        minimal_interview_data: dict,
+        concurrency_manager: ConcurrencyManager,
+        mock_llm_client: MagicMock,
+    ) -> None:
+        """Test that minimal projects are detected correctly."""
+        orchestrator = PipelineOrchestrator(
+            llm_client=mock_llm_client,
+            concurrency_manager=concurrency_manager,
+        )
+
+        profile = orchestrator.analyze_complexity(minimal_interview_data)
+
+        assert isinstance(profile, ComplexityProfile)
+        assert profile.project_type_bucket == "cli_tool"
+        assert profile.depth_level == "minimal"
+        assert profile.estimated_phase_count <= 4
+        assert profile.score <= 4.0
+
+    @pytest.mark.asyncio
+    async def test_minimal_pipeline_generates_concise_output(
+        self,
+        minimal_interview_data: dict,
+        concurrency_manager: ConcurrencyManager,
+        mock_llm_client: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        """Test that minimal complexity produces appropriately scoped outputs."""
+        # Mock LLM responses
+        mock_llm_client.generate = AsyncMock(return_value="""
+        # CLI Architecture
+        Simple command-line tool structure.
+        
+        ## Components
+        - argparse CLI interface
+        - Regex pattern engine
+        - File operations module
+        
+        ## Testing
+        Unit tests for pattern matching
+        """)
+
+        orchestrator = PipelineOrchestrator(
+            llm_client=mock_llm_client,
+            concurrency_manager=concurrency_manager,
+        )
+
+        # Mock generators to return appropriate minimal output
+        mock_design = ProjectDesign(
+            project_name="file-renamer",
+            objectives=["Batch rename files using regex"],
+            tech_stack=["Python", "argparse"],
+            architecture_overview="Simple CLI tool",
+        )
+        orchestrator.project_design_gen.generate = AsyncMock(return_value=mock_design)
+
+        mock_devplan = DevPlan(
+            phases=[
+                DevPlanPhase(
+                    number=1,
+                    title="Core Implementation",
+                    steps=[
+                        DevPlanStep(number="1.1", description="Setup CLI"),
+                        DevPlanStep(number="1.2", description="Implement renaming"),
+                    ],
+                ),
+                DevPlanPhase(
+                    number=2,
+                    title="Testing",
+                    steps=[
+                        DevPlanStep(number="2.1", description="Add unit tests"),
+                    ],
+                ),
+            ],
+            summary="Minimal CLI development plan",
+        )
+        orchestrator.basic_devplan_gen.generate = AsyncMock(return_value=mock_devplan)
+        orchestrator.detailed_devplan_gen.generate = AsyncMock(return_value=mock_devplan)
+
+        result = await orchestrator.run_adaptive_pipeline(
+            project_name="file-renamer",
+            languages=["Python"],
+            requirements="Batch rename files with regex",
+            interview_data=minimal_interview_data,
+            output_dir=str(tmp_path),
+            save_artifacts=True,
+            enable_validation=False,
+            enable_correction=False,
+        )
+
+        design, devplan, handoff, complexity = result
+
+        # Verify minimal complexity characteristics
+        assert complexity.depth_level == "minimal"
+        assert len(devplan.phases) <= 4
+        assert (tmp_path / "complexity_profile.md").exists()
+
+
+class TestAdaptivePipelineStandardComplexity:
+    """Tests for standard complexity projects (APIs, web apps)."""
+
+    @pytest.fixture
+    def standard_interview_data(self) -> dict:
+        """Interview data for a standard complexity project.
+        
+        Scoring calculation:
+        - project_type "api" = 3
+        - requirements "auth" triggers auth_db = 2
+        - apis "SendGrid,Stripe,Twilio" = 3 services = 2
+        - team_size "4" = "4_6" = 1.2x multiplier
+        Base: 3 + 2 + 2 = 7, with 1.2x = 8.4 => "detailed" but let's aim for standard
+        
+        Adjusted to get score in 4-7 range (standard):
+        - api = 3, auth_db = 2, 1_2_services = 1, 2_3 = 1.0x
+        Base: 3 + 2 + 1 = 6 * 1.0 = 6 => "standard"
+        """
+        return {
+            "project_name": "task-api",
+            "project_type": "api",
+            "requirements": "REST API with user authentication, task CRUD, and PostgreSQL",
+            "languages": ["Python", "TypeScript"],
+            "frameworks": ["FastAPI", "React"],
+            "apis": "SendGrid,Stripe",  # 2 services = 1_2_services bucket
+            "team_size": "2",  # 2_3 bucket = 1.0x multiplier
+        }
+
+    def test_standard_complexity_detection(
+        self,
+        standard_interview_data: dict,
+        concurrency_manager: ConcurrencyManager,
+        mock_llm_client: MagicMock,
+    ) -> None:
+        """Test that standard projects are detected correctly."""
+        orchestrator = PipelineOrchestrator(
+            llm_client=mock_llm_client,
+            concurrency_manager=concurrency_manager,
+        )
+
+        profile = orchestrator.analyze_complexity(standard_interview_data)
+
+        assert isinstance(profile, ComplexityProfile)
+        # Score should be around 6: api(3) + auth_db(2) + 1_2_services(1) * 1.0 = 6
+        assert profile.depth_level == "standard", f"Got score={profile.score}, depth={profile.depth_level}"
+        assert 3 <= profile.estimated_phase_count <= 6
+        assert 4.0 <= profile.score <= 7.0
+
+    @pytest.mark.asyncio
+    async def test_standard_pipeline_with_validation(
+        self,
+        standard_interview_data: dict,
+        concurrency_manager: ConcurrencyManager,
+        mock_llm_client: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        """Test standard complexity with validation enabled."""
+        mock_llm_client.generate = AsyncMock(return_value="""
+        # API Architecture
+        
+        ## Architecture Overview
+        REST API with authentication and task management.
+        
+        ## Database
+        PostgreSQL with users and tasks tables.
+        
+        ## Testing
+        Pytest with 80% coverage target.
+        """)
+
+        orchestrator = PipelineOrchestrator(
+            llm_client=mock_llm_client,
+            concurrency_manager=concurrency_manager,
+        )
+
+        # Mock generators
+        mock_design = ProjectDesign(
+            project_name="task-api",
+            objectives=["Build REST API", "User authentication", "Task CRUD"],
+            tech_stack=["Python", "FastAPI", "PostgreSQL"],
+            architecture_overview="""
+            # Architecture
+            REST API backend.
+            
+            ## Database
+            PostgreSQL.
+            
+            ## Testing
+            Pytest.
+            """,
+        )
+        orchestrator.project_design_gen.generate = AsyncMock(return_value=mock_design)
+
+        mock_devplan = DevPlan(
+            phases=[
+                DevPlanPhase(
+                    number=i,
+                    title=f"Phase {i}",
+                    steps=[
+                        DevPlanStep(number=f"{i}.1", description=f"Step 1 of phase {i}"),
+                        DevPlanStep(number=f"{i}.2", description=f"Step 2 of phase {i}"),
+                    ],
+                )
+                for i in range(1, 5)
+            ],
+            summary="Standard API development plan",
+        )
+        orchestrator.basic_devplan_gen.generate = AsyncMock(return_value=mock_devplan)
+        orchestrator.detailed_devplan_gen.generate = AsyncMock(return_value=mock_devplan)
+
+        result = await orchestrator.run_adaptive_pipeline(
+            project_name="task-api",
+            languages=["Python", "TypeScript"],
+            requirements="REST API with auth and tasks",
+            interview_data=standard_interview_data,
+            output_dir=str(tmp_path),
+            save_artifacts=True,
+            enable_validation=True,
+            enable_correction=False,
+        )
+
+        design, devplan, handoff, complexity = result
+
+        # Verify standard complexity characteristics
+        assert complexity.depth_level == "standard"
+        assert 3 <= len(devplan.phases) <= 6
+        assert (tmp_path / "project_design.md").exists()
+
+
+class TestAdaptivePipelineDetailedComplexity:
+    """Tests for detailed/complex projects (SaaS, enterprise)."""
+
+    @pytest.fixture
+    def detailed_interview_data(self) -> dict:
+        """Interview data for a detailed complexity project.
+        
+        Scoring calculation:
+        - project_type "saas platform" = 5
+        - requirements "real-time" triggers realtime = 3
+        - apis "6 services" = 6_plus_services = 3
+        - team_size "8" = 7_plus = 1.5x multiplier
+        Base: 5 + 3 + 3 = 11, with 1.5x = 16.5 => "detailed"
+        """
+        return {
+            "project_name": "enterprise-crm",
+            "project_type": "saas platform",
+            "requirements": "Multi-tenant CRM with real-time collaboration, insights, multi-region deployment",
+            "languages": ["Python", "TypeScript", "Go"],
+            "frameworks": ["FastAPI", "Next.js", "Kubernetes"],
+            "apis": "Stripe, SendGrid, Twilio, AWS S3, Auth0, OpenAI",  # 6 services
+            "team_size": "8",
+        }
+
+    def test_detailed_complexity_detection(
+        self,
+        detailed_interview_data: dict,
+        concurrency_manager: ConcurrencyManager,
+        mock_llm_client: MagicMock,
+    ) -> None:
+        """Test that complex projects are detected correctly."""
+        orchestrator = PipelineOrchestrator(
+            llm_client=mock_llm_client,
+            concurrency_manager=concurrency_manager,
+        )
+
+        profile = orchestrator.analyze_complexity(detailed_interview_data)
+
+        assert isinstance(profile, ComplexityProfile)
+        assert profile.depth_level == "detailed", f"Got score={profile.score}, depth={profile.depth_level}"
+        assert profile.estimated_phase_count >= 5
+        assert profile.score >= 8.0
+
+    @pytest.mark.asyncio
+    async def test_detailed_pipeline_produces_comprehensive_output(
+        self,
+        detailed_interview_data: dict,
+        concurrency_manager: ConcurrencyManager,
+        mock_llm_client: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        """Test that detailed complexity produces comprehensive outputs."""
+        mock_llm_client.generate = AsyncMock(return_value="""
+        # Enterprise CRM Architecture
+        
+        ## Architecture Overview
+        Multi-tenant SaaS platform with microservices.
+        
+        ## Database
+        PostgreSQL with tenant isolation, Redis for caching.
+        
+        ## Security
+        Auth0 integration, row-level security, audit logging.
+        
+        ## Testing
+        Comprehensive test suite with 90% coverage.
+        """)
+
+        orchestrator = PipelineOrchestrator(
+            llm_client=mock_llm_client,
+            concurrency_manager=concurrency_manager,
+        )
+
+        # Mock generators for comprehensive output
+        mock_design = ProjectDesign(
+            project_name="enterprise-crm",
+            objectives=[
+                "Multi-tenant architecture",
+                "Real-time collaboration",
+                "ML-based insights",
+                "Multi-region deployment",
+                "Enterprise security",
+            ],
+            tech_stack=["Python", "FastAPI", "PostgreSQL", "Redis", "Kubernetes"],
+            architecture_overview="""
+            # Enterprise Architecture
+            
+            ## Microservices
+            - User Service
+            - CRM Service
+            - ML Service
+            - Notification Service
+            
+            ## Database
+            PostgreSQL with sharding.
+            
+            ## Testing
+            Pytest + integration tests.
+            """,
+        )
+        orchestrator.project_design_gen.generate = AsyncMock(return_value=mock_design)
+
+        mock_devplan = DevPlan(
+            phases=[
+                DevPlanPhase(
+                    number=i,
+                    title=f"Phase {i}",
+                    steps=[
+                        DevPlanStep(number=f"{i}.{j}", description=f"Step {j}")
+                        for j in range(1, 6)
+                    ],
+                )
+                for i in range(1, 8)  # 7 phases for complex project
+            ],
+            summary="Comprehensive enterprise development plan",
+        )
+        orchestrator.basic_devplan_gen.generate = AsyncMock(return_value=mock_devplan)
+        orchestrator.detailed_devplan_gen.generate = AsyncMock(return_value=mock_devplan)
+
+        result = await orchestrator.run_adaptive_pipeline(
+            project_name="enterprise-crm",
+            languages=["Python", "TypeScript", "Go"],
+            requirements="Enterprise CRM platform",
+            interview_data=detailed_interview_data,
+            output_dir=str(tmp_path),
+            save_artifacts=True,
+            enable_validation=True,
+            enable_correction=False,
+        )
+
+        design, devplan, handoff, complexity = result
+
+        # Verify detailed complexity characteristics
+        assert complexity.depth_level == "detailed"
+        assert len(devplan.phases) >= 5
+        assert len(design.objectives) >= 3
+
+
+class TestAdaptivePipelineValidationCorrection:
+    """Tests for validation and correction loop."""
+
+    @pytest.fixture
+    def interview_data_with_issues(self) -> dict:
+        """Interview data that might trigger validation issues."""
+        return {
+            "project_name": "incomplete-api",
+            "project_type": "api",
+            "requirements": "API backend",  # Vague requirements
+            "languages": ["Python"],
+            "frameworks": [],
+            "apis": "",
+            "team_size": "solo",
+        }
+
+    @pytest.mark.asyncio
+    async def test_correction_loop_invoked_on_issues(
+        self,
+        interview_data_with_issues: dict,
+        concurrency_manager: ConcurrencyManager,
+        mock_llm_client: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        """Test that correction loop is invoked when validation finds issues."""
+        # This test verifies the correction loop is called but uses mocks
+        # to avoid actual LLM calls
+        
+        orchestrator = PipelineOrchestrator(
+            llm_client=mock_llm_client,
+            concurrency_manager=concurrency_manager,
+        )
+
+        # Create design that will fail validation (missing sections)
+        mock_design = ProjectDesign(
+            project_name="incomplete-api",
+            objectives=["Build API"],
+            tech_stack=["Python"],
+            architecture_overview="Incomplete design",  # Missing required sections
+        )
+        orchestrator.project_design_gen.generate = AsyncMock(return_value=mock_design)
+
+        mock_devplan = DevPlan(
+            phases=[
+                DevPlanPhase(
+                    number=1,
+                    title="Development",
+                    steps=[DevPlanStep(number="1.1", description="Build API")],
+                ),
+            ],
+            summary="Basic plan",
+        )
+        orchestrator.basic_devplan_gen.generate = AsyncMock(return_value=mock_devplan)
+        orchestrator.detailed_devplan_gen.generate = AsyncMock(return_value=mock_devplan)
+
+        # Mock the correction loop to track if it was called (NOT async - it's a regular method)
+        with patch.object(orchestrator, 'run_correction_loop') as mock_correction:
+            from src.pipeline.design_correction_loop import DesignCorrectionResult
+            from src.pipeline.design_validator import DesignValidationReport
+            from src.pipeline.llm_sanity_reviewer import LLMSanityReviewResult
+            
+            # Create proper DesignCorrectionResult with required fields
+            mock_validation = DesignValidationReport(
+                is_valid=True,
+                auto_correctable=False,
+                issues=[],
+                checks={"completeness": True, "consistency": True},
+            )
+            mock_review = LLMSanityReviewResult(
+                confidence=0.9,
+                notes="Design passes all checks.",
+                risks=[],
+            )
+            mock_correction.return_value = DesignCorrectionResult(
+                design_text="Corrected design text",
+                validation=mock_validation,
+                review=mock_review,
+            )
+            
+            result = await orchestrator.run_adaptive_pipeline(
+                project_name="incomplete-api",
+                languages=["Python"],
+                requirements="API backend",
+                interview_data=interview_data_with_issues,
+                output_dir=str(tmp_path),
+                save_artifacts=True,
+                enable_validation=True,
+                enable_correction=True,
+            )
+            
+            # Verify pipeline completed
+            design, devplan, handoff, complexity = result
+            assert design is not None
+            assert devplan is not None
+
+
+class TestAdaptivePipelineArtifacts:
+    """Tests for artifact generation in adaptive pipeline."""
+
+    @pytest.fixture
+    def standard_interview_data(self) -> dict:
+        return {
+            "project_name": "artifact-test",
+            "project_type": "api",
+            "requirements": "Test artifact generation",
+            "languages": ["Python"],
+            "frameworks": [],
+            "apis": "",
+            "team_size": "solo",
+        }
+
+    @pytest.mark.asyncio
+    async def test_all_artifacts_generated(
+        self,
+        standard_interview_data: dict,
+        concurrency_manager: ConcurrencyManager,
+        mock_llm_client: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        """Test that all expected artifacts are generated."""
+        mock_llm_client.generate = AsyncMock(return_value="Mock content")
+
+        orchestrator = PipelineOrchestrator(
+            llm_client=mock_llm_client,
+            concurrency_manager=concurrency_manager,
+        )
+
+        mock_design = ProjectDesign(
+            project_name="artifact-test",
+            objectives=["Test artifacts"],
+            tech_stack=["Python"],
+            architecture_overview="""
+            # Architecture
+            Test.
+            
+            ## Database
+            SQLite.
+            
+            ## Testing
+            Pytest.
+            """,
+        )
+        orchestrator.project_design_gen.generate = AsyncMock(return_value=mock_design)
+
+        mock_devplan = DevPlan(
+            phases=[
+                DevPlanPhase(
+                    number=1,
+                    title="Test",
+                    steps=[DevPlanStep(number="1.1", description="Test step")],
+                ),
+            ],
+            summary="Test plan",
+        )
+        orchestrator.basic_devplan_gen.generate = AsyncMock(return_value=mock_devplan)
+        orchestrator.detailed_devplan_gen.generate = AsyncMock(return_value=mock_devplan)
+
+        await orchestrator.run_adaptive_pipeline(
+            project_name="artifact-test",
+            languages=["Python"],
+            requirements="Test",
+            interview_data=standard_interview_data,
+            output_dir=str(tmp_path),
+            save_artifacts=True,
+            enable_validation=False,
+            enable_correction=False,
+        )
+
+        # Verify all expected artifacts exist
+        expected_artifacts = [
+            "complexity_profile.md",
+            "project_design.md",
+        ]
+        
+        for artifact in expected_artifacts:
+            assert (tmp_path / artifact).exists(), f"Missing artifact: {artifact}"
+
+
+@pytest.mark.requires_api
+class TestAdaptivePipelineRealLLM:
+    """Tests that actually call LLM APIs.
+    
+    These tests are skipped by default. Run with:
+        pytest -m requires_api tests/integration/test_adaptive_pipeline_e2e.py
+    
+    Requires environment variables:
+        - OPENAI_API_KEY or REQUESTY_API_KEY
+    """
+
+    @pytest.fixture
+    def skip_if_no_api_key(self) -> None:
+        """Skip test if no API key is available."""
+        if not os.getenv("OPENAI_API_KEY") and not os.getenv("REQUESTY_API_KEY"):
+            pytest.skip("No API key available for real LLM tests")
+
+    @pytest.fixture
+    def real_llm_client(self):
+        """Create a real LLM client from config."""
+        from src.config import load_config
+        from src.clients.factory import create_llm_client
+        
+        # Temporarily override any invalid provider in environment
+        original_provider = os.environ.get("LLM_PROVIDER")
+        if original_provider and original_provider not in ["openai", "generic", "aether", "agentrouter", "requesty"]:
+            os.environ["LLM_PROVIDER"] = "requesty"
+        
+        try:
+            config = load_config()
+            return create_llm_client(config)
+        finally:
+            # Restore original value
+            if original_provider:
+                os.environ["LLM_PROVIDER"] = original_provider
+            elif "LLM_PROVIDER" in os.environ:
+                del os.environ["LLM_PROVIDER"]
+
+    @pytest.fixture
+    def real_concurrency_manager(self):
+        """Create a real concurrency manager."""
+        from src.config import load_config
+        
+        # Temporarily override any invalid provider in environment
+        original_provider = os.environ.get("LLM_PROVIDER")
+        if original_provider and original_provider not in ["openai", "generic", "aether", "agentrouter", "requesty"]:
+            os.environ["LLM_PROVIDER"] = "requesty"
+        
+        try:
+            config = load_config()
+            return ConcurrencyManager(config)
+        finally:
+            if original_provider:
+                os.environ["LLM_PROVIDER"] = original_provider
+            elif "LLM_PROVIDER" in os.environ:
+                del os.environ["LLM_PROVIDER"]
+
+    @pytest.mark.asyncio
+    async def test_real_minimal_pipeline(
+        self,
+        skip_if_no_api_key: None,
+        real_llm_client,
+        real_concurrency_manager,
+        tmp_path: Path,
+    ) -> None:
+        """Run actual pipeline with minimal complexity project."""
+        from src.pipeline.compose import PipelineOrchestrator
+        from src.pipeline.design_generator import AdaptiveDesignGenerator
+        
+        interview_data = {
+            "project_name": "quick-note",
+            "project_type": "cli_tool",
+            "requirements": "CLI tool to quickly jot down notes to a local file",
+            "languages": ["Python"],
+            "frameworks": [],
+            "apis": "",
+            "team_size": "solo",
+        }
+        
+        orchestrator = PipelineOrchestrator(
+            llm_client=real_llm_client,
+            concurrency_manager=real_concurrency_manager,
+        )
+        
+        # Run complexity analysis
+        profile = orchestrator.analyze_complexity(interview_data)
+        
+        assert profile.depth_level == "minimal"
+        assert profile.score <= 4.0
+        assert profile.estimated_phase_count <= 4
+
+    @pytest.mark.asyncio
+    async def test_real_standard_pipeline(
+        self,
+        skip_if_no_api_key: None,
+        real_llm_client,
+        real_concurrency_manager,
+        tmp_path: Path,
+    ) -> None:
+        """Run actual pipeline with standard complexity project."""
+        from src.pipeline.compose import PipelineOrchestrator
+        
+        interview_data = {
+            "project_name": "task-api",
+            "project_type": "api",
+            "requirements": "REST API for task management with authentication and database",
+            "languages": ["Python"],
+            "frameworks": ["FastAPI", "SQLAlchemy"],
+            "apis": ["auth0"],
+            "team_size": "3",
+        }
+        
+        orchestrator = PipelineOrchestrator(
+            llm_client=real_llm_client,
+            concurrency_manager=real_concurrency_manager,
+        )
+        
+        profile = orchestrator.analyze_complexity(interview_data)
+        
+        assert profile.depth_level in ["standard", "detailed"]
+        assert 4.0 < profile.score <= 12.0
+        assert 5 <= profile.estimated_phase_count <= 7
+
+    @pytest.mark.asyncio
+    async def test_real_detailed_pipeline(
+        self,
+        skip_if_no_api_key: None,
+        real_llm_client,
+        real_concurrency_manager,
+        tmp_path: Path,
+    ) -> None:
+        """Run actual pipeline with detailed complexity project."""
+        from src.pipeline.compose import PipelineOrchestrator
+        
+        interview_data = {
+            "project_name": "enterprise-platform",
+            "project_type": "saas",
+            "requirements": "Multi-tenant SaaS platform with real-time collaboration, ML recommendations, and multi-region deployment",
+            "languages": ["TypeScript", "Python"],
+            "frameworks": ["Next.js", "FastAPI", "PyTorch"],
+            "apis": ["stripe", "sendgrid", "auth0", "datadog", "cloudflare", "openai"],
+            "team_size": "15",
+        }
+        
+        orchestrator = PipelineOrchestrator(
+            llm_client=real_llm_client,
+            concurrency_manager=real_concurrency_manager,
+        )
+        
+        profile = orchestrator.analyze_complexity(interview_data)
+        
+        assert profile.depth_level == "detailed"
+        assert profile.score >= 8.0
+        assert profile.estimated_phase_count >= 7
+
diff --git a/tests/integration/test_adaptive_pipeline_orchestrator.py b/tests/integration/test_adaptive_pipeline_orchestrator.py
new file mode 100644
index 0000000..2fd3a2a
--- /dev/null
+++ b/tests/integration/test_adaptive_pipeline_orchestrator.py
@@ -0,0 +1,322 @@
+"""Integration tests for adaptive pipeline orchestrator."""
+
+from __future__ import annotations
+
+import pytest
+from pathlib import Path
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from src.pipeline.compose import PipelineOrchestrator
+from src.interview.complexity_analyzer import ComplexityProfile
+from src.pipeline.design_validator import DesignValidationReport
+from src.pipeline.design_correction_loop import DesignCorrectionResult
+from src.concurrency import ConcurrencyManager
+
+
+@pytest.fixture
+def mock_llm_client() -> MagicMock:
+    """Create a mock LLM client."""
+    client = MagicMock()
+    client.generate = AsyncMock(return_value="Mock generated content")
+    client.last_usage_metadata = None
+    return client
+
+
+@pytest.fixture
+def concurrency_manager() -> ConcurrencyManager:
+    """Create a concurrency manager."""
+    return ConcurrencyManager(max_concurrent=5)
+
+
+@pytest.fixture
+def orchestrator(mock_llm_client: MagicMock, concurrency_manager: ConcurrencyManager) -> PipelineOrchestrator:
+    """Create a pipeline orchestrator with mocked dependencies."""
+    return PipelineOrchestrator(
+        llm_client=mock_llm_client,
+        concurrency_manager=concurrency_manager,
+    )
+
+
+class TestComplexityAnalysis:
+    """Tests for complexity analysis method."""
+
+    def test_analyze_complexity_trivial_project(self, orchestrator: PipelineOrchestrator) -> None:
+        """Test complexity analysis for a trivial CLI project."""
+        interview_data = {
+            "project_type": "cli_tool",
+            "requirements": "Simple command-line utility",
+            "apis": "",
+            "team_size": "1",
+        }
+        
+        profile = orchestrator.analyze_complexity(interview_data)
+        
+        assert isinstance(profile, ComplexityProfile)
+        assert profile.project_type_bucket == "cli_tool"
+        assert profile.depth_level == "minimal"
+        assert profile.estimated_phase_count <= 5
+
+    def test_analyze_complexity_complex_saas(self, orchestrator: PipelineOrchestrator) -> None:
+        """Test complexity analysis for a complex SaaS project."""
+        interview_data = {
+            "project_type": "saas platform",
+            "requirements": "Multi-region real-time collaboration",
+            "apis": "Stripe, SendGrid, Twilio, AWS S3, Auth0",
+            "team_size": "8",
+        }
+        
+        profile = orchestrator.analyze_complexity(interview_data)
+        
+        assert isinstance(profile, ComplexityProfile)
+        assert profile.depth_level == "detailed"
+        assert profile.score >= 7
+        assert profile.estimated_phase_count >= 5
+
+
+class TestDesignValidation:
+    """Tests for design validation method."""
+
+    def test_validate_design_complete(self, orchestrator: PipelineOrchestrator) -> None:
+        """Test validation of a complete design."""
+        design_text = """
+        # Project Architecture
+        
+        ## Architecture Overview
+        This is a web application with REST API.
+        
+        ## Database
+        PostgreSQL data model with users table.
+        
+        ## Testing
+        Unit tests and integration tests required.
+        """
+        
+        report = orchestrator.validate_design(design_text)
+        
+        assert isinstance(report, DesignValidationReport)
+        assert report.checks["completeness"] is True
+
+    def test_validate_design_incomplete(self, orchestrator: PipelineOrchestrator) -> None:
+        """Test validation of an incomplete design."""
+        design_text = """
+        # Project
+        
+        This is just a simple description without proper sections.
+        """
+        
+        report = orchestrator.validate_design(design_text)
+        
+        assert isinstance(report, DesignValidationReport)
+        assert report.is_valid is False
+        assert len(report.issues) > 0
+
+
+class TestCorrectionLoop:
+    """Tests for design correction loop method."""
+
+    def test_run_correction_loop_valid_design(self, orchestrator: PipelineOrchestrator) -> None:
+        """Test correction loop with already valid design."""
+        design_text = """
+        # Architecture Overview
+        This is a standard web application.
+        
+        ## Database
+        PostgreSQL data model.
+        
+        ## Testing
+        Comprehensive test coverage.
+        """
+        
+        result = orchestrator.run_correction_loop(design_text)
+        
+        assert isinstance(result, DesignCorrectionResult)
+        assert result.validation.is_valid
+        assert not result.requires_human_review
+        assert not result.max_iterations_reached
+
+    def test_run_correction_loop_with_complexity(self, orchestrator: PipelineOrchestrator) -> None:
+        """Test correction loop with complexity profile."""
+        design_text = """
+        # Architecture
+        Simple CRUD application.
+        
+        ## Database
+        SQLite storage.
+        
+        ## Testing
+        Basic tests.
+        """
+        
+        profile = ComplexityProfile(
+            project_type_bucket="cli_tool",
+            technical_complexity_bucket="simple_crud",
+            integration_bucket="standalone",
+            team_size_bucket="solo",
+            score=1.0,
+            estimated_phase_count=3,
+            depth_level="minimal",
+            confidence=0.9,
+        )
+        
+        result = orchestrator.run_correction_loop(design_text, complexity_profile=profile)
+        
+        assert isinstance(result, DesignCorrectionResult)
+
+
+class TestMarkdownGeneration:
+    """Tests for markdown generation helpers."""
+
+    def test_complexity_profile_to_markdown(self, orchestrator: PipelineOrchestrator) -> None:
+        """Test complexity profile markdown generation."""
+        profile = ComplexityProfile(
+            project_type_bucket="web_app",
+            technical_complexity_bucket="auth_db",
+            integration_bucket="1_2_services",
+            team_size_bucket="2_3",
+            score=6.0,
+            estimated_phase_count=5,
+            depth_level="standard",
+            confidence=0.85,
+        )
+        
+        markdown = orchestrator._complexity_profile_to_markdown(profile)
+        
+        assert "# Complexity Profile" in markdown
+        assert "6.0" in markdown
+        assert "standard" in markdown
+        assert "web_app" in markdown
+
+    def test_validation_report_to_markdown_valid(self, orchestrator: PipelineOrchestrator) -> None:
+        """Test validation report markdown for valid design."""
+        report = DesignValidationReport(
+            is_valid=True,
+            auto_correctable=True,
+            issues=[],
+            checks={"completeness": True, "consistency": True},
+        )
+        
+        markdown = orchestrator._validation_report_to_markdown(report)
+        
+        assert "# Design Validation Report" in markdown
+        assert "Valid**: Yes" in markdown
+        assert "[PASS]" in markdown
+
+    def test_validation_report_to_markdown_invalid(self, orchestrator: PipelineOrchestrator) -> None:
+        """Test validation report markdown for invalid design."""
+        from src.pipeline.design_validator import DesignValidationIssue
+        
+        report = DesignValidationReport(
+            is_valid=False,
+            auto_correctable=True,
+            issues=[
+                DesignValidationIssue(
+                    code="completeness.missing_sections",
+                    message="Missing required sections",
+                    auto_correctable=True,
+                )
+            ],
+            checks={"completeness": False, "consistency": True},
+        )
+        
+        markdown = orchestrator._validation_report_to_markdown(report)
+        
+        assert "Valid**: No" in markdown
+        assert "[FAIL]" in markdown
+        assert "## Issues" in markdown
+        assert "completeness.missing_sections" in markdown
+
+
+class TestAdaptivePipelineIntegration:
+    """Integration tests for full adaptive pipeline."""
+
+    @pytest.mark.asyncio
+    async def test_adaptive_pipeline_basic_flow(
+        self,
+        mock_llm_client: MagicMock,
+        concurrency_manager: ConcurrencyManager,
+        tmp_path: Path,
+    ) -> None:
+        """Test basic adaptive pipeline flow with mocked LLM."""
+        from src.models import ProjectDesign
+        
+        # Setup mock responses
+        mock_llm_client.generate = AsyncMock(return_value="""
+        # Architecture Overview
+        A simple web application with REST API.
+        
+        ## Database
+        PostgreSQL with users table.
+        
+        ## Testing
+        Unit tests and integration tests.
+        """)
+        
+        orchestrator = PipelineOrchestrator(
+            llm_client=mock_llm_client,
+            concurrency_manager=concurrency_manager,
+        )
+        
+        # Mock the project design generator
+        mock_design = ProjectDesign(
+            project_name="TestProject",
+            objectives=["Build simple app"],
+            tech_stack=["Python", "FastAPI"],
+            architecture_overview="""
+            # Architecture
+            REST API backend.
+            
+            ## Database
+            PostgreSQL.
+            
+            ## Testing
+            Pytest.
+            """,
+        )
+        orchestrator.project_design_gen.generate = AsyncMock(return_value=mock_design)
+        
+        # Mock devplan generators
+        from src.models import DevPlan, DevPlanPhase, DevPlanStep
+        mock_devplan = DevPlan(
+            phases=[
+                DevPlanPhase(
+                    number=1,
+                    title="Setup",
+                    steps=[DevPlanStep(number="1.1", description="Initialize project")],
+                )
+            ],
+            summary="Test devplan",
+        )
+        orchestrator.basic_devplan_gen.generate = AsyncMock(return_value=mock_devplan)
+        orchestrator.detailed_devplan_gen.generate = AsyncMock(return_value=mock_devplan)
+        
+        interview_data = {
+            "project_type": "api",
+            "requirements": "Simple REST API",
+            "apis": "",
+            "team_size": "1",
+        }
+        
+        # Run adaptive pipeline
+        result = await orchestrator.run_adaptive_pipeline(
+            project_name="TestProject",
+            languages=["Python"],
+            requirements="Build a simple API",
+            interview_data=interview_data,
+            output_dir=str(tmp_path),
+            save_artifacts=True,
+            enable_validation=True,
+            enable_correction=False,  # Skip correction for faster test
+        )
+        
+        project_design, devplan, handoff, complexity_profile = result
+        
+        # Verify results
+        assert project_design is not None
+        assert devplan is not None
+        assert handoff is not None
+        assert complexity_profile is not None
+        
+        # Verify artifacts were saved
+        assert (tmp_path / "complexity_profile.md").exists()
+        assert (tmp_path / "project_design.md").exists()
diff --git a/tests/integration/test_interview_to_complexity_flow.py b/tests/integration/test_interview_to_complexity_flow.py
new file mode 100644
index 0000000..966f73c
--- /dev/null
+++ b/tests/integration/test_interview_to_complexity_flow.py
@@ -0,0 +1,38 @@
+from src.interview.interview_pipeline import InterviewPipeline, InterviewPipelineResult
+from src.interview.complexity_analyzer import ComplexityProfile
+
+
+def test_interview_pipeline_trivial_project():
+    pipeline = InterviewPipeline()
+
+    interview_data = {
+        "project_type": "CLI Tool",
+        "requirements": "Tiny helper to manage local text files.",
+        "team_size": "1",
+    }
+
+    result = pipeline.run(interview_data)
+
+    assert isinstance(result, InterviewPipelineResult)
+    assert isinstance(result.complexity_profile, ComplexityProfile)
+    assert result.inputs["project_type"] == "CLI Tool"
+    assert result.complexity_profile.estimated_phase_count == 3
+
+
+def test_interview_pipeline_more_complex_web_app():
+    pipeline = InterviewPipeline()
+
+    interview_data = {
+        "project_type": "Web App",
+        "requirements": "Realtime collaborative editor with authentication and database-backed storage.",
+        "frameworks": "Next.js, FastAPI",
+        "apis": ["auth0", "payments", "analytics"],
+        "team_size": "4-6",
+    }
+
+    result = pipeline.run(interview_data)
+
+    assert isinstance(result, InterviewPipelineResult)
+    assert isinstance(result.complexity_profile, ComplexityProfile)
+    assert result.complexity_profile.score > 3
+    assert result.complexity_profile.estimated_phase_count >= 5
diff --git a/tests/integration/test_mock_adaptive_pipeline.py b/tests/integration/test_mock_adaptive_pipeline.py
new file mode 100644
index 0000000..3c70af1
--- /dev/null
+++ b/tests/integration/test_mock_adaptive_pipeline.py
@@ -0,0 +1,34 @@
+from src.pipeline.mock_adaptive_pipeline import MockAdaptivePipeline, MockAdaptivePipelineResult
+
+
+def test_mock_adaptive_pipeline_trivial_project():
+    pipeline = MockAdaptivePipeline()
+
+    interview_data = {
+        "project_type": "CLI Tool",
+        "requirements": "Simple local CLI helper.",
+        "team_size": "1",
+    }
+
+    result = pipeline.run(interview_data)
+
+    assert isinstance(result, MockAdaptivePipelineResult)
+    assert result.devplan.phases
+    assert result.interview.complexity_profile.estimated_phase_count == 3
+    assert len(result.devplan.phases) == 3
+
+
+def test_mock_adaptive_pipeline_more_complex_project():
+    pipeline = MockAdaptivePipeline()
+
+    interview_data = {
+        "project_type": "Web App",
+        "requirements": "Complex SaaS platform with realtime collab and ML.",
+        "apis": ["billing", "auth", "analytics", "crm"],
+        "team_size": "7+",
+    }
+
+    result = pipeline.run(interview_data)
+
+    assert result.interview.complexity_profile.estimated_phase_count >= 5
+    assert len(result.devplan.phases) == result.interview.complexity_profile.estimated_phase_count
diff --git a/tests/integration/test_validation_and_correction.py b/tests/integration/test_validation_and_correction.py
new file mode 100644
index 0000000..e5a829f
--- /dev/null
+++ b/tests/integration/test_validation_and_correction.py
@@ -0,0 +1,14 @@
+from src.pipeline.design_correction_loop import DesignCorrectionLoop
+
+
+def test_validation_and_correction_integration():
+    loop = DesignCorrectionLoop()
+
+    design = """# Architecture\n\nSmall web app.\n\n## Data Model\nSimple.\n\n## Testing\nBasic tests.\n\nTrivial project but mentions microservices and event sourcing without scalability discussion."""
+
+    result = loop.run(design)
+
+    # For this mock, we don't assert on exact text, only that the loop completes
+    assert result.validation is not None
+    assert result.review is not None
+    assert result.validation.issues or result.max_iterations_reached in {True, False}
diff --git a/tests/test_pipeline_smoke.py b/tests/test_pipeline_smoke.py
new file mode 100644
index 0000000..9495dcd
--- /dev/null
+++ b/tests/test_pipeline_smoke.py
@@ -0,0 +1,28 @@
+"""Smoke test for full pipeline to ensure docs get generated."""
+
+import tempfile
+import pytest
+from pathlib import Path
+
+
+def test_pipeline_smoke_test():
+    """Run a minimal pipeline to verify all docs get generated."""
+    # This is a placeholder test - would need to implement actual pipeline testing
+    # For now, just verify the test framework works
+
+    # Create a temporary directory for test artifacts
+    with tempfile.TemporaryDirectory() as temp_dir:
+        docs_dir = Path(temp_dir) / "docs"
+        docs_dir.mkdir()
+
+        # Placeholder assertions - in real implementation would:
+        # 1. Run a tiny pipeline on a minimal project
+        # 2. Assert design.md exists and has key sections
+        # 3. Assert devplan.md exists and has phases
+        # 4. Assert handoff.md exists and has links
+
+        assert docs_dir.exists()
+        assert docs_dir.is_dir()
+
+        # This test would fail until we implement the real pipeline smoke test
+        # pytest.skip("Pipeline smoke test not yet implemented")
\ No newline at end of file
diff --git a/tests/unit/test_adaptive_design_generator.py b/tests/unit/test_adaptive_design_generator.py
new file mode 100644
index 0000000..133903f
--- /dev/null
+++ b/tests/unit/test_adaptive_design_generator.py
@@ -0,0 +1,52 @@
+from src.interview.complexity_analyzer import ComplexityProfile
+from src.pipeline.design_generator import AdaptiveDesignGenerator
+
+
+def _profile(score: float, depth: str, phases: int) -> ComplexityProfile:
+    return ComplexityProfile(
+        project_type_bucket="web_app",
+        technical_complexity_bucket="simple_crud",
+        integration_bucket="standalone",
+        team_size_bucket="solo",
+        score=score,
+        estimated_phase_count=phases,
+        depth_level=depth,  # type: ignore[arg-type]
+        confidence=0.9,
+    )
+
+
+def test_minimal_depth_has_core_sections_only():
+    gen = AdaptiveDesignGenerator()
+    profile = _profile(score=2.0, depth="minimal", phases=3)
+
+    text = gen.generate(profile, project_label="CLI Tool")
+
+    assert "# Adaptive Design for CLI Tool" in text
+    assert "## Architecture" in text
+    assert "## Data Model" in text
+    assert "## Testing" in text
+    # Minimal depth should not include advanced sections
+    assert "## Security" not in text
+    assert "## Scalability" not in text
+
+
+def test_standard_depth_includes_deployment_and_dependencies():
+    gen = AdaptiveDesignGenerator()
+    profile = _profile(score=5.0, depth="standard", phases=5)
+
+    text = gen.generate(profile, project_label="Web App")
+
+    assert "## Deployment" in text
+    assert "## Dependencies" in text
+
+
+def test_detailed_depth_includes_security_and_scalability():
+    gen = AdaptiveDesignGenerator()
+    profile = _profile(score=10.0, depth="detailed", phases=7)
+
+    text = gen.generate(profile, project_label="SaaS Platform")
+
+    assert "## Security" in text
+    assert "## Scalability & Reliability" in text
+    # Footer should reflect profile values
+    assert "Estimated phases: 7" in text
diff --git a/tests/unit/test_adaptive_devplan_generator.py b/tests/unit/test_adaptive_devplan_generator.py
new file mode 100644
index 0000000..cc659cb
--- /dev/null
+++ b/tests/unit/test_adaptive_devplan_generator.py
@@ -0,0 +1,49 @@
+from src.interview.complexity_analyzer import ComplexityProfile
+from src.pipeline.devplan_generator import AdaptiveDevPlanGenerator
+
+
+def _profile(score: float, depth: str, phases: int) -> ComplexityProfile:
+    return ComplexityProfile(
+        project_type_bucket="web_app",
+        technical_complexity_bucket="simple_crud",
+        integration_bucket="standalone",
+        team_size_bucket="solo",
+        score=score,
+        estimated_phase_count=phases,
+        depth_level=depth,  # type: ignore[arg-type]
+        confidence=0.9,
+    )
+
+
+def test_devplan_phase_count_matches_estimated_phases():
+    gen = AdaptiveDevPlanGenerator()
+    profile = _profile(score=2.0, depth="minimal", phases=3)
+
+    devplan = gen.generate(profile, project_label="CLI Tool")
+
+    assert len(devplan.phases) == 3
+    assert devplan.summary.startswith("Adaptive devplan for CLI Tool")
+
+
+def test_devplan_uses_canonical_names_for_common_counts():
+    gen = AdaptiveDevPlanGenerator()
+    profile = _profile(score=6.0, depth="standard", phases=5)
+
+    devplan = gen.generate(profile, project_label="Web App")
+
+    titles = [p.title for p in devplan.phases]
+    assert "Foundation" in titles[0]
+    assert "Deployment" in titles[-1]
+
+
+def test_devplan_handles_larger_phase_counts():
+    gen = AdaptiveDevPlanGenerator()
+    profile = _profile(score=15.0, depth="detailed", phases=10)
+
+    devplan = gen.generate(profile, project_label="SaaS")
+
+    assert len(devplan.phases) == 10
+    # Ensure we at least have some of the extended names present
+    titles = [p.title for p in devplan.phases]
+    assert any("Auth & Security" in t for t in titles)
+    assert any("Deployment" in t for t in titles)
diff --git a/tests/unit/test_complexity_analyzer.py b/tests/unit/test_complexity_analyzer.py
new file mode 100644
index 0000000..39f43b8
--- /dev/null
+++ b/tests/unit/test_complexity_analyzer.py
@@ -0,0 +1,85 @@
+from src.interview.complexity_analyzer import (
+    ComplexityAnalyzer,
+    estimate_phase_count,
+    ComplexityProfile,
+)
+
+
+def test_estimate_phase_count_thresholds():
+    # Test boundary conditions for phase count estimation
+    # Formula: score <= 3 -> 3, <= 7 -> 5, <= 12 -> 7, else min(9 + (score-12)//2, 15)
+    assert estimate_phase_count(0) == 3
+    assert estimate_phase_count(3) == 3
+    assert estimate_phase_count(4) == 5
+    assert estimate_phase_count(7) == 5
+    assert estimate_phase_count(8) == 7
+    assert estimate_phase_count(12) == 7
+    assert estimate_phase_count(13) == 9
+    # At score=20: 9 + (20-12)//2 = 9 + 4 = 13
+    assert estimate_phase_count(20) == 13
+    # At score=24: 9 + (24-12)//2 = 9 + 6 = 15 (capped)
+    assert estimate_phase_count(24) == 15
+    # At score=30: 9 + (30-12)//2 = 9 + 9 = 18, but capped at 15
+    assert estimate_phase_count(30) == 15
+
+
+def test_analyze_trivial_cli_solo():
+    analyzer = ComplexityAnalyzer()
+    data = {
+        "project_type": "CLI Tool",
+        "requirements": "Simple CRUD over a local file",
+        "team_size": "1",
+    }
+
+    profile = analyzer.analyze(data)
+
+    assert isinstance(profile, ComplexityProfile)
+    assert profile.project_type_bucket == "cli_tool"
+    assert profile.technical_complexity_bucket == "simple_crud"
+    assert profile.integration_bucket == "standalone"
+    assert profile.team_size_bucket == "solo"
+    assert profile.score <= 3
+    assert profile.estimated_phase_count == 3
+    assert profile.depth_level == "minimal"
+
+
+def test_analyze_standard_web_app_small_team():
+    analyzer = ComplexityAnalyzer()
+    data = {
+        "project_type": "Web App",
+        "requirements": "Web app with auth and database-backed CRUD UI.",
+        "frameworks": "Django",
+        "apis": ["payments"],
+        "team_size": "3",
+    }
+
+    profile = analyzer.analyze(data)
+
+    assert profile.project_type_bucket == "web_app"
+    assert profile.technical_complexity_bucket in {"auth_db", "simple_crud"}
+    assert profile.integration_bucket == "1_2_services"
+    assert profile.team_size_bucket == "2_3"
+    assert 3 < profile.score <= 12
+    assert profile.estimated_phase_count in {5, 7}
+    assert profile.depth_level in {"standard", "detailed"}
+
+
+def test_analyze_complex_saas_multi_region():
+    analyzer = ComplexityAnalyzer()
+    data = {
+        "project_type": "SaaS Platform",
+        "requirements": "Multi-region SaaS with realtime collaboration and ML-based recommendations.",
+        "apis": ["billing", "email", "analytics", "crm", "support", "search"],
+        "team_size": "10",
+    }
+
+    profile = analyzer.analyze(data)
+
+    assert profile.project_type_bucket == "saas"
+    assert profile.technical_complexity_bucket in {"realtime", "ml_ai", "multi_region"}
+    assert profile.integration_bucket == "6_plus_services"
+    assert profile.team_size_bucket == "7_plus"
+    assert profile.score >= 7
+    assert profile.estimated_phase_count >= 7
+    assert profile.depth_level == "detailed"
+    assert 0.5 <= profile.confidence <= 1.0
diff --git a/tests/unit/test_design_correction_loop.py b/tests/unit/test_design_correction_loop.py
new file mode 100644
index 0000000..b696373
--- /dev/null
+++ b/tests/unit/test_design_correction_loop.py
@@ -0,0 +1,23 @@
+from src.pipeline.design_correction_loop import DesignCorrectionLoop
+
+
+def test_correction_loop_converges_for_fixable_issues():
+    loop = DesignCorrectionLoop()
+
+    design = """# Architecture\n\nMinimal design.\n\n## Data Model\nSimple.\n\n## Testing\nBasic tests.\n\nTrivial CLI implemented with microservices and CQRS and event sourcing."""
+
+    result = loop.run(design)
+
+    assert not result.requires_human_review
+    assert result.validation is not None
+
+
+def test_correction_loop_flags_non_auto_correctable():
+    loop = DesignCorrectionLoop()
+
+    # This design will trigger a non-auto-correctable consistency issue
+    design = """Architecture: must be monolith.\nAlso using microservices everywhere.\n\n## Data Model\nSimple.\n\n## Testing\nBasic tests."""
+
+    result = loop.run(design)
+
+    assert result.requires_human_review
diff --git a/tests/unit/test_design_validator.py b/tests/unit/test_design_validator.py
new file mode 100644
index 0000000..2dc87f0
--- /dev/null
+++ b/tests/unit/test_design_validator.py
@@ -0,0 +1,51 @@
+from src.pipeline.design_validator import DesignValidator, DesignValidationReport
+from src.interview.complexity_analyzer import ComplexityProfile
+
+
+def _simple_profile(score: float) -> ComplexityProfile:
+    return ComplexityProfile(
+        project_type_bucket="web_app",
+        technical_complexity_bucket="simple_crud",
+        integration_bucket="standalone",
+        team_size_bucket="solo",
+        score=score,
+        estimated_phase_count=3,
+        depth_level="minimal",
+        confidence=1.0,
+    )
+
+
+def test_design_validator_completeness_and_consistency():
+    validator = DesignValidator()
+    design = """# Architecture\n\nThis is an architecture overview.\n\n## Data Model\nWe use a simple schema.\n\n## Testing\nUnit and integration tests."""
+
+    report = validator.validate(design, complexity_profile=_simple_profile(2))
+
+    assert isinstance(report, DesignValidationReport)
+    assert report.is_valid
+    assert report.auto_correctable
+    assert not report.issues
+
+
+def test_design_validator_flags_over_engineering_for_trivial_project():
+    validator = DesignValidator()
+    design = """Trivial CLI but implemented with microservices and CQRS and event sourcing.\nArchitecture: microservices.\nData model: simple.\nTesting: basic."""
+
+    report = validator.validate(design, complexity_profile=_simple_profile(2))
+
+    assert not report.is_valid
+    codes = {issue.code for issue in report.issues}
+    assert "over_engineering.complex_patterns_for_simple_project" in codes
+
+
+def test_design_validator_scope_alignment_for_complex_project():
+    validator = DesignValidator()
+    # Design for complex project (score=10) that does NOT mention scalability
+    # Note: "scalab" substring is checked, so avoid that word entirely
+    design = """Complex SaaS platform.\nArchitecture: microservices.\nData model: relational.\nTesting: comprehensive.\n(No performance discussion here.)"""
+
+    report = validator.validate(design, complexity_profile=_simple_profile(10))
+
+    assert not report.is_valid
+    codes = {issue.code for issue in report.issues}
+    assert "scope_alignment.missing_scalability" in codes
diff --git a/tests/unit/test_llm_sanity_reviewer.py b/tests/unit/test_llm_sanity_reviewer.py
new file mode 100644
index 0000000..006f330
--- /dev/null
+++ b/tests/unit/test_llm_sanity_reviewer.py
@@ -0,0 +1,24 @@
+from src.pipeline.design_validator import DesignValidationReport, DesignValidationIssue
+from src.pipeline.llm_sanity_reviewer import LLMSanityReviewer, LLMSanityReviewResult
+
+
+def test_sanity_reviewer_confident_when_valid():
+    reviewer = LLMSanityReviewer()
+    report = DesignValidationReport(is_valid=True, auto_correctable=True, issues=[], checks={})
+
+    result = reviewer.review("ok", report)
+
+    assert isinstance(result, LLMSanityReviewResult)
+    assert result.confidence > 0.8
+    assert not result.risks
+
+
+def test_sanity_reviewer_reduces_confidence_on_issues():
+    reviewer = LLMSanityReviewer()
+    issue = DesignValidationIssue(code="x", message="", auto_correctable=False)
+    report = DesignValidationReport(is_valid=False, auto_correctable=False, issues=[issue], checks={})
+
+    result = reviewer.review("not ok", report)
+
+    assert result.confidence <= 0.7
+    assert "x" in result.risks
diff --git a/tests/unit/test_streaming.py b/tests/unit/test_streaming.py
index 20508ad..c6bff19 100644
--- a/tests/unit/test_streaming.py
+++ b/tests/unit/test_streaming.py
@@ -6,7 +6,62 @@
 from unittest.mock import Mock, patch, mock_open
 import tempfile
 
-from src.streaming import StreamingHandler, StreamingSimulator
+from src.streaming import (
+    StreamingHandler,
+    StreamingSimulator,
+    STREAMING_PREFIXES,
+    StreamingStage,
+)
+
+
+class TestStreamingPrefixes:
+    """Tests for adaptive pipeline streaming prefixes."""
+
+    def test_all_stages_have_prefixes(self):
+        """Verify all expected stages have prefix definitions."""
+        expected_stages: list[StreamingStage] = [
+            "design",
+            "devplan",
+            "handoff",
+            "complexity",
+            "validation",
+            "correction",
+            "follow_up",
+        ]
+        for stage in expected_stages:
+            assert stage in STREAMING_PREFIXES
+            prefix = STREAMING_PREFIXES[stage]
+            assert prefix.startswith("[")
+            assert prefix.endswith("] ")
+
+    def test_create_stage_handler_complexity(self):
+        """Test creating stage handler for complexity."""
+        handler = StreamingHandler.create_stage_handler("complexity")
+        assert handler.prefix == "[complexity] "
+        assert handler.enable_console is True
+
+    def test_create_stage_handler_validation(self):
+        """Test creating stage handler for validation."""
+        handler = StreamingHandler.create_stage_handler("validation")
+        assert handler.prefix == "[validation] "
+
+    def test_create_stage_handler_correction(self):
+        """Test creating stage handler for correction."""
+        handler = StreamingHandler.create_stage_handler("correction")
+        assert handler.prefix == "[correction] "
+
+    def test_create_stage_handler_follow_up(self):
+        """Test creating stage handler for follow_up."""
+        handler = StreamingHandler.create_stage_handler("follow_up")
+        assert handler.prefix == "[follow_up] "
+
+    def test_create_stage_handler_with_log_file(self, tmp_path: Path):
+        """Test stage handler with file logging."""
+        log_file = tmp_path / "stream.log"
+        handler = StreamingHandler.create_stage_handler("complexity", log_file=log_file)
+        assert handler.prefix == "[complexity] "
+        assert handler.log_file == log_file
+        assert handler.enable_console is True
 
 
 class TestStreamingHandlerInitialization: