Files

Ed_ c428e4331a fix(mcp): wire run_powershell and MCP server for Windows/Scoop environment

- Add .mcp.json at project root (correct location for claude mcp add)
- Add mcp_env.toml: project-scoped PATH/env config for subprocess execution
- shell_runner.py: load mcp_env.toml, add stdin=DEVNULL to fix git hang
- mcp_server.py: call mcp_client.configure() at startup (fix ACCESS DENIED)
- conductor skill files: enforce run_powershell over Bash, tool use hierarchy
- CLAUDE.md: document Bash unreliability on Windows, run_powershell preference

2026-02-28 15:00:05 -05:00

6.3 KiB

Raw Blame History

CLAUDE.md

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

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:

Check TASKS.md — look for IN_PROGRESS or BLOCKED tracks
Review recent JOURNAL.md entries — scan last 2-3 entries for context
If resuming work: run /conductor-setup to load full context
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)

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

Multi-provider AI client (Gemini, Anthropic, DeepSeek)
Dear PyGui / ImGui GUI with multi-panel interface
MMA 4-tier orchestration engine
Custom MCP tools (26 tools via mcp_client.py)
Session logging and audit trails
Gemini CLI headless adapter
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

Run /conductor-setup to load session context
Pick active track from TASKS.md or /conductor-status
Run /conductor-implement to resume track execution
Follow TDD: Red (failing tests) → Green (pass) → Refactor
Delegate implementation to Tier 3 Workers, errors to Tier 4 QA
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

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

6.3 KiB Raw Blame History