ROADMAP.md

Okay, I will create a detailed, step-by-step implementation guide designed for you to build the simplified single-user version of the READMEs programming system. This document will serve as your roadmap, outlining the best sequence for file creation, implementation, and providing clear instructions for your LLM assistant (that's me!).

Implementation Guide: READMEs Programming System (Single-User)

I. Project Vision (Recap)

• README as Interface: The README.md file is the user's primary interaction point, blending documentation, code, and execution.
• Local .md Files as Modules: Other .md files act as supporting modules, housing reusable code, templates, documentation, and configurations.
• Warmhole Navigation: Local warmhole links are the primary navigation mechanism, connecting files and transferring context.
• Local State Management: State changes are tracked locally and are reflected directly within the working files.
• No Git (For Now): The initial implementation will be purely local, without any Git-based collaboration or tracking.
• Self-Contained: The system will be self-contained, where all the required information is inside the same folder.

II. Core Principles (LLM-Friendly)

• Modular Design: Break down the system into clear components.
• Incremental Approach: Implement features step-by-step, focusing on core functionality first.
• Test-Driven Development: Test each component thoroughly as you build it.
• Documentation as You Go: Keep your code well-documented, using the system standards as guidelines.
• LLM-Guided Development: Use the LLM for complex tasks, code generation, and idea generation.

III. Implementation Steps

Phase 1: Setting up the Project (Files and Basic Structure)

1. Step 1: Create the Core Files

   • Action: Create the following .md files in a new directory:
     • README.md (Main file)
     • Rdm_standards.md (System standards)
     • Rmd_parser_rules.md (Parser definitions)
     • Rdm_documentation.md (Project documentation)
     • my_first_library.md (Example library)
   • LLM Instruction: "Create the core project files: README.md, Rdm_standards.md, Rmd_parser_rules.md, Rdm_documentation.md, and my_first_library.md in a new directory. Each file should be empty for now except for the comments on the README.md (see the example below)."

   # READMEs Programming System
   
   A self-contained programming system using README.md as executable documentation.
   
   // Core files:
   //   - Rdm_standards.md
   //   - Rmd_parser_rules.md
   //   - Rdm_documentation.md
   //   - my_first_library.md
   

2. Step 2: Implement Core Standards in Rdm_standards.md

   • Action: Copy the content of the Rdm_standards.md (given in the previous message) and paste it into the Rdm_standards.md file. This will create the core standard definitions of the system.
   • LLM Instruction: "Copy the content of the Rdm_standards.md (provided in the previous message), and paste it into your local Rdm_standards.md file. Make sure that all code blocks are well defined, and that all the text is correctly placed."

3. Step 3: Implement Core Parser Rules in Rmd_parser_rules.md

   • Action: Copy the content of the Rmd_parser_rules.md (given in the previous message) and paste it into the Rmd_parser_rules.md file. This will create the core parser rules for the system.
   • LLM Instruction: "Copy the content of the Rmd_parser_rules.md (provided in the previous message), and paste it into your local Rmd_parser_rules.md file. Make sure that all code blocks are well defined, and that all the text is correctly placed."

4. Step 4: Populate Core Documentation in Rdm_documentation.md

   • Action: Copy the content of the Rdm_documentation.md (given in the previous message) and paste it into the Rdm_documentation.md file. This will create the core documentation for the system.
   • LLM Instruction: "Copy the content of the Rdm_documentation.md (provided in the previous message), and paste it into your local Rdm_documentation.md file. Make sure that all code blocks are well defined, and that all the text is correctly placed."

5. Step 5: Populate Example Library in my_first_library.md

   • Action: Copy the content of the my_first_library.md (given in the previous message) and paste it into the my_first_library.md file. This will create the example library for the system.
   • LLM Instruction: "Copy the content of the my_first_library.md (provided in the previous message), and paste it into your local my_first_library.md file. Make sure that all code blocks are well defined, and that all the text is correctly placed."

Phase 2: Implementing the Core Parsing and Execution Logic (JavaScript)

1. Step 6: Create a Javascript file called core_logic.js

   • Action: Create the Javascript file that will be responsible for all core functions. This file will contain the system_init, execute, and other core functionalities.
   • LLM Instruction: "Create the core_logic.js file, that will contain all core Javascript functions."

2. Step 7: Implement Core Javascript Helpers

   • Action: Implement the following helper functions, based on the javascript implementations described in the previous messages: extractByRegex, cacheMetadata and parseHeader. This files must be implemented in the core_logic.js file.
   • LLM Instruction: "Implement the extractByRegex, cacheMetadata and parseHeader functions, based on the previous javascript examples and store it in the core_logic.js file. The functions cacheMetadata and parseHeader will need to call each other."

3. Step 8: Implement the system_init function in core_logic.js

   • Action: Implement the core logic of the system_init in Javascript that will:
     • Read all .md files in the current directory
     • Use the extractByRegex, cacheMetadata and parseHeader to extract all functions, templates, warmholes, and system metadata from all documents, following the standards defined in Rdm_standards.md.
     • Save all the information into a global object (a variable) that you will use as local state for this implementation.
   • LLM Instruction: "Implement the system_init function in the core_logic.js file that will:
     • Read all .md files in the current directory.
     • Use the extractByRegex, cacheMetadata and parseHeader to extract all functions, templates, warmholes, and system metadata from all documents, following the standards defined in Rdm_standards.md.
     • Save all the information into a global object (a variable) that you will use as local state for this implementation."

4. Step 9: Implement the execute Function in core_logic.js

   • Action: Implement the core logic for execute function in JavaScript, which will:
     • Take as input a function or template name and a context (variables), and execute it, using the definitions in Rmd_parser_rules.md and the state.
     • If a template is executed, render the result with the current state.
     • If a function is executed, call the function and return the result.
   • LLM Instruction: "Implement the core logic for execute function in JavaScript inside the core_logic.js file, that will:
     • Take as input a function or template name and a context (variables), and execute it, using the definitions in Rmd_parser_rules.md and the state.
     • If a template is executed, render the result with the current state.
     • If a function is executed, call the function and return the result."

5. Step 10: Implement Warmhole Navigation in core_logic.js

   • Action: Implement the core logic for warmhole navigation, which will
     • Take as input a warmhole ID, and update the state.
     • Extract the state_transfer and update the context.
     • Make the previous_output accessible in the new context.
   • LLM Instruction: "Implement the core logic for warmhole navigation in JavaScript inside the core_logic.js file, that will:
     • Take as input a warmhole ID, and update the state.
     • Extract the state_transfer and update the context.
     • Make the previous_output accessible in the new context."

6. Step 11: Implement Basic State Management in core_logic.js

   • Action: Implement a state management system that:
     • Tracks changes to local variables, previous_output, and the warmhole state.
     • Make sure all this information is accessible from all files.
     • Provides a way to save and persist this state for future use.
   • LLM Instruction: "Implement a state management system in the core_logic.js file, that will:
     • Tracks changes to local variables, previous_output, and the warmhole state.
     • Make sure all this information is accessible from all files.
     • Provides a way to save and persist this state for future use."

Phase 3: Integrating Core System and Building IDE Extension

1. Step 12: Integrate JavaScript with README.md

   • Action: Modify the README.md file so that it loads the core_logic.js file when it starts, and executes the system_init function when the file is opened.
   • LLM Instruction: "Modify the README.md file so that it loads the core_logic.js file when it starts, and executes the system_init function when the file is opened. Also add a global function named execute that will call your execute function, for the user to call any function."

2. Step 13: Test Basic Core Functionality

   • Action: Test all core functionalities, focusing in:
     • Loading the files correctly.
     • Executing a function and printing the result.
     • Navigating through a warmhole.
     • Storing and retrieving state.
     • Following the standards defined in Rdm_standards.md.
   • LLM Instruction: "Test all core functionalities, focusing in:
     • Loading the files correctly.
     • Executing a function and printing the result.
     • Navigating through a warmhole.
     • Storing and retrieving state.
     • Following the standards defined in Rdm_standards.md."

3. Step 14: Build Basic IDE Extension

   • Action: Create a very simple IDE extension that:
     • Loads the README.md file.
     • Displays a console for the output.
     • Highlights the current warmhole.
     • Allows execution of specific functions using the execute global function.
   • LLM Instruction: "Create a very simple IDE extension that:
     • Loads the README.md file.
     • Displays a console for the output.
     • Highlights the current warmhole.
     • Allows execution of specific functions using the execute global function."

IV. LLM Prompts for Each Step

I've provided the core LLM instructions in each step. These prompts are designed to give clear and achievable tasks to an LLM. Feel free to adjust or modify the prompts based on your specific needs.

V. Testing

• Manual Testing: Run the system and test all functionalities and links between files.
• Incremental Testing: Test each component as you build it (not all at once).
• "Dogfooding": Use the system itself to test your system and make improvements based on usage.

VI. Iteration

• Refine: This is an iterative process. If something is not working correctly, refactor and improve it.
• Optimize: Make the system as optimized as possible, both in terms of parsing logic, performance, and user experience.

LLM Reasoning

An LLM, reviewing this document, would understand that:

• Clear Roadmap: You have a well-defined, step-by-step roadmap for implementation.
• Modular Approach: You are breaking down the project into logical, manageable tasks.
• Focus on Core: You are prioritizing the core functionality of the system.
• LLM Integration: You are using the LLM as a tool for development, not just for code generation.
• Test-Driven: You are creating a system that is easier to test because it is organized in small modules.
• Practical Approach: You are focusing on a practical approach that will generate immediate value.
• Scalable: The architecture is structured in a way that makes it easier to scale to other users.

In Summary

This is a clear, actionable plan that should guide you through the implementation process. By following this roadmap, using the prompts for your LLM assistant, and testing as you go, you'll be well on your way to creating a working, single-user version of your READMEs programming system. You've got this!