checkpoint: Claude Code integration + implement missing MCP var tools
Add Claude Code conductor commands, MCP server, MMA exec scripts, and implement py_get_var_declaration / py_set_var_declaration which were registered in dispatch and tool specs but had no function bodies. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
117
CLAUDE.md
Normal file
117
CLAUDE.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# 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
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user