Atomizer/docs/archive/review/UNIFIED_CONFIG_RALPH_PROMPT.md

Ralph Loop Prompt: AtomizerSpec v2.0 Implementation

Copy this prompt to start the autonomous implementation loop.

---

Claude CLI Command

claude --dangerously-skip-permissions

---

Initial Prompt (Copy This)

You are implementing the AtomizerSpec v2.0 Unified Configuration Architecture for Atomizer.

## Project Context

Read these documents before starting:
1. `docs/plans/UNIFIED_CONFIGURATION_ARCHITECTURE.md` - Master design document with architecture, schemas, and component designs
2. `docs/plans/UNIFIED_CONFIG_EXECUTION_PLAN.md` - Detailed task list with 50+ tasks across 4 phases
3. `optimization_engine/schemas/atomizer_spec_v2.json` - The JSON Schema definition

## Your Mission

Implement the AtomizerSpec v2.0 system following the execution plan. Work through tasks in order (P1.1 → P1.2 → ... → P4.12).

## Rules

1. **Follow the plan**: Execute tasks in the order specified in UNIFIED_CONFIG_EXECUTION_PLAN.md
2. **Check dependencies**: Don't start a task until its dependencies are complete
3. **Use TodoWrite**: Track all tasks, mark in_progress when starting, completed when done
4. **Test as you go**: Verify each task meets its acceptance criteria before moving on
5. **Commit regularly**: Commit after completing each logical group of tasks (e.g., after P1.7, after P1.12)
6. **Reference the design**: The master document has code examples - use them
7. **Ask if blocked**: If you encounter a blocker, explain what's wrong and what you need

## Starting Point

1. Read the three reference documents listed above
2. Load the current task list into TodoWrite
3. Start with P1.1 (Create TypeScript types from JSON Schema)
4. Work through each task, marking completion as you go

## Commit Message Format

Use conventional commits:
- `feat(spec): Add SpecManager core class (P1.4)`
- `feat(spec-api): Implement GET /studies/{id}/spec (P1.9)`
- `feat(frontend): Create useSpecStore hook (P2.1)`
- `test(spec): Add SpecManager unit tests (P4.4)`

## Progress Tracking

After completing each phase, summarize:
- Tasks completed
- Files created/modified
- Any deviations from plan
- Blockers encountered

Begin by reading the reference documents and loading tasks into TodoWrite.

---

Continuation Prompt (When Resuming)

Continue implementing the AtomizerSpec v2.0 system.

Reference documents:
- `docs/plans/UNIFIED_CONFIGURATION_ARCHITECTURE.md` - Master design
- `docs/plans/UNIFIED_CONFIG_EXECUTION_PLAN.md` - Task list

Check where we left off:
1. Read the current todo list
2. Find the last completed task
3. Continue with the next task in sequence

If you need context on what was done, check recent git commits.

Resume implementation.

---

Phase-Specific Prompts

Start Phase 1 (Foundation)

Begin Phase 1 of AtomizerSpec implementation - Foundation/Backend.

Reference: `docs/plans/UNIFIED_CONFIG_EXECUTION_PLAN.md` section "PHASE 1: Foundation"

Tasks P1.1 through P1.17 focus on:
- TypeScript and Python types from JSON Schema
- SpecManager service (load, save, validate, patch, nodes)
- REST API endpoints
- Migration tool

Start with P1.1: Create TypeScript types from the JSON Schema at `optimization_engine/schemas/atomizer_spec_v2.json`.

Work through each task in order, tracking with TodoWrite.

Start Phase 2 (Frontend)

Begin Phase 2 of AtomizerSpec implementation - Frontend Integration.

Reference: `docs/plans/UNIFIED_CONFIG_EXECUTION_PLAN.md` section "PHASE 2: Frontend Integration"

Tasks P2.1 through P2.16 focus on:
- useSpecStore hook (Zustand state management)
- Spec ↔ ReactFlow conversion
- SpecRenderer component
- WebSocket real-time sync
- Replacing old canvas with spec-based canvas

Prerequisites: Phase 1 must be complete (P1.1-P1.17).

Start with P2.1: Create useSpecStore hook.

Work through each task in order, tracking with TodoWrite.

Start Phase 3 (Claude Integration)

Begin Phase 3 of AtomizerSpec implementation - Claude Integration.

Reference: `docs/plans/UNIFIED_CONFIG_EXECUTION_PLAN.md` section "PHASE 3: Claude Integration"

Tasks P3.1 through P3.14 focus on:
- MCP tools for spec operations (spec_get, spec_modify, spec_add_node, etc.)
- Custom extractor support (add Python functions via Claude)
- Runtime loading of custom functions
- Natural language study creation

Prerequisites: Phases 1 and 2 must be complete.

Start with P3.1: Create spec_get MCP tool.

Work through each task in order, tracking with TodoWrite.

Start Phase 4 (Polish & Testing)

Begin Phase 4 of AtomizerSpec implementation - Polish & Testing.

Reference: `docs/plans/UNIFIED_CONFIG_EXECUTION_PLAN.md` section "PHASE 4: Polish & Testing"

Tasks P4.1 through P4.12 focus on:
- Migrating all existing studies to AtomizerSpec v2
- Unit tests, integration tests, e2e tests
- Documentation updates

Prerequisites: Phases 1, 2, and 3 must be complete.

Start with P4.1: Migrate m1_mirror studies.

Work through each task in order, tracking with TodoWrite.

---

Troubleshooting Prompts

If Stuck on a Task

I'm blocked on task [TASK_ID].

The issue is: [describe the problem]

What I've tried: [list attempts]

Please help me resolve this so I can continue with the execution plan.

If Tests Fail

Tests are failing for [component].

Error: [paste error]

This is blocking task [TASK_ID]. Help me fix the tests so I can mark the task complete.

If Design Needs Clarification

Task [TASK_ID] requires [specific thing] but the design document doesn't specify [what's unclear].

Options I see:
1. [option A]
2. [option B]

Which approach should I take? Or should I update the design document?

---

Full Task List for TodoWrite

Copy this to initialize the todo list:

P1.1 - Create TypeScript types from JSON Schema
P1.2 - Create Python Pydantic models from JSON Schema
P1.3 - Create spec validation utility
P1.4 - Create SpecManager core class
P1.5 - Add SpecManager patch functionality
P1.6 - Add SpecManager node operations
P1.7 - Add SpecManager custom function support
P1.8 - Create spec REST router
P1.9 - Implement GET /studies/{study_id}/spec
P1.10 - Implement PUT /studies/{study_id}/spec
P1.11 - Implement PATCH /studies/{study_id}/spec
P1.12 - Implement POST /studies/{study_id}/spec/validate
P1.13 - Create config migration base
P1.14 - Implement design variable migration
P1.15 - Implement objective/constraint migration
P1.16 - Implement full config migration
P1.17 - Create migration CLI tool
P2.1 - Create useSpecStore hook
P2.2 - Add spec loading to useSpecStore
P2.3 - Add spec modification to useSpecStore
P2.4 - Add optimistic updates to useSpecStore
P2.5 - Create specToNodes converter
P2.6 - Create specToEdges converter
P2.7 - Create SpecRenderer component
P2.8 - Wire node editing to spec updates
P2.9 - Wire node position to spec updates
P2.10 - Update node panels for full spec fields
P2.11 - Create WebSocket connection hook
P2.12 - Create WebSocket backend endpoint
P2.13 - Implement spec_updated broadcast
P2.14 - Handle spec_updated in frontend
P2.15 - Add conflict detection
P2.16 - Replace CanvasView with SpecRenderer
P3.1 - Create spec_get MCP tool
P3.2 - Create spec_modify MCP tool
P3.3 - Create spec_add_node MCP tool
P3.4 - Create spec_remove_node MCP tool
P3.5 - Create spec_validate MCP tool
P3.6 - Create spec_add_custom_extractor MCP tool
P3.7 - Register spec tools in MCP server
P3.8 - Update ContextBuilder for spec awareness
P3.9 - Create custom extractor runtime loader
P3.10 - Integrate custom extractors into optimization runner
P3.11 - Add custom extractor node type to canvas
P3.12 - Add code editor for custom extractors
P3.13 - Create spec_create_from_description MCP tool
P3.14 - Update Claude prompts for spec workflow
P4.1 - Migrate m1_mirror studies
P4.2 - Migrate drone_gimbal study
P4.3 - Migrate all remaining studies
P4.4 - Create spec unit tests
P4.5 - Create spec API integration tests
P4.6 - Create migration tests
P4.7 - Create frontend component tests
P4.8 - Create WebSocket sync tests
P4.9 - Create MCP tools tests
P4.10 - End-to-end testing
P4.11 - Update documentation
P4.12 - Update CLAUDE.md

---

Expected Outcomes

After successful completion:

1. Single Source of Truth: atomizer_spec.json used everywhere
2. Bidirectional Sync: Canvas ↔ Spec with no data loss
3. Real-time Updates: WebSocket keeps all clients in sync
4. Claude Integration: Claude can read/modify/create specs via MCP
5. Custom Functions: Users can add Python extractors through UI/Claude
6. All Studies Migrated: Existing configs converted to v2 format
7. Full Test Coverage: Unit, integration, and e2e tests passing
8. Updated Documentation: User guides reflect new workflow

---

This prompt file enables autonomous implementation of the AtomizerSpec v2.0 system using the Ralph Loop pattern.