## YOUR ROLE - UI/UX IMPROVEMENTS IDEATION AGENT

You are the **UI/UX Improvements Ideation Agent** in the Auto-Build framework. Your job is to analyze the application visually (using browser automation) and identify concrete improvements to the user interface and experience.

**Key Principle**: See the app as users see it. Identify friction points, inconsistencies, and opportunities for visual polish that will improve the user experience.

---

## YOUR CONTRACT

**Input Files**:
- `project_index.json` - Project structure and tech stack
- `ideation_context.json` - Existing features, roadmap items, kanban tasks

**Tools Available**:
- Puppeteer MCP for browser automation and screenshots
- File system access for analyzing components

**Output**: Append to `ideation.json` with UI/UX improvement ideas

Each idea MUST have this structure:
```json
{
  "id": "uiux-001",
  "type": "ui_ux_improvements",
  "title": "Short descriptive title",
  "description": "What the improvement does",
  "rationale": "Why this improves UX",
  "category": "usability|accessibility|performance|visual|interaction",
  "affected_components": ["Component1.tsx", "Component2.tsx"],
  "screenshots": ["screenshot_before.png"],
  "current_state": "Description of current state",
  "proposed_change": "Specific change to make",
  "user_benefit": "How users benefit from this change",
  "status": "draft",
  "created_at": "ISO timestamp"
}
```

---

## PHASE 0: LOAD CONTEXT AND DETERMINE APP URL

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

# Read ideation context
cat ideation_context.json

# Look for dev server configuration
cat package.json 2>/dev/null | grep -A5 '"scripts"'
cat vite.config.ts 2>/dev/null | head -30
cat next.config.js 2>/dev/null | head -20

# Check for running dev server ports
lsof -i :3000 2>/dev/null | head -3
lsof -i :5173 2>/dev/null | head -3
lsof -i :8080 2>/dev/null | head -3

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

Determine:
- What type of frontend (React, Vue, vanilla, etc.)
- What URL to visit (usually localhost:3000 or :5173)
- Is the dev server running?

### Graph Hints Integration

If `graph_hints.json` exists and contains hints for your ideation type (`ui_ux_improvements`), use them to:
1. **Avoid duplicates**: Don't suggest UI improvements that have already been tried or rejected
2. **Build on success**: Prioritize UI patterns that worked well in the past
3. **Learn from failures**: Avoid design approaches that previously caused issues
4. **Leverage context**: Use historical component/design knowledge to make better suggestions

---

## PHASE 1: LAUNCH BROWSER AND CAPTURE INITIAL STATE

Use Puppeteer MCP to navigate to the application:

```
<puppeteer_navigate>
url: http://localhost:3000
wait_until: networkidle2
</puppeteer_navigate>
```

Take a screenshot of the landing page:

```
<puppeteer_screenshot>
path: ideation/screenshots/landing_page.png
full_page: true
</puppeteer_screenshot>
```

Analyze:
- Overall visual hierarchy
- Color consistency
- Typography
- Spacing and alignment
- Navigation clarity

---

## PHASE 2: EXPLORE KEY USER FLOWS

Navigate through the main user flows and capture screenshots:

### 2.1 Navigation and Layout
```
<puppeteer_screenshot>
path: ideation/screenshots/navigation.png
selector: nav, header, .sidebar
</puppeteer_screenshot>
```

Look for:
- Is navigation clear and consistent?
- Are active states visible?
- Is there a clear hierarchy?

### 2.2 Interactive Elements
Click on buttons, forms, and interactive elements:

```
<puppeteer_click>
selector: button, .btn, [type="submit"]
</puppeteer_click>

<puppeteer_screenshot>
path: ideation/screenshots/interactive_state.png
</puppeteer_screenshot>
```

Look for:
- Hover states
- Focus states
- Loading states
- Error states
- Success feedback

### 2.3 Forms and Inputs
If forms exist, analyze them:

```
<puppeteer_screenshot>
path: ideation/screenshots/forms.png
selector: form, .form-container
</puppeteer_screenshot>
```

Look for:
- Label clarity
- Placeholder text
- Validation messages
- Input spacing
- Submit button placement

### 2.4 Empty States
Check for empty state handling:

```
<puppeteer_screenshot>
path: ideation/screenshots/empty_state.png
</puppeteer_screenshot>
```

Look for:
- Helpful empty state messages
- Call to action guidance
- Visual appeal of empty states

### 2.5 Mobile Responsiveness
Resize viewport and check responsive behavior:

```
<puppeteer_set_viewport>
width: 375
height: 812
</puppeteer_set_viewport>

<puppeteer_screenshot>
path: ideation/screenshots/mobile_view.png
full_page: true
</puppeteer_screenshot>
```

Look for:
- Mobile navigation
- Touch targets (min 44x44px)
- Content reflow
- Readable text sizes

---

## PHASE 3: ACCESSIBILITY AUDIT

Check for accessibility issues:

```
<puppeteer_evaluate>
// Check for accessibility basics
const audit = {
  images_without_alt: document.querySelectorAll('img:not([alt])').length,
  buttons_without_text: document.querySelectorAll('button:empty').length,
  inputs_without_labels: document.querySelectorAll('input:not([aria-label]):not([id])').length,
  low_contrast_text: 0, // Would need more complex check
  missing_lang: !document.documentElement.lang,
  missing_title: !document.title
};
return JSON.stringify(audit);
</puppeteer_evaluate>
```

Also check:
- Color contrast ratios
- Keyboard navigation
- Screen reader compatibility
- Focus indicators

---

## PHASE 4: ANALYZE COMPONENT CONSISTENCY

Read the component files to understand patterns:

```bash
# Find UI components
ls -la src/components/ 2>/dev/null
ls -la src/components/ui/ 2>/dev/null

# Look at button variants
cat src/components/ui/button.tsx 2>/dev/null | head -50
cat src/components/Button.tsx 2>/dev/null | head -50

# Look at form components
cat src/components/ui/input.tsx 2>/dev/null | head -50

# Check for design tokens
cat src/styles/tokens.css 2>/dev/null
cat tailwind.config.js 2>/dev/null | head -50
```

Look for:
- Inconsistent styling between components
- Missing component variants
- Hardcoded values that should be tokens
- Accessibility attributes

---

## PHASE 5: IDENTIFY IMPROVEMENT OPPORTUNITIES

For each category, think deeply:

### A. Usability Issues
- Confusing navigation
- Hidden actions
- Unclear feedback
- Poor form UX
- Missing shortcuts

### B. Accessibility Issues
- Missing alt text
- Poor contrast
- Keyboard traps
- Missing ARIA labels
- Focus management

### C. Performance Perception
- Missing loading indicators
- Slow perceived response
- Layout shifts
- Missing skeleton screens
- No optimistic updates

### D. Visual Polish
- Inconsistent spacing
- Alignment issues
- Typography hierarchy
- Color inconsistencies
- Missing hover/active states

### E. Interaction Improvements
- Missing animations
- Jarring transitions
- No micro-interactions
- Missing gesture support
- Poor touch targets

---

## PHASE 6: PRIORITIZE AND DOCUMENT

For each issue found, use ultrathink to analyze:

```
<ultrathink>
UI/UX Issue Analysis: [title]

What I observed:
- [Specific observation from screenshot/analysis]

Impact on users:
- [How this affects the user experience]

Existing patterns to follow:
- [Similar component/pattern in codebase]

Proposed fix:
- [Specific change to make]
- [Files to modify]
- [Code changes needed]

Priority:
- Severity: [low/medium/high]
- Effort: [low/medium/high]
- User impact: [low/medium/high]
</ultrathink>
```

---

## PHASE 7: CREATE/UPDATE IDEATION.JSON (MANDATORY)

**You MUST create or update ideation.json with your ideas.**

```bash
# Check if file exists
if [ -f ideation.json ]; then
  cat ideation.json
fi
```

Create the UI/UX ideas structure:

```bash
cat > ui_ux_ideas.json << 'EOF'
{
  "ui_ux_improvements": [
    {
      "id": "uiux-001",
      "type": "ui_ux_improvements",
      "title": "[Title]",
      "description": "[What the improvement does]",
      "rationale": "[Why this improves UX]",
      "category": "[usability|accessibility|performance|visual|interaction]",
      "affected_components": ["[Component.tsx]"],
      "screenshots": ["[screenshot_path.png]"],
      "current_state": "[Current state description]",
      "proposed_change": "[Specific proposed change]",
      "user_benefit": "[How users benefit]",
      "status": "draft",
      "created_at": "[ISO timestamp]"
    }
  ]
}
EOF
```

Verify:
```bash
cat ui_ux_ideas.json
```

---

## VALIDATION

After creating ideas:

1. Is it valid JSON?
2. Does each idea have a unique id starting with "uiux-"?
3. Does each idea have a valid category?
4. Does each idea have affected_components with real component paths?
5. Does each idea have specific current_state and proposed_change?

---

## COMPLETION

Signal completion:

```
=== UI/UX IDEATION COMPLETE ===

Ideas Generated: [count]

Summary by Category:
- Usability: [count]
- Accessibility: [count]
- Performance: [count]
- Visual: [count]
- Interaction: [count]

Screenshots saved to: ideation/screenshots/

ui_ux_ideas.json created successfully.

Next phase: [Low-Hanging Fruit or High-Value or Complete]
```

---

## CRITICAL RULES

1. **ACTUALLY LOOK AT THE APP** - Use Puppeteer to see real UI state
2. **BE SPECIFIC** - Don't say "improve buttons", say "add hover state to primary button in Header.tsx"
3. **REFERENCE SCREENSHOTS** - Include paths to screenshots that show the issue
4. **PROPOSE CONCRETE CHANGES** - Specific CSS/component changes, not vague suggestions
5. **CONSIDER EXISTING PATTERNS** - Suggest fixes that match the existing design system
6. **PRIORITIZE USER IMPACT** - Focus on changes that meaningfully improve UX

---

## FALLBACK IF PUPPETEER UNAVAILABLE

If Puppeteer MCP is not available, analyze components statically:

```bash
# Analyze component files directly
find . -name "*.tsx" -o -name "*.jsx" | xargs grep -l "className\|style" | head -20

# Look for styling patterns
grep -r "hover:\|focus:\|active:" --include="*.tsx" . | head -30

# Check for accessibility attributes
grep -r "aria-\|role=\|tabIndex" --include="*.tsx" . | head -30

# Look for loading states
grep -r "loading\|isLoading\|pending" --include="*.tsx" . | head -20
```

Document findings based on code analysis with note that visual verification is recommended.

---

## BEGIN

Start by reading project_index.json, then launch the browser to explore the application visually.

---

**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\ui_ux_improvements_ideas.json
**Max Ideas**: 5

Generate up to 5 UI/UX Improvements ideas.
Avoid duplicating features that are already planned (see ideation_context.json).
Output your ideas to ui_ux_improvements_ideas.json.


The user wants me to act as a UI/UX Improvements Ideation Agent. I need to:

1. Read project_index.json and ideation_context.json to understand the project
2. Try to launch a browser to visually inspect the application
3. Identify UI/UX improvements
4. Output ideas to ui_ux_improvements_ideas.json

Let me start by reading the context files.


I'll analyze the application for UI/UX improvement opportunities. Let me start by reading the project context files.


     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 project context is minimal. Let me understand the project better by looking at:
1. The package.json for tech stack and scripts
2. The actual source files to understand what kind of app this is
3. Any component files


Let me understand the project structure and tech stack better:


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


No files found


No frontend framework files found. Let me check what files actually exist in the project to understand its structure.


Let me explore the project structure more broadly:


This appears to be a very early-stage project - it's basically an empty repository with just the Auto-Claude framework configuration files. There's no frontend code, no HTML, no JavaScript/TypeScript components - just configuration and spec files.

Since there's no actual frontend application to analyze visually, I need to:
1. Acknowledge that the project is in early/planning stages
2. Look at the spec file to understand what UI is planned
3. Generate UI/UX improvement ideas based on the planned application design

Let me read the spec file to understand what kind of application is being built.


I see this is an early-stage project with mostly configuration files. Let me read the spec to understand what's being built:


     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


Now I understand - this is a **greenfield project** that is still in the specification phase. There's no frontend code yet - it's planned but not implemented. The project is building a Multi-LLM Agentic Development Platform with:
- FastAPI backend
- React/TypeScript frontend (planned)
- Multiple LLM providers

Since there's no actual UI code yet, I can't visually inspect the app with Puppeteer. However, I can still generate UI/UX improvement ideas based on the spec - these would be **proactive UX recommendations** for when the frontend is built.

Let me create UI/UX improvement ideas that would be valuable for this planned frontend:
1. Dashboard design recommendations
2. LLM provider status visualization
3. Cost tracking display
4. Spec editor UX
5. Task viewer improvements

These should be concrete suggestions that would help when the frontend is implemented.


Now I understand the situation. This is a **greenfield project** still in the specification phase - the React frontend is planned but not yet implemented. Since there's no actual frontend code to visually inspect, I'll generate proactive UI/UX recommendations based on the specification that will provide value when the frontend is built.

Let me verify there are no frontend files and then create the ideation output:


Confirmed - there's no frontend code yet. I'll create proactive UI/UX recommendations for when the frontend is built. These will be concrete, actionable ideas based on the spec that will help ensure good UX from the start.

I'll focus on:
1. LLM provider status visualization with real-time indicators
2. Cost tracking dashboard with clear spending insights
3. Spec interview wizard with progressive disclosure
4. Task viewer with model routing transparency
5. Accessibility foundations for the entire UI

Let me create the ideation JSON output file.


Confirmed - the frontend is planned but not yet implemented. I'll create proactive UI/UX improvement recommendations based on the specification that will provide value when the frontend is built. Let me create the output file:


Write

{
  "ui_ux_improvements": [
    {
      "id": "uiux-001",
      "type": "ui_ux_improvements",
      "title": "Real-time LLM Provider Health Indicators",
      "description": "Implement a visual status dashboard showing real-time health and availability of all LLM providers (Claude, Gemini, Grok, Ollama) with clear visual indicators",
      "rationale": "Users need immediate visibility into which AI models are available, especially since the system routes tasks to different providers. Without clear status, users may submit tasks to unavailable providers or not understand why tasks are failing.",
      "category": "usability",
      "affected_components": ["frontend/src/components/ModelStatus.tsx", "frontend/src/pages/Dashboard.tsx"],
      "screenshots": [],
      "current_state": "Planned component ModelStatus.tsx will display provider health - needs UX specification for clear, at-a-glance status communication",
      "proposed_change": "Design ModelStatus with: (1) Color-coded status badges (green=available, yellow=degraded, red=unavailable, gray=not configured) (2) Response time indicators showing latency (3) Tooltip on hover with details like API quota remaining, last successful call (4) Automatic refresh every 30 seconds with manual refresh option (5) Accessibility: ARIA labels for screen readers announcing status changes",
      "user_benefit": "Users can instantly understand system capabilities before submitting tasks, reducing frustration from failed requests and enabling informed model selection",
      "status": "draft",
      "created_at": "2026-01-12T11:55:00.000Z"
    },
    {
      "id": "uiux-002",
      "type": "ui_ux_improvements",
      "title": "Cost Tracking Dashboard with Budget Alerts",
      "description": "Create a comprehensive cost visualization dashboard with real-time spending, per-provider breakdown, and configurable budget alerts",
      "rationale": "The spec emphasizes cost optimization as a key feature. Users need clear visibility into spending to make informed decisions about model routing and to prevent unexpected bills.",
      "category": "usability",
      "affected_components": ["frontend/src/components/CostTracker.tsx", "frontend/src/pages/Dashboard.tsx"],
      "screenshots": [],
      "current_state": "Planned CostTracker.tsx component needs detailed UX design for effective cost communication",
      "proposed_change": "Implement CostTracker with: (1) Total spend card with period selector (today/week/month) (2) Pie chart showing cost breakdown by provider (3) Bar chart showing daily/weekly cost trends (4) Table of most expensive tasks with model used (5) Budget threshold settings with visual progress bar (6) Alert banner when approaching budget limit (80%, 90%, 100%) (7) Export capability for cost reports (8) Comparison of actual vs saved costs by using local Ollama models",
      "user_benefit": "Users gain full control over API spending, can identify cost drivers, set budgets to avoid overruns, and see the concrete savings from intelligent model routing",
      "status": "draft",
      "created_at": "2026-01-12T11:55:00.000Z"
    },
    {
      "id": "uiux-003",
      "type": "ui_ux_improvements",
      "title": "Spec Interview Wizard with Progress Indicators",
      "description": "Design the spec creation interview as a multi-step wizard with clear progress, save-and-resume, and contextual help",
      "rationale": "The adaptive spec system is central to the platform. A poorly designed interview will frustrate users and result in incomplete or unclear specifications that lead to poor implementation outcomes.",
      "category": "interaction",
      "affected_components": ["frontend/src/pages/SpecEditor.tsx"],
      "screenshots": [],
      "current_state": "SpecEditor.tsx is planned but needs UX design for the interview workflow",
      "proposed_change": "Design interview wizard with: (1) Step indicator showing current position (e.g., 'Step 2 of 5: Technical Requirements') (2) Auto-save draft every 30 seconds with visual confirmation (3) 'Save and continue later' button with email reminder option (4) Contextual help tooltips explaining why each question matters (5) Rich text editor for description fields with markdown preview (6) Question branching based on previous answers (7) Summary review step before submission (8) Keyboard navigation for accessibility (Tab, Enter to proceed) (9) Mobile-responsive layout for on-the-go spec creation",
      "user_benefit": "Users can complete spec interviews without losing work, understand the purpose of each question, and feel confident their requirements are captured accurately",
      "status": "draft",
      "created_at": "2026-01-12T11:55:00.000Z"
    },
    {
      "id": "uiux-004",
      "type": "ui_ux_improvements",
      "title": "Task Viewer with Model Routing Transparency",
      "description": "Enhance TaskViewer to show which LLM was selected for each task and why, making the routing logic transparent to users",
      "rationale": "The spec highlights 'transparency' as a key differentiator - users should have 'full visibility into which models did what and why'. Without this, the multi-model system feels like a black box.",
      "category": "usability",
      "affected_components": ["frontend/src/pages/TaskViewer.tsx"],
      "screenshots": [],
      "current_state": "TaskViewer.tsx is planned but needs design for routing transparency",
      "proposed_change": "Implement transparency features: (1) Badge showing which model executed each task (2) Expandable 'Routing Decision' panel explaining why this model was chosen (e.g., 'Selected Ollama for file analysis - no API cost, sufficient capability') (3) For cross-validated tasks, show all models that participated with their verdicts (4) Cost indicator per task (5) Execution timeline showing duration (6) 'Would have cost' comparison showing what cloud-only execution would cost (7) Filter/sort by model used (8) Visual indicator when task used fallback model due to primary unavailability",
      "user_benefit": "Users understand the system's decision-making, can verify appropriate model selection, and see concrete value from intelligent routing",
      "status": "draft",
      "created_at": "2026-01-12T11:55:00.000Z"
    },
    {
      "id": "uiux-005",
      "type": "ui_ux_improvements",
      "title": "Accessibility-First Component Foundation",
      "description": "Establish accessibility standards and patterns for all UI components from the start, ensuring WCAG 2.1 AA compliance",
      "rationale": "Building accessibility in from the beginning is far easier than retrofitting. The platform will be used by developers who may have various accessibility needs, and accessible design benefits all users.",
      "category": "accessibility",
      "affected_components": ["frontend/src/components/*", "frontend/src/App.tsx"],
      "screenshots": [],
      "current_state": "No frontend code exists yet - perfect time to establish accessibility patterns",
      "proposed_change": "Establish these patterns before building: (1) Use semantic HTML elements (nav, main, aside, article) (2) Implement skip-to-content link for keyboard users (3) Ensure all interactive elements have visible focus states (4) Use ARIA labels for icon-only buttons (5) Implement role='alert' for status changes and notifications (6) Ensure color contrast ratio minimum 4.5:1 for text (7) Support prefers-reduced-motion for animations (8) Keyboard shortcuts for common actions with discoverable help (?) (9) Error messages associated with form fields via aria-describedby (10) Test with axe-core in development pipeline",
      "user_benefit": "All users can effectively use the platform regardless of abilities, reducing barriers and ensuring professional-quality UX that reflects well on the product",
      "status": "draft",
      "created_at": "2026-01-12T11:55:00.000Z"
    }
  ],
  "metadata": {
    "generated_at": "2026-01-12T11:55:00.000Z",
    "project_state": "greenfield - frontend not yet implemented",
    "analysis_method": "specification-based proactive UX recommendations",
    "notes": "These recommendations are based on the project specification since no frontend code exists yet. They provide UX patterns and best practices to implement from the start rather than retrofit later."
  }
}


File created successfully at: C:\Users\MikeSwanson\claude-projects\ACPlus\auto-claude-plus\.auto-claude\ideation\ui_ux_improvements_ideas.json

Real-time LLM Provider Health Indicators

Implement a visual status dashboard showing real-time health and availability of all LLM providers (Claude, Gemini, Grok, Ollama) with clear visual indicators

Explanation: Users need immediate visibility into which AI models are available, especially since the system routes tasks to different providers. Without clear status, users may submit tasks to unavailable providers or not understand why tasks are failing.

Planned component ModelStatus.tsx will display provider health - needs UX specification for clear, at-a-glance status communication

Design ModelStatus with: (1) Color-coded status badges (green=available, yellow=degraded, red=unavailable, gray=not configured) (2) Response time indicators showing latency (3) Tooltip on hover with details like API quota remaining, last successful call (4) Automatic refresh every 30 seconds with manual refresh option (5) Accessibility: ARIA labels for screen readers announcing status changes

Users can instantly understand system capabilities before submitting tasks, reducing frustration from failed requests and enabling informed model selection

Cost Tracking Dashboard with Budget Alerts

Create a comprehensive cost visualization dashboard with real-time spending, per-provider breakdown, and configurable budget alerts

Explanation: The spec emphasizes cost optimization as a key feature. Users need clear visibility into spending to make informed decisions about model routing and to prevent unexpected bills.

Planned CostTracker.tsx component needs detailed UX design for effective cost communication

Implement CostTracker with: (1) Total spend card with period selector (today/week/month) (2) Pie chart showing cost breakdown by provider (3) Bar chart showing daily/weekly cost trends (4) Table of most expensive tasks with model used (5) Budget threshold settings with visual progress bar (6) Alert banner when approaching budget limit (80%, 90%, 100%) (7) Export capability for cost reports (8) Comparison of actual vs saved costs by using local Ollama models

Users gain full control over API spending, can identify cost drivers, set budgets to avoid overruns, and see the concrete savings from intelligent model routing

Spec Interview Wizard with Progress Indicators

Design the spec creation interview as a multi-step wizard with clear progress, save-and-resume, and contextual help

Explanation: The adaptive spec system is central to the platform. A poorly designed interview will frustrate users and result in incomplete or unclear specifications that lead to poor implementation outcomes.

SpecEditor.tsx is planned but needs UX design for the interview workflow

Design interview wizard with: (1) Step indicator showing current position (e.g., 'Step 2 of 5: Technical Requirements') (2) Auto-save draft every 30 seconds with visual confirmation (3) 'Save and continue later' button with email reminder option (4) Contextual help tooltips explaining why each question matters (5) Rich text editor for description fields with markdown preview (6) Question branching based on previous answers (7) Summary review step before submission (8) Keyboard navigation for accessibility (Tab, Enter to proceed) (9) Mobile-responsive layout for on-the-go spec creation

Users can complete spec interviews without losing work, understand the purpose of each question, and feel confident their requirements are captured accurately

Task Viewer with Model Routing Transparency

Enhance TaskViewer to show which LLM was selected for each task and why, making the routing logic transparent to users

Explanation: The spec highlights 'transparency' as a key differentiator - users should have 'full visibility into which models did what and why'. Without this, the multi-model system feels like a black box.

TaskViewer.tsx is planned but needs design for routing transparency

Implement transparency features: (1) Badge showing which model executed each task (2) Expandable 'Routing Decision' panel explaining why this model was chosen (e.g., 'Selected Ollama for file analysis - no API cost, sufficient capability') (3) For cross-validated tasks, show all models that participated with their verdicts (4) Cost indicator per task (5) Execution timeline showing duration (6) 'Would have cost' comparison showing what cloud-only execution would cost (7) Filter/sort by model used (8) Visual indicator when task used fallback model due to primary unavailability

Users understand the system's decision-making, can verify appropriate model selection, and see concrete value from intelligent routing

Accessibility-First Component Foundation

Establish accessibility standards and patterns for all UI components from the start, ensuring WCAG 2.1 AA compliance

Explanation: Building accessibility in from the beginning is far easier than retrofitting. The platform will be used by developers who may have various accessibility needs, and accessible design benefits all users.

No frontend code exists yet - perfect time to establish accessibility patterns

Establish these patterns before building: (1) Use semantic HTML elements (nav, main, aside, article) (2) Implement skip-to-content link for keyboard users (3) Ensure all interactive elements have visible focus states (4) Use ARIA labels for icon-only buttons (5) Implement role='alert' for status changes and notifications (6) Ensure color contrast ratio minimum 4.5:1 for text (7) Support prefers-reduced-motion for animations (8) Keyboard shortcuts for common actions with discoverable help (?) (9) Error messages associated with form fields via aria-describedby (10) Test with axe-core in development pipeline

All users can effectively use the platform regardless of abilities, reducing barriers and ensuring professional-quality UX that reflects well on the product

greenfield - frontend not yet implemented

specification-based proactive UX recommendations

These recommendations are based on the project specification since no frontend code exists yet. They provide UX patterns and best practices to implement from the start rather than retrofit later.


I've successfully created the UI/UX improvements ideation file. Let me verify it was created correctly and provide a summary.


Let me verify the file was created correctly:


     1→{
     2→  "ui_ux_improvements": [
     3→    {
     4→      "id": "uiux-001",
     5→      "type": "ui_ux_improvements",
     6→      "title": "Real-time LLM Provider Health Indicators",
     7→      "description": "Implement a visual status dashboard showing real-time health and availability of all LLM providers (Claude, Gemini, Grok, Ollama) with clear visual indicators",
     8→      "rationale": "Users need immediate visibility into which AI models are available, especially since the system routes tasks to different providers. Without clear status, users may submit tasks to unavailable providers or not understand why tasks are failing.",
     9→      "category": "usability",
    10→      "affected_components": ["frontend/src/components/ModelStatus.tsx", "frontend/src/pages/Dashboard.tsx"],
    11→      "screenshots": [],
    12→      "current_state": "Planned component ModelStatus.tsx will display provider health - needs UX specification for clear, at-a-glance status communication",
    13→      "proposed_change": "Design ModelStatus with: (1) Color-coded status badges (green=available, yellow=degraded, red=unavailable, gray=not configured) (2) Response time indicators showing latency (3) Tooltip on hover with details like API quota remaining, last successful call (4) Automatic refresh every 30 seconds with manual refresh option (5) Accessibility: ARIA labels for screen readers announcing status changes",
    14→      "user_benefit": "Users can instantly understand system capabilities before submitting tasks, reducing frustration from failed requests and enabling informed model selection",
    15→      "status": "draft",
    16→      "created_at": "2026-01-12T11:55:00.000Z"
    17→    },
    18→    {
    19→      "id": "uiux-002",
    20→      "type": "ui_ux_improvements",
    21→      "title": "Cost Tracking Dashboard with Budget Alerts",
    22→      "description": "Create a comprehensive cost visualization dashboard with real-time spending, per-provider breakdown, and configurable budget alerts",
    23→      "rationale": "The spec emphasizes cost optimization as a key feature. Users need clear visibility into spending to make informed decisions about model routing and to prevent unexpected bills.",
    24→      "category": "usability",
    25→      "affected_components": ["frontend/src/components/CostTracker.tsx", "frontend/src/pages/Dashboard.tsx"],
    26→      "screenshots": [],
    27→      "current_state": "Planned CostTracker.tsx component needs detailed UX design for effective cost communication",
    28→      "proposed_change": "Implement CostTracker with: (1) Total spend card with period selector (today/week/month) (2) Pie chart showing cost breakdown by provider (3) Bar chart showing daily/weekly cost trends (4) Table of most expensive tasks with model used (5) Budget threshold settings with visual progress bar (6) Alert banner when approaching budget limit (80%, 90%, 100%) (7) Export capability for cost reports (8) Comparison of actual vs saved costs by using local Ollama models",
    29→      "user_benefit": "Users gain full control over API spending, can identify cost drivers, set budgets to avoid overruns, and see the concrete savings from intelligent model routing",
    30→      "status": "draft",
    31→      "created_at": "2026-01-12T11:55:00.000Z"
    32→    },
    33→    {
    34→      "id": "uiux-003",
    35→      "type": "ui_ux_improvements",
    36→      "title": "Spec Interview Wizard with Progress Indicators",
    37→      "description": "Design the spec creation interview as a multi-step wizard with clear progress, save-and-resume, and contextual help",
    38→      "rationale": "The adaptive spec system is central to the platform. A poorly designed interview will frustrate users and result in incomplete or unclear specifications that lead to poor implementation outcomes.",
    39→      "category": "interaction",
    40→      "affected_components": ["frontend/src/pages/SpecEditor.tsx"],
    41→      "screenshots": [],
    42→      "current_state": "SpecEditor.tsx is planned but needs UX design for the interview workflow",
    43→      "proposed_change": "Design interview wizard with: (1) Step indicator showing current position (e.g., 'Step 2 of 5: Technical Requirements') (2) Auto-save draft every 30 seconds with visual confirmation (3) 'Save and continue later' button with email reminder option (4) Contextual help tooltips explaining why each question matters (5) Rich text editor for description fields with markdown preview (6) Question branching based on previous answers (7) Summary review step before submission (8) Keyboard navigation for accessibility (Tab, Enter to proceed) (9) Mobile-responsive layout for on-the-go spec creation",
    44→      "user_benefit": "Users can complete spec interviews without losing work, understand the purpose of each question, and feel confident their requirements are captured accurately",
    45→      "status": "draft",
    46→      "created_at": "2026-01-12T11:55:00.000Z"
    47→    },
    48→    {
    49→      "id": "uiux-004",
    50→      "type": "ui_ux_improvements",
    51→      "title": "Task Viewer with Model Routing Transparency",
    52→      "description": "Enhance TaskViewer to show which LLM was selected for each task and why, making the routing logic transparent to users",
    53→      "rationale": "The spec highlights 'transparency' as a key differentiator - users should have 'full visibility into which models did what and why'. Without this, the multi-model system feels like a black box.",
    54→      "category": "usability",
    55→      "affected_components": ["frontend/src/pages/TaskViewer.tsx"],
    56→      "screenshots": [],
    57→      "current_state": "TaskViewer.tsx is planned but needs design for routing transparency",
    58→      "proposed_change": "Implement transparency features: (1) Badge showing which model executed each task (2) Expandable 'Routing Decision' panel explaining why this model was chosen (e.g., 'Selected Ollama for file analysis - no API cost, sufficient capability') (3) For cross-validated tasks, show all models that participated with their verdicts (4) Cost indicator per task (5) Execution timeline showing duration (6) 'Would have cost' comparison showing what cloud-only execution would cost (7) Filter/sort by model used (8) Visual indicator when task used fallback model due to primary unavailability",
    59→      "user_benefit": "Users understand the system's decision-making, can verify appropriate model selection, and see concrete value from intelligent routing",
    60→      "status": "draft",
    61→      "created_at": "2026-01-12T11:55:00.000Z"
    62→    },
    63→    {
    64→      "id": "uiux-005",
    65→      "type": "ui_ux_improvements",
    66→      "title": "Accessibility-First Component Foundation",
    67→      "description": "Establish accessibility standards and patterns for all UI components from the start, ensuring WCAG 2.1 AA compliance",
    68→      "rationale": "Building accessibility in from the beginning is far easier than retrofitting. The platform will be used by developers who may have various accessibility needs, and accessible design benefits all users.",
    69→      "category": "accessibility",
    70→      "affected_components": ["frontend/src/components/*", "frontend/src/App.tsx"],
    71→      "screenshots": [],
    72→      "current_state": "No frontend code exists yet - perfect time to establish accessibility patterns",
    73→      "proposed_change": "Establish these patterns before building: (1) Use semantic HTML elements (nav, main, aside, article) (2) Implement skip-to-content link for keyboard users (3) Ensure all interactive elements have visible focus states (4) Use ARIA labels for icon-only buttons (5) Implement role='alert' for status changes and notifications (6) Ensure color contrast ratio minimum 4.5:1 for text (7) Support prefers-reduced-motion for animations (8) Keyboard shortcuts for common actions with discoverable help (?) (9) Error messages associated with form fields via aria-describedby (10) Test with axe-core in development pipeline",
    74→      "user_benefit": "All users can effectively use the platform regardless of abilities, reducing barriers and ensuring professional-quality UX that reflects well on the product",
    75→      "status": "draft",
    76→      "created_at": "2026-01-12T11:55:00.000Z"
    77→    }
    78→  ],
    79→  "metadata": {
    80→    "generated_at": "2026-01-12T11:55:00.000Z",
    81→    "project_state": "greenfield - frontend not yet implemented",
    82→    "analysis_method": "specification-based proactive UX recommendations",
    83→    "notes": "These recommendations are based on the project specification since no frontend code exists yet. They provide UX patterns and best practices to implement from the start rather than retrofit later."
    84→  }
    85→}
    86→

<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 file was created successfully with valid JSON. Let me provide the completion summary.