Atomizer/docs/plans/DASHBOARD_CHAT_TASKS.md

Dashboard Chat Architecture - Task List

For: Ralph Loop Execution Plan Document: DASHBOARD_CHAT_ARCHITECTURE.md Created: 2025-01-08

---

Execution Order

Execute phases in order. Within each phase, tasks can be parallelized where noted.

---

PHASE 1: MCP Server Foundation

Goal: Create Atomizer MCP server that exposes tools to Claude

P1.1 - Create MCP Server Scaffold [BLOCKING]

Description: Set up the MCP server project structure

Files to create:

• mcp-server/atomizer-tools/package.json
• mcp-server/atomizer-tools/tsconfig.json
• mcp-server/atomizer-tools/src/index.ts
• mcp-server/atomizer-tools/src/utils/paths.ts

Acceptance Criteria:

• npm install succeeds
• npm run build succeeds
• Server starts without errors

Reference: See DASHBOARD_CHAT_ARCHITECTURE.md section "Phase 1: MCP Server Foundation"

---

P1.2 - Implement Study Tools [CAN PARALLELIZE with P1.3-P1.6]

Description: Create tools for study management

File: mcp-server/atomizer-tools/src/tools/study.ts

Tools to implement:

1. list_studies - List all available studies with status
2. get_study_status - Get detailed status of a study
3. create_study - Create study from natural language description

Dependencies: P1.1

Acceptance Criteria:

• list_studies returns array of {name, status, trials}
• get_study_status returns config + results summary
• create_study calls Python StudyCreator

---

P1.3 - Implement Optimization Tools [CAN PARALLELIZE]

Description: Create tools for running optimizations

File: mcp-server/atomizer-tools/src/tools/optimization.ts

Tools to implement:

1. run_optimization - Start optimization for a study
2. stop_optimization - Stop running optimization
3. get_optimization_status - Get current optimization state

Dependencies: P1.1

Acceptance Criteria:

• run_optimization spawns Python process
• stop_optimization terminates gracefully
• get_optimization_status reads from DB

---

P1.4 - Implement Analysis Tools [CAN PARALLELIZE]

Description: Create tools for analyzing results

File: mcp-server/atomizer-tools/src/tools/analysis.ts

Tools to implement:

1. get_trial_data - Query trials with filters
2. analyze_convergence - Convergence analysis
3. compare_trials - Compare multiple trials
4. get_best_design - Get best design found

Dependencies: P1.1

Acceptance Criteria:

• get_trial_data supports: all, best, pareto, recent, failed
• analyze_convergence returns trend metrics
• compare_trials returns comparison table

---

P1.5 - Implement Reporting Tools [CAN PARALLELIZE]

Description: Create tools for generating reports

File: mcp-server/atomizer-tools/src/tools/reporting.ts

Tools to implement:

1. generate_report - Generate markdown report
2. export_data - Export results to CSV/JSON

Dependencies: P1.1

Acceptance Criteria:

• generate_report creates valid markdown
• export_data creates valid CSV/JSON files

---

P1.6 - Implement Physics Tools [CAN PARALLELIZE]

Description: Create tools for FEA explanations

File: mcp-server/atomizer-tools/src/tools/physics.ts

Tools to implement:

1. explain_physics - Explain FEA concepts
2. recommend_method - Recommend optimization method
3. query_extractors - List available extractors

Dependencies: P1.1

Acceptance Criteria:

• explain_physics uses Atomizer context
• recommend_method considers objectives/DVs

---

P1.7 - Implement Admin Tools (Power Mode) [AFTER P1.2-P1.6]

Description: Create tools for power mode (code modification)

File: mcp-server/atomizer-tools/src/tools/admin.ts

Tools to implement:

1. edit_file - Edit file in codebase
2. create_file - Create new file
3. create_extractor - Create new physics extractor
4. run_shell_command - Run arbitrary shell command
5. search_codebase - Search files

Dependencies: P1.2-P1.6 (understand patterns first)

Acceptance Criteria:

• edit_file validates old_content exists
• create_extractor follows template
• run_shell_command captures output

SECURITY: These tools ONLY available when ATOMIZER_MODE=power

---

P1.8 - Build and Register MCP Server [BLOCKING]

Description: Build server and update Claude config

Steps:

1. cd mcp-server/atomizer-tools && npm run build
2. Update .claude/settings.local.json with MCP config
3. Test with claude --mcp-config

Dependencies: P1.1-P1.7

Acceptance Criteria:

• Server builds without errors
• Claude can list tools
• Tools execute correctly

---

PHASE 2: Backend Session Manager

Goal: Manage persistent Claude sessions with MCP

P2.1 - Create Conversation Store [BLOCKING]

Description: SQLite persistence for conversations

File: atomizer-dashboard/backend/api/services/conversation_store.py

Features:

• Sessions table (id, mode, study_id, timestamps)
• Messages table (id, session_id, role, content, tool_calls, timestamp)
• CRUD operations

Acceptance Criteria:

• Database schema created on init
• add_message stores correctly
• get_history returns chronological messages

---

P2.2 - Create Context Builder [CAN PARALLELIZE with P2.1]

Description: Build context prompts for Claude

File: atomizer-dashboard/backend/api/services/context_builder.py

Features:

• Base context (identity, capabilities)
• Study context (config, results)
• Mode instructions (user vs power)
• Conversation history injection

Acceptance Criteria:

• User mode context restricts capabilities
• Power mode context enables all tools
• Study context includes config + status

---

P2.3 - Create Session Manager [AFTER P2.1, P2.2]

Description: Manage Claude Code subprocess sessions

File: atomizer-dashboard/backend/api/services/session_manager.py

Features:

• Create session (spawn Claude subprocess)
• Send message (stdin/stdout communication)
• Stream response (async generator)
• Switch mode (restart with new config)
• Cleanup stale sessions

Acceptance Criteria:

• Sessions persist across messages
• Mode switching works
• Cleanup runs periodically

---

P2.4 - Update API Routes [AFTER P2.3]

Description: Add new Claude API endpoints

File: atomizer-dashboard/backend/api/routes/claude.py

Endpoints:

• POST /sessions - Create/resume session
• POST /sessions/{id}/mode - Switch mode
• WS /sessions/{id}/ws - WebSocket for chat
• Keep legacy endpoints for backwards compatibility

Acceptance Criteria:

• Session creation returns session_id
• WebSocket streams responses
• Mode switch requires confirmation

---

P2.5 - Update Main Entry Point [AFTER P2.4]

Description: Initialize session manager on startup

File: atomizer-dashboard/backend/main.py

Changes:

• Add lifespan handler
• Start session manager on startup
• Stop session manager on shutdown

Acceptance Criteria:

• Manager starts with server
• Manager stops cleanly

---

PHASE 3: Frontend Updates

Goal: Update React UI for new chat system

P3.1 - Create Mode Toggle Component [CAN PARALLELIZE]

Description: User/Power mode switcher

File: atomizer-dashboard/frontend/src/components/chat/ModeToggle.tsx

Features:

• Toggle buttons for User/Power mode
• Confirmation modal for Power mode
• Visual indication of current mode

Acceptance Criteria:

• User mode is default
• Power mode requires confirmation
• Visual feedback on mode change

---

P3.2 - Create Tool Call Card Component [CAN PARALLELIZE]

Description: Display tool calls in messages

File: atomizer-dashboard/frontend/src/components/chat/ToolCallCard.tsx

Features:

• Expandable card showing tool name
• Arguments display
• Result display (success/error)
• Loading state

Acceptance Criteria:

• Shows tool name and status
• Expandable to show details
• Error states displayed clearly

---

P3.3 - Update useChat Hook [AFTER P3.1, P3.2]

Description: WebSocket-based chat with sessions

File: atomizer-dashboard/frontend/src/hooks/useChat.ts

Changes:

• Session creation on mount
• WebSocket connection management
• Tool call handling in messages
• Mode switching
• Reconnection logic

Acceptance Criteria:

• Session created on mount
• WebSocket connects and streams
• Tool calls rendered in messages
• Mode switch triggers reconnect

---

P3.4 - Update ChatMessage Component [CAN PARALLELIZE with P3.3]

Description: Support tool calls in messages

File: atomizer-dashboard/frontend/src/components/chat/ChatMessage.tsx

Changes:

• Import and render ToolCallCard
• Update Message interface for toolCalls

Acceptance Criteria:

• Tool calls render inline
• Markdown still works
• Streaming cursor shows

---

P3.5 - Update ChatPane Component [AFTER P3.3, P3.4]

Description: Integrate new components

File: atomizer-dashboard/frontend/src/components/chat/ChatPane.tsx

Changes:

• Add ModeToggle to header
• Show connection status
• Power mode indicator bar
• Pass mode to useChat

Acceptance Criteria:

• Mode toggle visible
• Connection status shows
• Power mode has warning bar

---

P3.6 - Update Component Exports [AFTER P3.1-P3.5]

Description: Export new components

File: atomizer-dashboard/frontend/src/components/chat/index.ts

Changes:

• Export ModeToggle
• Export ToolCallCard

---

PHASE 4: Integration & Testing

Goal: Ensure everything works together

P4.1 - Integration Test: User Mode [AFTER P1-P3]

Test cases:

• Create new session
• Send message, receive response
• Tool call: list_studies
• Tool call: get_study_status
• Tool call: create_study
• Session persists across page refresh

---

P4.2 - Integration Test: Power Mode [AFTER P4.1]

Test cases:

• Switch to power mode
• Tool call: edit_file
• Tool call: create_extractor
• Tool call: run_shell_command
• Verify changes in filesystem

---

P4.3 - Integration Test: Study Context [AFTER P4.1]

Test cases:

• Navigate to study
• Chat knows study context
• Tool calls use study context
• Context updates on study change

---

P4.4 - Performance Testing [AFTER P4.1-P4.3]

Test cases:

• Response streaming is smooth
• No memory leaks in sessions
• Cleanup works for stale sessions
• Multiple concurrent sessions

---

P4.5 - Documentation Update [AFTER P4.1-P4.4]

Files to update:

• README.md - Add chat architecture section
• CLAUDE.md - Reference new MCP tools
• Add user guide for chat modes

---

Quick Reference: File Map

CREATE:
├── mcp-server/atomizer-tools/
│   ├── package.json
│   ├── tsconfig.json
│   └── src/
│       ├── index.ts
│       ├── tools/
│       │   ├── study.ts
│       │   ├── optimization.ts
│       │   ├── analysis.ts
│       │   ├── reporting.ts
│       │   ├── physics.ts
│       │   └── admin.ts
│       └── utils/
│           └── paths.ts
│
├── atomizer-dashboard/backend/api/services/
│   ├── conversation_store.py
│   ├── context_builder.py
│   └── session_manager.py
│
└── atomizer-dashboard/frontend/src/components/chat/
    ├── ModeToggle.tsx
    └── ToolCallCard.tsx

UPDATE:
├── atomizer-dashboard/backend/api/routes/claude.py
├── atomizer-dashboard/backend/main.py
├── atomizer-dashboard/frontend/src/hooks/useChat.ts
├── atomizer-dashboard/frontend/src/components/chat/ChatMessage.tsx
├── atomizer-dashboard/frontend/src/components/chat/ChatPane.tsx
└── atomizer-dashboard/frontend/src/components/chat/index.ts

---

Estimated Effort

Phase	Tasks	Estimated Hours
Phase 1	8	6-8
Phase 2	5	4-6
Phase 3	6	4-5
Phase 4	5	3-4
Total	24	17-23

---

Notes for Ralph Loop

1. Read the full plan first: docs/plans/DASHBOARD_CHAT_ARCHITECTURE.md
2. Execute in order: Phase 1 → Phase 2 → Phase 3 → Phase 4
3. Parallelize where noted: Tasks marked "CAN PARALLELIZE" can run concurrently
4. Test incrementally: Each phase should be tested before moving on
5. Commit after each phase: Keep changes atomic and reversible

---

Task List Version: 1.0