## YOUR ROLE - SPEC CRITIC AGENT

You are the **Spec Critic Agent** in the Auto-Build spec creation pipeline. Your ONLY job is to critically review the spec.md document, find issues, and fix them.

**Key Principle**: Use extended thinking (ultrathink). Find problems BEFORE implementation.

---

## YOUR CONTRACT

**Inputs**:
- `spec.md` - The specification to critique
- `research.json` - Validated research findings
- `requirements.json` - Original user requirements
- `context.json` - Codebase context

**Output**:
- Fixed `spec.md` (if issues found)
- `critique_report.json` - Summary of issues and fixes

---

## PHASE 0: LOAD ALL CONTEXT

```bash
cat spec.md
cat research.json
cat requirements.json
cat context.json
```

Understand:
- What the spec claims
- What research validated
- What the user originally requested
- What patterns exist in the codebase

---

## PHASE 1: DEEP ANALYSIS (USE EXTENDED THINKING)

**CRITICAL**: Use extended thinking for this phase. Think deeply about:

### 1.1: Technical Accuracy

Compare spec.md against research.json AND validate with Context7:

- **Package names**: Does spec use correct package names from research?
- **Import statements**: Do imports match researched API patterns?
- **API calls**: Do function signatures match documentation?
- **Configuration**: Are env vars and config options correct?

**USE CONTEXT7 TO VALIDATE TECHNICAL CLAIMS:**

If the spec mentions specific libraries or APIs, verify them against Context7:

```
# Step 1: Resolve library ID
Tool: mcp__context7__resolve-library-id
Input: { "libraryName": "[library from spec]" }

# Step 2: Verify API patterns mentioned in spec
Tool: mcp__context7__get-library-docs
Input: {
  "context7CompatibleLibraryID": "[library-id]",
  "topic": "[specific API or feature mentioned in spec]",
  "mode": "code"
}
```

**Check for common spec errors:**
- Wrong package name (e.g., "react-query" vs "@tanstack/react-query")
- Outdated API patterns (e.g., using deprecated functions)
- Incorrect function signatures (e.g., wrong parameter order)
- Missing required configuration (e.g., missing env vars)

Flag any mismatches.

### 1.2: Completeness

Check against requirements.json:

- **All requirements covered?** - Each requirement should have implementation details
- **All acceptance criteria testable?** - Each criterion should be verifiable
- **Edge cases handled?** - Error conditions, empty states, timeouts
- **Integration points clear?** - How components connect

Flag any gaps.

### 1.3: Consistency

Check within spec.md:

- **Package names consistent** - Same name used everywhere
- **File paths consistent** - No conflicting paths
- **Patterns consistent** - Same style throughout
- **Terminology consistent** - Same terms for same concepts

Flag any inconsistencies.

### 1.4: Feasibility

Check practicality:

- **Dependencies available?** - All packages exist and are maintained
- **Infrastructure realistic?** - Docker setup will work
- **Implementation order logical?** - Dependencies before dependents
- **Scope appropriate?** - Not over-engineered, not under-specified

Flag any concerns.

### 1.5: Research Alignment

Cross-reference with research.json:

- **Verified information used?** - Spec should use researched facts
- **Unverified claims flagged?** - Any assumptions marked clearly
- **Gotchas addressed?** - Known issues from research handled
- **Recommendations followed?** - Research suggestions incorporated

Flag any divergences.

---

## PHASE 2: CATALOG ISSUES

Create a list of all issues found:

```
ISSUES FOUND:

1. [SEVERITY: HIGH] Package name incorrect
   - Spec says: "graphiti-core real_ladybug"
   - Research says: "graphiti-core" with separate "real_ladybug" dependency
   - Location: Line 45, Requirements section

2. [SEVERITY: MEDIUM] Missing edge case
   - Requirement: "Handle connection failures"
   - Spec: No error handling specified
   - Location: Implementation Notes section

3. [SEVERITY: LOW] Inconsistent terminology
   - Uses both "memory" and "episode" for same concept
   - Location: Throughout document
```

---

## PHASE 3: FIX ISSUES

For each issue found, fix it directly in spec.md:

```bash
# Read current spec
cat spec.md

# Apply fixes using edit commands
# Example: Fix package name
sed -i 's/graphiti-core real_ladybug/graphiti-core\nreal_ladybug/g' spec.md

# Or rewrite sections as needed
```

**For each fix**:
1. Make the change in spec.md
2. Verify the change was applied
3. Document what was changed

---

## PHASE 4: CREATE CRITIQUE REPORT

```bash
cat > critique_report.json << 'EOF'
{
  "critique_completed": true,
  "issues_found": [
    {
      "severity": "high|medium|low",
      "category": "accuracy|completeness|consistency|feasibility|alignment",
      "description": "[What was wrong]",
      "location": "[Where in spec.md]",
      "fix_applied": "[What was changed]",
      "verified": true
    }
  ],
  "issues_fixed": true,
  "no_issues_found": false,
  "critique_summary": "[Brief summary of critique]",
  "confidence_level": "high|medium|low",
  "recommendations": [
    "[Any remaining concerns or suggestions]"
  ],
  "created_at": "[ISO timestamp]"
}
EOF
```

If NO issues found:

```bash
cat > critique_report.json << 'EOF'
{
  "critique_completed": true,
  "issues_found": [],
  "issues_fixed": false,
  "no_issues_found": true,
  "critique_summary": "Spec is well-written with no significant issues found.",
  "confidence_level": "high",
  "recommendations": [],
  "created_at": "[ISO timestamp]"
}
EOF
```

---

## PHASE 5: VERIFY FIXES

After making changes:

```bash
# Verify spec is still valid markdown
head -50 spec.md

# Check key sections exist
grep -E "^##? Overview" spec.md
grep -E "^##? Requirements" spec.md
grep -E "^##? Success Criteria" spec.md
```

---

## PHASE 6: SIGNAL COMPLETION

```
=== SPEC CRITIQUE COMPLETE ===

Issues Found: [count]
- High severity: [count]
- Medium severity: [count]
- Low severity: [count]

Fixes Applied: [count]
Confidence Level: [high/medium/low]

Summary:
[Brief summary of what was found and fixed]

critique_report.json created successfully.
spec.md has been updated with fixes.
```

---

## CRITICAL RULES

1. **USE EXTENDED THINKING** - This is the deep analysis phase
2. **ALWAYS compare against research** - Research is the source of truth
3. **FIX issues, don't just report** - Make actual changes to spec.md
4. **VERIFY after fixing** - Ensure spec is still valid
5. **BE THOROUGH** - Check everything, miss nothing

---

## SEVERITY GUIDELINES

**HIGH** - Will cause implementation failure:
- Wrong package names
- Incorrect API signatures
- Missing critical requirements
- Invalid configuration

**MEDIUM** - May cause issues:
- Missing edge cases
- Incomplete error handling
- Unclear integration points
- Inconsistent patterns

**LOW** - Minor improvements:
- Terminology inconsistencies
- Documentation gaps
- Style issues
- Minor optimizations

---

## CATEGORY DEFINITIONS

- **Accuracy**: Technical correctness (packages, APIs, config)
- **Completeness**: Coverage of requirements and edge cases
- **Consistency**: Internal coherence of the document
- **Feasibility**: Practical implementability
- **Alignment**: Match with research findings

---

## EXTENDED THINKING PROMPT

When analyzing, think through:

> "Looking at this spec.md, I need to deeply analyze it against the research findings...
>
> First, let me check all package names. The research says the package is [X], but the spec says [Y]. This is a mismatch that needs fixing.
>
> Let me also verify with Context7 - I'll look up the actual package name and API patterns to confirm...
> [Use mcp__context7__resolve-library-id to find the library]
> [Use mcp__context7__get-library-docs to check API patterns]
>
> Next, looking at the API patterns. The research shows initialization requires [steps], but the spec shows [different steps]. Let me cross-reference with Context7 documentation... Another issue confirmed.
>
> For completeness, the requirements mention [X, Y, Z]. The spec covers X and Y but I don't see Z addressed anywhere. This is a gap.
>
> Looking at consistency, I notice 'memory' and 'episode' used interchangeably. Should standardize on one term.
>
> For feasibility, the Docker setup seems correct based on research. The port numbers match.
>
> Overall, I found [N] issues that need fixing before this spec is ready for implementation."

---

## BEGIN

Start by loading all context files, then use extended thinking to analyze the spec deeply.

---

**Spec Directory**: C:\Users\MikeSwanson\claude-projects\ACPlus\auto-claude-plus\.auto-claude\specs\001-multi-llm-agentic-development-platform
**Project Directory**: C:\Users\MikeSwanson\claude-projects\ACPlus\auto-claude-plus

## Context from Previous Phases

### Requirements
# Requirements Phase Summary

## Project Vision
Build a **multi-LLM agentic development platform** that orchestrates multiple AI models strategically, with adaptive requirements management and course correction capabilities. Extends Autocoder 2.0/Auto-Claude concepts.

## Key Architectural Decisions

**Multi-Model Strategy** (Core differentiator)
- No single LLM as source of truth - leverage collective intelligence
- Strategic routing by task type:
  - **Ollama**: Local, token-free lightweight tasks (file analysis, transforms)
  - **Claude Sonnet/Opus**: Complex reasoning and architecture
  - **Gemini**: Multimodal analysis, large context windows
  - **Grok**: Real-time information, alternative perspectives
- Cross-model validation for quality assurance
- Cost optimization through intelligent model selection

**Adaptive Requirements** (Not waterfall)
- Specs evolve with project, not frozen at start
- Re-interview capability to clarify ambiguities during development
- Spec versioning to track requirement evolution
- Mid-flight course correction and steering

## Critical Components to Implement

1. **Model Orchestration Layer**
   - Unified API wrapper supporting all providers
   - Task decomposition with model-specific assignments
   - Parallel execution engine with dependency management
   - Fallback strategies for model failures

2. **Version Control Integration**
   - Git/Gitea native support
   - Auto-branching strategies
   - Conventional commit message generation
   - PR creation with comprehensive descriptions

3. **Spec Management System**
   - Initial spec-app style interview
   - Spec versioning and history tracking
   - Re-interview workflow for clarification
   - Context preservation across changes

4. **Extensible Skill Architecture**
   - Plugin system for specialized capabilities
   - Model-specific and model-agnostic skills
   - Skill composition for complex workflows
   - Custom skill creation framework

5. **Quality Assurance Pipeline**
   - Multi-model consensus for critical decisions
   - Automated testing integration
   - Security scanning, performance profiling
   - Code quality metrics

## Technical Stack

- **Backend**: Python (FastAPI) orchestration layer
- **Frontend**: React/TypeScript for project management UI
- **State**: Track project state, agent activities, decisions
- **Database**: Store specs, decisions, task history, model interactions
- **MCP Server**: Feature graph and skill management

## Critical Constraints

- Minimum **3 LLM providers** working in concert
- Must demonstrate **cost savings** through model routing
- Must handle **mid-project requirement changes** gracefully
- Full **transparency**: visibility into which models did what and why
- Support **local-first** operation via Ollama

## Success Metrics

1. Complete full lifecycle: spec → implementation → steering → completion
2. Prove cost optimization through intelligent routing
3. Show quality improvements via cross-model validation
4. Handle evolving requirements without restart
5. Support at least 3 providers simultaneously

## Workflow Classification
**Type**: Refactoring - building on existing Autocoder 2.0/Auto-Claude patterns

### Research
# Research Phase Summary

## Critical Decisions & Package Choices

**LLM SDKs Verified:**
- **Anthropic Claude**: `pip install anthropic` - supports sync/async clients via `Anthropic()` and `AsyncAnthropic()`
- **Google Gemini**: `pip install google-genai` ⚠ **CRITICAL**: Old `google-generativeai` package is DEPRECATED (EOL Nov 30, 2025) - must use new `google-genai` for all development
- **xAI Grok**: `pip install xai-sdk` (official package, not community alternatives like `xai-grok` or `xai-grok-sdk`)
- **Ollama**: `pip install ollama` - requires separate Ollama server running locally

**Frameworks:**
- **Backend**: FastAPI - use `pip install "fastapi[standard]"` to get uvicorn + dependencies bundled
- **Frontend**: Vite + React + TypeScript - `npm create vite@latest -- --template react-ts`
- **MCP**: `pip install mcp` (v1.25.0+, v2 coming Q1)

## Critical Constraints & Requirements

**Python Requirements:**
- Python >= 3.10 (MCP SDK and xAI require this)
- Python >= 3.9 (Anthropic)
- Python >= 3.8 (Ollama)

**Node Requirements:**
- Node.js >= 18 (Vite)

**Infrastructure Dependencies:**
- **Ollama**: Separate Ollama server must be running (default: http://localhost:11434) + models must be pre-pulled with `ollama pull <model>`
- **FastAPI**: Requires ASGI server (uvicorn) - run with `uvicorn main:app --reload`
- **Vite**: Dev server runs on http://localhost:5173

## Key API Patterns Identified

**Authentication:**
- All LLM SDKs use environment variables: `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`
- Clients auto-detect env vars: `client = Anthropic()` or explicit: `Client(api_key='...')`

**Common Patterns:**
- All support both sync and async clients
- Context manager support for cleanup
- Streaming with `stream=True` parameter

**MCP Core Concepts:**
- **Resources**: GET-like endpoints for data access
- **Tools**: POST-like endpoints for actions
- **Prompts**: Reusable LLM interaction templates
- Transport options: stdio, SSE (Server-Sent Events)

## Critical Gotchas & Actionable Insights

1. **Google Gemini Migration Risk**: LLMs may generate code using deprecated `google-generativeai` - always use `google-genai`

2. **Ollama Workflow**:
   - Start server first: `ollama serve`
   - Pull models: `ollama pull gemma3`
   - Then use Python client

3. **FastAPI Setup**: Use `[standard]` extra to avoid missing uvicorn dependency

4. **xAI SDK**: gRPC-based, supports agentic tool calling with web search, X search, code execution

5. **Ollama Streaming**: Now supports streaming with MCP tool calling (recent update)

6. **Vite Templates**: `react-swc-ts` available for faster builds vs standard `react-ts`

7. **FastAPI Dev**: Use `--reload` flag for development only, not production

## Implementation Recommendations

- Use async clients for all LLM SDKs to enable concurrent operations
- FastAPI automatic OpenAPI docs available at `/docs` and `/redoc`
- Vite HMR provides instant updates without page refresh
- All verified packages have type definitions for better IDE support

### Context
# Context Phase: Key Findings

## Project Objective
Build a **multi-LLM agentic development platform** that orchestrates multiple AI models (Claude, Gemini, Grok, Ollama) for intelligent task routing, cost optimization, and quality assurance through cross-model validation.

## Critical Technical Decisions

**Tech Stack:**
- Backend: Python (FastAPI) for orchestration layer
- Frontend: React/TypeScript for project management UI
- Database: Store specs, decisions, task history, model interactions
- MCP Server: Feature graph and skill management
- Unified API wrapper supporting all LLM providers

**Model Routing Strategy:**
- Ollama → lightweight local tasks (file analysis, templating)
- Claude Sonnet/Opus → complex reasoning, architecture
- Gemini → multimodal analysis, large context windows
- Grok → real-time information, alternative perspectives

## Core Feature Requirements

**1. Multi-LLM Orchestration**
- Strategic task assignment based on model strengths
- Cross-model validation for quality assurance
- Fallback strategies when models fail
- Cost optimization through intelligent routing

**2. Adaptive Spec System**
- Initial spec-app style interview
- Re-interview capability for evolving requirements
- Spec versioning to track requirement evolution
- Continuous alignment with user intent

**3. Version Control Integration**
- Native Git/Gitea support
- Automatic branching strategies
- Conventional commit message generation
- PR creation with descriptions
- Branch-based code review

**4. Extensible Skill System**
- Model-specific or model-agnostic skills
- Examples: code review, security scanning, performance optimization
- Custom skill framework
- Skill composition/chaining

**5. Project Steering**
- Mid-flight direction changes
- Checkpoint system at milestones
- Context preservation across pivots
- Impact analysis for changes
- Graceful refactoring vs. starting over

**6. Quality Assurance**
- Multi-model consensus for critical decisions
- Automated testing integration
- Code quality metrics
- Security scanning
- Performance profiling

## Key Constraints

- Must support ≥3 LLM providers working together
- Cost optimization is critical success factor
- Local-first capability required (Ollama)
- Full transparency into model decisions
- Handle evolving requirements gracefully

## Implementation Priorities

**Success Metrics:**
1. Complete full lifecycle: spec → implementation → steering → completion
2. Demonstrate cost savings through model routing
3. Prove quality improvements via cross-validation
4. Handle mid-project requirement changes
5. Integrate 3+ LLM providers successfully

**Key Differentiators:**
- Model democracy (no single source of truth)
- Adaptive, not frozen requirements
- Local-first option for cost savings
- Course correction capabilities
- Full traceability

## Actionable Insights

- Build unified API abstraction layer first (critical for multi-provider support)
- Implement task decomposition engine early (enables parallel execution)
- Design state management for tracking decisions across models
- Create checkpoint system for milestone reviews
- Focus on graceful degradation and fallback strategies

### Spec Writing
# Spec Writing Phase - Key Findings

## Project Classification
- **Workflow Type**: Feature (Greenfield Development)
- **Rationale**: Empty codebase despite referencing Autocoder 2.0/Auto-Claude patterns. Building from scratch, not refactoring.

## Core Architecture Decisions

### Multi-Service Design (5 services)
1. **orchestration-service**: Task decomposition, model routing, parallel execution
2. **llm-wrapper-service**: Unified LLM API via LiteLLM abstraction
3. **spec-management-service**: Adaptive specs with interview/re-interview workflows
4. **skill-service**: Extensible plugin architecture
5. **version-control-service**: Git/Gitea automation

### Technology Stack
- **Backend**: Python 3.11+, FastAPI, SQLAlchemy, uvicorn (port 8000)
- **Frontend**: TypeScript, React, Vite (port 5173)
- **MCP Server**: FastMCP SDK, Python
- **LLM Integration**: LiteLLM as unified interface layer

## Critical Technical Decisions

### LiteLLM as Unified Interface
- **Why**: Single API for 100+ providers vs. managing 4+ separate SDKs
- **Models**: Claude (`claude-3-opus`), Gemini (`gemini/gemini-pro`), Grok (`xai/grok`), Ollama (`ollama/llama3`)
- **Built-in features**: Cost tracking, automatic retries, fallback logic
- **Pattern**: `await acompletion(model=model, messages=messages)` works universally

### Async-First Architecture
- All LLM calls use async clients (`AsyncAnthropic`, async `genai`, etc.)
- Enables parallel validation across models
- FastAPI async endpoints prevent blocking

### Database Schema Requirements
Four core models identified:
- `Spec`: Version-tracked project specifications
- `Task`: Task history with model assignments
- `Decision`: Decision tracking for course correction
- Model interaction logs (via LiteLLM)

## Critical Files & Components

### Backend Core (33 files total)
- **Entry**: `backend/main.py` (FastAPI app)
- **Orchestration**: `backend/services/orchestrator.py` (routing logic)
- **LLM Layer**: `backend/llm/unified_client.py` + 4 provider files
- **Routing**: `backend/llm/routing/router.py` (task-to-model matching)
- **Validation**: `backend/llm/validation/cross_validate.py`
- **Git**: `backend/git/git_service.py`, `gitea_service.py`

### Frontend (8 files)
- `Dashboard.tsx`, `SpecEditor.tsx`, `TaskViewer.tsx`
- `ModelStatus.tsx`, `CostTracker.tsx` (monitoring)

### MCP Server (4 files)
- `server.py`, `spec_tools.py`, `task_tools.py`, `project_state.py`

## Key Constraints & Requirements

### Environment Dependencies
```bash
ANTHROPIC_API_KEY, GEMINI_API_KEY, XAI_API_KEY required
Ollama needs local server (no API key)
```

### Explicitly Out of Scope
- Production deployment (K8s, cloud)
- Enterprise auth (SSO/SAML)
- Multi-tenant architecture
- Billing/subscriptions
- Mobile apps
- CI/CD integration beyond Git ops

## Actionable Implementation Insights

### Phase 1 Priority
1. Set up FastAPI skeleton + LiteLLM wrapper first (enables testing with real models early)
2. Build basic orchestrator with single-model routing before adding cross-validation
3. SQLAlchemy models before API routes (data layer foundation)

### Integration Strategy
- LiteLLM handles provider differences automatically
- Use `asyncio.gather()` for parallel model calls
- Cost tracking via `litellm.track_cost = True` (built-in)

### Git Workflow Pattern
- Feature branches per task
- Conventional commit message generation
- Gitea API for PR automation

### Cross-Model Validation Pattern
```python
async def parallel_validation(prompt, models):
    tasks = [call_llm(model, prompt) for model in models]
    return await asyncio.gather(*tasks, return_exceptions=True)
```

## Risk Mitigation
- LiteLLM abstracts provider API changes
- Async architecture prevents blocking on slow model responses
- Local Ollama provides cost-free fallback for high-volume tasks

**Spec File**: C:\Users\MikeSwanson\claude-projects\ACPlus\auto-claude-plus\.auto-claude\specs\001-multi-llm-agentic-development-platform\spec.md
**Research File**: C:\Users\MikeSwanson\claude-projects\ACPlus\auto-claude-plus\.auto-claude\specs\001-multi-llm-agentic-development-platform\research.json
**Critique Output**: C:\Users\MikeSwanson\claude-projects\ACPlus\auto-claude-plus\.auto-claude\specs\001-multi-llm-agentic-development-platform\critique_report.json

Use EXTENDED THINKING (ultrathink) to deeply analyze the spec.md:

1. **Technical Accuracy**: Do code examples match the research findings?
2. **Completeness**: Are all requirements covered? Edge cases handled?
3. **Consistency**: Do package names, APIs, and patterns match throughout?
4. **Feasibility**: Is the implementation approach realistic?

For each issue found:
- Fix it directly in spec.md
- Document what was fixed in critique_report.json

Output critique_report.json with:
{
  "issues_found": [...],
  "issues_fixed": true/false,
  "no_issues_found": true/false,
  "critique_summary": "..."
}


The user wants me to act as a Spec Critic Agent to review the spec.md document against research.json, requirements.json, and context.json. I need to:

1. Load all context files first
2. Use extended thinking to deeply analyze the spec
3. Find issues and fix them
4. Create a critique_report.json

Let me start by loading all the context files.

I'll begin by loading all context files to understand the full picture before critically analyzing the spec.


     1→# Specification: Multi-LLM Agentic Development Platform
     2→
     3→## Overview
     4→
     5→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.
     6→
     7→## Workflow Type
     8→
     9→**Type**: Feature (Greenfield Development)
    10→
    11→**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.
    12→
    13→## Task Scope
    14→
    15→### Services Involved
    16→
    17→- **orchestration-service** (primary) - Core task decomposition, model routing, parallel execution engine
    18→- **llm-wrapper-service** (primary) - Unified API abstraction for all LLM providers via LiteLLM
    19→- **spec-management-service** (primary) - Adaptive spec system with interview and versioning
    20→- **skill-service** (integration) - Extensible plugin architecture for specialized capabilities
    21→- **version-control-service** (integration) - Git/Gitea automation for branching, commits, PRs
    22→- **frontend-ui** (integration) - React/TypeScript project management dashboard
    23→
    24→### This Task Will:
    25→
    26→- [ ] Create Python/FastAPI backend with modular service architecture
    27→- [ ] Implement unified LLM wrapper supporting Claude, Gemini, Grok, and Ollama
    28→- [ ] Build task orchestration engine with model-specific routing
    29→- [ ] Implement cross-model validation for quality assurance
    30→- [ ] Create adaptive spec system with interview and re-interview workflows
    31→- [ ] Build extensible skill/addon plugin architecture
    32→- [ ] Integrate Git/Gitea for version control automation
    33→- [ ] Implement checkpoint system for project steering and course correction
    34→- [ ] Create React/TypeScript frontend for project management
    35→- [ ] Design database schema for specs, decisions, task history, model interactions
    36→- [ ] Build MCP server for feature graph and skill management
    37→
    38→### Out of Scope:
    39→
    40→- Production deployment infrastructure (Kubernetes, cloud deployment)
    41→- Enterprise SSO/SAML authentication
    42→- Multi-tenant user management
    43→- Billing and subscription management
    44→- Mobile application
    45→- Integration with CI/CD pipelines (beyond basic Git operations)
    46→
    47→## Service Context
    48→
    49→### Backend Orchestration Service
    50→
    51→**Tech Stack:**
    52→- Language: Python 3.11+
    53→- Framework: FastAPI with uvicorn ASGI server
    54→- Key packages: `fastapi[standard]`, `pydantic`, `httpx`, `sqlalchemy`
    55→- Key directories: `backend/`, `backend/services/`, `backend/api/`, `backend/models/`
    56→
    57→**Entry Point:** `backend/main.py`
    58→
    59→**How to Run:**
    60→```bash
    61→cd backend
    62→pip install -r requirements.txt
    63→uvicorn main:app --reload --port 8000
    64→```
    65→
    66→**Port:** 8000
    67→
    68→**API Documentation:** http://localhost:8000/docs (Swagger) and http://localhost:8000/redoc
    69→
    70→---
    71→
    72→### LLM Wrapper Service
    73→
    74→**Tech Stack:**
    75→- Language: Python 3.11+
    76→- Framework: LiteLLM for unified interface
    77→- Key packages: `litellm`, `anthropic`, `google-genai`, `xai-sdk`, `ollama`
    78→- Key directories: `backend/llm/`, `backend/llm/providers/`, `backend/llm/routing/`
    79→
    80→**Entry Point:** `backend/llm/__init__.py`
    81→
    82→**Configuration:**
    83→```bash
    84→# Environment variables required
    85→ANTHROPIC_API_KEY=your_anthropic_key
    86→GEMINI_API_KEY=your_gemini_key
    87→XAI_API_KEY=your_xai_key
    88→# Ollama uses local server, no API key needed
    89→```
    90→
    91→---
    92→
    93→### Frontend UI
    94→
    95→**Tech Stack:**
    96→- Language: TypeScript
    97→- Framework: React with Vite
    98→- Key packages: `react`, `react-dom`, `typescript`, `@tanstack/react-query`
    99→- Key directories: `frontend/src/`, `frontend/src/components/`, `frontend/src/pages/`
   100→
   101→**Entry Point:** `frontend/src/main.tsx`
   102→
   103→**How to Run:**
   104→```bash
   105→cd frontend
   106→npm install
   107→npm run dev
   108→```
   109→
   110→**Port:** 5173
   111→
   112→---
   113→
   114→### MCP Server
   115→
   116→**Tech Stack:**
   117→- Language: Python 3.11+
   118→- Framework: MCP SDK (FastMCP)
   119→- Key packages: `mcp>=1.25,<2`
   120→- Key directories: `mcp-server/`, `mcp-server/tools/`, `mcp-server/resources/`
   121→
   122→**Entry Point:** `mcp-server/server.py`
   123→
   124→**How to Run:**
   125→```bash
   126→cd mcp-server
   127→python server.py
   128→```
   129→
   130→## Files to Create
   131→
   132→| File | Service | Purpose |
   133→|------|---------|---------|
   134→| `backend/main.py` | orchestration | FastAPI application entry point |
   135→| `backend/requirements.txt` | orchestration | Python dependencies |
   136→| `backend/api/routes/__init__.py` | orchestration | API route aggregation |
   137→| `backend/api/routes/tasks.py` | orchestration | Task management endpoints |
   138→| `backend/api/routes/specs.py` | orchestration | Spec management endpoints |
   139→| `backend/api/routes/models.py` | orchestration | LLM provider status endpoints |
   140→| `backend/services/orchestrator.py` | orchestration | Task decomposition and routing |
   141→| `backend/services/spec_manager.py` | spec-management | Spec CRUD and versioning |
   142→| `backend/services/skill_registry.py` | skill-service | Skill loading and execution |
   143→| `backend/llm/unified_client.py` | llm-wrapper | LiteLLM wrapper with routing logic |
   144→| `backend/llm/providers/claude.py` | llm-wrapper | Claude-specific optimizations |
   145→| `backend/llm/providers/gemini.py` | llm-wrapper | Gemini-specific optimizations |
   146→| `backend/llm/providers/grok.py` | llm-wrapper | Grok-specific optimizations |
   147→| `backend/llm/providers/ollama.py` | llm-wrapper | Ollama local model integration |
   148→| `backend/llm/routing/router.py` | llm-wrapper | Task-to-model routing logic |
   149→| `backend/llm/routing/cost_tracker.py` | llm-wrapper | Token usage and cost tracking |
   150→| `backend/llm/validation/cross_validate.py` | llm-wrapper | Cross-model validation logic |
   151→| `backend/models/database.py` | orchestration | SQLAlchemy database setup |
   152→| `backend/models/spec.py` | orchestration | Spec data model |
   153→| `backend/models/task.py` | orchestration | Task data model |
   154→| `backend/models/decision.py` | orchestration | Decision tracking model |
   155→| `backend/git/git_service.py` | version-control | GitPython wrapper |
   156→| `backend/git/gitea_service.py` | version-control | Gitea API integration |
   157→| `backend/git/commit_generator.py` | version-control | Conventional commit messages |
   158→| `mcp-server/server.py` | mcp | FastMCP server entry |
   159→| `mcp-server/tools/spec_tools.py` | mcp | Spec management MCP tools |
   160→| `mcp-server/tools/task_tools.py` | mcp | Task management MCP tools |
   161→| `mcp-server/resources/project_state.py` | mcp | Project state MCP resources |
   162→| `frontend/package.json` | frontend | NPM dependencies |
   163→| `frontend/vite.config.ts` | frontend | Vite configuration |
   164→| `frontend/src/main.tsx` | frontend | React entry point |
   165→| `frontend/src/App.tsx` | frontend | Main application component |
   166→| `frontend/src/pages/Dashboard.tsx` | frontend | Project dashboard |
   167→| `frontend/src/pages/SpecEditor.tsx` | frontend | Spec editing interface |
   168→| `frontend/src/pages/TaskViewer.tsx` | frontend | Task status viewer |
   169→| `frontend/src/components/ModelStatus.tsx` | frontend | LLM provider status display |
   170→| `frontend/src/components/CostTracker.tsx` | frontend | Cost tracking visualization |
   171→| `docker-compose.yml` | infrastructure | Container orchestration |
   172→| `.env.example` | infrastructure | Environment variable template |
   173→
   174→## Patterns to Follow
   175→
   176→### LiteLLM Unified Interface Pattern
   177→
   178→Use LiteLLM as the unified API wrapper for all LLM providers:
   179→
   180→```python
   181→from litellm import completion, acompletion
   182→
   183→# Unified interface - same code for any provider
   184→async def call_llm(model: str, messages: list, **kwargs) -> str:
   185→    response = await acompletion(
   186→        model=model,  # e.g., "claude-3-opus", "gemini/gemini-pro", "ollama/llama3"
   187→        messages=messages,
   188→        **kwargs
   189→    )
   190→    return response.choices[0].message.content
   191→```
   192→
   193→**Key Points:**
   194→- Model names follow `provider/model` format for non-OpenAI models
   195→- Built-in cost tracking via `litellm.track_cost = True`
   196→- Automatic retries and fallbacks configurable
   197→- Same interface works across 100+ LLM providers
   198→
   199→---
   200→
   201→### FastAPI Service Pattern
   202→
   203→```python
   204→from fastapi import FastAPI, Depends, HTTPException
   205→from pydantic import BaseModel
   206→
   207→app = FastAPI(title="Multi-LLM Platform")
   208→
   209→class TaskCreate(BaseModel):
   210→    description: str
   211→    priority: str = "normal"
   212→
   213→@app.post("/tasks/", response_model=Task)
   214→async def create_task(task: TaskCreate, db: Session = Depends(get_db)):
   215→    """Create a new task with automatic model routing."""
   216→    return await orchestrator.create_task(task, db)
   217→```
   218→
   219→**Key Points:**
   220→- Use Pydantic models for request/response validation
   221→- Dependency injection for database sessions
   222→- Async endpoints for non-blocking LLM calls
   223→
   224→---
   225→
   226→### Async LLM Client Pattern
   227→
   228→```python
   229→from anthropic import AsyncAnthropic
   230→from google import genai
   231→from xai_sdk import AsyncClient as XAIClient
   232→from ollama import AsyncClient as OllamaClient
   233→
   234→# All providers support async clients for concurrent operations
   235→async def parallel_validation(prompt: str, models: list[str]) -> list[str]:
   236→    tasks = [call_llm(model, prompt) for model in models]
   237→    responses = await asyncio.gather(*tasks, return_exceptions=True)
   238→    return [r for r in responses if not isinstance(r, Exception)]
   239→```
   240→
   241→---
   242→
   243→### MCP Server Pattern
   244→
   245→```python
   246→from mcp.server.fastmcp import FastMCP
   247→
   248→mcp = FastMCP("multi-llm-platform")
   249→
   250→@mcp.tool()
   251→async def create_spec(description: str) -> dict:
   252→    """Create a new project specification."""
   253→    return await spec_service.create(description)
   254→
   255→@mcp.resource("project://state")
   256→async def get_project_state() -> str:
   257→    """Get current project state."""
   258→    return json.dumps(state_manager.get_state())
   259→```
   260→
   261→---
   262→
   263→### Git Integration Pattern
   264→
   265→```python
   266→from git import Repo
   267→
   268→def create_feature_branch(repo_path: str, feature_name: str) -> str:
   269→    """Create a feature branch following conventional naming."""
   270→    repo = Repo(repo_path)
   271→    branch_name = f"feature/{feature_name.lower().replace(' ', '-')}"
   272→    new_branch = repo.create_head(branch_name)
   273→    new_branch.checkout()
   274→    return branch_name
   275→
   276→def commit_with_message(repo_path: str, files: list, message: str):
   277→    """Commit with conventional commit message format."""
   278→    repo = Repo(repo_path)
   279→    repo.index.add(files)
   280→    repo.index.commit(message)
   281→```
   282→
   283→**Gotcha:** GitPython leaks resources in long-running processes. For daemon usage, spawn as subprocess.
   284→
   285→## Requirements
   286→
   287→### Functional Requirements
   288→
   289→1. **Multi-LLM Provider Integration**
   290→   - Description: Support Claude, Gemini, Grok, and Ollama through unified interface
   291→   - Acceptance: Can make requests to all 4 providers and receive responses
   292→
   293→2. **Strategic Model Routing**
   294→   - Description: Route tasks to optimal models based on task characteristics
   295→   - Acceptance: Routing logic correctly assigns file analysis to Ollama, complex reasoning to Claude, multimodal to Gemini, real-time info to Grok
   296→
   297→3. **Cross-Model Validation**
   298→   - Description: Have multiple models review work for quality assurance
   299→   - Acceptance: Critical decisions validated by 2+ models before acceptance
   300→
   301→4. **Cost Optimization**
   302→   - Description: Track and minimize API costs through intelligent model selection
   303→   - Acceptance: Cost tracking visible in UI, local models used for appropriate tasks
   304→
   305→5. **Adaptive Spec System**
   306→   - Description: Interview workflow for gathering requirements, with re-interview capability
   307→   - Acceptance: Can create spec via interview, modify spec mid-project, track spec versions
   308→
   309→6. **Version Control Integration**
   310→   - Description: Automatic branching, commit generation, PR creation
   311→   - Acceptance: Git operations automated, conventional commit messages generated
   312→
   313→7. **Project Steering**
   314→   - Description: Mid-flight direction changes with context preservation
   315→   - Acceptance: Can redirect project without losing history, impact analysis visible
   316→
   317→8. **Skill Plugin System**
   318→   - Description: Extensible architecture for specialized agent capabilities
   319→   - Acceptance: Can load/unload skills, skills can be model-specific or agnostic
   320→
   321→### Non-Functional Requirements
   322→
   323→1. **Performance**
   324→   - Parallel LLM calls for independent operations
   325→   - Response time < 30s for most operations
   326→   - Support concurrent users
   327→
   328→2. **Security**
   329→   - API keys stored securely (environment variables, not code)
   330→   - No credential logging
   331→   - Input validation on all endpoints
   332→
   333→3. **Reliability**
   334→   - Fallback strategies when models fail
   335→   - Graceful degradation when providers unavailable
   336→   - State persistence across restarts
   337→
   338→### Edge Cases
   339→
   340→1. **Provider Unavailable** - Fall back to alternate provider or queue for retry
   341→2. **Rate Limiting** - Implement exponential backoff, queue excess requests
   342→3. **Model Disagreement** - Escalate to higher-capability model for tie-breaking
   343→4. **Large Context** - Automatically route to models with larger context windows (Gemini)
   344→5. **Ollama Not Running** - Detect and warn, exclude from routing until available
   345→6. **Mid-Spec Change** - Version current spec, preserve history, enable diff view
   346→7. **Git Conflicts** - Detect and surface for manual resolution
   347→8. **API Key Invalid** - Mark provider as unavailable, notify user
   348→
   349→## Implementation Notes
   350→
   351→### DO
   352→
   353→- Use LiteLLM as unified wrapper instead of managing individual SDKs directly
   354→- Use `google-genai` package, NOT deprecated `google-generativeai`
   355→- Use official `xai-sdk` package, not community alternatives
   356→- Pin MCP to `mcp>=1.25,<2` to avoid v2 breaking changes
   357→- Use Python 3.11+ for compatibility with all packages (py-gitea requires 3.11+)
   358→- Use async clients for all LLM operations to enable concurrency
   359→- Use `fastapi[standard]` to get uvicorn bundled
   360→- Start Ollama server separately before using Python client
   361→- Pull Ollama models first: `ollama pull gemma3`
   362→
   363→### DON'T
   364→
   365→- Don't use GitPython in long-running daemon processes (resource leaks)
   366→- Don't hardcode API keys - use environment variables
   367→- Don't assume all models available - always check provider status
   368→- Don't block on single LLM call when parallel is possible
   369→- Don't generate code using deprecated google-generativeai patterns
   370→- Don't use `--reload` flag in production uvicorn
   371→
   372→## Development Environment
   373→
   374→### Prerequisites
   375→
   376→```bash
   377→# Python 3.11+
   378→python --version  # Should be 3.11+
   379→
   380→# Node.js 18+
   381→node --version  # Should be 18+
   382→
   383→# Ollama (for local LLM)
   384→# Download from https://ollama.com/download
   385→ollama --version
   386→```
   387→
   388→### Start Services
   389→
   390→```bash
   391→# Terminal 1: Start Ollama server
   392→ollama serve
   393→
   394→# Terminal 2: Pull models
   395→ollama pull gemma3
   396→ollama pull codellama
   397→
   398→# Terminal 3: Start backend
   399→cd backend
   400→pip install -r requirements.txt
   401→uvicorn main:app --reload --port 8000
   402→
   403→# Terminal 4: Start frontend
   404→cd frontend
   405→npm install
   406→npm run dev
   407→
   408→# Terminal 5: Start MCP server (optional)
   409→cd mcp-server
   410→python server.py
   411→```
   412→
   413→### Service URLs
   414→
   415→- Backend API: http://localhost:8000
   416→- API Docs: http://localhost:8000/docs
   417→- Frontend: http://localhost:5173
   418→- Ollama: http://localhost:11434
   419→
   420→### Required Environment Variables
   421→
   422→Create `.env` file from `.env.example`:
   423→
   424→```bash
   425→# LLM Provider Keys
   426→ANTHROPIC_API_KEY=sk-ant-...
   427→GEMINI_API_KEY=AI...
   428→XAI_API_KEY=xai-...
   429→
   430→# Ollama (optional, defaults shown)
   431→OLLAMA_HOST=http://localhost:11434
   432→
   433→# Database
   434→DATABASE_URL=sqlite:///./multi_llm_platform.db
   435→
   436→# Git/Gitea (optional)
   437→GITEA_URL=http://localhost:3000
   438→GITEA_TOKEN=your_gitea_token
   439→```
   440→
   441→## Success Criteria
   442→
   443→The task is complete when:
   444→
   445→1. [ ] Successfully make API calls to all 4 LLM providers (Claude, Gemini, Grok, Ollama)
   446→2. [ ] Demonstrate intelligent model routing (correct model for task type)
   447→3. [ ] Cross-model validation working for critical decisions
   448→4. [ ] Cost tracking visible and accurate in UI
   449→5. [ ] Spec interview workflow functional (create, modify, version)
   450→6. [ ] Git integration working (branch, commit, PR creation)
   451→7. [ ] Project steering possible mid-flight with context preservation
   452→8. [ ] Skill plugin system loading and executing skills
   453→9. [ ] Frontend dashboard displaying project state
   454→10. [ ] No console errors in frontend or backend
   455→11. [ ] All unit and integration tests passing
   456→
   457→## QA Acceptance Criteria
   458→
   459→**CRITICAL**: These criteria must be verified by the QA Agent before sign-off.
   460→
   461→### Unit Tests
   462→
   463→| Test | File | What to Verify |
   464→|------|------|----------------|
   465→| LLM Router | `backend/tests/test_llm_router.py` | Correct model selection for task types |
   466→| Cost Tracker | `backend/tests/test_cost_tracker.py` | Accurate token and cost calculation |
   467→| Spec Manager | `backend/tests/test_spec_manager.py` | CRUD operations, versioning |
   468→| Skill Registry | `backend/tests/test_skill_registry.py` | Skill loading, execution, unloading |
   469→| Git Service | `backend/tests/test_git_service.py` | Branch creation, commits, PR logic |
   470→| Cross Validator | `backend/tests/test_cross_validate.py` | Multi-model validation logic |
   471→
   472→### Integration Tests
   473→
   474→| Test | Services | What to Verify |
   475→|------|----------|----------------|
   476→| LLM Provider Health | llm-wrapper + all providers | All 4 providers respond correctly |
   477→| Task Routing E2E | orchestration + llm-wrapper | Tasks routed to correct models |
   478→| Spec Persistence | spec-management + database | Specs saved and versioned correctly |
   479→| Git Operations | version-control + local repo | Branch/commit/PR workflow works |
   480→| MCP Tools | mcp-server + backend | MCP tools execute successfully |
   481→
   482→### End-to-End Tests
   483→
   484→| Flow | Steps | Expected Outcome |
   485→|------|-------|------------------|
   486→| Project Creation | 1. Open dashboard 2. Start interview 3. Answer questions 4. View spec | Spec created and displayed |
   487→| Task Execution | 1. Create task 2. View routing 3. Check results | Task completed with correct model |
   488→| Cross Validation | 1. Mark task critical 2. Submit 3. View validation | Multiple models validate before accept |
   489→| Mid-Project Steer | 1. Modify spec 2. Confirm change 3. View history | Spec versioned, history preserved |
   490→| Cost Report | 1. Execute tasks 2. View dashboard 3. Check costs | Accurate cost breakdown by provider |
   491→
   492→### Browser Verification
   493→
   494→| Page/Component | URL | Checks |
   495→|----------------|-----|--------|
   496→| Dashboard | `http://localhost:5173/` | Project overview loads, no errors |
   497→| Spec Editor | `http://localhost:5173/spec` | Interview form works, saves correctly |
   498→| Task Viewer | `http://localhost:5173/tasks` | Task list displays, status updates |
   499→| Model Status | `http://localhost:5173/models` | Provider health indicators accurate |
   500→| Cost Tracker | `http://localhost:5173/costs` | Cost charts render, data accurate |
   501→
   502→### API Verification
   503→
   504→| Endpoint | Method | Checks |
   505→|----------|--------|--------|
   506→| `/health` | GET | Returns 200, all services healthy |
   507→| `/api/models/status` | GET | Returns status for all 4 providers |
   508→| `/api/tasks` | POST | Creates task, returns task ID |
   509→| `/api/specs` | POST | Creates spec from interview data |
   510→| `/api/specs/{id}/versions` | GET | Returns version history |
   511→
   512→### Database Verification
   513→
   514→| Check | Query/Command | Expected |
   515→|-------|---------------|----------|
   516→| Tables created | `SELECT name FROM sqlite_master WHERE type='table'` | specs, tasks, decisions, model_interactions |
   517→| Spec versioning | `SELECT COUNT(*) FROM spec_versions WHERE spec_id=1` | Versions increment on changes |
   518→| Cost tracking | `SELECT SUM(cost) FROM model_interactions` | Non-zero, matches UI display |
   519→
   520→### Security Verification
   521→
   522→| Check | Method | Expected |
   523→|-------|--------|----------|
   524→| No hardcoded keys | `grep -r "sk-ant\|AIza" backend/` | No matches |
   525→| Env vars loaded | Check startup logs | Keys loaded from environment |
   526→| Input validation | Send malformed JSON to endpoints | 422 validation error returned |
   527→
   528→### QA Sign-off Requirements
   529→
   530→- [ ] All unit tests pass (`pytest backend/tests/`)
   531→- [ ] All integration tests pass (`pytest backend/tests/integration/`)
   532→- [ ] All E2E tests pass (Playwright or manual)
   533→- [ ] Browser verification complete (all pages load, no console errors)
   534→- [ ] API verification complete (all endpoints respond correctly)
   535→- [ ] Database state verified (tables exist, data persists)
   536→- [ ] Security verification complete (no credential exposure)
   537→- [ ] No regressions in existing functionality
   538→- [ ] Code follows established patterns (LiteLLM, FastAPI conventions)
   539→- [ ] No security vulnerabilities introduced
   540→- [ ] Cost tracking accurate within 5% of actual API costs
   541→- [ ] All 4 LLM providers successfully integrated and responding
   542→
   543→---
   544→
   545→## Appendix: Package Versions
   546→
   547→### Python Requirements (requirements.txt)
   548→
   549→```
   550→# Core Framework
   551→fastapi[standard]>=0.115.0
   552→uvicorn>=0.30.0
   553→pydantic>=2.0.0
   554→
   555→# LLM Providers
   556→litellm>=1.0.0
   557→anthropic>=0.39.0
   558→google-genai>=1.0.0
   559→xai-sdk>=0.1.0
   560→ollama>=0.4.0
   561→
   562→# MCP
   563→mcp>=1.25,<2
   564→
   565→# Database
   566→sqlalchemy>=2.0.0
   567→alembic>=1.13.0
   568→
   569→# Git
   570→GitPython>=3.1.40
   571→py-gitea>=0.2.10
   572→
   573→# Utilities
   574→httpx>=0.27.0
   575→python-dotenv>=1.0.0
   576→```
   577→
   578→### Node Requirements (package.json)
   579→
   580→```json
   581→{
   582→  "dependencies": {
   583→    "react": "^18.0.0",
   584→    "react-dom": "^18.0.0",
   585→    "@tanstack/react-query": "^5.0.0"
   586→  },
   587→  "devDependencies": {
   588→    "typescript": "^5.0.0",
   589→    "vite": "^6.0.0",
   590→    "@types/react": "^18.0.0",
   591→    "@types/react-dom": "^18.0.0",
   592→    "vitest": "^2.0.0",
   593→    "@testing-library/react": "^16.0.0"
   594→  }
   595→}
   596→```
   597→
   598→---
   599→
   600→## Appendix: Phased Implementation Milestones
   601→
   602→Based on complexity assessment, implement in phases:
   603→
   604→1. **Phase 1**: Core orchestration layer with single LLM provider (Claude via LiteLLM)
   605→2. **Phase 2**: Add additional LLM providers with unified wrapper and routing
   606→3. **Phase 3**: Spec management system and version control integration
   607→4. **Phase 4**: Skill plugin system and cross-model validation
   608→5. **Phase 5**: Frontend UI and project steering capabilities
   609→6. **Phase 6**: Quality assurance, security hardening, and production readiness
   610→

<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>

# 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


     1→{
     2→  "integrations_researched": [
     3→    {
     4→      "name": "Anthropic Claude SDK",
     5→      "type": "library",
     6→      "verified_package": {
     7→        "name": "anthropic",
     8→        "install_command": "pip install anthropic",
     9→        "version": "latest (Nov 2025)",
    10→        "python_requires": ">=3.9",
    11→        "verified": true
    12→      },
    13→      "api_patterns": {
    14→        "imports": [
    15→          "from anthropic import Anthropic",
    16→          "from anthropic import AsyncAnthropic"
    17→        ],
    18→        "initialization": "client = Anthropic()  # Uses ANTHROPIC_API_KEY env var",
    19→        "key_functions": [
    20→          "client.messages.create(model, messages, max_tokens)",
    21→          "await async_client.messages.create(...)"
    22→        ],
    23→        "verified_against": "PyPI + GitHub anthropics/anthropic-sdk-python"
    24→      },
    25→      "configuration": {
    26→        "env_vars": ["ANTHROPIC_API_KEY"],
    27→        "config_files": [],
    28→        "dependencies": ["httpx"]
    29→      },
    30→      "extras": {
    31→        "bedrock": "pip install anthropic[bedrock]",
    32→        "vertex": "pip install anthropic[vertex]"
    33→      },
    34→      "gotchas": [
    35→        "Supports both sync and async clients via Anthropic() and AsyncAnthropic()",
    36→        "Context manager support for automatic HTTP client cleanup",
    37→        "Type definitions for all request/response fields"
    38→      ],
    39→      "research_sources": [
    40→        "https://pypi.org/project/anthropic/",
    41→        "https://github.com/anthropics/anthropic-sdk-python",
    42→        "https://platform.claude.com/docs/en/api/client-sdks"
    43→      ]
    44→    },
    45→    {
    46→      "name": "Google Gemini SDK",
    47→      "type": "library",
    48→      "verified_package": {
    49→        "name": "google-genai",
    50→        "install_command": "pip install google-genai",
    51→        "version": "GA (May 2025)",
    52→        "verified": true
    53→      },
    54→      "api_patterns": {
    55→        "imports": [
    56→          "from google import genai"
    57→        ],
    58→        "initialization": "client = genai.Client(api_key='GEMINI_API_KEY')  # or uses GEMINI_API_KEY env var",
    59→        "key_functions": [
    60→          "client.models.generate_content(model, contents)",
    61→          "client.models.generate_content_stream(...)"
    62→        ],
    63→        "verified_against": "Google AI for Developers docs"
    64→      },
    65→      "configuration": {
    66→        "env_vars": ["GEMINI_API_KEY"],
    67→        "config_files": [],
    68→        "dependencies": []
    69→      },
    70→      "extras": {
    71→        "async": "pip install google-genai[aiohttp]"
    72→      },
    73→      "gotchas": [
    74→        "CRITICAL: google-generativeai package is DEPRECATED (EOL Nov 30, 2025)",
    75→        "Must use new google-genai package for all new development",
    76→        "Supports both Gemini Developer API and Vertex AI APIs",
    77→        "LLMs may generate code for deprecated library - always use google-genai"
    78→      ],
    79→      "research_sources": [
    80→        "https://pypi.org/project/google-generativeai/",
    81→        "https://ai.google.dev/gemini-api/docs/libraries",
    82→        "https://github.com/googleapis/python-genai"
    83→      ]
    84→    },
    85→    {
    86→      "name": "xAI Grok SDK",
    87→      "type": "library",
    88→      "verified_package": {
    89→        "name": "xai-sdk",
    90→        "install_command": "pip install xai-sdk",
    91→        "version": "latest",
    92→        "python_requires": ">=3.10",
    93→        "verified": true
    94→      },
    95→      "api_patterns": {
    96→        "imports": [
    97→          "from xai_sdk import Client",
    98→          "from xai_sdk import AsyncClient"
    99→        ],
   100→        "initialization": "client = Client()  # Uses XAI_API_KEY env var",
   101→        "key_functions": [
   102→          "client.chat(...)",
   103→          "client.generate(...)",
   104→          "await async_client.chat(...)"
   105→        ],
   106→        "verified_against": "GitHub xai-org/xai-sdk-python + PyPI"
   107→      },
   108→      "configuration": {
   109→        "env_vars": ["XAI_API_KEY"],
   110→        "config_files": [],
   111→        "base_url": "https://api.x.ai/v1"
   112→      },
   113→      "extras": {
   114→        "telemetry_http": "pip install xai-sdk[telemetry-http]",
   115→        "telemetry_grpc": "pip install xai-sdk[telemetry-grpc]"
   116→      },
   117→      "gotchas": [
   118→        "gRPC-based Python library",
   119→        "Supports both sync and async clients",
   120→        "Agentic tool calling with web search, X search, and code execution",
   121→        "Multiple community SDKs exist (xai-grok, xai-grok-sdk) - use official xai-sdk"
   122→      ],
   123→      "research_sources": [
   124→        "https://github.com/xai-org/xai-sdk-python",
   125→        "https://pypi.org/project/xai-sdk/",
   126→        "https://docs.x.ai/docs/tutorial"
   127→      ]
   128→    },
   129→    {
   130→      "name": "Ollama Python",
   131→      "type": "library",
   132→      "verified_package": {
   133→        "name": "ollama",
   134→        "install_command": "pip install ollama",
   135→        "version": "latest (Nov 2025)",
   136→        "python_requires": ">=3.8",
   137→        "verified": true
   138→      },
   139→      "api_patterns": {
   140→        "imports": [
   141→          "import ollama",
   142→          "from ollama import Client",
   143→          "from ollama import AsyncClient"
   144→        ],
   145→        "initialization": "client = Client(host='http://localhost:11434')",
   146→        "key_functions": [
   147→          "ollama.chat(model, messages)",
   148→          "ollama.generate(model, prompt)",
   149→          "await AsyncClient().chat(model, messages, stream=True)"
   150→        ],
   151→        "verified_against": "GitHub ollama/ollama-python"
   152→      },
   153→      "configuration": {
   154→        "env_vars": [],
   155→        "config_files": [],
   156→        "host": "http://localhost:11434 (default)"
   157→      },
   158→      "infrastructure": {
   159→        "requires_docker": false,
   160→        "requires_ollama_server": true,
   161→        "install_ollama": "https://ollama.com/download"
   162→      },
   163→      "gotchas": [
   164→        "Ollama server must be running separately before using Python client",
   165→        "Pull models first with 'ollama pull <model>' e.g., 'ollama pull gemma3'",
   166→        "Supports streaming with stream=True parameter",
   167→        "Custom client with headers: Client(host=..., headers={...})",
   168→        "Now supports streaming with MCP tool calling"
   169→      ],
   170→      "research_sources": [
   171→        "https://github.com/ollama/ollama-python",
   172→        "https://pypi.org/project/ollama/",
   173→        "https://ollama.com/blog/streaming-tool"
   174→      ]
   175→    },
   176→    {
   177→      "name": "FastAPI",
   178→      "type": "framework",
   179→      "verified_package": {
   180→        "name": "fastapi",
   181→        "install_command": "pip install \"fastapi[standard]\"",
   182→        "version": "0.115.0+",
   183→        "verified": true
   184→      },
   185→      "api_patterns": {
   186→        "imports": [
   187→          "from fastapi import FastAPI",
   188→          "from fastapi import Depends, HTTPException",
   189→          "from pydantic import BaseModel"
   190→        ],
   191→        "initialization": "app = FastAPI()",
   192→        "key_functions": [
   193→          "@app.get('/path')",
   194→          "@app.post('/path')",
   195→          "async def endpoint(): ...",
   196→          "Depends() for dependency injection"
   197→        ],
   198→        "verified_against": "Official FastAPI docs"
   199→      },
   200→      "configuration": {
   201→        "env_vars": [],
   202→        "config_files": [],
   203→        "dependencies": ["uvicorn", "pydantic", "starlette"]
   204→      },
   205→      "infrastructure": {
   206→        "run_command": "uvicorn main:app --reload",
   207→        "default_port": 8000
   208→      },
   209→      "gotchas": [
   210→        "Use fastapi[standard] to get uvicorn and other standard dependencies",
   211→        "ASGI server (uvicorn) required to run the app",
   212→        "Built on Starlette (web) + Pydantic (data validation)",
   213→        "Automatic OpenAPI/Swagger docs at /docs and /redoc",
   214→        "--reload flag for development only"
   215→      ],
   216→      "research_sources": [
   217→        "https://pypi.org/project/fastapi/",
   218→        "https://fastapi.tiangolo.com/",
   219→        "https://fastapi.tiangolo.com/tutorial/"
   220→      ]
   221→    },
   222→    {
   223→      "name": "React with TypeScript (Vite)",
   224→      "type": "framework",
   225→      "verified_package": {
   226→        "name": "vite + react + typescript",
   227→        "install_command": "npm create vite@latest my-app -- --template react-ts",
   228→        "version": "Vite 6.3.2+ (latest)",
   229→        "node_requires": ">=18",
   230→        "verified": true
   231→      },
   232→      "api_patterns": {
   233→        "imports": [
   234→          "import React from 'react'",
   235→          "import { useState, useEffect } from 'react'"
   236→        ],
   237→        "project_structure": "index.html at root, src/ with main.tsx entry",
   238→        "key_features": [
   239→          "Hot Module Replacement (HMR)",
   240→          "Native ES modules in development",
   241→          "TypeScript support out of box"
   242→        ],
   243→        "verified_against": "Vite official guide"
   244→      },
   245→      "configuration": {
   246→        "config_files": ["vite.config.ts", "tsconfig.json"],
   247→        "commands": {
   248→          "dev": "npm run dev",
   249→          "build": "npm run build",
   250→          "preview": "npm run preview"
   251→        }
   252→      },
   253→      "infrastructure": {
   254→        "dev_server": "http://localhost:5173",
   255→        "build_output": "dist/"
   256→      },
   257→      "gotchas": [
   258→        "Node.js >= v18 required",
   259→        "Available templates: react-ts, react-swc-ts (faster builds)",
   260→        "For testing: npm install -D vitest @testing-library/react",
   261→        "HMR provides instant updates without page refresh"
   262→      ],
   263→      "research_sources": [
   264→        "https://vite.dev/guide/",
   265→        "https://blog.logrocket.com/how-to-build-react-typescript-app-vite/"
   266→      ]
   267→    },
   268→    {
   269→      "name": "MCP Python SDK",
   270→      "type": "library",
   271→      "verified_package": {
   272→        "name": "mcp",
   273→        "install_command": "pip install mcp",
   274→        "version": "1.25.0+ (v2 coming Q1)",
   275→        "python_requires": ">=3.10",
   276→        "verified": true
   277→      },
   278→      "api_patterns": {
   279→        "imports": [
   280→          "from mcp.server.fastmcp import FastMCP",
   281→          "from mcp.client import Client"
   282→        ],
   283→        "initialization": "mcp = FastMCP('server-name')",
   284→        "key_concepts": [
   285→          "Resources - like GET endpoints for data",
   286→          "Tools - like POST endpoints for actions",
   287→          "Prompts - reusable templates for LLM interactions"
   288→        ],
   289→        "verified_against": "GitHub modelcontextprotocol/python-sdk"
   290→      },
   291→      "configuration": {
   292→        "env_vars": [],
   293→        "config_files": [],
   294→        "transport_options": ["stdio", "SSE", "Streamable HTTP", "WebSocket"]
   295→      },
   296→      "extras": {
   297→        "cli": "pip install mcp[cli]",
   298→        "rich": "pip install mcp[rich]",
   299→        "websocket": "pip install mcp[ws]"
   300→      },
   301→      "gotchas": [
   302→        "MCP is authored by Anthropic",
   303→        "v2 planned for Q1 - pin to mcp>=1.25,<2 for stability",
   304→        "Separates context provision from LLM interaction",
   305→        "FastMCP provides high-level server abstraction"
   306→      ],
   307→      "research_sources": [
   308→        "https://pypi.org/project/mcp/",
   309→        "https://github.com/modelcontextprotocol/python-sdk",
   310→        "https://modelcontextprotocol.io/docs/develop/build-server"
   311→      ]
   312→    },
   313→    {
   314→      "name": "GitPython",
   315→      "type": "library",
   316→      "verified_package": {
   317→        "name": "GitPython",
   318→        "install_command": "pip install GitPython",
   319→        "version": "3.1.46+",
   320→        "verified": true
   321→      },
   322→      "api_patterns": {
   323→        "imports": [
   324→          "from git import Repo"
   325→        ],
   326→        "initialization": "repo = Repo('/path/to/repo')  # or Repo.init('/path')",
   327→        "key_functions": [
   328→          "Repo.init(path)",
   329→          "Repo.clone_from(url, path)",
   330→          "repo.create_head(branch_name)",
   331→          "repo.index.add(files)",
   332→          "repo.index.commit(message)",
   333→          "repo.git.push()",
   334→          "repo.is_dirty()"
   335→        ],
   336→        "verified_against": "GitPython documentation"
   337→      },
   338→      "configuration": {
   339→        "env_vars": [],
   340→        "requires": "Git must be installed on system"
   341→      },
   342→      "gotchas": [
   343→        "Not suited for long-running processes (daemons) - leaks system resources",
   344→        "Use as subprocess for long-running applications",
   345→        "is_dirty() checks for uncommitted changes (untracked, modified, staged)",
   346→        "Requires Git executable installed on system"
   347→      ],
   348→      "research_sources": [
   349→        "https://pypi.org/project/GitPython/",
   350→        "https://github.com/gitpython-developers/GitPython",
   351→        "https://gitpython.readthedocs.io/en/stable/"
   352→      ]
   353→    },
   354→    {
   355→      "name": "py-gitea (Gitea API Client)",
   356→      "type": "library",
   357→      "verified_package": {
   358→        "name": "py-gitea",
   359→        "install_command": "pip install py-gitea",
   360→        "version": "0.2.10 (Sep 2025)",
   361→        "python_requires": ">=3.11",
   362→        "verified": true
   363→      },
   364→      "api_patterns": {
   365→        "imports": [
   366→          "from gitea import Gitea"
   367→        ],
   368→        "initialization": "gitea = Gitea(url, token)",
   369→        "key_features": [
   370→          "Organizations management",
   371→          "Teams management",
   372→          "Repositories management",
   373→          "Users management"
   374→        ],
   375→        "verified_against": "GitHub Langenfeld/py-gitea"
   376→      },
   377→      "configuration": {
   378→        "env_vars": ["GITEA_TOKEN (recommended)"],
   379→        "requires_gitea": ">=1.16.1"
   380→      },
   381→      "alternatives": [
   382→        "py-gitea-opensuse-org (Dec 2025, auto-generated)",
   383→        "giteapy (older, Swagger-generated)"
   384→      ],
   385→      "gotchas": [
   386→        "Requires Gitea server >= 1.16.1",
   387→        "Python 3.11+ required (newer than some other packages)",
   388→        "Focused on Org/Team/Repo/User management"
   389→      ],
   390→      "research_sources": [
   391→        "https://pypi.org/project/py-gitea/",
   392→        "https://github.com/Langenfeld/py-gitea"
   393→      ]
   394→    },
   395→    {
   396→      "name": "LiteLLM (Unified LLM API)",
   397→      "type": "library",
   398→      "verified_package": {
   399→        "name": "litellm",
   400→        "install_command": "pip install litellm",
   401→        "version": "latest",
   402→        "verified": true
   403→      },
   404→      "api_patterns": {
   405→        "imports": [
   406→          "import litellm",
   407→          "from litellm import completion"
   408→        ],
   409→        "initialization": "response = completion(model='provider/model', messages=[...])",
   410→        "key_functions": [
   411→          "completion(model, messages)",
   412→          "acompletion(...) for async",
   413→          "embedding(model, input)"
   414→        ],
   415→        "verified_against": "LiteLLM documentation"
   416→      },
   417→      "configuration": {
   418→        "env_vars": [
   419→          "OPENAI_API_KEY",
   420→          "ANTHROPIC_API_KEY",
   421→          "GEMINI_API_KEY",
   422→          "Provider-specific keys"
   423→        ],
   424→        "supported_providers": [
   425→          "OpenAI", "Anthropic", "Google/Gemini", "Azure",
   426→          "AWS Bedrock", "Ollama", "Cohere", "HuggingFace",
   427→          "Groq", "VLLM", "100+ more"
   428→        ]
   429→      },
   430→      "key_features": [
   431→        "Unified interface for 100+ LLMs",
   432→        "OpenAI-compatible API format",
   433→        "Cost tracking and budgeting",
   434→        "Automatic retries and fallbacks",
   435→        "Load balancing across providers",
   436→        "Proxy server mode for gateway usage"
   437→      ],
   438→      "gotchas": [
   439→        "HIGHLY RECOMMENDED for multi-provider projects",
   440→        "Can use as SDK or Proxy Server (AI Gateway)",
   441→        "Mimics OpenAI API structure - write once, swap models",
   442→        "Enterprise adoption: Netflix, Lemonade, RocketMoney",
   443→        "470k+ downloads, 28k+ GitHub stars",
   444→        "Can combine with OpenRouter for even more models"
   445→      ],
   446→      "research_sources": [
   447→        "https://docs.litellm.ai/docs/",
   448→        "https://github.com/BerriAI/litellm",
   449→        "https://docs.litellm.ai/docs/providers"
   450→      ]
   451→    }
   452→  ],
   453→  "unverified_claims": [
   454→    {
   455→      "claim": "Cross-model validation quality improvements",
   456→      "reason": "This is an architectural pattern, not a package - implementation approach needs to be designed",
   457→      "risk_level": "low"
   458→    },
   459→    {
   460→      "claim": "Cost optimization through intelligent routing",
   461→      "reason": "Implementation depends on model pricing APIs and usage tracking - LiteLLM provides cost tracking support",
   462→      "risk_level": "low"
   463→    }
   464→  ],
   465→  "recommendations": [
   466→    {
   467→      "topic": "Unified LLM Interface",
   468→      "recommendation": "Use LiteLLM as the unified API wrapper instead of managing individual SDKs directly",
   469→      "rationale": "LiteLLM provides a single interface for 100+ models with automatic fallbacks, cost tracking, and load balancing - exactly what the multi-provider requirements need"
   470→    },
   471→    {
   472→      "topic": "Google Gemini",
   473→      "recommendation": "Use google-genai package, NOT google-generativeai",
   474→      "rationale": "google-generativeai was deprecated on Nov 30, 2025 - all new code must use google-genai"
   475→    },
   476→    {
   477→      "topic": "xAI Grok",
   478→      "recommendation": "Use official xai-sdk package, not community alternatives",
   479→      "rationale": "Multiple community packages exist (xai-grok, xai-grok-sdk) but official xai-sdk is most reliable"
   480→    },
   481→    {
   482→      "topic": "Git Integration",
   483→      "recommendation": "Use GitPython for programmatic Git, but avoid in long-running daemon processes",
   484→      "rationale": "GitPython has known resource leak issues in long-running processes - factor out to subprocess for daemons"
   485→    },
   486→    {
   487→      "topic": "Gitea API",
   488→      "recommendation": "Use py-gitea (v0.2.10) - most recently maintained",
   489→      "rationale": "Requires Python 3.11+ and Gitea 1.16.1+ - verify compatibility with other package requirements"
   490→    },
   491→    {
   492→      "topic": "Python Version",
   493→      "recommendation": "Use Python 3.11+ for maximum compatibility",
   494→      "rationale": "py-gitea requires 3.11+, xai-sdk requires 3.10+, MCP requires 3.10+ - 3.11 satisfies all"
   495→    },
   496→    {
   497→      "topic": "MCP Version",
   498→      "recommendation": "Pin MCP to mcp>=1.25,<2 for stability",
   499→      "rationale": "MCP v2 is planned for Q1 - pinning prevents breaking changes"
   500→    }
   501→  ],
   502→  "context7_libraries_found": [
   503→    "/anthropics/anthropic-sdk-python",
   504→    "/websites/fastapi_tiangolo",
   505→    "/ollama/ollama-python",
   506→    "/websites/ai_google_dev_gemini-api",
   507→    "/websites/typescriptlang",
   508→    "/modelcontextprotocol/python-sdk",
   509→    "/websites/x_ai"
   510→  ],
   511→  "python_requirements_summary": {
   512→    "minimum_python": "3.11",
   513→    "core_packages": [
   514→      "fastapi[standard]",
   515→      "uvicorn",
   516→      "pydantic",
   517→      "litellm",
   518→      "anthropic",
   519→      "google-genai",
   520→      "xai-sdk",
   521→      "ollama",
   522→      "mcp>=1.25,<2",
   523→      "GitPython",
   524→      "py-gitea"
   525→    ],
   526→    "optional_packages": [
   527→      "anthropic[bedrock]",
   528→      "anthropic[vertex]",
   529→      "google-genai[aiohttp]",
   530→      "xai-sdk[telemetry-http]",
   531→      "mcp[cli]"
   532→    ]
   533→  },
   534→  "frontend_requirements_summary": {
   535→    "node_minimum": "18",
   536→    "scaffold_command": "npm create vite@latest -- --template react-ts",
   537→    "dev_command": "npm run dev",
   538→    "build_command": "npm run build",
   539→    "test_packages": [
   540→      "vitest",
   541→      "@testing-library/react",
   542→      "@testing-library/jest-dom"
   543→    ]
   544→  },
   545→  "infrastructure_requirements": {
   546→    "ollama": {
   547→      "required": true,
   548→      "install": "https://ollama.com/download",
   549→      "note": "Ollama server must be running for local LLM inference"
   550→    },
   551→    "gitea": {
   552→      "optional": true,
   553→      "note": "Only if using Gitea for version control (alternative to GitHub)"
   554→    },
   555→    "database": {
   556→      "required": true,
   557→      "recommendation": "PostgreSQL or SQLite for state/spec storage",
   558→      "note": "Not specified in requirements - needs architectural decision"
   559→    }
   560→  },
   561→  "created_at": "2026-01-12T00:00:00Z"
   562→}
   563→

<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>

Anthropic Claude SDK

from anthropic import Anthropic
from anthropic import AsyncAnthropic

PyPI + GitHub anthropics/anthropic-sdk-python

xAI Grok SDK

from xai_sdk import Client
from xai_sdk import AsyncClient

client = Client()  # Uses XAI_API_KEY env var

Ollama Python

import ollama
from ollama import Client
from ollama import AsyncClient

Supports streaming with stream=True parameter

Now supports streaming with MCP tool calling

FastAPI

from fastapi import Depends, HTTPException

ASGI server (uvicorn) required to run the app

React with TypeScript (Vite)

vite + react + typescript

import { useState, useEffect } from 'react'

index.html at root, src/ with main.tsx entry

Hot Module Replacement (HMR)
Native ES modules in development
TypeScript support out of box

MCP Python SDK

from mcp.server.fastmcp import FastMCP
from mcp.client import Client

FastMCP provides high-level server abstraction

GitPython

Requires Git executable installed on system

py-gitea (Gitea API Client)

Organizations management
Teams management
Repositories management
Users management

Focused on Org/Team/Repo/User management

LiteLLM (Unified LLM API)

import litellm
from litellm import completion

completion(model, messages)
acompletion(...) for async
embedding(model, input)

OpenAI
Anthropic
Google/Gemini
Azure
AWS Bedrock
Ollama
Cohere
HuggingFace
Groq
VLLM
100+ more

Unified interface for 100+ LLMs
OpenAI-compatible API format
Cost tracking and budgeting
Automatic retries and fallbacks
Load balancing across providers
Proxy server mode for gateway usage

HIGHLY RECOMMENDED for multi-provider projects

Can use as SDK or Proxy Server (AI Gateway)

Cross-model validation quality improvements

Cost optimization through intelligent routing

Use Python 3.11+ for maximum compatibility

fastapi[standard] uvicorn pydantic litellm anthropic google-genai xai-sdk ollama mcp>=1.25,<2 GitPython py-gitea

anthropic[bedrock] anthropic[vertex] google-genai[aiohttp] xai-sdk[telemetry-http] mcp[cli]

npm create vite@latest -- --template react-ts

PostgreSQL or SQLite for state/spec storage