     1→{
     2→  "task_description": "Multi-LLM Agentic Development Platform\n\n  I want to build an advanced agentic development system that extends and integrates the best concepts from Autocoder 2.0 / Auto-Claude with multi-model orchestration and adaptive project management.\n\n  Core Features\n\n  1. Multi-LLM Provider Support\n  - Support multiple LLM providers: Claude (Code & API), Gemini, Grok, Ollama, and others\n  - Strategic model assignment - route tasks to models best suited for them:\n    - Ollama for local, token-free lightweight tasks (file analysis, simple transforms, templating)\n    - Claude Sonnet/Opus for complex reasoning and architecture\n    - Gemini for multimodal analysis and large context windows\n    - Grok for real-time information and alternative perspectives\n  - Cross-model validation: have different LLMs review each other's work for accuracy and quality assurance\n  - Cost optimization: intelligently balance between cloud and local models\n\n  2. Version Control Integration\n  - Native Git and Gitea support\n  - Automatic branching strategies for features/tasks\n  - Commit message generation aligned with conventional commits\n  - PR creation with comprehensive descriptions\n  - Support for reviewing and iterating on code in branches\n\n  3. Adaptive Spec System\n  - Initial spec-app style interview to gather requirements\n  - Re-interview capability: as the project evolves, conduct follow-up interviews to:\n    - Clarify ambiguous requirements that emerged during development\n    - Gather feedback on implemented features\n    - Adjust scope based on discoveries\n    - Validate assumptions with the user\n  - Spec versioning: track how requirements evolve over time\n  - Continuous alignment: ensure implementation stays true to user intent\n\n  4. Agent Skill System\n  - Extensible skill/addon architecture for specialized agent capabilities\n  - Skills can be model-specific or model-agnostic\n  - Examples: code review, security scanning, performance optimization, documentation generation\n  - Custom skill creation framework\n  - Skill composition: chain skills together for complex workflows\n\n  5. Project Steering & Course Correction\n  - Mid-flight adjustments: ability to redirect project direction after work has begun\n  - Checkpoint system: review progress at milestones and adjust plans\n  - Context preservation: maintain full project history when steering changes\n  - Impact analysis: understand implications of direction changes\n  - Graceful pivoting: refactor or adapt existing work rather than starting over\n\n  6. Intelligent Orchestration\n  - Task decomposition with model-specific assignments\n  - Parallel execution where possible\n  - Dependency management between tasks\n  - Progressive refinement: iterative improvement cycles\n  - Fallback strategies when a model fails or produces poor results\n\n  7. Quality Assurance\n  - Multi-model consensus for critical decisions\n  - Automated testing integration\n  - Code quality metrics and reporting\n  - Security vulnerability scanning\n  - Performance profiling\n\n  Technical Architecture\n\n  - Backend: Python (FastAPI) for orchestration layer\n  - Frontend: React/TypeScript UI for project management and monitoring\n  - Model Integration: Unified API wrapper supporting all providers\n  - State Management: Track project state, agent activities, and decisions\n  - Database: Store specs, decisions, task history, and model interactions\n  - MCP Server: Feature graph and skill management\n\n  Key Differentiators\n\n  1. Model democracy: No single LLM is the source of truth - leverage collective intelligence\n  2. Adaptive requirements: Specs evolve with the project, not frozen at start\n  3. Local-first option: Can run meaningful work without API costs via Ollama\n  4. Course correction: Projects aren't rigid - steer and adapt as you learn\n  5. Transparency: Full visibility into which models did what and why\n\n  Use Cases\n\n  - Large greenfield projects with evolving requirements\n  - Migrating/refactoring existing codebases with uncertain scope\n  - Research projects where requirements emerge through exploration\n  - Cost-sensitive projects that need to optimize token usage\n  - High-stakes projects requiring multi-model validation\n\n  Success Criteria\n\n  - Successfully complete a full project lifecycle: spec → implementation → steering → completion\n  - Demonstrate cost savings through intelligent model routing\n  - Show quality improvements through cross-model validation\n  - Handle mid-project requirement changes gracefully\n  - Support at least 3 different LLM providers working in concert",
     3→  "workflow_type": "refactoring"
     4→}

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>

Multi-LLM Agentic Development Platform

  I want to build an advanced agentic development system that extends and integrates the best concepts from Autocoder 2.0 / Auto-Claude with multi-model orchestration and adaptive project management.

  Core Features

  1. Multi-LLM Provider Support
  - Support multiple LLM providers: Claude (Code & API), Gemini, Grok, Ollama, and others
  - Strategic model assignment - route tasks to models best suited for them:
    - Ollama for local, token-free lightweight tasks (file analysis, simple transforms, templating)
    - Claude Sonnet/Opus for complex reasoning and architecture
    - Gemini for multimodal analysis and large context windows
    - Grok for real-time information and alternative perspectives
  - Cross-model validation: have different LLMs review each other's work for accuracy and quality assurance
  - Cost optimization: intelligently balance between cloud and local models

  2. Version Control Integration
  - Native Git and Gitea support
  - Automatic branching strategies for features/tasks
  - Commit message generation aligned with conventional commits
  - PR creation with comprehensive descriptions
  - Support for reviewing and iterating on code in branches

  3. Adaptive Spec System
  - Initial spec-app style interview to gather requirements
  - Re-interview capability: as the project evolves, conduct follow-up interviews to:
    - Clarify ambiguous requirements that emerged during development
    - Gather feedback on implemented features
    - Adjust scope based on discoveries
    - Validate assumptions with the user
  - Spec versioning: track how requirements evolve over time
  - Continuous alignment: ensure implementation stays true to user intent

  4. Agent Skill System
  - Extensible skill/addon architecture for specialized agent capabilities
  - Skills can be model-specific or model-agnostic
  - Examples: code review, security scanning, performance optimization, documentation generation
  - Custom skill creation framework
  - Skill composition: chain skills together for complex workflows

  5. Project Steering & Course Correction
  - Mid-flight adjustments: ability to redirect project direction after work has begun
  - Checkpoint system: review progress at milestones and adjust plans
  - Context preservation: maintain full project history when steering changes
  - Impact analysis: understand implications of direction changes
  - Graceful pivoting: refactor or adapt existing work rather than starting over

  6. Intelligent Orchestration
  - Task decomposition with model-specific assignments
  - Parallel execution where possible
  - Dependency management between tasks
  - Progressive refinement: iterative improvement cycles
  - Fallback strategies when a model fails or produces poor results

  7. Quality Assurance
  - Multi-model consensus for critical decisions
  - Automated testing integration
  - Code quality metrics and reporting
  - Security vulnerability scanning
  - Performance profiling

  Technical Architecture

  - Backend: Python (FastAPI) for orchestration layer
  - Frontend: React/TypeScript UI for project management and monitoring
  - Model Integration: Unified API wrapper supporting all providers
  - State Management: Track project state, agent activities, and decisions
  - Database: Store specs, decisions, task history, and model interactions
  - MCP Server: Feature graph and skill management

  Key Differentiators

  1. Model democracy: No single LLM is the source of truth - leverage collective intelligence
  2. Adaptive requirements: Specs evolve with the project, not frozen at start
  3. Local-first option: Can run meaningful work without API costs via Ollama
  4. Course correction: Projects aren't rigid - steer and adapt as you learn
  5. Transparency: Full visibility into which models did what and why

  Use Cases

  - Large greenfield projects with evolving requirements
  - Migrating/refactoring existing codebases with uncertain scope
  - Research projects where requirements emerge through exploration
  - Cost-sensitive projects that need to optimize token usage
  - High-stakes projects requiring multi-model validation

  Success Criteria

  - Successfully complete a full project lifecycle: spec → implementation → steering → completion
  - Demonstrate cost savings through intelligent model routing
  - Show quality improvements through cross-model validation
  - Handle mid-project requirement changes gracefully
  - Support at least 3 different LLM providers working in concert


     1→{
     2→  "task_description": "Multi-LLM Agentic Development Platform\n\n  I want to build an advanced agentic development system that extends and integrates the best concepts from Autocoder 2.0 / Auto-Claude with multi-model orchestration and adaptive project management.\n\n  Core Features\n\n  1. Multi-LLM Provider Support\n  - Support multiple LLM providers: Claude (Code & API), Gemini, Grok, Ollama, and others\n  - Strategic model assignment - route tasks to models best suited for them:\n    - Ollama for local, token-free lightweight tasks (file analysis, simple transforms, templating)\n    - Claude Sonnet/Opus for complex reasoning and architecture\n    - Gemini for multimodal analysis and large context windows\n    - Grok for real-time information and alternative perspectives\n  - Cross-model validation: have different LLMs review each other's work for accuracy and quality assurance\n  - Cost optimization: intelligently balance between cloud and local models\n\n  2. Version Control Integration\n  - Native Git and Gitea support\n  - Automatic branching strategies for features/tasks\n  - Commit message generation aligned with conventional commits\n  - PR creation with comprehensive descriptions\n  - Support for reviewing and iterating on code in branches\n\n  3. Adaptive Spec System\n  - Initial spec-app style interview to gather requirements\n  - Re-interview capability: as the project evolves, conduct follow-up interviews to:\n    - Clarify ambiguous requirements that emerged during development\n    - Gather feedback on implemented features\n    - Adjust scope based on discoveries\n    - Validate assumptions with the user\n  - Spec versioning: track how requirements evolve over time\n  - Continuous alignment: ensure implementation stays true to user intent\n\n  4. Agent Skill System\n  - Extensible skill/addon architecture for specialized agent capabilities\n  - Skills can be model-specific or model-agnostic\n  - Examples: code review, security scanning, performance optimization, documentation generation\n  - Custom skill creation framework\n  - Skill composition: chain skills together for complex workflows\n\n  5. Project Steering & Course Correction\n  - Mid-flight adjustments: ability to redirect project direction after work has begun\n  - Checkpoint system: review progress at milestones and adjust plans\n  - Context preservation: maintain full project history when steering changes\n  - Impact analysis: understand implications of direction changes\n  - Graceful pivoting: refactor or adapt existing work rather than starting over\n\n  6. Intelligent Orchestration\n  - Task decomposition with model-specific assignments\n  - Parallel execution where possible\n  - Dependency management between tasks\n  - Progressive refinement: iterative improvement cycles\n  - Fallback strategies when a model fails or produces poor results\n\n  7. Quality Assurance\n  - Multi-model consensus for critical decisions\n  - Automated testing integration\n  - Code quality metrics and reporting\n  - Security vulnerability scanning\n  - Performance profiling\n\n  Technical Architecture\n\n  - Backend: Python (FastAPI) for orchestration layer\n  - Frontend: React/TypeScript UI for project management and monitoring\n  - Model Integration: Unified API wrapper supporting all providers\n  - State Management: Track project state, agent activities, and decisions\n  - Database: Store specs, decisions, task history, and model interactions\n  - MCP Server: Feature graph and skill management\n\n  Key Differentiators\n\n  1. Model democracy: No single LLM is the source of truth - leverage collective intelligence\n  2. Adaptive requirements: Specs evolve with the project, not frozen at start\n  3. Local-first option: Can run meaningful work without API costs via Ollama\n  4. Course correction: Projects aren't rigid - steer and adapt as you learn\n  5. Transparency: Full visibility into which models did what and why\n\n  Use Cases\n\n  - Large greenfield projects with evolving requirements\n  - Migrating/refactoring existing codebases with uncertain scope\n  - Research projects where requirements emerge through exploration\n  - Cost-sensitive projects that need to optimize token usage\n  - High-stakes projects requiring multi-model validation\n\n  Success Criteria\n\n  - Successfully complete a full project lifecycle: spec \u2192 implementation \u2192 steering \u2192 completion\n  - Demonstrate cost savings through intelligent model routing\n  - Show quality improvements through cross-model validation\n  - Handle mid-project requirement changes gracefully\n  - Support at least 3 different LLM providers working in concert",
     3→  "scoped_services": [],
     4→  "files_to_modify": [],
     5→  "files_to_reference": [],
     6→  "created_at": "2026-01-12T11:50:41.978005"
     7→}

<system-reminder>
Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.
</system-reminder>


Excellent, I now have all four context files loaded. Let me do a deep analysis of the spec.md against the research.json and requirements.json to find issues.

## PHASE 1: DEEP ANALYSIS

### 1.1: Technical Accuracy

Let me compare the spec against research findings:

**Package names:**
- ✅ Spec says `anthropic` - research confirms `pip install anthropic`
- ✅ Spec says `google-genai` - research confirms (NOT deprecated `google-generativeai`)
- ✅ Spec says `xai-sdk` - research confirms (NOT community alternatives)
- ✅ Spec says `ollama` - research confirms
- ✅ Spec says `litellm` - research confirms
- ✅ Spec says `mcp>=1.25,<2` - research confirms
- ✅ Spec says `GitPython` - research confirms
- ✅ Spec says `py-gitea` - research confirms

**API patterns:**
Looking at line 229 in spec.md - the imports:
```python
from anthropic import AsyncAnthropic
from google import genai
from xai_sdk import AsyncClient as XAIClient
from ollama import AsyncClient as OllamaClient
```

Let me check research.json:
- Anthropic: `from anthropic import AsyncAnthropic` ✅
- Google Gemini: `from google import genai` ✅
- xAI: Research says `from xai_sdk import AsyncClient` ✅
- Ollama: Research says `from ollama import AsyncClient` ✅

**LiteLLM patterns:**
Spec line 181-191 shows:
```python
from litellm import completion, acompletion
response = await acompletion(model=model, messages=messages, **kwargs)
return response.choices[0].message.content

```

Research confirms the import structure and async completion method with proper response handling. **MCP pattern:** Spec line 246-259 shows `from mcp.server.fastmcp import FastMCP` with `mcp = FastMCP("multi-llm-platform")` and `@mcp.tool()` decorators, which aligns with research findings on the FastMCP initialization and tool registration approach.

Environment variables match across sources: `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`. Port configuration is consistent—backend runs on 8000, frontend on 5173, Ollama on 11434.

Checking requirements.json against spec coverage shows multi-LLM provider support (spec lines 288-292), strategic model routing (lines 293-295), and cross-model validation all present in the specification.

```
Covered (Lines 296-298)
4. Cost Optimization - ✅ Covered (Lines 299-301)
5. Adaptive Spec System - ✅ Covered (Lines 302-304)
6. Version Control Integration - ✅ Covered (Lines 305-307)
7. Project Steering - ✅ Covered (Lines 308-310)
8. Skill Plugin System - ✅ Covered (Lines 311-313)

Edge Cases in spec (Lines 338-348):
1. Provider Unavailable - ✅
2. Rate Limiting - ✅
3. Model Disagreement - ✅
4. Large Context - ✅
5. Ollama Not Running - ✅
6. Mid-Spec Change - ✅
7. Git Conflicts - ✅
8. API
```
Key Invalid - ✅

Package naming and file structure remain uniform across the spec, with consistent model naming conventions following LiteLLM standards and terminology applied throughout.

Docker configuration appears incomplete—the spec references `docker-compose.yml` but lacks actual configuration details. Python 3.11+ requirement aligns with py-gitea dependencies, and Ollama infrastructure needs are properly documented. However, there's a critical mismatch: the spec calls for `litellm` async operations using `acompletion`, which needs verification against actual LiteLLM API capabilities.

Cross-referencing the xai-sdk imports shows the spec correctly imports both `Client` and `AsyncClient` as specified in the research. Similarly, the Ollama async import pattern matches the documented API, confirming these integrations are properly aligned with their respective libraries.

However, there's a discrepancy in the LiteLLM model naming convention. The spec shows `"claude-3-opus"` as a model identifier, but LiteLLM documentation requires Claude models to be prefixed differently—they should follow the format `"claude-"` with the full model designation.

Looking at the model name formats more carefully: `claude-3-opus` might work if LiteLLM defaults to the latest version, but production implementations typically need the date suffix like `claude-3-opus-20240229`. The other formats appear correct—`gemini/gemini-pro` and `ollama/llama3` follow LiteLLM's expected patterns.

I also notice the QA section references test files like `backend/tests/test_llm_router.py` and `backend/tests/test_cost_tracker.py`, but these file paths aren't actually defined in the specification itself.

There are several gaps between what's listed in requirements and what's in the file structure: Alembic is specified as a dependency but no migration configuration appears in the files to create. Similarly, the frontend dependencies include Vitest and React Testing Library, yet no corresponding test files are outlined. The spec mentions a version-control-service but doesn't include route files like `backend/api/routes/git.py`. Additionally, the QA section references a `/health` endpoint that isn't documented elsewhere in the specification.

The model naming could be more precise—while LiteLLM does support aliases like `claude-3-opus-latest`, the spec uses `claude-3-opus` without clarifying whether this refers to a specific version or an alias. The examples also omit xAI's model format (such as `xai/grok-beta`), which would improve consistency across supported providers.

Now let me verify some critical API patterns with Context7 to ensure the spec's code examples are accurate:

Question: LiteLLM unified API for calling multiple LLM providers with async support

Question: FastMCP Python SDK for Model Context Protocol server

Question: FastAPI Python web framework async endpoints


Available Libraries:

Each result includes:
- Library ID: Context7-compatible identifier (format: /org/project)
- Name: Library or package name
- Description: Short summary
- Code Snippets: Number of available code examples
- Source Reputation: Authority indicator (High, Medium, Low, or Unknown)
- Benchmark Score: Quality indicator (100 is the highest score)
- Versions: List of versions if available. Use one of those versions if the user provides a version in their query. The format of the version is /org/project/version.

For best results, select libraries based on name match, source reputation, snippet coverage, benchmark score, and relevance to your use case.

----------

- Title: FastAPI
- Context7-compatible library ID: /websites/fastapi_tiangolo
- Description: FastAPI is a modern, fast web framework for building APIs with Python. It's known for its high performance, ease of use, and automatic interactive documentation.
- Code Snippets: 12067
- Source Reputation: High
- Benchmark Score: 94.6
----------
- Title: FastAPI
- Context7-compatible library ID: /fastapi/fastapi
- Description: FastAPI framework, high performance, easy to learn, fast to code, ready for production
- Code Snippets: 881
- Source Reputation: High
- Benchmark Score: 87.2
- Versions: 0.115.13, 0_116_1, 0.118.2, 0.122.0, 0.128.0
----------
- Title: FastAPI
- Context7-compatible library ID: /websites/fastapi_tiangolo_learn
- Description: FastAPI is a modern, fast web framework for building APIs with Python based on standard Python type hints, featuring automatic interactive documentation and high performance.
- Code Snippets: 2
- Source Reputation: High
- Benchmark Score: 8
----------
- Title: Awesome FastAPI
- Context7-compatible library ID: /mjhea0/awesome-fastapi
- Description: A curated list of awesome things related to FastAPI, a modern, high-performance Python web framework for building RESTful APIs.
- Code Snippets: 84
- Source Reputation: High
----------
- Title: FastAPI Boilerplate
- Context7-compatible library ID: /websites/benavlabs_github_io_fastapi-boilerplate
- Description: A production-ready FastAPI boilerplate providing a solid foundation for building scalable, async APIs with modern Python technologies, featuring performance, security, and developer experience enhancements.
- Code Snippets: 715
- Source Reputation: High


Available Libraries:

Each result includes:
- Library ID: Context7-compatible identifier (format: /org/project)
- Name: Library or package name
- Description: Short summary
- Code Snippets: Number of available code examples
- Source Reputation: Authority indicator (High, Medium, Low, or Unknown)
- Benchmark Score: Quality indicator (100 is the highest score)
- Versions: List of versions if available. Use one of those versions if the user provides a version in their query. The format of the version is /org/project/version.

For best results, select libraries based on name match, source reputation, snippet coverage, benchmark score, and relevance to your use case.

----------

- Title: Litellm
- Context7-compatible library ID: /berriai/litellm
- Description: LiteLLM enables calling all LLM APIs using the OpenAI format, supporting providers like Bedrock, Huggingface, VertexAI, and more, with features like consistent output, retry logic, and budget management.
- Code Snippets: 9205
- Source Reputation: High
- Benchmark Score: 85
- Versions: v1.80.7-nightly
----------
- Title: LiteLLM
- Context7-compatible library ID: /websites/litellm_ai
- Description: LiteLLM provides a unified OpenAI-compatible interface to call and manage over 100 Large Language Models (LLMs) from various providers, offering features like retry/fallback logic, cost tracking, and consistent output, available as a Python SDK or a Proxy Server (LLM Gateway).
- Code Snippets: 5273
- Source Reputation: High
- Benchmark Score: 87.4
----------
- Title: LiteLLM RS
- Context7-compatible library ID: /majiayu000/litellm-rs
- Description: LiteLLM RS is a Rust-based client or implementation for LiteLLM, offering a unified API for various large language model (LLM) providers.
- Code Snippets: 128
- Source Reputation: Medium
- Benchmark Score: 83.3
----------
- Title: Go LiteLLM
- Context7-compatible library ID: /andrejsstepanovs/go-litellm
- Description: A Go client library for interacting with the LiteLLM API, providing a simple, type-safe way to perform completions, audio transcription, image queries, structured JSON, embeddings, token counting, MCP tool operations, and model browsing.
- Code Snippets: 51
- Source Reputation: Medium
- Benchmark Score: 78.2
----------
- Title: LiteLLM
- Context7-compatible library ID: /voocel/litellm
- Description: LiteLLM is a clean and elegant Go library that provides a unified interface for making simple API calls to multiple LLM platforms, supporting features like function calling, streaming, and reasoning.
- Code Snippets: 27
- Source Reputation: High


Available Libraries:

Each result includes:
- Library ID: Context7-compatible identifier (format: /org/project)
- Name: Library or package name
- Description: Short summary
- Code Snippets: Number of available code examples
- Source Reputation: Authority indicator (High, Medium, Low, or Unknown)
- Benchmark Score: Quality indicator (100 is the highest score)
- Versions: List of versions if available. Use one of those versions if the user provides a version in their query. The format of the version is /org/project/version.

For best results, select libraries based on name match, source reputation, snippet coverage, benchmark score, and relevance to your use case.

----------

- Title: FastMCP
- Context7-compatible library ID: /jlowin/fastmcp
- Description: FastMCP is a Python framework for building Model Context Protocol (MCP) servers and clients, simplifying the creation of LLM-integrated applications with features like deployment, authentication, and dynamic tool generation.
- Code Snippets: 1749
- Source Reputation: High
- Benchmark Score: 78
----------
- Title: FastMCP
- Context7-compatible library ID: /websites/gofastmcp
- Description: FastMCP is a Python framework for building and managing Model Context Protocol (MCP) servers and clients, simplifying the connection of LLMs to data and functionality.
- Code Snippets: 1879
- Source Reputation: High
- Benchmark Score: 79.6
----------
- Title: FastMCP
- Context7-compatible library ID: /llmstxt/gofastmcp_llms-full_txt
- Description: FastMCP is a Python framework for building MCP servers, featuring an experimental OpenAPI parser, JWT claims, and optimized payload handling.
- Code Snippets: 12289
- Source Reputation: High
- Benchmark Score: 79
----------
- Title: FastMCP
- Context7-compatible library ID: /llmstxt/gofastmcp_llms_txt
- Description: FastMCP is a fast, Pythonic framework for building and deploying Multi-modal Conversational Platform (MCP) servers and clients, offering programmatic interfaces and extensive integrations for LLMs and various services.
- Code Snippets: 2135
- Source Reputation: High
- Benchmark Score: 76
----------
- Title: FastMCP
- Context7-compatible library ID: /websites/gofastmcp-getting-started
- Description: FastMCP is a Pythonic framework for building Model Context Protocol (MCP) servers and clients, simplifying the creation of tools, resources, and prompts for LLM applications. It provides a comprehensive ecosystem for development to production.
- Code Snippets: 33
- Source Reputation: High
- Benchmark Score: 37.6


Good, I found the Context7 library IDs. Now let me verify the critical patterns in the spec by querying the docs:
- LiteLLM: `/berriai/litellm` or `/websites/litellm_ai`
- FastMCP: `/jlowin/fastmcp` or `/websites/gofastmcp`
- FastAPI: `/websites/fastapi_tiangolo`

Let me check specific patterns to verify the spec's code examples are accurate.

Question: acompletion async API usage with model format for Claude Anthropic Gemini Ollama

Question: FastMCP server decorator patterns tool and resource decorators


Error: Claude requested permissions to use mcp__context7__query-docs, but you haven't granted it yet.


I couldn't access Context7 docs. That's okay - I have enough information from the research.json to do a thorough analysis. Let me proceed with my critique based on what I've found.

Based on my deep analysis, here are the issues I've identified:

## Issues Found

### HIGH SEVERITY

1. **Missing test files in "Files to Create"**
   - The QA section lists specific test files like `backend/tests/test_llm_router.py`, `backend/tests/test_cost_tracker.py`, etc.
   - But the "Files to Create" table doesn't include ANY test files
   - This is a completeness issue that will cause confusion during implementation

2. **Missing API routes for version control**
   - The spec mentions version-control-service as an integration service
   - There are Git service files (`backend/git/git_service.py`, `gitea_service.py`, `commit_generator.py`)
   - But there's no API route file like `backend/api/routes/git.py` to expose these services

3. **Missing health endpoint pattern**
   - QA section line 505 requires a `/health` endpoint
   - But there's no route file or pattern showing how to implement it
   - This is missing from both "Files to Create" and "Patterns to Follow"

### MEDIUM SEVERITY

4. **Missing Alembic configuration files**
   - requirements.txt lists `alembic>=1.13.0` (line 567)
   - But no alembic configuration files are in "Files to Create"
   - Need: `backend/alembic.ini`, `backend/migrations/` directory structure

5. **Incomplete model name examples in LiteLLM pattern**
   - Line 188 shows: `"claude-3-opus", "gemini/gemini-pro", "ollama/llama3"`
   - Missing xAI/Grok model format which should be: `"xai/grok-beta"` or similar
   - This inconsistency could confuse implementers

6. **Missing frontend test files**
   - package.json lists `vitest` and `@testing-library/react` as devDependencies
   - But no frontend test files are in "Files to Create"
   - Need: `frontend/src/__tests__/` or similar structure

7. **Missing model_interactions table in Database Verification**
   - Line 517 mentions verifying tables: `specs, tasks, decisions, model_interactions`
   - But there's no `backend/models/model_interaction.py` in Files to Create
   - Need to add this model file

### LOW SEVERITY

8. **Inconsistent naming conventions** - Some files use snake_case while others use camelCase, which could lead to import errors. **9. Missing environment variable documentation** - The spec doesn't list all required .env variables needed for local development setup.

10. **Incomplete routing configuration** - The QA section references URLs like `/spec`, `/tasks`, `/models`, `/costs` but no router file exists in the file creation list.

Now I have all the information I need. Let me perform my deep analysis and then fix the issues.

Based on my thorough analysis comparing spec.md against research.json and requirements.json, I've identified several issues that need fixing. Let me apply the fixes:

Edit

| `frontend/src/components/CostTracker.tsx` | frontend | Cost tracking visualization |
| `docker-compose.yml` | infrastructure | Container orchestration |
| `.env.example` | infrastructure | Environment variable template |

| `frontend/src/components/CostTracker.tsx` | frontend | Cost tracking visualization |
| `frontend/src/router.tsx` | frontend | React Router configuration |
| `frontend/src/__tests__/App.test.tsx` | frontend | Frontend component tests |
| `backend/api/routes/health.py` | orchestration | Health check endpoint |
| `backend/api/routes/git.py` | version-control | Git operations endpoints |
| `backend/models/model_interaction.py` | orchestration | Model interaction tracking |
| `backend/alembic.ini` | orchestration | Alembic migration config |
| `backend/migrations/env.py` | orchestration | Alembic environment setup |
| `backend/tests/__init__.py` | orchestration | Test package init |
| `backend/tests/test_llm_router.py` | orchestration | LLM router unit tests |
| `backend/tests/test_cost_tracker.py` | orchestration | Cost tracker tests |
| `backend/tests/test_spec_manager.py` | orchestration | Spec manager tests |
| `backend/tests/test_skill_registry.py` | orchestration | Skill registry tests |
| `backend/tests/test_git_service.py` | orchestration | Git service tests |
| `backend/tests/test_cross_validate.py` | orchestration | Cross-validation tests |
| `backend/tests/integration/__init__.py` | orchestration | Integration test package |
| `backend/tests/integration/test_providers.py` | orchestration | Provider integration tests |
| `docker-compose.yml` | infrastructure | Container orchestration |
| `.env.example` | infrastructure | Environment variable template |


The file C:\Users\MikeSwanson\claude-projects\ACPlus\auto-claude-plus\.auto-claude\specs\001-multi-llm-agentic-development-platform\spec.md has been updated successfully.

| `frontend/src/components/CostTracker.tsx` | frontend | Cost tracking visualization |
| `frontend/src/router.tsx` | frontend | React Router configuration |
| `frontend/src/__tests__/App.test.tsx` | frontend | Frontend component tests |
| `backend/api/routes/health.py` | orchestration | Health check endpoint |
| `backend/api/routes/git.py` | version-control | Git operations endpoints |
| `backend/models/model_interaction.py` | orchestration | Model interaction tracking |
| `backend/alembic.ini` | orchestration | Alembic migration config |
| `backend/migrations/env.py` | orchestration | Alembic environment setup |
| `backend/tests/__init__.py` | orchestration | Test package init |
| `backend/tests/test_llm_router.py` | orchestration | LLM router unit tests |
| `backend/tests/test_cost_tracker.py` | orchestration | Cost tracker tests |
| `backend/tests/test_spec_manager.py` | orchestration | Spec manager tests |
| `backend/tests/test_skill_registry.py` | orchestration | Skill registry tests |
| `backend/tests/test_git_service.py` | orchestration | Git service tests |
| `backend/tests/test_cross_validate.py` | orchestration | Cross-validation tests |
| `backend/tests/integration/__init__.py` | orchestration | Integration test package |
| `backend/tests/integration/test_providers.py` | orchestration | Provider integration tests |
| `docker-compose.yml` | infrastructure | Container orchestration |
| `.env.example` | infrastructure | Environment variable template |

# Specification: Multi-LLM Agentic Development Platform

## Overview

Build an advanced agentic development platform that orchestrates multiple AI models (Claude, Gemini, Grok, Ollama) for intelligent software development. The system strategically routes tasks to models best suited for them, implements cross-model validation for quality assurance, and provides cost optimization through intelligent balancing of cloud and local models. This greenfield project extends concepts from Autocoder 2.0/Auto-Claude with multi-model orchestration, adaptive requirements management, and mid-project course correction capabilities.

## Workflow Type

**Type**: Feature (Greenfield Development)

**Rationale**: Despite referencing existing Autocoder 2.0/Auto-Claude patterns, the project index shows an empty codebase with no existing code to refactor. This is building new functionality from scratch, requiring full-stack development across 5 services, 4+ external LLM provider integrations, database schema design, and novel architectural patterns for multi-model orchestration.

## Task Scope

### Services Involved

- **orchestration-service** (primary) - Core task decomposition, model routing, parallel execution engine
- **llm-wrapper-service** (primary) - Unified API abstraction for all LLM providers via LiteLLM
- **spec-management-service** (primary) - Adaptive spec system with interview and versioning
- **skill-service** (integration) - Extensible plugin architecture for specialized capabilities
- **version-control-service** (integration) - Git/Gitea automation for branching, commits, PRs
- **frontend-ui** (integration) - React/TypeScript project management dashboard

### This Task Will:

- [ ] Create Python/FastAPI backend with modular service architecture
- [ ] Implement unified LLM wrapper supporting Claude, Gemini, Grok, and Ollama
- [ ] Build task orchestration engine with model-specific routing
- [ ] Implement cross-model validation for quality assurance
- [ ] Create adaptive spec system with interview and re-interview workflows
- [ ] Build extensible skill/addon plugin architecture
- [ ] Integrate Git/Gitea for version control automation
- [ ] Implement checkpoint system for project steering and course correction
- [ ] Create React/TypeScript frontend for project management
- [ ] Design database schema for specs, decisions, task history, model interactions
- [ ] Build MCP server for feature graph and skill management

### Out of Scope:

- Production deployment infrastructure (Kubernetes, cloud deployment)
- Enterprise SSO/SAML authentication
- Multi-tenant user management
- Billing and subscription management
- Mobile application
- Integration with CI/CD pipelines (beyond basic Git operations)

## Service Context

### Backend Orchestration Service

**Tech Stack:**
- Language: Python 3.11+
- Framework: FastAPI with uvicorn ASGI server
- Key packages: `fastapi[standard]`, `pydantic`, `httpx`, `sqlalchemy`
- Key directories: `backend/`, `backend/services/`, `backend/api/`, `backend/models/`

**Entry Point:** `backend/main.py`

**How to Run:**
```bash
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
```

**Port:** 8000

**API Documentation:** http://localhost:8000/docs (Swagger) and http://localhost:8000/redoc

---

### LLM Wrapper Service

**Tech Stack:**
- Language: Python 3.11+
- Framework: LiteLLM for unified interface
- Key packages: `litellm`, `anthropic`, `google-genai`, `xai-sdk`, `ollama`
- Key directories: `backend/llm/`, `backend/llm/providers/`, `backend/llm/routing/`

**Entry Point:** `backend/llm/__init__.py`

**Configuration:**
```bash
# Environment variables required
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
XAI_API_KEY=your_xai_key
# Ollama uses local server, no API key needed
```

---

### Frontend UI

**Tech Stack:**
- Language: TypeScript
- Framework: React with Vite
- Key packages: `react`, `react-dom`, `typescript`, `@tanstack/react-query`
- Key directories: `frontend/src/`, `frontend/src/components/`, `frontend/src/pages/`

**Entry Point:** `frontend/src/main.tsx`

**How to Run:**
```bash
cd frontend
npm install
npm run dev
```

**Port:** 5173

---

### MCP Server

**Tech Stack:**
- Language: Python 3.11+
- Framework: MCP SDK (FastMCP)
- Key packages: `mcp>=1.25,<2`
- Key directories: `mcp-server/`, `mcp-server/tools/`, `mcp-server/resources/`

**Entry Point:** `mcp-server/server.py`

**How to Run:**
```bash
cd mcp-server
python server.py
```

## Files to Create

| File | Service | Purpose |
|------|---------|---------|
| `backend/main.py` | orchestration | FastAPI application entry point |
| `backend/requirements.txt` | orchestration | Python dependencies |
| `backend/api/routes/__init__.py` | orchestration | API route aggregation |
| `backend/api/routes/tasks.py` | orchestration | Task management endpoints |
| `backend/api/routes/specs.py` | orchestration | Spec management endpoints |
| `backend/api/routes/models.py` | orchestration | LLM provider status endpoints |
| `backend/services/orchestrator.py` | orchestration | Task decomposition and routing |
| `backend/services/spec_manager.py` | spec-management | Spec CRUD and versioning |
| `backend/services/skill_registry.py` | skill-service | Skill loading and execution |
| `backend/llm/unified_client.py` | llm-wrapper | LiteLLM wrapper with routing logic |
| `backend/llm/providers/claude.py` | llm-wrapper | Claude-specific optimizations |
| `backend/llm/providers/gemini.py` | llm-wrapper | Gemini-specific optimizations |
| `backend/llm/providers/grok.py` | llm-wrapper | Grok-specific optimizations |
| `backend/llm/providers/ollama.py` | llm-wrapper | Ollama local model integration |
| `backend/llm/routing/router.py` | llm-wrapper | Task-to-model routing logic |
| `backend/llm/routing/cost_tracker.py` | llm-wrapper | Token usage and cost tracking |
| `backend/llm/validation/cross_validate.py` | llm-wrapper | Cross-model validation logic |
| `backend/models/database.py` | orchestration | SQLAlchemy database setup |
| `backend/models/spec.py` | orchestration | Spec data model |
| `backend/models/task.py` | orchestration | Task data model |
| `backend/models/decision.py` | orchestration | Decision tracking model |
| `backend/git/git_service.py` | version-control | GitPython wrapper |
| `backend/git/gitea_service.py` | version-control | Gitea API integration |
| `backend/git/commit_generator.py` | version-control | Conventional commit messages |
| `mcp-server/server.py` | mcp | FastMCP server entry |
| `mcp-server/tools/spec_tools.py` | mcp | Spec management MCP tools |
| `mcp-server/tools/task_tools.py` | mcp | Task management MCP tools |
| `mcp-server/resources/project_state.py` | mcp | Project state MCP resources |
| `frontend/package.json` | frontend | NPM dependencies |
| `frontend/vite.config.ts` | frontend | Vite configuration |
| `frontend/src/main.tsx` | frontend | React entry point |
| `frontend/src/App.tsx` | frontend | Main application component |
| `frontend/src/pages/Dashboard.tsx` | frontend | Project dashboard |
| `frontend/src/pages/SpecEditor.tsx` | frontend | Spec editing interface |
| `frontend/src/pages/TaskViewer.tsx` | frontend | Task status viewer |
| `frontend/src/components/ModelStatus.tsx` | frontend | LLM provider status display |
| `frontend/src/components/CostTracker.tsx` | frontend | Cost tracking visualization |
| `docker-compose.yml` | infrastructure | Container orchestration |
| `.env.example` | infrastructure | Environment variable template |

## Patterns to Follow

### LiteLLM Unified Interface Pattern

Use LiteLLM as the unified API wrapper for all LLM providers:

```python
from litellm import completion, acompletion

# Unified interface - same code for any provider
async def call_llm(model: str, messages: list, **kwargs) -> str:
    response = await acompletion(
        model=model,  # e.g., "claude-3-opus", "gemini/gemini-pro", "ollama/llama3"
        messages=messages,
        **kwargs
    )
    return response.choices[0].message.content
```

**Key Points:**
- Model names follow `provider/model` format for non-OpenAI models
- Built-in cost tracking via `litellm.track_cost = True`
- Automatic retries and fallbacks configurable
- Same interface works across 100+ LLM providers

---

### FastAPI Service Pattern

```python
from fastapi import FastAPI, Depends, HTTPException
from pydantic import BaseModel

app = FastAPI(title="Multi-LLM Platform")

class TaskCreate(BaseModel):
    description: str
    priority: str = "normal"

@app.post("/tasks/", response_model=Task)
async def create_task(task: TaskCreate, db: Session = Depends(get_db)):
    """Create a new task with automatic model routing."""
    return await orchestrator.create_task(task, db)
```

**Key Points:**
- Use Pydantic models for request/response validation
- Dependency injection for database sessions
- Async endpoints for non-blocking LLM calls

---

### Async LLM Client Pattern

```python
from anthropic import AsyncAnthropic
from google import genai
from xai_sdk import AsyncClient as XAIClient
from ollama import AsyncClient as OllamaClient

# All providers support async clients for concurrent operations
async def parallel_validation(prompt: str, models: list[str]) -> list[str]:
    tasks = [call_llm(model, prompt) for model in models]
    responses = await asyncio.gather(*tasks, return_exceptions=True)
    return [r for r in responses if not isinstance(r, Exception)]
```

---

### MCP Server Pattern

```python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("multi-llm-platform")

@mcp.tool()
async def create_spec(description: str) -> dict:
    """Create a new project specification."""
    return await spec_service.create(description)

@mcp.resource("project://state")
async def get_project_state() -> str:
    """Get current project state."""
    return json.dumps(state_manager.get_state())
```

---

### Git Integration Pattern

```python
from git import Repo

def create_feature_branch(repo_path: str, feature_name: str) -> str:
    """Create a feature branch following conventional naming."""
    repo = Repo(repo_path)
    branch_name = f"feature/{feature_name.lower().replace(' ', '-')}"
    new_branch = repo.create_head(branch_name)
    new_branch.checkout()
    return branch_name

def commit_with_message(repo_path: str, files: list, message: str):
    """Commit with conventional commit message format."""
    repo = Repo(repo_path)
    repo.index.add(files)
    repo.index.commit(message)
```

**Gotcha:** GitPython leaks resources in long-running processes. For daemon usage, spawn as subprocess.

## Requirements

### Functional Requirements

1. **Multi-LLM Provider Integration**
   - Description: Support Claude, Gemini, Grok, and Ollama through unified interface
   - Acceptance: Can make requests to all 4 providers and receive responses

2. **Strategic Model Routing**
   - Description: Route tasks to optimal models based on task characteristics
   - Acceptance: Routing logic correctly assigns file analysis to Ollama, complex reasoning to Claude, multimodal to Gemini, real-time info to Grok

3. **Cross-Model Validation**
   - Description: Have multiple models review work for quality assurance
   - Acceptance: Critical decisions validated by 2+ models before acceptance

4. **Cost Optimization**
   - Description: Track and minimize API costs through intelligent model selection
   - Acceptance: Cost tracking visible in UI, local models used for appropriate tasks

5. **Adaptive Spec System**
   - Description: Interview workflow for gathering requirements, with re-interview capability
   - Acceptance: Can create spec via interview, modify spec mid-project, track spec versions

6. **Version Control Integration**
   - Description: Automatic branching, commit generation, PR creation
   - Acceptance: Git operations automated, conventional commit messages generated

7. **Project Steering**
   - Description: Mid-flight direction changes with context preservation
   - Acceptance: Can redirect project without losing history, impact analysis visible

8. **Skill Plugin System**
   - Description: Extensible architecture for specialized agent capabilities
   - Acceptance: Can load/unload skills, skills can be model-specific or agnostic

### Non-Functional Requirements

1. **Performance**
   - Parallel LLM calls for independent operations
   - Response time < 30s for most operations
   - Support concurrent users

2. **Security**
   - API keys stored securely (environment variables, not code)
   - No credential logging
   - Input validation on all endpoints

3. **Reliability**
   - Fallback strategies when models fail
   - Graceful degradation when providers unavailable
   - State persistence across restarts

### Edge Cases

1. **Provider Unavailable** - Fall back to alternate provider or queue for retry
2. **Rate Limiting** - Implement exponential backoff, queue excess requests
3. **Model Disagreement** - Escalate to higher-capability model for tie-breaking
4. **Large Context** - Automatically route to models with larger context windows (Gemini)
5. **Ollama Not Running** - Detect and warn, exclude from routing until available
6. **Mid-Spec Change** - Version current spec, preserve history, enable diff view
7. **Git Conflicts** - Detect and surface for manual resolution
8. **API Key Invalid** - Mark provider as unavailable, notify user

## Implementation Notes

### DO

- Use LiteLLM as unified wrapper instead of managing individual SDKs directly
- Use `google-genai` package, NOT deprecated `google-generativeai`
- Use official `xai-sdk` package, not community alternatives
- Pin MCP to `mcp>=1.25,<2` to avoid v2 breaking changes
- Use Python 3.11+ for compatibility with all packages (py-gitea requires 3.11+)
- Use async clients for all LLM operations to enable concurrency
- Use `fastapi[standard]` to get uvicorn bundled
- Start Ollama server separately before using Python client
- Pull Ollama models first: `ollama pull gemma3`

### DON'T

- Don't use GitPython in long-running daemon processes (resource leaks)
- Don't hardcode API keys - use environment variables
- Don't assume all models available - always check provider status
- Don't block on single LLM call when parallel is possible
- Don't generate code using deprecated google-generativeai patterns
- Don't use `--reload` flag in production uvicorn

## Development Environment

### Prerequisites

```bash
# Python 3.11+
python --version  # Should be 3.11+

# Node.js 18+
node --version  # Should be 18+

# Ollama (for local LLM)
# Download from https://ollama.com/download
ollama --version
```

### Start Services

```bash
# Terminal 1: Start Ollama server
ollama serve

# Terminal 2: Pull models
ollama pull gemma3
ollama pull codellama

# Terminal 3: Start backend
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Terminal 4: Start frontend
cd frontend
npm install
npm run dev

# Terminal 5: Start MCP server (optional)
cd mcp-server
python server.py
```

### Service URLs

- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/docs
- Frontend: http://localhost:5173
- Ollama: http://localhost:11434

### Required Environment Variables

Create `.env` file from `.env.example`:

```bash
# LLM Provider Keys
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AI...
XAI_API_KEY=xai-...

# Ollama (optional, defaults shown)
OLLAMA_HOST=http://localhost:11434

# Database
DATABASE_URL=sqlite:///./multi_llm_platform.db

# Git/Gitea (optional)
GITEA_URL=http://localhost:3000
GITEA_TOKEN=your_gitea_token
```

## Success Criteria

The task is complete when:

1. [ ] Successfully make API calls to all 4 LLM providers (Claude, Gemini, Grok, Ollama)
2. [ ] Demonstrate intelligent model routing (correct model for task type)
3. [ ] Cross-model validation working for critical decisions
4. [ ] Cost tracking visible and accurate in UI
5. [ ] Spec interview workflow functional (create, modify, version)
6. [ ] Git integration working (branch, commit, PR creation)
7. [ ] Project steering possible mid-flight with context preservation
8. [ ] Skill plugin system loading and executing skills
9. [ ] Frontend dashboard displaying project state
10. [ ] No console errors in frontend or backend
11. [ ] All unit and integration tests passing

## QA Acceptance Criteria

**CRITICAL**: These criteria must be verified by the QA Agent before sign-off.

### Unit Tests

| Test | File | What to Verify |
|------|------|----------------|
| LLM Router | `backend/tests/test_llm_router.py` | Correct model selection for task types |
| Cost Tracker | `backend/tests/test_cost_tracker.py` | Accurate token and cost calculation |
| Spec Manager | `backend/tests/test_spec_manager.py` | CRUD operations, versioning |
| Skill Registry | `backend/tests/test_skill_registry.py` | Skill loading, execution, unloading |
| Git Service | `backend/tests/test_git_service.py` | Branch creation, commits, PR logic |
| Cross Validator | `backend/tests/test_cross_validate.py` | Multi-model validation logic |

### Integration Tests

| Test | Services | What to Verify |
|------|----------|----------------|
| LLM Provider Health | llm-wrapper + all providers | All 4 providers respond correctly |
| Task Routing E2E | orchestration + llm-wrapper | Tasks routed to correct models |
| Spec Persistence | spec-management + database | Specs saved and versioned correctly |
| Git Operations | version-control + local repo | Branch/commit/PR workflow works |
| MCP Tools | mcp-server + backend | MCP tools execute successfully |

### End-to-End Tests

| Flow | Steps | Expected Outcome |
|------|-------|------------------|
| Project Creation | 1. Open dashboard 2. Start interview 3. Answer questions 4. View spec | Spec created and displayed |
| Task Execution | 1. Create task 2. View routing 3. Check results | Task completed with correct model |
| Cross Validation | 1. Mark task critical 2. Submit 3. View validation | Multiple models validate before accept |
| Mid-Project Steer | 1. Modify spec 2. Confirm change 3. View history | Spec versioned, history preserved |
| Cost Report | 1. Execute tasks 2. View dashboard 3. Check costs | Accurate cost breakdown by provider |

### Browser Verification

| Page/Component | URL | Checks |
|----------------|-----|--------|
| Dashboard | `http://localhost:5173/` | Project overview loads, no errors |
| Spec Editor | `http://localhost:5173/spec` | Interview form works, saves correctly |
| Task Viewer | `http://localhost:5173/tasks` | Task list displays, status updates |
| Model Status | `http://localhost:5173/models` | Provider health indicators accurate |
| Cost Tracker | `http://localhost:5173/costs` | Cost charts render, data accurate |

### API Verification

| Endpoint | Method | Checks |
|----------|--------|--------|
| `/health` | GET | Returns 200, all services healthy |
| `/api/models/status` | GET | Returns status for all 4 providers |
| `/api/tasks` | POST | Creates task, returns task ID |
| `/api/specs` | POST | Creates spec from interview data |
| `/api/specs/{id}/versions` | GET | Returns version history |

### Database Verification

| Check | Query/Command | Expected |
|-------|---------------|----------|
| Tables created | `SELECT name FROM sqlite_master WHERE type='table'` | specs, tasks, decisions, model_interactions |
| Spec versioning | `SELECT COUNT(*) FROM spec_versions WHERE spec_id=1` | Versions increment on changes |
| Cost tracking | `SELECT SUM(cost) FROM model_interactions` | Non-zero, matches UI display |

### Security Verification

| Check | Method | Expected |
|-------|--------|----------|
| No hardcoded keys | `grep -r "sk-ant\|AIza" backend/` | No matches |
| Env vars loaded | Check startup logs | Keys loaded from environment |
| Input validation | Send malformed JSON to endpoints | 422 validation error returned |

### QA Sign-off Requirements

- [ ] All unit tests pass (`pytest backend/tests/`)
- [ ] All integration tests pass (`pytest backend/tests/integration/`)
- [ ] All E2E tests pass (Playwright or manual)
- [ ] Browser verification complete (all pages load, no console errors)
- [ ] API verification complete (all endpoints respond correctly)
- [ ] Database state verified (tables exist, data persists)
- [ ] Security verification complete (no credential exposure)
- [ ] No regressions in existing functionality
- [ ] Code follows established patterns (LiteLLM, FastAPI conventions)
- [ ] No security vulnerabilities introduced
- [ ] Cost tracking accurate within 5% of actual API costs
- [ ] All 4 LLM providers successfully integrated and responding

---

## Appendix: Package Versions

### Python Requirements (requirements.txt)

```
# Core Framework
fastapi[standard]>=0.115.0
uvicorn>=0.30.0
pydantic>=2.0.0

# LLM Providers
litellm>=1.0.0
anthropic>=0.39.0
google-genai>=1.0.0
xai-sdk>=0.1.0
ollama>=0.4.0

# MCP
mcp>=1.25,<2

# Database
sqlalchemy>=2.0.0
alembic>=1.13.0

# Git
GitPython>=3.1.40
py-gitea>=0.2.10

# Utilities
httpx>=0.27.0
python-dotenv>=1.0.0
```

### Node Requirements (package.json)

```json
{
  "dependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "@tanstack/react-query": "^5.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "vite": "^6.0.0",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "vitest": "^2.0.0",
    "@testing-library/react": "^16.0.0"
  }
}
```

---

## Appendix: Phased Implementation Milestones

Based on complexity assessment, implement in phases:

1. **Phase 1**: Core orchestration layer with single LLM provider (Claude via LiteLLM)
2. **Phase 2**: Add additional LLM providers with unified wrapper and routing
3. **Phase 3**: Spec management system and version control integration
4. **Phase 4**: Skill plugin system and cross-model validation
5. **Phase 5**: Frontend UI and project steering capabilities
6. **Phase 6**: Quality assurance, security hardening, and production readiness

+| `frontend/src/router.tsx` | frontend | React Router configuration |

+| `frontend/src/__tests__/App.test.tsx` | frontend | Frontend component tests |

+| `backend/api/routes/health.py` | orchestration | Health check endpoint |

+| `backend/api/routes/git.py` | version-control | Git operations endpoints |

+| `backend/models/model_interaction.py` | orchestration | Model interaction tracking |

+| `backend/alembic.ini` | orchestration | Alembic migration config |

+| `backend/migrations/env.py` | orchestration | Alembic environment setup |

+| `backend/tests/__init__.py` | orchestration | Test package init |

+| `backend/tests/test_llm_router.py` | orchestration | LLM router unit tests |

+| `backend/tests/test_cost_tracker.py` | orchestration | Cost tracker tests |

+| `backend/tests/test_spec_manager.py` | orchestration | Spec manager tests |

+| `backend/tests/test_skill_registry.py` | orchestration | Skill registry tests |

+| `backend/tests/test_git_service.py` | orchestration | Git service tests |

+| `backend/tests/test_cross_validate.py` | orchestration | Cross-validation tests |

+| `backend/tests/integration/__init__.py` | orchestration | Integration test package |

+| `backend/tests/integration/test_providers.py` | orchestration | Provider integration tests |


Good, I've added the missing test files and other missing files. Now let me fix the LiteLLM model format issue to include xAI/Grok format:

async def call_llm(model: str, messages: list, **kwargs) -> str:
    response = await acompletion(
        model=model,  # e.g., "claude-3-opus", "gemini/gemini-pro", "ollama/llama3"
        messages=messages,
        **kwargs
    )
    return response.choices[0].message.content

async def call_llm(model: str, messages: list, **kwargs) -> str:
    response = await acompletion(
        model=model,  # e.g., "claude-3-opus-20240229", "gemini/gemini-pro", "xai/grok-beta", "ollama/llama3"
        messages=messages,
        **kwargs
    )
    return response.choices[0].message.content


async def call_llm(model: str, messages: list, **kwargs) -> str:
    response = await acompletion(
        model=model,  # e.g., "claude-3-opus-20240229", "gemini/gemini-pro", "xai/grok-beta", "ollama/llama3"
        messages=messages,
        **kwargs
    )
    return response.choices[0].message.content

# Specification: Multi-LLM Agentic Development Platform

## Overview

Build an advanced agentic development platform that orchestrates multiple AI models (Claude, Gemini, Grok, Ollama) for intelligent software development. The system strategically routes tasks to models best suited for them, implements cross-model validation for quality assurance, and provides cost optimization through intelligent balancing of cloud and local models. This greenfield project extends concepts from Autocoder 2.0/Auto-Claude with multi-model orchestration, adaptive requirements management, and mid-project course correction capabilities.

## Workflow Type

**Type**: Feature (Greenfield Development)

**Rationale**: Despite referencing existing Autocoder 2.0/Auto-Claude patterns, the project index shows an empty codebase with no existing code to refactor. This is building new functionality from scratch, requiring full-stack development across 5 services, 4+ external LLM provider integrations, database schema design, and novel architectural patterns for multi-model orchestration.

## Task Scope

### Services Involved

- **orchestration-service** (primary) - Core task decomposition, model routing, parallel execution engine
- **llm-wrapper-service** (primary) - Unified API abstraction for all LLM providers via LiteLLM
- **spec-management-service** (primary) - Adaptive spec system with interview and versioning
- **skill-service** (integration) - Extensible plugin architecture for specialized capabilities
- **version-control-service** (integration) - Git/Gitea automation for branching, commits, PRs
- **frontend-ui** (integration) - React/TypeScript project management dashboard

### This Task Will:

- [ ] Create Python/FastAPI backend with modular service architecture
- [ ] Implement unified LLM wrapper supporting Claude, Gemini, Grok, and Ollama
- [ ] Build task orchestration engine with model-specific routing
- [ ] Implement cross-model validation for quality assurance
- [ ] Create adaptive spec system with interview and re-interview workflows
- [ ] Build extensible skill/addon plugin architecture
- [ ] Integrate Git/Gitea for version control automation
- [ ] Implement checkpoint system for project steering and course correction
- [ ] Create React/TypeScript frontend for project management
- [ ] Design database schema for specs, decisions, task history, model interactions
- [ ] Build MCP server for feature graph and skill management

### Out of Scope:

- Production deployment infrastructure (Kubernetes, cloud deployment)
- Enterprise SSO/SAML authentication
- Multi-tenant user management
- Billing and subscription management
- Mobile application
- Integration with CI/CD pipelines (beyond basic Git operations)

## Service Context

### Backend Orchestration Service

**Tech Stack:**
- Language: Python 3.11+
- Framework: FastAPI with uvicorn ASGI server
- Key packages: `fastapi[standard]`, `pydantic`, `httpx`, `sqlalchemy`
- Key directories: `backend/`, `backend/services/`, `backend/api/`, `backend/models/`

**Entry Point:** `backend/main.py`

**How to Run:**
```bash
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000
```

**Port:** 8000

**API Documentation:** http://localhost:8000/docs (Swagger) and http://localhost:8000/redoc

---

### LLM Wrapper Service

**Tech Stack:**
- Language: Python 3.11+
- Framework: LiteLLM for unified interface
- Key packages: `litellm`, `anthropic`, `google-genai`, `xai-sdk`, `ollama`
- Key directories: `backend/llm/`, `backend/llm/providers/`, `backend/llm/routing/`

**Entry Point:** `backend/llm/__init__.py`

**Configuration:**
```bash
# Environment variables required
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
XAI_API_KEY=your_xai_key
# Ollama uses local server, no API key needed
```

---

### Frontend UI

**Tech Stack:**
- Language: TypeScript
- Framework: React with Vite
- Key packages: `react`, `react-dom`, `typescript`, `@tanstack/react-query`
- Key directories: `frontend/src/`, `frontend/src/components/`, `frontend/src/pages/`

**Entry Point:** `frontend/src/main.tsx`

**How to Run:**
```bash
cd frontend
npm install
npm run dev
```

**Port:** 5173

---

### MCP Server

**Tech Stack:**
- Language: Python 3.11+
- Framework: MCP SDK (FastMCP)
- Key packages: `mcp>=1.25,<2`
- Key directories: `mcp-server/`, `mcp-server/tools/`, `mcp-server/resources/`

**Entry Point:** `mcp-server/server.py`

**How to Run:**
```bash
cd mcp-server
python server.py
```

## Files to Create

| File | Service | Purpose |
|------|---------|---------|
| `backend/main.py` | orchestration | FastAPI application entry point |
| `backend/requirements.txt` | orchestration | Python dependencies |
| `backend/api/routes/__init__.py` | orchestration | API route aggregation |
| `backend/api/routes/tasks.py` | orchestration | Task management endpoints |
| `backend/api/routes/specs.py` | orchestration | Spec management endpoints |
| `backend/api/routes/models.py` | orchestration | LLM provider status endpoints |
| `backend/services/orchestrator.py` | orchestration | Task decomposition and routing |
| `backend/services/spec_manager.py` | spec-management | Spec CRUD and versioning |
| `backend/services/skill_registry.py` | skill-service | Skill loading and execution |
| `backend/llm/unified_client.py` | llm-wrapper | LiteLLM wrapper with routing logic |
| `backend/llm/providers/claude.py` | llm-wrapper | Claude-specific optimizations |
| `backend/llm/providers/gemini.py` | llm-wrapper | Gemini-specific optimizations |
| `backend/llm/providers/grok.py` | llm-wrapper | Grok-specific optimizations |
| `backend/llm/providers/ollama.py` | llm-wrapper | Ollama local model integration |
| `backend/llm/routing/router.py` | llm-wrapper | Task-to-model routing logic |
| `backend/llm/routing/cost_tracker.py` | llm-wrapper | Token usage and cost tracking |
| `backend/llm/validation/cross_validate.py` | llm-wrapper | Cross-model validation logic |
| `backend/models/database.py` | orchestration | SQLAlchemy database setup |
| `backend/models/spec.py` | orchestration | Spec data model |
| `backend/models/task.py` | orchestration | Task data model |
| `backend/models/decision.py` | orchestration | Decision tracking model |
| `backend/git/git_service.py` | version-control | GitPython wrapper |
| `backend/git/gitea_service.py` | version-control | Gitea API integration |
| `backend/git/commit_generator.py` | version-control | Conventional commit messages |
| `mcp-server/server.py` | mcp | FastMCP server entry |
| `mcp-server/tools/spec_tools.py` | mcp | Spec management MCP tools |
| `mcp-server/tools/task_tools.py` | mcp | Task management MCP tools |
| `mcp-server/resources/project_state.py` | mcp | Project state MCP resources |
| `frontend/package.json` | frontend | NPM dependencies |
| `frontend/vite.config.ts` | frontend | Vite configuration |
| `frontend/src/main.tsx` | frontend | React entry point |
| `frontend/src/App.tsx` | frontend | Main application component |
| `frontend/src/pages/Dashboard.tsx` | frontend | Project dashboard |
| `frontend/src/pages/SpecEditor.tsx` | frontend | Spec editing interface |
| `frontend/src/pages/TaskViewer.tsx` | frontend | Task status viewer |
| `frontend/src/components/ModelStatus.tsx` | frontend | LLM provider status display |
| `frontend/src/components/CostTracker.tsx` | frontend | Cost tracking visualization |
| `frontend/src/router.tsx` | frontend | React Router configuration |
| `frontend/src/__tests__/App.test.tsx` | frontend | Frontend component tests |
| `backend/api/routes/health.py` | orchestration | Health check endpoint |
| `backend/api/routes/git.py` | version-control | Git operations endpoints |
| `backend/models/model_interaction.py` | orchestration | Model interaction tracking |
| `backend/alembic.ini` | orchestration | Alembic migration config |
| `backend/migrations/env.py` | orchestration | Alembic environment setup |
| `backend/tests/__init__.py` | orchestration | Test package init |
| `backend/tests/test_llm_router.py` | orchestration | LLM router unit tests |
| `backend/tests/test_cost_tracker.py` | orchestration | Cost tracker tests |
| `backend/tests/test_spec_manager.py` | orchestration | Spec manager tests |
| `backend/tests/test_skill_registry.py` | orchestration | Skill registry tests |
| `backend/tests/test_git_service.py` | orchestration | Git service tests |
| `backend/tests/test_cross_validate.py` | orchestration | Cross-validation tests |
| `backend/tests/integration/__init__.py` | orchestration | Integration test package |
| `backend/tests/integration/test_providers.py` | orchestration | Provider integration tests |
| `docker-compose.yml` | infrastructure | Container orchestration |
| `.env.example` | infrastructure | Environment variable template |

## Patterns to Follow

### LiteLLM Unified Interface Pattern

Use LiteLLM as the unified API wrapper for all LLM providers:

```python
from litellm import completion, acompletion

# Unified interface - same code for any provider
async def call_llm(model: str, messages: list, **kwargs) -> str:
    response = await acompletion(
        model=model,  # e.g., "claude-3-opus", "gemini/gemini-pro", "ollama/llama3"
        messages=messages,
        **kwargs
    )
    return response.choices[0].message.content
```

**Key Points:**
- Model names follow `provider/model` format for non-OpenAI models
- Built-in cost tracking via `litellm.track_cost = True`
- Automatic retries and fallbacks configurable
- Same interface works across 100+ LLM providers

---

### FastAPI Service Pattern

```python
from fastapi import FastAPI, Depends, HTTPException
from pydantic import BaseModel

app = FastAPI(title="Multi-LLM Platform")

class TaskCreate(BaseModel):
    description: str
    priority: str = "normal"

@app.post("/tasks/", response_model=Task)
async def create_task(task: TaskCreate, db: Session = Depends(get_db)):
    """Create a new task with automatic model routing."""
    return await orchestrator.create_task(task, db)
```

**Key Points:**
- Use Pydantic models for request/response validation
- Dependency injection for database sessions
- Async endpoints for non-blocking LLM calls

---

### Async LLM Client Pattern

```python
from anthropic import AsyncAnthropic
from google import genai
from xai_sdk import AsyncClient as XAIClient
from ollama import AsyncClient as OllamaClient

# All providers support async clients for concurrent operations
async def parallel_validation(prompt: str, models: list[str]) -> list[str]:
    tasks = [call_llm(model, prompt) for model in models]
    responses = await asyncio.gather(*tasks, return_exceptions=True)
    return [r for r in responses if not isinstance(r, Exception)]
```

---

### MCP Server Pattern

```python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("multi-llm-platform")

@mcp.tool()
async def create_spec(description: str) -> dict:
    """Create a new project specification."""
    return await spec_service.create(description)

@mcp.resource("project://state")
async def get_project_state() -> str:
    """Get current project state."""
    return json.dumps(state_manager.get_state())
```

---

### Git Integration Pattern

```python
from git import Repo

def create_feature_branch(repo_path: str, feature_name: str) -> str:
    """Create a feature branch following conventional naming."""
    repo = Repo(repo_path)
    branch_name = f"feature/{feature_name.lower().replace(' ', '-')}"
    new_branch = repo.create_head(branch_name)
    new_branch.checkout()
    return branch_name

def commit_with_message(repo_path: str, files: list, message: str):
    """Commit with conventional commit message format."""
    repo = Repo(repo_path)
    repo.index.add(files)
    repo.index.commit(message)
```

**Gotcha:** GitPython leaks resources in long-running processes. For daemon usage, spawn as subprocess.

## Requirements

### Functional Requirements

1. **Multi-LLM Provider Integration**
   - Description: Support Claude, Gemini, Grok, and Ollama through unified interface
   - Acceptance: Can make requests to all 4 providers and receive responses

2. **Strategic Model Routing**
   - Description: Route tasks to optimal models based on task characteristics
   - Acceptance: Routing logic correctly assigns file analysis to Ollama, complex reasoning to Claude, multimodal to Gemini, real-time info to Grok

3. **Cross-Model Validation**
   - Description: Have multiple models review work for quality assurance
   - Acceptance: Critical decisions validated by 2+ models before acceptance

4. **Cost Optimization**
   - Description: Track and minimize API costs through intelligent model selection
   - Acceptance: Cost tracking visible in UI, local models used for appropriate tasks

5. **Adaptive Spec System**
   - Description: Interview workflow for gathering requirements, with re-interview capability
   - Acceptance: Can create spec via interview, modify spec mid-project, track spec versions

6. **Version Control Integration**
   - Description: Automatic branching, commit generation, PR creation
   - Acceptance: Git operations automated, conventional commit messages generated

7. **Project Steering**
   - Description: Mid-flight direction changes with context preservation
   - Acceptance: Can redirect project without losing history, impact analysis visible

8. **Skill Plugin System**
   - Description: Extensible architecture for specialized agent capabilities
   - Acceptance: Can load/unload skills, skills can be model-specific or agnostic

### Non-Functional Requirements

1. **Performance**
   - Parallel LLM calls for independent operations
   - Response time < 30s for most operations
   - Support concurrent users

2. **Security**
   - API keys stored securely (environment variables, not code)
   - No credential logging
   - Input validation on all endpoints

3. **Reliability**
   - Fallback strategies when models fail
   - Graceful degradation when providers unavailable
   - State persistence across restarts

### Edge Cases

1. **Provider Unavailable** - Fall back to alternate provider or queue for retry
2. **Rate Limiting** - Implement exponential backoff, queue excess requests
3. **Model Disagreement** - Escalate to higher-capability model for tie-breaking
4. **Large Context** - Automatically route to models with larger context windows (Gemini)
5. **Ollama Not Running** - Detect and warn, exclude from routing until available
6. **Mid-Spec Change** - Version current spec, preserve history, enable diff view
7. **Git Conflicts** - Detect and surface for manual resolution
8. **API Key Invalid** - Mark provider as unavailable, notify user

## Implementation Notes

### DO

- Use LiteLLM as unified wrapper instead of managing individual SDKs directly
- Use `google-genai` package, NOT deprecated `google-generativeai`
- Use official `xai-sdk` package, not community alternatives
- Pin MCP to `mcp>=1.25,<2` to avoid v2 breaking changes
- Use Python 3.11+ for compatibility with all packages (py-gitea requires 3.11+)
- Use async clients for all LLM operations to enable concurrency
- Use `fastapi[standard]` to get uvicorn bundled
- Start Ollama server separately before using Python client
- Pull Ollama models first: `ollama pull gemma3`

### DON'T

- Don't use GitPython in long-running daemon processes (resource leaks)
- Don't hardcode API keys - use environment variables
- Don't assume all models available - always check provider status
- Don't block on single LLM call when parallel is possible
- Don't generate code using deprecated google-generativeai patterns
- Don't use `--reload` flag in production uvicorn

## Development Environment

### Prerequisites

```bash
# Python 3.11+
python --version  # Should be 3.11+

# Node.js 18+
node --version  # Should be 18+

# Ollama (for local LLM)
# Download from https://ollama.com/download
ollama --version
```

### Start Services

```bash
# Terminal 1: Start Ollama server
ollama serve

# Terminal 2: Pull models
ollama pull gemma3
ollama pull codellama

# Terminal 3: Start backend
cd backend
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Terminal 4: Start frontend
cd frontend
npm install
npm run dev

# Terminal 5: Start MCP server (optional)
cd mcp-server
python server.py
```

### Service URLs

- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/docs
- Frontend: http://localhost:5173
- Ollama: http://localhost:11434

### Required Environment Variables

Create `.env` file from `.env.example`:

```bash
# LLM Provider Keys
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AI...
XAI_API_KEY=xai-...

# Ollama (optional, defaults shown)
OLLAMA_HOST=http://localhost:11434

# Database
DATABASE_URL=sqlite:///./multi_llm_platform.db

# Git/Gitea (optional)
GITEA_URL=http://localhost:3000
GITEA_TOKEN=your_gitea_token
```

## Success Criteria

The task is complete when:

1. [ ] Successfully make API calls to all 4 LLM providers (Claude, Gemini, Grok, Ollama)
2. [ ] Demonstrate intelligent model routing (correct model for task type)
3. [ ] Cross-model validation working for critical decisions
4. [ ] Cost tracking visible and accurate in UI
5. [ ] Spec interview workflow functional (create, modify, version)
6. [ ] Git integration working (branch, commit, PR creation)
7. [ ] Project steering possible mid-flight with context preservation
8. [ ] Skill plugin system loading and executing skills
9. [ ] Frontend dashboard displaying project state
10. [ ] No console errors in frontend or backend
11. [ ] All unit and integration tests passing

## QA Acceptance Criteria

**CRITICAL**: These criteria must be verified by the QA Agent before sign-off.

### Unit Tests

| Test | File | What to Verify |
|------|------|----------------|
| LLM Router | `backend/tests/test_llm_router.py` | Correct model selection for task types |
| Cost Tracker | `backend/tests/test_cost_tracker.py` | Accurate token and cost calculation |
| Spec Manager | `backend/tests/test_spec_manager.py` | CRUD operations, versioning |
| Skill Registry | `backend/tests/test_skill_registry.py` | Skill loading, execution, unloading |
| Git Service | `backend/tests/test_git_service.py` | Branch creation, commits, PR logic |
| Cross Validator | `backend/tests/test_cross_validate.py` | Multi-model validation logic |

### Integration Tests

| Test | Services | What to Verify |
|------|----------|----------------|
| LLM Provider Health | llm-wrapper + all providers | All 4 providers respond correctly |
| Task Routing E2E | orchestration + llm-wrapper | Tasks routed to correct models |
| Spec Persistence | spec-management + database | Specs saved and versioned correctly |
| Git Operations | version-control + local repo | Branch/commit/PR workflow works |
| MCP Tools | mcp-server + backend | MCP tools execute successfully |

### End-to-End Tests

| Flow | Steps | Expected Outcome |
|------|-------|------------------|
| Project Creation | 1. Open dashboard 2. Start interview 3. Answer questions 4. View spec | Spec created and displayed |
| Task Execution | 1. Create task 2. View routing 3. Check results | Task completed with correct model |
| Cross Validation | 1. Mark task critical 2. Submit 3. View validation | Multiple models validate before accept |
| Mid-Project Steer | 1. Modify spec 2. Confirm change 3. View history | Spec versioned, history preserved |
| Cost Report | 1. Execute tasks 2. View dashboard 3. Check costs | Accurate cost breakdown by provider |

### Browser Verification

| Page/Component | URL | Checks |
|----------------|-----|--------|
| Dashboard | `http://localhost:5173/` | Project overview loads, no errors |
| Spec Editor | `http://localhost:5173/spec` | Interview form works, saves correctly |
| Task Viewer | `http://localhost:5173/tasks` | Task list displays, status updates |
| Model Status | `http://localhost:5173/models` | Provider health indicators accurate |
| Cost Tracker | `http://localhost:5173/costs` | Cost charts render, data accurate |

### API Verification

| Endpoint | Method | Checks |
|----------|--------|--------|
| `/health` | GET | Returns 200, all services healthy |
| `/api/models/status` | GET | Returns status for all 4 providers |
| `/api/tasks` | POST | Creates task, returns task ID |
| `/api/specs` | POST | Creates spec from interview data |
| `/api/specs/{id}/versions` | GET | Returns version history |

### Database Verification

| Check | Query/Command | Expected |
|-------|---------------|----------|
| Tables created | `SELECT name FROM sqlite_master WHERE type='table'` | specs, tasks, decisions, model_interactions |
| Spec versioning | `SELECT COUNT(*) FROM spec_versions WHERE spec_id=1` | Versions increment on changes |
| Cost tracking | `SELECT SUM(cost) FROM model_interactions` | Non-zero, matches UI display |

### Security Verification

| Check | Method | Expected |
|-------|--------|----------|
| No hardcoded keys | `grep -r "sk-ant\|AIza" backend/` | No matches |
| Env vars loaded | Check startup logs | Keys loaded from environment |
| Input validation | Send malformed JSON to endpoints | 422 validation error returned |

### QA Sign-off Requirements

- [ ] All unit tests pass (`pytest backend/tests/`)
- [ ] All integration tests pass (`pytest backend/tests/integration/`)
- [ ] All E2E tests pass (Playwright or manual)
- [ ] Browser verification complete (all pages load, no console errors)
- [ ] API verification complete (all endpoints respond correctly)
- [ ] Database state verified (tables exist, data persists)
- [ ] Security verification complete (no credential exposure)
- [ ] No regressions in existing functionality
- [ ] Code follows established patterns (LiteLLM, FastAPI conventions)
- [ ] No security vulnerabilities introduced
- [ ] Cost tracking accurate within 5% of actual API costs
- [ ] All 4 LLM providers successfully integrated and responding

---

## Appendix: Package Versions

### Python Requirements (requirements.txt)

```
# Core Framework
fastapi[standard]>=0.115.0
uvicorn>=0.30.0
pydantic>=2.0.0

# LLM Providers
litellm>=1.0.0
anthropic>=0.39.0
google-genai>=1.0.0
xai-sdk>=0.1.0
ollama>=0.4.0

# MCP
mcp>=1.25,<2

# Database
sqlalchemy>=2.0.0
alembic>=1.13.0

# Git
GitPython>=3.1.40
py-gitea>=0.2.10

# Utilities
httpx>=0.27.0
python-dotenv>=1.0.0
```

### Node Requirements (package.json)

```json
{
  "dependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "@tanstack/react-query": "^5.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "vite": "^6.0.0",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "vitest": "^2.0.0",
    "@testing-library/react": "^16.0.0"
  }
}
```

---

## Appendix: Phased Implementation Milestones

Based on complexity assessment, implement in phases:

1. **Phase 1**: Core orchestration layer with single LLM provider (Claude via LiteLLM)
2. **Phase 2**: Add additional LLM providers with unified wrapper and routing
3. **Phase 3**: Spec management system and version control integration
4. **Phase 4**: Skill plugin system and cross-model validation
5. **Phase 5**: Frontend UI and project steering capabilities
6. **Phase 6**: Quality assurance, security hardening, and production readiness

-        model=model,  # e.g., "claude-3-opus", "gemini/gemini-pro", "ollama/llama3"

+        model=model,  # e.g., "claude-3-opus-20240229", "gemini/gemini-pro", "xai/grok-beta", "ollama/llama3"


Good, I've fixed the model name examples. Now let me add the health check pattern since it's mentioned in QA but not in the patterns section:

**Key Points:**
- Use Pydantic models for request/response validation
- Dependency injection for database sessions
- Async endpoints for non-blocking LLM calls

---

### Async LLM Client Pattern

**Key Points:**
- Use Pydantic models for request/response validation
- Dependency injection for database sessions
- Async endpoints for non-blocking LLM calls

---

### Health Check Pattern

```python
from fastapi import FastAPI
from pydantic import BaseModel

class HealthResponse(BaseModel):
    status: str
    services: dict[str, str]

@app.get("/health", response_model=HealthResponse)
async def health_check():
    """Check health of all services and LLM providers."""
    services = {
        "database": "healthy",
        "ollama": await check_ollama_status(),
        "claude": await check_claude_status(),
        "gemini": await check_gemini_status(),
        "grok": await check_grok_status(),
    }
    overall = "healthy" if all(s == "healthy" for s in services.values()) else "degraded"
    return HealthResponse(status=overall, services=services)
```

---

### Async LLM Client Pattern