docs: Major documentation overhaul - restructure folders, update tagline, add Getting Started guide
- Restructure docs/ folder (remove numeric prefixes): - 04_USER_GUIDES -> guides/ - 05_API_REFERENCE -> api/ - 06_PHYSICS -> physics/ - 07_DEVELOPMENT -> development/ - 08_ARCHIVE -> archive/ - 09_DIAGRAMS -> diagrams/ - Replace tagline 'Talk, don't click' with 'LLM-driven optimization framework' in 9 files - Create comprehensive docs/GETTING_STARTED.md: - Prerequisites and quick setup - Project structure overview - First study tutorial (Claude or manual) - Dashboard usage guide - Neural acceleration introduction - Rewrite docs/00_INDEX.md with correct paths and modern structure - Archive obsolete files: - 01_PROTOCOLS.md -> archive/historical/01_PROTOCOLS_legacy.md - 03_GETTING_STARTED.md -> archive/historical/ - ATOMIZER_PODCAST_BRIEFING.md -> archive/marketing/ - Update timestamps to 2026-01-20 across all key files - Update .gitignore to exclude docs/generated/ - Version bump: ATOMIZER_CONTEXT v1.8 -> v2.0
This commit is contained in:
286
docs/plans/UNIFIED_CONFIG_RALPH_PROMPT.md
Normal file
286
docs/plans/UNIFIED_CONFIG_RALPH_PROMPT.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# Ralph Loop Prompt: AtomizerSpec v2.0 Implementation
|
||||
|
||||
**Copy this prompt to start the autonomous implementation loop.**
|
||||
|
||||
---
|
||||
|
||||
## Claude CLI Command
|
||||
|
||||
```bash
|
||||
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.*
|
||||
Reference in New Issue
Block a user