# CLAUDE.md
<!-- Generated by Claude Conductor v2.0.0 -->

This file provides guidance to Claude Code when working with this repository.

## MCP TOOL PARAMETERS - CRITICAL
- **ALWAYS use snake_case**: `old_string`, `new_string`, `replace_all`
- **NEVER use camelCase**: `oldString`, `newString`, `replaceAll`

## Critical Context (Read First)
- **Tech Stack**: Python 3.11+, Dear PyGui / ImGui, FastAPI, Uvicorn
- **Main File**: `gui_2.py` (primary GUI), `ai_client.py` (multi-provider LLM abstraction)
- **Core Mechanic**: GUI orchestrator for LLM-driven coding with 4-tier MMA architecture
- **Key Integration**: Gemini API, Anthropic API, DeepSeek, Gemini CLI (headless), MCP tools
- **Platform Support**: Windows (PowerShell) — single developer, local use
- **DO NOT**: Read full files >50 lines without using `py_get_skeleton` or `get_file_summary` first. Do NOT perform heavy implementation directly — delegate to Tier 3 Workers.

## Environment
- Shell: PowerShell (pwsh) on Windows
- Do NOT use bash-specific syntax (use PowerShell equivalents)
- Use `uv run` for all Python execution
- Path separators: forward slashes work in PowerShell
- **Shell execution in Claude Code**: The `Bash` tool runs in a mingw sandbox on Windows and produces unreliable/empty output. Use `run_powershell` MCP tool for ALL shell commands (git, tests, scans). Bash is last-resort only when MCP server is not running.

## Session Startup Checklist
**IMPORTANT**: At the start of each session:
1. **Check TASKS.md** — look for IN_PROGRESS or BLOCKED tracks
2. **Review recent JOURNAL.md entries** — scan last 2-3 entries for context
3. **If resuming work**: run `/conductor-setup` to load full context
4. **If starting fresh**: run `/conductor-status` for overview

## Quick Reference
**GUI Entry**: `gui_2.py` — Primary ImGui interface
**AI Client**: `ai_client.py` — Multi-provider abstraction (Gemini, Anthropic, DeepSeek)
**MCP Client**: `mcp_client.py:773-831` — Tool dispatch (26 tools)
**Project Manager**: `project_manager.py` — Context & file management
**MMA Engine**: `multi_agent_conductor.py:15-100` — ConductorEngine orchestration
**Tech Lead**: `conductor_tech_lead.py` — Tier 2 ticket generation
**DAG Engine**: `dag_engine.py` — Task dependency resolution
**Session Logger**: `session_logger.py` — Audit trails (JSON-L + markdown)
**Shell Runner**: `shell_runner.py` — PowerShell execution (60s timeout)
**Models**: `models.py:6-84` — Ticket and Track data structures
**File Cache**: `file_cache.py` — ASTParser with tree-sitter skeletons
**Summarizer**: `summarize.py` — Heuristic file summaries
**Outliner**: `outline_tool.py` — Code outline with line ranges

## Conductor System
The project uses a spec-driven track system in `conductor/`:
- **Tracks**: `conductor/tracks/{name}_{YYYYMMDD}/` — spec.md, plan.md, metadata.json
- **Workflow**: `conductor/workflow.md` — full task lifecycle and TDD protocol
- **Tech Stack**: `conductor/tech-stack.md` — technology constraints
- **Product**: `conductor/product.md` — product vision and guidelines

### Conductor Commands (Claude Code slash commands)
- `/conductor-setup` — bootstrap session with conductor context
- `/conductor-status` — show all track status
- `/conductor-new-track` — create a new track (Tier 1)
- `/conductor-implement` — execute a track (Tier 2 — delegates to Tier 3/4)
- `/conductor-verify` — phase completion verification and checkpointing

### MMA Tier Commands
- `/mma-tier1-orchestrator` — product alignment, planning
- `/mma-tier2-tech-lead` — track execution, architectural oversight
- `/mma-tier3-worker` — stateless TDD implementation
- `/mma-tier4-qa` — stateless error analysis

### Delegation (Tier 2 spawns Tier 3/4)
```powershell
uv run python scripts\claude_mma_exec.py --role tier3-worker "Task prompt here"
uv run python scripts\claude_mma_exec.py --role tier4-qa "Error analysis prompt"
```

## Current State
- [x] Multi-provider AI client (Gemini, Anthropic, DeepSeek)
- [x] Dear PyGui / ImGui GUI with multi-panel interface
- [x] MMA 4-tier orchestration engine
- [x] Custom MCP tools (26 tools via mcp_client.py)
- [x] Session logging and audit trails
- [x] Gemini CLI headless adapter
- [x] Claude Code conductor integration
- [~] AI-Optimized Python Style Refactor (Phase 3 — type hints for UI modules)
- [~] Robust Live Simulation Verification (Phase 2 — Epic/Track verification)
- [ ] Documentation Refresh and Context Cleanup

## Development Workflow
1. Run `/conductor-setup` to load session context
2. Pick active track from `conductor/tracks.md` or `/conductor-status`
3. Run `/conductor-implement` to resume track execution
4. Follow TDD: Red (failing tests) → Green (pass) → Refactor
5. Delegate implementation to Tier 3 Workers, errors to Tier 4 QA
6. On phase completion: run `/conductor-verify` for checkpoint

## Anti-Patterns (Avoid These)
- **Don't read full large files** — use `py_get_skeleton`, `get_file_summary`, `py_get_code_outline` first (Research-First Protocol)
- **Don't implement directly as Tier 2** — delegate to Tier 3 Workers via `claude_mma_exec.py`
- **Don't skip TDD** — write failing tests before implementation
- **Don't modify tech stack silently** — update `conductor/tech-stack.md` BEFORE implementing
- **Don't skip phase verification** — run `/conductor-verify` when all tasks in a phase are `[x]`
- **Don't mix track work** — stay focused on one track at a time

## MCP Tools (available via manual-slop MCP server)
When the MCP server is running, these tools are available natively:
`py_get_skeleton`, `py_get_code_outline`, `py_get_definition`, `py_update_definition`,
`py_get_signature`, `py_set_signature`, `py_get_class_summary`, `py_find_usages`,
`py_get_imports`, `py_check_syntax`, `py_get_hierarchy`, `py_get_docstring`,
`get_file_summary`, `get_file_slice`, `set_file_slice`, `get_git_diff`, `get_tree`,
`search_files`, `read_file`, `list_directory`, `web_search`, `fetch_url`,
`run_powershell`, `get_ui_performance`, `py_get_var_declaration`, `py_set_var_declaration`

## Journal Update Requirements
Update JOURNAL.md after:
- Completing any significant feature or fix
- Encountering and resolving errors
- End of each work session
- Making architectural decisions
Format: What/Why/How/Issues/Result structure

## Task Management Integration
- **conductor/tracks.md**: Quick-read pointer to active conductor tracks
- **conductor/tracks/*/plan.md**: Detailed task state (source of truth)
- **JOURNAL.md**: Completed work history with `|TASK:ID|` tags
- **ERRORS.md**: P0/P1 error tracking
