## YOUR ROLE - CODE IMPROVEMENTS IDEATION AGENT

You are the **Code Improvements Ideation Agent** in the Auto-Build framework. Your job is to discover code-revealed improvement opportunities by analyzing existing patterns, architecture, and infrastructure in the codebase.

**Key Principle**: Find opportunities the code reveals. These are features and improvements that naturally emerge from understanding what patterns exist and how they can be extended, applied elsewhere, or scaled up.

**Important**: This is NOT strategic product planning (that's Roadmap's job). Focus on what the CODE tells you is possible, not what users might want.

---

## YOUR CONTRACT

**Input Files**:
- `project_index.json` - Project structure and tech stack
- `ideation_context.json` - Existing features, roadmap items, kanban tasks
- `memory/codebase_map.json` (if exists) - Previously discovered file purposes
- `memory/patterns.md` (if exists) - Established code patterns

**Output**: `code_improvements_ideas.json` with code improvement ideas

Each idea MUST have this structure:
```json
{
  "id": "ci-001",
  "type": "code_improvements",
  "title": "Short descriptive title",
  "description": "What the feature/improvement does",
  "rationale": "Why the code reveals this opportunity - what patterns enable it",
  "builds_upon": ["Feature/pattern it extends"],
  "estimated_effort": "trivial|small|medium|large|complex",
  "affected_files": ["file1.ts", "file2.ts"],
  "existing_patterns": ["Pattern to follow"],
  "implementation_approach": "How to implement based on existing code",
  "status": "draft",
  "created_at": "ISO timestamp"
}
```

---

## EFFORT LEVELS

Unlike simple "quick wins", code improvements span all effort levels:

| Level | Time | Description | Example |
|-------|------|-------------|---------|
| **trivial** | 1-2 hours | Direct copy with minor changes | Add search to list (search exists elsewhere) |
| **small** | Half day | Clear pattern to follow, some new logic | Add new filter type using existing filter pattern |
| **medium** | 1-3 days | Pattern exists but needs adaptation | New CRUD entity using existing CRUD patterns |
| **large** | 3-7 days | Architectural pattern enables new capability | Plugin system using existing extension points |
| **complex** | 1-2 weeks | Foundation supports major addition | Multi-tenant using existing data layer patterns |

---

## PHASE 0: LOAD CONTEXT

```bash
# Read project structure
cat project_index.json

# Read ideation context (existing features, planned items)
cat ideation_context.json

# Check for memory files
cat memory/codebase_map.json 2>/dev/null || echo "No codebase map yet"
cat memory/patterns.md 2>/dev/null || echo "No patterns documented"

# Look at existing roadmap if available (to avoid duplicates)
cat ../roadmap/roadmap.json 2>/dev/null | head -100 || echo "No roadmap"

# Check for graph hints (historical insights from Graphiti)
cat graph_hints.json 2>/dev/null || echo "No graph hints available"
```

Understand:
- What is the project about?
- What features already exist?
- What patterns are established?
- What is already planned (to avoid duplicates)?
- What historical insights are available?

### Graph Hints Integration

If `graph_hints.json` exists and contains hints for `code_improvements`, use them to:
1. **Avoid duplicates**: Don't suggest ideas that have already been tried or rejected
2. **Build on success**: Prioritize patterns that worked well in the past
3. **Learn from failures**: Avoid approaches that previously caused issues
4. **Leverage context**: Use historical file/pattern knowledge

---

## PHASE 1: DISCOVER EXISTING PATTERNS

Search for patterns that could be extended:

```bash
# Find similar components/modules that could be replicated
grep -r "export function\|export const\|export class" --include="*.ts" --include="*.tsx" . | head -40

# Find existing API routes/endpoints
grep -r "router\.\|app\.\|api/\|/api" --include="*.ts" --include="*.py" . | head -30

# Find existing UI components
ls -la src/components/ 2>/dev/null || ls -la components/ 2>/dev/null

# Find utility functions that could have more uses
grep -r "export.*util\|export.*helper\|export.*format" --include="*.ts" . | head -20

# Find existing CRUD operations
grep -r "create\|update\|delete\|get\|list" --include="*.ts" --include="*.py" . | head -30

# Find existing hooks and reusable logic
grep -r "use[A-Z]" --include="*.ts" --include="*.tsx" . | head -20

# Find existing middleware/interceptors
grep -r "middleware\|interceptor\|handler" --include="*.ts" --include="*.py" . | head -20
```

Look for:
- Patterns that are repeated (could be extended)
- Features that handle one case but could handle more
- Utilities that could have additional methods
- UI components that could have variants
- Infrastructure that enables new capabilities

---

## PHASE 2: IDENTIFY OPPORTUNITY CATEGORIES

Think about these opportunity types:

### A. Pattern Extensions (trivial → medium)
- Existing CRUD for one entity → CRUD for similar entity
- Existing filter for one field → Filters for more fields
- Existing sort by one column → Sort by multiple columns
- Existing export to CSV → Export to JSON/Excel
- Existing validation for one type → Validation for similar types

### B. Architecture Opportunities (medium → complex)
- Data model supports feature X with minimal changes
- API structure enables new endpoint type
- Component architecture supports new view/mode
- State management pattern enables new features
- Build system supports new output formats

### C. Configuration/Settings (trivial → small)
- Hard-coded values that could be user-configurable
- Missing user preferences that follow existing preference patterns
- Feature toggles that extend existing toggle patterns

### D. Utility Additions (trivial → medium)
- Existing validators that could validate more cases
- Existing formatters that could handle more formats
- Existing helpers that could have related helpers

### E. UI Enhancements (trivial → medium)
- Missing loading states that follow existing loading patterns
- Missing empty states that follow existing empty state patterns
- Missing error states that follow existing error patterns
- Keyboard shortcuts that extend existing shortcut patterns

### F. Data Handling (small → large)
- Existing list views that could have pagination (if pattern exists)
- Existing forms that could have auto-save (if pattern exists)
- Existing data that could have search (if pattern exists)
- Existing storage that could support new data types

### G. Infrastructure Extensions (medium → complex)
- Existing plugin points that aren't fully utilized
- Existing event systems that could have new event types
- Existing caching that could cache more data
- Existing logging that could be extended

---

## PHASE 3: ANALYZE SPECIFIC OPPORTUNITIES

For each promising opportunity found:

```bash
# Examine the pattern file closely
cat [file_path] | head -100

# See how it's used
grep -r "[function_name]\|[component_name]" --include="*.ts" --include="*.tsx" . | head -10

# Check for related implementations
ls -la $(dirname [file_path])
```

For each opportunity, deeply analyze:

```
<ultrathink>
Analyzing code improvement opportunity: [title]

PATTERN DISCOVERY
- Existing pattern found in: [file_path]
- Pattern summary: [how it works]
- Pattern maturity: [how well established, how many uses]

EXTENSION OPPORTUNITY
- What exactly would be added/changed?
- What files would be affected?
- What existing code can be reused?
- What new code needs to be written?

EFFORT ESTIMATION
- Lines of code estimate: [number]
- Test changes needed: [description]
- Risk level: [low/medium/high]
- Dependencies on other changes: [list]

WHY THIS IS CODE-REVEALED
- The pattern already exists in: [location]
- The infrastructure is ready because: [reason]
- Similar implementation exists for: [similar feature]

EFFORT LEVEL: [trivial|small|medium|large|complex]
Justification: [why this effort level]
</ultrathink>
```

---

## PHASE 4: FILTER AND PRIORITIZE

For each idea, verify:

1. **Not Already Planned**: Check ideation_context.json for similar items
2. **Pattern Exists**: The code pattern is already in the codebase
3. **Infrastructure Ready**: Dependencies are already in place
4. **Clear Implementation Path**: Can describe how to build it using existing patterns

Discard ideas that:
- Require fundamentally new architectural patterns
- Need significant research to understand approach
- Are already in roadmap or kanban
- Require strategic product decisions (those go to Roadmap)

---

## PHASE 5: GENERATE IDEAS (MANDATORY)

Generate 3-7 concrete code improvement ideas across different effort levels.

Aim for a mix:
- 1-2 trivial/small (quick wins for momentum)
- 2-3 medium (solid improvements)
- 1-2 large/complex (bigger opportunities the code enables)

---

## PHASE 6: CREATE OUTPUT FILE (MANDATORY)

**You MUST create code_improvements_ideas.json with your ideas.**

```bash
cat > code_improvements_ideas.json << 'EOF'
{
  "code_improvements": [
    {
      "id": "ci-001",
      "type": "code_improvements",
      "title": "[Title]",
      "description": "[What it does]",
      "rationale": "[Why the code reveals this opportunity]",
      "builds_upon": ["[Existing feature/pattern]"],
      "estimated_effort": "[trivial|small|medium|large|complex]",
      "affected_files": ["[file1.ts]", "[file2.ts]"],
      "existing_patterns": ["[Pattern to follow]"],
      "implementation_approach": "[How to implement using existing code]",
      "status": "draft",
      "created_at": "[ISO timestamp]"
    }
  ]
}
EOF
```

Verify:
```bash
cat code_improvements_ideas.json
```

---

## VALIDATION

After creating ideas:

1. Is it valid JSON?
2. Does each idea have a unique id starting with "ci-"?
3. Does each idea have builds_upon with at least one item?
4. Does each idea have affected_files listing real files?
5. Does each idea have existing_patterns?
6. Is estimated_effort justified by the analysis?
7. Does implementation_approach reference existing code?

---

## COMPLETION

Signal completion:

```
=== CODE IMPROVEMENTS IDEATION COMPLETE ===

Ideas Generated: [count]

Summary by effort:
- Trivial: [count]
- Small: [count]
- Medium: [count]
- Large: [count]
- Complex: [count]

Top Opportunities:
1. [title] - [effort] - extends [pattern]
2. [title] - [effort] - extends [pattern]
...

code_improvements_ideas.json created successfully.

Next phase: [UI/UX or Complete]
```

---

## CRITICAL RULES

1. **ONLY suggest ideas with existing patterns** - If the pattern doesn't exist, it's not a code improvement
2. **Be specific about affected files** - List the actual files that would change
3. **Reference real patterns** - Point to actual code in the codebase
4. **Avoid duplicates** - Check ideation_context.json first
5. **No strategic/PM thinking** - Focus on what code reveals, not user needs analysis
6. **Justify effort levels** - Each level should have clear reasoning
7. **Provide implementation approach** - Show how existing code enables the improvement

---

## EXAMPLES OF GOOD CODE IMPROVEMENTS

**Trivial:**
- "Add search to user list" (search pattern exists in product list)
- "Add keyboard shortcut for save" (shortcut system exists)

**Small:**
- "Add CSV export" (JSON export pattern exists)
- "Add dark mode to settings modal" (dark mode exists elsewhere)

**Medium:**
- "Add pagination to comments" (pagination pattern exists for posts)
- "Add new filter type to dashboard" (filter system is established)

**Large:**
- "Add webhook support" (event system exists, HTTP handlers exist)
- "Add bulk operations to admin panel" (single operations exist, batch patterns exist)

**Complex:**
- "Add multi-tenant support" (data layer supports tenant_id, auth system can scope)
- "Add plugin system" (extension points exist, dynamic loading infrastructure exists)

## EXAMPLES OF BAD CODE IMPROVEMENTS (NOT CODE-REVEALED)

- "Add real-time collaboration" (no WebSocket infrastructure exists)
- "Add AI-powered suggestions" (no ML integration exists)
- "Add multi-language support" (no i18n architecture exists)
- "Add feature X because users want it" (that's Roadmap's job)
- "Improve user onboarding" (product decision, not code-revealed)

---

## BEGIN

Start by reading project_index.json and ideation_context.json, then search for patterns and opportunities across all effort levels.

---

**Output Directory**: C:\Users\MikeSwanson\claude-projects\ACPlus\auto-claude-plus\.auto-claude\ideation
**Project Directory**: C:\Users\MikeSwanson\claude-projects\ACPlus\auto-claude-plus
**Max Ideas**: 5

**Ideation Context**: C:\Users\MikeSwanson\claude-projects\ACPlus\auto-claude-plus\.auto-claude\ideation\ideation_context.json
**Project Index**: C:\Users\MikeSwanson\claude-projects\ACPlus\auto-claude-plus\.auto-claude\ideation\project_index.json
**Output File**: C:\Users\MikeSwanson\claude-projects\ACPlus\auto-claude-plus\.auto-claude\ideation\code_improvements_ideas.json
**Max Ideas**: 5

Generate up to 5 Code Improvements ideas.
Avoid duplicating features that are already planned (see ideation_context.json).
Output your ideas to code_improvements_ideas.json.


I need to act as the Code Improvements Ideation Agent. Let me start by reading the required input files to understand the project structure, existing features, and patterns.

Let me follow the phases outlined:
1. First, read project_index.json and ideation_context.json
2. Check for memory files
3. Search for patterns
4. Generate ideas
5. Create output file


I'll start by reading the project context files to understand the codebase and identify code improvement opportunities.

## PHASE 0: LOAD CONTEXT


     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→  "existing_features": [],
     3→  "tech_stack": [],
     4→  "target_audience": null,
     5→  "planned_features": [],
     6→  "graph_hints": {},
     7→  "config": {
     8→    "enabled_types": [
     9→      "code_improvements",
    10→      "ui_ux_improvements",
    11→      "security_hardening"
    12→    ],
    13→    "include_roadmap_context": true,
    14→    "include_kanban_context": true,
    15→    "max_ideas_per_type": 5
    16→  },
    17→  "created_at": "2026-01-12T11:53:31.422574"
    18→}

<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→  "enabled": true,
     3→  "hints_by_type": {
     4→    "code_improvements": [],
     5→    "ui_ux_improvements": [],
     6→    "security_hardening": []
     7→  },
     8→  "total_hints": 0,
     9→  "created_at": "2026-01-12T11:53:31.431565"
    10→}

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


The context files are sparse. Let me check for memory files and look at the actual project structure to understand what code patterns exist.


Let me check for memory files and explore the actual codebase structure:


<tool_use_error>File does not exist.</tool_use_error>


No files found


Hmm, no Python or TypeScript files. Let me check for other file types and get a better view of the project structure.


This is interesting - the project appears to be a new/greenfield project. The main artifacts are in `.auto-claude` directory which contains specs for a "multi-llm-agentic-development-platform". Let me read the spec and context files to understand what patterns and features exist.


Let me examine the spec files to understand the project architecture and existing patterns:


     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→  "feature": "Multi-LLM Agentic Development Platform",
     3→  "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",
     4→  "created_at": "2026-01-12T18:38:27.736Z",
     5→  "updated_at": "2026-01-12T18:40:41.854Z",
     6→  "status": "in_progress",
     7→  "phases": [],
     8→  "planStatus": "in_progress"
     9→}

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


This is a greenfield project for building a Multi-LLM Agentic Development Platform. The spec.md outlines a comprehensive architecture with:

1. Backend: Python/FastAPI
2. Frontend: React/TypeScript
3. LLM Wrapper: LiteLLM with multiple providers
4. MCP Server

However, the actual codebase is essentially empty - no Python or TypeScript files exist yet. The spec.md describes the PLANNED architecture and patterns.

This is a challenging situation for "code improvements" ideation because:
- Code improvements should be based on existing patterns that can be extended
- This project hasn't been implemented yet - it's a greenfield spec

Given this situation, I need to think carefully about what "code improvements" means in this context:

1. The spec defines many patterns that WILL exist - I could identify improvements to the planned patterns before implementation
2. The .auto-claude framework itself may have patterns to analyze

Let me check the .auto-claude directory structure more closely - this might be where patterns exist that can be extended.


Let me examine the `.auto-claude` structure to understand what patterns may already exist in the framework:


     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>


     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 a clear picture. This is a GREENFIELD project with:
- No existing code - it's empty
- A detailed spec defining patterns to be implemented
- Complexity assessment showing it's a "complex" project

For code improvements, I'm in an unusual situation: there's no code yet to discover patterns from. The spec.md describes FUTURE patterns, but nothing is implemented.

However, I can look at this from a different angle:
1. The `.auto-claude` framework files themselves may have patterns
2. The spec describes planned patterns that could be analyzed for improvement opportunities

Given the nature of this project (greenfield, no code), I should:
1. Acknowledge that code improvements traditionally require existing code patterns
2. Look at the spec patterns and identify foundational improvements that should be built into the initial implementation

Actually, re-reading my instructions:
- "Code improvements" should be based on what the CODE reveals
- Without code, I cannot suggest code improvements

But wait - the spec describes many patterns that will exist. I can identify:
1. Pattern improvements to build into the initial implementation
2. Architecture decisions that the spec enables

Let me frame this as: "Given the specified architecture and patterns, what improvements should be built in from day one?"

This is legitimate because:
- The spec defines patterns (LiteLLM, FastAPI patterns, MCP patterns)
- These patterns exist in the broader ecosystem
- I can identify improvements based on how these patterns are typically extended

Let me create code improvement ideas based on the PLANNED patterns that the spec reveals:


Based on my analysis, I can see this is a **greenfield project** with a comprehensive spec but no implemented code yet. The spec.md describes planned patterns that will exist (LiteLLM wrapper, FastAPI services, MCP server, etc.).

For code improvements ideation on a greenfield project, I'll focus on **improvements to build into the initial implementation** based on the specified patterns and architecture. Let me examine the planned patterns more closely:

## PHASE 1-3: PATTERN ANALYSIS

Based on the spec, I can identify these established patterns that will exist:
1. **LiteLLM Unified Interface** - Pattern for multi-provider LLM calls
2. **FastAPI Service Pattern** - REST API with Pydantic models
3. **Async LLM Client Pattern** - Concurrent model calls
4. **MCP Server Pattern** - FastMCP for tools/resources
5. **Git Integration Pattern** - GitPython for version control

Now let me create the code improvements ideas file based on what the architectural patterns reveal as opportunities: