## YOUR ROLE - SPEC WRITER AGENT

You are the **Spec Writer Agent** in the Auto-Build spec creation pipeline. Your ONLY job is to read the gathered context and write a complete, valid `spec.md` document.

**Key Principle**: Synthesize context into actionable spec. No user interaction needed.

---

## YOUR CONTRACT

**Inputs** (read these files):
- `project_index.json` - Project structure
- `requirements.json` - User requirements
- `context.json` - Relevant files discovered

**Output**: `spec.md` - Complete specification document

You MUST create `spec.md` with ALL required sections (see template below).

**DO NOT** interact with the user. You have all the context you need.

---

## PHASE 0: LOAD ALL CONTEXT (MANDATORY)

```bash
# Read all input files
cat project_index.json
cat requirements.json
cat context.json
```

Extract from these files:
- **From project_index.json**: Services, tech stacks, ports, run commands
- **From requirements.json**: Task description, workflow type, services, acceptance criteria
- **From context.json**: Files to modify, files to reference, patterns

---

## PHASE 1: ANALYZE CONTEXT

Before writing, think about:

### 1.1: Implementation Strategy
- What's the optimal order of implementation?
- Which service should be built first?
- What are the dependencies between services?

### 1.2: Risk Assessment
- What could go wrong?
- What edge cases exist?
- Any security considerations?

### 1.3: Pattern Synthesis
- What patterns from reference files apply?
- What utilities can be reused?
- What's the code style?

---

## PHASE 2: WRITE SPEC.MD (MANDATORY)

Create `spec.md` using this EXACT template structure:

```bash
cat > spec.md << 'SPEC_EOF'
# Specification: [Task Name from requirements.json]

## Overview

[One paragraph: What is being built and why. Synthesize from requirements.json task_description]

## Workflow Type

**Type**: [from requirements.json: feature|refactor|investigation|migration|simple]

**Rationale**: [Why this workflow type fits the task]

## Task Scope

### Services Involved
- **[service-name]** (primary) - [role from context analysis]
- **[service-name]** (integration) - [role from context analysis]

### This Task Will:
- [ ] [Specific change 1 - from requirements]
- [ ] [Specific change 2 - from requirements]
- [ ] [Specific change 3 - from requirements]

### Out of Scope:
- [What this task does NOT include]

## Service Context

### [Primary Service Name]

**Tech Stack:**
- Language: [from project_index.json]
- Framework: [from project_index.json]
- Key directories: [from project_index.json]

**Entry Point:** `[path from project_index]`

**How to Run:**
```bash
[command from project_index.json]
```

**Port:** [port from project_index.json]

[Repeat for each involved service]

## Files to Modify

| File | Service | What to Change |
|------|---------|---------------|
| `[path from context.json]` | [service] | [specific change needed] |

## Files to Reference

These files show patterns to follow:

| File | Pattern to Copy |
|------|----------------|
| `[path from context.json]` | [what pattern this demonstrates] |

## Patterns to Follow

### [Pattern Name]

From `[reference file path]`:

```[language]
[code snippet if available from context, otherwise describe pattern]
```

**Key Points:**
- [What to notice about this pattern]
- [What to replicate]

## Requirements

### Functional Requirements

1. **[Requirement Name from requirements.json]**
   - Description: [What it does]
   - Acceptance: [How to verify - from acceptance_criteria]

2. **[Requirement Name]**
   - Description: [What it does]
   - Acceptance: [How to verify]

### Edge Cases

1. **[Edge Case]** - [How to handle it]
2. **[Edge Case]** - [How to handle it]

## Implementation Notes

### DO
- Follow the pattern in `[file]` for [thing]
- Reuse `[utility/component]` for [purpose]
- [Specific guidance based on context]

### DON'T
- Create new [thing] when [existing thing] works
- [Anti-pattern to avoid based on context]

## Development Environment

### Start Services

```bash
[commands from project_index.json]
```

### Service URLs
- [Service Name]: http://localhost:[port]

### Required Environment Variables
- `VAR_NAME`: [from project_index or .env.example]

## Success Criteria

The task is complete when:

1. [ ] [From requirements.json acceptance_criteria]
2. [ ] [From requirements.json acceptance_criteria]
3. [ ] No console errors
4. [ ] Existing tests still pass
5. [ ] New functionality verified via browser/API

## QA Acceptance Criteria

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

### Unit Tests
| Test | File | What to Verify |
|------|------|----------------|
| [Test Name] | `[path/to/test]` | [What this test should verify] |

### Integration Tests
| Test | Services | What to Verify |
|------|----------|----------------|
| [Test Name] | [service-a ↔ service-b] | [API contract, data flow] |

### End-to-End Tests
| Flow | Steps | Expected Outcome |
|------|-------|------------------|
| [User Flow] | 1. [Step] 2. [Step] | [Expected result] |

### Browser Verification (if frontend)
| Page/Component | URL | Checks |
|----------------|-----|--------|
| [Component] | `http://localhost:[port]/[path]` | [What to verify] |

### Database Verification (if applicable)
| Check | Query/Command | Expected |
|-------|---------------|----------|
| [Migration exists] | `[command]` | [Expected output] |

### QA Sign-off Requirements
- [ ] All unit tests pass
- [ ] All integration tests pass
- [ ] All E2E tests pass
- [ ] Browser verification complete (if applicable)
- [ ] Database state verified (if applicable)
- [ ] No regressions in existing functionality
- [ ] Code follows established patterns
- [ ] No security vulnerabilities introduced

SPEC_EOF
```

---

## PHASE 3: VERIFY SPEC

After creating, verify the spec has all required sections:

```bash
# Check required sections exist
grep -E "^##? Overview" spec.md && echo "✓ Overview"
grep -E "^##? Workflow Type" spec.md && echo "✓ Workflow Type"
grep -E "^##? Task Scope" spec.md && echo "✓ Task Scope"
grep -E "^##? Success Criteria" spec.md && echo "✓ Success Criteria"

# Check file length (should be substantial)
wc -l spec.md
```

If any section is missing, add it immediately.

---

## PHASE 4: SIGNAL COMPLETION

```
=== SPEC DOCUMENT CREATED ===

File: spec.md
Sections: [list of sections]
Length: [line count] lines

Required sections: ✓ All present

Next phase: Implementation Planning
```

---

## CRITICAL RULES

1. **ALWAYS create spec.md** - The orchestrator checks for this file
2. **Include ALL required sections** - Overview, Workflow Type, Task Scope, Success Criteria
3. **Use information from input files** - Don't make up data
4. **Be specific about files** - Use exact paths from context.json
5. **Include QA criteria** - The QA agent needs this for validation

---

## COMMON ISSUES TO AVOID

1. **Missing sections** - Every required section must exist
2. **Empty tables** - Fill in tables with data from context
3. **Generic content** - Be specific to this project and task
4. **Invalid markdown** - Check table formatting, code blocks
5. **Too short** - Spec should be comprehensive (500+ chars)

---

## ERROR RECOVERY

If spec.md is invalid or incomplete:

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

# Identify what's missing
grep -E "^##" spec.md  # See what sections exist

# Append missing sections or rewrite
cat >> spec.md << 'EOF'
## [Missing Section]

[Content]
EOF

# Or rewrite entirely if needed
cat > spec.md << 'EOF'
[Complete spec]
EOF
```

---

## BEGIN

Start by reading all input files (project_index.json, requirements.json, context.json), then write the complete spec.md.

---

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


Let me start by reading all the input files to gather the complete context for writing the spec.md document.

I'll read all the input files to gather the complete context for writing the spec.md document.


     1→{
     2→  "project_root": "C:\\Users\\MikeSwanson\\claude-projects\\ACPlus\\auto-claude-plus",
     3→  "project_type": "single",
     4→  "services": {},
     5→  "infrastructure": {},
     6→  "conventions": {}
     7→}

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


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

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

Multi-LLM Agentic Development Platform

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

  Core Features

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

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

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

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

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

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

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

  Technical Architecture

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

  Key Differentiators

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

  Use Cases

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

  Success Criteria

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


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

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


Now I have all the context. Let me analyze:

1. **From project_index.json**: This is a new project with no existing services defined - it's essentially empty/starting fresh.

2. **From requirements.json**: Full task description for a multi-LLM agentic development platform with:
   - Multi-LLM Provider Support (Claude, Gemini, Grok, Ollama)
   - Version Control Integration (Git/Gitea)
   - Adaptive Spec System
   - Agent Skill System
   - Project Steering & Course Correction
   - Intelligent Orchestration
   - Quality Assurance
   - Tech: Python/FastAPI backend, React/TypeScript frontend, MCP Server

3. **From context.json**: Same task description, but with empty arrays for scoped_services, files_to_modify, files_to_reference - this is a greenfield project.

4. **From the context provided in the system prompt**: Additional details about:
   - Research findings (verified packages, API patterns)
   - Key technical decisions and constraints

Now I need to write a comprehensive spec.md for this greenfield project. Since there are no existing files to reference or modify, I'll focus on what needs to be created from scratch.

Let me write the spec.md now.

Now let me also check the current project structure to understand what exists already:


This is a greenfield project - just git and the spec infrastructure is in place. Let me also read the research.json and complexity_assessment.json for more context:

Let me also read the research.json and complexity_assessment.json for additional context:


     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


     1→{
     2→  "complexity": "complex",
     3→  "workflow_type": "feature",
     4→  "confidence": 0.95,
     5→  "reasoning": "This is a large greenfield multi-LLM platform requiring 4+ external LLM provider integrations (Claude, Gemini, Grok, Ollama), Git/Gitea integration, full-stack development (FastAPI backend + React frontend), database schema design, and new architectural patterns for multi-model orchestration. The project index shows no existing patterns to leverage - this is building from scratch.",
     6→
     7→  "analysis": {
     8→    "scope": {
     9→      "estimated_files": 75,
    10→      "estimated_services": 5,
    11→      "is_cross_cutting": true,
    12→      "notes": "Core services: orchestration layer, unified LLM wrapper, spec management, skill system, version control integration. Plus frontend components, database models, API routes, utilities, and configuration."
    13→    },
    14→    "integrations": {
    15→      "external_services": ["Claude API", "Gemini API", "Grok API", "Ollama", "Git", "Gitea"],
    16→      "new_dependencies": ["fastapi", "litellm", "sqlalchemy", "react", "typescript", "gitpython", "pydantic", "httpx"],
    17→      "research_needed": true,
    18→      "notes": "Each LLM provider has different API patterns. Multi-model orchestration and cross-validation are novel patterns requiring careful design. Git/Gitea automation needs research."
    19→    },
    20→    "infrastructure": {
    21→      "docker_changes": true,
    22→      "database_changes": true,
    23→      "config_changes": true,
    24→      "notes": "Need Docker for backend/frontend/database containerization. Database schema for specs, decisions, task history, model interactions. Multiple .env variables for API keys and model configurations."
    25→    },
    26→    "knowledge": {
    27→      "patterns_exist": false,
    28→      "research_required": true,
    29→      "unfamiliar_tech": ["multi-model orchestration", "cross-model validation", "litellm or unified LLM wrapper", "MCP server development", "adaptive spec systems"],
    30→      "notes": "Project index shows empty project - no existing codebase patterns. Multi-model orchestration is a novel architectural pattern. Need to research each provider's API, rate limits, and capabilities."
    31→    },
    32→    "risk": {
    33→      "level": "high",
    34→      "concerns": [
    35→        "API key management for 4+ providers",
    36→        "Cost control across multiple paid APIs",
    37→        "Concurrent execution and race conditions in orchestration",
    38→        "State management complexity across parallel model calls",
    39→        "Cross-model validation logic and consensus mechanisms",
    40→        "Fallback strategies when models fail",
    41→        "Security of credential storage",
    42→        "Performance optimization for parallel API calls"
    43→      ],
    44→      "notes": "Complex distributed system with multiple external dependencies. Need careful error handling, retry logic, and graceful degradation."
    45→    }
    46→  },
    47→
    48→  "recommended_phases": [
    49→    "discovery",
    50→    "requirements",
    51→    "research",
    52→    "context",
    53→    "spec_writing",
    54→    "self_critique",
    55→    "planning",
    56→    "validation"
    57→  ],
    58→
    59→  "flags": {
    60→    "needs_research": true,
    61→    "needs_self_critique": true,
    62→    "needs_infrastructure_setup": true
    63→  },
    64→
    65→  "validation_recommendations": {
    66→    "risk_level": "high",
    67→    "skip_validation": false,
    68→    "minimal_mode": false,
    69→    "test_types_required": ["unit", "integration", "e2e"],
    70→    "security_scan_required": true,
    71→    "staging_deployment_required": false,
    72→    "reasoning": "Multi-provider API integration with credential handling requires comprehensive testing. Security scan needed for API key management and authentication flows. No staging deployment since this is greenfield - local Docker environment sufficient for initial validation."
    73→  },
    74→
    75→  "additional_notes": {
    76→    "workflow_type_clarification": "Marked as 'feature' rather than 'refactoring' because the project index shows an empty project with no existing code to refactor. This is greenfield development building new functionality from scratch, even though it's inspired by existing Autocoder 2.0/Auto-Claude concepts.",
    77→    "phased_implementation_recommended": true,
    78→    "suggested_milestones": [
    79→      "Phase 1: Core orchestration layer with single LLM provider",
    80→      "Phase 2: Add additional LLM providers with unified wrapper",
    81→      "Phase 3: Spec management and version control integration",
    82→      "Phase 4: Skill system and cross-model validation",
    83→      "Phase 5: Frontend UI and project steering",
    84→      "Phase 6: Quality assurance and production hardening"
    85→    ]
    86→  },
    87→
    88→  "created_at": "2025-01-12T12:00:00.000Z"
    89→}
    90→

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

Claude API
Gemini API
Grok API
Ollama
Git
Gitea

fastapi litellm sqlalchemy react typescript gitpython pydantic httpx

multi-model orchestration
cross-model validation
litellm or unified LLM wrapper
MCP server development
adaptive spec systems

discovery requirements research context spec_writing self_critique planning validation


Now I have comprehensive context. Let me synthesize this into a complete spec.md document. This is a greenfield project for a multi-LLM agentic development platform. I have:

1. **Project structure**: Empty project, greenfield development
2. **Requirements**: Full task description from requirements.json
3. **Research findings**: Verified packages, API patterns, gotchas
4. **Complexity assessment**: Complex, feature workflow, 75+ files, 5 services, high risk

Key information:
- Tech stack: Python 3.11+/FastAPI backend, React/TypeScript frontend
- LLM SDKs: Anthropic, Google-genai, xai-sdk, ollama
- Unified wrapper: LiteLLM recommended
- MCP: mcp>=1.25,<2
- Git: GitPython + py-gitea
- Node: 18+

I'll write a comprehensive spec.md now.

Now I have all the context. Let me write the comprehensive spec.md document:

Write

# 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