Ed_
c428e4331a
- 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
119 lines
6.3 KiB
Markdown
119 lines
6.3 KiB
Markdown
# CLAUDE.md
|
|
<!-- Generated by Claude Conductor v2.0.0 -->
|
|
|
|
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:
|
|
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 `TASKS.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
|
|
- **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
|