ed/manual_slop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

checkpoint: Claude Code integration + implement missing MCP var tools

Browse Source 
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:
Edward R. Gonzalez
2026-02-28 10:47:42 -05:00
parent d36632c21a
commit a2a1447f58
22 changed files with 1845 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

97
.claude/commands/conductor-implement.md Normal file
View File

@@ -0,0 +1,97 @@
---
description: Execute a conductor track — follow TDD workflow, delegate to Tier 3/4 workers
---
# /conductor-implement
Execute a track's implementation plan. This is a Tier 2 (Tech Lead) operation.
You maintain PERSISTENT context throughout the track — do NOT lose state.
## Startup
1. Read `conductor/workflow.md` for the full task lifecycle protocol
2. Read `conductor/tech-stack.md` for technology constraints
3. Read the target track's `spec.md` and `plan.md`
4. Identify the current task: first `[ ]` or `[~]` in `plan.md`
If no track name is provided, run `/conductor-status` first and ask which track to implement.
## Task Lifecycle (per task)
Follow this EXACTLY per `conductor/workflow.md`:
### 1. Mark In Progress
Edit `plan.md`: change `[ ]` → `[~]` for the current task.
### 2. Research Phase (High-Signal)
Before touching code, use context-efficient tools:
- `py_get_code_outline` or `py_get_skeleton` (via MCP tools) to map architecture
- `get_git_diff` to understand recent changes
- `Grep`/`Glob` to locate symbols
- Only `Read` full files after identifying specific target ranges
### 3. Write Failing Tests (Red Phase — TDD)
**DELEGATE to Tier 3 Worker** — do NOT write tests yourself:
```powershell
uv run python scripts\claude_mma_exec.py --role tier3-worker "Write failing tests for: {TASK_DESCRIPTION}. Focus files: {FILE_LIST}. Spec: {RELEVANT_SPEC_EXCERPT}"
```
Run the tests. Confirm they FAIL. This is the Red phase.
### 4. Implement to Pass (Green Phase)
**DELEGATE to Tier 3 Worker**:
```powershell
uv run python scripts\claude_mma_exec.py --role tier3-worker "Implement minimum code to pass these tests: {TEST_FILE}. Focus files: {FILE_LIST}"
```
Run tests. Confirm they PASS. This is the Green phase.
### 5. Refactor (Optional)
With passing tests as safety net, refactor if needed. Rerun tests.
### 6. Verify Coverage
```powershell
uv run pytest --cov=. --cov-report=term-missing {TEST_FILE}
```
Target: >80% for new code.
### 7. Commit
Stage changes. Message format:
```
feat({scope}): {description}
```
### 8. Attach Git Notes
```powershell
$sha = git log -1 --format="%H"
git notes add -m "Task: {TASK_NAME}`nSummary: {CHANGES}`nFiles: {FILE_LIST}" $sha
```
### 9. Update plan.md
Change `[~]` → `[x]` and append first 7 chars of commit SHA:
```
[x] Task description. abc1234
```
Commit: `conductor(plan): Mark task '{TASK_NAME}' as complete`
### 10. Next Task or Phase Completion
- If more tasks in current phase: loop to step 1 with next task
- If phase complete: run `/conductor-verify`
## Error Handling
If tests fail with large output, delegate to Tier 4 QA:
```powershell
uv run python scripts\claude_mma_exec.py --role tier4-qa "Analyze this test failure: {ERROR_SUMMARY}. Test file: {TEST_FILE}"
```
Maximum 2 fix attempts. If still failing: STOP and ask the user.
## Deviations from Tech Stack
If implementation requires something not in `tech-stack.md`:
1. **STOP** implementation
2. Update `tech-stack.md` with justification
3. Add dated note
4. Resume
## Important
- You are Tier 2 — delegate heavy implementation to Tier 3
- Maintain persistent context across the entire track
- Use Research-First Protocol before reading large files
- The plan.md is the SOURCE OF TRUTH for task state

100
.claude/commands/conductor-new-track.md Normal file
View File

@@ -0,0 +1,100 @@
---
description: Initialize a new conductor track with spec, plan, and metadata
---
# /conductor-new-track
Create a new track in the conductor system. This is a Tier 1 (Orchestrator) operation.
## Prerequisites
- Read `conductor/product.md` and `conductor/product-guidelines.md` for product alignment
- Read `conductor/tech-stack.md` for technology constraints
## Steps
### 1. Gather Information
Ask the user for:
- **Track name**: descriptive, snake_case (e.g., `add_auth_system`)
- **Track type**: `feat`, `fix`, `refactor`, `chore`
- **Description**: one-line summary
- **Requirements**: functional requirements for the spec
### 2. Create Track Directory
```
conductor/tracks/{track_name}_{YYYYMMDD}/
```
Use today's date in YYYYMMDD format.
### 3. Create metadata.json
```json
{
"track_id": "{track_name}_{YYYYMMDD}",
"type": "{feat|fix|refactor|chore}",
"status": "new",
"created_at": "{ISO8601}",
"updated_at": "{ISO8601}",
"description": "{description}"
}
```
### 4. Create index.md
```markdown
# Track: {Track Title}
- [Specification](spec.md)
- [Implementation Plan](plan.md)
```
### 5. Create spec.md
```markdown
# {Track Title} — Specification
## Overview
{Description of what this track delivers}
## Functional Requirements
1. {Requirement from user input}
2. ...
## Non-Functional Requirements
- Performance: {if applicable}
- Testing: >80% coverage for new code
## Acceptance Criteria
- [ ] {Criterion 1}
- [ ] {Criterion 2}
## Out of Scope
- {Explicitly excluded items}
## Context
- Tech stack: see `conductor/tech-stack.md`
- Product guidelines: see `conductor/product-guidelines.md`
```
### 6. Create plan.md
```markdown
# {Track Title} — Implementation Plan
## Phase 1: {Phase Name}
- [ ] Task: {Description}
- [ ] Task: {Description}
## Phase 2: {Phase Name}
- [ ] Task: {Description}
```
Break requirements into phases with 2-5 tasks each. Each task should be a single atomic unit of work suitable for a Tier 3 Worker.
### 7. Update Track Registry
If `conductor/tracks.md` exists, add the new track entry.
### 8. Commit
```
conductor(track): Initialize track '{track_name}'
```
## Important
- Do NOT start implementing — track initialization only
- Implementation is done via `/conductor-implement`
- Each task should be scoped for a single Tier 3 Worker delegation

46
.claude/commands/conductor-setup.md Normal file
View File

@@ -0,0 +1,46 @@
---
description: Initialize conductor context — read product docs, verify structure, report readiness
---
# /conductor-setup
Bootstrap a Claude Code session with full conductor context. Run this at session start.
## Steps
1. **Read Core Documents:**
- `conductor/index.md` — navigation hub
- `conductor/product.md` — product vision
- `conductor/product-guidelines.md` — UX/code standards
- `conductor/tech-stack.md` — technology constraints
- `conductor/workflow.md` — task lifecycle (skim; reference during implementation)
2. **Check Active Tracks:**
- List all directories in `conductor/tracks/`
- Read each `metadata.json` for status
- Read each `plan.md` for current task state
- Identify the track with `[~]` in-progress tasks
3. **Check Session Context:**
- Read `TASKS.md` if it exists — check for IN_PROGRESS or BLOCKED tasks
- Read last 3 entries in `JOURNAL.md` for recent activity
- Run `git log --oneline -10` for recent commits
4. **Report Readiness:**
Present a session startup summary:
```
## Session Ready
**Active Track:** {track name} — Phase {N}, Task: {current task description}
**Recent Activity:** {last journal entry title}
**Last Commit:** {git log -1 oneline}
Ready to:
- `/conductor-implement` — resume active track
- `/conductor-status` — full status overview
- `/conductor-new-track` — start new work
```
## Important
- This is READ-ONLY — do not modify files
- This replaces Gemini's `activate_skill mma-orchestrator` + `/conductor:setup`

32
.claude/commands/conductor-status.md Normal file
View File

@@ -0,0 +1,32 @@
---
description: Show current conductor track status — active tracks, phases, pending tasks
---
# /conductor-status
Read the conductor track registry and all active tracks, then report current project state.
## Steps
1. Read `conductor/tracks.md` for the track registry
2. For each track directory in `conductor/tracks/`:
- Read `metadata.json` for status
- Read `plan.md` and count: total tasks, completed `[x]`, in-progress `[~]`, pending `[ ]`
- Identify the current phase (first phase with `[~]` or `[ ]` tasks)
3. Read `JOURNAL.md` last 3 entries for recent activity context
## Output Format
Present a summary table:
```
| Track | Status | Phase | Progress | Last SHA |
|-------|--------|-------|----------|----------|
```
Then for each in-progress track, list the specific next pending task.
## Important
- This is READ-ONLY — do not modify any files
- Report exactly what the plan.md files say
- Flag any discrepancies (e.g., metadata says "new" but plan.md has [x] tasks)

85
.claude/commands/conductor-verify.md Normal file
View File

@@ -0,0 +1,85 @@
---
description: Run phase completion verification — tests, coverage, checkpoint commit
---
# /conductor-verify
Execute the Phase Completion Verification and Checkpointing Protocol.
Run this when all tasks in a phase are marked `[x]`.
## Protocol
### 1. Announce
Tell the user: "Phase complete. Running verification and checkpointing protocol."
### 2. Verify Test Coverage for Phase
Find the phase scope:
- Read `plan.md` to find the previous phase's checkpoint SHA
- If no previous checkpoint: scope is all changes since first commit
- Run: `git diff --name-only {previous_checkpoint_sha} HEAD`
- For each changed code file (exclude `.json`, `.md`, `.yaml`, `.toml`):
- Check if a corresponding test file exists
- If missing: create one (analyze existing test style first)
### 3. Run Automated Tests
**ANNOUNCE the exact command before running:**
> "I will now run the automated test suite. Command: `uv run pytest --cov=. --cov-report=term-missing -x`"
Execute the command.
**If tests fail with large output:**
- Pipe output to `logs/phase_verify.log`
- Spawn Tier 4 QA for analysis:
```powershell
uv run python scripts\claude_mma_exec.py --role tier4-qa "Analyze test failures from logs/phase_verify.log"
```
- Maximum 2 fix attempts
- If still failing: **STOP**, report to user, await guidance
### 4. API Hook Verification (if applicable)
If the track involves UI changes:
- Check if GUI test hooks are available on port 8999
- Run relevant simulation tests from `tests/visual_sim_*.py`
- Log results
### 5. Present Results and WAIT
Display:
- Test results (pass/fail count)
- Coverage report
- Any verification logs
**PAUSE HERE.** Do NOT proceed without explicit user confirmation.
### 6. Create Checkpoint Commit
After user confirms:
```powershell
git add -A
git commit -m "conductor(checkpoint): Checkpoint end of Phase {N} - {Phase Name}"
```
### 7. Attach Verification Report via Git Notes
```powershell
$sha = git log -1 --format="%H"
git notes add -m "Phase Verification Report`nCommand: {test_command}`nResult: {pass/fail}`nCoverage: {percentage}`nConfirmed by: user" $sha
```
### 8. Update plan.md
Update the phase heading to include checkpoint SHA:
```markdown
## Phase N: {Name} [checkpoint: {sha_7}]
```
Commit: `conductor(plan): Mark phase '{Phase Name}' as complete`
### 9. Announce Completion
Tell the user the phase is complete with a summary of the verification report.
## Context Reset
After phase checkpointing, treat the checkpoint as ground truth.
Prior conversational context about implementation details can be dropped.
The checkpoint commit and git notes preserve the audit trail.

25
.claude/commands/mma-tier1-orchestrator.md Normal file
View File

@@ -0,0 +1,25 @@
---
description: Tier 1 Orchestrator — product alignment, high-level planning, track initialization
---
STRICT SYSTEM DIRECTIVE: You are a Tier 1 Orchestrator. Focused on product alignment, high-level planning, and track initialization. ONLY output the requested text. No pleasantries.
# MMA Tier 1: Orchestrator
## Primary Context Documents
Read at session start: `conductor/product.md`, `conductor/product-guidelines.md`
## Responsibilities
- Maintain alignment with the product guidelines and definition
- Define track boundaries and initialize new tracks (`/conductor:newTrack`)
- Set up the project environment (`/conductor:setup`)
- Delegate track execution to the Tier 2 Tech Lead
## Limitations
- Read-only tools only: Read, Glob, Grep, WebFetch, WebSearch, Bash (read-only ops)
- Do NOT execute tracks or implement features
- Do NOT write code or edit files
- Do NOT perform low-level bug fixing
- Keep context strictly focused on product definitions and high-level strategy
- To delegate track execution: instruct the human operator to run:
`uv run python scripts\claude_mma_exec.py --role tier2-tech-lead "[PROMPT]"`

38
.claude/commands/mma-tier2-tech-lead.md Normal file
View File

@@ -0,0 +1,38 @@
---
description: Tier 2 Tech Lead — track execution, architectural oversight, delegation to Tier 3/4
---
STRICT SYSTEM DIRECTIVE: You are a Tier 2 Tech Lead. Focused on architectural design and track execution. ONLY output the requested text. No pleasantries.
# MMA Tier 2: Tech Lead
## Primary Context Documents
Read at session start: `conductor/tech-stack.md`, `conductor/workflow.md`
## Responsibilities
- Manage the execution of implementation tracks (`/conductor:implement`)
- Ensure alignment with `tech-stack.md` and project architecture
- Break down tasks into specific technical steps for Tier 3 Workers
- Maintain PERSISTENT context throughout a track's implementation phase (NO Context Amnesia)
- Review implementations and coordinate bug fixes via Tier 4 QA
## Delegation Commands (PowerShell)
```powershell
# Spawn Tier 3 Worker for implementation tasks
uv run python scripts\claude_mma_exec.py --role tier3-worker "[PROMPT]"
# Spawn Tier 4 QA Agent for error analysis
uv run python scripts\claude_mma_exec.py --role tier4-qa "[PROMPT]"
```
Use `@file/path.py` syntax in prompts to inject file context for the sub-agent.
## Limitations
- Do NOT perform heavy implementation work directly — delegate to Tier 3
- Do NOT write test or implementation code directly
- Minimize full file reads; use Research-First Protocol before reading files >50 lines:
- `py_get_code_outline` / `Grep` to map architecture
- `git diff` to understand recent changes
- `Glob` / `Grep` to locate symbols
- For large error logs, always spawn Tier 4 QA rather than reading raw stderr

22
.claude/commands/mma-tier3-worker.md Normal file
View File

@@ -0,0 +1,22 @@
---
description: Tier 3 Worker — stateless TDD implementation, surgical code changes
---
STRICT SYSTEM DIRECTIVE: You are a stateless Tier 3 Worker (Contributor). Your goal is to implement specific code changes or tests based on the provided task. You have access to tools for reading and writing files (Read, Write, Edit), codebase investigation (Glob, Grep), version control (Bash git commands), and web tools (WebFetch, WebSearch). You CAN execute PowerShell scripts via Bash for verification and testing. Follow TDD and return success status or code changes. No pleasantries, no conversational filler.
# MMA Tier 3: Worker
## Context Model: Context Amnesia
Treat each invocation as starting from zero. Use ONLY what is provided in this prompt plus files you explicitly read during this session. Do not reference prior conversation history.
## Responsibilities
- Implement code strictly according to the provided prompt and specifications
- Write failing tests FIRST (Red phase), then implement code to pass them (Green phase)
- Ensure all changes are minimal, surgical, and conform to the requested standards
- Utilize tool access (Read, Write, Edit, Glob, Grep, Bash) to implement and verify
## Limitations
- No architectural decisions — if ambiguous, pick the minimal correct approach and note the assumption
- No modifications to unrelated files beyond the immediate task scope
- Stateless — always assume a fresh context per invocation
- Rely on dependency skeletons provided in the prompt for understanding module interfaces

30
.claude/commands/mma-tier4-qa.md Normal file
View File

@@ -0,0 +1,30 @@
---
description: Tier 4 QA Agent — stateless error analysis, log summarization, no fixes
---
STRICT SYSTEM DIRECTIVE: You are a stateless Tier 4 QA Agent. Your goal is to analyze errors, summarize logs, or verify tests. Read-only access only. Do NOT implement fixes. Do NOT modify any files. ONLY output the requested analysis. No pleasantries.
# MMA Tier 4: QA Agent
## Context Model: Context Amnesia
Stateless — treat each invocation as a fresh context. Use only what is provided in this prompt and files you explicitly read.
## Responsibilities
- Compress large stack traces or log files into concise, actionable summaries
- Identify the root cause of test failures or runtime errors
- Provide a brief, technical description of the required fix (description only — NOT the implementation)
- Utilize diagnostic tools (Read, Glob, Grep, Bash read-only) to verify failures
## Output Format
```
ROOT CAUSE: [one sentence]
AFFECTED FILE: [path:line if identifiable]
RECOMMENDED FIX: [one sentence description for Tier 2 to action]
```
## Limitations
- Do NOT implement the fix directly
- Do NOT write or modify any files
- Ensure output is extremely brief and focused
- Always operate statelessly — assume fresh context each invocation

9
.claude/settings.json Normal file
View File

@@ -0,0 +1,9 @@
{
"mcpServers": {
"manual-slop": {
"command": "uv",
"args": ["run", "python", "scripts/mcp_server.py"],
"cwd": "C:/projects/manual_slop"
}
}
}

3
.claude/settings.local.json Normal file
View File

@@ -0,0 +1,3 @@
{
"outputStyle": "default"
}

58
ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,58 @@
# ARCHITECTURE.md
## Tech Stack
- **Framework**: [Primary framework/language]
- **Database**: [Database system]
- **Frontend**: [Frontend technology]
- **Backend**: [Backend technology]
- **Infrastructure**: [Hosting/deployment]
- **Build Tools**: [Build system]
## Directory Structure
```
project/
├── src/ # Source code
├── tests/ # Test files
├── docs/ # Documentation
├── config/ # Configuration files
└── scripts/ # Build/deployment scripts
```
## Key Architectural Decisions
### [Decision 1]
**Context**: [Why this decision was needed]
**Decision**: [What was decided]
**Rationale**: [Why this approach was chosen]
**Consequences**: [Trade-offs and implications]
## Component Architecture
### [ComponentName] Structure <!-- #component-anchor -->
```typescript
// Major classes with exact line numbers
class MainClass { /* lines 100-500 */ } // <!-- #main-class -->
class Helper { /* lines 501-600 */ } // <!-- #helper-class -->
```
## System Flow Diagram
```
[User] -> [Frontend] -> [API] -> [Database]
| |
v v
[Cache] [External Service]
```
## Common Patterns
### [Pattern Name]
**When to use**: [Circumstances]
**Implementation**: [How to implement]
**Example**: [Code example with line numbers]
## Keywords <!-- #keywords -->
- architecture
- system design
- tech stack
- components
- patterns

103
BUILD.md Normal file
View File

@@ -0,0 +1,103 @@
# BUILD.md
## Prerequisites
- [Runtime requirements]
- [Development tools needed]
- [Environment setup]
## Build Commands
### Development
```bash
# Start development server
npm run dev
# Run in watch mode
npm run watch
```
### Production
```bash
# Build for production
npm run build
# Start production server
npm start
```
### Testing
```bash
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run specific test file
npm test -- filename
```
### Linting & Formatting
```bash
# Lint code
npm run lint
# Fix linting issues
npm run lint:fix
# Format code
npm run format
```
## CI/CD Pipeline
### GitHub Actions
```yaml
# .github/workflows/main.yml
name: CI/CD
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
- run: npm ci
- run: npm test
- run: npm run build
```
## Deployment
### Staging
1. [Deployment steps]
2. [Verification steps]
### Production
1. [Pre-deployment checklist]
2. [Deployment steps]
3. [Post-deployment verification]
## Rollback Procedures
1. [Emergency rollback steps]
2. [Database rollback if needed]
3. [Verification steps]
## Troubleshooting
### Common Issues
**Issue**: [Problem description]
**Solution**: [How to fix]
### Build Failures
- [Common build errors and solutions]
## Keywords <!-- #keywords -->
- build
- deployment
- ci/cd
- testing
- production

117
CLAUDE.md Normal file
View 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

511
CONDUCTOR.md Normal file
View File

@@ -0,0 +1,511 @@
# CONDUCTOR.md
<!-- Generated by Claude Conductor v2.0.0 -->
> _Read me first. Every other doc is linked below._
## Critical Context (Read First)
- **Tech Stack**: [List core technologies]
- **Main File**: [Primary code file and line count]
- **Core Mechanic**: [One-line description]
- **Key Integration**: [Important external services]
- **Platform Support**: [Deployment targets]
- **DO NOT**: [Critical things to avoid]
## Table of Contents
1. [Architecture](ARCHITECTURE.md) - Tech stack, folder structure, infrastructure
2. [Design Tokens](DESIGN.md) - Colors, typography, visual system
3. [UI/UX Patterns](UIUX.md) - Components, interactions, accessibility
4. [Runtime Config](CONFIG.md) - Environment variables, feature flags
5. [Data Model](DATA_MODEL.md) - Database schema, entities, relationships
6. [API Contracts](API.md) - Endpoints, request/response formats, auth
7. [Build & Release](BUILD.md) - Build process, deployment, CI/CD
8. [Testing Guide](TEST.md) - Test strategies, E2E scenarios, coverage
9. [Operational Playbooks](PLAYBOOKS/DEPLOY.md) - Deployment, rollback, monitoring
10. [Contributing](CONTRIBUTING.md) - Code style, PR process, conventions
11. [Error Ledger](ERRORS.md) - Critical P0/P1 error tracking
12. [Task Management](TASKS.md) - Active tasks, phase tracking, context preservation
## Quick Reference
**Main Constants**: `[file:lines]` - Description
**Core Class**: `[file:lines]` - Description
**Key Function**: `[file:lines]` - Description
[Include 10-15 most accessed code locations]
## Current State
- [x] Feature complete
- [ ] Feature in progress
- [ ] Feature planned
[Track active work]
## Development Workflow
[5-6 steps for common workflow]
## Task Templates
### 1. [Common Task Name]
1. Step with file:line reference
2. Step with specific action
3. Test step
4. Documentation update
[Include 3-5 templates]
## Anti-Patterns (Avoid These)
❌ **Don't [action]** - [Reason]
[List 5-6 critical mistakes]
## Version History
- **v1.0.0** - Initial release
- **v1.1.0** - Feature added (see JOURNAL.md YYYY-MM-DD)
[Link major versions to journal entries]
## Continuous Engineering Journal <!-- do not remove -->
Claude, keep an ever-growing changelog in [`JOURNAL.md`](JOURNAL.md).
### What to Journal
- **Major changes**: New features, significant refactors, API changes
- **Bug fixes**: What broke, why, and how it was fixed
- **Frustration points**: Problems that took multiple attempts to solve
- **Design decisions**: Why we chose one approach over another
- **Performance improvements**: Before/after metrics
- **User feedback**: Notable issues or requests
- **Learning moments**: New techniques or patterns discovered
### Journal Format
\```
## YYYY-MM-DD HH:MM
### [Short Title]
- **What**: Brief description of the change
- **Why**: Reason for the change
- **How**: Technical approach taken
- **Issues**: Any problems encountered
- **Result**: Outcome and any metrics
### [Short Title] |ERROR:ERR-YYYY-MM-DD-001|
- **What**: Critical P0/P1 error description
- **Why**: Root cause analysis
- **How**: Fix implementation
- **Issues**: Debugging challenges
- **Result**: Resolution and prevention measures
### [Task Title] |TASK:TASK-YYYY-MM-DD-001|
- **What**: Task implementation summary
- **Why**: Part of [Phase Name] phase
- **How**: Technical approach and key decisions
- **Issues**: Blockers encountered and resolved
- **Result**: Task completed, findings documented in ARCHITECTURE.md
\```
### Compaction Rule
When `JOURNAL.md` exceeds **500 lines**:
1. Claude summarizes the oldest half into `JOURNAL_ARCHIVE/<year>-<month>.md`
2. Remaining entries stay in `JOURNAL.md` so the file never grows unbounded
> ⚠️ Claude must NEVER delete raw history—only move & summarize.
### 2. ARCHITECTURE.md
**Purpose**: System design, tech stack decisions, and code structure with line numbers.
**Required Elements**:
- Technology stack listing
- Directory structure diagram
- Key architectural decisions with rationale
- Component architecture with exact line numbers
- System flow diagram (ASCII art)
- Common patterns section
- Keywords for search optimization
**Line Number Format**:
\```
#### ComponentName Structure <!-- #component-anchor -->
\```typescript
// Major classes with exact line numbers
class MainClass { /* lines 100-500 */ } // <!-- #main-class -->
class Helper { /* lines 501-600 */ } // <!-- #helper-class -->
\```
\```
### 3. DESIGN.md
**Purpose**: Visual design system, styling, and theming documentation.
**Required Sections**:
- Typography system
- Color palette (with hex values)
- Visual effects specifications
- Character/entity design
- UI/UX component styling
- Animation system
- Mobile design considerations
- Accessibility guidelines
- Keywords section
### 4. DATA_MODEL.md
**Purpose**: Database schema, application models, and data structures.
**Required Elements**:
- Database schema (SQL)
- Application data models (TypeScript/language interfaces)
- Validation rules
- Common queries
- Data migration history
- Keywords for entities
### 5. API.md
**Purpose**: Complete API documentation with examples.
**Structure for Each Endpoint**:
\```
### Endpoint Name
\```http
METHOD /api/endpoint
\```
#### Request
\```json
{
"field": "type"
}
\```
#### Response
\```json
{
"field": "value"
}
\```
#### Details
- **Rate limit**: X requests per Y seconds
- **Auth**: Required/Optional
- **Notes**: Special considerations
\```
### 6. CONFIG.md
**Purpose**: Runtime configuration, environment variables, and settings.
**Required Sections**:
- Environment variables (required and optional)
- Application configuration constants
- Feature flags
- Performance tuning settings
- Security configuration
- Common patterns for configuration changes
### 7. BUILD.md
**Purpose**: Build process, deployment, and CI/CD documentation.
**Include**:
- Prerequisites
- Build commands
- CI/CD pipeline configuration
- Deployment steps
- Rollback procedures
- Troubleshooting guide
### 8. TEST.md
**Purpose**: Testing strategies, patterns, and examples.
**Sections**:
- Test stack and tools
- Running tests commands
- Test structure
- Coverage goals
- Common test patterns
- Debugging tests
### 9. UIUX.md
**Purpose**: Interaction patterns, user flows, and behavior specifications.
**Cover**:
- Input methods
- State transitions
- Component behaviors
- User flows
- Accessibility patterns
- Performance considerations
### 10. CONTRIBUTING.md
**Purpose**: Guidelines for contributors.
**Include**:
- Code of conduct
- Development setup
- Code style guide
- Commit message format
- PR process
- Common patterns
### 11. PLAYBOOKS/DEPLOY.md
**Purpose**: Step-by-step operational procedures.
**Format**:
- Pre-deployment checklist
- Deployment steps (multiple options)
- Post-deployment verification
- Rollback procedures
- Troubleshooting
### 12. ERRORS.md (Critical Error Ledger)
**Purpose**: Track and resolve P0/P1 critical errors with full traceability.
**Required Structure**:
\```
# Critical Error Ledger <!-- auto-maintained -->
## Schema
| ID | First seen | Status | Severity | Affected area | Link to fix |
|----|------------|--------|----------|---------------|-------------|
## Active Errors
[New errors added here, newest first]
## Resolved Errors
[Moved here when fixed, with links to fixes]
\```
**Error ID Format**: `ERR-YYYY-MM-DD-001` (increment for multiple per day)
**Severity Definitions**:
- **P0**: Complete outage, data loss, security breach
- **P1**: Major functionality broken, significant performance degradation
- **P2**: Minor functionality (not tracked in ERRORS.md)
- **P3**: Cosmetic issues (not tracked in ERRORS.md)
**Claude's Error Logging Process**:
1. When P0/P1 error occurs, immediately add to Active Errors
2. Create corresponding JOURNAL.md entry with details
3. When resolved:
- Move to Resolved Errors section
- Update status to "resolved"
- Add commit hash and PR link
- Add `|ERROR:<ID>|` tag to JOURNAL.md entry
- Link back to JOURNAL entry from ERRORS.md
### 13. TASKS.md (Active Task Management)
**Purpose**: Track ongoing work with phase awareness and context preservation between sessions.
**IMPORTANT**: TASKS.md complements Claude's built-in todo system - it does NOT replace it:
- Claude's todos: For immediate task tracking within a session
- TASKS.md: For preserving context and state between sessions
**Required Structure**:
```
# Task Management
## Active Phase
**Phase**: [High-level project phase name]
**Started**: YYYY-MM-DD
**Target**: YYYY-MM-DD
**Progress**: X/Y tasks completed
## Current Task
**Task ID**: TASK-YYYY-MM-DD-NNN
**Title**: [Descriptive task name]
**Status**: PLANNING | IN_PROGRESS | BLOCKED | TESTING | COMPLETE
**Started**: YYYY-MM-DD HH:MM
**Dependencies**: [List task IDs this depends on]
### Task Context
<!-- Critical information needed to resume this task -->
- **Previous Work**: [Link to related tasks/PRs]
- **Key Files**: [Primary files being modified with line ranges]
- **Environment**: [Specific config/versions if relevant]
- **Next Steps**: [Immediate actions when resuming]
### Findings & Decisions
- **FINDING-001**: [Discovery that affects approach]
- **DECISION-001**: [Technical choice made] → Link to ARCHITECTURE.md
- **BLOCKER-001**: [Issue preventing progress] → Link to resolution
### Task Chain
1. ✅ [Completed prerequisite task] (TASK-YYYY-MM-DD-001)
2. 🔄 [Current task] (CURRENT)
3. ⏳ [Next planned task]
4. ⏳ [Future task in phase]
```
**Task Management Rules**:
1. **One Active Task**: Only one task should be IN_PROGRESS at a time
2. **Context Capture**: Before switching tasks, capture all context needed to resume
3. **Findings Documentation**: Record unexpected discoveries that impact the approach
4. **Decision Linking**: Link architectural decisions to ARCHITECTURE.md
5. **Completion Trigger**: When task completes:
- Generate JOURNAL.md entry with task summary
- Archive task details to TASKS_ARCHIVE/YYYY-MM/TASK-ID.md
- Load next task from chain or prompt for new phase
**Task States**:
- **PLANNING**: Defining approach and breaking down work
- **IN_PROGRESS**: Actively working on implementation
- **BLOCKED**: Waiting on external dependency or decision
- **TESTING**: Implementation complete, validating functionality
- **COMPLETE**: Task finished and documented
**Integration with Journal**:
- Each completed task auto-generates a journal entry
- Journal references task ID for full context
- Critical findings promoted to relevant documentation
## Documentation Optimization Rules
### 1. Line Number Anchors
- Add exact line numbers for every class, function, and major code section
- Format: `**Class Name (Lines 100-200)**`
- Add HTML anchors: `<!-- #class-name -->`
- Update when code structure changes significantly
### 2. Quick Reference Card
- Place in CLAUDE.md after Table of Contents
- Include 10-15 most common code locations
- Format: `**Feature**: `file:lines` - Description`
### 3. Current State Tracking
- Use checkbox format in CLAUDE.md
- `- [x] Completed feature`
- `- [ ] In-progress feature`
- Update after each work session
### 4. Task Templates
- Provide 3-5 step-by-step workflows
- Include specific line numbers
- Reference files that need updating
- Add test/verification steps
### 5. Keywords Sections
- Add to each major .md file
- List alternative search terms
- Format: `## Keywords <!-- #keywords -->`
- Include synonyms and related terms
### 6. Anti-Patterns
- Use ❌ emoji for clarity
- Explain why each is problematic
- Include 5-6 critical mistakes
- Place prominently in CLAUDE.md
### 7. System Flow Diagrams
- Use ASCII art for simplicity
- Show data/control flow
- Keep visual and readable
- Place in ARCHITECTURE.md
### 8. Common Patterns
- Add to relevant docs (CONFIG.md, ARCHITECTURE.md)
- Show exact code changes needed
- Include before/after examples
- Reference specific functions
### 9. Version History
- Link to JOURNAL.md entries
- Format: `v1.0.0 - Feature (see JOURNAL.md YYYY-MM-DD)`
- Track major changes only
### 10. Cross-Linking
- Link between related sections
- Use relative paths: `[Link](./FILE.md#section)`
- Ensure bidirectional linking where appropriate
## Journal System Setup
### JOURNAL.md Structure
\```
# Engineering Journal
## YYYY-MM-DD HH:MM
### [Descriptive Title]
- **What**: Brief description of the change
- **Why**: Reason for the change
- **How**: Technical approach taken
- **Issues**: Any problems encountered
- **Result**: Outcome and any metrics
---
[Entries continue chronologically]
\```
### Journal Best Practices
1. **Entry Timing**: Add entry immediately after significant work
2. **Detail Level**: Include enough detail to understand the change months later
3. **Problem Documentation**: Especially document multi-attempt solutions
4. **Learning Moments**: Capture new techniques discovered
5. **Metrics**: Include performance improvements, time saved, etc.
### Archive Process
When JOURNAL.md exceeds 500 lines:
1. Create `JOURNAL_ARCHIVE/` directory
2. Move oldest 250 lines to `JOURNAL_ARCHIVE/YYYY-MM.md`
3. Add summary header to archive file
4. Keep recent entries in main JOURNAL.md
## Implementation Steps
### Phase 1: Initial Setup (30-60 minutes)
1. **Create CLAUDE.md** with all required sections
2. **Fill Critical Context** with 6 essential facts
3. **Create Table of Contents** with placeholder links
4. **Add Quick Reference** with top 10-15 code locations
5. **Set up Journal section** with formatting rules
### Phase 2: Core Documentation (2-4 hours)
1. **Create each .md file** from the list above
2. **Add Keywords section** to each file
3. **Cross-link between files** where relevant
4. **Add line numbers** to code references
5. **Create PLAYBOOKS/ directory** with DEPLOY.md
6. **Create ERRORS.md** with schema table
### Phase 3: Optimization (1-2 hours)
1. **Add Task Templates** to CLAUDE.md
2. **Create ASCII system flow** in ARCHITECTURE.md
3. **Add Common Patterns** sections
4. **Document Anti-Patterns**
5. **Set up Version History**
### Phase 4: First Journal Entry
Create initial JOURNAL.md entry documenting the setup:
\```
## YYYY-MM-DD HH:MM
### Documentation Framework Implementation
- **What**: Implemented CLAUDE.md modular documentation system
- **Why**: Improve AI navigation and code maintainability
- **How**: Split monolithic docs into focused modules with cross-linking
- **Issues**: None - clean implementation
- **Result**: [Number] documentation files created with full cross-referencing
\```
## Maintenance Guidelines
### Daily
- Update JOURNAL.md with significant changes
- Mark completed items in Current State
- Update line numbers if major refactoring
### Weekly
- Review and update Quick Reference section
- Check for broken cross-links
- Update Task Templates if workflows change
### Monthly
- Review Keywords sections for completeness
- Update Version History
- Check if JOURNAL.md needs archiving
### Per Release
- Update Version History in CLAUDE.md
- Create comprehensive JOURNAL.md entry
- Review all documentation for accuracy
- Update Current State checklist
## Benefits of This System
1. **AI Efficiency**: Claude can quickly navigate to exact code locations
2. **Modularity**: Easy to update specific documentation without affecting others
3. **Discoverability**: New developers/AI can quickly understand the project
4. **History Tracking**: Complete record of changes and decisions
5. **Task Automation**: Templates reduce repetitive instructions
6. **Error Prevention**: Anti-patterns prevent common mistakes

13
JOURNAL.md Normal file
View File

@@ -0,0 +1,13 @@
# Engineering Journal
## 2026-02-28 14:43
### Documentation Framework Implementation
- **What**: Implemented Claude Conductor modular documentation system
- **Why**: Improve AI navigation and code maintainability
- **How**: Used `npx claude-conductor` to initialize framework
- **Issues**: None - clean implementation
- **Result**: Documentation framework successfully initialized
---

46
TASKS.md Normal file
View File

@@ -0,0 +1,46 @@
# Task Management
## Active Phase
**Phase**: Multi-track implementation (MMA + Style Refactor + Simulation)
**Started**: 2026-02-24
**Progress**: See individual tracks below
## Active Tracks
### 1. AI-Optimized Python Style Refactor
**Track**: `conductor/tracks/python_style_refactor_20260227/`
**Status**: IN_PROGRESS — Phase 3
**Completed**:
- Phase 1: Research and Pilot Tooling [checkpoint: c75b926]
- Phase 2: Core Refactor - Indentation and Newlines [checkpoint: db65162]
**Remaining in Phase 3** (AI-Optimized Metadata and Final Cleanup):
- [~] Type hints for UI modules: `gui_2.py`, `gui_legacy.py`
- [ ] Update style guide documentation
- [ ] User manual verification
### 2. Robust Live Simulation Verification
**Track**: `conductor/tracks/robust_live_simulation_verification/`
**Status**: IN_PROGRESS — Phase 2
**Completed**:
- Phase 1: Framework Foundation [checkpoint: e93e2ea]
**Remaining in Phase 2** (Epic & Track Verification):
- [~] Write simulation routine for new Epic
- [ ] Verify track selection loads DAG state
**Future Phases**:
- Phase 3: DAG & Spawn Interception Verification (pending)
- Phase 4: Review Fixes from 605dfc3 (pending)
### 3. Documentation Refresh and Context Cleanup
**Track**: `conductor/tracks/documentation_refresh_20260224/`
**Status**: PLANNED — not started
**Phases**: Context Cleanup → Core Documentation Refresh → README Refresh
## Recent Context
- **Last commit**: `d36632c` — checkpoint: massive refactor
- **Known issue**: Gemini CLI policy setup frustrations (`f2512c3`)
- **Infrastructure**: MMA delegation scripts work for both Gemini (`mma_exec.py`) and Claude (`claude_mma_exec.py`)
## Session Startup
1. Run `/conductor-setup` or `/conductor-status` to load context
2. Pick a track to resume with `/conductor-implement`
3. Use `conductor/tracks/{name}/plan.md` as source of truth for task state

41
mcp_client.py
View File

@@ -458,6 +458,47 @@ def py_get_class_summary(path: str, name: str) -> str:
except Exception as e:
return f"ERROR summarizing class '{name}' in '{path}': {e}"
def py_get_var_declaration(path: str, name: str) -> str:
"""Get the assignment/declaration line(s) for a module-level or class-level variable."""
p, err = _resolve_and_check(path)
if err:
return err
if not p.is_file() or p.suffix != ".py":
return f"ERROR: not a python file: {path}"
try:
import ast
code = p.read_text(encoding="utf-8").lstrip(chr(0xFEFF))
lines = code.splitlines(keepends=True)
tree = ast.parse(code)
node = _get_symbol_node(tree, name)
if not node or not isinstance(node, (ast.Assign, ast.AnnAssign)):
return f"ERROR: could not find variable '{name}' in {path}"
start = getattr(node, "lineno") - 1
end = getattr(node, "end_lineno")
return "".join(lines[start:end])
except Exception as e:
return f"ERROR retrieving variable '{name}' from '{path}': {e}"
def py_set_var_declaration(path: str, name: str, new_declaration: str) -> str:
"""Surgically replace a variable assignment/declaration."""
p, err = _resolve_and_check(path)
if err:
return err
if not p.is_file() or p.suffix != ".py":
return f"ERROR: not a python file: {path}"
try:
import ast
code = p.read_text(encoding="utf-8").lstrip(chr(0xFEFF))
tree = ast.parse(code)
node = _get_symbol_node(tree, name)
if not node or not isinstance(node, (ast.Assign, ast.AnnAssign)):
return f"ERROR: could not find variable '{name}' in {path}"
start = getattr(node, "lineno")
end = getattr(node, "end_lineno")
return set_file_slice(path, start, end, new_declaration)
except Exception as e:
return f"ERROR updating variable '{name}' in '{path}': {e}"
def get_git_diff(path: str, base_rev: str = "HEAD", head_rev: str = "") -> str:
"""
Returns the git diff for a file or directory.

1
pyproject.toml
View File

@@ -14,6 +14,7 @@ dependencies = [
"uvicorn",
"tree-sitter>=0.25.2",
"tree-sitter-python>=0.25.0",
"mcp>=1.0.0",
]
[dependency-groups]

289
scripts/claude_mma_exec.py Normal file
View File

@@ -0,0 +1,289 @@
import argparse
import subprocess
import os
import ast
import datetime
import re
import tomllib
import tree_sitter
import tree_sitter_python
LOG_FILE = 'logs/claude_mma_delegation.log'
MODEL_MAP = {
'tier1-orchestrator': 'claude-opus-4-6',
'tier1': 'claude-opus-4-6',
'tier2-tech-lead': 'claude-sonnet-4-6',
'tier2': 'claude-sonnet-4-6',
'tier3-worker': 'claude-sonnet-4-6',
'tier3': 'claude-sonnet-4-6',
'tier4-qa': 'claude-haiku-4-5',
'tier4': 'claude-haiku-4-5',
}
def generate_skeleton(code: str) -> str:
"""
Parses Python code and replaces function/method bodies with '...',
preserving docstrings if present.
"""
try:
PY_LANGUAGE = tree_sitter.Language(tree_sitter_python.language())
parser = tree_sitter.Parser(PY_LANGUAGE)
tree = parser.parse(bytes(code, "utf8"))
edits = []
def is_docstring(node):
if node.type == "expression_statement" and node.child_count > 0:
if node.children[0].type == "string":
return True
return False
def walk(node):
if node.type == "function_definition":
body = node.child_by_field_name("body")
if body and body.type == "block":
indent = " " * body.start_point.column
first_stmt = None
for child in body.children:
if child.type != "comment":
first_stmt = child
break
if first_stmt and is_docstring(first_stmt):
start_byte = first_stmt.end_byte
end_byte = body.end_byte
if end_byte > start_byte:
edits.append((start_byte, end_byte, f"\n{indent}..."))
else:
start_byte = body.start_byte
end_byte = body.end_byte
edits.append((start_byte, end_byte, "..."))
for child in node.children:
walk(child)
walk(tree.root_node)
edits.sort(key=lambda x: x[0], reverse=True)
code_bytes = bytearray(code, "utf8")
for start, end, replacement in edits:
code_bytes[start:end] = bytes(replacement, "utf8")
return code_bytes.decode("utf8")
except Exception as e:
return f"# Error generating skeleton: {e}\n{code}"
def get_model_for_role(role: str) -> str:
"""Returns the Claude model to use for a given tier role."""
return MODEL_MAP.get(role, 'claude-haiku-4-5')
def get_role_documents(role: str) -> list[str]:
if role in ('tier1-orchestrator', 'tier1'):
return ['conductor/product.md', 'conductor/product-guidelines.md']
elif role in ('tier2-tech-lead', 'tier2'):
return ['conductor/tech-stack.md', 'conductor/workflow.md']
elif role in ('tier3-worker', 'tier3'):
return ['conductor/workflow.md']
return []
def log_delegation(role, full_prompt, result=None, summary_prompt=None):
os.makedirs('logs/claude_agents', exist_ok=True)
timestamp = datetime.datetime.now().strftime('%Y%m%d_%H%M%S')
log_file = f'logs/claude_agents/claude_{role}_task_{timestamp}.log'
with open(log_file, 'w', encoding='utf-8') as f:
f.write("==================================================\n")
f.write(f"ROLE: {role}\n")
f.write(f"TIMESTAMP: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
f.write("--------------------------------------------------\n")
f.write(f"FULL PROMPT:\n{full_prompt}\n")
f.write("--------------------------------------------------\n")
if result:
f.write(f"RESULT:\n{result}\n")
f.write("==================================================\n")
os.makedirs(os.path.dirname(LOG_FILE), exist_ok=True)
display_prompt = summary_prompt if summary_prompt else full_prompt
with open(LOG_FILE, 'a', encoding='utf-8') as f:
f.write(f"[{datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}] {role}: {display_prompt[:100]}... (Log: {log_file})\n")
return log_file
def get_dependencies(filepath: str) -> list[str]:
"""Identify top-level module imports from a Python file."""
try:
with open(filepath, 'r', encoding='utf-8') as f:
tree = ast.parse(f.read())
dependencies = []
for node in tree.body:
if isinstance(node, ast.Import):
for alias in node.names:
dependencies.append(alias.name.split('.')[0])
elif isinstance(node, ast.ImportFrom):
if node.module:
dependencies.append(node.module.split('.')[0])
seen = set()
result = []
for d in dependencies:
if d not in seen:
result.append(d)
seen.add(d)
return result
except Exception as e:
print(f"Error getting dependencies for {filepath}: {e}")
return []
def execute_agent(role: str, prompt: str, docs: list[str]) -> str:
model = get_model_for_role(role)
# Advanced Context: Dependency skeletons for Tier 3
injected_context = ""
UNFETTERED_MODULES = ['mcp_client', 'project_manager', 'events', 'aggregate']
if role in ['tier3', 'tier3-worker']:
for doc in docs:
if doc.endswith('.py') and os.path.exists(doc):
deps = get_dependencies(doc)
for dep in deps:
dep_file = f"{dep}.py"
if dep_file in docs:
continue
if os.path.exists(dep_file) and dep_file != doc:
try:
if dep in UNFETTERED_MODULES:
with open(dep_file, 'r', encoding='utf-8') as f:
full_content = f.read()
injected_context += f"\n\nFULL MODULE CONTEXT: {dep_file}\n{full_content}\n"
else:
with open(dep_file, 'r', encoding='utf-8') as f:
skeleton = generate_skeleton(f.read())
injected_context += f"\n\nDEPENDENCY SKELETON: {dep_file}\n{skeleton}\n"
except Exception as e:
print(f"Error gathering context for {dep_file}: {e}")
if len(injected_context) > 15000:
injected_context = injected_context[:15000] + "... [TRUNCATED FOR COMMAND LINE LIMITS]"
# MMA Protocol: Tier 3 and 4 are stateless. Build system directive.
if role in ['tier3', 'tier3-worker']:
system_directive = (
"STRICT SYSTEM DIRECTIVE: You are a stateless Tier 3 Worker (Contributor). "
"Your goal is to implement specific code changes or tests based on the provided task. "
"You have access to tools for reading and writing files (Read, Write, Edit), "
"codebase investigation (Glob, Grep), "
"version control (Bash git commands), and web tools (WebFetch, WebSearch). "
"You CAN execute PowerShell scripts via Bash for verification and testing. "
"Follow TDD and return success status or code changes. No pleasantries, no conversational filler."
)
elif role in ['tier4', 'tier4-qa']:
system_directive = (
"STRICT SYSTEM DIRECTIVE: You are a stateless Tier 4 QA Agent. "
"Your goal is to analyze errors, summarize logs, or verify tests. "
"You have access to tools for reading files and exploring the codebase (Read, Glob, Grep). "
"You CAN execute PowerShell scripts via Bash (read-only) for diagnostics. "
"ONLY output the requested analysis. No pleasantries."
)
else:
system_directive = (
f"STRICT SYSTEM DIRECTIVE: You are a stateless {role}. "
"ONLY output the requested text. No pleasantries."
)
command_text = f"{system_directive}\n\n{injected_context}\n\n"
# Inline documents to ensure sub-agent has context in headless mode
for doc in docs:
if os.path.exists(doc):
try:
with open(doc, 'r', encoding='utf-8') as f:
content = f.read()
command_text += f"\n\nFILE CONTENT: {doc}\n{content}\n"
except Exception as e:
print(f"Error inlining {doc}: {e}")
command_text += f"\n\nTASK: {prompt}\n\n"
# Spawn claude CLI non-interactively via PowerShell
ps_command = (
"if (Test-Path 'C:\\projects\\misc\\setup_claude.ps1') "
"{ . 'C:\\projects\\misc\\setup_claude.ps1' }; "
f"claude --model {model} --print"
)
cmd = ['powershell.exe', '-NoProfile', '-Command', ps_command]
try:
env = os.environ.copy()
env['CLAUDE_CLI_HOOK_CONTEXT'] = 'mma_headless'
process = subprocess.run(
cmd,
input=command_text,
capture_output=True,
text=True,
encoding='utf-8',
env=env
)
# claude --print outputs plain text — no JSON parsing needed
result = process.stdout if process.stdout else f"Error: {process.stderr}"
log_file = log_delegation(role, command_text, result, summary_prompt=prompt)
print(f"Sub-agent log created: {log_file}")
return result
except Exception as e:
err_msg = f"Execution failed: {str(e)}"
log_delegation(role, command_text, err_msg)
return err_msg
def create_parser():
parser = argparse.ArgumentParser(description="Claude MMA Execution Script")
parser.add_argument(
"--role",
choices=['tier1', 'tier2', 'tier3', 'tier4',
'tier1-orchestrator', 'tier2-tech-lead', 'tier3-worker', 'tier4-qa'],
help="The tier role to execute"
)
parser.add_argument(
"--task-file",
type=str,
help="TOML file defining the task"
)
parser.add_argument(
"prompt",
type=str,
nargs='?',
help="The prompt for the tier (optional if --task-file is used)"
)
return parser
def main():
parser = create_parser()
args = parser.parse_args()
role = args.role
prompt = args.prompt
docs = []
if args.task_file and os.path.exists(args.task_file):
with open(args.task_file, "rb") as f:
task_data = tomllib.load(f)
role = task_data.get("role", role)
prompt = task_data.get("prompt", prompt)
docs = task_data.get("docs", [])
if not role or not prompt:
parser.print_help()
return
if not docs:
docs = get_role_documents(role)
# Extract @file references from the prompt
file_refs = re.findall(r"@([\w./\\]+)", prompt)
for ref in file_refs:
if os.path.exists(ref) and ref not in docs:
docs.append(ref)
print(f"Executing role: {role} with docs: {docs}")
result = execute_agent(role, prompt, docs)
print(result)
if __name__ == "__main__":
main()

88
scripts/claude_tool_bridge.py Normal file
View File

@@ -0,0 +1,88 @@
import sys
import json
import logging
import os
# Add project root to sys.path so we can import api_hook_client
project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
if project_root not in sys.path:
sys.path.append(project_root)
try:
from api_hook_client import ApiHookClient
except ImportError:
print("FATAL: Failed to import ApiHookClient. Ensure it's in the Python path.", file=sys.stderr)
sys.exit(1)
def main():
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s', stream=sys.stderr)
logging.debug("Claude Tool Bridge script started.")
try:
input_data = sys.stdin.read()
if not input_data:
logging.debug("No input received from stdin. Exiting gracefully.")
return
logging.debug(f"Received raw input data: {input_data}")
try:
hook_input = json.loads(input_data)
except json.JSONDecodeError:
logging.error("Failed to decode JSON from stdin.")
print(json.dumps({"decision": "deny", "reason": "Invalid JSON received from stdin."}))
return
# Claude Code PreToolUse hook format: tool_name + tool_input
tool_name = hook_input.get('tool_name')
tool_input = hook_input.get('tool_input', {})
if tool_name is None:
logging.error("Could not determine tool name from input. Expected 'tool_name'.")
print(json.dumps({"decision": "deny", "reason": "Missing 'tool_name' in hook input."}))
return
if not isinstance(tool_input, dict):
logging.warning(f"tool_input is not a dict: {tool_input}. Treating as empty.")
tool_input = {}
logging.debug(f"Resolved tool_name: '{tool_name}', tool_input: {tool_input}")
# Check context — if not running via Manual Slop, pass through
hook_context = os.environ.get("CLAUDE_CLI_HOOK_CONTEXT")
logging.debug(f"Checking CLAUDE_CLI_HOOK_CONTEXT: '{hook_context}'")
if hook_context == 'mma_headless':
# Sub-agents in headless MMA mode: auto-allow all tools
logging.debug("CLAUDE_CLI_HOOK_CONTEXT is 'mma_headless'. Allowing for sub-agent.")
print(json.dumps({"decision": "allow", "reason": "Sub-agent headless mode (MMA)."}))
return
if hook_context != 'manual_slop':
# Not a programmatic Manual Slop session — allow through silently
logging.debug(f"CLAUDE_CLI_HOOK_CONTEXT is '{hook_context}', not 'manual_slop'. Allowing.")
print(json.dumps({"decision": "allow", "reason": f"Non-programmatic usage (CLAUDE_CLI_HOOK_CONTEXT={hook_context})."}))
return
# manual_slop context: route to GUI for approval
logging.debug("CLAUDE_CLI_HOOK_CONTEXT is 'manual_slop'. Routing to API Hook Client.")
client = ApiHookClient(base_url="http://127.0.0.1:8999")
try:
logging.debug(f"Requesting confirmation for tool '{tool_name}' with args: {tool_input}")
response = client.request_confirmation(tool_name, tool_input)
if response and response.get('approved') is True:
logging.debug("User approved tool execution.")
print(json.dumps({"decision": "allow"}))
else:
reason = response.get('reason', 'User rejected tool execution in GUI.') if response else 'No response from GUI.'
logging.debug(f"User denied tool execution. Reason: {reason}")
print(json.dumps({"decision": "deny", "reason": reason}))
except Exception as e:
logging.error(f"API Hook Client error: {str(e)}", exc_info=True)
print(json.dumps({"decision": "deny", "reason": f"Manual Slop hook server unreachable: {str(e)}"}))
except Exception as e:
logging.error(f"Unexpected error in bridge: {str(e)}", exc_info=True)
print(json.dumps({"decision": "deny", "reason": f"Internal bridge error: {str(e)}"}))
if __name__ == "__main__":
main()

91
scripts/mcp_server.py Normal file
View File

@@ -0,0 +1,91 @@
"""
MCP server exposing Manual Slop's custom tools (mcp_client.py) to Claude Code.
All 26 tools from mcp_client.MCP_TOOL_SPECS are served, plus run_powershell.
Delegates to mcp_client.dispatch() for all tools except run_powershell,
which routes through shell_runner.run_powershell() directly.
Usage (in .claude/settings.json mcpServers):
"command": "uv", "args": ["run", "python", "scripts/mcp_server.py"]
"""
import asyncio
import os
import sys
# Add project root to sys.path
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
import mcp_client
import shell_runner
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent
# run_powershell is handled by shell_runner, not mcp_client.dispatch()
# Define its spec here since it's not in MCP_TOOL_SPECS
RUN_POWERSHELL_SPEC = {
"name": "run_powershell",
"description": (
"Run a PowerShell script within the project base directory. "
"Returns combined stdout, stderr, and exit code. "
"60-second timeout. Use for builds, tests, and system commands."
),
"parameters": {
"type": "object",
"properties": {
"script": {
"type": "string",
"description": "PowerShell script content to execute."
}
},
"required": ["script"]
}
}
server = Server("manual-slop-tools")
@server.list_tools()
async def list_tools() -> list[Tool]:
tools = []
for spec in mcp_client.MCP_TOOL_SPECS:
tools.append(Tool(
name=spec["name"],
description=spec["description"],
inputSchema=spec["parameters"],
))
# Add run_powershell
tools.append(Tool(
name=RUN_POWERSHELL_SPEC["name"],
description=RUN_POWERSHELL_SPEC["description"],
inputSchema=RUN_POWERSHELL_SPEC["parameters"],
))
return tools
@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
try:
if name == "run_powershell":
script = arguments.get("script", "")
result = shell_runner.run_powershell(script, os.getcwd())
else:
result = mcp_client.dispatch(name, arguments)
return [TextContent(type="text", text=str(result))]
except Exception as e:
return [TextContent(type="text", text=f"ERROR: {e}")]
async def main():
async with stdio_server() as (read_stream, write_stream):
await server.run(
read_stream,
write_stream,
server.create_initialization_options(),
)
if __name__ == "__main__":
asyncio.run(main())